Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Isolate npm state and retain packed CLI failure diagnostics (#5741)

Nick Gomez22f56be46af2
diff --git a/packages/cli/tests/e2e/install-fixture.test-helper.ts b/packages/cli/tests/e2e/install-fixture.test-helper.ts
index e253b5ee3..c016527b9 100644
--- a/packages/cli/tests/e2e/install-fixture.test-helper.ts
+++ b/packages/cli/tests/e2e/install-fixture.test-helper.ts
@@ -53,7 +53,6 @@ export async function createInstallFixture(optionalParent = false) {
const env = {
...process.env,
npm_config_registry: registryUrl,
- npm_config_cache: join(root, 'npm-cache'),
npm_config_fetch_retries: '0',
pnpm_config_registry: registryUrl,
pnpm_config_cache_dir: join(root, 'pnpm-cache'),
diff --git a/packages/cli/tests/e2e/packed-install-deadline-diagnostics.test.ts b/packages/cli/tests/e2e/packed-install-deadline-diagnostics.test.ts
new file mode 100644
index 000000000..8ba619992
--- /dev/null
+++ b/packages/cli/tests/e2e/packed-install-deadline-diagnostics.test.ts
@@ -0,0 +1,124 @@
+import { type ChildProcess, execFile } from 'node:child_process';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { expect, test } from 'vitest';
+import { installPackedCli } from './packed-install.test-helper';
+
+test('retains npm debug logs exactly once in a fresh acquisition deadline error chain after cleanup', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-cli-deadline-diagnostics-'));
+ const packageDir = join(root, 'package');
+ const packDest = join(root, 'pack');
+ const installPrefix = join(root, 'install');
+ for (const dir of [packageDir, packDest, installPrefix]) mkdirSync(dir);
+ let clock = 0;
+ let budget = 0;
+ let installer: ChildProcess | undefined;
+ let nativeFailure: unknown;
+ let failure: unknown;
+ let logs: string[] = [];
+ const registry = createServer((_request, response) => {
+ if (installer && installer.exitCode === null && installer.signalCode === null) {
+ clock += budget;
+ installer.kill('SIGTERM');
+ } else {
+ response.writeHead(500);
+ response.end('No active installer');
+ }
+ });
+ try {
+ await new Promise<void>((resolve) => registry.listen(0, '127.0.0.1', resolve));
+ const address = registry.address();
+ if (!address || typeof address === 'string') throw new Error('Registry did not bind TCP');
+ writeFileSync(
+ join(packageDir, 'package.json'),
+ JSON.stringify({
+ name: '@inkeep/open-knowledge',
+ version: '1.0.0',
+ dependencies: { 'ok-deadline-snapshot-fixture': '1.0.0' },
+ }),
+ );
+ writeFileSync(join(root, 'empty.npmrc'), '');
+ failure = await installPackedCli(
+ {
+ packageDir,
+ packDest,
+ installPrefix,
+ mode: 'fresh',
+ env: {
+ ...process.env,
+ npm_config_userconfig: join(root, 'empty.npmrc'),
+ npm_config_registry: `http://127.0.0.1:${address.port}`,
+ npm_config_loglevel: 'silent',
+ },
+ },
+ {
+ now: () => clock,
+ executeInstall: (command, args, options) => {
+ budget = options.timeout ?? 0;
+ const execution = promisify(execFile)(command, args, {
+ ...options,
+ timeout: Math.min(budget, 5_000),
+ });
+ installer = execution.child;
+ return execution.catch((error: unknown) => {
+ nativeFailure = error;
+ throw error;
+ });
+ },
+ },
+ ).catch((error: unknown) => error);
+ logs = readdirSync(packDest, { recursive: true, withFileTypes: true })
+ .filter((entry) => entry.isFile() && entry.name.endsWith('-debug-0.log'))
+ .map((entry) => readFileSync(join(entry.parentPath, entry.name), 'utf8'));
+ } finally {
+ if (installer && installer.exitCode === null && installer.signalCode === null)
+ installer.kill('SIGTERM');
+ registry.closeAllConnections();
+ await new Promise<void>((resolve, reject) =>
+ registry.close((error) => (error ? reject(error) : resolve())),
+ );
+ rmSync(root, { recursive: true, force: true });
+ }
+ expect(existsSync(root)).toBe(false);
+ expect(failure).toBeInstanceOf(Error);
+ if (!(failure instanceof Error)) throw new Error('Expected acquisition deadline failure');
+ const matchesStartupGuard =
+ nativeFailure instanceof Error &&
+ 'killed' in nativeFailure &&
+ nativeFailure.killed === true &&
+ 'code' in nativeFailure &&
+ nativeFailure.code === null &&
+ 'signal' in nativeFailure &&
+ nativeFailure.signal === 'SIGTERM';
+ expect(
+ clock,
+ matchesStartupGuard
+ ? 'npm install stopped before the fixture registry request; check the 5-second startup hang guard'
+ : failure.message,
+ ).toBeGreaterThanOrEqual(budget);
+ expect(failure.message).toContain('acquisition deadline elapsed on attempt 1 of 3.');
+ expect(failure.cause).toBe(nativeFailure);
+ expect(nativeFailure).toMatchObject({ code: null, killed: true, signal: 'SIGTERM' });
+ expect(logs).toContainEqual(expect.stringMatching(/verbose title npm pack\b/));
+ expect(logs).toContainEqual(expect.stringMatching(/verbose title npm install\b/));
+ const messages: string[] = [];
+ let current: unknown = failure;
+ while (current instanceof Error) {
+ messages.push(current.message);
+ current = current.cause;
+ }
+ for (const log of logs) expect(failure.message).toContain(log);
+ const copies = logs.map((log) => messages.join('\n').split(log).length - 1);
+ expect(copies).toEqual(logs.map(() => 1));
+});
diff --git a/packages/cli/tests/e2e/packed-install-diagnostics.test.ts b/packages/cli/tests/e2e/packed-install-diagnostics.test.ts
new file mode 100644
index 000000000..83991e221
--- /dev/null
+++ b/packages/cli/tests/e2e/packed-install-diagnostics.test.ts
@@ -0,0 +1,213 @@
+import { execFile } from 'node:child_process';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ realpathSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, relative } from 'node:path';
+import { promisify } from 'node:util';
+import { expect, test } from 'vitest';
+import { z } from 'zod';
+import { installPackedCli } from './packed-install.test-helper';
+
+function createDiagnosticFixture() {
+ const root = mkdtempSync(join(tmpdir(), 'ok-cli-npm-diagnostics-'));
+ const packageDir = join(root, 'package');
+ const packDest = join(root, 'pack');
+ const installPrefix = join(root, 'install');
+ for (const dir of [packageDir, packDest, installPrefix]) mkdirSync(dir);
+ return {
+ root,
+ packageDir,
+ packDest,
+ installPrefix,
+ mode: 'fresh' as const,
+ env: {
+ ...process.env,
+ npm_config_cache: join(root, 'inherited-cache'),
+ npm_config_logs_dir: join(root, 'inherited-logs'),
+ npm_config_userconfig: join(root, 'empty.npmrc'),
+ npm_config_ignore_scripts: 'false',
+ npm_config_loglevel: 'error',
+ },
+ };
+}
+
+function writeLocalPackage(packageDir: string, failingInstall = false) {
+ for (const dir of ['dist/public', 'dist/assets/skills'])
+ mkdirSync(join(packageDir, dir), { recursive: true });
+ writeFileSync(
+ join(packageDir, 'package.json'),
+ JSON.stringify({
+ name: '@inkeep/open-knowledge',
+ version: '1.0.0',
+ bin: { ok: 'dist/cli.mjs' },
+ ...(failingInstall ? { scripts: { postinstall: 'node install-failure.cjs' } } : {}),
+ }),
+ );
+ writeFileSync(
+ join(packageDir, 'dist/cli.mjs'),
+ '#!/usr/bin/env node\nconsole.log("diagnostic fixture ready");\n',
+ );
+ writeFileSync(join(packageDir, 'dist/public/index.html'), '<title>CLI fixture</title>');
+ writeFileSync(join(packageDir, 'dist/assets/skills/SKILL.md'), '# CLI fixture\n');
+ if (failingInstall)
+ writeFileSync(
+ join(packageDir, 'install-failure.cjs'),
+ `const fs = require('node:fs');
+const path = require('node:path');
+fs.writeFileSync(path.join(process.env.INIT_CWD, 'npm-context.json'), JSON.stringify({ cache: process.env.npm_config_cache, logs: process.env.npm_config_logs_dir }));
+process.stderr.write('NPMPACK_INSTALL_CONTROL\\n');
+process.exit(23);
+`,
+ );
+}
+
+function npmFailure(failure: unknown): Error {
+ expect(failure).toBeInstanceOf(Error);
+ if (!(failure instanceof Error)) throw new Error('Expected real npm failure');
+ return failure;
+}
+
+function npmDebugStack(root: string, command: 'pack' | 'install') {
+ const log = readdirSync(root, { recursive: true, withFileTypes: true })
+ .filter((entry) => entry.isFile() && entry.name.endsWith('-debug-0.log'))
+ .map((entry) => readFileSync(join(entry.parentPath, entry.name), 'utf8'))
+ .find((content) => content.includes(`verbose title npm ${command}`));
+ expect(log).toBeTypeOf('string');
+ if (typeof log !== 'string') throw new Error(`Expected real npm ${command} debug log`);
+ const stack = log.split('\n').find((line) => line.includes('verbose stack'));
+ expect(stack).toBeTypeOf('string');
+ if (typeof stack !== 'string') throw new Error(`Expected real npm ${command} debug stack`);
+ return stack;
+}
+
+test('retains npm pack stderr and debug details after fixture cleanup', async () => {
+ const fixture = createDiagnosticFixture();
+ let failure: unknown;
+ let debugStack = '';
+ try {
+ writeFileSync(join(fixture.packageDir, 'package.json'), '{"name":');
+ failure = await installPackedCli(fixture).catch((error: unknown) => error);
+ debugStack = npmDebugStack(fixture.root, 'pack');
+ } finally {
+ rmSync(fixture.root, { recursive: true, force: true });
+ }
+ expect(failure).toBeInstanceOf(Error);
+ if (!(failure instanceof Error)) throw new Error('Expected real npm pack failure');
+ expect(failure.message).toContain('EJSONPARSE');
+ expect(failure.message).toMatch(/npm (?:error|ERR!)/);
+ expect(failure.message).toContain('verbose stack');
+ expect(failure.message).toContain(debugStack);
+});
+
+test('retains npm pack debug details when stderr is silent', async () => {
+ const fixture = createDiagnosticFixture();
+ let failure: unknown;
+ let debugStack = '';
+ try {
+ writeFileSync(join(fixture.packageDir, 'package.json'), '{"name":');
+ failure = await installPackedCli({
+ ...fixture,
+ env: { ...fixture.env, npm_config_loglevel: 'silent' },
+ }).catch((error: unknown) => error);
+ debugStack = npmDebugStack(fixture.root, 'pack');
+ } finally {
+ rmSync(fixture.root, { recursive: true, force: true });
+ }
+ const error = npmFailure(failure);
+ expect(error.message).toContain('EJSONPARSE');
+ expect(error.message).toContain('verbose stack');
+ expect(error.message).toContain(debugStack);
+});
+
+test('retains npm install stderr and debug details after fixture cleanup', async () => {
+ const fixture = createDiagnosticFixture();
+ let failure: unknown;
+ let debugStack = '';
+ try {
+ writeLocalPackage(fixture.packageDir, true);
+ failure = await installPackedCli(fixture).catch((error: unknown) => error);
+ debugStack = npmDebugStack(fixture.root, 'install');
+ } finally {
+ rmSync(fixture.root, { recursive: true, force: true });
+ }
+ const error = npmFailure(failure);
+ expect(error.message).toContain('NPMPACK_INSTALL_CONTROL');
+ expect(error.message).toMatch(/npm (?:error|ERR!) code 23/);
+ expect(error.message).toContain('verbose stack');
+ expect(error.message).toContain(debugStack);
+});
+
+test('keeps concurrent invocations npm caches and logs private', async () => {
+ const fixture = createDiagnosticFixture();
+ const inheritedEnv = { ...fixture.env };
+ const inheritedDirs = [fixture.env.npm_config_cache, fixture.env.npm_config_logs_dir];
+ for (const dir of inheritedDirs) {
+ mkdirSync(dir);
+ writeFileSync(join(dir, 'sentinel'), 'caller-owned evidence');
+ }
+ try {
+ writeLocalPackage(fixture.packageDir, true);
+ const calls = ['first', 'second'].map((name) => {
+ const packDest = join(fixture.root, `${name}-pack`);
+ const installPrefix = join(fixture.root, `${name}-install`);
+ mkdirSync(packDest);
+ mkdirSync(installPrefix);
+ return { ...fixture, packDest, installPrefix };
+ });
+ const failures = await Promise.all(
+ calls.map((call) => installPackedCli(call).catch((error: unknown) => error)),
+ );
+ for (const failure of failures)
+ expect(npmFailure(failure).message).toContain('NPMPACK_INSTALL_CONTROL');
+ const contexts = calls.map(({ installPrefix }) =>
+ z
+ .object({ cache: z.string(), logs: z.string() })
+ .parse(JSON.parse(readFileSync(join(installPrefix, 'npm-context.json'), 'utf8'))),
+ );
+ expect(new Set(contexts.map(({ cache }) => cache)).size).toBe(2);
+ expect(new Set(contexts.map(({ logs }) => logs)).size).toBe(2);
+ for (const [index, { cache, logs }] of contexts.entries()) {
+ for (const dir of [cache, logs]) {
+ const path = relative(realpathSync(fixture.root), realpathSync(dir));
+ expect(isAbsolute(path)).toBe(false);
+ expect(path.split(/[\\/]/)).not.toContain('..');
+ expect(inheritedDirs).not.toContain(dir);
+ }
+ const debugLogs = readdirSync(logs).filter((name) => name.endsWith('-debug-0.log'));
+ const contents = debugLogs.map((name) => readFileSync(join(logs, name), 'utf8'));
+ expect(contents).toHaveLength(2);
+ expect(contents).toContainEqual(expect.stringMatching(/verbose title npm pack\b/));
+ expect(contents).toContainEqual(expect.stringMatching(/verbose title npm install\b/));
+ expect(contents.join('\n')).toContain(calls[index].installPrefix);
+ expect(contents.join('\n')).not.toContain(calls[1 - index].installPrefix);
+ }
+ for (const dir of inheritedDirs) {
+ expect(readdirSync(dir)).toEqual(['sentinel']);
+ expect(readFileSync(join(dir, 'sentinel'), 'utf8')).toBe('caller-owned evidence');
+ }
+ expect(fixture.env).toEqual(inheritedEnv);
+ } finally {
+ rmSync(fixture.root, { recursive: true, force: true });
+ }
+});
+
+test('installs a valid local packed CLI', async () => {
+ const fixture = createDiagnosticFixture();
+ try {
+ writeLocalPackage(fixture.packageDir);
+ const installed = await installPackedCli(fixture);
+ expect(existsSync(installed.binShim)).toBe(true);
+ const result = await promisify(execFile)(process.execPath, [installed.cliPath]);
+ expect(result.stdout.trim()).toBe('diagnostic fixture ready');
+ } finally {
+ rmSync(fixture.root, { recursive: true, force: true });
+ }
+});
diff --git a/packages/cli/tests/e2e/packed-install.test-helper.ts b/packages/cli/tests/e2e/packed-install.test-helper.ts
index bff1d3560..94561c633 100644
--- a/packages/cli/tests/e2e/packed-install.test-helper.ts
+++ b/packages/cli/tests/e2e/packed-install.test-helper.ts
@@ -4,6 +4,8 @@ import {
cpSync,
existsSync,
mkdirSync,
+ mkdtempSync,
+ readdirSync,
readFileSync,
realpathSync,
rmSync,
@@ -236,6 +238,54 @@ interface InstallRuntime {
) => Promise<{ stdout: string; stderr: string }>;
}
+interface NpmContext {
+ cacheDir: string;
+ logsDir: string;
+}
+
+function createNpmContext(packDest: string): NpmContext {
+ const root = realpathSync(mkdtempSync(join(packDest, 'npm-')));
+ const cacheDir = join(root, 'cache');
+ const logsDir = join(root, 'logs');
+ mkdirSync(cacheDir);
+ mkdirSync(logsDir);
+ return {
+ cacheDir,
+ logsDir,
+ };
+}
+
+function npmDebugEvidence({ logsDir }: NpmContext): string {
+ let files: string[];
+ try {
+ files = readdirSync(logsDir)
+ .filter((name) => /-debug-\d+\.log$/.test(name))
+ .sort();
+ } catch (error) {
+ return `\nNpm debug logs unavailable at ${logsDir}: ${String(error)}\n`;
+ }
+ if (!files.length) return `\nNo npm debug logs available at ${logsDir}.\n`;
+ return files
+ .map((name) => {
+ const path = join(logsDir, name);
+ try {
+ return `\nNpm debug log ${path}:\n${readFileSync(path, 'utf8')}`;
+ } catch (error) {
+ return `\nNpm debug log unreadable at ${path}: ${String(error)}\n`;
+ }
+ })
+ .join('');
+}
+
+function attachNpmDebugEvidence(error: unknown, evidence: string): unknown {
+ if (error instanceof Error) {
+ try {
+ error.message += evidence;
+ } catch {}
+ }
+ return error;
+}
+
async function prepareLockedConsumer(
options: PackedInstallOptions,
tarball: string,
@@ -318,17 +368,24 @@ export async function installPackedCli(
{ now, executeInstall }: InstallRuntime = { now: Date.now, executeInstall: execute },
) {
const installPrefix = realpathSync(options.installPrefix);
- const env = options.env ?? process.env;
+ const env = { ...(options.env ?? process.env) };
const mode =
options.mode ?? z.enum(['locked', 'fresh']).parse(env.OK_CLI_E2E_INSTALL_MODE ?? 'locked');
const graphDir = join(options.packageDir, 'test-results');
const graphPath = join(graphDir, 'cli-e2e-fresh-graph.json');
if (mode === 'fresh') rmSync(graphPath, { force: true });
- const packed = await execute('npm', ['pack', '--json', '--pack-destination', options.packDest], {
- cwd: options.packageDir,
- encoding: 'utf8',
- env,
- });
+ const npm = createNpmContext(options.packDest);
+ const npmArgs = ['--cache', npm.cacheDir, '--logs-dir', npm.logsDir];
+ let packed: { stdout: string; stderr: string };
+ try {
+ packed = await execute(
+ 'npm',
+ ['pack', '--json', '--pack-destination', options.packDest, ...npmArgs],
+ { cwd: options.packageDir, encoding: 'utf8', env },
+ );
+ } catch (error) {
+ throw attachNpmDebugEvidence(error, npmDebugEvidence(npm));
+ }
const [archive] = z
.array(z.object({ filename: z.string(), integrity: z.string() }))
.nonempty()
@@ -349,6 +406,7 @@ export async function installPackedCli(
'--prefix',
installPrefix,
tarball,
+ ...npmArgs,
];
const configuredFetchTimeout = z.coerce
.number()
@@ -371,6 +429,7 @@ export async function installPackedCli(
let stderr: string;
let failed = false;
let deadlineError: unknown;
+ let diagnostics = '';
try {
({ stdout, stderr } = await executeInstall(
command,
@@ -383,6 +442,7 @@ export async function installPackedCli(
},
));
} catch (error) {
+ if (mode === 'fresh') diagnostics = npmDebugEvidence(npm);
const failure = z
.object({
stdout: z.string(),
@@ -392,7 +452,7 @@ export async function installPackedCli(
code: z.union([z.string(), z.number(), z.null()]).optional(),
})
.safeParse(error);
- if (!failure.success) throw error;
+ if (!failure.success) throw attachNpmDebugEvidence(error, diagnostics);
({ stdout, stderr } = failure.data);
const ownDeadline =
failure.data.killed === true &&
@@ -401,7 +461,7 @@ export async function installPackedCli(
now() >= deadline;
if (typeof failure.data.code === 'string' || (failure.data.signal && !ownDeadline)) {
process.stderr.write(stdout + stderr);
- throw error;
+ throw attachNpmDebugEvidence(error, diagnostics);
}
if (ownDeadline) deadlineError = error;
failed = true;
@@ -468,11 +528,11 @@ export async function installPackedCli(
TRANSPORT_CODES.has(failure.code) ||
/^(?:E|ERR_PNPM_FETCH_)(?:408|429|5\d\d)$/.test(failure.code),
);
- const message = `Packed CLI ${command} installation failed.\n${refetched.map(({ packageId, verdict }) => `pnpm started fetching ${packageId} but never finished, and pnpm 12 skips a failed optional dependency without reporting why. Fetched again by the harness: ${verdict.code.startsWith('INCOMPLETE_FETCH') ? '' : `${verdict.code}: `}${verdict.reason}.\n`).join('')}${stdout}${stderr}`;
+ const message = `Packed CLI ${command} installation failed.\n${refetched.map(({ packageId, verdict }) => `pnpm started fetching ${packageId} but never finished, and pnpm 12 skips a failed optional dependency without reporting why. Fetched again by the harness: ${verdict.code.startsWith('INCOMPLETE_FETCH') ? '' : `${verdict.code}: `}${verdict.reason}.\n`).join('')}${stdout}${stderr}${diagnostics}`;
if (!retryable) {
if (deadlineError)
throw new Error(
- `Packed CLI ${command} acquisition deadline elapsed on attempt ${attempt} of ${INSTALL_ATTEMPTS}.`,
+ `Packed CLI ${command} acquisition deadline elapsed on attempt ${attempt} of ${INSTALL_ATTEMPTS}.${diagnostics}`,
{ cause: deadlineError },
);
throw new Error(unobserved ? `CLI fetch observer did not run.\n${message}` : message);
diff --git a/packages/cli/tests/e2e/packed-install.test.ts b/packages/cli/tests/e2e/packed-install.test.ts
index 09e8e3c76..0c22e08a7 100644
--- a/packages/cli/tests/e2e/packed-install.test.ts
+++ b/packages/cli/tests/e2e/packed-install.test.ts
@@ -56,15 +56,18 @@ test('reports unavailable registry acquisition after bounded attempts', async ()
...process.env,
npm_config_registry: `http://127.0.0.1:${address.port}`,
npm_config_fetch_retries: '0',
- npm_config_cache: join(root, 'cache'),
FORCE_COLOR: '1',
},
}),
).rejects.toMatchObject({ name: 'CliInstallUnavailableError', exitCode: 77 });
expect(registryReached).toBe(true);
- const logs = join(root, 'cache', '_logs');
- const installs = readdirSync(logs).filter((name) =>
- /\bverbose title npm install\b/.test(readFileSync(join(logs, name), 'utf8')),
+ const installs = readdirSync(root, { recursive: true, withFileTypes: true }).filter(
+ (entry) =>
+ entry.isFile() &&
+ entry.name.endsWith('-debug-0.log') &&
+ /\bverbose title npm install\b/.test(
+ readFileSync(join(entry.parentPath, entry.name), 'utf8'),
+ ),
);
expect(installs).toHaveLength(3);
} finally {