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