rapidkit 0.37.0 → 0.38.0

package/docs/doctor-command.md

@@ -0,0 +1,263 @@
+# RapidKit Doctor Command
+
+`doctor` checks health for the npm wrapper environment in system, workspace, or project scope.
+
+**Related:** [workspace-operations.md](./workspace-operations.md) · [commands-reference.md](./commands-reference.md) · [Documentation index](./README.md)
+
+## Command Modes
+
+### 1) System Check
+
+```bash
+npx rapidkit doctor
+```
+
+Checks host prerequisites:
+- Python
+- Poetry (optional)
+- pipx (optional)
+- RapidKit Core availability
+- Go (optional)
+
+### 2) Workspace Check (Canonical)
+
+```bash
+cd my-workspace
+npx rapidkit doctor workspace
+```
+
+Checks:
+- all system checks
+- workspace marker resolution
+- project discovery and per-project health
+- dependency/env readiness by project type (Python/Node/Go)
+
+> Compatibility note: `npx rapidkit doctor --workspace` still works, but `doctor workspace` is the canonical form.
+
+### 3) Project Check (Canonical)
+
+```bash
+cd my-workspace/my-project
+npx rapidkit doctor project
+```
+
+Checks:
+- all system checks
+- nearest project resolution (current folder or parent with project markers)
+- project-specific framework/runtime health
+- dependency/env readiness for the selected project
+- enterprise probes (config contract, migration surface, runtime health surface)
+- score explainability breakdown for audit trails
+
+> Compatibility note: `npx rapidkit doctor --project` also works.
+
+## Typical Usage
+
+```bash
+# Pre-flight on a contributor machine
+npx rapidkit doctor
+
+# Full check inside a workspace
+npx rapidkit doctor workspace
+
+# Focus only on current project
+npx rapidkit doctor project
+
+# Machine-readable output
+npx rapidkit doctor workspace --json
+
+# Attempt safe fixes (interactive)
+npx rapidkit doctor workspace --fix
+
+# Attempt safe fixes for current project only
+npx rapidkit doctor project --fix
+
+# JSON output with audit-ready breakdown + probes
+npx rapidkit doctor project --json
+```
+
+## Enterprise Fix Pipeline
+
+When `--fix` is enabled, Doctor now runs a staged treatment pipeline:
+
+1. Fix policy engine assigns risk for each fix step (`safe`, `guarded`, `invasive`).
+2. Transaction snapshots are created for guarded/invasive steps.
+3. Dependency orchestrator executes known dependency commands via structured adapters.
+4. Post-fix verification re-runs project diagnostics.
+5. Retry policy re-attempts transient network failures once before failing.
+
+If a guarded/invasive step fails, Doctor attempts rollback from snapshot and records the failure.
+
+## CI Example
+
+```yaml
+name: Health Check
+on: [push]
+
+jobs:
+  doctor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npx rapidkit doctor
+```
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | checks passed or warnings only |
+| `1` | blocking issues found |
+
+## Enterprise Probe Extensions
+
+Doctor supports project-local custom probes via JSON contract files:
+
+- `.rapidkit/doctor.probes.json`
+- `doctor.probes.json`
+
+Schema:
+
+```json
+{
+  "probes": [
+    {
+      "id": "db-schema-contract",
+      "label": "Database schema contract",
+      "severity": "error",
+      "anyOfPaths": ["prisma/schema.prisma", "migrations"],
+      "allOfPaths": ["README.md"],
+      "recommendation": "Define deterministic schema + migration baseline."
+    }
+  ]
+}
+```
+
+Each probe is evaluated during `doctor project` and emitted in:
+
+- human output (`Probe checks`)
+- JSON output (`project.probes`)
+- evidence (`doctor-project-last-run.json`)
+
+## Adapter Plugin Contract
+
+Doctor also supports runtime adapter checks via JSON contracts:
+
+- `.rapidkit/doctor.adapters.json`
+- `doctor.adapters.json`
+
+Schema:
+
+```json
+{
+  "checks": [
+    {
+      "id": "boot-probe-contract",
+      "label": "Boot probe contract",
+      "severity": "error",
+      "runtimes": ["node", "python"],
+      "anyOfPaths": ["src/main.ts", "app/main.py"],
+      "allOfPaths": ["README.md"],
+      "recommendation": "Expose deterministic bootstrap path and document runtime startup.",
+      "passReason": "Bootstrap contract markers detected.",
+      "failReason": "Bootstrap contract markers are missing."
+    }
+  ]
+}
+```
+
+This enables enterprise teams to extend Doctor checks without patching core CLI logic.
+
+## Score Explainability
+
+Both workspace/project JSON outputs include `scoreBreakdown` with:
+
+- `id` and `label`
+- normalized `status` (`ok`, `warn`, `error`)
+- `scope` (`host-system`, `project-scoped`)
+- `policyRuleId` (deterministic rule that selected status/severity)
+- deterministic `reason`
+
+Workspace scope additionally appends aggregate policy rules (`workspace-aggregate`), such as:
+
+- discovery gate
+- system error gate
+- blocking issue gate
+- advisory warning gate
+
+This allows CI and governance pipelines to audit why a score was produced.
+
+## Contract Metadata (Enterprise)
+
+Both JSON output and evidence files include a `contract` object:
+
+- `version`: current doctor evidence contract version
+- `scoringPolicyVersion`: current deterministic scoring policy version
+- `generatedBy`: emitting surface (`rapidkit-npm`)
+- `deterministicScoreBreakdown`: explicit deterministic score policy flag
+- `scopeModel`: how scope semantics are encoded
+
+Use these fields for strict consumers in CI/CD and extension adapters to prevent schema drift.
+
+## Drift Delta and Scope Provenance
+
+Workspace/project outputs now include:
+
+- `summary.scopeProvenance`: scoped vs aggregated vs mixed coverage summary
+- `driftDelta`: change report compared with previous evidence (new/resolved issues, score delta, system status changes)
+
+These fields are designed for release gates and extension timeline cards that must show progression, not only snapshots.
+
+## Workspace scope CI exit codes
+
+- `npx rapidkit doctor workspace --strict` exits `1` when health score reports errors **or** warnings.
+- `npx rapidkit doctor workspace --ci` exits `1` on errors and `2` on warnings only (errors take precedence).
+- Without `--strict` or `--ci`, doctor reports findings but exits `0` (backward compatible).
+
+## Workspace fix behavior
+
+- Reuses cached project scans when valid; refreshes `.rapidkit/reports/doctor-last-run.json`.
+- `--fix` runs interactive remediation; `--plan` prints plan only; `--apply` applies non-interactively.
+- `--plan` cannot be combined with `--fix` or `--apply`.
+- Advisory warnings do not automatically become shell fix commands.
+- Go `go mod tidy` fixes are skipped when the Go toolchain is unavailable.
+
+## Workspace JSON fields (AI/automation)
+
+`npx rapidkit doctor workspace --json` includes per-project metadata: `framework`, `frameworkKey`, `importStack`, `runtimeFamily`, `projectKind`, `supportTier`, `frameworkConfidence`.
+
+## Project scope behavior
+
+- Resolves current or nearest parent project from nested directories.
+- Supports RapidKit and non-RapidKit projects when `.rapidkit` is missing.
+- Evidence: `.rapidkit/reports/doctor-project-last-run.json`.
+- `--fix`, `--plan`, and `--apply` apply only project-scoped fixes.
+
+## Project JSON fields (AI/automation)
+
+`npx rapidkit doctor project --json` includes `scope`, `contract`, `project`, `summary.scopeProvenance`, `driftDelta`, and `scoreBreakdown`.
+
+## Evidence schema compatibility
+
+- Workspace evidence: `doctor-workspace-evidence-v1`
+- Project evidence: `doctor-project-evidence-v1`
+- Workspace scan cache: `doctor-workspace-cache-v1`
+
+Legacy evidence without `schemaVersion` is still accepted. Unknown versions are treated as invalid evidence. `readiness` and `workspace share` share the same validation path.
+
+## Related Workspace Commands
+
+```bash
+npx rapidkit bootstrap [--profile <profile>]
+npx rapidkit setup <python|node|go> [--warm-deps]
+npx rapidkit workspace list
+npx rapidkit cache <status|clear|prune|repair>
+npx rapidkit mirror <status|sync|verify|rotate>
+```
+
+Use `doctor workspace` before and after major workspace operations to detect drift early.
+Use `doctor project` before changing a single service to keep project-scope evidence deterministic.

