@soapjs/cli 1.0.0

package/docs/cli/add-route.md

@@ -0,0 +1,79 @@
+# `soap add route`
+
+Add a route to an existing resource.
+
+```bash
+soap add route invoice approve --method post --path approve --auth jwt --zone public
+soap add route invoice approve --method post --path approve --auth jwt --policy custom:approver
+soap add route invoice approve -i
+soap add route -i
+```
+
+## Interactive Flow
+
+```bash
+soap add route -i
+```
+
+When arguments are omitted, interactive mode can select the resource from `.soap/registry.json` and ask for the route name.
+
+Prompts cover:
+
+- resource
+- route name
+- HTTP method
+- route path
+- API zone from project zones
+- route auth from enabled project auth
+- target: direct controller, use case, CQRS command, or CQRS query
+- Bruno refresh when Bruno is enabled
+
+CQRS command and query targets are only offered when the project architecture is `cqrs`.
+
+## Non-Interactive Use
+
+Without `-i`, both resource and route name are required:
+
+```bash
+soap add route invoice approve --method post --path approve
+```
+
+Target options are mutually exclusive:
+
+```bash
+--use-case approve-invoice
+--command approve-invoice
+--query find-invoices
+```
+
+Use only one target option.
+
+## Auth Policies
+
+Attach a policy to a protected route:
+
+```bash
+soap add route invoice approve --method post --path approve --auth jwt --policy roles:admin,editor
+soap add route invoice approve --method post --path approve --auth api-key --policy admin
+soap add route invoice approve --method post --path approve --auth jwt --policy custom:approver
+```
+
+Supported policies:
+
+- `admin` -> `@AdminOnly('<strategy>')`
+- `roles:a,b` -> `@Auth('<strategy>', { roles: ['a', 'b'] })`
+- `custom:name` -> `@Auth('<strategy>', { policy: 'name' })`
+
+Policies require route auth. `--auth none --policy ...` fails before writing files.
+
+## Contracts
+
+When the project has `contracts: ["zod"]`, generated route contracts parse input through Zod schemas.
+
+## Bruno
+
+Refresh Bruno after adding a route:
+
+```bash
+soap add route invoice approve --method post --path approve --bruno
+```

package/docs/cli/bruno.md

@@ -0,0 +1,58 @@
+# Bruno
+
+Bruno generation is driven by `.soap/registry.json`.
+
+Enable Bruno at project creation:
+
+```bash
+soap create users-api --api-client bruno --skip-install
+```
+
+Enable it later:
+
+```bash
+soap update config --add-api-client bruno
+soap generate bruno
+```
+
+## Interactive Generation
+
+```bash
+soap generate bruno -i
+```
+
+Interactive mode analyzes the current collection before writing:
+
+- detected routes
+- existing Bruno files
+- missing Bruno files
+- modified generated Bruno files
+
+Then choose:
+
+- generate missing only
+- regenerate all unmodified generated files
+- generate E2E flow
+- abort
+
+Manual `.bru` edits are detected from the registry hash and are skipped unless you use `--force`.
+
+## E2E Flow
+
+```bash
+soap generate bruno --e2e
+soap generate bruno -i
+```
+
+E2E files are generated for resources with complete CRUD routes.
+
+## Overwrite Behavior
+
+```bash
+soap generate bruno --force
+soap generate bruno --write-new
+soap generate bruno --on-conflict skip
+```
+
+Default behavior skips modified generated files.
+

package/docs/cli/create.md

