@stjoseph/prumo 0.0.2 → 0.0.5

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 |
@@ -110,6 +125,6 @@ Once written, those documents belong to the team. Prumo does not come back and r
 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, it offers to create one first. ';
+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 one'));
+    }
+    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 API's database check is the exception: it may ask a question, which the interleaved output of a parallel
+    // run would bury, so the root asks it first and the API's own check then finds nothing to do.
+    const parallelDev = 'pnpm -r --parallel dev';
+    const dev = types.includes('api')
+        ? `node apps/api/scripts/database.mjs --check && ${parallelDev}`
+        : parallelDev;
+    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

@@ -1,4 +1,5 @@
 import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { readdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -6,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')));
 }
@@ -20,20 +22,55 @@ async function nameMobileApp(app, name) {
         return setJsonc(result, ['expo', 'scheme'], schemeFor(name));
     });
 }
-function run(command, args, cwd) {
-    const result = spawnSync(command, args, { cwd, stdio: 'inherit' });
+const SECRET_LINE = /^BETTER_AUTH_SECRET=.*$/m;
+// `.env` stays out of git, so the example is the committed truth and a fresh project gets a copy it can start with.
+// Only the secret differs: a sample value is public, so every generated API draws its own.
+async function writeLocalEnv(app, type) {
+    const example = join(app, '.env.example');
+    if (!existsSync(example)) {
+        return;
+    }
+    let env = await readFile(example, 'utf8');
+    if (type === 'api') {
+        if (!SECRET_LINE.test(env)) {
+            throw new Error(`${example} no longer carries a BETTER_AUTH_SECRET line`);
+        }
+        env = env.replace(SECRET_LINE, `BETTER_AUTH_SECRET=${randomBytes(32).toString('base64url')}`);
+    }
+    await writeFile(join(app, '.env'), env);
+}
+// 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);
         }
@@ -46,15 +83,21 @@ export async function generate({ templates, knowledge, target, answers, install,
             mobileScheme: schemeFor(answers.name),
         });
         await nameProject(target, answers.name);
+        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);
     }
 }

package/dist/output.js

@@ -0,0 +1,24 @@
+export class CliError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}
+export function errorEnvelope(command, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof CliError ? error.code : isParseArgsError(error) ? 'usage' : 'failed';
+    const data = error instanceof CliError ? error.data : undefined;
+    return data === undefined
+        ? { ok: false, command, error: { code, message } }
+        : { ok: false, command, error: { code, message }, data };
+}
+function isParseArgsError(error) {
+    const code = error?.code;
+    return typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS_');
+}
+export function writeEnvelope(envelope) {
+    process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}

package/dist/questions.js

@@ -1,28 +1,29 @@
 import { validateProjectName } from "./names.js";
