@unerr-ai/unerr 0.1.0 → 0.1.1

package/dist/daemon/process-manager.js

@@ -0,0 +1,299 @@
+/**
+ * Process manager — spawn, stop, monitor, and idle-sweep per-repo child processes.
+ *
+ * Each managed repo gets a single Node.js child process (fork of `unerr --daemon-child`).
+ * Communication is via Node.js IPC channel (`process.send` / `process.on('message')`).
+ *
+ * The idle sweep runs every 60s. A repo process is eligible for stop when:
+ *   - Zero active connections (no IDE bridges connected)
+ *   - lastActivity older than the repo's idleTimeout
+ *
+ * Child lifecycle:
+ *   fork() → child sends { type: "ready", sock } → status = "running"
+ *   child sends { type: "activity" } → updates lastActivity
+ *   parent sends { type: "shutdown" } → child snapshots + exits
+ *   child exits → status = "stopped", cleanup
+ */
+import { fork } from "node:child_process";
+import { readNeedsInput, readRegistry, writeRegistry } from "./registry.js";
+// ── Process Manager ─────────────────────────────────────────────
+const IDLE_SWEEP_INTERVAL_MS = 60_000;
+const READY_TIMEOUT_MS = 30_000;
+export class ProcessManager {
+    repos = new Map();
+    sweepTimer = null;
+    onEvent = null;
+    stopped = false;
+    /** Register an event handler for lifecycle events (logging, dashboard SSE). */
+    setEventHandler(handler) {
+        this.onEvent = handler;
+    }
+    /** Start the idle sweep timer. */
+    startIdleSweep() {
+        if (this.sweepTimer)
+            return;
+        this.sweepTimer = setInterval(() => this.runIdleSweep(), IDLE_SWEEP_INTERVAL_MS);
+        this.sweepTimer.unref();
+    }
+    /** Stop the idle sweep timer. */
+    stopIdleSweep() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = null;
+        }
+    }
+    /**
+     * Ensure a repo process is running. If already running, returns the sock path.
+     * If stopped, spawns it and waits for the "ready" IPC message.
+     */
+    async ensure(repoPath) {
+        const existing = this.repos.get(repoPath);
+        if (existing?.status === "running" && existing.sock) {
+            return existing.sock;
+        }
+        if (existing?.status === "starting") {
+            return this.waitForReady(existing);
+        }
+        return this.spawn(repoPath);
+    }
+    /** Record that a bridge connected to this repo. */
+    connect(repoPath) {
+        const repo = this.repos.get(repoPath);
+        if (repo) {
+            repo.connections++;
+            repo.lastActivity = Date.now();
+        }
+    }
+    /** Record that a bridge disconnected from this repo. */
+    disconnect(repoPath) {
+        const repo = this.repos.get(repoPath);
+        if (repo && repo.connections > 0) {
+            repo.connections--;
+        }
+    }
+    /** Record activity (tool call) for this repo. */
+    recordActivity(repoPath) {
+        const repo = this.repos.get(repoPath);
+        if (repo) {
+            repo.lastActivity = Date.now();
+            this.onEvent?.("activity", repo);
+        }
+    }
+    /** Gracefully stop a specific repo's process. */
+    async stop(repoPath) {
+        const repo = this.repos.get(repoPath);
+        if (!repo?.child || repo.status === "stopped")
+            return;
+        await this.shutdownChild(repo);
+    }
+    /** Gracefully stop ALL children, then clean up. */
+    async shutdownAll() {
+        this.stopped = true;
+        this.stopIdleSweep();
+        const shutdowns = [];
+        for (const repo of this.repos.values()) {
+            if (repo.child && repo.status !== "stopped") {
+                shutdowns.push(this.shutdownChild(repo));
+            }
+        }
+        await Promise.allSettled(shutdowns);
+    }
+    /** Get status for all managed repos (for daemon status / dashboard). */
+    getStatus() {
+        const registry = readRegistry();
+        const entries = [];
+        for (const regEntry of registry.repos) {
+            const managed = this.repos.get(regEntry.path);
+            entries.push({
+                path: regEntry.path,
+                label: regEntry.label,
+                status: managed?.status ?? "stopped",
+                pid: managed?.pid ?? null,
+                memory: managed?.memory ?? null,
+                idle: managed?.lastActivity
+                    ? Math.round((Date.now() - managed.lastActivity) / 1000)
+                    : null,
+                connections: managed?.connections ?? 0,
+                lastActivity: managed?.lastActivity
+                    ? new Date(managed.lastActivity).toISOString()
+                    : regEntry.lastActivity,
+                entityCount: managed?.entities ?? null,
+                edgeCount: managed?.edges ?? null,
+                needsInput: managed?.needsInput ?? readNeedsInput(regEntry.path),
+            });
+        }
+        return entries;
+    }
+    /** Get a managed repo record (for internal use). */
+    getManaged(repoPath) {
+        return this.repos.get(repoPath);
+    }
+    // ── Internal: spawn ─────────────────────────────────────────
+    async spawn(repoPath) {
+        const reg = readRegistry();
+        const entry = reg.repos.find((r) => r.path === repoPath);
+        const repo = {
+            path: repoPath,
+            label: entry?.label ?? repoPath.split("/").pop() ?? repoPath,
+            idleTimeout: entry?.idleTimeout ?? 1800,
+            status: "starting",
+            child: null,
+            pid: null,
+            sock: null,
+            connections: 0,
+            lastActivity: Date.now(),
+            startedAt: Date.now(),
+            memory: null,
+            entities: null,
+            edges: null,
+            needsInput: [],
+            readyResolve: null,
+            readyReject: null,
+        };
+        this.repos.set(repoPath, repo);
+        const unerrBin = process.argv[1];
+        const child = fork(unerrBin, ["--daemon-child"], {
+            cwd: repoPath,
+            stdio: ["ignore", "ignore", "inherit", "ipc"],
+            detached: false,
+            env: {
+                ...process.env,
+                UNERR_DAEMON_CHILD: "1",
+                UNERR_REPO_PATH: repoPath,
+            },
+        });
+        repo.child = child;
+        repo.pid = child.pid ?? null;
+        child.on("message", (msg) => {
+            this.handleChildMessage(repoPath, msg);
+        });
+        child.on("exit", (code, signal) => {
+            this.handleChildExit(repoPath, code, signal);
+        });
+        child.on("error", (err) => {
+            repo.status = "error";
+            repo.readyReject?.(err);
+            repo.readyResolve = null;
+            repo.readyReject = null;
+            this.onEvent?.("error", repo, err.message);
+        });
+        // Update registry lastStarted
+        if (entry) {
+            entry.lastStarted = new Date().toISOString();
+            writeRegistry(reg);
+        }
+        return this.waitForReady(repo);
+    }
+    waitForReady(repo) {
+        if (repo.sock && repo.status === "running") {
+            return Promise.resolve(repo.sock);
+        }
+        return new Promise((resolve, reject) => {
+            repo.readyResolve = resolve;
+            repo.readyReject = reject;
+            const timer = setTimeout(() => {
+                repo.readyReject?.(new Error(`Repo process ${repo.path} failed to become ready in ${READY_TIMEOUT_MS}ms`));
+                repo.readyResolve = null;
+                repo.readyReject = null;
+                if (repo.status === "starting") {
+                    repo.status = "error";
+                    repo.child?.kill("SIGTERM");
+                }
+            }, READY_TIMEOUT_MS);
+            timer.unref();
+        });
+    }
+    // ── Internal: IPC handling ──────────────────────────────────
+    handleChildMessage(repoPath, msg) {
+        const repo = this.repos.get(repoPath);
+        if (!repo)
+            return;
+        switch (msg.type) {
+            case "ready":
+                repo.sock = msg.sock;
+                repo.status = "running";
+                repo.readyResolve?.(msg.sock);
+                repo.readyResolve = null;
+                repo.readyReject = null;
+                this.onEvent?.("started", repo);
+                break;
+            case "activity":
+                repo.lastActivity = Date.now();
+                this.onEvent?.("activity", repo);
+                break;
+            case "stats":
+                repo.entities = msg.entities;
+                repo.edges = msg.edges;
+                repo.memory = msg.memory;
+                break;
+            case "needs_input":
+                repo.needsInput = msg.signals;
+                break;
+        }
+    }
+    handleChildExit(repoPath, code, signal) {
+        const repo = this.repos.get(repoPath);
+        if (!repo)
+            return;
+        const prev = repo.status;
+        repo.status = "stopped";
+        repo.child = null;
+        repo.pid = null;
+        repo.sock = null;
+        repo.connections = 0;
+        if (prev === "starting") {
+            repo.readyReject?.(new Error(`Child exited during startup (code=${code}, signal=${signal})`));
+            repo.readyResolve = null;
+            repo.readyReject = null;
+        }
+        this.onEvent?.("stopped", repo, `code=${code}, signal=${signal}`);
+    }
+    // ── Internal: graceful shutdown ─────────────────────────────
+    shutdownChild(repo) {
+        return new Promise((resolve) => {
+            if (!repo.child) {
+                resolve();
+                return;
+            }
+            const child = repo.child;
+            const timer = setTimeout(() => {
+                if (!child.killed) {
+                    child.kill("SIGKILL");
+                }
+                resolve();
+            }, 10_000);
+            timer.unref();
+            child.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            try {
+                child.send({ type: "shutdown" });
+            }
+            catch {
+                child.kill("SIGTERM");
+            }
+        });
+    }
+    // ── Internal: idle sweep ────────────────────────────────────
+    runIdleSweep() {
+        if (this.stopped)
+            return;
+        const now = Date.now();
+        for (const repo of this.repos.values()) {
+            if (repo.status !== "running")
+                continue;
+            if (repo.connections > 0)
+                continue;
+            if (repo.idleTimeout === 0)
+                continue;
+            const idleMs = now - repo.lastActivity;
+            const timeoutMs = repo.idleTimeout * 1000;
+            if (idleMs >= timeoutMs) {
+                this.shutdownChild(repo).catch(() => {
+                    /* best-effort */
+                });
+            }
+        }
+    }
+}

