rapidkit 0.37.0 → 0.38.0

package/docs/contracts/README.md

@@ -0,0 +1,71 @@
+# RapidKit CLI Contracts
+
+Contract documentation for JSON payloads, support matrices, and cross-repo parity.
+
+## Monorepo workflow
+
+Canonical JSON lives in **`../contracts/`** (npm package root, published in the tarball).
+
+| Script                              | Purpose                                                                                     |
+| ----------------------------------- | ------------------------------------------------------------------------------------------- |
+| `npm run generate:contracts`        | Regenerate runtime surface, create planner, import-stack parity, module-layout, infra-stack |
+| `npm run check:generated-contracts` | Verify committed JSON matches generators                                                    |
+| `npm run sync:parity-snapshot`      | Copy canonical → vscode `contracts/` mirror                                                 |
+| `npm run check:parity-snapshot`     | Verify mirrors match canonical                                                              |
+| `npm run validate:contracts`        | Generate check + mirror check + contract tests                                              |
+
+Workflow: change code → `npm run generate:contracts` → `npm run sync:parity-snapshot` → commit npm + vscode `contracts/`.
+
+## Documents in this folder
+
+| File                                                           | Purpose                                                     |
+| -------------------------------------------------------------- | ----------------------------------------------------------- |
+| [ARTIFACT_CATALOG.md](./ARTIFACT_CATALOG.md)                   | On-disk artifact paths, schema versions, and consumer rules |
+| [COMMAND_OWNERSHIP_MATRIX.md](./COMMAND_OWNERSHIP_MATRIX.md)   | Which commands the npm wrapper owns vs Python Core          |
+| [RUNTIME_SUPPORT_MATRIX.md](./RUNTIME_SUPPORT_MATRIX.md)       | Scaffold, import, lifecycle, and module support tiers       |
+| [RUNTIME_ACCEPTANCE_MATRIX.md](./RUNTIME_ACCEPTANCE_MATRIX.md) | Runtime acceptance matrix expectations                      |
+| [rapidkit-cli-contracts.json](./rapidkit-cli-contracts.json)   | Core CLI JSON schema fragments                              |
+
+## Workspace intelligence schemas
+
+Published under `../contracts/` (not duplicated in this folder):
+
+- `workspace-registry.v1.json` — canonical project registry summary (see [ARTIFACT_CATALOG.md](./ARTIFACT_CATALOG.md))
+- `release-readiness.v1.json` — release readiness gate evidence
+- `workspace-run-last.v1.json` — multi-stage workspace run evidence
+- `doctor-workspace-evidence.v1.json` / `doctor-project-evidence.v1.json` — doctor evidence
+- `analyze-last-run.v1.json` — analyze evidence
+- `pipeline-last-run.v1.json` — governance pipeline orchestration
+- `create-planner-capabilities.v1.json` — native-create, external-create-adopt, and adopt-only capability lanes
+
+Workspace intelligence (`../contracts/workspace-intelligence/`):
+
+- `workspace-model.v1.json`
+- `workspace-context.v1.json`
+- `workspace-model-snapshot.v1.json`
+- `workspace-model-diff.v1.json`
+- `workspace-impact.v1.json`
+- `workspace-verify.v1.json`
+
+CLI commands: see [commands-reference.md](../commands-reference.md) and [../README.md](../README.md#workspace-intelligence).
+
+## Core CLI JSON payloads
+
+`rapidkit-cli-contracts.json` describes:
+
+- `VersionResponse` — `rapidkit version --json`
+- `CommandsResponse` — `rapidkit commands --json`
+- `ProjectDetectResponse` — `rapidkit project detect --json`
+- `ModulesListResponseV1` — `rapidkit modules list --json-schema 1`
+
+## Versioning
+
+- Payloads include `schema_version` where applicable.
+- Backward-compatible changes keep the same schema version.
+- Breaking changes require a schema bump and updated tests in `src/__tests__/contracts/`.
+
+## See also
+
+- [Documentation index](../README.md)
+- [commands-reference.md](../commands-reference.md)
+- [workspace-operations.md](../workspace-operations.md)

package/docs/contracts/RUNTIME_ACCEPTANCE_MATRIX.md

@@ -0,0 +1,98 @@
+# RapidKit Runtime Acceptance Matrix
+
+Last updated: 2026-06-05
+
+This document defines the executable acceptance gate for RapidKit npm workspace
+and project orchestration. It complements
+[RUNTIME_SUPPORT_MATRIX.md](RUNTIME_SUPPORT_MATRIX.md): the support matrix says
+what RapidKit promises; this acceptance matrix verifies the promise with a real
+workspace.
+
+## Command
+
+```bash
+npm run test:runtime-matrix
+```
+
+For a stricter prepared-machine run where Go, Java, .NET, Python, and Node
+toolchains are expected to be installed:
+
+```bash
+npm run test:runtime-matrix:full
+```
+
+The script can also be invoked directly:
+
+```bash
+node scripts/runtime-acceptance-matrix.mjs --report ./runtime-acceptance-report.json
+```
+
+## Modes
+
+| Mode     | Purpose                                                                 | External runtime requirement |
+| -------- | ----------------------------------------------------------------------- | ---------------------------- |
+| default  | Scaffold, import, contract, doctor, archive, and actionable diagnostics | no                           |
+| `--full` | Everything in default plus lifecycle commands must pass                 | yes                          |
+
+Default mode is intentionally network-safe. It creates a minimal workspace,
+uses `--skip-install` for scaffolded projects, and accepts missing-runtime
+lifecycle failures only when the CLI prints actionable diagnostics such as
+`Reason`, `Command`, and `Hint`.
+
+## Coverage
+
+The matrix verifies:
+
+- npm-owned global entrypoints: `--version` and `-v`.
+- global command ownership contract via `commands --json`, plus core-owned
+  catalog commands in default/full modes: `version`, `commands`, `list`,
+  `info`, `frameworks`, `modules`, and `license`.
+- `create workspace` with a Python-free minimal profile.
+- `create project` for npm-backed Go Fiber, Go Gin, Spring Boot, and ASP.NET
+  Core Clean Web API kits.
+- `create project` for core-backed FastAPI and NestJS kits through the current
+  bridge/fallback path.
+- `import` for observed runtime projects without first-class kits, including
+  Laravel/PHP, Rails/Ruby, Axum/Rust, and generic unknown backends.
+- `workspace sync`, `workspace policy show/set`.
+- Snapshot safety flows: create/list/inspect/restore dry-run.
+- Project safety flows: archive list, archive dry-run, and delete dry-run.
+- `workspace contract init/inspect/verify/graph`.
+- `doctor workspace` and `doctor project`.
+- `project commands --json` capability reporting for every generated/imported
+  project.
+- Project lifecycle `init`, `help`, `test`, `build`, `lint`, and `format` in
+  default and full modes, with missing runtime/tooling reported as actionable
+  setup diagnostics in default mode.
+- `workspace run init/test/build`, including default-mode actionable setup
+  failures and full-mode hard pass requirements.
+- Rejection of unsupported fleet stages such as `workspace run dev`.
+- Portable archive export, inspect, strict verify, doctor, and hydrate preview.
+
+## Report Contract
+
+Each run writes a JSON report with:
+
+- `kind: rapidkit.runtime.acceptance.matrix`
+- runtime preflight availability
+- per-scenario command, cwd, exit code, duration, status, and output tails
+- final summary and exit code
+
+By default, reports are written under the system temp report directory and are
+not deleted with the temporary workspace. Use `--report <file>` when you need a
+stable release-evidence path inside the repository or an artifact directory.
+
+## Release Rule
+
+This gate is intentionally **manual/local-only for now**. Do not add it to
+regular GitHub Actions until it has a dedicated scheduled/manual workflow with
+runtime caches and explicit cost controls.
+
+For npm releases:
+
+1. Run `npm run test:runtime-matrix` locally before publishing a release
+   candidate.
+2. Run `npm run test:runtime-matrix:full` on at least one prepared release
+   machine with Go, Java, .NET, Python, and Node installed.
+3. Any newly added first-class or extended runtime must add at least one matrix
+   scenario before release.

package/docs/contracts/RUNTIME_SUPPORT_MATRIX.md

@@ -0,0 +1,74 @@
+# RapidKit Runtime Support Matrix
+
+Last updated: 2026-06-15
+
+This document defines the public support contract for RapidKit npm workspace projects.
+It separates three concerns:
+
+- **First-class**: curated RapidKit kit/framework with scaffold/import/govern/lifecycle support. Module mutation still follows the runtime row below.
+- **Extended**: scaffold/import/govern/lifecycle or import/govern workflows are supported, but Core module mutation is disabled unless explicitly added later.
+- **Observed**: import/govern/contract visibility is supported; lifecycle commands may require manual project scripts or future adapters.
+
+## Runtime Tiers
+
+| Runtime             | Tier        | Scaffold | Import | Lifecycle Commands                                | Module Commands | Doctor    |
+| ------------------- | ----------- | -------: | -----: | ------------------------------------------------- | --------------: | --------- |
+| Python              | first-class |      yes |    yes | init, dev, start, build, test, lint, format, help |             yes | full      |
+| Node.js             | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |             yes | full      |
+| Go                  | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
+| Java / Spring Boot  | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
+| .NET / ASP.NET Core | extended    |      yes |    yes | init, dev, start, build, test, lint, format, help |              no | readiness |
+| PHP                 | observed    |       no |    yes | help                                              |              no | observed  |
+| Ruby                | observed    |       no |    yes | help                                              |              no | observed  |
+| Rust                | observed    |       no |    yes | help                                              |              no | observed  |
+| Elixir              | observed    |       no |    yes | help                                              |              no | observed  |
+| Clojure             | observed    |       no |    yes | help                                              |              no | observed  |
+| Scala               | observed    |       no |    yes | help                                              |              no | observed  |
+| Kotlin              | observed    |       no |    yes | help                                              |              no | observed  |
+| Deno                | observed    |       no |    yes | help                                              |              no | observed  |
+| Bun                 | observed    |       no |    yes | help                                              |              no | observed  |
+| Unknown             | observed    |       no |    yes | help                                              |              no | observed  |
+
+## Framework Tiers
+
+> **Runtime vs framework:** Python **runtime** stays first-class (Core-backed modules). Node.js **runtime** is extended; **NestJS** is the first-class Node framework. Frontend stacks (Next.js, Remix, Vite variants, Nuxt, Angular, Astro, SvelteKit) are extended frameworks on the Node runtime.
+
+| Tier        | Frameworks                                                                                                                                                  |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| first-class | FastAPI, NestJS                                                                                                                                              |
+| extended    | Go/Fiber, Go/Gin, Spring Boot, ASP.NET Core, Django, Flask, Express, Fastify, Koa, Echo, Laravel, Symfony, Rails, Sinatra, Actix, Axum, Rocket, Phoenix, Next.js, Remix, React, Vue, Svelte, Solid, Nuxt, Angular, Astro, SvelteKit |
+| observed    | Python, Node.js, Go, Java, PHP, Ruby, Rust, Elixir, Unknown/generic projects                                                                                |
+
+## Import Policy
+
+Imported projects are **observed and governed by default**:
+
+- RapidKit writes `.rapidkit/project.json` so workspace contract, graph, doctor, and sharing flows can discover the project.
+- RapidKit writes `.rapidkit/import.json` and `.rapidkit/import-readiness.json` for auditability.
+- Secrets and dependency/build caches are not copied during local-folder import.
+- `module_support` defaults to `false` for imported projects unless existing RapidKit metadata explicitly opts in.
+
+This keeps imports safe for arbitrary repositories while still enabling workspace-level visibility and lifecycle support where adapters exist.
+
+## Executable Acceptance Gate
+
+The runtime support contract is validated by
+[RUNTIME_ACCEPTANCE_MATRIX.md](RUNTIME_ACCEPTANCE_MATRIX.md).
+
+Run the default, network-safe gate locally before release:
+
+```bash
+npm run test:runtime-matrix
+```
+
+Run the full lifecycle gate on a prepared machine with Go, Java, .NET, Python,
+and Node installed:
+
+```bash
+npm run test:runtime-matrix:full
+```
+
+This gate is not wired into regular GitHub Actions yet because it creates real
+workspaces and projects across multiple runtimes. Keep it manual/local until a
+dedicated scheduled or manually dispatched workflow has runtime caches and cost
+controls.

package/docs/contracts/rapidkit-cli-contracts.json

@@ -0,0 +1,239 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://getrapidkit.com/schemas/rapidkit-cli-contracts.json",
+    "title": "RapidKit Core CLI Contracts",
+    "type": "object",
+    "definitions": {
+        "VersionResponse": {
+            "type": "object",
+            "required": [
+                "schema_version",
+                "version"
+            ],
+            "properties": {
+                "schema_version": {
+                    "const": 1
+                },
+                "version": {
+                    "type": "string",
+                    "minLength": 1
+                }
+            },
+            "additionalProperties": true
+        },
+        "CommandsResponse": {
+            "type": "object",
+            "required": [
+                "schema_version",
+                "commands"
+            ],
+            "properties": {
+                "schema_version": {
+                    "const": 1
+                },
+                "commands": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "minLength": 1
+                    },
+                    "minItems": 1
+                },
+                "descriptions": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                }
+            },
+            "additionalProperties": true
+        },
+        "ProjectDetectResponse": {
+            "type": "object",
+            "required": [
+                "schema_version",
+                "input",
+                "confidence",
+                "isRapidkitProject",
+                "projectRoot",
+                "engine",
+                "markers"
+            ],
+            "properties": {
+                "schema_version": {
+                    "const": 1
+                },
+                "input": {
+                    "type": "string"
+                },
+                "confidence": {
+                    "enum": [
+                        "strong",
+                        "weak",
+                        "none"
+                    ]
+                },
+                "isRapidkitProject": {
+                    "type": "boolean"
+                },
+                "projectRoot": {
+                    "type": [
+                        "string",
+                        "null"
+                    ]
+                },
+                "engine": {
+                    "type": "string"
+                },
+                "markers": {
+                    "type": "object"
+                }
+            },
+            "additionalProperties": true
+        },
+        "ModulesListResponseV1": {
+            "type": "object",
+            "required": [
+                "schema_version",
+                "generated_at",
+                "filters",
+                "stats",
+                "modules"
+            ],
+            "properties": {
+                "schema_version": {
+                    "const": 1
+                },
+                "generated_at": {
+                    "type": "string",
+                    "format": "date-time"
+                },
+                "etag": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "filters": {
+                    "type": "object",
+                    "properties": {
+                        "category": {
+                            "type": [
+                                "string",
+                                "null"
+                            ]
+                        },
+                        "tag": {
+                            "type": [
+                                "string",
+                                "null"
+                            ]
+                        },
+                        "detailed": {
+                            "type": "boolean"
+                        }
+                    },
+                    "additionalProperties": true
+                },
+                "stats": {
+                    "type": "object",
+                    "required": [
+                        "total",
+                        "returned",
+                        "invalid"
+                    ],
+                    "properties": {
+                        "total": {
+                            "type": "integer",
+                            "minimum": 0
+                        },
+                        "returned": {
+                            "type": "integer",
+                            "minimum": 0
+                        },
+                        "invalid": {
+                            "type": "integer",
+                            "minimum": 0
+                        }
+                    },
+                    "additionalProperties": true
+                },
+                "modules": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "required": [
+                            "name",
+                            "version",
+                            "category",
+                            "status",
+                            "slug"
+                        ],
+                        "properties": {
+                            "name": {
+                                "type": "string"
+                            },
+                            "display_name": {
+                                "type": "string"
+                            },
+                            "version": {
+                                "type": "string"
+                            },
+                            "category": {
+                                "type": "string"
+                            },
+                            "status": {
+                                "type": "string"
+                            },
+                            "description": {
+                                "type": "string"
+                            },
+                            "tags": {
+                                "type": "array",
+                                "items": {
+                                    "type": "string"
+                                }
+                            },
+                            "slug": {
+                                "type": "string"
+                            }
+                        },
+                        "additionalProperties": true
+                    }
+                },
+                "invalid_modules": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "required": [
+                            "slug"
+                        ],
+                        "properties": {
+                            "slug": {
+                                "type": "string"
+                            },
+                            "messages": {
+                                "type": "array",
+                                "items": {
+                                    "type": "string"
+                                }
+                            }
+                        },
+                        "additionalProperties": true
+                    }
+                },
+                "warnings": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "errors": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            },
+            "additionalProperties": true
+        }
+    }
+}

