@dokebi/cli 0.4.1 → 0.4.26

package/dist/verify-tests.js

@@ -0,0 +1,449 @@
+// The `test` step of `dokebi verify` (D-0077 H): the project's own tests, with a result per test.
+//
+// - Only when package.json has a `test` script; without one the step is skipped (`no test
+//   script`), never a failure.
+// - A script that is a plain `node … --test …` command (optionally after `KEY=value` words) is run
+//   directly with the CLI's node and the reporter in test-reporter.ts, which writes one JSON line
+//   per finished test to a temporary file: name, `[ID]` tag, ok, ms, file, skipped, todo and the
+//   first line of the failure. Anything else (another runner, shell syntax, a pretest/posttest
+//   script) runs as `npm run test` and only its exit code and duration are recorded.
+// - The tests get the app's environment: the project's .env under the CLI's environment
+//   (D-0073), NODE_ENV=test unless one of them sets it. No stdout or stderr of the tests is ever
+//   copied into the result; an error line is masked again with every secret value verify can know
+//   (.env values, secret-named environment variables, dokebi.yaml secrets as `config show` hides
+//   them) — and dropped when those cannot be read (fail closed).
+// - The tests run in their own process group, which is killed at the time limit and after the
+//   run (a server a test left behind must not hold a port when verify starts the app).
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { delimiter, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { redaction } from '@dokebi/core/libraries';
+import { configShow, SECRET_MARKER, URL_SECRET_MARKER } from './config-show.js';
+import { configTarget, parseProjectConfig, readProjectSettings } from './configuration.js';
+import { debug, describeError, isMissing } from './diagnostics.js';
+import { appEnvironment, readEnvFile } from './env-file.js';
+import { CliError } from './errors.js';
+import { redactNpmOutput } from './npm-client.js';
+import { forwardTermination, killGroup, PROCESS_GROUPS } from './process-group.js';
+/** Default time limit of the test step (`--test-timeout-ms`), like typecheck and build. */
+export const TEST_TIMEOUT_MS = 300_000;
+/** At most this many results are listed; failures always are (`omitted` counts the rest). */
+export const MAX_TEST_RESULTS = 1000;
+/** A leading `[ABC-12] ` tag of a test name: the id (D-0077 A; the framework gives it no meaning). */
+export const TEST_ID = /^\[([A-Za-z][A-Za-z0-9._-]{0,63})\]\s/;
+/**
+ * The words of a script, or undefined when it uses anything a shell would interpret (operators,
+ * substitutions, escapes, globs outside quotes are kept as words: node expands them itself).
+ */
+export function scriptWords(script) {
+    const words = [];
+    let word;
+    let quote;
+    for (const character of script) {
+        if (quote) {
+            if (character === quote)
+                quote = undefined;
+            else if (quote === '"' && /[$`\\]/.test(character))
+                return undefined;
+            else
+                word += character;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            word ??= '';
+        }
+        else if (/\s/.test(character)) {
+            if (word !== undefined)
+                words.push(word);
+            word = undefined;
+        }
+        else if (/[|&;<>()$`\\{}~#!]/.test(character))
+            return undefined;
+        else
+            word = (word ?? '') + character;
+    }
+    if (quote)
+        return undefined;
+    if (word !== undefined)
+        words.push(word);
+    return words;
+}
+const REPORTER_FLAGS = ['--test-reporter', '--test-reporter-destination'];
+/** Node options whose value is the next word (`--import tsx`). */
+const VALUE_FLAGS = new Set([
+    '--import',
+    '--require',
+    '-r',
+    '--loader',
+    '--experimental-loader',
+    '--env-file',
+    '--conditions',
+    '-C',
+    ...REPORTER_FLAGS,
+]);
+/**
+ * Whether `--test` is a node option of these words: before the first file or pattern (after it,
+ * node passes `--test` to the script instead).
+ */
+function testFlagFirst(words) {
+    for (let index = 0; index < words.length; index++) {
+        const word = words[index];
+        if (word === '--test')
+            return true;
+        if (!word.startsWith('-'))
+            return false;
+        if (VALUE_FLAGS.has(word))
+            index++;
+    }
+    return false;
+}
+/** Whether verify can run `script` with its reporter, and how. */
+export function planTests(script, scripts) {
+    if (typeof scripts.pretest === 'string' || typeof scripts.posttest === 'string')
+        return { runner: 'other', reason: 'package.json has a pretest or posttest script' };
+    const words = scriptWords(script.trim());
+    if (!words)
+        return { runner: 'other', reason: 'the test script uses shell syntax' };
+    const env = {};
+    while (words[0] && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) {
+        const assignment = words.shift();
+        const equals = assignment.indexOf('=');
+        env[assignment.slice(0, equals)] = assignment.slice(equals + 1);
+    }
+    if (words.shift() !== 'node')
+        return { runner: 'other', reason: 'the test script is not a node --test command' };
+    if (!testFlagFirst(words))
+        return { runner: 'other', reason: 'the test script is not a node --test command' };
+    const args = [];
+    for (let index = 0; index < words.length; index++) {
+        const word = words[index];
+        const flag = REPORTER_FLAGS.find((name) => word === name || word.startsWith(`${name}=`));
+        if (!flag)
+            args.push(word);
+        else if (word === flag)
+            index++; // `--test-reporter spec`: its value is the next word
+    }
+    return { runner: 'node', args, env };
+}
+/** The id of a test: the tag of its own name, else of the nearest parent with one. */
+export function testId(name, parents = []) {
+    for (const candidate of [name, ...[...parents].reverse()]) {
+        const match = TEST_ID.exec(candidate);
+        if (match?.[1])
+            return match[1];
+    }
+    return undefined;
+}
+/** All strings in a value (a secret list hides every item). */
+function strings(value, into) {
+    if (typeof value === 'string')
+        into.push(value, ...maskedCredentials(value));
+    else if (Array.isArray(value))
+        for (const item of value)
+            strings(item, into);
+    else if (value && typeof value === 'object')
+        for (const item of Object.values(value))
+            strings(item, into);
+}
+/**
+ * The credentials core's `maskCredentials` hides in a text (`//user:pa/ss@` of a URL, also with a
+ * raw `/` in the password; `Password=...` of a connection string): the text itself and the hidden
+ * part, read off its masked form, so verify hides exactly what the logs hide (no rule of its own).
+ */
+export function maskedCredentials(text) {
+    const value = text.trim();
+    const masked = redaction.maskCredentials(value);
+    if (masked === value)
+        return [];
+    let start = 0;
+    while (start < value.length && value[start] === masked[start])
+        start++;
+    let end = 0;
+    while (end < value.length - start &&
+        end < masked.length - start &&
+        value[value.length - 1 - end] === masked[masked.length - 1 - end])
+        end++;
+    const hidden = value.slice(start, value.length - end);
+    // `user:password` of a URL: the password alone too (it may show up without its user).
+    const colon = hidden.indexOf(':');
+    return [value, hidden, ...(colon >= 0 ? [hidden.slice(colon + 1)] : [])].filter(Boolean);
+}
+/** The raw values `config show` hides: walks the raw options next to the shown ones. */
+function hiddenValues(raw, shown, into) {
+    if (shown === SECRET_MARKER) {
+        strings(raw, into);
+        return;
+    }
+    // A URL or connection string with credentials, whether `config show` marked it or not.
+    if (typeof raw === 'string') {
+        into.push(...maskedCredentials(raw));
+        if (typeof shown === 'string' && shown.includes(URL_SECRET_MARKER))
+            into.push(raw.trim());
+        return;
+    }
+    if (Array.isArray(raw) && Array.isArray(shown))
+        raw.forEach((item, index) => {
+            hiddenValues(item, shown[index], into);
+        });
+    else if (raw && typeof raw === 'object' && shown && typeof shown === 'object')
+        for (const [key, item] of Object.entries(raw))
+            hiddenValues(item, shown[key], into);
+}
+/**
+ * Every secret value verify can know for this project: the values of .env, of environment
+ * variables named like a secret (core's `redaction.isSecretEnvironmentName`: the field rule of the
+ * logs plus `*_KEY`, `*_PASS`; never PWD or OLDPWD, which would cut the project folder out of
+ * every error line), and of the options of the settings file (DOKEBI_CONFIG, else dokebi.yaml) `config show` hides. Throws when they cannot be
+ * read (the caller then drops the error lines).
+ */
+export async function knownSecrets(root) {
+    const values = [...Object.values(readEnvFile(root))];
+    for (const [name, value] of Object.entries(process.env))
+        if (value && redaction.isSecretEnvironmentName(name, value))
+            values.push(value);
+    // M50: the settings file the app and its tests read (DOKEBI_CONFIG, else dokebi.yaml). One
+    // read: `config show` hides in the same text the raw values are taken from.
+    let settings;
+    try {
+        settings = await readProjectSettings(root);
+    }
+    catch (error) {
+        // No dokebi.yaml holds no secret; a named file that cannot be read fails closed (throws).
+        if (!isMissing(error) || (await configTarget(root)).fromEnvironment)
+            throw error;
+    }
+    if (settings)
+        hiddenValues(parseProjectConfig(settings.source).options, (await configShow(root, undefined, { source: settings.source, file: settings.target.file }))
+            .value, values);
+    // Short values (`1`, `true`, a port) are not secrets and would mask ordinary words.
+    return [...new Set(values.filter((value) => value.length >= 6))].sort((a, b) => b.length - a.length);
+}
+/** A secret-named `key=value` / `key: value` in a line (password=…, apiKey: …, token=…). */
+const NAMED_SECRET = /\b([A-Za-z0-9_.-]*(?:secret|password|passwd|passphrase|token|api[_-]?key|credential)s?)(\s*[=:]\s*)(["']?)[^\s"',;]+/gi;
+/** An error line with the known secret values and secret-looking parts replaced by `***`. */
+export function maskLine(line, secrets) {
+    let text = line;
+    for (const secret of secrets)
+        text = text.split(secret).join('***');
+    return redactNpmOutput(text).replace(NAMED_SECRET, '$1$2$3***');
+}
+/** Runs a command in its own process group without keeping any output; bounded by timeoutMs. */
+function runBounded(command, args, cwd, env, timeoutMs) {
+    const began = performance.now();
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            env,
+            // The tests' own output is never read: it may print anything (secrets included).
+            stdio: 'ignore',
+            detached: PROCESS_GROUPS,
+        });
+        const forwarding = forwardTermination(child.pid);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            debug('verify: the tests reached the time limit; killing them', { timeoutMs });
+            killGroup(child.pid, 'SIGKILL');
+        }, timeoutMs);
+        child.once('error', (cause) => {
+            clearTimeout(timer);
+            forwarding();
+            reject(new CliError('TEST_FAILED', `Could not run the tests (${command})`, { cause }));
+        });
+        child.once('close', (code, signal) => {
+            clearTimeout(timer);
+            forwarding();
+            // Whatever the tests left running in the group (a server, a watcher) goes too, so it
+            // cannot hold the port of the app verify starts next.
+            if (!timedOut && killGroup(child.pid, 'SIGKILL'))
+                debug('verify: killed processes the tests left behind', { pid: child.pid });
+            resolve({ code, signal, timedOut, ms: Math.round(performance.now() - began) });
+        });
+    });
+}
+/** The reporter lines that are complete JSON objects (a killed run may end mid-line). */
+function reportedTests(text) {
+    const tests = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            tests.push(JSON.parse(line));
+        }
+        catch (error) {
+            debug('verify: skipped an incomplete reporter line', { error: describeError(error) });
+        }
+    }
+    return tests;
+}
+function testFile(root, file) {
+    if (!file)
+        return undefined;
+    const path = relative(root, file);
+    return path && !path.startsWith('..') ? path.split(sep).join('/') : file;
+}
+/**
+ * The test step of verify for the project at `root` whose package.json scripts are `scripts`.
+ * Throws a CliError (ENV_FILE_INVALID, TEST_FAILED) only when the tests cannot be run at all.
+ */
+export async function runTests(root, scripts, options = {}) {
+    const script = scripts.test;
+    if (typeof script !== 'string')
+        return { ok: true, skipped: 'no test script' };
+    const timeoutMs = options.timeoutMs ?? TEST_TIMEOUT_MS;
+    const plan = planTests(script, scripts);
+    debug('verify: running the tests', { runner: plan.runner, timeoutMs });
+    // The app's environment (D-0073), as a test run: NODE_ENV=test unless .env or the
+    // environment sets it. NODE_TEST_CONTEXT would make node --test act as a child of another
+    // run (verify itself under node --test) and report to its stdout instead of the reporter.
+    const env = appEnvironment(root, 'test', plan.runner === 'node' ? plan.env : {});
+    delete env.NODE_TEST_CONTEXT;
+    env.PATH = [join(root, 'node_modules', '.bin'), env.PATH].filter(Boolean).join(delimiter);
+    const timedOut = (ms) => ({
+        code: 'TEST_TIMEOUT',
+        message: `The tests did not finish within ${ms} ms (npx dokebi verify --test-timeout-ms <ms> allows more)`,
+    });
+    if (plan.runner === 'other') {
+        const npmPath = process.env.npm_execpath;
+        const viaNode = npmPath?.endsWith('npm-cli.js');
+        const run = await runBounded(viaNode ? process.execPath : 'npm', [...(viaNode ? [npmPath] : []), 'run', 'test'], root, env, timeoutMs);
+        const ok = run.code === 0 && !run.timedOut;
+        const tests = {
+            runner: 'other',
+            ms: run.ms,
+            exitCode: run.code,
+            reason: plan.reason,
+        };
+        return {
+            ok,
+            ...(ok
+                ? {}
+                : run.timedOut
+                    ? timedOut(timeoutMs)
+                    : {
+                        code: 'TEST_FAILED',
+                        message: `npm run test exited with ${run.code ?? run.signal}; run it to see the output (verify does not copy test output)`,
+                    }),
+            details: { runner: 'other', reason: plan.reason, exitCode: run.code },
+            tests,
+        };
+    }
+    const work = await mkdtemp(join(tmpdir(), 'dokebi-verify-tests-'));
+    try {
+        const report = join(work, 'report.jsonl');
+        const reporter = fileURLToPath(new URL('./test-reporter.js', import.meta.url));
+        const run = await runBounded(process.execPath, 
+        // Node reads options only before the first file or pattern: the reporter goes first.
+        [`--test-reporter=${reporter}`, `--test-reporter-destination=${report}`, ...plan.args], root, env, timeoutMs);
+        let text = '';
+        try {
+            text = await readFile(report, 'utf8');
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+            debug('verify: the test run wrote no report', { exitCode: run.code });
+        }
+        let secrets;
+        try {
+            secrets = await knownSecrets(root);
+        }
+        catch (error) {
+            // Fail closed: without the secret list no error line leaves this function.
+            debug('verify: the secret values could not be read; error lines are left out', {
+                error: describeError(error),
+            });
+        }
+        const all = reportedTests(text).map((test) => {
+            const id = testId(test.name, test.parents ?? []);
+            const file = testFile(root, test.file);
+            return {
+                name: [...(test.parents ?? []), test.name].join(' > '),
+                ...(id ? { id } : {}),
+                ok: test.ok,
+                ms: test.ms,
+                ...(file ? { file } : {}),
+                ...(test.skipped ? { skipped: true } : {}),
+                ...(test.todo ? { todo: true } : {}),
+                ...(test.error
+                    ? {
+                        error: secrets
+                            ? maskLine(test.error, secrets)
+                            : '(hidden: the secret values could not be read to mask it)',
+                    }
+                    : {}),
+            };
+        });
+        const failed = all.filter((test) => !test.ok);
+        const skipped = all.filter((test) => test.ok && test.skipped).length;
+        const todo = all.filter((test) => test.ok && test.todo && !test.skipped).length;
+        // Failures always; the others in run order while there is room.
+        let room = Math.max(0, MAX_TEST_RESULTS - failed.length);
+        const results = all.filter((test) => !test.ok || room-- > 0);
+        const tests = {
+            runner: 'node',
+            total: all.length,
+            passed: all.length - failed.length - skipped - todo,
+            failed: failed.length,
+            skipped,
+            todo,
+            ms: run.ms,
+            exitCode: run.code,
+            results,
+            ...(results.length < all.length ? { omitted: all.length - results.length } : {}),
+        };
+        const ok = !run.timedOut && run.code === 0 && failed.length === 0;
+        const counts = {
+            total: tests.total,
+            passed: tests.passed,
+            failed: tests.failed,
+            skipped,
+            todo,
+        };
+        debug('verify: tests finished', { ...counts, exitCode: run.code, ms: run.ms });
+        return {
+            ok,
+            ...(ok
+                ? {}
+                : run.timedOut
+                    ? timedOut(timeoutMs)
+                    : {
+                        code: 'TEST_FAILED',
+                        message: failed.length
+                            ? `${failed.length} of ${all.length} test(s) failed: ${failed
+                                .slice(0, 5)
+                                .map((test) => test.name)
+                                .join('; ')}${failed.length > 5 ? '; …' : ''}`
+                            : `node --test exited with ${run.code ?? run.signal} and no failed test (see npm run test)`,
+                    }),
+            details: {
+                runner: 'node',
+                ...counts,
+                exitCode: run.code,
+                ...(failed.length ? { failures: failed.map((test) => test.name) } : {}),
+            },
+            tests,
+        };
+    }
+    finally {
+        await rm(work, { recursive: true, force: true }).catch((error) => debug('verify: could not remove the test report folder', {
+            work,
+            error: describeError(error),
+        }));
+    }
+}
+/**
+ * The human lines verify prints under its test check: one per failing test, then a summary
+ * (each line starts with a newline and two spaces).
+ */
+export function testLines(report) {
+    if (report.runner === 'other')
+        return `\n  tests: npm run test exited with ${report.exitCode ?? 'no code'} in ${report.ms} ms (no per-test results: ${report.reason})`;
+    const failures = report.results
+        .filter((test) => !test.ok)
+        .map((test) => `\n  FAIL ${test.name}${test.file ? ` (${test.file})` : ''}${test.error ? `: ${test.error}` : ''}`);
+    return `${failures.join('')}\n  tests: ${report.passed} passed, ${report.failed} failed, ${report.skipped} skipped, ${report.todo} todo of ${report.total} in ${report.ms} ms (node:test)`;
+}

