tinybeeai 0.0.0-stage → 0.16.1

package/dist/cli/init.js

@@ -0,0 +1,746 @@
+// `localdost init`: detects the repo in the current folder, writes .env.localdost (references and
+// non-secret config only) and .localdost/config.json, and creates the first dot.
+//
+// Also exports the env-file loader and the service probes that `localdost doctor` and `localdost start` use.
+import { execFile } from 'node:child_process';
+import { createServer } from 'node:net';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { reviewChildEnv } from '../review/backend-cli.js';
+import { ENV_FILE, envFilePath, invokedDir, parseEnvFile } from './env-file.js';
+import { dotDir } from '../legacy-names.js';
+// The env file name, the invoked folder, and the file parser live in env-file.ts, which imports nothing from localdost. They stay exported here for the importers that already use them.
+export { ENV_FILE, envFilePath, invokedDir, parseEnvFile };
+export const CONFIG_FILE = path.join('.localdost', 'config.json');
+/** .localdost/config.json in `dir`, or the .qadots/ copy an older init wrote when only that exists. */
+export function configFilePath(dir) {
+    return path.join(dotDir(dir), 'config.json');
+}
+/** The default data folder of `dir`: .localdost/data, or .qadots/data when only that folder exists. */
+export function defaultDataDir(dir) {
+    return path.join(dotDir(dir), 'data');
+}
+export const DEFAULT_PORT = 4319;
+const PW_CONFIGS = ['playwright.config.ts', 'playwright.config.mts', 'playwright.config.js', 'playwright.config.mjs', 'playwright.config.cjs'];
+/** Binaries a `${cmd:...}` reference may run. Each prints a secret to stdout and needs no shell. */
+const REF_COMMANDS = new Set(['gh', 'op', 'security', 'pass']);
+/**
+ * The read-only subcommand each reference binary may run. `gh api -X DELETE ...` or `op item delete`
+ * in a .env.localdost would otherwise act with the person's credentials when they run start or doctor.
+ */
+const REF_SUBCOMMANDS = {
+    gh: (a) => a[0] === 'auth' && a[1] === 'token',
+    op: (a) => a[0] === 'read',
+    security: (a) => a[0] === 'find-generic-password' || a[0] === 'find-internet-password',
+    pass: (a) => a[0] === 'show' || (a.length === 1 && !a[0].startsWith('-')),
+};
+/** True when a `${cmd:...}` reference names an allowed binary and its read-only subcommand. */
+export function refCommandAllowed(bin, args) {
+    return REF_COMMANDS.has(bin) && (REF_SUBCOMMANDS[bin]?.(args) ?? false);
+}
+/** Runs a binary without a shell. Never throws. */
+export function sh(cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+        const child = execFile(cmd, args, { cwd: opts.cwd, timeout: opts.timeoutMs ?? 15_000, env: opts.env ?? process.env, maxBuffer: 4 * 1024 * 1024, encoding: 'utf8' }, (err, stdout, stderr) => {
+            const code = err ? (typeof err.code === 'number' ? err.code : null) : 0;
+            resolve({ ok: !err, code, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') });
+        });
+        if (opts.input !== undefined)
+            child.stdin?.end(opts.input);
+        else
+            child.stdin?.end();
+    });
+}
+async function resolveRef(ref, env) {
+    const envRef = /^\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(ref);
+    if (envRef) {
+        const v = env[envRef[1]]?.trim();
+        return v ? { value: v, source: 'env-ref' } : { source: 'unresolved', error: `${envRef[1]} is not exported in this shell` };
+    }
+    const cmdRef = /^\$\{cmd:(.+)\}$/.exec(ref);
+    if (cmdRef) {
+        const [bin, ...args] = cmdRef[1].trim().split(/\s+/);
+        if (!REF_COMMANDS.has(bin))
+            return { source: 'unresolved', error: `"${bin}" is not an allowed reference command (${[...REF_COMMANDS].join(', ')})` };
+        if (!refCommandAllowed(bin, args))
+            return {
+                source: 'unresolved',
+                error: `\`${cmdRef[1].trim()}\` is not a read-only reference (gh auth token, op read, security find-generic-password, pass show)`,
+            };
+        const r = await sh(bin, args, { timeoutMs: 15_000 });
+        const v = r.stdout.trim();
+        return r.ok && v ? { value: v, source: 'cmd-ref' } : { source: 'unresolved', error: `\`${cmdRef[1].trim()}\` failed` };
+    }
+    return { value: ref, source: 'literal' };
+}
+/**
+ * Reads .env.localdost in `dir` and resolves `${env:NAME}` and `${cmd:...}` references.
+ * A variable already set in the shell wins over the file. Relative LOCALDOST_DATA_DIR resolves against `dir`.
+ */
+export async function loadLocaldostEnv(dir, env = process.env) {
+    const file = envFilePath(dir);
+    if (!existsSync(file))
+        return { vars: {}, refs: [] };
+    const parsed = parseEnvFile(readFileSync(file, 'utf8'));
+    const vars = {};
+    const refs = [];
+    for (const [key, ref] of Object.entries(parsed)) {
+        if (env[key]?.trim()) {
+            refs.push({ key, ref, resolved: true, source: 'shell' });
+            continue;
+        }
+        if (ref === '')
+            continue;
+        const r = await resolveRef(ref, env);
+        if (r.value !== undefined) {
+            vars[key] = key === 'LOCALDOST_DATA_DIR' && !path.isAbsolute(r.value) ? path.resolve(dir, r.value) : r.value;
+            refs.push({ key, ref, resolved: true, source: r.source });
+        }
+        else {
+            refs.push({ key, ref, resolved: false, source: 'unresolved', error: r.error });
+        }
+    }
+    return { file, vars, refs };
+}
+/** Loads .env.localdost into process.env without overriding the shell. */
+export async function applyLocaldostEnv(dir) {
+    const loaded = await loadLocaldostEnv(dir);
+    for (const [k, v] of Object.entries(loaded.vars))
+        if (!process.env[k]?.trim())
+            process.env[k] = v;
+    return loaded;
+}
+export function readLocaldostConfig(dir) {
+    const file = configFilePath(dir);
+    if (!existsSync(file))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------- detection ----------
+export function parseGithubRemote(url) {
+    const m = /github\.com[:/]+([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(url.trim());
+    return m ? { owner: m[1], name: m[2] } : undefined;
+}
+export async function detectRepo(dir) {
+    const remote = await sh('git', ['remote', 'get-url', 'origin'], { cwd: dir });
+    const parsed = remote.ok ? parseGithubRemote(remote.stdout) : undefined;
+    if (!parsed)
+        return undefined;
+    return { ...parsed, defaultBranch: await detectDefaultBranch(dir) };
+}
+async function detectDefaultBranch(dir) {
+    const head = await sh('git', ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], { cwd: dir });
+    if (head.ok && head.stdout.trim())
+        return head.stdout.trim().replace(/^origin\//, '');
+    for (const b of ['main', 'master']) {
+        const r = await sh('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${b}`], { cwd: dir });
+        if (r.ok)
+            return b;
+    }
+    const cur = await sh('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: dir });
+    const name = cur.stdout.trim();
+    return cur.ok && name && name !== 'HEAD' ? name : 'main';
+}
+/** Finds the Playwright config and the test command from package.json scripts. */
+export function detectTests(dir) {
+    const playwrightConfig = PW_CONFIGS.find((f) => existsSync(path.join(dir, f)));
+    let scripts = {};
+    let deps = {};
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        scripts = pkg.scripts ?? {};
+        deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    }
+    catch {
+        /* no package.json */
+    }
+    const hasPlaywright = !!deps['@playwright/test'] || !!deps.playwright || !!playwrightConfig;
+    let command = 'npx playwright test';
+    let note;
+    const order = ['test:e2e', 'e2e', 'test:playwright', 'playwright', 'test'];
+    const names = [...order.filter((n) => scripts[n]), ...Object.keys(scripts).filter((n) => !order.includes(n))];
+    const script = names.find((n) => /playwright\s+test/.test(scripts[n]));
+    if (script) {
+        const value = scripts[script].trim();
+        // The runner spawns the command without a shell, so chained scripts cannot run as-is.
+        if (/&&|\|\||[;|<>]/.test(value))
+            note = `script "${script}" chains commands; using \`npx playwright test\` instead`;
+        else
+            command = value.startsWith('npx ') ? value : `npx ${value}`;
+    }
+    else if (!hasPlaywright) {
+        note = 'no Playwright config or dependency found; add @playwright/test or pass --command';
+    }
+    let baseUrl;
+    if (playwrightConfig) {
+        const found = baseUrlFromConfig(readFileSync(path.join(dir, playwrightConfig), 'utf8'));
+        baseUrl = found.url;
+        if (found.note)
+            note = note ? `${note}; ${found.note}` : found.note;
+    }
+    return { command, playwrightConfig, baseUrl, hasPlaywright, note };
+}
+/**
+ * The first http(s) URL in a Playwright config. A port written as `${PORT}` resolves from the
+ * constant's numeric default, so `const PORT = Number(process.env.PORT ?? 4400)` gives 4400. Before
+ * this, `http://localhost:${PORT}` came out as `http://localhost` with no port (KAT-78).
+ */
+export function baseUrlFromConfig(src) {
+    const m = /(https?:\/\/[A-Za-z0-9.-]+)(?::(\d+)|:\$\{\s*([A-Za-z_$][\w$]*)\s*\})?/.exec(src);
+    if (!m)
+        return {};
+    if (m[2])
+        return { url: `${m[1]}:${m[2]}` };
+    if (!m[3])
+        return { url: m[1] };
+    const name = m[3].replace(/\$/g, '\\$');
+    const decl = new RegExp(`(?:const|let|var)\\s+${name}\\s*=\\s*([^;\\n]+)`).exec(src);
+    const port = decl ? /(\d{2,5})\D*$/.exec(decl[1].trim())?.[1] : undefined;
+    if (port)
+        return { url: `${m[1]}:${port}` };
+    return { url: m[1], note: `the base URL port comes from \`${m[3]}\` in the Playwright config; pass --base-url` };
+}
+/** True when `gh auth token` prints a token. The token itself never leaves this function. */
+export async function hasGhToken() {
+    const r = await sh('gh', ['auth', 'token'], { timeoutMs: 10_000 });
+    return r.ok && !!r.stdout.trim();
+}
+/** Checks the Claude CLI login, and with `roundTrip` that `claude -p` answers. */
+export async function checkClaudeCli(env, roundTrip) {
+    const bin = env.LOCALDOST_CLAUDE_BIN?.trim() || 'claude';
+    const status = await sh(bin, ['auth', 'status', '--json'], { timeoutMs: 20_000 });
+    if (status.code === null && !status.stdout)
+        return { ok: false, detail: `"${bin}" is not installed or not on PATH` };
+    let loggedIn;
+    try {
+        loggedIn = !!JSON.parse(status.stdout).loggedIn;
+    }
+    catch {
+        loggedIn = status.ok;
+    }
+    if (!loggedIn)
+        return { ok: false, detail: 'Claude CLI is not signed in' };
+    if (!roundTrip)
+        return { ok: true, detail: 'Claude CLI signed in' };
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'localdost-claude-check-'));
+    // Same allowlist as the server's Claude CLI children: unrelated host secrets stay out.
+    const cleanEnv = reviewChildEnv(env);
+    try {
+        const args = ['-p', '--output-format', 'json', '--model', env.LOCALDOST_CLAUDE_FAST_MODEL?.trim() || 'haiku'];
+        args.push('--tools', '', '--strict-mcp-config', '--setting-sources', '', '--no-session-persistence', '--max-turns', '1');
+        const r = await sh(bin, args, { cwd, timeoutMs: 90_000, input: 'Reply with the single word OK.', env: cleanEnv });
+        if (!r.ok)
+            return { ok: false, detail: `\`claude -p\` failed${r.code === null ? ' (timed out)' : ` (exit ${r.code})`}` };
+        let text = r.stdout;
+        try {
+            text = String(JSON.parse(r.stdout).result ?? '');
+        }
+        catch {
+            /* plain text */
+        }
+        return /ok/i.test(text) ? { ok: true, detail: '`claude -p` answered' } : { ok: false, detail: '`claude -p` gave an unexpected reply' };
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+}
+/** Checks the Codex CLI login with `codex login status`. No model call, so no usage is spent. */
+export async function checkCodexCli(env) {
+    const bin = env.LOCALDOST_CODEX_BIN?.trim() || 'codex';
+    const r = await sh(bin, ['login', 'status'], { timeoutMs: 20_000 });
+    if (r.code === null && !r.stdout)
+        return { ok: false, detail: `"${bin}" is not installed or not on PATH` };
+    const text = `${r.stdout}`.trim().split('\n')[0] ?? '';
+    if (!r.ok || /not logged in/i.test(text))
+        return { ok: false, detail: 'Codex CLI is not signed in' };
+    return { ok: true, detail: text || 'Codex CLI signed in' };
+}
+/** Team keys visible to LINEAR_API_KEY, or undefined when the call fails. */
+export async function linearTeams(env) {
+    const key = env.LINEAR_API_KEY?.trim();
+    if (!key)
+        return undefined;
+    try {
+        const res = await fetch(env.LINEAR_API_URL?.trim() || 'https://api.linear.app/graphql', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: key },
+            body: JSON.stringify({ query: '{ teams(first: 50) { nodes { key } } }' }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        return body.data?.teams?.nodes?.map((n) => n.key);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Jira project keys visible to JIRA_EMAIL and JIRA_API_TOKEN, or undefined when the call fails. */
+export async function jiraProjects(env, baseUrl) {
+    const email = env.JIRA_EMAIL?.trim();
+    const token = env.JIRA_API_TOKEN?.trim();
+    if (!email || !token)
+        return undefined;
+    try {
+        const res = await fetch(`${baseUrl.replace(/\/+$/, '')}/rest/api/3/project/search?maxResults=50`, {
+            headers: { accept: 'application/json', authorization: `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        return body.values?.map((p) => p.key);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when nothing listens on the port on any interface. */
+export function portFree(port) {
+    return new Promise((resolve) => {
+        const srv = createServer();
+        srv.once('error', () => resolve(false));
+        srv.listen({ port, host: '0.0.0.0', exclusive: true }, () => srv.close(() => resolve(true)));
+    });
+}
+// ---------- GitHub Issues tracker ----------
+const REPO_ID = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** Splits repeatable flag values and comma lists into trimmed, non-empty entries without repeats. */
+function flagList(values, sep) {
+    const seen = new Set();
+    return (values ?? [])
+        .flatMap((v) => v.split(sep))
+        .map((v) => v.trim())
+        .filter((v) => v && !seen.has(v.toLowerCase()) && !!seen.add(v.toLowerCase()));
+}
+/**
+ * The GitHub Issues tracker of `localdost init` from its flags: `--tracker-repos` (owner/name, repeatable or comma separated),
+ * `--require-labels` (an issue needs one of them to be reviewed) and `--milestone` (repeatable or comma separated).
+ * No repos means the repo of the folder. Returns the error to print for a repo that is not owner/name.
+ */
+export function githubTrackerFromFlags(f) {
+    const repos = flagList(f.repos, /[\s,]+/);
+    const bad = repos.find((r) => !REPO_ID.test(r));
+    if (bad)
+        return { ok: false, error: `--tracker-repos must be owner/name, got "${bad}"` };
+    const required = flagList(f.requireLabels, /,/);
+    if (required.length > 20 || required.some((l) => l.length > 50))
+        return { ok: false, error: '--require-labels takes up to 20 labels, each up to 50 characters' };
+    const milestones = flagList(f.milestones, /,/);
+    return {
+        ok: true,
+        tracker: {
+            kind: 'github',
+            ...(repos.length ? { repos } : {}),
+            ...(required.length ? { labels: { require: required } } : {}),
+            ...(milestones.length ? { milestones } : {}),
+        },
+    };
+}
+/** One line for the init summary: `acme/product, label pod:agentic, milestone 2026.11`. */
+function githubTrackerLine(t, fallbackRepo) {
+    const repos = t.repos?.length ? t.repos.join(', ') : (fallbackRepo ?? 'this repo');
+    const parts = [repos];
+    if (t.labels?.require?.length)
+        parts.push(`label ${t.labels.require.join(' or ')}`);
+    if (t.milestones?.length)
+        parts.push(`milestone ${t.milestones.join(', ')}`);
+    return parts.join(', ');
+}
+export function renderEnvFile(p) {
+    const lines = [
+        `# localdost settings${p.slug ? ` for ${p.slug}` : ''}. Written by \`localdost init\`. Keep it out of git.`,
+        '# This file holds no secrets. ${env:NAME} reads NAME from your shell and ${cmd:...} runs one of',
+        `# ${[...REF_COMMANDS].join(', ')} at start. A variable already set in your shell wins over this file.`,
+        '',
+        `PORT=${p.port}`,
+        '# Local only. Export LOCALDOST_TOKEN in your shell before you change HOST to 0.0.0.0.',
+        'HOST=127.0.0.1',
+        'LOCALDOST_DATA_DIR=.localdost/data',
+        '# Polls GitHub and the tracker, so no public webhook URL is needed.',
+        'LOCALDOST_POLL=1',
+        '',
+        `LOCALDOST_LLM=${p.model}`,
+    ];
+    if (p.model === 'anthropic')
+        lines.push('ANTHROPIC_API_KEY=${env:ANTHROPIC_API_KEY}');
+    lines.push('');
+    lines.push(p.github ? 'GITHUB_TOKEN=${cmd:gh auth token}' : '# GITHUB_TOKEN=${cmd:gh auth token}   (run `gh auth login` first)');
+    if (p.tracker?.kind === 'linear')
+        lines.push('LINEAR_API_KEY=${env:LINEAR_API_KEY}');
+    if (p.tracker?.kind === 'jira') {
+        lines.push(`JIRA_BASE_URL=${p.tracker.baseUrl}`, 'JIRA_EMAIL=${env:JIRA_EMAIL}', 'JIRA_API_TOKEN=${env:JIRA_API_TOKEN}');
+    }
+    lines.push('', '# Public HTTPS URL for links and phone push, e.g. a cloudflared tunnel (docs/DEPLOY.md).', '# LOCALDOST_PUBLIC_URL=https://qa.example.com', '');
+    return lines.join('\n');
+}
+/** Adds entries to .gitignore when missing. Returns the entries it added. */
+export function ensureGitignore(dir, entries) {
+    const file = path.join(dir, '.gitignore');
+    const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const have = new Set(text.split(/\r?\n/).map((l) => l.trim()));
+    const add = entries.filter((e) => !have.has(e));
+    if (add.length)
+        writeFileSync(file, `${text}${text && !text.endsWith('\n') ? '\n' : ''}# localdost\n${add.join('\n')}\n`);
+    return add;
+}
+// ---------- the dot ----------
+function dotInput(cfg, hosted, absWorkdir) {
+    const slug = cfg.repo ? `${cfg.repo.owner}/${cfg.repo.name}` : cfg.name;
+    return {
+        name: cfg.name,
+        role: 'qa-lead',
+        mission: `Keep ${slug}${cfg.repo ? ` ${cfg.repo.defaultBranch}` : ''} green: the test suite passes after every merge and every PR.`,
+        notifyWhen: 'A merge or PR breaks a test, a new ticket carries risk, or the app is down.',
+        mustNot: 'Never merge, revert, or push. Never comment on a ticket without asking.',
+        ...(cfg.repo ? { repo: cfg.repo } : {}),
+        ...(cfg.tracker ? { tracker: cfg.tracker } : {}),
+        ...(cfg.baseUrl ? { baseUrl: cfg.baseUrl } : {}),
+        // Hosted servers clone the repo per run; a local server runs in this checkout.
+        runner: hosted ? { mode: 'local', command: cfg.runner.command } : { mode: 'local', workdir: absWorkdir, command: cfg.runner.command },
+    };
+}
+async function upsertDotApi(server, input, knownId) {
+    const headers = { 'content-type': 'application/json' };
+    const token = process.env.LOCALDOST_TOKEN?.trim();
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    const base = server.replace(/\/+$/, '');
+    const listRes = await fetch(`${base}/api/dots`, { headers, signal: AbortSignal.timeout(10_000) });
+    if (listRes.status === 401)
+        throw new Error(`${base} needs a token: export LOCALDOST_TOKEN in this shell`);
+    if (!listRes.ok)
+        throw new Error(`GET ${base}/api/dots returned ${listRes.status}`);
+    const dots = (await listRes.json());
+    const existing = dots.find((d) => d.id === knownId) ?? dots.find((d) => d.name === input.name);
+    const res = existing
+        ? await fetch(`${base}/api/dots/${existing.id}`, { method: 'PATCH', headers, body: JSON.stringify(input), signal: AbortSignal.timeout(10_000) })
+        : await fetch(`${base}/api/dots`, { method: 'POST', headers, body: JSON.stringify(input), signal: AbortSignal.timeout(10_000) });
+    if (!res.ok)
+        throw new Error(`${existing ? 'PATCH' : 'POST'} ${base}/api/dots returned ${res.status}`);
+    const dot = (await res.json());
+    return { id: dot.id, created: !existing };
+}
+async function upsertDotDb(dataDir, input, knownId) {
+    // config.ts and db.ts read the data dir at import time.
+    process.env.LOCALDOST_DATA_DIR = dataDir;
+    delete process.env.LOCALDOST_DB;
+    const { createWatch, findOne, get, update } = await import('../db.js');
+    const { NO_STAGE_OFFER } = await import('../stages/config.js');
+    const existing = (knownId ? get('watches', knownId) : undefined) ?? findOne('watches', { name: input.name });
+    if (existing) {
+        update('watches', existing.id, { ...input, updatedAt: new Date().toISOString() });
+        return { id: existing.id, created: false };
+    }
+    return { id: createWatch({ ...NO_STAGE_OFFER, ...input }).id, created: true };
+}
+// ---------- command ----------
+const HELP = `Usage: localdost init [options]
+
+Sets up localdost for the git repo in the current folder. Writes .env.localdost (no secrets,
+only references) and .localdost/config.json, adds .env.localdost and .localdost/data/ to .gitignore,
+and creates the first dot.
+
+  -y, --yes                 Accept every detected value, never prompt
+  --dir <path>              Repo folder (default: current folder)
+  --repo <owner/name>       GitHub repo (default: from git remote origin)
+  --branch <name>           Default branch (default: from origin/HEAD)
+  --tracker <kind>          linear | jira | github | none (default: from LINEAR_API_KEY or JIRA_* in env)
+  --linear-team <KEY>       Linear team key, repeatable
+  --jira-url <url>          Jira base URL (default: JIRA_BASE_URL)
+  --jira-project <KEY>      Jira project key, repeatable
+  --tracker-repos <o/n>     GitHub Issues: repo whose issues the dot reviews, repeatable (default: the repo above).
+                            Defects are filed in the first one
+  --require-labels <l,...>  GitHub Issues: review only issues with one of these labels, for example pod:agentic.
+                            The first also goes on the defects the dot files
+  --milestone <title>       GitHub Issues: review only issues in this milestone, repeatable
+  --port <n>                Server port (default: ${DEFAULT_PORT})
+  --name <text>             Dot name (default: repo name)
+  --base-url <url>          App URL the tests run against (default: from the Playwright config)
+  --command <cmd>           Test command (default: from package.json scripts)
+  --model <kind>            claude-cli | codex-cli | anthropic | mock (default: detected)
+  --server <url>            Create the dot on a running localdost server through the API
+                            (for a hosted server; sends LOCALDOST_TOKEN from your shell)
+  --skip-model-check        Do not run a \`claude -p\` round trip
+  --no-dot                  Write the files only
+  -h, --help                Show this help
+`;
+export async function runInit(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        allowPositionals: false,
+        options: {
+            yes: { type: 'boolean', short: 'y' },
+            dir: { type: 'string' },
+            repo: { type: 'string' },
+            branch: { type: 'string' },
+            tracker: { type: 'string' },
+            'linear-team': { type: 'string', multiple: true },
+            'jira-url': { type: 'string' },
+            'jira-project': { type: 'string', multiple: true },
+            'tracker-repos': { type: 'string', multiple: true },
+            'require-labels': { type: 'string', multiple: true },
+            milestone: { type: 'string', multiple: true },
+            port: { type: 'string' },
+            name: { type: 'string' },
+            'base-url': { type: 'string' },
+            command: { type: 'string' },
+            model: { type: 'string' },
+            server: { type: 'string' },
+            'skip-model-check': { type: 'boolean' },
+            'no-dot': { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    if (values.help) {
+        console.log(HELP);
+        return 0;
+    }
+    const dir = path.resolve(values.dir ?? invokedDir());
+    const interactive = !values.yes && process.stdin.isTTY === true && process.stdout.isTTY === true;
+    const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+    const ask = async (q, def) => {
+        if (!rl)
+            return def;
+        const a = (await rl.question(`${q}${def ? ` [${def}]` : ''}: `)).trim();
+        return a || def;
+    };
+    const say = (label, value) => console.log(`  ${label.padEnd(12)} ${value}`);
+    const fail = (msg) => {
+        rl?.close();
+        console.error(`localdost init: ${msg}`);
+        return 1;
+    };
+    try {
+        if (!existsSync(dir))
+            return fail(`${dir} does not exist`);
+        const prev = readLocaldostConfig(dir);
+        // References already in .env.localdost count as set, e.g. LINEAR_API_KEY=${env:...}.
+        const env = { ...(await loadLocaldostEnv(dir)).vars, ...process.env };
+        console.log(`localdost init in ${dir}\n`);
+        // Repo
+        let repo = await detectRepo(dir);
+        if (values.repo) {
+            const [owner, name] = values.repo.split('/');
+            if (!owner || !name)
+                return fail('--repo must be owner/name');
+            repo = { owner, name, defaultBranch: repo?.defaultBranch ?? 'main' };
+        }
+        if (!repo && rl) {
+            const a = await ask('GitHub repo (owner/name), empty for none', '');
+            const [owner, name] = a.split('/');
+            if (owner && name)
+                repo = { owner, name, defaultBranch: 'main' };
+        }
+        if (repo && values.branch)
+            repo.defaultBranch = values.branch;
+        if (repo && rl)
+            repo.defaultBranch = await ask('Default branch', repo.defaultBranch);
+        say('Repo', repo ? `${repo.owner}/${repo.name} (${repo.defaultBranch})` : 'none found (no GitHub remote "origin")');
+        // Tests
+        const tests = detectTests(dir);
+        const command = values.command ?? tests.command;
+        say('Tests', `${command}${tests.playwrightConfig ? ` with ${tests.playwrightConfig}` : ''}`);
+        if (tests.note && !values.command)
+            say('', `note: ${tests.note}`);
+        const baseUrl = values['base-url'] ?? tests.baseUrl;
+        if (baseUrl)
+            say('Base URL', baseUrl);
+        // GitHub token
+        const gh = await hasGhToken();
+        say('GitHub', gh ? '`gh auth token` works (stored as a reference, not the token)' : 'no token: run `gh auth login`');
+        // Model
+        let model;
+        const modelFlag = values.model ?? env.LOCALDOST_LLM?.trim();
+        if (modelFlag) {
+            if (modelFlag !== 'claude-cli' && modelFlag !== 'codex-cli' && modelFlag !== 'anthropic' && modelFlag !== 'mock')
+                return fail('--model must be claude-cli, codex-cli, anthropic, or mock');
+            model = modelFlag;
+            if (model === 'codex-cli') {
+                const codex = await checkCodexCli(env);
+                say('Model', `${model}: ${codex.detail}`);
+            }
+            else
+                say('Model', model);
+        }
+        else {
+            const claude = await checkClaudeCli(env, !values['skip-model-check']);
+            if (claude.ok)
+                model = 'claude-cli';
+            else if (env.ANTHROPIC_API_KEY?.trim())
+                model = 'anthropic';
+            else
+                model = 'mock';
+            const why = model === 'claude-cli'
+                ? claude.detail
+                : model === 'anthropic'
+                    ? `ANTHROPIC_API_KEY is set (${claude.detail})`
+                    : `${claude.detail}; no ANTHROPIC_API_KEY`;
+            say('Model', `${model}: ${why}`);
+        }
+        // Tracker
+        // The GitHub flags name the tracker: --require-labels alone means GitHub Issues.
+        const githubFlags = !!(values['tracker-repos']?.length || values['require-labels']?.length || values.milestone?.length);
+        let kind = values.tracker ??
+            (githubFlags ? 'github' : env.LINEAR_API_KEY?.trim() ? 'linear' : env.JIRA_API_TOKEN?.trim() || env.JIRA_BASE_URL?.trim() ? 'jira' : 'none');
+        if (rl && !values.tracker && !githubFlags)
+            kind = await ask('Tracker (linear, jira, github, none)', kind);
+        if (githubFlags && kind !== 'github')
+            return fail('--tracker-repos, --require-labels and --milestone need --tracker github');
+        let tracker;
+        if (kind === 'linear') {
+            let teams = values['linear-team'] ?? [];
+            if (!teams.length) {
+                const visible = await linearTeams(env);
+                if (visible?.length === 1)
+                    teams = visible;
+                else if (rl)
+                    teams = (await ask(`Linear team keys, comma separated${visible?.length ? ` (${visible.join(', ')})` : ''}`, '')).split(/[,\s]+/).filter(Boolean);
+            }
+            if (!teams.length)
+                return fail('Linear needs a team: pass --linear-team <KEY>');
+            tracker = { kind: 'linear', teamKeys: teams };
+            say('Tracker', `Linear ${teams.join(', ')}`);
+        }
+        else if (kind === 'jira') {
+            let baseJira = values['jira-url'] ?? env.JIRA_BASE_URL?.trim() ?? '';
+            if (!baseJira && rl)
+                baseJira = await ask('Jira base URL (https://acme.atlassian.net)', '');
+            if (!baseJira)
+                return fail('Jira needs a base URL: pass --jira-url or export JIRA_BASE_URL');
+            baseJira = baseJira.replace(/\/+$/, '');
+            let keys = values['jira-project'] ?? [];
+            if (!keys.length) {
+                const visible = await jiraProjects(env, baseJira);
+                if (visible?.length === 1)
+                    keys = visible;
+                else if (rl)
+                    keys = (await ask(`Jira project keys, comma separated${visible?.length ? ` (${visible.slice(0, 10).join(', ')})` : ''}`, ''))
+                        .split(/[,\s]+/)
+                        .filter(Boolean);
+            }
+            if (!keys.length)
+                return fail('Jira needs a project: pass --jira-project <KEY>');
+            tracker = { kind: 'jira', baseUrl: baseJira, projectKeys: keys };
+            say('Tracker', `Jira ${keys.join(', ')} on ${new URL(baseJira).host}`);
+        }
+        else if (kind === 'github') {
+            let repos = values['tracker-repos'] ?? [];
+            let labels = values['require-labels'] ?? [];
+            let milestones = values.milestone ?? [];
+            if (rl) {
+                if (!repos.length)
+                    repos = [await ask('GitHub repos whose issues the dot reviews, comma separated (empty: the repo above)', '')];
+                if (!labels.length)
+                    labels = [await ask('Review only issues with one of these labels, comma separated (empty: all issues)', '')];
+                if (!milestones.length)
+                    milestones = [await ask('Review only these milestones, comma separated (empty: all)', '')];
+            }
+            const made = githubTrackerFromFlags({ repos, requireLabels: labels, milestones });
+            if (!made.ok)
+                return fail(made.error);
+            tracker = made.tracker;
+            if (!tracker.repos?.length && !repo)
+                return fail('GitHub Issues needs a repo: pass --tracker-repos <owner/name>, or run in a repo with an origin remote');
+            say('Tracker', `GitHub Issues in ${githubTrackerLine(tracker, repo ? `${repo.owner}/${repo.name}` : undefined)}`);
+        }
+        else if (kind === 'none') {
+            say('Tracker', 'none');
+        }
+        else {
+            return fail('--tracker must be linear, jira, github, or none');
+        }
+        // Port and name
+        let port = Number(values.port ?? prev?.port ?? DEFAULT_PORT);
+        if (!values.port && !prev?.port && !values.server) {
+            // Another localdost (the demo, a dogfood run) often holds 4319. Take the next free port.
+            let p = port;
+            // 4320 is the demo sample shop's port.
+            while (p < port + 20 && (p === 4320 || !(await portFree(p))))
+                p++;
+            if (p !== port)
+                say('Port', `${port} is in use, using ${p}`);
+            port = p;
+        }
+        if (rl && !values.port)
+            port = Number(await ask('Port', String(port)));
+        if (!Number.isInteger(port) || port < 1 || port > 65535)
+            return fail('--port must be 1-65535');
+        const name = values.name ?? prev?.name ?? repo?.name ?? path.basename(dir);
+        // Files
+        const cfg = {
+            version: 1,
+            name,
+            ...(repo ? { repo } : {}),
+            ...(tracker ? { tracker } : {}),
+            runner: { mode: 'local', workdir: '.', command },
+            ...(tests.playwrightConfig ? { playwrightConfig: tests.playwrightConfig } : {}),
+            ...(baseUrl ? { baseUrl } : {}),
+            port,
+            model,
+            ...(values.server ? { server: values.server.replace(/\/+$/, '') } : {}),
+            ...(prev?.dotId ? { dotId: prev.dotId } : {}),
+            updatedAt: new Date().toISOString(),
+        };
+        mkdirSync(path.join(dir, '.localdost'), { recursive: true });
+        writeFileSync(path.join(dir, ENV_FILE), renderEnvFile({ port, model, github: gh, tracker, slug: repo ? `${repo.owner}/${repo.name}` : undefined }));
+        const added = ensureGitignore(dir, [ENV_FILE, '.localdost/data/']);
+        console.log(`\nWrote ${ENV_FILE}, ${CONFIG_FILE}${added.length ? `, and added ${added.join(', ')} to .gitignore` : ''}`);
+        // Dot
+        if (!values['no-dot']) {
+            const server = cfg.server;
+            const hosted = !!server && !/^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(server);
+            const input = dotInput(cfg, hosted, dir);
+            try {
+                const r = server
+                    ? await upsertDotApi(server, input, prev?.dotId)
+                    : await upsertDotDb((await loadLocaldostEnv(dir)).vars.LOCALDOST_DATA_DIR ?? defaultDataDir(dir), input, prev?.dotId);
+                cfg.dotId = r.id;
+                console.log(`${r.created ? 'Created' : 'Updated'} dot "${name}" (${r.id}) ${server ? `on ${server}` : `in .localdost/data`}`);
+            }
+            catch (err) {
+                writeFileSync(configFilePath(dir), `${JSON.stringify(cfg, null, 2)}\n`);
+                return fail(`could not create the dot: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        writeFileSync(configFilePath(dir), `${JSON.stringify(cfg, null, 2)}\n`);
+        rl?.close();
+        const missing = [];
+        if (!gh)
+            missing.push('gh auth login');
+        if (model === 'mock')
+            missing.push('claude auth login   (or codex login with LOCALDOST_LLM=codex-cli, or export ANTHROPIC_API_KEY in your shell)');
+        if (tracker?.kind === 'linear' && !env.LINEAR_API_KEY?.trim())
+            missing.push('export LINEAR_API_KEY=<key from linear.app/settings/api>');
+        if (tracker?.kind === 'jira' && !(env.JIRA_EMAIL?.trim() && env.JIRA_API_TOKEN?.trim()))
+            missing.push('export JIRA_EMAIL=<you@company.com> JIRA_API_TOKEN=<token from id.atlassian.com>');
+        if (!tests.hasPlaywright && !values.command)
+            missing.push('npm i -D @playwright/test && npx playwright install chromium');
+        console.log('\nNext steps:');
+        for (const m of missing)
+            console.log(`  ${m}`);
+        console.log('  localdost doctor        check every service');
+        if (cfg.server) {
+            console.log(`  open ${cfg.server}   the dot is on that server`);
+        }
+        else {
+            console.log(`  localdost start         run the server on http://localhost:${port}`);
+            console.log('  docs/DEPLOY.md       host it on Railway, Docker Compose, or a cloudflared tunnel');
+        }
+        console.log('\nNever paste a token into a chat or this file. Export it in your shell instead.');
+        return 0;
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+}
+//# sourceMappingURL=init.js.map