@uluops/setup 0.2.0 → 0.6.0

package/dist/steps/metrics.js

@@ -1,106 +1,108 @@
 /**
  * Metrics Step
  *
- * Installs agent-metrics tool files to ~/.claude/tools/agent-metrics/
- * and configures the SubagentStop hook in settings.json for auto-capture.
+ * Installs agent-metrics tool files and configures post-agent hooks.
+ * Only active for harnesses that support hooks (currently Claude Code only).
  */
-import { mkdir, readdir, copyFile, rm, access } from "node:fs/promises";
+import { mkdir, readdir, copyFile, rm, access, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { getClaudeHome } from "../lib/paths.js";
-import { readSettings, writeSettings, mergeUluopsHook, removeUluopsHook, } from "../lib/settings-merger.js";
-/** Where agent-metrics dist files are installed */
-export function getMetricsToolDir() {
-    return join(getClaudeHome(), "tools", "agent-metrics");
+/** Where agent-metrics dist files are installed (derived from profile) */
+function getMetricsToolDir(profile) {
+    return profile.paths.toolsDir;
 }
-/** Path to Claude Code's settings.json */
-export function getSettingsPath() {
-    return join(getClaudeHome(), "settings.json");
-}
-/** The hook command that runs on SubagentStop */
-function getHookCommand() {
-    const toolDir = getMetricsToolDir();
-    return `node ${join(toolDir, "dist", "hook.js")}`;
+/**
+ * The hook command that runs on SubagentStop.
+ * @internal Exported for testing only — not part of the public API.
+ */
+export function getHookCommand(profile) {
+    const toolDir = getMetricsToolDir(profile);
+    if (!toolDir)
+        throw new Error("No tool dir for this harness");
+    const nodePath = process.execPath;
+    const hookPath = join(toolDir, "dist", "hook.js");
+    if (nodePath.includes('"') || hookPath.includes('"')) {
+        throw new Error("Hook command paths must not contain double-quote characters");
+    }
+    return `"${nodePath}" "${hookPath}"`;
 }
 /**
  * Find the agent-metrics package source directory.
  * Looks for it as a sibling package in the monorepo or as an npm dependency.
+ *
+ * Also reads the source package.json's version so the manifest can record
+ * which agent-metrics version was actually copied — the shared version
+ * ledger across the setup↔agent-metrics seam.
  */
 async function findMetricsSource() {
-    // Try to find the package via Node.js module resolution
     try {
         const resolved = import.meta.resolve("@uluops/agent-metrics");
         // resolved is like file:///path/to/dist/index.js — get the package root
         const distDir = new URL(".", resolved).pathname;
         const pkgRoot = join(distDir, "..");
-        return pkgRoot;
+        const version = await readSourceVersion(pkgRoot);
+        return { pkgRoot, version };
+    }
+    catch {
+        return null;
+    }
+}
+async function readSourceVersion(pkgRoot) {
+    try {
+        const raw = await readFile(join(pkgRoot, "package.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === "string" ? parsed.version : null;
     }
     catch {
-        // Not installed as dependency
+        return null;
     }
-    return null;
 }
 /**
- * Copy agent-metrics dist files to the tool directory.
- * Copies all .js files needed for the hook and CLI.
+ * 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.
  */
-async function copyToolFiles(srcRoot, destRoot, dryRun) {
-    const srcDist = join(srcRoot, "dist");
-    const destDist = join(destRoot, "dist");
-    if (!dryRun) {
-        await mkdir(destDist, { recursive: true });
-        await mkdir(join(destDist, "commands"), { recursive: true });
-        await mkdir(join(destDist, "display"), { recursive: true });
-    }
-    let filesCopied = 0;
-    // Copy top-level dist files
-    const topFiles = await readdir(srcDist);
-    for (const file of topFiles) {
-        if (!file.endsWith(".js"))
-            continue;
-        if (file.includes(".test."))
-            continue;
-        if (file === "test-utils.js")
-            continue;
-        if (!dryRun) {
-            await copyFile(join(srcDist, file), join(destDist, file));
-        }
-        filesCopied++;
-    }
-    // Copy commands/ subdirectory
+export async function readInstalledMetricsVersion(toolDir) {
+    return readSourceVersion(toolDir);
+}
+/** Copy .js files from a source dir to a dest dir, skipping test files. */
+async function copyJsDir(srcDir, destDir, dryRun) {
+    let count = 0;
     try {
-        const cmdFiles = await readdir(join(srcDist, "commands"));
-        for (const file of cmdFiles) {
-            if (!file.endsWith(".js"))
+        const files = await readdir(srcDir);
+        for (const file of files) {
+            if (!file.endsWith(".js") || file.includes(".test.") || file === "test-utils.js")
                 continue;
-            if (file.includes(".test."))
-                continue;
-            if (!dryRun) {
-                await copyFile(join(srcDist, "commands", file), join(destDist, "commands", file));
-            }
-            filesCopied++;
+            if (!dryRun)
+                await copyFile(join(srcDir, file), join(destDir, file));
+            count++;
         }
     }
     catch {
-        // commands/ doesn't exist — not critical
+        // Directory doesn't exist — not critical
     }
-    // Copy display/ subdirectory
-    try {
-        const dispFiles = await readdir(join(srcDist, "display"));
-        for (const file of dispFiles) {
-            if (!file.endsWith(".js"))
-                continue;
-            if (file.includes(".test."))
-                continue;
-            if (!dryRun) {
-                await copyFile(join(srcDist, "display", file), join(destDist, "display", file));
-            }
-            filesCopied++;
+    return count;
+}
+async function copyToolFiles(srcRoot, destRoot, dryRun) {
+    const srcDist = join(srcRoot, "dist");
+    const destDist = join(destRoot, "dist");
+    const subDirs = ["commands", "display"];
+    // Replace, don't merge. The previous behavior copied new files over old
+    // ones without removing stale entries — if agent-metrics renames or
+    // removes a file in a future version, the stale file would persist on
+    // disk and shadow the new one. Wipe dist/ before repopulating so the
+    // installed tree matches the source tree exactly.
+    if (!dryRun) {
+        await rm(destDist, { recursive: true, force: true });
+        await mkdir(destDist, { recursive: true });
+        for (const sub of subDirs) {
+            await mkdir(join(destDist, sub), { recursive: true });
         }
     }
-    catch {
-        // display/ doesn't exist — not critical
+    let filesCopied = await copyJsDir(srcDist, destDist, dryRun);
+    for (const sub of subDirs) {
+        filesCopied += await copyJsDir(join(srcDist, sub), join(destDist, sub), dryRun);
     }
-    // Copy package.json (needed for CLI bin resolution)
+    // Copy package.json (needed for CLI bin resolution and version detection)
     try {
         if (!dryRun) {
             await copyFile(join(srcRoot, "package.json"), join(destRoot, "package.json"));
@@ -113,61 +115,59 @@ async function copyToolFiles(srcRoot, destRoot, dryRun) {
     return filesCopied;
 }
 /**
- * Install agent-metrics: copy tool files and configure SubagentStop hook.
+ * Install agent-metrics: copy tool files and configure hook.
+ * Skips entirely if the harness doesn't support hooks.
  */
-export async function installMetrics(dryRun) {
-    const toolDir = getMetricsToolDir();
-    const settingsPath = getSettingsPath();
-    // Find source package
-    const srcRoot = await findMetricsSource();
+export async function installMetrics(profile, dryRun) {
+    if (!profile.hooks || !profile.paths.toolsDir || !profile.paths.settingsPath) {
+        return {
+            toolFilesCopied: 0,
+            hookConfigured: false,
+            hooksInstalledVersion: null,
+            skippedReason: "no-hook-support",
+        };
+    }
+    const toolDir = profile.paths.toolsDir;
+    const settingsPath = profile.paths.settingsPath;
+    const source = await findMetricsSource();
     let toolFilesCopied = 0;
-    if (srcRoot) {
-        // Copy tool files
+    if (source) {
         if (!dryRun) {
             await mkdir(toolDir, { recursive: true });
         }
-        toolFilesCopied = await copyToolFiles(srcRoot, toolDir, dryRun);
+        toolFilesCopied = await copyToolFiles(source.pkgRoot, toolDir, dryRun);
     }
-    else {
-        // Check if already installed (from previous run or install.sh)
-        try {
-            await access(join(toolDir, "dist", "hook.js"));
-        }
-        catch {
-            // Not found anywhere — skip tool installation, just configure hook
-            // if files happen to exist
-        }
-    }
-    // Configure hook in settings.json
     let hookConfigured = false;
-    if (!dryRun) {
-        const settings = await readSettings(settingsPath);
-        const hookCommand = getHookCommand();
-        const merged = mergeUluopsHook(settings, hookCommand);
-        await writeSettings(settingsPath, merged);
+    const hookJsPath = join(toolDir, "dist", "hook.js");
+    const hookJsExists = await access(hookJsPath).then(() => true, () => false);
+    if (hookJsExists && !dryRun) {
+        const hookCommand = getHookCommand(profile);
+        await profile.hooks.install(settingsPath, hookCommand, false);
         hookConfigured = true;
     }
-    else {
+    else if (hookJsExists && dryRun) {
         hookConfigured = true;
     }
-    return { toolFilesCopied, hookConfigured };
+    // Prefer the source version (from import.meta.resolve); fall back to reading
+    // the just-copied package.json from the harness tree so the manifest still
+    // records something useful when the source resolution returned null but a
+    // prior install left files behind.
+    const hooksInstalledVersion = source?.version ?? (hookJsExists ? await readInstalledMetricsVersion(toolDir) : null);
+    return { toolFilesCopied, hookConfigured, hooksInstalledVersion };
 }
 /**
- * Uninstall agent-metrics: remove hook from settings and optionally remove tool files.
+ * Uninstall agent-metrics: remove hook and tool files.
  */
-export async function uninstallMetrics(dryRun) {
-    const settingsPath = getSettingsPath();
-    const toolDir = getMetricsToolDir();
-    // Remove hook from settings.json
+export async function uninstallMetrics(profile, dryRun) {
+    if (!profile.hooks || !profile.paths.toolsDir || !profile.paths.settingsPath) {
+        return;
+    }
     if (!dryRun) {
-        const settings = await readSettings(settingsPath);
-        const cleaned = removeUluopsHook(settings);
-        await writeSettings(settingsPath, cleaned);
+        await profile.hooks.remove(profile.paths.settingsPath, false);
     }
-    // Remove tool directory
     if (!dryRun) {
         try {
-            await rm(toolDir, { recursive: true, force: true });
+            await rm(profile.paths.toolsDir, { recursive: true, force: true });
         }
         catch {
             // Already gone

package/dist/steps/shell.d.ts

@@ -1,2 +1,4 @@
+/** Write a fenced ULUOPS_API_KEY export block into the user's shell profile, replacing any existing UluOps block. */
 export declare function writeShellExport(profilePath: string, apiKey: string, dryRun: boolean): Promise<void>;
+/** Remove the fenced UluOps export block from the user's shell profile. */
 export declare function removeShellExport(profilePath: string): Promise<void>;

package/dist/steps/shell.js

@@ -1,7 +1,17 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWrite } from "../lib/atomic-write.js";
+import { backupFile } from "../lib/file-ops.js";
+import { getUluopsDir } from "../lib/paths.js";
 const FENCE_START = "# --- UluOps (managed by @uluops/setup) ---";
 const FENCE_END = "# --- /UluOps ---";
+/** Characters safe for shell variable values (no metacharacters). */
+const SAFE_KEY_PATTERN = /^[a-zA-Z0-9_\-\.]+$/;
+/** Write a fenced ULUOPS_API_KEY export block into the user's shell profile, replacing any existing UluOps block. */
 export async function writeShellExport(profilePath, apiKey, dryRun) {
+    if (!SAFE_KEY_PATTERN.test(apiKey)) {
+        throw new Error("API key contains characters unsafe for shell export. Only alphanumeric, underscore, hyphen, and dot are allowed.");
+    }
     const block = `${FENCE_START}\nexport ULUOPS_API_KEY="${apiKey}"\n${FENCE_END}`;
     let content;
     try {
@@ -9,27 +19,30 @@ export async function writeShellExport(profilePath, apiKey, dryRun) {
     }
     catch {
         if (!dryRun) {
-            await writeFile(profilePath, block + "\n");
+            await atomicWrite(profilePath, block + "\n", { mode: 0o600 });
         }
         return;
     }
     const startIdx = content.indexOf(FENCE_START);
     const endIdx = content.indexOf(FENCE_END);
-    if (startIdx !== -1 && endIdx !== -1) {
-        // Replace existing fenced block
+    if (!dryRun) {
+        await backupProfile(profilePath);
+    }
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        // Replace existing fenced block (use last FENCE_END after FENCE_START to handle duplicates)
         const before = content.slice(0, startIdx);
         const after = content.slice(endIdx + FENCE_END.length);
         if (!dryRun) {
-            await writeFile(profilePath, before + block + after);
+            await atomicWrite(profilePath, before + block + after);
         }
     }
     else {
-        // Append
         if (!dryRun) {
-            await writeFile(profilePath, content.trimEnd() + "\n\n" + block + "\n");
+            await atomicWrite(profilePath, content.trimEnd() + "\n\n" + block + "\n");
         }
     }
 }
+/** Remove the fenced UluOps export block from the user's shell profile. */
 export async function removeShellExport(profilePath) {
     let content;
     try {
@@ -40,9 +53,13 @@ export async function removeShellExport(profilePath) {
     }
     const startIdx = content.indexOf(FENCE_START);
     const endIdx = content.indexOf(FENCE_END);
-    if (startIdx !== -1 && endIdx !== -1) {
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        await backupProfile(profilePath);
         const before = content.slice(0, startIdx);
         const after = content.slice(endIdx + FENCE_END.length);
-        await writeFile(profilePath, (before + after).replace(/\n{3,}/g, "\n\n"));
+        await atomicWrite(profilePath, (before + after).replace(/\n{3,}/g, "\n\n"));
     }
 }
+async function backupProfile(profilePath) {
+    await backupFile(profilePath, join(getUluopsDir(), "backups", "shell"));
+}

package/dist/steps/signup.d.ts

@@ -1,13 +1,16 @@
 import type { AuthResult } from "./auth.js";
 /**
- * Password complexity rules (matches ops-uluops-api validation).
- * Validated client-side for instant feedback before network round-trip.
+ * Advisory password hints. Returns warning strings for inquirer display,
+ * but all are non-blocking — server validation is the authority.
+ * @internal Exported for testing only — not part of the public API.
  */
-declare function validatePassword(password: string): string | true;
+declare function hintPassword(password: string): true;
+/** @internal Exported for testing only — not part of the public API. */
 declare function validateEmail(email: string): string | true;
 /**
  * Interactive signup flow: create account + generate API key.
  * Returns the same AuthResult shape as resolveApiKey for seamless integration.
  */
 export declare function signup(): Promise<AuthResult>;
-export { validatePassword, validateEmail };
+/** @internal Exported for testing only — not part of the public API. */
+export { hintPassword, validateEmail };

package/dist/steps/signup.js

@@ -1,21 +1,23 @@
 const API_BASE = "https://api.uluops.ai/api/v1";
 /**
- * Password complexity rules (matches ops-uluops-api validation).
- * Validated client-side for instant feedback before network round-trip.
+ * Advisory password hints. Returns warning strings for inquirer display,
+ * but all are non-blocking — server validation is the authority.
+ * @internal Exported for testing only — not part of the public API.
  */
-function validatePassword(password) {
+function hintPassword(password) {
     if (password.length < 8)
-        return "Password must be at least 8 characters";
-    if (password.length > 128)
-        return "Password must be at most 128 characters";
-    if (!/[a-z]/.test(password))
-        return "Password must include a lowercase letter";
-    if (!/[A-Z]/.test(password))
-        return "Password must include an uppercase letter";
-    if (!/[0-9]/.test(password))
-        return "Password must include a number";
+        console.warn("  ⚠ Hint: server may require at least 8 characters");
+    else if (password.length > 128)
+        console.warn("  ⚠ Hint: server may reject passwords over 128 characters");
+    else if (!/[a-z]/.test(password))
+        console.warn("  ⚠ Hint: server may require a lowercase letter");
+    else if (!/[A-Z]/.test(password))
+        console.warn("  ⚠ Hint: server may require an uppercase letter");
+    else if (!/[0-9]/.test(password))
+        console.warn("  ⚠ Hint: server may require a number");
     return true;
 }
+/** @internal Exported for testing only — not part of the public API. */
 function validateEmail(email) {
     if (!email.trim())
         return "Email is required";
@@ -36,19 +38,19 @@ export async function signup() {
     const pwd = await password({
         message: "Password",
         mask: "*",
-        validate: validatePassword,
+        validate: hintPassword,
     });
     // Register
-    const registerRes = await callApi(`${API_BASE}/auth/register`, "POST", { email, password: pwd });
+    const registerRes = await callApi(`${API_BASE}/auth/register`, "POST", { email, password: pwd }, undefined, (res) => !!res.data?.sessionToken && typeof res.data.user?.email === "string");
     const sessionToken = registerRes.data.sessionToken;
     // Create API key using the session
-    const keyRes = await callApi(`${API_BASE}/auth/keys`, "POST", { name: "Setup CLI" }, sessionToken);
+    const keyRes = await callApi(`${API_BASE}/auth/keys`, "POST", { name: "Setup CLI" }, sessionToken, (res) => !!res.data?.key);
     return {
         apiKey: keyRes.data.key,
-        email: registerRes.data.user.email,
+        email: registerRes.data.user?.email ?? email,
     };
 }
-async function callApi(url, method, body, bearerToken) {
+async function callApi(url, method, body, bearerToken, validate) {
     const headers = {
         "Content-Type": "application/json",
     };
@@ -71,7 +73,14 @@ async function callApi(url, method, body, bearerToken) {
         throw err;
     }
     if (res.ok) {
-        return (await res.json());
+        const body = await res.json();
+        if (typeof body !== "object" || body === null) {
+            throw new Error("Unexpected API response shape");
+        }
+        if (validate && !validate(body)) {
+            throw new Error("API response failed structural validation");
+        }
+        return body;
     }
     // Handle known error codes
     const errorBody = await res.json().catch(() => null);
@@ -88,5 +97,5 @@ async function callApi(url, method, body, bearerToken) {
     }
     throw new Error(`Signup failed (${res.status}): ${message}`);
 }
-// Exported for testing
-export { validatePassword, validateEmail };
+/** @internal Exported for testing only — not part of the public API. */
+export { hintPassword, validateEmail };

package/dist/steps/verify.d.ts

@@ -1,4 +1,4 @@
-interface VerifyResult {
+export interface VerifyResult {
     ok: boolean;
     checks: {
         label: string;
@@ -6,5 +6,5 @@ interface VerifyResult {
         detail?: string;
     }[];
 }
+/** Run all verification checks against the current installation and return structured results. */
 export declare function verify(): Promise<VerifyResult>;
-export {};