+import { CliError } from "./output.js";
 const TYPES = ['api', 'web', 'mobile', 'site'];
 const TENANT_AWARE = ['api', 'web', 'mobile'];
 function missing(flag) {
-    throw new Error(`Missing ${flag}. Outside an interactive terminal every answer must come from a flag.`);
+    throw new CliError('needs_input', `Missing ${flag}. Outside an interactive terminal every answer must come from a flag.`);
 }
 function parseTypes(value) {
     const types = value.split(',').map((type) => type.trim());
     const unknown = types.filter((type) => !TYPES.includes(type));
     if (unknown.length > 0 || types.length === 0) {
-        throw new Error(`Unknown type: ${unknown.join(', ')}. Choose from ${TYPES.join(', ')}.`);
+        throw new CliError('invalid_input', `Unknown type: ${unknown.join(', ')}. Choose from ${TYPES.join(', ')}.`);
     }
     return [...new Set(types)];
 }
 export async function resolveAnswers(flags, asker) {
     if (flags.alone && flags.monorepo) {
-        throw new Error('Choose --alone or --monorepo, not both.');
+        throw new CliError('invalid_input', 'Choose --alone or --monorepo, not both.');
     }
     if (flags.multiTenant && flags.singleTenant) {
-        throw new Error('Choose --multi-tenant or --single-tenant, not both.');
+        throw new CliError('invalid_input', 'Choose --multi-tenant or --single-tenant, not both.');
     }
     const name = flags.name ?? (asker === undefined ? missing('the project name') : await asker.name());
     const invalid = validateProjectName(name);
     if (invalid !== undefined) {
-        throw new Error(`Invalid project name "${name}". ${invalid}`);
+        throw new CliError('invalid_input', `Invalid project name "${name}". ${invalid}`);
     }
     let types;
     if (flags.types !== undefined) {
@@ -37,7 +38,7 @@ export async function resolveAnswers(flags, asker) {
     let architecture = 'alone';
     if (types.length > 1) {
         if (flags.alone) {
-            throw new Error('--alone holds a single type; several types make a workspace.');
+            throw new CliError('invalid_input', '--alone holds a single type; several types make a workspace.');
         }
         architecture = 'monorepo';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stjoseph/prumo",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "description": "Scaffolds a TypeScript project and ships it the conventions it follows, in a .prumo/ folder any AI assistant reads.",
   "keywords": [
     "scaffolding",

package/templates/api/.env.example

@@ -2,8 +2,11 @@ NODE_ENV=development
 PORT=3000
 LOG_LEVEL=info
 
-DATABASE_URL=postgresql://app:app@localhost:5432/app
-AUTH_DATABASE_URL=postgresql://app:app@localhost:5432/app
+# MISSING until `pnpm db:setup` creates a database; `pnpm dev` offers to run it.
+DATABASE_URL=MISSING
+AUTH_DATABASE_URL=MISSING
+# Read by docker-compose.yml, not by the API: the port Postgres is published on.
+POSTGRES_PORT=5432
 
 BETTER_AUTH_SECRET=replace-this-with-at-least-32-characters
 BETTER_AUTH_URL=http://localhost:3000

package/templates/api/README.md

@@ -2,18 +2,23 @@
 
 ## Requirements
 
-Node 22.17 or later, pnpm, and Docker.
+Node 22.17 or later, pnpm, and Docker Desktop running: the database and the tests both run in it.
 
 ## Running it
 
 ```sh
 pnpm install
-cp .env.example .env        # then replace BETTER_AUTH_SECRET with 32 or more random characters
-docker compose up -d --wait
-pnpm db:migrate
 pnpm dev
 ```
 
+`.env` comes with the generated project, copied from `.env.example` with a random `BETTER_AUTH_SECRET`. It is not
+committed, so on a fresh clone run `cp .env.example .env` and replace the secret with 32 or more random characters.
+
+`DATABASE_URL` starts as `MISSING`. While it is, `pnpm dev` offers to create the database first: it asks for a name,
+starts Postgres from `docker-compose.yml` on port 5432 or the next free one (kept in `POSTGRES_PORT`), writes the URL
+into `.env`, and migrates. `pnpm db:setup` does the same at any time. Without a terminal every answer comes from a
+flag: `--name`, `--port`, `--skip-migrate`, and `--json` for one JSON result on stdout.
+
 The API listens on `http://localhost:3000`. Outside production, its documentation is at `/api/docs`.
 
 `pnpm db:migrate` builds first, then runs Better Auth's migrations and then the application's. Before
@@ -27,6 +32,8 @@ still completes.
 | `pnpm test` | Runs the suite against a throwaway Postgres; Docker must be running |
 | `pnpm lint` | Biome |
 | `pnpm typecheck` | `tsc --noEmit`, also run before every push |
+| `pnpm db:setup` | Creates a development database in Docker, writes its URL into `.env`, and migrates |
+| `pnpm db:migrate` | Builds, then runs Better Auth's migrations and the application's |
 | `pnpm db:migration:create` | Generates a migration from the entity diff, to be read and edited before committing |
 
 ## Conventions

package/templates/api/docker-compose.yml

@@ -1,3 +1,6 @@
+# The Compose project, and so the names of the container and its volume. `prumo new` sets it to the project's name.
+name: api
+
 services:
   postgres:
     image: postgres:18-alpine
@@ -6,7 +9,7 @@ services:
       POSTGRES_PASSWORD: app
       POSTGRES_DB: app
     ports:
-      - '5432:5432'
+      - '${POSTGRES_PORT:-5432}:5432'
     volumes:
       - postgres:/var/lib/postgresql
       - ./docker/init:/docker-entrypoint-initdb.d:ro

package/templates/api/package.json

@@ -6,13 +6,14 @@
     "build": "nest build",
     "start": "nest start",
     "start:dev": "nest start --watch",
-    "dev": "pnpm start:dev",
+    "dev": "node scripts/database.mjs --check && pnpm start:dev",
     "start:prod": "node dist/main",
     "lint": "biome check",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:cov": "vitest run --coverage",
+    "db:setup": "node scripts/database.mjs",
     "db:migrate": "nest build && auth migrate --config dist/auth/auth.js --yes && mikro-orm migration:up",
     "db:migration:create": "mikro-orm migration:create",
     "prepare": "node .githooks/install.mjs"

package/templates/api/scripts/database.mjs

@@ -0,0 +1,307 @@
+// Creates the development database in Docker and writes its URL into .env.
+//
+//   node scripts/database.mjs            creates a database, whatever .env holds
+//   node scripts/database.mjs --check    does nothing unless DATABASE_URL is still MISSING; `pnpm dev` runs this
+//
+// The server is always the one in docker-compose.yml, published on 5432 or, when that port is taken, the next free
+// one, kept in POSTGRES_PORT. It needs no dependency, so it runs before `pnpm install` has installed anything.
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { connect } from 'node:net'
+import { basename, dirname, join, resolve } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+import { parseArgs } from 'node:util'
+
+const MISSING = 'MISSING'
+const USER = 'app'
+const PASSWORD = 'app'
+const DEFAULT_PORT = 5432
+const PORTS_TRIED = 20
+const NAME = /^[a-z_][a-z0-9_]{0,62}$/
+
+const api = resolve(import.meta.dirname, '..')
+const envPath = join(api, '.env')
+
+const { values } = parseArgs({
+  options: {
+    check: { type: 'boolean', default: false },
+    name: { type: 'string' },
+    port: { type: 'string' },
+    'skip-migrate': { type: 'boolean', default: false },
+    json: { type: 'boolean', default: false },
+  },
+})
+
+const json = values.json
+const interactive = !json && process.stdin.isTTY === true && process.stdout.isTTY === true
+// Under --json, stdout belongs to the result document.
+const childStdio = ['ignore', json ? 2 : 'inherit', 'inherit']
+
+class Failure extends Error {
+  constructor(code, message) {
+    super(message)
+    this.code = code
+  }
+}
+
+function say(message) {
+  ;(json ? process.stderr : process.stdout).write(`${message}\n`)
+}
+
+async function ask(question, fallback) {
+  const readline = createInterface({ input: process.stdin, output: process.stdout })
+  const suffix = fallback === undefined ? '' : ` (${fallback})`
+  const answer = (await readline.question(`${question}${suffix}: `)).trim()
+  readline.close()
+  return answer === '' ? fallback : answer
+}
+
+async function confirm(question) {
+  const answer = await ask(`${question} [Y/n]`)
+  return answer === undefined || /^y(es)?$/i.test(answer)
+}
+
+function readEnv() {
+  return existsSync(envPath) ? readFileSync(envPath, 'utf8') : undefined
+}
+
+function envValue(env, key) {
+  return new RegExp(`^${key}=(.*)$`, 'm').exec(env)?.[1]?.trim()
+}
+
+function withEnvValue(env, key, value) {
+  const line = new RegExp(`^${key}=.*$`, 'm')
+  return line.test(env)
+    ? env.replace(line, `${key}=${value}`)
+    : `${env.replace(/\n?$/, '\n')}${key}=${value}\n`
+}
+
+function writeEnv(entries) {
+  let env = readEnv() ?? ''
+  for (const [key, value] of Object.entries(entries)) {
+    env = withEnvValue(env, key, value)
+  }
+  writeFileSync(envPath, env)
+}
+
+function defaultName() {
+  let directory = api
+
+  // The project root is where .prumo/ lives: the api itself when alone, two levels up in a workspace.
+  while (!existsSync(join(directory, '.prumo')) && dirname(directory) !== directory) {
+    directory = dirname(directory)
+  }
+
+  const root = existsSync(join(directory, '.prumo')) ? directory : api
+  const name = basename(root)
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, '_')
+
+  return NAME.test(name) ? name : `app_${name}`.slice(0, 63)
+}
+
+function docker(args, options = {}) {
+  return spawnSync('docker', args, { cwd: api, encoding: 'utf8', ...options })
+}
+
+function listening(host, port) {
+  return new Promise((done) => {
+    const socket = connect({ host, port, timeout: 1000 })
+    const finish = (open) => {
+      socket.destroy()
+      done(open)
+    }
+    socket.once('connect', () => finish(true))
+    socket.once('timeout', () => finish(false))
+    socket.once('error', () => finish(false))
+  })
+}
+
+async function portTaken(port) {
+  // A server on this machine may listen on only one of the two loopback addresses.
+  return (await listening('127.0.0.1', port)) || (await listening('::1', port))
+}
+
+function requireDocker() {
+  if (docker(['--version']).error !== undefined) {
+    throw new Failure(
+      'docker_missing',
+      'Docker is not installed. Install Docker Desktop from https://www.docker.com/products/docker-desktop/ and run this again.',
+    )
+  }
+  if (docker(['info']).status !== 0) {
+    throw new Failure(
+      'docker_not_running',
+      'Docker is installed but not running. Open Docker Desktop, wait until it says it is running, and run this again.',
+    )
+  }
+}
+
+// The port the service already publishes, when it is up: moving it would only restart it for nothing.
+function publishedPort() {
+  const result = docker(['compose', 'port', 'postgres', '5432'])
+  const port = /:(\d+)\s*$/.exec(result.stdout ?? '')?.[1]
+
+  return result.status === 0 && port !== undefined ? Number(port) : undefined
+}
+
+async function choosePort(env) {
+  const running = publishedPort()
+
+  if (running !== undefined) {
+    return running
+  }
+
+  if (values.port !== undefined) {
+    const port = Number(values.port)
+    if (await portTaken(port)) {
+      throw new Failure('port_busy', `Port ${port} is already in use.`)
+    }
+    return port
+  }
+
+  const start = Number(envValue(env, 'POSTGRES_PORT') ?? DEFAULT_PORT)
+
+  for (let port = start; port < start + PORTS_TRIED; port += 1) {
+    if (!(await portTaken(port))) {
+      if (port !== start) {
+        say(`Port ${start} is in use; Postgres will listen on ${port}.`)
+      }
+      return port
+    }
+  }
+
+  throw new Failure(
+    'port_busy',
+    `Ports ${start} to ${start + PORTS_TRIED - 1} are all in use. Pass --port with a free one.`,
+  )
+}
+
+function startPostgres(port) {
+  // docker-compose.yml reads POSTGRES_PORT from this .env, so the file is written before the service starts.
+  writeEnv({ POSTGRES_PORT: port })
+  say('Starting Postgres in Docker…')
+
+  if (docker(['compose', 'up', '-d', '--wait'], { stdio: childStdio }).status !== 0) {
+    throw new Failure('docker_failed', '`docker compose up -d --wait` failed; its output is above.')
+  }
+}
+
+// Stop at the first error, print bare values, and read the SQL from stdin.
+const PSQL_SCRIPT = ['-v', 'ON_ERROR_STOP=1', '-tAq', '-f', '-']
+
+function sql(database, text) {
+  const result = docker(
+    ['compose', 'exec', '-T', 'postgres', 'psql', '-U', USER, '-d', database, ...PSQL_SCRIPT],
+    { input: text },
+  )
+
+  if (result.error !== undefined || result.status !== 0) {
+    throw new Failure(
+      'postgres_error',
+      result.stderr?.trim() || result.error?.message || 'psql failed',
+    )
+  }
+
+  return result.stdout.trim()
+}
+
+async function main() {
+  const env = readEnv()
+
+  if (values.check) {
+    // No .env, or a URL someone already chose: the API's own validation has the last word.
+    if (env === undefined || envValue(env, 'DATABASE_URL') !== MISSING) {
+      return undefined
+    }
+    if (!interactive) {
+      throw new Failure(
+        'database_missing',
+        'DATABASE_URL is MISSING in .env. Run `pnpm db:setup` first.',
+      )
+    }
+    say('DATABASE_URL in .env is still MISSING.')
+    if (!(await confirm('Create a development database in Docker now?'))) {
+      throw new Failure('declined', 'DATABASE_URL is MISSING. Run `pnpm db:setup` when ready.')
+    }
+  }
+
+  if (env === undefined) {
+    throw new Failure('env_missing', `${envPath} does not exist. Copy .env.example to .env first.`)
+  }
+
+  const name = values.name ?? (interactive ? await ask('Database name', defaultName()) : undefined)
+
+  if (name === undefined) {
+    throw new Failure(
+      'needs_input',
+      'The database name is required. Outside an interactive terminal, pass --name.',
+    )
+  }
+  if (!NAME.test(name)) {
+    throw new Failure(
+      'invalid_name',
+      `"${name}" is not a valid name: lowercase letters, digits and _, not starting with a digit.`,
+    )
+  }
+
+  requireDocker()
+
+  const port = await choosePort(env)
+  startPostgres(port)
+
+  const exists = sql('postgres', `SELECT 1 FROM pg_database WHERE datname = '${name}'`) === '1'
+
+  if (exists) {
+    say(`Database ${name} already exists; using it.`)
+  } else {
+    sql('postgres', `CREATE DATABASE "${name}"`)
+    say(`Created database ${name}.`)
+  }
+
+  // The image runs docker/init only for the database it creates on first start; every other one needs them too.
+  const init = join(api, 'docker', 'init')
+  for (const file of readdirSync(init)
+    .filter((entry) => entry.endsWith('.sql'))
+    .sort()) {
+    sql(name, readFileSync(join(init, file), 'utf8'))
+  }
+
+  const url = `postgresql://${USER}:${PASSWORD}@localhost:${port}/${name}`
+  writeEnv({ DATABASE_URL: url, AUTH_DATABASE_URL: url })
+  say('Wrote DATABASE_URL and AUTH_DATABASE_URL to .env.')
+
+  let migrated = false
+
+  if (!values['skip-migrate']) {
+    say('Migrating…')
+    if (spawnSync('pnpm', ['db:migrate'], { cwd: api, stdio: childStdio }).status !== 0) {
+      throw new Failure(
+        'migrate_failed',
+        '`pnpm db:migrate` failed. The database exists and .env points at it.',
+      )
+    }
+    migrated = true
+  }
+
+  return { database: name, port, created: !exists, migrated }
+}
+
+try {
+  const data = await main()
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ ok: true, command: 'db', data: data ?? null })}\n`)
+  }
+} catch (error) {
+  const code = error instanceof Failure ? error.code : 'unexpected'
+  const message = error instanceof Error ? error.message : String(error)
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: false, command: 'db', error: { code, message } })}\n`,
+    )
+  } else {
+    process.stderr.write(`${message}\n`)
+  }
+  process.exitCode = 1
+}

