@uluops/setup 0.2.0

package/dist/steps/metrics.js

@@ -0,0 +1,176 @@
+/**
+ * Metrics Step
+ *
+ * Installs agent-metrics tool files to ~/.claude/tools/agent-metrics/
+ * and configures the SubagentStop hook in settings.json for auto-capture.
+ */
+import { mkdir, readdir, copyFile, rm, access } from "node:fs/promises";
+import { join } from "node:path";
+import { getClaudeHome } from "../lib/paths.js";
+import { readSettings, writeSettings, mergeUluopsHook, removeUluopsHook, } from "../lib/settings-merger.js";
+/** Where agent-metrics dist files are installed */
+export function getMetricsToolDir() {
+    return join(getClaudeHome(), "tools", "agent-metrics");
+}
+/** Path to Claude Code's settings.json */
+export function getSettingsPath() {
+    return join(getClaudeHome(), "settings.json");
+}
+/** The hook command that runs on SubagentStop */
+function getHookCommand() {
+    const toolDir = getMetricsToolDir();
+    return `node ${join(toolDir, "dist", "hook.js")}`;
+}
+/**
+ * Find the agent-metrics package source directory.
+ * Looks for it as a sibling package in the monorepo or as an npm dependency.
+ */
+async function findMetricsSource() {
+    // Try to find the package via Node.js module resolution
+    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;
+        const pkgRoot = join(distDir, "..");
+        return pkgRoot;
+    }
+    catch {
+        // Not installed as dependency
+    }
+    return null;
+}
+/**
+ * Copy agent-metrics dist files to the tool directory.
+ * Copies all .js files needed for the hook and CLI.
+ */
+async function copyToolFiles(srcRoot, destRoot, dryRun) {
+    const srcDist = join(srcRoot, "dist");
+    const destDist = join(destRoot, "dist");
+    if (!dryRun) {
+        await mkdir(destDist, { recursive: true });
+        await mkdir(join(destDist, "commands"), { recursive: true });
+        await mkdir(join(destDist, "display"), { recursive: true });
+    }
+    let filesCopied = 0;
+    // Copy top-level dist files
+    const topFiles = await readdir(srcDist);
+    for (const file of topFiles) {
+        if (!file.endsWith(".js"))
+            continue;
+        if (file.includes(".test."))
+            continue;
+        if (file === "test-utils.js")
+            continue;
+        if (!dryRun) {
+            await copyFile(join(srcDist, file), join(destDist, file));
+        }
+        filesCopied++;
+    }
+    // Copy commands/ subdirectory
+    try {
+        const cmdFiles = await readdir(join(srcDist, "commands"));
+        for (const file of cmdFiles) {
+            if (!file.endsWith(".js"))
+                continue;
+            if (file.includes(".test."))
+                continue;
+            if (!dryRun) {
+                await copyFile(join(srcDist, "commands", file), join(destDist, "commands", file));
+            }
+            filesCopied++;
+        }
+    }
+    catch {
+        // commands/ doesn't exist — not critical
+    }
+    // Copy display/ subdirectory
+    try {
+        const dispFiles = await readdir(join(srcDist, "display"));
+        for (const file of dispFiles) {
+            if (!file.endsWith(".js"))
+                continue;
+            if (file.includes(".test."))
+                continue;
+            if (!dryRun) {
+                await copyFile(join(srcDist, "display", file), join(destDist, "display", file));
+            }
+            filesCopied++;
+        }
+    }
+    catch {
+        // display/ doesn't exist — not critical
+    }
+    // Copy package.json (needed for CLI bin resolution)
+    try {
+        if (!dryRun) {
+            await copyFile(join(srcRoot, "package.json"), join(destRoot, "package.json"));
+        }
+        filesCopied++;
+    }
+    catch {
+        // Not critical
+    }
+    return filesCopied;
+}
+/**
+ * Install agent-metrics: copy tool files and configure SubagentStop hook.
+ */
+export async function installMetrics(dryRun) {
+    const toolDir = getMetricsToolDir();
+    const settingsPath = getSettingsPath();
+    // Find source package
+    const srcRoot = await findMetricsSource();
+    let toolFilesCopied = 0;
+    if (srcRoot) {
+        // Copy tool files
+        if (!dryRun) {
+            await mkdir(toolDir, { recursive: true });
+        }
+        toolFilesCopied = await copyToolFiles(srcRoot, toolDir, dryRun);
+    }
+    else {
+        // Check if already installed (from previous run or install.sh)
+        try {
+            await access(join(toolDir, "dist", "hook.js"));
+        }
+        catch {
+            // Not found anywhere — skip tool installation, just configure hook
+            // if files happen to exist
+        }
+    }
+    // Configure hook in settings.json
+    let hookConfigured = false;
+    if (!dryRun) {
+        const settings = await readSettings(settingsPath);
+        const hookCommand = getHookCommand();
+        const merged = mergeUluopsHook(settings, hookCommand);
+        await writeSettings(settingsPath, merged);
+        hookConfigured = true;
+    }
+    else {
+        hookConfigured = true;
+    }
+    return { toolFilesCopied, hookConfigured };
+}
+/**
+ * Uninstall agent-metrics: remove hook from settings and optionally remove tool files.
+ */
+export async function uninstallMetrics(dryRun) {
+    const settingsPath = getSettingsPath();
+    const toolDir = getMetricsToolDir();
+    // Remove hook from settings.json
+    if (!dryRun) {
+        const settings = await readSettings(settingsPath);
+        const cleaned = removeUluopsHook(settings);
+        await writeSettings(settingsPath, cleaned);
+    }
+    // Remove tool directory
+    if (!dryRun) {
+        try {
+            await rm(toolDir, { recursive: true, force: true });
+        }
+        catch {
+            // Already gone
+        }
+    }
+}

