Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix: provision the ephemeral project root in ok start (PRD-8210) (#3756)

mike-inkeep670c38cc0dfb
diff --git a/.changeset/single-file-ephemeral-projectdir.md b/.changeset/single-file-ephemeral-projectdir.md
new file mode 100644
index 000000000..213285498
--- /dev/null
+++ b/.changeset/single-file-ephemeral-projectdir.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+`ok start --single-file` no longer deletes the directory it runs in. Previously, running it from inside an initialized OK project silently adopted that project as the session's "throwaway" root and recursively deleted it — content, `.git`, everything — when idle shutdown fired; from a non-project directory it refused to start with `MissingOkConfigError`. The command now provisions its own temp project root when `--project-dir` is absent (removing it on shutdown), requires any provided `--project-dir` to be a throwaway `ok-ephemeral-*` temp dir (seeding the synthesized config into it when bare; anything else — an ordinary directory or a real initialized project — is refused with a clear message instead of written to), and the ephemeral cleanup refuses to remove any directory that does not resolve to an `ok-ephemeral-*` temp dir — symlinks included — so no flag combination can point the reap at real data. `--project-dir` without `--single-file` is now rejected instead of silently ignored, ephemeral sessions no longer inherit the enclosing project's `server.*` settings — the user-global `~/.ok/global.yml` layer still applies, matching `ok <file>`, and flags and env still override — and both flags are hidden from `ok start --help` — they are the desktop spawn contract, and `ok <file>` is the supported way to open one file.
diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.ts
index 65a56d95c..e8080cdb9 100644
--- a/packages/cli/src/commands/start.test.ts
+++ b/packages/cli/src/commands/start.test.ts
@@ -1,9 +1,17 @@
import type { spawn as NativeSpawn } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { request as httpRequest } from 'node:http';
import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { idleShutdownToMs } from '@inkeep/open-knowledge-core';
import { type Config, ConfigSchema } from '@inkeep/open-knowledge-server';
@@ -12,9 +20,11 @@ import {
type BootedStartServer,
bootStartServer,
deriveServerProcessTitle,
+ EphemeralProjectDirNotThrowawayError,
formatServerReuseNotice,
formatShutdownNotice,
isLoopbackHost,
+ isReapableEphemeralProjectDir,
isServerLockCollision,
OkDirMissingError,
parseExternalUrlFlag,
@@ -23,6 +33,7 @@ import {
resolveBundledReactShellDir,
resolveHost,
resolveServerReuse,
+ resolveStartConfig,
resolveStartConsoleLevel,
resolveStartShellDir,
shouldOpenBrowser,
@@ -788,6 +799,163 @@ describe('bootStartServer (integration)', () => {
await rm(shellDir, { recursive: true, force: true });
}
});
+
+ // --- ephemeral single-file: bootStartServer establishes the root it consumes ---
+
+ test('--single-file with no projectDir self-provisions a throwaway root — cwd is never consumed', async () => {
+ // cwd (tmpDir) is an initialized project (beforeEach seeds .ok/config.yml)
+ // — exactly the shape the old cwd fallback consumed as the "throwaway"
+ // ephemeral root and then recursively deleted on idle shutdown.
+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
+ const sentinel = join(tmpDir, 'IMPORTANT.md');
+ writeFileSync(sentinel, 'keep me', 'utf-8');
+ try {
+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
+ booted = await bootStartServer({
+ config: makeTestConfig(),
+ cwd: tmpDir,
+ host: TEST_HOST,
+ skipAutoInit: true,
+ singleFile: join(looseDir, 'note.md'),
+ });
+ await booted.ready;
+
+ // The ephemeral root is a fresh ok-ephemeral-* temp dir, not cwd.
+ const ephemeralRoot = dirname(dirname(booted.lockDir)); // lockDir = <projectDir>/.ok/local
+ expect(ephemeralRoot).not.toBe(tmpDir);
+ expect(booted.lockDir.startsWith(tmpDir)).toBe(false);
+ expect(basename(ephemeralRoot).startsWith('ok-ephemeral-')).toBe(true);
+ expect(existsSync(join(ephemeralRoot, '.ok', 'config.yml'))).toBe(true);
+
+ // destroy() reaps the self-provisioned root; the cwd project survives.
+ await booted.destroy();
+ booted = null;
+ expect(existsSync(ephemeralRoot)).toBe(false);
+ expect(existsSync(sentinel)).toBe(true);
+ expect(existsSync(join(tmpDir, '.ok', 'config.yml'))).toBe(true);
+ } finally {
+ await rm(looseDir, { recursive: true, force: true });
+ }
+ });
+
+ test('--single-file with a provided empty --project-dir seeds the synthesized config and boots', async () => {
+ // The parent-spawn ABI hands over a pre-created dir; a directly-typed
+ // --project-dir may be bare. Boot seeds the missing config instead of
+ // refusing with MissingOkConfigError.
+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
+ const providedDir = await mkdtemp(resolve(tmpdir(), 'ok-ephemeral-'));
+ try {
+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
+ booted = await bootStartServer({
+ config: makeTestConfig(),
+ cwd: tmpDir,
+ host: TEST_HOST,
+ skipAutoInit: true,
+ singleFile: join(looseDir, 'note.md'),
+ projectDir: providedDir,
+ });
+ await booted.ready;
+ expect(existsSync(join(providedDir, '.ok', 'config.yml'))).toBe(true);
+ expect(existsSync(join(providedDir, '.ok', '.gitignore'))).toBe(true);
+
+ // Parent-provided: destroy leaves the dir for the parent to remove.
+ await booted.destroy();
+ booted = null;
+ expect(existsSync(providedDir)).toBe(true);
+ } finally {
+ await rm(looseDir, { recursive: true, force: true });
+ await rm(providedDir, { recursive: true, force: true });
+ }
+ });
+
+ test('--single-file with an ordinary bare --project-dir is refused, not seeded', async () => {
+ // Only the sanctioned throwaway shape gets the synthesized config. An
+ // arbitrary user directory must stay untouched: no .ok/ written, no boot.
+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
+ const ordinaryDir = await mkdtemp(resolve(tmpdir(), 'ok-start-ordinary-'));
+ try {
+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
+ await expect(
+ bootStartServer({
+ config: makeTestConfig(),
+ cwd: tmpDir,
+ host: TEST_HOST,
+ skipAutoInit: true,
+ singleFile: join(looseDir, 'note.md'),
+ projectDir: ordinaryDir,
+ }),
+ ).rejects.toThrow(EphemeralProjectDirNotThrowawayError);
+ expect(existsSync(join(ordinaryDir, '.ok'))).toBe(false);
+ } finally {
+ await rm(looseDir, { recursive: true, force: true });
+ await rm(ordinaryDir, { recursive: true, force: true });
+ }
+ });
+
+ test('--single-file with an initialized real project as --project-dir is refused untouched', async () => {
+ // The highest-risk input class: a real project has a config, so it passes
+ // the boot config gate — the throwaway check must gate it BEFORE that,
+ // or the ephemeral session scatters .ok/local state into a real project.
+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
+ const realProject = await mkdtemp(resolve(tmpdir(), 'ok-start-realproj-'));
+ try {
+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
+ mkdirSync(join(realProject, '.ok'), { recursive: true });
+ writeFileSync(join(realProject, '.ok', 'config.yml'), 'content:\n dir: .\n', 'utf-8');
+ writeFileSync(join(realProject, 'KEEP.md'), 'keep me', 'utf-8');
+ await expect(
+ bootStartServer({
+ config: makeTestConfig(),
+ cwd: tmpDir,
+ host: TEST_HOST,
+ skipAutoInit: true,
+ singleFile: join(looseDir, 'note.md'),
+ projectDir: realProject,
+ }),
+ ).rejects.toThrow(EphemeralProjectDirNotThrowawayError);
+ expect(existsSync(join(realProject, 'KEEP.md'))).toBe(true);
+ expect(existsSync(join(realProject, '.ok', 'local'))).toBe(false);
+ } finally {
+ await rm(looseDir, { recursive: true, force: true });
+ await rm(realProject, { recursive: true, force: true });
+ }
+ });
+
+ test('boot failure after self-provisioning reaps the freshly created ephemeral dir', async () => {
+ // Force the failure AFTER the dir is minted by pre-binding the requested
+ // port. TMPDIR scopes the mint to a private root (os.tmpdir() reads env
+ // per call), so the "nothing left behind" assertion cannot race other
+ // suites minting ok-ephemeral-* dirs in the shared temp root.
+ const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
+ const privateTmp = await mkdtemp(resolve(tmpdir(), 'ok-start-privtmp-'));
+ const prevTmpdirEnv = process.env.TMPDIR;
+ const { createServer } = await import('node:http');
+ const blocker = createServer(() => {});
+ await new Promise<void>((r) => blocker.listen(0, '127.0.0.1', () => r()));
+ const addr = blocker.address();
+ const blockedPort = typeof addr === 'object' && addr !== null ? addr.port : 0;
+ try {
+ writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
+ process.env.TMPDIR = privateTmp;
+ await expect(
+ bootStartServer({
+ config: makeTestConfig(),
+ cwd: tmpDir,
+ host: TEST_HOST,
+ skipAutoInit: true,
+ singleFile: join(looseDir, 'note.md'),
+ port: blockedPort,
+ }),
+ ).rejects.toThrow();
+ expect(readdirSync(privateTmp).filter((n) => n.startsWith('ok-ephemeral-'))).toEqual([]);
+ } finally {
+ if (prevTmpdirEnv === undefined) delete process.env.TMPDIR;
+ else process.env.TMPDIR = prevTmpdirEnv;
+ await new Promise<void>((r) => blocker.close(() => r()));
+ await rm(looseDir, { recursive: true, force: true });
+ await rm(privateTmp, { recursive: true, force: true });
+ }
+ });
});
describe('bootStartServer — no auto git-init from ok start (US-004)', () => {
@@ -1135,20 +1303,105 @@ describe('tryDescribeLockCollision', () => {
});
});
+describe('resolveStartConfig (ephemeral config isolation)', () => {
+ test('single-file sessions drop the project config but keep the user-global layer', () => {
+ // The cwd anchor points at whatever project the shell sits in — unrelated
+ // to the loose file. Its server.* settings must not leak into the session,
+ // but the user-global layer must survive (parity with `ok <file>`, whose
+ // loadConfig on the ephemeral root reads user-global first).
+ const projectConfig = ConfigSchema.parse({ server: { port: 4242 } });
+ const userConfig = ConfigSchema.parse({ server: { port: 5151 } });
+ const resolved = resolveStartConfig(projectConfig, '/tmp/note.md', () => userConfig);
+ expect(resolved.server?.port).toBe(5151);
+ expect(resolved).not.toBe(projectConfig);
+ });
+
+ test('plain ok start keeps the loaded project config untouched', () => {
+ const projectConfig = ConfigSchema.parse({ server: { port: 4242 } });
+ let userReads = 0;
+ const resolved = resolveStartConfig(projectConfig, undefined, () => {
+ userReads += 1;
+ return ConfigSchema.parse({});
+ });
+ expect(resolved).toBe(projectConfig);
+ expect(userReads).toBe(0);
+ });
+});
+
+describe('isReapableEphemeralProjectDir', () => {
+ test('accepts a direct ok-ephemeral-* child of os.tmpdir()', () => {
+ expect(isReapableEphemeralProjectDir(join(tmpdir(), 'ok-ephemeral-abc123'))).toBe(true);
+ });
+
+ test('rejects a dir outside the temp root, whatever its name', () => {
+ // The exact shape the cwd-fallback bug produced: a real project handed to
+ // the reap. Containment must refuse it regardless of contents.
+ expect(isReapableEphemeralProjectDir('/Users/someone/my-project')).toBe(false);
+ });
+
+ test('rejects a temp-root child without the ok-ephemeral- prefix', () => {
+ // A user project living directly in the temp dir (common on Linux where
+ // tmpdir() is /tmp) is not reapable — provenance requires the prefix.
+ expect(isReapableEphemeralProjectDir(join(tmpdir(), 'my-scratch-project'))).toBe(false);
+ });
+
+ test('rejects an ok-ephemeral-* dir nested deeper than the temp root', () => {
+ expect(isReapableEphemeralProjectDir(join(tmpdir(), 'nested', 'ok-ephemeral-x'))).toBe(false);
+ });
+
+ test('pierces temp-root symlinks via the injected realpath (macOS /tmp → /private/tmp)', () => {
+ // The whole target is realpath-resolved: a literal '/tmp/ok-ephemeral-x'
+ // matches when realpath maps the /tmp prefix onto the temp root.
+ const realpathFn = (p: string): string =>
+ p === '/tmp' || p.startsWith('/tmp/') ? p.replace(/^\/tmp/, '/private/tmp') : p;
+ expect(
+ isReapableEphemeralProjectDir('/tmp/ok-ephemeral-x', {
+ tmpdirFn: () => '/private/tmp',
+ realpathFn,
+ }),
+ ).toBe(true);
+ });
+
+ test('resolves a symlink leaf: an ok-ephemeral-* link pointing elsewhere is refused', () => {
+ // The predicate canonicalizes the LEAF too — a link named ok-ephemeral-*
+ // must not launder its target into reapability.
+ const targetDir = mkdtempSync(join(tmpdir(), 'ok-start-symtarget-'));
+ const link = join(tmpdir(), `ok-ephemeral-link-${basename(targetDir)}`);
+ symlinkSync(targetDir, link);
+ try {
+ expect(isReapableEphemeralProjectDir(link)).toBe(false);
+ } finally {
+ rmSync(link, { force: true });
+ rmSync(targetDir, { recursive: true, force: true });
+ }
+ });
+
+ test('accepts a real mkdtemp ok-ephemeral-* dir on this OS (symlinked temp prefix and all)', () => {
+ const real = mkdtempSync(join(tmpdir(), 'ok-ephemeral-'));
+ try {
+ expect(isReapableEphemeralProjectDir(real)).toBe(true);
+ } finally {
+ rmSync(real, { recursive: true, force: true });
+ }
+ });
+});
+
describe('withEphemeralTempDirReap', () => {
+ const reapable = join(tmpdir(), 'ok-ephemeral-x');
+
test('runs the inner handler, then removes the temp projectDir', async () => {
const order: string[] = [];
const handler = async () => {
order.push('handler');
};
const removed: string[] = [];
- const wrapped = withEphemeralTempDirReap(handler, '/tmp/ok-ephemeral-x', async (dir) => {
+ const wrapped = withEphemeralTempDirReap(handler, reapable, async (dir) => {
order.push('rm');
removed.push(dir);
});
await wrapped();
expect(order).toEqual(['handler', 'rm']);
- expect(removed).toEqual(['/tmp/ok-ephemeral-x']);
+ expect(removed).toEqual([reapable]);
});
test('swallows a rm failure (best-effort) — the handler still completes', async () => {
@@ -1157,7 +1410,7 @@ describe('withEphemeralTempDirReap', () => {
async () => {
handled = true;
},
- '/tmp/ok-ephemeral-y',
+ reapable,
async () => {
throw new Error('EBUSY');
},
@@ -1165,19 +1418,39 @@ describe('withEphemeralTempDirReap', () => {
await expect(wrapped()).resolves.toBeUndefined();
expect(handled).toBe(true);
});
+
test('reaps the temp dir even when the inner handler throws (finally)', async () => {
const removed: string[] = [];
const wrapped = withEphemeralTempDirReap(
async () => {
throw new Error('destroy failed');
},
- '/tmp/ok-ephemeral-throw',
+ reapable,
async (dir) => {
removed.push(dir);
},
);
await expect(wrapped()).rejects.toThrow('destroy failed');
- expect(removed).toEqual(['/tmp/ok-ephemeral-throw']);
+ expect(removed).toEqual([reapable]);
+ });
+
+ test('REFUSES to rm a non-throwaway target — the containment backstop', async () => {
+ // A real project wired into the ephemeral teardown must be leaked, never
+ // deleted. The handler still runs; only the rm is withheld.
+ const removed: string[] = [];
+ let handled = false;
+ const wrapped = withEphemeralTempDirReap(
+ async () => {
+ handled = true;
+ },
+ '/Users/someone/my-project',
+ async (dir) => {
+ removed.push(dir);
+ },
+ );
+ await wrapped();
+ expect(handled).toBe(true);
+ expect(removed).toEqual([]);
});
});
diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.ts
index f5dad23a3..973a9b1e6 100644
--- a/packages/cli/src/commands/start.ts
+++ b/packages/cli/src/commands/start.ts
@@ -20,10 +20,11 @@
* path the CLI uses, without process-level signal coupling.
*/
import { spawn as nativeSpawn } from 'node:child_process';
-import { existsSync as fsExistsSync } from 'node:fs';
+import { existsSync as fsExistsSync, realpathSync } from 'node:fs';
import { rm } from 'node:fs/promises';
import type { Server as HttpServer } from 'node:http';
-import { basename, resolve as pathResolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { basename, dirname, resolve as pathResolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import {
applyConfigOverlay,
@@ -32,19 +33,22 @@ import {
EnvVarError,
IDLE_SHUTDOWN_DURATION_RE,
idleShutdownToMs,
+ OK_DIR,
resolveEnvConfigLayer,
resolveServerRuntimeConfig,
type ServerRuntimeConfig,
} from '@inkeep/open-knowledge-core';
+import { readConfigSafely, resolveConfigPath } from '@inkeep/open-knowledge-core/server';
import {
type BootedServer,
type Config,
+ EPHEMERAL_PROJECT_DIR_PREFIX,
isProjectRoot,
lockAdvertisesUi,
type PinoLogger,
prepareSingleFileOpen,
} from '@inkeep/open-knowledge-server';
-import { Command, InvalidArgumentError } from 'commander';
+import { Command, InvalidArgumentError, Option } from 'commander';
import { makeLazyEmbeddingsKeyStore } from '../auth/embeddings-key-store.ts';
import { detectGh } from '../auth/gh-detect.ts';
import { makeLazyProbeTokenStore } from '../auth/token-store.ts';
@@ -268,13 +272,89 @@ export class OkDirMissingError extends Error {
}
}
+/**
+ * Thrown by `bootStartServer` when `--single-file` is given a `--project-dir`
+ * that is not the sanctioned throwaway shape (`ok-ephemeral-*` directly under
+ * the OS temp dir) — whether bare or already initialized. Booting with an
+ * ordinary directory as the ephemeral root would write `.ok/` state into a
+ * directory the user may not consider disposable, and the shutdown reap would
+ * then (rightly) decline to clean it up. Refuse up front with the working
+ * alternatives instead.
+ */
+export class EphemeralProjectDirNotThrowawayError extends Error {
+ readonly projectDir: string;
+ constructor(projectDir: string) {
+ super(
+ `--project-dir must be a throwaway ${EPHEMERAL_PROJECT_DIR_PREFIX}* directory under the OS temp dir. ` +
+ `Refusing to write ephemeral session state into ${projectDir}. ` +
+ 'Omit --project-dir to let ok start create (and clean up) its own.',
+ );
+ this.name = 'EphemeralProjectDirNotThrowawayError';
+ this.projectDir = projectDir;
+ }
+}
+
+/**
+ * Provenance check for the destructive ephemeral reap: the CANONICAL target
+ * must be a direct `ok-ephemeral-*` child of `os.tmpdir()` — the exact shape
+ * `createEphemeralProjectDir` mints. The reap recursively deletes its target,
+ * so it must never trust a flag value alone: `--project-dir` is user-reachable,
+ * and an earlier cwd fallback let the reap delete a real project (content,
+ * `.git`, everything) on idle shutdown.
+ *
+ * The whole path is realpath-resolved before the check: a symlinked temp-root
+ * prefix (macOS `/tmp` → `/private/tmp`, `/var` → `/private/var`) still
+ * matches, and a symlink LEAF named `ok-ephemeral-*` resolves to its target,
+ * so a link pointing at a real project fails the check and is refused. When
+ * the leaf does not exist (already reaped), its parent is still resolved and
+ * the literal basename is kept. Any other realpath failure (EACCES, ELOOP,
+ * EIO) fails CLOSED: a path that cannot be trusted is not a reap target.
+ * Never throws. Deps are injectable for tests.
+ */
+export function isReapableEphemeralProjectDir(
+ dir: string,
+ deps: { tmpdirFn?: () => string; realpathFn?: (path: string) => string } = {},
+): boolean {
+ const tmpdirFn = deps.tmpdirFn ?? tmpdir;
+ const realpathFn = deps.realpathFn ?? realpathSync;
+ const canonical = (path: string): string | null => {
+ try {
+ return realpathFn(path);
+ } catch (err) {
+ return (err as NodeJS.ErrnoException).code === 'ENOENT' ? pathResolve(path) : null;
+ }
+ };
+ const literal = pathResolve(dir);
+ let target: string | null;
+ try {
+ target = realpathFn(literal);
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+ const parent = canonical(dirname(literal));
+ target = parent === null ? null : pathResolve(parent, basename(literal));
+ } else {
+ target = null;
+ }
+ }
+ if (target === null) return false;
+ const tmpRoot = canonical(tmpdirFn());
+ if (tmpRoot === null) return false;
+ return dirname(target) === tmpRoot && basename(target).startsWith(EPHEMERAL_PROJECT_DIR_PREFIX);
+}
+
/**
* Wrap an idle-shutdown handler so that, after the server is destroyed, the
* ephemeral session's throwaway temp projectDir is removed. Without this an
* agent- or tab-closed single-file session leaks its temp dir — boot's destroy
* alone releases the locks but leaves the dir on disk. Reaping is best-effort
- * (the dir lives in os.tmpdir and is OS-reaped regardless). `rmFn` is injected
- * for testing.
+ * (the dir lives in os.tmpdir and is OS-reaped regardless). `rmFn` is
+ * injected for testing.
+ *
+ * The reap REFUSES any target that fails `isReapableEphemeralProjectDir` —
+ * this is the containment backstop for a recursive delete of a user-influenced
+ * path, and it must stay in front of every rm this wrapper performs. The
+ * predicate is deliberately NOT injectable: an injection seam here is a
+ * bypass door for the one check standing between a flag value and `rm -rf`.
*/
export function withEphemeralTempDirReap(
handler: () => Promise<void>,
@@ -287,14 +367,22 @@ export function withEphemeralTempDirReap(
} finally {
// `finally` so a throwing handler (e.g. destroy() propagating) still reaps
// the temp dir rather than leaking it.
- try {
- await rmFn(projectDir);
- } catch (err) {
- // best-effort; the dir is in os.tmpdir (OS-reaped) regardless. rm with
- // force already swallows ENOENT, so anything here (EPERM, bad path) is
- // unexpected — log it so leaked dirs are attributable.
+ if (isReapableEphemeralProjectDir(projectDir)) {
+ try {
+ await rmFn(projectDir);
+ } catch (err) {
+ // best-effort; the dir is in os.tmpdir (OS-reaped) regardless. rm with
+ // force already swallows ENOENT, so anything here (EPERM, bad path) is
+ // unexpected — log it so leaked dirs are attributable.
+ process.stderr.write(
+ `[start] ephemeral temp dir reap failed for ${projectDir}: ${err instanceof Error ? err.message : String(err)}\n`,
+ );
+ }
+ } else {
+ // A non-throwaway target means a caller wired a real directory into the
+ // ephemeral teardown — leave it in place rather than delete user data.
process.stderr.write(
- `[start] ephemeral temp dir reap failed for ${projectDir}: ${err instanceof Error ? err.message : String(err)}\n`,
+ `[start] leaving ${projectDir} in place: only ${EPHEMERAL_PROJECT_DIR_PREFIX}* dirs under the OS temp dir are removed on ephemeral teardown\n`,
);
}
}
@@ -498,14 +586,18 @@ interface BootStartServerOptions {
* - boots with `ephemeral: true` + `gitEnabled: false` + MCP unmounted, and
* skips the init-required guard and the reclaim sweeps (no project to
* reclaim).
- * The caller (`runSingleFileBrowserOpen` / the desktop spawn) owns the temp
- * projectDir's lifecycle and removes it on teardown.
+ * With `projectDir` set, the caller (`runSingleFileBrowserOpen` / the desktop
+ * spawn) owns the temp dir's lifecycle and removes it on teardown; without
+ * it, `bootStartServer` creates its own throwaway dir and reaps it on
+ * destroy and idle shutdown.
*/
singleFile?: string;
/**
* Explicit project root, distinct from `cwd`. Only meaningful in the
* ephemeral single-file path, where it is the throwaway temp dir carrying the
- * synthesized `.ok/config.yml`. Defaults to `cwd`.
+ * synthesized `.ok/config.yml` (seeded on boot when missing). When absent in
+ * that path, a fresh temp dir is created — never `cwd`: a real project as the
+ * ephemeral root gets recursively deleted by the idle-shutdown reap.
*/
projectDir?: string;
}
@@ -546,9 +638,16 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Boo
opts.idleThresholdMs === undefined ? DEFAULT_IDLE_THRESHOLD_MS : opts.idleThresholdMs;
const { existsSync, mkdirSync } = await import('node:fs');
- const { basename, dirname } = await import('node:path');
- const { bootServer, getLogger, resolveContentDir, resolveLockDir, waitForServerLockDrain } =
- await import('@inkeep/open-knowledge-server');
+ const { basename, dirname, resolve } = await import('node:path');
+ const {
+ bootServer,
+ createEphemeralProjectDir,
+ getLogger,
+ resolveContentDir,
+ resolveLockDir,
+ seedEphemeralProjectDir,
+ waitForServerLockDrain,
+ } = await import('@inkeep/open-knowledge-server');
const log = opts.log ?? getLogger('start');
@@ -558,7 +657,6 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Boo
// `.ok/` state lives only in the throwaway `projectDir`. The init-required
// guard + reclaim sweeps target a real project — neither applies here.
const ephemeral = opts.singleFile !== undefined;
- const ephemeralProjectDir = opts.projectDir ?? cwd;
// `--single-file` is the desktop→child spawn contract (the desktop passes a
// path already validated by `prepareSingleFileOpen`), but the flag is directly
// reachable. Re-validate to the same typed rejections `ok <file>` gives
@@ -571,6 +669,65 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Boo
const ephemeralContentDir = ephemeralFile ? dirname(ephemeralFile) : undefined;
const ephemeralDocRelPath = ephemeralFile ? basename(ephemeralFile) : undefined;
+ // Establish the ephemeral project root this boot consumes — the invariant is
+ // that whoever boots the ephemeral shape provisions its throwaway projectDir.
+ // A parent-provided `--project-dir` (the desktop / `ok <file>` spawn ABI) is
+ // used as-is, seeded if its synthesized config is missing; with no
+ // `--project-dir`, a fresh temp dir is created HERE and owned by this boot
+ // (reaped on destroy and on idle shutdown). Never fall back to cwd: an
+ // initialized cwd passes the boot config gate and the ephemeral teardown
+ // would then recursively delete a real project on idle shutdown.
+ let ephemeralProjectDir: string | undefined;
+ let ownsEphemeralProjectDir = false;
+ if (ephemeralContentDir !== undefined) {
+ if (opts.projectDir !== undefined) {
+ ephemeralProjectDir = opts.projectDir;
+ // EVERY provided --project-dir must be the sanctioned throwaway shape,
+ // config or no config. Gating only the seeding branch would wave through
+ // an initialized real project (it has a config), boot with it as the
+ // ephemeral root, and scatter `.ok/local/` runtime state into it — the
+ // exact input class the cwd fallback destroyed. Both spawn-ABI producers
+ // pass a `createEphemeralProjectDir` result, which satisfies this.
+ if (!isReapableEphemeralProjectDir(ephemeralProjectDir)) {
+ throw new EphemeralProjectDirNotThrowawayError(ephemeralProjectDir);
+ }
+ if (!existsSync(resolve(ephemeralProjectDir, OK_DIR, 'config.yml'))) {
+ seedEphemeralProjectDir(ephemeralProjectDir, ephemeralContentDir);
+ }
+ } else {
+ ephemeralProjectDir = createEphemeralProjectDir(ephemeralContentDir);
+ ownsEphemeralProjectDir = true;
+ }
+ }
+ // Best-effort cleanup for the self-provisioned dir when boot fails below —
+ // the parent-provided dir stays the parent's to remove. Failures are logged,
+ // not swallowed: this process is the dir's sole owner, so a silent rm
+ // failure would orphan `ok-ephemeral-*` dirs with no diagnostic trail.
+ const reapOwnedEphemeralDir = async (): Promise<void> => {
+ if (!ownsEphemeralProjectDir || ephemeralProjectDir === undefined) return;
+ if (!isReapableEphemeralProjectDir(ephemeralProjectDir)) {
+ // Can only fire if the dir this process minted stopped resolving to the
+ // throwaway shape between mint and teardown — something replaced it
+ // under a running session. Worth a trail, not silence.
+ log.warn(
+ { ephemeralProjectDir },
+ '[start] refusing to reap self-provisioned ephemeral dir: no longer resolves to an ok-ephemeral-* temp dir',
+ );
+ return;
+ }
+ try {
+ await rm(ephemeralProjectDir, { recursive: true, force: true });
+ } catch (err) {
+ log.warn(
+ { err, ephemeralProjectDir },
+ '[start] failed to reap self-provisioned ephemeral temp dir',
+ );
+ }
+ };
+ // `const` capture: `let` narrowing does not survive into the idle-shutdown
+ // closure passed to bootServer below.
+ const reapDirOnIdle = ephemeralProjectDir;
+
if (!ephemeral) {
// Guard: cwd must already be a valid OK project root (`.ok/config.yml`
// exists as a regular file). ok start no longer scaffolds — run `ok init`
@@ -673,95 +830,119 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Boo
// within the predecessor's last seconds. On timeout we proceed anyway and
// let the acquire collide: a wedged teardown should fail loud, not spawn a
// duplicate.
- {
- const drainLockDir = resolveLockDir(ephemeral ? ephemeralProjectDir : cwd);
- const drainWaitStartedAt = Date.now();
- const drainOutcome = await waitForServerLockDrain(drainLockDir);
- if (drainOutcome !== 'no-drain') {
- // `waitedMs` is the tuning signal for the 10s drain timeout: released
- // durations creeping toward it mean real teardowns are outgrowing the
- // budget and would start colliding under normal load.
- log.info(
- {
- event: 'start-waited-for-draining-predecessor',
- outcome: drainOutcome,
- waitedMs: Date.now() - drainWaitStartedAt,
- drainLockDir,
- },
- drainOutcome === 'released'
- ? '[start] predecessor server finished draining — proceeding'
- : '[start] predecessor server still draining after wait — proceeding to collide',
- );
+ // From here to the end of bootServer a throw must clean up the
+ // self-provisioned ephemeral dir — the caller never learns the path, so an
+ // unreaped dir on a failed boot is unattributable.
+ let booted: BootedServer;
+ try {
+ {
+ const drainLockDir = resolveLockDir(ephemeralProjectDir ?? cwd);
+ const drainWaitStartedAt = Date.now();
+ const drainOutcome = await waitForServerLockDrain(drainLockDir);
+ if (drainOutcome !== 'no-drain') {
+ // `waitedMs` is the tuning signal for the 10s drain timeout: released
+ // durations creeping toward it mean real teardowns are outgrowing the
+ // budget and would start colliding under normal load.
+ log.info(
+ {
+ event: 'start-waited-for-draining-predecessor',
+ outcome: drainOutcome,
+ waitedMs: Date.now() - drainWaitStartedAt,
+ drainLockDir,
+ },
+ drainOutcome === 'released'
+ ? '[start] predecessor server finished draining — proceeding'
+ : '[start] predecessor server still draining after wait — proceeding to collide',
+ );
+ }
}
+
+ booted = await bootServer({
+ config,
+ contentDir,
+ projectDir: ephemeralProjectDir ?? cwd,
+ contentRoot: ephemeral ? undefined : config.content.dir,
+ port: opts.port,
+ host,
+ quiet: false,
+ detectGh,
+ tokenStore,
+ embeddingsKeyStore,
+ mcpTomlEditor: getNativeTomlMcpEditor(),
+ // Ephemeral single-file mode: scope content to the one doc, no MCP, no git
+ // (shadow repo + commits off), and a no-op git preflight so a machine
+ // without git can still open a loose file. The synthesized config lives at
+ // `ephemeralProjectDir/.ok/config.yml`; the file edit lands on the real
+ // file inside `contentDir`.
+ ...(ephemeral
+ ? {
+ ephemeral: true as const,
+ singleDocRelPath: ephemeralDocRelPath,
+ gitEnabled: false as const,
+ gitPreflight: () => ({
+ ok: true as const,
+ version: '0.0.0',
+ resolvedPath: 'git',
+ source: 'PATH' as const,
+ }),
+ }
+ : {}),
+ // Pass the exact runtime that started this server so /api/local-op/* can
+ // spawn additional CLI processes without needing open-knowledge on PATH.
+ localOpCliArgs: [process.execPath, process.argv[1]],
+ // ACP threads skip injecting the `open-knowledge` MCP server when the
+ // agent's own harness already loads OK's managed editor-config entry.
+ probeHarnessManagedMcpEntry: (editorId, agentCwd) =>
+ probeOwnManagedEditorMcpEntry(editorId, agentCwd),
+ // Pi has no MCP client, so its ACP threads get OK tools from the managed
+ // bridge extension in the project instead — probed at session setup and,
+ // with the user's consent, provisioned there and then.
+ probePiAcpBridge: (agentCwd) => probePiBridgeState(agentCwd),
+ ensurePiAcpBridge: (agentCwd) => ensurePiBridge(agentCwd),
+ // CLI-specific opt-ins
+ idleShutdownMs: idleThresholdMs,
+ ...(opts.serverRuntime !== undefined ? { serverRuntime: opts.serverRuntime } : {}),
+ ...(opts.bind !== undefined ? { bind: opts.bind } : {}),
+ skipAutoInit: true, // Guard already ran above; no scaffold fn to pass
+ idleShutdownHandler: (destroyServer) => {
+ const handler = destroyServer;
+ const reaped =
+ reapDirOnIdle !== undefined ? withEphemeralTempDirReap(handler, reapDirOnIdle) : handler;
+ // Outermost: the exit fires only after destroy AND the ephemeral temp
+ // dir reap have both run.
+ return withIdleShutdownProcessExit(reaped, { log, exit: opts.idleExit });
+ },
+ log,
+ // Content assets serve by default (bootServer default-on). The React
+ // shell dir is passed through when present — the default for plain
+ // `ok start` — so the one-listener composition is the norm.
+ ...(opts.serveContentAssets !== undefined
+ ? { serveContentAssets: opts.serveContentAssets }
+ : {}),
+ ...(opts.reactShellDistDir ? { reactShellDistDir: opts.reactShellDistDir } : {}),
+ });
+ } catch (err) {
+ await reapOwnedEphemeralDir();
+ throw err;
}
- const booted: BootedServer = await bootServer({
- config,
- contentDir,
- projectDir: ephemeral ? ephemeralProjectDir : cwd,
- contentRoot: ephemeral ? undefined : config.content.dir,
- port: opts.port,
- host,
- quiet: false,
- detectGh,
- tokenStore,
- embeddingsKeyStore,
- mcpTomlEditor: getNativeTomlMcpEditor(),
- // Ephemeral single-file mode: scope content to the one doc, no MCP, no git
- // (shadow repo + commits off), and a no-op git preflight so a machine
- // without git can still open a loose file. The synthesized config lives at
- // `ephemeralProjectDir/.ok/config.yml`; the file edit lands on the real
- // file inside `contentDir`.
- ...(ephemeral
- ? {
- ephemeral: true as const,
- singleDocRelPath: ephemeralDocRelPath,
- gitEnabled: false as const,
- gitPreflight: () => ({
- ok: true as const,
- version: '0.0.0',
- resolvedPath: 'git',
- source: 'PATH' as const,
- }),
+ // A parent-provided dir stays the parent's to remove (the desktop and the
+ // `ok <file>` browser path both reap their own temp dir on teardown); the
+ // self-provisioned dir has no other owner, so destroy() reaps it here.
+ const innerDestroy = booted.destroy;
+ const destroy = ownsEphemeralProjectDir
+ ? async (): Promise<void> => {
+ try {
+ await innerDestroy();
+ } finally {
+ await reapOwnedEphemeralDir();
}
- : {}),
- // Pass the exact runtime that started this server so /api/local-op/* can
- // spawn additional CLI processes without needing open-knowledge on PATH.
- localOpCliArgs: [process.execPath, process.argv[1]],
- // ACP threads skip injecting the `open-knowledge` MCP server when the
- // agent's own harness already loads OK's managed editor-config entry.
- probeHarnessManagedMcpEntry: (editorId, agentCwd) =>
- probeOwnManagedEditorMcpEntry(editorId, agentCwd),
- // Pi has no MCP client, so its ACP threads get OK tools from the managed
- // bridge extension in the project instead — probed at session setup and,
- // with the user's consent, provisioned there and then.
- probePiAcpBridge: (agentCwd) => probePiBridgeState(agentCwd),
- ensurePiAcpBridge: (agentCwd) => ensurePiBridge(agentCwd),
- // CLI-specific opt-ins
- idleShutdownMs: idleThresholdMs,
- ...(opts.serverRuntime !== undefined ? { serverRuntime: opts.serverRuntime } : {}),
- ...(opts.bind !== undefined ? { bind: opts.bind } : {}),
- skipAutoInit: true, // Guard already ran above; no scaffold fn to pass
- idleShutdownHandler: (destroyServer) => {
- const handler = destroyServer;
- const reaped = ephemeral ? withEphemeralTempDirReap(handler, ephemeralProjectDir) : handler;
- // Outermost: the exit fires only after destroy AND the ephemeral temp
- // dir reap have both run.
- return withIdleShutdownProcessExit(reaped, { log, exit: opts.idleExit });
- },
- log,
- // Content assets serve by default (bootServer default-on). The React
- // shell dir is passed through when present — the default for plain
- // `ok start` — so the one-listener composition is the norm.
- ...(opts.serveContentAssets !== undefined
- ? { serveContentAssets: opts.serveContentAssets }
- : {}),
- ...(opts.reactShellDistDir ? { reactShellDistDir: opts.reactShellDistDir } : {}),
- });
+ }
+ : innerDestroy;
return {
httpServer: booted.httpServer,
- destroy: booted.destroy,
+ destroy,
lockDir: booted.lockDir,
contentDir,
port: booted.port,
@@ -815,6 +996,34 @@ interface StartCommandOptions {
externalUrl?: string;
}
+/**
+ * Resolve the file-layer config for a `start` invocation. An ephemeral
+ * single-file session drops the PROJECT layers: the CLI's cwd anchor points
+ * at whatever project the shell happens to sit in, which is unrelated to the
+ * loose file being opened — inheriting its `server.*` settings made the same
+ * session behave differently by cwd. The user-global `~/.ok/global.yml`
+ * layer SURVIVES, matching `ok <file>` (whose `loadConfig(ephemeralRoot)`
+ * reads user-global plus the synthesized project config, which contributes
+ * only `content.dir` — overridden explicitly by the ephemeral boot anyway).
+ * Flags and env still override through the normal precedence.
+ *
+ * The user-layer read does not sideline a broken file (the primary
+ * `loadConfig` this session already did that and reported it); it degrades
+ * to schema defaults. `readUserConfig` is injected for tests.
+ */
+export function resolveStartConfig(
+ config: Config,
+ singleFile: string | undefined,
+ readUserConfig: () => Config = () =>
+ readConfigSafely({
+ absPath: resolveConfigPath('user', process.cwd()),
+ sideline: false,
+ warn: () => {},
+ }).value,
+): Config {
+ return singleFile !== undefined ? readUserConfig() : config;
+}
+
/**
* Validator for Commander's `option` parser — restricts `--mode` to the
* documented enum. Throws `InvalidArgumentError` for anything else,
@@ -873,7 +1082,8 @@ export function formatShutdownNotice(signal: NodeJS.Signals): string[] {
* This is the "browser mode" path; bit-for-bit identical to today's
* behavior when called with no `--mode` or with `--mode=browser`.
*/
-export async function runStartCommand(config: Config, opts: StartCommandOptions): Promise<void> {
+export async function runStartCommand(configArg: Config, opts: StartCommandOptions): Promise<void> {
+ const config = resolveStartConfig(configArg, opts.singleFile);
// Quiet the terminal BEFORE any getLogger()/reclaim sweep fires (both happen
// inside bootStartServer below). The `start` logger and the skill-reclaim
// sweep are constructed before bootServer wires the file sink, so a level
@@ -1043,6 +1253,13 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
process.exit(1);
}
+ // --project-dir refused (not a throwaway shape) — the message carries the
+ // fix; render it cleanly like the other flag-validation rejections.
+ if (err instanceof EphemeralProjectDirNotThrowawayError) {
+ console.error(error(err.message));
+ process.exit(1);
+ }
+
// Git preflight failure: bootServer already emitted telemetry, logged the
// event, wrote install guidance to stderr, and flushed the OTel exporter
// before re-throwing the typed error. The CLI just maps it to EX_CONFIG
@@ -1075,6 +1292,15 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
process.exit(1);
}
+ // bootServer's own config gate (`.ok/config.yml` absent at the resolved
+ // projectDir). The CLI guard above normally fires first; this arm covers
+ // the remaining direct-flag shapes so the user gets the message, not a
+ // stack trace.
+ if (err instanceof serverModule.MissingOkConfigError) {
+ console.error(error(err.message));
+ process.exit(1);
+ }
+
// Spawn-or-reuse: a plain `ok start` that collided with a live server
// reads the holder's advertisement, reports its URL, and exits 0 — a
// second start attaches to the running composition instead of failing.
@@ -1391,13 +1617,20 @@ export function startCommand(getConfig: () => Config): Command {
'Serve content assets from this server (now the default; kept for compatibility)',
)
.option('--react-shell-dist-dir <path>', 'Serve React shell from <path>')
- .option(
- '--single-file <path>',
- 'No-project ephemeral single-file mode: scope the server to one markdown file (git + MCP off)',
+ // Hidden from --help: both are the desktop→child spawn ABI, not a user
+ // surface — the supported way to open one file is `ok <file>`. They stay
+ // functional (and validated) for parent spawners and anyone who knows.
+ .addOption(
+ new Option(
+ '--single-file <path>',
+ 'No-project ephemeral single-file mode: scope the server to one markdown file (git + MCP off)',
+ ).hideHelp(),
)
- .option(
- '--project-dir <dir>',
- 'Throwaway project root for --single-file (where ephemeral .ok/ state lives)',
+ .addOption(
+ new Option(
+ '--project-dir <dir>',
+ 'Throwaway project root for --single-file (where ephemeral .ok/ state lives)',
+ ).hideHelp(),
)
.option(
'--external-url <url>',
@@ -1416,6 +1649,15 @@ export function startCommand(getConfig: () => Config): Command {
process.exit(2);
}
+ // `--project-dir` names the throwaway root of the ephemeral single-file
+ // shape and means nothing outside it. Fail loud rather than silently
+ // ignore — a user pointing it at a real project must not believe the
+ // server is rooted there.
+ if (opts.projectDir !== undefined && opts.singleFile === undefined) {
+ process.stderr.write("error: option '--project-dir' requires '--single-file'\n");
+ process.exit(2);
+ }
+
// `--mode=app` shortcuts the server boot and hands off to the
// desktop app.
if (opts.mode === 'app') {
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index a0eb77175..d579ca5f0 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -529,11 +529,13 @@ export {
export { originGitHubHost } from './share/git-context.ts';
export {
createEphemeralProjectDir,
+ EPHEMERAL_PROJECT_DIR_PREFIX,
prepareSingleFileOpen,
SingleFileNotAFileError,
SingleFileNotFoundError,
SingleFileNotMarkdownError,
type SingleFileOpenPlan,
+ seedEphemeralProjectDir,
} from './single-file-open.ts';
export {
BUNDLE_IDS,
diff --git a/packages/server/src/single-file-open.test.ts b/packages/server/src/single-file-open.test.ts
index f310b4e54..e21d89da4 100644
--- a/packages/server/src/single-file-open.test.ts
+++ b/packages/server/src/single-file-open.test.ts
@@ -13,10 +13,12 @@ import { basename, join } from 'node:path';
import { afterEach, describe, expect, test } from 'vitest';
import {
createEphemeralProjectDir,
+ EPHEMERAL_PROJECT_DIR_PREFIX,
prepareSingleFileOpen,
SingleFileNotAFileError,
SingleFileNotFoundError,
SingleFileNotMarkdownError,
+ seedEphemeralProjectDir,
} from './single-file-open.ts';
const cleanups: string[] = [];
@@ -134,8 +136,23 @@ describe('createEphemeralProjectDir', () => {
// spaces are valid YAML.
expect(cfg).toContain(JSON.stringify(contentDir));
// The throwaway dir is an `ok-ephemeral-*` mkdtemp under os.tmpdir, NOT the
- // user's content dir.
- expect(basename(projectDir).startsWith('ok-ephemeral-')).toBe(true);
+ // user's content dir. The prefix doubles as the reap's provenance marker,
+ // so the constant and the minted name must stay one and the same.
+ expect(basename(projectDir).startsWith(EPHEMERAL_PROJECT_DIR_PREFIX)).toBe(true);
expect(projectDir).not.toBe(contentDir);
});
});
+
+describe('seedEphemeralProjectDir', () => {
+ test('seeds .ok/config.yml + .gitignore into an existing dir and returns it', () => {
+ const contentDir = tmp('sfo-content-');
+ const bareDir = tmp('sfo-bare-');
+ const returned = seedEphemeralProjectDir(bareDir, contentDir);
+ expect(returned).toBe(bareDir);
+ expect(existsSync(join(bareDir, '.ok', 'config.yml'))).toBe(true);
+ expect(existsSync(join(bareDir, '.ok', '.gitignore'))).toBe(true);
+ expect(readFileSync(join(bareDir, '.ok', 'config.yml'), 'utf-8')).toContain(
+ JSON.stringify(contentDir),
+ );
+ });
+});
diff --git a/packages/server/src/single-file-open.ts b/packages/server/src/single-file-open.ts
index 11701fe2a..e8761d416 100644
--- a/packages/server/src/single-file-open.ts
+++ b/packages/server/src/single-file-open.ts
@@ -138,19 +138,25 @@ function resolveProjectContentDir(projectRoot: string): string {
}
/**
- * Create the throwaway `projectDir` for an ephemeral single-file session: an
- * `os.tmpdir()` `mkdtemp` carrying a synthesized minimal `.ok/config.yml`
- * (so the boot config gate passes) plus a `.ok/.gitignore` (so the
- * boot hygiene warning stays quiet). The `.ok/local/` runtime state (lock,
- * shadow, caches) lands here, never in the user's directory. The owner of
- * the session lifecycle (the CLI browser path, or the desktop window) removes
- * this directory on teardown.
+ * Basename prefix of every throwaway ephemeral projectDir this module mints
+ * (`mkdtemp` under `os.tmpdir()`). The CLI's idle-shutdown reap uses it as a
+ * provenance check before recursively deleting a projectDir — a dir that is
+ * not a direct `ok-ephemeral-*` child of the temp root is never a sanctioned
+ * reap target, whatever flag value claimed it was.
+ */
+export const EPHEMERAL_PROJECT_DIR_PREFIX = 'ok-ephemeral-';
+
+/**
+ * Seed an existing directory as an ephemeral single-file projectDir: a
+ * synthesized minimal `.ok/config.yml` (so the boot config gate passes) plus
+ * a `.ok/.gitignore` (so the boot hygiene warning stays quiet). Writes
+ * unconditionally — callers that might hand it a dir with a real config guard
+ * with their own existence check first.
*
* `contentDir` is written into `content.dir` for honesty, but the ephemeral
* boot passes `contentDir` explicitly — config resolution does not drive it.
*/
-export function createEphemeralProjectDir(contentDir: string): string {
- const projectDir = mkdtempSync(resolve(tmpdir(), 'ok-ephemeral-'));
+export function seedEphemeralProjectDir(projectDir: string, contentDir: string): string {
const okDir = resolve(projectDir, OK_DIR);
mkdirSync(okDir, { recursive: true });
// Minimal valid YAML config — empty would also parse to schema defaults, but
@@ -165,3 +171,18 @@ export function createEphemeralProjectDir(contentDir: string): string {
writeFileSync(resolve(okDir, '.gitignore'), 'local/\n', 'utf-8');
return projectDir;
}
+
+/**
+ * Create the throwaway `projectDir` for an ephemeral single-file session: an
+ * `os.tmpdir()` `mkdtemp` seeded via `seedEphemeralProjectDir`. The
+ * `.ok/local/` runtime state (lock, shadow, caches) lands here, never in the
+ * user's directory. The owner of the session lifecycle (the CLI browser path,
+ * the desktop window, or `bootStartServer` when it self-provisions for a
+ * direct `ok start --single-file`) removes this directory on teardown.
+ */
+export function createEphemeralProjectDir(contentDir: string): string {
+ return seedEphemeralProjectDir(
+ mkdtempSync(resolve(tmpdir(), EPHEMERAL_PROJECT_DIR_PREFIX)),
+ contentDir,
+ );
+}