@@ -0,0 +1,73 @@
+# `soap create`
+
+Create a new SoapJS project.
+
+Generated projects require Node.js `>=24.17.0` (Node 24 LTS or newer).
+The generator writes `.nvmrc` with `24.17.0` so `nvm use` selects the supported runtime.
+
+```bash
+soap create users-api --skip-install
+soap create users-api --install
+soap create users-api --git-init --skip-install
+soap create users-api -i
+soap create users-api --preset express-postgres-api --skip-install
+soap create users-api --db mysql --db sqlite --skip-install
+```
+
+## Interactive Flow
+
+```bash
+soap create users-api -i
+```
+
+Prompts cover the supported MVP capabilities:
+
+- framework
+- architecture
+- databases
+- auth
+- messaging
+- realtime
+- telemetry
+- OpenAPI docs
+- contracts
+- Bruno API client
+- API zones
+- package manager
+- dependency install intent
+- git init intent
+
+Before writing files, interactive mode prints a project summary and asks for confirmation.
+
+Use `--yes` to skip the final confirmation:
+
+```bash
+soap create users-api -i --yes
+```
+
+## Presets
+
+Available presets:
+
+- `express-mongo-api`
+- `express-postgres-api`
+- `express-cqrs-kafka-api`
+- `express-full-demo`
+
+Examples:
+
+```bash
+soap create users-api --preset express-mongo-api --skip-install
+soap create users-api -i --preset express-full-demo
+```
+
+In interactive mode, preset values become prompt defaults. Explicit CLI flags still override prompt answers and preset defaults.
+
+## Notes
+
+- Only `express` is currently supported.
+- `--contracts zod` enables generated contracts backed by Zod.
+- Database capabilities include `mongo`, `postgres`, `mysql`, `sqlite`, and `redis`. Resource repositories are generated for Mongo and SQL adapters; Redis is infrastructure-only for now.
+- `--install` runs the selected package manager after files are written. `--skip-install` always skips installation.
+- `--git-init` runs `git init` after files are written. It does not commit or push.
+- `--dry-run` prints the planned file count and planned writes.

package/docs/cli/index.md

@@ -0,0 +1,92 @@
+# SoapJS CLI Reference
+
+This reference lists the main CLI commands and links to task-focused docs.
+
+## Project Creation
+
+- [`soap create`](create.md) creates a new SoapJS service.
+- Use `--install` to install dependencies after generation.
+- Use `--git-init` to initialize a local git repository. The CLI does not commit or push.
+- Use `-i` for guided creation.
+
+```bash
+soap create users-api --db postgres --auth jwt --docs openapi --api-client bruno --install
+soap create users-api -i
+```
+
+## Add Code
+
+- [`soap add resource`](add-resource.md) adds a resource, optional CRUD routes, storage, contracts, tests, and Bruno requests.
+- [`soap add route`](add-route.md) adds a custom route to an existing resource.
+
+```bash
+soap add resource invoice --crud --db postgres --auth jwt --zone private
+soap add route invoice approve --method post --path :id/approve --auth jwt --policy custom:approver
+```
+
+Additional component commands:
+
+```bash
+soap add entity invoice --feature invoice
+soap add use-case approve-invoice --feature invoice
+soap add repository invoice --feature invoice --db postgres
+soap add command approve-invoice --feature invoice
+soap add query find-invoices --feature invoice
+soap add event invoice-approved --feature invoice
+soap add socket invoice-updates --feature invoice --auth jwt
+```
+
+## Generate API Artifacts
+
+- [`soap generate bruno`](bruno.md) refreshes Bruno API requests from the route registry.
+- `soap generate openapi` fetches the running app OpenAPI spec.
+
+```bash
+soap generate bruno
+soap generate bruno --e2e
+soap generate openapi --output openapi.json
+```
+
+## Update Project Capabilities
+
+`soap update config` adds infrastructure after project creation.
+
+```bash
+soap update config --add-db mysql
+soap update config --add-auth api-key
+soap update config --add-docs openapi
+soap update config --add-contracts zod
+soap update config --add-api-client bruno
+soap update config --add-realtime ws
+```
+
+Updates are add-only. They do not remove existing capabilities.
+
+## Validate And Inspect
+
+```bash
+soap info
+soap doctor
+soap check routes
+```
+
+- `info` prints project metadata.
+- `doctor` validates the local `.soap` project structure.
+- `check routes` validates route registry consistency, auth, zones, contracts, and Bruno files.
+
+## Remove Generated Code
+
+- [`soap remove`](remove.md) safely removes generated routes or resources tracked in `.soap/registry.json`.
+
+```bash
+soap remove route invoice create
+soap remove resource invoice
+soap remove resource invoice -i
+```
+
+## Interactive Mode
+
+See [`interactive-mode.md`](interactive-mode.md).
+
+Interactive mode resolves inputs only. It uses the same deterministic planners and file writer as flag-based commands.
+