package/dist/steps/shell.d.ts

@@ -0,0 +1,2 @@
+export declare function writeShellExport(profilePath: string, apiKey: string, dryRun: boolean): Promise<void>;
+export declare function removeShellExport(profilePath: string): Promise<void>;

package/dist/steps/shell.js

@@ -0,0 +1,48 @@
+import { readFile, writeFile } from "node:fs/promises";
+const FENCE_START = "# --- UluOps (managed by @uluops/setup) ---";
+const FENCE_END = "# --- /UluOps ---";
+export async function writeShellExport(profilePath, apiKey, dryRun) {
+    const block = `${FENCE_START}\nexport ULUOPS_API_KEY="${apiKey}"\n${FENCE_END}`;
+    let content;
+    try {
+        content = await readFile(profilePath, "utf-8");
+    }
+    catch {
+        if (!dryRun) {
+            await writeFile(profilePath, block + "\n");
+        }
+        return;
+    }
+    const startIdx = content.indexOf(FENCE_START);
+    const endIdx = content.indexOf(FENCE_END);
+    if (startIdx !== -1 && endIdx !== -1) {
+        // Replace existing fenced block
+        const before = content.slice(0, startIdx);
+        const after = content.slice(endIdx + FENCE_END.length);
+        if (!dryRun) {
+            await writeFile(profilePath, before + block + after);
+        }
+    }
+    else {
+        // Append
+        if (!dryRun) {
+            await writeFile(profilePath, content.trimEnd() + "\n\n" + block + "\n");
+        }
+    }
+}
+export async function removeShellExport(profilePath) {
+    let content;
+    try {
+        content = await readFile(profilePath, "utf-8");
+    }
+    catch {
+        return;
+    }
+    const startIdx = content.indexOf(FENCE_START);
+    const endIdx = content.indexOf(FENCE_END);
+    if (startIdx !== -1 && endIdx !== -1) {
+        const before = content.slice(0, startIdx);
+        const after = content.slice(endIdx + FENCE_END.length);
+        await writeFile(profilePath, (before + after).replace(/\n{3,}/g, "\n\n"));
+    }
+}

package/dist/steps/signup.d.ts

@@ -0,0 +1,13 @@
+import type { AuthResult } from "./auth.js";
+/**
+ * Password complexity rules (matches ops-uluops-api validation).
+ * Validated client-side for instant feedback before network round-trip.
+ */
+declare function validatePassword(password: string): string | true;
+declare function validateEmail(email: string): string | true;
+/**
+ * Interactive signup flow: create account + generate API key.
+ * Returns the same AuthResult shape as resolveApiKey for seamless integration.
+ */
+export declare function signup(): Promise<AuthResult>;
+export { validatePassword, validateEmail };

