@uluops/setup 0.2.0 → 0.6.0

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

@@ -1,9 +1,14 @@
+import type { HarnessProfile } from "../harnesses/index.js";
 export interface CommandsResult {
     agentCommands: number;
     workflowCommands: number;
+    pipelineCommands: number;
     skipped: number;
     removed: number;
     files: string[];
+    skippedReason?: string;
 }
-export declare function installCommands(localDefs: boolean, dryRun: boolean, existingManifestCommands?: string[]): Promise<CommandsResult>;
+/** 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,13 +1,37 @@
 import { readdir, mkdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
-import { ASSETS_DIR, getCommandsDir } from "../lib/paths.js";
-import { copyIfChanged } from "../lib/file-ops.js";
-const SUBDIRS = ["agents", "workflows"];
-export async function installCommands(localDefs, dryRun, existingManifestCommands) {
-    const srcBase = join(ASSETS_DIR, "commands");
-    const destBase = getCommandsDir(localDefs);
+import { ASSETS_DIR, findProjectRoot } from "../lib/paths.js";
+import { copyIfChanged, unlinkFiles } from "../lib/file-ops.js";
+const SUBDIRS = ["agents", "workflows", "pipelines"];
+/** Install pre-rendered command files from harness-specific assets. */
+export async function installCommands(profile, localDefs, dryRun, existingManifestCommands) {
+    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,
+            pipelineCommands: 0,
+            skipped: 0,
+            removed: 0,
+            files: [],
+            skippedReason: "not-supported",
+        };
+    }
     let agentCommands = 0;
     let workflowCommands = 0;
+    let pipelineCommands = 0;
     let skipped = 0;
     const allFiles = [];
     for (const subdir of SUBDIRS) {
@@ -18,7 +42,7 @@ export async function installCommands(localDefs, dryRun, existingManifestCommand
         }
         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;
@@ -29,8 +53,10 @@ export async function installCommands(localDefs, dryRun, existingManifestCommand
             if (result === "copied") {
                 if (subdir === "agents")
                     agentCommands++;
-                else
+                else if (subdir === "workflows")
                     workflowCommands++;
+                else
+                    pipelineCommands++;
             }
             else {
                 skipped++;
@@ -58,12 +84,13 @@ export async function installCommands(localDefs, dryRun, existingManifestCommand
     return {
         agentCommands,
         workflowCommands,
+        pipelineCommands,
         skipped,
         removed,
         files: allFiles,
     };
 }
+/** 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.d.ts

@@ -1,3 +1,4 @@
+import type { HarnessProfile } from "../harnesses/index.js";
 export interface Environment {
     os: "linux" | "darwin" | "win32";
     isWsl: boolean;
@@ -5,5 +6,7 @@ export interface Environment {
     shellProfile: string | null;
     nodeVersion: string;
     claudeHomeExists: boolean;
+    detectedHarnesses: HarnessProfile[];
 }
+/** Detect the current environment: OS, shell, Node version, harnesses, and Claude home status. */
 export declare function detect(): Promise<Environment>;

package/dist/steps/detect.js

@@ -1,16 +1,25 @@
 import { platform, release } from "node:os";
 import { access } from "node:fs/promises";
 import { getClaudeHome, getShellProfile } from "../lib/paths.js";
+import { detectHarnesses } from "../harnesses/index.js";
 const SUPPORTED_PLATFORMS = new Set(["linux", "darwin", "win32"]);
+/** Detect the current environment: OS, shell, Node version, harnesses, and Claude home status. */
 export async function detect() {
     const p = platform();
     if (!SUPPORTED_PLATFORMS.has(p)) {
         throw new Error(`Unsupported platform: ${p}. Expected linux, darwin, or win32.`);
     }
     const os = p;
+    if (os === "win32") {
+        throw new Error("Windows (native) is not supported. Please use WSL2 (Ubuntu) and run setup inside WSL.");
+    }
     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());
@@ -19,6 +28,7 @@ export async function detect() {
     catch {
         // Does not exist
     }
+    const detectedHarnesses = detectHarnesses();
     return {
         os,
         isWsl,
@@ -26,5 +36,6 @@ export async function detect() {
         shellProfile: profile?.path ?? null,
         nodeVersion,
         claudeHomeExists,
+        detectedHarnesses,
     };
 }

package/dist/steps/mcp.d.ts

@@ -1,6 +1,10 @@
+import type { HarnessProfile } from "../harnesses/index.js";
 export interface McpResult {
     configPath: string;
     scope: "global" | "local";
+    packageWarnings: string[];
 }
-export declare function installMcp(apiKey: string, scope: "global" | "local", dryRun: boolean): Promise<McpResult>;
-export declare function uninstallMcp(configPath: string): Promise<void>;
+/** Write UluOps MCP server entries into a harness's config file. */
+export declare function installMcp(profile: HarnessProfile, apiKey: string, scope: "global" | "local", dryRun: boolean): Promise<McpResult>;
+/** Remove UluOps MCP server entries from the harness config. */
+export declare function uninstallMcp(profile: HarnessProfile, configPath: string): Promise<void>;

package/dist/steps/mcp.js

@@ -1,40 +1,57 @@
-import { readFile, writeFile, access } from "node:fs/promises";
+import { readFile, 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 { 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"
+        ? 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) {
+    await backupFile(configPath, getBackupDir(harnessName));
 }
-async function addToGitignore() {
-    const gitignorePath = join(process.cwd(), ".gitignore");
+async function addToGitignore(localConfigFilename) {
+    const root = await findProjectRoot();
+    const gitignorePath = join(root, ".gitignore");
     try {
-        await access(join(process.cwd(), ".git"));
+        await access(join(root, ".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,38 @@
 /**
  * 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;
+    /**
+     * 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;
 }
 /**
- * Install agent-metrics: copy tool files and configure SubagentStop hook.
+ * 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.
  */
-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>;