package/docs/cli/interactive-mode.md

@@ -0,0 +1,61 @@
+# Interactive Mode
+
+Interactive mode is a guided input layer for the same deterministic generators used by the flag-based CLI.
+
+Use `-i` or `--interactive` on supported commands:
+
+```bash
+soap create users-api -i
+soap add resource invoice -i
+soap add route invoice approve -i
+soap generate bruno -i
+soap remove route invoice approve -i
+soap remove resource invoice -i
+```
+
+Interactive mode requires a TTY. In CI and scripts, use explicit flags instead.
+
+## Supported Commands
+
+- `soap create <name> -i`
+- `soap add resource <name> -i`
+- `soap add route [resource] [name] -i`
+- `soap generate bruno -i`
+- `soap remove route <resource> <route> -i`
+- `soap remove resource <resource> -i`
+
+## When To Use It
+
+Use interactive mode when exploring project capabilities or when adding resources manually during local development. Use explicit flags in scripts, CI, project templates, and documentation examples that should be reproducible.
+
+The scenario guides can be followed either with flags or with `-i`:
+
+- [Regular CRUD API](../guides/regular-api.md)
+- [CQRS, events, Kafka, and WebSockets](../guides/cqrs-events-realtime.md)
+- [Auth and route policies](../guides/auth.md)
+- [Storage capabilities](../guides/storage.md)
+- [Quality, tests, and safe changes](../guides/quality-and-safety.md)
+
+## Safety Rules
+
+- Prompts only resolve command options; planners and writers stay deterministic.
+- The CLI reads `.soap` before project-aware prompts.
+- Interactive choices are limited to capabilities enabled in `.soap/project.json`.
+- Modified generated files are not overwritten or deleted unless you use `--force` or `--on-conflict overwrite`.
+- `--yes` skips final confirmation prompts where supported.
+- `--dry-run` prints planned writes/deletes without changing files.
+
+## Conflict Policy
+
+Most write commands support:
+
+```bash
+--on-conflict skip
+--on-conflict overwrite
+--on-conflict new
+--on-conflict abort
+```
+
+`ask` is reserved by the shared policy but per-file interactive conflict resolution is not implemented yet.
+
+Remove commands do not support `new`, because deletion cannot be written as a `.new` file.

package/docs/cli/remove.md

@@ -0,0 +1,45 @@
+# `soap remove`
+
+Safely remove generated routes and resources.
+
+```bash
+soap remove route invoice create
+soap remove resource invoice
+```
+
+Remove commands only delete files tracked in `.soap/registry.json`.
+
+## Interactive Flow
+
+```bash
+soap remove route invoice create -i
+soap remove resource invoice -i
+```
+
+Interactive mode shows a preview before deletion:
+
+- tracked files to delete
+- modified tracked files
+- registry entries to remove
+
+Then it asks for confirmation.
+
+Use `--yes` to skip confirmation:
+
+```bash
+soap remove route invoice create -i --yes
+```
+
+## Modified Files
+
+Modified generated files are not deleted by default.
+
+Use `--force` or `--on-conflict overwrite` to delete modified generated files:
+
+```bash
+soap remove route invoice create --force
+soap remove resource invoice --on-conflict overwrite
+```
+
+`--dry-run` prints planned deletes and registry updates without changing files.
+

package/docs/guides/auth.md

