@uluops/setup 0.2.0 → 0.4.0

package/dist/steps/mcp.js

@@ -1,40 +1,65 @@
-import { readFile, writeFile, access } from "node:fs/promises";
-import { join } from "node:path";
-import { readConfig, mergeUluopsMcp, removeUluopsMcp, writeConfig, } from "../lib/config-merger.js";
-import { getClaudeJsonPath, getLocalMcpPath } from "../lib/paths.js";
-export async function installMcp(apiKey, scope, dryRun) {
-    const configPath = scope === "global" ? getClaudeJsonPath() : getLocalMcpPath();
-    const config = await readConfig(configPath);
-    const merged = mergeUluopsMcp(config, apiKey);
+import { readFile, access, mkdir, copyFile } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { checkMcpPackageAvailability } from "../lib/config-merger.js";
+import { findProjectRoot, getBackupDir } from "../lib/paths.js";
+import { atomicWrite } from "../lib/atomic-write.js";
+/** Write UluOps MCP server entries into a harness's config file. */
+export async function installMcp(profile, apiKey, scope, dryRun) {
+    const configPath = scope === "global"
+        ? profile.paths.globalMcpConfig
+        : join(await findProjectRoot(), profile.paths.localMcpConfig);
+    const config = await profile.mcpConfig.read(configPath);
+    const merged = profile.mcpConfig.merge(config, apiKey);
+    const packageWarnings = [];
+    const { missing } = await checkMcpPackageAvailability();
+    if (missing.length > 0) {
+        packageWarnings.push(`npm packages not found in registry: ${missing.join(", ")}. MCP servers may fail to start.`);
+    }
     if (!dryRun) {
-        await writeConfig(configPath, merged);
+        // Backup before first write
+        await backupConfig(profile.name, configPath);
+        await profile.mcpConfig.write(configPath, merged);
     }
-    // If local scope in a git repo, add .mcp.json to .gitignore
     if (scope === "local" && !dryRun) {
-        await addToGitignore();
+        await addToGitignore(profile.paths.localMcpConfig);
     }
-    return { configPath, scope };
+    return { configPath, scope, packageWarnings };
+}
+/** Remove UluOps MCP server entries from the harness config. */
+export async function uninstallMcp(profile, configPath) {
+    await backupConfig(profile.name, configPath);
+    const config = await profile.mcpConfig.read(configPath);
+    const cleaned = profile.mcpConfig.remove(config);
+    await profile.mcpConfig.write(configPath, cleaned);
 }
-export async function uninstallMcp(configPath) {
-    const config = await readConfig(configPath);
-    const cleaned = removeUluopsMcp(config);
-    await writeConfig(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`));
 }
-async function addToGitignore() {
+async function addToGitignore(localConfigFilename) {
     const gitignorePath = join(process.cwd(), ".gitignore");
     try {
         await access(join(process.cwd(), ".git"));
     }
     catch {
-        return; // Not a git repo
+        return;
     }
     try {
         const content = await readFile(gitignorePath, "utf-8");
-        if (content.includes(".mcp.json"))
+        if (content.includes(localConfigFilename))
             return;
-        await writeFile(gitignorePath, content.trimEnd() + "\n.mcp.json\n");
+        await atomicWrite(gitignorePath, content.trimEnd() + `\n${localConfigFilename}\n`);
     }
     catch {
-        await writeFile(gitignorePath, ".mcp.json\n");
+        await atomicWrite(gitignorePath, `${localConfigFilename}\n`);
     }
 }

package/dist/steps/metrics.d.ts

@@ -1,22 +1,26 @@
 /**
  * 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).
  */
-/** Where agent-metrics dist files are installed */
-export declare function getMetricsToolDir(): string;
-/** Path to Claude Code's settings.json */
-export declare function getSettingsPath(): string;
+import type { HarnessProfile } from "../harnesses/index.js";
+/**
+ * The hook command that runs on SubagentStop.
+ * @internal Exported for testing only — not part of the public API.
+ */
+export declare function getHookCommand(profile: HarnessProfile): string;
 export interface MetricsResult {
     toolFilesCopied: number;
     hookConfigured: boolean;
+    skippedReason?: string;
 }
 /**
- * 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 declare function installMetrics(dryRun: boolean): Promise<MetricsResult>;
+export declare function installMetrics(profile: HarnessProfile, dryRun: boolean): Promise<MetricsResult>;
 /**
- * Uninstall agent-metrics: remove hook from settings and optionally remove tool files.
+ * Uninstall agent-metrics: remove hook and tool files.
  */
-export declare function uninstallMetrics(dryRun: boolean): Promise<void>;
+export declare function uninstallMetrics(profile: HarnessProfile, dryRun: boolean): Promise<void>;

package/dist/steps/metrics.js

@@ -1,25 +1,24 @@
 /**
  * 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 { 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");
+    return `"${process.execPath}" "${join(toolDir, "dist", "hook.js")}"`;
 }
 /**
  * Find the agent-metrics package source directory.
@@ -43,62 +42,37 @@ async function findMetricsSource() {
  * Copy agent-metrics dist files to the tool directory.
  * Copies all .js files needed for the hook and CLI.
  */
-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
+/** 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"))
-                continue;
-            if (file.includes(".test."))
+        const files = await readdir(srcDir);
+        for (const file of files) {
+            if (!file.endsWith(".js") || file.includes(".test.") || file === "test-utils.js")
                 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"];
+    if (!dryRun) {
+        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)
     try {
@@ -113,61 +87,57 @@ 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
+export async function installMetrics(profile, dryRun) {
+    if (!profile.hooks || !profile.paths.toolsDir || !profile.paths.settingsPath) {
+        return { toolFilesCopied: 0, hookConfigured: false, skippedReason: "no-hook-support" };
+    }
+    const toolDir = profile.paths.toolsDir;
+    const settingsPath = profile.paths.settingsPath;
     const srcRoot = await findMetricsSource();
     let toolFilesCopied = 0;
     if (srcRoot) {
-        // Copy tool files
         if (!dryRun) {
             await mkdir(toolDir, { recursive: true });
         }
         toolFilesCopied = await copyToolFiles(srcRoot, 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
+            // Not found anywhere
         }
     }
-    // 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 };
 }
 /**
- * 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,14 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { atomicWrite } from "../lib/atomic-write.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 +16,27 @@ export async function writeShellExport(profilePath, apiKey, dryRun) {
     }
     catch {
         if (!dryRun) {
-            await writeFile(profilePath, block + "\n");
+            await atomicWrite(profilePath, block + "\n");
         }
         return;
     }
     const startIdx = content.indexOf(FENCE_START);
     const endIdx = content.indexOf(FENCE_END);
-    if (startIdx !== -1 && endIdx !== -1) {
-        // Replace existing fenced block
+    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 +47,9 @@ 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) {
         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"));
     }
 }

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 validatePassword(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>;
+/** @internal Exported for testing only — not part of the public API. */
 export { validatePassword, 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) {
     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";
@@ -40,12 +42,18 @@ export async function signup() {
     });
     // Register
     const registerRes = await callApi(`${API_BASE}/auth/register`, "POST", { email, password: pwd });
+    if (!registerRes.data?.sessionToken) {
+        throw new Error("Registration succeeded but response missing session token");
+    }
     const sessionToken = registerRes.data.sessionToken;
     // Create API key using the session
     const keyRes = await callApi(`${API_BASE}/auth/keys`, "POST", { name: "Setup CLI" }, sessionToken);
+    if (!keyRes.data?.key) {
+        throw new Error("API key creation succeeded but response missing key");
+    }
     return {
         apiKey: keyRes.data.key,
-        email: registerRes.data.user.email,
+        email: registerRes.data.user?.email ?? email,
     };
 }
 async function callApi(url, method, body, bearerToken) {
@@ -71,7 +79,11 @@ 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");
+        }
+        return body;
     }
     // Handle known error codes
     const errorBody = await res.json().catch(() => null);
@@ -88,5 +100,5 @@ async function callApi(url, method, body, bearerToken) {
     }
     throw new Error(`Signup failed (${res.status}): ${message}`);
 }
-// Exported for testing
+/** @internal Exported for testing only — not part of the public API. */
 export { validatePassword, 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 {};