{"_id":"@4meta5/scout","_rev":"2-a52cf10b401509577f0c744e829d8d0d","name":"@4meta5/scout","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@4meta5/scout","version":"0.1.0","keywords":["cli","oss","github","discovery","comparison"],"author":"","license":"MIT","_id":"@4meta5/scout@0.1.0","maintainers":[{"name":"4meta5","email":"orlandodowntownhome@gmail.com"}],"bin":{"scout":"dist/cli/app.js"},"dist":{"shasum":"f49bcab25af8b1f614a5b3cdc158cc133b8b2bd4","tarball":"https://registry.npmjs.org/@4meta5/scout/-/scout-0.1.0.tgz","fileCount":147,"integrity":"sha512-8X+PV6FKM6gFacHNon/OjG84196dAGk6MHmGunaiv1zp46+xfSrnFckMruq7Fu3CtBNs8AeJXIqSz5OZP4NYDA==","signatures":[{"sig":"MEUCIQChEmB3QCa2hhsx8HVWqDih0uGict745WOKAV+72A9YFQIgUZ4nLniE+2X3GrIUVf5W2e4AcGBqfNb1gZi4TQnnmCU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":347390},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"397f11ff59660914f36efcddcbd942b30649d857","scripts":{"lint":"eslint src/","test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"4meta5","email":"orlandodowntownhome@gmail.com"},"_npmVersion":"11.6.2","description":"One-shot OSS comparison CLI that finds actively maintained repos implementing similar components/patterns","directories":{},"_nodeVersion":"25.2.1","dependencies":{"zod":"^3.23.0","execa":"^9.0.0","env-paths":"^3.0.0","neverthrow":"^8.0.0","ts-pattern":"^5.0.0","@octokit/rest":"^21.0.0","@stricli/core":"^1.0.0"},"_hasShrinkwrap":false,"packageManager":"pnpm@9.15.0","devDependencies":{"eslint":"^9.0.0","vitest":"^2.0.0","@eslint/js":"^9.0.0","typescript":"^5.7.0","@types/node":"^22.0.0","typescript-eslint":"^8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/scout_0.1.0_1770019605564_0.14545539937945717","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@4meta5/scout","version":"0.2.0","type":"module","description":"One-shot OSS comparison CLI that finds actively maintained repos implementing similar components/patterns","main":"dist/index.js","types":"dist/index.d.ts","bin":{"scout":"dist/cli/app.js"},"scripts":{"build":"tsc","build:all":"pnpm -r build","test":"vitest run","test:all":"pnpm -r test","test:watch":"vitest","typecheck":"tsc --noEmit","typecheck:all":"pnpm -r typecheck","lint":"eslint src/","prepublishOnly":"npm run build"},"keywords":["cli","oss","github","discovery","comparison"],"author":"","license":"MIT","dependencies":{"@octokit/rest":"^21.0.0","@stricli/core":"^1.0.0","env-paths":"^3.0.0","execa":"^9.0.0","neverthrow":"^8.0.0","ts-pattern":"^5.0.0","zod":"^3.23.0"},"devDependencies":{"@eslint/js":"^9.0.0","@types/node":"^22.0.0","eslint":"^9.0.0","typescript":"^5.7.0","typescript-eslint":"^8.0.0","vitest":"^2.0.0"},"packageManager":"pnpm@9.15.0","engines":{"node":">=20"},"gitHead":"495ec7e55ccc986178a6703314ce30bb744445fc","_id":"@4meta5/scout@0.2.0","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-V0PdEbSqmFCUDdxwMGJp0EjsYv1tnNjlF6qFGN+z3SKeS54TbtbJrX/ngTCi/oWmgGH/mA7MHy7xW0NtDlIuIA==","shasum":"8d7838970e4b156e1dba9d02e74856e92fdbca9c","tarball":"https://registry.npmjs.org/@4meta5/scout/-/scout-0.2.0.tgz","fileCount":187,"unpackedSize":456484,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDwm0ZgRgBxP+Emcxrkmq9a01Pj+gFtQKQdqvphkFn9UQIgOfKvVfpafjVysi/X6/mfAZ9PxH5jayr/4ddfyk3OKoA="}]},"_npmUser":{"name":"4meta5","email":"orlandodowntownhome@gmail.com"},"directories":{},"maintainers":[{"name":"4meta5","email":"orlandodowntownhome@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/scout_0.2.0_1770166668455_0.41655670898322805"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-02T08:06:45.459Z","modified":"2026-02-04T00:57:48.695Z","0.1.0":"2026-02-02T08:06:45.703Z","0.2.0":"2026-02-04T00:57:48.588Z"},"license":"MIT","keywords":["cli","oss","github","discovery","comparison"],"description":"One-shot OSS comparison CLI that finds actively maintained repos implementing similar components/patterns","maintainers":[{"name":"4meta5","email":"orlandodowntownhome@gmail.com"}],"readme":"# scout\n\nFind actively maintained OSS implementing patterns similar to your project.\n\n[![npm](https://img.shields.io/npm/v/@4meta5/scout)](https://npmjs.com/package/@4meta5/scout)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n```bash\nnpx @4meta5/scout scan && npx @4meta5/scout discover\n```\n\n## What It Does\n\nScout analyzes your codebase and finds comparable open source projects. It:\n\n- **Scans** your project to identify what you're building (CLI, MCP server, plugin, etc.)\n- **Discovers** GitHub repos with similar patterns and active maintenance\n- **Validates** structural matches and modern development practices\n- **Generates** focused context bundles for code exploration\n\n## Quick Start\n\n1. Set your GitHub token:\n\n```bash\nexport GITHUB_TOKEN=ghp_your_token_here\n```\n\n2. Run the pipeline in your project:\n\n```bash\n# Fingerprint your project\nscout scan\n\n# Find similar repos\nscout discover\n\n# Clone top candidates\nscout clone\n\n# Validate and score\nscout validate\n\n# Generate context bundles\nscout focus\n\n# Create comparison report\nscout compare\n```\n\n3. Open `.scout/REPORT.md` for results.\n\n## Installation\n\n```bash\nnpm install -g @4meta5/scout\n```\n\nOr use directly with npx:\n\n```bash\nnpx @4meta5/scout scan\n```\n\n## Commands\n\n| Command | Description | Output |\n|---------|-------------|--------|\n| `scan` | Fingerprint local project | `fingerprint.json`, `targets.json` |\n| `discover` | Search GitHub for similar repos | `candidates.tier1.json` |\n| `clone` | Shallow clone top candidates | `clone-manifest.json` |\n| `validate` | Check structural matches | `validate-summary.json` |\n| `focus` | Generate context bundles | `FOCUS.md` per repo |\n| `compare` | Create comparison report | `REPORT.md`, `report.json` |\n\n### Compact Digest Mode\n\nFor LLM-friendly output, use the `--digest` flag:\n\n```bash\nscout compare --digest\n```\n\nThis generates a 1-2 page summary in `.scout/DIGEST.md` plus `digest.json`, suitable for Engram ingestion or Claude context windows.\n\n**Digest output structure:**\n- Top recommendation with score, license, and entry point\n- Compact alternatives table (top 5)\n- Pipeline summary (discovered → cloned → validated)\n\n## V1 Core Pipeline\n\nScout V1 provides a stable, one-shot OSS comparison pipeline:\n\n| Command | Status | Description |\n|---------|--------|-------------|\n| `scan` | Stable | Fingerprint local project |\n| `discover` | Stable | Search GitHub for similar repos |\n| `clone` | Stable | Shallow clone top candidates |\n| `validate` | Stable | Check structural matches |\n| `focus` | Stable | Generate context bundles |\n| `compare` | Stable | Create comparison report |\n\nThese 6 commands are the **V1 guarantee**. They are stable, tested, and suitable for production use.\n\n---\n\n## Experimental Features\n\n**Warning: Not part of core guarantees. May change without notice.**\n\n### Watch / Review\n\nTrack validated repos over time and generate differential review sessions.\n\n```bash\nnpm install @4meta5/scout-watch\n```\n\nOnce installed, these commands become available:\n\n- `scout watch add` - Add repo to tracking\n- `scout watch list` - List tracked repos\n- `scout watch remove` - Remove from tracking\n- `scout watch run-once` - Process updates\n- `scout review run` - Launch differential review\n\nSee [@4meta5/scout-watch](https://www.npmjs.com/package/@4meta5/scout-watch) for full documentation.\n\n## How Scoring Works\n\nScout uses a two-tier scoring system.\n\n**Tier 1 (Discovery)** scores based on:\n- Recency: How recently the repo was updated\n- Activity: Stars and forks as popularity signal\n- Lane hits: How many search patterns matched\n\n**Tier 2 (Validation)** adds:\n- Structural match: Does it implement the same patterns?\n- Modernity: ESM, TypeScript strict, modern tooling\n\n## Configuration\n\nScout uses XDG-compliant paths. Global config lives at `~/.config/scout/config.json`.\n\nProject config in `.scoutrc.json` overrides global settings:\n\n```json\n{\n  \"github\": {\n    \"token\": \"ghp_...\"\n  },\n  \"discovery\": {\n    \"recencyWindowDays\": 90,\n    \"maxCandidatesTier1\": 50,\n    \"cloneBudget\": 5\n  }\n}\n```\n\nEnvironment variable `GITHUB_TOKEN` takes precedence over config files.\n\n## Detection Targets\n\nScout identifies these component patterns:\n\n| Kind | Signals |\n|------|---------|\n| `mcp-server` | @modelcontextprotocol deps, MCP config files |\n| `cli` | bin field, commander/yargs/stricli deps |\n| `skill` | SKILL.md, skills/ directory |\n| `hook` | hooks/ directory, git hook patterns |\n| `plugin` | plugins/ directory, plugin manifests |\n| `library` | Fallback for npm packages |\n\n## Output Structure\n\nAll outputs go to `.scout/` by default:\n\n```\n.scout/\n  fingerprint.json      # Project analysis\n  targets.json          # Detected component types\n  candidates.tier1.json # Discovery results\n  clone-manifest.json   # Cloned repos\n  validate-summary.json # Validation scores\n  focus/\n    owner-repo/\n      FOCUS.md          # Context bundle\n      RUN_HINTS.md      # Build/test commands\n      PROVENANCE.md     # Source tracking\n  REPORT.md             # Final comparison\n  report.json           # Machine-readable report\n```\n\n## Development\n\nThis is a pnpm workspace. Core package is at root, optional packages under `packages/`.\n\n```bash\npnpm install          # Install all dependencies\npnpm build            # Build core only\npnpm build:all        # Build all packages\npnpm test             # Test core only\npnpm test:all         # Test all packages\npnpm typecheck:all    # Type check all packages\n```\n\n## Requirements\n\n- Node.js 20+\n- GitHub token with `public_repo` scope\n\n## License\n\nMIT\n","readmeFilename":"README.md"}