@stjoseph/prumo 0.0.3 → 0.0.6

package/README.md

@@ -31,7 +31,7 @@ workspace holding four applications, without either one carrying rules it has no
 
 ## Requirements
 
-Node 22.17 or later, pnpm, and Docker for anything with an API.
+Node 22.17 or later, pnpm, and Docker for anything with an API. `prumo doctor` checks all of it.
 
 ## Running it
 
@@ -62,6 +62,21 @@ npx @stjoseph/prumo new my-app --types api,web --single-tenant
 | `--multi-tenant` or `--single-tenant` | Whether the application serves several tenants |
 | `--skip-install` | Stops after writing the files |
 
+## Commands
+
+| Command | What it does |
+|---|---|
+| `prumo new [name]` | Generates a project |
+| `prumo db` | Inside a project with an API: creates the development database in Docker and writes its URL into `.env` |
+| `prumo clean` | Removes what the project needed only once, today the database setup, once the database exists |
+| `prumo doctor` | Checks Node, pnpm, git and Docker on this machine |
+| `prumo version` · `--version` · `-v` | Prints the CLI version |
+| `prumo help [command]` · `--help` | Lists the commands, or describes one |
+
+Every command takes `--json`: stdout then holds exactly one document, `{ "ok": true, "command", "data" }` or
+`{ "ok": false, "command", "error": { "code", "message" } }`, anything written for a person goes to stderr, nothing
+is asked, and the exit code is 0 only when `ok` is true.
+
 ## What it generates
 
 | Type | What you get |
