Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Start ok auth git-credential without booting the whole CLI (#6733)

Dimitri POSTOLOV15789ebc4127
diff --git a/.changeset/fast-git-credential-helper.md b/.changeset/fast-git-credential-helper.md
new file mode 100644
index 000000000..e498d702b
--- /dev/null
+++ b/.changeset/fast-git-credential-helper.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Git operations that OpenKnowledge authenticates start faster: its credential helper now answers about six times faster, and git no longer prints "unknown command 'store'" or "unknown command 'erase'" after each fetch or push.
diff --git a/knip.config.ts b/knip.config.ts
index e04bf5228..1342c6bf1 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -160,7 +160,13 @@ export default {
ignoreDependencies: ['@types/shell-quote'],
},
'packages/cli': {
- entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],
+ entry: [
+ 'src/**/*.test.ts',
+ 'scripts/*.ts',
+ 'tests/**/*.ts',
+ 'src/parse-worker.ts',
+ 'src/bin.ts',
+ ],
ignoreDependencies: ['yjs'],
},
'packages/desktop': {
diff --git a/packages/cli/src/auth/token-store.ts b/packages/cli/src/auth/token-store.ts
index b3a203188..11104136f 100644
--- a/packages/cli/src/auth/token-store.ts
+++ b/packages/cli/src/auth/token-store.ts
@@ -1,11 +1,12 @@
import { existsSync, mkdirSync, readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import {
- currentDesktopProduct,
OK_USER_HOME_AUTH_FILE,
okUserHomeDisplayPath,
-} from '@inkeep/open-knowledge-core';
-import { atomicWriteFileSync, okUserHomeDir } from '@inkeep/open-knowledge-core/server';
+} from '@inkeep/open-knowledge-core/constants/ok-dir';
+import { okUserHomeDir } from '@inkeep/open-knowledge-core/constants/ok-user-home';
+import { currentDesktopProduct } from '@inkeep/open-knowledge-core/constants/product';
+import { atomicWriteFileSync } from '@inkeep/open-knowledge-core/util/atomic-yaml-write';
import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
interface TokenEntry {
diff --git a/packages/cli/src/bin.ts b/packages/cli/src/bin.ts
new file mode 100644
index 000000000..7b10de442
--- /dev/null
+++ b/packages/cli/src/bin.ts
@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { recordCliEntryPath } from './cli-entry-path.ts';
+import {
+ gitCredentialHelperOperation,
+ handleCredentialUpdate,
+} from './commands/auth/git-credential-operation.ts';
+
+recordCliEntryPath(import.meta.url);
+
+const helperOperation = gitCredentialHelperOperation(process.argv.slice(2));
+if (helperOperation === 'get') {
+ const { runGitCredentialGet } = await import('./commands/auth/git-credential-helper.ts');
+ process.exit(await runGitCredentialGet());
+}
+if (helperOperation !== null) {
+ process.exit(await handleCredentialUpdate(helperOperation, process.stdin));
+}
+await import('./cli.ts');
diff --git a/packages/cli/src/cli-entry-path.ts b/packages/cli/src/cli-entry-path.ts
new file mode 100644
index 000000000..1e57a534a
--- /dev/null
+++ b/packages/cli/src/cli-entry-path.ts
@@ -0,0 +1,11 @@
+import { fileURLToPath } from 'node:url';
+
+let cliEntryPath: string | undefined;
+
+export function recordCliEntryPath(entryUrl: string): void {
+ cliEntryPath ??= fileURLToPath(entryUrl);
+}
+
+export function recordedCliEntryPath(): string | undefined {
+ return cliEntryPath;
+}
diff --git a/packages/cli/src/cli-logger.ts b/packages/cli/src/cli-logger.ts
index 0aee025cf..37a0e2fd8 100644
--- a/packages/cli/src/cli-logger.ts
+++ b/packages/cli/src/cli-logger.ts
@@ -1,4 +1,5 @@
-import { createFileLogger, findEnclosingProjectRoot } from '@inkeep/open-knowledge-server';
+import { createFileLogger } from '@inkeep/open-knowledge-server/file-logger';
+import { findEnclosingProjectRoot } from '@inkeep/open-knowledge-server/fs/find-project-root';
import type { Logger as PinoLoggerInstance } from 'pino';
let cliLogger: PinoLoggerInstance | undefined;
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 04a9f703f..8b34fa8e4 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -26,6 +26,7 @@ import {
trustSystemCertificates,
} from '@inkeep/open-knowledge-server';
import { Command } from 'commander';
+import { recordCliEntryPath } from './cli-entry-path.ts';
import { getCliLogger, initCliLogger } from './cli-logger.ts';
import { auditCommand } from './commands/audit.ts';
import { authCommand } from './commands/auth/index.ts';
@@ -65,6 +66,8 @@ import { loadConfig } from './index.ts';
import { recordInvocationCwd, resolveProjectAnchor } from './project-anchor.ts';
import { buildVersionNotice } from './version-notice.ts';
+recordCliEntryPath(import.meta.url);
+
const program = new Command();
let resolvedConfig: Config;
diff --git a/packages/cli/src/commands/auth/git-credential-get.ts b/packages/cli/src/commands/auth/git-credential-get.ts
index e97bbd899..dd335ed1a 100644
--- a/packages/cli/src/commands/auth/git-credential-get.ts
+++ b/packages/cli/src/commands/auth/git-credential-get.ts
@@ -1,15 +1,46 @@
import type { Readable, Writable } from 'node:stream';
-import { gitCredentialHostKey } from '@inkeep/open-knowledge-core';
+import { gitCredentialHostKey } from '@inkeep/open-knowledge-core/constants/github';
import type { Logger as PinoLoggerInstance } from 'pino';
import type { TokenStore, TokenStoreDiagnostics } from '../../auth/token-store.ts';
-export type KeychainReadInfo = Parameters<NonNullable<TokenStoreDiagnostics['onKeychainRead']>>[0];
+type KeychainReadInfo = Parameters<NonNullable<TokenStoreDiagnostics['onKeychainRead']>>[0];
export interface CredentialGetLogContext {
log?: PinoLoggerInstance;
getDiag?: () => KeychainReadInfo | undefined;
}
+export interface GitCredentialGetContext {
+ getTokenStore: (diag?: TokenStoreDiagnostics) => Promise<TokenStore>;
+ log?: PinoLoggerInstance;
+}
+
+export async function getGitCredential({
+ getTokenStore,
+ log,
+}: GitCredentialGetContext): Promise<number> {
+ try {
+ let lastKeychainRead: KeychainReadInfo | undefined;
+ const store = await getTokenStore({
+ onKeychainRead: (info) => {
+ lastKeychainRead = info;
+ },
+ onBackendSelected: (info) => {
+ if (info.backend === 'file' && info.reason) {
+ log?.warn({ backend: 'file', reason: info.reason }, '[auth] token storage fallback');
+ }
+ },
+ });
+ return await handleCredentialGet(process.stdin, process.stdout, store, {
+ log,
+ getDiag: () => lastKeychainRead,
+ });
+ } catch (err) {
+ log?.error({ err }, '[auth] git-credential get: unexpected error');
+ return 1;
+ }
+}
+
export async function handleCredentialGet(
input: Readable,
output: Writable,
diff --git a/packages/cli/src/commands/auth/git-credential-helper.test.ts b/packages/cli/src/commands/auth/git-credential-helper.test.ts
new file mode 100644
index 000000000..c7cce0f6c
--- /dev/null
+++ b/packages/cli/src/commands/auth/git-credential-helper.test.ts
@@ -0,0 +1,256 @@
+import { execFileSync, spawn, spawnSync } from 'node:child_process';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ realpathSync,
+ rmSync,
+ statSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { afterEach, beforeAll, beforeEach, describe, expect, test } from 'vitest';
+import { configureTestGitRepository } from '../../../../../test-support/configure-git-fixture.test-helper.ts';
+import {
+ GITHUB_HOST,
+ type GitHubStandIn,
+ startGitHubStandIn,
+} from '../../../tests/support/github-stand-in.test-helper.ts';
+import { buildCliCredentialHelper } from '../../auth/resolve-auth.ts';
+import { linesCarrying } from '../git-credential-fixtures.test-helper.ts';
+
+const CLI_DIST = resolve(import.meta.dirname, '../../../dist');
+const CLI_ENTRY = join(CLI_DIST, 'cli.mjs');
+const ORIGIN_URL = `https://${GITHUB_HOST}/alice/demo.git`;
+const RELAY_TOKEN = 'ok-test-helper-relay-token-github-accepts';
+const STALE_RELAY_TOKEN = 'ok-test-helper-relay-token-github-rejects';
+const GET_BUNDLE_BUDGET_BYTES = 300 * 1024;
+const UPDATE_BUNDLE_BUDGET_BYTES = 8 * 1024;
+const HELPER_INPUT = `protocol=https\nhost=${GITHUB_HOST}\n\n`;
+const CHILD_TIMEOUT_MS = 10_000;
+
+const LOAD_PROBE = `import { writeFileSync } from 'node:fs';
+import { registerHooks } from 'node:module';
+const loaded = [];
+registerHooks({
+ load(url, context, nextLoad) {
+ loaded.push(url);
+ return nextLoad(url, context);
+ },
+});
+process.on('exit', () => writeFileSync(process.env.OK_TEST_LOAD_RECORD, JSON.stringify(loaded)));
+`;
+
+let workspace: string;
+let home: string;
+let projectDir: string;
+let traceFile: string;
+let standIn: GitHubStandIn | undefined;
+
+function hermeticEnv(extra: Record<string, string> = {}): Record<string, string> {
+ return {
+ PATH: process.env.PATH ?? '',
+ HOME: home,
+ USERPROFILE: home,
+ GIT_CONFIG_NOSYSTEM: '1',
+ GIT_CONFIG_GLOBAL: join(home, '.gitconfig'),
+ GIT_TERMINAL_PROMPT: '0',
+ ...extra,
+ };
+}
+
+function helperOperations(): string[] {
+ if (!existsSync(traceFile)) return [];
+ return linesCarrying(readFileSync(traceFile, 'utf-8'), 'run_command:').flatMap((line) => {
+ const operation = /auth git-credential (get|store|erase)\b/.exec(line)?.[1];
+ return operation === undefined ? [] : [operation];
+ });
+}
+
+function fetchThroughOkHelper(
+ relayToken: string,
+): Promise<{ status: number | null; stderr: string }> {
+ const fetch = spawn(
+ 'git',
+ [
+ '-c',
+ 'credential.helper=',
+ '-c',
+ buildCliCredentialHelper([process.execPath, CLI_ENTRY]),
+ '-c',
+ 'credential.interactive=false',
+ 'fetch',
+ 'origin',
+ ],
+ {
+ cwd: projectDir,
+ stdio: ['ignore', 'ignore', 'pipe'],
+ env: hermeticEnv({
+ GIT_TRACE: traceFile,
+ OK_GH_TOKEN: relayToken,
+ OK_GH_TOKEN_HOST: GITHUB_HOST,
+ }),
+ },
+ );
+ let stderr = '';
+ fetch.stderr.setEncoding('utf-8');
+ fetch.stderr.on('data', (chunk: string) => {
+ stderr += chunk;
+ });
+ const { promise, resolve, reject } = Promise.withResolvers<{
+ status: number | null;
+ stderr: string;
+ }>();
+ fetch.once('error', reject);
+ fetch.once('close', (status) => resolve({ status, stderr }));
+ return promise;
+}
+
+interface LoadedBundle {
+ status: number | null;
+ stdout: string;
+ stderr: string;
+ bytes: number;
+ files: string[];
+}
+
+function bundleLoadedBy(args: readonly string[]): LoadedBundle {
+ const probe = join(workspace, 'load-probe.mjs');
+ const record = join(workspace, 'loaded-modules.json');
+ writeFileSync(probe, LOAD_PROBE);
+ const run = spawnSync(
+ process.execPath,
+ ['--import', pathToFileURL(probe).href, CLI_ENTRY, ...args],
+ {
+ cwd: projectDir,
+ input: HELPER_INPUT,
+ encoding: 'utf-8',
+ timeout: CHILD_TIMEOUT_MS,
+ killSignal: 'SIGKILL',
+ env: hermeticEnv({
+ OK_TEST_LOAD_RECORD: record,
+ OK_GH_TOKEN: RELAY_TOKEN,
+ OK_GH_TOKEN_HOST: GITHUB_HOST,
+ }),
+ },
+ );
+ expect(
+ run.error,
+ `${args.join(' ')} did not finish within ${CHILD_TIMEOUT_MS} ms:\n${run.stderr}`,
+ ).toBeUndefined();
+ const dist = realpathSync(CLI_DIST);
+ const files = (JSON.parse(readFileSync(record, 'utf-8')) as string[])
+ .filter((url) => url.startsWith('file:'))
+ .map((url) => realpathSync(fileURLToPath(url)))
+ .filter((path) => path.startsWith(`${dist}${sep}`));
+ expect(files, 'the load probe saw no dist/cli.mjs, so it measured nothing').toContain(
+ join(dist, 'cli.mjs'),
+ );
+ return {
+ status: run.status,
+ stdout: run.stdout,
+ stderr: run.stderr,
+ bytes: files.reduce((sum, path) => sum + statSync(path).size, 0),
+ files,
+ };
+}
+
+describe("git authenticates through OpenKnowledge's built credential helper", () => {
+ beforeAll(() => {
+ expect(
+ existsSync(CLI_ENTRY),
+ `${CLI_ENTRY} is missing. The cli \`test\` turbo task builds it first; a bare vitest run needs \`pnpm --dir packages/cli run build:cli\`.`,
+ ).toBe(true);
+ });
+
+ beforeEach(async () => {
+ workspace = realpathSync(mkdtempSync(join(tmpdir(), 'ok-git-credential-helper-')));
+ home = join(workspace, 'home');
+ projectDir = join(workspace, 'project');
+ traceFile = join(workspace, 'git-trace.log');
+ mkdirSync(home, { recursive: true });
+ mkdirSync(projectDir, { recursive: true });
+ standIn = await startGitHubStandIn({
+ root: join(workspace, 'github'),
+ acceptedPassword: RELAY_TOKEN,
+ repositories: ['alice/demo.git'],
+ });
+ for (const [key, value] of [
+ ['user.name', 'Helper Test'],
+ ['user.email', '[email protected]'],
+ ['init.defaultBranch', 'main'],
+ ['commit.gpgsign', 'false'],
+ ['http.proxy', standIn.proxyUrl],
+ ['http.sslCAInfo', standIn.caFile],
+ ['http.curloptResolve', `${GITHUB_HOST}:443:127.0.0.1`],
+ ]) {
+ execFileSync('git', ['config', '--file', join(home, '.gitconfig'), '--add', key, value]);
+ }
+ const git = (...args: string[]) =>
+ execFileSync('git', args, { cwd: projectDir, env: hermeticEnv(), stdio: 'ignore' });
+ git('init', '--initial-branch=main');
+ configureTestGitRepository(projectDir);
+ git('commit', '--allow-empty', '-m', 'seed');
+ git('push', standIn.repositoryDir('alice/demo.git'), 'main:main');
+ git('remote', 'add', 'origin', ORIGIN_URL);
+ });
+
+ afterEach(async () => {
+ await standIn?.close();
+ standIn = undefined;
+ rmSync(workspace, { recursive: true, force: true });
+ });
+
+ test('an accepted token is fetched with get, then git reports it to store without an error', async () => {
+ const fetched = await fetchThroughOkHelper(RELAY_TOKEN);
+
+ expect(fetched.status, fetched.stderr).toBe(0);
+ expect(standIn?.requests.filter((request) => request.status === 200)).toContainEqual(
+ expect.objectContaining({
+ credential: { username: 'x-access-token', password: RELAY_TOKEN },
+ }),
+ );
+ expect(helperOperations()).toEqual(['get', 'store']);
+ expect(linesCarrying(fetched.stderr, 'error:')).toEqual([]);
+ });
+
+ test('a rejected token is reported to erase without an error from the helper', async () => {
+ const fetched = await fetchThroughOkHelper(STALE_RELAY_TOKEN);
+
+ expect(fetched.status).not.toBe(0);
+ expect(fetched.stderr).toContain('Authentication failed');
+ expect(helperOperations()).toEqual(['get', 'erase']);
+ expect(linesCarrying(fetched.stderr, 'error:')).toEqual([]);
+ });
+
+ test('each helper call loads only its own slice of the bundle, not the whole CLI', () => {
+ const get = bundleLoadedBy(['auth', 'git-credential', 'get']);
+ expect(get.status, get.stderr).toBe(0);
+ expect(get.bytes, get.files.join('\n')).toBeLessThan(GET_BUNDLE_BUDGET_BYTES);
+ for (const operation of ['store', 'erase']) {
+ const update = bundleLoadedBy(['auth', 'git-credential', operation]);
+ expect(update.status, update.stderr).toBe(0);
+ expect(update.bytes, update.files.join('\n')).toBeLessThan(UPDATE_BUNDLE_BUDGET_BYTES);
+ }
+ });
+
+ test('any other argv shape runs the full CLI, which applies its options and errors', () => {
+ const prefixed = bundleLoadedBy(['--log-level', 'debug', 'auth', 'git-credential', 'get']);
+ expect(prefixed.bytes).toBeGreaterThan(GET_BUNDLE_BUDGET_BYTES);
+ expect(prefixed.status, prefixed.stderr).toBe(0);
+ expect(prefixed.stdout).toBe(`username=x-access-token\npassword=${RELAY_TOKEN}\n`);
+
+ const help = bundleLoadedBy(['auth', 'git-credential', 'get', '--help']);
+ expect(help.bytes).toBeGreaterThan(GET_BUNDLE_BUDGET_BYTES);
+ expect(help.status, help.stderr).toBe(0);
+ expect(help.stdout).toContain('Usage:');
+
+ const unknown = bundleLoadedBy(['auth', 'git-credential', 'frob']);
+ expect(unknown.bytes).toBeGreaterThan(GET_BUNDLE_BUDGET_BYTES);
+ expect(unknown.status).toBe(1);
+ expect(unknown.stderr).toContain("error: unknown command 'frob'");
+ });
+});
diff --git a/packages/cli/src/commands/auth/git-credential-helper.ts b/packages/cli/src/commands/auth/git-credential-helper.ts
new file mode 100644
index 000000000..549085a19
--- /dev/null
+++ b/packages/cli/src/commands/auth/git-credential-helper.ts
@@ -0,0 +1,14 @@
+import { flushFileLogger } from '@inkeep/open-knowledge-server/file-logger';
+import { createTokenStore } from '../../auth/token-store.ts';
+import { initCliLogger } from '../../cli-logger.ts';
+import { getGitCredential } from './git-credential-get.ts';
+
+export async function runGitCredentialGet(): Promise<number> {
+ const log = initCliLogger({ command: 'auth', cwd: process.cwd() });
+ const exitCode = await getGitCredential({
+ getTokenStore: (diag) => createTokenStore(undefined, diag),
+ log,
+ });
+ await flushFileLogger(log);
+ return exitCode;
+}
diff --git a/packages/cli/src/commands/auth/git-credential-operation.ts b/packages/cli/src/commands/auth/git-credential-operation.ts
new file mode 100644
index 000000000..a815c5920
--- /dev/null
+++ b/packages/cli/src/commands/auth/git-credential-operation.ts
@@ -0,0 +1,36 @@
+import type { Readable } from 'node:stream';
+
+export const GIT_CREDENTIAL_OPERATIONS = ['get', 'store', 'erase'] as const;
+
+export type GitCredentialOperation = (typeof GIT_CREDENTIAL_OPERATIONS)[number];
+
+function isGitCredentialOperation(value: string | undefined): value is GitCredentialOperation {
+ return GIT_CREDENTIAL_OPERATIONS.some((operation) => operation === value);
+}
+
+export function gitCredentialHelperOperation(
+ args: readonly string[],
+): GitCredentialOperation | null {
+ if (args.length !== 3 || args[0] !== 'auth' || args[1] !== 'git-credential') return null;
+ const operation = args[2];
+ return isGitCredentialOperation(operation) ? operation : null;
+}
+
+export function handleCredentialUpdate(
+ operation: Exclude<GitCredentialOperation, 'get'>,
+ input: Readable,
+): Promise<number> {
+ switch (operation) {
+ case 'store':
+ case 'erase':
+ return drainInput(input);
+ }
+}
+
+function drainInput(input: Readable): Promise<number> {
+ const { promise, resolve } = Promise.withResolvers<number>();
+ input.once('end', () => resolve(0));
+ input.once('error', () => resolve(0));
+ input.resume();
+ return promise;
+}
diff --git a/packages/cli/src/commands/auth/git-credential.ts b/packages/cli/src/commands/auth/git-credential.ts
index 3e7aa7f5b..751c8eaac 100644
--- a/packages/cli/src/commands/auth/git-credential.ts
+++ b/packages/cli/src/commands/auth/git-credential.ts
@@ -2,7 +2,18 @@ import { flushFileLogger } from '@inkeep/open-knowledge-server';
import { Command } from 'commander';
import type { Logger as PinoLoggerInstance } from 'pino';
import type { TokenStore, TokenStoreDiagnostics } from '../../auth/token-store.ts';
-import { handleCredentialGet, type KeychainReadInfo } from './git-credential-get.ts';
+import { getGitCredential } from './git-credential-get.ts';
+import {
+ GIT_CREDENTIAL_OPERATIONS,
+ type GitCredentialOperation,
+ handleCredentialUpdate,
+} from './git-credential-operation.ts';
+
+const OPERATION_DESCRIPTIONS: Record<GitCredentialOperation, string> = {
+ get: 'Lookup credentials from TokenStore (called by git)',
+ store: 'Accept a credential git approved, without saving it (called by git)',
+ erase: 'Accept a credential git rejected, without removing it (called by git)',
+};
export function gitCredentialCommand(
getTokenStore: (diag?: TokenStoreDiagnostics) => Promise<TokenStore>,
@@ -11,35 +22,20 @@ export function gitCredentialCommand(
const cmd = new Command('git-credential');
cmd.description('Git credential helper (git credential-helper protocol)');
- cmd
- .command('get')
- .description('Lookup credentials from TokenStore (called by git)')
- .action(async () => {
- const log = getLog?.();
- try {
- let lastKeychainRead: KeychainReadInfo | undefined;
- const store = await getTokenStore({
- onKeychainRead: (info) => {
- lastKeychainRead = info;
- },
- onBackendSelected: (info) => {
- if (info.backend === 'file' && info.reason) {
- log?.warn({ backend: 'file', reason: info.reason }, '[auth] token storage fallback');
- }
- },
- });
- const exitCode = await handleCredentialGet(process.stdin, process.stdout, store, {
- log,
- getDiag: () => lastKeychainRead,
- });
+ for (const operation of GIT_CREDENTIAL_OPERATIONS) {
+ cmd
+ .command(operation)
+ .description(OPERATION_DESCRIPTIONS[operation])
+ .action(async () => {
+ const log = getLog?.();
+ const exitCode =
+ operation === 'get'
+ ? await getGitCredential({ getTokenStore, log })
+ : await handleCredentialUpdate(operation, process.stdin);
await flushFileLogger(log);
process.exit(exitCode);
- } catch (err) {
- log?.error({ err }, '[auth] git-credential get: unexpected error');
- await flushFileLogger(log);
- process.exit(1);
- }
- });
+ });
+ }
return cmd;
}
diff --git a/packages/cli/src/commands/mcp.ts b/packages/cli/src/commands/mcp.ts
index 0f72f9926..9e18d0946 100644
--- a/packages/cli/src/commands/mcp.ts
+++ b/packages/cli/src/commands/mcp.ts
@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
import { homedir } from 'node:os';
import type { Config } from '@inkeep/open-knowledge-server';
import { Command } from 'commander';
+import { recordedCliEntryPath } from '../cli-entry-path.ts';
import {
emitBundleProxyEvent,
findBundledOkPath,
@@ -86,6 +87,7 @@ export function mcpCommand(getConfig: () => Config): Command {
await startGlobalMcpServer({
startupCwd,
startupConfig,
+ bundleAnchorPath: recordedCliEntryPath(),
});
} catch (err) {
process.stderr.write(
diff --git a/packages/cli/src/mcp/bundle-identity-anchor.test.ts b/packages/cli/src/mcp/bundle-identity-anchor.test.ts
new file mode 100644
index 000000000..ae57d0a2b
--- /dev/null
+++ b/packages/cli/src/mcp/bundle-identity-anchor.test.ts
@@ -0,0 +1,84 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { afterEach, beforeAll, describe, expect, test } from 'vitest';
+
+const CLI_ENTRY = resolve(import.meta.dirname, '../../dist/cli.mjs');
+const ANCHOR_LINE = /\[mcp\] bundle identity anchor=(.+?) dev=\d+ inode=\d+/;
+const ANCHOR_WAIT_MS = 20_000;
+const RUN_AS_DARWIN = "Object.defineProperty(process, 'platform', { value: 'darwin' });\n";
+
+let home: string | undefined;
+
+function anchorReportedByBuiltMcp(): Promise<string> {
+ home = realpathSync(mkdtempSync(join(tmpdir(), 'ok-mcp-anchor-')));
+ const runAsDarwin = join(home, 'run-as-darwin.mjs');
+ writeFileSync(runAsDarwin, RUN_AS_DARWIN);
+ const mcp = spawn(
+ process.execPath,
+ ['--import', pathToFileURL(runAsDarwin).href, CLI_ENTRY, 'mcp', '--no-bundle-proxy'],
+ {
+ cwd: home,
+ stdio: ['pipe', 'ignore', 'pipe'],
+ env: { PATH: process.env.PATH ?? '', HOME: home },
+ },
+ );
+ let stderr = '';
+ let settled = false;
+ const { promise, resolve, reject } = Promise.withResolvers<string>();
+ const fail = (reason: string): void => {
+ settled = true;
+ clearTimeout(timer);
+ mcp.kill('SIGKILL');
+ reject(new Error(`${reason}:\n${stderr}`));
+ };
+ const timer = setTimeout(
+ () => fail(`no bundle identity anchor line within ${ANCHOR_WAIT_MS} ms`),
+ ANCHOR_WAIT_MS,
+ );
+ mcp.stderr.setEncoding('utf-8');
+ mcp.stderr.on('data', (chunk: string) => {
+ stderr += chunk;
+ if (settled) return;
+ if (stderr.includes('bundle identity watcher off')) {
+ fail('ok mcp started no bundle identity watcher');
+ return;
+ }
+ const anchor = ANCHOR_LINE.exec(stderr)?.[1];
+ if (anchor === undefined) return;
+ settled = true;
+ clearTimeout(timer);
+ mcp.once('close', () => resolve(anchor));
+ mcp.stdin.end();
+ });
+ mcp.once('error', (err) => {
+ settled = true;
+ clearTimeout(timer);
+ reject(err);
+ });
+ return promise;
+}
+
+describe('the built CLI anchors the macOS MCP upgrade watcher on its entry file', () => {
+ beforeAll(() => {
+ expect(
+ existsSync(CLI_ENTRY),
+ `${CLI_ENTRY} is missing. The cli \`test\` turbo task builds it first; a bare vitest run needs \`pnpm --dir packages/cli run build:cli\`.`,
+ ).toBe(true);
+ });
+
+ afterEach(() => {
+ if (home !== undefined) rmSync(home, { recursive: true, force: true });
+ home = undefined;
+ });
+
+ test(
+ 'ok mcp watches dist/cli.mjs, the file an upgrade replaces under the same name',
+ async () => {
+ expect(await anchorReportedByBuiltMcp()).toBe(realpathSync(CLI_ENTRY));
+ },
+ ANCHOR_WAIT_MS + 5_000,
+ );
+});
diff --git a/packages/cli/src/mcp/server-bundle-identity.test.ts b/packages/cli/src/mcp/server-bundle-identity.test.ts
index a9f548a4d..79bb5da81 100644
--- a/packages/cli/src/mcp/server-bundle-identity.test.ts
+++ b/packages/cli/src/mcp/server-bundle-identity.test.ts
@@ -1,5 +1,6 @@
import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
import { ConfigSchema } from '@inkeep/open-knowledge-server';
import { afterEach, expect, test, vi } from 'vitest';
import type { BundleIdentityState, BundleIdentityWatcherDeps } from './bundle-identity.ts';
@@ -73,6 +74,7 @@ test.for([false, true])(
handle = await startGlobalMcpServer({
startupCwd: root,
startupConfig: ConfigSchema.parse({}),
+ bundleAnchorPath: fileURLToPath(new URL('./server.ts', import.meta.url)),
});
const detect = observation.detect;
if (detect === undefined) throw new Error('Bundle watcher was not registered');
diff --git a/packages/cli/src/mcp/server.ts b/packages/cli/src/mcp/server.ts
index eba60d438..a570116a3 100644
--- a/packages/cli/src/mcp/server.ts
+++ b/packages/cli/src/mcp/server.ts
@@ -37,8 +37,6 @@ import { attachLifecycleLogging } from './lifecycle-logging.ts';
import { parseSpawnTimeoutEnv, resolveMcpHttpUrl, resolveMcpKeepaliveWsUrl } from './shim.ts';
import { createMcpStderrMirror } from './stderr-mirror.ts';
-const BUNDLE_IDENTITY_ANCHOR = fileURLToPath(import.meta.url);
-
const execFileAsync = promisify(execFile);
export async function countWorktrees(dir: string): Promise<number> {
@@ -59,6 +57,7 @@ export async function countWorktrees(dir: string): Promise<number> {
interface StartGlobalMcpServerOptions {
startupCwd: string;
startupConfig: Config;
+ bundleAnchorPath: string | undefined;
spawnTimeoutMs?: number;
envAutoStart?: string;
}
@@ -346,8 +345,12 @@ export async function startGlobalMcpServer(
stdin: process.stdin,
});
- if (process.platform === 'darwin') {
- const bootIdentity = captureBootIdentity(BUNDLE_IDENTITY_ANCHOR, {
+ const bundleAnchorPath = process.platform === 'darwin' ? opts.bundleAnchorPath : undefined;
+ if (process.platform === 'darwin' && bundleAnchorPath === undefined) {
+ stderr.write('[mcp] bundle identity watcher off: no CLI entry path was recorded\n');
+ }
+ if (bundleAnchorPath !== undefined) {
+ const bootIdentity = captureBootIdentity(bundleAnchorPath, {
realpathSync,
statInoSync: (p) => filesystemIdentity(statSync(p, { bigint: true })),
log: (m) => stderr.write(`${m}\n`),
@@ -358,7 +361,7 @@ export async function startGlobalMcpServer(
bundleWatcher = startBundleIdentityWatcher({
detect: () =>
detectBundleIdentity({
- bundleAnchorPath: BUNDLE_IDENTITY_ANCHOR,
+ bundleAnchorPath,
currentInode: capturedInode,
platform: process.platform,
realpath: realpathSync,
diff --git a/packages/cli/tsconfig.json b/packages/cli/tsconfig.json
index 51d366b34..6d8980f2d 100644
--- a/packages/cli/tsconfig.json
+++ b/packages/cli/tsconfig.json
@@ -2,6 +2,7 @@
"extends": "../../tsconfig.json",
"compilerOptions": {
"module": "esnext",
+ "lib": ["ES2024"],
"noEmit": true,
"allowImportingTsExtensions": true
},
diff --git a/packages/cli/tsdown.config.ts b/packages/cli/tsdown.config.ts
index 3bbc9f679..1020d049e 100644
--- a/packages/cli/tsdown.config.ts
+++ b/packages/cli/tsdown.config.ts
@@ -137,7 +137,7 @@ export default defineConfig([
// `parse-worker` ships as its own entry so the server's parse pool can
// spawn `./parse-worker.mjs` next to dist/cli.mjs at runtime (the
// published install has no node_modules to resolve through).
- entry: { cli: 'src/cli.ts', 'parse-worker': 'src/parse-worker.ts' },
+ entry: { cli: 'src/bin.ts', 'parse-worker': 'src/parse-worker.ts' },
unbundle: false,
format: 'esm',
dts: false,
diff --git a/packages/core/package.json b/packages/core/package.json
index 87e46fa92..634423551 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -287,6 +287,18 @@
"types": "./dist/constants-native-menu-labels.d.mts",
"default": "./dist/constants-native-menu-labels.mjs"
},
+ "./constants/ok-dir": {
+ "@inkeep/source": "./src/constants/ok-dir.ts",
+ "development": "./src/constants/ok-dir.ts",
+ "types": "./dist/constants-ok-dir.d.mts",
+ "default": "./dist/constants-ok-dir.mjs"
+ },
+ "./constants/ok-user-home": {
+ "@inkeep/source": "./src/constants/ok-user-home.ts",
+ "development": "./src/constants/ok-user-home.ts",
+ "types": "./dist/constants-ok-user-home.d.mts",
+ "default": "./dist/constants-ok-user-home.mjs"
+ },
"./constants/preview-embed-starters": {
"@inkeep/source": "./src/constants/preview-embed-starters.ts",
"development": "./src/constants/preview-embed-starters.ts",
@@ -683,6 +695,12 @@
"types": "./dist/uninstall-bridge.d.mts",
"default": "./dist/uninstall-bridge.mjs"
},
+ "./util/atomic-yaml-write": {
+ "@inkeep/source": "./src/util/atomic-yaml-write.ts",
+ "development": "./src/util/atomic-yaml-write.ts",
+ "types": "./dist/util-atomic-yaml-write.d.mts",
+ "default": "./dist/util-atomic-yaml-write.mjs"
+ },
"./util/doc-name": {
"@inkeep/source": "./src/util/doc-name.ts",
"development": "./src/util/doc-name.ts",
diff --git a/packages/core/tests/contract/module-subpaths.test.ts b/packages/core/tests/contract/module-subpaths.test.ts
index 238b5a9be..e65f394f8 100644
--- a/packages/core/tests/contract/module-subpaths.test.ts
+++ b/packages/core/tests/contract/module-subpaths.test.ts
@@ -33,6 +33,8 @@ import * as constantsManualUpdateCheckSubpath from '@inkeep/open-knowledge-core/
import * as constantsMcpSubpath from '@inkeep/open-knowledge-core/constants/mcp';
import * as constantsMenuLabelsSubpath from '@inkeep/open-knowledge-core/constants/menu-labels';
import * as constantsNativeMenuLabelsSubpath from '@inkeep/open-knowledge-core/constants/native-menu-labels';
+import * as constantsOkDirSubpath from '@inkeep/open-knowledge-core/constants/ok-dir';
+import * as constantsOkUserHomeSubpath from '@inkeep/open-knowledge-core/constants/ok-user-home';
import * as constantsPreviewEmbedStartersSubpath from '@inkeep/open-knowledge-core/constants/preview-embed-starters';
import * as constantsPreviewThemeTokensSubpath from '@inkeep/open-knowledge-core/constants/preview-theme-tokens';
import * as constantsProductSubpath from '@inkeep/open-knowledge-core/constants/product';
@@ -84,6 +86,7 @@ import * as schemasApiSubpath from '@inkeep/open-knowledge-core/schemas/api';
import * as schemasCc1Subpath from '@inkeep/open-knowledge-core/schemas/cc1';
import * as searchWorkspaceSearchSubpath from '@inkeep/open-knowledge-core/search/workspace-search';
import * as seedPlanWorkSubpath from '@inkeep/open-knowledge-core/seed-plan-work';
+import * as serverBarrel from '@inkeep/open-knowledge-core/server';
import * as sharingSubpath from '@inkeep/open-knowledge-core/sharing';
import * as skillTargetsSchemaSubpath from '@inkeep/open-knowledge-core/skill-targets/schema';
import * as skillsCatalogSchemaSubpath from '@inkeep/open-knowledge-core/skills-catalog/schema';
@@ -99,6 +102,7 @@ import * as typesIdentitySubpath from '@inkeep/open-knowledge-core/types/identit
import * as typesPrincipalSubpath from '@inkeep/open-knowledge-core/types/principal';
import * as typesTimelineSubpath from '@inkeep/open-knowledge-core/types/timeline';
import * as uninstallBridgeSubpath from '@inkeep/open-knowledge-core/uninstall-bridge';
+import * as utilAtomicYamlWriteSubpath from '@inkeep/open-knowledge-core/util/atomic-yaml-write';
import * as utilDocNameSubpath from '@inkeep/open-knowledge-core/util/doc-name';
import * as utilsAssetHrefSubpath from '@inkeep/open-knowledge-core/utils/asset-href';
import * as utilsChunkedInsertSubpath from '@inkeep/open-knowledge-core/utils/chunked-insert';
@@ -177,6 +181,7 @@ const MODULE_SUBPATHS: Record<string, object> = {
'./constants/mcp': constantsMcpSubpath,
'./constants/menu-labels': constantsMenuLabelsSubpath,
'./constants/native-menu-labels': constantsNativeMenuLabelsSubpath,
+ './constants/ok-dir': constantsOkDirSubpath,
'./constants/preview-embed-starters': constantsPreviewEmbedStartersSubpath,
'./constants/preview-theme-tokens': constantsPreviewThemeTokensSubpath,
'./constants/product': constantsProductSubpath,
@@ -270,23 +275,31 @@ const MODULE_SUBPATHS: Record<string, object> = {
'./utils/youtube-embed': utilsYoutubeEmbedSubpath,
};
+const SERVER_MODULE_SUBPATHS: Record<string, object> = {
+ './constants/ok-user-home': constantsOkUserHomeSubpath,
+ './util/atomic-yaml-write': utilAtomicYamlWriteSubpath,
+};
+
const CONDITION_ORDER = ['@inkeep/source', 'development', 'types', 'default'];
const packageJson: { exports: Record<string, Record<string, string>> } = JSON.parse(
readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
);
+const MODULE_SUBPATH_KEYS = Object.keys({ ...MODULE_SUBPATHS, ...SERVER_MODULE_SUBPATHS });
+
const rootBindings = new Map(Object.entries(root));
+const serverBindings = new Map(Object.entries(serverBarrel));
describe('per-module core subpaths', () => {
test('every export key beside the pre-existing entries is imported by this contract', () => {
const declared = Object.keys(packageJson.exports).filter(
(key) => !PRE_EXISTING_KEYS.includes(key),
);
- expect(Object.keys(MODULE_SUBPATHS).sort()).toEqual(declared.sort());
+ expect(MODULE_SUBPATH_KEYS.toSorted()).toEqual(declared.toSorted());
});
- test.each(Object.keys(MODULE_SUBPATHS))(
+ test.each(MODULE_SUBPATH_KEYS)(
'%s points its conditions at the module its name implies',
(key) => {
const conditions = packageJson.exports[key];
@@ -314,4 +327,16 @@ describe('per-module core subpaths', () => {
if (bindings.length > 0) expect(shared.length).toBeGreaterThan(0);
},
);
+
+ test.each(Object.entries(SERVER_MODULE_SUBPATHS))(
+ '%s serves the same runtime bindings as the ./server barrel',
+ (_key, namespace) => {
+ const shared = Object.entries(namespace).filter(([name]) => serverBindings.has(name));
+ const divergent = shared
+ .filter(([name, value]) => value !== serverBindings.get(name))
+ .map(([name]) => name);
+ expect(divergent).toEqual([]);
+ expect(shared.length).toBeGreaterThan(0);
+ },
+ );
});
diff --git a/packages/core/tests/contract/subpath-types/consumer.ts b/packages/core/tests/contract/subpath-types/consumer.ts
index ae2381e56..83d60af78 100644
--- a/packages/core/tests/contract/subpath-types/consumer.ts
+++ b/packages/core/tests/contract/subpath-types/consumer.ts
@@ -205,6 +205,11 @@ export type {
OPEN_KNOWLEDGE_GITHUB_URL,
} from '@inkeep/open-knowledge-core/constants/menu-labels';
export type { NativeMenuLabelKey } from '@inkeep/open-knowledge-core/constants/native-menu-labels';
+export type {
+ OK_USER_HOME_AUTH_FILE,
+ okUserHomeDisplayPath,
+} from '@inkeep/open-knowledge-core/constants/ok-dir';
+export type { okUserHomeDir } from '@inkeep/open-knowledge-core/constants/ok-user-home';
export type {
PREVIEW_EMBED_STARTERS,
PreviewEmbedStarter,
@@ -758,6 +763,10 @@ export type {
UninstallProjectRow,
UninstallScreenSpec,
} from '@inkeep/open-knowledge-core/uninstall-bridge';
+export type {
+ atomicWriteFile,
+ atomicWriteFileSync,
+} from '@inkeep/open-knowledge-core/util/atomic-yaml-write';
export type {
isHiddenDocName,
isProjectSkillBundlePath,
diff --git a/packages/core/tsdown.config.ts b/packages/core/tsdown.config.ts
index 1cb7f9042..3826fd898 100644
--- a/packages/core/tsdown.config.ts
+++ b/packages/core/tsdown.config.ts
@@ -48,6 +48,8 @@ const entry = {
'constants-mcp': 'src/constants/mcp.ts',
'constants-menu-labels': 'src/constants/menu-labels.ts',
'constants-native-menu-labels': 'src/constants/native-menu-labels.ts',
+ 'constants-ok-dir': 'src/constants/ok-dir.ts',
+ 'constants-ok-user-home': 'src/constants/ok-user-home.ts',
'constants-preview-embed-starters': 'src/constants/preview-embed-starters.ts',
'constants-preview-theme-tokens': 'src/constants/preview-theme-tokens.ts',
'constants-product': 'src/constants/product.ts',
@@ -114,6 +116,7 @@ const entry = {
'types-principal': 'src/types/principal.ts',
'types-timeline': 'src/types/timeline.ts',
'uninstall-bridge': 'src/uninstall-bridge.ts',
+ 'util-atomic-yaml-write': 'src/util/atomic-yaml-write.ts',
'util-doc-name': 'src/util/doc-name.ts',
'utils-asset-href': 'src/utils/asset-href.ts',
'utils-chunked-insert': 'src/utils/chunked-insert.ts',
diff --git a/packages/desktop/tests/smoke/_helpers/stale-build-guard.ts b/packages/desktop/tests/smoke/_helpers/stale-build-guard.ts
index 64951abb8..e6abd634a 100644
--- a/packages/desktop/tests/smoke/_helpers/stale-build-guard.ts
+++ b/packages/desktop/tests/smoke/_helpers/stale-build-guard.ts
@@ -70,7 +70,10 @@ const CHECKS: BuildArtifactCheck[] = [
{
name: '@inkeep/open-knowledge CLI executable',
out: resolve(DESKTOP_PKG, '..', 'cli', 'dist', 'cli.mjs'),
- srcs: [resolve(DESKTOP_PKG, '..', 'cli', 'src', 'cli.ts')],
+ srcs: [
+ resolve(DESKTOP_PKG, '..', 'cli', 'src', 'bin.ts'),
+ resolve(DESKTOP_PKG, '..', 'cli', 'src', 'cli.ts'),
+ ],
},
];
diff --git a/packages/server/package.json b/packages/server/package.json
index 671c24223..ef49ef9b2 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -16,6 +16,18 @@
"development": "./src/parse-worker.ts",
"types": "./dist/parse-worker.d.mts",
"default": "./dist/parse-worker.mjs"
+ },
+ "./file-logger": {
+ "@inkeep/source": "./src/file-logger.ts",
+ "development": "./src/file-logger.ts",
+ "types": "./dist/file-logger.d.mts",
+ "default": "./dist/file-logger.mjs"
+ },
+ "./fs/find-project-root": {
+ "@inkeep/source": "./src/fs/find-project-root.ts",
+ "development": "./src/fs/find-project-root.ts",
+ "types": "./dist/fs-find-project-root.d.mts",
+ "default": "./dist/fs-find-project-root.mjs"
}
},
"files": [
diff --git a/packages/server/src/file-logger.ts b/packages/server/src/file-logger.ts
index d22b5041f..48ffcd486 100644
--- a/packages/server/src/file-logger.ts
+++ b/packages/server/src/file-logger.ts
@@ -1,6 +1,6 @@
import { mkdirSync, readdirSync, renameSync, statSync, unlinkSync } from 'node:fs';
import { join } from 'node:path';
-import { okUserHomeDir } from '@inkeep/open-knowledge-core/server';
+import { okUserHomeDir } from '@inkeep/open-knowledge-core/constants/ok-user-home';
import type { LoggerOptions, Logger as PinoLoggerInstance } from 'pino';
import pino from 'pino';
diff --git a/packages/server/src/fs/find-project-root.ts b/packages/server/src/fs/find-project-root.ts
index 82ccd377e..a99014b22 100644
--- a/packages/server/src/fs/find-project-root.ts
+++ b/packages/server/src/fs/find-project-root.ts
@@ -1,6 +1,6 @@
import { statSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
-import { OK_PROJECT_MARKER } from '@inkeep/open-knowledge-core';
+import { OK_PROJECT_MARKER } from '@inkeep/open-knowledge-core/constants/ok-dir';
const ANCESTOR_WALK_DEPTH_LIMIT = 30;
diff --git a/packages/server/src/parse-worker-bundle.uncached.test.ts b/packages/server/src/parse-worker-bundle.uncached.test.ts
index c6d369652..fe0dbbf27 100644
--- a/packages/server/src/parse-worker-bundle.uncached.test.ts
+++ b/packages/server/src/parse-worker-bundle.uncached.test.ts
@@ -20,7 +20,7 @@ describe('worker entry ships in every bundle shape', () => {
Object.hasOwn(config.entry, 'cli'),
);
expect(standalone?.entry).toMatchObject({
- cli: 'src/cli.ts',
+ cli: 'src/bin.ts',
'parse-worker': 'src/parse-worker.ts',
});
});
diff --git a/packages/server/tsdown.config.ts b/packages/server/tsdown.config.ts
index 3eb40ed2a..6a6f80e08 100644
--- a/packages/server/tsdown.config.ts
+++ b/packages/server/tsdown.config.ts
@@ -18,7 +18,12 @@ export default defineConfig({
// worker_threads file next to the importing bundle (`./parse-worker.mjs`
// sibling probe), so inlining it into index.mjs would leave no file to
// spawn in dist-based installs.
- entry: { index: 'src/index.ts', 'parse-worker': 'src/parse-worker.ts' },
+ entry: {
+ index: 'src/index.ts',
+ 'parse-worker': 'src/parse-worker.ts',
+ 'file-logger': 'src/file-logger.ts',
+ 'fs-find-project-root': 'src/fs/find-project-root.ts',
+ },
unbundle: false,
format: 'esm',
dts: { tsconfig: 'tsconfig.build.json' },