@soapjs/cli 1.0.0

package/docs/guides/regular-api.md

@@ -0,0 +1,119 @@
+# Guide: Regular CRUD API
+
+Use this path for a conventional Express service with generated CRUD routes, storage, route contracts, tests, Bruno, and OpenAPI.
+
+## Create The Project
+
+```bash
+soap create billing-api \
+  --db postgres \
+  --auth jwt \
+  --docs openapi \
+  --contracts zod \
+  --api-client bruno \
+  --install \
+  --git-init
+```
+
+Interactive equivalent:
+
+```bash
+soap create billing-api -i
+```
+
+In interactive mode, select:
+
+- architecture: `regular`
+- database: `postgres`
+- auth: `jwt`
+- docs: `openapi`
+- contracts: `zod`
+- API client: `bruno`
+- install dependencies: yes when wanted
+- git init: yes only when you want a new local repository
+
+## Run The Service
+
+```bash
+cd billing-api
+npm run build
+npm test
+npm start
+```
+
+Health check:
+
+```bash
+curl http://localhost:3000/health
+```
+
+## Add A CRUD Resource
+
+```bash
+soap add resource invoice \
+  --crud \
+  --db postgres \
+  --auth jwt \
+  --zone private \
+  --field number:string \
+  --field total:number \
+  --field paid:boolean:optional \
+  --bruno
+```
+
+Generated output includes:
+
+- domain entity and entity spec
+- repository port
+- in-memory repository and repository spec
+- Postgres SQL repository
+- CRUD use-cases and use-case specs
+- route contracts
+- route controllers
+- resource setup registration
+- Bruno requests when Bruno is enabled
+
+## Add A Custom Route
+
+```bash
+soap add route invoice approve \
+  --method post \
+  --path :id/approve \
+  --auth jwt \
+  --zone private \
+  --policy custom:invoice-approver \
+  --bruno
+```
+
+Route paths are scoped under the resource path. The example generates `/invoices/:id/approve`.
+
+## Validate Generated Metadata
+
+```bash
+soap info
+soap doctor
+soap check routes
+```
+
+Run these after adding or removing resources/routes.
+
+## Refresh API Artifacts
+
+```bash
+soap generate bruno
+soap generate bruno --e2e
+soap generate openapi --output openapi.json
+```
+
+`generate openapi` expects the service to be running.
+
+## Safe Removal
+
+```bash
+soap remove route invoice approve
+soap remove resource invoice --dry-run
+soap remove resource invoice
+```
+
+Modified generated files are skipped unless you use `--force` or `--on-conflict overwrite`.
+

package/docs/guides/storage.md

@@ -0,0 +1,101 @@
+# Guide: Storage Capabilities
+
+Storage capabilities affect generated dependencies, config, Docker services, and resource repository templates.
+
+## Supported Storage
+
+| Capability | Project infra | Resource repository |
+| --- | --- | --- |
+| `none` | no external service | in-memory |
+| `mongo` | Mongo client, config, Docker service | Mongo repository |
+| `postgres` | SQL client, config, Docker service | SQL repository |
+| `mysql` | SQL client, config, Docker service | SQL repository |
+| `sqlite` | SQL client, local filename config | SQL repository |
+| `redis` | Redis client/config/Docker service | infrastructure only |
+
+Redis is currently infrastructure-only for resources. Do not pass `--db redis` to resource generation expecting a Redis repository template.
+
+## Create With Storage
+
+```bash
+soap create data-api --db postgres --install
+soap create data-api --db mysql --db sqlite --skip-install
+soap create data-api --db mongo --db redis --skip-install
+```
+
+## Add Storage Later
+
+```bash
+soap update config --add-db postgres
+soap update config --add-db mysql
+soap update config --add-db sqlite
+soap update config --add-db redis
+```
+
+`update config` is add-only.
+
+## Add Resources With Storage
+
+```bash
+soap add resource invoice --crud --db postgres
+soap add resource invoice --crud --db mysql
+soap add resource note --crud --db sqlite
+soap add resource customer --crud --db mongo
+soap add resource task --crud --db none
+```
+
+Generated SQL repositories use the same repository template with adapter-specific config:
+
+- PostgreSQL uses `$1`, `$2` placeholders.
+- MySQL and SQLite use `?` placeholders.
+
+## Environment Variables
+
+PostgreSQL:
+
+```txt
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_DB=app
+POSTGRES_USER=app
+POSTGRES_PASSWORD=app
+```
+
+MySQL:
+
+```txt
+MYSQL_HOST=localhost
+MYSQL_PORT=3306
+MYSQL_DATABASE=app
+MYSQL_USER=app
+MYSQL_PASSWORD=app
+```
+
+SQLite:
+
+```txt
+SQLITE_FILENAME=./data/app.sqlite
+```
+
+Mongo:
+
+```txt
+MONGO_URI=mongodb://localhost:27017/app
+```
+
+Redis:
+
+```txt
+REDIS_URL=redis://localhost:6379
+```
+
+## Docker
+
+```bash
+make up
+make logs
+make down
+```
+
+Generated Docker Compose includes services for Mongo, Postgres, MySQL, Redis, and Kafka/Redpanda when those capabilities are enabled.
+