@@ -105,11 +120,17 @@ Once written, those documents belong to the team. Prumo does not come back and r
 | [`docs/DECISIONS.md`](https://github.com/stjosephworks/prumo/blob/main/docs/DECISIONS.md) | Every decision, why it won, and what it costs |
 | [`docs/OPEN-QUESTIONS.md`](https://github.com/stjosephworks/prumo/blob/main/docs/OPEN-QUESTIONS.md) | What has been raised and is still unresolved |
 
+## Releasing
+
+`main` publishes itself. A push to `main` runs the whole CI, and when `cli/package.json` carries a version the
+registry does not have yet, the `publish` job sends it to npm through npm's trusted publishing, with provenance and
+without a token in the repository. Any other push to `main` publishes nothing.
+
 ## Status
 
 Prumo is in beta. `0.0.1` is the first published version: every template runs and every generated
 project is verified in CI, and what a generated project looks like can still change before 1.0.
 What is known to be missing is listed in [`docs/OPEN-QUESTIONS.md`](https://github.com/stjosephworks/prumo/blob/main/docs/OPEN-QUESTIONS.md), and
-`prumo new` is the only command. Updating a project's `.prumo/` in place comes after 1.0.
+updating a project's `.prumo/` in place comes after 1.0.
 
 MIT licensed. See [`LICENSE`](https://github.com/stjosephworks/prumo/blob/main/LICENSE).

package/dist/clean.js

@@ -0,0 +1,135 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile, rm, rmdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { apiPath, findProjectRoot } from "./database.js";
+import { readJsonc, setJsonc } from "./jsonc.js";
+import { CliError } from "./output.js";
+const SAMPLE_URL = 'postgresql://app:app@localhost:5432/app';
+export const API_DEV_PREFIX = 'node scripts/database.mjs --check && ';
+export const ROOT_DEV_PREFIX = 'node apps/api/scripts/database.mjs --check && ';
+export const SETUP_SCRIPT = 'node scripts/database.mjs';
+export const EXAMPLE_BLOCK = '# MISSING until `pnpm db:setup` creates a database; `pnpm dev` offers to run it.\n' +
+    'DATABASE_URL=MISSING\nAUTH_DATABASE_URL=MISSING\n';
+export const README_PARAGRAPH = '`DATABASE_URL` starts as `MISSING`. While it is, `pnpm dev` offers to create the database first: it asks for a name,\n' +
+    'starts Postgres from `docker-compose.yml` on port 5432 or the next free one (kept in `POSTGRES_PORT`), writes the URL\n' +
+    'into `.env`, and migrates. `pnpm db:setup` does the same at any time. Without a terminal every answer comes from a\n' +
+    'flag: `--name`, `--port`, `--skip-migrate`, and `--json` for one JSON result on stdout.\n';
+const README_REPLACEMENT = 'Before the first `pnpm dev`, start Postgres with `docker compose up -d --wait` and run `pnpm db:migrate`.\n' +
+    '`.env.example` points at that service on port 5432; when `POSTGRES_PORT` changes, change both URLs with it.\n';
+export const README_ROW = '| `pnpm db:setup` | Creates a development database in Docker, writes its URL into `.env`, and migrates |\n';
+export const WORKSPACE_SENTENCE = 'If the workspace holds `api` and its database is not set up yet, `pnpm dev` offers to create the database first.\n\n';
+function textRule(id, file, description, from, to, marker) {
+    return {
+        id,
+        file,
+        description,
+        inspect: (text) => text.includes(from) ? 'pending' : text.includes(marker) ? 'modified' : 'absent',
+        change: (text) => text.replace(from, to),
+    };
+}
+function scriptRule(id, file, description, key, decide) {
+    const scriptOf = (text) => readJsonc(text).scripts?.[key];
+    return {
+        id,
+        file,
+        description,
+        inspect: (text) => {
+            const value = scriptOf(text);
+            return value === undefined ? 'absent' : decide(value).status;
+        },
+        change: (text) => setJsonc(text, ['scripts', key], decide(scriptOf(text) ?? '').next),
+    };
+}
+function devRule(id, file, prefix) {
+    return scriptRule(id, file, `Stop checking the database before \`dev\``, 'dev', (value) => value.startsWith(prefix)
+        ? { status: 'pending', next: value.slice(prefix.length) }
+        : { status: value.includes('database.mjs') ? 'modified' : 'absent', next: value });
+}
+function rulesFor(root, api, templates) {
+    const at = (file) => relative(root, join(api, file));
+    const rules = [
+        devRule('api-dev-check', at('package.json'), API_DEV_PREFIX),
+        scriptRule('api-db-setup', at('package.json'), 'Remove the `db:setup` script', 'db:setup', (value) => value === SETUP_SCRIPT ? { status: 'pending' } : { status: 'modified', next: value }),
+        textRule('api-env-example', at('.env.example'), 'Put a sample database URL back in `.env.example`', EXAMPLE_BLOCK, `DATABASE_URL=${SAMPLE_URL}\nAUTH_DATABASE_URL=${SAMPLE_URL}\n`, '=MISSING'),
+        textRule('api-readme-setup', at('README.md'), 'Replace the README paragraph about `MISSING`', README_PARAGRAPH, README_REPLACEMENT, 'db:setup'),
+        textRule('api-readme-row', at('README.md'), 'Remove `db:setup` from the README', README_ROW, '', '`pnpm db:setup`'),
+    ];
+    if (api !== root) {
+        rules.push(devRule('root-dev-check', 'package.json', ROOT_DEV_PREFIX), textRule('root-readme', 'README.md', 'Remove the database offer from the README', WORKSPACE_SENTENCE, '', 'offers to create the database'));
+    }
+    return { rules, script: join(templates, 'api', 'scripts', 'database.mjs') };
+}
+export async function planClean({ cwd, templates, force, }) {
+    const root = findProjectRoot(cwd);
+    const api = apiPath(root);
+    if (api === undefined) {
+        return { root, items: [], apply: async () => { } };
+    }
+    const env = await readFile(join(api, '.env'), 'utf8').catch(() => undefined);
+    if (!force && env !== undefined && /^DATABASE_URL=MISSING$/m.test(env)) {
+        throw new CliError('database_missing', 'DATABASE_URL is still MISSING: set the database up before removing what sets it up, or pass --force.');
+    }
+    const { rules, script } = rulesFor(root, api, templates);
+    const items = [];
+    const pending = [];
+    for (const rule of rules) {
+        const text = await readFile(join(root, rule.file), 'utf8').catch(() => undefined);
+        const status = text === undefined ? 'absent' : rule.inspect(text);
+        items.push({ id: rule.id, path: rule.file, description: rule.description, status });
+        if (status === 'pending') {
+            pending.push(rule);
+        }
+    }
+    const scriptPath = join(api, 'scripts', 'database.mjs');
+    const shipped = await readFile(script, 'utf8');
+    const current = await readFile(scriptPath, 'utf8').catch(() => undefined);
+    const scriptItem = {
+        id: 'api-database-script',
+        path: relative(root, scriptPath),
+        description: 'Delete the database setup script',
+        status: current === undefined ? 'absent' : current === shipped ? 'pending' : 'modified',
+    };
+    items.push(scriptItem);
+    return {
+        root,
+        items,
+        apply: async () => {
+            for (const rule of pending) {
+                const path = join(root, rule.file);
+                await writeFile(path, rule.change(await readFile(path, 'utf8')));
+            }
+            if (scriptItem.status === 'pending') {
+                await rm(scriptPath);
+                if (existsSync(dirname(scriptPath)) && (await readdir(dirname(scriptPath))).length === 0) {
+                    await rmdir(dirname(scriptPath));
+                }
+            }
+            for (const item of items) {
+                if (item.status === 'pending') {
+                    item.status = 'removed';
+                }
+            }
+        },
+    };
+}
+const SYMBOL = {
+    pending: '-',
+    removed: '✓',
+    modified: '!',
+    absent: '·',
+};
+export function cleanText(items) {
+    if (items.length === 0) {
+        return 'Nothing to clean.';
+    }
+    return items
+        .map((item) => {
+        const note = item.status === 'modified'
+            ? ' (changed since generated; kept)'
+            : item.status === 'absent'
+                ? ' (already gone)'
+                : '';
+        return `${SYMBOL[item.status]} ${item.description}: ${item.path}${note}`;
+    })
+        .join('\n');
+}

package/dist/cli.js

@@ -1,16 +1,36 @@
 #!/usr/bin/env node
-import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import * as prompt from '@clack/prompts';
 import { terminalAsker } from "./asker.js";
 import { assetsFor, requireAssets } from "./assets.js";
+import { cleanText, planClean } from "./clean.js";
+import { COMMANDS, findCommand, helpText } from "./commands.js";
+import { runDatabase } from "./database.js";
+import { doctor, doctorText } from "./doctor.js";
 import { generate } from "./generate.js";
 import { validateProjectName } from "./names.js";
+import { CliError, errorEnvelope, writeEnvelope } from "./output.js";
 import { resolveAnswers } from "./questions.js";
-const USAGE = `Usage: prumo new [name] [--types api,web,mobile,site] [--alone | --monorepo]
-                  [--multi-tenant | --single-tenant] [--skip-install]`;
-async function main() {
+function version() {
+    // src/cli.ts and dist/cli.js both sit one level below package.json.
+    const pkg = JSON.parse(readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf8'));
+    return pkg.version;
+}
+function help(name) {
+    if (name === undefined) {
+        return { data: { commands: COMMANDS }, text: helpText() };
+    }
+    const command = findCommand(name);
+    if (command === undefined) {
+        throw new CliError('unknown_command', `Unknown command "${name}". Run \`prumo help\`.`);
+    }
+    return { data: { commands: [command] }, text: helpText(command) };
+}
+async function runNew(args, json) {
     const { values, positionals } = parseArgs({
+        args,
         allowPositionals: true,
         options: {
             types: { type: 'string' },
@@ -19,15 +39,14 @@ async function main() {
             'multi-tenant': { type: 'boolean', default: false },
             'single-tenant': { type: 'boolean', default: false },
             'skip-install': { type: 'boolean', default: false },
-            help: { type: 'boolean', default: false },
+            json: { type: 'boolean', default: false },
         },
     });
-    const [command, name] = positionals;
-    if (values.help || command !== 'new') {
-        console.log(USAGE);
-        process.exit(values.help ? 0 : 1);
+    const [name, ...extra] = positionals;
+    if (extra.length > 0) {
+        throw new CliError('usage', `Unexpected argument: ${extra.join(' ')}`);
     }
-    const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+    const interactive = !json && process.stdin.isTTY === true && process.stdout.isTTY === true;
     const answers = await resolveAnswers({
         name,
         types: values.types,
@@ -36,19 +55,120 @@ async function main() {
         multiTenant: values['multi-tenant'],
         singleTenant: values['single-tenant'],
     }, interactive ? terminalAsker(validateProjectName) : undefined);
-    if (answers.types.length > 1) {
+    if (!json && answers.types.length > 1) {
         prompt.log.info(`${answers.types.length} types make a workspace: apps/ and packages/ under one root.`);
     }
-    const here = import.meta.dirname;
+    const target = resolve(answers.name);
+    const install = !values['skip-install'];
     await generate({
-        ...requireAssets(assetsFor(here)),
-        target: resolve(answers.name),
+        ...requireAssets(assetsFor(import.meta.dirname)),
+        target,
         answers,
-        install: !values['skip-install'],
+        install,
+        childOutput: json ? 'stderr' : 'inherit',
+    });
+    if (!json) {
+        prompt.outro(`Created ${answers.name}.`);
+    }
+    return { data: { ...answers, target, installed: install }, text: '' };
+}
+async function runClean(args, json) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            'dry-run': { type: 'boolean', default: false },
+            yes: { type: 'boolean', default: false },
+            force: { type: 'boolean', default: false },
+            json: { type: 'boolean', default: false },
+        },
+    });
+    const plan = await planClean({
+        cwd: process.cwd(),
+        templates: requireAssets(assetsFor(import.meta.dirname)).templates,
+        force: values.force,
     });
-    prompt.outro(`Created ${answers.name}.`);
+    const pending = plan.items.some((item) => item.status === 'pending');
+    const result = (applied) => ({
+        data: { root: plan.root, dryRun: values['dry-run'], applied, items: plan.items },
+        text: cleanText(plan.items),
+    });
+    if (!pending || values['dry-run']) {
+        return result(false);
+    }
+    if (!values.yes) {
+        const interactive = !json && process.stdin.isTTY === true && process.stdout.isTTY === true;
+        if (!interactive) {
+            throw new CliError('needs_input', 'Outside an interactive terminal, pass --yes to clean.');
+        }
+        console.log(cleanText(plan.items));
+        const confirmed = await prompt.confirm({ message: 'Remove these?', initialValue: false });
+        if (prompt.isCancel(confirmed) || !confirmed) {
+            throw new CliError('declined', 'Nothing was removed.');
+        }
+    }
+    await plan.apply();
+    return result(true);
+}
+async function main(argv) {
+    const json = argv.includes('--json');
+    const index = argv.findIndex((arg) => !arg.startsWith('-'));
+    const command = index === -1 ? undefined : argv[index];
+    const args = index === -1 ? [] : argv.slice(index + 1);
+    const wantsHelp = argv.includes('--help') || argv.includes('-h');
+    const name = command ?? (argv.includes('--version') || argv.includes('-v') ? 'version' : 'help');
+    try {
+        let result;
+        if (wantsHelp && command !== undefined && command !== 'help') {
+            result = help(command);
+        }
+        else if (name === 'help') {
+            const [topic] = args.filter((arg) => !arg.startsWith('-'));
+            result = help(topic);
+        }
+        else if (name === 'version') {
+            const current = version();
+            result = { data: { version: current }, text: current };
+        }
+        else if (name === 'doctor') {
+            const report = await doctor();
+            if (!report.ready) {
+                throw new CliError('not_ready', 'This machine is missing something Prumo needs.', report);
+            }
+            result = { data: report, text: doctorText(report) };
+        }
+        else if (name === 'db') {
+            // The script writes its own output, --json included.
+            process.exitCode = runDatabase(args, process.cwd());
+            return;
+        }
+        else if (name === 'clean') {
+            result = await runClean(args, json);
+        }
+        else if (name === 'new') {
+            result = await runNew(args, json);
+        }
+        else {
+            throw new CliError('unknown_command', `Unknown command "${name}". Run \`prumo help\`.`);
+        }
+        if (json) {
+            writeEnvelope({ ok: true, command: name, data: result.data });
+        }
+        else if (result.text !== '') {
+            console.log(result.text);
+        }
+    }
+    catch (error) {
+        const envelope = errorEnvelope(name, error);
+        if (json) {
+            writeEnvelope(envelope);
+        }
+        else if (error instanceof CliError && error.code === 'not_ready') {
+            console.error(doctorText(error.data));
+        }
+        else {
+            console.error(envelope.ok ? '' : envelope.error.message);
+        }
+        process.exitCode = 1;
+    }
 }
-main().catch((error) => {
-    console.error(error instanceof Error ? error.message : error);
-    process.exit(1);
-});
+await main(process.argv.slice(2));

package/dist/commands.js

@@ -0,0 +1,80 @@
+const JSON_OPTION = {
+    flag: '--json',
+    description: 'Print one JSON document on stdout and never prompt',
+};
+export const COMMANDS = [
+    {
+        name: 'new',
+        usage: 'prumo new [name] [options]',
+        summary: 'Generate a project and the .prumo/ context it follows',
+        options: [
+            { flag: '--types <list>', description: 'Comma-separated: api, web, mobile, site' },
+            { flag: '--alone', description: 'One project of one type' },
+            { flag: '--monorepo', description: 'A workspace, even for a single type' },
+            { flag: '--multi-tenant', description: 'Tenant-aware api, web and mobile' },
+            { flag: '--single-tenant', description: 'No tenancy' },
+            { flag: '--skip-install', description: 'Do not run pnpm install' },
+            JSON_OPTION,
+        ],
+    },
+    {
+        name: 'db',
+        usage: 'prumo db [options]',
+        summary: "Create the development database in Docker and write its URL into the API's .env",
+        options: [
+            { flag: '--name <name>', description: 'Database name; asked when omitted' },
+            {
+                flag: '--port <port>',
+                description: 'Host port for Postgres; the first free from 5432 by default',
+            },
+            { flag: '--skip-migrate', description: 'Do not run pnpm db:migrate afterwards' },
+            JSON_OPTION,
+        ],
+    },
+    {
+        name: 'clean',
+        usage: 'prumo clean [options]',
+        summary: 'Remove what a project needed only once, such as the database setup',
+        options: [
+            { flag: '--dry-run', description: 'List what would be removed, and change nothing' },
+            { flag: '--yes', description: 'Do not ask for confirmation; required without a terminal' },
+            { flag: '--force', description: 'Clean even while DATABASE_URL is still MISSING' },
+            JSON_OPTION,
+        ],
+    },
+    {
+        name: 'doctor',
+        usage: 'prumo doctor',
+        summary: 'Check that this machine has what a Prumo project needs',
+        options: [JSON_OPTION],
+    },
+    {
+        name: 'version',
+        usage: 'prumo version',
+        summary: 'Print the CLI version',
+        options: [JSON_OPTION],
+    },
+    {
+        name: 'help',
+        usage: 'prumo help [command]',
+        summary: 'List the commands, or describe one',
+        options: [JSON_OPTION],
+    },
+];
+export function findCommand(name) {
+    return COMMANDS.find((command) => command.name === name);
+}
+function columns(rows) {
+    const width = Math.max(...rows.map(([left]) => left.length));
+    return rows.map(([left, right]) => `  ${left.padEnd(width)}  ${right}`).join('\n');
+}
+export function helpText(command) {
+    if (command !== undefined) {
+        return `Usage: ${command.usage}\n\n${command.summary}\n\nOptions:\n${columns(command.options.map((option) => [option.flag, option.description]))}`;
+    }
+    return `Usage: prumo <command> [options]\n\nCommands:\n${columns(COMMANDS.map((entry) => [entry.name, entry.summary]))}\n\nOptions:\n${columns([
+        ['-h, --help', 'Show help; `prumo <command> --help` for one command'],
+        ['-v, --version', 'Print the CLI version'],
+        [JSON_OPTION.flag, JSON_OPTION.description],
+    ])}`;
+}

package/dist/compose.js

@@ -204,7 +204,13 @@ export async function composeWorkspace({ templates, target, types, mobileScheme
         });
     }
     // One command for everything and one per app. Each app answers to `dev`, so the root never needs to know how.
-    await rewriteText(join(target, 'package.json'), (text) => types.reduce((pkg, type) => setJsonc(pkg, ['scripts', type], `pnpm --filter ${type} dev`), setJsonc(text, ['scripts', 'dev'], 'pnpm -r --parallel dev')));
+    // The database and the ports are the exception: both may ask a question, which the interleaved output of a
+    // parallel run would bury, so the root asks first and each app's own check then finds nothing to do.
+    // `pnpm -r --parallel` starts each app in its own process group, so Ctrl+C reaches pnpm and leaves the apps
+    // running. The ports script wraps the run, remembers what it started, and stops all of it on the way out.
+    const database = types.includes('api') ? 'node apps/api/scripts/database.mjs --check && ' : '';
+    const dev = `${database}node scripts/ports.mjs --all -- pnpm -r --parallel dev`;
+    await rewriteText(join(target, 'package.json'), (text) => types.reduce((pkg, type) => setJsonc(pkg, ['scripts', type], `pnpm --filter ${type} dev`), setJsonc(text, ['scripts', 'dev'], dev)));
     const manifests = await Promise.all(apps.map(async (app) => readJsonc(await readFile(join(app, 'package.json'), 'utf8'))));
     const catalogs = collectCatalog(manifests);
     if (clients.length > 0) {

package/dist/database.js

@@ -0,0 +1,46 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { CliError } from "./output.js";
+const SCRIPT = join('scripts', 'database.mjs');
+export function findProjectRoot(from) {
+    let directory = resolve(from);
+    while (!existsSync(join(directory, '.prumo', 'config.json'))) {
+        if (dirname(directory) === directory) {
+            throw new CliError('not_a_project', 'Not inside a Prumo project: no .prumo/config.json here or above.');
+        }
+        directory = dirname(directory);
+    }
+    return directory;
+}
+export function readConfig(root) {
+    return JSON.parse(readFileSync(join(root, '.prumo', 'config.json'), 'utf8'));
+}
+// Where the API sits, or undefined when the project has none.
+export function apiPath(root) {
+    const config = readConfig(root);
+    if (!config.types.includes('api')) {
+        return undefined;
+    }
+    return config.architecture === 'alone' ? root : join(root, 'apps', 'api');
+}
+export function apiDirectory(root) {
+    const api = apiPath(root);
+    if (api === undefined) {
+        throw new CliError('no_api', 'This project has no api, so it has no database to create.');
+    }
+    if (!existsSync(join(api, SCRIPT))) {
+        throw new CliError('script_missing', `${join(api, SCRIPT)} does not exist; the project predates \`prumo db\` or was cleaned.`);
+    }
+    return api;
+}
+// The logic lives in the project, so it runs without Prumo installed; this command only finds it and runs it.
+// The script answers --json itself, so its stdout is passed through untouched.
+export function runDatabase(args, cwd) {
+    const api = apiDirectory(findProjectRoot(cwd));
+    const result = spawnSync(process.execPath, [SCRIPT, ...args], { cwd: api, stdio: 'inherit' });
+    if (result.error !== undefined) {
+        throw result.error;
+    }
+    return result.status ?? 1;
+}

package/dist/doctor.js

@@ -0,0 +1,70 @@
+import { spawnSync } from 'node:child_process';
+const NODE_FLOOR = [22, 17, 0];
+export const systemProbe = {
+    nodeVersion: process.versions.node,
+    run: (command, args) => {
+        const result = spawnSync(command, args, { encoding: 'utf8', timeout: 10_000 });
+        return { ok: result.error === undefined && result.status === 0, stdout: result.stdout ?? '' };
+    },
+};
+function atLeast(version, floor) {
+    const parts = version.split('.').map(Number);
+    for (const [index, minimum] of floor.entries()) {
+        const part = parts[index] ?? 0;
+        if (part !== minimum) {
+            return part > minimum;
+        }
+    }
+    return true;
+}
+function firstLine(text) {
+    return text.trim().split('\n')[0] ?? '';
+}
+export async function doctor(probe = systemProbe) {
+    const checks = [];
+    checks.push({
+        id: 'node',
+        label: 'Node',
+        required: true,
+        ...(atLeast(probe.nodeVersion, NODE_FLOOR)
+            ? { status: 'ok', detail: probe.nodeVersion }
+            : { status: 'fail', detail: `${probe.nodeVersion}; 22.17.0 or later is required` }),
+    });
+    for (const [id, label, why] of [
+        ['pnpm', 'pnpm', 'installs and runs every generated project'],
+        ['git', 'git', 'every generated project starts as a repository'],
+    ]) {
+        const result = probe.run(id, ['--version']);
+        checks.push({
+            id,
+            label,
+            required: true,
+            ...(result.ok
+                ? { status: 'ok', detail: firstLine(result.stdout) }
+                : { status: 'fail', detail: `not found; it ${why}` }),
+        });
+    }
+    const docker = probe.run('docker', ['--version']);
+    const dockerRunning = docker.ok && probe.run('docker', ['info']).ok;
+    checks.push({
+        id: 'docker',
+        label: 'Docker',
+        required: false,
+        ...(dockerRunning
+            ? { status: 'ok', detail: firstLine(docker.stdout) }
+            : {
+                status: 'warn',
+                detail: docker.ok
+                    ? 'installed but not running; open Docker Desktop. The API runs its database and tests in it'
+                    : 'not found; install Docker Desktop. The API runs its database and tests in it',
+            }),
+    });
+    return { ready: checks.every((check) => !check.required || check.status === 'ok'), checks };
+}
+const SYMBOL = { ok: '✓', warn: '!', fail: '✗' };
+export function doctorText(report) {
+    const width = Math.max(...report.checks.map((check) => check.label.length));
+    const lines = report.checks.map((check) => `${SYMBOL[check.status]} ${check.label.padEnd(width)}  ${check.detail}`);
+    lines.push('', report.ready ? 'Ready.' : 'Not ready: fix what is marked ✗ before generating a project.');
+    return lines.join('\n');
+}

package/dist/generate.js

@@ -7,6 +7,7 @@ import { composeWorkspace, copyTemplate } from "./compose.js";
 import { writeContext } from "./context.js";
 import { setJsonc } from "./jsonc.js";
 import { schemeFor } from "./names.js";
+import { CliError } from "./output.js";
 async function rewrite(path, change) {
     await writeFile(path, change(await readFile(path, 'utf8')));
 }
@@ -38,21 +39,38 @@ async function writeLocalEnv(app, type) {
     }
     await writeFile(join(app, '.env'), env);
 }
-function run(command, args, cwd) {
-    const result = spawnSync(command, args, { cwd, stdio: 'inherit' });
+// Compose names the container and volume after the project; without this, every workspace's apps/api is `api`
+// and a second project's database replaces the first's.
+async function nameCompose(api, name) {
+    await rewrite(join(api, 'docker-compose.yml'), (text) => {
+        if (!/^name: .*$/m.test(text)) {
+            throw new Error(`${join(api, 'docker-compose.yml')} no longer carries a top-level name`);
+        }
+        return text.replace(/^name: .*$/m, `name: ${name}`);
+    });
+}
+function run(command, args, cwd, output) {
+    // Under --json stdout belongs to the result document, so a child's output goes to stderr instead.
+    const result = spawnSync(command, args, {
+        cwd,
+        stdio: output === 'inherit' ? 'inherit' : ['ignore', 2, 2],
+    });
     if (result.status !== 0) {
         throw new Error(`${command} ${args.join(' ')} failed in ${cwd}`);
     }
 }
-export async function generate({ templates, knowledge, target, answers, install, }) {
+export async function generate({ templates, knowledge, target, answers, install, childOutput = 'inherit', }) {
     if (existsSync(target) && (await readdir(target)).length > 0) {
-        throw new Error(`${target} already exists and is not empty.`);
+        throw new CliError('target_not_empty', `${target} already exists and is not empty.`);
     }
     const [only] = answers.types;
     if (answers.architecture === 'alone' && only !== undefined) {
         await copyTemplate(join(templates, only), target);
         await nameProject(target, answers.name);
         await writeLocalEnv(target, only);
+        if (only === 'api') {
+            await nameCompose(target, answers.name);
+        }
         if (only === 'mobile') {
             await nameMobileApp(target, answers.name);
         }
@@ -68,15 +86,18 @@ export async function generate({ templates, knowledge, target, answers, install,
         for (const type of answers.types) {
             await writeLocalEnv(join(target, 'apps', type), type);
         }
+        if (answers.types.includes('api')) {
+            await nameCompose(join(target, 'apps', 'api'), answers.name);
+        }
         if (answers.types.includes('mobile')) {
             await nameMobileApp(join(target, 'apps', 'mobile'), answers.name);
         }
     }
     await writeContext(knowledge, target, answers);
-    run('git', ['init', '--quiet'], target);
+    run('git', ['init', '--quiet'], target, childOutput);
     if (install) {
-        run('pnpm', ['install'], target);
+        run('pnpm', ['install'], target, childOutput);
         // Rewriting the contract import changes import grouping and line length; only the formatter can settle both.
-        run('pnpm', ['exec', 'biome', 'check', '--write'], target);
+        run('pnpm', ['exec', 'biome', 'check', '--write'], target, childOutput);
     }
 }