@dokebi/cli 0.2.5 → 0.4.0

package/dist/log-writer.js

@@ -8,9 +8,16 @@
 // The CLI listens on the IPC channel until the start is decided: { spawned: pid }, { ready: true }
 // when the start line passes, { exited: code, signal } and { failed: text }. The writer's own
 // errors go to its stderr, which the CLI points at `.dokebi/run/log-writer.log`.
+//
+// Before it starts the app it listens on a loopback control port (log-writer-control.ts, D-0073
+// addendum) and tells the CLI `{ control: port }`, which goes into the pid file: a later
+// `dokebi stop` that may not signal the app (an agent sandbox per command) asks the writer, its
+// parent, to stop it. Both sides prove the app's DOKEBI_INSTANCE_TOKEN first.
 import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
 import { debug, describeError, reportError } from './diagnostics.js';
-import { LineBuffer, RotatingLog } from './rotating-log.js';
+import { ControlServer } from './log-writer-control.js';
+import { forwardOutput, LineBuffer, RotatingLog } from './rotating-log.js';
 /** Written by the generated `src/main.ts` once `app.start()` resolved. */
 const STARTED = 'Dokebi application started';
 /** How long the pipes may stay open after the app exited (a child it left holds them). */
@@ -43,8 +50,23 @@ if (!file ||
     send({ failed: text }, () => process.exit(2));
 }
 else
