@uluops/setup 0.2.0 → 0.6.0

package/dist/lib/paths.d.ts

@@ -2,12 +2,39 @@
 export declare const PACKAGE_ROOT: string;
 /** Assets directory containing pre-rendered .md files */
 export declare const ASSETS_DIR: string;
+export declare function setProjectRoot(path: string | null): void;
+/** Walk upward from cwd to find the nearest directory containing .git or package.json. Falls back to cwd. */
+export declare function findProjectRoot(): Promise<string>;
+/** Return the Claude config home directory (~/.claude by default, or CLAUDE_HOME env override). */
 export declare function getClaudeHome(): string;
+/** Return the path to Claude's global config file (~/.claude.json by default, or CLAUDE_JSON_PATH env override). */
 export declare function getClaudeJsonPath(): string;
-export declare function getLocalMcpPath(): string;
+/** Return the path to the project-local MCP config file (.mcp.json in project root). */
+export declare function getLocalMcpPath(): Promise<string>;
+/** Return the UluOps state directory (~/.uluops/). Harness-neutral. */
+export declare function getUluopsDir(): string;
+/** Return the path to the UluOps install manifest file (new location). */
 export declare function getManifestPath(): string;
-export declare function getAgentsDir(localDefs: boolean): string;
-export declare function getCommandsDir(localDefs: boolean): string;
+/** Return the legacy manifest path for migration. */
+export declare function getLegacyManifestPath(): string;
+/**
+ * Return the backup directory for a harness's **config** files.
+ *
+ * Scope is deliberately narrow: this directory holds copies of mutable
+ * user-owned config surfaces (the MCP config file, the shell profile),
+ * NOT vendor-owned tool files in `~/.claude/tools/agent-metrics/`. Tool
+ * files are treated as disposable — they can be regenerated by re-running
+ * setup, and the source of truth lives in the npm-installed
+ * `@uluops/agent-metrics` package. Backing them up would require a
+ * different ritual (versioned snapshots tied to the manifest's
+ * hooksInstalledVersion) and is not provided here.
+ *
+ * Renaming this to `getConfigBackupDir` would be more honest but is a
+ * public surface change deferred until we have a tool-file backup to
+ * disambiguate against.
+ */
+export declare function getBackupDir(harnessName: string): string;
+/** Detect the user's shell and return its name and profile path, or null if unsupported. */
 export declare function getShellProfile(): {
     shell: string;
     path: string;

package/dist/lib/paths.js

@@ -1,33 +1,119 @@
 import { homedir, platform } from "node:os";
-import { join, dirname } from "node:path";
+import { join, dirname, isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
+import { access } from "node:fs/promises";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Root of the npm package (where assets/ lives) */
 export const PACKAGE_ROOT = join(__dirname, "..", "..");
 /** Assets directory containing pre-rendered .md files */
 export const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
+/** Explicit project root override via --project-root flag or env var. */
+let projectRootOverride = null;
+export function setProjectRoot(path) {
+    projectRootOverride = path;
+}
+/** Walk upward from cwd to find the nearest directory containing .git or package.json. Falls back to cwd. */
+export async function findProjectRoot() {
+    if (projectRootOverride)
+        return projectRootOverride;
+    const envRoot = process.env["ULUOPS_PROJECT_ROOT"];
+    if (envRoot) {
+        if (!isAbsolute(envRoot)) {
+            throw new Error(`ULUOPS_PROJECT_ROOT must be an absolute path, got: ${envRoot}`);
+        }
+        if (envRoot.includes("..")) {
+            throw new Error(`ULUOPS_PROJECT_ROOT must not contain traversal sequences: ${envRoot}`);
+        }
+        return envRoot;
+    }
+    let dir = process.cwd();
+    const root = dirname(dir);
+    while (dir !== root) {
+        if (await isProjectMarker(dir))
+            return dir;
+        dir = dirname(dir);
+    }
+    if (await isProjectMarker(dir))
+        return dir;
+    return process.cwd();
+}
+async function isProjectMarker(dir) {
+    try {
+        await access(join(dir, ".git"));
+        return true;
+    }
+    catch {
+        // continue
+    }
+    try {
+        await access(join(dir, "package.json"));
+        return true;
+    }
+    catch {
+        // continue
+    }
+    return false;
+}
+/** Validate an env-var-supplied path: must be absolute and contain no traversal sequences. */
+function validateEnvPath(value, varName) {
+    if (!isAbsolute(value)) {
+        throw new Error(`${varName} must be an absolute path, got: ${value}`);
+    }
+    if (value.includes("..")) {
+        throw new Error(`${varName} must not contain traversal sequences: ${value}`);
+    }
+    return value;
+}
+/** Return the Claude config home directory (~/.claude by default, or CLAUDE_HOME env override). */
 export function getClaudeHome() {
+    const envHome = process.env["CLAUDE_HOME"];
+    if (envHome)
+        return validateEnvPath(envHome, "CLAUDE_HOME");
     return join(homedir(), ".claude");
 }
+/** Return the path to Claude's global config file (~/.claude.json by default, or CLAUDE_JSON_PATH env override). */
 export function getClaudeJsonPath() {
+    const envPath = process.env["CLAUDE_JSON_PATH"];
+    if (envPath)
+        return validateEnvPath(envPath, "CLAUDE_JSON_PATH");
     return join(homedir(), ".claude.json");
 }
-export function getLocalMcpPath() {
-    return join(process.cwd(), ".mcp.json");
+/** Return the path to the project-local MCP config file (.mcp.json in project root). */
+export async function getLocalMcpPath() {
+    return join(await findProjectRoot(), ".mcp.json");
 }
+/** Return the UluOps state directory (~/.uluops/). Harness-neutral. */
+export function getUluopsDir() {
+    return join(homedir(), ".uluops");
+}
+/** Return the path to the UluOps install manifest file (new location). */
 export function getManifestPath() {
-    return join(getClaudeHome(), "uluops-manifest.json");
+    return join(getUluopsDir(), "manifest.json");
 }
-export function getAgentsDir(localDefs) {
-    if (localDefs)
-        return join(process.cwd(), "uluops", "agents");
-    return join(getClaudeHome(), "agents");
+/** Return the legacy manifest path for migration. */
+export function getLegacyManifestPath() {
+    return join(getClaudeHome(), "uluops-manifest.json");
 }
-export function getCommandsDir(localDefs) {
-    if (localDefs)
-        return join(process.cwd(), "uluops", "commands");
-    return join(getClaudeHome(), "commands");
+/**
+ * Return the backup directory for a harness's **config** files.
+ *
+ * Scope is deliberately narrow: this directory holds copies of mutable
+ * user-owned config surfaces (the MCP config file, the shell profile),
+ * NOT vendor-owned tool files in `~/.claude/tools/agent-metrics/`. Tool
+ * files are treated as disposable — they can be regenerated by re-running
+ * setup, and the source of truth lives in the npm-installed
+ * `@uluops/agent-metrics` package. Backing them up would require a
+ * different ritual (versioned snapshots tied to the manifest's
+ * hooksInstalledVersion) and is not provided here.
+ *
+ * Renaming this to `getConfigBackupDir` would be more honest but is a
+ * public surface change deferred until we have a tool-file backup to
+ * disambiguate against.
+ */
+export function getBackupDir(harnessName) {
+    return join(getUluopsDir(), "backups", harnessName);
 }
+/** Detect the user's shell and return its name and profile path, or null if unsupported. */
 export function getShellProfile() {
     const shell = process.env["SHELL"] ?? "";
     const home = homedir();

package/dist/lib/settings-merger.d.ts

@@ -13,31 +13,54 @@ interface HookMatcher {
     matcher?: string;
     hooks: HookEntry[];
 }
-interface ClaudeSettings {
+export interface HarnessSettings {
     permissions?: Record<string, unknown>;
     hooks?: Record<string, HookMatcher[]>;
     [key: string]: unknown;
 }
+/**
+ * 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 declare const CLAUDE_HOOK_TYPES: Set<string>;
+/** Default Claude Code hook event used when no override is configured. */
+export declare const DEFAULT_CLAUDE_HOOK_TYPE = "SubagentStop";
+export interface HookProbeResult {
+    hookType: string;
+    supported: boolean;
+    warning?: string;
+}
+/** Check whether the configured hook event type is in the known supported set. Returns the resolved hook type and a warning if unsupported. */
+export declare function probeHookSupport(hookTypeOverride?: string): HookProbeResult;
 /**
  * Read an existing settings.json, or return empty object if it doesn't exist.
+ * Throws on malformed JSON to prevent silent data loss during merge+write.
  */
-export declare function readSettings(path: string): Promise<ClaudeSettings>;
+export declare function readSettings(path: string): Promise<HarnessSettings>;
 /**
  * Write settings back to file with stable formatting.
  */
-export declare function writeSettings(path: string, settings: ClaudeSettings): Promise<void>;
+export declare function writeSettings(path: string, settings: HarnessSettings): Promise<void>;
 /**
- * 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 declare function mergeUluopsHook(settings: ClaudeSettings, hookCommand: string): ClaudeSettings;
+export declare function mergeUluopsHook(settings: HarnessSettings, hookCommand: string, hookTypeOverride?: string, matcher?: string): HarnessSettings;
 /**
- * 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 declare function removeUluopsHook(settings: ClaudeSettings): ClaudeSettings;
+export declare function removeUluopsHook(settings: HarnessSettings, hookTypeOverride?: string): HarnessSettings;
 /**
  * Check if a UluOps hook is configured in settings.
  */
-export declare function hasUluopsHook(settings: ClaudeSettings): boolean;
+export declare function hasUluopsHook(settings: HarnessSettings, hookTypeOverride?: string): boolean;
 export {};

package/dist/lib/settings-merger.js

@@ -4,37 +4,95 @@
  * Safe read/merge/remove for Claude Code's settings.json.
  * Only touches UluOps-managed hook entries — all other settings preserved.
  */
-import { readFile, writeFile } from "node:fs/promises";
-/** Marker embedded in hook commands to identify UluOps-managed entries */
-const ULUOPS_HOOK_MARKER = "tools/agent-metrics";
+import { readFile } from "node:fs/promises";
+import { atomicWrite } from "./atomic-write.js";
+/**
+ * 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 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(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 {${[...CLAUDE_HOOK_TYPES].join(", ")}, AfterTool}. Metrics may silently fail if this hook type does not exist in the harness.`,
+    };
+}
 /**
  * Read an existing settings.json, or return empty object if it doesn't exist.
+ * Throws on malformed JSON to prevent silent data loss during merge+write.
  */
 export async function readSettings(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch {
+        return {}; // File doesn't exist — fresh config
+    }
     try {
-        const raw = await readFile(path, "utf-8");
         return JSON.parse(raw);
     }
     catch {
-        return {};
+        throw new Error(`Failed to parse settings at ${path} — file contains invalid JSON`);
     }
 }
 /**
  * Write settings back to file with stable formatting.
  */
 export async function writeSettings(path, settings) {
-    await writeFile(path, JSON.stringify(settings, null, 2) + "\n");
+    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) {
+export function mergeUluopsHook(settings, hookCommand, hookTypeOverride, matcher) {
+    const hookType = hookTypeOverride ?? getDefaultHookEventType();
     const hooks = settings.hooks ?? {};
-    const existing = hooks["SubagentStop"] ?? [];
-    // Remove any existing UluOps hook entries
-    const filtered = existing.filter((m) => !m.hooks.some((h) => h.command.includes(ULUOPS_HOOK_MARKER)));
-    // Add the new UluOps hook
+    const existing = hooks[hookType] ?? [];
+    const filtered = existing.filter((m) => !m.hooks.some((h) => h.command.includes(HOOK_OWNERSHIP_SIGNATURE)));
     const uluopsHook = {
         hooks: [
             {
@@ -44,32 +102,36 @@ export function mergeUluopsHook(settings, hookCommand) {
             },
         ],
     };
+    if (matcher) {
+        uluopsHook.matcher = matcher;
+    }
     return {
         ...settings,
         hooks: {
             ...hooks,
-            SubagentStop: [...filtered, uluopsHook],
+            [hookType]: [...filtered, uluopsHook],
         },
     };
 }
 /**
- * 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) {
+export function removeUluopsHook(settings, hookTypeOverride) {
+    const hookType = hookTypeOverride ?? getDefaultHookEventType();
     const hooks = settings.hooks;
     if (!hooks)
         return settings;
-    const subagentStop = hooks["SubagentStop"];
-    if (!subagentStop)
+    const hookEntries = hooks[hookType];
+    if (!hookEntries)
         return settings;
-    const filtered = subagentStop.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["SubagentStop"];
+        delete updatedHooks[hookType];
     }
     else {
-        updatedHooks["SubagentStop"] = filtered;
+        updatedHooks[hookType] = filtered;
     }
     const result = { ...settings };
     if (Object.keys(updatedHooks).length === 0) {
@@ -83,9 +145,10 @@ export function removeUluopsHook(settings) {
 /**
  * Check if a UluOps hook is configured in settings.
  */
-export function hasUluopsHook(settings) {
-    const subagentStop = settings.hooks?.["SubagentStop"];
-    if (!subagentStop)
+export function hasUluopsHook(settings, hookTypeOverride) {
+    const hookType = hookTypeOverride ?? getDefaultHookEventType();
+    const hookEntries = settings.hooks?.[hookType];
+    if (!hookEntries)
         return false;
-    return subagentStop.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

@@ -1,8 +1,11 @@
+import type { HarnessProfile } from "../harnesses/index.js";
 export interface AgentsResult {
     copied: number;
     skipped: number;
     removed: number;
     files: string[];
 }
-export declare function installAgents(localDefs: boolean, dryRun: boolean, existingManifestAgents?: string[]): Promise<AgentsResult>;
+/** 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,14 +1,53 @@
+import { readdir, mkdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
-import { ASSETS_DIR, getAgentsDir } from "../lib/paths.js";
-import { syncAssets, unlinkFiles } from "../lib/file-ops.js";
-export async function installAgents(localDefs, dryRun, existingManifestAgents) {
-    return syncAssets({
-        srcDir: join(ASSETS_DIR, "agents"),
-        destDir: getAgentsDir(localDefs),
-        dryRun,
-        oldManifestFiles: existingManifestAgents,
-    });
+import { ASSETS_DIR, findProjectRoot } from "../lib/paths.js";
+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 ext = profile.agentExtension;
+    let files;
+    try {
+        files = (await readdir(srcDir)).filter((f) => f.endsWith(ext));
+    }
+    catch {
+        return { copied: 0, skipped: 0, removed: 0, files: [] };
+    }
+    let copied = 0;
+    let skipped = 0;
+    for (const file of files) {
+        const result = await copyIfChanged(join(srcDir, file), join(destDir, file), dryRun);
+        if (result === "copied")
+            copied++;
+        else
+            skipped++;
+    }
+    // Remove files that were in the old manifest but no longer in the package
+    let removed = 0;
+    if (existingManifestAgents) {
+        for (const oldFile of existingManifestAgents) {
+            if (!files.includes(oldFile)) {
+                if (!dryRun) {
+                    try {
+                        await unlink(join(destDir, oldFile));
+                    }
+                    catch {
+                        // Already gone
+                    }
+                }
+                removed++;
+            }
+        }
+    }
+    return { copied, skipped, removed, files };
 }
+/** Remove previously installed agent files by name. */
 export async function uninstallAgents(files, defsPath) {
     return unlinkFiles(join(defsPath, "agents"), files);
 }

package/dist/steps/auth.js

@@ -1,6 +1,9 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
+function getKeyPrefix() {
+    return process.env["ULUOPS_KEY_PREFIX"] ?? "ulr_";
+}
 /**
  * Resolve API key from flags, env, credentials file, or interactive prompt.
  */
@@ -20,20 +23,22 @@ export async function resolveApiKey(options) {
         if (!options.interactive) {
             throw new Error("No API key found. Pass --api-key or set ULUOPS_API_KEY. Get one at app.uluops.ai/settings/api-keys");
         }
+        const prefix = getKeyPrefix();
         const { input } = await import("@inquirer/prompts");
         apiKey = await input({
             message: "Enter your UluOps API key",
             validate: (val) => {
                 if (!val.trim())
                     return "Get a key at app.uluops.ai/settings/api-keys";
-                if (!val.startsWith("ulr_"))
-                    return "API keys start with ulr_ — get one at app.uluops.ai/settings/api-keys";
+                if (!val.startsWith(prefix))
+                    return `API keys typically start with ${prefix} — if your key has a different format, just paste it and server validation will check it`;
                 return true;
             },
         });
     }
-    if (!apiKey?.startsWith("ulr_")) {
-        throw new Error("API keys start with ulr_ — get one at app.uluops.ai/settings/api-keys");
+    const prefix = getKeyPrefix();
+    if (!apiKey.startsWith(prefix) && !options.skipValidation) {
+        process.stderr.write(`  ⚠ Key does not start with expected prefix "${prefix}" — proceeding with server validation\n`);
     }
     // Validate against server
     if (!options.skipValidation) {
@@ -43,22 +48,33 @@ export async function resolveApiKey(options) {
     return { apiKey, email: null };
 }
 async function readCredentialsFile() {
+    const credsPath = join(homedir(), ".uluops", "credentials.json");
+    let raw;
     try {
-        const credsPath = join(homedir(), ".uluops", "credentials.json");
-        const raw = await readFile(credsPath, "utf-8");
-        const creds = JSON.parse(raw);
-        const defaultProfile = creds["default"];
-        return defaultProfile?.apiKey ?? defaultProfile?.api_key;
+        raw = await readFile(credsPath, "utf-8");
     }
     catch {
-        return undefined;
+        return undefined; // File doesn't exist
+    }
+    let creds;
+    try {
+        creds = JSON.parse(raw);
     }
+    catch (err) {
+        throw new Error(`Malformed credentials file at ${credsPath}: ${err instanceof Error ? err.message : "invalid JSON"}`);
+    }
+    if (typeof creds !== "object" || creds === null)
+        return undefined;
+    const profiles = creds;
+    const defaultProfile = profiles["default"];
+    return defaultProfile?.apiKey ?? defaultProfile?.api_key;
 }
 async function validateKey(apiKey) {
     const url = "https://api.uluops.ai/api/v1/registry/users/me";
     try {
         const res = await fetch(url, {
             headers: { Authorization: `Bearer ${apiKey}` },
+            signal: AbortSignal.timeout(15000),
         });
         if (res.status === 401) {
             throw new Error("Invalid API key — generate a new one at app.uluops.ai/settings/api-keys");

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>;