package/dist/daemon/protocol.js

@@ -0,0 +1,23 @@
+/**
+ * unerrd protocol — newline-delimited JSON over UDS (~/.unerr/unerrd.sock).
+ *
+ * Three communication planes:
+ *   1. Bridge → unerrd (ensure/connect/disconnect/activity)
+ *   2. Daemon CLI → unerrd (status/add/remove/stop/shutdown)
+ *   3. unerrd ↔ child repo processes (ready/activity/stats/shutdown)
+ */
+export const JAVA_BUILD_TOOLS = [
+    "Maven",
+    "Gradle",
+    "Bazel",
+    "Sbt",
+];
+// ── Constants ───────────────────────────────────────────────────
+/** Default idle timeout for repos (30 minutes in seconds). */
+export const DEFAULT_IDLE_TIMEOUT_S = 1800;
+/** Default warm-start budget (top N most-recently-active repos). */
+export const DEFAULT_WARM_START_BUDGET = 3;
+/** Default warm-start delay after daemon boot (ms). */
+export const DEFAULT_WARM_START_DELAY_MS = 30_000;
+/** Default warm-start idle-days cutoff. */
+export const DEFAULT_WARM_START_IDLE_DAYS = 14;

package/dist/daemon/registry.js

@@ -0,0 +1,270 @@
+/**
+ * Daemon registry — CRUD operations on ~/.unerr/repos.json.
+ *
+ * The registry is the single source of truth for which repos are managed
+ * by the unerrd supervisor. Each repo entry stores:
+ *   - Absolute path (identity anchor — P3: directory is identity)
+ *   - Timestamps (addedAt, lastStarted, lastActivity)
+ *   - Derived label (basename for display, guaranteed unique in registry)
+ *   - Settings (idleTimeout, javaBuildTool, autostart, future keys)
+ *
+ * All repo-specific artifacts live in <repo>/.unerr/. The registry only
+ * stores paths + metadata. Deleting ~/.unerr/ loses registration, not
+ * intelligence — each repo's .unerr/ is intact.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { DEFAULT_IDLE_TIMEOUT_S, } from "./protocol.js";
+// ── Paths ───────────────────────────────────────────────────────
+/** Global unerr directory — supervisor state only. Respects UNERR_HOME for testing. */
+export function globalDir() {
+    const override = process.env.UNERR_HOME;
+    if (override)
+        return join(override, ".unerr");
+    return join(homedir(), ".unerr");
+}
+/** Path to the registry file. */
+export function registryPath() {
+    return join(globalDir(), "repos.json");
+}
+// ── Read / Write ────────────────────────────────────────────────
+/** Read the registry from disk. Returns empty registry if missing. */
+export function readRegistry() {
+    try {
+        const raw = readFileSync(registryPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || !Array.isArray(parsed.repos)) {
+            return { version: 1, repos: [] };
+        }
+        return parsed;
+    }
+    catch {
+        return { version: 1, repos: [] };
+    }
+}
+/** Write the registry atomically (write-then-rename is overkill for <100 entries). */
+export function writeRegistry(reg) {
+    const dir = globalDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(registryPath(), `${JSON.stringify(reg, null, 2)}\n`);
+}
+// ── Label generation ────────────────────────────────────────────
+/**
+ * Derive a unique, human-friendly label from the repo path.
+ * Falls back to `<parent>-<basename>` then `<basename>-<N>` on collision.
+ */
+export function deriveLabel(repoPath, existing) {
+    const base = basename(repoPath);
+    const taken = new Set(existing.map((e) => e.label));
+    if (!taken.has(base))
+        return base;
+    const parentBase = `${basename(dirname(repoPath))}-${base}`;
+    if (!taken.has(parentBase))
+        return parentBase;
+    for (let i = 2; i < 100; i++) {
+        const candidate = `${base}-${i}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    return `${base}-${Date.now()}`;
+}
+/**
+ * Add a repo to the registry.
+ *
+ * Steps:
+ *   1. Resolve to absolute path
+ *   2. Check if already registered (idempotent — returns existing entry)
+ *   3. Parent-directory conflict check
+ *   4. Child-directory overlap scan
+ *   5. Add entry with settings
+ *   6. Ensure <repo>/.unerr/ exists
+ *   7. Mirror settings to <repo>/.unerr/config.json
+ */
+export function addRepo(rawPath, settings = {}, opts = {}) {
+    const absPath = resolve(rawPath);
+    const reg = readRegistry();
+    // Already registered — idempotent
+    const existing = reg.repos.find((r) => r.path === absPath);
+    if (existing) {
+        return { ok: true, entry: existing, created: false };
+    }
+    // Parent-directory conflict: walk up from absPath checking for existing registrations
+    if (!opts.skipParentCheck) {
+        const parentConflict = detectParentConflict(absPath, reg.repos);
+        if (parentConflict) {
+            return {
+                ok: false,
+                error: `Parent directory ${parentConflict} already registered with unerrd. That process covers this subdirectory.`,
+                parentConflict,
+            };
+        }
+    }
+    // Child-directory overlap: any registered repo that is a subdirectory of absPath
+    if (!opts.skipChildCheck) {
+        const childConflicts = detectChildConflicts(absPath, reg.repos);
+        if (childConflicts.length > 0) {
+            return {
+                ok: false,
+                error: `Subdirectories already registered: ${childConflicts.join(", ")}. Remove them first or use --skip-child-check.`,
+                childConflicts,
+            };
+        }
+    }
+    const entry = {
+        path: absPath,
+        addedAt: new Date().toISOString(),
+        lastStarted: null,
+        lastActivity: null,
+        idleTimeout: settings.idleTimeout ?? DEFAULT_IDLE_TIMEOUT_S,
+        label: deriveLabel(absPath, reg.repos),
+        settings: buildSettings(settings),
+    };
+    reg.repos.push(entry);
+    writeRegistry(reg);
+    // Ensure <repo>/.unerr/ exists
+    const unerrDir = join(absPath, ".unerr");
+    if (!existsSync(unerrDir)) {
+        mkdirSync(unerrDir, { recursive: true });
+    }
+    // Mirror settings to local config
+    mirrorSettingsToLocal(absPath, entry.settings);
+    return { ok: true, entry, created: true };
+}
+/** Remove a repo from the registry by absolute path. */
+export function removeRepo(rawPath) {
+    const absPath = resolve(rawPath);
+    const reg = readRegistry();
+    const before = reg.repos.length;
+    reg.repos = reg.repos.filter((r) => r.path !== absPath);
+    if (reg.repos.length === before)
+        return false;
+    writeRegistry(reg);
+    return true;
+}
+/** Find a repo entry by path or label. */
+export function findRepo(pathOrLabel) {
+    const reg = readRegistry();
+    const abs = resolve(pathOrLabel);
+    return (reg.repos.find((r) => r.path === abs) ??
+        reg.repos.find((r) => r.label === pathOrLabel));
+}
+/** List all registered repos. */
+export function listRepos() {
+    return readRegistry().repos;
+}
+// ── Config update ───────────────────────────────────────────────
+/**
+ * Update settings on an existing repo entry.
+ * Writes to both registry and <repo>/.unerr/config.json.
+ * Returns the updated entry, or null if not found.
+ */
+export function updateRepoSettings(rawPath, patch) {
+    const absPath = resolve(rawPath);
+    const reg = readRegistry();
+    const entry = reg.repos.find((r) => r.path === absPath);
+    if (!entry)
+        return null;
+    // Apply patch
+    for (const [k, v] of Object.entries(patch)) {
+        entry.settings[k] = v;
+        // Keep top-level shorthand fields in sync
+        if (k === "idleTimeout" && typeof v === "number") {
+            entry.idleTimeout = v;
+        }
+    }
+    writeRegistry(reg);
+    mirrorSettingsToLocal(absPath, entry.settings);
+    return entry;
+}
+// ── Parent / child detection ────────────────────────────────────
+/**
+ * Walk up from `target` checking if any parent directory is registered.
+ * Returns the conflicting parent path, or null.
+ */
+export function detectParentConflict(target, repos) {
+    const registeredPaths = new Set(repos.map((r) => r.path));
+    let current = dirname(target);
+    const root = dirname(current) === current ? current : undefined;
+    while (current !== root) {
+        if (registeredPaths.has(current))
+            return current;
+        // Also check for .unerr/ directory with a running process
+        if (existsSync(join(current, ".unerr", "state", "proxy.pid"))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Find registered repos that are subdirectories of `target`.
+ * Returns paths of conflicting children.
+ */
+export function detectChildConflicts(target, repos) {
+    const normalized = target.endsWith("/") ? target : `${target}/`;
+    return repos.filter((r) => r.path.startsWith(normalized)).map((r) => r.path);
+}
+// ── Needs-input signals ─────────────────────────────────────────
+/**
+ * Read needs_input signals from <repo>/.unerr/needs-input.json.
+ * Written by the per-repo process when auto-detection picks under ambiguity.
+ */
+export function readNeedsInput(repoPath) {
+    try {
+        const p = join(repoPath, ".unerr", "needs-input.json");
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Write needs_input signals to <repo>/.unerr/needs-input.json.
+ * Called by the per-repo process (e.g., Java build tool auto-detection).
+ */
+export function writeNeedsInput(repoPath, signals) {
+    const dir = join(repoPath, ".unerr");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "needs-input.json"), `${JSON.stringify(signals, null, 2)}\n`);
+}
+// ── Internal helpers ────────────────────────────────────────────
+/** Build a clean settings object from partial input. */
+function buildSettings(partial) {
+    const s = {};
+    for (const [k, v] of Object.entries(partial)) {
+        if (v !== undefined && k !== "idleTimeout") {
+            s[k] = v;
+        }
+    }
+    return s;
+}
+/**
+ * Mirror settings from registry into <repo>/.unerr/config.json.
+ * Merges with any existing config (preserves repoId, mode, etc.).
+ */
+function mirrorSettingsToLocal(repoPath, settings) {
+    const configPath = join(repoPath, ".unerr", "config.json");
+    let config = {};
+    try {
+        config = JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        // Fresh config
+    }
+    for (const [k, v] of Object.entries(settings)) {
+        if (v !== undefined) {
+            config[k] = v;
+        }
+    }
+    const dir = join(repoPath, ".unerr");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+}

package/dist/daemon/settings-schema.js

@@ -0,0 +1,72 @@
+/**
+ * Settings schema — allow-list + validation for per-repo daemon settings.
+ *
+ * Every key that `daemon add --<key>=<value>` or `daemon config --<key>=<value>`
+ * accepts is registered here. The registry stores arbitrary `settings: Record<…>`
+ * so new keys require zero schema migration — just add a row to SETTINGS_SCHEMA.
+ */
+import { JAVA_BUILD_TOOLS } from "./protocol.js";
+const parsePositiveInt = (raw) => {
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0) {
+        throw new Error(`Expected non-negative integer, got "${raw}"`);
+    }
+    return n;
+};
+const parseJavaBuildTool = (raw) => {
+    const normalized = raw.charAt(0).toUpperCase() + raw.slice(1).toLowerCase();
+    if (!JAVA_BUILD_TOOLS.includes(normalized)) {
+        throw new Error(`Invalid Java build tool "${raw}". Valid: ${JAVA_BUILD_TOOLS.join(", ")}`);
+    }
+    return normalized;
+};
+const parseAutostart = (raw) => {
+    const valid = ["eager", "auto", "never"];
+    const lower = raw.toLowerCase();
+    if (!valid.includes(lower)) {
+        throw new Error(`Invalid autostart value "${raw}". Valid: ${valid.join(", ")}`);
+    }
+    return lower;
+};
+export const SETTINGS_SCHEMA = [
+    {
+        flag: "idle-timeout",
+        key: "idleTimeout",
+        description: "Idle timeout in seconds before auto-stop (0 = never)",
+        parse: parsePositiveInt,
+    },
+    {
+        flag: "java-build-tool",
+        key: "javaBuildTool",
+        description: `Java build tool override (${JAVA_BUILD_TOOLS.join("|")})`,
+        parse: parseJavaBuildTool,
+    },
+    {
+        flag: "autostart",
+        key: "autostart",
+        description: "Warm-start policy on daemon boot (eager|auto|never)",
+        parse: parseAutostart,
+    },
+];
+/** Map from CLI flag name → SettingDef for O(1) lookup. */
+export const SETTINGS_BY_FLAG = new Map(SETTINGS_SCHEMA.map((s) => [s.flag, s]));
+/** Map from camelCase key → SettingDef for config.json round-tripping. */
+export const SETTINGS_BY_KEY = new Map(SETTINGS_SCHEMA.map((s) => [s.key, s]));
+/**
+ * Parse raw CLI `--key=value` pairs into validated RepoSettings.
+ * Returns only the keys that were explicitly provided.
+ * Throws on the first invalid value with a descriptive error.
+ */
+export function parseSettingsFlags(raw) {
+    const result = {};
+    for (const [flag, value] of Object.entries(raw)) {
+        if (value === undefined)
+            continue;
+        const def = SETTINGS_BY_FLAG.get(flag);
+        if (!def) {
+            throw new Error(`Unknown setting "--${flag}". Valid flags: ${SETTINGS_SCHEMA.map((s) => `--${s.flag}`).join(", ")}`);
+        }
+        result[def.key] = def.parse(value);
+    }
+    return result;
+}