-    run(file, maxBytes, keep, entry);
-function run(file, maxBytes, keep, entry) {
+    void openControl().then((control) => run(file, maxBytes, keep, entry, control));
+/** The control port (D-0073 addendum); none without the instance token or when listen fails. */
+async function openControl() {
+    const token = process.env.DOKEBI_INSTANCE_TOKEN;
+    if (!token) {
+        debug('No instance token; the control port is not opened');
+        return undefined;
+    }
+    const control = new ControlServer(token);
+    // Without the port (a sandbox that refuses it), stop needs a shell that may signal the app.
+    const port = await control.listen();
+    if (port === undefined)
+        return undefined;
+    send({ control: port });
+    return control;
+}
+function run(file, maxBytes, keep, entry, control) {
     for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'])
         process.on(signal, () => debug('Log writer ignores the signal; it exits when the app exits', { signal }));
     const log = new RotatingLog(file, maxBytes, keep);
@@ -58,7 +80,11 @@ function run(file, maxBytes, keep, entry) {
     }
     log.write(Buffer.from(`\n--- dokebi start ${new Date().toISOString()} ---\n`));
     const app = spawn(process.execPath, [entry], { stdio: ['ignore', 'pipe', 'pipe'] });
-    let ready = false;
+    // `ready` goes to the CLI only after the start line is in app.log (forwardOutput).
+    const write = forwardOutput(log, STARTED, () => {
+        debug('Start line written to the app log', { pid: app.pid });
+        send({ ready: true });
+    });
     let exit;
     let open = 2;
     let finished = false;
@@ -71,7 +97,9 @@ function run(file, maxBytes, keep, entry) {
         log.write(Buffer.from(`--- dokebi: app exited (${how}) ---\n`));
         log.close();
         debug('Log writer finished', { pid: app.pid, code: exit.code, signal: exit.signal });
-        send({ exited: exit.code, signal: exit.signal }, () => process.exit(0));
+        const { code, signal } = exit;
+        // A client waiting on the control port learns that the writer is done when it closes.
+        void (control?.close() ?? Promise.resolve()).then(() => send({ exited: code, signal }, () => process.exit(0)));
     };
     app.once('error', (error) => {
         // spawn failed (the app never ran): there is no exit event to wait for.
@@ -83,6 +111,8 @@ function run(file, maxBytes, keep, entry) {
     if (app.pid !== undefined) {
         debug('App process spawned by the log writer', { pid: app.pid, maxBytes, keep });
         send({ spawned: app.pid });
+        const exited = new Promise((resolve) => app.once('exit', () => resolve()));
+        control?.attach(controlled(app.pid, () => exit === undefined, exited));
     }
     app.once('exit', (code, signal) => {
         exit = { code, signal };
@@ -104,13 +134,6 @@ function run(file, maxBytes, keep, entry) {
             return;
         const lines = new LineBuffer();
         let timer;
-        const write = (data) => {
-            if (!ready && data.includes(STARTED)) {
-                ready = true;
-                send({ ready: true });
-            }
-            log.write(data);
-        };
         stream.on('data', (chunk) => {
             const whole = lines.push(chunk);
             if (whole)
@@ -131,3 +154,21 @@ function run(file, maxBytes, keep, entry) {
     follow(app.stdout, 'stdout');
     follow(app.stderr, 'stderr');
 }
+/** The app as the control port drives it: signals go to its pid, exits are awaited. */
+function controlled(pid, running, exit) {
+    return {
+        pid,
+        running,
+        exited: (ms) => Promise.race([exit.then(() => true), delay(ms, false)]),
+        signal: (signal) => {
+            try {
+                process.kill(pid, signal);
+            }
+            catch (error) {
+                // ESRCH: the app exited meanwhile, which the stop sees as exited. Anything else is logged.
+                if (error.code !== 'ESRCH')
+                    reportError('APP_SIGNAL_FAILED', 'Unable to signal the app', error);
+            }
+        },
+    };
+}

package/dist/manifest.d.ts

@@ -1,3 +1,4 @@
+import { type FileOwner } from './install-plan.js';
 export interface Dependency {
     name: string;
     version: string;
@@ -8,6 +9,8 @@ export interface Dependency {
 export interface Template {
     source: string;
     target: string;
+    /** Who edits the file (absent: `user`). */
+    owner?: FileOwner;
 }
 export interface PluginManifest {
     packageName: string;
@@ -22,9 +25,34 @@ export interface PluginManifest {
     optionsSchema?: string;
     documentation?: string;
     installModule?: string;
+    /** D-0070: contribution points the plugin contributes to (its `definePlugin` `contributes`). */
+    contributes?: string[];
+    /** D-0070: contribution points the plugin collects (its `definePlugin` `collects`). */
+    collects?: string[];
+    /** D-0070: CLI-managed units this plugin receives (`apps`, `modules`). */
+    hosts?: HostRole[];
 }
 export declare const PACKAGE_NAME: RegExp;
 export declare const ID: RegExp;
+/** A contribution point name, `<owner>:<name>` (the same rule as core's definePoint). */
+export declare const POINT: RegExp;
+/**
+ * The install-time roles a manifest may declare in `dokebi.hosts` (D-0070), a closed list:
+ * - `apps`: receives the apps of `dokebi app add|link|unlink|remove` (src/apps/<name>/app.ts as
+ *   `entry.apps`), owns `src/apps/`, keeps their domains and settings in its options section
+ *   (`domains`, `apps`) and ships the app skeletons (`templates/app*`, `templates/inertia-build`).
+ * - `modules`: receives the modules of `dokebi module add|remove` (src/shared/modules/<name>/
+ *   module.ts appended to `entry.modules`) and ships their skeletons (`templates/module*`).
+ */
+export declare const HOST_ROLES: readonly ['apps', 'modules'];
+export type HostRole = (typeof HOST_ROLES)[number];
+/**
+ * The installed plugin that hosts `role` (D-0070). More than one is HOST_CONFLICT; none is
+ * HOST_MISSING, whose fix names the command that installs one.
+ */
+export declare function hostOf(plugins: readonly PluginManifest[], role: HostRole): PluginManifest;
+/** Like hostOf, but undefined when no installed plugin hosts `role`. */
+export declare function findHost(plugins: readonly PluginManifest[], role: HostRole): PluginManifest | undefined;
 /**
  * Reads package.json `dokebi` metadata. Schema 1 keeps the legacy top-level files list.
  * Schema 2 moves files into `install` and adds optional dependencies, entry and defaults.

package/dist/manifest.js

@@ -7,6 +7,68 @@ import { readInstallPlan } from './install-plan.js';
 import { assertLayout } from './layout.js';
 export const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 export const ID = /^[a-z0-9][a-z0-9._/-]*$/;
+/** A contribution point name, `<owner>:<name>` (the same rule as core's definePoint). */
+export const POINT = /^[a-z0-9][a-z0-9._/-]{0,95}:[a-z0-9][a-z0-9._-]{0,63}$/;
+/**
+ * The install-time roles a manifest may declare in `dokebi.hosts` (D-0070), a closed list:
+ * - `apps`: receives the apps of `dokebi app add|link|unlink|remove` (src/apps/<name>/app.ts as
+ *   `entry.apps`), owns `src/apps/`, keeps their domains and settings in its options section
+ *   (`domains`, `apps`) and ships the app skeletons (`templates/app*`, `templates/inertia-build`).
+ * - `modules`: receives the modules of `dokebi module add|remove` (src/shared/modules/<name>/
+ *   module.ts appended to `entry.modules`) and ships their skeletons (`templates/module*`).
+ */
+export const HOST_ROLES = ['apps', 'modules'];
+/** At most this many points per list (core's definePlugin limit). */
+const MAX_POINTS = 64;
+/**
+ * The installed plugin that hosts `role` (D-0070). More than one is HOST_CONFLICT; none is
+ * HOST_MISSING, whose fix names the command that installs one.
+ */
+export function hostOf(plugins, role) {
+    const found = plugins.filter((plugin) => plugin.hosts?.includes(role));
+    if (found.length > 1)
+        throw new CliError('HOST_CONFLICT', `More than one installed plugin hosts ${role}: ${found.map((plugin) => plugin.id).join(', ')}`, { details: { role, plugins: found.map((plugin) => plugin.id) } });
+    const [host] = found;
+    if (!host)
+        throw new CliError('HOST_MISSING', `No installed plugin hosts ${role} (package.json dokebi.hosts, D-0070); install one with npx dokebi plugins search ${role}, or upgrade the plugin that provides ${role} to a version that declares it`, { details: { role } });
+    return host;
+}
+/** Like hostOf, but undefined when no installed plugin hosts `role`. */
+export function findHost(plugins, role) {
+    return plugins.some((plugin) => plugin.hosts?.includes(role)) ? hostOf(plugins, role) : undefined;
+}
+/** `dokebi.contributes` / `dokebi.collects`: distinct point names (D-0070). */
+function readPoints(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) ||
+        value.length > MAX_POINTS ||
+        value.some((item) => typeof item !== 'string' || !POINT.test(item)) ||
+        new Set(value).size !== value.length)
+        throw new CliError('INVALID_MANIFEST', `dokebi.${label} must list distinct point names`);
+    return [...value];
+}
+/** `dokebi.hosts`: distinct roles from HOST_ROLES (D-0070). */
+function readHosts(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) ||
+        value.some((item) => !HOST_ROLES.includes(item)) ||
+        new Set(value).size !== value.length)
+        throw new CliError('INVALID_MANIFEST', `dokebi.hosts must list distinct roles from: ${HOST_ROLES.join(', ')}`);
+    return [...value];
+}
+/** The D-0070 fields of a manifest, only those present (a stored manifest round-trips). */
+function readRoles(metadata) {
+    const contributes = readPoints(metadata.contributes, 'contributes');
+    const collects = readPoints(metadata.collects, 'collects');
+    const hosts = readHosts(metadata.hosts);
+    return {
+        ...(contributes ? { contributes } : {}),
+        ...(collects ? { collects } : {}),
+        ...(hosts ? { hosts } : {}),
+    };
+}
 function field(value, label) {
     if (typeof value !== 'string' || !value)
         throw new CliError('INVALID_MANIFEST', label);
@@ -91,9 +153,19 @@ export function readManifest(value, options = {}) {
     }
     const legacyFiles = readInstallPlan({ files: legacy }, [], false).files;
     const install = readInstallPlan(metadata.install, legacyFiles, extended);
+    const roles = readRoles(metadata);
     if (options.checkLayout !== false)
-        assertLayout(install, id);
-    return { packageName, version, id, core, dependencies, ...install, ...readResources(metadata) };
+        assertLayout(install, id, roles.hosts ?? []);
+    return {
+        packageName,
+        version,
+        id,
+        core,
+        dependencies,
+        ...install,
+        ...readResources(metadata),
+        ...roles,
+    };
 }
 /** Reads a manifest previously normalized into .dokebi/state.json. */
 export function readStoredManifest(value) {
@@ -119,6 +191,9 @@ export function readStoredManifest(value) {
             ...(stored.optionsSchema === undefined ? {} : { optionsSchema: stored.optionsSchema }),
             ...(stored.documentation === undefined ? {} : { documentation: stored.documentation }),
             ...(stored.installModule === undefined ? {} : { installModule: stored.installModule }),
+            ...(stored.contributes === undefined ? {} : { contributes: stored.contributes }),
+            ...(stored.collects === undefined ? {} : { collects: stored.collects }),
+            ...(stored.hosts === undefined ? {} : { hosts: stored.hosts }),
         },
     }, { checkLayout: false });
 }

package/dist/npm-client.d.ts

@@ -10,3 +10,52 @@ export declare class NpmClient {
     /** `npm install` at a workspace root: brings its lock and node_modules in line (D-0035). */
     installWorkspace(root: string): Promise<void>;
 }
+export interface NpmRun {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly timedOut: boolean;
+    /** The last NPM_OUTPUT_TAIL_BYTES bytes of each stream, redacted. */
+    readonly stderr: string;
+    readonly stdout: string;
+}
+/**
+ * Runs npm in `directory` (the npm that started this CLI when there is one, else `npm` on PATH)
+ * and keeps the bounded, redacted end of both streams. Every npm call of the CLI goes through
+ * here. `--loglevel=warn` is always added: an inherited `loglevel=silent` (`npx -s` and
+ * `npm run -s` export `npm_config_loglevel=silent` to their child) makes npm print nothing, not
+ * even its error, and NPM_FAILED then had empty `stderr`/`stdout`. npm's debug log file keeps
+ * every level either way. Rejects (NPM_FAILED) only when npm cannot be started; the exit code is
+ * the caller's to judge.
+ */
+export declare function runNpm(directory: string, npmArgs: readonly string[], options: {
+    readonly timeoutMs: number;
+}): Promise<NpmRun>;
+/**
+ * Copies the project's `.npmrc` into a staging folder. `configRoot` is the folder npm reads the
+ * project config from: the project, or the workspace root for a member. npm reads that file
+ * only at its local prefix, and a staging folder with its own package.json is one, so without the
+ * copy an install there ignores e.g. a project `@dokebi:registry` that version resolution
+ * honoured (registry.ts asks npm in the project folder).
+ */
+export declare function stageNpmConfig(configRoot: string, staging: string): Promise<boolean>;
+/** npm output that means the registry could not be reached (offline, DNS, proxy, timeout). */
+export declare function networkFailure(output: string): boolean;
+/** Bytes of npm output kept per stream for NPM_FAILED details. */
+export declare const NPM_OUTPUT_TAIL_BYTES = 4096;
+/**
+ * The last NPM_OUTPUT_TAIL_BYTES bytes of process output, as redacted text. The one helper for
+ * every child output the CLI puts in a result: npm (`runNpm`), project scripts that verify runs
+ * (typecheck, build) and recipe step commands, so a credential printed by a build never lands
+ * in `--json` (D-0047: only secrets are masked, nothing else is cut but the bound).
+ */
+export declare class OutputTail {
+    #private;
+    bytes: number;
+    push(chunk: Buffer): void;
+    text(): string;
+}
+/**
+ * Removes credentials npm may print: `user:password@` in URLs, `_authToken=`/`_auth=`/
+ * `_password=` values (npmrc lines), bearer tokens and npm access tokens (`npm_…`).
+ */
+export declare function redactNpmOutput(text: string): string;

package/dist/npm-client.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
 import { readdir, readFile, writeFile } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
-import { debug } from './diagnostics.js';
+import { debug, isMissing } from './diagnostics.js';
 import { CliError } from './errors.js';
 import { json, object, parseObject } from './filesystem.js';
 import { PACKAGE_NAME } from './manifest.js';
@@ -42,16 +42,40 @@ export function validateProjectPackage(pkg) {
 export class NpmClient {
     /** Installs into a standalone directory (the project or the CLI's staging). */
     async install(directory, spec) {
-        await this.#run(directory, [
-            'install',
-            ...(spec ? [spec] : []),
-            '--ignore-scripts',
-            '--save-exact',
-            '--no-audit',
-            '--no-fund',
-            '--workspaces=false',
-            '--package-lock=true',
-        ]);
+        try {
+            await this.#run(directory, [
+                'install',
+                ...(spec ? [spec] : []),
+                '--ignore-scripts',
+                '--save-exact',
+                '--no-audit',
+                '--no-fund',
+                '--workspaces=false',
+                '--package-lock=true',
+            ]);
+        }
+        catch (error) {
+            // Every install runs in a staging folder (or the new project before it is moved into
+            // place), so the project is untouched: `stage` lets the envelope say mutation none.
+            if (!(error instanceof CliError) || error.code !== 'NPM_FAILED')
+                throw error;
+            const details = (error.details ?? {});
+            const network = networkFailure(`${details.stderr ?? ''}\n${details.stdout ?? ''}`);
+            throw new CliError('NPM_FAILED', error.message, {
+                cause: error.cause ?? error,
+                details: {
+                    ...details,
+                    stage: 'staging',
+                    ...(network
+                        ? {
+                            network: true,
+                            hint: 'the registry was not reachable: retry when online, or with packages from the npm cache: npm_config_prefer_offline=true npx dokebi …',
+                        }
+                        : {}),
+                },
+                phase: 'install',
+            });
+        }
         for (const file of ['package.json', 'package-lock.json']) {
             const content = parseObject(await readFile(resolve(directory, file), 'utf8'), file);
             if (file === 'package.json')
@@ -75,38 +99,135 @@ export class NpmClient {
         await this.#run(root, ['install', '--ignore-scripts', '--no-audit', '--no-fund']);
     }
     async #run(directory, npmArgs) {
-        const npmScript = process.env.npm_execpath;
-        const command = npmScript?.endsWith('npm-cli.js') ? process.execPath : 'npm';
-        const args = [...(npmScript?.endsWith('npm-cli.js') ? [npmScript] : []), ...npmArgs];
-        const began = performance.now();
-        debug('Running npm', { args: npmArgs.slice(0, 16), directory });
-        await new Promise((resolvePromise, reject) => {
-            const child = spawn(command, args, {
-                cwd: directory,
-                stdio: 'ignore',
-            });
-            let timedOut = false;
-            const timer = setTimeout(() => {
-                timedOut = true;
-                child.kill('SIGKILL');
-            }, 120000);
-            child.on('error', (cause) => {
-                clearTimeout(timer);
-                reject(new CliError('NPM_FAILED', 'Could not execute npm', { cause }));
+        const result = await runNpm(directory, npmArgs, { timeoutMs: 120_000 });
+        if (result.exitCode === 0 && !result.timedOut)
+            return;
+        throw new CliError('NPM_FAILED', result.timedOut ? 'npm timed out' : `npm failed with exit code ${result.exitCode}`, {
+            details: {
+                command: npmArgs[0],
+                exitCode: result.exitCode,
+                signal: result.signal,
+                timedOut: result.timedOut,
+                stderr: result.stderr,
+                stdout: result.stdout,
+            },
+        });
+    }
+}
+/**
+ * Runs npm in `directory` (the npm that started this CLI when there is one, else `npm` on PATH)
+ * and keeps the bounded, redacted end of both streams. Every npm call of the CLI goes through
+ * here. `--loglevel=warn` is always added: an inherited `loglevel=silent` (`npx -s` and
+ * `npm run -s` export `npm_config_loglevel=silent` to their child) makes npm print nothing, not
+ * even its error, and NPM_FAILED then had empty `stderr`/`stdout`. npm's debug log file keeps
+ * every level either way. Rejects (NPM_FAILED) only when npm cannot be started; the exit code is
+ * the caller's to judge.
+ */
+export function runNpm(directory, npmArgs, options) {
+    const npmScript = process.env.npm_execpath;
+    const viaNode = npmScript?.endsWith('npm-cli.js') === true;
+    const command = viaNode ? process.execPath : 'npm';
+    const args = [...(viaNode ? [npmScript] : []), ...npmArgs, '--loglevel=warn'];
+    const began = performance.now();
+    debug('Running npm', { args: npmArgs.slice(0, 16), directory });
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(command, args, { cwd: directory, stdio: ['ignore', 'pipe', 'pipe'] });
+        // npm's own words are the cause of a failure: keep the end of both streams (bounded).
+        const stdout = new OutputTail();
+        const stderr = new OutputTail();
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, options.timeoutMs);
+        child.on('error', (cause) => {
+            clearTimeout(timer);
+            reject(new CliError('NPM_FAILED', 'Could not execute npm', {
+                cause,
+                details: { command: npmArgs[0], directory },
+            }));
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            debug('npm finished', {
+                command: npmArgs[0],
+                exitCode: code,
+                signal,
+                timedOut,
+                ms: Math.round(performance.now() - began),
+                stdoutBytes: stdout.bytes,
+                stderrBytes: stderr.bytes,
             });
-            child.on('close', (code) => {
-                clearTimeout(timer);
-                debug('npm finished', {
-                    command: npmArgs[0],
-                    exitCode: code,
-                    timedOut,
-                    ms: Math.round(performance.now() - began),
-                });
-                if (code === 0 && !timedOut)
-                    resolvePromise();
-                else
-                    reject(new CliError('NPM_FAILED', timedOut ? 'npm timed out' : `npm failed with exit code ${code}`));
+            resolvePromise({
+                exitCode: code,
+                signal,
+                timedOut,
+                stderr: stderr.text(),
+                stdout: stdout.text(),
             });
         });
+    });
+}
+/**
+ * Copies the project's `.npmrc` into a staging folder. `configRoot` is the folder npm reads the
+ * project config from: the project, or the workspace root for a member. npm reads that file
+ * only at its local prefix, and a staging folder with its own package.json is one, so without the
+ * copy an install there ignores e.g. a project `@dokebi:registry` that version resolution
+ * honoured (registry.ts asks npm in the project folder).
+ */
+export async function stageNpmConfig(configRoot, staging) {
+    let content;
+    try {
+        content = await readFile(resolve(configRoot, '.npmrc'));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
     }
+    await writeFile(resolve(staging, '.npmrc'), content, { mode: 0o600 });
+    debug('Project npm config copied into staging', { from: configRoot, staging });
+    return true;
+}
+/** npm output that means the registry could not be reached (offline, DNS, proxy, timeout). */
+export function networkFailure(output) {
+    return /\b(ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENETUNREACH|EHOSTUNREACH|ENOTCACHED)\b|network request|fetch failed|request to \S+ failed/i.test(output);
+}
+/** Bytes of npm output kept per stream for NPM_FAILED details. */
+export const NPM_OUTPUT_TAIL_BYTES = 4096;
+/**
+ * The last NPM_OUTPUT_TAIL_BYTES bytes of process output, as redacted text. The one helper for
+ * every child output the CLI puts in a result: npm (`runNpm`), project scripts that verify runs
+ * (typecheck, build) and recipe step commands, so a credential printed by a build never lands
+ * in `--json` (D-0047: only secrets are masked, nothing else is cut but the bound).
+ */
+export class OutputTail {
+    #buffer = Buffer.alloc(0);
+    bytes = 0;
+    push(chunk) {
+        this.bytes += chunk.length;
+        const joined = Buffer.concat([this.#buffer, chunk]);
+        this.#buffer =
+            joined.length > NPM_OUTPUT_TAIL_BYTES
+                ? joined.subarray(joined.length - NPM_OUTPUT_TAIL_BYTES)
+                : joined;
+    }
+    text() {
+        // A cut multi-byte character at the start decodes as U+FFFD; drop it.
+        const text = this.#buffer.toString('utf8').replace(/^\uFFFD+/, '');
+        return redactNpmOutput(this.bytes > this.#buffer.length ? `…${text}` : text);
+    }
+}
+/**
+ * Removes credentials npm may print: `user:password@` in URLs, `_authToken=`/`_auth=`/
+ * `_password=` values (npmrc lines), bearer tokens and npm access tokens (`npm_…`).
+ */
+export function redactNpmOutput(text) {
+    return text
+        .replace(/\/\/[^\s/@]*@/g, '//***@')
+        .replace(/(_authToken|_auth|_password)(\s*[=:]\s*)("?)[^\s"]+/gi, '$1$2$3***')
+        .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, '$1 ***')
+        .replace(/\bnpm_[A-Za-z0-9]{20,}\b/g, 'npm_***');
 }

package/dist/output.d.ts

@@ -1,3 +1,3 @@
-export declare const CLI_VERSION = "0.2.5";
+export declare const CLI_VERSION = "0.4.0";
 export declare function envelope(command: string, result: unknown, ok?: boolean): object;
 export declare function failure(command: string, error: unknown, mutationStarted: boolean): object;

package/dist/output.js

@@ -1,17 +1,14 @@
 import { CliError } from './errors.js';
-export const CLI_VERSION = '0.2.5';
+export const CLI_VERSION = '0.4.0';
 export function envelope(command, result, ok = true) {
     return { schemaVersion: 1, cliVersion: CLI_VERSION, command, ok, result, error: null };
 }
 export function failure(command, error, mutationStarted) {
     const code = error instanceof CliError ? error.code : 'INTERNAL_ERROR';
-    const mutation = !mutationStarted
-        ? 'none'
-        : code === 'COMMIT_FAILED'
-            ? 'rolled-back'
-            : code === 'RECOVERY_REQUIRED'
-                ? 'recovery-required'
-                : 'unknown';
+    // npm failing in the staging folder never touched the project (D-0065, AI-M01).
+    const staged = code === 'NPM_FAILED' &&
+        error instanceof CliError &&
+        error.details?.stage === 'staging';
     const phase = (error instanceof CliError ? error.phase : undefined) ??
         (code === 'NPM_FAILED'
             ? 'install'
@@ -20,6 +17,15 @@ export function failure(command, error, mutationStarted) {
                 : code === 'USAGE'
                     ? 'arguments'
                     : 'unknown');
+    // An error of the arguments phase is raised before anything is written (or before a
+    // transaction commits): the project is untouched.
+    const mutation = !mutationStarted || staged || phase === 'arguments'
+        ? 'none'
+        : code === 'COMMIT_FAILED'
+            ? 'rolled-back'
+            : code === 'RECOVERY_REQUIRED'
+                ? 'recovery-required'
+                : 'unknown';
     return {
         schemaVersion: 1,
         cliVersion: CLI_VERSION,

package/dist/plugin-lifecycle.d.ts

@@ -13,6 +13,11 @@ export interface LifecyclePlan extends Omit<InstallPlan, 'configDefaults'> {
     defaults: Record<string, unknown>[];
     requires: string[];
     configChanges: ConfigChange[];
+    /**
+     * planInstall only (D-0073): environment variables that must hold a secret. The CLI writes a
+     * generated value into the project's .env when neither the environment nor .env has one.
+     */
+    envSecrets: string[];
 }
 export interface CheckDiagnostic {
     code: string;
@@ -34,6 +39,8 @@ export interface LifecycleInput {
     readonly projectPackages: readonly string[];
     readonly installation?: Installation;
 }
+/** An environment variable name a plan may ask a generated secret for. */
+export declare const ENV_NAME: RegExp;
 export declare function optionsOf(options: Record<string, unknown>, id: string): Record<string, unknown>;
 export declare function optionPath(value: unknown): string[];
 /** Static `dokebi.install` merged with the module's planInstall or planUpgrade result. */