@soapjs/cli 1.0.0

package/build/resolvers/add-route.resolver.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addRouteResolver = exports.AddRouteResolver = void 0;
+const errors_1 = require("../core/errors");
+const route_plan_1 = require("../commands/add/route-plan");
+class AddRouteResolver {
+    resolve(input) {
+        const config = requireRouteConfig(input.projectConfig);
+        const flags = input.flags;
+        const promptAnswers = input.promptAnswers ?? {};
+        const preset = input.preset ?? {};
+        const method = normalizeRouteMethod(pick(flags.method, promptAnswers.method, preset.method, "get"));
+        const auth = normalizeRouteAuth(pick(flags.auth, promptAnswers.auth, preset.auth, config.resource.auth));
+        const zone = pick(flags.zone, promptAnswers.zone, preset.zone, config.resource.zone);
+        const useCase = pick(flags.useCase, promptAnswers.useCase, preset.useCase);
+        const command = pick(flags.command, promptAnswers.command, preset.command);
+        const query = pick(flags.query, promptAnswers.query, preset.query);
+        assertSingleRouteTarget({ useCase, command, query });
+        if ((command || query) && config.project.project.architecture !== "cqrs") {
+            throw new errors_1.CliError("CQRS route targets require a project created with `--architecture cqrs`.");
+        }
+        assertCapability("auth", auth, enabledRouteAuthValues(config.project.project.capabilities.auth));
+        assertCapability("zone", zone, config.project.project.zones);
+        return {
+            method,
+            path: pick(flags.path, promptAnswers.path, preset.path),
+            useCase,
+            command,
+            query,
+            auth,
+            zone,
+        };
+    }
+}
+exports.AddRouteResolver = AddRouteResolver;
+function requireRouteConfig(config) {
+    if (!config) {
+        throw new errors_1.CliError("Project and resource config are required to resolve route input.");
+    }
+    return config;
+}
+function pick(...values) {
+    return values.find((item) => item !== undefined);
+}
+function normalizeRouteMethod(value) {
+    const method = (value ?? "get").toLowerCase();
+    if (!route_plan_1.routeMethods.includes(method)) {
+        throw new errors_1.CliError(`Unsupported HTTP method "${value}". Allowed values: ${route_plan_1.routeMethods.join(", ")}.`);
+    }
+    return method;
+}
+function normalizeRouteAuth(value) {
+    if (value === "local") {
+        return "jwt";
+    }
+    if (value === "jwt" || value === "api-key" || value === "none") {
+        return value;
+    }
+    throw new errors_1.CliError(`Auth "${value}" cannot protect routes. Use jwt, api-key, or none.`);
+}
+function enabledRouteAuthValues(values) {
+    const allowed = ["none"];
+    if (values.includes("jwt") || values.includes("local")) {
+        allowed.push("jwt");
+    }
+    if (values.includes("api-key")) {
+        allowed.push("api-key");
+    }
+    return allowed;
+}
+function assertCapability(label, value, allowed) {
+    if (!allowed.includes(value)) {
+        const allowedValues = allowed.length > 0 ? allowed.join(", ") : "none";
+        throw new errors_1.CliError(`${label} "${value}" is not enabled for this project. Allowed values: ${allowedValues}.`);
+    }
+}
+function assertSingleRouteTarget(options) {
+    const targets = [options.useCase, options.command, options.query].filter(Boolean);
+    if (targets.length > 1) {
+        throw new errors_1.CliError("Route target options are mutually exclusive. Use only one of --use-case, --command, or --query.");
+    }
+}
+exports.addRouteResolver = new AddRouteResolver();

package/build/resolvers/create-config.resolver.d.ts

