@dokebi/cli 0.4.2 → 0.4.26

package/dist/dev-host.js

@@ -0,0 +1,55 @@
+// Default development hosts, unique per project (D-0102). Browsers scope cookies by host, not by
+// port, so two projects on `web.localhost:4410` and `web.localhost:4960` overwrite each other's
+// session and XSRF-TOKEN cookies (AI-M24). Wherever the CLI picks a domain for an app itself (the
+// first app of @dokebi/app, `app add --domain auto`, the blog/api recipes and the site recipe's
+// `--domains auto`), it is `<app>.<project>.localhost`: the project label comes from the
+// package.json name (else the folder name), cleaned to one DNS label. Every `*.localhost` name
+// resolves to this machine (browsers, macOS and systemd resolvers), and verify connects to the
+// listening address with the Host header, so no hosts file is needed. A domain the user names is
+// never changed.
+import { readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { FALLBACK_PROJECT_NAME } from './dev-infra.js';
+import { debug, describeError, isMissing } from './diagnostics.js';
+/** The answer that asks the CLI for the default development host (`--domain auto`, `--domains auto`). */
+export const AUTO_DOMAIN = 'auto';
+/** A DNS label (RFC 1035): lower-case letters, digits and inner dashes, at most 63 characters. */
+export function hostLabel(value) {
+    return value
+        .toLowerCase()
+        .replace(/^@[^/]+\//, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+/, '')
+        .slice(0, 63)
+        .replace(/-+$/, '');
+}
+/** The project's label: from the package.json name, else the folder name, else `dokebi-app`. */
+export function projectHostLabel(packageName, folder) {
+    return ((typeof packageName === 'string' ? hostLabel(packageName) : '') ||
+        hostLabel(basename(folder)) ||
+        FALLBACK_PROJECT_NAME);
+}
+/** `<app>.<project>.localhost`: the development host of one app of one project. */
+export function devHost(app, project) {
+    return `${hostLabel(app) || 'app'}.${project}.localhost`;
+}
+/**
+ * The label of the project at `root` (D-0102). Before `init` (a recipe planning a new folder)
+ * there is no package.json yet: the folder name is what init writes as the package name.
+ */
+export async function readProjectHostLabel(root) {
+    let name;
+    try {
+        name = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
+            .name;
+    }
+    catch (error) {
+        // No package.json yet (a recipe planning a new project): the folder name decides.
+        if (!isMissing(error))
+            throw error;
+        debug('Project host label from the folder name', { root, error: describeError(error) });
+    }
+    const label = projectHostLabel(name, root);
+    debug('Project host label', { root, label });
+    return label;
+}

package/dist/dev-infra.d.ts

@@ -17,12 +17,78 @@ export declare function withEnv(text: string, name: string, value: string, comme
  * user's project, not a plugin (it predates D-0070 and is kept so existing projects keep theirs).
  */
 export declare const FALLBACK_PROJECT_NAME = "dokebi-app";
+/**
+ * The variables compose.yaml takes from the environment without a default (`${NAME}`, `$NAME`,
+ * `${NAME:?…}`, `${NAME?…}`) that `dokebi dev-infra up` does not provide: it passes
+ * DOKEBI_DB_PASSWORD (from dokebi.yaml) and Compose reads the project's `.env`. R2 Codex T2: a
+ * compose.yaml rewritten to need BOOKING_DB_PORT from the project's own script made
+ * `dev-infra up` fail, and neither doctor nor the dev-infra plan said so.
+ */
+export declare function composeUnsetVariables(compose: string, envKeys?: Iterable<string>): string[];
+/** The names a `.env` text sets (`NAME=` or `export NAME=`), read leniently: doctor reports an
+ * invalid `.env` on its own, so a line this cannot read is simply not a name. */
+export declare function envKeys(text: string): string[];
+/** The doctor and dev-infra advice for compose variables dev-infra up does not set. */
+export declare function composeVariablesHint(variables: readonly string[]): string;
 /** Compose project names: lower-case letters, digits, dashes and underscores. */
 export declare function composeProject(name: string): string;
+/**
+ * The replica set a development MongoDB runs as (D-0103): one member, so multi-document
+ * transactions work as they do in production. Other databases have none.
+ */
+export declare const MONGO_REPLICA_SET = "rs0";
+export declare function replicaSetOf(docker: Pick<DockerSettings, 'image'>): string | undefined;
 /** The compose.yaml text of the development database (the developer owns it afterwards). */
 export declare function composeText(project: string, variant: string, docker: DockerSettings, port: number): string;
-/** The connection URL from the variant template. */
-export declare function connectionUrl(docker: DockerSettings, password: string, port: number): string;
+/**
+ * The host port the `db` service of a kept compose.yaml publishes (its first `ports` entry):
+ * the short syntax (`127.0.0.1:18482:5432`) or the long one (`published: 18482`). `undefined`
+ * when the entry is missing or in another form (a variable, a range, a bare container port):
+ * the CLI cannot read it, and never rewrites it.
+ */
+export declare function composePublishedPort(text: string): number | undefined;
+/**
+ * The compose.yaml services that publish host port `port`, reading `${NAME:-value}` and
+ * `${NAME-value}` as their value (a variable without one is not read). R3 Codex T2: the app
+ * itself was a service of compose.yaml on options.dokebi-web.port, so `dev-infra up` started it
+ * and `npx dokebi start` (and verify) then found the port taken.
+ */
+export declare function composeServicesPublishing(text: string, port: number): string[];
+/**
+ * The compose.yaml services built from the project folder itself (`build: .`, or `build:` with
+ * `context: .` or no context): the app's own image. R4 Codex T4: its compose.yaml had the app as
+ * `build: .` with `\${DOKEBI_APP_PORT:?…}` as the port, so the port rule could not read it, and
+ * `dev-infra up` (which starts every service of the file) failed on the app's deploy variables.
+ * A service built from a subfolder (a database image with extensions) is infrastructure.
+ */
+export declare function composeServicesBuildingProject(text: string): string[];
+/** The variables of `unset` that only `services` of compose.yaml use. */
+export declare function composeVariablesOf(text: string, services: readonly string[], unset: readonly string[]): string[];
+/** The doctor advice when compose.yaml builds and runs the app itself. */
+export declare function composeBuildsAppHint(services: readonly string[], variables: readonly string[]): string;
+/** The doctor advice when compose.yaml starts something on the app's own port. */
+export declare function composeAppPortHint(services: readonly string[], port: number): string;
+/**
+ * The same compose.yaml with only the published host port of the `db` service changed: the
+ * digits are replaced in the source text of that one scalar (the first `ports` entry, or its
+ * `published` key), so its address, container port, quoting and every other byte of the file
+ * stay. `undefined` when that entry is not in a form `composePublishedPort` reads.
+ */
+export declare function withComposePort(text: string, port: number): string | undefined;
+/**
+ * Whether a kept compose service starts its server as a replica set (`--replSet` in its command
+ * or entrypoint). A compose.yaml written before D-0103 runs a standalone mongod.
+ */
+export declare function runsReplicaSet(service: {
+    command?: unknown;
+    entrypoint?: unknown;
+}): boolean;
+/**
+ * The connection URL from the variant template. With a replica set the driver is told its name
+ * and to talk to the one member at this address (`directConnection`), never to the member name
+ * the set reports, which only resolves inside the container.
+ */
+export declare function connectionUrl(docker: DockerSettings, password: string, port: number, replicaSet?: string): string;
 /** The same URL with the password hidden, for results and logs. */
 export declare function redactUrl(url: string): string;
 /**
@@ -35,13 +101,15 @@ export declare function freePortAfter(port: number): Promise<number | undefined>
 /**
  * A taken port is the user's call (AI-M03): the question to ask and what to do now. `delegated`:
  * the user left the choices to the agent (--defaults / --answers-from defaults), so the agent may
- * take the proposed port and must tell the user; otherwise it asks and ends its turn.
+ * take the proposed port and must tell the user; otherwise it asks and ends its turn. `flag` is
+ * the flag of the command to run again (recipe, dev-infra), or the option a `config set` changes
+ * before the same command runs again (verify, AI-M04 F5).
  */
 export declare function portQuestion(input: {
     readonly what: 'Web' | 'Database';
     readonly port: number;
     readonly alternative: number | undefined;
-    readonly flag: '--port' | '--db-port';
+    readonly flag: '--port' | '--db-port' | 'dokebi-web.port';
     readonly delegated: boolean;
 }): {
     waitForUser: boolean;

package/dist/dev-infra.js

@@ -1,5 +1,5 @@
 // Development infrastructure (D-0065): compose.yaml for the database a project uses, the
-// generated password in .env and the matching dokebi.yaml address. Docker data comes from the
+// generated password only in the dokebi.yaml address. Docker data comes from the
 // db package's `dokebiCatalog.variants[].devInfra.docker`.
 import { execFile } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
@@ -7,7 +7,8 @@ import { statSync } from 'node:fs';
 import { connect, createServer } from 'node:net';
 import { delimiter, join } from 'node:path';
 import { promisify } from 'node:util';
-import { stringify } from 'yaml';
+import { isMap, isScalar, parseDocument, stringify } from 'yaml';
+import { databaseEnvironment } from './dev-compose.js';
 import { debug, describeError, isMissing } from './diagnostics.js';
 const exec = promisify(execFile);
 export const COMPOSE_FILE = 'compose.yaml';
@@ -38,6 +39,41 @@ export function withEnv(text, name, value, comment) {
  * user's project, not a plugin (it predates D-0070 and is kept so existing projects keep theirs).
  */
 export const FALLBACK_PROJECT_NAME = 'dokebi-app';
+/**
+ * The variables compose.yaml takes from the environment without a default (`${NAME}`, `$NAME`,
+ * `${NAME:?…}`, `${NAME?…}`) that `dokebi dev-infra up` does not provide: it passes
+ * DOKEBI_DB_PASSWORD (from dokebi.yaml) and Compose reads the project's `.env`. R2 Codex T2: a
+ * compose.yaml rewritten to need BOOKING_DB_PORT from the project's own script made
+ * `dev-infra up` fail, and neither doctor nor the dev-infra plan said so.
+ */
+export function composeUnsetVariables(compose, envKeys = []) {
+    const provided = new Set([PASSWORD_VARIABLE, ...envKeys]);
+    const text = compose
+        .split('\n')
+        .filter((line) => !line.trimStart().startsWith('#'))
+        .join('\n')
+        .replaceAll('$$', '');
+    const unset = new Set();
+    for (const match of text.matchAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?:(:?[-+?])[^}]*)?\}|\$([A-Za-z_][A-Za-z0-9_]*)/g)) {
+        const name = match[1] ?? match[3];
+        const operator = match[2];
+        // A default (`-`) or an alternative (`+`) never fails; `?` and a bare name need a value.
+        if (name === undefined || operator?.includes('-') || operator?.includes('+'))
+            continue;
+        if (!provided.has(name))
+            unset.add(name);
+    }
+    return [...unset].sort();
+}
+/** The names a `.env` text sets (`NAME=` or `export NAME=`), read leniently: doctor reports an
+ * invalid `.env` on its own, so a line this cannot read is simply not a name. */
+export function envKeys(text) {
+    return [...text.matchAll(/^[ \t]*(?:export[ \t]+)?([A-Za-z_][A-Za-z0-9_]*)[ \t]*=/gm)].map((match) => match[1]);
+}
+/** The doctor and dev-infra advice for compose variables dev-infra up does not set. */
+export function composeVariablesHint(variables) {
+    return `compose.yaml needs ${variables.join(', ')} from the environment, which npx dokebi dev-infra up does not set, so dev-infra up fails. dev-infra up passes the passwords of dokebi.yaml: ${PASSWORD_VARIABLE}, and for every connection DOKEBI_<PLUGIN>_<CONNECTION>_PASSWORD (or _TOKEN; without the connection for main, such as DOKEBI_REDIS_PASSWORD); use those names, give a default in compose.yaml (\${NAME:-value}) or set it in .env`;
+}
 /** Compose project names: lower-case letters, digits, dashes and underscores. */
 export function composeProject(name) {
     const cleaned = name
@@ -55,20 +91,60 @@ function dataDirectory(image) {
         return '/data/db';
     return '/var/lib/mysql';
 }
+/**
+ * The replica set a development MongoDB runs as (D-0103): one member, so multi-document
+ * transactions work as they do in production. Other databases have none.
+ */
+export const MONGO_REPLICA_SET = 'rs0';
+export function replicaSetOf(docker) {
+    return docker.image.startsWith('mongo') ? MONGO_REPLICA_SET : undefined;
+}
+/** Where the generated mongod keeps its key file: inside the container, written at each start. */
+const MONGO_KEY_FILE = '/tmp/dokebi-replica-set.key';
+/**
+ * The mongod start and readiness check of a single-node replica set. With authentication
+ * (`MONGO_INITDB_ROOT_USERNAME`) mongod requires a key file for a replica set; one member never
+ * authenticates to another, so a fresh random key at each container start is enough. The
+ * healthcheck initiates the set once (`NotYetInitialized` only: during the image's first-run
+ * initialisation the temporary server has no replica set and the check just fails) and passes
+ * only when this member is the writable primary, so `up --wait` returns when transactions work.
+ */
+function replicaSetService(docker, name) {
+    const auth = Object.hasOwn(docker.env, 'MONGO_INITDB_ROOT_USERNAME');
+    const mongod = `docker-entrypoint.sh mongod --replSet ${name} --bind_ip_all${auth ? ` --keyFile ${MONGO_KEY_FILE}` : ''}`;
+    const start = auth
+        ? `head -c 756 /dev/urandom | base64 > ${MONGO_KEY_FILE} && chmod 400 ${MONGO_KEY_FILE} && chown mongodb:mongodb ${MONGO_KEY_FILE} && exec ${mongod}`
+        : `exec ${mongod}`;
+    // `$$` is a literal `$` for Compose: the shell of the container reads its own variables.
+    const login = auth
+        ? ' -u "$$MONGO_INITDB_ROOT_USERNAME" -p "$$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase admin'
+        : '';
+    const check = `try { rs.status() } catch (e) { if (e.codeName !== 'NotYetInitialized') throw e; rs.initiate({ _id: '${name}', members: [{ _id: 0, host: '127.0.0.1:${docker.port}' }] }) } if (!db.hello().isWritablePrimary) quit(1)`;
+    return {
+        entrypoint: ['bash', '-c', start],
+        healthcheck: ['CMD-SHELL', `mongosh --quiet${login} --eval "${check}"`],
+    };
+}
 /** The compose.yaml text of the development database (the developer owns it afterwards). */
 export function composeText(project, variant, docker, port) {
-    const interpolate = (value) => value.replaceAll(`\${${PASSWORD_VARIABLE}}`, `\${${PASSWORD_VARIABLE}:?set ${PASSWORD_VARIABLE} in .env (npx dokebi dev-infra writes it)}`);
+    const interpolate = (value) => value.replaceAll(`\${${PASSWORD_VARIABLE}}`, 
+    // Compose refuses every command without the password (an empty one would start the
+    // database open); the message names the commands that pass it from dokebi.yaml.
+    `\${${PASSWORD_VARIABLE}:?run it as npx dokebi dev-infra up or down, which pass the password from dokebi.yaml}`);
+    const replicaSet = replicaSetOf(docker);
+    const cluster = replicaSet ? replicaSetService(docker, replicaSet) : undefined;
     const document = {
         name: project,
         services: {
             [DB_SERVICE]: {
                 image: docker.image,
                 restart: 'unless-stopped',
+                ...(cluster ? { entrypoint: cluster.entrypoint } : {}),
                 environment: Object.fromEntries(Object.entries(docker.env).map(([key, value]) => [key, interpolate(value)])),
                 ports: [`127.0.0.1:${port}:${docker.port}`],
                 volumes: [`db-data:${dataDirectory(docker.image)}`],
                 healthcheck: {
-                    test: docker.healthcheck.map(interpolate),
+                    test: cluster ? cluster.healthcheck : docker.healthcheck.map(interpolate),
                     interval: '2s',
                     timeout: '5s',
                     retries: 60,
@@ -77,17 +153,155 @@ export function composeText(project, variant, docker, port) {
         },
         volumes: { 'db-data': {} },
     };
+    const clusterNote = replicaSet
+        ? `# MongoDB runs as the single-node replica set ${replicaSet}, so multi-document transactions work;
+# the healthcheck initiates it once. Connect with replicaSet=${replicaSet}&directConnection=true.
+`
+        : '';
     return `# Development ${variant} database of this project, written by \`npx dokebi dev-infra\`.
-# It is yours to change. The password is read from .env (not committed); dokebi.yaml holds the
-# same address for the app. Start: docker compose up -d --wait · Stop: docker compose down
-# (add -v to delete the data volume).
-${stringify(document, { lineWidth: 0 })}`;
-}
-/** The connection URL from the variant template. */
-export function connectionUrl(docker, password, port) {
-    return docker.url
+# It is yours to change. The password comes from dokebi.yaml through the CLI child environment.
+# Start: npx dokebi dev-infra up · Stop: npx dokebi dev-infra down
+# Named data volumes are retained by down.
+${clusterNote}${stringify(document, { lineWidth: 0 })}`;
+}
+/** The short-syntax port entry `[ip:]published:target[/protocol]` of a compose service. */
+const SHORT_PORT = /^((?:[^:]*:)?)(\d+)(:\d+(?:\/[a-z]+)?)$/;
+/**
+ * The host port the `db` service of a kept compose.yaml publishes (its first `ports` entry):
+ * the short syntax (`127.0.0.1:18482:5432`) or the long one (`published: 18482`). `undefined`
+ * when the entry is missing or in another form (a variable, a range, a bare container port):
+ * the CLI cannot read it, and never rewrites it.
+ */
+export function composePublishedPort(text) {
+    const entry = parseDocument(text).getIn(['services', DB_SERVICE, 'ports', 0], true);
+    if (isScalar(entry)) {
+        const match = SHORT_PORT.exec(String(entry.value));
+        return match ? Number(match[2]) : undefined;
+    }
+    if (isMap(entry)) {
+        const published = Number(String(entry.get('published') ?? ''));
+        return Number.isSafeInteger(published) && published > 0 ? published : undefined;
+    }
+    return undefined;
+}
+/**
+ * The compose.yaml services that publish host port `port`, reading `${NAME:-value}` and
+ * `${NAME-value}` as their value (a variable without one is not read). R3 Codex T2: the app
+ * itself was a service of compose.yaml on options.dokebi-web.port, so `dev-infra up` started it
+ * and `npx dokebi start` (and verify) then found the port taken.
+ */
+export function composeServicesPublishing(text, port) {
+    const services = parseDocument(text).get('services', true);
+    if (!isMap(services))
+        return [];
+    const value = (raw) => String(raw ?? '').replaceAll(/\$\{[A-Za-z_][A-Za-z0-9_]*:?-([^}]*)\}/g, '$1');
+    const found = [];
+    for (const item of services.items) {
+        const ports = isMap(item.value) ? item.value.get('ports', true) : undefined;
+        if (!ports || typeof ports !== 'object' || !('items' in ports))
+            continue;
+        const published = ports.items.map((entry) => {
+            if (isScalar(entry))
+                return SHORT_PORT.exec(value(entry.value))?.[2];
+            if (isMap(entry))
+                return value(entry.get('published'));
+            return undefined;
+        });
+        if (published.some((host) => host !== undefined && Number(host) === port))
+            found.push(String(isScalar(item.key) ? item.key.value : item.key));
+    }
+    return found;
+}
+/**
+ * The compose.yaml services built from the project folder itself (`build: .`, or `build:` with
+ * `context: .` or no context): the app's own image. R4 Codex T4: its compose.yaml had the app as
+ * `build: .` with `\${DOKEBI_APP_PORT:?…}` as the port, so the port rule could not read it, and
+ * `dev-infra up` (which starts every service of the file) failed on the app's deploy variables.
+ * A service built from a subfolder (a database image with extensions) is infrastructure.
+ */
+export function composeServicesBuildingProject(text) {
+    const services = parseDocument(text).get('services', true);
+    if (!isMap(services))
+        return [];
+    const root = (raw) => {
+        const path = String(raw ?? '.').trim();
+        return path === '' || path === '.' || path === './';
+    };
+    const found = [];
+    for (const item of services.items) {
+        const build = isMap(item.value) ? item.value.get('build', true) : undefined;
+        if (build === undefined)
+            continue;
+        const local = isScalar(build)
+            ? root(build.value)
+            : isMap(build)
+                ? root(build.get('context'))
+                : false;
+        if (local)
+            found.push(String(isScalar(item.key) ? item.key.value : item.key));
+    }
+    return found;
+}
+/** The variables of `unset` that only `services` of compose.yaml use. */
+export function composeVariablesOf(text, services, unset) {
+    const document = parseDocument(text);
+    for (const service of services)
+        document.deleteIn(['services', service]);
+    const left = new Set(composeUnsetVariables(String(document)));
+    return unset.filter((name) => !left.has(name));
+}
+/** The doctor advice when compose.yaml builds and runs the app itself. */
+export function composeBuildsAppHint(services, variables) {
+    const theirs = variables.length
+        ? ` (the variables COMPOSE_VARIABLES_UNSET names, ${variables.join(', ')}, go with ${services.length > 1 ? 'them' : 'it'})`
+        : '';
+    return `compose.yaml service ${services.join(', ')} is built from this project (build: .): npx dokebi dev-infra up builds and starts it with the infrastructure, and npx dokebi start, dev and verify then run the app a second time beside it (or find its port taken), or dev-infra up fails on what only the app needs${theirs}. compose.yaml is the development infrastructure (databases, Redis, NATS, mail): keep a container of the app in its own Compose file (compose.deploy.yaml from npx dokebi init --deploy, started with docker compose -f compose.deploy.yaml)`;
+}
+/** The doctor advice when compose.yaml starts something on the app's own port. */
+export function composeAppPortHint(services, port) {
+    return `compose.yaml service ${services.join(', ')} publishes port ${port}, the port of options.dokebi-web.port: npx dokebi dev-infra up starts it, and npx dokebi start, dev and verify then find the port taken (PORT_IN_USE). compose.yaml is the development infrastructure (databases, Redis, NATS, mail); keep a container of the app in its own Compose file (for example compose.deploy.yaml from npx dokebi init --deploy) or give it another host port`;
+}
+/**
+ * The same compose.yaml with only the published host port of the `db` service changed: the
+ * digits are replaced in the source text of that one scalar (the first `ports` entry, or its
+ * `published` key), so its address, container port, quoting and every other byte of the file
+ * stay. `undefined` when that entry is not in a form `composePublishedPort` reads.
+ */
+export function withComposePort(text, port) {
+    if (composePublishedPort(text) === undefined)
+        return undefined;
+    const entry = parseDocument(text).getIn(['services', DB_SERVICE, 'ports', 0], true);
+    const scalar = isMap(entry) ? entry.get('published', true) : entry;
+    if (!isScalar(scalar) || !scalar.range)
+        return undefined;
+    const [from, to] = scalar.range;
+    const source = text.slice(from, to);
+    const pattern = isMap(entry)
+        ? /^(["']?)(\d+)(["']?)$/
+        : /^(["']?(?:[^:"']*:)?)(\d+)(:\d+(?:\/[a-z]+)?["']?)$/;
+    if (!pattern.test(source))
+        return undefined;
+    return `${text.slice(0, from)}${source.replace(pattern, `$1${port}$3`)}${text.slice(to)}`;
+}
+/**
+ * Whether a kept compose service starts its server as a replica set (`--replSet` in its command
+ * or entrypoint). A compose.yaml written before D-0103 runs a standalone mongod.
+ */
+export function runsReplicaSet(service) {
+    return /--replSet\b/.test(`${JSON.stringify(service.command)} ${JSON.stringify(service.entrypoint)}`);
+}
+/**
+ * The connection URL from the variant template. With a replica set the driver is told its name
+ * and to talk to the one member at this address (`directConnection`), never to the member name
+ * the set reports, which only resolves inside the container.
+ */
+export function connectionUrl(docker, password, port, replicaSet) {
+    const url = docker.url
         .replace('{password}', encodeURIComponent(password))
         .replace('{port}', String(port));
+    if (!replicaSet)
+        return url;
+    return `${url}${url.includes('?') ? '&' : '?'}replicaSet=${encodeURIComponent(replicaSet)}&directConnection=true`;
 }
 /** The same URL with the password hidden, for results and logs. */
 export function redactUrl(url) {
@@ -136,19 +350,25 @@ export async function freePortAfter(port) {
 /**
  * A taken port is the user's call (AI-M03): the question to ask and what to do now. `delegated`:
  * the user left the choices to the agent (--defaults / --answers-from defaults), so the agent may
- * take the proposed port and must tell the user; otherwise it asks and ends its turn.
+ * take the proposed port and must tell the user; otherwise it asks and ends its turn. `flag` is
+ * the flag of the command to run again (recipe, dev-infra), or the option a `config set` changes
+ * before the same command runs again (verify, AI-M04 F5).
  */
 export function portQuestion(input) {
     const { what, port, alternative, flag, delegated } = input;
     const proposal = alternative ?? '<free port>';
-    const question = `${what} port ${port} is in use by another program. Use port ${proposal} instead (${flag} ${proposal}), or stop the program that uses ${port} and keep ${port}?`;
+    const use = (value) => flag.startsWith('--') ? `${flag} ${value}` : `npx dokebi config set ${flag}=${value}`;
+    const again = (value) => flag.startsWith('--')
+        ? `run the same command again with ${use(value)}`
+        : `run ${use(value)} (--dry-run first), then the same command again`;
+    const question = `${what} port ${port} is in use by another program. Use port ${proposal} instead (${use(proposal)}), or stop the program that uses ${port} and keep ${port}?`;
     const rule = 'do not pick the port yourself unless the user left choices to you (--defaults / --answers-from defaults)';
     return {
         waitForUser: !delegated,
         question,
         next: delegated
-            ? `The user left the choices to you (--defaults), so you may run the same command again with ${flag} ${proposal}; tell the user the port you chose and why (${port} was in use). Nothing was changed. Otherwise ${rule}.`
-            : `Ask the user this question and end your turn; ${rule}. Nothing was changed. After the answer, run the same command again with ${flag} <the chosen port>, or as it was once the user stopped the other program.`,
+            ? `The user left the choices to you (--defaults), so you may ${again(proposal)}; tell the user the port you chose and why (${port} was in use). Nothing was changed. Otherwise ${rule}.`
+            : `Ask the user this question and end your turn; ${rule}. Nothing was changed. After the answer, ${again('<the chosen port>')}, or as it was once the user stopped the other program.`,
     };
 }
 /**
@@ -204,7 +424,7 @@ export async function dockerAvailable() {
 /** Whether the compose service of this project runs (a later recipe run skips `up`). */
 export async function composeServiceRunning(root) {
     try {
-        const { stdout } = await exec('docker', ['compose', 'ps', '--status', 'running', '--services'], { cwd: root, timeout: 15_000 });
+        const { stdout } = await exec('docker', ['compose', 'ps', '--status', 'running', '--services'], { cwd: root, timeout: 15_000, env: { ...process.env, ...(await databaseEnvironment(root)) } });
         return stdout.split('\n').includes(DB_SERVICE);
     }
     catch (error) {

package/dist/dev-watch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The recorded state of the watched paths. `changed(path)` answers whether a reported path really
+ * changed since it was recorded (or since its last change) and records its new state.
+ */
+export declare class WatchedState {
+    #private;
+    /**
+     * @param skip paths that are neither recorded nor compared (files whose events the caller drops,
+     * such as views served by Vite).
+     */
+    constructor(options?: {
+        limit?: number;
+        skip?: (path: string) => boolean;
+    });
+    /** Whether every path under the recorded folders is known (false past the limit). */
+    get complete(): boolean;
+    /** Events answered "no change" so far. */
+    get ignored(): number;
+    /** Records a file or folder (not its contents); a missing one is recorded as absent. */
+    record(path: string): void;
+    /** Records a folder and everything under it (symbolic links are not followed into). */
+    recordTree(folder: string): void;
+    /**
+     * Whether the path an fs.watch event on `folder` names changed (see `changed`). The folder's own
+     * name that is not an entry of it means the folder itself (libuv).
+     */
+    changedIn(folder: string, name: string): boolean;
+    /**
+     * Whether `path` differs from its recorded state; the new state is recorded. A path that is
+     * absent now and was absent (or unknown with a complete record) did not change; an unchanged
+     * folder changed when an entry below it did.
+     */
+    changed(path: string): boolean;
+}