package/docs/create-planner-capabilities.md

@@ -0,0 +1,81 @@
+# Create Planner Capabilities
+
+RapidKit is a Workspace Intelligence platform, not a blind scaffold wrapper.
+The create planner separates project creation into three lanes so developers,
+CI, and AI agents share the same expectations.
+
+## Lanes
+
+| Lane                    | Status    | Meaning                                                                                             |
+| ----------------------- | --------- | --------------------------------------------------------------------------------------------------- |
+| `native-create`         | Available | RapidKit owns the scaffold contract, marker, registry, doctor, bootstrap, and workspace model path. |
+| `external-create-adopt` | Planned   | A stable ecosystem generator exists, but RapidKit does not yet own the full post-create contract.   |
+| `adopt-only`            | Available | The project enters Workspace Intelligence through import/adopt, not native create.                  |
+
+## Native create
+
+Native create is reserved for kits with deterministic RapidKit contracts:
+
+- FastAPI
+- NestJS
+- Go Fiber and Go Gin
+- Spring Boot
+- ASP.NET Core Web API
+- Frontend kits (`frontend.nextjs`, `frontend.vite-react`, `frontend.angular`, and related frontend generators)
+
+These kits can be exposed through `rapidkit create project` because RapidKit can
+create the project and immediately produce the expected `.rapidkit` metadata,
+workspace registry entries, doctor evidence, and workspace model data.
+
+## External create, then adopt
+
+Some ecosystems have stable external commands but are not RapidKit-native create
+targets yet:
+
+- WordPress site: `wp core download`, `wp config create`, `wp db create`, `wp core install`
+- WordPress block/plugin: `npx @wordpress/create-block@latest <slug>`
+- Laravel: `composer create-project laravel/laravel <name>`
+- Symfony: `composer create-project symfony/skeleton <name>`
+- Rails: `rails new <name>`
+
+These are `external-create-adopt` candidates, not active native kits. Until the
+post-create contract is implemented end to end, RapidKit should guide users to
+create externally and then adopt/import the project.
+
+## Adopt only
+
+If a project already exists, or if the requested runtime has no RapidKit-owned
+create contract, the correct lane is `adopt-only`.
+
+Adoption still gives the project Workspace Intelligence:
+
+- framework and runtime detection
+- workspace registry membership
+- doctor and analyze evidence
+- workspace model and context generation
+- governance, Advisor, Studio, and agent grounding
+
+## Product rule
+
+Do not convert an unsupported or ambiguous stack request into a different native
+kit. For example, a PHP, WordPress, Laravel, Symfony, or Rails request must not
+be translated into FastAPI, NestJS, Go, Java, .NET, or a frontend kit.
+
+If native create is unavailable, the planner should explain the supported lane
+and guide the user to `adopt-only` or a future `external-create-adopt` flow.
+
+## CLI guard
+
+`rapidkit create project <kit> <name>` must check the capability lane before
+running any native generator or delegating to the Core engine.
+
+If the request resolves to `external-create-adopt` or an explicit `adopt-only`
+runtime, the CLI must stop early and explain:
+
+- native create is not available yet for the requested stack
+- whether the future lane is `external-create-adopt` or current `adopt-only`
+- which external generator commands are relevant, when known
+- how to run `npx rapidkit adopt <project-path>` after the project exists
+
+This keeps AI surfaces, CI, and developer terminals aligned: unsupported stacks
+are never silently rewritten into unrelated native kits.