@soapjs/cli 1.0.0

package/docs/plans/interactive-mode-plan.md

@@ -0,0 +1,601 @@
+# Soap CLI Interactive Mode Plan
+
+This plan adapts `/Users/rad/Downloads/SOAP_CLI_INTERACTIVE_MODE_TICKETS.md` to the current `soap-cli` codebase.
+
+The current CLI is deterministic, registry-aware, and template-based. Interactive mode must preserve that model. It should resolve command inputs, never generate code through AI, and never hide file writes, deletes, or overwrites.
+
+## Current Baseline
+
+Current command surface:
+
+- `soap create`
+- `soap add resource`
+- `soap add route`
+- `soap add entity`
+- `soap add use-case`
+- `soap add repository`
+- `soap add command`
+- `soap add query`
+- `soap add event`
+- `soap add socket`
+- `soap generate bruno`
+- `soap generate openapi`
+- `soap info`
+- `soap doctor`
+- `soap check routes`
+- `soap remove route`
+- `soap remove resource`
+- `soap update config`
+
+Current capability model:
+
+- Framework: `express`
+- Architecture: `regular`, `cqrs`
+- Databases: `mongo`, `postgres`, `mysql`, `sqlite`, `redis`
+- Auth: `jwt`, `api-key`, `local`
+- Messaging: `in-memory`, `kafka`
+- Realtime: `ws`
+- Telemetry: `logs`, `otel-noop`
+- Docs: `openapi`
+- API client: `bruno`
+
+Out of scope for the first interactive pass:
+
+- MySQL and SQLite
+- OAuth2 and Basic auth
+- role/admin decorator policies beyond existing auth strategy values
+- Zod as a separate capability
+- Pino/tracing capability names
+- git init
+- Docker enable/disable toggle
+- migrations, DB indexes, generated test suites, mapper prompts
+- registry field metadata
+
+These are valid future directions, but they require model/schema work before prompts should expose them.
+
+## Design Rules
+
+1. Interactive is optional.
+
+   Every interactive flow must have an equivalent flag-based non-interactive flow.
+
+2. Resolution order is fixed.
+
+   ```txt
+   explicit CLI flags
+   interactive answers
+   .soap project/api/registry defaults
+   preset defaults
+   hardcoded fallback defaults
+   ```
+
+3. Interactive prompts are project-aware.
+
+   Existing `.soap/project.json`, `.soap/structure.json`, `.soap/api.json`, and `.soap/registry.json` determine available choices.
+
+4. Prompting is only input resolution.
+
+   Prompt answers feed the same deterministic planners and writers used by non-interactive commands.
+
+5. File conflict behavior is shared.
+
+   Interactive mode may ask, but actual writes/deletes must still go through the same safe file writer and registry hash checks.
+
+6. Future capability expansion must happen below the prompt layer first.
+
+   Do not ask users about a capability until the config schema, dependency resolver, templates, registry behavior, and validation support it.
+
+## Phase 1 — Interactive Foundation
+
+### INT-MVP-001 — Shared Interactive Option
+
+Add `-i, --interactive` to supported commands.
+
+Initial supported commands:
+
+- `soap create <name>`
+- `soap add resource <name>`
+- `soap add route <resource> <name>`
+- `soap generate bruno`
+- `soap remove route <resource> <route>`
+- `soap remove resource <resource>`
+
+Also add shared `--on-conflict <policy>` where useful.
+
+Policies:
+
+- `ask`
+- `skip`
+- `overwrite`
+- `new`
+- `abort`
+
+Mapping to existing behavior:
+
+- `skip` -> current skip modified behavior
+- `overwrite` -> `--force`
+- `new` -> `--write-new` where supported
+- `abort` -> fail on first conflict
+- `ask` -> prompt only in interactive TTY
+
+Acceptance:
+
+- Commands accept `-i` and `--interactive`.
+- Help documents interactive flags.
+- No prompt appears unless `-i` is passed.
+- Existing non-interactive behavior remains unchanged.
+
+### INT-MVP-002 — Prompt Adapter
+
+Add a prompt abstraction under `src/prompts`.
+
+Suggested files:
+
+```txt
+src/prompts/prompt.types.ts
+src/prompts/prompt-adapter.ts
+src/prompts/inquirer-prompt-adapter.ts
+src/prompts/mock-prompt-adapter.ts
+```
+
+Interface:
+
+```ts
+interface PromptAdapter {
+  input(question: InputQuestion): Promise<string>;
+  confirm(question: ConfirmQuestion): Promise<boolean>;
+  select<T extends string>(question: SelectQuestion<T>): Promise<T>;
+  multiSelect<T extends string>(question: MultiSelectQuestion<T>): Promise<T[]>;
+}
+```
+
+Acceptance:
+
+- Command code does not import `@inquirer/prompts` directly.
+- Adapter is mockable in tests.
+- `@inquirer/prompts` is the only prompt implementation dependency.
+
+### INT-MVP-003 — Terminal Capability Guard
+
+Add TTY detection.
+
+Suggested files:
+
+```txt
+src/terminal/terminal-capabilities.ts
+src/commands/shared/interactive-guard.ts
+```
+
+Behavior:
+
+- If `--interactive` is passed outside a TTY, fail clearly.
+- Non-interactive commands still work in CI.
+- `--yes` may skip confirmations but must not imply interactive mode.
+
+Error:
+
+```txt
+Interactive mode requires a TTY. Use explicit flags instead.
+```
+
+Acceptance:
+
+- TTY and non-TTY behavior covered by unit tests.
+
+### INT-MVP-004 — Input Resolvers
+
+Add small resolvers for current command inputs.
+
+Suggested files:
+
+```txt
+src/resolvers/resolver.types.ts
+src/resolvers/create-config.resolver.ts
+src/resolvers/add-resource.resolver.ts
+src/resolvers/add-route.resolver.ts
+src/resolvers/generate-bruno.resolver.ts
+```
+
+Acceptance:
+
+- Flags always win over prompt answers.
+- Prompt answers win over config defaults.
+- Project config restricts available options.
+- Invalid resolved values fail before file planning.
+
+### INT-MVP-005 — Shared Conflict Policy
+
+Consolidate current `force`, `writeNew`, and skip behavior.
+
+Suggested files:
+
+```txt
+src/io/conflict-policy.ts
+src/prompts/file-conflict.prompt.ts
+```
+
+Acceptance:
+
+- Existing `--force` and `--write-new` still work.
+- Interactive conflict `ask` presents skip/overwrite/write-new/abort.
+- Non-interactive default stays safe.
+
+## Phase 2 — Interactive Create
+
+### INT-MVP-101 — `soap create <name> -i`
+
+Prompt only for current supported capabilities.
+
+Prompt flow:
+
+```txt
+Project name
+Framework: express
+Architecture: regular/cqrs
+Databases: mongo/postgres/mysql/sqlite/redis/none
+Auth: jwt/api-key/local/none
+Messaging: in-memory/kafka
+Realtime: ws/none
+Telemetry: logs/otel-noop
+Docs: openapi/none
+API client: bruno/none
+Zones: public/private/admin
+Package manager: npm/pnpm/yarn/bun
+Install dependencies: yes/no
+```
+
+Do not prompt for unsupported future options.
+
+Acceptance:
+
+- Provided flags skip matching questions.
+- Answers feed existing `createProjectFiles` and `createSoapConfigBundle`.
+- Generated `.soap` files match selected answers.
+- `--dry-run` prints summary and planned file count.
+
+### INT-MVP-102 — Create Summary
+
+Before writing files, show a summary in interactive mode.
+
+Example:
+
+```txt
+Project: billing-service
+Architecture: regular
+Databases: postgres
+Auth: jwt
+Docs: openapi
+API client: bruno
+
+Generate project? yes/no
+```
+
+Acceptance:
+
+- User can abort before writes.
+- `--yes` skips final confirmation.
+
+### INT-MVP-103 — Create Presets
+
+Add presets compatible with current capability model.
+
+Initial presets:
+
+- `express-mongo-api`
+- `express-postgres-api`
+- `express-cqrs-kafka-api`
+- `express-full-demo`
+
+Suggested files:
+
+```txt
+src/presets/create-presets.ts
+src/presets/preset.types.ts
+```
+
+Acceptance:
+
+- `soap create my-api --preset express-mongo-api` works without prompts.
+- `soap create my-api -i --preset express-mongo-api` uses preset values as defaults.
+- Invalid preset shows available presets.
+
+## Phase 3 — Interactive Resource And Route
+
+### INT-MVP-201 — `soap add resource <name> -i`
+
+Prompt flow based on current generator:
+
+```txt
+Resource name
+Generate CRUD: yes/no
+Storage: none + enabled databases only
+Auth: none + enabled route auth only
+Zone: enabled project zones
+Generate Bruno requests: yes/no if Bruno enabled
+Enable Bruno now: yes/no if Bruno disabled
+Run as dry-run first: yes/no
+```
+
+Acceptance:
+
+- Reads `.soap` before prompting.
+- Does not offer unavailable DB/auth choices.
+- If Bruno is enabled interactively, updates `.soap/api.json` and project capabilities using update config behavior.
+- Generated files and registry are unchanged from equivalent flag-based flow.
+
+### INT-MVP-202 — Resource Plan Summary
+
+Reuse the existing resource planning summary from `soap add resource --dry-run`.
+
+Acceptance:
+
+- Interactive mode shows planned file groups before writing.
+- User can abort.
+- `--yes` skips final confirmation.
+
+### INT-MVP-203 — `soap add route <resource> <name> -i`
+
+Prompt flow:
+
+```txt
+Resource: select from registry if missing
+Route name
+HTTP method
+Path
+Zone
+Auth
+Target: direct/use-case/command/query
+Generate Bruno request: yes/no if Bruno enabled
+```
+
+Acceptance:
+
+- Resource list comes from registry.
+- Auth choices come from enabled capabilities.
+- Zone choices come from `.soap/project.json`.
+- Generated route matches equivalent non-interactive flags.
+
+## Phase 4 — Interactive Generated Artifacts
+
+### INT-MVP-301 — `soap generate bruno -i`
+
+Prompt flow:
+
+```txt
+Detected routes
+Existing Bruno files
+Missing Bruno files
+Modified generated Bruno files
+
+Choose:
+- generate missing only
+- regenerate all unmodified generated files
+- generate E2E flow
+- abort
+```
+
+Acceptance:
+
+- Manual `.bru` edits are detected.
+- User can avoid overwriting modified files.
+- `--force` still overrides.
+
+### INT-MVP-302 — Interactive OpenAPI Export
+
+Optional small enhancement:
+
+```bash
+soap generate openapi -i
+```
+
+Prompt:
+
+```txt
+Output path: openapi.json
+```
+
+Acceptance:
+
+- Only offered when OpenAPI capability is enabled.
+- Dry run does not fetch from server.
+
+## Phase 5 — Interactive Remove
+
+### INT-MVP-401 — `soap remove route/resource -i`
+
+Use existing safe remove behavior.
+
+Prompt flow:
+
+```txt
+Found route/resource
+Tracked files to delete
+Modified tracked files
+Registry entries to remove
+
+Continue? yes/no
+```
+
+Acceptance:
+
+- Shows tracked file list before deletion.
+- Refuses modified files unless user chooses overwrite/force.
+- Dry run shows planned deletion.
+- Does not delete untracked files.
+
+## Phase 6 — Tests And Docs
+
+### INT-MVP-501 — Resolver Unit Tests
+
+Test:
+
+- flags override prompts
+- prompts override project config
+- project config overrides preset
+- preset overrides fallback
+- invalid values fail
+
+### INT-MVP-502 — Prompt Adapter Tests
+
+Test commands with mocked prompt adapter.
+
+Initial integration tests:
+
+- `soap create my-api -i`
+- `soap add resource users -i`
+- `soap add route users search -i`
+- `soap generate bruno -i`
+- `soap remove route users create-user -i`
+
+### INT-MVP-503 — Interactive Docs
+
+Add:
+
+```txt
+docs/cli/interactive-mode.md
+docs/cli/create.md
+docs/cli/add-resource.md
+docs/cli/add-route.md
+docs/cli/bruno.md
+```
+
+Update root README with an interactive section.
+
+## Phase 7 — Future Capability Expansion
+
+These items should not be prompt-only tickets. Each needs schema, templates, validation, registry, docs, and tests.
+
+### FUT-001 — Contracts Capability
+
+Add explicit contract capability, likely:
+
+```ts
+contracts: ["zod"]
+```
+
+Work required:
+
+- config schema
+- dependency resolver
+- route/resource templates
+- registry metadata
+- `soap update config --add-contracts zod`
+- interactive prompts
+
+### FUT-002 — Resource Field Metadata
+
+Add field definitions to registry.
+
+Used by:
+
+- entity templates
+- contracts
+- Bruno request bodies
+- repositories
+- later migrations/indexes
+
+This should be implemented before INT-style field prompts.
+
+### FUT-003 — CRUD Route Matrix
+
+Allow per-operation route config:
+
+- method
+- path
+- zone
+- auth
+- Bruno yes/no
+
+Requires route registry extension before interactive prompts expose it.
+
+### FUT-004 — Auth Policies
+
+Add route policy support beyond strategy names:
+
+- admin
+- roles
+- custom
+
+Implemented through registry metadata, `--policy`, CRUD matrix policy overrides, generated auth decorators, docs, and route checks.
+
+### FUT-005 — More Storage Adapters
+
+Add MySQL/SQLite only after:
+
+- dependency resolver support
+- generated config
+- docker/dev story
+- repository templates
+- smoke tests
+
+Implemented for MySQL and SQLite through the shared SQL runtime path, dependency resolver, generated config/client files, Docker/dev configuration for MySQL, SQLite env configuration, resource SQL repositories, and smoke generation tests.
+
+### FUT-006 — Generated Tests
+
+Add unit/integration test generation as a separate epic.
+
+Do not include test prompts before the generator can produce compiling tests.
+
+Implemented for generated CRUD resources in regular and CQRS modes:
+
+- entity specs
+- in-memory repository CRUD specs
+- regular CRUD use-case specs
+- CQRS command/query handler specs
+
+Verified with generated project `npm test` for regular and CQRS resources with custom field metadata.
+
+### FUT-007 — Git Init And Install
+
+Can be added later, but should remain explicit and safe.
+
+Implemented as explicit post-create actions:
+
+- `--install` runs the selected package manager after files are written.
+- `--skip-install` takes precedence over install.
+- interactive create asks about dependency installation.
+- `--git-init` runs `git init` after files are written.
+- interactive create asks about git init with default `false`.
+- no auto-commit and no push behavior.
+
+## Recommended Implementation Order
+
+```txt
+1. INT-MVP-001 shared interactive option
+2. INT-MVP-002 prompt adapter
+3. INT-MVP-003 terminal guard
+4. INT-MVP-005 shared conflict policy
+5. INT-MVP-004 input resolvers
+6. INT-MVP-101 create wizard
+7. INT-MVP-102 create summary
+8. INT-MVP-103 create presets
+9. INT-MVP-201 add resource wizard
+10. INT-MVP-202 resource plan summary
+11. INT-MVP-203 add route wizard
+12. INT-MVP-301 generate bruno wizard
+13. INT-MVP-401 remove wizard
+14. INT-MVP-501 resolver tests
+15. INT-MVP-502 prompt/integration tests
+16. INT-MVP-503 interactive docs
+17. FUT-001 contracts capability
+18. FUT-002 resource field metadata
+19. FUT-003 CRUD route matrix
+20. FUT-004 auth policies
+21. FUT-005 more storage adapters
+22. FUT-006 generated tests
+23. FUT-007 git init and install
+```
+
+## Codex Ticket Prompt
+
+```txt
+Implement INT-MVP-XXX from docs/plans/interactive-mode-plan.md.
+
+Constraints:
+- Preserve non-interactive behavior.
+- Interactive mode only resolves options; generation stays deterministic.
+- Use the existing .soap config and registry model.
+- Do not expose unsupported future capabilities in prompts.
+- Do not overwrite modified generated files without shared conflict policy.
+- Add focused tests or smoke verification for the implemented behavior.
+```

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@soapjs/cli",
+  "version": "1.0.0",
+  "description": "Deterministic project and code generator for SoapJS services.",
+  "homepage": "https://docs.soapjs.com",
+  "repository": "https://github.com/soapjs/soap-cli",
+  "bin": {
+    "soap": "./build/index.js"
+  },
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.17.0"
+  },
+  "author": "Radoslaw Kamysz <radoslaw.kamysz@gmail.com>",
+  "keywords": [
+    "clean",
+    "architecture",
+    "clean architecture",
+    "api design",
+    "framework",
+    "code generation",
+    "framework",
+    "typescript",
+    "microservices",
+    "backend",
+    "cli"
+  ],
+  "scripts": {
+    "clean": "rm -rf ./build",
+    "build": "npm run clean && tsc -b && chmod +x ./build/index.js",
+    "prepublish": "npm run clean && tsc --project tsconfig.build.json"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^3.3.2",
+    "change-case": "^4.1.2",
+    "commander": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^4.5.4"
+  }
+}