@uluops/setup 0.7.0 → 0.9.0

package/dist/cli.js

@@ -3,11 +3,13 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { info, printAgentList } from "./lib/display.js";
 import { getVersion } from "./lib/version.js";
-import { resolveHarnessName, listHarnesses, detectHarnesses, HarnessNotTestedError, } from "./harnesses/index.js";
+import { listHarnesses, detectHarnesses, getProfile, HarnessNotTestedError, } from "./harnesses/index.js";
 import { InstallLockHeldError } from "./lib/install-lock.js";
 import { runSetup } from "./commands/setup.js";
 import { runUninstall } from "./commands/uninstall.js";
 import { runVerify } from "./commands/verify.js";
+import { ConflictRejectedError } from "./commands/errors.js";
+import { selectHarnesses, HarnessSelectionError, } from "./cli/select-harnesses.js";
 async function main() {
     const version = await getVersion();
     const program = new Command()
@@ -16,7 +18,8 @@ async function main() {
         .version(version)
         .option("--api-key <key>", "API key (skip prompt)")
         .option("--signup", "Create a new account (email + password, no browser)")
-        .option("--harness <name>", `Target harness: ${listHarnesses().join(", ")} (aliases: claude, oc, gemini)`, "claude-code")
+        .option("--harness <name>", `Target harness: ${listHarnesses().join(", ")} (aliases: claude, oc, gemini). Accepts comma-separated subset ("claude-code,codex") or "all" to install into every detected stable harness.`, "claude-code")
+        .option("--all-detected", "Install into every detected stable harness. Canonical form; equivalent to --harness all.", false)
         .option("--scope <mode>", 'MCP connectivity scope: "global" (~/.claude.json) or "local" (.mcp.json)', "global")
         .option("--local-defs", "Save agents/commands locally (./uluops/) for project isolation", false)
         .option("--shell", "Write API key export to shell profile", false)
@@ -46,7 +49,17 @@ async function main() {
         return;
     }
     if (opts.uninstall) {
-        await runUninstall({ dryRun: opts.dryRun });
+        // --harness / --all-detected on uninstall acts as a FILTER over the
+        // manifest's recorded harnesses, not a selection over what's detected
+        // on disk. Pass through the raw flag values; runUninstall delegates
+        // parsing + validation to resolveUninstallFilter (which mirrors the
+        // install-side conflict detection).
+        await runUninstall({
+            dryRun: opts.dryRun,
+            harnessArg: opts.harness,
+            harnessFromCli: program.getOptionValueSource("harness") === "cli",
+            allDetected: opts.allDetected,
+        });
         return;
     }
     if (opts.scope && opts.scope !== "local" && opts.scope !== "global") {
@@ -54,42 +67,59 @@ async function main() {
         process.exit(1);
     }
     const scope = opts.scope === "local" ? "local" : "global";
-    // Resolve harness: if --harness was passed explicitly, honor it as-is.
-    // Otherwise auto-detect — single match wins silently, multiple matches
-    // prompt the user, no matches falls back to the default (claude-code)
-    // to preserve the landing-page "just run npx @uluops/setup" promise.
-    const harnessExplicit = program.getOptionValueSource("harness") === "cli";
-    let harnessName;
-    if (harnessExplicit) {
-        harnessName = resolveHarnessName(opts.harness);
-    }
-    else {
-        const detected = detectHarnesses();
-        if (detected.length === 1) {
-            harnessName = detected[0].name;
-            if (harnessName !== "claude-code") {
-                info(chalk.dim(`Detected ${chalk.cyan(detected[0].displayName)} — using as target (pass --harness to override)`));
-            }
-        }
-        else if (detected.length > 1) {
-            const isInteractive = !opts.yes && !opts.apiKey && !process.env["ULUOPS_API_KEY"] && process.stdin.isTTY;
-            if (isInteractive) {
-                const { select } = await import("@inquirer/prompts");
-                harnessName = await select({
-                    message: "Multiple harnesses detected — which one are you setting up?",
-                    choices: detected.map((p) => ({ name: p.displayName, value: p.name })),
-                    default: detected[0].name,
+    // Resolve harness selection through the pure selection module so the
+    // matrix of (--harness, --all-detected, detection count, TTY) lives in
+    // one tested place. cli.ts only wires the prompt and emit-info callbacks.
+    const detected = detectHarnesses();
+    const isInteractive = !opts.yes &&
+        !opts.apiKey &&
+        !process.env["ULUOPS_API_KEY"] &&
+        !!process.stdin.isTTY;
+    let harnessNames;
+    try {
+        harnessNames = await selectHarnesses({
+            harnessArg: opts.harness,
+            harnessFromCli: program.getOptionValueSource("harness") === "cli",
+            allDetected: opts.allDetected,
+            detected,
+            defaultHarness: "claude-code",
+            isInteractive,
+            emitInfo: (msg) => info(chalk.dim(msg)),
+            promptCheckbox: async (profiles) => {
+                const { checkbox } = await import("@inquirer/prompts");
+                const chosen = await checkbox({
+                    message: "Multiple harnesses detected. Which would you like to install into?",
+                    instructions: " (use space to toggle, enter to confirm)",
+                    choices: profiles.map((p) => ({
+                        name: p.displayName,
+                        value: p.name,
+                        checked: true,
+                    })),
                 });
                 console.log();
-            }
-            else {
-                harnessName = detected[0].name;
-                info(chalk.dim(`Multiple harnesses detected (${detected.map((p) => p.displayName).join(", ")}); defaulting to ${chalk.cyan(detected[0].displayName)} — pass --harness to choose`));
-            }
-        }
-        else {
-            harnessName = resolveHarnessName(opts.harness);
+                return chosen;
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof HarnessSelectionError) {
+            console.error(chalk.red(`\n  ${err.message}\n`));
+            process.exit(1);
         }
+        throw err;
+    }
+    // Resolve every name through getProfile up front. This catches typos
+    // (e.g. `--harness claude-cod,codex`) before any state is touched and
+    // surfaces the canonical "Available: ..." error. Aliases ('claude' →
+    // 'claude-code') are normalized here as a side effect.
+    let resolvedHarnesses;
+    try {
+        resolvedHarnesses = harnessNames.map((n) => getProfile(n).name);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`\n  ${msg}\n`));
+        process.exit(1);
     }
     await runSetup({
         apiKey: opts.apiKey,
@@ -104,10 +134,21 @@ async function main() {
         skipValidation: opts.skipValidation,
         dryRun: opts.dryRun,
         yes: opts.yes,
-        harness: harnessName,
+        harnesses: resolvedHarnesses,
     });
 }
 main().catch((err) => {
+    if (err instanceof ConflictRejectedError) {
+        // Single-harness path: user declined the conflict prompt. Exit 0
+        // (today's UX — no error). The multi-harness orchestrator catches
+        // this inside its loop and never lets it bubble to here when there
+        // are siblings to install; this handler only fires when the declined
+        // harness was the only target (the loop continues, finds nothing
+        // installed, and... actually the loop swallows it before propagating,
+        // so this handler is defense-in-depth for any future caller of
+        // checkConflicts outside the loop). Either way: exit 0, no message.
+        process.exit(0);
+    }
     if (err instanceof HarnessNotTestedError) {
         console.error(chalk.yellow(`\n  ${err.message}\n`));
         process.exit(1);

package/dist/commands/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Typed setup errors. Each class corresponds to a distinct failure category
+ * the per-harness orchestrator (or the top-level CLI handler) needs to
+ * discriminate to choose the right exit code, message, and continue/abort
+ * decision.
+ *
+ * Discrimination at the type level — not on error.message — because messages
+ * are user-facing and will drift; constructors are stable.
+ */
+/**
+ * Raised when the user declines a "Continue?" conflict prompt during a
+ * first-install for a harness. The single-harness path catches this in
+ * the CLI top-level handler and exits 0 cleanly (today's UX). The
+ * multi-harness path catches it in the per-harness loop, marks that
+ * harness as `declined`, and continues with siblings.
+ *
+ * NOT an operational failure — this is a deliberate user choice. The
+ * exit-code classifier (spec §7.5) treats `declined` as exit 0 unless
+ * combined with an actual `failed` harness in the same run.
+ */
+export declare class ConflictRejectedError extends Error {
+    readonly harnessName: string;
+    constructor(harnessName: string);
+}

package/dist/commands/errors.js

@@ -0,0 +1,28 @@
+/**
+ * Typed setup errors. Each class corresponds to a distinct failure category
+ * the per-harness orchestrator (or the top-level CLI handler) needs to
+ * discriminate to choose the right exit code, message, and continue/abort
+ * decision.
+ *
+ * Discrimination at the type level — not on error.message — because messages
+ * are user-facing and will drift; constructors are stable.
+ */
+/**
+ * Raised when the user declines a "Continue?" conflict prompt during a
+ * first-install for a harness. The single-harness path catches this in
+ * the CLI top-level handler and exits 0 cleanly (today's UX). The
+ * multi-harness path catches it in the per-harness loop, marks that
+ * harness as `declined`, and continues with siblings.
+ *
+ * NOT an operational failure — this is a deliberate user choice. The
+ * exit-code classifier (spec §7.5) treats `declined` as exit 0 unless
+ * combined with an actual `failed` harness in the same run.
+ */
+export class ConflictRejectedError extends Error {
+    harnessName;
+    constructor(harnessName) {
+        super(`User declined conflict prompt for ${harnessName}`);
+        this.harnessName = harnessName;
+        this.name = "ConflictRejectedError";
+    }
+}

package/dist/commands/helpers.d.ts

@@ -2,6 +2,7 @@ import { detect } from "../steps/detect.js";
 import type { McpResult } from "../steps/mcp.js";
 import type { AgentsResult } from "../steps/agents.js";
 import type { CommandsResult } from "../steps/commands.js";
+import type { SkillsResult } from "../steps/skills.js";
 import type { MetricsResult } from "../steps/metrics.js";
 import type { CliExecutor, CliInstallResult } from "../steps/cli.js";
 import type { AgentMetricsCliExecutor, AgentMetricsCliInstallResult } from "../steps/agent-metrics-cli.js";
@@ -12,6 +13,7 @@ export declare function initContext(opts: {
     signup: boolean;
     skipValidation: boolean;
     yes: boolean;
+    dryRun?: boolean;
 }): Promise<{
     env: Awaited<ReturnType<typeof detect>>;
     apiKey: string;
@@ -31,6 +33,11 @@ export declare function installCommandsDefs(profile: HarnessProfile, opts: {
     localDefs: boolean;
     dryRun: boolean;
 }, prev?: string[]): Promise<CommandsResult>;
+/** Copy Codex-style skills from assets to the harness directory. */
+export declare function installSkillsDefs(profile: HarnessProfile, opts: {
+    localDefs: boolean;
+    dryRun: boolean;
+}, prev?: string[]): Promise<SkillsResult>;
 /** Install agent-metrics hook and tool files (Claude Code only). */
 export declare function configureMetricsStep(profile: HarnessProfile, opts: {
     dryRun: boolean;

package/dist/commands/helpers.js

@@ -3,10 +3,11 @@ import { join } from "node:path";
 import { readdir } from "node:fs/promises";
 import { detect } from "../steps/detect.js";
 import { signup } from "../steps/signup.js";
-import { resolveApiKey, hasCredentialsFile } from "../steps/auth.js";
+import { resolveApiKey, hasCredentialsFile, writeCredentialsFile } from "../steps/auth.js";
 import { installMcp } from "../steps/mcp.js";
 import { installAgents } from "../steps/agents.js";
 import { installCommands } from "../steps/commands.js";
+import { installSkills } from "../steps/skills.js";
 import { installMetrics } from "../steps/metrics.js";
 import { installCli, CLI_PACKAGE } from "../steps/cli.js";
 import { installAgentMetricsCli, AGENT_METRICS_PACKAGE, AGENT_METRICS_BIN, } from "../steps/agent-metrics-cli.js";
@@ -15,6 +16,7 @@ import { probeHookSupport } from "../lib/settings-merger.js";
 import { findProjectRoot, ASSETS_DIR } from "../lib/paths.js";
 import { getHealthTimeout } from "../lib/health.js";
 import { ok, warn, fail, info } from "../lib/display.js";
+import { ConflictRejectedError } from "./errors.js";
 /**
  * Decide whether to ask the user "Are you creating a new account?".
  * The prompt is the new-user friction-reducer — it should fire only when
@@ -47,6 +49,10 @@ async function shouldPromptForAccount(opts) {
 export async function initContext(opts) {
     const env = await detect();
     let apiKey;
+    let resolvedEmail = null;
+    // Capture before auth runs — a successful resolve via the credentials file
+    // would otherwise create the appearance of "no prior file" after the fact.
+    const credsExistedAtStart = await hasCredentialsFile();
     let creatingAccount = opts.signup;
     if (!opts.signup && (await shouldPromptForAccount(opts))) {
         const { confirm } = await import("@inquirer/prompts");
@@ -56,21 +62,28 @@ export async function initContext(opts) {
         });
         console.log();
     }
+    let credsSource = "flag";
     try {
         if (creatingAccount) {
             info("Create your UluOps account\n");
             const auth = await signup();
             apiKey = auth.apiKey;
+            resolvedEmail = auth.email;
+            credsSource = "signup";
             ok(`Account created (${auth.email})`);
             ok(`API key generated`);
         }
         else {
+            const interactive = !opts.yes && !opts.apiKey && !process.env["ULUOPS_API_KEY"];
             const auth = await resolveApiKey({
                 apiKeyFlag: opts.apiKey,
                 skipValidation: opts.skipValidation,
-                interactive: !opts.yes && !opts.apiKey && !process.env["ULUOPS_API_KEY"],
+                interactive,
             });
             apiKey = auth.apiKey;
+            resolvedEmail = auth.email;
+            credsSource =
+                opts.apiKey || process.env["ULUOPS_API_KEY"] ? "flag" : "prompt";
             if (auth.email)
                 ok(`Key validated (${auth.email})`);
             else if (opts.skipValidation)
@@ -83,6 +96,34 @@ export async function initContext(opts) {
         fail(err instanceof Error ? err.message : String(err));
         process.exit(1);
     }
+    // Persist the key locally so @uluops/cli and the SDK can read it from disk.
+    // Always write after signup (key was just minted, nothing else holds it).
+    // Otherwise write only if there was no prior file — avoids churning
+    // createdAt on every returning-user invocation.
+    if (credsSource === "signup" || !credsExistedAtStart) {
+        try {
+            await writeCredentialsFile(apiKey, {
+                email: resolvedEmail,
+                source: credsSource,
+                dryRun: opts.dryRun,
+            });
+            if (!opts.dryRun)
+                ok("Credentials saved → ~/.uluops/credentials.json");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            warn(`Could not save credentials to ~/.uluops/credentials.json: ${msg}`);
+            // On signup, the warn() above is the ONLY surface that names the failure.
+            // The key was just minted; if we don't persist it and don't surface it,
+            // the user has no path back to it short of minting another one.
+            // Print recovery context so the message is actionable, not just a flag.
+            if (credsSource === "signup") {
+                warn("  Your key was generated but is not on disk for @uluops/cli to read.");
+                warn("  Copy it from the MCP config block written above (look for ULUOPS_API_KEY)");
+                warn("  or pass --skip-validation --api-key <key> on the next run.");
+            }
+        }
+    }
     return { env, apiKey };
 }
 /** Write MCP server entries to harness config and report warnings. */
@@ -107,6 +148,11 @@ export async function installAgentsDefs(profile, opts, prev) {
         ? "./uluops/agents/"
         : `${profile.paths.agentsDir.replace(process.env["HOME"] ?? "", "~")}/`;
     ok(`${res.files.length} agents → ${dest}${parts.length ? ` (${parts.join(", ")})` : ""}`);
+    // Per-file copy failures are non-fatal — surface them so the user knows
+    // re-running setup will retry the unwritten files.
+    for (const f of res.failures) {
+        warn(`Failed to copy agent ${f.file}: ${f.error} — re-run setup to retry`);
+    }
     return res;
 }
 /** Copy slash-command definitions from assets (Claude Code only). */
@@ -128,6 +174,33 @@ export async function installCommandsDefs(profile, opts, prev) {
         ? "./uluops/commands/"
         : `${profile.paths.commandsDir.replace(process.env["HOME"] ?? "", "~")}/`;
     ok(`${res.files.length} commands → ${dest}${parts.length ? ` (${parts.join(", ")})` : ""}`);
+    // Per-file copy failures are non-fatal — surface them so the user knows
+    // re-running setup will retry the unwritten files.
+    for (const f of res.failures) {
+        warn(`Failed to copy command ${f.file}: ${f.error} — re-run setup to retry`);
+    }
+    return res;
+}
+/** Copy Codex-style skills from assets to the harness directory. */
+export async function installSkillsDefs(profile, opts, prev) {
+    const res = await installSkills(profile, opts.localDefs, opts.dryRun, prev);
+    if (res.skippedReason === "not-supported") {
+        return res;
+    }
+    const parts = [];
+    if (res.copied > 0)
+        parts.push(`${res.copied} copied`);
+    if (res.skipped > 0)
+        parts.push(`${res.skipped} unchanged`);
+    if (res.removed > 0)
+        parts.push(`${res.removed} removed`);
+    const dest = opts.localDefs
+        ? "./uluops/skills/"
+        : `${(profile.paths.skillsDir ?? "").replace(process.env["HOME"] ?? "", "~")}/`;
+    ok(`${res.files.length} skills → ${dest}${parts.length ? ` (${parts.join(", ")})` : ""}`);
+    for (const f of res.failures) {
+        warn(`Failed to copy skill ${f.file}: ${f.error} — re-run setup to retry`);
+    }
     return res;
 }
 /** Install agent-metrics hook and tool files (Claude Code only). */
@@ -360,7 +433,11 @@ export async function checkConflicts(profile, localDefs) {
     const { confirm } = await import("@inquirer/prompts");
     const proceed = await confirm({ message: "Continue?", default: true });
     if (!proceed) {
-        process.exit(0);
+        // Throw instead of process.exit so the multi-harness loop can catch and
+        // continue with sibling harnesses. The single-harness CLI top-level
+        // handler catches ConflictRejectedError and exits 0 cleanly, preserving
+        // today's UX. (Spec §7.5; replaces the prior process.exit(0).)
+        throw new ConflictRejectedError(profile.name);
     }
 }
 /** Fetch a URL and return true if the response is OK, false on any failure. */

package/dist/commands/per-harness.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Per-harness orchestration types + the exit-code classifier.
+ *
+ * Lives in its own module so both `runSetup` (which produces these) and
+ * `printSetupSummary` (which renders them) can import without circular
+ * dependency. The classifier is testable in isolation — every row of the
+ * spec §7.5 4-tier table is one test.
+ */
+import type { HarnessProfile } from "../harnesses/index.js";
+import type { PartialStep } from "../lib/manifest.js";
+import type { AgentsResult } from "../steps/agents.js";
+import type { CommandsResult } from "../steps/commands.js";
+import type { SkillsResult } from "../steps/skills.js";
+import type { MetricsResult } from "../steps/metrics.js";
+import type { McpResult } from "../steps/mcp.js";
+/**
+ * Per-harness outcome captured by the orchestrator loop.
+ *
+ * `status` semantics:
+ *   ok        — every per-harness step succeeded; the user's choice was
+ *               carried out and recorded in the manifest.
+ *   failed    — an OPERATIONAL error occurred (MCP write failed,
+ *               agents-step mkdir EACCES, etc.). Drives exit code 1.
+ *   declined  — the user actively rejected the conflict prompt. NOT an
+ *               error from the tool's perspective — it's a deliberate
+ *               choice. Drives exit code 0 (with a non-zero summary line
+ *               surfacing the count).
+ */
+export interface PerHarnessResult {
+    harnessName: string;
+    profile: HarnessProfile;
+    status: "ok" | "failed" | "declined";
+    error?: string;
+    mcpResult?: McpResult;
+    agentsResult?: AgentsResult;
+    commandsResult?: CommandsResult;
+    skillsResult?: SkillsResult;
+    metricsResult?: MetricsResult;
+    partial?: PartialStep | null;
+}
+/**
+ * Decide the process exit code from a set of per-harness results.
+ *
+ * Spec §7.5 4-tier table:
+ *
+ *   | Outcome                                              | Exit |
+ *   |------------------------------------------------------|------|
+ *   | Every harness ok                                     |  0   |
+ *   | Any harness failed (operational)                     |  1   |
+ *   | Any declined AND zero failed                         |  0   |
+ *   | Empty (user unchecked all, or no harnesses to run)   |  0   |
+ *
+ * Rationale: CI wrapping `--harness all` should not be poisoned by
+ * user-policy choices (declines, no-op outcomes) but MUST fail on
+ * operational errors (EACCES, ENOSPC, parse-error) so deploy pipelines
+ * can detect partial failure and re-run.
+ *
+ * `partial` is a property of a `failed` result (post-MCP-success step
+ * threw), not its own status — it's already covered by the failed
+ * branch. A successful run with file-level `failures[]` arrays is
+ * still `status: "ok"` (file failures are recoverable on re-run; the
+ * user has working state).
+ */
+export declare function classifyExit(results: PerHarnessResult[]): number;

package/dist/commands/per-harness.js

@@ -0,0 +1,37 @@
+/**
+ * Per-harness orchestration types + the exit-code classifier.
+ *
+ * Lives in its own module so both `runSetup` (which produces these) and
+ * `printSetupSummary` (which renders them) can import without circular
+ * dependency. The classifier is testable in isolation — every row of the
+ * spec §7.5 4-tier table is one test.
+ */
+/**
+ * Decide the process exit code from a set of per-harness results.
+ *
+ * Spec §7.5 4-tier table:
+ *
+ *   | Outcome                                              | Exit |
+ *   |------------------------------------------------------|------|
+ *   | Every harness ok                                     |  0   |
+ *   | Any harness failed (operational)                     |  1   |
+ *   | Any declined AND zero failed                         |  0   |
+ *   | Empty (user unchecked all, or no harnesses to run)   |  0   |
+ *
+ * Rationale: CI wrapping `--harness all` should not be poisoned by
+ * user-policy choices (declines, no-op outcomes) but MUST fail on
+ * operational errors (EACCES, ENOSPC, parse-error) so deploy pipelines
+ * can detect partial failure and re-run.
+ *
+ * `partial` is a property of a `failed` result (post-MCP-success step
+ * threw), not its own status — it's already covered by the failed
+ * branch. A successful run with file-level `failures[]` arrays is
+ * still `status: "ok"` (file failures are recoverable on re-run; the
+ * user has working state).
+ */
+export function classifyExit(results) {
+    if (results.length === 0)
+        return 0;
+    const anyFailed = results.some((r) => r.status === "failed");
+    return anyFailed ? 1 : 0;
+}

package/dist/commands/setup.d.ts

@@ -1,4 +1,5 @@
-export declare function runSetup(opts: {
+export type { PerHarnessResult } from "./per-harness.js";
+interface RunSetupOpts {
     apiKey?: string;
     signup: boolean;
     scope: "global" | "local";
@@ -7,9 +8,10 @@ export declare function runSetup(opts: {
     skipValidation: boolean;
     dryRun: boolean;
     yes: boolean;
-    harness: string;
+    harnesses: string[];
     withCli?: boolean;
     cli?: boolean;
     withAgentMetricsCli?: boolean;
     agentMetricsCli?: boolean;
-}): Promise<void>;
+}
+export declare function runSetup(opts: RunSetupOpts): Promise<void>;