package/docs/examples/ci-agent-grounding.yml

@@ -0,0 +1,62 @@
+# Example: RapidKit agent grounding gate for consumer workspaces
+#
+# Copy to your repo as `.github/workflows/rapidkit-agent-grounding.yml`
+# and adjust `working-directory` to your RapidKit workspace root.
+#
+# Requires: Node.js 20+, `rapidkit` available via npx in CI.
+
+name: RapidKit Agent Grounding
+
+on:
+  pull_request:
+    paths:
+      - '.rapidkit/**'
+      - 'AGENTS.md'
+      - 'CLAUDE.md'
+      - '.github/copilot-instructions.md'
+      - '.cursor/rules/**'
+  workflow_dispatch:
+
+jobs:
+  agent-grounding:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: . # set to your workspace root if nested
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install RapidKit CLI
+        run: npm install -g rapidkit@latest
+
+      - name: Run governance pipeline
+        run: npx rapidkit pipeline --json --strict
+        continue-on-error: true
+        id: pipeline
+
+      - name: Sync and verify agent grounding
+        run: |
+          npx rapidkit workspace agent-sync --write --refresh-context --strict --json
+        env:
+          RAPIDKIT_NO_AGENT_SYNC: '0'
+
+      - name: Upload agent grounding artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: rapidkit-agent-grounding
+          path: |
+            .rapidkit/reports/INDEX.json
+            .rapidkit/reports/workspace-context-agent.json
+            .rapidkit/reports/pipeline-last-run.json
+            AGENTS.md
+          if-no-files-found: ignore
+
+      - name: Fail if pipeline blocked
+        if: steps.pipeline.outcome == 'failure'
+        run: exit 1

