@uluops/setup 0.6.5 → 0.8.1

package/dist/steps/auth.js

@@ -1,6 +1,8 @@
-import { readFile, access } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile, access, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { extractEmail } from "../lib/json-guards.js";
+import { atomicWrite } from "../lib/atomic-write.js";
 function getKeyPrefix() {
     return process.env["ULUOPS_KEY_PREFIX"] ?? "ulr_";
 }
@@ -21,6 +23,50 @@ export async function hasCredentialsFile() {
         return false;
     }
 }
+/**
+ * Persist an API key to ~/.uluops/credentials.json so @uluops/cli and the SDK
+ * can resolve it from disk without ULUOPS_API_KEY in the shell environment.
+ *
+ * Merges into the existing file when present: only the `default` profile is
+ * replaced; any other named profiles are preserved. Creates ~/.uluops/ with
+ * mode 0o700 if missing. Writes the file at 0o600 via atomicWrite.
+ */
+export async function writeCredentialsFile(apiKey, opts) {
+    if (opts?.dryRun)
+        return;
+    const credsPath = credentialsPath();
+    await mkdir(dirname(credsPath), { recursive: true, mode: 0o700 });
+    // Merge: preserve any non-default profiles already on disk.
+    let existing = {};
+    try {
+        const raw = await readFile(credsPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            existing = parsed;
+        }
+    }
+    catch {
+        // No existing file, or unparseable — start fresh.
+    }
+    const merged = {
+        ...existing,
+        default: {
+            // type discriminant must match the shape @uluops/cli writes via
+            // saveCredentials and the shape @uluops/sdk-core's StoredProfile expects.
+            // Without it, `ulu auth logout` reads creds.type !== 'api_key' and
+            // dispatches the revocation call with no bearer header — the server-side
+            // key survives a "successful" logout.
+            type: "api_key",
+            apiKey,
+            email: opts?.email ?? null,
+            createdAt: new Date().toISOString(),
+            source: opts?.source ?? "flag",
+        },
+    };
+    await atomicWrite(credsPath, JSON.stringify(merged, null, 2) + "\n", {
+        mode: 0o600,
+    });
+}
 /**
  * Resolve API key from flags, env, credentials file, or interactive prompt.
  */
