@qpqjs/cli 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @qpqjs/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `qpq` command line tool: build, dev, and deploy orchestration for [quidproquo](https://github.com/qpqjs/quidproquo) apps.
+
+An app scaffolded with `create-qpq-app` already depends on this and aliases the common commands in its npm scripts, so `npm run dev` and `npm run deploy` are the usual way in. Everything else you call as `qpq` directly.
+
+```bash
+npm install --save-dev @qpqjs/cli
+npx qpq
+```
+
+Running `qpq` with no command opens an interactive menu. Every command also takes `--app` and `--deployment` (an entry in `apps/<app>/deploy.config.json`).
+
+## Commands
+
+**Local development**
+
+| Command | Does |
+| --- | --- |
+| `qpq go:dev` | Runs the full local stack, api and web, in one process |
+| `qpq go:dev:api` | Just the api dev server, with hot reload |
+| `qpq go:dev:web` | Just the views microfrontend dev servers |
+| `qpq migrate [app]` | Runs pending migrations against the local dev store once, then exits |
+
+**Deploying**
+
+| Command | Does |
+| --- | --- |
+| `qpq setup` | Prepares a cloud environment for its first deploy: checks every step (credentials, IAM, hosted zones, bucket names, CDK bootstrap, then the account, domain and bootstrap stacks with the GitHub OIDC provider and deploy role they create), shows what is already in place, and runs the ones you tick in order. Services are deployed afterwards with `qpq go` or `qpq go:docker`. `--check` only reports, `--yes` runs everything, `--only <ids>` a subset |
+| `qpq go [svc] [stack]` | Deploys services. Interactive unless you pass the positional args |
+| `qpq go:docker` | The same, but deploys in parallel via docker. `--build-only` and `--from-build` split it across machines (see below) |
+| `qpq synth [service]` | Synthesises the configs to `dist/apps/<app>/infrastructure` without deploying |
+| `qpq teardown` | Destroys the web, api, and inf stacks for selected services |
+| `qpq clear-resources` | Empties selected buckets and tables. Data only, stacks are untouched |
+
+For `go`, `svc` is `all`, a comma-separated list, or one of `account`, `domain`, `bootstrap`. `stack` is `all`, `inf`, `api`, `web`, or `views`. A full `all all` or `all api` deploy also publishes federated backends.
+
+**Splitting a docker deploy across machines**
+
+`qpq go:docker` can stop after its build half and resume from the result on another machine, so a CI deploy of a multi-service app can run one job per service and phase while keeping the orders a single `go:docker all all` enforces: every inf stack lands before any api stack, and each api deploy is followed by its federated publish.
+
+| Command | Does |
+| --- | --- |
+| `qpq go:docker <svc> <stack> --build-only` | Builds the app's workspace packages (other apps' are skipped unless this app depends on them), bundles the api, views and federated remote, synthesises the CDK assembly and writes a manifest. No docker needed. AWS credentials are, since `cdk synth` looks up hosted zones and VPCs |
+| `qpq go:docker <svc> <stack> --from-build` | Deploys the chosen stack from that saved build without rebuilding. After `api` it also publishes the federated remote. Needs docker and the same `--deployment`; the workspace does not need to be built |
+
+The build prints the directories that make up each service's saved build: `dist/qpq/go-docker/<app>/<svc>` (the assembly and the manifest), plus `dist/apps/<app>/services/<svc>/views` and `dist/apps/<app>/services/<svc>/service-remote-published` when the service has them. Upload those as the job's artifact. A build made with `all` can deploy any stack. One made with a single stack can only deploy that stack, so a build for `inf` cannot deploy `api` and skip the publish.
+
+The CI shape is a build matrix (`<svc> all --build-only`, one job per service, in parallel), then `<svc> inf --from-build` for every service, then `api` and `web`, then `views`, each job downloading its artifact first. The `qpq:predeploy` hook runs in the build half only. The saved build holds your bundled code and synthesised templates, never credentials; keep the artifact retention short all the same.
+
+`GO_DOCKER_BUILD_CONCURRENCY` caps how many bundles and synths run at once and defaults to the machine's core count. `GO_DOCKER_DEPLOY_CONCURRENCY` caps the deploy containers and defaults to unlimited.
+
+**Federated remotes**
+
+| Command | Does |
+| --- | --- |
+| `qpq publish` | Build, upload, and deploy federated remotes |
+| `qpq publish:build` | Build them locally |
+| `qpq publish:upload` | Upload the built version directories. Nothing goes live |
+| `qpq publish:deploy` | Flip the manifests to the uploaded versions |
+
+Splitting upload from deploy is what makes a rollback a manifest change rather than a redeploy.
+
+**Workspace**
+
+| Command | Does |
+| --- | --- |
+| `qpq prep` | Regenerates `apps/<app>/tsconfig.federated.json` |
+| `qpq script:new <dir>` | Writes a user-script template project: `src/main.ts` exporting functions, built into one `main.js` a service loads from a storage drive with `askUserScriptExecute` |
+| `qpq script:build <dir> [--out <dir>] [--source-map]` | Bundles a user-script project into one file, `dist/main.js` (or `--out`), npm packages folded in, framework packages external, Node builtins refused. No source map unless `--source-map`, which embeds it in `main.js`; a `.map` file is never written. Needs no `npm install` in the project |
+| `qpq script:builder-layer [--arch arm64\|x86_64]` | Installs rspack for the lambda architecture (default arm64, matching `defineJavascriptRuntime`'s default) into the builder layer directory owned by `@qpqjs/user-script`, so a service that registered `defineUserScriptBuilder` can build scripts on lambda. Run it from the app's `qpq:predeploy` hook; it loads no config, since that hook fires before the workspace is built |
+| `qpq check:circular` | Scans workspace sources for circular imports. `--warn` to report without failing |
+| `qpq hooks <name>` | Runs `qpq:<name>` in every app and package that defines it, dependency ordered and in parallel |
+
+## User scripts
+
+A user script is a small TypeScript project (`src/main.ts` exporting functions) that a service loads from a storage drive and calls by name with `askUserScriptExecute`. `qpq script:new` writes one and `qpq script:build` bundles it on your machine. To build on the platform instead, a service registers `defineUserScriptBuilder()` from `@qpqjs/user-script` and calls `askUserScriptBuild` with the source directory and the output file on a drive, or `askUserScriptBuildFromZip` with the project as one zip file; either writes exactly one file, at the path given, which is what `askUserScriptExecute` is then pointed at; on the dev server that just works, and on lambda the service also needs the rspack layer: pass `getUserScriptBuilderApiLayer()` in its api layers and have the app's `qpq:predeploy` hook run `qpq script:builder-layer` (with `--arch x86_64` if the app's lambdas are x86). Both sides use the one directory the package owns, so no path is configured anywhere.
+
+## Platforms
+
+The target platform comes from your app's `deploy.config.json`, so the same commands work whichever one an environment uses. AWS and docker are supported today.
+
+## Status
+
+Pre-1.0. The whole `@qpqjs/*` family releases in lockstep, so versions that share a number were built and tested together. Expect APIs to move between releases, and pin your versions.
+
+## Documentation
+
+[docs.quidproquojs.com](https://docs.quidproquojs.com)
+
+## License
+
+MIT. See [LICENSE](https://github.com/qpqjs/quidproquo/blob/main/LICENSE).

package/docker/cdk-deployer/Dockerfile

@@ -0,0 +1,13 @@
+# Deploy runner for `qpq go:docker`. Containers deploy PRE-SYNTHESIZED
+# cloud assemblies (`cdk deploy --app /assembly <stack>`), so the image needs
+# only the CDK CLI — not the workspace, its npm-linked quidproquo packages, or
+# any platform-specific node_modules.
+#
+# CDK_VERSION is passed at build time to match the workspace's aws-cdk, so the
+# CLI can always read the assembly schema the host synthesized.
+FROM node:24-slim
+
+ARG CDK_VERSION=2
+RUN npm install -g aws-cdk@${CDK_VERSION}
+
+WORKDIR /work

package/docker/dev-server/Dockerfile

@@ -0,0 +1,47 @@
+# Runtime image for `qpq go` on the docker platform: the QPQ dev server
+# (a full local platform emulation — sqlite KVS, file storage, queues,
+# websockets) hosting every service of the app, plus the pre-built views.
+#
+# The server bundle externalizes bare packages (native modules must load from
+# a real install), so runtime deps are npm-installed in the image, then the
+# locally-built quidproquo packages are overlaid so the image runs the same
+# qpq code the bundle was built against.
+FROM node:24-trixie-slim
+
+WORKDIR /app
+
+# Runtime deps (package.json is the consumer root's, with workspaces/scripts
+# stripped by the assemble step). Slow but correct: natives compile for linux.
+# vendor/ must be present before the install: consumers on file: refs have
+# their quidproquo deps rewritten to file:./vendor/<pkg> so npm can resolve
+# them (and their transitive deps) inside the context.
+COPY vendor/ ./vendor/
+COPY package.json ./
+RUN npm install --omit=dev
+
+# Overlay the locally-built quidproquo packages over the installed ones.
+# npm leaves file:./vendor deps as symlinks and registry deps as real
+# directories — rm+cp replaces either shape with the vendored code (a plain
+# COPY cannot write a directory over a symlink).
+RUN set -e; for d in ./vendor/*/; do \
+      [ -d "$d" ] || continue; \
+      pkg="$(basename "$d")"; \
+      rm -rf "./node_modules/$pkg"; \
+      cp -a "$d" "./node_modules/$pkg"; \
+    done
+
+COPY server/ ./server/
+COPY web/ ./web/
+
+ENV QPQ_WEB_ROOT=/app/web
+ENV NODE_ENV=production
+
+# api + site / websocket / file-storage secure urls, then one port per hosted web
+# entry. The build rewrites this line from the app's config.
+EXPOSE 8080 8888 3001
+
+# Emulated platform state (KVS JSON files + file storage) lives here — mount
+# a volume to persist it across container restarts.
+VOLUME /app/.qpq-runtime
+
+CMD ["node", "server/main.js"]

package/lib/commonjs/bin/qpq.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/commonjs/bin/qpq.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_1 = require("../cli");
+(0, cli_1.runCli)(process.argv.slice(2));
+//# sourceMappingURL=qpq.js.map

package/lib/commonjs/bin/qpq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qpq.js","sourceRoot":"","sources":["../../../src/bin/qpq.ts"],"names":[],"mappings":";;;AACA,gCAAgC;AAEhC,IAAA,YAAM,EAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { runCli } from '../cli';\n\nrunCli(process.argv.slice(2));\n"]}

package/lib/commonjs/bin/qpqCdkApp.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/commonjs/bin/qpqCdkApp.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// The CDK app command (`cdk ... --app "node -r ts-node/register/transpile-only <this file>"`).
+// Runs under ts-node hooks so per-app TS config fragments and service
+// infrastructure.ts files can be required directly.
+const deploy_aws_1 = require("@qpqjs/deploy-aws");
+(0, deploy_aws_1.createWorkspaceQpqCdkApp)();
+//# sourceMappingURL=qpqCdkApp.js.map

package/lib/commonjs/bin/qpqCdkApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qpqCdkApp.js","sourceRoot":"","sources":["../../../src/bin/qpqCdkApp.ts"],"names":[],"mappings":";;AAAA,+FAA+F;AAC/F,sEAAsE;AACtE,oDAAoD;AACpD,kDAA6D;AAE7D,IAAA,qCAAwB,GAAE,CAAC","sourcesContent":["// The CDK app command (`cdk ... --app \"node -r ts-node/register/transpile-only <this file>\"`).\n// Runs under ts-node hooks so per-app TS config fragments and service\n// infrastructure.ts files can be required directly.\nimport { createWorkspaceQpqCdkApp } from '@qpqjs/deploy-aws';\n\ncreateWorkspaceQpqCdkApp();\n"]}

package/lib/commonjs/cli/commandMenu.d.ts

@@ -0,0 +1,2 @@
+import { CliCommand } from './commandRegistry';
+export declare const promptCommandFromMenu: (commands: CliCommand[]) => Promise<CliCommand>;

package/lib/commonjs/cli/commandMenu.js

@@ -0,0 +1,81 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptCommandFromMenu = void 0;
+// Interactive drill-down for a bare `qpq`: the colon-separated command names
+// form a tree (go, go:dev, go:dev:api, ...). Each menu level renders its
+// options as the full command line they resolve to (`qpq go:dev:api`) with
+// the command's summary alongside, groups shown as `qpq go:??`, and drilling
+// continues until the user picks a runnable leaf. Rows are deliberately left
+// unstyled so inquirer's active-item highlight colours the whole row.
+const prompts_1 = require("../lib/prompts");
+const lastSegment = (name) => name.split(':').slice(-1)[0];
+// The first path segment of `name` below `prefix` ('' means the tree root).
+const childSegment = (name, prefix) => name.slice(prefix ? prefix.length + 1 : 0).split(':')[0];
+const runRow = (command) => ({
+    label: `qpq ${command.name}`,
+    summary: command.summary,
+    value: { kind: 'run', command },
+});
+const buildRows = (commands, prefix) => {
+    var _a;
+    const exact = prefix ? commands.find((command) => command.name === prefix) : undefined;
+    const deeper = commands.filter((command) => command.name !== prefix && (!prefix || command.name.startsWith(`${prefix}:`)));
+    const segments = [...new Set(deeper.map((command) => childSegment(command.name, prefix)))];
+    const groupRows = [];
+    const leafRows = [];
+    for (const segment of segments) {
+        const segmentPrefix = prefix ? `${prefix}:${segment}` : segment;
+        const subtree = deeper.filter((command) => command.name === segmentPrefix || command.name.startsWith(`${segmentPrefix}:`));
+        if (subtree.length === 1 && subtree[0].name === segmentPrefix) {
+            leafRows.push(runRow(subtree[0]));
+        }
+        else {
+            // A group's summary is its own runnable command's summary when it has
+            // one, otherwise a listing of what's inside.
+            const groupSummary = (_a = subtree.find((command) => command.name === segmentPrefix)) === null || _a === void 0 ? void 0 : _a.summary;
+            groupRows.push({
+                label: `qpq ${segmentPrefix}:??`,
+                summary: groupSummary !== null && groupSummary !== void 0 ? groupSummary : subtree.map((command) => lastSegment(command.name)).join(', '),
+                value: { kind: 'drill', prefix: segmentPrefix },
+            });
+        }
+    }
+    // The current prefix's own command (run what this menu is named after)
+    // leads, then groups, then the remaining runnable commands.
+    const rows = [...(exact ? [runRow(exact)] : []), ...groupRows, ...leafRows];
+    if (prefix) {
+        rows.push({ label: '(back)', value: { kind: 'back' } });
+    }
+    return rows;
+};
+// Align the rows into two columns: the command line, then its summary.
+const toChoices = (rows) => {
+    const columnWidth = Math.max(...rows.map((row) => row.label.length)) + 2;
+    return rows.map((row) => ({
+        name: row.summary ? `${row.label.padEnd(columnWidth)}${row.summary}` : row.label,
+        value: row.value,
+        short: row.label,
+    }));
+};
+// Walk the menu until a runnable command is picked.
+const promptCommandFromMenu = (commands) => __awaiter(void 0, void 0, void 0, function* () {
+    let prefix = '';
+    for (;;) {
+        const picked = yield (0, prompts_1.promptSelectDetailed)('Run:', toChoices(buildRows(commands, prefix)));
+        if (picked.kind === 'run') {
+            return picked.command;
+        }
+        prefix = picked.kind === 'drill' ? picked.prefix : prefix.split(':').slice(0, -1).join(':');
+    }
+});
+exports.promptCommandFromMenu = promptCommandFromMenu;
+//# sourceMappingURL=commandMenu.js.map

package/lib/commonjs/cli/commandMenu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandMenu.js","sourceRoot":"","sources":["../../../src/cli/commandMenu.ts"],"names":[],"mappings":"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","sourcesContent":["// Interactive drill-down for a bare `qpq`: the colon-separated command names\n// form a tree (go, go:dev, go:dev:api, ...). Each menu level renders its\n// options as the full command line they resolve to (`qpq go:dev:api`) with\n// the command's summary alongside, groups shown as `qpq go:??`, and drilling\n// continues until the user picks a runnable leaf. Rows are deliberately left\n// unstyled so inquirer's active-item highlight colours the whole row.\nimport { promptSelectDetailed } from '../lib/prompts';\nimport { CliCommand } from './commandRegistry';\n\ntype MenuChoice = { kind: 'run'; command: CliCommand } | { kind: 'drill'; prefix: string } | { kind: 'back' };\n\ntype MenuRow = { label: string; summary?: string; value: MenuChoice };\n\nconst lastSegment = (name: string): string => name.split(':').slice(-1)[0];\n\n// The first path segment of `name` below `prefix` ('' means the tree root).\nconst childSegment = (name: string, prefix: string): string => name.slice(prefix ? prefix.length + 1 : 0).split(':')[0];\n\nconst runRow = (command: CliCommand): MenuRow => ({\n  label: `qpq ${command.name}`,\n  summary: command.summary,\n  value: { kind: 'run', command },\n});\n\nconst buildRows = (commands: CliCommand[], prefix: string): MenuRow[] => {\n  const exact = prefix ? commands.find((command) => command.name === prefix) : undefined;\n  const deeper = commands.filter((command) => command.name !== prefix && (!prefix || command.name.startsWith(`${prefix}:`)));\n  const segments = [...new Set(deeper.map((command) => childSegment(command.name, prefix)))];\n\n  const groupRows: MenuRow[] = [];\n  const leafRows: MenuRow[] = [];\n\n  for (const segment of segments) {\n    const segmentPrefix = prefix ? `${prefix}:${segment}` : segment;\n    const subtree = deeper.filter((command) => command.name === segmentPrefix || command.name.startsWith(`${segmentPrefix}:`));\n\n    if (subtree.length === 1 && subtree[0].name === segmentPrefix) {\n      leafRows.push(runRow(subtree[0]));\n    } else {\n      // A group's summary is its own runnable command's summary when it has\n      // one, otherwise a listing of what's inside.\n      const groupSummary = subtree.find((command) => command.name === segmentPrefix)?.summary;\n      groupRows.push({\n        label: `qpq ${segmentPrefix}:??`,\n        summary: groupSummary ?? subtree.map((command) => lastSegment(command.name)).join(', '),\n        value: { kind: 'drill', prefix: segmentPrefix },\n      });\n    }\n  }\n\n  // The current prefix's own command (run what this menu is named after)\n  // leads, then groups, then the remaining runnable commands.\n  const rows = [...(exact ? [runRow(exact)] : []), ...groupRows, ...leafRows];\n\n  if (prefix) {\n    rows.push({ label: '(back)', value: { kind: 'back' } });\n  }\n\n  return rows;\n};\n\n// Align the rows into two columns: the command line, then its summary.\nconst toChoices = (rows: MenuRow[]): { name: string; value: MenuChoice; short?: string }[] => {\n  const columnWidth = Math.max(...rows.map((row) => row.label.length)) + 2;\n\n  return rows.map((row) => ({\n    name: row.summary ? `${row.label.padEnd(columnWidth)}${row.summary}` : row.label,\n    value: row.value,\n    short: row.label,\n  }));\n};\n\n// Walk the menu until a runnable command is picked.\nexport const promptCommandFromMenu = async (commands: CliCommand[]): Promise<CliCommand> => {\n  let prefix = '';\n\n  for (;;) {\n    const picked = await promptSelectDetailed<MenuChoice>('Run:', toChoices(buildRows(commands, prefix)));\n\n    if (picked.kind === 'run') {\n      return picked.command;\n    }\n\n    prefix = picked.kind === 'drill' ? picked.prefix : prefix.split(':').slice(0, -1).join(':');\n  }\n};\n"]}

package/lib/commonjs/cli/commandRegistry.d.ts

@@ -0,0 +1,10 @@
+export type CliCommand = {
+    name: string;
+    usageArgs?: string;
+    summary: string;
+    usageExtra?: string[];
+    promptArgs?: () => Promise<string[]>;
+    run: (commandArgv: string[]) => Promise<void>;
+};
+export declare const cliCommands: CliCommand[];
+export declare const buildUsage: () => string;

package/lib/commonjs/cli/commandRegistry.js

@@ -0,0 +1,177 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUsage = exports.cliCommands = void 0;
+// Single source of truth for every qpq command: its name, the one-line
+// summary (shared by `qpq help` and the interactive menu) and a runner.
+//
+// Command modules are required lazily inside each runner so a simple
+// `qpq help` doesn't pay for the whole toolchain, and so ts-node can be
+// registered before any command module (or anything it requires) loads.
+const prompts_1 = require("../lib/prompts");
+// `qpq hooks` needs a hook name; when launched from the menu there is no
+// argv to pass it in, so ask.
+const promptHookName = () => __awaiter(void 0, void 0, void 0, function* () {
+    return [
+        yield (0, prompts_1.promptText)('Hook name (runs qpq:<name>, or plain <name>, in every app/package that defines it):'),
+    ];
+});
+/* eslint-disable @typescript-eslint/no-require-imports */
+exports.cliCommands = [
+    {
+        name: 'go',
+        usageArgs: '[svc] [stack]',
+        summary: 'Deploy services (interactive; platform from the deployment in deploy.config.json).',
+        usageExtra: [
+            'Pass positional args to skip prompts, e.g. qpq go all all — svc is',
+            "'all' | comma-list | account | domain | bootstrap; stack is all|inf|api|web|views.",
+            "A full 'all all' (or 'all api') deploy also publishes federated backends.",
+        ],
+        run: (a) => require('../commands/go').goCommand(a),
+    },
+    {
+        name: 'setup',
+        summary: 'Take a cloud environment from empty to deployed: checked steps, run in order (interactive)',
+        usageExtra: ["--check prints each step's status; --yes runs them all; --only <ids> runs a subset."],
+        run: (a) => require('../commands/setup').setupCommand(a),
+    },
+    {
+        name: 'go:docker',
+        usageArgs: '[svc] [stack]',
+        summary: 'Same as go (incl. positional args), but deploys in parallel via docker',
+        usageExtra: [
+            '--build-only builds and saves everything a deploy needs (no docker needed);',
+            '--from-build deploys the chosen stack from that saved build without rebuilding',
+            '(an api deploy also publishes the federated remote). One CI job per service and phase.',
+        ],
+        run: (a) => require('../commands/goDocker').goDockerCommand(a),
+    },
+    {
+        name: 'go:dev',
+        summary: 'Run the full local dev stack (api + web) in one process',
+        run: (a) => require('../commands/goDev').goDevCommand(a),
+    },
+    {
+        name: 'go:dev:api',
+        summary: 'Run the local API dev server (hot reload)',
+        run: (a) => require('../commands/goDevApi').goDevApiCommand(a),
+    },
+    {
+        name: 'go:dev:web',
+        summary: 'Run every views microfrontend dev server',
+        run: (a) => require('../commands/goDevWeb').goDevWebCommand(a),
+    },
+    {
+        name: 'migrate',
+        usageArgs: '[app]',
+        summary: 'Run pending migrations against the LOCAL dev store, once, then exit.',
+        usageExtra: [
+            'Deployed, migrations run on a stack update; nothing local ever deploys, so',
+            'this is how you exercise one before shipping it. Records what it runs, so a',
+            'second call is a no-op.',
+        ],
+        run: (a) => require('../commands/migrate').migrateCommand(a),
+    },
+    {
+        name: 'teardown',
+        summary: 'Destroy web/api/inf stacks for selected services (interactive)',
+        run: (a) => require('../commands/teardown').teardownCommand(a),
+    },
+    {
+        name: 'clear-resources',
+        summary: 'Empty selected buckets/tables (data only, stacks untouched; interactive)',
+        run: (a) => require('../commands/clearResources').clearResourcesCommand(a),
+    },
+    {
+        name: 'synth',
+        usageArgs: '[service]',
+        summary: 'Synth QPQ configs to dist/apps/<app>/infrastructure',
+        run: (a) => require('../commands/synth').synthCommand(a),
+    },
+    {
+        name: 'prep',
+        summary: 'Regenerate apps/<app>/tsconfig.federated.json',
+        run: (a) => require('../commands/prep').prepCommand(a),
+    },
+    {
+        name: 'publish',
+        summary: 'Build + upload + deploy federated remotes',
+        run: (a) => require('../commands/publish').publishCommand(a),
+    },
+    {
+        name: 'publish:build',
+        summary: 'Build federated remotes locally',
+        run: (a) => require('../commands/publish').publishBuildCommand(a),
+    },
+    {
+        name: 'publish:upload',
+        summary: 'Upload built version dirs (nothing goes live)',
+        run: (a) => require('../commands/publish').publishUploadCommand(a),
+    },
+    {
+        name: 'publish:deploy',
+        summary: 'Flip manifests to the uploaded versions',
+        run: (a) => require('../commands/publish').publishDeployCommand(a),
+    },
+    {
+        name: 'script:new',
+        usageArgs: '<dir>',
+        summary: 'Write a user-script template project (src/main.ts exporting functions) into a new directory',
+        run: (a) => require('../commands/scriptNew').scriptNewCommand(a),
+    },
+    {
+        name: 'script:build',
+        usageArgs: '<dir> [--out <dir>] [--source-map]',
+        summary: 'Bundle a user-script project into one main.js that askUserScriptExecute loads from a drive (--source-map embeds the map in it)',
+        run: (a) => require('../commands/scriptBuild').scriptBuildCommand(a),
+    },
+    {
+        name: 'script:builder-layer',
+        usageArgs: '[--arch arm64|x86_64]',
+        summary: 'Install rspack for the lambda architecture (default arm64) into the user-script builder layer, for services that build user scripts',
+        run: (a) => require('../commands/scriptBuilderLayer').scriptBuilderLayerCommand(a),
+    },
+    {
+        name: 'check:circular',
+        summary: 'Scan workspace sources for circular imports (fails on cycles; --warn to only report)',
+        run: (a) => require('../commands/checkCircular').checkCircularCommand(a),
+    },
+    {
+        name: 'hooks',
+        usageArgs: '<name>',
+        summary: 'Run qpq:<name> (or plain <name>) in every app/package that defines it (dependency ordered, parallel; --jobs=N)',
+        promptArgs: promptHookName,
+        run: (a) => require('../commands/hooks').hooksCommand(a),
+    },
+];
+/* eslint-enable @typescript-eslint/no-require-imports */
+// Width of the "name [args]" column in the usage text.
+const usageColumnWidth = 17;
+const buildUsage = () => {
+    const commandLines = exports.cliCommands.flatMap((command) => {
+        var _a;
+        const nameAndArgs = command.usageArgs ? `${command.name} ${command.usageArgs}` : command.name;
+        const extraLines = ((_a = command.usageExtra) !== null && _a !== void 0 ? _a : []).map((line) => `  ${''.padEnd(usageColumnWidth)}${line}`);
+        return [`  ${nameAndArgs.padEnd(usageColumnWidth)}${command.summary}`, ...extraLines];
+    });
+    return [
+        'qpq — build, dev and deploy orchestration for QPQ apps',
+        '',
+        'Usage: qpq <command> [--app <name>] [--deployment <name>]',
+        '       qpq            (no command opens an interactive menu)',
+        '',
+        'Commands:',
+        ...commandLines,
+        '',
+    ].join('\n');
+};
+exports.buildUsage = buildUsage;
+//# sourceMappingURL=commandRegistry.js.map

package/lib/commonjs/cli/commandRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandRegistry.js","sourceRoot":"","sources":["../../../src/cli/commandRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["// Single source of truth for every qpq command: its name, the one-line\n// summary (shared by `qpq help` and the interactive menu) and a runner.\n//\n// Command modules are required lazily inside each runner so a simple\n// `qpq help` doesn't pay for the whole toolchain, and so ts-node can be\n// registered before any command module (or anything it requires) loads.\nimport { promptText } from '../lib/prompts';\n\nexport type CliCommand = {\n  name: string;\n  // Argument hint shown in the usage text, e.g. '[svc] [stack]'.\n  usageArgs?: string;\n  summary: string;\n  // Extra usage-only detail lines, indented under the summary.\n  usageExtra?: string[];\n  // Menu-only: commands that need a positional argument (which the menu has\n  // no argv to carry) gather it here before running.\n  promptArgs?: () => Promise<string[]>;\n  run: (commandArgv: string[]) => Promise<void>;\n};\n\n// `qpq hooks` needs a hook name; when launched from the menu there is no\n// argv to pass it in, so ask.\nconst promptHookName = async (): Promise<string[]> => [\n  await promptText('Hook name (runs qpq:<name>, or plain <name>, in every app/package that defines it):'),\n];\n\n/* eslint-disable @typescript-eslint/no-require-imports */\nexport const cliCommands: CliCommand[] = [\n  {\n    name: 'go',\n    usageArgs: '[svc] [stack]',\n    summary: 'Deploy services (interactive; platform from the deployment in deploy.config.json).',\n    usageExtra: [\n      'Pass positional args to skip prompts, e.g. qpq go all all — svc is',\n      \"'all' | comma-list | account | domain | bootstrap; stack is all|inf|api|web|views.\",\n      \"A full 'all all' (or 'all api') deploy also publishes federated backends.\",\n    ],\n    run: (a) => require('../commands/go').goCommand(a),\n  },\n  {\n    name: 'setup',\n    summary: 'Take a cloud environment from empty to deployed: checked steps, run in order (interactive)',\n    usageExtra: [\"--check prints each step's status; --yes runs them all; --only <ids> runs a subset.\"],\n    run: (a) => require('../commands/setup').setupCommand(a),\n  },\n  {\n    name: 'go:docker',\n    usageArgs: '[svc] [stack]',\n    summary: 'Same as go (incl. positional args), but deploys in parallel via docker',\n    usageExtra: [\n      '--build-only builds and saves everything a deploy needs (no docker needed);',\n      '--from-build deploys the chosen stack from that saved build without rebuilding',\n      '(an api deploy also publishes the federated remote). One CI job per service and phase.',\n    ],\n    run: (a) => require('../commands/goDocker').goDockerCommand(a),\n  },\n  {\n    name: 'go:dev',\n    summary: 'Run the full local dev stack (api + web) in one process',\n    run: (a) => require('../commands/goDev').goDevCommand(a),\n  },\n  {\n    name: 'go:dev:api',\n    summary: 'Run the local API dev server (hot reload)',\n    run: (a) => require('../commands/goDevApi').goDevApiCommand(a),\n  },\n  {\n    name: 'go:dev:web',\n    summary: 'Run every views microfrontend dev server',\n    run: (a) => require('../commands/goDevWeb').goDevWebCommand(a),\n  },\n  {\n    name: 'migrate',\n    usageArgs: '[app]',\n    summary: 'Run pending migrations against the LOCAL dev store, once, then exit.',\n    usageExtra: [\n      'Deployed, migrations run on a stack update; nothing local ever deploys, so',\n      'this is how you exercise one before shipping it. Records what it runs, so a',\n      'second call is a no-op.',\n    ],\n    run: (a) => require('../commands/migrate').migrateCommand(a),\n  },\n  {\n    name: 'teardown',\n    summary: 'Destroy web/api/inf stacks for selected services (interactive)',\n    run: (a) => require('../commands/teardown').teardownCommand(a),\n  },\n  {\n    name: 'clear-resources',\n    summary: 'Empty selected buckets/tables (data only, stacks untouched; interactive)',\n    run: (a) => require('../commands/clearResources').clearResourcesCommand(a),\n  },\n  {\n    name: 'synth',\n    usageArgs: '[service]',\n    summary: 'Synth QPQ configs to dist/apps/<app>/infrastructure',\n    run: (a) => require('../commands/synth').synthCommand(a),\n  },\n  {\n    name: 'prep',\n    summary: 'Regenerate apps/<app>/tsconfig.federated.json',\n    run: (a) => require('../commands/prep').prepCommand(a),\n  },\n  {\n    name: 'publish',\n    summary: 'Build + upload + deploy federated remotes',\n    run: (a) => require('../commands/publish').publishCommand(a),\n  },\n  {\n    name: 'publish:build',\n    summary: 'Build federated remotes locally',\n    run: (a) => require('../commands/publish').publishBuildCommand(a),\n  },\n  {\n    name: 'publish:upload',\n    summary: 'Upload built version dirs (nothing goes live)',\n    run: (a) => require('../commands/publish').publishUploadCommand(a),\n  },\n  {\n    name: 'publish:deploy',\n    summary: 'Flip manifests to the uploaded versions',\n    run: (a) => require('../commands/publish').publishDeployCommand(a),\n  },\n  {\n    name: 'script:new',\n    usageArgs: '<dir>',\n    summary: 'Write a user-script template project (src/main.ts exporting functions) into a new directory',\n    run: (a) => require('../commands/scriptNew').scriptNewCommand(a),\n  },\n  {\n    name: 'script:build',\n    usageArgs: '<dir> [--out <dir>] [--source-map]',\n    summary: 'Bundle a user-script project into one main.js that askUserScriptExecute loads from a drive (--source-map embeds the map in it)',\n    run: (a) => require('../commands/scriptBuild').scriptBuildCommand(a),\n  },\n  {\n    name: 'script:builder-layer',\n    usageArgs: '[--arch arm64|x86_64]',\n    summary: 'Install rspack for the lambda architecture (default arm64) into the user-script builder layer, for services that build user scripts',\n    run: (a) => require('../commands/scriptBuilderLayer').scriptBuilderLayerCommand(a),\n  },\n  {\n    name: 'check:circular',\n    summary: 'Scan workspace sources for circular imports (fails on cycles; --warn to only report)',\n    run: (a) => require('../commands/checkCircular').checkCircularCommand(a),\n  },\n  {\n    name: 'hooks',\n    usageArgs: '<name>',\n    summary: 'Run qpq:<name> (or plain <name>) in every app/package that defines it (dependency ordered, parallel; --jobs=N)',\n    promptArgs: promptHookName,\n    run: (a) => require('../commands/hooks').hooksCommand(a),\n  },\n];\n/* eslint-enable @typescript-eslint/no-require-imports */\n\n// Width of the \"name [args]\" column in the usage text.\nconst usageColumnWidth = 17;\n\nexport const buildUsage = (): string => {\n  const commandLines = cliCommands.flatMap((command) => {\n    const nameAndArgs = command.usageArgs ? `${command.name} ${command.usageArgs}` : command.name;\n    const extraLines = (command.usageExtra ?? []).map((line) => `  ${''.padEnd(usageColumnWidth)}${line}`);\n    return [`  ${nameAndArgs.padEnd(usageColumnWidth)}${command.summary}`, ...extraLines];\n  });\n\n  return [\n    'qpq — build, dev and deploy orchestration for QPQ apps',\n    '',\n    'Usage: qpq <command> [--app <name>] [--deployment <name>]',\n    '       qpq            (no command opens an interactive menu)',\n    '',\n    'Commands:',\n    ...commandLines,\n    '',\n  ].join('\\n');\n};\n"]}

package/lib/commonjs/cli/index.d.ts

@@ -0,0 +1 @@
+export * from './runCli';

package/lib/commonjs/cli/index.js

@@ -0,0 +1,18 @@
+"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("./runCli"), exports);
+//# sourceMappingURL=index.js.map

package/lib/commonjs/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB","sourcesContent":["export * from './runCli';\n"]}

package/lib/commonjs/cli/runCli.d.ts

@@ -0,0 +1 @@
+export declare const runCli: (argv: string[]) => Promise<void>;

package/lib/commonjs/cli/runCli.js

@@ -0,0 +1,86 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCli = void 0;
+const commandMenu_1 = require("./commandMenu");
+const commandRegistry_1 = require("./commandRegistry");
+// Service infrastructure.ts files (and app config fragments) are TypeScript —
+// register ts-node's transpile-only require hook so the CLI can require them
+// directly, using the consumer root's tsconfig.json ts-node settings.
+//
+// CONTRACT: JavaScript apps (create-qpq-app --language javascript) also lean
+// on this hook — their tsconfig.json ts-node block sets allowJs (so their
+// ESM-syntax infrastructure.js compiles at require time) and scope/scopeDir
+// (so the hook never touches quidproquo libs outside the app). Any
+// replacement for ts-node here must honour those consumer tsconfig options.
+const registerTsNode = () => {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require('ts-node').register({ transpileOnly: true });
+};
+// Inquirer throws ExitPromptError on ctrl-c; treat that as a quiet exit
+// rather than a command failure.
+const isPromptExit = (error) => error instanceof Error && error.name === 'ExitPromptError';
+// Bare `qpq` on a terminal: drill through the command menu, gathering any
+// arguments the picked command needs. Returns null when the user bails out.
+const resolveCommandInteractively = () => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const command = yield (0, commandMenu_1.promptCommandFromMenu)(commandRegistry_1.cliCommands);
+        const commandArgv = command.promptArgs ? yield command.promptArgs() : [];
+        return { command, commandArgv };
+    }
+    catch (error) {
+        if (isPromptExit(error)) {
+            return null;
+        }
+        throw error;
+    }
+});
+const runCli = (argv) => __awaiter(void 0, void 0, void 0, function* () {
+    const [commandName, ...argvRest] = argv;
+    if (commandName === 'help' || commandName === '--help') {
+        console.log((0, commandRegistry_1.buildUsage)());
+        return;
+    }
+    let command;
+    let commandArgv = [];
+    if (!commandName) {
+        // Only prompt on a real terminal; piped/CI invocations get the usage text.
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            console.log((0, commandRegistry_1.buildUsage)());
+            return;
+        }
+        const resolved = yield resolveCommandInteractively();
+        if (!resolved) {
+            return;
+        }
+        ({ command, commandArgv } = resolved);
+    }
+    else {
+        command = commandRegistry_1.cliCommands.find((c) => c.name === commandName);
+        commandArgv = argvRest;
+        if (!command) {
+            console.error(`Unknown command: ${commandName}`);
+            console.log((0, commandRegistry_1.buildUsage)());
+            process.exitCode = 1;
+            return;
+        }
+    }
+    registerTsNode();
+    try {
+        yield command.run(commandArgv);
+    }
+    catch (error) {
+        console.error(`qpq ${command.name} failed:`, error);
+        process.exitCode = 1;
+    }
+});
+exports.runCli = runCli;
+//# sourceMappingURL=runCli.js.map