@oscharko-dev/keiko-cli 0.2.0

package/dist/uninstall.js

@@ -0,0 +1,345 @@
+// `keiko uninstall` — reverses the runtime artifacts Keiko creates on a machine so a
+// user can clean their device and reinstall a clean version. CLI-only surface; no UI
+// route, no server change, no new runtime dependency.
+//
+// SCOPE BOUNDARY (deliberate, see PR rationale): Keiko never removes its own installed
+// npm package. A running Node process cannot reliably delete the package files it is
+// executing from, and the deterministic-first architecture avoids shelling into a
+// package manager. `uninstall` therefore reverses only Keiko-OWNED runtime artifacts
+// and prints the exact package-manager command to remove the package itself — the same
+// guidance `keiko doctor` already gives. The artifacts reversed are:
+//
+//   1. Launcher OS shortcuts — delegated to `removeLauncherShortcuts`, which
+//      content-hash-verifies each recorded shortcut and refuses any foreign/modified
+//      file (home-contained; never deletes a file Keiko did not generate).
+//   2. `keiko:start` / `keiko:stop` scripts in the project `package.json` — removed
+//      ONLY when their value exactly matches what `keiko init` writes, so a
+//      user-customized script is never clobbered.
+//   3. The `.keiko/` state directory — every artifact the allowlisted runtime-state
+//      manifest (`state-paths.ts`, Issue #1321) recognizes is removed: lifecycle/launcher
+//      files, the UI / Memory / Local-Knowledge databases and their WAL/SHM sidecars,
+//      Evidence and Quality-Intelligence records, and the sealed credential vaults. An
+//      unrecognized customer file and any symlink are left in place; a directory (and the
+//      state root) is removed only once no such entry survives beneath it. Nothing
+//      recursively deletes an arbitrary directory or follows a symlink out of `.keiko`.
+//
+// With no scope flag every step runs; `--state` / `--launchers` / `--scripts` narrow
+// it. `--dry-run` reports `would-...` without changing anything.
+import { existsSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir as defaultHomedir } from "node:os";
+import { join, resolve } from "node:path";
+import { LauncherError } from "./launcher-platforms.js";
+import { removeLauncherShortcuts } from "./launcher.js";
+import { KEIKO_START_SCRIPT, KEIKO_STOP_SCRIPT } from "./init.js";
+import { localPackageRoot } from "./install-layout.js";
+import { classifyPid, defaultIsProcessAlive, inspectStateRoot, isInsidePath, resolveStateDir, scanRuntimeState, } from "./state-paths.js";
+const USAGE = `Usage:
+  keiko uninstall [--state] [--launchers] [--scripts] [--state-dir PATH]
+                  [--package PATH] [--force] [--dry-run]
+
+Reverses the runtime artifacts Keiko creates on this machine:
+  --launchers  remove the user-local OS shortcut(s) (\`keiko launcher install\`)
+  --scripts    remove the keiko:start / keiko:stop scripts from package.json
+  --state      remove Keiko-owned runtime state under .keiko: lifecycle/launcher files,
+               UI / Memory / Local-Knowledge databases and their WAL/SHM sidecars,
+               Evidence and Quality-Intelligence records, and the sealed credential vaults
+
+With no scope flag, all three are removed. An unknown (non-Keiko) file under .keiko and any
+symlink are always left in place, and the state directory is removed only once nothing of
+yours remains. The installed npm package itself is left in place; the command prints the
+package-manager step to remove it. \`--force\` stops a running UI before removing state;
+\`--dry-run\` shows what would be removed. Filesystem unlinking does not guarantee secure
+erasure of SSD-backed data.
+`;
+const KEIKO_SCRIPTS = {
+    "keiko:start": KEIKO_START_SCRIPT,
+    "keiko:stop": KEIKO_STOP_SCRIPT,
+};
+function readFlagValue(args, index) {
+    const value = args[index + 1];
+    return value === undefined || value.startsWith("--") ? null : value;
+}
+function applyValuedFlag(raw, arg, value) {
+    if (arg === "--state-dir")
+        raw.stateDirArg = value;
+    else
+        raw.packageArg = value;
+}
+function applyBooleanFlag(raw, arg) {
+    switch (arg) {
+        case "--state":
+            raw.state = true;
+            return true;
+        case "--launchers":
+            raw.launchers = true;
+            return true;
+        case "--scripts":
+            raw.scripts = true;
+            return true;
+        case "--dry-run":
+            raw.dryRun = true;
+            return true;
+        case "--force":
+            raw.force = true;
+            return true;
+        default:
+            return false;
+    }
+}
+function parseUninstallArgs(args, cwd) {
+    const raw = {
+        state: false,
+        launchers: false,
+        scripts: false,
+        stateDirArg: undefined,
+        packageArg: undefined,
+        dryRun: false,
+        force: false,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined)
+            return null;
+        if (arg === "--help" || arg === "-h")
+            return "help";
+        if (applyBooleanFlag(raw, arg))
+            continue;
+        if (arg === "--state-dir" || arg === "--package") {
+            const value = readFlagValue(args, i);
+            if (value === null)
+                return null;
+            applyValuedFlag(raw, arg, value);
+            i += 1;
+            continue;
+        }
+        return null;
+    }
+    return finalizeOptions(raw, cwd);
+}
+function finalizeOptions(raw, cwd) {
+    const anyScope = raw.state || raw.launchers || raw.scripts;
+    return {
+        scopes: anyScope
+            ? { state: raw.state, launchers: raw.launchers, scripts: raw.scripts }
+            : { state: true, launchers: true, scripts: true },
+        packagePath: raw.packageArg === undefined ? resolve(cwd, "package.json") : resolve(cwd, raw.packageArg),
+        stateDirArg: raw.stateDirArg,
+        dryRun: raw.dryRun,
+        force: raw.force,
+    };
+}
+function resolveDeps(deps) {
+    return {
+        cwd: deps.cwd ?? process.cwd(),
+        homedir: deps.homedir ?? defaultHomedir,
+        isProcessAlive: deps.isProcessAlive ?? defaultIsProcessAlive,
+        killProcess: deps.killProcess ?? process.kill.bind(process),
+    };
+}
+// Returns "ok" to proceed, or "refused" when state removal is requested while the UI is
+// running and `--force` was not given (removing live state would orphan the process).
+function ensureServerStoppable(opts, io, deps, stateDir) {
+    if (!opts.scopes.state)
+        return "ok";
+    const probe = classifyPid(join(stateDir, "ui.pid"), deps.isProcessAlive);
+    if (probe.state !== "running" || probe.pid === undefined)
+        return "ok";
+    if (!opts.force) {
+        io.err(`keiko uninstall: the Keiko UI is running (pid ${String(probe.pid)}). Run \`keiko stop\` first, or re-run with --force to stop it.\n`);
+        return "refused";
+    }
+    if (opts.dryRun) {
+        io.out(`would-stop: Keiko UI (pid ${String(probe.pid)})\n`);
+        return "ok";
+    }
+    io.out(`Stopping Keiko UI (pid ${String(probe.pid)}) ...\n`);
+    try {
+        deps.killProcess(probe.pid, "SIGTERM");
+    }
+    catch {
+        // Process already exited between the probe and the signal — nothing to stop.
+    }
+    return "ok";
+}
+function removeLaunchersStep(opts, io, deps, stateDir) {
+    if (!opts.scopes.launchers)
+        return 0;
+    const result = removeLauncherShortcuts(io, {
+        stateDir,
+        homedir: deps.homedir(),
+        dryRun: opts.dryRun,
+    });
+    return result.refused;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function pruneKeikoScripts(scripts, io, dryRun) {
+    const removeNames = new Set();
+    for (const [name, expected] of Object.entries(KEIKO_SCRIPTS)) {
+        if (!(name in scripts))
+            continue;
+        if (scripts[name] !== expected) {
+            io.out(`kept: ${name} (customized — not the script keiko init writes)\n`);
+            continue;
+        }
+        io.out(`${dryRun ? "would-remove" : "removed"}: package.json script ${name}\n`);
+        removeNames.add(name);
+    }
+    const next = Object.fromEntries(Object.entries(scripts).filter(([key]) => !removeNames.has(key)));
+    return { next, removed: removeNames.size };
+}
+function removeScriptsStep(opts, io) {
+    if (!opts.scopes.scripts)
+        return;
+    if (!existsSync(opts.packagePath)) {
+        io.out(`scripts: package.json not found at ${opts.packagePath} (nothing to remove)\n`);
+        return;
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(opts.packagePath, "utf8"));
+    }
+    catch {
+        io.err(`keiko uninstall: package.json at ${opts.packagePath} is not valid JSON; skipping scripts.\n`);
+        return;
+    }
+    const scripts = isRecord(pkg) ? pkg.scripts : undefined;
+    if (!isRecord(pkg) || !isRecord(scripts)) {
+        io.out("scripts: no keiko:start / keiko:stop scripts found.\n");
+        return;
+    }
+    const { next, removed } = pruneKeikoScripts(scripts, io, opts.dryRun);
+    if (removed > 0 && !opts.dryRun) {
+        writeFileSync(opts.packagePath, `${JSON.stringify({ ...pkg, scripts: next }, null, 2)}\n`, "utf8");
+    }
+}
+// Issue #1321: remove every Keiko-owned sensitive runtime artifact under the state dir,
+// not only the three lifecycle/launcher files. The set is the allowlisted manifest in
+// `state-paths.ts` (UI/Memory/Knowledge DBs + sidecars, Evidence/QI records, the sealed
+// credential vaults, config, logs). Anything the manifest does not recognize — an unknown
+// customer file or a symlink — is reported and left in place, and a directory is removed
+// only when no such retained entry survives beneath it. Content-free: paths only.
+function removeOwnedFiles(scan, io, dryRun) {
+    for (const file of scan.files) {
+        if (dryRun) {
+            io.out(`would-remove: ${file.absPath}\n`);
+            continue;
+        }
+        unlinkSync(file.absPath);
+        io.out(`removed: ${file.absPath}\n`);
+    }
+}
+function reportRetained(scan, io) {
+    for (const entry of scan.retained) {
+        const why = entry.reason === "symlink"
+            ? "symlink — not followed"
+            : entry.reason === "hardlink"
+                ? "hardlink — not modified or removed"
+                : "not a recognized Keiko artifact";
+        io.out(`kept: ${entry.absPath} (${why})\n`);
+    }
+}
+// Owned directories are visited deepest-first (the scan lists them shallowest-first). A
+// directory is removed only when no retained entry lives beneath it, so an unknown file or
+// a refused symlink anywhere inside keeps the whole chain up to the state root in place.
+function removeOwnedDirectories(scan, io, dryRun) {
+    for (const dir of [...scan.directories].reverse()) {
+        if (scan.retained.some((entry) => isInsidePath(dir.absPath, entry.absPath)))
+            continue;
+        if (dryRun) {
+            io.out(`would-remove: ${dir.absPath}\n`);
+            continue;
+        }
+        rmdirSync(dir.absPath);
+        io.out(`removed: ${dir.absPath}\n`);
+    }
+}
+function finalizeStateDir(scan, stateDir, io, dryRun) {
+    if (scan.retained.length === 0) {
+        if (dryRun)
+            io.out(`would-remove: ${stateDir} (empty after removals)\n`);
+        else {
+            rmdirSync(stateDir);
+            io.out(`removed: ${stateDir}\n`);
+        }
+        return;
+    }
+    const topLevel = new Set(scan.retained.map((entry) => entry.relPath.split("/")[0] ?? entry.relPath));
+    const count = topLevel.size;
+    io.out(`kept: ${stateDir} (still contains ${String(count)} non-Keiko entr${count === 1 ? "y" : "ies"})\n`);
+}
+function removeStateStep(opts, io, stateDir) {
+    if (!opts.scopes.state)
+        return;
+    if (!existsSync(stateDir)) {
+        io.out(`state: ${stateDir} not found (nothing to remove)\n`);
+        return;
+    }
+    const scan = scanRuntimeState(stateDir);
+    removeOwnedFiles(scan, io, opts.dryRun);
+    reportRetained(scan, io);
+    removeOwnedDirectories(scan, io, opts.dryRun);
+    finalizeStateDir(scan, stateDir, io, opts.dryRun);
+}
+function refuseUnsafeStateRoot(opts, io, root) {
+    if (!opts.scopes.state && !opts.scopes.launchers)
+        return false;
+    if (root.status === "symlink") {
+        io.err(`keiko uninstall: refusing to use symlinked state directory: ${root.absPath}\n`);
+        return true;
+    }
+    if (root.status === "not-directory") {
+        io.err(`keiko uninstall: refusing to use non-directory state path: ${root.absPath}\n`);
+        return true;
+    }
+    return false;
+}
+function printPackageGuidance(io, deps) {
+    const localInstalled = existsSync(localPackageRoot(deps.cwd));
+    io.out("\nKeiko runtime artifacts processed. To remove the package itself, run:\n");
+    if (localInstalled) {
+        io.out("  npm uninstall @oscharko-dev/keiko        (local install in this project)\n");
+        io.out("  npm uninstall -g @oscharko-dev/keiko     (if also installed globally)\n");
+    }
+    else {
+        io.out("  npm uninstall -g @oscharko-dev/keiko     (global install)\n");
+        io.out("  npm uninstall @oscharko-dev/keiko        (if installed locally in a project)\n");
+    }
+    io.out("  yarn remove @oscharko-dev/keiko  •  pnpm remove @oscharko-dev/keiko  (yarn / pnpm)\n");
+}
+export function runUninstallCli(args, io, env, deps = {}) {
+    const resolved = resolveDeps(deps);
+    const opts = parseUninstallArgs(args, resolved.cwd);
+    if (opts === "help") {
+        io.out(USAGE);
+        return 0;
+    }
+    if (opts === null) {
+        io.err(USAGE);
+        return 2;
+    }
+    const stateDir = resolveStateDir(resolved.cwd, env, opts.stateDirArg);
+    const stateRoot = inspectStateRoot(stateDir);
+    if (refuseUnsafeStateRoot(opts, io, stateRoot))
+        return 1;
+    try {
+        if (ensureServerStoppable(opts, io, resolved, stateDir) === "refused")
+            return 1;
+        const launcherRefused = removeLaunchersStep(opts, io, resolved, stateDir);
+        removeScriptsStep(opts, io);
+        removeStateStep(opts, io, stateDir);
+        printPackageGuidance(io, resolved);
+        return launcherRefused > 0 ? 1 : 0;
+    }
+    catch (e) {
+        if (e instanceof LauncherError) {
+            io.err(`${e.message}\n`);
+            return 1;
+        }
+        // Filesystem errors (e.g. a read-only package.json or state file) are reported as a
+        // clean non-zero exit rather than crashing the CLI with an unhandled exception.
+        io.err(`keiko uninstall: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+}

package/dist/verify.d.ts

@@ -0,0 +1,3 @@
+import type { CliIo } from "./runner.js";
+export declare function runVerifyCli(args: readonly string[], io: CliIo): Promise<number>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAoFzC,wBAAsB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BtF"}

package/dist/verify.js

@@ -0,0 +1,108 @@
+// `keiko verify` — the real verification gate (NOT a dry-run). It detects the workspace, builds a
+// plan from the detected npm scripts, runs the allowlisted commands through the #6 safe tool layer
+// under per-command resource limits, and prints a redacted human table (or --json of the report).
+// Exit 0 when overall status is `passed`; 1 when any step did not pass or a workspace/runtime error
+// occurred; 2 on a usage error. Mirrors runContextCli's structure (flag parsing, --json, typed
+// error catch at the boundary).
+import { detectWorkspace, WorkspaceError } from "@oscharko-dev/keiko-workspace";
+import { buildVerificationPlan, buildVerificationSummary, detectScripts, EmptyPlanError, runVerification, VerificationError, } from "@oscharko-dev/keiko-verification";
+const VALID_KINDS = new Set([
+    "test",
+    "targeted-test",
+    "typecheck",
+    "lint",
+    "build",
+]);
+const USAGE = `Usage:
+  keiko verify [--dir PATH] [--only KIND[,KIND]] [--changed FILE[,FILE]] [--json]
+
+Runs the project's own gates (typecheck, lint, test, build) through the safe tool
+layer under per-command resource limits and prints a redacted evidence summary.
+KIND is one of: test, targeted-test, typecheck, lint, build.
+`;
+// Returns the value of a `--flag value` pair, undefined if absent, or null if present without a
+// value (a usage error) — identical contract to runContextCli's flagValue.
+function flagValue(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1) {
+        return undefined;
+    }
+    const value = args[i + 1];
+    return value === undefined || value.startsWith("--") ? null : value;
+}
+function parseKinds(raw) {
+    const parts = raw.split(",").map((p) => p.trim());
+    if (parts.some((p) => !VALID_KINDS.has(p))) {
+        return null;
+    }
+    return parts;
+}
+function parseArgs(args) {
+    const dirRaw = flagValue(args, "--dir");
+    const onlyRaw = flagValue(args, "--only");
+    const changedRaw = flagValue(args, "--changed");
+    if (dirRaw === null || onlyRaw === null || changedRaw === null) {
+        return null;
+    }
+    const only = onlyRaw === undefined ? undefined : parseKinds(onlyRaw);
+    if (only === null) {
+        return null;
+    }
+    const changed = changedRaw === undefined ? undefined : changedRaw.split(",").map((p) => p.trim());
+    return { dir: dirRaw ?? ".", only, changed, json: args.includes("--json") };
+}
+async function runPlan(parsed) {
+    const workspace = detectWorkspace(parsed.dir);
+    const catalog = detectScripts(workspace);
+    const plan = buildVerificationPlan(workspace, catalog, {
+        only: parsed.only,
+        changedFiles: parsed.changed,
+    });
+    if (plan.steps.length === 0) {
+        throw new EmptyPlanError("verification plan contains no runnable or skipped steps");
+    }
+    return runVerification(plan, { workspace });
+}
+function renderText(report, io) {
+    const summary = buildVerificationSummary(report);
+    io.out(`Verification: ${summary.overallStatus} (${String(summary.durationMs)}ms)\n`);
+    io.out("KIND\tSTATUS\tEXIT\tMS\tCOMMAND\tDETAIL\n");
+    for (const r of summary.results) {
+        const exit = r.exitCode === null ? "-" : String(r.exitCode);
+        io.out(`${r.kind}\t${r.status}\t${exit}\t${String(r.durationMs)}\t${r.command}\t${r.detail ?? ""}\n`);
+    }
+}
+export async function runVerifyCli(args, io) {
+    // Issue #640: handle --help / -h before workflow-arg validation so help discovery exits 0
+    // with usage on stdout, not 2 with a validation error on stderr.
+    if (args.includes("--help") || args.includes("-h")) {
+        io.out(USAGE);
+        return 0;
+    }
+    const parsed = parseArgs(args);
+    if (parsed === null) {
+        io.err(USAGE);
+        return 2;
+    }
+    try {
+        const report = await runPlan(parsed);
+        if (parsed.json) {
+            io.out(`${JSON.stringify(buildVerificationSummary(report), null, 2)}\n`);
+        }
+        else {
+            renderText(report, io);
+        }
+        return report.overallStatus === "passed" ? 0 : 1;
+    }
+    catch (error) {
+        if (error instanceof WorkspaceError) {
+            io.err(`Error [${error.code}]: ${error.message}\n`);
+            return 1;
+        }
+        if (error instanceof VerificationError) {
+            io.err(`Error [${error.code}]: ${error.message}\n`);
+            return 1;
+        }
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@oscharko-dev/keiko-cli",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Internal CLI package: command modules for the `keiko` binary shipped via the root product package (ADR-0019). Not published independently.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@oscharko-dev/keiko-contracts": "0.2.0",
+    "@oscharko-dev/keiko-security": "0.2.0",
+    "@oscharko-dev/keiko-model-gateway": "0.2.0",
+    "@oscharko-dev/keiko-workspace": "0.2.0",
+    "@oscharko-dev/keiko-tools": "0.2.0",
+    "@oscharko-dev/keiko-evaluations": "0.2.0",
+    "@oscharko-dev/keiko-evidence": "0.2.0",
+    "@oscharko-dev/keiko-verification": "0.2.0",
+    "@oscharko-dev/keiko-harness": "0.2.0",
+    "@oscharko-dev/keiko-sdk": "0.2.0",
+    "@oscharko-dev/keiko-workflows": "0.2.0",
+    "@oscharko-dev/keiko-server": "0.2.0",
+    "@oscharko-dev/keiko-memory-vault": "0.2.0"
+  }
+}