@@ -0,0 +1,32 @@
+import { PackageManager } from "../core/command-context";
+import { ApiZone, Architecture, ProjectCapabilities } from "../config/schemas/types";
+import { CommandInputResolver } from "./resolver.types";
+export interface CreateConfigInput {
+    framework?: string;
+    architecture?: Architecture;
+    db?: string | string[];
+    auth?: string | string[];
+    messaging?: string | string[];
+    telemetry?: string | string[];
+    docs?: string | string[];
+    contracts?: string | string[];
+    apiClient?: string | string[];
+    realtime?: string | string[];
+    zones?: string | string[];
+    packageManager?: PackageManager;
+}
+export interface CreateConfigResult {
+    framework: "express";
+    architecture: Architecture;
+    capabilities: ProjectCapabilities;
+    zones: ApiZone[];
+    packageManager?: PackageManager;
+}
+export declare class CreateConfigResolver implements CommandInputResolver<CreateConfigInput, CreateConfigInput, undefined, CreateConfigResult> {
+    resolve(input: {
+        flags: CreateConfigInput;
+        promptAnswers?: CreateConfigInput;
+        preset?: Partial<CreateConfigResult>;
+    }): CreateConfigResult;
+}
+export declare const createConfigResolver: CreateConfigResolver;

package/build/resolvers/create-config.resolver.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConfigResolver = exports.CreateConfigResolver = void 0;
+const errors_1 = require("../core/errors");
+const project_plan_1 = require("../commands/create/project-plan");
+class CreateConfigResolver {
+    resolve(input) {
+        const flags = input.flags;
+        const promptAnswers = input.promptAnswers ?? {};
+        const preset = input.preset ?? {};
+        const capabilities = (0, project_plan_1.createDefaultCapabilities)();
+        const framework = pick(flags.framework, promptAnswers.framework, preset.framework, "express");
+        if (framework !== "express") {
+            throw new errors_1.CliError("Only framework \"express\" is supported.");
+        }
+        const architecture = pick(flags.architecture, promptAnswers.architecture, preset.architecture, "regular");
+        if (architecture !== "regular" && architecture !== "cqrs") {
+            throw new errors_1.CliError("Architecture must be regular or cqrs.");
+        }
+        capabilities.databases = parseOptionList(pickList(flags.db, promptAnswers.db, preset.capabilities?.databases), project_plan_1.databaseOptions, "database");
+        capabilities.auth = parseOptionList(pickList(flags.auth, promptAnswers.auth, preset.capabilities?.auth), project_plan_1.authOptions, "auth");
+        capabilities.messaging = parseOptionList(pickList(flags.messaging, promptAnswers.messaging, preset.capabilities?.messaging), project_plan_1.messagingOptions, "messaging");
+        capabilities.telemetry = parseOptionList(pickList(flags.telemetry, promptAnswers.telemetry, preset.capabilities?.telemetry), project_plan_1.telemetryOptions, "telemetry");
+        capabilities.docs = parseOptionList(pickList(flags.docs, promptAnswers.docs, preset.capabilities?.docs), project_plan_1.docsOptions, "docs");
+        capabilities.contracts = parseOptionList(pickList(flags.contracts, promptAnswers.contracts, preset.capabilities?.contracts), project_plan_1.contractsOptions, "contracts");
+        capabilities.apiClient = parseOptionList(pickList(flags.apiClient, promptAnswers.apiClient, preset.capabilities?.apiClient), ["bruno"], "api-client");
+        capabilities.realtime = parseOptionList(pickList(flags.realtime, promptAnswers.realtime, preset.capabilities?.realtime), project_plan_1.realtimeOptions, "realtime");
+        if (capabilities.messaging.length === 0)
+            capabilities.messaging = ["in-memory"];
+        if (capabilities.telemetry.length === 0)
+            capabilities.telemetry = ["logs"];
+        const zones = parseOptionList(pick(flags.zones, promptAnswers.zones, preset.zones, "public,private,admin"), project_plan_1.zonesOptions, "zone");
+        return {
+            framework,
+            architecture,
+            capabilities,
+            zones: zones.length > 0 ? zones : ["public", "private", "admin"],
+            packageManager: pick(flags.packageManager, promptAnswers.packageManager, preset.packageManager),
+        };
+    }
+}
+exports.CreateConfigResolver = CreateConfigResolver;
+function pick(...values) {
+    return values.find((value) => value !== undefined);
+}
+function pickList(...values) {
+    return values.find((value) => value !== undefined && (!Array.isArray(value) || value.length > 0));
+}
+function parseOptionList(value, allowed, label) {
+    try {
+        return (0, project_plan_1.parseCsvOption)(value, allowed);
+    }
+    catch (error) {
+        throw new errors_1.CliError(`Invalid ${label} option: ${error.message}`);
+    }
+}
+exports.createConfigResolver = new CreateConfigResolver();

