@uluops/setup 0.2.0

package/dist/lib/manifest.js

@@ -0,0 +1,34 @@
+import { readFile, writeFile, unlink } from "node:fs/promises";
+import { getManifestPath } from "./paths.js";
+function isManifest(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const m = obj;
+    return (typeof m["version"] === "string" &&
+        typeof m["installedAt"] === "string" &&
+        typeof m["mcpConfigPath"] === "string" &&
+        typeof m["defsPath"] === "string" &&
+        Array.isArray(m["agents"]) &&
+        Array.isArray(m["commands"]));
+}
+export async function loadManifest() {
+    try {
+        const raw = await readFile(getManifestPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        return isManifest(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveManifest(manifest) {
+    await writeFile(getManifestPath(), JSON.stringify(manifest, null, 2) + "\n");
+}
+export async function deleteManifest() {
+    try {
+        await unlink(getManifestPath());
+    }
+    catch {
+        // Already gone
+    }
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,14 @@
+/** Root of the npm package (where assets/ lives) */
+export declare const PACKAGE_ROOT: string;
+/** Assets directory containing pre-rendered .md files */
+export declare const ASSETS_DIR: string;
+export declare function getClaudeHome(): string;
+export declare function getClaudeJsonPath(): string;
+export declare function getLocalMcpPath(): string;
+export declare function getManifestPath(): string;
+export declare function getAgentsDir(localDefs: boolean): string;
+export declare function getCommandsDir(localDefs: boolean): string;
+export declare function getShellProfile(): {
+    shell: string;
+    path: string;
+} | null;

package/dist/lib/paths.js

@@ -0,0 +1,49 @@
+import { homedir, platform } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Root of the npm package (where assets/ lives) */
+export const PACKAGE_ROOT = join(__dirname, "..", "..");
+/** Assets directory containing pre-rendered .md files */
+export const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
+export function getClaudeHome() {
+    return join(homedir(), ".claude");
+}
+export function getClaudeJsonPath() {
+    return join(homedir(), ".claude.json");
+}
+export function getLocalMcpPath() {
+    return join(process.cwd(), ".mcp.json");
+}
+export function getManifestPath() {
+    return join(getClaudeHome(), "uluops-manifest.json");
+}
+export function getAgentsDir(localDefs) {
+    if (localDefs)
+        return join(process.cwd(), "uluops", "agents");
+    return join(getClaudeHome(), "agents");
+}
+export function getCommandsDir(localDefs) {
+    if (localDefs)
+        return join(process.cwd(), "uluops", "commands");
+    return join(getClaudeHome(), "commands");
+}
+export function getShellProfile() {
+    const shell = process.env["SHELL"] ?? "";
+    const home = homedir();
+    const os = platform();
+    if (shell.endsWith("/zsh")) {
+        return { shell: "zsh", path: join(home, ".zshrc") };
+    }
+    if (shell.endsWith("/bash")) {
+        const file = os === "darwin" ? ".bash_profile" : ".bashrc";
+        return { shell: "bash", path: join(home, file) };
+    }
+    if (shell.endsWith("/fish")) {
+        return {
+            shell: "fish",
+            path: join(home, ".config", "fish", "config.fish"),
+        };
+    }
+    return null;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Settings Merger
+ *
+ * Safe read/merge/remove for Claude Code's settings.json.
+ * Only touches UluOps-managed hook entries — all other settings preserved.
+ */
+interface HookEntry {
+    type: string;
+    command: string;
+    timeout?: number;
+}
+interface HookMatcher {
+    matcher?: string;
+    hooks: HookEntry[];
+}
+interface ClaudeSettings {
+    permissions?: Record<string, unknown>;
+    hooks?: Record<string, HookMatcher[]>;
+    [key: string]: unknown;
+}
+/**
+ * Read an existing settings.json, or return empty object if it doesn't exist.
+ */
+export declare function readSettings(path: string): Promise<ClaudeSettings>;
+/**
+ * Write settings back to file with stable formatting.
+ */
+export declare function writeSettings(path: string, settings: ClaudeSettings): Promise<void>;
+/**
+ * Merge the UluOps SubagentStop hook into settings, preserving all other
+ * hooks and settings. If a UluOps hook already exists, it is replaced.
+ */
+export declare function mergeUluopsHook(settings: ClaudeSettings, hookCommand: string): ClaudeSettings;
+/**
+ * Remove UluOps hook entries from settings. If SubagentStop becomes empty,
+ * the key is removed. If hooks becomes empty, the key is removed.
+ */
+export declare function removeUluopsHook(settings: ClaudeSettings): ClaudeSettings;
+/**
+ * Check if a UluOps hook is configured in settings.
+ */
+export declare function hasUluopsHook(settings: ClaudeSettings): boolean;
+export {};

package/dist/lib/settings-merger.js

@@ -0,0 +1,91 @@
+/**
+ * Settings Merger
+ *
+ * Safe read/merge/remove for Claude Code's settings.json.
+ * Only touches UluOps-managed hook entries — all other settings preserved.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+/** Marker embedded in hook commands to identify UluOps-managed entries */
+const ULUOPS_HOOK_MARKER = "tools/agent-metrics";
+/**
+ * Read an existing settings.json, or return empty object if it doesn't exist.
+ */
+export async function readSettings(path) {
+    try {
+        const raw = await readFile(path, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write settings back to file with stable formatting.
+ */
+export async function writeSettings(path, settings) {
+    await writeFile(path, JSON.stringify(settings, null, 2) + "\n");
+}
+/**
+ * Merge the UluOps SubagentStop hook into settings, preserving all other
+ * hooks and settings. If a UluOps hook already exists, it is replaced.
+ */
+export function mergeUluopsHook(settings, hookCommand) {
+    const hooks = settings.hooks ?? {};
+    const existing = hooks["SubagentStop"] ?? [];
+    // Remove any existing UluOps hook entries
+    const filtered = existing.filter((m) => !m.hooks.some((h) => h.command.includes(ULUOPS_HOOK_MARKER)));
+    // Add the new UluOps hook
+    const uluopsHook = {
+        hooks: [
+            {
+                type: "command",
+                command: hookCommand,
+                timeout: 30,
+            },
+        ],
+    };
+    return {
+        ...settings,
+        hooks: {
+            ...hooks,
+            SubagentStop: [...filtered, uluopsHook],
+        },
+    };
+}
+/**
+ * Remove UluOps hook entries from settings. If SubagentStop becomes empty,
+ * the key is removed. If hooks becomes empty, the key is removed.
+ */
+export function removeUluopsHook(settings) {
+    const hooks = settings.hooks;
+    if (!hooks)
+        return settings;
+    const subagentStop = hooks["SubagentStop"];
+    if (!subagentStop)
+        return settings;
+    const filtered = subagentStop.filter((m) => !m.hooks.some((h) => h.command.includes(ULUOPS_HOOK_MARKER)));
+    const updatedHooks = { ...hooks };
+    if (filtered.length === 0) {
+        delete updatedHooks["SubagentStop"];
+    }
+    else {
+        updatedHooks["SubagentStop"] = filtered;
+    }
+    const result = { ...settings };
+    if (Object.keys(updatedHooks).length === 0) {
+        delete result.hooks;
+    }
+    else {
+        result.hooks = updatedHooks;
+    }
+    return result;
+}
+/**
+ * Check if a UluOps hook is configured in settings.
+ */
+export function hasUluopsHook(settings) {
+    const subagentStop = settings.hooks?.["SubagentStop"];
+    if (!subagentStop)
+        return false;
+    return subagentStop.some((m) => m.hooks.some((h) => h.command.includes(ULUOPS_HOOK_MARKER)));
+}

package/dist/steps/agents.d.ts

@@ -0,0 +1,8 @@
+export interface AgentsResult {
+    copied: number;
+    skipped: number;
+    removed: number;
+    files: string[];
+}
+export declare function installAgents(localDefs: boolean, dryRun: boolean, existingManifestAgents?: string[]): Promise<AgentsResult>;
+export declare function uninstallAgents(files: string[], defsPath: string): Promise<number>;

package/dist/steps/agents.js

@@ -0,0 +1,14 @@
+import { join } from "node:path";
+import { ASSETS_DIR, getAgentsDir } from "../lib/paths.js";
+import { syncAssets, unlinkFiles } from "../lib/file-ops.js";
+export async function installAgents(localDefs, dryRun, existingManifestAgents) {
+    return syncAssets({
+        srcDir: join(ASSETS_DIR, "agents"),
+        destDir: getAgentsDir(localDefs),
+        dryRun,
+        oldManifestFiles: existingManifestAgents,
+    });
+}
+export async function uninstallAgents(files, defsPath) {
+    return unlinkFiles(join(defsPath, "agents"), files);
+}

package/dist/steps/auth.d.ts

@@ -0,0 +1,12 @@
+export interface AuthResult {
+    apiKey: string;
+    email: string | null;
+}
+/**
+ * Resolve API key from flags, env, credentials file, or interactive prompt.
+ */
+export declare function resolveApiKey(options: {
+    apiKeyFlag?: string;
+    skipValidation?: boolean;
+    interactive?: boolean;
+}): Promise<AuthResult>;

package/dist/steps/auth.js

@@ -0,0 +1,80 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/**
+ * Resolve API key from flags, env, credentials file, or interactive prompt.
+ */
+export async function resolveApiKey(options) {
+    let apiKey = options.apiKeyFlag;
+    // 1. Flag
+    if (!apiKey) {
+        // 2. Env var
+        apiKey = process.env["ULUOPS_API_KEY"];
+    }
+    if (!apiKey) {
+        // 3. Credentials file
+        apiKey = await readCredentialsFile();
+    }
+    if (!apiKey) {
+        // 4. Interactive prompt
+        if (!options.interactive) {
+            throw new Error("No API key found. Pass --api-key or set ULUOPS_API_KEY. Get one at app.uluops.ai/settings/api-keys");
+        }
+        const { input } = await import("@inquirer/prompts");
+        apiKey = await input({
+            message: "Enter your UluOps API key",
+            validate: (val) => {
+                if (!val.trim())
+                    return "Get a key at app.uluops.ai/settings/api-keys";
+                if (!val.startsWith("ulr_"))
+                    return "API keys start with ulr_ — get one at app.uluops.ai/settings/api-keys";
+                return true;
+            },
+        });
+    }
+    if (!apiKey?.startsWith("ulr_")) {
+        throw new Error("API keys start with ulr_ — get one at app.uluops.ai/settings/api-keys");
+    }
+    // Validate against server
+    if (!options.skipValidation) {
+        const result = await validateKey(apiKey);
+        return { apiKey, email: result.email };
+    }
+    return { apiKey, email: null };
+}
+async function readCredentialsFile() {
+    try {
+        const credsPath = join(homedir(), ".uluops", "credentials.json");
+        const raw = await readFile(credsPath, "utf-8");
+        const creds = JSON.parse(raw);
+        const defaultProfile = creds["default"];
+        return defaultProfile?.apiKey ?? defaultProfile?.api_key;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function validateKey(apiKey) {
+    const url = "https://api.uluops.ai/api/v1/registry/users/me";
+    try {
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (res.status === 401) {
+            throw new Error("Invalid API key — generate a new one at app.uluops.ai/settings/api-keys");
+        }
+        if (!res.ok) {
+            throw new Error(`API returned ${res.status}. Try --skip-validation to continue offline.`);
+        }
+        const data = (await res.json());
+        return { email: data.email ?? null };
+    }
+    catch (err) {
+        // fetch() throws TypeError for network failures (ENOTFOUND, ECONNREFUSED).
+        // Re-thrown errors from the res.status checks above are plain Error instances.
+        if (err instanceof TypeError) {
+            throw new Error("Can't reach api.uluops.ai — check your connection. Use --skip-validation to continue offline.");
+        }
+        throw err;
+    }
+}

package/dist/steps/commands.d.ts

@@ -0,0 +1,9 @@
+export interface CommandsResult {
+    agentCommands: number;
+    workflowCommands: number;
+    skipped: number;
+    removed: number;
+    files: string[];
+}
+export declare function installCommands(localDefs: boolean, dryRun: boolean, existingManifestCommands?: string[]): Promise<CommandsResult>;
+export declare function uninstallCommands(files: string[], defsPath: string): Promise<number>;

package/dist/steps/commands.js

@@ -0,0 +1,69 @@
+import { readdir, mkdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { ASSETS_DIR, getCommandsDir } from "../lib/paths.js";
+import { copyIfChanged } from "../lib/file-ops.js";
+const SUBDIRS = ["agents", "workflows"];
+export async function installCommands(localDefs, dryRun, existingManifestCommands) {
+    const srcBase = join(ASSETS_DIR, "commands");
+    const destBase = getCommandsDir(localDefs);
+    let agentCommands = 0;
+    let workflowCommands = 0;
+    let skipped = 0;
+    const allFiles = [];
+    for (const subdir of SUBDIRS) {
+        const srcDir = join(srcBase, subdir);
+        const destDir = join(destBase, subdir);
+        if (!dryRun) {
+            await mkdir(destDir, { recursive: true });
+        }
+        let files;
+        try {
+            files = (await readdir(srcDir)).filter((f) => f.endsWith(".md"));
+        }
+        catch {
+            continue;
+        }
+        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
+                    workflowCommands++;
+            }
+            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
+                    }
+                }
+                removed++;
+            }
+        }
+    }
+    return {
+        agentCommands,
+        workflowCommands,
+        skipped,
+        removed,
+        files: allFiles,
+    };
+}
+export async function uninstallCommands(files, defsPath) {
+    const { unlinkFiles } = await import("../lib/file-ops.js");
+    return unlinkFiles(join(defsPath, "commands"), files);
+}

package/dist/steps/detect.d.ts

@@ -0,0 +1,9 @@
+export interface Environment {
+    os: "linux" | "darwin" | "win32";
+    isWsl: boolean;
+    shell: string | null;
+    shellProfile: string | null;
+    nodeVersion: string;
+    claudeHomeExists: boolean;
+}
+export declare function detect(): Promise<Environment>;

package/dist/steps/detect.js

@@ -0,0 +1,30 @@
+import { platform, release } from "node:os";
+import { access } from "node:fs/promises";
+import { getClaudeHome, getShellProfile } from "../lib/paths.js";
+const SUPPORTED_PLATFORMS = new Set(["linux", "darwin", "win32"]);
+export async function detect() {
+    const p = platform();
+    if (!SUPPORTED_PLATFORMS.has(p)) {
+        throw new Error(`Unsupported platform: ${p}. Expected linux, darwin, or win32.`);
+    }
+    const os = p;
+    const isWsl = os === "linux" && release().toLowerCase().includes("microsoft");
+    const profile = getShellProfile();
+    const nodeVersion = process.version;
+    let claudeHomeExists = false;
+    try {
+        await access(getClaudeHome());
+        claudeHomeExists = true;
+    }
+    catch {
+        // Does not exist
+    }
+    return {
+        os,
+        isWsl,
+        shell: profile?.shell ?? null,
+        shellProfile: profile?.path ?? null,
+        nodeVersion,
+        claudeHomeExists,
+    };
+}

package/dist/steps/mcp.d.ts

@@ -0,0 +1,6 @@
+export interface McpResult {
+    configPath: string;
+    scope: "global" | "local";
+}
+export declare function installMcp(apiKey: string, scope: "global" | "local", dryRun: boolean): Promise<McpResult>;
+export declare function uninstallMcp(configPath: string): Promise<void>;

package/dist/steps/mcp.js

@@ -0,0 +1,40 @@
+import { readFile, writeFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import { readConfig, mergeUluopsMcp, removeUluopsMcp, writeConfig, } from "../lib/config-merger.js";
+import { getClaudeJsonPath, getLocalMcpPath } from "../lib/paths.js";
+export async function installMcp(apiKey, scope, dryRun) {
+    const configPath = scope === "global" ? getClaudeJsonPath() : getLocalMcpPath();
+    const config = await readConfig(configPath);
+    const merged = mergeUluopsMcp(config, apiKey);
+    if (!dryRun) {
+        await writeConfig(configPath, merged);
+    }
+    // If local scope in a git repo, add .mcp.json to .gitignore
+    if (scope === "local" && !dryRun) {
+        await addToGitignore();
+    }
+    return { configPath, scope };
+}
+export async function uninstallMcp(configPath) {
+    const config = await readConfig(configPath);
+    const cleaned = removeUluopsMcp(config);
+    await writeConfig(configPath, cleaned);
+}
+async function addToGitignore() {
+    const gitignorePath = join(process.cwd(), ".gitignore");
+    try {
+        await access(join(process.cwd(), ".git"));
+    }
+    catch {
+        return; // Not a git repo
+    }
+    try {
+        const content = await readFile(gitignorePath, "utf-8");
+        if (content.includes(".mcp.json"))
+            return;
+        await writeFile(gitignorePath, content.trimEnd() + "\n.mcp.json\n");
+    }
+    catch {
+        await writeFile(gitignorePath, ".mcp.json\n");
+    }
+}

package/dist/steps/metrics.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Metrics Step
+ *
+ * Installs agent-metrics tool files to ~/.claude/tools/agent-metrics/
+ * and configures the SubagentStop hook in settings.json for auto-capture.
+ */
+/** Where agent-metrics dist files are installed */
+export declare function getMetricsToolDir(): string;
+/** Path to Claude Code's settings.json */
+export declare function getSettingsPath(): string;
+export interface MetricsResult {
+    toolFilesCopied: number;
+    hookConfigured: boolean;
+}
+/**
+ * Install agent-metrics: copy tool files and configure SubagentStop hook.
+ */
+export declare function installMetrics(dryRun: boolean): Promise<MetricsResult>;
+/**
+ * Uninstall agent-metrics: remove hook from settings and optionally remove tool files.
+ */
+export declare function uninstallMetrics(dryRun: boolean): Promise<void>;