@uluops/setup 0.2.0 → 0.4.0

package/dist/lib/asset-catalog.d.ts

@@ -0,0 +1,9 @@
+export interface CommandEntry {
+    name: string;
+    description: string;
+    model: string;
+}
+/** Get all agent command entries from assets. */
+export declare function getAgentCommands(): Promise<CommandEntry[]>;
+/** Get all workflow command entries from assets. */
+export declare function getWorkflowCommands(): Promise<CommandEntry[]>;

package/dist/lib/asset-catalog.js

@@ -0,0 +1,56 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ASSETS_DIR } from "./paths.js";
+/**
+ * Parse YAML-like frontmatter from a markdown file.
+ * Returns key-value pairs between the opening and closing `---`.
+ */
+function parseFrontmatter(content) {
+    const lines = content.split("\n");
+    if (lines[0]?.trim() !== "---")
+        return {};
+    const result = {};
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "---")
+            break;
+        const colonIdx = line.indexOf(":");
+        if (colonIdx > 0) {
+            const key = line.slice(0, colonIdx).trim();
+            const value = line.slice(colonIdx + 1).trim();
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/** Scan a commands subdirectory and return sorted entries with frontmatter metadata. */
+async function scanCommandDir(dir) {
+    let files;
+    try {
+        files = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const file of files.filter((f) => f.endsWith(".md"))) {
+        const content = await readFile(join(dir, file), "utf-8");
+        const fm = parseFrontmatter(content);
+        if (fm["name"]) {
+            entries.push({
+                name: fm["name"],
+                description: fm["description"] ?? "",
+                model: fm["model"] ?? "sonnet",
+            });
+        }
+    }
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Get all agent command entries from assets. */
+export async function getAgentCommands() {
+    return scanCommandDir(join(ASSETS_DIR, "commands", "agents"));
+}
+/** Get all workflow command entries from assets. */
+export async function getWorkflowCommands() {
+    return scanCommandDir(join(ASSETS_DIR, "commands", "workflows"));
+}

package/dist/lib/atomic-write.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Atomic Write
+ *
+ * Write-to-temp-then-rename pattern to prevent partial writes
+ * from corrupting user config files.
+ */
+export interface AtomicWriteOptions {
+    /** File mode (permissions). Defaults to Node's default (0o666 before umask). */
+    mode?: number;
+}
+export declare function atomicWrite(path: string, content: string, options?: AtomicWriteOptions): Promise<void>;

package/dist/lib/atomic-write.js

@@ -0,0 +1,28 @@
+/**
+ * Atomic Write
+ *
+ * Write-to-temp-then-rename pattern to prevent partial writes
+ * from corrupting user config files.
+ */
+import { writeFile, rename, unlink, chmod } from "node:fs/promises";
+export async function atomicWrite(path, content, options) {
+    const tmp = `${path}.uluops-tmp`;
+    try {
+        await writeFile(tmp, content, { encoding: "utf-8", mode: options?.mode });
+        if (options?.mode) {
+            // Ensure mode is applied even if umask is permissive
+            await chmod(tmp, options.mode);
+        }
+        await rename(tmp, path);
+    }
+    catch (err) {
+        // Clean up temp file on failure
+        try {
+            await unlink(tmp);
+        }
+        catch {
+            // Temp file may not exist
+        }
+        throw err;
+    }
+}

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

@@ -3,12 +3,18 @@ interface McpServerConfig {
     args: string[];
     env: Record<string, string>;
 }
-interface ClaudeConfig {
+export interface ClaudeConfig {
     mcpServers?: Record<string, McpServerConfig>;
     [key: string]: unknown;
 }
+/** Check whether the UluOps MCP client packages exist on the npm registry. Returns lists of available and missing packages. */
+export declare function checkMcpPackageAvailability(): Promise<{
+    available: string[];
+    missing: string[];
+}>;
 /**
  * Read an existing config file, or return empty object if it doesn't exist.
+ * Throws on malformed JSON to prevent silent data loss during merge+write.
  */
 export declare function readConfig(path: string): Promise<ClaudeConfig>;
 /**

package/dist/lib/config-merger.js

@@ -1,15 +1,42 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { atomicWrite } from "./atomic-write.js";
+const MCP_PACKAGES = ["uluops-tracker-mcp-client", "uluops-registry-mcp-client"];
+/** Check whether the UluOps MCP client packages exist on the npm registry. Returns lists of available and missing packages. */
+export async function checkMcpPackageAvailability() {
+    const available = [];
+    const missing = [];
+    const results = await Promise.allSettled(MCP_PACKAGES.map((pkg) => fetch(`https://registry.npmjs.org/${pkg}`, {
+        method: "HEAD",
+        signal: AbortSignal.timeout(5000),
+        redirect: "follow",
+    }).then((res) => ({ pkg, ok: res.ok }))));
+    for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        if (result.status === "fulfilled" && result.value.ok) {
+            available.push(result.value.pkg);
+        }
+        else {
+            const pkg = result.status === "fulfilled"
+                ? result.value.pkg
+                : MCP_PACKAGES[i] ?? "unknown";
+            missing.push(pkg);
+        }
+    }
+    return { available, missing };
+}
 /**
  * Read an existing config file, or return empty object if it doesn't exist.
+ * Throws on malformed JSON to prevent silent data loss during merge+write.
  */
 export async function readConfig(path) {
+    let raw;
     try {
-        const raw = await readFile(path, "utf-8");
-        return JSON.parse(raw);
+        raw = await readFile(path, "utf-8");
     }
     catch {
-        return {};
+        return {}; // File doesn't exist — fresh config
     }
+    return JSON.parse(raw);
 }
 /**
  * Merge UluOps MCP server entries into a config, preserving all other keys.
@@ -59,5 +86,7 @@ export function removeUluopsMcp(config) {
  * Write config back to file, preserving formatting.
  */
 export async function writeConfig(path, config) {
-    await writeFile(path, JSON.stringify(config, null, 2) + "\n");
+    await atomicWrite(path, JSON.stringify(config, null, 2) + "\n", {
+        mode: 0o600,
+    });
 }

package/dist/lib/display.d.ts

@@ -0,0 +1,14 @@
+import type { HarnessProfile } from "../harnesses/index.js";
+declare const ok: (msg: string) => void;
+declare const warn: (msg: string) => void;
+declare const fail: (msg: string) => void;
+declare const info: (msg: string) => void;
+export { ok, warn, fail, info };
+export declare function printSetupSummary(opts: {
+    profile: HarnessProfile;
+    agentCount: number;
+    commandCount: number;
+    apiKey: string;
+}): Promise<void>;
+export declare function maskKey(key: string): string;
+export declare function printAgentList(): Promise<void>;

package/dist/lib/display.js

@@ -0,0 +1,66 @@
+import chalk from "chalk";
+import { getAgentCommands, getWorkflowCommands } from "./asset-catalog.js";
+const ok = (msg) => console.log(`  ${chalk.green("✓")} ${msg}`);
+const warn = (msg) => console.log(`  ${chalk.yellow("⚠")} ${msg}`);
+const fail = (msg) => console.log(`  ${chalk.red("✗")} ${msg}`);
+const info = (msg) => console.log(`  ${msg}`);
+export { ok, warn, fail, info };
+export async function printSetupSummary(opts) {
+    console.log();
+    console.log(`  ${chalk.dim("━".repeat(46))}`);
+    console.log();
+    const parts = [`${opts.agentCount} agents`];
+    if (opts.commandCount > 0)
+        parts.push(`${opts.commandCount} slash commands`);
+    if (opts.profile.hooks)
+        parts.push("metrics");
+    console.log(`  ${chalk.bold("Setup complete!")} ${chalk.dim(`(${opts.profile.displayName})`)} ${parts.join(" · ")}`);
+    console.log();
+    if (opts.profile.name === "claude-code") {
+        await printAgentList();
+    }
+    const masked = maskKey(opts.apiKey);
+    info("For SDK/CLI usage, add to your shell profile:");
+    info(`  ${chalk.cyan(`export ULUOPS_API_KEY="${masked}"`)}`);
+    console.log();
+    info(`Run again to update: ${chalk.cyan("npx @uluops/setup")}`);
+    console.log();
+    console.log(`  ${chalk.dim("━".repeat(46))}`);
+    console.log();
+    console.log(`  ${chalk.yellow.bold(`Restart ${opts.profile.displayName} to load agents.`)}`);
+    console.log();
+}
+export function maskKey(key) {
+    if (!key || key.length <= 4)
+        return "****";
+    const last4 = key.slice(-4);
+    return `${"*".repeat(Math.max(4, key.length - 4))}${last4}`;
+}
+export async function printAgentList() {
+    const workflows = await getWorkflowCommands();
+    const agents = await getAgentCommands();
+    if (workflows.length > 0) {
+        info(chalk.bold("WORKFLOWS"));
+        for (const wf of workflows) {
+            const cmd = `/workflows:${wf.name}`;
+            const desc = wf.description.length > 40
+                ? wf.description.slice(0, 37) + "..."
+                : wf.description;
+            info(`  ${chalk.cyan(cmd.padEnd(34))}${desc}`);
+        }
+        console.log();
+    }
+    if (agents.length > 0) {
+        info(`${chalk.bold("AGENTS")} (run individually)${" ".repeat(26)}${chalk.dim("MODEL")}`);
+        for (const agent of agents) {
+            const cmd = `/agents:${agent.name}`;
+            const desc = agent.description.length > 17
+                ? agent.description.slice(0, 14) + "..."
+                : agent.description;
+            info(`  ${chalk.cyan(cmd.padEnd(34))}${desc.padEnd(17)}${chalk.dim(agent.model)}`);
+        }
+        console.log();
+    }
+    info(chalk.dim(`  This is the starter set. Browse more agents at registry.uluops.ai`));
+    console.log();
+}

package/dist/lib/file-ops.d.ts

@@ -2,6 +2,11 @@
  * Copy a file if its content has changed (hash comparison). Returns "copied" or "skipped".
  */
 export declare function copyIfChanged(srcPath: string, destPath: string, dryRun: boolean): Promise<"copied" | "skipped">;
+/**
+ * Write content to a file if it differs from the current content (hash comparison).
+ * Returns "copied" or "skipped".
+ */
+export declare function writeIfChanged(destPath: string, content: string, dryRun: boolean): Promise<"copied" | "skipped">;
 /**
  * Remove files from a directory. Returns count of successfully removed files.
  */
@@ -14,6 +19,7 @@ export declare function syncAssets(opts: {
     srcDir: string;
     destDir: string;
     dryRun: boolean;
+    extension?: string;
     oldManifestFiles?: string[];
 }): Promise<{
     copied: number;

package/dist/lib/file-ops.js

@@ -21,6 +21,26 @@ export async function copyIfChanged(srcPath, destPath, dryRun) {
     }
     return "copied";
 }
+/**
+ * Write content to a file if it differs from the current content (hash comparison).
+ * Returns "copied" or "skipped".
+ */
+export async function writeIfChanged(destPath, content, dryRun) {
+    const newHash = fileHash(content);
+    try {
+        const existing = await readFile(destPath, "utf-8");
+        if (newHash === fileHash(existing)) {
+            return "skipped";
+        }
+    }
+    catch {
+        // File doesn't exist yet
+    }
+    if (!dryRun) {
+        await writeFile(destPath, content);
+    }
+    return "copied";
+}
 /**
  * Remove files from a directory. Returns count of successfully removed files.
  */
@@ -46,7 +66,8 @@ export async function syncAssets(opts) {
     if (!opts.dryRun) {
         await mkdir(opts.destDir, { recursive: true });
     }
-    const assetFiles = (await readdir(opts.srcDir)).filter((f) => f.endsWith(".md"));
+    const ext = opts.extension ?? ".md";
+    const assetFiles = (await readdir(opts.srcDir)).filter((f) => f.endsWith(ext));
     let copied = 0;
     let skipped = 0;
     const errors = [];

package/dist/lib/hash.d.ts

@@ -1 +1,2 @@
+/** Return a truncated SHA-256 hash (12 hex chars) of the given string content. */
 export declare function fileHash(content: string): string;

package/dist/lib/hash.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+/** Return a truncated SHA-256 hash (12 hex chars) of the given string content. */
 export function fileHash(content) {
     return createHash("sha256").update(content).digest("hex").slice(0, 12);
 }

package/dist/lib/health.d.ts

@@ -0,0 +1,2 @@
+/** Shared health check timeout, configurable via ULUOPS_HEALTH_TIMEOUT env var. */
+export declare function getHealthTimeout(): number;

package/dist/lib/health.js

@@ -0,0 +1,10 @@
+/** Shared health check timeout, configurable via ULUOPS_HEALTH_TIMEOUT env var. */
+export function getHealthTimeout() {
+    const env = process.env["ULUOPS_HEALTH_TIMEOUT"];
+    if (env) {
+        const ms = Number(env);
+        if (Number.isFinite(ms) && ms > 0)
+            return ms;
+    }
+    return 10_000;
+}

package/dist/lib/manifest.d.ts

@@ -1,16 +1,33 @@
-export interface Manifest {
-    version: string;
+/** Per-harness installation state. */
+export interface HarnessManifest {
     installedAt: string;
+    setupVersion: string;
     mcpScope: "global" | "local";
     mcpConfigPath: string;
     defsScope: "global" | "local";
     defsPath: string;
-    shellModified: boolean;
     agents: string[];
     commands: string[];
-    /** Whether agent-metrics hook is configured */
-    metricsHookInstalled?: boolean;
+    hooksInstalled: boolean;
+}
+/** Top-level manifest with per-harness entries. */
+export interface Manifest {
+    version: string;
+    installedAt: string;
+    shellModified: boolean;
+    harnesses: Record<string, HarnessManifest>;
+    contentHash?: string;
+}
+export interface ManifestValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
 }
+/** Validate a manifest against the current filesystem state. */
+export declare function validateManifest(manifest: Manifest): Promise<ManifestValidationResult>;
+/** Load the install manifest. Tries new location first, falls back to legacy, auto-migrates. */
 export declare function loadManifest(): Promise<Manifest | null>;
+/** Save the install manifest to ~/.uluops/manifest.json. Creates directory if needed. */
 export declare function saveManifest(manifest: Manifest): Promise<void>;
+/** Delete the install manifest file from disk. Tries both locations. */
 export declare function deleteManifest(): Promise<void>;

package/dist/lib/manifest.js

@@ -1,6 +1,32 @@
-import { readFile, writeFile, unlink } from "node:fs/promises";
-import { getManifestPath } from "./paths.js";
-function isManifest(obj) {
+import { readFile, unlink, access, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { getManifestPath, getLegacyManifestPath, getUluopsDir } from "./paths.js";
+import { fileHash } from "./hash.js";
+import { atomicWrite } from "./atomic-write.js";
+function isNewManifest(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const m = obj;
+    if (typeof m["version"] !== "string" ||
+        typeof m["installedAt"] !== "string" ||
+        typeof m["shellModified"] !== "boolean" ||
+        typeof m["harnesses"] !== "object" ||
+        m["harnesses"] === null)
+        return false;
+    // Validate at least one harness entry has required fields
+    const harnesses = m["harnesses"];
+    for (const h of Object.values(harnesses)) {
+        if (typeof h !== "object" || h === null)
+            return false;
+        const hm = h;
+        if (typeof hm["mcpConfigPath"] !== "string" || typeof hm["defsPath"] !== "string")
+            return false;
+        if (!Array.isArray(hm["agents"]) || !Array.isArray(hm["commands"]))
+            return false;
+    }
+    return true;
+}
+function isLegacyManifest(obj) {
     if (typeof obj !== "object" || obj === null)
         return false;
     const m = obj;
@@ -9,26 +35,135 @@ function isManifest(obj) {
         typeof m["mcpConfigPath"] === "string" &&
         typeof m["defsPath"] === "string" &&
         Array.isArray(m["agents"]) &&
-        Array.isArray(m["commands"]));
+        Array.isArray(m["commands"]) &&
+        !("harnesses" in m));
 }
-export async function loadManifest() {
+function migrateManifest(old) {
+    return {
+        version: old.version,
+        installedAt: old.installedAt,
+        shellModified: old.shellModified,
+        harnesses: {
+            "claude-code": {
+                installedAt: old.installedAt,
+                setupVersion: old.version,
+                mcpScope: old.mcpScope,
+                mcpConfigPath: old.mcpConfigPath,
+                defsScope: old.defsScope,
+                defsPath: old.defsPath,
+                agents: old.agents,
+                commands: old.commands,
+                hooksInstalled: old.metricsHookInstalled ?? false,
+            },
+        },
+    };
+}
+/** Validate a manifest against the current filesystem state. */
+export async function validateManifest(manifest) {
+    const errors = [];
+    const warnings = [];
+    for (const [harnessName, hm] of Object.entries(manifest.harnesses)) {
+        const mcpExists = await pathExists(hm.mcpConfigPath);
+        if (!mcpExists) {
+            errors.push(`[${harnessName}] MCP config path does not exist: ${hm.mcpConfigPath}`);
+        }
+        const defsExists = await pathExists(hm.defsPath);
+        if (!defsExists) {
+            errors.push(`[${harnessName}] Defs path does not exist: ${hm.defsPath}`);
+        }
+        if (hm.agents.length > 0 && defsExists) {
+            const missing = await findMissingFiles(hm.defsPath, "agents", hm.agents);
+            if (missing.length > 0) {
+                warnings.push(`[${harnessName}] Agent files missing from disk: ${missing.join(", ")}`);
+            }
+        }
+        if (hm.commands.length > 0 && defsExists) {
+            const missing = await findMissingFiles(hm.defsPath, "commands", hm.commands);
+            if (missing.length > 0) {
+                warnings.push(`[${harnessName}] Command files missing from disk: ${missing.join(", ")}`);
+            }
+        }
+    }
+    const manifestPath = getManifestPath();
     try {
-        const raw = await readFile(getManifestPath(), "utf-8");
+        const raw = await readFile(manifestPath, "utf-8");
         const parsed = JSON.parse(raw);
-        return isManifest(parsed) ? parsed : null;
+        const { contentHash: storedHash, ...withoutHash } = parsed;
+        const canonical = JSON.stringify(withoutHash, null, 2) + "\n";
+        const currentHash = fileHash(canonical);
+        if (storedHash && storedHash !== currentHash) {
+            warnings.push("Manifest file has been modified since installation — content hash mismatch");
+        }
     }
     catch {
-        return null;
+        warnings.push("Cannot read manifest file to verify content hash");
     }
+    return { valid: errors.length === 0, errors, warnings };
 }
-export async function saveManifest(manifest) {
-    await writeFile(getManifestPath(), JSON.stringify(manifest, null, 2) + "\n");
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
-export async function deleteManifest() {
+async function findMissingFiles(baseDir, subDir, files) {
+    const missing = [];
+    for (const file of files) {
+        if (!(await pathExists(join(baseDir, subDir, file)))) {
+            missing.push(file);
+        }
+    }
+    return missing;
+}
+async function readManifestFile(path) {
     try {
-        await unlink(getManifestPath());
+        const raw = await readFile(path, "utf-8");
+        return JSON.parse(raw);
     }
     catch {
-        // Already gone
+        return null;
+    }
+}
+/** Load the install manifest. Tries new location first, falls back to legacy, auto-migrates. */
+export async function loadManifest() {
+    // Try new location first
+    const newData = await readManifestFile(getManifestPath());
+    if (newData && isNewManifest(newData))
+        return newData;
+    // Fall back to legacy location
+    const legacyData = await readManifestFile(getLegacyManifestPath());
+    if (legacyData && isLegacyManifest(legacyData)) {
+        return migrateManifest(legacyData);
+    }
+    // Also check if legacy location has new format (written by newer version but not yet moved)
+    if (legacyData && isNewManifest(legacyData))
+        return legacyData;
+    return null;
+}
+/** Save the install manifest to ~/.uluops/manifest.json. Creates directory if needed. */
+export async function saveManifest(manifest) {
+    const dir = getUluopsDir();
+    await mkdir(dir, { recursive: true });
+    // Serialize without hash, compute hash of that content, embed it.
+    // Validation compares the stored hash against a re-hash of the file
+    // with contentHash stripped, so both sides agree on the input.
+    const { contentHash: _, ...withoutHash } = manifest;
+    const canonical = JSON.stringify(withoutHash, null, 2) + "\n";
+    const hash = fileHash(canonical);
+    const final = JSON.stringify({ ...withoutHash, contentHash: hash }, null, 2) + "\n";
+    await atomicWrite(getManifestPath(), final);
+}
+/** Delete the install manifest file from disk. Tries both locations. */
+export async function deleteManifest() {
+    for (const path of [getManifestPath(), getLegacyManifestPath()]) {
+        try {
+            await unlink(path);
+        }
+        catch {
+            // Already gone
+        }
     }
 }

package/dist/lib/paths.d.ts

@@ -2,12 +2,24 @@
 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. */
+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;