@garygentry/feature-forge 0.1.0

package/dist/cli.js

@@ -0,0 +1,508 @@
+/**
+ * CLI entry & dispatch (spec 07). The installer's process entry point and orchestration
+ * layer: it parses `process.argv` via `node:util.parseArgs`, resolves the target agent set,
+ * runs the per-agent plan/apply (or list) pipeline catching per-agent failures, renders the
+ * `RunReport`, and returns the process exit code.
+ *
+ * Zero runtime deps (`node:` built-ins only). Core functions return `Result`/`RunReport` and
+ * never throw for expected errors; `main` is the single boundary that maps to exit codes and
+ * touches `process`. `runCli` is the env-injectable testable core (the hermetic seam item 011
+ * relies on). Named exports only.
+ */
+import { parseArgs } from "node:util";
+import process from "node:process";
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import * as path from "node:path";
+import { AGENT_IDS, AGENT_TARGETS, EXIT, err, ok, } from "./types.js";
+import { detectAgent, detectAgents, resolveRoots } from "./agent-targets.js"; // 02
+import { locateSource } from "./source.js"; // 03
+import { plan, resolveMode } from "./plan.js"; // 04
+import { apply } from "./apply.js"; // 04
+import { manifestPath, readManifest, planUninstall } from "./manifest.js"; // 05
+import { preflightRauf, RAUF_PIN } from "./rauf.js"; // 06
+import { sha256File } from "./hash.js"; // 03 (list destination-drift hashing)
+import { renderReport } from "./report.js"; // 09
+/** Canonical subcommand table (REQ-DIST-03, §1.2). */
+export const SUBCOMMANDS = [
+    { canonical: "install", aliases: ["add"], help: "Install feature-forge into the target agent(s)." },
+    { canonical: "update", aliases: [], help: "Reconcile an existing install to the current adapters." },
+    { canonical: "uninstall", aliases: ["remove"], help: "Remove a prior install (manifest-tracked files only)." },
+    { canonical: "list", aliases: ["ls"], help: "Report per-agent detected / installed / up-to-date status." },
+];
+/** Canonical flag table (REQ-FLAG-01..05, §1.3). */
+export const FLAGS = [
+    { name: "agent", short: "a", type: "string", arg: "<id>", help: `Scope to one agent (${AGENT_IDS.join("|")}). Default: all detected.` },
+    { name: "global", short: "g", type: "boolean", help: "Install into the user-level config dir (default: project-local)." },
+    { name: "symlink", type: "boolean", help: "Symlink the bundle instead of copying (default: copy; Windows always copies)." },
+    { name: "force", type: "boolean", help: "Overwrite a locally-modified destination that would otherwise be skipped." },
+    { name: "dry-run", type: "boolean", help: "Print the planned actions without changing anything." },
+    { name: "yes", short: "y", type: "boolean", help: "Non-interactive: assume confirmed; never block on input." },
+    { name: "json", type: "boolean", help: "Emit the run report as JSON." },
+    { name: "skip-rauf", type: "boolean", help: "Skip the rauf resolvability preflight (records raufPin: null)." },
+    { name: "source", type: "string", arg: "<dir>", hidden: true, help: "(test only) Override the adapters source directory." },
+    { name: "help", short: "h", type: "boolean", help: "Show this help and exit." },
+    { name: "version", type: "boolean", help: "Print the installer version and exit." },
+];
+/**
+ * Parse and validate `argv` (already sliced past `node` + script — `process.argv.slice(2)`)
+ * via `node:util.parseArgs` (zero-dep). Resolves aliases, rejects unknown
+ * subcommand/flag/agent (and a parseArgs throw) as a `USAGE` error. Pure: no I/O, no exit.
+ */
+export function parseCliArgs(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options: buildParseOptions(), allowPositionals: true });
+    }
+    catch (e) {
+        return usage(`invalid arguments: ${e.message}`);
+    }
+    const positionals = parsed.positionals;
+    const values = parsed.values;
+    const wantsHelp = values.help === true;
+    const wantsVersion = values.version === true;
+    // Resolve the subcommand (first positional) unless help/version short-circuits in main().
+    const raw = positionals[0];
+    let subcommand;
+    if (raw !== undefined) {
+        subcommand = resolveSubcommand(raw);
+        if (subcommand === undefined) {
+            return usage(`unknown subcommand '${raw}'. Run 'feature-forge --help' for usage.`);
+        }
+        if (positionals.length > 1) {
+            return usage(`unexpected extra argument '${positionals[1]}'.`);
+        }
+    }
+    else if (!wantsHelp && !wantsVersion) {
+        return usage("no subcommand given. Run 'feature-forge --help' for usage.");
+    }
+    // Validate --agent against the closed set (REQ-FLAG-01).
+    let agent;
+    const agentRaw = values.agent;
+    if (typeof agentRaw === "string") {
+        if (!isAgentId(agentRaw)) {
+            return usage(`unknown agent '${agentRaw}'. Valid: ${AGENT_IDS.join(", ")}.`);
+        }
+        agent = agentRaw;
+    }
+    const flags = {
+        agent,
+        global: values.global === true,
+        symlink: values.symlink === true,
+        force: values.force === true,
+        dryRun: values["dry-run"] === true,
+        yes: values.yes === true,
+        json: values.json === true,
+        skipRauf: values["skip-rauf"] === true,
+        source: typeof values.source === "string" ? values.source : undefined,
+    };
+    // help/version with no subcommand is still "ok": main() acts on flags before requiring a
+    // subcommand. "list" is a harmless placeholder main() never reaches in that case.
+    return ok({ subcommand: subcommand ?? "list", flags });
+}
+/**
+ * Build the `node:util.parseArgs` `options` object from the single FLAGS spec (§1.5) so parsing
+ * always equals the documented surface (REQ-DIST-03). The SOLE source of the parse config —
+ * shared by `parseCliArgs` and `rawParse` so the two can never drift.
+ */
+function buildParseOptions() {
+    const options = {};
+    for (const f of FLAGS) {
+        options[f.name] = f.short ? { type: f.type, short: f.short } : { type: f.type };
+    }
+    return options;
+}
+/** Resolve an alias/canonical token to a `Subcommand`, or undefined if unknown. */
+function resolveSubcommand(token) {
+    for (const s of SUBCOMMANDS) {
+        if (s.canonical === token || s.aliases.includes(token))
+            return s.canonical;
+    }
+    return undefined;
+}
+/** Narrowing guard for the closed `AgentId` set. */
+function isAgentId(v) {
+    return AGENT_IDS.includes(v);
+}
+/** Small helper: a USAGE Result (mapped to EXIT.USAGE at the boundary). */
+function usage(message) {
+    return err({ code: "USAGE", message, remedy: "Run 'feature-forge --help' for usage." });
+}
+/**
+ * Map a structured `InstallerError` to a process exit code (tech-spec §7).
+ * "USAGE" → EXIT.USAGE (2); everything else → EXIT.FAILURE (1).
+ */
+export function mapErrorToExit(error) {
+    return error.code === "USAGE" ? EXIT.USAGE : EXIT.FAILURE;
+}
+/**
+ * Run the full CLI pipeline programmatically and return the assembled `RunReport` WITHOUT
+ * touching `process` (no argv read, no stdout/stderr write, no exit). This is the testable
+ * core (08 §3.4): it threads env.home/cwd into detection/manifest calls, env.registry into the
+ * rauf preflight, and env.platform into the copy/symlink mode decision.
+ */
+export async function runCli(argv, env = {}) {
+    const parsed = parseCliArgs(argv);
+    if (!parsed.ok) {
+        // runCli's contract is the dispatch core; parse validation is owned by main (§3.1). Direct
+        // callers with malformed argv surface here as an unexpected throw (main never reaches this).
+        throw new Error(parsed.error.message);
+    }
+    const { subcommand, flags } = parsed.value;
+    return subcommand === "list"
+        ? runList(flags, env)
+        : runMutation(subcommand, flags, env);
+}
+// ---------------------------------------------------------------------------
+// 4. main — the dispatch boundary (§3.1)
+// ---------------------------------------------------------------------------
+/**
+ * Parse → help/version precedence → run pipeline (catching per-agent errors via runCli) →
+ * render → exit code. The only place that writes to stdout/stderr and decides the exit code.
+ * Never reads stdin (REQ-DIST-02).
+ *
+ * @param argv - the post-`node` argument list (`process.argv.slice(2)` in production).
+ * @param env  - the injectable CLI env (the hermetic-test seam, §3.1a); default `{}` = real
+ *               defaults. Tests inject a throwing seam (e.g. a registry that throws) here to
+ *               exercise the UNEXPECTED boundary catch deterministically without a network call.
+ */
+export async function main(argv, env = {}) {
+    let report;
+    let json = false;
+    try {
+        const parsed = parseCliArgs(argv);
+        if (!parsed.ok) {
+            process.stderr.write(`error: ${parsed.error.message}\n\n`);
+            process.stderr.write(helpText() + "\n");
+            return mapErrorToExit(parsed.error); // EXIT.USAGE
+        }
+        const { flags } = parsed.value;
+        json = flags.json;
+        const meta = parseMetaFlags(argv); // --help/--version (not part of CliFlags)
+        if (meta.help) {
+            process.stdout.write(helpText() + "\n");
+            return EXIT.SUCCESS;
+        }
+        if (meta.version) {
+            process.stdout.write(readInstallerVersion() + "\n");
+            return EXIT.SUCCESS;
+        }
+        if (!hadSubcommand(argv)) {
+            process.stderr.write("error: no subcommand given.\n\n");
+            process.stderr.write(helpText() + "\n");
+            return EXIT.USAGE;
+        }
+        report = await runCli(argv, env);
+    }
+    catch (e) {
+        // Boundary catch: an UNEXPECTED exception must never surface as a bare stack alone
+        // (tech-spec §7). Print a one-line actionable message and exit 1.
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`error: unexpected failure: ${msg}\n`);
+        return EXIT.FAILURE;
+    }
+    process.stdout.write(renderReport(report, { json }) + "\n");
+    return report.exitCode;
+}
+/** Raw parseArgs over the single FLAGS spec (shared `buildParseOptions`); null if argv is malformed. */
+function rawParse(argv) {
+    try {
+        return parseArgs({ args: argv, options: buildParseOptions(), allowPositionals: true });
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the `--help`/`--version` booleans (recognized before subcommand validation, §1.4). */
+function parseMetaFlags(argv) {
+    const parsed = rawParse(argv);
+    const values = (parsed?.values ?? {});
+    return { help: values.help === true, version: values.version === true };
+}
+/** True iff `argv` carries a leading positional (a subcommand token), per parseArgs. */
+function hadSubcommand(argv) {
+    const parsed = rawParse(argv);
+    return parsed !== null && parsed.positionals.length > 0;
+}
+// ---------------------------------------------------------------------------
+// 5. runMutation — install / update / uninstall (§3.2)
+// ---------------------------------------------------------------------------
+/** Orchestrate a mutating run (install | update | uninstall). Never throws for expected errors. */
+async function runMutation(subcommand, flags, env) {
+    const scope = flags.global ? "global" : "project";
+    const mode = resolveMode(flags.symlink, (env.platform ?? process.platform) === "win32");
+    const ropts = { home: env.home, cwd: env.cwd, scope };
+    const targets = flags.agent
+        ? [flags.agent]
+        : detectAgents(ropts).filter((d) => d.detected).map((d) => d.agent);
+    let raufPin = flags.skipRauf ? null : RAUF_PIN;
+    let raufError;
+    // Rauf preflight: install/update only, once, network only when not dry-run/skip AND there is at
+    // least one target (zero detected ⇒ nothing to do, so no network query — DET-04, REQ-PERF-01).
+    if (targets.length > 0 &&
+        (subcommand === "install" || subcommand === "update") &&
+        !flags.skipRauf &&
+        !flags.dryRun) {
+        const pf = preflightRauf({ skip: flags.skipRauf, query: env.registry });
+        if (!pf.ok) {
+            raufError = pf.error; // RAUF_UNRESOLVABLE — recorded, does NOT abort skill installs
+            raufPin = null; // not resolvable ⇒ no usable pin recorded this run
+        }
+    }
+    const agentReports = [];
+    for (const agent of targets) {
+        const detection = detectAgent(agent, ropts);
+        const r = await runOneAgent(subcommand, agent, detection, flags, scope, mode, raufPin, env);
+        agentReports.push(r);
+    }
+    const anyAgentFailed = agentReports.some((r) => !r.ok);
+    const exitCode = anyAgentFailed || raufError !== undefined ? EXIT.FAILURE : EXIT.SUCCESS;
+    // NOTE (spec 07 §3.2): the `attachRaufError(reports, raufError)` hook is intentionally elided in
+    // favor of the sanctioned run-level `RunReport.raufError` field (a §3.2 MAY). renderReport surfaces
+    // it and it rides the `--json` machine surface (REQ-DET-05); there is no separate attach step.
+    return {
+        subcommand,
+        scope,
+        mode,
+        dryRun: flags.dryRun,
+        agents: agentReports,
+        exitCode,
+        ...(raufError ? { raufError } : {}),
+    };
+}
+/** Run the pipeline for a single agent, returning its AgentReport (catches every expected error). */
+async function runOneAgent(subcommand, agent, detection, flags, scope, mode, raufPin, env) {
+    const mpath = manifestPath(agent, scope, { home: env.home, cwd: env.cwd });
+    const roots = resolveRoots({ home: env.home, cwd: env.cwd, scope });
+    const scopeRoot = scope === "global" ? roots.home : roots.cwd;
+    const agentRoot = path.join(scopeRoot, AGENT_TARGETS[agent].configDirName);
+    // uninstall path: manifest → planUninstall → apply.
+    if (subcommand === "uninstall") {
+        const m = readManifest(mpath);
+        if (!m.ok)
+            return failed(agent, detection.detected, m.error);
+        if (m.value === null) {
+            // Nothing installed for this agent: not an error — an "ok, no-op" report.
+            return { agent, detected: detection.detected, ok: true, actions: [], raufPin: null };
+        }
+        const rp = planUninstall(m.value);
+        if (!rp.ok)
+            return failed(agent, detection.detected, rp.error);
+        const ctx = {
+            agent,
+            scope,
+            mode: m.value.mode,
+            agentRoot,
+            destination: m.value.destination,
+            manifestPath: mpath,
+            source: null,
+            raufPin: null,
+            now: new Date().toISOString(),
+            priorManifest: m.value,
+        };
+        return finishAgent(agent, detection.detected, rp.value, flags, raufPin, ctx);
+    }
+    // install/update path: locate+integrity+fingerprint → readManifest → plan → apply.
+    const located = locateSource(agent, { source: flags.source });
+    if (!located.ok)
+        return failed(agent, detection.detected, located.error);
+    const prior = readManifest(mpath);
+    if (!prior.ok)
+        return failed(agent, detection.detected, prior.error);
+    const planCtx = {
+        agent,
+        scope,
+        mode,
+        destination: detection.destination,
+        source: located.value,
+        priorManifest: prior.value,
+        force: flags.force,
+        raufPin,
+    };
+    const planned = plan(subcommand, planCtx);
+    if (!planned.ok)
+        return failed(agent, detection.detected, planned.error);
+    const ctx = {
+        agent,
+        scope,
+        mode,
+        agentRoot,
+        destination: detection.destination,
+        manifestPath: mpath,
+        source: located.value,
+        raufPin,
+        now: new Date().toISOString(),
+        priorManifest: prior.value,
+    };
+    return finishAgent(agent, detection.detected, planned.value, flags, raufPin, ctx);
+}
+/** Apply a plan unless --dry-run; build the agent's report either way. */
+async function finishAgent(agent, detected, planned, flags, raufPin, ctx) {
+    if (flags.dryRun) {
+        // Plan only: the actions shown are exactly what a real run performs (REQ-OPS-05). No writes.
+        return { agent, detected, ok: true, actions: planned.files, raufPin };
+    }
+    const report = await apply(planned, ctx);
+    if (!report.ok)
+        return failed(agent, detected, report.error ?? unexpected(agent));
+    return { agent, detected, ok: true, actions: report.actions, raufPin };
+}
+/** A failed single-agent report (REQ-OBS-03): ok:false + the structured error. */
+function failed(agent, detected, error) {
+    return { agent, detected, ok: false, actions: [], error };
+}
+/** Fallback error if apply reports ok:false with no attached error (defensive). */
+function unexpected(agent) {
+    return { code: "UNEXPECTED", agent, message: `apply for "${agent}" failed without an error` };
+}
+// ---------------------------------------------------------------------------
+// 6. runList — read-only list/ls (§3.3, REQ-OPS-04, REQ-PERF-01)
+// ---------------------------------------------------------------------------
+/** Orchestrate the read-only `list` operation: no network, no apply, no writes. */
+async function runList(flags, env) {
+    const scope = flags.global ? "global" : "project";
+    const ropts = { home: env.home, cwd: env.cwd, scope };
+    const targets = flags.agent ? [flags.agent] : [...AGENT_IDS];
+    const agentReports = [];
+    for (const agent of targets) {
+        const detection = detectAgent(agent, ropts);
+        agentReports.push(listOneAgent(agent, detection, flags, scope, env));
+    }
+    const anyFailed = agentReports.some((r) => !r.ok);
+    return {
+        subcommand: "list",
+        scope,
+        mode: "copy", // mode is irrelevant for list; report the default for shape stability
+        dryRun: false,
+        agents: agentReports,
+        exitCode: anyFailed ? EXIT.FAILURE : EXIT.SUCCESS,
+    };
+}
+/** Compute one agent's list status without any write or network call (REQ-PERF-01). */
+function listOneAgent(agent, detection, flags, scope, env) {
+    const mpath = manifestPath(agent, scope, { home: env.home, cwd: env.cwd });
+    const m = readManifest(mpath);
+    if (!m.ok)
+        return failed(agent, detection.detected, m.error);
+    const installed = m.value !== null;
+    // Status is carried as synthetic FileAction rows the renderer decodes (status, not file writes):
+    const statusActions = [
+        { relpath: `detected:${detection.detected}`, action: "unchanged" },
+        { relpath: `installed:${installed}`, action: "unchanged" },
+    ];
+    if (installed && m.value !== null) {
+        const located = locateSource(agent, { source: flags.source });
+        if (located.ok) {
+            const upToDate = located.value.sourceHash === m.value.sourceHash;
+            statusActions.push({ relpath: `up-to-date:${upToDate}`, action: "unchanged" });
+        }
+        else {
+            statusActions.push({ relpath: "up-to-date:unknown(source-missing)", action: "unchanged" });
+        }
+        // Destination drift (REQ-SAFE-03, §5.13 list half): a copy-mode install is "drifted" when any
+        // manifest-recorded file's bytes on disk no longer match its recorded sha256 — a local user
+        // edit, independent of whether the SOURCE changed. Reads ONLY the manifest (per-file sha256)
+        // against a fresh local hash (no network, no source needed). Symlink mode has no per-file
+        // sha256 to compare, so drift is reported as not-applicable.
+        statusActions.push({ relpath: `drift:${detectDestinationDrift(m.value)}`, action: "unchanged" });
+    }
+    return {
+        agent,
+        detected: detection.detected,
+        ok: true,
+        actions: statusActions,
+        raufPin: m.value?.raufPin ?? null,
+    };
+}
+/**
+ * Return `"true"` if any manifest-recorded file's on-disk bytes differ from its recorded sha256
+ * (a locally-modified destination, REQ-SAFE-03), `"false"` if every recorded file matches, or
+ * `"n/a(symlink)"` for a symlink-mode install (no per-file sha256 to compare). A missing recorded
+ * file also counts as drift. Pure read of the manifest's per-file sha256 against a fresh local
+ * hash — no network, no source bundle needed (REQ-PERF-01). Hash errors are swallowed as drift
+ * (an unreadable recorded file is itself a deviation from the clean install).
+ */
+function detectDestinationDrift(manifest) {
+    if (manifest.mode === "symlink")
+        return "n/a(symlink)";
+    for (const f of manifest.files) {
+        if (f.sha256 === undefined)
+            continue; // no recorded hash to compare against
+        try {
+            if (sha256File(path.join(manifest.destination, f.path)) !== f.sha256)
+                return "true";
+        }
+        catch {
+            return "true"; // unreadable/absent recorded file ⇒ drift
+        }
+    }
+    return "false";
+}
+// ---------------------------------------------------------------------------
+// 7. helpText and --version (§3.4)
+// ---------------------------------------------------------------------------
+/**
+ * Build the full `--help` text from the single CLI_SPEC (SUBCOMMANDS + FLAGS, §1.5) so the
+ * listed surface can never drift from what parseArgs accepts (REQ-DIST-03). Hidden flags
+ * (--source) are omitted. Pure: returns a string, no I/O.
+ */
+export function helpText() {
+    const lines = [];
+    lines.push("feature-forge — cross-agent installer for the feature-forge skill suite");
+    lines.push("");
+    lines.push("USAGE:");
+    lines.push("  feature-forge <command> [flags]");
+    lines.push("");
+    lines.push("COMMANDS:");
+    for (const s of SUBCOMMANDS) {
+        const alias = s.aliases.length ? ` (alias: ${s.aliases.join(", ")})` : "";
+        lines.push(`  ${s.canonical.padEnd(10)} ${s.help}${alias}`);
+    }
+    lines.push("");
+    lines.push("FLAGS:");
+    for (const f of FLAGS) {
+        if (f.hidden)
+            continue;
+        const long = `--${f.name}${f.arg ? " " + f.arg : ""}`;
+        const short = f.short ? `-${f.short}, ` : "    ";
+        lines.push(`  ${short}${long.padEnd(18)} ${f.help}`);
+    }
+    lines.push("");
+    lines.push("EXAMPLES:");
+    lines.push("  npx feature-forge install                 # install into all detected agents (project scope)");
+    lines.push("  npx feature-forge install -a claude -g    # install into ~/.claude only");
+    lines.push("  npx feature-forge update --dry-run        # preview an update, change nothing");
+    lines.push("  npx feature-forge list --json             # machine-readable per-agent status");
+    lines.push("  npx feature-forge uninstall -a cursor     # remove the cursor install (manifest-tracked only)");
+    return lines.join("\n");
+}
+/**
+ * Read the installer package's own version from the bundled package.json (REQ-DIST-03). Resolved
+ * relative to the compiled module via `import.meta.url` so it works when run via `npx`. On any
+ * read error, fall back to "unknown" (never throw from --version).
+ */
+function readInstallerVersion() {
+    try {
+        const url = new URL("../package.json", import.meta.url);
+        const pkg = JSON.parse(readFileSync(url, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+// ---------------------------------------------------------------------------
+// 8. Process entry shim
+// ---------------------------------------------------------------------------
+// Only run when invoked as the bin (not when imported by tests / index.ts).
+const entry = process.argv[1];
+if (entry !== undefined && import.meta.url === pathToFileURL(entry).href) {
+    main(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((e) => {
+        process.stderr.write(`error: fatal: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exitCode = EXIT.FAILURE;
+    });
+}

package/dist/detect.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Internal detection probes for the agent-detection-map surface (spec 02 §5.1, §5.3).
+ *
+ * Two probes, both total and non-throwing:
+ *   - `probeConfigDir` — the PRIMARY detection signal: a single `fs.statSync`. Never mkdir,
+ *     never throws (REQ-DET-02/04, REQ-PERF-01).
+ *   - `cliOnPath` — SECONDARY, advisory only: is the agent's CLI on PATH? Never gates
+ *     `detected` (REQ-DET-02). `cursor` is intentionally omitted (IDE/GUI agent, no CLI).
+ *
+ * Zero runtime dependencies; only `node:` built-ins.
+ */
+import type { AgentId } from "./types.js";
+/**
+ * The primary detection signal (REQ-DET-02): is `configDir` an existing directory?
+ * Uses a single synchronous `fs.statSync` — never an agent subprocess (detection stays
+ * instant, REQ-PERF-01) and never creates the dir (REQ-DET-04). Any stat failure
+ * (`ENOENT` not present, `EACCES` unreadable, or a non-directory at the path) ⇒ `false`.
+ *
+ * Synchronous by design: exactly one stat per agent (five total), so async adds no
+ * throughput and would complicate the pure-derivation surface.
+ */
+export declare function probeConfigDir(configDir: string): boolean;
+/**
+ * The PATH-resolver seam: given a binary basename, return true iff it resolves on PATH.
+ * Default uses the platform's real resolver executable (`where` on Windows, `which` on POSIX) —
+ * NOT the shell builtin `command`, which is not an executable on PATH and so always throws
+ * ENOENT under `execFileSync` (no shell). Injectable so tests can drive present/absent without
+ * depending on the host PATH.
+ */
+export type PathResolver = (bin: string) => boolean;
+/** The real resolver: `which <bin>` (POSIX) / `where <bin>` (Windows). Any failure ⇒ false. */
+export declare const realPathResolver: PathResolver;
+/**
+ * Secondary, **advisory** info (REQ-DET-02): is the agent's CLI resolvable on PATH? This is
+ * reported as `DetectionResult.cliOnPath` but **never** gates `detected`. Uses the platform's
+ * resolver executable (`where` on Windows, `which` elsewhere — a real binary on PATH, not the
+ * shell builtin `command`) once per agent. Any failure — no resolver, not found, spawn error —
+ * yields `false`; it never throws and never blocks detection.
+ *
+ * Agents without a canonical CLI (cursor) always report `false` here without spawning.
+ *
+ * @param id       - the agent whose CLI basename to probe.
+ * @param resolve  - the PATH resolver seam (default: {@link realPathResolver}); injectable for tests.
+ */
+export declare function cliOnPath(id: AgentId, resolve?: PathResolver): boolean;

package/dist/detect.js

@@ -0,0 +1,72 @@
+/**
+ * Internal detection probes for the agent-detection-map surface (spec 02 §5.1, §5.3).
+ *
+ * Two probes, both total and non-throwing:
+ *   - `probeConfigDir` — the PRIMARY detection signal: a single `fs.statSync`. Never mkdir,
+ *     never throws (REQ-DET-02/04, REQ-PERF-01).
+ *   - `cliOnPath` — SECONDARY, advisory only: is the agent's CLI on PATH? Never gates
+ *     `detected` (REQ-DET-02). `cursor` is intentionally omitted (IDE/GUI agent, no CLI).
+ *
+ * Zero runtime dependencies; only `node:` built-ins.
+ */
+import * as fs from "node:fs";
+import { execFileSync } from "node:child_process";
+/**
+ * The primary detection signal (REQ-DET-02): is `configDir` an existing directory?
+ * Uses a single synchronous `fs.statSync` — never an agent subprocess (detection stays
+ * instant, REQ-PERF-01) and never creates the dir (REQ-DET-04). Any stat failure
+ * (`ENOENT` not present, `EACCES` unreadable, or a non-directory at the path) ⇒ `false`.
+ *
+ * Synchronous by design: exactly one stat per agent (five total), so async adds no
+ * throughput and would complicate the pure-derivation surface.
+ */
+export function probeConfigDir(configDir) {
+    try {
+        return fs.statSync(configDir).isDirectory();
+    }
+    catch {
+        return false; // ENOENT / EACCES / not-a-dir → not detected (never throws, REQ-DET-04)
+    }
+}
+/** Per-agent CLI executable basename probed on PATH (advisory only). */
+const CLI_NAMES = {
+    claude: "claude",
+    codex: "codex",
+    copilot: "copilot",
+    gemini: "gemini",
+    // cursor: intentionally omitted — IDE/GUI agent, no canonical CLI on PATH (REQ-DET-02).
+};
+/** The real resolver: `which <bin>` (POSIX) / `where <bin>` (Windows). Any failure ⇒ false. */
+export const realPathResolver = (bin) => {
+    const isWin = process.platform === "win32";
+    try {
+        execFileSync(isWin ? "where" : "which", [bin], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false; // not found / no resolver / spawn error — advisory, never an error
+    }
+};
+/**
+ * Secondary, **advisory** info (REQ-DET-02): is the agent's CLI resolvable on PATH? This is
+ * reported as `DetectionResult.cliOnPath` but **never** gates `detected`. Uses the platform's
+ * resolver executable (`where` on Windows, `which` elsewhere — a real binary on PATH, not the
+ * shell builtin `command`) once per agent. Any failure — no resolver, not found, spawn error —
+ * yields `false`; it never throws and never blocks detection.
+ *
+ * Agents without a canonical CLI (cursor) always report `false` here without spawning.
+ *
+ * @param id       - the agent whose CLI basename to probe.
+ * @param resolve  - the PATH resolver seam (default: {@link realPathResolver}); injectable for tests.
+ */
+export function cliOnPath(id, resolve = realPathResolver) {
+    const bin = CLI_NAMES[id];
+    if (!bin)
+        return false;
+    try {
+        return resolve(bin);
+    }
+    catch {
+        return false; // advisory; absence is normal, never an error
+    }
+}