@codemation/cli

The Codemation command-line package: parse arguments, wire a small composition root, and run build, dev, serve, and user subcommands against a consumer project (your app that defines codemation.config.ts and workflows).

It is intentionally thin: no DI container. CliProgramFactory is the single place the object graph is constructed; command classes receive dependencies via constructors.

How it fits in the monorepo

The CLI orchestrates other packages. It does not embed the full Next UI or engine, but it now owns the dev runtime control plane directly instead of delegating dev hot-swap to separate workspace packages.

  Consumer project (your repo)
  ├── codemation.config.ts
  ├── src/workflows/…
  └── .codemation/output/
      ├── build/              ← emitted JS + index.js (after promote)
      ├── staging/…           ← transient during a build
      └── current.json        ← manifest (from publish step, not from ensureBuilt alone)
           ▲
           │ paths + env
           │
  ┌────────┴────────────────────────────────────────────────────────────┐
  │                        @codemation/cli                                │
  │                                                                       │
  │   bin/codemation.js                                                   │
  │        │                                                              │
  │        ▼                                                              │
  │   CliBin.run()                                                        │
  │        │                                                              │
  │        ▼                                                              │
  │   CliProgramFactory.create()  ──►  CliProgram.run()  (Commander.js)  │
  │        │                              │                               │
  │        │                              ├── build    → BuildCommand     │
  │        │                              ├── dev      → DevCommand       │
  │        │                              ├── serve web  → ServeWebCommand│
  │        │                              ├── serve worker → ServeWorker… │
  │        │                              └── user create → UserCreate…   │
  │        │                                                              │
  └────────┼────────────────────────────────────────────────────────────┘
           │
           │  uses / spawns
           ▼
  ┌────────────────────┬─────────────────────┬────────────────────────────┐
  │ @codemation/host   │ @codemation/next-host│ CLI-owned dev runtime     │
  │ (plugin discovery, │ (production:        │ (stable proxy +           │
  │  logging, workflow │  `pnpm exec next    │  disposable API runtime)  │
  │  path helpers)     │   start` cwd)      │                            │
  └─────────┬──────────┴──────────┬──────────┴─────────────┬────────────────┘
            │                     │                      │
            │                     │                      │
            ▼                     │                      ▼
  ┌───────────────────┐           │            ┌─────────────────────┐
  │ Engine & types     │           │            │ Worker runtime      │
  │ via host (not a    │           │            │ via CLI + host      │
  │ direct cli dep)    │           │            │ (`serve worker`)    │
  └───────────────────┘           │            └─────────────────────┘

Reading the diagram

• Vertical flow: the binary loads CliProgramFactory, builds CliProgram, then Commander dispatches to a command class (commands/*).
• Horizontal row: shared libraries the CLI imports for discovery, logging, and path logic; next-host is where serve web runs the production Next server; the CLI now also owns the stable dev proxy and disposable in-process API runtime used by codemation dev. serve worker stays inside the CLI/host container flow instead of delegating to a separate worker package.
• Consumer tree: ConsumerOutputBuilder is now a production-oriented emission step for codemation build; dev and serve web load consumer config directly instead of going through published manifests.

For default consumer dev vs framework UI watch mode (codemation dev vs codemation dev --watch-framework), see docs/development-modes.md at the repo root.

Entry points

| Entry | Role | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bin/codemation.js (package "bin") | Production entry: loads reflect-metadata, runs CliBin. | | src/bin.ts | Bundled bin artifact used by tsdown for the same behavior. | | Programmatic | Import CliProgramFactory and create(), or compose CliProgram with test doubles. Public exports are in src/index.ts. |

Commands (overview)

| Command | Purpose | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | codemation dev (default) | Dev session: ports, lock, packaged UI proxy, stable CLI-owned dev endpoint, watch consumer sources, and hot-swap a disposable in-process API runtime on change. | | codemation dev --watch-framework | Framework-author dev session: same runtime/proxy flow, but runs next dev for @codemation/next-host UI HMR. | | codemation build | Emit consumer output under .codemation/output/build for production-oriented packaging flows. | | codemation serve web | Start next start from @codemation/next-host; the host loads consumer config directly and fetches runtime bootstrap contracts instead of consuming a published manifest. | | codemation serve worker | Load AppConfig, build the app container in-process, and start the configured queue-backed worker runtime. | | codemation user create | Create/update a DB user when auth is local (uses consumer config / DATABASE_URL). Dispatches UpsertLocalBootstrapUserCommand via the host CommandBus (password minimum 8 characters, same as invite acceptance). | | codemation user list | List users via ListUserAccountsQuery and the host QueryBus (same auth/DB requirements as user create). |

Programmatic bootstrap: CodemationCliApplicationSession builds an app container for command/query access (no HTTP/WebSocket servers); migrations and startup side effects remain explicit after container creation.

Use codemation --help and codemation <command> --help for flags (--consumer-root, build targets, etc.).

Consumer build pipeline (summary)

1. ConsumerOutputBuilder.ensureBuilt() discovers config and workflows, transpiles with TypeScript, stages under .codemation/output/staging/<version>-<uuid>/, then renames to .codemation/output/build/ (atomic promote).
2. Watch (dev): debounced chokidar rebuilds; incremental builds copy forward from the last promoted build/ when possible.
3. Consume: the Next host no longer depends on published current.json manifests for dev or serve web; it loads consumer config directly and exposes bootstrap contracts from the prepared runtime.

Production-oriented build flags

codemation build and codemation serve web (consumer build step) accept:

| Flag | Purpose | | ----------------------------- | ------------------------------------------------------------- | | --no-source-maps | Omit .js.map next to emitted workflow modules. | | --target es2020 | es2022 | ECMAScript target for emitted workflow JS (default es2022). |

Programmatically, map the same flags with ConsumerBuildOptionsParser or pass ConsumerBuildOptions into ConsumerOutputBuilder.

Tests

Unit tests live under test/ (Vitest).

pnpm --filter @codemation/cli test

From the repository root they are also included in the shared unit suite:

pnpm run test:unit

What is covered

• ConsumerBuildOptionsParser: maps CLI flags (--no-source-maps, --target) to ConsumerBuildOptions.
• ConsumerOutputBuilder + build options: default build emits .js.map for transpiled workflows; sourceMaps: false omits them.
• ConsumerOutputBuilder
  • Full build (ensureBuilt): stage under .codemation/output/staging/…, then promote to .codemation/output/build/.
  • Watch + incremental: after a full build, a single workflow file change triggers a rebuild promoted to the same build/ path (chokidar + debounce; tests set CHOKIDAR_USEPOLLING).

Tests use a temporary consumer fixture (codemation.config.ts + src/workflows) and do not mock TypeScript transpilation or host discovery helpers.