Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

End local auth subprocesses when their server shuts down (#5227)

Nick Gomez74980add05bf
diff --git a/.changeset/auth-file-atomic-write.md b/.changeset/auth-file-atomic-write.md
new file mode 100644
index 000000000..e36725cd3
--- /dev/null
+++ b/.changeset/auth-file-atomic-write.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Write the stored sign-in file atomically with owner-only permissions, so an interrupted write keeps the previously stored credentials.
diff --git a/.changeset/pending-signin-server-lifetime.md b/.changeset/pending-signin-server-lifetime.md
new file mode 100644
index 000000000..73a443c40
--- /dev/null
+++ b/.changeset/pending-signin-server-lifetime.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+End pending sign-in and authentication subprocesses when their server shuts down.
diff --git a/knip.config.ts b/knip.config.ts
index 37d9ce912..be41ab16c 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -145,15 +145,11 @@ 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/auth-child-lifecycle.test-helper.ts b/packages/app/tests/integration/auth-child-lifecycle.test-helper.ts
new file mode 100644
index 000000000..c1d1ecca5
--- /dev/null
+++ b/packages/app/tests/integration/auth-child-lifecycle.test-helper.ts
@@ -0,0 +1,75 @@
+import { ChildProcess } from 'node:child_process';
+import { subscribe, unsubscribe } from 'node:diagnostics_channel';
+import { once } from 'node:events';
+import { createServer, type Socket } from 'node:net';
+
+export function observeChildren(command: readonly string[]) {
+ const children: { child: ChildProcess; pid: number; closed: Promise<void> }[] = [];
+ const listener = (message: unknown): void => {
+ if (
+ !message ||
+ typeof message !== 'object' ||
+ !('process' in message) ||
+ !(message.process instanceof ChildProcess)
+ ) {
+ throw new Error('Unexpected child process diagnostic');
+ }
+ const child = message.process;
+ child.once('spawn', () => {
+ if (!command.every((arg, index) => child.spawnargs[index] === arg)) return;
+ const pid = child.pid;
+ if (pid === undefined) throw new Error('Spawned child has no pid');
+ children.push({
+ child,
+ pid,
+ closed: new Promise<void>((resolve) => child.once('close', () => resolve())),
+ });
+ });
+ };
+ subscribe('child_process', listener);
+ return {
+ children,
+ runningPids: () =>
+ children
+ .filter(({ child }) => child.exitCode === null && child.signalCode === null)
+ .map(({ pid }) => pid),
+ stop: () => unsubscribe('child_process', listener),
+ };
+}
+
+export async function createControlledAuthCli() {
+ const sockets = new Set<Socket>();
+ const ready = Promise.withResolvers<void>();
+ const control = createServer((socket) => {
+ sockets.add(socket);
+ ready.resolve();
+ socket.once('close', () => sockets.delete(socket));
+ socket.on('error', () => socket.destroy());
+ });
+ control.listen(0, '127.0.0.1');
+ await once(control, 'listening');
+ const address = control.address();
+ if (!address || typeof address === 'string') throw new Error('Missing control listener');
+ const script = `
+ const net = require('node:net');
+ process.on('SIGTERM', () => {});
+ const socket = net.connect(${address.port}, '127.0.0.1', () => {
+ console.log(JSON.stringify({type:'verification', user_code:'WDJB-MJHT', verification_uri:'https://github.com/login/device', expires_in:900}));
+ console.error('First copy your one-time code: WDJB-MJHT');
+ console.error('https://github.com/login/device');
+ });
+ socket.once('end', () => process.exit(0));
+ socket.once('error', () => process.exit(1));
+ `;
+ return {
+ ready: ready.promise,
+ script,
+ cliArgs: [process.execPath, '-e', script],
+ release: async () => {
+ const closed = once(control, 'close');
+ control.close();
+ for (const socket of sockets) socket.end();
+ await closed;
+ },
+ };
+}
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 a28cc2b18..8a60e5826 100644
--- a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
+++ b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
@@ -1,4 +1,3 @@
-
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/gh-cold-after-shutdown.test.ts b/packages/app/tests/integration/gh-cold-after-shutdown.test.ts
new file mode 100644
index 000000000..66002caaf
--- /dev/null
+++ b/packages/app/tests/integration/gh-cold-after-shutdown.test.ts
@@ -0,0 +1,54 @@
+import { delimiter } from 'node:path';
+import { expect, test, vi } from 'vitest';
+import { observeChildren } from './auth-child-lifecycle.test-helper';
+import { createControlledGh } from './gh-process-lifecycle.test-helper';
+import { createTestServer, type TestServer } from './test-harness';
+
+vi.mock('node:child_process', async (importOriginal) => {
+ const original = await importOriginal<typeof import('node:child_process')>();
+ const { guardAbsoluteGhLaunches } = await import('./gh-process-safety.test-helper');
+ return guardAbsoluteGhLaunches(original);
+});
+
+test.skipIf(process.platform === 'win32')(
+ 'a cold gh sign-in request after shutdown starts no gh child',
+ async () => {
+ const fixture = await createControlledGh({ version: 'park', auth: 'park', lookup: 'park' });
+ vi.stubEnv('PATH', `${fixture.dir}${delimiter}${process.env.PATH ?? ''}`);
+ const observer = observeChildren(['gh']);
+ const controller = new AbortController();
+ let server: TestServer | undefined;
+ let request: Promise<{ kind: 'response'; status: number; body: string }> | undefined;
+ try {
+ server = await createTestServer();
+ await server.instance.destroy();
+ request = fetch(`${server.baseUrl}/api/local-op/auth/gh-login`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ signal: controller.signal,
+ })
+ .then(async (response) => ({
+ kind: 'response' as const,
+ status: response.status,
+ body: await response.text(),
+ }))
+ .catch(() => ({ kind: 'response' as const, status: 0, body: '' }));
+ const first = await Promise.race([
+ request,
+ fixture.next('version').then(() => ({ kind: 'version' as const })),
+ ]);
+ expect(first.kind).toBe('response');
+ if (first.kind === 'response') expect(first.status).toBe(503);
+ expect(observer.children).toHaveLength(0);
+ } finally {
+ controller.abort();
+ await fixture.cleanup();
+ await request;
+ await Promise.all(observer.children.map(({ closed }) => closed));
+ await server?.cleanup();
+ observer.stop();
+ vi.unstubAllEnvs();
+ }
+ },
+);
diff --git a/packages/app/tests/integration/gh-discovery-shutdown.test.ts b/packages/app/tests/integration/gh-discovery-shutdown.test.ts
new file mode 100644
index 000000000..8152c4c5d
--- /dev/null
+++ b/packages/app/tests/integration/gh-discovery-shutdown.test.ts
@@ -0,0 +1,58 @@
+import { delimiter } from 'node:path';
+import { expect, test, vi } from 'vitest';
+import { observeChildren } from './auth-child-lifecycle.test-helper';
+import { createControlledGh } from './gh-process-lifecycle.test-helper';
+import { createTestServer, type TestServer } from './test-harness';
+
+vi.mock('node:child_process', async (importOriginal) => {
+ const original = await importOriginal<typeof import('node:child_process')>();
+ const { guardAbsoluteGhLaunches } = await import('./gh-process-safety.test-helper');
+ return guardAbsoluteGhLaunches(original);
+});
+
+test.skipIf(process.platform === 'win32')(
+ 'server shutdown drains its pending gh discovery child before returning',
+ async () => {
+ const fixture = await createControlledGh({ version: 'park', auth: 'park', lookup: 'park' });
+ vi.stubEnv('PATH', `${fixture.dir}${delimiter}${process.env.PATH ?? ''}`);
+ const observer = observeChildren([]);
+ const controller = new AbortController();
+ let server: TestServer | undefined;
+ let destruction: Promise<void> | undefined;
+ let request: Promise<{ status: number; body: string }> | undefined;
+ try {
+ server = await createTestServer();
+ request = fetch(`${server.baseUrl}/api/local-op/auth/gh-login`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ signal: controller.signal,
+ })
+ .then(async (response) => ({ status: response.status, body: await response.text() }))
+ .catch(() => ({ status: 0, body: '' }));
+ const connected = await fixture.next('version');
+ const probe = observer.children.find(({ pid }) => pid === connected.pid);
+ expect(probe?.child.spawnargs).toContain('--version');
+ if (!probe) throw new Error('Pending version child was not observed');
+ destruction = server.instance.destroy();
+ const firstFinished = await Promise.race([
+ probe.closed.then(() => 'probe closed'),
+ destruction.then(() => 'server destroyed'),
+ ]);
+ expect(firstFinished).toBe('probe closed');
+ await destruction;
+ const response = await request;
+ expect(response.status).toBe(503);
+ expect(probe.child.exitCode !== null || probe.child.signalCode !== null).toBe(true);
+ } finally {
+ controller.abort();
+ await fixture.cleanup();
+ await request;
+ await destruction;
+ await Promise.all(observer.children.map(({ closed }) => closed));
+ await server?.cleanup();
+ observer.stop();
+ vi.unstubAllEnvs();
+ }
+ },
+);
diff --git a/packages/app/tests/integration/gh-lookup-shutdown.test.ts b/packages/app/tests/integration/gh-lookup-shutdown.test.ts
new file mode 100644
index 000000000..b14191bd0
--- /dev/null
+++ b/packages/app/tests/integration/gh-lookup-shutdown.test.ts
@@ -0,0 +1,90 @@
+import { delimiter } from 'node:path';
+import { expect, test, vi } from 'vitest';
+import { observeChildren } from './auth-child-lifecycle.test-helper';
+import { createControlledGh } from './gh-process-lifecycle.test-helper';
+import { createTestServer, type TestServer } from './test-harness';
+
+vi.mock('node:child_process', async (importOriginal) => {
+ const original = await importOriginal<typeof import('node:child_process')>();
+ const { guardAbsoluteGhLaunches } = await import('./gh-process-safety.test-helper');
+ return guardAbsoluteGhLaunches(original);
+});
+
+test.skipIf(process.platform === 'win32')(
+ 'server shutdown terminates the pending gh username lookup without completing sign-in',
+ async () => {
+ const fixture = await createControlledGh({
+ version: 'complete',
+ auth: 'complete',
+ lookup: 'park',
+ });
+ vi.stubEnv('PATH', `${fixture.dir}${delimiter}${process.env.PATH ?? ''}`);
+ const observer = observeChildren(['gh']);
+ const controller = new AbortController();
+ let server: TestServer | undefined;
+ let destruction: Promise<void> | undefined;
+ try {
+ server = await createTestServer();
+ const response = await fetch(`${server.baseUrl}/api/local-op/auth/gh-login`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ signal: controller.signal,
+ });
+ expect(response.status).toBe(200);
+ if (!response.body) throw new Error('Missing gh auth stream');
+ const reader = response.body.getReader();
+ const decoder = new TextDecoder();
+ let stream = '';
+ try {
+ while (!stream.includes('"type":"verification"')) {
+ const { done, value } = await reader.read();
+ if (done) throw new Error('gh auth stream ended before verification');
+ stream += decoder.decode(value, { stream: true });
+ }
+ await fixture.next('lookup');
+ const lookup = observer.children.find(({ child }) => child.spawnargs[1] === 'api');
+ expect(lookup).toBeDefined();
+ if (!lookup) throw new Error('Pending lookup child was not observed');
+ const termination = vi.spyOn(lookup.child, 'kill');
+ destruction = server.instance.destroy();
+ await Promise.resolve();
+ const lookupWasTerminated = termination.mock.calls.length > 0;
+ const firstFinished = Promise.race([
+ lookup.closed.then(() => 'lookup closed'),
+ destruction.then(() => 'server destroyed'),
+ ]);
+ fixture.release('lookup');
+ expect(await firstFinished).toBe('lookup closed');
+ await Promise.all([destruction, lookup.closed]);
+ for (;;) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ stream += decoder.decode(value, { stream: true });
+ }
+ const events = stream
+ .split('\n')
+ .filter(Boolean)
+ .map((line) => JSON.parse(line) as { type?: string });
+ expect(events.map((event) => event.type)).toContain('verification');
+ expect({
+ lookupWasTerminated,
+ completed: events.some((event) => event.type === 'complete'),
+ }).toEqual({
+ lookupWasTerminated: true,
+ completed: false,
+ });
+ } finally {
+ reader.releaseLock();
+ }
+ } finally {
+ controller.abort();
+ await fixture.cleanup();
+ await Promise.all(observer.children.map(({ closed }) => closed));
+ await destruction;
+ await server?.cleanup();
+ observer.stop();
+ vi.unstubAllEnvs();
+ }
+ },
+);
diff --git a/packages/app/tests/integration/gh-process-lifecycle.test-helper.ts b/packages/app/tests/integration/gh-process-lifecycle.test-helper.ts
new file mode 100644
index 000000000..bd5d1b01d
--- /dev/null
+++ b/packages/app/tests/integration/gh-process-lifecycle.test-helper.ts
@@ -0,0 +1,110 @@
+import { once } from 'node:events';
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer, type Socket } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export type GhPhase = 'version' | 'auth' | 'lookup' | 'status';
+
+type GhMessage = { phase: GhPhase; event: 'connected' | 'signal'; pid: number };
+
+export async function createControlledGh(options: {
+ version: 'park' | 'complete';
+ auth: 'park' | 'complete';
+ lookup: 'park' | 'complete';
+ status?: 'park' | 'complete';
+}) {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-gh-lifecycle-'));
+ const sockets = new Map<Socket, GhPhase>();
+ const released = new Set<GhPhase>();
+ let cleaningUp = false;
+ const messages: GhMessage[] = [];
+ const waiters: Array<{
+ match: (message: GhMessage) => boolean;
+ resolve: (message: GhMessage) => void;
+ }> = [];
+ const control = createServer((socket) => {
+ let buffer = '';
+ socket.on('data', (chunk: Buffer) => {
+ buffer += chunk.toString('utf8');
+ const lines = buffer.split('\n');
+ buffer = lines.pop() ?? '';
+ for (const line of lines.filter(Boolean)) {
+ const message = JSON.parse(line) as GhMessage;
+ if (message.event === 'connected') {
+ sockets.set(socket, message.phase);
+ if (cleaningUp || released.has(message.phase)) socket.write('release\n');
+ }
+ messages.push(message);
+ const index = waiters.findIndex(({ match }) => match(message));
+ if (index >= 0) waiters.splice(index, 1)[0]?.resolve(message);
+ }
+ });
+ socket.once('close', () => sockets.delete(socket));
+ socket.on('error', () => socket.destroy());
+ });
+ control.listen(0, '127.0.0.1');
+ await once(control, 'listening');
+ const address = control.address();
+ if (!address || typeof address === 'string') throw new Error('Missing gh fixture address');
+
+ const executable = join(dir, 'gh');
+ const script = `#!${process.execPath}
+const net = require('node:net');
+const phase = process.argv[2] === '--version' ? 'version' : process.argv[2] === 'api' ? 'lookup' : process.argv[3] === 'status' ? 'status' : 'auth';
+const modes = ${JSON.stringify(options)};
+const socket = net.connect(${address.port}, '127.0.0.1');
+let buffer = '';
+function complete() {
+ if (phase === 'version') process.stdout.write('gh version 1.0.0\\n');
+ if (phase === 'lookup') process.stdout.write('octocat\\n');
+ socket.end(() => process.exit(0));
+}
+socket.on('connect', () => {
+ socket.write(JSON.stringify({ phase, event: 'connected', pid: process.pid }) + '\\n', () => {
+ if (phase === 'auth') {
+ process.stderr.write('First copy your one-time code: WDJB-MJHT\\nhttps://github.com/login/device\\n');
+ }
+ if (phase === 'status') process.stdout.write(JSON.stringify({ authenticated: false }) + '\\n');
+ if (modes[phase] === 'complete') complete();
+ });
+});
+socket.on('data', (chunk) => {
+ buffer += chunk.toString('utf8');
+ if (buffer.includes('release\\n')) complete();
+});
+socket.on('error', () => process.exit(1));
+process.on('SIGTERM', () => socket.write(JSON.stringify({ phase, event: 'signal', pid: process.pid }) + '\\n', () => socket.end(() => process.exit(0))));
+`;
+ writeFileSync(executable, script, { flag: 'wx', mode: 0o755 });
+ chmodSync(executable, 0o755);
+
+ return {
+ dir,
+ executable,
+ port: address.port,
+ messages,
+ next: (phase: GhPhase, event: GhMessage['event'] = 'connected') => {
+ const found = messages.find((message) => message.phase === phase && message.event === event);
+ if (found) return Promise.resolve(found);
+ return new Promise<GhMessage>((resolve) => {
+ waiters.push({
+ match: (message) => message.phase === phase && message.event === event,
+ resolve,
+ });
+ });
+ },
+ release: (phase: GhPhase) => {
+ released.add(phase);
+ for (const [socket, current] of sockets) if (current === phase) socket.write('release\n');
+ },
+ cleanup: async () => {
+ cleaningUp = true;
+ for (const socket of sockets.keys()) socket.write('release\n');
+ const closed = once(control, 'close');
+ control.close();
+ await closed;
+ rmSync(dir, { recursive: true, force: true });
+ },
+ };
+}
diff --git a/packages/app/tests/integration/gh-process-safety.test-helper.ts b/packages/app/tests/integration/gh-process-safety.test-helper.ts
new file mode 100644
index 000000000..c8d849043
--- /dev/null
+++ b/packages/app/tests/integration/gh-process-safety.test-helper.ts
@@ -0,0 +1,36 @@
+import type * as childProcess from 'node:child_process';
+import { basename, isAbsolute } from 'node:path';
+import { promisify } from 'node:util';
+
+export function guardAbsoluteGhLaunches(original: typeof childProcess): typeof childProcess {
+ const check = (command: unknown): void => {
+ if (
+ typeof command === 'string' &&
+ isAbsolute(command) &&
+ /^gh(?:\.exe)?$/i.test(basename(command))
+ ) {
+ throw new Error(`Unexpected absolute gh invocation: ${command}`);
+ }
+ };
+ const guardedExecFile = ((...args: unknown[]) => {
+ check(args[0]);
+ return Reflect.apply(original.execFile, original, args);
+ }) as typeof original.execFile;
+ const nativePromisified = Reflect.get(original.execFile, promisify.custom);
+ if (typeof nativePromisified === 'function') {
+ Object.defineProperty(guardedExecFile, promisify.custom, {
+ value: (...args: unknown[]) => {
+ check(args[0]);
+ return Reflect.apply(nativePromisified, original.execFile, args);
+ },
+ });
+ }
+ return {
+ ...original,
+ execFile: guardedExecFile,
+ spawn: ((...args: unknown[]) => {
+ check(args[0]);
+ return Reflect.apply(original.spawn, original, args);
+ }) as typeof original.spawn,
+ };
+}
diff --git a/packages/app/tests/integration/gh-shared-discovery.test.ts b/packages/app/tests/integration/gh-shared-discovery.test.ts
new file mode 100644
index 000000000..1a97cf2da
--- /dev/null
+++ b/packages/app/tests/integration/gh-shared-discovery.test.ts
@@ -0,0 +1,116 @@
+import { delimiter } from 'node:path';
+import { expect, test, vi } from 'vitest';
+import { observeChildren } from './auth-child-lifecycle.test-helper';
+import { createControlledGh } from './gh-process-lifecycle.test-helper';
+import { createTestServer, type TestServer } from './test-harness';
+
+vi.mock('node:child_process', async (importOriginal) => {
+ const original = await importOriginal<typeof import('node:child_process')>();
+ const { guardAbsoluteGhLaunches } = await import('./gh-process-safety.test-helper');
+ return guardAbsoluteGhLaunches(original);
+});
+
+test.skipIf(process.platform === 'win32')(
+ 'destroying one server preserves pending gh discovery and sign-in for another server',
+ async () => {
+ const fixture = await createControlledGh({ version: 'park', auth: 'park', lookup: 'park' });
+ vi.stubEnv('PATH', `${fixture.dir}${delimiter}${process.env.PATH ?? ''}`);
+ const observer = observeChildren([]);
+ const controllers: AbortController[] = [];
+ let firstServer: TestServer | undefined;
+ let secondServer: TestServer | undefined;
+ let firstRequest: Promise<{ status: number; body: string }> | undefined;
+ let statusRequest: Promise<{ status: number; body: { ghAvailable?: boolean } }> | undefined;
+ try {
+ const statusCli = [
+ process.execPath,
+ '-e',
+ `const socket = require('node:net').connect(${fixture.port}, '127.0.0.1', () => {
+ socket.write(JSON.stringify({ phase: 'status', event: 'connected', pid: process.pid }) + '\\n', () => {
+ process.stdout.write(JSON.stringify({ authenticated: false }) + '\\n', () => socket.end(() => process.exit(0)));
+ });
+ });`,
+ ];
+ firstServer = await createTestServer();
+ secondServer = await createTestServer({ localOpCliArgs: statusCli });
+ const firstController = new AbortController();
+ controllers.push(firstController);
+ firstRequest = fetch(`${firstServer.baseUrl}/api/local-op/auth/gh-login`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ signal: firstController.signal,
+ })
+ .then(async (response) => ({ status: response.status, body: await response.text() }))
+ .catch(() => ({ status: 0, body: '' }));
+ const version = await fixture.next('version');
+ const probe = observer.children.find(({ pid }) => pid === version.pid);
+ expect(probe?.child.spawnargs).toContain('--version');
+ if (!probe) throw new Error('Shared version child was not observed');
+
+ const statusController = new AbortController();
+ controllers.push(statusController);
+ statusRequest = fetch(`${secondServer.baseUrl}/api/local-op/auth/status`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ signal: statusController.signal,
+ })
+ .then(async (response) => ({
+ status: response.status,
+ body: (await response.json()) as { ghAvailable?: boolean },
+ }))
+ .catch(() => ({ status: 0, body: {} }));
+ const status = await fixture.next('status');
+ const statusChild = observer.children.find(({ pid }) => pid === status.pid);
+ expect(statusChild).toBeDefined();
+ if (!statusChild) throw new Error('Second-server status child was not observed');
+ await statusChild.closed;
+ await Promise.resolve();
+
+ await firstServer.instance.destroy();
+ fixture.release('version');
+ await probe.closed;
+ const [firstResponse, statusResponse] = await Promise.all([firstRequest, statusRequest]);
+ expect(firstResponse.status).toBe(503);
+ expect(statusResponse.status).toBe(200);
+ expect(statusResponse.body.ghAvailable).toBe(true);
+ const loginController = new AbortController();
+ controllers.push(loginController);
+ const loginResponse = await fetch(`${secondServer.baseUrl}/api/local-op/auth/gh-login`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ signal: loginController.signal,
+ });
+ expect(loginResponse.status).toBe(200);
+ if (!loginResponse.body) throw new Error('Missing second-server gh auth stream');
+ const reader = loginResponse.body.getReader();
+ try {
+ let stream = '';
+ while (!stream.includes('"type":"verification"')) {
+ const { done, value } = await reader.read();
+ if (done) throw new Error('Second-server gh auth stream ended before verification');
+ stream += new TextDecoder().decode(value);
+ }
+ const auth = await fixture.next('auth');
+ const authChild = observer.children.find(({ pid }) => pid === auth.pid);
+ expect(authChild).toBeDefined();
+ if (!authChild) throw new Error('Second-server auth child was not observed');
+ await secondServer.instance.destroy();
+ await authChild.closed;
+ expect(authChild.child.exitCode !== null || authChild.child.signalCode !== null).toBe(true);
+ } finally {
+ reader.releaseLock();
+ }
+ } finally {
+ for (const controller of controllers) controller.abort();
+ await fixture.cleanup();
+ await Promise.all([firstRequest, statusRequest]);
+ await Promise.all(observer.children.map(({ closed }) => closed));
+ await Promise.all([firstServer?.cleanup(), secondServer?.cleanup()]);
+ observer.stop();
+ vi.unstubAllEnvs();
+ }
+ },
+);
diff --git a/packages/app/tests/integration/gh-status-shutdown.test.ts b/packages/app/tests/integration/gh-status-shutdown.test.ts
new file mode 100644
index 000000000..f4072d07d
--- /dev/null
+++ b/packages/app/tests/integration/gh-status-shutdown.test.ts
@@ -0,0 +1,66 @@
+import { delimiter } from 'node:path';
+import { expect, test, vi } from 'vitest';
+import { observeChildren } from './auth-child-lifecycle.test-helper';
+import { createControlledGh } from './gh-process-lifecycle.test-helper';
+import { createTestServer, type TestServer } from './test-harness';
+
+vi.mock('node:child_process', async (importOriginal) => {
+ const original = await importOriginal<typeof import('node:child_process')>();
+ const { guardAbsoluteGhLaunches } = await import('./gh-process-safety.test-helper');
+ return guardAbsoluteGhLaunches(original);
+});
+
+test.skipIf(process.platform === 'win32')(
+ 'an auth status result after shutdown cannot start gh discovery',
+ async () => {
+ const fixture = await createControlledGh({
+ version: 'park',
+ auth: 'park',
+ lookup: 'park',
+ status: 'park',
+ });
+ vi.stubEnv('PATH', `${fixture.dir}${delimiter}${process.env.PATH ?? ''}`);
+ const observer = observeChildren(['gh']);
+ const controller = new AbortController();
+ let server: TestServer | undefined;
+ let request: Promise<{ kind: 'response'; status: number }> | undefined;
+ let destruction: Promise<void> | undefined;
+ try {
+ server = await createTestServer({ localOpCliArgs: ['gh'] });
+ request = fetch(`${server.baseUrl}/api/local-op/auth/status`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ host: 'github.com' }),
+ signal: controller.signal,
+ })
+ .then(async (response) => {
+ await response.text();
+ return { kind: 'response' as const, status: response.status };
+ })
+ .catch(() => ({ kind: 'response' as const, status: 0 }));
+ const status = await fixture.next('status');
+ expect(observer.children.some(({ pid }) => pid === status.pid)).toBe(true);
+ destruction = server.instance.destroy();
+ fixture.release('status');
+ const first = await Promise.race([
+ request,
+ fixture.next('version').then(() => ({ kind: 'version' as const })),
+ ]);
+ expect(first.kind).toBe('response');
+ if (first.kind === 'response') expect(first.status).toBe(503);
+ expect(
+ observer.children.filter(({ child }) => child.spawnargs.includes('--version')),
+ ).toHaveLength(0);
+ await destruction;
+ } finally {
+ controller.abort();
+ await fixture.cleanup();
+ await request;
+ await destruction;
+ await Promise.all(observer.children.map(({ closed }) => closed));
+ await server?.cleanup();
+ observer.stop();
+ vi.unstubAllEnvs();
+ }
+ },
+);
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 4fc2c11f9..6fcdc23f2 100644
--- a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
+++ b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
@@ -1,4 +1,3 @@
-
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 9f2f6feb6..40b5cdfd6 100644
--- a/packages/app/tests/integration/interior-edit-freshness.test.ts
+++ b/packages/app/tests/integration/interior-edit-freshness.test.ts
@@ -1,4 +1,3 @@
-
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 2a085742b..93666af70 100644
--- a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
+++ b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
@@ -1,4 +1,3 @@
-
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/local-op-auth-pat-shutdown.test.ts b/packages/app/tests/integration/local-op-auth-pat-shutdown.test.ts
new file mode 100644
index 000000000..f6088d631
--- /dev/null
+++ b/packages/app/tests/integration/local-op-auth-pat-shutdown.test.ts
@@ -0,0 +1,31 @@
+import { expect, test } from 'vitest';
+import { createControlledAuthCli, observeChildren } from './auth-child-lifecycle.test-helper';
+import { createTestServer, type TestServer } from './test-harness';
+
+test('server destruction ends a pending token sign-in child', async () => {
+ const fixture = await createControlledAuthCli();
+ const observer = observeChildren(fixture.cliArgs);
+ let server: TestServer | undefined;
+ const controller = new AbortController();
+ let response: Promise<unknown> | undefined;
+ try {
+ server = await createTestServer({ localOpCliArgs: fixture.cliArgs });
+ response = fetch(`${server.baseUrl}/api/local-op/auth/pat`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ token: 'fixture-token', host: 'github.com' }),
+ signal: controller.signal,
+ }).catch((error: unknown) => error);
+ await fixture.ready;
+ expect(observer.children).toHaveLength(1);
+ await server.instance.destroy();
+ expect(observer.runningPids()).toEqual([]);
+ } finally {
+ controller.abort();
+ await fixture.release();
+ await Promise.all(observer.children.map(({ closed }) => closed));
+ await response;
+ await server?.cleanup();
+ observer.stop();
+ }
+});
diff --git a/packages/app/tests/integration/local-op-auth-shutdown.test.ts b/packages/app/tests/integration/local-op-auth-shutdown.test.ts
new file mode 100644
index 000000000..f41b95f77
--- /dev/null
+++ b/packages/app/tests/integration/local-op-auth-shutdown.test.ts
@@ -0,0 +1,107 @@
+import { constants, copyFileSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { describe, expect, test, vi } from 'vitest';
+import { createControlledAuthCli, observeChildren } from './auth-child-lifecycle.test-helper';
+import { createTestServer, type TestServer } from './test-harness';
+
+async function openLogin(
+ server: TestServer,
+ channel: string,
+ controller: AbortController,
+ expectedStatus = 200,
+) {
+ const response = await fetch(`${server.baseUrl}/api/local-op/auth/${channel}`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ signal: controller.signal,
+ });
+ expect(response.status).toBe(expectedStatus);
+ if (expectedStatus !== 200) {
+ await response.text();
+ return;
+ }
+ if (!response.body) throw new Error('Missing auth stream');
+ const reader = response.body.getReader();
+ const decoder = new TextDecoder();
+ let buffered = '';
+ try {
+ for (;;) {
+ const { value, done } = await reader.read();
+ if (done) throw new Error('Auth stream ended before verification');
+ buffered += decoder.decode(value, { stream: true });
+ const lines = buffered.split('\n');
+ buffered = lines.pop() ?? '';
+ for (const line of lines.filter(Boolean)) {
+ if (JSON.parse(line).type === 'verification') return;
+ }
+ }
+ } finally {
+ reader.releaseLock();
+ }
+}
+
+describe.each(['login', 'gh-login'])('auth shutdown: %s', (channel) => {
+ test.each(['active', 'detached', 'cancelled', 'displaced', 'failed test', 'shutdown admission'])(
+ 'server destruction reaps every owned child after %s',
+ async (scenario) => {
+ const fixture = await createControlledAuthCli();
+ const binDir = mkdtempSync(join(tmpdir(), 'ok-auth-bin-'));
+ copyFileSync(
+ process.execPath,
+ join(binDir, process.platform === 'win32' ? 'gh.exe' : 'gh'),
+ constants.COPYFILE_FICLONE,
+ );
+ vi.stubEnv('PATH', `${binDir}${delimiter}${process.env.PATH ?? ''}`);
+ const observer = observeChildren(channel === 'login' ? fixture.cliArgs : ['gh', 'auth']);
+ const controllers: AbortController[] = [];
+ let server: TestServer | undefined;
+ const forcedFailure = new Error('controlled test failure');
+ let caught: unknown;
+ try {
+ server = await createTestServer({ localOpCliArgs: fixture.cliArgs });
+ writeFileSync(join(server.contentDir, 'auth'), fixture.script);
+ try {
+ const first = new AbortController();
+ controllers.push(first);
+ if (scenario === 'shutdown admission') await server.instance.destroy();
+ await openLogin(server, channel, first, scenario === 'shutdown admission' ? 503 : 200);
+ expect(observer.children).toHaveLength(scenario === 'shutdown admission' ? 0 : 1);
+ if (scenario === 'detached') first.abort();
+ if (scenario === 'cancelled') {
+ const response = await fetch(`${server.baseUrl}/api/local-op/auth/cancel`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ channel }),
+ });
+ expect(response.status).toBe(200);
+ await response.text();
+ }
+ if (scenario === 'displaced') {
+ const second = new AbortController();
+ controllers.push(second);
+ await openLogin(server, channel, second);
+ expect(observer.children).toHaveLength(2);
+ }
+ if (scenario === 'failed test') throw forcedFailure;
+ } catch (error) {
+ if (error !== forcedFailure) throw error;
+ caught = error;
+ } finally {
+ await server.instance.destroy();
+ }
+ expect(caught).toBe(scenario === 'failed test' ? forcedFailure : undefined);
+ expect(observer.runningPids()).toEqual([]);
+ } finally {
+ for (const controller of controllers) controller.abort();
+ await fixture.release();
+ await Promise.all(observer.children.map(({ closed }) => closed));
+ await server?.cleanup();
+ observer.stop();
+ vi.unstubAllEnvs();
+ rmSync(binDir, { recursive: true, force: true });
+ }
+ },
+ );
+});
diff --git a/packages/app/tests/integration/local-op-subprocess-shutdown.test.ts b/packages/app/tests/integration/local-op-subprocess-shutdown.test.ts
new file mode 100644
index 000000000..1ed45602b
--- /dev/null
+++ b/packages/app/tests/integration/local-op-subprocess-shutdown.test.ts
@@ -0,0 +1,79 @@
+import { expect, test } from 'vitest';
+import { createControlledAuthCli, observeChildren } from './auth-child-lifecycle.test-helper';
+import { createTestServer, type TestServer } from './test-harness';
+
+test.each(['status', 'repos', 'signout'])(
+ 'server destruction ends its pending auth %s subprocess',
+ async (operation) => {
+ const fixture = await createControlledAuthCli();
+ const observer = observeChildren(fixture.cliArgs);
+ const controller = new AbortController();
+ let server: TestServer | undefined;
+ let request: Promise<unknown> | undefined;
+ try {
+ server = await createTestServer({ localOpCliArgs: fixture.cliArgs });
+ request = fetch(`${server.baseUrl}/api/local-op/auth/${operation}`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ host: 'github.com' }),
+ signal: controller.signal,
+ })
+ .then((response) => response.text())
+ .catch((error: unknown) => error);
+ await fixture.ready;
+ expect(observer.children).toHaveLength(1);
+ await server.instance.destroy();
+ expect(observer.runningPids()).toEqual([]);
+ } finally {
+ controller.abort();
+ await fixture.release();
+ await Promise.all(observer.children.map(({ closed }) => closed));
+ await request;
+ await server?.cleanup();
+ observer.stop();
+ }
+ },
+);
+
+test.each(['pat', 'status', 'repos', 'signout'])(
+ 'a pending auth %s request after server destruction starts no subprocess',
+ async (operation) => {
+ const fixture = await createControlledAuthCli();
+ const observer = observeChildren(fixture.cliArgs);
+ const controller = new AbortController();
+ let server: TestServer | undefined;
+ let request: Promise<{ kind: 'response'; status: number }> | undefined;
+ try {
+ server = await createTestServer({ localOpCliArgs: fixture.cliArgs });
+ await server.instance.destroy();
+ request = fetch(`${server.baseUrl}/api/local-op/auth/${operation}`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ host: 'github.com',
+ ...(operation === 'pat' ? { token: 'fixture-token' } : {}),
+ }),
+ signal: controller.signal,
+ })
+ .then(async (response) => {
+ await response.text();
+ return { kind: 'response' as const, status: response.status };
+ })
+ .catch(() => ({ kind: 'response' as const, status: 0 }));
+ const first = await Promise.race([
+ request,
+ fixture.ready.then(() => ({ kind: 'child' as const })),
+ ]);
+ expect(first.kind).toBe('response');
+ if (first.kind === 'response') expect(first.status).toBe(503);
+ expect(observer.children).toHaveLength(0);
+ } finally {
+ controller.abort();
+ await fixture.release();
+ await Promise.all(observer.children.map(({ closed }) => closed));
+ await request;
+ await server?.cleanup();
+ observer.stop();
+ }
+ },
+);
diff --git a/packages/app/tests/integration/producer-guard-wiring.test.ts b/packages/app/tests/integration/producer-guard-wiring.test.ts
index 878d5196b..867598d34 100644
--- a/packages/app/tests/integration/producer-guard-wiring.test.ts
+++ b/packages/app/tests/integration/producer-guard-wiring.test.ts
@@ -1,4 +1,3 @@
-
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 4ada3cf26..0970ac12f 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,4 +1,3 @@
-
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 cbe2b705f..b632185e1 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,4 +1,3 @@
-
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 89bc9b4d9..c530ce4ba 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,4 +1,3 @@
-
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 a78aeb0e4..d3767adc9 100644
--- a/packages/app/tests/integration/undo-after-rollback.test.ts
+++ b/packages/app/tests/integration/undo-after-rollback.test.ts
@@ -1,4 +1,3 @@
-
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 e7cc69c3f..b076f955c 100644
--- a/packages/app/tests/integration/undo-recycle-reset.test.ts
+++ b/packages/app/tests/integration/undo-recycle-reset.test.ts
@@ -1,4 +1,3 @@
-
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 9ddcd0730..7935e35f8 100644
--- a/packages/app/tests/integration/undo-rederive-survival.test.ts
+++ b/packages/app/tests/integration/undo-rederive-survival.test.ts
@@ -1,4 +1,3 @@
-
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/src/auth/token-store.test.ts b/packages/cli/src/auth/token-store.test.ts
index 72f2db491..68aa70201 100644
--- a/packages/cli/src/auth/token-store.test.ts
+++ b/packages/cli/src/auth/token-store.test.ts
@@ -1,8 +1,64 @@
-import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { chmodSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+const fsSeam = vi.hoisted(() => ({
+ stopMessage: 'process stopped partway through a file write',
+ keepBytes: null as null | ((byteLength: number) => number),
+ stopped: false,
+ writes: null as null | Array<{ path: string; mode: number; text: string }>,
+}));
+
+vi.mock('node:fs', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('node:fs')>();
+ const stoppedMutators = Object.fromEntries(
+ (
+ [
+ 'appendFileSync',
+ 'chmodSync',
+ 'copyFileSync',
+ 'renameSync',
+ 'rmSync',
+ 'truncateSync',
+ 'unlinkSync',
+ 'writeSync',
+ ] as const
+ ).map((name) => [
+ name,
+ (...args: unknown[]) => {
+ if (fsSeam.stopped) throw new Error(fsSeam.stopMessage);
+ return (actual[name] as (...forwarded: unknown[]) => unknown)(...args);
+ },
+ ]),
+ );
+ const writeFileSync: typeof actual.writeFileSync = (file, data, options) => {
+ if (fsSeam.stopped) throw new Error(fsSeam.stopMessage);
+ const keepBytes = fsSeam.keepBytes;
+ if (keepBytes !== null) {
+ fsSeam.keepBytes = null;
+ const bytes =
+ typeof data === 'string'
+ ? Buffer.from(data, 'utf-8')
+ : Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+ actual.writeFileSync(file, bytes.subarray(0, keepBytes(bytes.byteLength)), options);
+ fsSeam.stopped = true;
+ throw new Error(fsSeam.stopMessage);
+ }
+ actual.writeFileSync(file, data, options);
+ if (fsSeam.writes !== null && typeof file === 'string') {
+ fsSeam.writes.push({
+ path: file,
+ mode: actual.statSync(file).mode & 0o777,
+ text: actual.readFileSync(file, 'utf-8'),
+ });
+ }
+ };
+ return { ...actual, ...stoppedMutators, writeFileSync };
+});
+
+type RecordedWrite = NonNullable<typeof fsSeam.writes>[number];
+
interface KeyringCall {
service: string;
account: string;
@@ -180,6 +236,105 @@ describe('FileBackend', () => {
});
});
+const SEEDED_AUTH_YML = [
+ 'github.com:',
+ ' login: alice',
+ ' token: gho_alice',
+ 'gitlab.com:',
+ ' login: bob',
+ ' token: glpat_bob',
+ '',
+].join('\n');
+
+const SEEDED_ENTRIES = {
+ 'github.com': { login: 'alice', token: 'gho_alice' },
+ 'gitlab.com': { login: 'bob', token: 'glpat_bob' },
+};
+
+const CREDENTIAL_TOKENS = ['gho_alice', 'glpat_bob', 'cb_carol'];
+
+const authFileWrites = [
+ {
+ operation: 'set()',
+ run: (store: FileBackend) => store.set('codeberg.org', 'carol', 'cb_carol'),
+ },
+ { operation: 'clear()', run: (store: FileBackend) => store.clear('github.com') },
+];
+
+const stopPoints = [
+ { at: 'before its first byte', keepBytes: () => 0 },
+ { at: 'halfway through', keepBytes: (byteLength: number) => Math.floor(byteLength / 2) },
+ { at: 'one byte before the end', keepBytes: (byteLength: number) => byteLength - 1 },
+];
+
+describe.each(authFileWrites)('FileBackend $operation auth.yml write', ({ run }) => {
+ let tmpDir: string;
+ let authFile: string;
+
+ beforeEach(() => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'ok-token-store-write-'));
+ authFile = join(tmpDir, 'auth.yml');
+ writeFileSync(authFile, SEEDED_AUTH_YML, { mode: 0o600 });
+ });
+
+ afterEach(() => {
+ fsSeam.keepBytes = null;
+ fsSeam.stopped = false;
+ fsSeam.writes = null;
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ test.each(stopPoints)(
+ 'stopped $at leaves every previous entry readable and the file bytes unchanged',
+ async ({ keepBytes }) => {
+ fsSeam.keepBytes = keepBytes;
+ await expect(run(new FileBackend(authFile))).rejects.toThrow(fsSeam.stopMessage);
+
+ const reopened = new FileBackend(authFile);
+ expect({
+ 'github.com': await reopened.get('github.com'),
+ 'gitlab.com': await reopened.get('gitlab.com'),
+ }).toEqual(SEEDED_ENTRIES);
+ expect(readFileSync(authFile, 'utf-8')).toBe(SEEDED_AUTH_YML);
+ },
+ );
+
+ test.skipIf(process.platform === 'win32')(
+ 'leaves a group-readable auth.yml holding credentials at mode 0600',
+ async () => {
+ chmodSync(authFile, 0o644);
+
+ await run(new FileBackend(authFile));
+
+ expect(await new FileBackend(authFile).get('gitlab.com')).toEqual(
+ SEEDED_ENTRIES['gitlab.com'],
+ );
+ expect((statSync(authFile).mode & 0o777).toString(8)).toBe('600');
+ },
+ );
+
+ test.skipIf(process.platform === 'win32')(
+ 'puts credential bytes only into files without group or other permission bits',
+ async () => {
+ chmodSync(authFile, 0o644);
+ const writes: RecordedWrite[] = [];
+ fsSeam.writes = writes;
+
+ await run(new FileBackend(authFile));
+
+ const holdingCredentials = writes.filter((write) =>
+ CREDENTIAL_TOKENS.some((token) => write.text.includes(token)),
+ );
+ expect(holdingCredentials.length).toBeGreaterThan(0);
+ expect(
+ holdingCredentials
+ .filter((write) => (write.mode & 0o077) !== 0)
+ .map((write) => `${basename(write.path)} mode ${write.mode.toString(8)}`),
+ ).toEqual([]);
+ },
+ );
+});
+
describe('createTokenStore', () => {
beforeEach(resetKeyringMockState);
diff --git a/packages/cli/src/auth/token-store.ts b/packages/cli/src/auth/token-store.ts
index c14e31849..00257f7cc 100644
--- a/packages/cli/src/auth/token-store.ts
+++ b/packages/cli/src/auth/token-store.ts
@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
import { homedir } from 'node:os';
import { dirname, join } from 'node:path';
+import { atomicWriteFileSync } from '@inkeep/open-knowledge-core/server';
import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
interface TokenEntry {
@@ -126,7 +127,7 @@ export class FileBackend implements TokenStore {
private write(data: Record<string, TokenEntry>): void {
const dir = dirname(this.authFile);
if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
- writeFileSync(this.authFile, yamlStringify(data), { mode: 0o600 });
+ atomicWriteFileSync(this.authFile, yamlStringify(data), { mode: 0o600 });
}
async get(host: string): Promise<TokenEntry | null> {
diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.ts
index 2a597ec3d..f4cc8a286 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,4 +1,3 @@
-
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 01ef76a9f..8fb428b90 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,4 +1,3 @@
-
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 fb0ba5a7c..fc267cbea 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,4 +1,3 @@
-
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 fa3cfcd86..bfd7e3109 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,4 +1,3 @@
-
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 8be632ba4..4d3250d3a 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,4 +1,3 @@
-
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index fb6e0aa2b..870e2c456 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -1410,9 +1410,11 @@ export function respondPersistenceFailure(
);
}
-export function createApiExtension(
- options: ApiExtensionOptions,
-): Extension & { nativeApi: NativeApiHandle; localApi: LocalApiDispatch } {
+export function createApiExtension(options: ApiExtensionOptions): Extension & {
+ nativeApi: NativeApiHandle;
+ localApi: LocalApiDispatch;
+ shutdownLocalOps(): Promise<void>;
+} {
const { durabilityState } = options;
const ingressPolicy = options.ingressPolicy ?? buildIngressPolicy({});
const checkLocalOpSecurity = (
@@ -5293,5 +5295,6 @@ export function createApiExtension(
},
nativeApi,
localApi,
+ shutdownLocalOps: localOpRoutes.shutdown,
};
}
diff --git a/packages/server/src/http/local-op-auth-shutdown-errors.test.ts b/packages/server/src/http/local-op-auth-shutdown-errors.test.ts
new file mode 100644
index 000000000..5c8d94efa
--- /dev/null
+++ b/packages/server/src/http/local-op-auth-shutdown-errors.test.ts
@@ -0,0 +1,380 @@
+import { ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { createServer } from 'node:http';
+import { constants } from 'node:os';
+import { PassThrough } from 'node:stream';
+import { afterEach, expect, test, vi } from 'vitest';
+import { createConcurrencyGuard } from '../local-op-security.ts';
+import { loggerFactory } from '../logger.ts';
+import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';
+import { useIsolatedHome } from '../share/git-host-declarations.test-helper.ts';
+import type { SyncEngine } from '../sync-engine.ts';
+import { createLocalOpRoutes } from './local-op-routes.ts';
+
+const { spawn } = vi.hoisted(() => ({ spawn: vi.fn() }));
+vi.mock('node:child_process', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('node:child_process')>()),
+ spawn,
+}));
+
+class RecordedChild extends EventEmitter {
+ pid = 42;
+ exitCode: number | null = null;
+ signalCode: NodeJS.Signals | null = null;
+ killed = false;
+ stdin = new PassThrough();
+ stdout = new PassThrough();
+ stderr = new PassThrough();
+ signals: number[] = [];
+ refuseCancellation = true;
+ refuseTermination = false;
+ _handle = {
+ kill: (signal: number): number => {
+ this.signals.push(signal);
+ return (signal === constants.signals.SIGTERM && this.refuseCancellation) ||
+ (signal === constants.signals.SIGKILL && this.refuseTermination)
+ ? -constants.errno.EPERM
+ : 0;
+ },
+ };
+ kill = ChildProcess.prototype.kill;
+
+ close(): void {
+ if (this.exitCode !== null) return;
+ this.exitCode = 0;
+ this.emit('close', 0, null);
+ }
+}
+
+function guardNativeSpawn(): void {
+ vi.spyOn(ChildProcess.prototype, 'spawn').mockImplementation(() => {
+ throw new Error('This recording-only test must not spawn a real process');
+ });
+}
+
+async function createRecordingServer(getSyncEngine?: () => SyncEngine | null) {
+ const group = createLocalOpRoutes({
+ projectDir: undefined,
+ contentDir: home(),
+ log: loggerFactory.getLogger('test'),
+ checkLocalOpSecurity: () => true,
+ localOpCliArgs: ['recorded-auth-cli'],
+ localOpGuard: createConcurrencyGuard(),
+ getSyncEngine,
+ authStreamHeartbeatMs: undefined,
+ embeddingsSecretsFile: undefined,
+ readSemanticProviderConfig: undefined,
+ semanticSearch: undefined,
+ });
+ const server = createServer((req, res) => {
+ const dispatch = group.table.resolve(req.url ?? '/')?.dispatch;
+ if (!dispatch) {
+ res.writeHead(404).end();
+ return;
+ }
+ void dispatch(req, res);
+ });
+ const { baseUrl } = await listenOnLoopback(server);
+ return {
+ group,
+ baseUrl,
+ async close(): Promise<void> {
+ server.closeAllConnections();
+ await new Promise<void>((resolve) => server.close(() => resolve()));
+ },
+ };
+}
+
+async function drainPriorEvents(baseUrl: string): Promise<void> {
+ const barrier = await fetch(`${baseUrl}/test-event-loop-barrier`);
+ await barrier.text();
+}
+
+const verification = {
+ type: 'verification',
+ user_code: 'WDJB-MJHT',
+ verification_uri: 'https://github.com/login/device',
+ expires_in: 900,
+};
+
+function postAuth(baseUrl: string, route: 'login' | 'pat', body: object): Promise<Response> {
+ return fetch(`${baseUrl}/api/local-op/auth/${route}`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(body),
+ });
+}
+
+const home = useIsolatedHome();
+afterEach(() => {
+ spawn.mockReset();
+ vi.restoreAllMocks();
+});
+
+test('shutdown retains a live auth child after cancellation cannot deliver its signal', async () => {
+ guardNativeSpawn();
+ const child = new RecordedChild();
+ spawn.mockImplementation(() => {
+ queueMicrotask(() => child.stdout.write(`${JSON.stringify(verification)}\n`));
+ return child;
+ });
+ const fixture = await createRecordingServer();
+ let shutdown: Promise<void> | undefined;
+ try {
+ const login = await postAuth(fixture.baseUrl, 'login', {});
+ expect(login.status).toBe(200);
+ const cancel = await fetch(`${fixture.baseUrl}/api/local-op/auth/cancel`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ });
+ expect(cancel.status).toBe(200);
+ await cancel.text();
+ expect(await login.text()).toContain('verification');
+ expect(child.exitCode).toBeNull();
+ expect(child.signals).toEqual([constants.signals.SIGTERM]);
+ let destroyed = false;
+ shutdown = fixture.group.shutdown().then(() => {
+ destroyed = true;
+ });
+ expect(child.signals).toEqual([constants.signals.SIGTERM, constants.signals.SIGKILL]);
+ await drainPriorEvents(fixture.baseUrl);
+ expect(destroyed).toBe(false);
+ child.close();
+ await shutdown;
+ expect(destroyed).toBe(true);
+ } finally {
+ child.close();
+ await shutdown;
+ await fixture.close();
+ }
+});
+
+test('shutdown waits for close when the native signal reports an already-dead child', async () => {
+ guardNativeSpawn();
+ const child = new RecordedChild();
+ child._handle.kill = (signal: number) => {
+ child.signals.push(signal);
+ return -constants.errno.ESRCH;
+ };
+ spawn.mockImplementation(() => {
+ queueMicrotask(() => child.stdout.write(`${JSON.stringify(verification)}\n`));
+ return child;
+ });
+ const fixture = await createRecordingServer();
+ let shutdown: Promise<unknown> | undefined;
+ try {
+ const login = await postAuth(fixture.baseUrl, 'login', {});
+ expect(login.status).toBe(200);
+ let settled = false;
+ shutdown = fixture.group.shutdown().then(
+ () => {
+ settled = true;
+ return null;
+ },
+ (error: unknown) => {
+ settled = true;
+ return error;
+ },
+ );
+ await drainPriorEvents(fixture.baseUrl);
+ expect(child.signals).toEqual([constants.signals.SIGKILL]);
+ expect(settled).toBe(false);
+ child.close();
+ expect(await shutdown).toBeNull();
+ expect(settled).toBe(true);
+ } finally {
+ child.close();
+ await shutdown;
+ await fixture.close();
+ }
+});
+
+test('shutdown drains another auth child when one termination is refused', async () => {
+ guardNativeSpawn();
+ const refused = new RecordedChild();
+ refused.refuseCancellation = false;
+ refused.refuseTermination = true;
+ const draining = new RecordedChild();
+ const children = [refused, draining];
+ spawn.mockImplementation(() => {
+ const child = children.shift();
+ if (!child) throw new Error('Unexpected auth child');
+ queueMicrotask(() => child.stdout.write(`${JSON.stringify(verification)}\n`));
+ return child;
+ });
+ const fixture = await createRecordingServer();
+ let shutdown: Promise<unknown> | undefined;
+ try {
+ const first = await postAuth(fixture.baseUrl, 'login', {});
+ expect(first.status).toBe(200);
+ const second = await postAuth(fixture.baseUrl, 'login', {});
+ expect(second.status).toBe(200);
+ expect(spawn).toHaveBeenCalledTimes(2);
+ let settled = false;
+ shutdown = fixture.group.shutdown().then(
+ () => {
+ settled = true;
+ return null;
+ },
+ (error: unknown) => {
+ settled = true;
+ return error;
+ },
+ );
+ await drainPriorEvents(fixture.baseUrl);
+ expect(refused.signals).toContain(constants.signals.SIGKILL);
+ expect(draining.signals).toContain(constants.signals.SIGKILL);
+ expect(refused.exitCode).toBeNull();
+ expect(draining.exitCode).toBeNull();
+ expect(settled).toBe(false);
+ draining.close();
+ expect(await shutdown).toBeInstanceOf(AggregateError);
+ expect(await fixture.group.shutdown().catch((error: unknown) => error)).toBeInstanceOf(
+ AggregateError,
+ );
+ expect(spawn).toHaveBeenCalledTimes(2);
+ } finally {
+ refused.close();
+ draining.close();
+ await shutdown;
+ await fixture.close();
+ }
+});
+
+test('shutdown suppresses a buffered device-code completion and sync resume', async () => {
+ guardNativeSpawn();
+ const child = new RecordedChild();
+ spawn.mockImplementation(() => {
+ queueMicrotask(() => child.stdout.write(`${JSON.stringify(verification)}\n`));
+ return child;
+ });
+ const notifyCredentialsChanged = vi.fn(async () => {});
+ const refreshPushPermission = vi.fn(async () => null);
+ const engine = { notifyCredentialsChanged, refreshPushPermission } as unknown as SyncEngine;
+ const fixture = await createRecordingServer(() => engine);
+ let shutdown: Promise<void> | undefined;
+ try {
+ const login = await postAuth(fixture.baseUrl, 'login', {});
+ expect(login.status).toBe(200);
+ expect(spawn).toHaveBeenCalledTimes(1);
+ shutdown = fixture.group.shutdown();
+ child.stdout.write(
+ `${JSON.stringify({ type: 'complete', host: 'github.com', login: 'octocat' })}\n`,
+ );
+ await drainPriorEvents(fixture.baseUrl);
+ expect(child.exitCode).toBeNull();
+ const resumedBeforeClose = notifyCredentialsChanged.mock.calls.length;
+ const refreshedBeforeClose = refreshPushPermission.mock.calls.length;
+ child.close();
+ await shutdown;
+ const events = (await login.text())
+ .trim()
+ .split('\n')
+ .map((line) => JSON.parse(line));
+ expect(events).toContainEqual(verification);
+ expect.soft(events).not.toContainEqual(expect.objectContaining({ type: 'complete' }));
+ expect.soft(resumedBeforeClose).toBe(0);
+ expect.soft(refreshedBeforeClose).toBe(0);
+ } finally {
+ child.close();
+ await shutdown;
+ await fixture.close();
+ }
+});
+
+test('shutdown suppresses a late token completion and sync resume', async () => {
+ guardNativeSpawn();
+ const child = new RecordedChild();
+ const spawned = Promise.withResolvers<void>();
+ spawn.mockImplementation(() => {
+ spawned.resolve();
+ return child;
+ });
+ const notifyCredentialsChanged = vi.fn(async () => {});
+ const refreshPushPermission = vi.fn(async () => null);
+ const engine = { notifyCredentialsChanged, refreshPushPermission } as unknown as SyncEngine;
+ const fixture = await createRecordingServer(() => engine);
+ let shutdown: Promise<void> | undefined;
+ let response: Promise<Response> | undefined;
+ try {
+ response = postAuth(fixture.baseUrl, 'pat', { token: 'fixture-token', host: 'github.com' });
+ await spawned.promise;
+ expect(spawn).toHaveBeenCalledTimes(1);
+ await drainPriorEvents(fixture.baseUrl);
+ let shutdownSettled = false;
+ shutdown = fixture.group.shutdown().then(() => {
+ shutdownSettled = true;
+ });
+ await drainPriorEvents(fixture.baseUrl);
+ const finishedBeforeChild = shutdownSettled;
+ child.stdout.write(
+ `${JSON.stringify({ type: 'complete', host: 'github.com', login: 'octocat' })}\n`,
+ );
+ child.close();
+ const result = await response;
+ await shutdown;
+ expect.soft(result.ok).toBe(false);
+ expect.soft(notifyCredentialsChanged).not.toHaveBeenCalled();
+ expect.soft(refreshPushPermission).not.toHaveBeenCalled();
+ expect.soft(finishedBeforeChild).toBe(false);
+ } finally {
+ child.close();
+ await shutdown;
+ await response;
+ await fixture.close();
+ }
+});
+
+test('shutdown settles after a synchronous repos launch failure', async () => {
+ guardNativeSpawn();
+ spawn.mockImplementation(() => {
+ throw new Error('recorded launch failure');
+ });
+ const group = createLocalOpRoutes({
+ projectDir: undefined,
+ contentDir: home(),
+ log: loggerFactory.getLogger('test'),
+ checkLocalOpSecurity: () => true,
+ localOpCliArgs: ['recorded-auth-cli'],
+ localOpGuard: createConcurrencyGuard(),
+ getSyncEngine: undefined,
+ authStreamHeartbeatMs: undefined,
+ embeddingsSecretsFile: undefined,
+ readSemanticProviderConfig: undefined,
+ semanticSearch: undefined,
+ });
+ const failed = Promise.withResolvers<unknown>();
+ const server = createServer((req, res) => {
+ const dispatch = group.table.resolve(req.url ?? '/')?.dispatch;
+ if (!dispatch) {
+ res.writeHead(404).end();
+ return;
+ }
+ void dispatch(req, res).catch((error) => {
+ failed.resolve(error);
+ res.destroy();
+ });
+ });
+ try {
+ const { baseUrl } = await listenOnLoopback(server);
+ const request = fetch(`${baseUrl}/api/local-op/auth/repos`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ }).catch(() => undefined);
+ expect(await failed.promise).toMatchObject({ message: 'recorded launch failure' });
+ expect(spawn).toHaveBeenCalledTimes(1);
+ let settled = false;
+ const shutdown = group.shutdown().then(() => {
+ settled = true;
+ });
+ await drainPriorEvents(baseUrl);
+ expect(settled).toBe(true);
+ await shutdown;
+ await request;
+ } finally {
+ server.closeAllConnections();
+ await new Promise<void>((resolve) => server.close(() => resolve()));
+ }
+});
diff --git a/packages/server/src/http/local-op-routes.test.ts b/packages/server/src/http/local-op-routes.test.ts
index f4f6f7070..19eb860b5 100644
--- a/packages/server/src/http/local-op-routes.test.ts
+++ b/packages/server/src/http/local-op-routes.test.ts
@@ -265,7 +265,8 @@ describe('auth-login stream displacement (a second start orphans the first clien
test('gh-login rejects an explicit undeclared host before looking up gh and accepts a declaration', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-gh-login-host-'));
- const probe = vi.spyOn(ghLogin, 'cachedGhBinaryPath').mockResolvedValue(null);
+ const probe = vi.fn(async () => null);
+ vi.spyOn(ghLogin, 'createGhBinaryPathResolver').mockReturnValue(probe);
try {
const baseUrl = await serveLocalOpGroup({ projectDir });
const rejected = await postJson(baseUrl, '/api/local-op/auth/gh-login', {
@@ -367,7 +368,7 @@ describe('auth-login stream displacement (a second start orphans the first clien
test('auth subprocesses run in the project directory instead of the server cwd', async () => {
const projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-auth-cwd-')));
- vi.spyOn(ghLogin, 'cachedGhBinaryPath').mockResolvedValue(null);
+ vi.spyOn(ghLogin, 'createGhBinaryPathResolver').mockReturnValue(async () => null);
try {
const localOpCliArgs = [
process.execPath,
diff --git a/packages/server/src/http/local-op-routes.ts b/packages/server/src/http/local-op-routes.ts
index 6879ff90c..a18921aa7 100644
--- a/packages/server/src/http/local-op-routes.ts
+++ b/packages/server/src/http/local-op-routes.ts
@@ -49,13 +49,14 @@ import {
} from '../local-op-security.ts';
import {
type AuthEvent,
- cachedGhBinaryPath,
classifyCloneError,
+ createGhBinaryPathResolver,
runCloneSubprocess,
runDeviceFlowSubprocess,
runGhDeviceLoginSubprocess,
runPatSubprocess,
} from '../local-ops/index.ts';
+import { LocalOpSubprocessLifetime } from '../local-ops/subprocess-lifetime.ts';
import type { PinoLogger } from '../logger.ts';
import { readDeclaredGitHubHosts, resolveGitHubAuthHost } from '../share/git-context.ts';
import { redactShareSubprocessStderr } from '../share/publish.ts';
@@ -101,7 +102,9 @@ export interface LocalOpRouteDeps {
semanticSearch: SemanticSearchService | undefined;
}
-export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
+export function createLocalOpRoutes(
+ deps: LocalOpRouteDeps,
+): ApiRouteGroup & { shutdown(): Promise<void> } {
const {
projectDir,
contentDir,
@@ -115,6 +118,8 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
readSemanticProviderConfig,
semanticSearch,
} = deps;
+ const subprocessLifetime = new LocalOpSubprocessLifetime();
+ const resolveGhBinaryPath = createGhBinaryPathResolver(subprocessLifetime);
const LOCAL_OP_CLONE_KEY = '/api/local-op/clone';
const LOCAL_OP_OK_INIT_KEY = '/api/local-op/ok-init';
@@ -528,6 +533,19 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
const authLoginInFlight: { current: InFlightAuthStream | null } = { current: null };
const authGhLoginInFlight: { current: InFlightAuthStream | null } = { current: null };
+ function shutdown(): Promise<void> {
+ return subprocessLifetime.shutdown();
+ }
+
+ function rejectShuttingDown(res: ServerResponse, handler: string, err?: unknown): boolean {
+ if (!subprocessLifetime.stopped) return false;
+ if (err !== undefined) log.debug({ err, handler }, '[local-op] error after server shutdown');
+ errorResponse(res, 503, 'urn:ok:error:auth-failed', 'The server is shutting down.', {
+ handler,
+ });
+ return true;
+ }
+
const DISPLACED_STREAM_MESSAGE = 'Sign-in was replaced by a newer sign-in attempt.';
function streamAuthFlow(cfg: {
@@ -542,6 +560,8 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
const { res, handler, guardKey, inFlight, concurrentMessage, streamErrorMessage, makeFlow } =
cfg;
+ if (rejectShuttingDown(res, handler)) return;
+
if (!localOpGuard.tryAcquire(guardKey)) {
const stale = inFlight.current;
if (!stale) {
@@ -598,6 +618,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
};
const flow = makeFlow((event: AuthEvent) => {
+ if (subprocessLifetime.stopped) return;
if (event.type === 'error') {
writeStreamError(500, 'urn:ok:error:auth-failed', streamErrorMessage, {
cause: event.message ? new Error(event.message) : undefined,
@@ -633,7 +654,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
};
res.on('close', onClientClose);
- void flow.done.finally(() => {
+ const finish = () => {
stopHeartbeat();
res.off('close', onClientClose);
if (!res.writableEnded && !res.destroyed) {
@@ -645,7 +666,8 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
inFlight.current = null;
localOpGuard.release(guardKey);
}
- });
+ };
+ subprocessLifetime.track(flow.done.then(finish, finish));
}
const HANDLE_LOCAL_OP_AUTH_LOGIN = 'local-op-auth-login';
@@ -664,6 +686,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
res: ServerResponse,
body: LocalOpAuthHostRequest,
): Promise<void> {
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_LOGIN)) return;
const host = resolveAuthHost(res, HANDLE_LOCAL_OP_AUTH_LOGIN, body.host);
if (host === null) return;
streamAuthFlow({
@@ -675,6 +698,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
streamErrorMessage: 'Auth subprocess reported an error.',
makeFlow: (onEvent) =>
runDeviceFlowSubprocess({
+ lifetime: subprocessLifetime,
cliArgs: localOpCliArgs,
cwd: authProjectDir,
host,
@@ -688,36 +712,44 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
const handleLocalOpAuthGhLogin = withValidation(
LocalOpAuthHostRequestSchema,
async (_req, res, body) => {
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_GH_LOGIN)) return;
const host = resolveAuthHost(res, HANDLE_LOCAL_OP_AUTH_GH_LOGIN, body.host);
if (host === null) return;
- const ghPath = await cachedGhBinaryPath();
- if (ghPath === null) {
- errorResponse(
+ const finish = subprocessLifetime.begin();
+ try {
+ const ghPath = await resolveGhBinaryPath();
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_GH_LOGIN)) return;
+ if (ghPath === null) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:auth-failed',
+ 'The GitHub CLI (gh) is not installed.',
+ { handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN },
+ );
+ return;
+ }
+
+ streamAuthFlow({
res,
- 400,
- 'urn:ok:error:auth-failed',
- 'The GitHub CLI (gh) is not installed.',
- { handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN },
- );
- return;
+ handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN,
+ guardKey: LOCAL_OP_AUTH_GH_LOGIN_KEY,
+ inFlight: authGhLoginInFlight,
+ concurrentMessage: 'A gh sign-in is already in progress.',
+ streamErrorMessage: 'gh sign-in reported an error.',
+ makeFlow: (onEvent) =>
+ runGhDeviceLoginSubprocess({
+ lifetime: subprocessLifetime,
+ host,
+ ghPath,
+ cwd: authProjectDir,
+ timeoutMs: AUTH_DEVICE_FLOW_TIMEOUT_MS,
+ onEvent,
+ }),
+ });
+ } finally {
+ finish();
}
-
- streamAuthFlow({
- res,
- handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN,
- guardKey: LOCAL_OP_AUTH_GH_LOGIN_KEY,
- inFlight: authGhLoginInFlight,
- concurrentMessage: 'A gh sign-in is already in progress.',
- streamErrorMessage: 'gh sign-in reported an error.',
- makeFlow: (onEvent) =>
- runGhDeviceLoginSubprocess({
- host,
- ghPath,
- cwd: authProjectDir,
- timeoutMs: AUTH_DEVICE_FLOW_TIMEOUT_MS,
- onEvent,
- }),
- });
},
{
handler: HANDLE_LOCAL_OP_AUTH_GH_LOGIN,
@@ -764,6 +796,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
const handleLocalOpAuthStatus = withValidation(
LocalOpAuthHostRequestSchema,
async (_req, res, body) => {
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_STATUS)) return;
const host = resolveAuthHost(res, HANDLE_LOCAL_OP_AUTH_STATUS, body.host);
if (host === null) return;
@@ -778,19 +811,22 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
return;
}
+ const finish = subprocessLifetime.begin();
try {
const [cmd, ...baseArgs] = localOpCliArgs;
const spawnArgs = [...baseArgs, 'auth', 'status', '--json', '--host', host];
const output = await new Promise<string>((resolve, reject) => {
- const child = spawn(
- cmd,
- spawnArgs,
- withHiddenWindowsConsole({
- ...LOCAL_OP_PIPE_STDIO_OPTIONS,
- env: { ...process.env },
- cwd: authProjectDir,
- }),
+ const child = subprocessLifetime.spawn(() =>
+ spawn(
+ cmd,
+ spawnArgs,
+ withHiddenWindowsConsole({
+ ...LOCAL_OP_PIPE_STDIO_OPTIONS,
+ env: { ...process.env },
+ cwd: authProjectDir,
+ }),
+ ),
);
let settled = false;
const killTimer = setTimeout(() => {
@@ -835,7 +871,9 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
break;
} catch {}
}
- const ghAvailable = (await cachedGhBinaryPath()) !== null;
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_STATUS)) return;
+ const ghAvailable = (await resolveGhBinaryPath()) !== null;
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_STATUS)) return;
if (parsed !== null) {
successResponse(
res,
@@ -854,12 +892,14 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
);
}
} catch (err) {
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_STATUS, err)) return;
errorResponse(res, 500, 'urn:ok:error:auth-failed', 'Auth status check failed.', {
handler: HANDLE_LOCAL_OP_AUTH_STATUS,
cause: err,
});
} finally {
localOpGuard.release(LOCAL_OP_AUTH_STATUS_KEY);
+ finish();
}
},
{
@@ -874,6 +914,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
const handleLocalOpAuthPat = withValidation(
LocalOpAuthPatRequestSchema,
async (_req, res, body) => {
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_PAT)) return;
const host = resolveAuthHost(res, HANDLE_LOCAL_OP_AUTH_PAT, body.host);
if (host === null) return;
@@ -888,13 +929,16 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
return;
}
+ const finish = subprocessLifetime.begin();
try {
const result = await runPatSubprocess({
+ lifetime: subprocessLifetime,
cliArgs: localOpCliArgs,
cwd: authProjectDir,
host,
token: body.token,
});
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_PAT)) return;
if (result.ok) {
onAuthCredentialLanded(getSyncEngine);
successResponse(
@@ -910,12 +954,14 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
});
}
} catch (err) {
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_PAT, err)) return;
errorResponse(res, 500, 'urn:ok:error:auth-failed', 'Storing the token failed.', {
handler: HANDLE_LOCAL_OP_AUTH_PAT,
cause: err,
});
} finally {
localOpGuard.release(LOCAL_OP_AUTH_PAT_KEY);
+ finish();
}
},
{
@@ -942,6 +988,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
res: ServerResponse,
body: LocalOpAuthHostRequest,
): Promise<void> {
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_REPOS)) return;
const host = resolveAuthHost(res, HANDLE_LOCAL_OP_AUTH_REPOS, body.host);
if (host === null) return;
@@ -970,15 +1017,26 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
let settled = false;
let stdoutBuffer = '';
- const child = spawn(
- cmd,
- spawnArgs,
- withHiddenWindowsConsole({
- ...LOCAL_OP_PIPE_STDIO_OPTIONS,
- env: { ...process.env },
- cwd: authProjectDir,
- }),
- );
+ const finish = subprocessLifetime.begin();
+ const child = (() => {
+ try {
+ return subprocessLifetime.spawn(() =>
+ spawn(
+ cmd,
+ spawnArgs,
+ withHiddenWindowsConsole({
+ ...LOCAL_OP_PIPE_STDIO_OPTIONS,
+ env: { ...process.env },
+ cwd: authProjectDir,
+ }),
+ ),
+ );
+ } catch (err) {
+ finish();
+ localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
+ throw err;
+ }
+ })();
const killTimer = setTimeout(() => {
if (settled) return;
@@ -1001,6 +1059,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
killTimer.unref?.();
child.stdout.on('data', (chunk: Buffer) => {
+ if (subprocessLifetime.stopped) return;
stdoutBuffer += chunk.toString('utf-8');
const lines = stdoutBuffer.split('\n');
stdoutBuffer = lines.pop() ?? '';
@@ -1033,6 +1092,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
});
child.on('close', (code) => {
+ finish();
clearTimeout(killTimer);
if (!settled) {
settled = true;
@@ -1069,7 +1129,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
if (!settled) {
settled = true;
clearTimeout(killTimer);
- child.kill('SIGTERM');
+ if (!subprocessLifetime.stopped) child.kill('SIGTERM');
localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
}
});
@@ -1079,6 +1139,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
const handleLocalOpAuthSignout = withValidation(
LocalOpAuthHostRequestSchema,
async (_req, res, body) => {
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_SIGNOUT)) return;
const host = body.host ?? resolveAuthHost(res, HANDLE_LOCAL_OP_AUTH_SIGNOUT, undefined);
if (host === null) return;
@@ -1093,19 +1154,22 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
return;
}
+ const finish = subprocessLifetime.begin();
try {
const [cmd, ...baseArgs] = localOpCliArgs;
const spawnArgs = [...baseArgs, 'auth', 'signout', '--host', host];
await new Promise<void>((resolve, reject) => {
- const child = spawn(
- cmd,
- spawnArgs,
- withHiddenWindowsConsole({
- ...LOCAL_OP_IGNORED_STDIO_OPTIONS,
- env: { ...process.env },
- cwd: authProjectDir,
- }),
+ const child = subprocessLifetime.spawn(() =>
+ spawn(
+ cmd,
+ spawnArgs,
+ withHiddenWindowsConsole({
+ ...LOCAL_OP_IGNORED_STDIO_OPTIONS,
+ env: { ...process.env },
+ cwd: authProjectDir,
+ }),
+ ),
);
let settled = false;
const killTimer = setTimeout(() => {
@@ -1135,6 +1199,7 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
});
});
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_SIGNOUT)) return;
successResponse(
res,
200,
@@ -1145,12 +1210,14 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
},
);
} catch (err) {
+ if (rejectShuttingDown(res, HANDLE_LOCAL_OP_AUTH_SIGNOUT, err)) return;
errorResponse(res, 500, 'urn:ok:error:auth-failed', 'Auth signout failed.', {
handler: HANDLE_LOCAL_OP_AUTH_SIGNOUT,
cause: err,
});
} finally {
localOpGuard.release(LOCAL_OP_AUTH_SIGNOUT_KEY);
+ finish();
}
},
{
@@ -1398,12 +1465,15 @@ export function createLocalOpRoutes(deps: LocalOpRouteDeps): ApiRouteGroup {
'/api/local-op/embeddings/test': handleLocalOpEmbeddingsTest,
} satisfies ApiRouteRecord;
- return createApiRouteGroup(routes, {
- mutatingPrefixes: ['/api/local-op/'],
- dynamic: {
- prefix: '/api/local-op/',
- template: '/api/local-op/:op',
- dispatch: () => undefined,
- },
- });
+ return {
+ ...createApiRouteGroup(routes, {
+ mutatingPrefixes: ['/api/local-op/'],
+ dynamic: {
+ prefix: '/api/local-op/',
+ template: '/api/local-op/:op',
+ dispatch: () => undefined,
+ },
+ }),
+ shutdown,
+ };
}
diff --git a/packages/server/src/local-ops/auth-flow.ts b/packages/server/src/local-ops/auth-flow.ts
index 0a8124c37..1494a6c4a 100644
--- a/packages/server/src/local-ops/auth-flow.ts
+++ b/packages/server/src/local-ops/auth-flow.ts
@@ -1,8 +1,10 @@
import { redactedStderrDetail, stderrDetailSuffix } from './clone-error-classify.ts';
import { type LocalOpCliInvocation, runSubprocess } from './subprocess.ts';
+import type { LocalOpSubprocessLifetime } from './subprocess-lifetime.ts';
import type { AuthEvent } from './types.ts';
export interface RunDeviceFlowOptions extends LocalOpCliInvocation {
+ lifetime?: LocalOpSubprocessLifetime;
host?: string;
timeoutMs?: number;
onEvent: (event: AuthEvent) => void;
@@ -56,12 +58,14 @@ export function runDeviceFlowSubprocess(opts: RunDeviceFlowOptions): RunDeviceFl
let sawTerminal = false;
const proc = runSubprocess({
+ lifetime: opts.lifetime,
cliArgs: opts.cliArgs,
cliEnv: opts.cliEnv,
cwd: opts.cwd,
trailingArgs: ['auth', 'login', '--json', '--host', host],
timeoutMs,
onLine: ({ parsed }) => {
+ if (opts.lifetime?.stopped) return;
if (!parsed) return;
const event = asAuthEvent(parsed);
if (!event) return;
@@ -73,6 +77,7 @@ export function runDeviceFlowSubprocess(opts: RunDeviceFlowOptions): RunDeviceFl
});
const done = proc.done.then((result) => {
+ if (opts.lifetime?.stopped) return;
if (sawTerminal) return;
if (result.timedOut) {
opts.onEvent({ type: 'error', message: 'Sign-in timed out' });
diff --git a/packages/server/src/local-ops/auth-pat.ts b/packages/server/src/local-ops/auth-pat.ts
index 0c6766470..e64080c69 100644
--- a/packages/server/src/local-ops/auth-pat.ts
+++ b/packages/server/src/local-ops/auth-pat.ts
@@ -1,7 +1,9 @@
import { stderrDetailSuffix } from './clone-error-classify.ts';
import { type LocalOpCliInvocation, runSubprocess } from './subprocess.ts';
+import type { LocalOpSubprocessLifetime } from './subprocess-lifetime.ts';
export interface RunPatOptions extends LocalOpCliInvocation {
+ lifetime?: LocalOpSubprocessLifetime;
host?: string;
token: string;
timeoutMs?: number;
@@ -18,6 +20,7 @@ export async function runPatSubprocess(opts: RunPatOptions): Promise<RunPatResul
let terminal: RunPatResult | null = null;
const proc = runSubprocess({
+ lifetime: opts.lifetime,
cliArgs: opts.cliArgs,
cliEnv: opts.cliEnv,
cwd: opts.cwd,
diff --git a/packages/server/src/local-ops/gh-login.ts b/packages/server/src/local-ops/gh-login.ts
index 380c26774..bd8419a85 100644
--- a/packages/server/src/local-ops/gh-login.ts
+++ b/packages/server/src/local-ops/gh-login.ts
@@ -3,16 +3,24 @@ import { existsSync } from 'node:fs';
import { promisify } from 'node:util';
import { getLogger } from '../logger.ts';
import { runSubprocess } from './subprocess.ts';
+import type { LocalOpSubprocessLifetime } from './subprocess-lifetime.ts';
import type { AuthEvent } from './types.ts';
const execFileAsync = promisify(execFile);
-async function execForStdout(cmd: string, args: string[], timeoutMs: number): Promise<string> {
- const { stdout } = await execFileAsync(cmd, args, {
- encoding: 'utf-8',
- timeout: timeoutMs,
- windowsHide: true,
- });
+async function execForStdout(
+ cmd: string,
+ args: string[],
+ timeoutMs: number,
+ lifetime?: LocalOpSubprocessLifetime,
+): Promise<string> {
+ const launch = () =>
+ execFileAsync(cmd, args, {
+ encoding: 'utf-8',
+ timeout: timeoutMs,
+ windowsHide: true,
+ });
+ const { stdout } = await (lifetime ? lifetime.execFile(launch) : launch());
return stdout;
}
@@ -27,15 +35,21 @@ const KNOWN_GH_PATHS: readonly string[] = [
interface ResolveGhDeps {
_exec?: (cmd: string, args: string[], timeoutMs: number) => Promise<string>;
_fileExists?: (path: string) => boolean;
+ _lifetime?: LocalOpSubprocessLifetime;
}
export async function resolveGhBinaryPath(deps: ResolveGhDeps = {}): Promise<string | null> {
- const exec = deps._exec ?? execForStdout;
+ const exec =
+ deps._exec ??
+ ((cmd: string, args: string[], timeoutMs: number) =>
+ execForStdout(cmd, args, timeoutMs, deps._lifetime));
const fileExists = deps._fileExists ?? existsSync;
const candidates = ['gh', ...KNOWN_GH_PATHS.filter(fileExists)];
for (const cmd of candidates) {
+ if (deps._lifetime?.stopped) return null;
try {
await exec(cmd, ['--version'], 5000);
+ if (deps._lifetime?.stopped) return null;
return cmd;
} catch {}
}
@@ -46,30 +60,38 @@ async function resolveGhLogin(
ghPath: string,
host: string,
exec: (cmd: string, args: string[], timeoutMs: number) => Promise<string> = execForStdout,
+ lifetime?: LocalOpSubprocessLifetime,
): Promise<string> {
+ if (lifetime?.stopped) return '';
try {
const out = await exec(ghPath, ['api', '--hostname', host, 'user', '--jq', '.login'], 10000);
return out.trim();
} catch (err) {
+ if (lifetime?.stopped) return '';
getLogger('gh-login').warn({ err }, 'post-login username lookup failed');
return '';
}
}
let ghPathCache: string | null | undefined;
-let ghProbeInFlight: Promise<string | null> | undefined;
-
-export async function cachedGhBinaryPath(): Promise<string | null> {
- if (ghPathCache) return ghPathCache;
- ghProbeInFlight ??= resolveGhBinaryPath().then((path) => {
- ghProbeInFlight = undefined;
- if (path !== null) ghPathCache = path;
- return path;
- });
- return ghProbeInFlight;
+export function createGhBinaryPathResolver(
+ lifetime: LocalOpSubprocessLifetime,
+): () => Promise<string | null> {
+ let pending: Promise<string | null> | undefined;
+ return () => {
+ if (lifetime.stopped) return Promise.resolve(null);
+ if (ghPathCache) return Promise.resolve(ghPathCache);
+ pending ??= resolveGhBinaryPath({ _lifetime: lifetime }).then((path) => {
+ pending = undefined;
+ if (!lifetime.stopped && path !== null) ghPathCache = path;
+ return lifetime.stopped ? null : path;
+ });
+ return pending;
+ };
}
export interface RunGhDeviceLoginOptions {
+ lifetime?: LocalOpSubprocessLifetime;
host: string;
ghPath: string;
cwd?: string;
@@ -97,6 +119,7 @@ export function runGhDeviceLoginSubprocess(
let stderrBuf = '';
const proc = runSubprocess({
+ lifetime: opts.lifetime,
cliArgs: [opts.ghPath],
cwd: opts.cwd,
trailingArgs: [
@@ -112,6 +135,7 @@ export function runGhDeviceLoginSubprocess(
timeoutMs,
onLine: () => {},
onStderr: (chunk) => {
+ if (opts.lifetime?.stopped) return;
stderrBuf += chunk.toString('utf-8');
if (emittedVerification) return;
const code = stderrBuf.match(CODE_RE)?.[1];
@@ -129,7 +153,7 @@ export function runGhDeviceLoginSubprocess(
});
const verificationDeadline = setTimeout(() => {
- if (emittedVerification) return;
+ if (emittedVerification || opts.lifetime?.stopped) return;
deadlineExpired = true;
opts.onEvent({
type: 'error',
@@ -143,6 +167,7 @@ export function runGhDeviceLoginSubprocess(
const done = proc.done.then(async (result) => {
clearTimeout(verificationDeadline);
+ if (opts.lifetime?.stopped) return;
if (deadlineExpired) return;
if (result.timedOut) {
opts.onEvent({ type: 'error', message: 'gh sign-in timed out — please try again' });
@@ -150,7 +175,13 @@ export function runGhDeviceLoginSubprocess(
}
if (result.cancelled) return;
if (result.code === 0) {
- const login = await resolveGhLogin(opts.ghPath, opts.host);
+ const login = await resolveGhLogin(
+ opts.ghPath,
+ opts.host,
+ (cmd, args, timeoutMs) => execForStdout(cmd, args, timeoutMs, opts.lifetime),
+ opts.lifetime,
+ );
+ if (opts.lifetime?.stopped) return;
opts.onEvent({ type: 'complete', host: opts.host, login });
return;
}
diff --git a/packages/server/src/local-ops/index.ts b/packages/server/src/local-ops/index.ts
index 101ab9aa2..eb24f9419 100644
--- a/packages/server/src/local-ops/index.ts
+++ b/packages/server/src/local-ops/index.ts
@@ -20,7 +20,7 @@ export {
runCloneSubprocess,
validateCloneInputs,
} from './clone-flow.ts';
-export { cachedGhBinaryPath, runGhDeviceLoginSubprocess } from './gh-login.ts';
+export { createGhBinaryPathResolver, runGhDeviceLoginSubprocess } from './gh-login.ts';
export type { LocalOpCliInvocation } from './subprocess.ts';
export type {
AuthEvent,
diff --git a/packages/server/src/local-ops/subprocess-lifetime.test.ts b/packages/server/src/local-ops/subprocess-lifetime.test.ts
new file mode 100644
index 000000000..1e2b52d46
--- /dev/null
+++ b/packages/server/src/local-ops/subprocess-lifetime.test.ts
@@ -0,0 +1,156 @@
+import { type ChildProcess, spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { createServer, type Socket } from 'node:net';
+import { describe, expect, onTestFinished, test } from 'vitest';
+import { LocalOpSubprocessLifetime } from './subprocess-lifetime.ts';
+
+const DESCENDANT = `
+const socket = require('node:net').connect(Number(process.argv[1]), '127.0.0.1', () => {
+ socket.write(process.pid + '\\n');
+});
+socket.on('error', () => process.exit(0));
+socket.on('end', () => process.exit(0));
+`;
+
+const CHILD = `
+const [port, mode, descendant] = process.argv.slice(1);
+require('node:child_process')
+ .spawn(process.execPath, ['-e', descendant, port], { stdio: ['ignore', 'inherit', 'inherit'] })
+ .once('spawn', () => {
+ if (mode === 'exit') process.exit(0);
+ });
+if (mode === 'stay') {
+ const socket = require('node:net').connect(Number(port), '127.0.0.1');
+ socket.on('error', () => process.exit(0));
+ socket.on('end', () => process.exit(0));
+}
+`;
+
+interface Descendant {
+ pid: number;
+ connected(): boolean;
+}
+
+interface ReleaseChannel {
+ port: number;
+ descendant: Promise<Descendant>;
+ release(): Promise<void>;
+}
+
+interface OwnedRun {
+ child: ChildProcess;
+ exited: Promise<number | null>;
+ closed: Promise<void>;
+}
+
+async function openReleaseChannel(): Promise<ReleaseChannel> {
+ const held = new Set<{ socket: Socket; closed: Promise<void> }>();
+ let releasing = false;
+ let connect!: (descendant: Descendant) => void;
+ const descendant = new Promise<Descendant>((resolve) => {
+ connect = resolve;
+ });
+ const server = createServer((socket) => {
+ let open = true;
+ const closed = new Promise<void>((resolve) => {
+ socket.once('close', () => {
+ open = false;
+ resolve();
+ });
+ });
+ held.add({ socket, closed });
+ socket.on('error', () => {});
+ if (releasing) socket.end();
+ socket.setEncoding('utf8');
+ let received = '';
+ socket.on('data', (chunk: string) => {
+ received += chunk;
+ const end = received.indexOf('\n');
+ if (end >= 0) connect({ pid: Number(received.slice(0, end)), connected: () => open });
+ });
+ });
+ server.listen(0, '127.0.0.1');
+ await once(server, 'listening');
+ const address = server.address();
+ if (address === null || typeof address === 'string') {
+ server.close();
+ throw new Error('The release channel has no port.');
+ }
+ return {
+ port: address.port,
+ descendant,
+ async release() {
+ releasing = true;
+ const serverClosed = new Promise<void>((resolve) => server.close(() => resolve()));
+ for (const { socket } of held) socket.end();
+ await Promise.all([...held].map(({ closed }) => closed));
+ await serverClosed;
+ },
+ };
+}
+
+function launch(
+ lifetime: LocalOpSubprocessLifetime,
+ channel: ReleaseChannel,
+ mode: 'stay' | 'exit',
+): OwnedRun {
+ const child = lifetime.spawn(() =>
+ spawn(process.execPath, ['-e', CHILD, String(channel.port), mode, DESCENDANT], {
+ stdio: ['pipe', 'pipe', 'pipe'],
+ }),
+ );
+ const run: OwnedRun = {
+ child,
+ exited: new Promise((resolve) => child.once('exit', (code) => resolve(code))),
+ closed: new Promise((resolve) => child.once('close', () => resolve())),
+ };
+ onTestFinished(async () => {
+ await channel.release();
+ await run.closed;
+ });
+ return run;
+}
+
+function descendantHoldingOutput(
+ channel: ReleaseChannel,
+ run: OwnedRun,
+ childExits: boolean,
+): Promise<Descendant> {
+ const exitedFirst = run.exited.then((code) => {
+ if (childExits && code === 0) return channel.descendant;
+ throw new Error(`The child exited with code ${code} before its descendant connected.`);
+ });
+ return Promise.race([channel.descendant, exitedFirst]);
+}
+
+describe('LocalOpSubprocessLifetime', () => {
+ test('shutdown settles after ending a child whose output a descendant still holds', async ({
+ annotate,
+ }) => {
+ const channel = await openReleaseChannel();
+ const lifetime = new LocalOpSubprocessLifetime();
+ const run = launch(lifetime, channel, 'stay');
+ const descendant = await descendantHoldingOutput(channel, run, false);
+ await annotate(`child pid ${run.child.pid}, descendant pid ${descendant.pid}`);
+
+ await lifetime.shutdown();
+
+ expect(descendant.connected()).toBe(true);
+ expect([run.child.exitCode, run.child.signalCode]).not.toEqual([null, null]);
+ });
+
+ test('shutdown settles for an exited child whose output a descendant still holds', async ({
+ annotate,
+ }) => {
+ const channel = await openReleaseChannel();
+ const lifetime = new LocalOpSubprocessLifetime();
+ const run = launch(lifetime, channel, 'exit');
+ const descendant = await descendantHoldingOutput(channel, run, true);
+ expect(await run.exited).toBe(0);
+ await annotate(`child pid ${run.child.pid}, descendant pid ${descendant.pid}`);
+
+ await lifetime.shutdown();
+
+ expect(descendant.connected()).toBe(true);
+ });
+});
diff --git a/packages/server/src/local-ops/subprocess-lifetime.ts b/packages/server/src/local-ops/subprocess-lifetime.ts
new file mode 100644
index 000000000..28aa2cf7a
--- /dev/null
+++ b/packages/server/src/local-ops/subprocess-lifetime.ts
@@ -0,0 +1,115 @@
+import type { ChildProcess } from 'node:child_process';
+
+interface OwnedChild {
+ child: ChildProcess;
+ closed: Promise<void>;
+}
+
+export class LocalOpSubprocessLifetime {
+ private readonly children = new Set<OwnedChild>();
+ private readonly operations = new Set<Promise<unknown>>();
+ private shuttingDown = false;
+ private shutdownPromise: Promise<void> | undefined;
+
+ get stopped(): boolean {
+ return this.shuttingDown;
+ }
+
+ spawn<T extends ChildProcess>(launch: () => T): T {
+ this.assertOpen();
+ const child = launch();
+ this.hold(child);
+ return child;
+ }
+
+ execFile<T extends Promise<unknown> & { child: ChildProcess }>(launch: () => T): T {
+ this.assertOpen();
+ const request = launch();
+ this.hold(request.child);
+ return request;
+ }
+
+ begin(): () => void {
+ this.assertOpen();
+ let finish!: () => void;
+ const completion = new Promise<void>((resolve) => {
+ finish = resolve;
+ });
+ this.operations.add(completion);
+ return () => {
+ this.operations.delete(completion);
+ finish();
+ };
+ }
+
+ track<T>(operation: Promise<T>): Promise<T> {
+ this.operations.add(operation);
+ void operation.then(
+ () => this.operations.delete(operation),
+ () => this.operations.delete(operation),
+ );
+ return operation;
+ }
+
+ shutdown(): Promise<void> {
+ if (this.shutdownPromise) return this.shutdownPromise;
+ this.shuttingDown = true;
+ this.shutdownPromise = this.drain();
+ return this.shutdownPromise;
+ }
+
+ private assertOpen(): void {
+ if (this.shuttingDown) throw new Error('The server is shutting down.');
+ }
+
+ private hold(child: ChildProcess): void {
+ let owned: OwnedChild;
+ const closed = new Promise<void>((resolve) => {
+ child.once('close', () => {
+ this.children.delete(owned);
+ resolve();
+ });
+ });
+ owned = { child, closed };
+ this.children.add(owned);
+ }
+
+ private async drain(): Promise<void> {
+ const results = await Promise.allSettled(
+ [...this.children].map(async ({ child, closed }) => {
+ if (child.pid !== undefined && child.exitCode === null && child.signalCode === null) {
+ let signalError: Error | undefined;
+ const onError = (error: Error) => {
+ signalError = error;
+ };
+ child.on('error', onError);
+ try {
+ child.kill('SIGKILL');
+ if (signalError) {
+ throw new Error(`Could not stop auth subprocess ${child.pid} (${child.spawnfile})`, {
+ cause: signalError,
+ });
+ }
+ } finally {
+ child.off('error', onError);
+ }
+ }
+ if (child.exitCode === null && child.signalCode === null) {
+ await Promise.race([
+ new Promise<void>((resolve) => child.once('exit', () => resolve())),
+ closed,
+ ]);
+ }
+ for (const stream of [child.stdin, child.stdout, child.stderr]) {
+ if (stream && !stream.destroyed) stream.destroy();
+ }
+ await closed;
+ }),
+ );
+ const errors = results
+ .filter((result) => result.status === 'rejected')
+ .map((result) => result.reason);
+ if (errors.length > 0) throw new AggregateError(errors, 'Auth subprocess shutdown failed');
+ await Promise.allSettled(this.operations);
+ }
+}
diff --git a/packages/server/src/local-ops/subprocess.ts b/packages/server/src/local-ops/subprocess.ts
index 0ecad089d..afad1e48e 100644
--- a/packages/server/src/local-ops/subprocess.ts
+++ b/packages/server/src/local-ops/subprocess.ts
@@ -1,6 +1,7 @@
import { spawn } from 'node:child_process';
import { posix, win32 } from 'node:path';
import { withHiddenWindowsConsole } from '../child-process-windows-hide.ts';
+import type { LocalOpSubprocessLifetime } from './subprocess-lifetime.ts';
interface ParsedLine {
raw: string;
@@ -16,6 +17,7 @@ export interface LocalOpCliInvocation {
}
interface SubprocessRunOptions extends LocalOpCliInvocation {
+ lifetime?: LocalOpSubprocessLifetime;
trailingArgs: readonly string[];
extraPathDirs?: readonly string[];
timeoutMs: number;
@@ -132,15 +134,17 @@ export function runSubprocess(opts: SubprocessRunOptions): SubprocessController
opts.stdinData !== undefined ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'];
let child: ReturnType<typeof spawn>;
try {
- child = spawn(
- cmd,
- argv,
- withHiddenWindowsConsole({
- stdio,
- cwd: opts.cwd,
- env: childEnv,
- }),
- );
+ const launch = () =>
+ spawn(
+ cmd,
+ argv,
+ withHiddenWindowsConsole({
+ stdio,
+ cwd: opts.cwd,
+ env: childEnv,
+ }),
+ );
+ child = opts.lifetime ? opts.lifetime.spawn(launch) : launch();
} catch (err) {
return {
done: Promise.resolve({
diff --git a/packages/server/src/server-factory-local-op-shutdown.test.ts b/packages/server/src/server-factory-local-op-shutdown.test.ts
new file mode 100644
index 000000000..202454fe4
--- /dev/null
+++ b/packages/server/src/server-factory-local-op-shutdown.test.ts
@@ -0,0 +1,176 @@
+import { ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { mkdtempSync, rmSync } from 'node:fs';
+import {
+ createServer as createHttpServer,
+ type IncomingMessage,
+ type ServerResponse,
+} from 'node:http';
+import { constants, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PassThrough } from 'node:stream';
+import { afterEach, expect, test, vi } from 'vitest';
+import { createHttpApp } from './http/http-app.ts';
+import { getLogger, loggerFactory, type PinoLogger } from './logger.ts';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
+import { createServer } from './server-factory.ts';
+import { useIsolatedHome } from './share/git-host-declarations.test-helper.ts';
+
+const auth = vi.hoisted(() => ({
+ cli: 'recorded-auth-cli',
+ child: undefined as object | undefined,
+}));
+vi.mock('node:child_process', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('node:child_process')>();
+ return {
+ ...actual,
+ spawn: (...args: Parameters<typeof actual.spawn>) => {
+ if (args[0] !== auth.cli) return actual.spawn(...args);
+ if (auth.child === undefined) throw new Error('Unexpected auth child');
+ return auth.child;
+ },
+ };
+});
+
+class RecordedChild extends EventEmitter {
+ pid = 42;
+ spawnfile = auth.cli;
+ exitCode: number | null = null;
+ signalCode: NodeJS.Signals | null = null;
+ killed = false;
+ stdin = new PassThrough();
+ stdout = new PassThrough();
+ stderr = new PassThrough();
+ signals: number[] = [];
+ _handle = {
+ kill: (signal: number): number => {
+ this.signals.push(signal);
+ return signal === constants.signals.SIGKILL ? -constants.errno.EPERM : 0;
+ },
+ };
+ kill = ChildProcess.prototype.kill;
+
+ close(): void {
+ if (this.exitCode !== null) return;
+ this.exitCode = 0;
+ this.emit('close', 0, null);
+ }
+}
+
+function guardNativeAuthSpawn(): void {
+ const prototype = ChildProcess.prototype as ChildProcess & {
+ spawn(options: { file: string }): unknown;
+ };
+ const nativeSpawn = prototype.spawn;
+ vi.spyOn(prototype, 'spawn').mockImplementation(function (this: ChildProcess, options) {
+ if (options.file === auth.cli) {
+ throw new Error('This recording-only test must not spawn the auth CLI');
+ }
+ return nativeSpawn.call(this, options);
+ });
+}
+
+interface LogEntry {
+ level: 'info' | 'warn' | 'error' | 'debug';
+ msg: string;
+ payload: Record<string, unknown>;
+}
+
+function captureLogs(): LogEntry[] {
+ const entries: LogEntry[] = [];
+ loggerFactory.configure({
+ loggerFactory: () => {
+ const record =
+ (level: LogEntry['level']) =>
+ (payload: unknown, msg: string): void => {
+ entries.push({ level, msg, payload: (payload as Record<string, unknown>) ?? {} });
+ };
+ return {
+ info: record('info'),
+ warn: record('warn'),
+ error: record('error'),
+ debug: record('debug'),
+ } as unknown as PinoLogger;
+ },
+ });
+ return entries;
+}
+
+const home = useIsolatedHome();
+afterEach(() => {
+ auth.child = undefined;
+ vi.restoreAllMocks();
+ loggerFactory.reset();
+});
+
+test('destroy rejects with a refused auth subprocess termination and records the phase error', async () => {
+ guardNativeAuthSpawn();
+ const logs = captureLogs();
+ const child = new RecordedChild();
+ auth.child = child;
+ child.stdout.write(
+ `${JSON.stringify({
+ type: 'verification',
+ user_code: 'WDJB-MJHT',
+ verification_uri: 'https://github.com/login/device',
+ expires_in: 900,
+ })}\n`,
+ );
+ const projectDir = mkdtempSync(join(tmpdir(), 'ok-local-op-shutdown-'));
+ const instance = createServer({
+ contentDir: projectDir,
+ projectDir,
+ gitEnabled: false,
+ quiet: true,
+ localOpCliArgs: [auth.cli],
+ configHomedirOverride: home(),
+ });
+ const notFound = (_req: IncomingMessage, res: ServerResponse): void => {
+ res.writeHead(404).end();
+ };
+ const { requestListener } = createHttpApp({
+ nativeApi: instance.nativeApi,
+ legacyDispatch: notFound,
+ contentDispatch: notFound,
+ log: getLogger('test'),
+ });
+ const http = createHttpServer(requestListener);
+ try {
+ await instance.ready;
+ const { baseUrl } = await listenOnLoopback(http);
+ const login = await fetch(`${baseUrl}/api/local-op/auth/login`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ });
+ expect(login.status).toBe(200);
+
+ const outcome = await instance.destroy().then(
+ () => 'resolved',
+ (error: unknown) => error,
+ );
+
+ expect(child.signals).toContain(constants.signals.SIGKILL);
+ const refusal = `Could not stop auth subprocess ${child.pid} (${auth.cli})`;
+ expect(outcome).toBeInstanceOf(AggregateError);
+ expect((outcome as AggregateError).errors).toEqual([
+ expect.objectContaining({
+ message: refusal,
+ cause: expect.objectContaining({ code: 'EPERM' }),
+ }),
+ ]);
+ const summaries = logs.filter(
+ (entry) => entry.level === 'warn' && entry.msg.includes('shutdown flushed'),
+ );
+ expect(summaries.flatMap((entry) => entry.payload.phaseErrors)).toContainEqual({
+ phase: 'local-op-subprocess-shutdown',
+ error: refusal,
+ });
+ } finally {
+ child.close();
+ await instance.destroy().catch(() => undefined);
+ http.closeAllConnections();
+ await new Promise<void>((resolve) => http.close(() => resolve()));
+ rmSync(projectDir, { recursive: true, force: true });
+ }
+});
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index 984ee3c90..a84ba3013 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -990,6 +990,7 @@ export function createServer(options: ServerOptions): ServerInstance {
let sessionManager: AgentSessionManager;
let nativeApi: NativeApiHandle;
let localApi: LocalApiDispatch;
+ let shutdownLocalOps: () => Promise<void>;
let bridgeLossReporter: BridgeDeriveLossReporter | undefined;
let inPlaceRescanTimer: ReturnType<typeof setTimeout> | null = null;
let shadowWarmupTimer: ReturnType<typeof setTimeout> | null = null;
@@ -2198,6 +2199,7 @@ export function createServer(options: ServerOptions): ServerInstance {
hocuspocus.configuration.extensions.push(apiExtension);
nativeApi = apiExtension.nativeApi;
localApi = apiExtension.localApi;
+ shutdownLocalOps = apiExtension.shutdownLocalOps;
const bridgeGuardConfig = readConfigSafely({
absPath: resolveConfigPath('project', projectDir),
@@ -3155,6 +3157,8 @@ export function createServer(options: ServerOptions): ServerInstance {
const t0 = Date.now();
const phaseErrors: Array<{ phase: string; error: string }> = [];
shutdownAllowsUnload = true;
+ const authShutdown = Promise.allSettled([shutdownLocalOps()]);
+ let authResult: PromiseSettledResult<void> | undefined;
try {
await closeIndexRegeneration();
@@ -3401,6 +3405,18 @@ export function createServer(options: ServerOptions): ServerInstance {
}
}
+ [authResult] = await authShutdown;
+ if (authResult.status === 'rejected') {
+ const reason: unknown = authResult.reason;
+ const failures = reason instanceof AggregateError ? reason.errors : [reason];
+ phaseErrors.push({
+ phase: 'local-op-subprocess-shutdown',
+ error: failures
+ .map((failure) => (failure instanceof Error ? failure.message : String(failure)))
+ .join('; '),
+ });
+ log.error({ err: reason }, '[server] shutdown local-op subprocess drain failed');
+ }
const durationMs = Date.now() - t0;
if (phaseErrors.length === 0) {
log.info(
@@ -3433,6 +3449,7 @@ export function createServer(options: ServerOptions): ServerInstance {
});
}
}
+ if (authResult?.status === 'rejected') throw authResult.reason;
})();
return inflightDestroy;