package/docs/from-code-to-shared-understanding.md

@@ -0,0 +1,46 @@
+# From Code to Shared Understanding
+
+How RapidKit transforms projects and repositories into workspace intelligence for developers, CI, and AI agents.
+
+This Mermaid diagram is kept in the internal documentation because GitHub renders it correctly. The main npm README uses a PNG version of the same diagram so it remains visible on npm package pages.
+
+```mermaid
+flowchart TB
+
+    Code["Code & Repositories"]
+    Projects["Projects"]
+    Workspace["Workspace"]
+
+    Code --> Projects
+    Projects --> Workspace
+
+    subgraph Intelligence["Workspace Intelligence"]
+        Model["Workspace Model"]
+        Context["Agent Context"]
+        Impact["Impact Analysis"]
+        Verify["Verification"]
+        Evidence["Evidence & Gates"]
+    end
+
+    Workspace --> Model
+    Workspace --> Context
+    Workspace --> Impact
+    Workspace --> Verify
+    Workspace --> Evidence
+
+    Model --> Dev["Developers"]
+    Model --> CI["CI"]
+    Model --> Agents["AI Agents"]
+
+    Context --> Agents
+
+    Impact --> Dev
+    Impact --> CI
+
+    Verify --> CI
+    Verify --> Agents
+    Evidence --> Dev
+    Evidence --> CI
+    Evidence --> Agents
+```
+

package/docs/governance-policy.enterprise.example.json

