Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(cli): Linux CLI e2e CI smoke + ok auth status backend field (#1712)

miles-kt-inkeep99be633f7741
diff --git a/.changeset/cli-auth-status-backend-field.md b/.changeset/cli-auth-status-backend-field.md
new file mode 100644
index 000000000..df7e3768c
--- /dev/null
+++ b/.changeset/cli-auth-status-backend-field.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+`ok auth status --json` now includes a `backend` field naming where credentials are stored — `keyring` (the OS keychain) or `file` (`~/.ok/auth.yml`). The field appears in every JSON status shape, including when you are not logged in, so you can confirm which storage backend is active without a stored token. Human-readable (non-`--json`) output is unchanged.
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 6d8225817..91c166733 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -41,6 +41,7 @@
"build": "bun run build:cli && bun run build:assets",
"postinstall": "node scripts/postinstall.mjs",
"test": "bun run build:schema && bun test",
+ "test:e2e:cli": "bun test ./tests/e2e/cli-linux-e2e.ts",
"typecheck": "tsc --noEmit",
"prepublishOnly": "bash ../../scripts/check-notices-clean.sh && bun run build"
},
diff --git a/packages/cli/src/commands/auth/status.test.ts b/packages/cli/src/commands/auth/status.test.ts
index 898815fab..6d1744456 100644
--- a/packages/cli/src/commands/auth/status.test.ts
+++ b/packages/cli/src/commands/auth/status.test.ts
@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { GhDetectResult } from '../../auth/gh-detect.ts';
import { FileBackend } from '../../auth/token-store.ts';
-import { resolveStatusSource } from './status.ts';
+import { buildStatusPayload, resolveStatusSource } from './status.ts';
function makeStore(tmpDir: string) {
return new FileBackend(join(tmpDir, 'auth.yml'));
@@ -88,3 +88,47 @@ describe('resolveStatusSource', () => {
expect(seen).toEqual(['ghe.example.com']);
});
});
+
+describe('buildStatusPayload', () => {
+ test('surfaces the active backend when unauthenticated (no token) — the headless-Linux probe shape', () => {
+ expect(buildStatusPayload('github.com', 'file', { authenticated: false })).toEqual({
+ type: 'status',
+ host: 'github.com',
+ backend: 'file',
+ authenticated: false,
+ });
+ });
+
+ test('surfaces the active backend when authenticated', () => {
+ expect(
+ buildStatusPayload('github.com', 'keyring', {
+ authenticated: true,
+ tier: 'B',
+ login: 'alice',
+ name: 'Alice',
+ email: '[email protected]',
+ }),
+ ).toEqual({
+ type: 'status',
+ host: 'github.com',
+ backend: 'keyring',
+ authenticated: true,
+ tier: 'B',
+ login: 'alice',
+ name: 'Alice',
+ email: '[email protected]',
+ });
+ });
+
+ test('surfaces the active backend alongside an invalid-token error', () => {
+ expect(
+ buildStatusPayload('github.com', 'file', { authenticated: false, error: 'token invalid' }),
+ ).toEqual({
+ type: 'status',
+ host: 'github.com',
+ backend: 'file',
+ authenticated: false,
+ error: 'token invalid',
+ });
+ });
+});
diff --git a/packages/cli/src/commands/auth/status.ts b/packages/cli/src/commands/auth/status.ts
index 5f661785d..d80b059c4 100644
--- a/packages/cli/src/commands/auth/status.ts
+++ b/packages/cli/src/commands/auth/status.ts
@@ -23,15 +23,37 @@ export async function resolveStatusSource(
return { tier: entry.gitProtocol === 'ssh' ? 'C' : 'B', token: entry.token };
}
+export type StatusOutcome =
+ | { authenticated: false }
+ | { authenticated: false; error: string }
+ | {
+ authenticated: true;
+ tier: 'A' | 'B' | 'C';
+ login: string;
+ name: string | null;
+ email: string | null;
+ };
+
+export function buildStatusPayload(
+ host: string,
+ backend: TokenStore['backend'],
+ outcome: StatusOutcome,
+): Record<string, unknown> {
+ return { type: 'status', host, backend, ...outcome };
+}
+
async function runStatus(opts: StatusOptions, tokenStore: TokenStore): Promise<void> {
const { host, json } = opts;
validateGitHubHost(host);
+ const backend = tokenStore.backend;
const source = await resolveStatusSource(host, tokenStore);
if (source.tier === 'none') {
if (json) {
- process.stdout.write(`${JSON.stringify({ type: 'status', host, authenticated: false })}\n`);
+ process.stdout.write(
+ `${JSON.stringify(buildStatusPayload(host, backend, { authenticated: false }))}\n`,
+ );
} else {
process.stderr.write(`Not logged in to ${host}\n`);
}
@@ -45,15 +67,15 @@ async function runStatus(opts: StatusOptions, tokenStore: TokenStore): Promise<v
const { data } = await octokit.users.getAuthenticated();
if (json) {
process.stdout.write(
- `${JSON.stringify({
- type: 'status',
- host,
- authenticated: true,
- tier: source.tier,
- login: data.login,
- name: data.name,
- email: data.email,
- })}\n`,
+ `${JSON.stringify(
+ buildStatusPayload(host, backend, {
+ authenticated: true,
+ tier: source.tier,
+ login: data.login,
+ name: data.name,
+ email: data.email,
+ }),
+ )}\n`,
);
} else {
process.stderr.write(`✓ Logged in as ${data.login} on ${host}\n`);
@@ -61,8 +83,9 @@ async function runStatus(opts: StatusOptions, tokenStore: TokenStore): Promise<v
} catch {
if (json) {
process.stdout.write(
- JSON.stringify({ type: 'status', host, authenticated: false, error: 'token invalid' }) +
- '\n',
+ `${JSON.stringify(
+ buildStatusPayload(host, backend, { authenticated: false, error: 'token invalid' }),
+ )}\n`,
);
} else {
process.stderr.write(`✗ Token invalid for ${host}\n`);
diff --git a/packages/cli/tests/e2e/cli-linux-e2e.ts b/packages/cli/tests/e2e/cli-linux-e2e.ts
new file mode 100644
index 000000000..531ec3566
--- /dev/null
+++ b/packages/cli/tests/e2e/cli-linux-e2e.ts
@@ -0,0 +1,299 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { type ChildProcess, execFileSync, spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI_PKG_DIR = resolve(HERE, '..', '..'); // packages/cli
+const WORKSPACE_DIST_CLI = join(CLI_PKG_DIR, 'dist', 'cli.mjs');
+const NODE = process.execPath.includes('bun') ? 'node' : process.execPath;
+const SUT_MODE = process.env.OK_E2E_SUT === 'workspace' ? 'workspace' : 'packed';
+const HERMETIC_ENV = { OK_BUNDLE_PROXY: '0' } as const;
+const START_PORT = Number(process.env.OK_E2E_PORT ?? 13581);
+
+interface Harness {
+ cliPath: string; // absolute path to cli.mjs to run under node
+ binShim: string | null; // installed `.bin/ok` shim (packed mode only)
+ installPrefix: string | null; // temp npm prefix (packed mode only)
+ packDest: string | null; // temp dir holding the npm pack tarball (packed mode only)
+ contentDir: string; // git-backed temp content dir
+ lockPath: string; // <contentDir>/.ok/local/server.lock
+ server: ChildProcess | null;
+}
+
+const H: Harness = {
+ cliPath: '',
+ binShim: null,
+ installPrefix: null,
+ packDest: null,
+ contentDir: '',
+ lockPath: '',
+ server: null,
+};
+
+function runOk(
+ args: string[],
+ opts: { cwd?: string; timeoutMs?: number; env?: NodeJS.ProcessEnv } = {},
+): { status: number | null; signal: NodeJS.Signals | null; stdout: string; stderr: string } {
+ const r = spawnSync(NODE, [H.cliPath, ...args], {
+ cwd: opts.cwd ?? H.contentDir,
+ timeout: opts.timeoutMs ?? 30_000,
+ encoding: 'utf8',
+ env: { ...process.env, ...HERMETIC_ENV, ...opts.env },
+ });
+ return {
+ status: r.status,
+ signal: r.signal,
+ stdout: r.stdout ?? '',
+ stderr: r.stderr ?? '',
+ };
+}
+
+async function waitFor(
+ predicate: () => boolean | Promise<boolean>,
+ { timeoutMs = 30_000, intervalMs = 250 } = {},
+): Promise<boolean> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (await predicate()) return true;
+ await new Promise((r) => setTimeout(r, intervalMs));
+ }
+ return false;
+}
+
+function tcpConnect(host: string, port: number, timeoutMs: number): Promise<boolean> {
+ return new Promise((res) => {
+ const sock = connect({ host, port });
+ const done = (ok: boolean) => {
+ sock.destroy();
+ res(ok);
+ };
+ sock.setTimeout(timeoutMs);
+ sock.once('connect', () => done(true));
+ sock.once('timeout', () => done(false));
+ sock.once('error', () => done(false));
+ });
+}
+
+async function tcpReachable(port: number, timeoutMs = 2000): Promise<boolean> {
+ const [v4, v6] = await Promise.all([
+ tcpConnect('127.0.0.1', port, timeoutMs),
+ tcpConnect('::1', port, timeoutMs),
+ ]);
+ return v4 || v6;
+}
+
+function readLockPort(): number | null {
+ if (!existsSync(H.lockPath)) return null;
+ try {
+ const meta = JSON.parse(readFileSync(H.lockPath, 'utf8')) as { port?: number };
+ return typeof meta.port === 'number' ? meta.port : null;
+ } catch {
+ return null;
+ }
+}
+
+beforeAll(async () => {
+ if (!existsSync(WORKSPACE_DIST_CLI)) {
+ throw new Error(
+ `Missing ${WORKSPACE_DIST_CLI}. Run \`bun run build --filter=@inkeep/open-knowledge\` before this smoke.`,
+ );
+ }
+
+ if (SUT_MODE === 'packed') {
+ const packDest = mkdtempSync(join(tmpdir(), 'ok-e2e-pack-'));
+ H.packDest = packDest;
+ const packOut = execFileSync('npm', ['pack', '--silent', '--pack-destination', packDest], {
+ cwd: CLI_PKG_DIR,
+ encoding: 'utf8',
+ }).trim();
+ const tarball = join(packDest, packOut.split('\n').pop()?.trim() ?? '');
+ if (!existsSync(tarball)) throw new Error(`npm pack produced no tarball (got "${packOut}")`);
+
+ H.installPrefix = mkdtempSync(join(tmpdir(), 'ok-e2e-install-'));
+ execFileSync('npm', ['install', '--silent', '--prefix', H.installPrefix, tarball], {
+ encoding: 'utf8',
+ timeout: 180_000,
+ });
+ const installed = join(H.installPrefix, 'node_modules', '@inkeep', 'open-knowledge');
+ H.cliPath = join(installed, 'dist', 'cli.mjs');
+ H.binShim = join(H.installPrefix, 'node_modules', '.bin', 'ok');
+ } else {
+ H.cliPath = WORKSPACE_DIST_CLI;
+ }
+
+ H.contentDir = mkdtempSync(join(tmpdir(), 'ok-e2e-content-'));
+ execFileSync('git', ['init', '-q'], { cwd: H.contentDir });
+ execFileSync('git', ['config', 'user.email', '[email protected]'], { cwd: H.contentDir });
+ execFileSync('git', ['config', 'user.name', 'OK E2E'], { cwd: H.contentDir });
+ H.lockPath = join(H.contentDir, '.ok', 'local', 'server.lock');
+}, 240_000);
+
+afterAll(async () => {
+ if (H.server && H.server.exitCode === null) {
+ H.server.kill('SIGKILL');
+ }
+ for (const dir of [H.contentDir, H.installPrefix, H.packDest]) {
+ if (dir) rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+describe(`CLI Linux e2e (${SUT_MODE} SUT)`, () => {
+ test('1. install fidelity: the bin runs under Node and ships its UI + assets', () => {
+ const v = runOk(['--version'], { cwd: CLI_PKG_DIR });
+ expect(v.status).toBe(0);
+ expect(v.stdout.trim()).toMatch(/\d+\.\d+\.\d+/);
+
+ if (SUT_MODE === 'packed') {
+ const installed = dirname(dirname(H.cliPath)); // .../@inkeep/open-knowledge
+ expect(existsSync(join(installed, 'dist', 'public'))).toBe(true);
+ expect(existsSync(join(installed, 'dist', 'assets', 'skills'))).toBe(true);
+ expect(H.binShim && existsSync(H.binShim)).toBe(true);
+ }
+ });
+
+ test('2. ok init scaffolds .ok/ in the content dir', () => {
+ const r = runOk(['init', '--no-mcp'], { timeoutMs: 60_000 });
+ expect(r.status).toBe(0);
+ expect(existsSync(join(H.contentDir, '.ok'))).toBe(true);
+ });
+
+ test('3. ok start boots, writes server.lock with a port, and serves HTTP', async () => {
+ H.server = spawn(NODE, [H.cliPath, 'start', '--port', String(START_PORT)], {
+ cwd: H.contentDir,
+ env: { ...process.env, ...HERMETIC_ENV },
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ let serverLog = '';
+ H.server.stdout?.on('data', (d) => {
+ serverLog += d;
+ });
+ H.server.stderr?.on('data', (d) => {
+ serverLog += d;
+ });
+
+ const lockReady = await waitFor(() => readLockPort() !== null, { timeoutMs: 45_000 });
+ const lockState = !existsSync(H.lockPath)
+ ? 'lock file never appeared'
+ : `lock file exists but unreadable: ${readFileSync(H.lockPath, 'utf8').slice(0, 200)}`;
+ expect(lockReady, `${lockState}\nServer log:\n${serverLog}`).toBe(true);
+
+ const port = readLockPort();
+ expect(port).toBe(START_PORT);
+ expect(H.server.exitCode, 'server exited during startup').toBeNull();
+
+ const reachable = await waitFor(() => tcpReachable(port as number), { timeoutMs: 15_000 });
+ expect(reachable, 'server port never accepted a TCP connection').toBe(true);
+ }, 70_000);
+
+ test('4. ok mcp answers a stdio round-trip: tools/list + exec + write + read-back', async () => {
+ const transport = new StdioClientTransport({
+ command: NODE,
+ args: [H.cliPath, 'mcp'],
+ cwd: H.contentDir,
+ env: { ...process.env, ...HERMETIC_ENV } as Record<string, string>,
+ });
+ const client = new Client({ name: 'ok-e2e', version: '0.0.0' });
+ try {
+ await client.connect(transport);
+
+ const tools = await client.listTools();
+ const names = new Set(tools.tools.map((t) => t.name));
+ for (const required of ['exec', 'search', 'write', 'edit']) {
+ expect(names.has(required), `MCP tool "${required}" missing`).toBe(true);
+ }
+
+ const marker = `e2e-marker-${START_PORT}`;
+ const writeRes = (await client.callTool({
+ name: 'write',
+ arguments: {
+ cwd: H.contentDir,
+ document: { path: 'e2e/smoke', content: `# Smoke\n\n${marker}\n` },
+ },
+ })) as { isError?: boolean };
+ expect(writeRes.isError ?? false).toBe(false);
+
+ const catRes = (await client.callTool({
+ name: 'exec',
+ arguments: { command: 'cat e2e/smoke.md', cwd: H.contentDir },
+ })) as { isError?: boolean; content?: Array<{ type: string; text?: string }> };
+ expect(catRes.isError ?? false).toBe(false);
+ const catText = (catRes.content ?? []).map((c) => c.text ?? '').join('\n');
+ expect(catText).toContain(marker);
+ } finally {
+ await client.close().catch(() => {});
+ }
+ }, 60_000);
+
+ test('5. file-watcher ingests an external disk write (inotify on Linux)', async () => {
+ const marker = `okwatchprobe${START_PORT}`;
+ writeFileSync(
+ join(H.contentDir, `${marker}.md`),
+ `---\ntitle: Watcher Probe\n---\n\n# Watcher Probe\n\n${marker} body sentinel\n`,
+ );
+
+ const transport = new StdioClientTransport({
+ command: NODE,
+ args: [H.cliPath, 'mcp'],
+ cwd: H.contentDir,
+ env: { ...process.env, ...HERMETIC_ENV } as Record<string, string>,
+ });
+ const client = new Client({ name: 'ok-e2e-watch', version: '0.0.0' });
+ try {
+ await client.connect(transport);
+ const found = await waitFor(
+ async () => {
+ const res = (await client.callTool({
+ name: 'search',
+ arguments: { query: marker, cwd: H.contentDir },
+ })) as { isError?: boolean; content?: Array<{ type: string; text?: string }> };
+ if (res.isError) return false;
+ const text = (res.content ?? []).map((c) => c.text ?? '').join('\n');
+ return text.includes(marker);
+ },
+ { timeoutMs: 20_000, intervalMs: 500 },
+ );
+ expect(found, 'file-watcher never surfaced the disk-dropped doc via search').toBe(true);
+ } finally {
+ await client.close().catch(() => {});
+ }
+ }, 40_000);
+
+ test('6. keyring resolves without hanging and `ok auth status` names the backend', () => {
+ const headlessEnv = { DBUS_SESSION_BUS_ADDRESS: '', XDG_RUNTIME_DIR: '' };
+ const r = runOk(['auth', 'status', '--json'], { timeoutMs: 15_000, env: headlessEnv });
+
+ expect(r.signal, `ok auth status hung (keyring D-Bus trap?). stderr:\n${r.stderr}`).toBeNull();
+
+ const line = r.stdout.trim().split('\n').filter(Boolean).pop() ?? '{}';
+ let payload: { backend?: string };
+ try {
+ payload = JSON.parse(line) as { backend?: string };
+ } catch {
+ throw new Error(
+ `Failed to parse JSON from \`ok auth status --json\`.\nLast stdout line: ${line}\nFull stdout:\n${r.stdout}\nstderr:\n${r.stderr}`,
+ );
+ }
+ expect(['keyring', 'file']).toContain(payload.backend);
+ });
+
+ test('7. shutdown releases the server lock', async () => {
+ expect(H.server).not.toBeNull();
+ const server = H.server as ChildProcess;
+ const exited = new Promise<void>((res) => server.once('exit', () => res()));
+ server.kill('SIGTERM');
+ const cleanExit = await Promise.race([
+ exited.then(() => true),
+ new Promise<boolean>((r) => setTimeout(() => r(false), 10_000)),
+ ]);
+ expect(cleanExit, 'server did not exit within 10s of SIGTERM').toBe(true);
+
+ const lockGone = await waitFor(() => !existsSync(H.lockPath), { timeoutMs: 5_000 });
+ expect(lockGone, 'server.lock was not released on shutdown').toBe(true);
+ }, 20_000);
+});