package/dist/steps/signup.js

@@ -0,0 +1,92 @@
+const API_BASE = "https://api.uluops.ai/api/v1";
+/**
+ * Password complexity rules (matches ops-uluops-api validation).
+ * Validated client-side for instant feedback before network round-trip.
+ */
+function validatePassword(password) {
+    if (password.length < 8)
+        return "Password must be at least 8 characters";
+    if (password.length > 128)
+        return "Password must be at most 128 characters";
+    if (!/[a-z]/.test(password))
+        return "Password must include a lowercase letter";
+    if (!/[A-Z]/.test(password))
+        return "Password must include an uppercase letter";
+    if (!/[0-9]/.test(password))
+        return "Password must include a number";
+    return true;
+}
+function validateEmail(email) {
+    if (!email.trim())
+        return "Email is required";
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+        return "Invalid email format";
+    return true;
+}
+/**
+ * Interactive signup flow: create account + generate API key.
+ * Returns the same AuthResult shape as resolveApiKey for seamless integration.
+ */
+export async function signup() {
+    const { input, password } = await import("@inquirer/prompts");
+    const email = await input({
+        message: "Email",
+        validate: validateEmail,
+    });
+    const pwd = await password({
+        message: "Password",
+        mask: "*",
+        validate: validatePassword,
+    });
+    // Register
+    const registerRes = await callApi(`${API_BASE}/auth/register`, "POST", { email, password: pwd });
+    const sessionToken = registerRes.data.sessionToken;
+    // Create API key using the session
+    const keyRes = await callApi(`${API_BASE}/auth/keys`, "POST", { name: "Setup CLI" }, sessionToken);
+    return {
+        apiKey: keyRes.data.key,
+        email: registerRes.data.user.email,
+    };
+}
+async function callApi(url, method, body, bearerToken) {
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (bearerToken) {
+        headers["Authorization"] = `Bearer ${bearerToken}`;
+    }
+    let res;
+    try {
+        res = await fetch(url, {
+            method,
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(15000),
+        });
+    }
+    catch (err) {
+        if (err instanceof TypeError) {
+            throw new Error("Can't reach api.uluops.ai — check your connection.");
+        }
+        throw err;
+    }
+    if (res.ok) {
+        return (await res.json());
+    }
+    // Handle known error codes
+    const errorBody = await res.json().catch(() => null);
+    const message = errorBody?.error?.message ?? errorBody?.message ?? `HTTP ${res.status}`;
+    if (res.status === 409) {
+        throw new Error(`Email already registered. Run without --signup and use your existing API key.`);
+    }
+    if (res.status === 429) {
+        const retryAfter = res.headers.get("Retry-After");
+        throw new Error(`Rate limited — try again${retryAfter ? ` in ${retryAfter}s` : " shortly"}.`);
+    }
+    if (res.status === 400) {
+        throw new Error(`Registration failed: ${message}`);
+    }
+    throw new Error(`Signup failed (${res.status}): ${message}`);
+}
+// Exported for testing
+export { validatePassword, validateEmail };

package/dist/steps/verify.d.ts

@@ -0,0 +1,10 @@
+interface VerifyResult {
+    ok: boolean;
+    checks: {
+        label: string;
+        passed: boolean;
+        detail?: string;
+    }[];
+}
+export declare function verify(): Promise<VerifyResult>;
+export {};

package/dist/steps/verify.js