@@ -0,0 +1,90 @@
+# Guide: Auth And Route Policies
+
+SoapJS CLI supports project-level auth capabilities and route-level policies.
+
+## Enable Auth
+
+At project creation:
+
+```bash
+soap create secure-api --auth jwt --auth api-key --skip-install
+```
+
+After project creation:
+
+```bash
+soap update config --add-auth jwt
+soap update config --add-auth api-key
+```
+
+Supported auth capabilities:
+
+- `jwt`
+- `api-key`
+- `local`
+
+For routes, `local` is normalized to `jwt`.
+
+## Add Protected CRUD Routes
+
+```bash
+soap add resource report --crud --auth jwt --zone private
+```
+
+Admin zone:
+
+```bash
+soap add resource audit-log --crud --auth jwt --zone admin
+```
+
+Public route:
+
+```bash
+soap add route report summary --method get --path summary --auth none --zone public
+```
+
+## Add Policies
+
+Policies require route auth.
+
+```bash
+soap add route report approve --method post --path approve --auth jwt --policy roles:admin,editor
+soap add route report purge --method delete --path purge --auth api-key --policy admin
+soap add route report export --method post --path export --auth jwt --policy custom:report-exporter
+```
+
+Generated decorators:
+
+- `admin` -> `@AdminOnly('<strategy>')`
+- `roles:a,b` -> `@Auth('<strategy>', { roles: ['a', 'b'] })`
+- `custom:name` -> `@Auth('<strategy>', { policy: 'name' })`
+
+Invalid:
+
+```bash
+soap add route report approve --auth none --policy admin
+```
+
+The CLI fails before writing files because policies require auth.
+
+## CRUD Route Matrix Policies
+
+Use matrix policies when each CRUD operation needs different auth.
+
+```bash
+soap add resource report --crud \
+  --crud-route list:get:/search:jwt:private:roles=admin,editor:bruno \
+  --crud-route create:post:/submit:api-key:private:custom=report-writer:bruno \
+  --crud-route delete:delete:/:id:jwt:admin:admin:no-bruno
+```
+
+Matrix policy syntax uses `roles=...` and `custom=...` because `:` separates matrix fields.
+
+## Validate Auth Metadata
+
+```bash
+soap check routes
+```
+
+This checks unknown auth strategies, disabled auth capabilities, invalid zones, policy-without-auth, contracts, and Bruno files.
+

package/docs/guides/cqrs-events-realtime.md

@@ -0,0 +1,100 @@
+# Guide: CQRS, Events, Kafka, And WebSockets
+
+Use this path when the service should be event-oriented or needs WebSocket handlers.
+
+## Create A CQRS Project
+
+```bash
+soap create operations-api \
+  --architecture cqrs \
+  --messaging kafka \
+  --realtime ws \
+  --auth jwt \
+  --api-client bruno \
+  --install
+```
+
+Interactive equivalent:
+
+```bash
+soap create operations-api -i
+```
+
+In interactive mode, select:
+
+- architecture: `cqrs`
+- messaging: `kafka`
+- realtime: `ws`
+- auth as needed
+- API client as needed
+
+Kafka support uses Redpanda in generated Docker Compose.
+
+## Add A CQRS CRUD Resource
+
+```bash
+soap add resource shipment \
+  --crud \
+  --auth jwt \
+  --zone private \
+  --field trackingNumber:string \
+  --field status:string
+```
+
+CQRS CRUD generation creates:
+
+- commands for create/update/delete
+- queries for get/list
+- command/query handlers
+- handler specs
+- route controllers that dispatch through command/query buses
+- entity and in-memory repository specs
+
+## Add Commands And Queries Directly
+
+```bash
+soap add command dispatch-shipment --feature shipment
+soap add query find-shipments --feature shipment
+```
+
+These commands require a CQRS project.
+
+## Add Domain Events
+
+```bash
+soap add event shipment-dispatched --feature shipment
+```
+
+In CQRS projects, the CLI also generates an event handler placeholder under the feature API layer.
+
+## Add WebSocket Handlers
+
+```bash
+soap add socket shipment-updates --feature shipment --auth jwt
+```
+
+WebSocket support must be enabled first:
+
+```bash
+soap update config --add-realtime ws
+```
+
+The socket command updates `src/config/sockets.ts` and adds a handler under the feature.
+
+## Run With Docker Services
+
+```bash
+make up
+make logs
+make down
+```
+
+Generated Docker Compose includes the API and Redpanda when Kafka is enabled.
+
+## Validate
+
+```bash
+npm test
+soap check routes
+```
+

