@dokebi/cli 0.4.2 → 0.4.27

package/dist/npm-client.js

@@ -1,14 +1,81 @@
 import { spawn } from 'node:child_process';
 import { readdir, readFile, writeFile } from 'node:fs/promises';
-import { isAbsolute, resolve } from 'node:path';
+import { isAbsolute, posix, resolve } from 'node:path';
+import { redaction } from '@dokebi/core/libraries';
 import { debug, isMissing } from './diagnostics.js';
 import { CliError } from './errors.js';
 import { json, object, parseObject } from './filesystem.js';
 import { PACKAGE_NAME } from './manifest.js';
 import { normalizeLockPaths, normalizePackagePaths } from './npm-paths.js';
+import { forwardTermination, killGroup, PROCESS_GROUPS } from './process-group.js';
+/** How long one npm install, pack or workspace install may take by default (2 minutes). */
+export const NPM_TIMEOUT_MS = 120_000;
+/** The environment variable that sets that limit in milliseconds (D-0110 §4). */
+export const NPM_TIMEOUT_ENV = 'DOKEBI_NPM_TIMEOUT_MS';
+/** The shortest and the longest limit the variable may set: 1 second and 24 hours. */
+export const NPM_TIMEOUT_RANGE = { min: 1000, max: 86_400_000 };
+/**
+ * The time limit of the npm commands NpmClient runs: `DOKEBI_NPM_TIMEOUT_MS` (a whole number of
+ * milliseconds within NPM_TIMEOUT_RANGE) or NPM_TIMEOUT_MS. A slow registry or a large first
+ * install may need more; anything else in the variable is INVALID_ENV, never a silent default.
+ */
+export function npmTimeoutMs(env = process.env) {
+    const text = env[NPM_TIMEOUT_ENV]?.trim();
+    if (text === undefined || text === '')
+        return NPM_TIMEOUT_MS;
+    const value = Number(text);
+    if (!/^[0-9]+$/.test(text) ||
+        !Number.isSafeInteger(value) ||
+        value < NPM_TIMEOUT_RANGE.min ||
+        value > NPM_TIMEOUT_RANGE.max)
+        throw new CliError('INVALID_ENV', `${NPM_TIMEOUT_ENV} must be a whole number of milliseconds from ${NPM_TIMEOUT_RANGE.min} to ${NPM_TIMEOUT_RANGE.max}`, {
+            details: { variable: NPM_TIMEOUT_ENV, value: text, ...NPM_TIMEOUT_RANGE },
+            phase: 'arguments',
+        });
+    debug('npm time limit from the environment', { variable: NPM_TIMEOUT_ENV, timeoutMs: value });
+    return value;
+}
+/**
+ * D-0138: what NPM_FAILED says when npm's code is ERESOLVE. The newest catalog packages fit each
+ * other (scripts/catalog/peers.ts), but a newer one may need a newer version of a package the
+ * project has (session 0.4.4 needs web ^0.4.3); add and upgrade without a version pick one that
+ * fits, and a named version gets details.fix (project.ts #peerConflict). Otherwise the conflict
+ * comes from another package or from a registry that is not the one the project was installed
+ * from; neither is fixed by forcing npm.
+ */
+export const ERESOLVE_HINT = "npm could not fit the packages' peer ranges (stderr names them: 'Found: <installed>' and 'peer <package>@<range> from <new package>'). Do not retry with --legacy-peer-deps or --force: they install a combination the packages do not support. When the new package needs a newer version of one the project has, upgrade that one first (npx dokebi upgrade <its plugin id>) and repeat the command. Otherwise check that npm config get @dokebi:registry names the registry in package-lock.json's resolved URLs, and that the package named in stderr is a version this project's core supports.";
+/**
+ * Whether npm reads the path of a `file:` spec in the home folder: npm-package-arg fromFile takes
+ * a URL path whose first segment is `~` for it, relative (`~/x.tgz`, `./~/x.tgz`) or written
+ * absolute (`/~/x.tgz`, `//~/x.tgz`, `/../~/x.tgz`), never a folder of the project or of the
+ * root (R6-cli-1, R7-cli-1: the absolute ones were taken for the path /~/x.tgz). Backslashes
+ * count as separators, as on Windows.
+ */
+function homeTarball(path) {
+    return /^\/?~(?:\/|$)/.test(posix.normalize(path.replace(/\\/g, '/')));
+}
+/**
+ * Whether npm takes a backslash in the path of a `file:` spec for part of a file name: outside
+ * Windows npm-package-arg encodes it as %5C (`file:vendor\\x.tgz` reads the one file
+ * `vendor\\x.tgz`) but saves the spec with `/` (`file:vendor/x.tgz`), another path (R7-cli-3).
+ * On Windows it is a separator for npm, as for the CLI (R5C-2).
+ */
+function backslashName(path) {
+    return process.platform !== 'win32' && path.includes('\\');
+}
 export function packageSpec(spec, cwd) {
-    if (spec.endsWith('.tgz'))
-        return `file:${resolve(cwd, spec.replace(/^file:/, ''))}`;
+    if (spec.endsWith('.tgz')) {
+        const path = resolve(cwd, spec.replace(/^file:/, ''));
+        if (backslashName(path)) {
+            debug('A tarball path with a backslash is refused outside Windows', { spec, path });
+            throw new CliError('INVALID_SPEC', `npm reads the backslash in ${path} as part of a file name, and would save another path: name the tarball with / or rename the file`);
+        }
+        if (homeTarball(path)) {
+            debug('A tarball path npm reads in the home folder is refused', { spec, path });
+            throw new CliError('INVALID_SPEC', `npm reads ${path} in the home folder, not at that path: name the tarball by its full path`);
+        }
+        return `file:${path}`;
+    }
     const match = /^((?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*)(?:@([a-zA-Z0-9.*^~<>=| -]+))?$/.exec(spec);
     if (!match?.[1] || !PACKAGE_NAME.test(match[1]))
         throw new CliError('INVALID_SPEC', 'Use a registry package or local .tgz');
@@ -23,6 +90,29 @@ export function dependencyMap(pkg) {
     }
     return result;
 }
+/**
+ * The project-relative path of a `file:<path>.tgz` dependency that stays inside the project
+ * (`file:vendor/web-0.4.3.tgz`, as npm writes a tarball installed from the project), else undefined.
+ * The staging install gets a copy at the same path, so package.json and package-lock.json keep it
+ * relative and the project can move (2026-10-28).
+ */
+export function projectTarball(value) {
+    if (!value.startsWith('file:') || !value.endsWith('.tgz'))
+        return undefined;
+    const path = value.slice(5);
+    if (isAbsolute(path) || /^[a-zA-Z]:/.test(path))
+        return undefined;
+    // Backslashes first: on POSIX normalize() takes `vendor\..\..\x.tgz` for one name, and the
+    // `..` came back as `vendor/../../x.tgz`, a path out of the project (R5C-2).
+    const inside = posix.normalize(path.replace(/\\/g, '/'));
+    if (inside === '..' || inside.startsWith('../') || inside.startsWith('/'))
+        return undefined;
+    // npm reads a path whose first segment is `~` (also `./~/x.tgz`, `vendor/../~/x.tgz`) as the
+    // home folder (npm-package-arg fromFile), never a folder of the project (R6-cli-1).
+    if (homeTarball(inside))
+        return undefined;
+    return inside;
+}
 export function validateProjectPackage(pkg) {
     if (pkg.workspaces !== undefined)
         throw new CliError('UNSUPPORTED_PROJECT', 'Workspace projects are not supported');
@@ -32,20 +122,37 @@ export function validateProjectPackage(pkg) {
                 value.startsWith('workspace:') ||
                 value.startsWith('link:') ||
                 (value.startsWith('file:')
-                    ? !isAbsolute(value.slice(5)) || !value.endsWith('.tgz')
+                    ? !value.endsWith('.tgz') ||
+                        (isAbsolute(value.slice(5))
+                            ? homeTarball(value.slice(5))
+                            : projectTarball(value) === undefined)
                     : !/^[a-zA-Z0-9.*^~<>=| -]+$/.test(value))) {
-                throw new CliError('UNSUPPORTED_PROJECT', 'Use registry dependencies or absolute file tarballs');
+                throw new CliError('UNSUPPORTED_PROJECT', 'Use registry dependencies or file tarballs (an absolute path, or a path inside the project)');
+            }
+            // After the check above, so a backslash path out of the project is refused as one (R5C-2).
+            if (value.startsWith('file:') && backslashName(value.slice(5))) {
+                const path = value.slice(5);
+                debug('A file: tarball with a backslash is refused outside Windows', { path });
+                throw new CliError('UNSUPPORTED_PROJECT', `npm reads the backslash in ${value} as part of a file name and saves the path with /`, {
+                    details: {
+                        path,
+                        fix: `write it with / in package.json (file:${path.replace(/\\/g, '/')}), or rename the file so it has no backslash`,
+                    },
+                });
             }
         }
     }
 }
 export class NpmClient {
-    /** Installs into a standalone directory (the project or the CLI's staging). */
+    /**
+     * Installs into a standalone directory (the project or the CLI's staging): the package.json as
+     * it is, plus `spec` (one spec, or several in one npm run).
+     */
     async install(directory, spec) {
         try {
             await this.#run(directory, [
                 'install',
-                ...(spec ? [spec] : []),
+                ...(spec === undefined ? [] : typeof spec === 'string' ? (spec ? [spec] : []) : spec),
                 '--ignore-scripts',
                 '--save-exact',
                 '--no-audit',
@@ -71,7 +178,9 @@ export class NpmClient {
                             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 …',
                         }
-                        : {}),
+                        : details.npmCode === 'ERESOLVE'
+                            ? { hint: ERESOLVE_HINT }
+                            : {}),
                 },
                 phase: 'install',
             });
