@cmgmyr/hive 0.1.0

package/dist/mcpConfig.js

@@ -0,0 +1,121 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseToml } from "smol-toml";
+const serverPath = () => fileURLToPath(new URL("./index.js", import.meta.url));
+function addCommand(scope, name, pinned, args) {
+    return `  claude mcp add --scope ${scope} ${name} -- ${[pinned, ...args].map((a) => `"${a}"`).join(" ")}`;
+}
+export function registrationProblem(r, pinned) {
+    const reRegister = [addCommand(r.scope, r.name, pinned, r.args)];
+    if (!r.command.includes("/")) {
+        return [
+            `runs "${r.command}", which a Node version manager re-resolves per`,
+            "directory, so the server can start under a Node that cannot load hive's store.",
+            `Re-register with an absolute interpreter, in ${r.source}:`,
+            ...reRegister,
+        ];
+    }
+    if (r.command !== pinned) {
+        return [
+            `pins a different interpreter than this CLI runs (${pinned}).`,
+            "That is fine only while both were built against the same ABI.",
+            `Re-register with this one, in ${r.source}:`,
+            ...reRegister,
+        ];
+    }
+    return null;
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+const userConfigPath = () => join(resolve(process.env.CLAUDE_CONFIG_DIR || homedir()), ".claude.json");
+export const codexConfigPath = () => join(resolve(process.env.CODEX_HOME || join(homedir(), ".codex")), "config.toml");
+const isHive = (name, raw) => name === "hive" ||
+    (Array.isArray(raw?.args) &&
+        raw.args.some((a) => typeof a === "string" && resolve(a) === serverPath()));
+export function hiveRegistrations(projectPath) {
+    const found = [];
+    const collect = (servers, scope, source) => {
+        if (!servers || typeof servers !== "object")
+            return;
+        for (const [name, raw] of Object.entries(servers)) {
+            const command = raw?.command;
+            if (typeof command !== "string")
+                continue;
+            if (!isHive(name, raw))
+                continue;
+            const args = Array.isArray(raw.args)
+                ? raw.args.filter((a) => typeof a === "string")
+                : [];
+            found.push({ name, scope, source, command, args });
+        }
+    };
+    const claudeJson = userConfigPath();
+    const user = readJson(claudeJson);
+    collect(user?.mcpServers, "user", claudeJson);
+    if (projectPath) {
+        collect(user?.projects?.[projectPath]?.mcpServers, "local", claudeJson);
+        const projectFile = join(projectPath, ".mcp.json");
+        collect(readJson(projectFile)?.mcpServers, "project", projectFile);
+    }
+    return found;
+}
+export function codexHiveRegistrations() {
+    const source = codexConfigPath();
+    let text;
+    try {
+        text = readFileSync(source, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = parseToml(text);
+    }
+    catch {
+        return [];
+    }
+    const servers = parsed.mcp_servers;
+    if (!servers || typeof servers !== "object" || Array.isArray(servers))
+        return [];
+    const found = [];
+    for (const [name, raw] of Object.entries(servers)) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const command = raw.command;
+        if (typeof command !== "string")
+            continue;
+        const argsValue = raw.args;
+        const args = Array.isArray(argsValue)
+            ? argsValue.filter((arg) => typeof arg === "string")
+            : [];
+        if (isHive(name, { command, args }))
+            found.push({ name, source, command, args });
+    }
+    return found;
+}
+export function registrationOffer(pinned, found) {
+    if (found.length > 0)
+        return null;
+    const source = userConfigPath();
+    const servers = readJson(source)?.mcpServers;
+    if (!servers || typeof servers !== "object")
+        return null;
+    if (Object.entries(servers).some(([name, raw]) => isHive(name, raw))) {
+        return null;
+    }
+    return [
+        `hive's MCP tools are not registered in ${source}.`,
+        "The `hive` command and the MCP server are registered separately, so this",
+        "adds the server, pinned to the same interpreter:",
+        addCommand("user", "hive", pinned, [serverPath()]),
+    ];
+}

package/dist/processes.js

@@ -0,0 +1,161 @@
+import { getProject } from "./context.js";
+import { db } from "./db.js";
+import { loadProjectYml } from "./projectYml.js";
+import { closeAgentRow, killAgentPane, relayoutAfterPaneLeft } from "./spawn.js";
+import { cancelCopyMode, paneProcessExited, paneReissued, paneVisibility, paneWindow, projectWindows, rowLive, rowLiveProbe, sessionName, tmux, } from "./tmux.js";
+// One derivation for every surface that reports where a project's processes are: `hive status`,
+// `hive doctor`, and the dashboard. Two tmux window lookups per project, then one per running
+// process, and none at all for a project with neither a running command nor a defined one.
+export function snapshotProcesses(projectId) {
+    const rows = runningCommandRows(projectId);
+    const project = getProject(projectId);
+    const defined = project ? Object.keys(loadProjectYml(project.path).config?.processes ?? {}) : [];
+    if (rows.length === 0 && defined.length === 0)
+        return [];
+    const windows = rows.length > 0 ? projectWindows(sessionName(), projectId) : null;
+    const running = new Set(rows.map((r) => r.name));
+    return [
+        ...rows.map((r) => ({
+            name: r.name,
+            running: true,
+            // A row recorded on a socket this process cannot see into reads as unknown, never as a
+            // location: the pane id would name whatever holds it on THIS server.
+            visibility: windows !== null && rowLive(r.tmux_socket, r.tmux_target) === true ? paneVisibility(r.tmux_target, windows) : null,
+            startedAt: r.created_at,
+        })),
+        ...defined
+            .filter((name) => !running.has(name))
+            .map((name) => ({ name, running: false, visibility: null, startedAt: null })),
+    ];
+}
+export const COMMAND_KIND = "command";
+export const STOP_GRACE_MS = 2000;
+// The closed set docs/projects.md's "Lifetime" section is checked against (test/docs.test.mjs):
+// every way a hive.yml process can be stopped, named once here and rendered by whoever prints it.
+export const STOP_REASONS = {
+    byHand: "hive stop",
+    leadSessionEnded: "lead session ended",
+    leadPaneExited: "lead pane exited",
+    previousLead: "left running by a previous lead",
+};
+const STOPPABLE_COLUMNS = "id, project_id, name, tmux_target, tmux_socket, pane_pid, created_at";
+export function runningCommandRows(projectId) {
+    return db
+        .prepare(`SELECT ${STOPPABLE_COLUMNS} FROM agents
+       WHERE project_id = ? AND status = 'running' AND kind = 'command' ORDER BY created_at`)
+        .all(projectId);
+}
+export function runningCommandRow(projectId, name) {
+    return db
+        .prepare(`SELECT ${STOPPABLE_COLUMNS} FROM agents
+       WHERE project_id = ? AND name = ? AND status = 'running' AND kind = 'command'`)
+        .get(projectId, name);
+}
+export const STOPPING_MARKER_TTL_SECONDS = 30;
+export const stoppingMarkerKey = (agentId) => `stopping:${agentId}`;
+// Written BEFORE the pane is touched and read by the janitor's sweep. Ordering alone used to carry
+// "this process died on its own", and it could not: an interrupted stop left a closed row over a
+// live process, invisible to every surface, and the next start doubled it (todo 765, measured).
+function markStopping(projectId, agentId) {
+    try {
+        db.prepare(`INSERT INTO kv (project_id, key, value, updated_by, expires_at)
+       VALUES (?, ?, '"stopping"', 'hive', datetime('now', printf('+%d seconds', ?)))
+       ON CONFLICT(project_id, key) DO UPDATE SET
+         value = excluded.value, updated_at = datetime('now'), expires_at = excluded.expires_at`).run(projectId, stoppingMarkerKey(agentId), STOPPING_MARKER_TTL_SECONDS);
+    }
+    catch {
+    }
+}
+export function stoppingMarkerLive(projectId, agentId) {
+    try {
+        return !!db
+            .prepare(`SELECT 1 FROM kv WHERE project_id = ? AND key = ?
+          AND (expires_at IS NULL OR expires_at >= datetime('now'))`)
+            .get(projectId, stoppingMarkerKey(agentId));
+    }
+    catch {
+        return false;
+    }
+}
+function clearStoppingMarker(projectId, agentId) {
+    try {
+        db.prepare("DELETE FROM kv WHERE project_id = ? AND key = ?").run(projectId, stoppingMarkerKey(agentId));
+    }
+    catch {
+    }
+}
+const STOP_POLL_MS = 50;
+function waitForPaneToExit(target, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (paneProcessExited(target) === true)
+            return true;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(STOP_POLL_MS, remaining));
+    }
+}
+// The only thing that stops a hive.yml command. kill-pane alone is SIGHUP, which a dev server with
+// detached grandchildren survives while still holding its port, so the graceful leg comes first and
+// the receipt says which one ended it.
+// `reason` is deliberately not read here and is not carried on the receipt: it is a required
+// argument so every caller has to declare its trigger from the closed set docs/projects.md is
+// checked against, and whichever caller prints it already knows which one it passed.
+export function stopProcess(row, reason) {
+    const probe = rowLiveProbe(row.tmux_socket, row.tmux_target);
+    // A pane hive cannot see is left alone, row and all: closing the row here would hide a process
+    // that is still running from every surface that reports one.
+    if (probe.live === null)
+        return { name: row.name, leg: "unreachable" };
+    // A reissued pane id belongs to whoever holds it now, so it is never killed - same compare as
+    // janitor() and wake delivery.
+    if (probe.live === false || paneReissued(row.pane_pid, probe)) {
+        closeAgentRow(row.id);
+        return { name: row.name, leg: "already-gone" };
+    }
+    markStopping(row.project_id, row.id);
+    const window = paneWindow(row.tmux_target);
+    try {
+        // In copy mode C-c is `cancel`, not SIGINT, so the graceful leg would silently do nothing to a
+        // pane someone scrolled back in. A stop may take that scrollback position: the process is ending.
+        cancelCopyMode(row.tmux_target);
+        tmux("send-keys", "-t", row.tmux_target, "C-c");
+    }
+    catch {
+    }
+    let leg = "interrupted";
+    if (!waitForPaneToExit(row.tmux_target, STOP_GRACE_MS)) {
+        try {
+            killAgentPane(row.tmux_target);
+        }
+        catch {
+        }
+        leg = waitForPaneToExit(row.tmux_target, STOP_GRACE_MS) ? "killed" : "still-running";
+    }
+    // The row closes only once the pane is confirmed gone. A stop that did not finish leaves the row
+    // RUNNING, so the process stays visible to hive status, hive stop and the janitor.
+    if (leg === "still-running")
+        return { name: row.name, leg };
+    closeAgentRow(row.id, row.tmux_target);
+    clearStoppingMarker(row.project_id, row.id);
+    relayoutAfterPaneLeft(window);
+    return { name: row.name, leg };
+}
+export function stopAllProcesses(projectId, reason) {
+    return runningCommandRows(projectId).map((row) => stopProcess(row, reason));
+}
+export function stopLine(stopped) {
+    switch (stopped.leg) {
+        case "interrupted":
+            return `${stopped.name}: stopped (C-c)`;
+        case "killed":
+            return `${stopped.name}: stopped (killed after ${STOP_GRACE_MS / 1000}s)`;
+        case "already-gone":
+            return `${stopped.name}: already gone (nothing was running)`;
+        case "unreachable":
+            return `${stopped.name}: tmux could not be probed, so hive left it running`;
+        case "still-running":
+            return `${stopped.name}: still running: its pane survived C-c and kill-pane, so hive left the row open`;
+    }
+}