package/docs/guides/index.md

@@ -0,0 +1,24 @@
+# SoapJS CLI Developer Guides
+
+Use these guides when building a service with SoapJS CLI.
+
+SoapJS CLI and generated projects require Node.js `>=24.17.0` (Node 24 LTS or newer).
+Generated projects include `.nvmrc` with `24.17.0`.
+
+## Start Here
+
+- [Regular CRUD API](regular-api.md): create a standard Express CRUD API with storage, auth, contracts, tests, Bruno, and OpenAPI.
+- [CQRS, events, Kafka, and WebSockets](cqrs-events-realtime.md): create a CQRS/event-oriented service and add realtime handlers.
+
+## Capability Guides
+
+- [Auth and route policies](auth.md): JWT, API key, local auth, admin/roles/custom route policies.
+- [Storage capabilities](storage.md): Mongo, Postgres, MySQL, SQLite, Redis, Docker, and environment variables.
+
+## Operations
+
+- [Quality, tests, and safe changes](quality-and-safety.md): generated tests, validation commands, dry-runs, conflict policies, remove safety, install, and git init.
+
+## Command Reference
+
+See [CLI reference](../cli/index.md) for command-level docs.

package/docs/guides/quality-and-safety.md

@@ -0,0 +1,88 @@
+# Guide: Quality, Tests, And Safe Changes
+
+SoapJS CLI is registry-aware. Generated files are tracked in `.soap/registry.json` with hashes so later commands can avoid overwriting user edits.
+
+## Generated Tests
+
+CRUD resource generation creates compiling Node test files.
+
+Regular CRUD resources generate:
+
+- entity spec
+- in-memory repository CRUD spec
+- use-case specs for list/get/create/update/delete
+
+CQRS CRUD resources generate:
+
+- command handler specs
+- query handler specs
+- entity spec
+- in-memory repository CRUD spec
+
+Run tests:
+
+```bash
+npm test
+```
+
+The generated `test` script builds first, then runs compiled `.spec.js` and `.test.js` files with `node --test`.
+
+## Validation Commands
+
+```bash
+soap info
+soap doctor
+soap check routes
+```
+
+Use these commands after changing capabilities, adding routes, or removing generated code.
+
+## Dry Runs
+
+Use `--dry-run` before risky writes or deletes.
+
+```bash
+soap add resource invoice --crud --dry-run
+soap remove resource invoice --dry-run
+soap update config --add-db mysql --dry-run
+```
+
+## Conflict Policies
+
+Generated files are safe by default:
+
+- unchanged generated files can be updated
+- modified generated files are skipped
+- `--force` overwrites or deletes modified generated files
+- `--write-new` writes a `.new` file where supported
+- `--on-conflict abort` fails on the first conflict
+
+Examples:
+
+```bash
+soap generate bruno --write-new
+soap remove resource invoice --force
+soap add resource invoice --crud --on-conflict abort
+```
+
+## Remove Generated Code
+
+```bash
+soap remove route invoice create
+soap remove resource invoice
+soap remove resource invoice -i
+```
+
+Remove only touches files tracked in the registry. If a generated file was modified, it is skipped unless you explicitly force deletion.
+
+## Git And Install
+
+Dependency installation and Git initialization are explicit.
+
+```bash
+soap create users-api --install
+soap create users-api --git-init --skip-install
+```
+
+`--git-init` only runs `git init`. It does not commit or push.
+