@uluops/setup 0.4.0 → 0.6.0

package/dist/lib/settings-merger.js

@@ -6,30 +6,57 @@
  */
 import { readFile } from "node:fs/promises";
 import { atomicWrite } from "./atomic-write.js";
-/** Marker embedded in hook commands to identify UluOps-managed entries */
-const ULUOPS_HOOK_MARKER = "tools/agent-metrics";
-/** Supported hook event types in Claude Code. Update when Claude Code adds/renames types. */
-const SUPPORTED_HOOK_TYPES = new Set([
+/**
+ * Substring used purely as an *ownership sentinel* — present in every hook
+ * command we install, so we can identify our own entries in `settings.json`
+ * without false-positives on the user's hooks.
+ *
+ * This is intentionally NOT a path constant. The path where the hook lives
+ * is derived from each profile's `paths.toolsDir`; if those move (a harness
+ * restructure, a custom toolsDir, a future per-instance layout), the
+ * signature must remain stable so existing user settings.json entries
+ * keep being recognized as UluOps-managed.
+ *
+ * The current value `agent-metrics/dist/hook.js` is the suffix of every
+ * hook command we emit — discriminating enough to avoid colliding with
+ * user-named tools while surviving moves of the parent directory.
+ */
+const HOOK_OWNERSHIP_SIGNATURE = "agent-metrics/dist/hook.js";
+/**
+ * Supported hook event types in Claude Code's settings.json schema.
+ *
+ * This set is a snapshot of the harness's vocabulary. When Claude Code
+ * adds, renames, or removes hook types, this set rots — the `probeHookSupport`
+ * warning will fire on legitimate user configs and (worse) train users to
+ * ignore it. The snapshot test in `settings-merger.test.ts` exists to make
+ * any change to the set visible in PR review so the warning logic can be
+ * re-evaluated.
+ *
+ * Exported for that test only — runtime callers should use `probeHookSupport`.
+ */
+export const CLAUDE_HOOK_TYPES = new Set([
     "SubagentStop",
     "PreToolUse",
     "PostToolUse",
     "Notification",
     "Stop",
 ]);
+/** Default Claude Code hook event used when no override is configured. */
+export const DEFAULT_CLAUDE_HOOK_TYPE = "SubagentStop";
 /** Configurable hook type via env var. Falls back to SubagentStop. */
-function getHookEventType() {
-    return process.env["ULUOPS_HOOK_TYPE"] ?? "SubagentStop";
+function getDefaultHookEventType() {
+    return process.env["ULUOPS_HOOK_TYPE"] ?? DEFAULT_CLAUDE_HOOK_TYPE;
 }
 /** Check whether the configured hook event type is in the known supported set. Returns the resolved hook type and a warning if unsupported. */
-export function probeHookSupport() {
-    const hookType = getHookEventType();
-    if (SUPPORTED_HOOK_TYPES.has(hookType)) {
+export function probeHookSupport(hookTypeOverride) {
+    const hookType = hookTypeOverride ?? getDefaultHookEventType();
+    if (CLAUDE_HOOK_TYPES.has(hookType) || hookType === "AfterTool") {
         return { hookType, supported: true };
     }
     return {
         hookType,
         supported: false,
-        warning: `Hook type "${hookType}" is not in the known supported set {${[...SUPPORTED_HOOK_TYPES].join(", ")}}. Metrics may silently fail if this hook type does not exist in Claude Code.`,
+        warning: `Hook type "${hookType}" is not in the known supported set {${[...CLAUDE_HOOK_TYPES].join(", ")}, AfterTool}. Metrics may silently fail if this hook type does not exist in the harness.`,
     };
 }
 /**
@@ -44,7 +71,12 @@ export async function readSettings(path) {
     catch {
         return {}; // File doesn't exist — fresh config
     }
-    return JSON.parse(raw);
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Failed to parse settings at ${path} — file contains invalid JSON`);
+    }
 }
 /**
  * Write settings back to file with stable formatting.
@@ -53,14 +85,14 @@ export async function writeSettings(path, settings) {
     await atomicWrite(path, JSON.stringify(settings, null, 2) + "\n");
 }
 /**
- * Merge the UluOps SubagentStop hook into settings, preserving all other
+ * Merge the UluOps hook into settings, preserving all other
  * hooks and settings. If a UluOps hook already exists, it is replaced.
  */
-export function mergeUluopsHook(settings, hookCommand) {
-    const hookType = getHookEventType();
+export function mergeUluopsHook(settings, hookCommand, hookTypeOverride, matcher) {
+    const hookType = hookTypeOverride ?? getDefaultHookEventType();
     const hooks = settings.hooks ?? {};
     const existing = hooks[hookType] ?? [];
-    const filtered = existing.filter((m) => !m.hooks.some((h) => h.command.includes(ULUOPS_HOOK_MARKER)));
+    const filtered = existing.filter((m) => !m.hooks.some((h) => h.command.includes(HOOK_OWNERSHIP_SIGNATURE)));
     const uluopsHook = {
         hooks: [
             {
@@ -70,6 +102,9 @@ export function mergeUluopsHook(settings, hookCommand) {
             },
         ],
     };
+    if (matcher) {
+        uluopsHook.matcher = matcher;
+    }
     return {
         ...settings,
         hooks: {
@@ -79,18 +114,18 @@ export function mergeUluopsHook(settings, hookCommand) {
     };
 }
 /**
- * Remove UluOps hook entries from settings. If SubagentStop becomes empty,
+ * Remove UluOps hook entries from settings. If a hook type becomes empty,
  * the key is removed. If hooks becomes empty, the key is removed.
  */
-export function removeUluopsHook(settings) {
-    const hookType = getHookEventType();
+export function removeUluopsHook(settings, hookTypeOverride) {
+    const hookType = hookTypeOverride ?? getDefaultHookEventType();
     const hooks = settings.hooks;
     if (!hooks)
         return settings;
     const hookEntries = hooks[hookType];
     if (!hookEntries)
         return settings;
-    const filtered = hookEntries.filter((m) => !m.hooks.some((h) => h.command.includes(ULUOPS_HOOK_MARKER)));
+    const filtered = hookEntries.filter((m) => !m.hooks.some((h) => h.command.includes(HOOK_OWNERSHIP_SIGNATURE)));
     const updatedHooks = { ...hooks };
     if (filtered.length === 0) {
         delete updatedHooks[hookType];
@@ -110,10 +145,10 @@ export function removeUluopsHook(settings) {
 /**
  * Check if a UluOps hook is configured in settings.
  */
-export function hasUluopsHook(settings) {
-    const hookType = getHookEventType();
+export function hasUluopsHook(settings, hookTypeOverride) {
+    const hookType = hookTypeOverride ?? getDefaultHookEventType();
     const hookEntries = settings.hooks?.[hookType];
     if (!hookEntries)
         return false;
-    return hookEntries.some((m) => m.hooks.some((h) => h.command.includes(ULUOPS_HOOK_MARKER)));
+    return hookEntries.some((m) => m.hooks.some((h) => h.command.includes(HOOK_OWNERSHIP_SIGNATURE)));
 }

package/dist/lib/version.d.ts

@@ -0,0 +1,2 @@
+/** Read the package version from package.json. */
+export declare function getVersion(): Promise<string>;

package/dist/lib/version.js

@@ -0,0 +1,10 @@
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Read the package version from package.json. */
+export async function getVersion() {
+    const pkgPath = join(__dirname, "..", "..", "package.json");
+    const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+    return pkg.version;
+}

package/dist/steps/agents.d.ts

@@ -5,8 +5,7 @@ export interface AgentsResult {
     removed: number;
     files: string[];
 }
-/** Copy agent definition files from assets to the harness agents directory,
- *  transforming frontmatter to match the target harness format. */
+/** Copy pre-rendered agent definitions from harness-specific assets to the target directory. */
 export declare function installAgents(profile: HarnessProfile, localDefs: boolean, dryRun: boolean, existingManifestAgents?: string[]): Promise<AgentsResult>;
 /** Remove previously installed agent files by name. */
 export declare function uninstallAgents(files: string[], defsPath: string): Promise<number>;

package/dist/steps/agents.js

@@ -1,23 +1,20 @@
-import { readFile, readdir, mkdir, unlink } from "node:fs/promises";
+import { readdir, mkdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { ASSETS_DIR, findProjectRoot } from "../lib/paths.js";
-import { copyIfChanged, writeIfChanged, unlinkFiles } from "../lib/file-ops.js";
-import { transformAgent } from "../lib/agent-transform.js";
-/** Source directory for agent assets (single set, Claude Code format). */
-const AGENTS_SRC = join(ASSETS_DIR, "agents");
-/** Copy agent definition files from assets to the harness agents directory,
- *  transforming frontmatter to match the target harness format. */
+import { copyIfChanged, unlinkFiles } from "../lib/file-ops.js";
+/** Copy pre-rendered agent definitions from harness-specific assets to the target directory. */
 export async function installAgents(profile, localDefs, dryRun, existingManifestAgents) {
+    const srcDir = join(ASSETS_DIR, profile.name, "agents");
     const destDir = localDefs
         ? join(await findProjectRoot(), "uluops", "agents")
         : profile.paths.agentsDir;
     if (!dryRun) {
         await mkdir(destDir, { recursive: true });
     }
-    const needsTransform = profile.name !== "claude-code";
+    const ext = profile.agentExtension;
     let files;
     try {
-        files = (await readdir(AGENTS_SRC)).filter((f) => f.endsWith(".md"));
+        files = (await readdir(srcDir)).filter((f) => f.endsWith(ext));
     }
     catch {
         return { copied: 0, skipped: 0, removed: 0, files: [] };
@@ -25,15 +22,7 @@ export async function installAgents(profile, localDefs, dryRun, existingManifest
     let copied = 0;
     let skipped = 0;
     for (const file of files) {
-        let result;
-        if (needsTransform) {
-            const markdown = await readFile(join(AGENTS_SRC, file), "utf-8");
-            const transformed = transformAgent(markdown, profile.name);
-            result = await writeIfChanged(join(destDir, file), transformed, dryRun);
-        }
-        else {
-            result = await copyIfChanged(join(AGENTS_SRC, file), join(destDir, file), dryRun);
-        }
+        const result = await copyIfChanged(join(srcDir, file), join(destDir, file), dryRun);
         if (result === "copied")
             copied++;
         else

package/dist/steps/cli.d.ts

@@ -0,0 +1,53 @@
+export declare const CLI_PACKAGE = "@uluops/cli";
+export declare const CLI_BIN = "ulu";
+export interface CliExecutor {
+    /** Returns the installed CLI version, or null if `ulu` is not on PATH or fails to run. */
+    detect: () => string | null;
+    /** Best-effort `npm install -g`. Returns ok + captured error for surface display. */
+    install: () => {
+        ok: boolean;
+        error?: string;
+    };
+    /** Best-effort `npm uninstall -g`. Returns ok + captured error. */
+    uninstall: () => {
+        ok: boolean;
+        error?: string;
+    };
+}
+/** Default executor — shells out to `ulu` and `npm`. */
+export declare const defaultExecutor: CliExecutor;
+export interface CliInstallResult {
+    /** `ulu` is on PATH after this step, regardless of how it got there. */
+    installed: boolean;
+    /** Version string from `ulu --version`, if detectable. */
+    version: string | null;
+    /** True when `ulu` was already on PATH before we did anything. */
+    alreadyPresent: boolean;
+    /** Set when our `npm install -g` attempt failed; caller decides how to surface. */
+    error?: string;
+}
+/**
+ * Install `@uluops/cli` globally if not already present.
+ *
+ * Designed to never abort the parent setup flow:
+ * - If `ulu` is already on PATH, returns `{ installed: true, alreadyPresent: true }` without touching npm.
+ * - If `npm install -g` fails (permissions, network, nvm prefix surprise), returns
+ *   `{ installed: false, error }` so the caller can warn-and-continue.
+ * - In dryRun mode, no executor calls happen.
+ */
+export declare function installCli(opts: {
+    dryRun: boolean;
+    executor?: CliExecutor;
+}): Promise<CliInstallResult>;
+export interface CliUninstallResult {
+    removed: boolean;
+    error?: string;
+}
+/**
+ * Uninstall `@uluops/cli` globally. Best-effort: if the package isn't there,
+ * npm exits non-zero on some platforms — we treat that as success.
+ */
+export declare function uninstallCli(opts: {
+    dryRun: boolean;
+    executor?: CliExecutor;
+}): Promise<CliUninstallResult>;

package/dist/steps/cli.js

@@ -0,0 +1,90 @@
+import { spawnSync } from "node:child_process";
+export const CLI_PACKAGE = "@uluops/cli";
+export const CLI_BIN = "ulu";
+/** Default executor — shells out to `ulu` and `npm`. */
+export const defaultExecutor = {
+    detect: () => {
+        const r = spawnSync(CLI_BIN, ["--version"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (r.status !== 0 || !r.stdout)
+            return null;
+        return r.stdout.trim() || null;
+    },
+    install: () => {
+        const r = spawnSync("npm", ["install", "-g", CLI_PACKAGE], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (r.status === 0)
+            return { ok: true };
+        const stderr = (r.stderr ?? "").toString().trim();
+        const stdout = (r.stdout ?? "").toString().trim();
+        return { ok: false, error: stderr || stdout || `exit ${r.status}` };
+    },
+    uninstall: () => {
+        const r = spawnSync("npm", ["uninstall", "-g", CLI_PACKAGE], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (r.status === 0)
+            return { ok: true };
+        const stderr = (r.stderr ?? "").toString().trim();
+        const stdout = (r.stdout ?? "").toString().trim();
+        return { ok: false, error: stderr || stdout || `exit ${r.status}` };
+    },
+};
+/**
+ * Install `@uluops/cli` globally if not already present.
+ *
+ * Designed to never abort the parent setup flow:
+ * - If `ulu` is already on PATH, returns `{ installed: true, alreadyPresent: true }` without touching npm.
+ * - If `npm install -g` fails (permissions, network, nvm prefix surprise), returns
+ *   `{ installed: false, error }` so the caller can warn-and-continue.
+ * - In dryRun mode, no executor calls happen.
+ */
+export async function installCli(opts) {
+    const executor = opts.executor ?? defaultExecutor;
+    const existing = executor.detect();
+    if (existing !== null) {
+        return { installed: true, version: existing, alreadyPresent: true };
+    }
+    if (opts.dryRun) {
+        return { installed: false, version: null, alreadyPresent: false };
+    }
+    const res = executor.install();
+    if (!res.ok) {
+        return {
+            installed: false,
+            version: null,
+            alreadyPresent: false,
+            error: res.error,
+        };
+    }
+    const after = executor.detect();
+    return {
+        installed: after !== null,
+        version: after,
+        alreadyPresent: false,
+    };
+}
+/**
+ * Uninstall `@uluops/cli` globally. Best-effort: if the package isn't there,
+ * npm exits non-zero on some platforms — we treat that as success.
+ */
+export async function uninstallCli(opts) {
+    const executor = opts.executor ?? defaultExecutor;
+    if (opts.dryRun)
+        return { removed: true };
+    const before = executor.detect();
+    if (before === null)
+        return { removed: true };
+    const res = executor.uninstall();
+    if (res.ok)
+        return { removed: true };
+    const after = executor.detect();
+    if (after === null)
+        return { removed: true };
+    return { removed: false, error: res.error };
+}

package/dist/steps/commands.d.ts

@@ -8,7 +8,7 @@ export interface CommandsResult {
     files: string[];
     skippedReason?: string;
 }
-/** Install slash-command files, transforming to target format as needed. */
+/** Install pre-rendered command files from harness-specific assets. */
 export declare function installCommands(profile: HarnessProfile, localDefs: boolean, dryRun: boolean, existingManifestCommands?: string[]): Promise<CommandsResult>;
 /** Remove previously installed command files by relative path. Returns count of successfully removed files. */
 export declare function uninstallCommands(files: string[], defsPath: string): Promise<number>;

package/dist/steps/commands.js

@@ -1,57 +1,24 @@
-import { readFile, readdir, mkdir, unlink } from "node:fs/promises";
+import { readdir, mkdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { ASSETS_DIR, findProjectRoot } from "../lib/paths.js";
-import { copyIfChanged, writeIfChanged } from "../lib/file-ops.js";
+import { copyIfChanged, unlinkFiles } from "../lib/file-ops.js";
 const SUBDIRS = ["agents", "workflows", "pipelines"];
-/** Harnesses that support command installation. */
-const SUPPORTED_HARNESSES = new Set(["claude-code", "gemini-cli"]);
-// --- Gemini CLI transform ---
-/**
- * Strip YAML frontmatter from rendered markdown, returning just the body.
- */
-function stripFrontmatter(markdown) {
-    const first = markdown.indexOf("---");
-    if (first === -1)
-        return markdown;
-    const second = markdown.indexOf("---", first + 3);
-    if (second === -1)
-        return markdown;
-    return markdown.substring(second + 3);
-}
-/**
- * Escape a string for use in a TOML basic string (double-quoted).
- */
-function escapeToml(value) {
-    return value
-        .replace(/\\/g, "\\\\")
-        .replace(/"/g, '\\"')
-        .replace(/\n/g, "\\n")
-        .replace(/\r/g, "\\r")
-        .replace(/\t/g, "\\t");
-}
-/**
- * Transform a Claude Code markdown command to a Gemini CLI TOML command.
- * Strips frontmatter, substitutes $ARGUMENTS → {{args}}, wraps in TOML.
- */
-function transformToGeminiToml(markdown, description) {
-    const body = stripFrontmatter(markdown)
-        .replace(/\$ARGUMENTS/g, "{{args}}")
-        .trim();
-    // Escape """ in body for TOML multi-line strings
-    const escaped = body.replace(/"""/g, '""\\"');
-    return `description = "${escapeToml(description)}"\nprompt = """\n${escaped}\n"""\n`;
-}
-/**
- * Extract the description from a markdown command's YAML frontmatter.
- */
-function extractDescription(markdown) {
-    const match = markdown.match(/^description:\s*(.+)$/m);
-    return match?.[1]?.trim() ?? "";
-}
-// --- Install ---
-/** Install slash-command files, transforming to target format as needed. */
+/** Install pre-rendered command files from harness-specific assets. */
 export async function installCommands(profile, localDefs, dryRun, existingManifestCommands) {
-    if (!SUPPORTED_HARNESSES.has(profile.name)) {
+    const srcBase = join(ASSETS_DIR, profile.name, "commands");
+    const destBase = localDefs
+        ? join(await findProjectRoot(), "uluops", "commands")
+        : profile.paths.commandsDir;
+    // If no commands directory exists for this harness, skip gracefully
+    let hasSrcDir;
+    try {
+        await readdir(srcBase);
+        hasSrcDir = true;
+    }
+    catch {
+        hasSrcDir = false;
+    }
+    if (!hasSrcDir) {
         return {
             agentCommands: 0,
             workflowCommands: 0,
@@ -62,11 +29,6 @@ export async function installCommands(profile, localDefs, dryRun, existingManife
             skippedReason: "not-supported",
         };
     }
-    const srcBase = join(ASSETS_DIR, "commands");
-    const destBase = localDefs
-        ? join(await findProjectRoot(), "uluops", "commands")
-        : profile.paths.commandsDir;
-    const needsTransform = profile.name === "gemini-cli";
     let agentCommands = 0;
     let workflowCommands = 0;
     let pipelineCommands = 0;
@@ -80,26 +42,14 @@ export async function installCommands(profile, localDefs, dryRun, existingManife
         }
         let files;
         try {
-            files = (await readdir(srcDir)).filter((f) => f.endsWith(".md"));
+            files = (await readdir(srcDir)).filter((f) => f.endsWith(".md") || f.endsWith(".toml"));
         }
         catch {
             continue;
         }
         for (const file of files) {
-            const destFile = needsTransform
-                ? file.replace(/\.md$/, ".toml")
-                : file;
-            const relativePath = `${subdir}/${destFile}`;
-            let result;
-            if (needsTransform) {
-                const markdown = await readFile(join(srcDir, file), "utf-8");
-                const description = extractDescription(markdown);
-                const toml = transformToGeminiToml(markdown, description);
-                result = await writeIfChanged(join(destDir, destFile), toml, dryRun);
-            }
-            else {
-                result = await copyIfChanged(join(srcDir, file), join(destDir, destFile), dryRun);
-            }
+            const relativePath = `${subdir}/${file}`;
+            const result = await copyIfChanged(join(srcDir, file), join(destDir, file), dryRun);
             if (result === "copied") {
                 if (subdir === "agents")
                     agentCommands++;
@@ -142,6 +92,5 @@ export async function installCommands(profile, localDefs, dryRun, existingManife
 }
 /** Remove previously installed command files by relative path. Returns count of successfully removed files. */
 export async function uninstallCommands(files, defsPath) {
-    const { unlinkFiles } = await import("../lib/file-ops.js");
     return unlinkFiles(join(defsPath, "commands"), files);
 }

package/dist/steps/detect.js

@@ -16,6 +16,10 @@ export async function detect() {
     const isWsl = os === "linux" && release().toLowerCase().includes("microsoft");
     const profile = getShellProfile();
     const nodeVersion = process.version;
+    const majorVersion = parseInt(nodeVersion.slice(1).split(".")[0] ?? "0", 10);
+    if (majorVersion < 20) {
+        throw new Error(`Unsupported Node.js version: ${nodeVersion}. @uluops/setup requires Node.js 20 or higher.`);
+    }
     let claudeHomeExists = false;
     try {
         await access(getClaudeHome());

package/dist/steps/mcp.js

@@ -1,8 +1,9 @@
-import { readFile, access, mkdir, copyFile } from "node:fs/promises";
-import { join, basename } from "node:path";
+import { readFile, access } from "node:fs/promises";
+import { join } from "node:path";
 import { checkMcpPackageAvailability } from "../lib/config-merger.js";
 import { findProjectRoot, getBackupDir } from "../lib/paths.js";
 import { atomicWrite } from "../lib/atomic-write.js";
+import { backupFile } from "../lib/file-ops.js";
 /** Write UluOps MCP server entries into a harness's config file. */
 export async function installMcp(profile, apiKey, scope, dryRun) {
     const configPath = scope === "global"
@@ -33,22 +34,13 @@ export async function uninstallMcp(profile, configPath) {
     await profile.mcpConfig.write(configPath, cleaned);
 }
 async function backupConfig(harnessName, configPath) {
-    try {
-        await access(configPath);
-    }
-    catch {
-        return; // Nothing to back up
-    }
-    const backupDir = getBackupDir(harnessName);
-    await mkdir(backupDir, { recursive: true });
-    const filename = basename(configPath);
-    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    await copyFile(configPath, join(backupDir, `${filename}.${timestamp}.bak`));
+    await backupFile(configPath, getBackupDir(harnessName));
 }
 async function addToGitignore(localConfigFilename) {
-    const gitignorePath = join(process.cwd(), ".gitignore");
+    const root = await findProjectRoot();
+    const gitignorePath = join(root, ".gitignore");
     try {
-        await access(join(process.cwd(), ".git"));
+        await access(join(root, ".git"));
     }
     catch {
         return;

package/dist/steps/metrics.d.ts

@@ -13,8 +13,20 @@ export declare function getHookCommand(profile: HarnessProfile): string;
 export interface MetricsResult {
     toolFilesCopied: number;
     hookConfigured: boolean;
+    /**
+     * Version of @uluops/agent-metrics whose dist was installed into the
+     * harness tree. Null when the metrics step was skipped or the source
+     * package.json could not be read.
+     */
+    hooksInstalledVersion: string | null;
     skippedReason?: string;
 }
+/**
+ * Read the installed agent-metrics version from the harness tree.
+ * Returns null when the file is missing or unparseable.
+ * Exported so verify.ts can detect drift between installed and source.
+ */
+export declare function readInstalledMetricsVersion(toolDir: string): Promise<string | null>;
 /**
  * Install agent-metrics: copy tool files and configure hook.
  * Skips entirely if the harness doesn't support hooks.