package/templates/mobile/README.md

@@ -9,10 +9,12 @@ to open the app.
 
 ```sh
 pnpm install
-cp .env.example .env        # EXPO_PUBLIC_API_URL points at the API
 pnpm dev
 ```
 
+`.env` comes with the generated project, copied from `.env.example`; `EXPO_PUBLIC_API_URL` points at the API. It is
+not committed, so on a fresh clone run `cp .env.example .env`.
+
 On an Android emulator `localhost` is the emulator itself; point `EXPO_PUBLIC_API_URL` at your machine's address.
 
 ## Everyday commands

package/templates/web/README.md

@@ -8,10 +8,12 @@ Node 22.17 or later, pnpm, and the API running.
 
 ```sh
 pnpm install
-cp .env.example .env        # VITE_API_URL points at the API
 pnpm dev
 ```
 
+`.env` comes with the generated project, copied from `.env.example`; `VITE_API_URL` points at the API. It is not
+committed, so on a fresh clone run `cp .env.example .env`.
+
 The app runs on `http://localhost:5173`, which is the origin the API trusts by default (`WEB_ORIGIN`).
 
 Open it and you are sent to sign in, because everything but the sign-in and sign-up pages needs a session. Follow

package/templates/workspace/README.md

@@ -2,7 +2,7 @@
 
 ## Requirements
 
-Node 22.17 or later, pnpm, and Docker for the API.
+Node 22.17 or later and pnpm. For the API, Docker Desktop running: its database and tests run in it.
 
 ## Layout
 
@@ -22,7 +22,7 @@ Node 22.17 or later, pnpm, and Docker for the API.
 
 ## Trying it
 
-With the API migrated, run `pnpm dev`. If the workspace holds `web`, open `http://localhost:5173`: you are sent to
+Run `pnpm dev`. If the workspace holds `api` and its database is not set up yet, it offers to create one first. If the workspace holds `web`, open `http://localhost:5173`: you are sent to
 sign in, and **Sign up** creates an account and takes you to your profile. Each app's README says what it needs
 before it starts.