rapidkit 0.29.1 → 0.31.0

package/README.md

@@ -131,6 +131,7 @@ npx rapidkit create # Prompts: workspace | project
 npx rapidkit create workspace <name> [--profile <profile>] [--author <name>] [--yes]
 npx rapidkit bootstrap [--profile <profile>] [--json]
 npx rapidkit setup <python|node|go|java> [--warm-deps]
+npx rapidkit analyze [--workspace <path>] [--json] [--strict] [--output <file>]
 npx rapidkit readiness [--json] [--strict]
 npx rapidkit autopilot release [--mode <audit|safe-fix|enforce>] [--json] [--output <file>] [--since <ref>] [--parallel] [--max-workers <n>]
 ```
@@ -145,6 +146,15 @@ npx rapidkit doctor workspace [--fix] [--plan] [--apply]
 npx rapidkit doctor project [--fix] [--plan] [--apply]
 npx rapidkit workspace list # Display all workspaces created on this system
 npx rapidkit workspace share [--output <file>] [--include-paths] [--no-doctor]
+npx rapidkit workspace contract init [--force] [--json]
+npx rapidkit workspace contract inspect [--json]
+npx rapidkit workspace contract verify [--strict] [--json]
+npx rapidkit workspace contract graph [--json]
+npx rapidkit workspace export --output team-workspace.rapidkit-archive.zip
+npx rapidkit workspace archive inspect team-workspace.rapidkit-archive.zip [--json]
+npx rapidkit workspace archive verify team-workspace.rapidkit-archive.zip [--strict] [--json]
+npx rapidkit workspace archive doctor team-workspace.rapidkit-archive.zip [--strict] [--json]
+npx rapidkit workspace hydrate team-workspace.rapidkit-archive.zip --output ./team-workspace
 npx rapidkit import <path|git-url> [--workspace <path>] [--name <project-name>] [--git] [--json]
 npx rapidkit snapshot create [name] [--include-projects] [--reason <text>] [--json]
 npx rapidkit snapshot list [--json]
@@ -247,6 +257,53 @@ Bundle content includes:
 
 `--include-paths` is intended for internal teams only because it includes absolute filesystem paths.
 
+### Workspace contract registry
+
+Use `workspace contract` when multiple projects in one workspace need a shared source of truth for
+services, ports, APIs, events, owners, dependencies, and required environment variables.
+
+```bash
+npx rapidkit workspace contract init
+npx rapidkit workspace contract inspect
+npx rapidkit workspace contract verify --strict
+npx rapidkit workspace contract graph
+```
+
+The contract is written to `.rapidkit/workspace.contract.json`. It starts from discovered RapidKit
+projects and gives teams a stable place to declare cross-project service contracts. Verification
+checks schema validity, duplicate project slugs, invalid or colliding ports, and dependencies that
+point to unknown projects.
+
+RapidKit keeps this contract alive during normal workspace work:
+
+- `create project` syncs the contract after successful project creation inside a workspace.
+- `workspace sync` reconciles discovered projects into the contract without overwriting manually declared APIs, events, owners, dependencies, env vars, or custom ports.
+- New projects receive a framework-aware default HTTP port when possible, and the next free port is selected if the default is already claimed.
+- `workspace share` includes the contract snapshot so teammates can inspect service topology before reproducing or importing the workspace.
+- `workspace contract graph` renders the service/dependency/event topology for humans or returns a JSON graph for tools and UI surfaces.
+
+### Portable workspace archives
+
+Use `workspace export` when you need to send a full workspace to a teammate or move it to another machine.
+Export excludes dependency folders, build output, git history, logs, `.env` files, and private keys by default.
+
+```bash
+npx rapidkit workspace export --output team-workspace.rapidkit-archive.zip
+npx rapidkit workspace archive inspect team-workspace.rapidkit-archive.zip
+npx rapidkit workspace archive verify team-workspace.rapidkit-archive.zip --strict
+npx rapidkit workspace archive doctor team-workspace.rapidkit-archive.zip
+npx rapidkit workspace hydrate team-workspace.rapidkit-archive.zip --output ./team-workspace
+
+# Preview a hydrate without writing files
+npx rapidkit workspace hydrate team-workspace.rapidkit-archive.zip --output ./team-workspace --dry-run
+```
+
+Archives include a RapidKit/Workspai manifest with file sizes and SHA-256 checksums. `workspace hydrate`
+verifies the archive before writing files. Use `workspace archive verify --strict` as a handoff or CI gate,
+and `workspace archive doctor` when you want human-readable readiness/security guidance before a teammate
+imports the workspace. Use `--include-env` only for trusted internal handoffs when you intentionally need
+environment files inside the archive.
+
 ### Command ownership
 
 RapidKit keeps the wrapper boundary explicit so users know which layer owns each action.
@@ -267,6 +324,7 @@ RapidKit keeps the wrapper boundary explicit so users know which layer owns each
 | `workspace run`                                    | Workspace orchestrator | Stage execution across discovered projects with optional affected-only, blast-radius expansion, and policy-gated pre-checks     |
 
 Use `npx rapidkit doctor` for a quick host pre-flight, `npx rapidkit doctor project` for a service-level check, and `npx rapidkit doctor workspace` for the full workspace picture.
+Use `npx rapidkit analyze --json` to generate CI-friendly workspace health evidence and save it under `.rapidkit/reports/`.
 Use `npx rapidkit doctor workspace --plan` or `npx rapidkit doctor project --plan` to preview remediation safely.
 Use `npx rapidkit doctor workspace --apply` or `npx rapidkit doctor project --apply` for non-interactive remediation runs.
 Use `npx rapidkit readiness` when you need machine-readable release evidence or strict CI gating.
@@ -474,13 +532,17 @@ npx rapidkit workspace run test --parallel
 # Test only affected projects since last commit
 npx rapidkit workspace run test --affected --since HEAD~1
 
-# Test affected + their dependents (requires dependency graph)
+# Test affected + downstream dependents from workspace.contract.json
 npx rapidkit workspace run test --affected --blast-radius
 
 # Build specific projects with custom stages (if defined in .rapidkit/context.json)
 npx rapidkit workspace run build --json --max-workers 8
 ```
 
+`--blast-radius` uses `.rapidkit/workspace.contract.json` when available. It expands direct
+`dependsOn` relationships and event relationships where one project `publishes` an event and another
+project `consumes` it. Legacy `.rapidkit/workspace-dependency-graph.json` remains supported as a fallback.
+
 ### Supported Runtimes & Frameworks
 
 | Runtime    | Frameworks                     | Status   |
@@ -580,6 +642,14 @@ npm run install:local
 npx rapidkit --version
 ```
 
+> Packaging note: `npm run prepack` will regenerate `data/modules-embeddings.json` from the mock embeddings script before `npm pack` / `npm publish`.
+>
+> If you need to refresh the local test embeddings manually, run:
+>
+> ```bash
+> npm run test:prepare-embeddings
+> ```
+
 ## Troubleshooting
 
 ### Quick fixes matrix