package/build/resolvers/generate-bruno.resolver.d.ts

@@ -0,0 +1,17 @@
+import { SoapConfig } from "../config/schemas/types";
+import { CommandInputResolver } from "./resolver.types";
+export interface GenerateBrunoInput {
+    e2e?: boolean;
+}
+export interface GenerateBrunoResult {
+    e2e: boolean;
+}
+export declare class GenerateBrunoResolver implements CommandInputResolver<GenerateBrunoInput, GenerateBrunoInput, SoapConfig, GenerateBrunoResult> {
+    resolve(input: {
+        flags: GenerateBrunoInput;
+        promptAnswers?: GenerateBrunoInput;
+        projectConfig?: SoapConfig;
+        preset?: Partial<GenerateBrunoResult>;
+    }): GenerateBrunoResult;
+}
+export declare const generateBrunoResolver: GenerateBrunoResolver;

package/build/resolvers/generate-bruno.resolver.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateBrunoResolver = exports.GenerateBrunoResolver = void 0;
+const errors_1 = require("../core/errors");
+class GenerateBrunoResolver {
+    resolve(input) {
+        const config = input.projectConfig;
+        if (!config) {
+            throw new errors_1.CliError("Project config is required to resolve Bruno generation input.");
+        }
+        if (!config.project.capabilities.apiClient.includes("bruno") && !config.api.bruno.enabled) {
+            throw new errors_1.CliError("Bruno is not enabled for this project. Create the project with `--api-client bruno`.");
+        }
+        return {
+            e2e: Boolean(pick(input.flags.e2e, input.promptAnswers?.e2e, input.preset?.e2e, false)),
+        };
+    }
+}
+exports.GenerateBrunoResolver = GenerateBrunoResolver;
+function pick(...values) {
+    return values.find((value) => value !== undefined);
+}
+exports.generateBrunoResolver = new GenerateBrunoResolver();

package/build/resolvers/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./resolver.types";
+export * from "./create-config.resolver";
+export * from "./add-resource.resolver";
+export * from "./add-route.resolver";
+export * from "./generate-bruno.resolver";

package/build/resolvers/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./resolver.types"), exports);
+__exportStar(require("./create-config.resolver"), exports);
+__exportStar(require("./add-resource.resolver"), exports);
+__exportStar(require("./add-route.resolver"), exports);
+__exportStar(require("./generate-bruno.resolver"), exports);

package/build/resolvers/resolver.types.d.ts

@@ -0,0 +1,8 @@
+export interface CommandInputResolver<TFlags, TPromptAnswers, TConfig, TResult, TPreset = Partial<TResult>> {
+    resolve(input: {
+        flags: TFlags;
+        promptAnswers?: TPromptAnswers;
+        projectConfig?: TConfig;
+        preset?: TPreset;
+    }): TResult;
+}

package/build/resolvers/resolver.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/summary/create-summary.d.ts

@@ -0,0 +1,2 @@
+import { ProjectPlan } from "../commands/create/project-plan";
+export declare function formatCreateSummary(plan: ProjectPlan): string;

package/build/summary/create-summary.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCreateSummary = void 0;
+function formatCreateSummary(plan) {
+    return [
+        `Project: ${plan.name}`,
+        `Framework: ${plan.framework}`,
+        `Architecture: ${plan.architecture}`,
+        `Databases: ${formatList(plan.capabilities.databases)}`,
+        `Auth: ${formatList(plan.capabilities.auth)}`,
+        `Messaging: ${formatList(plan.capabilities.messaging)}`,
+        `Realtime: ${formatList(plan.capabilities.realtime)}`,
+        `Telemetry: ${formatList(plan.capabilities.telemetry)}`,
+        `Docs: ${formatList(plan.capabilities.docs)}`,
+        `Contracts: ${formatList(plan.capabilities.contracts)}`,
+        `API client: ${formatList(plan.capabilities.apiClient)}`,
+        `Zones: ${formatList(plan.zones)}`,
+        `Package manager: ${plan.packageManager}`,
+    ].join("\n");
+}
+exports.formatCreateSummary = formatCreateSummary;
+function formatList(values) {
+    return values.length > 0 ? values.join(", ") : "none";
+}

