{"id":50400085,"url":"https://github.com/rapidkitlabs/rapidkit-npm","last_synced_at":"2026-06-09T01:01:15.454Z","repository":{"id":321999426,"uuid":"1081781406","full_name":"rapidkitlabs/rapidkit-npm","owner":"rapidkitlabs","description":"Official CLI for RapidKit - an open-source workspace platform that standardizes how teams build, scale, and deploy backend services.","archived":false,"fork":false,"pushed_at":"2026-06-02T23:08:08.000Z","size":1749,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T12:23:28.670Z","etag":null,"topics":["api","backend","boilerplate","cli","developer-tools","fastapi","frameworks","generator","microservices","nestjs","python","rapidkit","scaffold","typescript","workspace"],"latest_commit_sha":null,"homepage":"https://www.getrapidkit.com/rapidkit-npm","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rapidkitlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":"docs/governance-policy.enterprise.example.json","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T09:26:10.000Z","updated_at":"2026-06-02T23:05:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rapidkitlabs/rapidkit-npm","commit_stats":null,"previous_names":["getrapidkit/rapidkit-npm","rapidkitlabs/rapidkit-npm"],"tags_count":67,"template":false,"template_full_name":null,"purl":"pkg:github/rapidkitlabs/rapidkit-npm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapidkitlabs%2Frapidkit-npm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapidkitlabs%2Frapidkit-npm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapidkitlabs%2Frapidkit-npm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapidkitlabs%2Frapidkit-npm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rapidkitlabs","download_url":"https://codeload.github.com/rapidkitlabs/rapidkit-npm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapidkitlabs%2Frapidkit-npm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34086664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","backend","boilerplate","cli","developer-tools","fastapi","frameworks","generator","microservices","nestjs","python","rapidkit","scaffold","typescript","workspace"],"created_at":"2026-05-30T23:01:03.282Z","updated_at":"2026-06-09T01:01:15.444Z","avatar_url":"https://github.com/rapidkitlabs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RapidKit NPM CLI\n\n\u003e RapidKit is an open-source workspace platform that standardizes how teams build, scale, and deploy backend services.\n\nProduction-ready scaffolding for FastAPI, NestJS, Spring Boot, Go/Fiber, Go/Gin, and ASP.NET Core.  \n**50+ RapidKit Core modules** are available through the CLI for supported module-capable runtimes, with FastAPI and NestJS as first-class module installation targets. Spring Boot, Go, and ASP.NET Core kits run as npm-level generators.\nBuilt for clean architecture, minimal boilerplate, and fast deployment.\n\n\u003e **💡 Recommended:** Install the [Workspai VS Code extension](https://marketplace.visualstudio.com/items?itemName=rapidkit.rapidkit-vscode) for AI-assisted project creation, workspace exploration, and context-aware coding — all backed by this CLI.\n\n[![npm version](https://img.shields.io/npm/v/rapidkit.svg?style=flat-square)](https://www.npmjs.com/package/rapidkit)\n[![Downloads](https://img.shields.io/npm/dm/rapidkit.svg?style=flat-square)](https://www.npmjs.com/package/rapidkit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\n[![GitHub Stars](https://img.shields.io/github/stars/rapidkitlabs/rapidkit-npm.svg?style=flat-square)](https://github.com/rapidkitlabs/rapidkit-npm/stargazers)\n[![Built by RapidKit](https://img.shields.io/badge/Built%20by-RapidKit-0f172a?logo=github)](https://www.getrapidkit.com)\n\nThe official RapidKit npm CLI for creating and operating workspaces and projects.\n\n- Workspace-first lifecycle (`create workspace` → `bootstrap` → `setup` → `create project`)\n- Multi-runtime support across Python, Node.js, Java, Go, and .NET\n- Policy enforcement with `warn` / `strict` modes\n- Cache and mirror lifecycle commands for stable environments\n\n## Workspace-First Architecture\n\nRapidKit is designed around the workspace as the operational boundary.\n\n- The workspace owns policy, readiness, and shared tooling state.\n- Projects are discovered and managed inside that workspace boundary.\n- Wrapper-owned commands stay in the npm CLI; runtime-specific execution is delegated only when appropriate.\n- Release evidence is written into `.rapidkit/reports/` so CI, docs, and local workflows use the same contract surface.\n\nThis layout keeps workspace setup deterministic, makes cross-project orchestration explicit, and avoids drifting behavior between the CLI and the core runtime.\n\n## RapidKit CLI in the Workspai Ecosystem\n\nThe `rapidkit` npm package remains the official RapidKit CLI.\n\nIt works alongside Workspai, a product developed by RapidKit.\n\n| Component         | Repository                                                                          | Role                                                       |\n| ----------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------- |\n| CLI               | [rapidkitlabs/rapidkit-npm](https://github.com/rapidkitlabs/rapidkit-npm)           | Official RapidKit npm CLI                                  |\n| VS Code Extension | [rapidkitlabs/rapidkit-vscode](https://github.com/rapidkitlabs/rapidkit-vscode)     | **Workspai** — visual explorer + AI features (recommended) |\n| Core Engine       | [rapidkitlabs/rapidkit-core](https://github.com/rapidkitlabs/rapidkit-core)         | Official RapidKit Core                                     |\n| Examples          | [rapidkitlabs/rapidkit-examples](https://github.com/rapidkitlabs/rapidkit-examples) | Example workspaces and starter references                  |\n\n## Requirements\n\n- Node.js `\u003e= 20.19.6`\n- Python `\u003e= 3.10` (for Python/Core workflows)\n- Java 21+ and Maven 3.9+ (optional, for Spring Boot projects)\n- Go (optional, for Go projects)\n- .NET SDK 8+ (optional, for ASP.NET Core projects)\n\n## Install\n\nInstall the RapidKit CLI npm package (`rapidkit`) globally:\n\n```bash\nnpm install -g rapidkit\n```\n\nOr run directly with `npx`:\n\n```bash\nnpx rapidkit --help\n```\n\nThe commands above provide install/help entry points for the same CLI.\n\n## 60-Second Quickstart\n\n```bash\nnpx rapidkit my-workspace\ncd my-workspace\nnpx rapidkit create project\ncd \u003cproject-name\u003e\nnpx rapidkit init \u0026\u0026 npx rapidkit dev\n```\n\nIf you prefer explicit commands instead of shortcut mode:\n\n```bash\nnpx rapidkit create workspace my-workspace --yes --profile polyglot\n```\n\n## Quick Start (Recommended)\n\n### 1) Create a workspace\n\n```bash\nnpx rapidkit create workspace my-workspace --yes --profile polyglot\ncd my-workspace\n```\n\nShortcut form (equivalent workspace creation flow):\n\n```bash\nnpx rapidkit my-workspace\n```\n\nThis shortcut launches the same interactive workspace wizard (author, profile, Python version, environment strategy).\n\n### 2) Bootstrap and setup runtimes\n\n```bash\nnpx rapidkit bootstrap --profile polyglot\nnpx rapidkit setup python\nnpx rapidkit setup node --warm-deps\nnpx rapidkit setup java --warm-deps\nnpx rapidkit setup go --warm-deps\nnpx rapidkit setup dotnet --warm-deps\n```\n\n### 3) Create projects\n\n```bash\nnpx rapidkit create project                  # Interactive kit picker\nnpx rapidkit create project fastapi.standard my-api --yes --skip-install\nnpx rapidkit create project fastapi.ddd my-api --yes --skip-install\nnpx rapidkit create project nestjs.standard my-nest --yes --skip-install\nnpx rapidkit create project springboot.standard my-spring --yes --skip-install\nnpx rapidkit create project gofiber.standard my-fiber --yes --skip-install\nnpx rapidkit create project gogin.standard my-gin --yes --skip-install\nnpx rapidkit create project dotnet.webapi.clean my-dotnet --yes --skip-install\n```\n\n## Core Commands\n\n### Workspace lifecycle\n\n```bash\nnpx rapidkit create # Prompts: workspace | project\nnpx rapidkit create workspace \u003cname\u003e [--profile \u003cprofile\u003e] [--author \u003cname\u003e] [--yes]\nnpx rapidkit bootstrap [--profile \u003cprofile\u003e] [--json]\nnpx rapidkit setup \u003cpython|node|go|java|dotnet\u003e [--warm-deps]\nnpx rapidkit analyze [--workspace \u003cpath\u003e] [--json] [--strict] [--output \u003cfile\u003e]\nnpx rapidkit readiness [--json] [--strict]\nnpx rapidkit autopilot release [--mode \u003caudit|safe-fix|enforce\u003e] [--json] [--output \u003cfile\u003e] [--since \u003cref\u003e] [--parallel] [--max-workers \u003cn\u003e]\n```\n\nRecommended for CI: `npx rapidkit autopilot release --mode enforce --json --output .rapidkit/reports/autopilot-release.json`\n\n```bash\nnpx rapidkit workspace policy show\nnpx rapidkit workspace policy set \u003ckey\u003e \u003cvalue\u003e\nnpx rapidkit doctor\nnpx rapidkit doctor workspace [--fix] [--plan] [--apply]\nnpx rapidkit doctor project [--fix] [--plan] [--apply]\nnpx rapidkit workspace list # Display all workspaces created on this system\nnpx rapidkit workspace share [--output \u003cfile\u003e] [--include-paths] [--no-doctor]\nnpx rapidkit workspace contract init [--force] [--json]\nnpx rapidkit workspace contract inspect [--json]\nnpx rapidkit workspace contract verify [--strict] [--json]\nnpx rapidkit workspace contract graph [--json]\nnpx rapidkit workspace export --output team-workspace.rapidkit-archive.zip\nnpx rapidkit workspace archive inspect team-workspace.rapidkit-archive.zip [--json]\nnpx rapidkit workspace archive verify team-workspace.rapidkit-archive.zip [--strict] [--json]\nnpx rapidkit workspace archive doctor team-workspace.rapidkit-archive.zip [--strict] [--json]\nnpx rapidkit workspace hydrate team-workspace.rapidkit-archive.zip --output ./team-workspace\nnpx rapidkit import \u003cpath|git-url\u003e [--workspace \u003cpath\u003e] [--name \u003cproject-name\u003e] [--git] [--json]\nnpx rapidkit snapshot create [name] [--include-projects] [--reason \u003ctext\u003e] [--json]\nnpx rapidkit snapshot list [--json]\nnpx rapidkit snapshot inspect \u003cname\u003e [--json]\nnpx rapidkit snapshot restore \u003cname\u003e [--dry-run] [--force] [--json]\nnpx rapidkit project archive \u003cname\u003e [--reason \u003ctext\u003e] [--dry-run] [--json]\nnpx rapidkit project archives [--json]\nnpx rapidkit project restore \u003carchive\u003e [--name \u003cproject-name\u003e] [--force] [--dry-run] [--json]\nnpx rapidkit project delete \u003cname\u003e [--permanent --confirm \u003cname\u003e] [--dry-run] [--json]\nnpx rapidkit workspace init # Full-init alias (same behavior as root init/workspace run init at workspace root)\nnpx rapidkit workspace run \u003cinit|test|build|start\u003e [--affected] [--blast-radius] [--since \u003cref\u003e] [--parallel] [--max-workers \u003cn\u003e] [--strict] [--json]\n```\n\n### Project import into workspace\n\nUse `import` to bring an existing backend project (local folder or git repository) into a RapidKit workspace.\n\n```bash\n# Local folder import\nnpx rapidkit import ../orders-api\n\n# Git import\nnpx rapidkit import https://github.com/acme/orders-api.git --git\n\n# Explicit workspace and custom target name\nnpx rapidkit import ../orders-api --workspace ./my-workspace --name orders-api\n\n# Machine-readable output\nnpx rapidkit import ../orders-api --json\n```\n\nImport behavior:\n\n- Local folders are copied; git sources are cloned with shallow history.\n- If you run import outside any workspace and do not pass `--workspace`, RapidKit auto-creates/reuses the default workspace at `~/Workspai/rapidkits/default-workspace`.\n- CLI cannot change your parent shell directory; instead it prints a next-step `cd ...` hint (and returns `suggestedCdCommand` in JSON mode).\n- If workspace sync fails after import, RapidKit rolls back imported files and registry entries before returning an error.\n\nJSON output (`--json`) includes:\n\n- `workspacePath`\n- `workspaceResolution` (`explicit` | `nearest` | `default-auto`)\n- `defaultWorkspaceCreated`\n- `suggestedCdCommand`\n- `importedProject` (`name`, `path`, `stack`, `runtime`, `framework`, `supportTier`, `moduleSupport`, `confidence`, `source`)\n\nImported projects also receive `.rapidkit/import-readiness.json`, which records framework detection,\nruntime command support, and module mutation policy. Existing projects from Laravel, Rails, Rust,\nElixir, Kotlin, Deno, Bun, and other ecosystems are importable/governed even when RapidKit does not\nyet ship a first-class scaffold for that stack.\n\n### Workspace snapshots and safe project operations\n\nUse `snapshot` before migrations, mass imports, dependency upgrades, or release preparation.\nBy default snapshots preserve workspace metadata only (`.rapidkit`, workspace marker, and config files).\nUse `--include-projects` when you need a full recoverable copy of project source files too.\n\n```bash\nnpx rapidkit snapshot create before-upgrade --reason \"before dependency upgrade\"\nnpx rapidkit snapshot list\nnpx rapidkit snapshot inspect before-upgrade\nnpx rapidkit snapshot restore before-upgrade --dry-run\nnpx rapidkit snapshot restore before-upgrade --force\n```\n\nProject delete is intentionally safe-by-default:\n\n```bash\nnpx rapidkit project archive orders-api --reason \"replaced by orders-v2\"\nnpx rapidkit project archives\nnpx rapidkit project restore orders-api\nnpx rapidkit project delete orders-api\nnpx rapidkit project delete orders-api --permanent --confirm orders-api\n```\n\nLifecycle safety rules:\n\n- `project delete` archives by default; permanent removal requires `--permanent --confirm \u003cexact-project-name\u003e`.\n- `snapshot restore` requires `--force` unless it is a dry-run.\n- Restore, archive, and permanent delete create a pre-operation metadata snapshot automatically.\n- Archive manifests are stored beside archived projects under `.rapidkit/archive/projects`.\n- Lifecycle operations append JSONL audit records to `.rapidkit/audit/events.jsonl`.\n- Workspace policy can require reasons, require safety snapshots, or block permanent delete via `.rapidkit/policies.yml`.\n\n### Workspace collaboration bundle\n\nUse `workspace share` to export a portable JSON snapshot for team handoff,\ndebugging, and cross-machine diagnostics.\n\n```bash\nnpx rapidkit workspace share\n# default output: .rapidkit/reports/share-bundle.json\n\nnpx rapidkit workspace share --output ./team-share.json\nnpx rapidkit workspace share --include-paths\nnpx rapidkit workspace share --no-doctor\n```\n\nBundle content includes:\n\n- Workspace metadata (`name`, `profile`, RapidKit version)\n- Discovered RapidKit projects (`relative_path`, runtime, kit)\n- Workspace and project report file index\n- Latest doctor evidence per project (unless `--no-doctor` is used)\n\n`--include-paths` is intended for internal teams only because it includes absolute filesystem paths.\n\n### Workspace contract registry\n\nUse `workspace contract` when multiple projects in one workspace need a shared source of truth for\nservices, ports, APIs, events, owners, dependencies, and required environment variables.\n\n```bash\nnpx rapidkit workspace contract init\nnpx rapidkit workspace contract inspect\nnpx rapidkit workspace contract verify --strict\nnpx rapidkit workspace contract graph\n```\n\nThe contract is written to `.rapidkit/workspace.contract.json`. It starts from discovered RapidKit\nprojects and gives teams a stable place to declare cross-project service contracts. Verification\nchecks schema validity, duplicate project slugs, invalid or colliding ports, and dependencies that\npoint to unknown projects.\n\nRapidKit keeps this contract alive during normal workspace work:\n\n- `create project` syncs the contract after successful project creation inside a workspace.\n- `workspace sync` reconciles discovered projects into the contract without overwriting manually declared APIs, events, owners, dependencies, env vars, or custom ports.\n- New projects receive a framework-aware default HTTP port when possible, and the next free port is selected if the default is already claimed.\n- `workspace share` includes the contract snapshot so teammates can inspect service topology before reproducing or importing the workspace.\n- `workspace contract graph` renders the service/dependency/event topology for humans or returns a JSON graph for tools and UI surfaces.\n\n### Portable workspace archives\n\nUse `workspace export` when you need to send a full workspace to a teammate or move it to another machine.\nExport excludes dependency folders, build output, git history, logs, `.env` files, and private keys by default.\n\n```bash\nnpx rapidkit workspace export --output team-workspace.rapidkit-archive.zip\nnpx rapidkit workspace archive inspect team-workspace.rapidkit-archive.zip\nnpx rapidkit workspace archive verify team-workspace.rapidkit-archive.zip --strict\nnpx rapidkit workspace archive doctor team-workspace.rapidkit-archive.zip\nnpx rapidkit workspace hydrate team-workspace.rapidkit-archive.zip --output ./team-workspace\n\n# Preview a hydrate without writing files\nnpx rapidkit workspace hydrate team-workspace.rapidkit-archive.zip --output ./team-workspace --dry-run\n```\n\nArchives include a RapidKit/Workspai manifest with file sizes and SHA-256 checksums. `workspace hydrate`\nverifies the archive before writing files. Use `workspace archive verify --strict` as a handoff or CI gate,\nand `workspace archive doctor` when you want human-readable readiness/security guidance before a teammate\nimports the workspace. Use `--include-env` only for trusted internal handoffs when you intentionally need\nenvironment files inside the archive.\n\n### Command ownership\n\nRapidKit keeps the wrapper boundary explicit so users know which layer owns each action.\n\n| Command family                                     | Owner                  | Notes                                                                                                                           |\n| -------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| `create workspace`, `workspace`, `cache`, `mirror` | RapidKit wrapper       | Platform-level orchestration                                                                                                    |\n| `init`                                             | Wrapper orchestrated   | Project init in project dirs; full-init alias at workspace root                                                                 |\n| `dev`, `test`, `build`, `start`                    | Runtime aware          | Delegates to the active project/runtime when available                                                                          |\n| `readiness`                                        | Wrapper release gate   | Generates release-readiness evidence (`--json` for CI, `--strict` for fail-fast)                                                |\n| `autopilot release`                                | Wrapper orchestrator   | Runs doctor/readiness/remediation/workspace-run gates and emits release verdict evidence                                        |\n| `import`                                           | Workspace ingestion    | Imports local folders or git backends with rollback-safe sync behavior                                                          |\n| `snapshot`                                         | Workspace recovery     | Creates/list/restores metadata or full workspace snapshots with destructive-operation guards                                    |\n| `project archive/restore/delete`                   | Project lifecycle      | Archives by default, restores archived projects, requires exact confirmation for permanent delete, and creates safety snapshots |\n| `doctor`                                           | Wrapper system check   | Checks host prerequisites by default                                                                                            |\n| `doctor workspace`                                 | Workspace health       | Full workspace scan with project-level details and fixes                                                                        |\n| `doctor project`                                   | Project health         | Current project (or nearest parent) diagnostics with project evidence and scoped fixes                                          |\n| `workspace run`                                    | Workspace orchestrator | Stage execution across discovered projects with optional affected-only, blast-radius expansion, and policy-gated pre-checks     |\n\nUse `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.\nUse `npx rapidkit analyze --json` to generate CI-friendly workspace health evidence and save it under `.rapidkit/reports/`.\nUse `npx rapidkit doctor workspace --plan` or `npx rapidkit doctor project --plan` to preview remediation safely.\nUse `npx rapidkit doctor workspace --apply` or `npx rapidkit doctor project --apply` for non-interactive remediation runs.\nUse `npx rapidkit readiness` when you need machine-readable release evidence or strict CI gating.\nUse `npx rapidkit autopilot release` to run an end-to-end pre-merge release gate in one command.\n\n### Doctor workspace fix behavior\n\n- `npx rapidkit doctor workspace` reuses cached project scans when valid and refreshes evidence under `.rapidkit/reports/doctor-last-run.json`.\n- `npx rapidkit doctor workspace --fix` runs interactive remediation (confirmation prompt).\n- `npx rapidkit doctor workspace --plan` prints remediation plan only (no mutations).\n- `npx rapidkit doctor workspace --apply` applies remediation plan non-interactively.\n- Advisory warnings (for example, detected vulnerabilities or optional env metadata gaps) are reported in workspace health, but they do not automatically become shell fix commands.\n- It is valid to see `No fixes needed` after `--fix`/`--apply` when only advisory warnings are present.\n- URL-based fixes are recorded as manual guidance (for example, install pages) and are not executed as shell commands.\n- Go project fixes that require `go mod tidy` are skipped when the Go toolchain is not available, with a clear install-and-rerun hint.\n- `--plan` cannot be combined with `--fix` or `--apply`.\n\n### Doctor workspace JSON fields (AI/automation)\n\n`npx rapidkit doctor workspace --json` includes project-level runtime/profile metadata used by extension and AI tooling:\n\n- `framework`\n- `frameworkKey`\n- `importStack`\n- `runtimeFamily`\n- `projectKind`\n- `supportTier`\n- `frameworkConfidence`\n\n### Doctor project behavior\n\n- `npx rapidkit doctor project` resolves the current project or the nearest parent project when run from nested directories.\n- Project mode supports RapidKit and non-RapidKit backend projects (generic runtime diagnostics still run when `.rapidkit` is missing).\n- JSON evidence is written to `.rapidkit/reports/doctor-project-last-run.json` (workspace-level when available).\n- `--fix` in project mode applies only project-scoped actionable fixes, with the same safe/guarded handling used by doctor fix flows.\n- `--plan` in project mode prints remediation plan only (no mutations).\n- `--apply` in project mode applies project-scoped remediation non-interactively.\n- `--plan` cannot be combined with `--fix` or `--apply`.\n- Project diagnostics include built-in probes (configuration surface, migration surface, runtime health surface) and optional custom probe/adapter contracts.\n\n### Doctor project JSON fields (AI/automation)\n\n`npx rapidkit doctor project --json` includes project-scoped evidence fields for extension and automation consumers:\n\n- `scope` (`project`)\n- `contract` (doctor evidence contract + scoring policy version)\n- `project` (framework/runtime metadata, canonical `frameworkKey` and `importStack`, issues, fix commands, probes)\n- `summary.scopeProvenance`\n- `driftDelta`\n- `scoreBreakdown`\n\n### Doctor evidence schema compatibility\n\nDoctor persisted evidence now carries explicit schema tags:\n\n- Workspace evidence: `schemaVersion = doctor-workspace-evidence-v1`, `evidenceType = workspace`\n- Project evidence: `schemaVersion = doctor-project-evidence-v1`, `evidenceType = project`\n- Workspace scan cache: `schemaVersion = doctor-workspace-cache-v1`\n\nCompatibility policy for automation consumers:\n\n- Legacy doctor evidence without `schemaVersion` is still accepted.\n- Unknown or incompatible doctor evidence schema versions are treated as invalid evidence (safe fallback, no crash).\n- `readiness` and `workspace share` use the same compatibility validation path, so behavior is consistent across CLI surfaces.\n\n### Project lifecycle\n\n```bash\nnpx rapidkit create project \u003ckit\u003e \u003cname\u003e [--yes] [--skip-install]\nnpx rapidkit project commands [--json]\nnpx rapidkit commands --scope project [--json]\nnpx rapidkit init\nnpx rapidkit dev\nnpx rapidkit test\nnpx rapidkit build\nnpx rapidkit start\n```\n\n`project commands` shows the effective command contract for the current project. Core-backed\nFastAPI/NestJS projects can use module commands such as `add` and `modules`. npm-backed Go, Spring\nBoot, and ASP.NET Core projects use runtime lifecycle commands and workspace governance while Core\nmodule mutation remains disabled. Imported observed projects are safe to inspect, share, and govern;\nthey expose help-level lifecycle support until a runtime adapter or project-local command mapping is\navailable.\n\n### Operations\n\n```bash\nnpx rapidkit cache \u003cstatus|clear|prune|repair\u003e\nnpx rapidkit mirror \u003cstatus|sync|verify|rotate\u003e\n```\n\n## Profiles\n\n- `minimal` — baseline workspace scaffolding\n- `java-only` — Java-focused workspace\n- `python-only` — Python-focused workspace\n- `node-only` — Node.js-focused workspace\n- `go-only` — Go-focused workspace\n- `polyglot` — Python + Node.js + Go + Java\n- `enterprise` — polyglot + governance-oriented checks\n\n## Policy Modes\n\n`mode` in `.rapidkit/policies.yml` controls enforcement:\n\n- `warn` (default): report violations, continue\n- `strict`: block incompatible operations\n\n## Workspace Policy Management\n\nManage `.rapidkit/policies.yml` via CLI (recommended, avoids manual YAML edits):\n\n```bash\nnpx rapidkit workspace policy show\nnpx rapidkit workspace policy set mode strict\nnpx rapidkit workspace policy set dependency_sharing_mode shared-runtime-caches\nnpx rapidkit workspace policy set rules.enforce_toolchain_lock true\n```\n\nSupported keys:\n\n- `mode`\n- `dependency_sharing_mode`\n- `rules.enforce_workspace_marker`\n- `rules.enforce_toolchain_lock`\n- `rules.disallow_untrusted_tool_sources`\n- `rules.enforce_compatibility_matrix`\n- `rules.require_mirror_lock_for_offline`\n\n## Setup and Warm Dependencies\n\n`setup \u003cruntime\u003e` validates toolchain and updates `.rapidkit/toolchain.lock`.\n\n`--warm-deps` adds optional dependency warm-up:\n\n- Node: lock/dependency warm-up in Node project directories\n- Go: module warm-up in Go project directories\n- Python: accepted, currently reports node/go scope\n\nWarm-deps behavior is non-fatal by design and reports explicit outcome (`completed` / `failed` / `skipped`).\n\n## VS Code Extension (Recommended)\n\nFor the best RapidKit experience, use the **Workspai VS Code extension** — it wraps this CLI with a\nvisual workspace explorer, AI-powered project creation, and context-aware coding assistance.\n\n### Why use the extension?\n\n| Feature                                | CLI | Extension        |\n| -------------------------------------- | --- | ---------------- |\n| Create workspace / project             | ✅  | ✅ Visual wizard |\n| AI Create — describe → scaffold        | ❌  | ✅               |\n| Project Assistant (context-aware Q\u0026A)  | ❌  | ✅               |\n| Workspace tree explorer                | ❌  | ✅               |\n| Module catalog browser                 | ❌  | ✅               |\n| One-click `rapidkit init / dev / test` | ❌  | ✅               |\n| Inline AI on every workspace item      | ❌  | ✅               |\n\n### Install\n\nSearch **Workspai** in the VS Code Extensions marketplace, or:\n\n```bash\next install rapidkit.rapidkit-vscode\n```\n\n\u003e The extension calls this CLI under the hood — both tools work together seamlessly.\n\u003e You do **not** need to install the CLI separately when using the extension.\n\n- Extension repository: https://github.com/rapidkitlabs/rapidkit-vscode\n\n## CI Workflow Ownership Map\n\nUse this map to avoid overlap when editing CI:\n\n- `.github/workflows/ci.yml`\n  - Build/lint/typecheck/tests/coverage matrix\n  - General quality and contract gates\n- `.github/workflows/workspace-e2e-matrix.yml`\n  - Cross-OS workspace lifecycle smoke\n  - Setup (`--warm-deps`) + cache/mirror ops\n  - Chaos/non-fatal warm-deps behavior (Ubuntu job)\n- `.github/workflows/windows-bridge-e2e.yml`\n  - Native Windows bridge/lifecycle checks\n- `.github/workflows/e2e-smoke.yml`\n  - Focused bridge regression smoke (fast, narrow scope)\n- `.github/workflows/security.yml`\n  - Security scanning and policy checks\n\n## Documentation Index\n\nPrimary docs live under `docs/`:\n\n- General docs index: [docs/README.md](docs/README.md)\n- Setup details: [docs/SETUP.md](docs/SETUP.md)\n- Doctor command: [docs/doctor-command.md](docs/doctor-command.md)\n- Workspace marker spec: [docs/WORKSPACE_MARKER_SPEC.md](docs/WORKSPACE_MARKER_SPEC.md)\n- Config file guide: [docs/config-file-guide.md](docs/config-file-guide.md)\n- Package manager policy: [docs/PACKAGE_MANAGER_POLICY.md](docs/PACKAGE_MANAGER_POLICY.md)\n- Security: [docs/SECURITY.md](docs/SECURITY.md)\n- Development: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)\n\n## Workspace Run — Polyglot Fleet Orchestration\n\n`workspace run` is an enterprise-grade orchestrator for executing CI-safe stages (init, test, build, start) across polyglot monorepos. It supports 20+ frameworks across 9 runtimes with professional-grade features.\n\n### Quick Start\n\n```bash\n# Test all discovered projects in parallel\nnpx rapidkit workspace run test --parallel\n\n# Test only affected projects since last commit\nnpx rapidkit workspace run test --affected --since HEAD~1\n\n# Test affected + downstream dependents from workspace.contract.json\nnpx rapidkit workspace run test --affected --blast-radius\n\n# Build specific projects with custom stages (if defined in .rapidkit/context.json)\nnpx rapidkit workspace run build --json --max-workers 8\n```\n\n`--blast-radius` uses `.rapidkit/workspace.contract.json` when available. It expands direct\n`dependsOn` relationships and event relationships where one project `publishes` an event and another\nproject `consumes` it. Legacy `.rapidkit/workspace-dependency-graph.json` remains supported as a fallback.\n\n### Supported Runtimes \u0026 Frameworks\n\n| Runtime    | Frameworks                     | Status   |\n| ---------- | ------------------------------ | -------- |\n| **Node**   | NestJS, Express, Next.js, Nuxt | Built-in |\n| **Go**     | Fiber, Gin, Echo, Chi          | Built-in |\n| **Java**   | Spring Boot, Quarkus, Gradle   | Built-in |\n| **Python** | FastAPI, Django, Flask, Poetry | Built-in |\n| **PHP**    | Laravel, Symfony, Slim         | Observed |\n| **Rust**   | Actix, Axum, Rocket, Tokio     | Observed |\n| **.NET**   | ASP.NET Core, Entity Framework | Built-in |\n| **Elixir** | Phoenix, Umbrella Projects     | Observed |\n| **Ruby**   | Rails, Sinatra, RSpec          | Observed |\n\nFor the public scaffold/import/lifecycle/module support contract, see\n[docs/contracts/RUNTIME_SUPPORT_MATRIX.md](docs/contracts/RUNTIME_SUPPORT_MATRIX.md).\n\n### Enterprise Features\n\n1. **Command Overrides** — Customize stage commands per project via `.rapidkit/context.json`\n2. **Multi-Framework Projects** — Support full-stack apps (e.g., Laravel + Vue in same directory)\n3. **Error Diagnostics** — Categorize errors (setup vs test failure vs runtime) for better CI feedback\n4. **Preflight Validation** — Validate command availability before execution\n5. **Health Checks** — Verify services are ready (port listening, HTTP health, log grep)\n6. **Custom Stages** — Define project-specific stages (lint, docs, bench, etc.)\n7. **Stage Dependencies** — Define execution order and prerequisites\n8. **Environment Variants** — dev/staging/prod command variants\n9. **Caching** — Skip re-runs of completed stages\n10. **Composite Steps** — Multi-step build logic\n\nFor deeper enterprise deployment and governance details, see:\n\n- [docs/README.md](docs/README.md)\n- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n\n### Configuration Example\n\n```json\n{\n  \".rapidkit/context.json\": {\n    \"runtime\": \"php\",\n    \"framework\": \"Laravel\",\n    \"commands\": {\n      \"test\": \"php artisan test --parallel=4\",\n      \"build\": \"php artisan config:cache \u0026\u0026 php artisan route:cache\",\n      \"lint\": \"php bin/phpstan analyse --level=8\"\n    },\n    \"environment\": \"dev\"\n  }\n}\n```\n\n### Output \u0026 Reporting\n\n```bash\n# JSON report for CI integration\nnpx rapidkit workspace run test --json \u003e test-results.json\n\ncat test-results.json | jq '.projects[] | {path, status, errorCategory}'\n# Output:\n# {\n#   \"path\": \"services/api\",\n#   \"status\": \"failed\",\n#   \"errorCategory\": \"setup\"  # setup | test-failure | runtime | dependency | timeout\n# }\n```\n\n## Command Semantics\n\nRapidKit has two workspace-level execution surfaces, and three equivalent full-init aliases at workspace root:\n\n| Command                                                            | Intent                                                                            | Scope                                     |\n| ------------------------------------------------------------------ | --------------------------------------------------------------------------------- | ----------------------------------------- |\n| `init` (at workspace root), `workspace init`, `workspace run init` | Mirrored full-init orchestration (workspace-profile deps + selected project init) | Workspace root + discovered project fleet |\n| `workspace run \u003ctest\\|build\\|start\u003e`                               | Fleet stage execution — run a CI-safe stage across discovered projects            | Selected project fleet                    |\n| `init`, `test`, `build`, `start`, `dev` (inside project directory) | Project primitive — run one stage in the current project only                     | Single project                            |\n\n**Key design rule:** at workspace root, these are equivalent aliases: `npx rapidkit init`, `npx rapidkit workspace init`, `npx rapidkit workspace run init`.\nInside a project directory, `npx rapidkit init` remains a project-scoped primitive.\n\n`dev` is intentionally excluded from `workspace run` — it is a long-running local process, not a CI batch stage.\n\nDetailed enterprise semantic specs and governance evidence contracts are intentionally excluded from OSS docs.\n\n## Development\n\n```bash\nnpm ci\nnpm run build\nnpm run test\nnpm run lint\nnpm run typecheck\n```\n\nLink local CLI globally for manual testing:\n\n```bash\nnpm run install:local\nnpx rapidkit --version\n```\n\n\u003e Packaging note: `npm run prepack` validates the committed `data/modules-embeddings.json`\n\u003e artifact before `npm pack` / `npm publish`. This keeps packaging deterministic and avoids\n\u003e registry or `npx` downloads during release.\n\u003e\n\u003e If you need to refresh the local test embeddings manually, run:\n\u003e\n\u003e ```bash\n\u003e npm run generate-embeddings\n\u003e ```\n\n## Troubleshooting\n\n### Quick fixes matrix\n\n| Problem                        | Quick check                                        | Fix                                                                     |\n| ------------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------- |\n| `python3` not found            | `python3 --version`                                | Install Python 3.10+ and re-run `npx rapidkit create workspace ...`     |\n| `setup --warm-deps` skipped    | Check for `package.json` / `go.mod` in current dir | Run from the target project directory                                   |\n| strict policy blocks command   | Review `.rapidkit/policies.yml`                    | Set policy intentionally via `npx rapidkit workspace policy set ...`    |\n| doctor output seems stale      | Check report timestamp in `.rapidkit/reports/`     | Re-run `npx rapidkit doctor workspace` or `npx rapidkit doctor project` |\n| affected run scope seems wrong | Verify git ref                                     | Use `--since \u003cref\u003e` explicitly                                          |\n\n- If setup output looks stale, run `npx rapidkit setup \u003cruntime\u003e` again to refresh `.rapidkit/toolchain.lock`.\n- If dependency warm-up is skipped, verify you are inside the corresponding project directory (`package.json` for Node, `go.mod` for Go).\n- For strict-mode blocks, inspect `.rapidkit/policies.yml` and workspace profile in `.rapidkit/workspace.json`.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapidkitlabs%2Frapidkit-npm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frapidkitlabs%2Frapidkit-npm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapidkitlabs%2Frapidkit-npm/lists"}