rapidkit 0.32.1 → 0.33.0

package/README.md

@@ -20,6 +20,7 @@ The official RapidKit npm CLI for creating and operating workspaces and projects
 - Multi-runtime support across Python, Node.js, Java, Go, and .NET
 - Policy enforcement with `warn` / `strict` modes
 - Cache and mirror lifecycle commands for stable environments
+- Contract-driven workspace infra sidecar (`infra plan|up|down|status`) for local Postgres, Redis, mail, and related dev dependencies
 
 ## Workspace-First Architecture
 
@@ -149,6 +150,7 @@ npx rapidkit doctor
 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 foundation ensure [--force] [--json]
 npx rapidkit workspace share [--output <file>] [--include-paths] [--no-doctor]
 npx rapidkit workspace contract init [--force] [--json]
 npx rapidkit workspace contract inspect [--json]
@@ -170,6 +172,10 @@ npx rapidkit project restore <archive> [--name <project-name>] [--force] [--dry-
 npx rapidkit project delete <name> [--permanent --confirm <name>] [--dry-run] [--json]
 npx rapidkit workspace init # Full-init alias (same behavior as root init/workspace run init at workspace root)
 npx rapidkit workspace run <init|test|build|start> [--affected] [--blast-radius] [--since <ref>] [--parallel] [--max-workers <n>] [--strict] [--json]
+npx rapidkit infra plan [--workspace <path>] [--json] [--dry-run] [--verbose]
+npx rapidkit infra up [--workspace <path>] [--no-plan] [--build]
+npx rapidkit infra down [--workspace <path>] [--volumes]
+npx rapidkit infra status [--workspace <path>] [--json] [--strict]
 ```
 
 ### Project import into workspace
@@ -313,13 +319,46 @@ and `workspace archive doctor` when you want human-readable readiness/security g
 imports the workspace. Use `--include-env` only for trusted internal handoffs when you intentionally need
 environment files inside the archive.
 
+### Workspace infrastructure (sidecar)
+
+Use `infra` when a workspace needs local dev dependencies (PostgreSQL, Redis, Mailpit, MinIO, and
+related services) without replacing the workspace's own `docker-compose.yml`.
+
+Discovery is contract-first and runtime-agnostic:
+
+- Installed Core module slugs from each project's `registry.json`
+- Infra-related variables from each project's `.env.example`
+- Optional env declarations from `.rapidkit/workspace.contract.json`
+- Manual overrides in `.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 are written beside the workspace (sidecar strategy):
+
+- `.rapidkit/infra/docker-compose.yml` — generated Docker Compose stack
+- `.rapidkit/reports/infra-plan.json` — machine-readable plan and discovery evidence
+- `.rapidkit/infra/.env.example` — connection env preview for local `.env` files
+
+`infra up` refreshes the plan by default. Use `--no-plan` to start from the last saved plan only.
+Connection defaults prefer project `.env.example` values (for example `RAPIDKIT_DB_POSTGRES_URL`).
+
+This command family is wrapper-owned, does not mutate Core modules, and works for polyglot workspaces
+(FastAPI, NestJS, Go, Spring Boot, .NET, and imported projects) as long as projects expose
+`.rapidkit/project.json` and env/override signals.
+
 ### Command ownership
 
 RapidKit keeps the wrapper boundary explicit so users know which layer owns each action.
 
 | Command family                                     | Owner                  | Notes                                                                                                                           |
 | -------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `create workspace`, `workspace`, `cache`, `mirror` | RapidKit wrapper       | Platform-level orchestration                                                                                                    |
+| `create workspace`, `workspace`, `cache`, `mirror`, `infra` | RapidKit wrapper       | Platform-level orchestration                                                                                                    |
 | `init`                                             | Wrapper orchestrated   | Project init in project dirs; full-init alias at workspace root                                                                 |
 | `dev`, `test`, `build`, `start`                    | Runtime aware          | Delegates to the active project/runtime when available                                                                          |
 | `readiness`                                        | Wrapper release gate   | Generates release-readiness evidence (`--json` for CI, `--strict` for fail-fast)                                                |
@@ -331,6 +370,7 @@ RapidKit keeps the wrapper boundary explicit so users know which layer owns each
 | `doctor workspace`                                 | Workspace health       | Full workspace scan with project-level details and fixes                                                                        |
 | `doctor project`                                   | Project health         | Current project (or nearest parent) diagnostics with project evidence and scoped fixes                                          |
 | `workspace run`                                    | Workspace orchestrator | Stage execution across discovered projects with optional affected-only, blast-radius expansion, and policy-gated pre-checks     |
+| `infra`                                            | Workspace sidecar      | Contract-driven local infra discovery, compose generation, and Docker lifecycle (`plan`, `up`, `down`, `status`)                  |
 
 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/`.
@@ -424,8 +464,11 @@ available.
 ```bash
 npx rapidkit cache <status|clear|prune|repair>
 npx rapidkit mirror <status|sync|verify|rotate>
+npx rapidkit infra <plan|up|down|status>
 ```
 
+See [Workspace infrastructure (sidecar)](#workspace-infrastructure-sidecar) for discovery rules and generated artifacts.
+
 ## Profiles
 
 - `minimal` — baseline workspace scaffolding
@@ -663,12 +706,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`.
+> Packaging note: `npm run prepack` validates the committed `data/modules-embeddings.json`
+> artifact before `npm pack` / `npm publish`. This keeps packaging deterministic and avoids
+> registry or `npx` downloads during release.
 >
 > If you need to refresh the local test embeddings manually, run:
 >
 > ```bash
-> npm run test:prepare-embeddings
+> npm run generate-embeddings
 > ```
 
 ## Troubleshooting

package/contracts/backend-import-stack-parity.snapshot.json

@@ -0,0 +1,37 @@
+{
+    "schemaVersion": "backend-import-stack-parity-v1",
+    "frameworkToStack": {
+        "fastapi": "fastapi",
+        "django": "django",
+        "flask": "flask",
+        "python": "unknown",
+        "nestjs": "nestjs",
+        "express": "express",
+        "fastify": "unknown",
+        "koa": "koa",
+        "node": "unknown",
+        "gofiber": "go",
+        "gogin": "go",
+        "echo": "go",
+        "go": "go",
+        "springboot": "springboot",
+        "java": "unknown",
+        "rails": "rails",
+        "ruby": "unknown",
+        "dotnet": "dotnet",
+        "unknown": "unknown"
+    },
+    "runtimeToStack": {
+        "python": "unknown",
+        "node": "unknown",
+        "nodejs": "unknown",
+        "typescript": "unknown",
+        "go": "go",
+        "golang": "go",
+        "java": "unknown",
+        "ruby": "unknown",
+        "dotnet": "dotnet",
+        "csharp": "dotnet",
+        "unknown": "unknown"
+    }
+}

package/contracts/infra-stack.v1.json

@@ -0,0 +1,162 @@
+{
+  "schemaVersion": "rapidkit.infra-stack.v1",
+  "description": "Canonical workspace infrastructure service catalog and module/env resolution rules.",
+  "futureProfiles": ["frontend-dev", "edge-proxy"],
+  "services": {
+    "postgres": {
+      "displayName": "PostgreSQL",
+      "category": "database",
+      "image": "postgres:16-alpine",
+      "ports": [{ "name": "sql", "host": 5432, "container": 5432 }],
+      "env": {
+        "POSTGRES_USER": "rapidkit",
+        "POSTGRES_PASSWORD": "rapidkit",
+        "POSTGRES_DB": "rapidkit"
+      },
+      "volumes": ["postgres_data:/var/lib/postgresql/data"],
+      "healthcheck": {
+        "test": ["CMD-SHELL", "pg_isready -U rapidkit -d rapidkit"],
+        "interval": "10s",
+        "timeout": "5s",
+        "retries": 5
+      },
+      "connectionEnv": {
+        "DATABASE_URL": "postgresql://rapidkit:rapidkit@localhost:5432/rapidkit",
+        "RAPIDKIT_DB_POSTGRES_URL": "postgresql://rapidkit:rapidkit@localhost:5432/rapidkit"
+      }
+    },
+    "redis": {
+      "displayName": "Redis",
+      "category": "cache",
+      "image": "redis:7-alpine",
+      "ports": [{ "name": "redis", "host": 6379, "container": 6379 }],
+      "command": ["redis-server", "--appendonly", "yes"],
+      "volumes": ["redis_data:/data"],
+      "healthcheck": {
+        "test": ["CMD", "redis-cli", "ping"],
+        "interval": "10s",
+        "timeout": "3s",
+        "retries": 5
+      },
+      "connectionEnv": {
+        "REDIS_URL": "redis://localhost:6379/0",
+        "CELERY_BROKER_URL": "redis://localhost:6379/0",
+        "CELERY_RESULT_BACKEND": "redis://localhost:6379/1"
+      }
+    },
+    "mongo": {
+      "displayName": "MongoDB",
+      "category": "database",
+      "image": "mongo:7",
+      "ports": [{ "name": "mongo", "host": 27017, "container": 27017 }],
+      "volumes": ["mongo_data:/data/db"],
+      "connectionEnv": {
+        "MONGODB_URI": "mongodb://localhost:27017/rapidkit",
+        "MONGO_URL": "mongodb://localhost:27017/rapidkit"
+      }
+    },
+    "mysql": {
+      "displayName": "MySQL",
+      "category": "database",
+      "image": "mysql:8.4",
+      "ports": [{ "name": "mysql", "host": 3306, "container": 3306 }],
+      "env": {
+        "MYSQL_ROOT_PASSWORD": "rapidkit",
+        "MYSQL_DATABASE": "rapidkit",
+        "MYSQL_USER": "rapidkit",
+        "MYSQL_PASSWORD": "rapidkit"
+      },
+      "healthcheck": {
+        "test": ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-urapidkit", "-prapidkit"],
+        "interval": "10s",
+        "timeout": "5s",
+        "retries": 5
+      },
+      "connectionEnv": {
+        "DATABASE_URL": "mysql://rapidkit:rapidkit@localhost:3306/rapidkit"
+      }
+    },
+    "rabbitmq": {
+      "displayName": "RabbitMQ",
+      "category": "queue",
+      "image": "rabbitmq:3-management-alpine",
+      "ports": [
+        { "name": "amqp", "host": 5672, "container": 5672 },
+        { "name": "management", "host": 15672, "container": 15672 }
+      ],
+      "healthcheck": {
+        "test": ["CMD", "rabbitmq-diagnostics", "-q", "ping"],
+        "interval": "15s",
+        "timeout": "10s",
+        "retries": 5
+      },
+      "connectionEnv": {
+        "CELERY_BROKER_URL": "amqp://guest:guest@localhost:5672//",
+        "RABBITMQ_URL": "amqp://guest:guest@localhost:5672//"
+      }
+    },
+    "mailpit": {
+      "displayName": "Mailpit (SMTP dev)",
+      "category": "communication",
+      "image": "axllent/mailpit:latest",
+      "ports": [
+        { "name": "smtp", "host": 1025, "container": 1025 },
+        { "name": "ui", "host": 8025, "container": 8025 }
+      ],
+      "connectionEnv": {
+        "SMTP_HOST": "localhost",
+        "SMTP_PORT": "1025",
+        "MAIL_URL": "smtp://localhost:1025"
+      }
+    },
+    "minio": {
+      "displayName": "MinIO (S3-compatible)",
+      "category": "storage",
+      "image": "minio/minio:latest",
+      "ports": [
+        { "name": "s3", "host": 9000, "container": 9000 },
+        { "name": "console", "host": 9001, "container": 9001 }
+      ],
+      "command": ["server", "/data", "--console-address", ":9001"],
+      "env": {
+        "MINIO_ROOT_USER": "rapidkit",
+        "MINIO_ROOT_PASSWORD": "rapidkit-dev"
+      },
+      "volumes": ["minio_data:/data"],
+      "connectionEnv": {
+        "AWS_S3_ENDPOINT": "http://localhost:9000",
+        "S3_ENDPOINT_URL": "http://localhost:9000"
+      }
+    }
+  },
+  "moduleMappings": {
+    "free/database/db_postgres": ["postgres"],
+    "free/database/db_mongo": ["mongo"],
+    "free/database/db_mysql": ["mysql"],
+    "free/cache/redis": ["redis"],
+    "free/tasks/celery": ["redis"],
+    "free/tasks/workflow_engine": ["postgres", "redis"],
+    "free/tasks/queue_platform": ["redis"],
+    "free/tasks/event_bus": ["redis"],
+    "free/communication/webhook_platform": ["postgres", "redis"],
+    "free/communication/email": ["mailpit"],
+    "free/business/storage": ["minio"],
+    "free/security/audit_policy": ["postgres"],
+    "free/business/approval_engine": ["postgres", "redis"]
+  },
+  "envVarMappings": {
+    "DATABASE_URL": ["postgres"],
+    "RAPIDKIT_DB_POSTGRES_URL": ["postgres"],
+    "REDIS_URL": ["redis"],
+    "CELERY_BROKER_URL": ["redis"],
+    "CELERY_RESULT_BACKEND": ["redis"],
+    "MONGODB_URI": ["mongo"],
+    "MONGO_URL": ["mongo"],
+    "MYSQL_URL": ["mysql"],
+    "RABBITMQ_URL": ["rabbitmq"],
+    "SMTP_HOST": ["mailpit"],
+    "MAIL_URL": ["mailpit"],
+    "AWS_S3_ENDPOINT": ["minio"],
+    "S3_ENDPOINT_URL": ["minio"]
+  }
+}

package/contracts/module-layout.v1.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": "rapidkit.module-layout.v1",
+  "canonicalModuleRoot": "src/modules/free",
+  "pathPattern": "src/modules/free/{category}/{module}",
+  "slugPattern": "free/{category}/{module}",
+  "frameworks": {
+    "fastapi": {
+      "moduleCommands": true,
+      "injectAnchors": [
+        "src/routing/__init__.py",
+        "src/modules/__init__.py"
+      ],
+      "moduleMarkerFiles": ["__init__.py"]
+    },
+    "nestjs": {
+      "moduleCommands": true,
+      "injectAnchors": [
+        "src/app.module.ts",
+        "src/modules/index.ts"
+      ],
+      "moduleMarkerFiles": ["index.ts", "module.ts"]
+    }
+  },
+  "unsupportedModuleFrameworks": ["go", "springboot", "dotnet"]
+}