@@ -99,7 +208,8 @@ export class NpmClient {
         await this.#run(root, ['install', '--ignore-scripts', '--no-audit', '--no-fund']);
     }
     async #run(directory, npmArgs) {
-        const result = await runNpm(directory, npmArgs, { timeoutMs: 120_000 });
+        const timeoutMs = npmTimeoutMs();
+        const result = await runNpm(directory, npmArgs, { timeoutMs });
         if (result.exitCode === 0 && !result.timedOut)
             return;
         throw new CliError('NPM_FAILED', result.timedOut ? 'npm timed out' : `npm failed with exit code ${result.exitCode}`, {
@@ -108,6 +218,12 @@ export class NpmClient {
                 exitCode: result.exitCode,
                 signal: result.signal,
                 timedOut: result.timedOut,
+                ...(result.timedOut
+                    ? {
+                        timeoutMs,
+                        hint: `raise the limit with ${NPM_TIMEOUT_ENV}=<ms> when npm needs longer`,
+                    }
+                    : {}),
                 stderr: result.stderr,
                 stdout: result.stdout,
                 ...result.notes,
@@ -132,7 +248,15 @@ export function runNpm(directory, npmArgs, options) {
     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 runs in a process group of its own (process-group.ts): the time limit ends npm and
+        // everything it started (git, a lifecycle script, node-gyp), not npm alone. Those children
+        // hold its pipes, so killing npm alone left the command waiting for them as well.
+        const child = spawn(command, args, {
+            cwd: directory,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: PROCESS_GROUPS,
+        });
+        const forwarding = forwardTermination(child.pid);
         // 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();
@@ -145,10 +269,17 @@ export function runNpm(directory, npmArgs, options) {
         let timedOut = false;
         const timer = setTimeout(() => {
             timedOut = true;
-            child.kill('SIGKILL');
+            debug('npm reached its time limit; killing its process group', {
+                command: npmArgs[0],
+                pid: child.pid,
+                timeoutMs: options.timeoutMs,
+            });
+            // Windows has no process groups: there killGroup ends npm itself (process-group.ts).
+            killGroup(child.pid, 'SIGKILL');
         }, options.timeoutMs);
         child.on('error', (cause) => {
             clearTimeout(timer);
+            forwarding();
             reject(new CliError('NPM_FAILED', 'Could not execute npm', {
                 cause,
                 details: { command: npmArgs[0], directory },
@@ -156,6 +287,10 @@ export function runNpm(directory, npmArgs, options) {
         });
         child.on('close', (code, signal) => {
             clearTimeout(timer);
+            forwarding();
+            // A child npm left behind in its group (a script that forked) does not outlive the command.
+            if (!timedOut && killGroup(child.pid, 'SIGKILL'))
+                debug('npm left processes behind; killed them', { command: npmArgs[0], pid: child.pid });
             debug('npm finished', {
                 command: npmArgs[0],
                 exitCode: code,
@@ -288,12 +423,14 @@ export class NpmFailureNotes {
     }
 }
 /**
- * Removes credentials npm may print: `user:password@` in URLs, `_authToken=`/`_auth=`/
- * `_password=` values (npmrc lines), bearer tokens and npm access tokens (`npm_…`).
+ * Removes credentials npm may print: `user:password@` in URLs (core's rule, which also takes a
+ * raw `/` inside a password: `//app:Zm9v/YmFy@db` kept the part after the slash before),
+ * `_authToken=`/`_auth=`/`_password=` values (npmrc lines), bearer tokens and npm access tokens
+ * (`npm_…`).
  */
 export function redactNpmOutput(text) {
-    return text
-        .replace(/\/\/[^\s/@]*@/g, '//***@')
+    return redaction
+        .maskCredentials(text)
         .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/npm-paths.js

@@ -1,4 +1,4 @@
-import { resolve } from 'node:path';
+import { isAbsolute, relative, resolve } from 'node:path';
 import { object } from './filesystem.js';
 const DEPENDENCY_FIELDS = [
     'dependencies',
@@ -6,10 +6,24 @@ const DEPENDENCY_FIELDS = [
     'optionalDependencies',
     'peerDependencies',
 ];
+/**
+ * A `file:` reference npm wrote in a staging folder, made valid in the project it is copied to:
+ * one that leaves the folder (`file:../../x.tgz`, npm's way to name an absolute tarball) becomes
+ * absolute; one inside it stays relative (`file:vendor/web.tgz`: the project's own tarball, which
+ * staging holds at the same path, so the project keeps it relative and can move, 2026-10-28).
+ */
 function localReference(value, root) {
-    return typeof value === 'string' && value.startsWith('file:')
-        ? `file:${resolve(root, value.slice(5))}`
-        : value;
+    if (typeof value !== 'string' || !value.startsWith('file:'))
+        return value;
+    const path = value.slice(5);
+    const absolute = resolve(root, path);
+    const inside = relative(root, absolute);
+    // `..` as the first segment only: `..vendor/x.tgz` is a folder of the project (R6-cli-3: taken
+    // for a way out, it became an absolute path into the staging folder, deleted after the commit).
+    const first = inside.split(/[\\/]/)[0];
+    if (!isAbsolute(path) && inside !== '' && first !== '..' && !isAbsolute(inside))
+        return `file:${inside.split('\\').join('/')}`;
+    return `file:${absolute}`;
 }
 export function normalizePackagePaths(pkg, root) {
     for (const field of DEPENDENCY_FIELDS) {

package/dist/openapi.d.ts

@@ -0,0 +1,27 @@
+import type { DescribeResult } from './describe.js';
+export declare const OPENAPI_VERSION = "3.1.0";
+type Json = Record<string, unknown>;
+/** The D-0074 error body. */
+export declare const ERROR_BODY_SCHEMA: Json;
+/** `/posts/:id(^\\d+)/*` → `/posts/{id}/{wildcard}` and the path parameter names. */
+export declare function openApiPath(url: string): {
+    path: string;
+    names: string[];
+};
+/** `get_posts_id`: the deterministic name of a route without `config.id`. */
+export declare function operationName(method: string, url: string): string;
+export interface OpenApiOptions {
+    /** One app's document; UNKNOWN_APP when the project has no such app. */
+    readonly app?: string;
+    /** `info.version` (the project's package.json version; default 0.0.0). */
+    readonly version?: string;
+}
+/** `{ apps: { name: document } }` without `--app` when the project has several apps. */
+export type OpenApiResult = Json | {
+    readonly apps: Record<string, Json>;
+};
+/** OpenAPI documents of the described project (one per app). */
+export declare function openApi(result: DescribeResult, options?: OpenApiOptions): OpenApiResult;
+/** The project's package.json version, for `info.version`. */
+export declare function projectVersion(root: string): string | undefined;
+export {};