@nostale/cli 0.1.0

package/dist/commands/config.js

@@ -0,0 +1,43 @@
+import { hasInstallation } from '../lib/api-config.js';
+import { installDir, resolveInstall } from '../lib/install-root.js';
+import { promptSelect } from '../tui/prompts.js';
+import { run as runProviders } from './config/providers.js';
+import { run as runTemplates } from './config/templates.js';
+import { run as runTokens } from './config/tokens.js';
+import { run as runSources } from './config/sources.js';
+import { run as runGeneration } from './config/generation.js';
+const SUBCOMMANDS = {
+    providers: { label: 'Providers', run: runProviders },
+    templates: { label: 'Templates', run: runTemplates },
+    tokens: { label: 'MCP Tokens', run: runTokens },
+    sources: { label: 'Sources', run: runSources },
+    generation: { label: 'Generation toggle', run: runGeneration },
+};
+function isSubcommandName(value) {
+    return Object.hasOwn(SUBCOMMANDS, value);
+}
+/**
+ * `nostale config [subcommand]` — M18 replaces "just re-run the wizard" with a submenu of thin
+ * wiki-api REST clients (`./config/*.ts`), each authenticating via `lib/http.ts`'s
+ * `login`/`authedFetch`. `nostale config` alone shows an interactive menu; `nostale config
+ * providers` (etc.) dispatches straight to that subcommand.
+ */
+export async function configCommand(subcommand) {
+    const dir = installDir(resolveInstall());
+    if (!hasInstallation(dir)) {
+        console.error('No .env found — run `nostale setup` first.');
+        process.exitCode = 1;
+        return;
+    }
+    if (subcommand) {
+        if (!isSubcommandName(subcommand)) {
+            console.error(`Unknown subcommand "${subcommand}" — expected one of: ${Object.keys(SUBCOMMANDS).join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        await SUBCOMMANDS[subcommand].run(dir);
+        return;
+    }
+    const choice = await promptSelect('What would you like to configure?', Object.entries(SUBCOMMANDS).map(([value, { label }]) => ({ label, value: value })));
+    await SUBCOMMANDS[choice].run(dir);
+}

package/dist/commands/doctor.js

@@ -0,0 +1,98 @@
+import { createClient } from '@libsql/client';
+import { readEnvFile } from '../lib/env-writer.js';
+import { installDir, resolveInstall } from '../lib/install-root.js';
+import { envFilePath } from '../lib/paths.js';
+import { isPortFree } from '../lib/ports.js';
+import { SERVICES, isServiceEnabled, statusService } from '../lib/process-manager.js';
+async function checkLibsql(env) {
+    const url = env.LIBSQL_URL;
+    if (!url)
+        return { name: 'LIBSQL_URL', ok: false, detail: 'not set in .env' };
+    try {
+        const client = createClient({ url, authToken: env.LIBSQL_AUTH_TOKEN || undefined });
+        await client.execute('select 1');
+        client.close();
+        return { name: 'LIBSQL_URL', ok: true, detail: `connected (${url})` };
+    }
+    catch (err) {
+        return { name: 'LIBSQL_URL', ok: false, detail: `cannot connect to ${url} — ${err.message}` };
+    }
+}
+function checkEncryptionKey(env) {
+    const key = env.SETTINGS_ENCRYPTION_KEY;
+    if (!key)
+        return { name: 'SETTINGS_ENCRYPTION_KEY', ok: false, detail: 'missing — run `nostale config` to generate one' };
+    if (!/^[0-9a-f]{64}$/.test(key))
+        return { name: 'SETTINGS_ENCRYPTION_KEY', ok: false, detail: 'set but not a 32-byte hex key' };
+    return { name: 'SETTINGS_ENCRYPTION_KEY', ok: true, detail: 'present' };
+}
+// Without this, apps/wiki-api/src/auth.ts refuses to boot (SECURITY-REVIEW-2026-07-10.md F-01) —
+// checked here too so `nostale doctor` surfaces the same problem before a restart hits it.
+function checkAuthSecret(env) {
+    const key = env.BETTER_AUTH_SECRET;
+    if (!key)
+        return { name: 'BETTER_AUTH_SECRET', ok: false, detail: 'missing — run `nostale config` to generate one' };
+    if (key.length < 32)
+        return { name: 'BETTER_AUTH_SECRET', ok: false, detail: 'set but shorter than 32 characters' };
+    return { name: 'BETTER_AUTH_SECRET', ok: true, detail: 'present' };
+}
+// Empty token means sqld accepts unauthenticated connections on the internal network
+// (SECURITY-REVIEW-2026-07-10.md F-06).
+function checkSqldAuthToken(env) {
+    const token = env.SQLD_AUTH_TOKEN;
+    if (env.NOSTALE_MODE !== 'server')
+        return { name: 'SQLD_AUTH_TOKEN', ok: true, detail: 'not applicable outside server mode' };
+    if (!token)
+        return { name: 'SQLD_AUTH_TOKEN', ok: false, detail: 'missing — sqld will accept unauthenticated connections; run `nostale config` to generate one' };
+    return { name: 'SQLD_AUTH_TOKEN', ok: true, detail: 'present' };
+}
+// Only meaningful for personal mode — server mode's ports are fixed by docker-compose.yml.
+async function checkPortConflicts(env) {
+    if (env.NOSTALE_MODE !== 'personal')
+        return [];
+    const results = [];
+    for (const service of SERVICES) {
+        if (!isServiceEnabled(service.name, env))
+            continue;
+        const port = Number(env[service.portEnvKey]);
+        if (!port)
+            continue;
+        if (statusService(service.name).running) {
+            results.push({ name: `port ${port} (${service.name})`, ok: true, detail: `held by nostale's own ${service.name}` });
+            continue;
+        }
+        const free = await isPortFree(port);
+        results.push({
+            name: `port ${port} (${service.name})`,
+            ok: free,
+            detail: free ? 'free' : 'already in use by another process — pick a different port via `nostale config`',
+        });
+    }
+    return results;
+}
+export async function doctorCommand() {
+    const dir = installDir(resolveInstall());
+    const env = readEnvFile(envFilePath(dir));
+    if (Object.keys(env).length === 0) {
+        console.log('✗ No .env found — run `nostale setup` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const results = [
+        await checkLibsql(env),
+        checkEncryptionKey(env),
+        checkAuthSecret(env),
+        checkSqldAuthToken(env),
+        ...(await checkPortConflicts(env)),
+    ];
+    for (const r of results)
+        console.log(`${r.ok ? '✓' : '✗'} ${r.name} — ${r.detail}`);
+    const failed = results.filter((r) => !r.ok);
+    if (failed.length > 0) {
+        console.log(`\n${failed.length} issue(s) found.`);
+        process.exitCode = 1;
+    }
+    else {
+        console.log('\nAll checks passed.');
+    }
+}

package/dist/commands/setup.js

@@ -0,0 +1,5 @@
+import { resolveInstall } from '../lib/install-root.js';
+import { runWizard } from '../lib/wizard.js';
+export async function setupCommand() {
+    await runWizard(resolveInstall());
+}

package/dist/commands/start.js

@@ -0,0 +1,23 @@
+import { execFileSync } from 'node:child_process';
+import { readEnvFile } from '../lib/env-writer.js';
+import { installDir, resolveInstall } from '../lib/install-root.js';
+import { envFilePath } from '../lib/paths.js';
+import { SERVICES, startAllPersonal } from '../lib/process-manager.js';
+export async function startCommand() {
+    const install = resolveInstall();
+    const dir = installDir(install);
+    const env = readEnvFile(envFilePath(dir));
+    if (!env.NOSTALE_MODE) {
+        console.log('No .env found — run `nostale setup` first.');
+        process.exitCode = 1;
+        return;
+    }
+    if (env.NOSTALE_MODE === 'server') {
+        execFileSync('docker', ['compose', 'up', '-d'], { cwd: dir, stdio: 'inherit' });
+        return;
+    }
+    const ports = Object.fromEntries(SERVICES.map((s) => [s.name, Number(env[s.portEnvKey])]));
+    const started = await startAllPersonal(install, env, ports, { restart: false });
+    for (const s of started)
+        console.log(`${s.name} on :${ports[s.name]} (pid ${s.pid})`);
+}

package/dist/commands/status.js

@@ -0,0 +1,17 @@
+import { execFileSync } from 'node:child_process';
+import { readEnvFile } from '../lib/env-writer.js';
+import { installDir, resolveInstall } from '../lib/install-root.js';
+import { envFilePath } from '../lib/paths.js';
+import { statusAll } from '../lib/process-manager.js';
+export function statusCommand() {
+    const dir = installDir(resolveInstall());
+    const env = readEnvFile(envFilePath(dir));
+    if (env.NOSTALE_MODE === 'server') {
+        execFileSync('docker', ['compose', 'ps'], { cwd: dir, stdio: 'inherit' });
+        return;
+    }
+    for (const status of statusAll(env)) {
+        const state = status.disabled ? 'disabled' : status.running ? `running (pid ${status.pid})` : 'stopped';
+        console.log(`${status.name}: ${state}`);
+    }
+}

package/dist/commands/stop.js

@@ -0,0 +1,16 @@
+import { execFileSync } from 'node:child_process';
+import { readEnvFile } from '../lib/env-writer.js';
+import { installDir, resolveInstall } from '../lib/install-root.js';
+import { envFilePath } from '../lib/paths.js';
+import { stopAll } from '../lib/process-manager.js';
+export function stopCommand() {
+    const dir = installDir(resolveInstall());
+    const env = readEnvFile(envFilePath(dir));
+    if (env.NOSTALE_MODE === 'server') {
+        execFileSync('docker', ['compose', 'down'], { cwd: dir, stdio: 'inherit' });
+        return;
+    }
+    for (const result of stopAll(env)) {
+        console.log(`${result.name}: ${result.stopped ? 'stopped' : 'was not running'}`);
+    }
+}

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { configCommand } from './commands/config.js';
+import { doctorCommand } from './commands/doctor.js';
+import { setupCommand } from './commands/setup.js';
+import { startCommand } from './commands/start.js';
+import { statusCommand } from './commands/status.js';
+import { stopCommand } from './commands/stop.js';
+const program = new Command();
+program.name('nostale').description('NoStale installer CLI/TUI — setup, process supervision, doctor').version('0.1.0');
+program.command('setup').description('Run the setup wizard (personal or server mode)').action(setupCommand);
+program
+    .command('config [subcommand]')
+    .description('Configure an existing installation — providers|templates|tokens|sources|generation (interactive menu if omitted)')
+    .action((subcommand) => configCommand(subcommand));
+program.command('doctor').description('Diagnose a broken installation').action(doctorCommand);
+program.command('start').description('Start services (personal mode) or the docker compose stack (server mode)').action(startCommand);
+program.command('stop').description('Stop services (personal mode) or the docker compose stack (server mode)').action(stopCommand);
+program.command('status').description('Show service status').action(statusCommand);
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

package/dist/lib/api-config.js

@@ -0,0 +1,21 @@
+import { readEnvFile } from './env-writer.js';
+import { envFilePath } from './paths.js';
+/**
+ * Resolves the wiki-api base URL + BetterAuth `origin` header from `.env`. Shared by
+ * `config.tsx`'s dispatcher and every `config/*.ts` subcommand so each one just calls
+ * `resolveApiConfig(installDir)` instead of re-deriving which env var wins per mode:
+ * personal mode writes `WIKI_API_BASE` + `WIKI_WEB_ORIGIN`, server mode writes
+ * `WIKI_API_PUBLIC_URL` only (origin falls back to the default `wiki-web` URL BetterAuth's
+ * `trustedOrigins` also falls back to — see `apps/wiki-api/src/auth.ts`).
+ */
+export function resolveApiConfig(installDir) {
+    const env = readEnvFile(envFilePath(installDir));
+    return {
+        wikiApiBase: env.WIKI_API_BASE || env.WIKI_API_PUBLIC_URL || 'http://localhost:3001',
+        origin: env.WIKI_WEB_ORIGIN || 'http://localhost:3000',
+    };
+}
+export function hasInstallation(installDir) {
+    const env = readEnvFile(envFilePath(installDir));
+    return Boolean(env.WIKI_API_BASE || env.WIKI_API_PUBLIC_URL);
+}

package/dist/lib/env-writer.js

@@ -0,0 +1,41 @@
+import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+export function parseEnv(content) {
+    const vars = {};
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        vars[key] = value;
+    }
+    return vars;
+}
+export function readEnvFile(path) {
+    if (!existsSync(path))
+        return {};
+    return parseEnv(readFileSync(path, 'utf-8'));
+}
+function serializeValue(value) {
+    return /[\s#"]/.test(value) ? `"${value.replace(/"/g, '\\"')}"` : value;
+}
+export function writeEnvFile(path, vars) {
+    const lines = Object.entries(vars)
+        .filter(([, value]) => value !== undefined && value !== null && value !== '')
+        .map(([key, value]) => `${key}=${serializeValue(value)}`);
+    // .env holds SETTINGS_ENCRYPTION_KEY/LLM_API_KEY in plaintext — mode:0o600 at creation isn't
+    // enough on its own since a prior run could have written it looser under a different umask
+    // (docs/13 finding #4), so chmod unconditionally on every write, not just the first.
+    writeFileSync(path, `# Generated by \`nostale setup\` — see docs/11-installer-and-marketing-site.md\n${lines.join('\n')}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+export function generateEncryptionKey() {
+    return randomBytes(32).toString('hex');
+}

package/dist/lib/http.js

@@ -0,0 +1,117 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { promptPassword, promptText, printStep } from '../tui/prompts.js';
+import { SESSION_FILE } from './paths.js';
+export async function waitForHttp(url, timeoutMs = 20000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            await fetch(url);
+            return true;
+        }
+        catch {
+            await new Promise((resolve) => setTimeout(resolve, 400));
+        }
+    }
+    return false;
+}
+/**
+ * BetterAuth's Set-Cookie response is `better-auth.session_token=<token>; Max-Age=...; Path=/;
+ * HttpOnly; SameSite=Lax` (confirmed empirically against a real wiki-api + `file:` libSQL — see
+ * M18 http.ts work order). We only need the `name=value` pair back on later requests, not the
+ * attributes, so strip everything from the first `;` onward. Handles multiple Set-Cookie headers
+ * (none expected today, but `getSetCookie()` is the forward-compatible read).
+ */
+function extractCookieHeader(response) {
+    const cookies = response.headers.getSetCookie?.() ?? [];
+    const pairs = cookies.map((raw) => raw.split(';', 1)[0].trim()).filter(Boolean);
+    if (pairs.length > 0)
+        return pairs.join('; ');
+    const fallback = response.headers.get('set-cookie');
+    return fallback ? fallback.split(';', 1)[0].trim() : null;
+}
+function readCachedCookie() {
+    return existsSync(SESSION_FILE) ? readFileSync(SESSION_FILE, 'utf-8').trim() || null : null;
+}
+function persistCookie(cookie) {
+    mkdirSync(dirname(SESSION_FILE), { recursive: true });
+    // mode:0o600 at creation isn't enough alone — a prior run could have left the file looser under
+    // a different umask, so chmod unconditionally on every write, same pattern as env-writer.ts
+    // (SECURITY-REVIEW-2026-07-10.md F-14). This is a bearer credential.
+    writeFileSync(SESSION_FILE, cookie, { mode: 0o600 });
+    chmodSync(SESSION_FILE, 0o600);
+}
+function clearCachedCookie() {
+    rmSync(SESSION_FILE, { force: true });
+}
+/**
+ * Prompts for email+password and signs in against BetterAuth, same `origin` header requirement
+ * as `wizard.ts`'s `provisionFirstUser` (BetterAuth rejects sign-in without an Origin header
+ * matching `trustedOrigins`, even for non-browser callers). Persists the resulting session
+ * cookie to `SESSION_FILE` (mode 0600 — it's a bearer credential) and returns it.
+ */
+export async function login(wikiApiBase, origin) {
+    printStep('Sign in to NoStale');
+    const email = await promptText('Email');
+    const password = await promptPassword('Password');
+    const response = await fetch(`${wikiApiBase}/api/auth/sign-in/email`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', origin },
+        body: JSON.stringify({ email, password }),
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`sign-in failed (${response.status}): ${body}`);
+    }
+    const cookie = extractCookieHeader(response);
+    if (!cookie)
+        throw new Error('sign-in succeeded but no session cookie was returned — cannot proceed');
+    persistCookie(cookie);
+    return cookie;
+}
+/**
+ * Every `nostale config *` subcommand's one entry point for talking to wiki-api: attaches the
+ * cached session cookie (from a prior `login()`), and on a 401 (missing/expired session)
+ * transparently re-prompts for login and retries the request once. Callers never touch
+ * `SESSION_FILE`/`login()` directly.
+ */
+export async function authedFetch(wikiApiBase, origin, path, init = {}) {
+    const cookie = readCachedCookie();
+    const headers = new Headers(init.headers);
+    if (cookie)
+        headers.set('cookie', cookie);
+    const response = await fetch(`${wikiApiBase}${path}`, { ...init, headers });
+    if (response.status !== 401)
+        return response;
+    clearCachedCookie();
+    const freshCookie = await login(wikiApiBase, origin);
+    const retryHeaders = new Headers(init.headers);
+    retryHeaders.set('cookie', freshCookie);
+    return fetch(`${wikiApiBase}${path}`, { ...init, headers: retryHeaders });
+}
+async function assertOk(response) {
+    if (response.ok)
+        return response;
+    const body = await response.text();
+    throw new Error(`request failed (${response.status}): ${body}`);
+}
+export async function apiGet(wikiApiBase, origin, path) {
+    const response = await authedFetch(wikiApiBase, origin, path);
+    return (await assertOk(response)).json();
+}
+export async function apiPost(wikiApiBase, origin, path, body) {
+    const response = await authedFetch(wikiApiBase, origin, path, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    return (await assertOk(response)).json();
+}
+export async function apiPut(wikiApiBase, origin, path, body) {
+    const response = await authedFetch(wikiApiBase, origin, path, {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    return (await assertOk(response)).json();
+}

package/dist/lib/install-root.js

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { NOSTALE_HOME } from './paths.js';
+import { findRepoRoot } from './repo-root.js';
+// This module lives at <package root>/dist/lib/install-root.js once compiled — three levels
+// down from the package root (dist/lib/install-root.js -> dist/lib -> dist -> package root).
+const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+export function cliPackageRoot() {
+    return packageRoot;
+}
+/**
+ * Bundled installs ship `<packageRoot>/services/*` alongside `dist/` (docs/14-npm-standalone-
+ * distribution.md M21) — their presence is what makes `nostale` runnable with zero prior
+ * `nostale` clone. Absent that dir, fall back to the monorepo/tsx dev workflow, which does
+ * require a checkout (repo-root.ts, unchanged). Split from resolveInstall() below so this,
+ * the actual highest-blast-radius branch in the package, is testable against fake directories
+ * instead of this checkout's own real (and test-run-dependent) `services/` presence.
+ */
+export function resolveInstallFrom(packageRoot, cwd) {
+    const servicesDir = join(packageRoot, 'services');
+    if (existsSync(servicesDir))
+        return { mode: 'bundled' };
+    return { mode: 'dev', repoRoot: findRepoRoot(cwd) };
+}
+export function resolveInstall() {
+    return resolveInstallFrom(packageRoot, process.cwd());
+}
+/** Where `.env` (and, for server mode, docker-compose.yml) live — repo root in dev mode (so
+ * Compose's cwd-relative auto-load keeps working there), `~/.nostale` otherwise. */
+export function installDir(install) {
+    return install.mode === 'dev' ? install.repoRoot : NOSTALE_HOME;
+}
+const BUNDLED_SERVICE_ENTRY = {
+    'wiki-api': 'index.cjs',
+    'wiki-worker': 'index.cjs',
+    'mcp-server': 'index.cjs',
+    'wiki-web': '.output/server/index.mjs',
+};
+/** Absolute path to a bundled service's entry point, e.g. for wiki-api's `--migrate-only` mode
+ * (M22) — invoked directly rather than through resolveServiceSource, which is spawn-shaped. */
+export function bundledServiceEntry(name) {
+    return join(packageRoot, 'services', name, BUNDLED_SERVICE_ENTRY[name]);
+}
+/** `ServiceDef.command()`'s replacement — resolves what to spawn for a given service, in
+ * whichever mode `install` says this is running under. */
+export function resolveServiceSource(install, name, port) {
+    if (install.mode === 'bundled') {
+        return { cmd: process.execPath, args: [bundledServiceEntry(name)], cwd: join(packageRoot, 'services', name) };
+    }
+    const { repoRoot } = install;
+    const cwd = join(repoRoot, 'apps', name);
+    if (name === 'wiki-web') {
+        return { cmd: join(repoRoot, 'node_modules/.bin/nuxt'), args: ['dev', '--port', String(port), '--host', '127.0.0.1'], cwd };
+    }
+    return { cmd: join(repoRoot, 'node_modules/.bin/tsx'), args: ['src/index.ts'], cwd };
+}
+/** Shared dir of pruned tree-sitter grammar `.wasm` files + web-tree-sitter's own runtime wasm,
+ * copied there once by `scripts/bundle-services.ts` (M21) — never per-service. */
+export function wasmDir() {
+    return join(packageRoot, 'services', 'wasm');
+}
+/** rag-core's `.sql` migration files, copied here by `scripts/bundle-services.ts` (M21) — only
+ * wiki-api reads these (on every boot), but set for every bundled service same as wasmDir since
+ * it's harmless where unused and keeps startService's bundled-env wiring in one place. */
+export function migrationsDir() {
+    return join(packageRoot, 'services', 'migrations');
+}
+/** `@nostale/cli`'s own installed version — the contract (M23/M24) is that a release tags
+ * `@nostale/cli@X.Y.Z` and all 4 GHCR images `X.Y.Z` together, so the CLI's own version is
+ * always the right image tag to pull for server mode. */
+export function cliVersion() {
+    const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8'));
+    return pkg.version;
+}

package/dist/lib/paths.js

@@ -0,0 +1,12 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const NOSTALE_HOME = join(homedir(), '.nostale');
+export const DATA_DIR = join(NOSTALE_HOME, 'data');
+export const PID_DIR = join(NOSTALE_HOME, 'pids');
+export const LOG_DIR = join(NOSTALE_HOME, 'logs');
+export const DEFAULT_DB_PATH = join(DATA_DIR, 'nostale.db');
+export const DEFAULT_WORK_DIR = join(NOSTALE_HOME, 'work');
+export const SESSION_FILE = join(NOSTALE_HOME, 'session');
+export function envFilePath(repoRoot) {
+    return join(repoRoot, '.env');
+}

package/dist/lib/ports.js

@@ -0,0 +1,19 @@
+import { createServer } from 'node:net';
+export function isPortFree(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => {
+            server.close(() => resolve(true));
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+/** Walks up from `preferred` until a port is both free on the OS and not already claimed this run. */
+export async function pickPort(preferred, taken = new Set()) {
+    let port = preferred;
+    while (taken.has(port) || !(await isPortFree(port))) {
+        port++;
+    }
+    return port;
+}