From df3a428e37ef74c18461c1567cc32ad69ebd0959 Mon Sep 17 00:00:00 2001 From: 1norahc Date: Sun, 13 Sep 2026 15:15:46 +0200 Subject: [PATCH] docs: complete MVP release readiness (#103) --- .github/workflows/ci.yml | 4 + CHANGELOG.md | 30 +++++ README.md | 25 ++-- docs/README.md | 16 +++ docs/examples/map-self-scan.json | 13 +++ docs/getting-started.md | 15 ++- docs/project/MVP_IMPLEMENTATION_REPORT.md | 107 ++++++++++++++++++ docs/project/ROADMAP.md | 15 ++- docs/specifications/README.md | 14 +++ library/LICENSING.md | 2 +- library/README.md | 17 ++- library/docs/README.md | 6 +- library/docs/specs/website.md | 8 +- library/examples/claude-code/README.md | 6 +- .../examples/poc-pattern-catalog/README.md | 21 ++-- tooling/README.md | 37 +++--- .../cli/registry-snapshot/registry.json | 2 +- tooling/packages/cli/scripts/sync-snapshot.ts | 40 ++++++- 18 files changed, 312 insertions(+), 66 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 docs/README.md create mode 100644 docs/examples/map-self-scan.json create mode 100644 docs/project/MVP_IMPLEMENTATION_REPORT.md create mode 100644 docs/specifications/README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 621572d..9be1d65 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -39,6 +39,10 @@ jobs: - run: pnpm lint - run: pnpm typecheck - run: pnpm test + - name: Check the bundled registry snapshot + env: + MAP_REPO: ${{ github.workspace }} + run: node packages/cli/scripts/sync-snapshot.ts --check - name: Test the GitHub installer working-directory: . run: | diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e172712 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,30 @@ +# Changelog + +## Unreleased — architecture-layer MVP + +### Added + +- Product, system, pattern graph, scanner, recommendation, verification, CLI, MCP, and + security architecture documentation. +- AI-focused ADRs for the deterministic core, stable pattern identity, versioned CLI + JSON, static analysis, and MCP isolation. +- Pattern Schema v1 plus scan and recommendation result schemas with fixtures. +- `map list`, `search`, `show`, `scan`, `suggest`, `graph`, and `validate`. +- Evidence certainty and explicit static-analysis limitations. +- Registry snapshot freshness enforcement in CI. + +### Changed + +- The YAML reader now supports folded and literal block strings used by pattern + metadata. +- README and library documentation now use the GitHub-only installation path and + consolidated monorepo structure. +- Saved analysis reports use the versioned scan-result envelope. + +### Compatibility + +- `map patterns`, `explain`, `analyze`, and `recommend` remain supported. +- Pattern IDs remain `category/slug` for schema version 1. +- Existing flat `related` metadata remains valid and maps to `works_with` graph edges. + +Earlier CLI changes are recorded in [`tooling/CHANGELOG.md`](tooling/CHANGELOG.md). diff --git a/README.md b/README.md index 3b89ed4..5ff5080 100644 --- a/README.md +++ b/README.md @@ -72,8 +72,9 @@ git pull --ff-only ```bash cd your-project map init -map analyze -map recommend +map scan --json +map suggest +map search retrieval map optimize --save map sync ``` @@ -98,9 +99,9 @@ existing files: ## One workflow, every agent ```text -project code ──▶ map analyze ──▶ detected AI architecture +project code ──▶ map scan ────▶ detected AI architecture │ -MAP library ──▶ map recommend ──▶ missing patterns +MAP library ──▶ map suggest ──▶ patterns to review │ map add / edit .map/ │ @@ -114,14 +115,21 @@ MAP library ──▶ map recommend ──▶ missing patterns | Command | Result | |---|---| | `map init` | Creates the `.map/` workspace and detects the project shape. | -| `map analyze` | Finds AI-related dependencies and architecture signals. | -| `map recommend` | Suggests missing patterns with evidence and priority. | -| `map patterns [query]` | Searches the local pattern catalog. | +| `map scan [path] [--json]` | Finds static AI architecture signals, evidence, certainty, and limits. | +| `map suggest [path] [--json]` | Suggests review candidates with triggers, rationale, and priority. | +| `map list [--json]` | Lists the local pattern catalog. | +| `map search [query] [--json]` | Searches patterns by ID, name, or summary. | +| `map show [--json]` | Shows one pattern and its decision guidance. | +| `map graph [pattern-id] [--json]` | Inspects the catalog as typed relationships. | | `map add ` | Adds a pattern prompt, metadata, and acceptance criteria. | +| `map validate [--json]` | Validates the project manifest and adopted pattern integrity. | | `map optimize --check` | Measures context and enforces the configured token budget. | | `map sync` | Generates instructions for supported AI coding assistants. | | `map doctor` | Checks the workspace, registry, compiler, and references. | +The original `analyze`, `recommend`, `patterns`, and `explain` commands remain +supported as compatible names. + ## What is inside this repository? | Area | Purpose | @@ -140,6 +148,9 @@ and verifiable acceptance criteria. - [Getting started](docs/getting-started.md) - [Project structure](docs/project-structure.md) +- [Product vision and MVP](docs/project/VISION.md) +- [System architecture](docs/architecture/README.md) +- [Machine-readable specifications](docs/specifications/) - [Pattern library](library/README.md) - [Human- and AI-readable schemas](library/docs/schemas/README.md) - [MAP Standard RFC](library/rfcs/0001-map-standard.md) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..cc747bf --- /dev/null +++ b/docs/README.md @@ -0,0 +1,16 @@ +# MAP documentation + +## Start here + +- [Getting started](getting-started.md) +- [Project structure](project-structure.md) +- [Vision](project/VISION.md), [product specification](project/PRODUCT_SPEC.md), and + [MVP scope](project/MVP.md) +- [Architecture overview](architecture/README.md) +- [Machine-readable specifications](specifications/) +- [Phase 0 repository audit](project/CURRENT_STATE.md) +- [MVP implementation report](project/MVP_IMPLEMENTATION_REPORT.md) + +Reusable AI engineering content lives in the [pattern library](../library/README.md). +Architecture decisions for MAP itself live in [`.map/decisions`](../.map/decisions/). + diff --git a/docs/examples/map-self-scan.json b/docs/examples/map-self-scan.json new file mode 100644 index 0000000..e184908 --- /dev/null +++ b/docs/examples/map-self-scan.json @@ -0,0 +1,13 @@ +{ + "schemaVersion": 1, + "kind": "map.scan-result", + "root": "/workspace/map/tooling", + "detectedAt": "2026-09-13T13:08:19.022Z", + "analyzers": ["dependency-manifest"], + "inspected": ["package.json"], + "concepts": [], + "limitations": [ + "Dependency manifests indicate declared packages, not whether or how code uses them.", + "The MVP scanner does not inspect source code, runtime behavior, nested workspaces, or secret values." + ] +} diff --git a/docs/getting-started.md b/docs/getting-started.md index df48d96..d795721 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -30,19 +30,22 @@ existing files unless `--force` is explicitly supplied. ## 3. Understand the architecture ```bash -map analyze -map recommend -map patterns retrieval +map scan +map suggest +map search retrieval ``` -`analyze` detects architecture signals from project manifests. `recommend` -maps those signals to production patterns, and `patterns` lets you browse the -full library. +`scan` detects evidence-backed architecture signals from project manifests and states +the limits of static analysis. `suggest` maps those signals to review candidates with +reasons, and `search` lets you browse the full library. Add `--json` to consume stable +scan and recommendation contracts from scripts or agents. The older `analyze`, +`recommend`, and `patterns` names remain supported. ## 4. Adopt knowledge into the project ```bash map add retrieval/chunking +map validate ``` The pattern's prompt, acceptance criteria, and metadata are copied into diff --git a/docs/project/MVP_IMPLEMENTATION_REPORT.md b/docs/project/MVP_IMPLEMENTATION_REPORT.md new file mode 100644 index 0000000..cfc08d9 --- /dev/null +++ b/docs/project/MVP_IMPLEMENTATION_REPORT.md @@ -0,0 +1,107 @@ +# MVP implementation report + +Status date: 2026-09-13 +Tracking issue: [#103](https://github.com/rajanbor/map/issues/103) + +## Outcome + +MAP now has a documented and working deterministic architecture-layer MVP. It keeps +the existing pattern catalog and `.map/` context compiler, adds enforced public +contracts, exposes a queryable pattern graph, and completes a local workflow from +discovery through structural validation. + +The implementation was delivered as reviewable stages: + +- [#104](https://github.com/rajanbor/map/pull/104): repository audit and baseline; +- [#105](https://github.com/rajanbor/map/pull/105): product, architecture, + specifications, security model, and ADRs; +- [#106](https://github.com/rajanbor/map/pull/106): Pattern Schema v1; +- [#107](https://github.com/rajanbor/map/pull/107): deterministic CLI MVP and result + schemas. + +## Implemented + +### Contracts + +- Six offline-validated JSON Schema contracts: document, project, decision, pattern, + scan result, and recommendation result. +- Pattern and anti-pattern base model with stable slash IDs, lifecycle, evidence, + MAP Score, legacy relations, and six typed relation kinds. +- Complete valid fixtures and at least three invalid fixtures per schema. +- Repository validation for every published `pattern.yaml`, directory identity, + required files, duplicate IDs, and relationship targets. + +### CLI and core + +- `list`, `search`, and `show`, with JSON discovery output. +- `scan` with evidence, confidence, certainty, inspected inputs, analyzers, and limits. +- `suggest` with deterministic priorities, triggers, and rationales. +- `graph` over 96 catalog nodes and 37 normalized typed edges. +- `validate` for `.map/map.config.json` and adopted-pattern file integrity. +- Backward-compatible `patterns`, `explain`, `analyze`, and `recommend` commands. +- Existing `init`, `add`, `sync`, `watch`, `optimize`, `doctor`, and `update` behavior + retained. + +### Operations + +- GitHub-only installer remains the documented distribution path. +- Bundled registry snapshot refreshed from the consolidated monorepo. +- CI now fails when the snapshot content differs from the registry built from source. +- README and library entry points describe the actual monorepo and install path. + +## Dogfood result + +The built CLI was run against MAP itself: + +```text +map scan tooling --json valid map.scan-result +map suggest tooling --json valid map.recommendation-result +map graph retrieval/chunking --json + 1 selected node, 6 outgoing works_with edges +map validate --json valid; .map/map.config.json checked +``` + +The retained [self-scan example](../examples/map-self-scan.json) sanitizes the local +path. It contains no detections because the selected root `tooling/package.json` has no +AI runtime dependency. Crucially, it reports that nested workspaces and source code +were not inspected; the result is limited evidence, not a claim that MAP contains no +AI-related architecture. + +## Verification evidence + +```text +registry builder: 96 patterns, pass +schema validator: 6 contracts, pass +build: pass +lint: pass +typecheck: pass +tests: 146 pass (130 CLI, 13 score, 3 registry) +pnpm audit: no known vulnerabilities +installer smoke: pass in required CI job +CLI JSON smoke: scan, suggest, graph, validate pass +``` + +## Known limits + +- The scanner reads supported manifests only at the selected root. It does not yet + traverse monorepos or parse source and runtime behavior. +- Current pattern metadata uses legacy `related` lists. The graph deliberately + normalizes these to `works_with`; stronger relation semantics require author review. +- The rule-based recommender uses detected concepts, not declared project intent or + verified adopted-pattern state. +- `validate` proves contract and file integrity, not pattern implementation. +- Anti-patterns can be modeled and validated, but none is published in the catalog yet. +- MCP, architecture diff, semantic indexing, and LLM-assisted analysis are deferred + adapters. +- The npm package is not published; installation is from GitHub. + +## Recommended next increments + +1. Add bounded monorepo discovery with include/exclude rules and evidence de-duplication. +2. Migrate reviewed pattern relations from legacy lists to explicit typed claims. +3. Define adopted intent and verification checks before graph-backed recommendation + ranking. +4. Publish the first anti-pattern with evidence and a `solves` relation. +5. Align library and SDK version streams before promising npm distribution. +6. Implement a read-only MCP adapter only after the core API contract is stable. + diff --git a/docs/project/ROADMAP.md b/docs/project/ROADMAP.md index 619b390..5594bc8 100644 --- a/docs/project/ROADMAP.md +++ b/docs/project/ROADMAP.md @@ -19,15 +19,19 @@ This roadmap describes capabilities. The pattern publication backlog remains in ## 2 — Evidence and verification -- Add recursive workspace discovery and configurable source analyzers. -- Model declared project intent and adopted-pattern verification. +- Add recursive workspace discovery and configurable source analyzers + ([#108](https://github.com/rajanbor/map/issues/108)). +- Model declared project intent and adopted-pattern verification + ([#110](https://github.com/rajanbor/map/issues/110)). - Add architecture diff, verification reports, and CI policy levels. -- Expand evidence provenance and pattern lifecycle governance. +- Expand evidence provenance, typed relations, graph-backed explanations, and pattern + lifecycle governance ([#109](https://github.com/rajanbor/map/issues/109)). ## 3 — Ecosystem adapters - Publish a protocol-neutral core API. -- Add an MCP adapter as a separate package. +- Add a read-only MCP adapter as a separate package + ([#111](https://github.com/rajanbor/map/issues/111)). - Define safe adapter and plugin discovery without executing untrusted code. - Add framework mappings that never become the canonical pattern model. @@ -40,3 +44,6 @@ This roadmap describes capabilities. The pattern publication backlog remains in Each phase must preserve deterministic offline behavior as the baseline and may add assisted behavior only as an explicit adapter. +Release-stream alignment and optional npm preparation are tracked separately in +[#112](https://github.com/rajanbor/map/issues/112); GitHub remains the supported +installation path until that work is complete and publicly verified. diff --git a/docs/specifications/README.md b/docs/specifications/README.md new file mode 100644 index 0000000..f502491 --- /dev/null +++ b/docs/specifications/README.md @@ -0,0 +1,14 @@ +# Specifications + +These documents explain MAP's versioned machine contracts in human terms: + +- [Pattern specification](PATTERN_SPEC.md) +- [Pattern Schema v1](PATTERN_SCHEMA.md) +- [MAP project manifest](MAP_MANIFEST.md) +- [Scan Result v1](SCAN_RESULT.md) +- [Recommendation Result v1](RECOMMENDATION_RESULT.md) +- [Verification Result design](VERIFICATION_RESULT.md) + +Normative JSON Schemas and fixtures live in [`library/schemas`](../../library/schemas/). +Architecture rationale lives in [`docs/architecture`](../architecture/), and accepted +decisions live in [`.map/decisions`](../../.map/decisions/). diff --git a/library/LICENSING.md b/library/LICENSING.md index 6ef3204..42f2990 100644 --- a/library/LICENSING.md +++ b/library/LICENSING.md @@ -6,7 +6,7 @@ MAP uses two licenses so it's easy to build on, while authorship stays credited. | What | License | You can | You must | |------|---------|---------|----------| -| **Code** — `reference/`, `examples/`, `scripts/` (the CLI lives in [missing-ai-patterns/cli](https://github.com/rajanbor/map/tree/main/tooling)) | [MIT](LICENSE) | Use, copy, modify, fork, ship commercially | Keep the copyright notice | +| **Code** — `reference/`, `examples/`, `scripts/`, and [`tooling/`](../tooling/) | [MIT](LICENSE) | Use, copy, modify, fork, ship commercially | Keep the copyright notice | | **Content** — `patterns/`, `docs/`, prose, diagrams | [CC BY 4.0](LICENSE-CONTENT) | Use, share, adapt, even commercially | **Give attribution** to MAP / the author | | **Name & brand** — "MAP", "Missing AI Patterns", logos | Reserved (not licensed) | — | Use a different name for forks | diff --git a/library/README.md b/library/README.md index c35e45e..acc5298 100644 --- a/library/README.md +++ b/library/README.md @@ -113,8 +113,8 @@ map/ .github/ Contributor experience: templates, labels, discussions, CI ``` -The **MAP CLI** lives in its own repository, -[missing-ai-patterns/cli](https://github.com/rajanbor/map/tree/main/tooling). It consumes the +The **MAP CLI** lives in this repository under +[`tooling/`](../tooling/). It consumes the **registry** — the machine-readable catalog this repository publishes with every release (see the [registry spec](docs/specs/registry.md)). @@ -168,13 +168,18 @@ and guardrails, so its decisions are consistent and reviewable. See the The [MAP CLI](https://github.com/rajanbor/map/tree/main/tooling) surfaces this directly: +Install it from GitHub (the npm package is not published yet): + ```bash -npm install -g @missing-ai-patterns/cli +git clone https://github.com/rajanbor/map.git +cd map +./scripts/install.sh -map explain retrieval/chunking # what the pattern is and when to use it +map init +map show retrieval/chunking # what the pattern is and when to use it map add retrieval/chunking # copy prompt.md + acceptance.md into your .map/ workspace -map analyze # detect the AI architecture already in your project -map recommend # which MAP patterns your architecture is missing +map scan # detect evidence-backed architecture signals +map suggest # review patterns your architecture may need ``` ## Contributing diff --git a/library/docs/README.md b/library/docs/README.md index eb6393a..5e4afd6 100644 --- a/library/docs/README.md +++ b/library/docs/README.md @@ -14,12 +14,12 @@ Specifications (the contracts tools build on — see the - **[Pattern Contract](pattern-contract.md)** — the files every pattern ships and who consumes them. - **[MAP Score](specs/map-score.md)** — the five-dimension 1–5 star rating. *(implemented)* - **[Registry](specs/registry.md)** — the machine-readable catalog artifact published on each release. *(implemented)* -- **[Pattern Schema](specs/pattern-schema.md)** — the formal, build-enforced schema for `pattern.yaml`. *(draft)* +- **[Pattern Schema](specs/pattern-schema.md)** — the formal, build-enforced schema for `pattern.yaml`. *(implemented)* - **[Pattern Lifecycle](specs/pattern-lifecycle.md)** — claiming, maturity, deprecation, and renames. *(draft)* - **[Decision Guides](specs/decision-guides.md)** — cross-category "X or Y?" guides and their contract. *(draft)* - **[Website](specs/website.md)** — the ultra-simple registry-fed site. *(draft)* - **[MAP Schemas](schemas/README.md)** — machine contracts paired with human guides and fixtures. For the patterns themselves, see [`../patterns/`](../patterns/). To contribute, see -[`../CONTRIBUTING.md`](../CONTRIBUTING.md). The `map` CLI lives in -[missing-ai-patterns/cli](https://github.com/rajanbor/map/tree/main/tooling). +[`../CONTRIBUTING.md`](../CONTRIBUTING.md). The `map` CLI lives in this monorepo under +[`../../tooling`](../../tooling/). diff --git a/library/docs/specs/website.md b/library/docs/specs/website.md index 5176111..1cb6b9a 100644 --- a/library/docs/specs/website.md +++ b/library/docs/specs/website.md @@ -19,8 +19,8 @@ projection of `registry.json`, the same artifact every other tool consumes. MAP currently onboards through a GitHub README — fine for contributors, weak for the "what is this, how do I try it in 30 seconds" visitor. The old in-repo `website/` placeholder promised an interactive knowledge site someday; that ambition blocked -shipping anything. A one-page site that states the pitch, shows `npm install -g -@missing-ai-patterns/cli`, and lists the catalog is achievable now and improves every +shipping anything. A one-page site that states the pitch, shows the GitHub installer, +and lists the catalog is achievable now and improves every link we share. ## Design @@ -35,14 +35,14 @@ works with JavaScript disabled. **Page structure** (single page, in order): -1. **Hero** — one-line pitch, `npm install -g @missing-ai-patterns/cli` in a copyable +1. **Hero** — one-line pitch, `git clone` plus `./scripts/install.sh` in a copyable block, links to GitHub + docs. 2. **What is MAP** — 3 short paragraphs (from the README's "What is MAP?" — the site never forks the message, it condenses it). 3. **The catalog** — categories with their published patterns (name, one-line summary, MAP Score as compact stars), linking to the pattern on GitHub; a counter ("N published / ~75 planned") from registry statuses. -4. **How you use it** — one worked example: `map analyze` → `map recommend` → +4. **How you use it** — one worked example: `map scan` → `map suggest` → `map add security/prompt-injection-defense`, as annotated terminal output. 5. **Docs & community** — links: philosophy, pattern anatomy, contributing, the RFC, discussions. diff --git a/library/examples/claude-code/README.md b/library/examples/claude-code/README.md index 1434591..a7eb3f3 100644 --- a/library/examples/claude-code/README.md +++ b/library/examples/claude-code/README.md @@ -61,9 +61,9 @@ flowchart TD As the [MAP CLI](https://github.com/rajanbor/map/tree/main/tooling) grows, an agent could pull structured pattern context directly: ```bash -map explain retrieval.chunking # what the pattern is and when to use it -map prompt retrieval.chunking # an implementation prompt for a coding agent -map recommend # patterns missing from the detected architecture +map show retrieval/chunking # what the pattern is and when to use it +map add retrieval/chunking # prompt + acceptance criteria for the project +map suggest # patterns worth reviewing for the detected architecture ``` This turns MAP from documentation an agent *reads* into an architecture layer an agent diff --git a/library/examples/poc-pattern-catalog/README.md b/library/examples/poc-pattern-catalog/README.md index e423491..4426628 100644 --- a/library/examples/poc-pattern-catalog/README.md +++ b/library/examples/poc-pattern-catalog/README.md @@ -4,24 +4,25 @@ Unlike the other examples (which are ADR-style documents), this one is runnable: it shows the two ways to consume MAP's pattern catalog, via the CLI and programmatically through the **registry** artifact. -## 1. The CLI: `map patterns` +## 1. The CLI: `map list` and `map search` ```bash -npm install -g @missing-ai-patterns/cli # or: npx @missing-ai-patterns/cli - -map patterns # full catalog (roadmap + written) -map patterns chunk # search by text -map patterns --category=retrieval # filter by category -map patterns --status=published # only written patterns -map patterns --json # machine-readable output +git clone https://github.com/rajanbor/map.git +cd map && ./scripts/install.sh + +map list # full catalog (roadmap + written) +map search chunk # search by text +map list --category=retrieval # filter by category +map list --status=published # only written patterns +map list --json # machine-readable output ``` Published patterns show their [MAP Score](../../docs/specs/map-score.md) star line, so you can compare candidates at a glance. `--json` is meant for scripts -and AI agents. `map explain ` gives the decision view of one pattern, and +and AI agents. `map show ` gives the decision view of one pattern, and `map add ` copies its prompt/acceptance files into your project. -The CLI lives in [missing-ai-patterns/cli](https://github.com/rajanbor/map/tree/main/tooling). +The CLI lives under [`tooling/`](../../../tooling/) in this repository. ## 2. Programmatic: the registry diff --git a/tooling/README.md b/tooling/README.md index aa1a7c1..b47996f 100644 --- a/tooling/README.md +++ b/tooling/README.md @@ -4,18 +4,19 @@ # missing-ai-patterns/cli -The `map` command and its shared libraries. The pattern catalog itself — the -patterns, docs, and specifications — lives in the canonical -[**map** repository](https://github.com/rajanbor/map); this repository -consumes its published **registry** artifact. +The `map` command and its shared libraries inside the consolidated MAP monorepo. +The pattern catalog under [`../library`](../library/) compiles into the registry this +workspace consumes. ```bash -npm install -g @missing-ai-patterns/cli +git clone https://github.com/rajanbor/map.git +cd map +./scripts/install.sh map init # create the .map/ workspace in your project -map analyze # detect your AI architecture -map recommend # find the patterns you're missing -map explain retrieval/chunking +map scan # detect evidence-backed architecture signals +map suggest # find patterns worth reviewing +map show retrieval/chunking map add retrieval/chunking ``` @@ -29,9 +30,9 @@ map add retrieval/chunking ## How data flows ``` -map repo (patterns, ROADMAP) - └── scripts/build-registry.ts → registry.json (published on each map release) - └── consumed here: bundled snapshot + `map update` cache +library/ (patterns, ROADMAP) + └── scripts/build-registry.ts → registry.json + └── tooling: bundled snapshot + `map update` cache ``` The CLI never parses the map repository's Markdown — it reads `registry.json` @@ -55,21 +56,23 @@ pnpm map -- --help # run the CLI from source Developing against a local map checkout: ```bash -MAP_REGISTRY=path/to/map/dist/registry.json pnpm map -- patterns +MAP_REGISTRY=path/to/map/library/dist/registry.json pnpm map -- list MAP_REPO=path/to/map pnpm --filter @missing-ai-patterns/cli sync-snapshot ``` ## Releasing 1. Bump versions in `packages/*/package.json`. -2. Refresh the bundled registry: `pnpm --filter @missing-ai-patterns/cli sync-snapshot`. -3. Tag `v` — the release workflow builds and publishes both packages to npm. +2. Refresh the bundled registry with `MAP_REPO=.. pnpm --filter @missing-ai-patterns/cli sync-snapshot`. +3. Tag `sdk/v` only when the npm publication workflow and credentials are ready. + +The public npm package is not currently published; the supported user installation is +the repository-level GitHub installer. ## Contributing -Issues and PRs about the **CLI, score library, or tooling** belong here; new -patterns and documentation belong in -[missing-ai-patterns/map](https://github.com/rajanbor/map). The +Issues and PRs for tooling, patterns, and documentation all belong in +[rajanbor/map](https://github.com/rajanbor/map). The [vision document](docs/vision.md) describes where the CLI is heading. ## License diff --git a/tooling/packages/cli/registry-snapshot/registry.json b/tooling/packages/cli/registry-snapshot/registry.json index 1c9d379..452f6e9 100644 --- a/tooling/packages/cli/registry-snapshot/registry.json +++ b/tooling/packages/cli/registry-snapshot/registry.json @@ -1,6 +1,6 @@ { "schemaVersion": 1, - "generatedAt": "2026-07-11T23:05:31.275Z", + "generatedAt": "2026-09-13T13:11:13.562Z", "source": { "repository": "https://github.com/rajanbor/map", "version": "0.5.0" diff --git a/tooling/packages/cli/scripts/sync-snapshot.ts b/tooling/packages/cli/scripts/sync-snapshot.ts index b3f1d5d..dd5693d 100644 --- a/tooling/packages/cli/scripts/sync-snapshot.ts +++ b/tooling/packages/cli/scripts/sync-snapshot.ts @@ -11,8 +11,10 @@ */ import { execFileSync } from "node:child_process"; -import { writeFile, readFile } from "node:fs/promises"; +import { writeFile, readFile, mkdtemp, rm } from "node:fs/promises"; +import { existsSync } from "node:fs"; import { join, dirname } from "node:path"; +import { tmpdir } from "node:os"; import { fileURLToPath } from "node:url"; const packageDir = join(dirname(fileURLToPath(import.meta.url)), ".."); @@ -21,11 +23,21 @@ const DEFAULT_REGISTRY_URL = "https://github.com/rajanbor/map/releases/latest/download/registry.json"; const mapRepo = process.env["MAP_REPO"]; +const check = process.argv.includes("--check"); +let generatedPath = snapshotPath; +let temporaryDirectory: string | undefined; if (mapRepo !== undefined && mapRepo !== "") { + const libraryRoot = existsSync(join(mapRepo, "library", "scripts", "build-registry.ts")) + ? join(mapRepo, "library") + : mapRepo; + if (check) { + temporaryDirectory = await mkdtemp(join(tmpdir(), "map-registry-check-")); + generatedPath = join(temporaryDirectory, "registry.json"); + } execFileSync( "node", - [join(mapRepo, "scripts", "build-registry.ts"), "--out", snapshotPath], + [join(libraryRoot, "scripts", "build-registry.ts"), "--out", generatedPath], { stdio: "inherit" }, ); } else { @@ -40,10 +52,30 @@ if (mapRepo !== undefined && mapRepo !== "") { } const body = await response.text(); JSON.parse(body); // fail fast on a corrupt download - await writeFile(snapshotPath, body); + if (check) { + generatedPath = snapshotPath; + } else { + await writeFile(snapshotPath, body); + } +} + +if (check) { + const expected = normalized(JSON.parse(await readFile(generatedPath, "utf8"))); + const actual = normalized(JSON.parse(await readFile(snapshotPath, "utf8"))); + if (JSON.stringify(actual) !== JSON.stringify(expected)) { + process.stderr.write("snapshot is stale; run with MAP_REPO= without --check\n"); + if (temporaryDirectory !== undefined) await rm(temporaryDirectory, { recursive: true, force: true }); + process.exit(1); + } } const { patterns } = JSON.parse(await readFile(snapshotPath, "utf8")) as { patterns: unknown[]; }; -process.stdout.write(`snapshot updated: ${patterns.length} patterns.\n`); +process.stdout.write(`snapshot ${check ? "current" : "updated"}: ${patterns.length} patterns.\n`); +if (temporaryDirectory !== undefined) await rm(temporaryDirectory, { recursive: true, force: true }); + +function normalized(value: Record): Record { + const { generatedAt: _generatedAt, ...rest } = value; + return rest; +}