package/contracts/runtime-command-surface.v1.json

@@ -0,0 +1,152 @@
+{
+  "schemaVersion": "rapidkit-runtime-command-surface-v1",
+  "lifecycleCommands": ["init", "dev", "start", "build", "test", "lint", "format", "help"],
+  "moduleMutationCommands": [
+    "add",
+    "modules",
+    "upgrade",
+    "diff",
+    "merge",
+    "reconcile",
+    "rollback",
+    "uninstall",
+    "checkpoint",
+    "snapshot",
+    "optimize"
+  ],
+  "globalCommands": ["create", "list", "info", "frameworks", "license"],
+  "universalCommands": ["version", "commands", "doctor", "project"],
+  "moduleSuggestionFrameworks": ["fastapi", "nestjs"],
+  "moduleUnsupportedFrameworks": ["go", "springboot", "dotnet"],
+  "scaffoldKits": [
+    "fastapi.standard",
+    "fastapi.ddd",
+    "nestjs.standard",
+    "gofiber.standard",
+    "gogin.standard",
+    "springboot.standard",
+    "dotnet.webapi.clean"
+  ],
+  "runtimeMatrix": {
+    "python": {
+      "tier": "first-class",
+      "scaffold": true,
+      "import": true,
+      "moduleCommands": true,
+      "doctor": "full",
+      "lifecycleCommands": ["init", "dev", "start", "build", "test", "lint", "format", "help"]
+    },
+    "node": {
+      "tier": "first-class",
+      "scaffold": true,
+      "import": true,
+      "moduleCommands": true,
+      "doctor": "full",
+      "lifecycleCommands": ["init", "dev", "start", "build", "test", "lint", "format", "help"]
+    },
+    "go": {
+      "tier": "extended",
+      "scaffold": true,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "readiness",
+      "lifecycleCommands": ["init", "dev", "start", "build", "test", "lint", "format", "help"]
+    },
+    "java": {
+      "tier": "extended",
+      "scaffold": true,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "readiness",
+      "lifecycleCommands": ["init", "dev", "start", "build", "test", "lint", "format", "help"]
+    },
+    "dotnet": {
+      "tier": "extended",
+      "scaffold": true,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "readiness",
+      "lifecycleCommands": ["init", "dev", "start", "build", "test", "lint", "format", "help"]
+    },
+    "php": {
+      "tier": "observed",
+      "scaffold": false,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "observed",
+      "lifecycleCommands": ["help"]
+    },
+    "ruby": {
+      "tier": "observed",
+      "scaffold": false,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "observed",
+      "lifecycleCommands": ["help"]
+    },
+    "rust": {
+      "tier": "observed",
+      "scaffold": false,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "observed",
+      "lifecycleCommands": ["help"]
+    },
+    "elixir": {
+      "tier": "observed",
+      "scaffold": false,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "observed",
+      "lifecycleCommands": ["help"]
+    },
+    "clojure": {
+      "tier": "observed",
+      "scaffold": false,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "observed",
+      "lifecycleCommands": ["help"]
+    },
+    "scala": {
+      "tier": "observed",
+      "scaffold": false,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "observed",
+      "lifecycleCommands": ["help"]
+    },
+    "kotlin": {
+      "tier": "observed",
+      "scaffold": false,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "observed",
+      "lifecycleCommands": ["help"]
+    },
+    "deno": {
+      "tier": "observed",
+      "scaffold": false,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "observed",
+      "lifecycleCommands": ["help"]
+    },
+    "bun": {
+      "tier": "observed",
+      "scaffold": false,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "observed",
+      "lifecycleCommands": ["help"]
+    },
+    "unknown": {
+      "tier": "observed",
+      "scaffold": false,
+      "import": true,
+      "moduleCommands": false,
+      "doctor": "observed",
+      "lifecycleCommands": ["help"]
+    }
+  }
+}