package/build/summary/index.d.ts

@@ -0,0 +1 @@
+export * from "./create-summary";

package/build/summary/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./create-summary"), exports);

package/build/templates/naming.d.ts

@@ -0,0 +1,11 @@
+export interface NameVariants {
+    rawName: string;
+    pascalName: string;
+    camelName: string;
+    kebabName: string;
+    snakeName: string;
+    constantName: string;
+    pluralName: string;
+}
+export declare function pluralize(value: string): string;
+export declare function createNameVariants(name: string): NameVariants;

package/build/templates/naming.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNameVariants = exports.pluralize = void 0;
+const change_case_1 = require("change-case");
+function pluralize(value) {
+    if (value.endsWith("s")) {
+        return value;
+    }
+    if (value.endsWith("y") && !/[aeiou]y$/i.test(value)) {
+        return `${value.slice(0, -1)}ies`;
+    }
+    if (/(s|x|z|ch|sh)$/i.test(value)) {
+        return `${value}es`;
+    }
+    return `${value}s`;
+}
+exports.pluralize = pluralize;
+function createNameVariants(name) {
+    const kebabName = (0, change_case_1.paramCase)(name);
+    return {
+        rawName: name,
+        pascalName: (0, change_case_1.pascalCase)(name),
+        camelName: (0, change_case_1.camelCase)(name),
+        kebabName,
+        snakeName: (0, change_case_1.snakeCase)(name),
+        constantName: (0, change_case_1.constantCase)(name),
+        pluralName: pluralize(kebabName),
+    };
+}
+exports.createNameVariants = createNameVariants;

package/build/templates/template-context.d.ts

@@ -0,0 +1,6 @@
+import { NameVariants } from "./naming";
+import { ProjectPlan } from "../commands/create/project-plan";
+export interface TemplateContext {
+    project: ProjectPlan;
+    names: NameVariants;
+}

package/build/templates/template-context.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/templates/template-engine.d.ts

@@ -0,0 +1 @@
+export declare function renderTemplate(template: string, values: Record<string, string | number | boolean | undefined>): string;

package/build/templates/template-engine.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTemplate = void 0;
+function renderTemplate(template, values) {
+    return template.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (_, key) => {
+        const value = values[key];
+        return value === undefined ? "" : String(value);
+    });
+}
+exports.renderTemplate = renderTemplate;

package/build/templates/template-resolver.d.ts

@@ -0,0 +1,2 @@
+export declare function registerTemplate(name: string, content: string): void;
+export declare function resolveTemplate(name: string): string;

package/build/templates/template-resolver.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTemplate = exports.registerTemplate = void 0;
+const errors_1 = require("../core/errors");
+const templates = new Map();
+function registerTemplate(name, content) {
+    templates.set(name, content);
+}
+exports.registerTemplate = registerTemplate;
+function resolveTemplate(name) {
+    const content = templates.get(name);
+    if (!content) {
+        throw new errors_1.CliError(`Missing template: ${name}`);
+    }
+    return content;
+}
+exports.resolveTemplate = resolveTemplate;

package/build/terminal/terminal-capabilities.d.ts

@@ -0,0 +1,6 @@
+export interface TerminalCapabilities {
+    stdinIsTty: boolean;
+    stdoutIsTty: boolean;
+}
+export declare function getTerminalCapabilities(): TerminalCapabilities;
+export declare function canRunInteractiveMode(capabilities?: TerminalCapabilities): boolean;

