@oscharko-dev/keiko-cli 0.2.0

package/dist/launcher-state.js

@@ -0,0 +1,228 @@
+// Persistent record of generated launcher shortcut paths, written under the existing
+// `.keiko/` state dir alongside `ui.pid` / `ui.log` (see `lifecycle.ts`). The state file
+// is plaintext JSON and contains ONLY:
+//   - the absolute path of each generated shortcut,
+//   - the SHA-256 hash of the content Keiko generated for that path at install time,
+//   - the platform id and an ISO timestamp for human inspection.
+//
+// It MUST NOT contain credentials, model identifiers, workspace data, or any
+// deployment-specific value (spec §"Security-critical patterns to NOT miss").
+//
+// SAFETY CONTRACT (spec §"Filesystem safety contract"):
+//   - State file is opened with `O_NOFOLLOW` on POSIX; symlinks at the state path are
+//     refused. On Windows the equivalent is to refuse if `lstat` reports a symlink.
+//   - All writes are atomic via mkdtemp → write → rename (atomic on POSIX; on Windows we
+//     accept the standard rename semantics; the file lives under the user's `.keiko/`).
+//   - The state dir itself is created with mode 0o700.
+//   - `loadState` returns an empty state when the file is missing OR malformed; we never
+//     throw on a missing/corrupt state file at read-time, but we DO refuse to write into
+//     a symlinked state path.
+import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { LauncherError, launcherFor } from "./launcher-platforms.js";
+import { isRealpathContained } from "./launcher-paths.js";
+export const LAUNCHER_STATE_VERSION = 1;
+const STATE_FILE_NAME = "launcher-state.json";
+const HASH_HEX_RE = /^[0-9a-f]{64}$/;
+export function hashContent(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function stateFilePath(stateDir) {
+    return join(stateDir, STATE_FILE_NAME);
+}
+function emptyState() {
+    return { version: LAUNCHER_STATE_VERSION, entries: [] };
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null;
+}
+function isPlatform(v) {
+    return v === "linux" || v === "darwin" || v === "win32";
+}
+function parseEntryShape(raw) {
+    if (!isObject(raw))
+        return null;
+    const { path, platform, contentSha256, createdAt } = raw;
+    if (typeof path !== "string" || path.length === 0)
+        return null;
+    if (!isPlatform(platform))
+        return null;
+    if (typeof contentSha256 !== "string" || !HASH_HEX_RE.test(contentSha256))
+        return null;
+    if (typeof createdAt !== "string")
+        return null;
+    return { path, platform, contentSha256, createdAt };
+}
+function isEntryContained(entry, options) {
+    if (options.homedir === undefined)
+        return true;
+    const approvedDir = launcherFor(entry.platform).installDirFor(options.homedir);
+    if (isRealpathContained(approvedDir, entry.path))
+        return true;
+    options.onWarn?.(`keiko launcher: refusing tampered state entry — path is outside the approved directory.\n  approved: ${approvedDir}\n  path:     ${entry.path}\n`);
+    return false;
+}
+function parseEntry(raw, options = {}) {
+    const entry = parseEntryShape(raw);
+    if (entry === null)
+        return null;
+    return isEntryContained(entry, options) ? entry : null;
+}
+export function parseState(raw, options = {}) {
+    if (!isObject(raw))
+        return emptyState();
+    if (raw.version !== LAUNCHER_STATE_VERSION)
+        return emptyState();
+    if (!Array.isArray(raw.entries))
+        return emptyState();
+    const entries = [];
+    for (const item of raw.entries) {
+        const parsed = parseEntry(item, options);
+        if (parsed !== null)
+            entries.push(parsed);
+    }
+    return { version: LAUNCHER_STATE_VERSION, entries };
+}
+function defaultWarn(msg) {
+    process.stderr.write(msg);
+}
+// Returns the lstat result, OR `null` to signal "treat as empty state". Refuses
+// (throws LauncherError) when the state path is a symlink (defense-in-depth).
+function statStateFile(file, warn) {
+    let stat;
+    try {
+        stat = lstatSync(file);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code !== "ENOENT") {
+            warn(`keiko launcher: cannot stat state file (${code ?? "unknown error"}): ${file}\n`);
+        }
+        return null;
+    }
+    if (stat.isSymbolicLink()) {
+        throw new LauncherError("STATE_SYMLINK_REFUSED", `keiko launcher: state file is a symlink and was refused: ${file}`);
+    }
+    if (!stat.isFile())
+        return null;
+    return stat;
+}
+function readStateRaw(file, warn) {
+    try {
+        return readWithoutFollow(file);
+    }
+    catch (e) {
+        if (e instanceof LauncherError)
+            throw e;
+        const code = e.code;
+        warn(`keiko launcher: cannot read state file (${code ?? "unknown error"}): ${file}\n`);
+        return null;
+    }
+}
+// Reads the state file, refusing to follow symlinks at the state path. Returns the empty
+// state if the file is missing, unreadable, malformed, or contains an unrecognised version.
+// Throws LauncherError ONLY when the state path exists as a symlink (defense-in-depth).
+//
+// When `options.homedir` is provided, every parsed entry is also containment-checked
+// against the approved installDir for its declared platform (F1 parse-time barrier).
+// Tampered entries are silently dropped and reported via `options.onWarn`.
+//
+// F6 error classification: ENOENT (missing file) is the silent-empty path; any other
+// `lstat`/read failure (EACCES/EIO/EISDIR) is surfaced via `options.onWarn` so the user
+// sees a signal instead of a phantom empty state. We still return `emptyState()` so the
+// workflow continues — `loadState` is best-effort by contract.
+export function loadState(stateDir, options = {}) {
+    const file = stateFilePath(stateDir);
+    const warn = options.onWarn ?? defaultWarn;
+    if (statStateFile(file, warn) === null)
+        return emptyState();
+    const raw = readStateRaw(file, warn);
+    if (raw === null)
+        return emptyState();
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        warn(`keiko launcher: state file is not valid JSON; ignoring: ${file}\n`);
+        return emptyState();
+    }
+    return parseState(parsed, options);
+}
+// F5: cap on the state-file size we will allocate a Buffer for. The launcher records
+// a handful of entries (~ a few hundred bytes each); 1 MiB is overwhelming headroom
+// and prevents a hostile/corrupt 1 GB state file from OOM-ing the launcher.
+export const MAX_STATE_FILE_BYTES = 1 << 20;
+// O_NOFOLLOW-based read: refuses to traverse a symlink at the final path component.
+// We avoid `readFileSync(file)` because it would follow a symlink. On Windows the
+// O_NOFOLLOW flag is undefined; we fall back to a normal open after the `lstat` check
+// in `loadState` has already proved the path is not a link.
+function readWithoutFollow(file) {
+    const nofollow = fsConstants.O_NOFOLLOW ?? 0;
+    const fd = openSync(file, fsConstants.O_RDONLY | nofollow);
+    try {
+        const stat = fstatSync(fd);
+        if (stat.size > MAX_STATE_FILE_BYTES) {
+            throw new LauncherError("STATE_TOO_LARGE", `keiko launcher: state file exceeds ${String(MAX_STATE_FILE_BYTES)} bytes (got ${String(stat.size)}); refusing to load.`);
+        }
+        if (stat.size === 0)
+            return "";
+        const buf = Buffer.alloc(stat.size);
+        let offset = 0;
+        while (offset < buf.length) {
+            const n = readSync(fd, buf, offset, buf.length - offset, offset);
+            if (n === 0)
+                break;
+            offset += n;
+        }
+        return buf.subarray(0, offset).toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+// Atomic write via mkdtemp → write → rename. The state dir is created with mode 0o700.
+// The final rename is atomic on POSIX and best-effort on Windows; both are acceptable
+// for a user-local state file. If the final path is a symlink we refuse before write
+// (defense-in-depth: a hostile state-dir actor could plant a symlink to /etc/passwd).
+export function saveState(stateDir, state) {
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    const file = stateFilePath(stateDir);
+    try {
+        const stat = lstatSync(file);
+        if (stat.isSymbolicLink()) {
+            throw new LauncherError("STATE_SYMLINK_REFUSED", `keiko launcher: state file is a symlink and was refused: ${file}`);
+        }
+    }
+    catch (e) {
+        if (e instanceof LauncherError)
+            throw e;
+        // ENOENT — fine; we're about to create it.
+    }
+    const tmpDir = mkdtempSync(join(stateDir, ".launcher-state-"));
+    const tmpFile = join(tmpDir, "state.json");
+    try {
+        writeFileSync(tmpFile, JSON.stringify(state, null, 2) + "\n", {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        renameSync(tmpFile, file);
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+export function upsertEntry(state, entry) {
+    const others = state.entries.filter((e) => e.path !== entry.path);
+    return { version: LAUNCHER_STATE_VERSION, entries: [...others, entry] };
+}
+export function removeEntry(state, path) {
+    return {
+        version: LAUNCHER_STATE_VERSION,
+        entries: state.entries.filter((e) => e.path !== path),
+    };
+}
+export function findEntry(state, path) {
+    return state.entries.find((e) => e.path === path);
+}

package/dist/launcher.d.ts

@@ -0,0 +1,21 @@
+import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
+import type { CliIo } from "./runner.js";
+export interface LauncherCliDeps {
+    readonly cwd?: string | undefined;
+    readonly homedir?: () => string;
+    readonly platform?: () => NodeJS.Platform;
+    readonly resolveExe?: (env: EnvSource) => string;
+    readonly stateDir?: string;
+}
+export interface RemoveLauncherResult {
+    readonly removed: number;
+    readonly refused: number;
+    readonly missing: number;
+}
+export declare function removeLauncherShortcuts(io: CliIo, deps: {
+    readonly stateDir: string;
+    readonly homedir: string;
+    readonly dryRun: boolean;
+}): RemoveLauncherResult;
+export declare function runLauncherCli(args: readonly string[], io: CliIo, env: EnvSource, deps?: LauncherCliDeps): number;
+//# sourceMappingURL=launcher.d.ts.map

package/dist/launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../src/launcher.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAoCzC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC,QAAQ,CAAC;IAG1C,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,MAAM,CAAC;IAGjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAkVD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAQD,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,KAAK,EACT,IAAI,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACtF,oBAAoB,CAwBtB;AAqED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,eAAoB,GACzB,MAAM,CA+BR"}

package/dist/launcher.js

@@ -0,0 +1,439 @@
+// `keiko launcher` — generates a reversible, user-local OS shortcut that starts the local
+// Keiko server in one user action. CLI-only surface; no UI route, no server change, no
+// new runtime dependency. Per ADR-0024 D8 / D9 #125 checklist:
+//
+//   - No postinstall side effect; shortcut creation is explicitly user-invoked.
+//   - No shell injection: the generated file content is built from a sanitized exec path
+//     (allow-list regex in launcher-platforms.ts) and a validated integer port.
+//   - Removal command documented and tested: `keiko launcher remove`.
+//   - No admin/root required: install paths are user-local (`~/.local/share/...`,
+//     `~/Applications/...`, `%APPDATA%\Microsoft\Windows\Start Menu\Programs\...`).
+//   - Generated locations enumerated below.
+//
+// SUBCOMMANDS:
+//   keiko launcher install [--dry-run] [--explain] [--port PORT]
+//   keiko launcher remove [--dry-run] [--explain]
+//   keiko launcher status
+//   keiko launcher --help
+//
+// GENERATED FILE LOCATIONS (per-platform, user-local approved directories — these are the
+// only directories the launcher will ever write to; the resolved target is realpath-
+// contained against the approved directory before any write):
+//   Linux:   ~/.local/share/applications/keiko.desktop
+//   macOS:   ~/Applications/Keiko Launcher.command
+//   Windows: %APPDATA%\Microsoft\Windows\Start Menu\Programs\Keiko.bat
+//
+// The launcher does NOT import lifecycle.ts; the generated shortcut spawns
+// `keiko start --open` as a subprocess. This keeps the launcher independent of the
+// lifecycle handler's runtime.
+import { chmodSync, closeSync, constants as fsConstants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync, } from "node:fs";
+import { homedir as defaultHomedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { LauncherError, launcherFor, validateExecPath, validatePort, } from "./launcher-platforms.js";
+import { assertRealpathContained } from "./launcher-paths.js";
+import { hashContent, loadState, removeEntry, saveState, upsertEntry, } from "./launcher-state.js";
+import { resolveKeikoBinary } from "./install-layout.js";
+const USAGE = `Usage:
+  keiko launcher install [--dry-run] [--explain] [--port PORT]
+  keiko launcher remove  [--dry-run] [--explain]
+  keiko launcher status
+  keiko launcher --help
+
+Generates a user-local OS shortcut that runs \`keiko start --open\` in one user action.
+Generated file locations:
+  Linux:   ~/.local/share/applications/keiko.desktop
+  macOS:   ~/Applications/Keiko Launcher.command
+  Windows: %APPDATA%\\Microsoft\\Windows\\Start Menu\\Programs\\Keiko.bat
+`;
+function parsePortFlag(value) {
+    if (value === undefined || value.startsWith("--")) {
+        return { ok: false, message: "missing value for --port" };
+    }
+    if (!/^\d{1,5}$/.test(value)) {
+        return { ok: false, message: `invalid --port value: ${value}` };
+    }
+    try {
+        return { ok: true, value: validatePort(Number(value)) };
+    }
+    catch (e) {
+        if (e instanceof LauncherError)
+            return { ok: false, message: e.message };
+        throw e;
+    }
+}
+function parseInstallArgs(rest) {
+    let dryRun = false;
+    let explain = false;
+    let port;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--explain") {
+            explain = true;
+        }
+        else if (arg === "--port") {
+            const parsed = parsePortFlag(rest[i + 1]);
+            if (!parsed.ok)
+                return parsed;
+            port = parsed.value;
+            i += 1;
+        }
+        else {
+            return { ok: false, message: `unknown flag: ${arg ?? "(undefined)"}` };
+        }
+    }
+    return { ok: true, value: { dryRun, explain, port } };
+}
+function parseRemoveArgs(rest) {
+    let dryRun = false;
+    let explain = false;
+    for (const arg of rest) {
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--explain") {
+            explain = true;
+            continue;
+        }
+        return { ok: false, message: `unknown flag: ${arg}` };
+    }
+    return { ok: true, value: { dryRun, explain } };
+}
+function defaultResolveExe(env) {
+    const resolution = resolveKeikoBinary(process.cwd(), env, process.argv);
+    if (resolution === undefined) {
+        throw new LauncherError("EXE_NOT_FOUND", "keiko launcher: cannot locate the `keiko` executable on PATH. Install with `npm install -g @oscharko-dev/keiko` before re-running.");
+    }
+    return validateExecPath(resolution.binPath);
+}
+// Path-containment helpers (realpathSync + ancestor walk) live in `./launcher-paths.ts`
+// so `launcher-state.ts` can apply the same boundary at state-file parse time.
+// Adapts the CliIo writer to the `onWarn(msg)` shape consumed by `loadState`. We wrap
+// in a block body (not an arrow shorthand) because `io.err` returns `void`, and the
+// `no-confusing-void-expression` lint rule forbids implicit-return shorthand-void.
+function ioWarn(io) {
+    return (msg) => {
+        io.err(msg);
+    };
+}
+function assertApprovedDirNotSymlink(approvedDir) {
+    try {
+        const stat = lstatSync(approvedDir);
+        if (stat.isSymbolicLink()) {
+            throw new LauncherError("APPROVED_DIR_SYMLINK_REFUSED", `keiko launcher: approved directory is a symlink and was refused: ${approvedDir}`);
+        }
+    }
+    catch (e) {
+        if (e instanceof LauncherError)
+            throw e;
+        // ENOENT — fine; we'll mkdir it below.
+    }
+}
+function assertTargetNotSymlink(target) {
+    try {
+        const stat = lstatSync(target);
+        if (stat.isSymbolicLink()) {
+            throw new LauncherError("TARGET_SYMLINK_REFUSED", `keiko launcher: refusing to write through a symlink at: ${target}`);
+        }
+    }
+    catch {
+        // ENOENT — fine, target will be created.
+    }
+}
+// Atomic O_EXCL write: opens with O_WRONLY|O_CREAT|O_EXCL so we can never overwrite an
+// existing file. If the file already exists we read it for content-hash comparison
+// (idempotent re-install / collision detection). On POSIX we also pass O_NOFOLLOW so a
+// symlink at the final path component is rejected; on Windows the lstat above is the
+// only available guard.
+//
+// MINOR (verifier): the `existsSync(targetPath)` check in `cmdInstall` and the `openSync`
+// call below form a TOCTOU window. The O_EXCL flag closes it — if another process plants
+// a file at `target` between the two calls, `openSync` raises `EEXIST` and we surface a
+// `TARGET_EXISTS` LauncherError (user-readable) rather than letting the raw ErrnoException
+// propagate. The conversion is the only reason we catch+rethrow here.
+function writeAtomicExcl(target, content, mode) {
+    const dir = dirname(target);
+    mkdirSync(dir, { recursive: true, mode: 0o755 });
+    const nofollow = fsConstants.O_NOFOLLOW ?? 0;
+    const flags = fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | nofollow;
+    let fd;
+    try {
+        fd = openSync(target, flags, mode);
+    }
+    catch (e) {
+        if (e.code === "EEXIST") {
+            throw new LauncherError("TARGET_EXISTS", `keiko launcher: ${target} appeared between the pre-flight existsSync check and the O_EXCL open. Refusing to overwrite (TOCTOU defense).`);
+        }
+        throw e;
+    }
+    try {
+        writeSync(fd, content);
+    }
+    finally {
+        closeSync(fd);
+    }
+    // Some platforms ignore the mode passed to open() when O_CREAT files exist; we set
+    // it explicitly here so the macOS .command script is executable.
+    try {
+        chmodSync(target, mode);
+    }
+    catch {
+        // best-effort
+    }
+}
+// F4: when `KEIKO_STATE_DIR` is set, its resolved path MUST be contained under the
+// user's homedir. Without this guard, an attacker who can plant the env var (wrapper
+// script in PATH, dev-container `.env`, exported in a parent shell) can combine with
+// F1 to steer the launcher state file to a world-writable location and from there to
+// arbitrary-file primitives. We re-use `assertRealpathContained` so symlinked-ancestor
+// edge cases compare consistently. The thrown error is re-classified as
+// `STATE_DIR_ESCAPE` so the user-facing message is unambiguous.
+function defaultStateDir(cwd, env, home) {
+    const fromEnv = env.KEIKO_STATE_DIR ?? process.env.KEIKO_STATE_DIR;
+    if (typeof fromEnv === "string" && fromEnv.length > 0) {
+        const resolved = isAbsolute(fromEnv) ? fromEnv : resolve(cwd, fromEnv);
+        try {
+            assertRealpathContained(home, resolved);
+        }
+        catch (e) {
+            if (e instanceof LauncherError && e.code === "PATH_ESCAPE") {
+                throw new LauncherError("STATE_DIR_ESCAPE", `keiko launcher: KEIKO_STATE_DIR ${fromEnv} resolves outside the user's home directory (${home}); refusing to proceed.`);
+            }
+            throw e;
+        }
+        return resolved;
+    }
+    return resolve(cwd, ".keiko");
+}
+function buildInstallPlan(launcher, homedir, args, exe) {
+    const approvedDir = launcher.installDirFor(homedir);
+    const targetPath = join(approvedDir, launcher.safeFileName());
+    const contentInput = { exe, port: args.port };
+    const content = launcher.generateContent(contentInput);
+    return {
+        platform: launcher.id,
+        approvedDir,
+        targetPath,
+        content,
+        contentInput,
+        fileMode: launcher.fileMode,
+    };
+}
+function describePlan(plan, explain) {
+    const lines = [];
+    lines.push(`platform: ${plan.platform}`);
+    lines.push(`path:     ${plan.targetPath}`);
+    lines.push(`mode:     0o${plan.fileMode.toString(8)}`);
+    if (explain) {
+        lines.push("--- begin generated content ---");
+        lines.push(plan.content.replace(/\r\n/g, "\n"));
+        lines.push("--- end generated content ---");
+        lines.push("Remove with: keiko launcher remove");
+    }
+    return lines.join("\n") + "\n";
+}
+function planToEntry(plan) {
+    return {
+        path: plan.targetPath,
+        platform: plan.platform,
+        contentSha256: hashContent(plan.content),
+        createdAt: new Date().toISOString(),
+    };
+}
+function handleExistingTarget(plan, stateDir, homedir, io) {
+    const existing = readFileSync(plan.targetPath, "utf8");
+    if (existing !== plan.content) {
+        throw new LauncherError("TARGET_FOREIGN", `keiko launcher: refusing to overwrite ${plan.targetPath}.\nA file with different content already exists. Move or remove it manually before re-running.`);
+    }
+    const loadOpts = { homedir, onWarn: ioWarn(io) };
+    saveState(stateDir, upsertEntry(loadState(stateDir, loadOpts), planToEntry(plan)));
+    io.out(`Keiko launcher already installed at ${plan.targetPath} (idempotent).\n`);
+    return 0;
+}
+function cmdInstall(args, io, env, deps) {
+    const launcher = launcherFor(deps.platform());
+    const exe = deps.resolveExe(env);
+    const home = deps.homedir();
+    const plan = buildInstallPlan(launcher, home, args, exe);
+    assertRealpathContained(plan.approvedDir, plan.targetPath);
+    if (args.dryRun || args.explain) {
+        io.out(describePlan(plan, args.explain));
+        if (args.dryRun)
+            io.out("(dry run — no file written.)\n");
+        return 0;
+    }
+    mkdirSync(plan.approvedDir, { recursive: true, mode: 0o755 });
+    assertApprovedDirNotSymlink(plan.approvedDir);
+    assertTargetNotSymlink(plan.targetPath);
+    if (existsSync(plan.targetPath)) {
+        return handleExistingTarget(plan, deps.stateDir, home, io);
+    }
+    writeAtomicExcl(plan.targetPath, plan.content, plan.fileMode);
+    const loadOpts = { homedir: home, onWarn: ioWarn(io) };
+    saveState(deps.stateDir, upsertEntry(loadState(deps.stateDir, loadOpts), planToEntry(plan)));
+    io.out(`Installed Keiko launcher at ${plan.targetPath}.\n`);
+    io.out("Remove with: keiko launcher remove\n");
+    return 0;
+}
+// F1 remove-time barrier: even though parseEntry filters out-of-bounds entries at load
+// time, we repeat the containment check here so a state row that bypassed the parser
+// (e.g. via a future call site without homedir context) cannot reach `unlinkSync` with
+// an attacker-controlled path. The throw is caught by `runLauncherCli` and surfaced as
+// a non-zero exit; we never delete or even probe `existsSync` on an out-of-bounds path.
+function processRemoveEntry(entry, args, io, homedir) {
+    assertRealpathContained(launcherFor(entry.platform).installDirFor(homedir), entry.path);
+    if (!existsSync(entry.path)) {
+        io.out(`missing: ${entry.path} (already gone — state cleared)\n`);
+        return "missing";
+    }
+    const existing = readFileSync(entry.path, "utf8");
+    if (hashContent(existing) !== entry.contentSha256) {
+        io.err(`refusing: ${entry.path} (content does not match the launcher Keiko generated; not deleted)\n`);
+        return "refused";
+    }
+    if (args.dryRun || args.explain) {
+        io.out(`would-delete: ${entry.path}\n`);
+        return "would-delete";
+    }
+    unlinkSync(entry.path);
+    io.out(`removed: ${entry.path}\n`);
+    return "removed";
+}
+// Shared launcher-shortcut removal used by both `keiko launcher remove` and
+// `keiko uninstall`. Loads the home-contained launcher state, content-hash-verifies
+// every recorded shortcut before unlinking (refusing any file whose content no longer
+// matches what Keiko generated), and persists the pruned state. When `dryRun` is true
+// it reports `would-delete` without touching the filesystem or the state file. The
+// returned counts let `uninstall` fold launcher refusals into its overall exit code.
+export function removeLauncherShortcuts(io, deps) {
+    const state = loadState(deps.stateDir, { homedir: deps.homedir, onWarn: ioWarn(io) });
+    if (state.entries.length === 0) {
+        io.out("Keiko launcher: nothing to remove (no recorded shortcuts).\n");
+        return { removed: 0, refused: 0, missing: 0 };
+    }
+    const removeArgs = { dryRun: deps.dryRun, explain: false };
+    let nextState = state;
+    let removed = 0;
+    let refused = 0;
+    let missing = 0;
+    for (const entry of state.entries) {
+        const outcome = processRemoveEntry(entry, removeArgs, io, deps.homedir);
+        if (outcome === "missing" || outcome === "removed")
+            nextState = removeEntry(nextState, entry.path);
+        if (outcome === "removed")
+            removed += 1;
+        else if (outcome === "refused")
+            refused += 1;
+        else if (outcome === "missing")
+            missing += 1;
+    }
+    if (!deps.dryRun) {
+        saveState(deps.stateDir, nextState);
+        io.out(`Keiko launcher: removed ${String(removed)} shortcut(s).\n`);
+    }
+    return { removed, refused, missing };
+}
+function cmdRemove(args, io, deps) {
+    const result = removeLauncherShortcuts(io, {
+        stateDir: deps.stateDir,
+        homedir: deps.homedir,
+        dryRun: args.dryRun || args.explain,
+    });
+    return result.refused > 0 ? 1 : 0;
+}
+function cmdStatus(io, deps) {
+    // F2 — parse-time containment in `loadState` already filters out-of-bounds entries
+    // before we reach `existsSync`/`readFileSync`, so a tampered state file cannot turn
+    // `status` into an arbitrary-file-existence/content probe. We additionally wrap the
+    // read in try/catch so an unreadable/EISDIR target classifies as `unreadable` instead
+    // of leaking the OS error (and its stack) onto stderr.
+    const state = loadState(deps.stateDir, { homedir: deps.homedir, onWarn: ioWarn(io) });
+    if (state.entries.length === 0) {
+        io.out("Keiko launcher: no shortcuts recorded.\n");
+        return 0;
+    }
+    for (const entry of state.entries) {
+        if (!existsSync(entry.path)) {
+            io.out(`${entry.path}\tmissing\n`);
+            continue;
+        }
+        let existing;
+        try {
+            existing = readFileSync(entry.path, "utf8");
+        }
+        catch {
+            io.out(`${entry.path}\tunreadable\n`);
+            continue;
+        }
+        const matches = hashContent(existing) === entry.contentSha256;
+        io.out(`${entry.path}\t${matches ? "ok" : "modified"}\n`);
+    }
+    return 0;
+}
+function isLauncherSubcommand(s) {
+    return s === "install" || s === "remove" || s === "status";
+}
+function resolveDeps(env, deps) {
+    const cwd = deps.cwd ?? process.cwd();
+    const homedirFn = deps.homedir ?? defaultHomedir;
+    return {
+        homedir: homedirFn,
+        platform: deps.platform ?? (() => process.platform),
+        resolveExe: deps.resolveExe ?? defaultResolveExe,
+        stateDir: deps.stateDir ?? defaultStateDir(cwd, env, homedirFn()),
+    };
+}
+export function runLauncherCli(args, io, env, deps = {}) {
+    const first = args[0];
+    if (first === undefined || first === "--help" || first === "-h") {
+        io.out(USAGE);
+        return 0;
+    }
+    if (!isLauncherSubcommand(first)) {
+        io.err(`keiko launcher: unknown subcommand: ${first}\n`);
+        io.err(USAGE);
+        return 2;
+    }
+    const rest = args.slice(1);
+    try {
+        // `resolveDeps` may throw `STATE_DIR_ESCAPE` (F4) when KEIKO_STATE_DIR resolves
+        // outside the user's home — it MUST be inside the try/catch so the LauncherError
+        // is converted to a `1` exit instead of an uncaught throw.
+        const r = resolveDeps(env, deps);
+        const home = r.homedir();
+        const handlers = {
+            install: () => dispatchInstall(rest, io, env, r),
+            remove: () => dispatchRemove(rest, io, { stateDir: r.stateDir, homedir: home }),
+            status: () => cmdStatus(io, { stateDir: r.stateDir, homedir: home }),
+        };
+        return handlers[first]();
+    }
+    catch (e) {
+        if (e instanceof LauncherError) {
+            io.err(`${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}
+function dispatchInstall(rest, io, env, ctx) {
+    const parsed = parseInstallArgs(rest);
+    if (!parsed.ok) {
+        io.err(`keiko launcher install: ${parsed.message}\n`);
+        io.err(USAGE);
+        return 2;
+    }
+    return cmdInstall(parsed.value, io, env, ctx);
+}
+function dispatchRemove(rest, io, ctx) {
+    const parsed = parseRemoveArgs(rest);
+    if (!parsed.ok) {
+        io.err(`keiko launcher remove: ${parsed.message}\n`);
+        io.err(USAGE);
+        return 2;
+    }
+    return cmdRemove(parsed.value, io, ctx);
+}