{"id":50800868,"url":"https://github.com/freshtechbro/specatlas","last_synced_at":"2026-06-12T19:33:44.405Z","repository":{"id":358447632,"uuid":"1241180611","full_name":"freshtechbro/specatlas","owner":"freshtechbro","description":"SpecAtlas is a CLI-first product reverse-engineering and clean-room planning system.","archived":false,"fork":false,"pushed_at":"2026-05-17T11:57:36.000Z","size":261,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T13:42:45.096Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/freshtechbro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-17T03:55:02.000Z","updated_at":"2026-05-17T11:57:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/freshtechbro/specatlas","commit_stats":null,"previous_names":["freshtechbro/specatlas"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/freshtechbro/specatlas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freshtechbro%2Fspecatlas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freshtechbro%2Fspecatlas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freshtechbro%2Fspecatlas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freshtechbro%2Fspecatlas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/freshtechbro","download_url":"https://codeload.github.com/freshtechbro/specatlas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freshtechbro%2Fspecatlas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34260309,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T19:33:41.646Z","updated_at":"2026-06-12T19:33:44.376Z","avatar_url":"https://github.com/freshtechbro.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SpecAtlas\n\nSpecAtlas is a CLI-first product intelligence and clean-room planning workspace. It turns safe product, repository, web, API, artifact, and worker evidence into a structured SpecAtlas package: 30 decomposition maps, reports, graphs, evidence ledgers, clean-room handoffs, and agent task plans.\n\nThe Rust core owns product behavior. Workers are invoked by the core as subprocess adapters; web, desktop, server, and MCP surfaces either call the core or read generated packages through shared schemas and contracts.\n\n## Contents\n\n| Start | Product | Run | Surfaces | Project |\n|---|---|---|---|---|\n| [Quick start](#quick-start) | [What SpecAtlas is](#what-specatlas-is) | [CLI workflows](#cli-workflows) | [Web workbench](#web-workbench) | [Repository layout](#repository-layout) |\n| [Prerequisites](#prerequisites) | [What SpecAtlas does](#what-specatlas-does) | [Common commands](#common-commands) | [Desktop shell](#desktop-shell) | [Generated package layout](#generated-package-layout) |\n| [Install](#install) | [What SpecAtlas does not do](#what-specatlas-does-not-do) | [Server and MCP](#server-and-mcp) | [Workers and plugins](#workers-and-plugins) | [Documentation map](#documentation-map) |\n| [Quality gates](#quality-gates) | [Architecture](#architecture) | [Package validation](#package-validation) | [Safety model](#safety-model) | [Agent notes](#agent-notes) |\n\n## Quick start\n\n```bash\nnpm install\ncargo run -q -p specatlas-cli -- --help\ncargo run -q -p specatlas-cli -- study WebPilot target/specatlas-routes/study\nnpm --prefix apps/web run dev\n```\n\nOpen the web workbench at `http://127.0.0.1:5173/?manifest=/sample-package/specatlas-package-manifest.json`, or upload a generated package directory in the browser.\n\n## What SpecAtlas is\n\nSpecAtlas is a local-first system for converting authorized evidence into a buildable clean-room implementation package. It supports two main operating modes:\n\n- Product teardown clean-room planning: discover product structure, competitive context, features, architecture, risks, and implementation tasks without copying protected expression.\n- Instrumentation mode: normalize worker output from safe fixtures, imports, static analyzers, browser observations, and metadata tools into package evidence.\n\nSpecAtlas is designed for repeatable package generation, agent handoff, safety review, and package inspection rather than ad hoc prose reports.\n\n## What SpecAtlas does\n\n- Runs CLI workflows for study, research, repository analysis, static analysis, URL analysis, web crawl, API inference, artifact import, decomposition, clean-room specs, agent plans, and instrumentation.\n- Produces 30 canonical decomposition maps plus reports, graphs, risk records, policy decisions, agent handoffs, and task DAGs.\n- Enforces Rust-core policy and sanitization before writing agent-facing reports and handoffs.\n- Runs Python and Node workers behind stdio adapter contracts.\n- Provides a read-only React workbench for package review.\n- Provides a Tauri desktop shell around the web workbench and local CLI workflows.\n- Provides server and MCP boundaries for collaboration metadata, JSON-RPC resources, and safe package access.\n\n## What SpecAtlas does not do\n\n- It does not copy proprietary assets, hidden implementation, private code, or blocked evidence into agent outputs.\n- It does not treat web, desktop, workers, or server code as product logic owners.\n- It does not silently fake external analyzer success. Missing tools must produce unavailable diagnostics.\n- It does not expose blocked evidence content through reports, web previews, MCP resources, or agent handoffs.\n- It does not claim hosted persistence is verified unless the configured server boundary and quality gates have actually run.\n\n## Prerequisites\n\n- Rust \u003e= 1.78, edition 2021.\n- Node \u003e= 20.\n- Python \u003e= 3.11.\n- Optional `just` for command aliases.\n- Tauri platform prerequisites when building the desktop app.\n- Optional `cargo llvm-cov` for the final 97 percent coverage gate.\n\n## Install\n\n```bash\nnpm install\ncargo metadata --format-version 1 --no-deps\npython3 -m compileall -q workers\n```\n\nRust dependencies are resolved by Cargo. Node workspaces are `apps/web` and `apps/desktop`. Python worker tests use the standard library test runner in this repository.\n\n## Common commands\n\n```bash\n# Rust\ncargo fmt --all -- --check\ncargo clippy --all-targets --all-features -- -D warnings\ncargo test --all-targets --all-features\ncargo llvm-cov --workspace --all-targets --all-features --fail-under-lines 97 --summary-only -j 1\n\n# Root JS, Python, web\nnpm run lint\nnpm run typecheck\nnpm run test\nnpm run build\nnpm run check\n\n# Smoke and final gates\nnpm run desktop:smoke\nnpm run package:smoke\nnpm run quality:final\n\n# Optional just aliases\njust check\njust schema-validate\n```\n\n## CLI workflows\n\nUse the workspace binary through Cargo while developing:\n\n```bash\ncargo run -q -p specatlas-cli -- \u003ccommand\u003e\n```\n\nGlobal flags parsed by the CLI:\n\n```text\n--output \u003cdir\u003e\n--format json|text\n--json\n--mode \u003cmode\u003e\n--profile \u003cprofile\u003e\n--authorization \u003cscope\u003e\n--policy \u003cname\u003e\n--evidence-required\n--no-proprietary-assets\n--no-copied-copy\n--product-description \u003ctext\u003e\n--example-url \u003curl\u003e\n--seed-repo \u003curl\u003e\n--stage \u003cstage\u003e\n--discovery-import \u003cpath\u003e\n```\n\nImplemented command surfaces:\n\n```bash\ncargo run -q -p specatlas-cli -- init specatlas-project\ncargo run -q -p specatlas-cli -- identify \u003ctarget\u003e specatlas-project\ncargo run -q -p specatlas-cli -- teardown \u003cproduct-name\u003e --product-description \"\u003cintent\u003e\" --example-url \u003curl\u003e --discovery-import \u003cverified-worker-or-fixture-json\u003e --output target/specatlas-routes/teardown\ncargo run -q -p specatlas-cli -- study \u003ctarget\u003e --output target/specatlas-routes/study\ncargo run -q -p specatlas-cli -- research external \u003cproduct-name\u003e --output target/specatlas-routes/research\ncargo run -q -p specatlas-cli -- find-repos \u003cproduct-name\u003e --output target/specatlas-routes/find-repos\ncargo run -q -p specatlas-cli -- find-analogs \u003cproduct-name\u003e --output target/specatlas-routes/find-analogs\ncargo run -q -p specatlas-cli -- repo analyze \u003cpath-or-url\u003e --output target/specatlas-routes/repo\ncargo run -q -p specatlas-cli -- analyze \u003ctarget\u003e --profile safe-static --output target/specatlas-routes/analyze\ncargo run -q -p specatlas-cli -- analyze-url \u003curl\u003e --profile web-observe --output target/specatlas-routes/analyze-url\ncargo run -q -p specatlas-cli -- web crawl \u003curl\u003e --output target/specatlas-routes/web-crawl\ncargo run -q -p specatlas-cli -- api infer \u003cpath\u003e --output target/specatlas-routes/api-infer\ncargo run -q -p specatlas-cli -- import \u003cartifact-or-tool-output\u003e --output target/specatlas-routes/import\ncargo run -q -p specatlas-cli -- decompose \u003ctarget\u003e --output target/specatlas-routes/decompose\ncargo run -q -p specatlas-cli -- cleanroom-spec \u003ctarget\u003e --output target/specatlas-routes/cleanroom-spec\ncargo run -q -p specatlas-cli -- agent-plan \u003ctarget\u003e --output target/specatlas-routes/agent-plan\ncargo run -q -p specatlas-cli -- instrument \u003cworker-output-json\u003e --output target/specatlas-routes/instrument\ncargo run -q -p specatlas-cli -- report specatlas-project\ncargo run -q -p specatlas-cli -- doctor specatlas-project\n```\n\nProduct Teardown is first-class at the CLI through `teardown \u003cproduct-name\u003e`. The import-backed workflow accepts structured product intent, consumes verified discovery imports, writes ranked repository candidates under `artifacts/repos/product-teardown-repositories.json`, writes search and analog artifacts under `artifacts/imports/`, then feeds the existing 30-map clean-room report and handoff pipeline. Stage routes such as `find-repos`, `find-analogs`, `research external`, and `repo analyze` are wrappers around the same evidence and policy gates.\n\nCapability truth table:\n\n| Stage | Status | Notes |\n|---|---|---|\n| Structured intake | Implemented | `--product-description`, `--example-url`, `--seed-repo`, `--stage`, and `--discovery-import` are parsed by the CLI. |\n| Verified discovery import | Implemented | Reuses fixture provenance or trusted worker-output authority before evidence can be reused. |\n| Search, repo, and analog artifacts | Import-backed | Writes typed artifacts only when reviewed evidence is reusable. |\n| Repository ranking | Implemented | Rust core scores relevance, activity, license, maintenance, and safety from sanitized metadata. |\n| Live provider discovery | Controlled-adapter boundary | Worker manifests exist for `search-discovery` and `github-discovery`, but live provider execution is not claimed. |\n| Clean-room maps, reports, handoff | Implemented | Existing Product Teardown decomposition, report, and agent handoff consume sanitized evidence only. |\n\nPlugin commands:\n\n```bash\ncargo run -q -p specatlas-cli -- plugins list examples/worker-plugin-registry\ncargo run -q -p specatlas-cli -- plugins install examples/worker-plugin-registry/research.json\ncargo run -q -p specatlas-cli -- plugins run examples/worker-plugin-registry research fixture-product target/plugin-output\n```\n\n## Server and MCP\n\nServer metadata and local HTTP control plane:\n\n```bash\ncargo run -q -p specatlas-cli -- server\ncargo run -q -p specatlas-cli -- server status\ncargo run -q -p specatlas-cli -- server start --host 127.0.0.1 --port 7417 --max-requests 1\n```\n\nAdd `--enable-demo` only for local demo mutation routes. Server status reports `local_ready`, `partially_configured`, or `configured_not_verified` based on environment configuration. Hosted boundary variables are:\n\n```bash\nSPECATLAS_DATABASE_URL=postgres://specatlas:specatlas_dev_only@localhost:5432/specatlas\nSPECATLAS_OBJECT_STORE=http://127.0.0.1:9000\nSPECATLAS_OBJECT_BUCKET=specatlas-artifacts\n```\n\nLocal infra templates live in `infra/docker-compose.yml` and `infra/server.Dockerfile`.\n\nMCP command:\n\n```bash\ncargo run -q -p specatlas-cli -- mcp serve\n```\n\nWhen stdin is non-interactive, `mcp serve` reads newline-delimited JSON-RPC and returns safe resources and tool responses.\n\n## Web workbench\n\nThe web workbench is a read-only React and TypeScript package reviewer in `apps/web`.\n\n```bash\nnpm --prefix apps/web run dev\nnpm --prefix apps/web run build\nnpm --prefix apps/web run test\nnpm --prefix apps/web run typecheck\n```\n\nImportant facts:\n\n- Vite serves on `127.0.0.1`.\n- Build output is `apps/web/dist/`.\n- The bundled sample manifest is `apps/web/public/sample-package/specatlas-package-manifest.json`.\n- The required package entry is `reports/report.json`.\n- The loader rejects unsafe paths and redacts blocked evidence before display.\n\n## Desktop shell\n\nThe desktop app is a Tauri 2 shell in `apps/desktop`. It wraps the web workbench and local CLI-backed package workflows.\n\n```bash\nnpm --prefix apps/desktop run dev\nnpm --prefix apps/desktop run build\nnpm --prefix apps/desktop run smoke\ncargo test --manifest-path apps/desktop/src-tauri/Cargo.toml\n```\n\nThe bundle target is the macOS `app` bundle configured in `apps/desktop/src-tauri/tauri.conf.json`. Local studies use the `specatlas` binary or the `SPECATLAS_CLI` environment variable when set.\n\n## Workers and plugins\n\nWorkers are subprocess adapters, not product logic owners.\n\n- Python entry: `workers/bin/specatlas-worker-python`.\n- Node entry: `workers/bin/specatlas-worker-node`.\n- Adapter schemas: `schemas/adapter_job.schema.json` and `schemas/adapter_event.schema.json`.\n- Manifests: `workers/manifests/*.json`.\n- Runtime profiles: `safe-static`, `web-observe`, `mobile-package`, and `report-only`.\n- Example plugin registry: `examples/worker-plugin-registry/`.\n\nWorker checks:\n\n```bash\npython3 -m compileall -q workers\npython3 -m unittest discover -s workers/tests\nnode --test workers/node/browser-worker.test.mjs\nnode --check workers/node/browser-worker.mjs\n```\n\n## Package validation\n\nGenerated packages use a constrained path layout. Rebuild a package manifest with:\n\n```bash\nnode scripts/build-package-manifest.mjs \u003cpackage-root\u003e\n```\n\nThe manifest builder rejects symlinks, hidden paths, unsupported roots, and invalid artifact object digests. Package smoke verifies web dist, desktop config, infra templates, `schemas/evidence.schema.json`, and the release readiness log.\n\n## Generated package layout\n\nA complete package can include:\n\n| Path | Purpose |\n|---|---|\n| `project.json` | Project metadata. |\n| `run.json`, `runs/*.json` | Run metadata and history. |\n| `specatlas-package-manifest.json` | Safe package file list. |\n| `maps/` | 30 canonical decomposition maps plus graph projections. |\n| `reports/` | Markdown, JSON, HTML, risk, UX, API, clean-room, and roadmap reports. |\n| `agent/` | Clean-room rules, handoff, prompts, milestones, tasks, and task DAG files. |\n| `evidence/` | Sources, events, claims, and policy decision ledgers. |\n| `graphs/` | Product and software graph JSON and SQLite outputs. |\n| `artifacts/` | Files, screenshots, traces, HAR, imports, repos, plugin outputs, and hashed objects. |\n| `projections/` | Boundary metadata such as DuckDB status. |\n\n## Architecture\n\n```text\nCLI commands\n  -\u003e Rust core workflows and policy\n  -\u003e workers through adapter contracts\n  -\u003e generated SpecAtlas package\n  -\u003e web, desktop, MCP, and server readers\n```\n\nCore architecture rules:\n\n- `crates/specatlas-cli` is the command surface.\n- `crates/specatlas-core` routes workflows and writes packages.\n- `crates/specatlas-policy`, `specatlas-cleanroom`, `specatlas-report`, `specatlas-decomposition`, and graph crates own product logic.\n- `crates/specatlas-server` owns collaboration metadata and hosted boundaries, not product analysis.\n- `crates/specatlas-mcp` exposes safe resources and tools.\n- `schemas/` define cross-boundary JSON contracts.\n\n## Repository layout\n\n| Path | Purpose |\n|---|---|\n| `crates/` | Rust workspace crates and CLI. |\n| `apps/web/` | React package workbench. |\n| `apps/desktop/` | Tauri desktop shell. |\n| `workers/` | Python and Node adapter runtimes. |\n| `schemas/` | JSON schemas for package and adapter contracts. |\n| `scripts/` | Quality, smoke, and package manifest scripts. |\n| `docs/` | Architecture, mode, safety, deployment, packaging, and development docs. |\n| `examples/` | Worker job examples and plugin registry fixtures. |\n| `corpus/` | Safe fixtures and golden outputs. |\n| `infra/` | Local server, Postgres, and object store templates. |\n| `tests/e2e/` | Full workflow Rust tests. |\n\n## Safety model\n\nSpecAtlas separates evidence collection from agent-consumable outputs. Blocked evidence can remain in ledgers for audit, but reports, agent handoffs, MCP resources, and web previews must show only safe references or redacted markers. Clean-room policy flags include evidence requirements, no proprietary assets, and no copied copy.\n\n## Quality gates\n\n`npm run quality:final` runs:\n\n1. `cargo fmt --all -- --check`\n2. `cargo clippy --all-targets --all-features -- -D warnings`\n3. `cargo test --all-targets --all-features`\n4. `cargo llvm-cov --workspace --all-targets --all-features --fail-under-lines 97 --summary-only -j 1`\n5. `cargo run -q -p specatlas-cli -- mcp serve`\n6. `cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml`\n7. `python3 -m compileall -q workers`\n8. `python3 -m unittest discover -s workers/tests`\n9. `node --test workers/node/browser-worker.test.mjs`\n10. `npm run check`\n11. `npm --prefix apps/desktop run build`\n12. `npm run desktop:smoke`\n13. `npm run package:smoke`\n\nDo not update release readiness results unless these gates are actually run.\n\n## Documentation map\n\n- [Architecture](docs/architecture.md)\n- [Modes](docs/modes.md)\n- [Adapter spec](docs/adapter-spec.md)\n- [Plugin API](docs/plugin-api.md)\n- [Web workbench](docs/web-workbench.md)\n- [Desktop](docs/desktop.md)\n- [Deployment](docs/deployment.md)\n- [Development](docs/development.md)\n- [Safety](docs/safety.md)\n- [Mobile companion mode](docs/mobile-companion-mode.md)\n- [Packaging](docs/packaging.md)\n- [Release readiness](docs/release-readiness.md)\n- [Worker docs](workers/README.md)\n\n## Agent notes\n\nScoped agent instructions:\n\n- [Root agent notes](AGENTS.md)\n- [Rust crates notes](crates/AGENTS.md)\n- [Web workbench notes](apps/web/AGENTS.md)\n- [Desktop notes](apps/desktop/AGENTS.md)\n- [Workers notes](workers/AGENTS.md)\n- [Docs notes](docs/AGENTS.md)\n- [Scripts notes](scripts/AGENTS.md)\n- [Schemas notes](schemas/AGENTS.md)\n- [Infra notes](infra/AGENTS.md)\n- [Tests notes](tests/AGENTS.md)\n- [Corpus notes](corpus/AGENTS.md)\n- [Examples notes](examples/AGENTS.md)\n\nRead the nearest `AGENTS.md` before editing within a subdirectory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreshtechbro%2Fspecatlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreshtechbro%2Fspecatlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreshtechbro%2Fspecatlas/lists"}