package/build/terminal/terminal-capabilities.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canRunInteractiveMode = exports.getTerminalCapabilities = void 0;
+function getTerminalCapabilities() {
+    return {
+        stdinIsTty: Boolean(process.stdin.isTTY),
+        stdoutIsTty: Boolean(process.stdout.isTTY),
+    };
+}
+exports.getTerminalCapabilities = getTerminalCapabilities;
+function canRunInteractiveMode(capabilities = getTerminalCapabilities()) {
+    return capabilities.stdinIsTty && capabilities.stdoutIsTty;
+}
+exports.canRunInteractiveMode = canRunInteractiveMode;

package/docs/adr/0001-soap-cli-project-aware-generator.md

@@ -0,0 +1,108 @@
+# ADR 0001: Soap CLI Project-Aware Generator
+
+## Status
+
+Accepted
+
+## Context
+
+SoapJS CLI generates service projects and later modifies them by adding resources, routes, API clients, documentation, auth, and infrastructure capabilities. The generator has to be repeatable, safe around user edits, and explicit about which files it owns.
+
+The MVP intentionally targets predictable project shapes instead of arbitrary existing codebases.
+
+## Decision
+
+SoapJS CLI is a template-based, project-aware generator.
+
+Generated projects include a `.soap` directory:
+
+- `.soap/project.json` stores selected capabilities and project metadata.
+- `.soap/structure.json` stores source layout conventions.
+- `.soap/api.json` stores API runtime settings used by generators.
+- `.soap/registry.json` stores resources, routes, generated files, owners, and hashes.
+
+The registry is the authority for follow-up commands such as `soap add`, `soap generate`, `soap check`, `soap remove`, and `soap update config`.
+
+## Why `.soap` Exists
+
+The CLI needs project-local state that is independent of package manager files and source code formatting. `.soap` gives commands a stable contract for:
+
+- enabled capabilities
+- expected project structure
+- API conventions
+- generated resource and route metadata
+- generated file ownership and hashes
+
+This avoids guessing project state from source files.
+
+## Why The Registry Exists
+
+The registry makes generated changes deterministic and safe.
+
+It records:
+
+- generated resources and route paths
+- generated file paths
+- generated file type and owner
+- content hashes from the last CLI write
+
+This allows the CLI to detect manual edits and skip, overwrite, or write `.new` files depending on command options.
+
+Without a registry, commands like `soap remove resource users` would have to infer ownership from filenames and could delete user-owned files.
+
+## Why The MVP Avoids Broad AST Mutation
+
+AST mutation is useful when editing arbitrary source code, but it increases complexity and risk:
+
+- user formatting and local patterns vary
+- imports and decorators can be organized many ways
+- partial edits can leave code in a hard-to-debug state
+- reliable idempotence requires many language-aware edge cases
+
+The MVP instead regenerates known composition files and generated artifacts from templates. This keeps behavior predictable and makes safety checks based on registry hashes straightforward.
+
+Future versions can add narrow AST transforms where there is a clear contract and test coverage.
+
+## Why Bruno Is Generated
+
+Bruno collections are generated from the route registry so API test artifacts stay aligned with generated routes.
+
+This gives every generated project a runnable local API smoke path:
+
+- health check
+- auth requests when auth is enabled
+- resource CRUD requests
+- optional E2E CRUD flow
+
+Because Bruno files are tracked in the registry, user edits are protected by the same hash-based safety behavior as TypeScript files.
+
+## Why Optional Adapters Are Wired In The Composition Root
+
+Optional adapters such as Mongo, Postgres, Kafka, OpenAPI, auth, and WebSocket support are wired in generated composition files:
+
+- `src/index.ts`
+- `src/config/config.ts`
+- `src/config/dependencies.ts`
+- `src/config/controllers.ts`
+- `src/config/resources.ts`
+
+This keeps feature code focused on domain/application concerns and keeps infrastructure selection in one predictable layer.
+
+It also makes `soap update config` practical: adding a capability rewrites known infrastructure files and adds missing adapter files without invasive edits across resource code.
+
+## Consequences
+
+Positive:
+
+- deterministic generated output
+- safer overwrite/remove behavior
+- simple validation through `soap check routes`
+- straightforward generated project structure
+- capability updates are practical in the MVP
+
+Tradeoffs:
+
+- arbitrary app migrations are out of scope
+- manually rewritten composition files may be skipped unless `--force` is used
+- the CLI favors project conventions over flexible source discovery
+- some future changes may require explicit migration commands