package/dist/profiles.js

@@ -0,0 +1,278 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { storeDir } from "./dataDir.js";
+export const PROFILE_FILES = ["posture.md", "runbook.md", "worker.md"];
+export const checkoutRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const shippedProfilesDir = join(checkoutRoot, "profiles");
+export const userProfilesDir = () => join(storeDir(), "profiles");
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function isValidProfileName(name) {
+    return NAME_PATTERN.test(name) && !name.includes("..");
+}
+const FILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*\.md$/;
+export function isValidProfileFileName(file) {
+    return FILE_NAME_PATTERN.test(file) && !file.includes("..");
+}
+function candidate(dir, name, file) {
+    return join(dir, name, file);
+}
+export function resolveProfileFile(name, file) {
+    if (!isValidProfileName(name) || !isValidProfileFileName(file))
+        return null;
+    const user = candidate(userProfilesDir(), name, file);
+    if (existsSync(user))
+        return { file, path: user, source: "user" };
+    const shipped = candidate(shippedProfilesDir, name, file);
+    if (existsSync(shipped))
+        return { file, path: shipped, source: "shipped" };
+    return null;
+}
+export function readProfileFile(name, file) {
+    const resolved = resolveProfileFile(name, file);
+    if (!resolved)
+        return null;
+    try {
+        return readFileSync(resolved.path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function renderProfileFile(name, file, vars) {
+    const template = readProfileFile(name, file);
+    return template == null ? null : renderTemplate(template, vars);
+}
+export function profileExists(name) {
+    if (!isValidProfileName(name))
+        return false;
+    return existsSync(join(userProfilesDir(), name)) || existsSync(join(shippedProfilesDir, name));
+}
+function namesIn(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && isValidProfileName(e.name))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+export function profileNames() {
+    return [...new Set([...namesIn(shippedProfilesDir), ...namesIn(userProfilesDir())])].sort();
+}
+function mdFilesIn(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isFile() && isValidProfileFileName(e.name))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+export function profileFileNames(name) {
+    if (!isValidProfileName(name))
+        return [];
+    const present = new Set([
+        ...mdFilesIn(join(shippedProfilesDir, name)),
+        ...mdFilesIn(join(userProfilesDir(), name)),
+    ]);
+    const known = PROFILE_FILES.filter((f) => present.has(f));
+    const extra = [...present].filter((f) => !PROFILE_FILES.includes(f)).sort();
+    return [...known, ...extra];
+}
+const ORIGIN_FILE = ".hive-origin.json";
+function contentHash(path) {
+    try {
+        return createHash("sha256").update(readFileSync(path)).digest("hex").slice(0, 16);
+    }
+    catch {
+        return null;
+    }
+}
+function readOrigins(name) {
+    try {
+        const raw = JSON.parse(readFileSync(join(userProfilesDir(), name, ORIGIN_FILE), "utf8"));
+        return raw && typeof raw === "object" ? raw : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeOrigin(name, file, hash) {
+    if (hash == null)
+        return;
+    const origins = readOrigins(name);
+    origins[file] = hash;
+    writeFileSync(join(userProfilesDir(), name, ORIGIN_FILE), `${JSON.stringify(origins, null, 2)}\n`);
+}
+function readFileSafe(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function lineDivergence(a, b) {
+    const linesA = a.split("\n");
+    const linesB = b.split("\n");
+    const counts = new Map();
+    for (const line of linesA)
+        counts.set(line, (counts.get(line) ?? 0) + 1);
+    let common = 0;
+    for (const line of linesB) {
+        const n = counts.get(line) ?? 0;
+        if (n > 0) {
+            common += 1;
+            counts.set(line, n - 1);
+        }
+    }
+    const total = linesA.length + linesB.length;
+    return total === 0 ? 0 : 1 - (2 * common) / total;
+}
+export const REWRITE_THRESHOLD = 0.5;
+export function profileStatus(name) {
+    const origins = readOrigins(name);
+    const files = [];
+    for (const file of profileFileNames(name)) {
+        const resolved = resolveProfileFile(name, file);
+        if (!resolved)
+            continue;
+        const shippedPath = candidate(shippedProfilesDir, name, file);
+        const shippedNow = contentHash(shippedPath);
+        let divergence = null;
+        if (resolved.source === "user") {
+            const userText = readFileSafe(resolved.path);
+            const shippedText = readFileSafe(shippedPath);
+            if (userText != null && shippedText != null)
+                divergence = lineDivergence(userText, shippedText);
+        }
+        files.push({
+            ...resolved,
+            upstreamMoved: resolved.source === "user" && origins[file] != null && shippedNow != null && shippedNow !== origins[file],
+            divergence,
+        });
+    }
+    return { name, files };
+}
+export class ProfileError extends Error {
+}
+function requireName(name) {
+    if (!isValidProfileName(name)) {
+        throw new ProfileError(`"${name}" is not a valid profile name (letters, digits, dot, dash, underscore; no path separators).`);
+    }
+}
+export function forkProfile(name, only) {
+    requireName(name);
+    if (!profileExists(name))
+        throw new ProfileError(`No profile named "${name}". List them with: hive profile list`);
+    const targetDir = join(userProfilesDir(), name);
+    mkdirSync(targetDir, { recursive: true });
+    const copied = [];
+    const skipped = [];
+    for (const file of only ? [only] : PROFILE_FILES) {
+        const source = candidate(shippedProfilesDir, name, file);
+        if (!existsSync(source)) {
+            if (only)
+                throw new ProfileError(`Profile "${name}" ships no ${file}.`);
+            continue;
+        }
+        const target = candidate(userProfilesDir(), name, file);
+        if (existsSync(target)) {
+            skipped.push(file);
+            continue;
+        }
+        copyFileSync(source, target);
+        writeOrigin(name, file, contentHash(source));
+        copied.push(file);
+    }
+    return { copied, skipped };
+}
+export function createProfile(name, from) {
+    requireName(name);
+    const existing = join(userProfilesDir(), name);
+    if (existsSync(existing)) {
+        throw new ProfileError(`You already have a profile named "${name}" at ${existing}.`);
+    }
+    if (from != null && !profileExists(from)) {
+        throw new ProfileError(`No profile named "${from}" to copy from.`);
+    }
+    const targetDir = join(userProfilesDir(), name);
+    mkdirSync(targetDir, { recursive: true });
+    if (from != null) {
+        for (const file of PROFILE_FILES) {
+            const resolved = resolveProfileFile(from, file);
+            if (resolved)
+                copyFileSync(resolved.path, join(targetDir, file));
+        }
+    }
+    else {
+        writeFileSync(join(targetDir, "posture.md"), `# ${name} posture\n\n<how a session running this profile should behave>\n`);
+    }
+    return targetDir;
+}
+const VAR_REF = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+const IF_LINE = /^[ \t]*<!--\s*if:([A-Za-z_][A-Za-z0-9_]*)\s*-->[ \t]*$/;
+const END_LINE = /^[ \t]*<!--\s*end\s*-->[ \t]*$/;
+const isSet = (vars, key) => vars[key] != null && String(vars[key]).trim() !== "";
+function renderConditionals(text, vars) {
+    const out = [];
+    const stack = [];
+    for (const line of text.split("\n")) {
+        const open = IF_LINE.exec(line);
+        if (open) {
+            stack.push(isSet(vars, open[1]));
+            continue;
+        }
+        if (END_LINE.test(line)) {
+            stack.pop();
+            continue;
+        }
+        if (stack.every(Boolean))
+            out.push(line);
+    }
+    return out.join("\n");
+}
+export function renderTemplate(text, vars) {
+    return (renderConditionals(text, vars)
+        .replace(VAR_REF, (match, key) => (isSet(vars, key) ? vars[key] : match))
+        .replace(/\n{3,}/g, "\n\n"));
+}
+export function templateVars(text) {
+    const found = new Set();
+    for (const line of text.split("\n")) {
+        const open = IF_LINE.exec(line);
+        if (open)
+            found.add(open[1]);
+    }
+    for (const match of text.matchAll(VAR_REF))
+        found.add(match[1]);
+    return [...found].sort();
+}
+const PAD_NAME = "[A-Za-z0-9][A-Za-z0-9_.-]*";
+const HIVE_PAD_CMD = new RegExp(`\`hive pad (${PAD_NAME})`, "g");
+const PAD_TOOL_CALL = /\bpad_(?:read|write)\([^)]*name\s*=\s*"([^"]+)"/g;
+const QUOTED_PAD_BEFORE = new RegExp(`"(${PAD_NAME})"\\s+pad\\b`, "gi");
+const QUOTED_PAD_AFTER = new RegExp(`\\bpad\\s+"(${PAD_NAME})"`, "gi");
+export function referencedPads(text) {
+    const found = new Set();
+    for (const re of [HIVE_PAD_CMD, PAD_TOOL_CALL, QUOTED_PAD_BEFORE, QUOTED_PAD_AFTER]) {
+        for (const m of text.matchAll(re))
+            found.add(m[1]);
+    }
+    return [...found].sort();
+}
+const PATH_TOKEN = /^[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.*-]+)+\/?$/;
+export function referencedPaths(text) {
+    const found = new Set();
+    for (const m of text.matchAll(/`([^`\n]+)`/g)) {
+        const token = m[1].trim();
+        if (!PATH_TOKEN.test(token))
+            continue;
+        found.add(token);
+    }
+    return [...found].sort();
+}