Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Classify packed CLI installs and replay committed dependencies (#5128)

Nick Gomez6c78f40a82c8
diff --git a/knip.config.ts b/knip.config.ts
index be41ab16c..37d9ce912 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -145,11 +145,15 @@ export default {
'packages/server': {
entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],
project: 'src/**',
- ignoreDependencies: ['@types/shell-quote'],
+ ignoreDependencies: [
+ '@types/shell-quote',
+ ],
},
'packages/cli': {
entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],
- ignoreDependencies: ['yjs'],
+ ignoreDependencies: [
+ 'yjs',
+ ],
},
'packages/desktop': {
entry: [
diff --git a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
index 8a60e5826..a28cc2b18 100644
--- a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
+++ b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
@@ -1,3 +1,4 @@
+
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
diff --git a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
index 6fcdc23f2..4fc2c11f9 100644
--- a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
+++ b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { normalizeBridge } from '@inkeep/open-knowledge-core';
import { updateYFragment } from '@tiptap/y-tiptap';
diff --git a/packages/app/tests/integration/interior-edit-freshness.test.ts b/packages/app/tests/integration/interior-edit-freshness.test.ts
index 40b5cdfd6..9f2f6feb6 100644
--- a/packages/app/tests/integration/interior-edit-freshness.test.ts
+++ b/packages/app/tests/integration/interior-edit-freshness.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
index 93666af70..2a085742b 100644
--- a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
+++ b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/producer-guard-wiring.test.ts b/packages/app/tests/integration/producer-guard-wiring.test.ts
index 867598d34..878d5196b 100644
--- a/packages/app/tests/integration/producer-guard-wiring.test.ts
+++ b/packages/app/tests/integration/producer-guard-wiring.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
index 0970ac12f..4ada3cf26 100644
--- a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
+++ b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
@@ -1,3 +1,4 @@
+
import { randomUUID } from 'node:crypto';
import { afterEach, describe, expect, test } from 'vitest';
import { agentWriteMd, createTestServer, type TestServer } from './test-harness';
diff --git a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
index b632185e1..cbe2b705f 100644
--- a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
+++ b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
@@ -1,3 +1,4 @@
+
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { join } from 'node:path';
diff --git a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
index c530ce4ba..89bc9b4d9 100644
--- a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
+++ b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
@@ -1,3 +1,4 @@
+
import { randomUUID } from 'node:crypto';
import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';
import type * as Y from 'yjs';
diff --git a/packages/app/tests/integration/undo-after-rollback.test.ts b/packages/app/tests/integration/undo-after-rollback.test.ts
index d3767adc9..a78aeb0e4 100644
--- a/packages/app/tests/integration/undo-after-rollback.test.ts
+++ b/packages/app/tests/integration/undo-after-rollback.test.ts
@@ -1,3 +1,4 @@
+
import { ROLLBACK_ORIGIN } from '@inkeep/open-knowledge-server';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
import * as Y from 'yjs';
diff --git a/packages/app/tests/integration/undo-recycle-reset.test.ts b/packages/app/tests/integration/undo-recycle-reset.test.ts
index b076f955c..e7cc69c3f 100644
--- a/packages/app/tests/integration/undo-recycle-reset.test.ts
+++ b/packages/app/tests/integration/undo-recycle-reset.test.ts
@@ -1,3 +1,4 @@
+
import { writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
diff --git a/packages/app/tests/integration/undo-rederive-survival.test.ts b/packages/app/tests/integration/undo-rederive-survival.test.ts
index 7935e35f8..9ddcd0730 100644
--- a/packages/app/tests/integration/undo-rederive-survival.test.ts
+++ b/packages/app/tests/integration/undo-rederive-survival.test.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter } from '@inkeep/open-knowledge-core';
import { Plugin, PluginKey } from '@tiptap/pm/state';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
diff --git a/packages/cli/tests/e2e/INSTALL.md b/packages/cli/tests/e2e/INSTALL.md
new file mode 100644
index 000000000..0be53871c
--- /dev/null
+++ b/packages/cli/tests/e2e/INSTALL.md
@@ -0,0 +1,41 @@
+# Packed CLI installation
+
+The required cli-e2e mode is `locked`. It packs the CLI from the checkout and replays its runtime graph from the committed workspace `pnpm-lock.yaml`, using the workspace package-manager pin. A temporary consumer retains the lock's package records, integrity, peer snapshots, platform metadata and patches. The consumer lock is generated for the run; it is not another maintained lockfile.
+
+Set `OK_CLI_E2E_INSTALL_MODE=fresh` to use npm's native fresh resolution with the same product assertions. Fresh mode deliberately retains npm's optional-dependency tolerance. Only fatal npm acquisition failures are classified as unavailable; strict complete acquisition applies to locked mode.
+
+Fresh mode writes npm's generated package-lock JSON to `packages/cli/test-results/cli-e2e-fresh-graph.json`, relative to the Open Knowledge workspace. The ignored artifact is replaced each run. It records resolution, including optional declarations and resolved package records. An optional version missing during resolution has no package record, but npm can retain the resolved record after dropping a package whose tarball failed. The artifact therefore cannot identify every optional package absent from disk.
+
+## Acquisition outcome
+
+Installer output is printed on failure. Only classified registry or transport errors receive retries: at most three attempts share the existing 180-second acquisition budget, with installer retries disabled and request deadlines fitted inside the remaining budget. Product errors, unclassified errors and external interruption do not become unavailable outcomes. Missing packed assets remain product failures.
+
+If all failures in a Vitest run are acquisition exhaustion, the reporter returns exit 77 and writes one stderr line beginning `INKEEP_GATE_RESULT_V1 ` followed by JSON. Any product failure keeps the ordinary failed-run result and suppresses this marker. This marker is diagnostic evidence, not an admission or successful-check result. The future gate reader and its complete shared schema belong to the gate integration.
+
+This producer emits these fields:
+
+| Field | Value or meaning |
+| --- | --- |
+| `boundary` | `round` |
+| `class` | `not-run` |
+| `exit` | `77` |
+| `signal` | `null`; an external signal does not emit this marker |
+| `outputBytes` | Captured installer stdout and stderr bytes across attempts, summed once per acquisition failure even if Vitest propagates that error more than once |
+| `runId` | A UUID for this emitted run result |
+| `head` | The checked-out Git commit; valid `GITHUB_SHA` is a fallback when Git lookup is unavailable |
+| `base` | `pull_request.base.sha` or `merge_group.base_sha` from `GITHUB_EVENT_PATH`; an explicit `GITHUB_BASE_SHA` is a fallback comparison input |
+| `subject` | `cli-e2e` |
+| `step` | `packed-install` |
+| `reasonCode` | `registry-unavailable` |
+
+`head` identifies the tree tested, which can be a pull-request merge commit. It does not claim to be the pull-request source commit. Unknown provenance is explicitly `null`: unavailable checkout identity or invalid comparison metadata also produces a separate diagnostic. A run without a comparison input has `base: null`. Metadata lookup cannot replace a confirmed acquisition outcome with a reporter exception. A consumer must not treat missing provenance as permission to admit a change.
+
+## Focused checks
+
+From the Open Knowledge workspace:
+
+```sh
+pnpm --dir packages/cli exec vitest run tests/e2e/packed-install.test.ts tests/e2e/install-outcome.test.ts tests/e2e/install-deadline.test.ts --reporter=verbose --maxWorkers=2
+```
+
+These checks use real npm and pnpm against an owned loopback registry. Deadline classification tests inject a clock and installer result without delivering signals. These focused files run in the CLI package's default `test` tier in CI. The cli-e2e job runs `pnpm --dir packages/cli test:e2e:cli`, which selects only `tests/e2e/cli-linux-e2e.ts` and drives the packed CLI's product journeys.
diff --git a/packages/cli/tests/e2e/cli-linux-e2e.ts b/packages/cli/tests/e2e/cli-linux-e2e.ts
index 87a8c3480..efb697813 100644
--- a/packages/cli/tests/e2e/cli-linux-e2e.ts
+++ b/packages/cli/tests/e2e/cli-linux-e2e.ts
@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import { installPackedCli } from './packed-install.test-helper';
const HERE = dirname(fileURLToPath(import.meta.url));
const CLI_PKG_DIR = resolve(HERE, '..', '..');
@@ -108,21 +109,14 @@ beforeAll(async () => {
if (SUT_MODE === 'packed') {
const packDest = mkdtempSync(join(tmpdir(), 'ok-e2e-pack-'));
H.packDest = packDest;
- const packOut = execFileSync('npm', ['pack', '--silent', '--pack-destination', packDest], {
- cwd: CLI_PKG_DIR,
- encoding: 'utf8',
- }).trim();
- const tarball = join(packDest, packOut.split('\n').pop()?.trim() ?? '');
- if (!existsSync(tarball)) throw new Error(`npm pack produced no tarball (got "${packOut}")`);
-
H.installPrefix = mkdtempSync(join(tmpdir(), 'ok-e2e-install-'));
- execFileSync('npm', ['install', '--silent', '--prefix', H.installPrefix, tarball], {
- encoding: 'utf8',
- timeout: 180_000,
+ const installed = await installPackedCli({
+ packageDir: CLI_PKG_DIR,
+ packDest,
+ installPrefix: H.installPrefix,
});
- const installed = join(H.installPrefix, 'node_modules', '@inkeep', 'open-knowledge');
- H.cliPath = join(installed, 'dist', 'cli.mjs');
- H.binShim = join(H.installPrefix, 'node_modules', '.bin', 'ok');
+ H.cliPath = installed.cliPath;
+ H.binShim = installed.binShim;
} else {
H.cliPath = WORKSPACE_DIST_CLI;
}
diff --git a/packages/cli/tests/e2e/install-deadline.test.ts b/packages/cli/tests/e2e/install-deadline.test.ts
new file mode 100644
index 000000000..338be03d2
--- /dev/null
+++ b/packages/cli/tests/e2e/install-deadline.test.ts
@@ -0,0 +1,252 @@
+import { afterAll, beforeAll, expect, test, vi } from 'vitest';
+import { createInstallFixture } from './install-fixture.test-helper';
+import { installPackedCli } from './packed-install.test-helper';
+
+let fixture: Awaited<ReturnType<typeof createInstallFixture>>;
+
+beforeAll(async () => {
+ fixture = await createInstallFixture();
+});
+
+afterAll(async () => {
+ await fixture.close();
+});
+
+function transportFailure(mode: 'locked' | 'fresh'): Error & {
+ code: number | string | null;
+ killed: boolean;
+ signal: string | null;
+ stdout: string;
+ stderr: string;
+} {
+ return Object.assign(new Error('Registry request timed out'), {
+ code: 1,
+ killed: false,
+ signal: null,
+ stdout: mode === 'locked' ? '{"level":"error","code":"ERR_SOCKET_TIMEOUT"}\n' : '',
+ stderr:
+ mode === 'locked'
+ ? 'OK_CLI_FETCH_OBSERVER_V1\nOK_CLI_FETCH_FAILURE_V1 {"code":"ERR_SOCKET_TIMEOUT"}\nRegistry unavailable…\n'
+ : 'npm error code ETIMEDOUT\nRegistry unavailable…\n',
+ });
+}
+
+test.each(['locked', 'fresh'] as const)(
+ 'fits registry request deadlines inside the acquisition budget in %s mode',
+ async (mode) => {
+ let clock = 0;
+ let attempts = 0;
+ const failure = transportFailure(mode);
+ const installation = installPackedCli(
+ { ...fixture, mode },
+ {
+ now: () => clock,
+ executeInstall: async (_command, args, options) => {
+ attempts++;
+ const setting = args.find((arg) => arg.startsWith('--fetch-timeout='));
+ const requestTimeout = setting
+ ? Number(setting.split('=')[1])
+ : mode === 'locked'
+ ? 60_000
+ : 300_000;
+ const remaining = options.timeout ?? 0;
+ if (requestTimeout >= remaining) {
+ clock += remaining;
+ throw Object.assign(new Error('Installation deadline expired'), {
+ code: null,
+ killed: true,
+ signal: 'SIGTERM',
+ stdout: '',
+ stderr: '',
+ });
+ }
+ clock += requestTimeout + 1;
+ throw failure;
+ },
+ },
+ );
+ await expect(installation).rejects.toMatchObject({
+ name: 'CliInstallUnavailableError',
+ exitCode: 77,
+ outputBytes: 3 * (Buffer.byteLength(failure.stdout) + Buffer.byteLength(failure.stderr)),
+ });
+ expect(attempts).toBe(3);
+ },
+);
+
+test.each(['locked', 'fresh'] as const)(
+ 'keeps classified acquisition unavailable when its deadline expires in %s mode',
+ async (mode) => {
+ let clock = 0;
+ let attempts = 0;
+ const installation = installPackedCli(
+ { ...fixture, mode },
+ {
+ now: () => clock,
+ executeInstall: async (_command, _args, options) => {
+ attempts++;
+ clock += options.timeout ?? 0;
+ throw Object.assign(transportFailure(mode), {
+ code: null,
+ killed: true,
+ signal: 'SIGTERM',
+ stdout: '',
+ });
+ },
+ },
+ );
+ await expect(installation).rejects.toMatchObject({
+ name: 'CliInstallUnavailableError',
+ exitCode: 77,
+ });
+ expect(attempts).toBe(1);
+ },
+);
+
+test('does not start another installer after the acquisition deadline', async () => {
+ let clock = 0;
+ let deadline = 0;
+ let attempts = 0;
+ const installation = installPackedCli(
+ { ...fixture, mode: 'fresh' },
+ {
+ now: () => {
+ const current = clock;
+ if (attempts > 0) clock = deadline;
+ return current;
+ },
+ executeInstall: async (_command, _args, options) => {
+ attempts++;
+ if (attempts > 1) throw new Error('Installer started after the deadline');
+ deadline = options.timeout ?? 0;
+ throw transportFailure('fresh');
+ },
+ },
+ );
+ await expect(installation).rejects.toMatchObject({
+ name: 'CliInstallUnavailableError',
+ exitCode: 77,
+ });
+ expect(attempts).toBe(1);
+});
+
+test.each([
+ { name: 'external termination', killed: false, signal: 'SIGTERM', code: null, expired: true },
+ { name: 'early termination', killed: true, signal: 'SIGTERM', code: null, expired: false },
+ { name: 'another signal', killed: true, signal: 'SIGKILL', code: null, expired: true },
+ {
+ name: 'output overflow',
+ killed: undefined,
+ signal: undefined,
+ code: 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+ expired: true,
+ },
+])(
+ 'preserves $name and its acquisition diagnostics',
+ async ({ name: _name, expired, ...fields }) => {
+ let clock = 0;
+ let attempts = 0;
+ let diagnostics = '';
+ const output = vi.spyOn(process.stderr, 'write').mockImplementation((chunk) => {
+ diagnostics += String(chunk);
+ return true;
+ });
+ const failure = Object.assign(transportFailure('fresh'), fields);
+ try {
+ const installation = installPackedCli(
+ { ...fixture, mode: 'fresh' },
+ {
+ now: () => clock,
+ executeInstall: async (_command, _args, options) => {
+ attempts++;
+ if (expired) clock += options.timeout ?? 0;
+ throw failure;
+ },
+ },
+ );
+ await expect(installation).rejects.toBe(failure);
+ expect(diagnostics).toContain(failure.stderr);
+ expect(attempts).toBe(1);
+ } finally {
+ output.mockRestore();
+ }
+ },
+);
+
+test.each(['locked', 'fresh'] as const)(
+ 'does not assign a prior transport failure to a silent deadline in %s mode',
+ async (mode) => {
+ let clock = 0;
+ let attempts = 0;
+ const failure = Object.assign(new Error('Installation deadline expired'), {
+ code: null,
+ killed: true,
+ signal: 'SIGTERM',
+ stdout: '',
+ stderr: '',
+ });
+ const installation = installPackedCli(
+ { ...fixture, mode },
+ {
+ now: () => clock,
+ executeInstall: async (_command, _args, options) => {
+ attempts++;
+ if (attempts === 1) throw transportFailure(mode);
+ clock += options.timeout ?? 0;
+ throw failure;
+ },
+ },
+ );
+ await expect(installation).rejects.toMatchObject({
+ message: expect.stringContaining('acquisition deadline elapsed on attempt 2 of 3.'),
+ cause: failure,
+ });
+ expect(attempts).toBe(2);
+ },
+);
+
+test.each(['locked', 'fresh'] as const)(
+ 'preserves lifecycle failures at the deadline in %s mode',
+ async (mode) => {
+ let clock = 0;
+ let attempts = 0;
+ const failure = Object.assign(transportFailure(mode), {
+ code: null,
+ killed: true,
+ signal: 'SIGTERM',
+ });
+ if (mode === 'locked') failure.stdout += '{"level":"error","code":"ELIFECYCLE"}\n';
+ else failure.stderr += 'npm error code ELIFECYCLE\n';
+ const installation = installPackedCli(
+ { ...fixture, mode },
+ {
+ now: () => clock,
+ executeInstall: async (_command, _args, options) => {
+ attempts++;
+ clock += options.timeout ?? 0;
+ throw failure;
+ },
+ },
+ );
+ await expect(installation).rejects.toMatchObject({
+ message: expect.stringContaining('acquisition deadline elapsed on attempt 1 of 3.'),
+ cause: failure,
+ });
+ expect(attempts).toBe(1);
+ },
+);
+
+test('preserves unclassified pnpm exits with optional acquisition errors', async () => {
+ let attempts = 0;
+ const failure = Object.assign(transportFailure('locked'), { stdout: '' });
+ const installation = installPackedCli(fixture, {
+ now: () => 0,
+ executeInstall: async () => {
+ attempts++;
+ throw failure;
+ },
+ });
+ await expect(installation).rejects.toThrow('Packed CLI pnpm installation failed');
+ await expect(installation).rejects.not.toMatchObject({ exitCode: 77 });
+ expect(attempts).toBe(1);
+});
diff --git a/packages/cli/tests/e2e/install-fixture.test-helper.ts b/packages/cli/tests/e2e/install-fixture.test-helper.ts
new file mode 100644
index 000000000..bf77042dc
--- /dev/null
+++ b/packages/cli/tests/e2e/install-fixture.test-helper.ts
@@ -0,0 +1,201 @@
+import { execFile } from 'node:child_process';
+import { mkdirSync, mkdtempSync, 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 YAML from 'yaml';
+import { z } from 'zod';
+
+const execute = promisify(execFile);
+export const PARENT = 'ok-cli-fixture-parent';
+export const LEAF = 'ok-cli-fixture-leaf';
+export const PEER = 'ok-cli-fixture-peer';
+
+export async function createInstallFixture(optionalParent = false) {
+ const root = mkdtempSync(join(tmpdir(), 'ok-cli-graph-'));
+ const packageDir = join(root, 'packages', 'cli');
+ const packDest = join(root, 'pack');
+ const installPrefix = join(root, 'install');
+ const archives = new Map<string, Buffer>();
+ const metadata = new Map<string, Record<string, unknown>>();
+ const responses = new Map<string, number | 'reset' | 'timeout'>();
+ const requests: string[] = [];
+ const registry = createServer((request, response) => {
+ const path = decodeURIComponent((request.url ?? '/').split('?')[0]);
+ requests.push(path);
+ const failure = responses.get(path);
+ if (failure === 'timeout') return;
+ if (failure === 'reset') {
+ response.destroy();
+ return;
+ }
+ if (failure) {
+ response.writeHead(failure);
+ response.end('fixture registry response');
+ return;
+ }
+ const archive = archives.get(path);
+ if (archive) {
+ response.writeHead(200, { 'content-type': 'application/octet-stream' });
+ response.end(archive);
+ return;
+ }
+ const manifest = metadata.get(path);
+ response.writeHead(manifest ? 200 : 404, { 'content-type': 'application/json' });
+ response.end(JSON.stringify(manifest ?? { error: 'not found' }));
+ });
+ 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');
+ const registryUrl = `http://127.0.0.1:${address.port}`;
+ const env = {
+ ...process.env,
+ npm_config_registry: registryUrl,
+ npm_config_cache: join(root, 'npm-cache'),
+ npm_config_fetch_retries: '0',
+ };
+ const close = async () => {
+ await new Promise<void>((resolve, reject) =>
+ registry.close((error) => (error ? reject(error) : resolve())),
+ );
+ rmSync(root, { recursive: true, force: true });
+ };
+ try {
+ const resolutions: Record<string, { integrity: string; tarball: string }> = {};
+ for (const name of [LEAF, PEER, PARENT]) {
+ const versions: Record<string, unknown> = {};
+ for (const version of name === PARENT ? ['1.0.0'] : ['1.0.0', '1.1.0']) {
+ const dir = join(root, 'registry-packages', `${name}-${version}`);
+ mkdirSync(dir, { recursive: true });
+ const manifest = {
+ name,
+ version,
+ main: 'index.cjs',
+ ...(name === PARENT
+ ? { dependencies: { [LEAF]: '^1.0.0' }, peerDependencies: { [PEER]: '^1.0.0' } }
+ : {}),
+ };
+ writeFileSync(join(dir, 'package.json'), JSON.stringify(manifest));
+ writeFileSync(
+ join(dir, 'index.cjs'),
+ name === PARENT
+ ? `module.exports = { leaf: require('${LEAF}'), peer: require('${PEER}') };\n`
+ : `module.exports = '${version}';\n`,
+ );
+ const result = await execute('npm', ['pack', '--ignore-scripts', '--json'], {
+ cwd: dir,
+ env: { ...env, npm_config_cache: join(root, 'pack-cache') },
+ });
+ const [packed] = z
+ .array(z.object({ filename: z.string(), integrity: z.string() }))
+ .nonempty()
+ .parse(JSON.parse(result.stdout));
+ const path = `/${name}/-/${packed.filename}`;
+ archives.set(path, readFileSync(join(dir, packed.filename)));
+ const resolution = { integrity: packed.integrity, tarball: `${registryUrl}${path}` };
+ resolutions[`${name}@${version}`] = resolution;
+ versions[version] = { ...manifest, dist: resolution };
+ }
+ metadata.set(`/${name}`, {
+ name,
+ 'dist-tags': { latest: name === PARENT ? '1.0.0' : '1.1.0' },
+ versions,
+ });
+ }
+ for (const path of [
+ packageDir,
+ packDest,
+ installPrefix,
+ join(packageDir, 'dist/public'),
+ join(packageDir, 'dist/assets/skills'),
+ ]) {
+ mkdirSync(path, { recursive: true });
+ }
+ writeFileSync(
+ join(root, 'package.json'),
+ JSON.stringify({
+ private: true,
+ packageManager: z
+ .object({ packageManager: z.string() })
+ .parse(
+ JSON.parse(readFileSync(new URL('../../../../package.json', import.meta.url), 'utf8')),
+ ).packageManager,
+ }),
+ );
+ writeFileSync(
+ join(root, 'pnpm-workspace.yaml'),
+ YAML.stringify({ packages: ['packages/*'], storeDir: join(root, 'store') }),
+ );
+ const manifest = {
+ name: '@inkeep/open-knowledge',
+ version: '1.0.0',
+ type: 'module',
+ bin: { ok: 'dist/cli.mjs' },
+ files: ['dist'],
+ dependencies: { [PEER]: '^1.0.0', ...(!optionalParent ? { [PARENT]: '^1.0.0' } : {}) },
+ ...(optionalParent ? { optionalDependencies: { [PARENT]: '^1.0.0' } } : {}),
+ };
+ writeFileSync(join(packageDir, 'package.json'), JSON.stringify(manifest));
+ writeFileSync(
+ join(packageDir, 'dist/cli.mjs'),
+ `#!/usr/bin/env node\nimport { createRequire } from 'node:module';\nconsole.log(JSON.stringify(createRequire(import.meta.url)('${PARENT}')));\n`,
+ );
+ writeFileSync(join(packageDir, 'dist/public/index.html'), '<title>CLI fixture</title>');
+ writeFileSync(join(packageDir, 'dist/assets/skills/SKILL.md'), '# CLI fixture\n');
+ const parentVersion = `1.0.0(${PEER}@1.0.0)`;
+ const lock = {
+ lockfileVersion: '9.0',
+ settings: { autoInstallPeers: true, excludeLinksFromLockfile: false },
+ importers: {
+ 'packages/cli': {
+ dependencies: {
+ [PEER]: { specifier: '^1.0.0', version: '1.0.0' },
+ ...(!optionalParent
+ ? { [PARENT]: { specifier: '^1.0.0', version: parentVersion } }
+ : {}),
+ },
+ ...(optionalParent
+ ? {
+ optionalDependencies: { [PARENT]: { specifier: '^1.0.0', version: parentVersion } },
+ }
+ : {}),
+ },
+ },
+ packages: {
+ [`${PARENT}@1.0.0`]: {
+ resolution: resolutions[`${PARENT}@1.0.0`],
+ peerDependencies: { [PEER]: '^1.0.0' },
+ },
+ [`${LEAF}@1.0.0`]: { resolution: resolutions[`${LEAF}@1.0.0`] },
+ [`${PEER}@1.0.0`]: { resolution: resolutions[`${PEER}@1.0.0`] },
+ },
+ snapshots: {
+ [`${PARENT}@${parentVersion}`]: {
+ dependencies: { [LEAF]: '1.0.0', [PEER]: '1.0.0' },
+ ...(optionalParent ? { optional: true } : {}),
+ },
+ [`${LEAF}@1.0.0`]: optionalParent ? { optional: true } : {},
+ [`${PEER}@1.0.0`]: {},
+ },
+ };
+ const lockPath = join(root, 'pnpm-lock.yaml');
+ writeFileSync(lockPath, YAML.stringify(lock));
+ return {
+ root,
+ packageDir,
+ packDest,
+ installPrefix,
+ env,
+ close,
+ requests,
+ responses,
+ manifest,
+ lock,
+ lockPath,
+ };
+ } catch (error) {
+ await close();
+ throw error;
+ }
+}
diff --git a/packages/cli/tests/e2e/install-outcome.test-helper.ts b/packages/cli/tests/e2e/install-outcome.test-helper.ts
new file mode 100644
index 000000000..bced9a13a
--- /dev/null
+++ b/packages/cli/tests/e2e/install-outcome.test-helper.ts
@@ -0,0 +1,88 @@
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import type { Reporter } from 'vitest/reporters';
+import { z } from 'zod';
+
+const unavailable = z.object({
+ name: z.literal('CliInstallUnavailableError'),
+ exitCode: z.literal(77),
+ acquisitionId: z.uuid(),
+ outputBytes: z.number().int().nonnegative(),
+});
+const commit = z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i);
+const eventSchema = z.object({
+ pull_request: z.object({ base: z.object({ sha: commit }) }).optional(),
+ merge_group: z.object({ base_sha: commit }).optional(),
+});
+
+function checkoutHead() {
+ try {
+ return commit.parse(
+ execFileSync('git', ['rev-parse', 'HEAD'], {
+ encoding: 'utf8',
+ stdio: ['ignore', 'pipe', 'pipe'],
+ }).trim(),
+ );
+ } catch (error) {
+ const fallback = commit.safeParse(process.env.GITHUB_SHA);
+ if (fallback.success) return fallback.data;
+ process.stderr.write(
+ `CLI acquisition result: checkout provenance unavailable: ${String(error)}\n`,
+ );
+ return null;
+ }
+}
+
+function comparisonBase() {
+ try {
+ const event = process.env.GITHUB_EVENT_PATH
+ ? eventSchema.parse(JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8')))
+ : undefined;
+ const base =
+ event?.pull_request?.base.sha ?? event?.merge_group?.base_sha ?? process.env.GITHUB_BASE_SHA;
+ return base === undefined ? null : commit.parse(base);
+ } catch (error) {
+ process.stderr.write(
+ `CLI acquisition result: comparison provenance unavailable: ${String(error)}\n`,
+ );
+ return null;
+ }
+}
+
+export default class InstallOutcomeReporter implements Reporter {
+ onTestRunEnd: NonNullable<Reporter['onTestRunEnd']> = (modules, errors, reason) => {
+ if (reason !== 'failed') return;
+ if (modules.some((module) => [...module.children.allTests('failed')].length > 0)) return;
+ const failures = [
+ ...errors,
+ ...modules.flatMap((module) => [
+ ...module.errors(),
+ ...[...module.children.allSuites()].flatMap((suite) => suite.errors()),
+ ]),
+ ];
+ const acquisitions = z.array(unavailable).nonempty().safeParse(failures);
+ if (!acquisitions.success) return;
+ const outputBytes = [
+ ...new Map(
+ acquisitions.data.map(({ acquisitionId, outputBytes }) => [acquisitionId, outputBytes]),
+ ).values(),
+ ].reduce((total, bytes) => total + bytes, 0);
+ process.stderr.write(
+ `INKEEP_GATE_RESULT_V1 ${JSON.stringify({
+ boundary: 'round',
+ class: 'not-run',
+ exit: 77,
+ signal: null,
+ outputBytes,
+ runId: randomUUID(),
+ head: checkoutHead(),
+ base: comparisonBase(),
+ subject: 'cli-e2e',
+ step: 'packed-install',
+ reasonCode: 'registry-unavailable',
+ })}\n`,
+ );
+ process.exitCode = 77;
+ };
+}
diff --git a/packages/cli/tests/e2e/install-outcome.test.ts b/packages/cli/tests/e2e/install-outcome.test.ts
new file mode 100644
index 000000000..591c476ea
--- /dev/null
+++ b/packages/cli/tests/e2e/install-outcome.test.ts
@@ -0,0 +1,190 @@
+import { execFile } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { expect, test, vi } from 'vitest';
+import { z } from 'zod';
+import InstallOutcomeReporter from './install-outcome.test-helper';
+import { CliInstallUnavailableError } from './packed-install.test-helper';
+
+const execute = promisify(execFile);
+const here = dirname(fileURLToPath(import.meta.url));
+const require_ = createRequire(import.meta.url);
+
+async function runFixture(
+ scenario: 'registry' | 'assets' | 'mixed',
+ options: { outsideGit?: boolean; env?: NodeJS.ProcessEnv; event?: unknown } = {},
+) {
+ const root = mkdtempSync(join(tmpdir(), 'ok-cli-outcome-'));
+ const config = join(root, 'vitest.config.mts');
+ const env = { ...process.env };
+ delete env.GITHUB_SHA;
+ delete env.GITHUB_EVENT_PATH;
+ delete env.GITHUB_BASE_SHA;
+ Object.assign(env, options.env);
+ if (options.event !== undefined) {
+ env.GITHUB_EVENT_PATH = join(root, 'event.json');
+ writeFileSync(env.GITHUB_EVENT_PATH, JSON.stringify(options.event));
+ }
+ writeFileSync(
+ config,
+ `import config from ${JSON.stringify(join(here, '../../vitest.e2e.config.ts'))};\nexport default { ...config, test: { ...config.test, include: ['*.test.ts'], maxWorkers: 2 } };\n`,
+ );
+ for (const failure of scenario === 'mixed' ? ['registry', 'assets'] : [scenario]) {
+ writeFileSync(
+ join(root, `${failure}.test.ts`),
+ `
+import { beforeAll, afterAll, expect, test } from ${JSON.stringify(fileURLToPath(import.meta.resolve('vitest')))};
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInstallFixture, LEAF } from ${JSON.stringify(join(here, 'install-fixture.test-helper.ts'))};
+import { installPackedCli } from ${JSON.stringify(join(here, 'packed-install.test-helper.ts'))};
+const fixture = await createInstallFixture(true);
+let installed;
+beforeAll(async () => {
+ ${failure === 'registry' ? "fixture.responses.set('/' + LEAF + '/-/' + LEAF + '-1.0.0.tgz', 503);" : "writeFileSync(join(fixture.packageDir, 'package.json'), JSON.stringify({ ...fixture.manifest, files: ['dist/cli.mjs'] }));"}
+ installed = await installPackedCli(fixture);
+});
+afterAll(() => fixture.close());
+test('packed CLI is ready', () => expect(installed.cliPath).toBeTruthy());
+`,
+ );
+ }
+ try {
+ try {
+ const result = await execute(
+ process.execPath,
+ [
+ join(dirname(require_.resolve('vitest/package.json')), 'vitest.mjs'),
+ 'run',
+ '--root',
+ root,
+ '--config',
+ config,
+ ],
+ { encoding: 'utf8', env, cwd: options.outsideGit ? root : undefined },
+ );
+ return { ...result, code: 0 };
+ } catch (error) {
+ return z.object({ code: z.number(), stdout: z.string(), stderr: z.string() }).parse(error);
+ }
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+}
+
+test('the CLI test runner reports acquisition exhaustion as did-not-run', async () => {
+ const result = await runFixture('registry');
+ expect(result.stdout + result.stderr).toContain('Packed CLI acquisition did-not-run');
+ expect(result.code).toBe(77);
+ const marker = result.stderr
+ .split('\n')
+ .find((line) => line.startsWith('INKEEP_GATE_RESULT_V1 '));
+ expect(marker).toBeDefined();
+ expect(JSON.parse(marker?.slice('INKEEP_GATE_RESULT_V1 '.length) ?? '{}')).toMatchObject({
+ class: 'not-run',
+ exit: 77,
+ outputBytes: expect.any(Number),
+ });
+ expect(
+ JSON.parse(marker?.slice('INKEEP_GATE_RESULT_V1 '.length) ?? '{}').outputBytes,
+ ).toBeGreaterThan(0);
+});
+
+test('the CLI test runner keeps missing packed assets as a product failure', async () => {
+ const result = await runFixture('assets');
+ expect(result.stdout + result.stderr).toContain('missing required asset');
+ expect(result.code).toBe(1);
+ expect(result.stderr).not.toContain('INKEEP_GATE_RESULT_V1');
+});
+
+test('a product failure takes precedence over acquisition exhaustion', async () => {
+ const result = await runFixture('mixed');
+ expect(result.stdout + result.stderr).toContain('Packed CLI acquisition did-not-run');
+ expect(result.stdout + result.stderr).toContain('missing required asset');
+ expect(result.code).toBe(1);
+ expect(result.stderr).not.toContain('INKEEP_GATE_RESULT_V1');
+});
+
+test.each([
+ { name: 'pull request', event: { pull_request: { base: { sha: 'b'.repeat(40) } } } },
+ { name: 'merge group', event: { merge_group: { base_sha: 'b'.repeat(40) } } },
+])('reports the available $name comparison identity', async ({ event }) => {
+ const result = await runFixture('registry', {
+ outsideGit: true,
+ env: { GITHUB_SHA: 'a'.repeat(40) },
+ event,
+ });
+ expect(result.code).toBe(77);
+ const marker = result.stderr
+ .split('\n')
+ .find((line) => line.startsWith('INKEEP_GATE_RESULT_V1 '));
+ expect(JSON.parse(marker?.slice('INKEEP_GATE_RESULT_V1 '.length) ?? '{}')).toMatchObject({
+ head: 'a'.repeat(40),
+ base: 'b'.repeat(40),
+ class: 'not-run',
+ });
+});
+
+test('preserves acquisition exhaustion when Git provenance is unavailable', async () => {
+ const result = await runFixture('registry', { outsideGit: true, env: { LC_ALL: 'C' } });
+ expect(result.code).toBe(77);
+ const marker = result.stderr
+ .split('\n')
+ .find((line) => line.startsWith('INKEEP_GATE_RESULT_V1 '));
+ expect(JSON.parse(marker?.slice('INKEEP_GATE_RESULT_V1 '.length) ?? '{}')).toMatchObject({
+ head: null,
+ base: null,
+ class: 'not-run',
+ });
+ expect(result.stderr).toContain('CLI acquisition result: checkout provenance unavailable');
+ expect(result.stderr).toContain('not a git repository');
+});
+
+test('preserves acquisition exhaustion when comparison metadata is invalid', async () => {
+ const result = await runFixture('registry', {
+ outsideGit: true,
+ env: { GITHUB_SHA: 'a'.repeat(40) },
+ event: { pull_request: { base: { sha: 'invalid' } } },
+ });
+ expect(result.code).toBe(77);
+ const marker = result.stderr
+ .split('\n')
+ .find((line) => line.startsWith('INKEEP_GATE_RESULT_V1 '));
+ expect(JSON.parse(marker?.slice('INKEEP_GATE_RESULT_V1 '.length) ?? '{}')).toMatchObject({
+ head: 'a'.repeat(40),
+ base: null,
+ class: 'not-run',
+ });
+ expect(result.stderr).toContain('CLI acquisition result: comparison provenance unavailable');
+ expect(result.stderr).toContain('"pull_request"');
+ expect(result.stderr).toContain('"sha"');
+});
+
+test('counts diagnostics once per acquisition when errors propagate', () => {
+ const first = { ...new CliInstallUnavailableError('First acquisition', 7), cause: undefined };
+ const second = { ...new CliInstallUnavailableError('Second acquisition', 11), cause: undefined };
+ let diagnostics = '';
+ const originalExit = process.exitCode;
+ const output = vi.spyOn(process.stderr, 'write').mockImplementation((chunk) => {
+ diagnostics += String(chunk);
+ return true;
+ });
+ try {
+ new InstallOutcomeReporter().onTestRunEnd([], [first, { ...first }, second], 'failed');
+ const marker = diagnostics
+ .split('\n')
+ .find((line) => line.startsWith('INKEEP_GATE_RESULT_V1 '));
+ expect(JSON.parse(marker?.slice('INKEEP_GATE_RESULT_V1 '.length) ?? '{}')).toMatchObject({
+ outputBytes: 18,
+ class: 'not-run',
+ });
+ expect(process.exitCode).toBe(77);
+ } finally {
+ process.exitCode = originalExit;
+ output.mockRestore();
+ }
+});
diff --git a/packages/cli/tests/e2e/packed-fetch.test-helper.cjs b/packages/cli/tests/e2e/packed-fetch.test-helper.cjs
new file mode 100644
index 000000000..f3e7d11c6
--- /dev/null
+++ b/packages/cli/tests/e2e/packed-fetch.test-helper.cjs
@@ -0,0 +1,19 @@
+module.exports = {
+ hooks: {
+ fetchers: {
+ remoteTarball: ({ defaultFetchers }) => {
+ process.stderr.write('OK_CLI_FETCH_OBSERVER_V1\n');
+ return async (...args) => {
+ try {
+ return await defaultFetchers.remoteTarball(...args);
+ } catch (error) {
+ process.stderr.write(
+ `OK_CLI_FETCH_FAILURE_V1 ${JSON.stringify({ code: error?.code, status: error?.response?.status })}\n`,
+ );
+ throw error;
+ }
+ };
+ },
+ },
+ },
+};
diff --git a/packages/cli/tests/e2e/packed-install.test-helper.ts b/packages/cli/tests/e2e/packed-install.test-helper.ts
new file mode 100644
index 000000000..82d87fcbf
--- /dev/null
+++ b/packages/cli/tests/e2e/packed-install.test-helper.ts
@@ -0,0 +1,342 @@
+import { type ExecFileOptionsWithStringEncoding, execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import {
+ cpSync,
+ existsSync,
+ mkdirSync,
+ readFileSync,
+ realpathSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual, promisify, stripVTControlCharacters } from 'node:util';
+import YAML from 'yaml';
+import { z } from 'zod';
+
+const execute = promisify(execFile);
+const INSTALL_ATTEMPTS = 3;
+const INSTALL_TIMEOUT_MS = 180_000;
+const OBSERVER_READY = 'OK_CLI_FETCH_OBSERVER_V1';
+const FETCH_FAILURE = 'OK_CLI_FETCH_FAILURE_V1 ';
+const TRANSPORT_CODES = new Set([
+ 'ECONNRESET',
+ 'ECONNREFUSED',
+ 'ETIMEDOUT',
+ 'ESOCKETTIMEDOUT',
+ 'ERR_SOCKET_TIMEOUT',
+ 'EAI_AGAIN',
+ 'ENOTFOUND',
+ 'ENETUNREACH',
+ 'EHOSTUNREACH',
+]);
+const declarations = z.record(z.string(), z.string());
+const manifestSchema = z.object({
+ name: z.string(),
+ version: z.string(),
+ dependencies: declarations.optional(),
+ optionalDependencies: declarations.optional(),
+ engines: declarations.optional(),
+ bin: z.union([z.string(), declarations]).optional(),
+});
+const references = z.record(z.string(), z.object({ specifier: z.string(), version: z.string() }));
+const lockSchema = z.looseObject({
+ lockfileVersion: z.literal('9.0'),
+ importers: z.record(
+ z.string(),
+ z.object({
+ dependencies: references.optional(),
+ optionalDependencies: references.optional(),
+ }),
+ ),
+ packages: z.record(z.string(), z.unknown()),
+ snapshots: z.record(z.string(), z.unknown()),
+});
+const fetchFailureSchema = z.object({ code: z.string().optional(), status: z.number().optional() });
+const pnpmErrorSchema = z.object({ level: z.literal('error'), code: z.string() });
+
+export class CliInstallUnavailableError extends Error {
+ readonly exitCode = 77;
+ readonly acquisitionId = randomUUID();
+ readonly outputBytes: number;
+
+ constructor(message: string, outputBytes: number) {
+ super(message);
+ this.name = 'CliInstallUnavailableError';
+ this.outputBytes = outputBytes;
+ }
+}
+
+export interface PackedInstallOptions {
+ packageDir: string;
+ packDest: string;
+ installPrefix: string;
+ mode?: 'locked' | 'fresh';
+ env?: NodeJS.ProcessEnv;
+}
+
+interface InstallRuntime {
+ now: () => number;
+ executeInstall: (
+ command: string,
+ args: string[],
+ options: ExecFileOptionsWithStringEncoding,
+ ) => Promise<{ stdout: string; stderr: string }>;
+}
+
+async function prepareLockedConsumer(
+ options: PackedInstallOptions,
+ tarball: string,
+ integrity: string,
+ env: NodeJS.ProcessEnv,
+) {
+ const workspaceDir = resolve(options.packageDir, '../..');
+ const lock = lockSchema.parse(
+ YAML.parse(readFileSync(join(workspaceDir, 'pnpm-lock.yaml'), 'utf8')),
+ );
+ const sourceManifest = manifestSchema.parse(
+ JSON.parse(readFileSync(join(options.packageDir, 'package.json'), 'utf8')),
+ );
+ const packed = await execute('tar', ['-xOf', tarball, 'package/package.json'], {
+ encoding: 'utf8',
+ env,
+ });
+ const manifest = manifestSchema.parse(JSON.parse(packed.stdout));
+ if (!isDeepStrictEqual(manifest, sourceManifest))
+ throw new Error('Packed CLI manifest differs from its source manifest');
+ const importer = lock.importers[relative(workspaceDir, options.packageDir).split('\\').join('/')];
+ if (!importer) throw new Error('Committed lockfile has no CLI importer');
+ for (const field of ['dependencies', 'optionalDependencies'] as const) {
+ const locked = Object.fromEntries(
+ Object.entries(importer[field] ?? {}).map(([name, entry]) => [name, entry.specifier]),
+ );
+ if (!isDeepStrictEqual(locked, manifest[field] ?? {}))
+ throw new Error(`Packed CLI ${field} differ from the committed lockfile`);
+ }
+ if (lock.pnpmfileChecksum !== undefined)
+ throw new Error('CLI replay requires explicit support for the workspace pnpmfile');
+ const workspace = z
+ .record(z.string(), z.unknown())
+ .parse(YAML.parse(readFileSync(join(workspaceDir, 'pnpm-workspace.yaml'), 'utf8')));
+ const patches = declarations.parse(workspace.patchedDependencies ?? {});
+ for (const path of Object.values(patches)) {
+ if (isAbsolute(path) || path.split(/[\\/]/).includes('..'))
+ throw new Error('CLI replay requires workspace-relative patch paths');
+ cpSync(join(workspaceDir, path), join(options.installPrefix, path), { recursive: true });
+ }
+ const { packageManager } = z
+ .object({ packageManager: z.string().regex(/^pnpm@\d+\.\d+\.\d+(?:\+.+)?$/) })
+ .parse(JSON.parse(readFileSync(join(workspaceDir, 'package.json'), 'utf8')));
+ const hook = readFileSync(
+ fileURLToPath(new URL('./packed-fetch.test-helper.cjs', import.meta.url)),
+ 'utf8',
+ );
+ writeFileSync(join(options.installPrefix, '.pnpmfile.cjs'), hook);
+ lock.pnpmfileChecksum = `sha256-${createHash('sha256').update(hook.replaceAll('\r\n', '\n')).digest('base64')}`;
+ cpSync(tarball, join(options.installPrefix, 'cli.tgz'));
+ const reference = 'file:cli.tgz';
+ const key = `${manifest.name}@${reference}`;
+ lock.importers = {
+ '.': { dependencies: { [manifest.name]: { specifier: reference, version: reference } } },
+ };
+ lock.packages[key] = {
+ resolution: { integrity, tarball: reference },
+ version: manifest.version,
+ engines: manifest.engines,
+ hasBin: Boolean(manifest.bin),
+ };
+ lock.snapshots[key] = Object.fromEntries(
+ (['dependencies', 'optionalDependencies'] as const).map((field) => [
+ field,
+ Object.fromEntries(
+ Object.entries(importer[field] ?? {}).map(([name, entry]) => [name, entry.version]),
+ ),
+ ]),
+ );
+ writeFileSync(
+ join(options.installPrefix, 'package.json'),
+ JSON.stringify({ private: true, packageManager, dependencies: { [manifest.name]: reference } }),
+ );
+ writeFileSync(
+ join(options.installPrefix, 'pnpm-workspace.yaml'),
+ YAML.stringify({ ...workspace, packages: [], enableGlobalVirtualStore: false }),
+ );
+ writeFileSync(join(options.installPrefix, 'pnpm-lock.yaml'), YAML.stringify(lock));
+ const version = await execute('pnpm', ['--version'], { cwd: options.installPrefix, env });
+ if (version.stdout.trim() !== packageManager.slice('pnpm@'.length).split('+')[0])
+ throw new Error('CLI replay pnpm version differs from the workspace pin');
+}
+
+export async function installPackedCli(
+ options: PackedInstallOptions,
+ { now, executeInstall }: InstallRuntime = { now: Date.now, executeInstall: execute },
+) {
+ const installPrefix = realpathSync(options.installPrefix);
+ 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 [archive] = z
+ .array(z.object({ filename: z.string(), integrity: z.string() }))
+ .nonempty()
+ .parse(JSON.parse(packed.stdout));
+ const tarball = realpathSync(join(options.packDest, archive.filename));
+ if (mode === 'locked')
+ await prepareLockedConsumer({ ...options, installPrefix }, tarball, archive.integrity, env);
+ const command = mode === 'locked' ? 'pnpm' : 'npm';
+ const args =
+ mode === 'locked'
+ ? ['install', '--frozen-lockfile', '--prod', '--reporter=ndjson', '--config.fetch-retries=0']
+ : [
+ 'install',
+ '--no-audit',
+ '--no-fund',
+ '--package-lock=true',
+ '--fetch-retries=0',
+ '--prefix',
+ installPrefix,
+ tarball,
+ ];
+ const configuredFetchTimeout = z.coerce
+ .number()
+ .int()
+ .positive()
+ .parse(env.npm_config_fetch_timeout ?? INSTALL_TIMEOUT_MS);
+ const deadline = now() + INSTALL_TIMEOUT_MS;
+ let unavailable: CliInstallUnavailableError | undefined;
+ let outputBytes = 0;
+ for (let attempt = 1; attempt <= INSTALL_ATTEMPTS; attempt++) {
+ const timeout = deadline - now();
+ if (timeout <= 0)
+ throw unavailable ?? new Error('Packed CLI acquisition deadline elapsed before installation');
+ const fetchTimeout = Math.min(
+ configuredFetchTimeout,
+ Math.max(1, Math.floor(timeout / (INSTALL_ATTEMPTS - attempt + 2))),
+ );
+ let stdout: string;
+ let stderr: string;
+ let failed = false;
+ let deadlineError: unknown;
+ try {
+ ({ stdout, stderr } = await executeInstall(
+ command,
+ [...args, `--fetch-timeout=${fetchTimeout}`],
+ {
+ cwd: installPrefix,
+ encoding: 'utf8',
+ timeout,
+ env,
+ },
+ ));
+ } catch (error) {
+ const failure = z
+ .object({
+ stdout: z.string(),
+ stderr: z.string(),
+ signal: z.string().nullable().optional(),
+ killed: z.boolean().optional(),
+ code: z.union([z.string(), z.number(), z.null()]).optional(),
+ })
+ .safeParse(error);
+ if (!failure.success) throw error;
+ ({ stdout, stderr } = failure.data);
+ const ownDeadline =
+ failure.data.killed === true &&
+ failure.data.code === null &&
+ failure.data.signal === 'SIGTERM' &&
+ now() >= deadline;
+ if (typeof failure.data.code === 'string' || (failure.data.signal && !ownDeadline)) {
+ process.stderr.write(stdout + stderr);
+ throw error;
+ }
+ if (ownDeadline) deadlineError = error;
+ failed = true;
+ }
+ outputBytes += Buffer.byteLength(stdout) + Buffer.byteLength(stderr);
+ const failures =
+ mode === 'locked'
+ ? stderr
+ .split('\n')
+ .filter((line) => line.startsWith(FETCH_FAILURE))
+ .map((line) => fetchFailureSchema.parse(JSON.parse(line.slice(FETCH_FAILURE.length))))
+ : failed
+ ? [
+ {
+ code:
+ [
+ ...stripVTControlCharacters(stderr).matchAll(
+ /^npm (?:error|ERR!) code (\S+)/gm,
+ ),
+ ].at(-1)?.[1] ?? '',
+ },
+ ]
+ : [];
+ if (mode === 'locked' && failed) {
+ const terminalErrors = stdout.split('\n').flatMap((line) => {
+ try {
+ const parsed = pnpmErrorSchema.safeParse(JSON.parse(line));
+ return parsed.success ? [{ code: parsed.data.code }] : [];
+ } catch {
+ return [];
+ }
+ });
+ failures.push(...terminalErrors);
+ if (!terminalErrors.length && !deadlineError)
+ failures.push({ code: 'UNCLASSIFIED_PNPM_FAILURE' });
+ }
+ const observed = mode !== 'locked' || stderr.split('\n').includes(OBSERVER_READY);
+ if (!failed && !failures.length && observed) break;
+ process.stderr.write(stdout + stderr);
+ const retryable =
+ failures.length > 0 &&
+ failures.every(
+ (failure) =>
+ TRANSPORT_CODES.has(failure.code ?? '') ||
+ /^(?:E|ERR_PNPM_FETCH_)(?:429|5\d\d)$/.test(failure.code ?? '') ||
+ ('status' in failure &&
+ (failure.status === 429 ||
+ (typeof failure.status === 'number' &&
+ failure.status >= 500 &&
+ failure.status <= 599))),
+ );
+ const message = `Packed CLI ${command} installation failed.\n${stdout}${stderr}`;
+ if (!retryable) {
+ if (deadlineError)
+ throw new Error(
+ `Packed CLI ${command} acquisition deadline elapsed on attempt ${attempt} of ${INSTALL_ATTEMPTS}.`,
+ { cause: deadlineError },
+ );
+ throw new Error(observed ? message : `CLI fetch observer did not run.\n${message}`);
+ }
+ unavailable = new CliInstallUnavailableError(
+ `Packed CLI acquisition did-not-run after ${attempt} of ${INSTALL_ATTEMPTS} attempts.\n${message}`,
+ outputBytes,
+ );
+ if (attempt === INSTALL_ATTEMPTS || now() >= deadline) throw unavailable;
+ rmSync(join(installPrefix, 'node_modules'), { recursive: true, force: true });
+ }
+ if (mode === 'fresh') {
+ mkdirSync(graphDir, { recursive: true });
+ cpSync(join(installPrefix, 'package-lock.json'), graphPath);
+ }
+ const installed = join(installPrefix, 'node_modules', '@inkeep', 'open-knowledge');
+ for (const asset of ['dist/cli.mjs', 'dist/public/index.html', 'dist/assets/skills']) {
+ if (!existsSync(join(installed, asset))) {
+ throw new Error(`Packed CLI is missing required asset: ${asset}`);
+ }
+ }
+ const binShim = join(installPrefix, 'node_modules', '.bin', 'ok');
+ if (!existsSync(binShim)) throw new Error('Packed CLI is missing its ok executable');
+ return {
+ cliPath: join(installed, 'dist', 'cli.mjs'),
+ binShim,
+ };
+}
diff --git a/packages/cli/tests/e2e/packed-install.test.ts b/packages/cli/tests/e2e/packed-install.test.ts
new file mode 100644
index 000000000..da83941f8
--- /dev/null
+++ b/packages/cli/tests/e2e/packed-install.test.ts
@@ -0,0 +1,266 @@
+import { execFile } from 'node:child_process';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ realpathSync,
+ 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 YAML from 'yaml';
+import { createInstallFixture, LEAF, PARENT, PEER } from './install-fixture.test-helper';
+import { installPackedCli } from './packed-install.test-helper';
+
+test('reports unavailable registry acquisition after bounded attempts', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ok-cli-install-contract-'));
+ const packageDir = join(root, 'package');
+ const packDest = join(root, 'pack');
+ const installPrefix = join(root, 'install');
+ for (const dir of [packageDir, packDest, installPrefix]) mkdirSync(dir);
+ writeFileSync(
+ join(packageDir, 'package.json'),
+ JSON.stringify({
+ name: '@inkeep/open-knowledge',
+ version: '1.0.0',
+ dependencies: { 'ok-cli-registry-fixture': '1.0.0' },
+ }),
+ );
+ let registryReached = false;
+ const registry = createServer((_request, response) => {
+ registryReached = true;
+ response.writeHead(503, { 'content-type': 'text/plain' });
+ response.end('registry temporarily unavailable');
+ });
+ 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');
+ try {
+ await expect(
+ installPackedCli({
+ mode: 'fresh',
+ packageDir,
+ packDest,
+ installPrefix,
+ env: {
+ ...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')),
+ );
+ expect(installs).toHaveLength(3);
+ } finally {
+ await new Promise<void>((resolve, reject) =>
+ registry.close((error) => (error ? reject(error) : resolve())),
+ );
+ rmSync(root, { recursive: true, force: true });
+ }
+});
+
+test('runs the packed CLI with the committed transitive and peer versions', async () => {
+ const fixture = await createInstallFixture();
+ try {
+ const installed = await installPackedCli(fixture);
+ const result = await promisify(execFile)(process.execPath, [installed.cliPath]);
+ expect(JSON.parse(result.stdout)).toEqual({ leaf: '1.0.0', peer: '1.0.0' });
+ } finally {
+ await fixture.close();
+ }
+});
+
+test('keeps fresh npm resolution selectable', async () => {
+ const fixture = await createInstallFixture();
+ try {
+ const installed = await installPackedCli({
+ ...fixture,
+ env: { ...fixture.env, OK_CLI_E2E_INSTALL_MODE: 'fresh' },
+ });
+ const result = await promisify(execFile)(process.execPath, [installed.cliPath]);
+ expect(JSON.parse(result.stdout)).toEqual({ leaf: '1.1.0', peer: '1.1.0' });
+ const graphPath = join(fixture.packageDir, 'test-results', 'cli-e2e-fresh-graph.json');
+ expect(existsSync(graphPath)).toBe(true);
+ expect(JSON.parse(readFileSync(graphPath, 'utf8'))).toMatchObject({
+ packages: {
+ [`node_modules/${LEAF}`]: { version: '1.1.0', integrity: expect.any(String) },
+ [`node_modules/${PEER}`]: { version: '1.1.0', integrity: expect.any(String) },
+ },
+ });
+ } finally {
+ await fixture.close();
+ }
+});
+
+test.each(['dist/public/index.html', 'dist/assets/skills'])(
+ 'rejects a packed files list that omits %s',
+ async (asset) => {
+ const fixture = await createInstallFixture();
+ try {
+ writeFileSync(
+ join(fixture.packageDir, 'package.json'),
+ JSON.stringify({
+ ...fixture.manifest,
+ files: [
+ 'dist/cli.mjs',
+ asset === 'dist/public/index.html' ? 'dist/assets' : 'dist/public',
+ ],
+ }),
+ );
+ await expect(installPackedCli(fixture)).rejects.toThrow(`missing required asset: ${asset}`);
+ } finally {
+ await fixture.close();
+ }
+ },
+);
+
+test('does not retry an optional dependency integrity mismatch', async () => {
+ const fixture = await createInstallFixture(true);
+ try {
+ fixture.lock.packages[`${LEAF}@1.0.0`].resolution.integrity =
+ `sha512-${Buffer.alloc(64).toString('base64')}`;
+ writeFileSync(fixture.lockPath, YAML.stringify(fixture.lock));
+ const installation = installPackedCli(fixture);
+ await expect(installation).rejects.toThrow('ERR_PNPM_TARBALL_INTEGRITY');
+ await expect(installation).rejects.not.toMatchObject({ exitCode: 77 });
+ expect(fixture.requests.filter((path) => path === `/${LEAF}/-/${LEAF}-1.0.0.tgz`)).toHaveLength(
+ 1,
+ );
+ } finally {
+ await fixture.close();
+ }
+});
+
+test('reports exhausted optional acquisition as unavailable', async () => {
+ const fixture = await createInstallFixture(true);
+ const path = `/${LEAF}/-/${LEAF}-1.0.0.tgz`;
+ try {
+ fixture.responses.set(path, 503);
+ await expect(installPackedCli(fixture)).rejects.toMatchObject({
+ name: 'CliInstallUnavailableError',
+ exitCode: 77,
+ });
+ expect(fixture.requests.filter((request) => request === path)).toHaveLength(3);
+ } finally {
+ await fixture.close();
+ }
+});
+
+test('does not retry an unavailable package version', async () => {
+ const fixture = await createInstallFixture(true);
+ const path = `/${LEAF}/-/${LEAF}-1.0.0.tgz`;
+ try {
+ fixture.responses.set(path, 404);
+ const installation = installPackedCli(fixture);
+ await expect(installation).rejects.toThrow('ERR_PNPM_FETCH_404');
+ await expect(installation).rejects.not.toMatchObject({ exitCode: 77 });
+ expect(fixture.requests.filter((request) => request === path)).toHaveLength(1);
+ } finally {
+ await fixture.close();
+ }
+});
+
+test('rejects a manifest that no longer matches the committed importer', async () => {
+ const fixture = await createInstallFixture();
+ try {
+ writeFileSync(
+ join(fixture.packageDir, 'package.json'),
+ JSON.stringify({
+ ...fixture.manifest,
+ dependencies: { ...fixture.manifest.dependencies, [PARENT]: '^2.0.0' },
+ }),
+ );
+ await expect(installPackedCli(fixture)).rejects.toThrow('differ from the committed lockfile');
+ } finally {
+ await fixture.close();
+ }
+});
+
+test('preserves optional platform exclusions from the committed graph', async () => {
+ const fixture = await createInstallFixture(true);
+ try {
+ Object.assign(fixture.lock.packages[`${PARENT}@1.0.0`], { os: [`!${process.platform}`] });
+ writeFileSync(fixture.lockPath, YAML.stringify(fixture.lock));
+ const installed = await installPackedCli(fixture);
+ const probe = promisify(execFile)(process.execPath, [
+ '--input-type=module',
+ '--eval',
+ `import { createRequire } from 'node:module'; const load = createRequire(process.argv[1]); console.log(load('${PEER}')); load('${PARENT}');`,
+ realpathSync(installed.cliPath),
+ ]);
+ await expect(probe).rejects.toMatchObject({
+ code: 1,
+ stdout: '1.0.0\n',
+ stderr: expect.stringContaining(`Cannot find module '${PARENT}'`),
+ });
+ } finally {
+ await fixture.close();
+ }
+});
+
+test('bounds transport retries for a required package', async () => {
+ const fixture = await createInstallFixture();
+ const path = `/${LEAF}/-/${LEAF}-1.0.0.tgz`;
+ try {
+ fixture.responses.set(path, 'reset');
+ await expect(installPackedCli(fixture)).rejects.toMatchObject({
+ name: 'CliInstallUnavailableError',
+ exitCode: 77,
+ });
+ expect(fixture.requests.filter((request) => request === path)).toHaveLength(3);
+ } finally {
+ await fixture.close();
+ }
+});
+
+test('reports registry socket timeouts as unavailable', async () => {
+ const fixture = await createInstallFixture();
+ const path = `/${LEAF}/-/${LEAF}-1.0.0.tgz`;
+ try {
+ fixture.responses.set(path, 'timeout');
+ await expect(
+ installPackedCli({
+ ...fixture,
+ env: { ...fixture.env, npm_config_fetch_timeout: '1000' },
+ }),
+ ).rejects.toMatchObject({ name: 'CliInstallUnavailableError', exitCode: 77 });
+ expect(fixture.requests.filter((request) => request === path)).toHaveLength(3);
+ } finally {
+ await fixture.close();
+ }
+});
+
+test('rejects a successful install without the fetch observer', async () => {
+ const fixture = await createInstallFixture();
+ let installed = false;
+ try {
+ const installation = installPackedCli(fixture, {
+ now: Date.now,
+ executeInstall: async (command, args, options) => {
+ const lockPath = join(fixture.installPrefix, 'pnpm-lock.yaml');
+ const lock = YAML.parse(readFileSync(lockPath, 'utf8'));
+ delete lock.pnpmfileChecksum;
+ writeFileSync(lockPath, YAML.stringify(lock));
+ const output = await promisify(execFile)(command, [...args, '--ignore-pnpmfile'], options);
+ installed = true;
+ return output;
+ },
+ });
+ await expect(installation).rejects.toThrow('CLI fetch observer did not run');
+ expect(installed).toBe(true);
+ } finally {
+ await fixture.close();
+ }
+});
diff --git a/packages/cli/vitest.e2e.config.ts b/packages/cli/vitest.e2e.config.ts
index 927f8801e..8cf5eecd0 100644
--- a/packages/cli/vitest.e2e.config.ts
+++ b/packages/cli/vitest.e2e.config.ts
@@ -1,19 +1,12 @@
import { defineConfig } from 'vitest/config';
import { okVitestBase } from '../../test-support/vitest.base';
+import InstallOutcomeReporter from './tests/e2e/install-outcome.test-helper';
-/**
- * Vitest config for the black-box CLI e2e (`test:e2e:cli`, the `cli-e2e` CI job).
- *
- * The single spec `tests/e2e/cli-linux-e2e.ts` deliberately omits the `.test`
- * infix so the unit tier never auto-discovers it. That also means the base
- * `include` glob does not match it and a bare CLI positional collects nothing,
- * so `include` is pinned to the one file here while keeping the shared base
- * (`bun:test` shim, `Bun` facade, development-condition pin, 30s timeout).
- */
export default defineConfig({
...okVitestBase,
test: {
...okVitestBase.test,
include: ['tests/e2e/cli-linux-e2e.ts'],
+ reporters: ['default', new InstallOutcomeReporter()],
},
});
diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.ts
index f4cc8a286..2a597ec3d 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';
export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';
diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.ts
index 8fb428b90..01ef76a9f 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,3 +1,4 @@
+
import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index fc267cbea..fb0ba5a7c 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.ts
index bfd7e3109..fa3cfcd86 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.ts
index 4d3250d3a..8be632ba4 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,3 +1,4 @@
+
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');