@@ -102,9 +148,19 @@ async function validateKey(apiKey) {
         if (!res.ok) {
             throw new Error(`API returned ${res.status}. Try --skip-validation to continue offline.`);
         }
-        // ops-uluops-api wraps user payloads as { data: { email, ... } }
-        const body = (await res.json());
-        return { email: body.data?.email ?? null };
+        // ops-uluops-api wraps user payloads as { data: { email, ... } }.
+        // Guard against malformed responses (HTML error pages, proxy interception,
+        // schema drift) — bare `as` would let `data` be a string, number, or null
+        // and produce a silent `email: null` result that looks like a normal
+        // logged-in user with no email on record.
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            throw new Error("API returned a non-JSON response. The endpoint may be down or behind a captive portal — try --skip-validation to continue offline.");
+        }
+        return { email: extractEmail(body) };
     }
     catch (err) {
         // fetch() throws TypeError for network failures (ENOTFOUND, ECONNREFUSED).

package/dist/steps/cli.d.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 export declare const CLI_PACKAGE = "@uluops/cli";
 export declare const CLI_BIN = "ulu";
 export interface CliExecutor {
@@ -14,6 +15,11 @@ export interface CliExecutor {
         error?: string;
     };
 }
+/** @internal — exported for test access to the timeout-summarization branch. */
+export declare function summarizeSpawnResult(r: ReturnType<typeof spawnSync>, op: string): {
+    ok: boolean;
+    error?: string;
+};
 /** Default executor — shells out to `ulu` and `npm`. */
 export declare const defaultExecutor: CliExecutor;
 export interface CliInstallResult {

package/dist/steps/cli.js

@@ -1,12 +1,37 @@
 import { spawnSync } from "node:child_process";
 export const CLI_PACKAGE = "@uluops/cli";
 export const CLI_BIN = "ulu";
+/**
+ * Maximum time we wait for an `npm install -g` / `npm uninstall -g` to
+ * complete before terminating it. Bounded to protect setup from indefinite
+ * hangs caused by corporate proxy stalls, lifecycle scripts awaiting stdin,
+ * or registry slow-response storms. 5 minutes is generous for an npm install
+ * of a small CLI and tight enough that users notice and can intervene.
+ */
+const NPM_TIMEOUT_MS = 5 * 60_000;
+/** Short read; 30s is plenty for `ulu --version`. */
+const DETECT_TIMEOUT_MS = 30_000;
+/** @internal — exported for test access to the timeout-summarization branch. */
+export function summarizeSpawnResult(r, op) {
+    if (r.status === 0)
+        return { ok: true };
+    if (r.signal === "SIGTERM" && r.status === null) {
+        return {
+            ok: false,
+            error: `npm ${op} exceeded ${NPM_TIMEOUT_MS / 1000}s timeout and was terminated`,
+        };
+    }
+    const stderr = (r.stderr ?? "").toString().trim();
+    const stdout = (r.stdout ?? "").toString().trim();
+    return { ok: false, error: stderr || stdout || `exit ${r.status}` };
+}
 /** 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"],
+            timeout: DETECT_TIMEOUT_MS,
         });
         if (r.status !== 0 || !r.stdout)
             return null;
@@ -16,23 +41,17 @@ export const defaultExecutor = {
         const r = spawnSync("npm", ["install", "-g", CLI_PACKAGE], {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
+            timeout: NPM_TIMEOUT_MS,
         });
-        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}` };
+        return summarizeSpawnResult(r, "install");
     },
     uninstall: () => {
         const r = spawnSync("npm", ["uninstall", "-g", CLI_PACKAGE], {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
+            timeout: NPM_TIMEOUT_MS,
         });
-        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}` };
+        return summarizeSpawnResult(r, "uninstall");
     },
 };
 /**

package/dist/steps/commands.d.ts

@@ -7,6 +7,16 @@ export interface CommandsResult {
     removed: number;
     files: string[];
     skippedReason?: string;
+    /**
+     * Per-file copy failures across all subdirs. The loop continues past errors
+     * so a single bad file cannot abort the install and leave commands half-
+     * installed. The caller surfaces these via `warn()`. Files in this list are
+     * NOT counted in agent/workflow/pipeline counters (or `skipped`).
+     */
+    failures: {
+        file: string;
+        error: string;
+    }[];
 }
 /** Install pre-rendered command files from harness-specific assets. */
 export declare function installCommands(profile: HarnessProfile, localDefs: boolean, dryRun: boolean, existingManifestCommands?: string[]): Promise<CommandsResult>;

package/dist/steps/commands.js

@@ -1,7 +1,7 @@
-import { readdir, mkdir, unlink } from "node:fs/promises";
+import { readdir, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { ASSETS_DIR, findProjectRoot } from "../lib/paths.js";
-import { copyIfChanged, unlinkFiles } from "../lib/file-ops.js";
+import { copyIfChanged, unlinkFiles, removeStaleFiles, } 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) {
@@ -27,6 +27,7 @@ export async function installCommands(profile, localDefs, dryRun, existingManife
             removed: 0,
             files: [],
             skippedReason: "not-supported",
+            failures: [],
         };
     }
     let agentCommands = 0;
@@ -34,6 +35,7 @@ export async function installCommands(profile, localDefs, dryRun, existingManife
     let pipelineCommands = 0;
     let skipped = 0;
     const allFiles = [];
+    const failures = [];
     for (const subdir of SUBDIRS) {
         const srcDir = join(srcBase, subdir);
         const destDir = join(destBase, subdir);
@@ -49,38 +51,36 @@ export async function installCommands(profile, localDefs, dryRun, existingManife
         }
         for (const file of files) {
             const relativePath = `${subdir}/${file}`;
-            const result = await copyIfChanged(join(srcDir, file), join(destDir, file), dryRun);
-            if (result === "copied") {
-                if (subdir === "agents")
-                    agentCommands++;
-                else if (subdir === "workflows")
-                    workflowCommands++;
-                else
-                    pipelineCommands++;
-            }
-            else {
-                skipped++;
-            }
-            allFiles.push(relativePath);
-        }
-    }
-    // Remove files that were in the old manifest but no longer in the package
-    let removed = 0;
-    if (existingManifestCommands) {
-        for (const oldFile of existingManifestCommands) {
-            if (!allFiles.includes(oldFile)) {
-                if (!dryRun) {
-                    try {
-                        await unlink(join(destBase, oldFile));
-                    }
-                    catch {
-                        // Already gone
-                    }
+            try {
+                const result = await copyIfChanged(join(srcDir, file), join(destDir, file), dryRun);
+                if (result === "copied") {
+                    if (subdir === "agents")
+                        agentCommands++;
+                    else if (subdir === "workflows")
+                        workflowCommands++;
+                    else
+                        pipelineCommands++;
+                }
+                else {
+                    skipped++;
                 }
-                removed++;
+                // Only track files that actually made it into a known state. Failed
+                // copies do NOT enter allFiles — otherwise the manifest's "remove
+                // stale entries on re-run" diff would treat a never-copied file as
+                // present, and an `--uninstall` would later try to unlink something
+                // that was never written.
+                allFiles.push(relativePath);
+            }
+            catch (err) {
+                // Continue past per-file failures (see AgentsResult.failures rationale).
+                failures.push({
+                    file: relativePath,
+                    error: err instanceof Error ? err.message : String(err),
+                });
             }
         }
     }
+    const removed = await removeStaleFiles(destBase, existingManifestCommands, allFiles, dryRun);
     return {
         agentCommands,
         workflowCommands,
@@ -88,6 +88,7 @@ export async function installCommands(profile, localDefs, dryRun, existingManife
         skipped,
         removed,
         files: allFiles,
+        failures,
     };
 }
 /** Remove previously installed command files by relative path. Returns count of successfully removed files. */

package/dist/steps/detect.js

@@ -16,7 +16,21 @@ export async function detect() {
     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);
+    // Standard process.version is v-prefixed semver ("v20.10.0"). We take the
+    // major after stripping the "v". The `?? "0"` removed from the prior version
+    // here was dead code — `"".split(".")` returns `[""]`, not an empty array,
+    // so the nullish coalesce never fired and an unparseable major silently
+    // resulted in NaN, which then fell through the `< 20` gate.
+    const majorVersion = parseInt(nodeVersion.slice(1).split(".")[0] ?? "", 10);
+    if (Number.isNaN(majorVersion)) {
+        // Defense in depth: a tampered binary, a wrapper that spoofs
+        // process.version, or a future Node release that breaks the v-prefixed
+        // semver convention would all silently pass the major-version gate.
+        // Reject with a distinct error so the user sees "your runtime is wrong"
+        // rather than the misleading "requires Node.js 20 or higher."
+        throw new Error(`Cannot parse Node.js version "${nodeVersion}". ` +
+            `@uluops/setup requires a standard v-prefixed semver (e.g., v20.10.0).`);
+    }
     if (majorVersion < 20) {
         throw new Error(`Unsupported Node.js version: ${nodeVersion}. @uluops/setup requires Node.js 20 or higher.`);
     }

package/dist/steps/mcp.js

@@ -1,9 +1,8 @@
 import { readFile, access } from "node:fs/promises";
 import { join } from "node:path";
 import { checkMcpPackageAvailability } from "../lib/config-merger.js";
-import { findProjectRoot, getBackupDir } from "../lib/paths.js";
+import { findProjectRoot } 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"
@@ -17,8 +16,6 @@ export async function installMcp(profile, apiKey, scope, dryRun) {
         packageWarnings.push(`npm packages not found in registry: ${missing.join(", ")}. MCP servers may fail to start.`);
     }
     if (!dryRun) {
-        // Backup before first write
-        await backupConfig(profile.name, configPath);
         await profile.mcpConfig.write(configPath, merged);
     }
     if (scope === "local" && !dryRun) {
@@ -28,14 +25,10 @@ export async function installMcp(profile, apiKey, scope, dryRun) {
 }
 /** 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);
 }
-async function backupConfig(harnessName, configPath) {
-    await backupFile(configPath, getBackupDir(harnessName));
-}
 async function addToGitignore(localConfigFilename) {
     const root = await findProjectRoot();
     try {

package/dist/steps/metrics.js

@@ -5,7 +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 { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 /** Where agent-metrics dist files are installed (derived from profile) */
 function getMetricsToolDir(profile) {
     return profile.paths.toolsDir;
@@ -36,8 +37,14 @@ export function getHookCommand(profile) {
 async function findMetricsSource() {
     try {
         const resolved = import.meta.resolve("@uluops/agent-metrics");
-        // resolved is like file:///path/to/dist/index.js — get the package root
-        const distDir = new URL(".", resolved).pathname;
+        // resolved is a file:// URL like file:///path/to/dist/index.js. Convert
+        // to a filesystem path via fileURLToPath, which handles Windows drive
+        // letters correctly. The previous `.pathname` access produced
+        // `/C:/path/to/...` on Windows (and WSL-mounted Windows paths),
+        // breaking the subsequent readFile of package.json — silently returning
+        // a null version and defeating verify's drift detection.
+        const distFile = fileURLToPath(resolved);
+        const distDir = dirname(distFile);
         const pkgRoot = join(distDir, "..");
         const version = await readSourceVersion(pkgRoot);
         return { pkgRoot, version };

package/dist/steps/shell.js

@@ -1,8 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { atomicWrite } from "../lib/atomic-write.js";
-import { backupFile } from "../lib/file-ops.js";
-import { getUluopsDir } from "../lib/paths.js";
 const FENCE_START = "# --- UluOps (managed by @uluops/setup) ---";
 const FENCE_END = "# --- /UluOps ---";
 /** Characters safe for shell variable values (no metacharacters). */
@@ -25,21 +22,18 @@ export async function writeShellExport(profilePath, apiKey, dryRun) {
     }
     const startIdx = content.indexOf(FENCE_START);
     const endIdx = content.lastIndexOf(FENCE_END);
-    if (!dryRun) {
-        await backupProfile(profilePath);
-    }
     if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
         // Replace existing fenced block — using lastIndexOf for FENCE_END collapses
         // any duplicate blocks left by earlier buggy installs into a single new block
         const before = content.slice(0, startIdx);
         const after = content.slice(endIdx + FENCE_END.length);
         if (!dryRun) {
-            await atomicWrite(profilePath, before + block + after);
+            await atomicWrite(profilePath, before + block + after, { mode: 0o600 });
         }
     }
     else {
         if (!dryRun) {
-            await atomicWrite(profilePath, content.trimEnd() + "\n\n" + block + "\n");
+            await atomicWrite(profilePath, content.trimEnd() + "\n\n" + block + "\n", { mode: 0o600 });
         }
     }
 }
@@ -55,12 +49,8 @@ export async function removeShellExport(profilePath) {
     const startIdx = content.indexOf(FENCE_START);
     const endIdx = content.lastIndexOf(FENCE_END);
     if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-        await backupProfile(profilePath);
         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"));
+        await atomicWrite(profilePath, (before + after).replace(/\n{3,}/g, "\n\n"), { mode: 0o600 });
     }
 }
-async function backupProfile(profilePath) {
-    await backupFile(profilePath, join(getUluopsDir(), "backups", "shell"));
-}

package/dist/steps/signup.js

@@ -50,6 +50,15 @@ export async function signup() {
         email: registerRes.data.user?.email ?? email,
     };
 }
+/**
+ * Issue a POST and decode the response into `T` via a caller-supplied
+ * structural predicate. `validate` is required, not optional — making it
+ * optional in earlier revisions meant a call site could omit it and get
+ * back `body as T` with only a "not null, is object" check, which is the
+ * pattern type-safety-validator flagged (EPI-OVR/H). Every current call
+ * site supplies a real predicate; this signature change locks that in for
+ * future call sites.
+ */
 async function callApi(url, method, body, bearerToken, validate) {
     const headers = {
         "Content-Type": "application/json",
@@ -77,7 +86,11 @@ async function callApi(url, method, body, bearerToken, validate) {
         if (typeof body !== "object" || body === null) {
             throw new Error("Unexpected API response shape");
         }
-        if (validate && !validate(body)) {
+        // `body as T` is a type assertion, not a runtime check — the validate
+        // predicate is what actually proves the structure. With validate now
+        // required, every code path passes through a real shape check before
+        // the cast is trusted.
+        if (!validate(body)) {
             throw new Error("API response failed structural validation");
         }
         return body;

package/dist/steps/skills.d.ts

@@ -0,0 +1,14 @@
+import type { HarnessProfile } from "../harnesses/index.js";
+export interface SkillsResult {
+    copied: number;
+    skipped: number;
+    removed: number;
+    files: string[];
+    skippedReason?: string;
+    failures: {
+        file: string;
+        error: string;
+    }[];
+}
+export declare function installSkills(profile: HarnessProfile, localDefs: boolean, dryRun: boolean, existingManifestSkills?: string[]): Promise<SkillsResult>;
+export declare function uninstallSkills(files: string[], defsPath: string): Promise<number>;

package/dist/steps/skills.js

@@ -0,0 +1,95 @@
+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";
+async function listFilesRecursive(dir, prefix = "") {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await listFilesRecursive(full, rel));
+        }
+        else if (entry.isFile()) {
+            files.push(rel);
+        }
+    }
+    return files.sort((a, b) => a.localeCompare(b));
+}
+export async function installSkills(profile, localDefs, dryRun, existingManifestSkills) {
+    const srcBase = join(ASSETS_DIR, profile.name, "skills");
+    const destBase = localDefs
+        ? join(await findProjectRoot(), "uluops", "skills")
+        : profile.paths.skillsDir;
+    if (!destBase) {
+        return {
+            copied: 0,
+            skipped: 0,
+            removed: 0,
+            files: [],
+            skippedReason: "not-supported",
+            failures: [],
+        };
+    }
+    const files = await listFilesRecursive(srcBase);
+    if (files.length === 0) {
+        return {
+            copied: 0,
+            skipped: 0,
+            removed: 0,
+            files: [],
+            skippedReason: "not-supported",
+            failures: [],
+        };
+    }
+    let copied = 0;
+    let skipped = 0;
+    const installedFiles = [];
+    const failures = [];
+    for (const file of files) {
+        const src = join(srcBase, file);
+        const dest = join(destBase, file);
+        try {
+            if (!dryRun) {
+                await mkdir(dirname(dest), { recursive: true });
+            }
+            const result = await copyIfChanged(src, dest, dryRun);
+            if (result === "copied")
+                copied++;
+            else
+                skipped++;
+            installedFiles.push(file);
+        }
+        catch (err) {
+            failures.push({
+                file,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const removed = await removeStaleFiles(destBase, existingManifestSkills, installedFiles, dryRun);
+    return { copied, skipped, removed, files: installedFiles, failures };
+}
+export async function uninstallSkills(files, defsPath) {
+    const skillsDir = join(defsPath, "skills");
+    const removed = await unlinkFiles(skillsDir, files);
+    const skillDirs = new Set(files
+        .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.
+        }
+    }
+    return removed;
+}