package/dist/verify.d.ts

@@ -1,5 +1,46 @@
+import { type AllowedMarker } from './check/index.js';
+import { type EnvFileWarning } from './env-file.js';
+import * as server from './server.js';
+import { type TestReport } from './verify-tests.js';
+/**
+ * D-0105 §4: with @dokebi/db installed, what the agent's final message must contain besides
+ * tellUser. The guidance asks for it, and an AI consumer that read it many times still left it
+ * out (AI-M23, AI-M24): verify ok repeats it at the moment the agent is about to report.
+ */
+export declare function finalReportLines(ok: boolean, installed: ReadonlySet<string>, allowed?: readonly AllowedMarker[]): string[];
+/**
+ * R1 measurement: a builder printed only `{ ok, checks, tests, tellUser }` of the verify JSON and
+ * never saw `finalReport`, so its final message lacked the section 6 table. The tellUser lines,
+ * which every builder relays, end with what finalReport asks for (the field stays as it is).
+ */
+export declare function tellUserWithReport(tellUser: readonly string[], finalReport: readonly string[], dbRules?: readonly string[]): string[];
+/**
+ * R6 Codex T3: the heading said "one row per rule" and the builder, which reads only tellUser of
+ * the result and had read part of section 6, wrote a table of twelve rules of its own. The
+ * heading names the rules of the installed @dokebi/db AI.md (`### 6.N Title`), so each row has
+ * one to answer. No installed AI.md: none.
+ */
+export declare function readDbPracticeRules(root: string): Promise<string[]>;
+/**
+ * M34: a builder silenced background-timer on a database polling loop and check passed. verify ok
+ * asks the final message to list every silenced problem with its reason, so the person reading it
+ * sees each one (the markers stay legitimate for per-process upkeep).
+ */
+export declare function allowedReport(allowed: readonly AllowedMarker[]): string;
+/**
+ * R2 Codex T2, T4, T5 (and R1 T1, T2): the builder relayed the headings verbatim, "the table below
+ * …", and put the table in a results file; it reads relay and tellUser, not finalReport. With
+ * finalReport lines, relay itself says that each heading's table or list follows it in the message.
+ * R4 Claude T4 copied the other lines and wrote its own headings for these two (`## Database
+ * practice (…)`): relay called them "a heading". They are lines to copy like the others.
+ */
+export declare const REPORT_RELAY: Readonly<{
+    tellUser: 'verbatim';
+    instruction: "Copy these lines unchanged into your final message to the user: do not translate, reword or summarize them. You may add your own summary after them. The lines that start with Database practice and Silenced check rules are copied word for word too (they are lines of this list, not headings to write in your own words), and right under each of them you write the table or list it announces, in the same final message, as finalReport says; a results file or a link to one does not replace it.";
+}>;
+export declare const DB_PRACTICE_REPORT = "Database practice (@dokebi/db is installed): your final message contains a table with one row per rule of section 6 of node_modules/@dokebi/db/AI.md: the rule, the queries or jobs it applies to, the measurement (rows read, rate, refusals) and the verdict (pass, or the fix you made). A rule you did not measure is not done; a separate results file does not replace the table in the message.";
 export interface VerifyCheck {
-    readonly name: 'doctor' | 'check' | 'typecheck' | 'build' | 'preflight' | 'start' | 'http' | 'stop';
+    readonly name: 'doctor' | 'check' | 'typecheck' | 'build' | 'test' | 'preflight' | 'start' | 'http' | 'stop';
     readonly ok: boolean;
     readonly skipped?: string;
     readonly ms: number;
@@ -18,16 +59,63 @@ export interface VerifyResult {
     readonly urls: string[];
     /** The listening addresses (the web listening line, else dokebi.yaml); HTTP checks connect here. */
     readonly listen: string[];
+    /**
+     * The project's tests when package.json has a `test` script (D-0077 H): with node:test a result
+     * per test (`runner: 'node'`), otherwise the exit code and duration (`runner: 'other'`).
+     */
+    readonly tests?: TestReport;
     /**
      * Only when ok and a recipe was applied (`.dokebi/recipe.json`): lines the agent's final
      * message to the user must include — each choice and who made it (a default with its reason)
-     * and the notices, such as no CSRF protection for HTML forms (AI-M03).
+     * and the notices, such as how the forms send the CSRF token (AI-M03, D-0076 §6).
      */
     readonly tellUser?: string[];
+    /** With tellUser: relay the lines verbatim (`{ tellUser: 'verbatim', instruction }`, AI-M05 F6). */
+    readonly relay?: {
+        readonly tellUser: 'verbatim';
+        readonly instruction: string;
+    };
+    /**
+     * Only when ok (D-0105 §4): what the final message must also contain, written by the agent
+     * (not copied): with @dokebi/db, the section 6 rule-by-rule measurement table.
+     */
+    readonly finalReport?: string[];
+    /**
+     * When the preflight found the web port taken (AI-M04 F5): the question for the user, like the
+     * recipe preflight (`waitForUser`, `question`, `next`; the problem has `alternative`).
+     */
+    readonly waitForUser?: boolean;
+    readonly question?: string;
+    readonly next?: string;
+    /**
+     * R4CC-7: what the project has that the app verify started does not take, such as a
+     * DOKEBI_CONFIG line of .env (`ENV_DOKEBI_CONFIG_IGNORED`, `path: .env:<line>`, `hint`).
+     */
+    readonly warnings?: Pick<EnvFileWarning, 'code' | 'path' | 'hint'>[];
+}
+/** One problem of verify's preflight. */
+export interface PreflightProblem {
+    readonly code: string;
+    readonly message: string;
+    readonly fix: string;
+    /** PORT_IN_USE: the first free port after the taken one (found like the recipe preflight). */
+    readonly alternative?: number;
+    readonly waitForUser?: boolean;
+    readonly question?: string;
+    readonly next?: string;
 }
+/**
+ * The preflight problem for a taken web port (AI-M04 F5), with what the recipe preflight gives:
+ * a free `alternative`, `waitForUser`, `question` and `next`. Who holds the port is not looked up
+ * (no `ps`); verify only knows it is not an app `dokebi start` runs for this project (that is
+ * ALREADY_RUNNING). `delegated`: the last recipe ran with --defaults (`.dokebi/recipe.json`).
+ */
+export declare function webPortProblem(port: number, delegated: boolean): Promise<PreflightProblem>;
 /**
  * Runs an npm script of the project; resolves with its exit code and the bounded, redacted end
- * of its output (stdout and stderr in arrival order, `OutputTail` of npm-client).
+ * of its output (stdout and stderr in arrival order, `OutputTail` of npm-client). The script runs
+ * in its own process group and the time limit kills the whole group: killing npm alone left tsc
+ * or Vite running, and the pipes they hold kept the step open until they ended by themselves.
  */
 export declare function npmScript(root: string, script: string, timeoutMs: number): Promise<{
     code: number | null;
@@ -46,17 +134,38 @@ export interface HttpProbe {
     readonly ok: boolean;
     /** `other`: an answer without this run's token header — another server on the port. */
     readonly instance?: 'ours' | 'other';
+    /**
+     * The identity probe (no readiness route and no app domain): `GET /` passes with any status
+     * below 500 that carries this run's header.
+     */
+    readonly identity?: true;
+    /** A domain answered with 401/403; reachability passed, login was not tested. */
+    readonly accessDenied?: true;
     readonly error?: string;
 }
 /**
  * The HTTP check of verify: GET the readiness path, then `/` of each app domain, at `base`. An
  * answer counts only when it carries `token` in the x-dokebi-verify header (the instance verify
  * started); anything else is retried like a failed request and then reported FOREIGN_SERVER.
+ * With neither a readiness path (`healthRoutes: false`) nor an app domain, one identity probe
+ * runs instead (ISSUE-0006 A08: no request at all used to pass): `GET /`, which passes with any
+ * status below 500 that carries the token, a 404 included (the app may have no route at `/`).
+ * Domain probes also accept 401/403 from this instance, reported as accessDenied: true.
+ * These prove reachability only; readiness still requires 2xx/3xx and login needs app tests.
+ * Each request must complete within `timeoutMs` (ISSUE-0006 A09).
  */
 export declare function httpChecks(base: string, paths: {
     ready: string | null;
     domains: readonly string[];
-}, token: string, delayMs?: number): Promise<Omit<VerifyCheck, 'name' | 'ms'>>;
+}, token: string, delayMs?: number, timeoutMs?: number): Promise<Omit<VerifyCheck, 'name' | 'ms'>>;
+/**
+ * While the app verify started runs: a SIGINT, SIGTERM or SIGHUP to verify (Ctrl+C, an agent's
+ * command time limit) stops that app first (stopStarted, forced after `limitMs`), then ends verify
+ * as the signal would have. Without it the background app outlived verify and held its port; the
+ * next verify then refused with ALREADY_RUNNING. Returns the function that removes the handlers.
+ */
+export declare function stopOnTermination(root: string, started: Pick<server.StartResult, 'pid' | 'logWriter'>, limitMs?: number): () => void;
 export declare function verify(root: string, options?: {
     waitMs?: number;
+    testTimeoutMs?: number;
 }): Promise<VerifyResult>;