@@ -0,0 +1,40 @@
+{
+    "policies": {
+        "dev": {
+            "allowedIdentities": [
+                "release@your-org.example"
+            ],
+            "allowedIssuers": [
+                "https://token.actions.githubusercontent.com"
+            ],
+            "allowedRekorUrls": [
+                "https://rekor.sigstore.dev"
+            ],
+            "requireTransparencyLog": false
+        },
+        "stage": {
+            "allowedIdentities": [
+                "release@your-org.example"
+            ],
+            "allowedIssuers": [
+                "https://token.actions.githubusercontent.com"
+            ],
+            "allowedRekorUrls": [
+                "https://rekor.sigstore.dev"
+            ],
+            "requireTransparencyLog": true
+        },
+        "prod": {
+            "allowedIdentities": [
+                "release@your-org.example"
+            ],
+            "allowedIssuers": [
+                "https://token.actions.githubusercontent.com"
+            ],
+            "allowedRekorUrls": [
+                "https://rekor.sigstore.dev"
+            ],
+            "requireTransparencyLog": true
+        }
+    }
+}

package/docs/mirror-config.enterprise.example.json

@@ -0,0 +1,60 @@
+{
+    "enabled": true,
+    "mode": "offline-first",
+    "prefetch": {
+        "retries": 2,
+        "backoffMs": 300,
+        "timeoutMs": 15000
+    },
+    "retention": {
+        "keepLast": 10
+    },
+    "security": {
+        "requireAttestation": true,
+        "requireSigstore": true,
+        "requireTransparencyLog": true,
+        "requireSignedGovernance": true,
+        "governanceBundle": {
+            "policyPath": ".rapidkit/governance-policy.json",
+            "signaturePath": ".rapidkit/governance-policy.sig",
+            "publicKeyPath": ".rapidkit/governance-public.pem",
+            "algorithm": "sha256"
+        },
+        "evidenceExport": {
+            "enabled": true,
+            "target": "http",
+            "endpoint": "https://siem.example.com/intake/rapidkit",
+            "authTokenEnv": "RAPIDKIT_EVIDENCE_TOKEN",
+            "timeoutMs": 10000,
+            "retries": 3,
+            "backoffMs": 500,
+            "deadLetterPath": ".rapidkit/reports/evidence-export-dead-letter.ndjson",
+            "signing": {
+                "enabled": true,
+                "hmacKeyEnv": "RAPIDKIT_EVIDENCE_HMAC_KEY",
+                "algorithm": "sha256",
+                "headerName": "x-rapidkit-evidence-signature"
+            },
+            "failOnError": true
+        }
+    },
+    "artifacts": [
+        {
+            "id": "backend-release",
+            "source": "mirror-source/release.bin",
+            "target": "releases/release.bin",
+            "sha256": "PUT_REAL_SHA256_HERE",
+            "required": true,
+            "attestation": {
+                "signature": "BASE64_DETACHED_SIGNATURE",
+                "publicKeyPath": ".rapidkit/mirror-public.pem",
+                "sigstore": {
+                    "signaturePath": ".rapidkit/release.sig",
+                    "identity": "release@your-org.example",
+                    "issuer": "https://token.actions.githubusercontent.com",
+                    "rekorUrl": "https://rekor.sigstore.dev"
+                }
+            }
+        }
+    ]
+}

package/docs/policies.workspace.example.yml

