@uluops/setup 0.7.0 → 0.8.1

package/dist/harnesses/codex.js

@@ -1,34 +1,101 @@
 /**
- * Codex Harness Profile (Scaffold)
+ * Codex Harness Profile
  *
- * Paths and metadata are verified from vendor docs.
- * Codex uses TOML config with `mcp_servers` key (nested tables).
+ * Codex uses TOML config with `mcp_servers` nested tables.
  * Agent definitions are TOML, not markdown.
- * Skills use a different path ($HOME/.agents/skills/) than agents (~/.codex/agents/).
- *
- * NOT YET TESTED with UluOps agents. McpConfigStrategy throws
- * until integration testing is complete.
- *
- * Will require `smol-toml` dependency when fully implemented.
+ * Skills live under ~/.codex/skills and are the preferred Codex-native
+ * surface for UluOps operator workflows.
  */
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { HarnessNotTestedError } from "./types.js";
+import { ULUOPS_SERVERS, } from "./types.js";
+import { atomicWrite } from "../lib/atomic-write.js";
+const RAW_TOML = "__rawToml";
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function serverBlock(name, pkg, apiKey) {
+    return [
+        `[mcp_servers.${tomlString(name)}]`,
+        `command = "npx"`,
+        `args = ["-y", ${tomlString(pkg)}]`,
+        ``,
+        `[mcp_servers.${tomlString(name)}.env]`,
+        `ULUOPS_API_KEY = ${tomlString(apiKey)}`,
+    ].join("\n");
+}
+function isServerTableFor(name, table) {
+    return table === `mcp_servers.${name}` || table === `mcp_servers."${name}"`;
+}
+function isServerSubtableFor(name, table) {
+    const unquotedPrefix = `mcp_servers.${name}.`;
+    const quotedPrefix = `mcp_servers."${name}".`;
+    return table.startsWith(unquotedPrefix) || table.startsWith(quotedPrefix);
+}
+function removeServerConfigBlocks(raw, name) {
+    const lines = raw.split("\n");
+    const kept = [];
+    let skipping = false;
+    for (const line of lines) {
+        const table = line.trim().match(/^\[([^\]]+)\]$/)?.[1];
+        if (table) {
+            skipping = isServerTableFor(name, table) || table === `mcp_servers.${name}.env` || table === `mcp_servers."${name}".env`;
+        }
+        if (!skipping)
+            kept.push(line);
+    }
+    return kept.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+function removeServerSubtree(raw, name) {
+    const lines = raw.split("\n");
+    const kept = [];
+    let skipping = false;
+    for (const line of lines) {
+        const table = line.trim().match(/^\[([^\]]+)\]$/)?.[1];
+        if (table) {
+            skipping = isServerTableFor(name, table) || isServerSubtableFor(name, table);
+        }
+        if (!skipping)
+            kept.push(line);
+    }
+    return kept.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+}
 class CodexMcpConfig {
-    async read() {
-        throw new HarnessNotTestedError("Codex (agent format compatibility under review)");
+    async read(path) {
+        try {
+            return { [RAW_TOML]: await readFile(path, "utf-8") };
+        }
+        catch {
+            return { [RAW_TOML]: "" };
+        }
     }
-    merge() {
-        throw new HarnessNotTestedError("Codex (agent format compatibility under review)");
+    merge(config, apiKey) {
+        let raw = typeof config[RAW_TOML] === "string" ? config[RAW_TOML] : "";
+        raw = removeServerConfigBlocks(removeServerConfigBlocks(raw, "uluops-tracker"), "uluops-registry");
+        const blocks = [
+            serverBlock("uluops-tracker", "@uluops/ops-mcp", apiKey),
+            serverBlock("uluops-registry", "@uluops/registry-mcp", apiKey),
+        ].join("\n\n");
+        return { [RAW_TOML]: [raw.trimEnd(), blocks].filter(Boolean).join("\n\n") + "\n" };
     }
-    remove() {
-        throw new HarnessNotTestedError("Codex (agent format compatibility under review)");
+    remove(config) {
+        let raw = typeof config[RAW_TOML] === "string" ? config[RAW_TOML] : "";
+        for (const name of ULUOPS_SERVERS) {
+            raw = removeServerSubtree(raw, name);
+        }
+        return { [RAW_TOML]: raw.trimEnd() ? `${raw.trimEnd()}\n` : "" };
     }
-    async write() {
-        throw new HarnessNotTestedError("Codex (agent format compatibility under review)");
+    async write(path, config) {
+        const raw = typeof config[RAW_TOML] === "string" ? config[RAW_TOML] : "";
+        await atomicWrite(path, raw, { mode: 0o600 });
     }
-    check() {
-        throw new HarnessNotTestedError("Codex (MCP config check not supported)");
+    check(config) {
+        const raw = typeof config[RAW_TOML] === "string" ? config[RAW_TOML] : "";
+        return ULUOPS_SERVERS.every((name) => {
+            const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            return new RegExp(String.raw `\[mcp_servers\.(?:"${escaped}"|${escaped})\]`).test(raw);
+        });
     }
 }
 const home = join(homedir(), ".codex");
@@ -45,7 +112,8 @@ export const codexProfile = {
         globalMcpConfig: join(home, "config.toml"),
         localMcpConfig: ".codex/config.toml",
         agentsDir: join(home, "agents"),
-        commandsDir: join(homedir(), ".agents", "skills"),
+        commandsDir: join(home, "commands"),
+        skillsDir: join(home, "skills"),
         settingsPath: null,
         toolsDir: null,
     },

package/dist/harnesses/index.js

@@ -6,7 +6,7 @@
  */
 import { existsSync } from "node:fs";
 import { claudeCodeProfile } from "./claude-code.js";
-import { opencodeProfile } from "./opencode.js";
+import { opencodeProfile, assertOpencodeEnvironment } from "./opencode.js";
 import { geminiCliProfile } from "./gemini-cli.js";
 import { codexProfile } from "./codex.js";
 export { ConfigParseError, HarnessNotTestedError, } from "./types.js";
@@ -33,6 +33,11 @@ export function getProfile(name) {
         const available = ALL_PROFILES.map((p) => p.name).join(", ");
         throw new Error(`Unknown harness "${name}". Available: ${available}`);
     }
+    // Harness-specific environment validation deferred from module-load to
+    // selection time. Keeps `--help` and `--uninstall` usable even when an
+    // unrelated harness's env is misconfigured.
+    if (resolved === "opencode")
+        assertOpencodeEnvironment();
     return profile;
 }
 /**

package/dist/harnesses/opencode.d.ts

@@ -11,4 +11,12 @@
  * Verified working shape from ~/opencode.jsonc (2026-04-30).
  */
 import { type HarnessProfile } from "./types.js";
+/**
+ * Throws the deferred XDG_CONFIG_HOME validation error, if any. Called by
+ * the harness registry when the user actually selects opencode (via
+ * `--harness opencode` or auto-detection picking it). Other entry points
+ * (`--help`, `--uninstall` of an unrelated harness, `--list`) never trigger
+ * this and remain usable.
+ */
+export declare function assertOpencodeEnvironment(): void;
 export declare const opencodeProfile: HarnessProfile;

package/dist/harnesses/opencode.js

@@ -106,17 +106,40 @@ class OpenCodeMcpConfig {
         return ULUOPS_SERVERS.every((name) => name in mcp);
     }
 }
+/**
+ * XDG_CONFIG_HOME validation is deferred from module-load to first opencode
+ * use. The previous design threw at import, which crashed `uluops-setup
+ * --help` and `--uninstall` for any user with an invalid XDG_CONFIG_HOME —
+ * blocking them from running the very commands they need to recover. Now
+ * the IIFE caches any validation error and the harness registry calls
+ * `assertOpencodeEnvironment()` only when the opencode profile is actually
+ * selected. Unselected, the module loads cleanly and the fallback path is
+ * used for shape-only computations.
+ */
+let deferredXdgConfigError = null;
 const xdgConfig = (() => {
     const env = process.env["XDG_CONFIG_HOME"];
     if (env) {
         if (!isAbsolute(env) || env.includes("..")) {
-            throw new Error(`XDG_CONFIG_HOME must be an absolute path without traversal: ${env}`);
+            deferredXdgConfigError = new Error(`XDG_CONFIG_HOME must be an absolute path without traversal: ${env}`);
+            return join(homedir(), ".config");
         }
         return env;
     }
     return join(homedir(), ".config");
 })();
 const home = join(xdgConfig, "opencode");
+/**
+ * Throws the deferred XDG_CONFIG_HOME validation error, if any. Called by
+ * the harness registry when the user actually selects opencode (via
+ * `--harness opencode` or auto-detection picking it). Other entry points
+ * (`--help`, `--uninstall` of an unrelated harness, `--list`) never trigger
+ * this and remain usable.
+ */
+export function assertOpencodeEnvironment() {
+    if (deferredXdgConfigError)
+        throw deferredXdgConfigError;
+}
 export const opencodeProfile = {
     name: "opencode",
     displayName: "OpenCode",

package/dist/harnesses/types.d.ts

@@ -54,6 +54,8 @@ export interface HarnessPaths {
     readonly agentsDir: string;
     /** Global commands/skills dir */
     readonly commandsDir: string;
+    /** Global Codex-style skills dir, when the harness supports skills as first-class install assets */
+    readonly skillsDir?: string | null;
     /** Settings file path, or null if harness has no settings file */
     readonly settingsPath: string | null;
     /** Tool installation dir, or null if harness has no tool installation */

package/dist/harnesses/types.js

@@ -20,7 +20,11 @@ export class ConfigParseError extends Error {
 /** Thrown when a harness is scaffolded but not yet tested/implemented. */
 export class HarnessNotTestedError extends Error {
     constructor(harnessName) {
-        super(`${harnessName} harness is not yet tested. Use --harness claude-code or --harness opencode.`);
+        super(
+        // Keep this list in sync with profiles whose `status === "stable"`.
+        // Today: claude-code, opencode, gemini-cli. When a new stable profile
+        // lands, add it here so the error stays actionable.
+        `${harnessName} harness is not yet tested. Use --harness claude-code, --harness opencode, or --harness gemini-cli.`);
         this.name = "HarnessNotTestedError";
     }
 }

package/dist/lib/atomic-write.js

@@ -5,10 +5,18 @@
  * from corrupting user config files.
  */
 import { writeFile, rename, unlink, chmod } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
 export async function atomicWrite(path, content, options) {
-    const tmp = `${path}.uluops-tmp`;
+    // Random suffix + 'wx' flag (O_CREAT|O_EXCL) prevents symlink races:
+    // an attacker cannot pre-position a symlink at an unpredictable path,
+    // and 'wx' fails atomically rather than following one that exists.
+    const tmp = `${path}.uluops-tmp.${randomBytes(8).toString("hex")}`;
     try {
-        await writeFile(tmp, content, { encoding: "utf-8", mode: options?.mode });
+        await writeFile(tmp, content, {
+            encoding: "utf-8",
+            mode: options?.mode,
+            flag: "wx",
+        });
         if (options?.mode) {
             // Ensure mode is applied even if umask is permissive
             await chmod(tmp, options.mode);

package/dist/lib/config-merger.d.ts

@@ -8,11 +8,14 @@ export interface ClaudeConfig {
     mcpServers?: Record<string, McpServerConfig>;
     [key: string]: unknown;
 }
-/** Check whether the UluOps MCP client packages exist on the npm registry. Returns lists of available and missing packages. */
-export declare function checkMcpPackageAvailability(): Promise<{
+interface AvailabilityResult {
     available: string[];
     missing: string[];
-}>;
+}
+/** Test-only: drop the memoized availability promise so the next call re-probes. */
+export declare function __resetAvailabilityCacheForTesting(): void;
+/** Check whether the UluOps MCP client packages exist on the npm registry. Returns lists of available and missing packages. */
+export declare function checkMcpPackageAvailability(): Promise<AvailabilityResult>;
 /**
  * Read an existing config file, or return empty object if it doesn't exist.
  * Throws on malformed JSON to prevent silent data loss during merge+write.

package/dist/lib/config-merger.js

@@ -1,8 +1,39 @@
 import { readFile } from "node:fs/promises";
 import { atomicWrite } from "./atomic-write.js";
 const MCP_PACKAGES = ["@uluops/ops-mcp", "@uluops/registry-mcp"];
+/**
+ * In-process memoization for the npm availability probe.
+ *
+ * Setup runs once per process; with multi-harness installs (or any future
+ * code path that calls installMcp more than once), the probe was firing
+ * redundantly against the npm registry. We cache the in-flight promise so
+ * concurrent callers share a single round-trip and subsequent callers get
+ * the resolved value instantly. Cache lifetime is the process — setup is
+ * one-shot, so a TTL adds state without buying anything.
+ *
+ * `__resetAvailabilityCacheForTesting` exists ONLY for tests that stub
+ * `fetch` per-case. Without a reset, the first test in a file would lock
+ * the cached result for every subsequent test in the same process.
+ */
+let _availabilityCache = null;
+/** Test-only: drop the memoized availability promise so the next call re-probes. */
+export function __resetAvailabilityCacheForTesting() {
+    _availabilityCache = null;
+}
 /** Check whether the UluOps MCP client packages exist on the npm registry. Returns lists of available and missing packages. */
-export async function checkMcpPackageAvailability() {
+export function checkMcpPackageAvailability() {
+    if (_availabilityCache)
+        return _availabilityCache;
+    _availabilityCache = probeAvailability().catch((err) => {
+        // If the probe itself throws unexpectedly (not an individual fetch — those
+        // are caught by Promise.allSettled), drop the cache so retries don't
+        // permanently inherit a poisoned promise.
+        _availabilityCache = null;
+        throw err;
+    });
+    return _availabilityCache;
+}
+async function probeAvailability() {
     const available = [];
     const missing = [];
     const results = await Promise.allSettled(MCP_PACKAGES.map((pkg) => fetch(`https://registry.npmjs.org/${pkg}`, {
@@ -10,16 +41,28 @@ export async function checkMcpPackageAvailability() {
         signal: AbortSignal.timeout(5000),
         redirect: "follow",
     }).then((res) => ({ pkg, ok: res.ok }))));
+    // Per-index correspondence: results[i] corresponds to MCP_PACKAGES[i] by
+    // Promise.allSettled's stable ordering. The previous `?? "unknown"` fallback
+    // could emit a literal "unknown" string into `missing`, hiding the real
+    // failure reason (DNS error, timeout, 404) under an undiagnosable label.
     for (let i = 0; i < results.length; i++) {
         const result = results[i];
-        if (result.status === "fulfilled" && result.value.ok) {
-            available.push(result.value.pkg);
+        const pkg = MCP_PACKAGES[i];
+        if (result.status === "fulfilled") {
+            if (result.value.ok) {
+                available.push(pkg);
+            }
+            else {
+                // Registry returned non-2xx — package likely missing or unpublished.
+                missing.push(pkg);
+            }
         }
         else {
-            const pkg = result.status === "fulfilled"
-                ? result.value.pkg
-                : MCP_PACKAGES[i] ?? "unknown";
-            missing.push(pkg);
+            // Network failure: AbortError (timeout), DNS, TLS, EAI_AGAIN, etc.
+            const reason = result.reason instanceof Error
+                ? result.reason.message
+                : String(result.reason);
+            missing.push(`${pkg} (network: ${reason})`);
         }
     }
     return { available, missing };

package/dist/lib/display.d.ts

@@ -1,13 +1,29 @@
-import type { HarnessProfile } from "../harnesses/index.js";
+import type { PerHarnessResult } from "../commands/per-harness.js";
 declare const ok: (msg: string) => void;
 declare const warn: (msg: string) => void;
 declare const fail: (msg: string) => void;
 declare const info: (msg: string) => void;
 export { ok, warn, fail, info };
-export declare function printSetupSummary(opts: {
-    profile: HarnessProfile;
-    agentCount: number;
-    commandCount: number;
+/**
+ * Render the final post-run summary.
+ *
+ * Single-harness: preserves today's banner format (Setup complete!
+ * + agent list + restart instruction) — regression baseline.
+ *
+ * Multi-harness: aggregate header line, per-harness section block with
+ * status icons + counts + re-run hints, single API-key reminder, single
+ * restart instruction naming each successfully-installed harness.
+ *
+ * Status rendering:
+ *   ok       — ✓ green     installed (counts)
+ *   ok+files-failed — same line, the per-step warn()s already surfaced
+ *                     the failed files during install (not re-printed)
+ *   failed (partial) — ⚠ yellow  partial — failed at "<step>"; re-run hint
+ *   failed (pre-MCP)— ✗ red     failed — <error>; re-run hint
+ *   declined — ⊘ dim       skipped — user declined conflict prompt
+ */
+export declare function printSetupSummary(input: {
+    results: PerHarnessResult[];
     apiKey: string;
 }): Promise<void>;
 export declare function maskKey(key: string): string;

package/dist/lib/display.js

@@ -5,30 +5,135 @@ const warn = (msg) => console.log(`  ${chalk.yellow("⚠")} ${msg}`);
 const fail = (msg) => console.log(`  ${chalk.red("✗")} ${msg}`);
 const info = (msg) => console.log(`  ${msg}`);
 export { ok, warn, fail, info };
-export async function printSetupSummary(opts) {
+const DIVIDER = `  ${chalk.dim("━".repeat(46))}`;
+/**
+ * Render the final post-run summary.
+ *
+ * Single-harness: preserves today's banner format (Setup complete!
+ * + agent list + restart instruction) — regression baseline.
+ *
+ * Multi-harness: aggregate header line, per-harness section block with
+ * status icons + counts + re-run hints, single API-key reminder, single
+ * restart instruction naming each successfully-installed harness.
+ *
+ * Status rendering:
+ *   ok       — ✓ green     installed (counts)
+ *   ok+files-failed — same line, the per-step warn()s already surfaced
+ *                     the failed files during install (not re-printed)
+ *   failed (partial) — ⚠ yellow  partial — failed at "<step>"; re-run hint
+ *   failed (pre-MCP)— ✗ red     failed — <error>; re-run hint
+ *   declined — ⊘ dim       skipped — user declined conflict prompt
+ */
+export async function printSetupSummary(input) {
+    const { results, apiKey } = input;
+    if (results.length === 0) {
+        // runSetup's empty-list branch already printed "nothing to install"
+        // and returned; this is defense-in-depth so the summary never crashes
+        // on an empty input.
+        return;
+    }
     console.log();
-    console.log(`  ${chalk.dim("━".repeat(46))}`);
+    console.log(DIVIDER);
     console.log();
-    const parts = [`${opts.agentCount} agents`];
-    if (opts.commandCount > 0)
-        parts.push(`${opts.commandCount} slash commands`);
-    if (opts.profile.hooks)
-        parts.push("metrics");
-    console.log(`  ${chalk.bold("Setup complete!")} ${chalk.dim(`(${opts.profile.displayName})`)} ${parts.join(" · ")}`);
+    const installed = results.filter((r) => r.status === "ok").length;
+    const failed = results.filter((r) => r.status === "failed").length;
+    const declined = results.filter((r) => r.status === "declined").length;
+    const total = results.length;
+    // Header
+    if (total === 1) {
+        const only = results[0];
+        if (only.status === "ok") {
+            console.log(`  ${chalk.bold("Setup complete!")} ${chalk.dim(`(${only.profile.displayName})`)} ${renderCounts(only)}`);
+        }
+        else if (only.status === "declined") {
+            console.log(`  ${chalk.bold("Setup skipped")} ${chalk.dim(`(${only.profile.displayName})`)} — you declined the conflict prompt`);
+        }
+        else {
+            console.log(`  ${chalk.red.bold("Setup failed")} ${chalk.dim(`(${only.profile.displayName})`)} — ${only.error ?? "see output above"}`);
+        }
+    }
+    else {
+        const summaryParts = [`${installed} installed`];
+        if (failed > 0)
+            summaryParts.push(`${failed} failed`);
+        if (declined > 0)
+            summaryParts.push(`${declined} declined`);
+        const allOk = failed === 0 && declined === 0;
+        const headerLabel = allOk ? "Setup complete:" : "Setup finished:";
+        console.log(`  ${chalk.bold(headerLabel)} ${summaryParts.join(", ")} of ${total} harnesses`);
+        console.log();
+        for (const r of results) {
+            printHarnessLine(r);
+        }
+    }
     console.log();
-    if (opts.profile.name === "claude-code") {
+    // Agent list — only for single-harness claude-code success (the bulk of
+    // single-harness installs). Multi-harness summaries omit it: it's long
+    // and per-claude-code, and the multi-harness reader is more interested
+    // in the per-harness status block than the agent catalog.
+    if (total === 1 &&
+        results[0].status === "ok" &&
+        results[0].profile.name === "claude-code") {
         await printAgentList();
     }
-    const masked = maskKey(opts.apiKey);
+    // API-key reminder — once per run regardless of harness count.
+    const masked = maskKey(apiKey);
     info("For SDK/CLI usage, add to your shell profile:");
     info(`  ${chalk.cyan(`export ULUOPS_API_KEY="${masked}"`)}`);
     console.log();
     info(`Run again to update: ${chalk.cyan("npx @uluops/setup")}`);
     console.log();
-    console.log(`  ${chalk.dim("━".repeat(46))}`);
-    console.log();
-    console.log(`  ${chalk.yellow.bold(`Restart ${opts.profile.displayName} to load agents.`)}`);
+    console.log(DIVIDER);
     console.log();
+    // Restart instruction — names each successfully-installed harness so
+    // the user knows what to restart. Suppressed entirely when nothing
+    // installed (all declined / all failed pre-MCP) — there's nothing to
+    // restart.
+    const restartTargets = results.filter((r) => r.status === "ok");
+    if (restartTargets.length > 0) {
+        const names = restartTargets.map((r) => r.profile.displayName).join(", ");
+        const verb = restartTargets.length === 1 ? "Restart" : "Restart each of";
+        console.log(`  ${chalk.yellow.bold(`${verb} ${names} to load agents.`)}`);
+        console.log();
+    }
+}
+function printHarnessLine(r) {
+    const label = chalk.bold(`[${r.profile.displayName}]`);
+    switch (r.status) {
+        case "ok": {
+            const counts = renderCounts(r);
+            console.log(`  ${chalk.green("✓")} ${label} installed ${counts}`);
+            return;
+        }
+        case "failed": {
+            if (r.partial) {
+                console.log(`  ${chalk.yellow("⚠")} ${label} partial — failed at "${r.partial}"${r.error ? `: ${r.error}` : ""}`);
+            }
+            else {
+                console.log(`  ${chalk.red("✗")} ${label} failed — ${r.error ?? "see output above"}`);
+            }
+            console.log(`     ${chalk.dim(`Re-run: npx @uluops/setup --harness ${r.harnessName}`)}`);
+            return;
+        }
+        case "declined":
+            console.log(`  ${chalk.dim("⊘")} ${label} skipped — user declined conflict prompt`);
+            return;
+    }
+}
+function renderCounts(r) {
+    const parts = [];
+    const agents = r.agentsResult?.files.length ?? 0;
+    const commands = r.commandsResult?.files.length ?? 0;
+    const skills = r.skillsResult?.files.length ?? 0;
+    if (agents > 0)
+        parts.push(`${agents} agents`);
+    if (commands > 0)
+        parts.push(`${commands} commands`);
+    if (skills > 0)
+        parts.push(`${skills} skills`);
+    if (r.metricsResult?.hookConfigured)
+        parts.push("metrics");
+    return parts.length > 0 ? `(${parts.join(" · ")})` : "";
 }
 export function maskKey(key) {
     if (!key || key.length <= 4)

package/dist/lib/file-ops.d.ts

@@ -11,6 +11,19 @@ export declare function writeIfChanged(destPath: string, content: string, dryRun
  * Remove files from a directory. Returns count of successfully removed files.
  */
 export declare function unlinkFiles(dir: string, files: string[]): Promise<number>;
+/**
+ * Reconcile a manifest's old file list against the current source set,
+ * unlinking the files that were installed previously but are no longer in
+ * the source. Returns the count of files that would have been removed
+ * (whether or not the unlink actually ran in dry-run mode).
+ *
+ * Extracted from three near-identical blocks in syncAssets, installAgents,
+ * and installCommands. Errors from unlink are swallowed silently — the
+ * "already gone" case is the dominant one (idempotent re-run, manual user
+ * deletion, prior failed install), and there's no recovery the caller
+ * can usefully perform mid-loop.
+ */
+export declare function removeStaleFiles(destDir: string, oldManifestFiles: string[] | undefined, currentFiles: string[], dryRun: boolean): Promise<number>;
 /**
  * Ensure a directory exists, then copy matching .md files using hash comparison.
  * Returns list of copied files, skipped count, and removed count (for old manifest entries).
@@ -27,8 +40,3 @@ export declare function syncAssets(opts: {
     removed: number;
     files: string[];
 }>;
-/**
- * Back up a file to the UluOps backup directory before modifying it.
- * No-op if the source file doesn't exist.
- */
-export declare function backupFile(srcPath: string, backupDir: string): Promise<void>;

package/dist/lib/file-ops.js

@@ -1,5 +1,5 @@
-import { readFile, writeFile, mkdir, unlink, access, copyFile, readdir } from "node:fs/promises";
-import { join, basename } from "node:path";
+import { readFile, writeFile, mkdir, unlink, readdir } from "node:fs/promises";
+import { join } from "node:path";
 import { fileHash } from "./hash.js";
 /**
  * Copy a file if its content has changed (hash comparison). Returns "copied" or "skipped".
@@ -57,6 +57,37 @@ export async function unlinkFiles(dir, files) {
     }
     return removed;
 }
+/**
+ * Reconcile a manifest's old file list against the current source set,
+ * unlinking the files that were installed previously but are no longer in
+ * the source. Returns the count of files that would have been removed
+ * (whether or not the unlink actually ran in dry-run mode).
+ *
+ * Extracted from three near-identical blocks in syncAssets, installAgents,
+ * and installCommands. Errors from unlink are swallowed silently — the
+ * "already gone" case is the dominant one (idempotent re-run, manual user
+ * deletion, prior failed install), and there's no recovery the caller
+ * can usefully perform mid-loop.
+ */
+export async function removeStaleFiles(destDir, oldManifestFiles, currentFiles, dryRun) {
+    if (!oldManifestFiles)
+        return 0;
+    let removed = 0;
+    for (const oldFile of oldManifestFiles) {
+        if (!currentFiles.includes(oldFile)) {
+            if (!dryRun) {
+                try {
+                    await unlink(join(destDir, oldFile));
+                }
+                catch {
+                    // Already gone
+                }
+            }
+            removed++;
+        }
+    }
+    return removed;
+}
 /**
  * Ensure a directory exists, then copy matching .md files using hash comparison.
  * Returns list of copied files, skipped count, and removed count (for old manifest entries).
@@ -83,40 +114,9 @@ export async function syncAssets(opts) {
         }
     }
     // Remove files that were in the old manifest but no longer in the package
-    let removed = 0;
-    if (opts.oldManifestFiles) {
-        for (const oldFile of opts.oldManifestFiles) {
-            if (!assetFiles.includes(oldFile)) {
-                if (!opts.dryRun) {
-                    try {
-                        await unlink(join(opts.destDir, oldFile));
-                    }
-                    catch {
-                        // Already gone
-                    }
-                }
-                removed++;
-            }
-        }
-    }
+    const removed = await removeStaleFiles(opts.destDir, opts.oldManifestFiles, assetFiles, opts.dryRun);
     if (errors.length > 0) {
         throw new Error(`Failed to copy ${errors.length} file(s):\n  ${errors.join("\n  ")}`);
     }
     return { copied, skipped, removed, files: assetFiles };
 }
-/**
- * Back up a file to the UluOps backup directory before modifying it.
- * No-op if the source file doesn't exist.
- */
-export async function backupFile(srcPath, backupDir) {
-    try {
-        await access(srcPath);
-    }
-    catch {
-        return; // Nothing to back up
-    }
-    await mkdir(backupDir, { recursive: true });
-    const filename = basename(srcPath);
-    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    await copyFile(srcPath, join(backupDir, `${filename}.${timestamp}.bak`));
-}