diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c45fd01..621572d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -39,6 +39,11 @@ jobs: - run: pnpm lint - run: pnpm typecheck - run: pnpm test + - name: Test the GitHub installer + working-directory: . + run: | + MAP_INSTALL_DIR="$RUNNER_TEMP/map-bin" ./scripts/install.sh + "$RUNNER_TEMP/map-bin/map" --version - name: Smoke-test the built CLI run: | node packages/cli/dist/map.js --help diff --git a/README.md b/README.md index afb2873..3b89ed4 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,76 @@ -# MAP — your AI engineering library +

+ MAP logo +

-MAP is a project toolkit for building AI systems with a repeatable structure. -Initialize it inside an application, keep architecture knowledge in `.map/`, and -use the CLI to analyze the codebase, adopt proven patterns, compile instructions -for AI coding assistants, and keep context within a token budget. +

MAP — your AI engineering library

+ +

+ One project structure for architecture decisions, prompts, agents, evaluations,
+ reusable AI patterns, and context optimization. +

+ +

+ CI + Code license: MIT + Content license: CC BY 4.0 + Node.js 20 or newer +

+ +MAP helps a software project explain itself to people and AI coding agents. You keep +the durable knowledge in one `.map/` directory. The CLI can analyze the project, +recommend missing production patterns, control the context budget, and generate the +native instruction files used by different assistants. + +> **Current distribution:** MAP is installed directly from this GitHub repository. +> The npm package is not published yet, so do not use `npm install +> @missing-ai-patterns/cli`. + +## Why MAP? + +AI projects quickly scatter important knowledge across prompts, chat histories, +vendor configuration, diagrams, and developer notes. That makes agents repeat old +mistakes and makes architectural decisions difficult to review. + +MAP gives that knowledge a stable home: + +- **one source of truth** for every supported coding assistant; +- **reusable patterns** with trade-offs, implementation prompts, and acceptance tests; +- **AI-aware ADRs and schemas** readable by people and machines; +- **token-budget control** that exposes oversized and duplicated context; +- **Git-native collaboration** with deterministic, reviewable changes and offline operation. + +## Install from GitHub + +Requirements: Git, Node.js 20 or newer, and either `pnpm` or `corepack`. + +```bash +git clone https://github.com/rajanbor/map.git +cd map +./scripts/install.sh +map --version +``` + +The installer builds the CLI from this checkout and creates a `map` symlink in +`~/.local/bin`. It never overwrites an unrelated executable. To choose another +location: + +```bash +MAP_INSTALL_DIR="$HOME/bin" ./scripts/install.sh +``` + +If that directory is not in `PATH`, the installer prints the exact line to add to +your shell configuration. To update MAP later: ```bash -npm install -g @missing-ai-patterns/cli -cd my-ai-project +cd map +git pull --ff-only +./scripts/install.sh +``` + +## Start an AI project + +```bash +cd your-project map init map analyze map recommend @@ -15,46 +78,89 @@ map optimize --save map sync ``` -`map init` creates a concrete, versioned workspace: +`map init` detects the project and creates a versioned workspace without overwriting +existing files: ```text .map/ -├── map.config.json project, analyzers, context targets, and tool settings -├── architecture/ system boundaries, data flow, and diagrams +├── map.config.json project, analyzers, targets, and tool settings +├── architecture/ system boundaries, data flows, and diagrams ├── decisions/ AI architecture decision records ├── patterns/ patterns adopted with `map add` -├── prompts/ reusable project prompts -├── agents/ agent roles and guardrails -├── evals/ datasets, rubrics, and evaluation configuration -├── tools/ project-level tool guidance and budgets -├── reports/ generated analysis and token reports (gitignored) -└── cache/ local registry/tool caches (gitignored) +├── prompts/ reusable product and engineering prompts +├── agents/ agent roles, permissions, and guardrails +├── evals/ datasets, rubrics, metrics, and quality gates +├── tools/ tool contracts and context budgets +├── reports/ generated analysis reports; ignored by Git +└── cache/ local registry cache; ignored by Git ``` -## Repository map +## One workflow, every agent + +```text +project code ──▶ map analyze ──▶ detected AI architecture + │ +MAP library ──▶ map recommend ──▶ missing patterns + │ + map add / edit .map/ + │ + map sync + │ + ┌────────────────────┼────────────────────┐ + ▼ ▼ ▼ + AGENTS.md CLAUDE.md Cursor / Copilot / Gemini +``` + +| 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 add ` | Adds a pattern prompt, metadata, and acceptance criteria. | +| `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. | + +## What is inside this repository? | Area | Purpose | -| --- | --- | -| [`library/`](library/) | The pattern library, specifications, examples, and reference implementations | -| [`tooling/`](tooling/) | The MAP CLI and reusable TypeScript packages | -| [`apps/website/`](apps/website/) | The public registry-driven website | -| [`docs/`](docs/) | Product model, project structure, and getting-started guides | -| [`.map/`](.map/) | MAP's own project workspace — MAP uses the structure it generates | - -## Core workflow - -1. `map init` detects the project and creates `.map/` without overwriting user files. -2. `map analyze` identifies AI-related technologies and architecture signals. -3. `map recommend` suggests missing production patterns. -4. `map add ` adopts a pattern into the project workspace. -5. `map optimize` estimates context usage, flags repeated content, and enforces a token budget. -6. `map sync` compiles the same source of truth into `CLAUDE.md`, `AGENTS.md`, - `GEMINI.md`, Cursor rules, and Copilot instructions. - -Start with [Getting started](docs/getting-started.md), review the -[project structure](docs/project-structure.md), or browse the -[pattern catalog](library/README.md). - -The original MAP repositories were consolidated here with their Git histories, -branches, tags, and releases preserved. +|---|---| +| [`library/`](library/) | AI engineering patterns, schemas, specifications, examples, and small reference implementations. | +| [`tooling/`](tooling/) | The TypeScript CLI, context compiler, analyzers, recommender, and shared packages. | +| [`apps/website/`](apps/website/) | The public, registry-driven pattern browser. | +| [`docs/`](docs/) | Getting started, project structure, and product documentation. | +| [`.map/`](.map/) | MAP's own workspace. The project uses the same structure it generates. | + +The pattern library is framework-agnostic. Each published pattern explains when to +use it, when not to use it, its failure modes, trade-offs, an implementation prompt, +and verifiable acceptance criteria. + +## Explore + +- [Getting started](docs/getting-started.md) +- [Project structure](docs/project-structure.md) +- [Pattern library](library/README.md) +- [Human- and AI-readable schemas](library/docs/schemas/README.md) +- [MAP Standard RFC](library/rfcs/0001-map-standard.md) +- [Schema roadmap](https://github.com/rajanbor/map/issues/98) + +## Develop MAP + +```bash +git clone https://github.com/rajanbor/map.git +cd map/tooling +corepack pnpm install --frozen-lockfile +corepack pnpm test +corepack pnpm build +``` + +Contributions should be small, testable, and readable by both people and agents. See +the [contribution guide](library/CONTRIBUTING.md) and open roadmap issues before +starting a larger contract change. + +## License +Code is available under the [MIT License](library/LICENSE). Documentation, patterns, +and other written content use [CC BY 4.0](library/LICENSE-CONTENT). The MAP name and +logo remain reserved as described in [LICENSING.md](library/LICENSING.md). diff --git a/docs/getting-started.md b/docs/getting-started.md index e16cbb8..df48d96 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -3,10 +3,23 @@ MAP turns project-specific AI knowledge into a small, versioned workspace that both people and coding agents can use. -## 1. Initialize a project +## 1. Install MAP from GitHub + +```bash +git clone https://github.com/rajanbor/map.git +cd map +./scripts/install.sh +map --version +``` + +MAP is currently distributed from its GitHub repository; the npm package is not +published yet. The installer builds the CLI and links it into `~/.local/bin` without +overwriting an unrelated executable. It requires Git, Node.js 20+, and `pnpm` or +`corepack`. + +## 2. Initialize a project ```bash -npm install -g @missing-ai-patterns/cli cd your-project map init ``` @@ -14,7 +27,7 @@ map init The initializer detects known language markers and creates `.map/`. It keeps existing files unless `--force` is explicitly supplied. -## 2. Understand the architecture +## 3. Understand the architecture ```bash map analyze @@ -26,7 +39,7 @@ map patterns retrieval maps those signals to production patterns, and `patterns` lets you browse the full library. -## 3. Adopt knowledge into the project +## 4. Adopt knowledge into the project ```bash map add retrieval/chunking @@ -36,7 +49,7 @@ The pattern's prompt, acceptance criteria, and metadata are copied into `.map/patterns/`, where they can be adapted to the application and reviewed with the rest of the code. -## 4. Keep context efficient +## 5. Keep context efficient ```bash map optimize @@ -49,7 +62,7 @@ shows the largest files, identifies substantial repeated blocks, and optionally enforces the budget in CI. The default budget and globs live under `tools.tokenOptimizer` in `.map/map.config.json`. -## 5. Compile assistant instructions +## 6. Compile assistant instructions ```bash map sync diff --git a/scripts/install.sh b/scripts/install.sh new file mode 100755 index 0000000..310e7f9 --- /dev/null +++ b/scripts/install.sh @@ -0,0 +1,58 @@ +#!/usr/bin/env bash +set -euo pipefail + +map_repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +map_install_dir="${MAP_INSTALL_DIR:-${HOME}/.local/bin}" +map_executable="${map_repo_root}/tooling/packages/cli/dist/map.js" +map_link="${map_install_dir}/map" + +if ! command -v node >/dev/null 2>&1; then + echo "error: Node.js 20 or newer is required" >&2 + exit 1 +fi + +map_node_major="$(node -p 'Number(process.versions.node.split(".")[0])')" +if (( map_node_major < 20 )); then + echo "error: Node.js 20 or newer is required; found $(node --version)" >&2 + exit 1 +fi + +if command -v pnpm >/dev/null 2>&1; then + map_package_manager=(pnpm) +elif command -v corepack >/dev/null 2>&1; then + map_package_manager=(corepack pnpm) +else + echo "error: pnpm or corepack is required to build MAP" >&2 + exit 1 +fi + +mkdir -p "${map_install_dir}" +if [[ -e "${map_link}" || -L "${map_link}" ]]; then + map_existing_target="$(readlink "${map_link}" 2>/dev/null || true)" + if [[ "${map_existing_target}" != "${map_executable}" ]]; then + echo "error: ${map_link} already exists and was not created by this checkout" >&2 + echo "Choose another location with MAP_INSTALL_DIR=/path/to/bin." >&2 + exit 1 + fi +fi + +echo "Building MAP from ${map_repo_root}" +( + cd "${map_repo_root}/tooling" + "${map_package_manager[@]}" install --frozen-lockfile + "${map_package_manager[@]}" build +) + +if [[ ! -L "${map_link}" ]]; then + ln -s "${map_executable}" "${map_link}" +fi + +map_version="$("${map_link}" --version | tr -d '[:space:]')" +echo "Installed MAP ${map_version} as ${map_link}" +case ":${PATH}:" in + *":${map_install_dir}:"*) ;; + *) + echo "Add this directory to PATH:" + echo " export PATH=\"${map_install_dir}:\$PATH\"" + ;; +esac diff --git a/tooling/package.json b/tooling/package.json index fb649a0..b581754 100644 --- a/tooling/package.json +++ b/tooling/package.json @@ -1,6 +1,7 @@ { "name": "@missing-ai-patterns/cli-workspace", "private": true, + "packageManager": "pnpm@10.11.0", "description": "Workspace for the MAP CLI and shared libraries.", "type": "module", "license": "MIT", diff --git a/tooling/packages/cli/README.md b/tooling/packages/cli/README.md index ddcf2fc..6a0ba8d 100644 --- a/tooling/packages/cli/README.md +++ b/tooling/packages/cli/README.md @@ -9,12 +9,18 @@ bundled with the package, so everything except `map update` works offline. ## Install +The CLI is currently installed from the MAP GitHub repository. The npm package is +not published yet. + ```bash -npm install -g @missing-ai-patterns/cli # or pnpm add -g / npx +git clone https://github.com/rajanbor/map.git +cd map +./scripts/install.sh map --help ``` -Requires Node >= 20. +Requires Git, Node >= 20, and `pnpm` or `corepack`. The installer builds this checkout +and links `map` into `~/.local/bin`; set `MAP_INSTALL_DIR` to choose another location. ## Commands