@@ -0,0 +1,23 @@
+version: "1.0"
+mode: warn # "warn" or "strict"
+dependency_sharing_mode: isolated # "isolated" or "shared-runtime-caches" or "shared-node-deps"
+# change profile (recommended): npx rapidkit bootstrap --profile polyglot
+# change mode/dependency manually: edit this file and rerun npx rapidkit init
+
+rules:
+  enforce_workspace_marker: true
+  enforce_toolchain_lock: false
+  disallow_untrusted_tool_sources: false
+  enforce_compatibility_matrix: false
+  require_mirror_lock_for_offline: true
+
+# preferred policy management commands:
+# npx rapidkit workspace policy show
+# npx rapidkit workspace policy set mode strict
+# npx rapidkit workspace policy set dependency_sharing_mode shared-runtime-caches
+# npx rapidkit workspace policy set rules.enforce_toolchain_lock true
+
+# dependency_sharing_mode options:
+# - isolated               (default, safest)
+# - shared-runtime-caches  (share Node/Python/Go caches at workspace level)
+# - shared-node-deps       (compat alias for Node shared mode)

package/docs/workspace-operations.md

@@ -0,0 +1,160 @@
+# Workspace Operations
+
+Behavioral guide for import, adoption, snapshots, archives, contracts, collaboration bundles, and local infra sidecars.
+
+Command syntax: [commands-reference.md](./commands-reference.md).
+
+## Import and adoption
+
+Use `import` to copy or clone an existing project into a RapidKit workspace.
+Use `adopt` when the project must stay where it already lives but should become visible to RapidKit and Workspai workspace intelligence.
+
+```bash
+npx rapidkit import ../orders-api
+npx rapidkit import https://github.com/acme/orders-api.git --git
+npx rapidkit import ../orders-api --workspace ./my-workspace --name orders-api --json
+npx rapidkit adopt ../marketing-web --workspace ./my-workspace
+npx rapidkit adopt --json
+```
+
+### Import behavior
+
+- Local folders are copied; git sources are cloned with shallow history.
+- Outside any workspace (no `--workspace`), RapidKit auto-creates/reuses the managed **Workspai** workspace at `~/rapidkit/workspaces/workspai`.
+- Existing workspaces under `~/Workspai/rapidkits/*` remain registered after upgrade.
+- CLI prints a next-step `cd ...` hint (`suggestedCdCommand` in JSON mode).
+- Failed workspace sync rolls back imported files and registry entries.
+
+### Adopt behavior
+
+- Source files are not moved or copied.
+- Default workspace resolution matches import (`workspai` under `~/rapidkit/workspaces/`).
+- Writes `.rapidkit/project.json`, `.rapidkit/adopt.json`, and `.rapidkit/adopt-readiness.json`.
+- Registry and contract sync include adopted projects for `workspace model`, `workspace context`, Dashboard, and agents.
+- `--dry-run --json` previews detection without writing metadata.
+
+### JSON output (`--json`)
+
+- `workspacePath`, `workspaceResolution` (`explicit` | `nearest` | `default-auto`)
+- `defaultWorkspaceCreated`, `suggestedCdCommand`
+- `importedProject` or `adoptedProject` (`name`, `path`, `stack`, `runtime`, `framework`, `supportTier`, `moduleSupport`, `confidence`, `source`)
+
+Imported projects receive `.rapidkit/import-readiness.json`. Adopted projects add frontend-aware detection for Next.js, React, Vite, Vue, Angular, SvelteKit, Nuxt, Astro, Remix, and Solid.
+
+## Workspace snapshots and safe project operations
+
+```bash
+npx rapidkit snapshot create before-upgrade --reason "before dependency upgrade"
+npx rapidkit snapshot list
+npx rapidkit snapshot inspect before-upgrade
+npx rapidkit snapshot restore before-upgrade --dry-run
+npx rapidkit snapshot restore before-upgrade --force
+```
+
+Project delete is safe-by-default:
+
+```bash
+npx rapidkit project archive orders-api --reason "replaced by orders-v2"
+npx rapidkit project archives
+npx rapidkit project restore orders-api
+npx rapidkit project delete orders-api
+npx rapidkit project delete orders-api --permanent --confirm orders-api
+```
+
+Lifecycle safety:
+
+- `project delete` archives by default; permanent removal requires `--permanent --confirm <exact-name>`.
+- `snapshot restore` requires `--force` unless dry-run.
+- Restore, archive, and permanent delete create pre-operation metadata snapshots.
+- Archive manifests live under `.rapidkit/archive/projects`.
+- Audit records append to `.rapidkit/audit/events.jsonl`.
+- Workspace policy can require reasons, safety snapshots, or block permanent delete via `.rapidkit/policies.yml`.
+
+## Workspace collaboration bundle
+
+```bash
+npx rapidkit workspace share
+npx rapidkit workspace share --output ./team-share.json
+npx rapidkit workspace share --include-paths
+npx rapidkit workspace share --no-doctor
+```
+
+Bundle includes workspace metadata, discovered projects, report index, and latest doctor evidence (unless `--no-doctor`). `--include-paths` is for internal teams only (absolute paths).
+
+## Workspace contract registry
+
+```bash
+npx rapidkit workspace contract init
+npx rapidkit workspace contract inspect
+npx rapidkit workspace contract verify --strict
+npx rapidkit workspace contract graph
+```
+
+Contract file: `.rapidkit/workspace.contract.json`. Verification checks schema, duplicate slugs, port collisions, and unknown dependencies.
+
+RapidKit keeps the contract alive during `create project` and `workspace sync` without overwriting manual API/event/owner declarations.
+
+## Portable workspace archives
+
+```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
+```
+
+Export excludes dependency folders, build output, git history, logs, `.env`, and private keys by default. Use `--include-env` only for trusted internal handoffs.
+
+## Workspace infrastructure (sidecar)
+
+Discovery sources: Core module slugs, project `.env.example`, workspace contract env, and `.rapidkit/infra/overrides.json`.
+
+```bash
+cd my-workspace
+npx rapidkit infra plan
+npx rapidkit infra up
+npx rapidkit infra status --strict
+npx rapidkit infra down
+```
+
+Artifacts:
+
+- `.rapidkit/infra/docker-compose.yml`
+- `.rapidkit/reports/infra-plan.json`
+- `.rapidkit/infra/.env.example`
+
+## Command ownership
+
+| Command family | Owner | Notes |
+| --- | --- | --- |
+| `create workspace`, `workspace`, `cache`, `mirror`, `infra` | RapidKit wrapper | Platform orchestration |
+| `init` | Wrapper orchestrated | Project init; full-init alias at workspace root |
+| `dev`, `test`, `build`, `start` | Runtime aware | Delegates to active project/runtime |
+| `readiness` | Wrapper release gate | Env + doctor + analyze + verify + dependency gates |
+| `pipeline` | Wrapper orchestrator | sync → doctor → analyze → readiness → autopilot |
+| `autopilot release` | Wrapper orchestrator | End-to-end release gate evidence |
+| `import` | Workspace ingestion | Rollback-safe sync |
+| `adopt` | Workspace adoption | In-place linking + registry sync |
+| `workspace model/context/diff/impact/verify` | Workspace intelligence | Model, context packs, blast radius |
+| `snapshot` | Workspace recovery | Metadata or full snapshots |
+| `project archive/restore/delete` | Project lifecycle | Safe delete with confirmation |
+| `doctor` / `doctor workspace` / `doctor project` | Wrapper health | Host, workspace, and project scopes |
+| `workspace run` | Workspace orchestrator | Fleet stage execution |
+| `infra` | Workspace sidecar | Contract-driven local dependencies |
+
+## Verification evidence freshness
+
+`workspace verify` treats evidence as release-gate material, not just as a file
+presence check. Required project evidence must match the affected project in
+`workspace-run-last.json`, and evidence generated before the current impact
+report is treated as stale and blocking. Re-run the recommended commands from
+`workspace impact --json` before using `workspace verify --strict` in CI.
+
+For doctor CI exit codes and JSON evidence fields, see [doctor-command.md](./doctor-command.md).
+
+## See also
+
+- [Documentation index](./README.md)
+- [commands-reference.md](./commands-reference.md)
+- [doctor-command.md](./doctor-command.md)