package/docs/cli/add-resource.md

@@ -0,0 +1,127 @@
+# `soap add resource`
+
+Add a resource to an existing SoapJS project.
+
+```bash
+soap add resource invoice --crud --db postgres --auth jwt --zone public
+soap add resource invoice --crud --db mysql --auth jwt --zone private
+soap add resource note --crud --db sqlite
+soap add resource product --crud --field title:string --field price:number --field active:boolean:optional
+soap add resource report --crud --auth jwt --policy roles:admin,editor
+soap add resource invoice -i
+```
+
+## Interactive Flow
+
+```bash
+soap add resource invoice -i
+```
+
+The command reads `.soap` before prompting and only offers enabled project capabilities:
+
+- CRUD generation
+- storage from enabled databases plus `none`
+- route auth from enabled auth strategies plus `none`
+- API zone from project zones
+- Bruno generation when Bruno is enabled
+- enabling Bruno when it is not enabled
+- optional dry-run-first preview
+
+Interactive mode prints the expanded resource plan before writing and asks for confirmation.
+
+Use `--yes` to skip final confirmation:
+
+```bash
+soap add resource invoice -i --yes
+```
+
+## Dry Run
+
+```bash
+soap add resource invoice --crud --db postgres --dry-run
+```
+
+Dry run prints the generated file groups without writing files.
+
+## Fields
+
+Store resource field metadata in `.soap/registry.json`:
+
+```bash
+soap add resource product --crud \
+  --field title:string \
+  --field price:number \
+  --field active:boolean:optional
+```
+
+Supported field types:
+
+- `string`
+- `number`
+- `boolean`
+- `date`
+
+Fields are used by generated entity props, Zod contracts when enabled, and Bruno request bodies. If no fields are provided, the generator uses `name:string`.
+
+## Storage
+
+Resource repositories are generated for:
+
+- `none` -> in-memory repository
+- `mongo` -> Mongo repository
+- `postgres` -> SQL repository using PostgreSQL config
+- `mysql` -> SQL repository using MySQL config
+- `sqlite` -> SQL repository using SQLite config
+
+`redis` is currently infrastructure-only and does not generate a resource repository adapter.
+
+## Auth Policies
+
+Attach a policy to protected generated routes:
+
+```bash
+soap add resource report --crud --auth jwt --policy roles:admin,editor
+soap add resource audit-log --crud --auth api-key --policy admin
+soap add resource invoice --crud --auth jwt --policy custom:billing-owner
+```
+
+Supported policies:
+
+- `admin` -> `@AdminOnly('<strategy>')`
+- `roles:a,b` -> `@Auth('<strategy>', { roles: ['a', 'b'] })`
+- `custom:name` -> `@Auth('<strategy>', { policy: 'name' })`
+
+Policies require route auth. Use `--auth jwt` or `--auth api-key`.
+
+## CRUD Route Matrix
+
+Override per-operation route metadata:
+
+```bash
+soap add resource report --crud \
+  --crud-route list:get:/search:jwt:private:admin:no-bruno \
+  --crud-route create:post:/submit:jwt:private:roles=admin,editor:bruno \
+  --crud-route update:patch:/:id:jwt:private:custom=report-owner:bruno
+```
+
+Format:
+
+```txt
+operation:method:path[:auth][:zone][:policy][:bruno|no-bruno]
+```
+
+Supported operations are `list`, `get`, `create`, `update`, and `delete`. Paths are relative to the resource base unless they already start with the resource path. Matrix policies use `admin`, `roles=a,b`, or `custom=name`. `no-bruno` excludes the operation from generated Bruno requests.
+
+## Contracts
+
+When the project has `contracts: ["zod"]`, generated resource route contracts parse input through Zod schemas.
+
+## Bruno
+
+If Bruno is enabled, resource generation refreshes the Bruno collection.
+
+If Bruno is disabled, interactive mode can enable it. Non-interactive mode can do the same explicitly:
+
+```bash
+soap add resource invoice --enable-bruno --bruno
+```