@@ -0,0 +1,184 @@
+import { readdir, access } from "node:fs/promises";
+import { join } from "node:path";
+import { loadManifest } from "../lib/manifest.js";
+import { readConfig } from "../lib/config-merger.js";
+import { readSettings, hasUluopsHook } from "../lib/settings-merger.js";
+import { getMetricsToolDir, getSettingsPath } from "./metrics.js";
+export async function verify() {
+    const checks = [];
+    let allOk = true;
+    // 1. Manifest
+    const manifest = await loadManifest();
+    if (!manifest) {
+        checks.push({
+            label: "Manifest found",
+            passed: false,
+            detail: "No manifest — run npx @uluops/setup first",
+        });
+        return { ok: false, checks };
+    }
+    checks.push({
+        label: `Manifest found (v${manifest.version}, installed ${manifest.installedAt.split("T")[0]})`,
+        passed: true,
+    });
+    // 2. MCP config
+    const config = await readConfig(manifest.mcpConfigPath);
+    const hasTracker = !!config.mcpServers?.["uluops-tracker"];
+    const hasRegistry = !!config.mcpServers?.["uluops-registry"];
+    if (hasTracker && hasRegistry) {
+        checks.push({
+            label: `MCP config present in ${manifest.mcpConfigPath} (2 servers)`,
+            passed: true,
+        });
+    }
+    else {
+        checks.push({
+            label: "MCP config",
+            passed: false,
+            detail: `Missing: ${[!hasTracker && "tracker", !hasRegistry && "registry"].filter(Boolean).join(", ")}`,
+        });
+        allOk = false;
+    }
+    // 3. Agent files
+    const agentsDir = join(manifest.defsPath, "agents");
+    try {
+        const agentFiles = await readdir(agentsDir);
+        const found = manifest.agents.filter((a) => agentFiles.includes(a)).length;
+        if (found === manifest.agents.length) {
+            checks.push({
+                label: `${found}/${manifest.agents.length} agents in ${agentsDir}`,
+                passed: true,
+            });
+        }
+        else {
+            checks.push({
+                label: `${found}/${manifest.agents.length} agents in ${agentsDir}`,
+                passed: false,
+                detail: `Missing ${manifest.agents.length - found} agent(s)`,
+            });
+            allOk = false;
+        }
+    }
+    catch {
+        checks.push({
+            label: "Agent files",
+            passed: false,
+            detail: `Directory not found: ${agentsDir}`,
+        });
+        allOk = false;
+    }
+    // 4. Command files
+    const commandsDir = join(manifest.defsPath, "commands");
+    try {
+        let found = 0;
+        for (const cmd of manifest.commands) {
+            try {
+                await access(join(commandsDir, cmd));
+                found++;
+            }
+            catch {
+                // Missing
+            }
+        }
+        if (found === manifest.commands.length) {
+            checks.push({
+                label: `${found}/${manifest.commands.length} commands in ${commandsDir}`,
+                passed: true,
+            });
+        }
+        else {
+            checks.push({
+                label: `${found}/${manifest.commands.length} commands in ${commandsDir}`,
+                passed: false,
+                detail: `Missing ${manifest.commands.length - found} command(s)`,
+            });
+            allOk = false;
+        }
+    }
+    catch {
+        checks.push({
+            label: "Command files",
+            passed: false,
+            detail: `Directory not found: ${commandsDir}`,
+        });
+        allOk = false;
+    }
+    // 5. Agent metrics hook
+    if (manifest.metricsHookInstalled) {
+        const settings = await readSettings(getSettingsPath());
+        const hookPresent = hasUluopsHook(settings);
+        const toolDir = getMetricsToolDir();
+        let hookFilePresent = false;
+        try {
+            await access(join(toolDir, "dist", "hook.js"));
+            hookFilePresent = true;
+        }
+        catch {
+            // Missing
+        }
+        if (hookPresent && hookFilePresent) {
+            checks.push({
+                label: "Agent metrics hook configured and tool files present",
+                passed: true,
+            });
+        }
+        else {
+            const missing = [
+                !hookPresent && "hook not in settings.json",
+                !hookFilePresent && "hook.js not found",
+            ]
+                .filter(Boolean)
+                .join(", ");
+            checks.push({
+                label: "Agent metrics",
+                passed: false,
+                detail: missing,
+            });
+            allOk = false;
+        }
+    }
+    // 6. API connectivity
+    const apiKey = extractApiKey(config);
+    if (apiKey) {
+        try {
+            const res = await fetch("https://api.uluops.ai/api/v1/registry/users/me", {
+                headers: { Authorization: `Bearer ${apiKey}` },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (res.ok) {
+                const data = (await res.json());
+                checks.push({
+                    label: `API key valid${data.email ? ` (user: ${data.email})` : ""}`,
+                    passed: true,
+                });
+            }
+            else {
+                checks.push({
+                    label: "API key valid",
+                    passed: false,
+                    detail: `Server returned ${res.status}`,
+                });
+                allOk = false;
+            }
+        }
+        catch {
+            checks.push({
+                label: "API connectivity",
+                passed: false,
+                detail: "Can't reach api.uluops.ai",
+            });
+            allOk = false;
+        }
+    }
+    return { ok: allOk, checks };
+}
+function extractApiKey(config) {
+    const raw = config.mcpServers;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return process.env["ULUOPS_API_KEY"];
+    }
+    const servers = raw;
+    return (servers["uluops-registry"]?.env?.["ULUOPS_API_KEY"] ??
+        servers["uluops-tracker"]?.env?.["ULUOPS_TRACKER_API_KEY"] ??
+        process.env["ULUOPS_API_KEY"]);
+}

package/dist/test/auth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/auth.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { resolveApiKey } from "../steps/auth.js";
+afterEach(() => {
+    vi.unstubAllEnvs();
+});
+describe("resolveApiKey", () => {
+    it("uses --api-key flag when provided", async () => {
+        const result = await resolveApiKey({
+            apiKeyFlag: "ulr_test123",
+            skipValidation: true,
+        });
+        expect(result.apiKey).toBe("ulr_test123");
+        expect(result.email).toBeNull();
+    });
+    it("uses ULUOPS_API_KEY env var when no flag", async () => {
+        vi.stubEnv("ULUOPS_API_KEY", "ulr_envkey");
+        const result = await resolveApiKey({
+            skipValidation: true,
+        });
+        expect(result.apiKey).toBe("ulr_envkey");
+    });
+    it("throws when key does not start with ulr_", async () => {
+        await expect(resolveApiKey({
+            apiKeyFlag: "bad_key",
+            skipValidation: true,
+        })).rejects.toThrow("API keys start with ulr_");
+    });
+    it("throws when no key found and not interactive", async () => {
+        vi.stubEnv("ULUOPS_API_KEY", "");
+        await expect(resolveApiKey({
+            interactive: false,
+            skipValidation: true,
+        })).rejects.toThrow("No API key found");
+    });
+    it("flag takes priority over env var", async () => {
+        vi.stubEnv("ULUOPS_API_KEY", "ulr_envkey");
+        const result = await resolveApiKey({
+            apiKeyFlag: "ulr_flagkey",
+            skipValidation: true,
+        });
+        expect(result.apiKey).toBe("ulr_flagkey");
+    });
+});

package/dist/test/config-io.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/config-io.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { writeFile, unlink, mkdtemp, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { readConfig, writeConfig } from "../lib/config-merger.js";
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "uluops-config-io-"));
+});
+afterEach(async () => {
+    try {
+        const { readdir } = await import("node:fs/promises");
+        for (const f of await readdir(tmpDir)) {
+            await unlink(join(tmpDir, f));
+        }
+    }
+    catch {
+        // cleanup best-effort
+    }
+});
+describe("readConfig", () => {
+    it("returns empty object when file does not exist", async () => {
+        const result = await readConfig(join(tmpDir, "nonexistent.json"));
+        expect(result).toEqual({});
+    });
+    it("returns empty object on malformed JSON", async () => {
+        const path = join(tmpDir, "bad.json");
+        await writeFile(path, "{ invalid }");
+        const result = await readConfig(path);
+        expect(result).toEqual({});
+    });
+    it("parses valid JSON correctly", async () => {
+        const path = join(tmpDir, "good.json");
+        await writeFile(path, JSON.stringify({ mcpServers: {}, numStartups: 5 }));
+        const result = await readConfig(path);
+        expect(result.mcpServers).toEqual({});
+        expect(result.numStartups).toBe(5);
+    });
+});
+describe("writeConfig", () => {
+    it("writes formatted JSON with trailing newline", async () => {
+        const path = join(tmpDir, "output.json");
+        await writeConfig(path, { mcpServers: {}, foo: "bar" });
+        const raw = await readFile(path, "utf-8");
+        expect(raw).toMatch(/\n$/);
+        const parsed = JSON.parse(raw);
+        expect(parsed.foo).toBe("bar");
+    });
+    it("round-trips through readConfig", async () => {
+        const path = join(tmpDir, "roundtrip.json");
+        const config = { mcpServers: { test: { command: "echo", args: [], env: {} } }, extra: true };
+        await writeConfig(path, config);
+        const loaded = await readConfig(path);
+        expect(loaded).toEqual(config);
+    });
+});

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

@@ -0,0 +1 @@
+export {};