Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 {