@dokebi/cli 0.4.1 → 0.4.26

package/dist/plugin-options.js

@@ -1,10 +1,134 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { ConfigValidator, loadSchema } from '@dokebi/config';
+import { debug, describeError } from './diagnostics.js';
 import { CliError } from './errors.js';
+import { optionsKey } from './manifest.js';
+import { optionsFix } from './option-fixes.js';
+import { readSettingsSchema } from './settings.js';
 import { packageFile } from './workspace.js';
+/** The smallest schema the validator compiles: whether it works at all. */
+const TRIVIAL_SCHEMA = Object.freeze({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    type: 'object',
+});
+/** The version of the @dokebi/config this CLI validates with ('unknown' when it cannot be read). */
+function configVersion() {
+    try {
+        // ESM resolution: @dokebi/config exports only an `import` condition.
+        let directory = dirname(fileURLToPath(import.meta.resolve('@dokebi/config')));
+        for (let depth = 0; depth < 4; depth++) {
+            const file = join(directory, 'package.json');
+            if (existsSync(file)) {
+                const pkg = JSON.parse(readFileSync(file, 'utf8'));
+                if (pkg.name === '@dokebi/config')
+                    return String(pkg.version);
+            }
+            directory = dirname(directory);
+        }
+    }
+    catch (error) {
+        debug('The @dokebi/config version could not be read', { error: describeError(error) });
+    }
+    return 'unknown';
+}
+/**
+ * The first line of an error and of each cause under it, at most 500 characters: why a schema
+ * failed, never a value. @dokebi/config's ConfigError says only "Invalid or unsupported options
+ * schema"; ajv's words (`strict mode: unknown keyword: "x-dokebi-…"`) are its cause (R5C-1).
+ */
+function reasonOf(error) {
+    const lines = [];
+    let current = error ?? 'unknown';
+    for (let depth = 0; depth < 4 && current !== undefined && current !== null; depth++) {
+        const text = current instanceof Error ? `${current.name}: ${current.message}` : String(current);
+        lines.push(text.split('\n')[0] ?? '');
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return lines.join(' <- caused by ').slice(0, 500);
+}
 export class PluginOptionsValidator {
     #validator;
+    /** Whether the validator itself works (a trivial schema compiles); asked once, on a failure. */
+    #works;
     constructor(options = {}) {
-        this.#validator = new ConfigValidator(options);
+        this.#validator =
+            options.validator ??
+                new ConfigValidator({ ...(options.allErrors ? { allErrors: true } : {}) });
+    }
+    /**
+     * AI-M45: a schema that cannot be read or compiled, with the reason. When even a trivial schema
+     * does not compile, the validator itself is broken (a damaged node_modules: ajv's files gone)
+     * and every plugin would be reported: the fix then says to restore the installation.
+     */
+    async #failure(cause, subject, reinstall) {
+        // A schema the validator takes (it refuses one without the 2020-12 `$schema`): with
+        // `{ type: 'object' }` alone the probe always failed, so every schema that did not compile
+        // was reported as a damaged installation with the fix `npm ci`.
+        this.#works ??= this.#validator.check(TRIVIAL_SCHEMA, {}).then(() => true, () => false);
+        const validatorBroken = !(await this.#works);
+        // A schema of a newer release than this CLI's @dokebi/config (2026-10-28: an older CLI met
+        // x-dokebi-secret and x-dokebi-alias-of and was read as a broken installation).
+        const keyword = /unknown keyword:? "?(x-dokebi-[\w-]+)/.exec(reasonOf(cause))?.[1];
+        if (!validatorBroken && keyword !== undefined) {
+            const version = configVersion();
+            return new CliError('INVALID_OPTIONS_SCHEMA', `The options schema of ${String(subject.plugin ?? subject.section)} uses ${keyword}, which the @dokebi/config ${version} of this CLI does not know`, {
+                cause,
+                details: {
+                    ...subject,
+                    reason: reasonOf(cause),
+                    keyword,
+                    config: version,
+                    validator: false,
+                    fix: `the schema comes from a newer release than this CLI: run the @dokebi/cli of the same release as the installed plugins (npm install the matching @dokebi/cli in the project, then npx dokebi), and keep @dokebi/core, @dokebi/config and @dokebi/cli of one release; the installation is not damaged`,
+                },
+                phase: 'plan',
+            });
+        }
+        return new CliError('INVALID_OPTIONS_SCHEMA', validatorBroken
+            ? 'The options schema validator of @dokebi/config cannot load (the installation is damaged)'
+            : `The options schema of ${String(subject.plugin ?? subject.section)} cannot be read or compiled`, {
+            cause,
+            details: {
+                ...subject,
+                reason: reasonOf(cause),
+                validator: validatorBroken,
+                fix: validatorBroken
+                    ? 'restore node_modules with npm ci (or npm install): the JSON Schema validator (ajv, a dependency of @dokebi/config) is missing files, so no options can be checked; every section is reported until then'
+                    : reinstall,
+            },
+            phase: 'plan',
+        });
+    }
+    /**
+     * D-0155: the options of an application settings section against the schema file beside its
+     * declaration (src/shared/settings/<section>.schema.json); no schema yet checks nothing.
+     */
+    async checkSettings(root, section, options) {
+        const schema = await readSettingsSchema(root, section);
+        if (!schema)
+            return { schema: null, errors: [] };
+        try {
+            const checked = await this.#validator.check(schema, options);
+            return { schema, errors: checked.errors };
+        }
+        catch (cause) {
+            throw await this.#failure(cause, { section }, `run npx dokebi settings sync to write src/shared/settings/${section}.schema.json again`);
+        }
+    }
+    /**
+     * A settings section against a schema in hand (`settings sync` checks the options against the
+     * schema it is about to write, before the file is on disk).
+     */
+    async checkSettingsWith(section, schema, options) {
+        try {
+            const checked = await this.#validator.check(schema, options);
+            return { schema, errors: checked.errors };
+        }
+        catch (cause) {
+            throw await this.#failure(cause, { section }, `correct the declaration of ${section} so core renders a valid schema, then npx dokebi settings sync`);
+        }
     }
     async check(root, plugin, options) {
         if (!plugin.optionsSchema)
@@ -16,7 +140,7 @@ export class PluginOptionsValidator {
             return { schema, errors: checked.errors };
         }
         catch (cause) {
-            throw new CliError('INVALID_OPTIONS_SCHEMA', plugin.id, { cause });
+            throw await this.#failure(cause, { plugin: plugin.id, version: plugin.version, schema: plugin.optionsSchema }, `reinstall ${plugin.packageName} (npm install), or use another version of it; details.reason says why`);
         }
     }
 }
@@ -24,12 +148,20 @@ export async function checkPluginOptions(root, plugin, options) {
     return new PluginOptionsValidator().check(root, plugin, options);
 }
 export async function validatePluginOptions(root, plugins, options) {
-    const validator = new PluginOptionsValidator();
+    // Every issue (D-0153): the fix names all unknown keys in one config unset.
+    const validator = new PluginOptionsValidator({ allErrors: true });
     for (const plugin of plugins) {
-        const result = await validator.check(root, plugin, Object.hasOwn(options, plugin.id) ? (options[plugin.id] ?? {}) : {});
+        // D-0151: the logger host's options are options.logging.
+        const key = optionsKey(plugin);
+        const result = await validator.check(root, plugin, Object.hasOwn(options, key) ? (options[key] ?? {}) : {});
         if (result.errors.length)
-            throw new CliError('INVALID_PLUGIN_OPTIONS', plugin.id, {
-                details: { plugin: plugin.id, errors: result.errors },
+            throw new CliError('INVALID_PLUGIN_OPTIONS', `The options of ${plugin.id} do not match its schema: options.${key}${(result.errors[0]?.instancePath ?? '').replaceAll('/', '.')} (${result.errors[0]?.keyword ?? 'invalid'})`, {
+                details: {
+                    plugin: plugin.id,
+                    errors: result.errors,
+                    fix: optionsFix(plugin.id, result.errors, `correct options.${key} in dokebi.yaml (npx dokebi plugins info ${plugin.id} --json lists the option keys)`, key, result.schema),
+                },
+                phase: 'plan',
             });
     }
 }

package/dist/plugins-command.js

@@ -109,9 +109,14 @@ export async function pluginsList(root, options) {
 export async function pluginsSearch(query) {
     return searchCatalog(await loadCatalog(), query);
 }
-function unknownPackage(catalog, key) {
+function unknownPackage(catalog, key, 
+/** An installed package the key names by its short name (AI-M04 F7), with its guide's path. */
+installed) {
     const search = searchCatalog(catalog, key);
-    return new CliError('UNKNOWN_PLUGIN', `No Dokebi package "${key}"`, {
+    const fix = installed
+        ? `npx dokebi plugins doc ${installed.package} --json (or read ${installed.path})`
+        : undefined;
+    return new CliError('UNKNOWN_PLUGIN', `No Dokebi package "${key}"${installed ? `; did you mean ${installed.package}? ${fix}` : ''}`, {
         phase: 'arguments',
         details: {
             query: key,
@@ -121,10 +126,44 @@ function unknownPackage(catalog, key) {
                 summary: entry.summary,
                 instead: entry.instead,
             })),
-            hint: 'npx dokebi plugins search <words> --json',
+            ...(installed && fix ? { package: installed.package, path: installed.path, fix } : {}),
+            hint: fix ?? 'npx dokebi plugins search <words> --json',
         },
     });
 }
+/** The guide path of an installed package's package.json (`dokebi.documentation`, else AI.md). */
+function documentationPath(packageName, pkg) {
+    const manifest = pkg.dokebi;
+    const documentation = typeof manifest?.documentation === 'string' ? manifest.documentation : 'AI.md';
+    return `node_modules/${packageName}/${documentation}`;
+}
+/**
+ * An id that is not in the catalog but names an installed @dokebi package by its short name
+ * (`dokebi-core`, `dokebi-cli`: core, CLI and drivers have no plugin id), AI-M04 F7.
+ */
+async function installedByShortName(root, key) {
+    const short = key
+        .trim()
+        .toLowerCase()
+        .replace(/^@dokebi\//, '')
+        .replace(/^dokebi-/, '');
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(short))
+        return undefined;
+    const packageName = `@dokebi/${short}`;
+    try {
+        const pkg = parseObject(await readFile(await packageFile(root, packageName, 'package.json'), 'utf8'), packageName);
+        return { package: packageName, path: documentationPath(packageName, pkg) };
+    }
+    catch (error) {
+        if (!isMissing(error) && !(error instanceof CliError))
+            throw error;
+        debug('plugins doc: no installed package by that short name', {
+            package: packageName,
+            error: describeError(error),
+        });
+        return undefined;
+    }
+}
 export async function pluginsInfo(root, key) {
     const catalog = await loadCatalog();
     const item = findPackage(catalog, key);
@@ -146,7 +185,7 @@ export async function pluginsDoc(root, key) {
     const item = findPackage(catalog, key);
     const packageName = item?.package ?? (key.startsWith('@') ? key : undefined);
     if (!packageName)
-        throw unknownPackage(catalog, key);
+        throw unknownPackage(catalog, key, await installedByShortName(root, key));
     let pkg;
     try {
         pkg = parseObject(await readFile(await packageFile(root, packageName, 'package.json'), 'utf8'), packageName);
@@ -167,9 +206,7 @@ export async function pluginsDoc(root, key) {
             },
         });
     }
-    const manifest = pkg.dokebi;
-    const documentation = typeof manifest?.documentation === 'string' ? manifest.documentation : 'AI.md';
-    const path = `node_modules/${packageName}/${documentation}`;
+    const path = documentationPath(packageName, pkg);
     let content;
     try {
         content = await readFile(await installedPath(root, path), 'utf8');

package/dist/process-group.d.ts

@@ -0,0 +1,39 @@
+/** Spawn with `detached: PROCESS_GROUPS`: on POSIX the child then leads a new process group. */
+export declare const PROCESS_GROUPS: boolean;
+/**
+ * Signals the process group of `pid` (POSIX; the child leads it) or the child alone (Windows):
+ * true when the signal was sent, false when nothing of the group is left (ESRCH, the expected
+ * case after a clean run) or it could not be signalled (logged at debug: the caller decides).
+ */
+export declare function killGroup(pid: number | undefined, signal: NodeJS.Signals): boolean;
+/**
+ * Whether the process group `pid` led still has a member (POSIX). A group outlives its leader
+ * while a member runs, and its id is not reused as long as it exists, so a member found here
+ * right after the leader exited is one the leader started.
+ */
+export declare function groupAlive(pid: number): boolean;
+/**
+ * Ends what is left of the process group of `pid` after its leader exited: processes the leader
+ * started and did not stop (a helper, a server holding a port). SIGTERM first, SIGKILL after
+ * `graceMs`. `none` when nothing was left (the usual case), else how they were ended.
+ */
+export declare function endLeftovers(pid: number, graceMs: number): Promise<'none' | 'terminated' | 'killed'>;
+/** The signals that end a command (Ctrl+C, an agent's command time limit, a closed terminal). */
+export declare const TERMINATING: readonly ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/**
+ * Holds off a terminating signal while a step must clean up first: the first SIGINT, SIGTERM or
+ * SIGHUP is recorded (`signal()`) instead of ending the process at once, so the step can see it,
+ * undo what it started and throw. `release()` removes the handlers and, when a signal came and
+ * nobody else listens for it, ends this process as that signal would have.
+ */
+export declare function holdTermination(): {
+    signal(): NodeJS.Signals | undefined;
+    release(): void;
+};
+/**
+ * A detached group no longer gets the terminal's Ctrl+C (nor a SIGTERM or SIGHUP sent to this
+ * process). While the child runs, this passes such a signal on to its group and then lets this
+ * process end as it would have without the listener. Returns the function that stops forwarding;
+ * call it once the child closed.
+ */
+export declare function forwardTermination(pid: number | undefined): () => void;

package/dist/process-group.js

@@ -0,0 +1,132 @@
+// Child commands that may start their own children (npm run, Vite, tsc, test runners) run in a
+// process group of their own, so a time limit can end all of them. Killing only the direct child
+// leaves the grandchildren running, and as they still hold the stdout/stderr pipes the child's
+// 'close' event (and the step waiting for it) would not come until they end by themselves.
+import { debug, describeError } from './diagnostics.js';
+/** Spawn with `detached: PROCESS_GROUPS`: on POSIX the child then leads a new process group. */
+export const PROCESS_GROUPS = process.platform !== 'win32';
+/**
+ * Signals the process group of `pid` (POSIX; the child leads it) or the child alone (Windows):
+ * true when the signal was sent, false when nothing of the group is left (ESRCH, the expected
+ * case after a clean run) or it could not be signalled (logged at debug: the caller decides).
+ */
+export function killGroup(pid, signal) {
+    if (pid === undefined)
+        return false;
+    try {
+        if (PROCESS_GROUPS)
+            process.kill(-pid, signal);
+        else
+            process.kill(pid, signal);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== 'ESRCH')
+            debug('Could not signal the process group', {
+                pid,
+                signal,
+                error: describeError(error),
+            });
+        return false;
+    }
+}
+/**
+ * Whether the process group `pid` led still has a member (POSIX). A group outlives its leader
+ * while a member runs, and its id is not reused as long as it exists, so a member found here
+ * right after the leader exited is one the leader started.
+ */
+export function groupAlive(pid) {
+    if (!PROCESS_GROUPS)
+        return false;
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        // ESRCH: nobody is left. EPERM: a member this user may not signal (not one the app started).
+        if (error.code !== 'ESRCH')
+            debug('Could not probe the process group', { pid, error: describeError(error) });
+        return false;
+    }
+}
+/**
+ * Ends what is left of the process group of `pid` after its leader exited: processes the leader
+ * started and did not stop (a helper, a server holding a port). SIGTERM first, SIGKILL after
+ * `graceMs`. `none` when nothing was left (the usual case), else how they were ended.
+ */
+export async function endLeftovers(pid, graceMs) {
+    if (!groupAlive(pid))
+        return 'none';
+    debug('Processes are left in the group of an exited process; ending them', { pid, graceMs });
+    killGroup(pid, 'SIGTERM');
+    const until = performance.now() + graceMs;
+    while (performance.now() < until) {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        if (!groupAlive(pid))
+            return 'terminated';
+    }
+    killGroup(pid, 'SIGKILL');
+    debug('Processes left in the group did not end on SIGTERM; killed', { pid, graceMs });
+    return 'killed';
+}
+/** The signals that end a command (Ctrl+C, an agent's command time limit, a closed terminal). */
+export const TERMINATING = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/**
+ * Holds off a terminating signal while a step must clean up first: the first SIGINT, SIGTERM or
+ * SIGHUP is recorded (`signal()`) instead of ending the process at once, so the step can see it,
+ * undo what it started and throw. `release()` removes the handlers and, when a signal came and
+ * nobody else listens for it, ends this process as that signal would have.
+ */
+export function holdTermination() {
+    let received;
+    const handlers = new Map();
+    for (const signal of TERMINATING) {
+        const handler = () => {
+            if (received)
+                return;
+            received = signal;
+            debug('A termination signal arrived; cleaning up before ending', { signal });
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+    return {
+        signal: () => received,
+        release: () => {
+            for (const [signal, handler] of handlers)
+                process.off(signal, handler);
+            handlers.clear();
+            if (received && process.listenerCount(received) === 0)
+                process.kill(process.pid, received);
+        },
+    };
+}
+/**
+ * A detached group no longer gets the terminal's Ctrl+C (nor a SIGTERM or SIGHUP sent to this
+ * process). While the child runs, this passes such a signal on to its group and then lets this
+ * process end as it would have without the listener. Returns the function that stops forwarding;
+ * call it once the child closed.
+ */
+export function forwardTermination(pid) {
+    const handlers = new Map();
+    const stop = () => {
+        for (const [signal, handler] of handlers)
+            process.off(signal, handler);
+        handlers.clear();
+    };
+    if (!PROCESS_GROUPS || pid === undefined)
+        return stop;
+    for (const signal of TERMINATING) {
+        const handler = () => {
+            debug('Passing a termination signal on to the child process group', { pid, signal });
+            killGroup(pid, signal);
+            stop();
+            // Nobody else listens: the signal's default action (ending this process) applies again.
+            if (process.listenerCount(signal) === 0)
+                process.kill(process.pid, signal);
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+    return stop;
+}

package/dist/project-guide.d.ts

@@ -1,3 +1,4 @@
+import type { Catalog } from './catalog.js';
 import type { PluginManifest } from './manifest.js';
 import type { RequiredPlugin } from './required-plugins.js';
 /** Markers of the CLI-maintained list of installed packages in AGENTS.md (D-0065). */
@@ -7,6 +8,12 @@ export declare const AGENTS_FILE = "AGENTS.md";
 export declare const CLAUDE_FILE = "CLAUDE.md";
 /** CLAUDE.md of a new project: Claude Code reads AGENTS.md through this import line. */
 export declare const CLAUDE_GUIDE = "@AGENTS.md\n";
+/**
+ * Markers of the project's own block in AGENTS.md (D-0077 G): the people of the project (or their
+ * tools) write rules there; the CLI never changes what is between them and doctor never judges it.
+ */
+export declare const PROJECT_START = "<!-- dokebi:project:start -->";
+export declare const PROJECT_END = "<!-- dokebi:project:end -->";
 /** One row of the installed list: a package, its version and its AI guide path. */
 export interface InstalledEntry {
     readonly id: string;
@@ -32,5 +39,16 @@ export declare function installedBlockEdited(text: string, entries: readonly Ins
  * of order (the developer removed them; doctor reports GUIDE_BLOCK_MISSING and the file stays).
  */
 export declare function replaceInstalledBlock(text: string, block: string): string | undefined;
+/** The project block as init writes it (and as it is added to an older AGENTS.md). */
+export declare function projectBlock(): string;
+/**
+ * The state of the project block in an AGENTS.md text: `ok` (one start, then one end, outside
+ * the installed list), `missing` (no marker at all: the next add, upgrade or remove adds an
+ * empty block) or `invalid` (a marker alone, repeated, out of order, or inside the installed
+ * list: doctor warns GUIDE_PROJECT_BLOCK_INVALID and the CLI leaves the file alone).
+ */
+export declare function projectBlockState(text: string): 'ok' | 'missing' | 'invalid';
+/** The text with an empty project block (and its heading) added at the end. */
+export declare function withProjectBlock(text: string): string;
 /** AGENTS.md of a new project (D-0065 skeleton): ask first, use the catalog, verify last. */
-export declare function projectGuide(entries: readonly InstalledEntry[]): string;
+export declare function projectGuide(entries: readonly InstalledEntry[], catalog?: Catalog): string;