@uluops/setup 0.11.0 → 0.12.0

package/dist/steps/metrics.js

@@ -5,6 +5,8 @@
  * Only active for harnesses that support hooks (currently Claude Code only).
  */
 import { mkdir, readdir, copyFile, rm, access, readFile } from "node:fs/promises";
+import { isEnoent } from "../lib/file-ops.js";
+import { warn } from "../lib/display.js";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 /** Where agent-metrics dist files are installed (derived from profile) */
@@ -84,8 +86,12 @@ async function copyJsDir(srcDir, destDir, dryRun) {
             count++;
         }
     }
-    catch {
-        // Directory doesn't exist — not critical
+    catch (err) {
+        // ENOENT = optional subdir absent. Anything else throws — swallowing it
+        // after the destructive rm below turns a read failure into a destroyed
+        // previously-working install reporting 0 files with no error.
+        if (!isEnoent(err))
+            throw err;
     }
     return count;
 }
@@ -99,6 +105,28 @@ async function copyToolFiles(srcRoot, destRoot, dryRun) {
     // disk and shadow the new one. Wipe dist/ before repopulating so the
     // installed tree matches the source tree exactly.
     if (!dryRun) {
+        // Verify the SOURCE is readable BEFORE the destructive wipe — an
+        // unreadable source after the rm leaves a destroyed install. A missing
+        // source dist (ENOENT) skips the whole copy without wiping. Subdirs are
+        // probed too: a readable top level with an EACCES subdir would otherwise
+        // throw with the installed tree already gone.
+        try {
+            await readdir(srcDist);
+            for (const sub of subDirs) {
+                try {
+                    await readdir(join(srcDist, sub));
+                }
+                catch (subErr) {
+                    if (!isEnoent(subErr))
+                        throw subErr; // absent subdir is fine
+                }
+            }
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return 0;
+            throw err;
+        }
         await rm(destDist, { recursive: true, force: true });
         await mkdir(destDist, { recursive: true });
         for (const sub of subDirs) {
@@ -116,8 +144,11 @@ async function copyToolFiles(srcRoot, destRoot, dryRun) {
         }
         filesCopied++;
     }
-    catch {
-        // Not critical
+    catch (err) {
+        // Non-fatal, but not silent: this file is what
+        // readInstalledMetricsVersion reads — a silent miss surfaces later as
+        // "version unknown" / spurious drift in verify.
+        warn(`Could not copy agent-metrics package.json: ${err instanceof Error ? err.message : String(err)} — installed-version detection will be degraded`);
     }
     return filesCopied;
 }
@@ -137,6 +168,12 @@ export async function installMetrics(profile, dryRun) {
     const toolDir = profile.paths.toolsDir;
     const settingsPath = profile.paths.settingsPath;
     const source = await findMetricsSource();
+    if (!source) {
+        // Unresolvable source is a DEGRADED state, not a silent no-op: a prior
+        // install's hook.js may keep hookConfigured true below while the files
+        // go stale. Say so.
+        warn("@uluops/agent-metrics could not be resolved — tool files not refreshed (a previously installed hook, if any, keeps running its old version)");
+    }
     let toolFilesCopied = 0;
     if (source) {
         if (!dryRun) {
@@ -155,6 +192,29 @@ export async function installMetrics(profile, dryRun) {
     else if (hookJsExists && dryRun) {
         hookConfigured = true;
     }
+    else {
+        // hook.js absent: the SETTINGS entry may still exist (externally
+        // cleared tool dir) — recording false from disk-existence alone would
+        // falsify a live hook. Ask the settings file, which is the authority
+        // verify already consults.
+        try {
+            hookConfigured = await profile.hooks.check(settingsPath);
+        }
+        catch (err) {
+            // Unreadable settings = hook state UNKNOWN, not false. Recording an
+            // observed false here would make uninstall skip hook removal over a
+            // possibly-live hook — return unobserved so the manifest keeps its
+            // prior record (the metricsObserved gate exists for exactly this).
+            warn(`Could not read ${settingsPath} (${err instanceof Error ? err.message : String(err)}) — hook state unknown; keeping the previously recorded value`);
+            const hooksInstalledVersionUnknown = source?.version ?? (await readInstalledMetricsVersion(toolDir));
+            return {
+                toolFilesCopied,
+                hookConfigured: false,
+                hooksInstalledVersion: hooksInstalledVersionUnknown,
+                skippedReason: "hook-state-unknown",
+            };
+        }
+    }
     // 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
@@ -170,14 +230,24 @@ export async function uninstallMetrics(profile, dryRun) {
         return;
     }
     if (!dryRun) {
-        await profile.hooks.remove(profile.paths.settingsPath, false);
+        try {
+            await profile.hooks.remove(profile.paths.settingsPath, false);
+        }
+        catch (err) {
+            // A malformed settings file must not abort the rest of uninstall —
+            // mirror the try/catch the MCP-removal path already has.
+            warn(`Could not remove metrics hook from ${profile.paths.settingsPath}: ${err instanceof Error ? err.message : String(err)}`);
+        }
     }
     if (!dryRun) {
         try {
             await rm(profile.paths.toolsDir, { recursive: true, force: true });
         }
-        catch {
-            // Already gone
+        catch (err) {
+            // force:true already tolerates ENOENT, so anything landing here is a
+            // REAL failure (EACCES/EBUSY) — name it, matching the hook-removal
+            // catch above.
+            warn(`Could not remove tool files at ${profile.paths.toolsDir}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }

package/dist/steps/shell.d.ts

@@ -1,4 +1,7 @@
 /** 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>;
+export declare function removeShellExport(profilePath: string): Promise<{
+    removed: boolean;
+    reason?: string;
+}>;

package/dist/steps/shell.js

@@ -1,5 +1,7 @@
-import { readFile } from "node:fs/promises";
+import { readFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
 import { atomicWrite } from "../lib/atomic-write.js";
+import { isEnoent } from "../lib/file-ops.js";
 const FENCE_START = "# --- UluOps (managed by @uluops/setup) ---";
 const FENCE_END = "# --- /UluOps ---";
 /** Characters safe for shell variable values (no metacharacters). */
@@ -9,13 +11,28 @@ 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}`;
+    // Fish has no `export` builtin — bash syntax in config.fish prints a
+    // parse error on EVERY new shell and never sets the variable (silent auth
+    // failure + visible breakage). Dialect follows the profile path.
+    const isFish = profilePath.endsWith("config.fish");
+    const exportLine = isFish
+        ? `set -gx ULUOPS_API_KEY "${apiKey}"`
+        : `export ULUOPS_API_KEY="${apiKey}"`;
+    const block = `${FENCE_START}\n${exportLine}\n${FENCE_END}`;
     let content;
     try {
         content = await readFile(profilePath, "utf-8");
     }
-    catch {
+    catch (err) {
+        if (!isEnoent(err)) {
+            // An unreadable-but-present shell profile must never be treated as
+            // absent — the fresh-file write below would replace the user's rc.
+            throw new Error(`Could not read ${profilePath} (${err instanceof Error ? err.message : String(err)}) — refusing to write the API-key export over a file that exists but could not be read. Nothing was modified.`);
+        }
         if (!dryRun) {
+            // A fresh fish user may have no ~/.config/fish/ yet — atomicWrite's
+            // 'wx' temp open ENOENTs on a missing parent.
+            await mkdir(dirname(profilePath), { recursive: true });
             await atomicWrite(profilePath, block + "\n", { mode: 0o600 });
         }
         return;
@@ -43,14 +60,35 @@ export async function removeShellExport(profilePath) {
     try {
         content = await readFile(profilePath, "utf-8");
     }
-    catch {
-        return;
+    catch (err) {
+        if (isEnoent(err)) {
+            return { removed: true, reason: "no profile file" }; // nothing to remove
+        }
+        // Unreadable-but-present: the export (and the plaintext key in it) may
+        // still be there — the caller must NOT print success.
+        return {
+            removed: false,
+            reason: `could not read ${profilePath}: ${err instanceof Error ? err.message : String(err)}`,
+        };
     }
     const startIdx = content.indexOf(FENCE_START);
     const endIdx = content.lastIndexOf(FENCE_END);
     if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
         const before = content.slice(0, startIdx);
         const after = content.slice(endIdx + FENCE_END.length);
-        await atomicWrite(profilePath, (before + after).replace(/\n{3,}/g, "\n\n"), { mode: 0o600 });
+        try {
+            await atomicWrite(profilePath, (before + after).replace(/\n{3,}/g, "\n\n"), { mode: 0o600 });
+        }
+        catch (err) {
+            // A write failure must land in the same result shape as a read
+            // failure — throwing here escapes past the caller's plaintext-key
+            // warning and aborts the rest of uninstall.
+            return {
+                removed: false,
+                reason: `could not rewrite ${profilePath}: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        return { removed: true };
     }
+    return { removed: true, reason: "no export block present" };
 }

package/dist/steps/signup.d.ts

@@ -10,6 +10,10 @@ declare function getPasswordHint(password: string): string | null;
 /**
  * Inquirer validate wrapper. Always returns true (hints are non-blocking)
  * and emits the pure-computed hint via console.warn for display.
+ *
+ * console.warn (stderr) is DELIBERATE, not a display.ts bypass: this fires
+ * mid-inquirer-prompt, and display's console.log helpers write to stdout —
+ * the stream inquirer is actively repainting. stderr interleaves cleanly.
  * @internal Exported for testing only — not part of the public API.
  */
 declare function hintPassword(password: string): true;

package/dist/steps/signup.js

@@ -22,6 +22,10 @@ function getPasswordHint(password) {
 /**
  * Inquirer validate wrapper. Always returns true (hints are non-blocking)
  * and emits the pure-computed hint via console.warn for display.
+ *
+ * console.warn (stderr) is DELIBERATE, not a display.ts bypass: this fires
+ * mid-inquirer-prompt, and display's console.log helpers write to stdout —
+ * the stream inquirer is actively repainting. stderr interleaves cleanly.
  * @internal Exported for testing only — not part of the public API.
  */
 function hintPassword(password) {
@@ -89,13 +93,25 @@ async function callApi(url, method, body, bearerToken, validate) {
         });
     }
     catch (err) {
-        if (err instanceof TypeError) {
+        // TypeError = network failure; TimeoutError = AbortSignal.timeout — both
+        // deserve the friendly message, not a raw DOMException.
+        if (err instanceof TypeError || err?.name === "TimeoutError") {
             throw new Error("Can't reach api.uluops.ai — check your connection.");
         }
         throw err;
     }
     if (res.ok) {
-        const body = await res.json();
+        // A 200 with a non-JSON body (proxy, captive portal) must not surface as
+        // a raw SyntaxError — mirror auth.ts's guarded decode. Worst case here is
+        // register: the account may exist server-side while the user sees a
+        // parse error, so the message must say what to do next.
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            throw new Error("API returned a non-JSON response. If this was a signup, the account may already exist — re-run and choose 'existing API key', or check app.uluops.ai.");
+        }
         if (typeof body !== "object" || body === null) {
             throw new Error("Unexpected API response shape");
         }

package/dist/steps/skills.d.ts

@@ -10,5 +10,16 @@ export interface SkillsResult {
         error: string;
     }[];
 }
+/**
+ * Install the harness's skill files from the bundled assets: unchanged files
+ * are skipped (hash comparison), updated files overwritten, and manifest
+ * entries no longer in the assets removed. `localDefs` redirects the install
+ * to `./uluops/skills` (project-scoped). Per-file failures are collected in
+ * the result, not thrown.
+ */
 export declare function installSkills(profile: HarnessProfile, localDefs: boolean, dryRun: boolean, existingManifestSkills?: string[]): Promise<SkillsResult>;
+/**
+ * Remove the manifest-listed skill files under `defsPath/skills`, then prune
+ * any directories left empty. Returns the number of files removed.
+ */
 export declare function uninstallSkills(files: string[], defsPath: string): Promise<number>;

package/dist/steps/skills.js

@@ -1,13 +1,18 @@
 import { mkdir, readdir, rmdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { ASSETS_DIR, findProjectRoot } from "../lib/paths.js";
-import { copyIfChanged, removeStaleFiles, unlinkFiles } from "../lib/file-ops.js";
+import { copyIfChanged, removeStaleFiles, unlinkFiles, isEnoent } from "../lib/file-ops.js";
 async function listFilesRecursive(dir, prefix = "") {
     let entries;
     try {
         entries = await readdir(dir, { withFileTypes: true });
     }
-    catch {
+    catch (err) {
+        // ENOENT = no skills shipped/installed at this level. Anything else
+        // throws — an empty list here becomes the manifest's authoritative
+        // skills record.
+        if (!isEnoent(err))
+            throw err;
         return [];
     }
     const files = [];
@@ -23,6 +28,13 @@ async function listFilesRecursive(dir, prefix = "") {
     }
     return files.sort((a, b) => a.localeCompare(b));
 }
+/**
+ * Install the harness's skill files from the bundled assets: unchanged files
+ * are skipped (hash comparison), updated files overwritten, and manifest
+ * entries no longer in the assets removed. `localDefs` redirects the install
+ * to `./uluops/skills` (project-scoped). Per-file failures are collected in
+ * the result, not thrown.
+ */
 export async function installSkills(profile, localDefs, dryRun, existingManifestSkills) {
     const srcBase = join(ASSETS_DIR, profile.name, "skills");
     const destBase = localDefs
@@ -74,21 +86,38 @@ export async function installSkills(profile, localDefs, dryRun, existingManifest
             });
         }
     }
-    const removed = await removeStaleFiles(destBase, existingManifestSkills, installedFiles, dryRun);
-    return { copied, skipped, removed, files: installedFiles, failures };
+    // See agents.ts: stale = no-longer-shipped, reconciled against SOURCE.
+    const removed = await removeStaleFiles(destBase, existingManifestSkills, files, dryRun);
+    const recordedSkillFiles = [
+        ...installedFiles,
+        ...failures
+            .map((f) => f.file)
+            .filter((f) => existingManifestSkills?.includes(f) ?? false),
+    ];
+    return { copied, skipped, removed, files: recordedSkillFiles, failures };
 }
+/**
+ * Remove the manifest-listed skill files under `defsPath/skills`, then prune
+ * any directories left empty. Returns the number of files removed.
+ */
 export async function uninstallSkills(files, defsPath) {
     const skillsDir = join(defsPath, "skills");
     const removed = await unlinkFiles(skillsDir, files);
     const skillDirs = new Set(files
+        .filter((file) => file.includes("/")) // top-level assets have no dir to prune
         .map((file) => file.split("/")[0])
         .filter((dir) => typeof dir === "string" && dir.length > 0));
     for (const dir of skillDirs) {
         try {
             await rmdir(join(skillsDir, dir));
         }
-        catch {
-            // Already gone or non-empty due to user files.
+        catch (err) {
+            const code = err?.code;
+            if (code !== "ENOENT" && code !== "ENOTEMPTY") {
+                // ENOENT (already gone) and ENOTEMPTY (user files present) are the
+                // expected outcomes; anything else is a real cleanup failure.
+                console.warn(`  ⚠ Could not remove skill dir ${join(skillsDir, dir)}: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     return removed;

package/dist/steps/username.js

@@ -49,13 +49,21 @@ export async function setUsername(apiKey, username) {
         });
     }
     catch (err) {
-        if (err instanceof TypeError) {
+        if (err instanceof TypeError || err?.name === "TimeoutError") {
             throw new Error("Can't reach api.uluops.ai — check your connection.");
         }
         throw err;
     }
     if (res.ok) {
-        const body = await res.json();
+        // Guarded decode — a 200 with a non-JSON body must not throw a raw
+        // SyntaxError (mirrors auth.ts / signup.ts).
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            throw new Error("API returned a non-JSON response — try again, or set the username later at app.uluops.ai.");
+        }
         if (typeof body !== "object" || body === null) {
             throw new Error("Unexpected API response shape");
         }

package/dist/steps/verify.js

@@ -5,6 +5,7 @@ import { getHealthTimeout } from "../lib/health.js";
 import { getProfile } from "../harnesses/index.js";
 import { readInstalledMetricsVersion } from "./metrics.js";
 import { extractEmail } from "../lib/json-guards.js";
+import { checkMcpPackageAvailability } from "../lib/config-merger.js";
 /**
  * Readiness probe: did the harness pick up the config after install?
  * The proxy signal is `configFile.mtimeMs > installedAt + 100ms` — a config
@@ -132,7 +133,20 @@ async function checkHooks(profile, hm, checks) {
     if (!hm.hooksInstalled || !profile.hooks || !profile.paths.settingsPath) {
         return true;
     }
-    const hookPresent = await profile.hooks.check(profile.paths.settingsPath);
+    // A malformed settings file must read as a failed check with the parse
+    // error as detail, not crash the whole verify run.
+    let hookPresent;
+    try {
+        hookPresent = await profile.hooks.check(profile.paths.settingsPath);
+    }
+    catch (err) {
+        checks.push({
+            label: `[${profile.displayName}] Agent metrics hook`,
+            passed: false,
+            detail: err instanceof Error ? err.message : String(err),
+        });
+        return false;
+    }
     let hookFilePresent = false;
     if (profile.paths.toolsDir) {
         try {
@@ -255,6 +269,9 @@ export async function verify() {
                 // object at all (surfaced below as a check failure) and returns null
                 // when data/email are absent or wrong-typed.
                 let email;
+                // No early return on a bad body: failing this check must not
+                // suppress the unrelated npm-resolvability check below.
+                let emailDecodeFailed = false;
                 try {
                     email = extractEmail(await res.json());
                 }
@@ -265,12 +282,15 @@ export async function verify() {
                         detail: err instanceof Error ? err.message : "Unexpected response shape",
                     });
                     allOk = false;
-                    return { ok: allOk, checks };
+                    emailDecodeFailed = true;
+                    email = null;
+                }
+                if (!emailDecodeFailed) {
+                    checks.push({
+                        label: `API key valid${email ? ` (user: ${email})` : ""}`,
+                        passed: true,
+                    });
                 }
-                checks.push({
-                    label: `API key valid${email ? ` (user: ${email})` : ""}`,
-                    passed: true,
-                });
             }
             else {
                 checks.push({
@@ -290,5 +310,34 @@ export async function verify() {
             allOk = false;
         }
     }
+    // MCP client packages resolvable on npm. The install-time probe warns and
+    // moves on (non-blocking by design) — this is where that warning stops
+    // being detached from runtime reality: the harness runs `npx -y <spec>` at
+    // startup, so an unresolvable package means MCP servers silently fail to
+    // start long after setup reported success. --verify re-asks the question
+    // on demand.
+    try {
+        const { missing } = await checkMcpPackageAvailability();
+        if (missing.length === 0) {
+            checks.push({ label: "MCP packages resolvable on npm", passed: true });
+        }
+        else {
+            checks.push({
+                label: "MCP packages resolvable on npm",
+                passed: false,
+                detail: `not found in registry: ${missing.join(", ")} — MCP servers will fail to start`,
+            });
+            allOk = false;
+        }
+    }
+    catch {
+        checks.push({
+            label: "MCP packages resolvable on npm",
+            passed: false,
+            detail: "npm registry unreachable — could not verify",
+        });
+        // Network-down is already reflected by the connectivity checks; do not
+        // double-fail the run for the same outage.
+    }
     return { ok: allOk, checks };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uluops/setup",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Zero-friction installer for UluOps agentic harnesses",
   "license": "MIT",
   "repository": {
@@ -24,6 +24,7 @@
     "uluops-setup": "./dist/cli.js"
   },
   "files": [
+    "CHANGELOG.md",
     "dist/cli.js",
     "dist/cli.d.ts",
     "dist/cli/**",
@@ -37,7 +38,9 @@
     "node": ">=20.0.0"
   },
   "scripts": {
+    "prebuild": "rm -rf dist",
     "build": "tsc -p tsconfig.build.json",
+    "postbuild": "chmod +x dist/cli.js",
     "dev": "tsx src/cli.ts",
     "typecheck": "tsc -p tsconfig.build.json --noEmit && tsc -p tsconfig.test.json --noEmit",
     "test": "vitest run",
@@ -45,7 +48,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@inquirer/prompts": "8.5.2",
+    "@inquirer/prompts": "8.6.0",
     "@uluops/agent-metrics": "0.8.0",
     "chalk": "5.6.2",
     "commander": "15.0.0",
@@ -53,8 +56,8 @@
   },
   "devDependencies": {
     "@types/node": "25.9.3",
-    "tsx": "4.22.4",
+    "tsx": "4.23.12",
     "typescript": "6.0.3",
-    "vitest": "4.1.9"
+    "vitest": "4.1.11"
   }
 }

package/dist/lib/agent-transform.d.ts

@@ -1,12 +0,0 @@
-/**
- * Agent Transform
- *
- * Transforms Claude Code agent markdown to other harness formats at install time.
- * Single source of truth: assets/agents/ contains Claude Code format only.
- * Each harness gets its frontmatter rewritten; the body is identical across all targets.
- */
-/**
- * Transform a Claude Code agent markdown file to a target harness format.
- * Returns the original content for claude-code; rewrites frontmatter for others.
- */
-export declare function transformAgent(markdown: string, harnessName: string): string;