@cmgmyr/hive 0.1.0

package/dist/projectYml.js

@@ -0,0 +1,254 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { parse } from "yaml";
+import { harnessNames } from "./harnesses.js";
+import { isValidProfileName } from "./profiles.js";
+import { errorMessage } from "./result.js";
+import { isWindowLayout, WINDOW_LAYOUTS } from "./tmux.js";
+export const DEFAULT_LEAD_BRANCHES = ["main", "master"];
+export const NO_PROFILE = "none";
+export function activeProfile(config) {
+    const name = config?.profile;
+    return name == null || name === NO_PROFILE ? null : name;
+}
+// First entry is the default; absent or empty means claude only (todo 526).
+export function allowedAgents(config) {
+    const list = config?.agents;
+    return list && list.length > 0 ? list : ["claude"];
+}
+function agentVarKey(harness) {
+    return `agents_${harness}`;
+}
+// One var per allowed harness, "1" - distinct from brief.ts's per-spawn harness_claude/harness_codex.
+export function agentVars(config) {
+    return Object.fromEntries(allowedAgents(config).map((name) => [agentVarKey(name), "1"]));
+}
+// Every known harness's key, not just currently-allowed ones - a strip for a disallowed harness
+// is correct, not missing, so doctor's scan must exclude the whole family.
+export function agentVarKeys() {
+    return harnessNames().map(agentVarKey);
+}
+// Mirrors mergedBriefVars (src/brief.ts): strip any project-defined agents_* var first so a lying
+// one can never silently win, then spread the derived vars on top.
+export function mergedProjectVars(config) {
+    const safe = { ...(config?.vars ?? {}) };
+    for (const key of agentVarKeys())
+        delete safe[key];
+    return { ...safe, ...agentVars(config) };
+}
+export function loadProjectYml(projectPath) {
+    const warnings = [];
+    const file = join(projectPath, "hive.yml");
+    if (!existsSync(file))
+        return { config: null, warnings };
+    let raw;
+    try {
+        raw = parse(readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        warnings.push(`hive.yml is not valid YAML: ${errorMessage(e)}`);
+        return { config: null, warnings };
+    }
+    if (raw == null || typeof raw !== "object") {
+        warnings.push("hive.yml must be a YAML mapping.");
+        return { config: null, warnings };
+    }
+    const root = raw;
+    let context_checkpoint_percent = null;
+    if (root.context_checkpoint_percent != null) {
+        const value = root.context_checkpoint_percent;
+        if (typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 100) {
+            context_checkpoint_percent = value;
+        }
+        else {
+            warnings.push("context_checkpoint_percent must be an integer from 1 through 100; ignoring it.");
+        }
+    }
+    const lead = typeof root.lead === "string" && root.lead.trim() !== "" ? root.lead.trim() : null;
+    let placement = null;
+    if (root.placement != null) {
+        if (root.placement === "split" || root.placement === "window") {
+            placement = root.placement;
+        }
+        else {
+            warnings.push(`placement must be "split" or "window"; ignoring "${String(root.placement)}".`);
+        }
+    }
+    let layout = null;
+    if (root.layout != null) {
+        if (isWindowLayout(root.layout)) {
+            layout = root.layout;
+        }
+        else {
+            warnings.push(`layout must be one of ${WINDOW_LAYOUTS.join(", ")}; ignoring "${String(root.layout)}".`);
+        }
+    }
+    let profile = null;
+    if (root.profile != null) {
+        const value = String(root.profile).trim();
+        if (value === "") {
+            warnings.push("profile is empty; ignoring it.");
+        }
+        else if (value !== NO_PROFILE && !isValidProfileName(value)) {
+            warnings.push(`profile "${value}" is not a valid profile name (letters, digits, dot, dash, underscore); ignoring it.`);
+        }
+        else {
+            profile = value;
+        }
+    }
+    let agents = null;
+    if (root.agents != null) {
+        if (!Array.isArray(root.agents)) {
+            warnings.push("agents must be a list of harness names; ignoring it.");
+        }
+        else {
+            const known = harnessNames();
+            const valid = [];
+            for (const entry of root.agents) {
+                const value = typeof entry === "string" ? entry.trim() : "";
+                if (value === "") {
+                    warnings.push("agents entry must be a non-empty harness name; skipped.");
+                }
+                else if (!known.includes(value)) {
+                    warnings.push(`agents: "${value}" is not a known harness (${known.join(", ")}); ignoring it.`);
+                }
+                else {
+                    valid.push(value);
+                }
+            }
+            agents = valid.length > 0 ? valid : null;
+        }
+    }
+    const review_tags = [];
+    if (root.review_tags != null) {
+        if (!Array.isArray(root.review_tags)) {
+            warnings.push("review_tags must be a list of todo tags; ignoring it.");
+        }
+        else {
+            for (const entry of root.review_tags) {
+                const value = typeof entry === "string" ? entry.trim() : "";
+                if (value === "") {
+                    warnings.push("review_tags entry must be a non-empty tag; skipped.");
+                }
+                else if (!review_tags.includes(value)) {
+                    review_tags.push(value);
+                }
+            }
+        }
+    }
+    let lead_branches = null;
+    if (root.lead_branches != null) {
+        const raw = Array.isArray(root.lead_branches) ? root.lead_branches : null;
+        const branches = raw
+            ?.filter((b) => typeof b === "string" && b.trim() !== "")
+            .map((b) => b.trim());
+        if (branches && branches.length === raw.length) {
+            lead_branches = branches;
+        }
+        else {
+            warnings.push("lead_branches must be a list of branch names; ignoring it.");
+        }
+    }
+    let dashboard = false;
+    if (root.dashboard != null) {
+        if (typeof root.dashboard === "boolean") {
+            dashboard = root.dashboard;
+        }
+        else {
+            warnings.push(`dashboard must be true or false; ignoring "${String(root.dashboard)}".`);
+        }
+    }
+    const vars = {};
+    if (root.vars != null) {
+        if (typeof root.vars !== "object" || Array.isArray(root.vars)) {
+            warnings.push("vars must be a mapping of name to value; ignoring it.");
+        }
+        else {
+            for (const [key, value] of Object.entries(root.vars)) {
+                if (value == null || typeof value === "object") {
+                    warnings.push(`var "${key}" must be a scalar; skipped.`);
+                    continue;
+                }
+                vars[key] = String(value);
+            }
+        }
+    }
+    const processes = {};
+    const rawProcesses = root.processes;
+    if (rawProcesses != null) {
+        if (typeof rawProcesses !== "object") {
+            warnings.push("hive.yml `processes` must be a mapping of name to command.");
+        }
+        else {
+            for (const [name, value] of Object.entries(rawProcesses)) {
+                if (typeof value === "string" && value.trim() !== "") {
+                    processes[name] = { command: value.trim(), dir: null, auto_start: true, visible: true, env: {} };
+                    continue;
+                }
+                if (value == null || typeof value !== "object") {
+                    warnings.push(`Process "${name}" needs a command string; skipped.`);
+                    continue;
+                }
+                const p = value;
+                if (typeof p.command !== "string" || p.command.trim() === "") {
+                    warnings.push(`Process "${name}" has no command; skipped.`);
+                    continue;
+                }
+                const dirValue = p.dir ?? p.working_dir;
+                let visible = true;
+                if (p.visible != null) {
+                    if (typeof p.visible === "boolean") {
+                        visible = p.visible;
+                    }
+                    else {
+                        warnings.push(`Process "${name}": visible must be true or false; ignoring "${String(p.visible)}".`);
+                    }
+                }
+                const env = {};
+                if (p.env != null && typeof p.env === "object") {
+                    for (const [k, v] of Object.entries(p.env)) {
+                        env[k] = String(v);
+                    }
+                }
+                processes[name] = {
+                    command: p.command.trim(),
+                    dir: typeof dirValue === "string" && dirValue.trim() !== "" ? dirValue.trim() : null,
+                    auto_start: p.auto_start !== false,
+                    visible,
+                    env,
+                };
+            }
+        }
+    }
+    return {
+        config: {
+            lead,
+            placement,
+            layout,
+            profile,
+            agents,
+            review_tags,
+            lead_branches,
+            context_checkpoint_percent,
+            dashboard,
+            vars,
+            processes,
+        },
+        warnings,
+    };
+}
+export function configHash(name, command, dir, env) {
+    return createHash("sha256")
+        .update(JSON.stringify([name, command, dir, env]))
+        .digest("hex");
+}
+export function resolveCommandDir(projectPath, dir) {
+    if (dir == null)
+        return projectPath;
+    const resolved = realpathSync(resolve(projectPath, dir));
+    if (resolved !== projectPath && !resolved.startsWith(projectPath + sep)) {
+        throw new Error(`dir "${dir}" escapes the project root`);
+    }
+    return resolved;
+}

package/dist/prompts.js

@@ -0,0 +1,18 @@
+const RUNBOOK_PROMPT = {
+    name: "runbook",
+    description: "Load this project's own standing process before planning or dispatching anything.",
+    text: `Run \`hive runbook\` in a shell and follow what it prints. It resolves this
+project's profile runbook, or its runbook pad when the project has no
+profile, with hive.yml vars substituted.
+
+If the project has neither, run help(topic="workflow") for hive's generic
+lead/worker pattern and agree a process with the human before dispatching
+anything.`,
+};
+export function registerPrompts(server) {
+    server.registerPrompt(RUNBOOK_PROMPT.name, { description: RUNBOOK_PROMPT.description }, () => ({
+        messages: [
+            { role: "user", content: { type: "text", text: RUNBOOK_PROMPT.text } },
+        ],
+    }));
+}

package/dist/ptys.js

@@ -0,0 +1,146 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { platform } from "node:os";
+const PS_LINE = /^\s*(\S+)\s+(\d+)\s+(.+?)\s*$/;
+export function parsePsSnapshot(output) {
+    const rows = [];
+    for (const line of output.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const m = PS_LINE.exec(line);
+        if (!m)
+            continue;
+        rows.push({ tty: m[1], ppid: Number(m[2]), comm: m[3] });
+    }
+    return rows;
+}
+export function countAllocatedTtys(rows) {
+    return new Set(rows.filter((r) => /^ttys/.test(r.tty)).map((r) => r.tty)).size;
+}
+export function isOrphanLoginShell(row) {
+    if (row.ppid !== 1)
+        return false;
+    const arg0 = row.comm.split(/\s+/, 1)[0] ?? row.comm;
+    const base = arg0.split("/").pop() ?? arg0;
+    return base.startsWith("-");
+}
+export function countOrphanLoginShells(rows) {
+    return rows.filter(isOrphanLoginShell).length;
+}
+function psSnapshot(field) {
+    return parsePsSnapshot(execFileSync("ps", ["-eo", `tty=,ppid=,${field}=`], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }));
+}
+export function ptyWarnThreshold(max) {
+    return Math.max(32, Math.floor(max / 10));
+}
+export function isLowHeadroom(headroom) {
+    const free = headroom.max - headroom.allocated;
+    return free < ptyWarnThreshold(headroom.max);
+}
+function isRealCount(n) {
+    return Number.isFinite(n) && n >= 0;
+}
+const SYSCTL = "/usr/sbin/sysctl";
+function darwinHeadroom() {
+    const max = Number(execFileSync(SYSCTL, ["-n", "kern.tty.ptmx_max"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim());
+    if (!isRealCount(max) || max === 0)
+        throw new Error("sysctl kern.tty.ptmx_max did not report a usable number");
+    const rows = psSnapshot("comm");
+    return {
+        allocated: countAllocatedTtys(rows),
+        max,
+        orphanLoginShells: countOrphanLoginShells(rows),
+        source: `${SYSCTL} -n kern.tty.ptmx_max, ps -eo tty=,ppid=,comm=`,
+    };
+}
+function linuxHeadroom() {
+    const max = Number(readFileSync("/proc/sys/kernel/pty/max", "utf8").trim());
+    const allocated = Number(readFileSync("/proc/sys/kernel/pty/nr", "utf8").trim());
+    if (!isRealCount(max) || max === 0 || !isRealCount(allocated)) {
+        throw new Error("/proc/sys/kernel/pty/{max,nr} did not report usable numbers");
+    }
+    let orphanLoginShells = 0;
+    try {
+        orphanLoginShells = countOrphanLoginShells(psSnapshot("args"));
+    }
+    catch {
+    }
+    return { allocated, max, orphanLoginShells, source: "/proc/sys/kernel/pty/{max,nr}" };
+}
+export function probeForPlatform(osPlatform) {
+    if (osPlatform === "darwin")
+        return darwinHeadroom;
+    if (osPlatform === "linux")
+        return linuxHeadroom;
+    return null;
+}
+export function safeProbe(probe) {
+    try {
+        return probe();
+    }
+    catch {
+        return null;
+    }
+}
+export function ptyHeadroom() {
+    try {
+        if (process.env.HIVE_PTY_HEADROOM_JSON)
+            return JSON.parse(process.env.HIVE_PTY_HEADROOM_JSON);
+        const probe = probeForPlatform(platform());
+        return probe ? safeProbe(probe) : null;
+    }
+    catch {
+        return null;
+    }
+}
+const PS_AGE_LINE = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(.+?)\s*$/;
+export function parseEtimeSeconds(etime) {
+    const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(etime) ?? /^(\d+)$/.exec(etime);
+    if (!m)
+        return null;
+    if (m.length === 2)
+        return Number(m[1]);
+    const [, days, hours, minutes, seconds] = m;
+    return (Number(days ?? 0) * 24 + Number(hours ?? 0)) * 3600 + Number(minutes) * 60 + Number(seconds);
+}
+export function parsePsSnapshotWithAge(output) {
+    const rows = [];
+    for (const line of output.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const m = PS_AGE_LINE.exec(line);
+        if (!m)
+            continue;
+        const seconds = parseEtimeSeconds(m[3]);
+        if (seconds === null)
+            continue;
+        rows.push({ pid: Number(m[1]), ppid: Number(m[2]), ageMs: seconds * 1000, tty: m[4], comm: m[5] });
+    }
+    return rows;
+}
+export function filterOrphanLoginShellsWithAge(rows) {
+    return rows.filter(isOrphanLoginShell);
+}
+function psSnapshotWithAge() {
+    try {
+        if (process.env.HIVE_PTY_PS_ROWS_JSON)
+            return JSON.parse(process.env.HIVE_PTY_PS_ROWS_JSON);
+        return parsePsSnapshotWithAge(execFileSync("ps", ["-eo", "pid=,ppid=,etime=,tty=,comm="], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+export function orphanLoginShellDetails() {
+    const rows = psSnapshotWithAge();
+    return rows === null ? null : filterOrphanLoginShellsWithAge(rows);
+}

package/dist/result.js

@@ -0,0 +1,53 @@
+export function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function ok(data) {
+    const text = typeof data === "string" ? data : JSON.stringify(data, null, 1);
+    return { content: [{ type: "text", text }] };
+}
+const STORE_REPLACED_MESSAGE = "hive: the store on disk was replaced out from under this session (likely a restore). " +
+    "This session has been writing to a file that no longer exists on disk; up to one tick " +
+    "of writes may already be lost. Restart this session before doing anything else.";
+export function registrationNoticeText(notice) {
+    return (`hive: no registered project matched this session's working directory, so it created ` +
+        `project ${notice.id} at "${notice.path}". If that's unintended: project_prune removes ` +
+        `it if it owns nothing yet, run the session from the intended directory, or call ` +
+        `project_select.`);
+}
+export async function run(fn) {
+    const { storeReplaced } = await import("./db.js");
+    if (storeReplaced()) {
+        return { content: [{ type: "text", text: STORE_REPLACED_MESSAGE }], isError: true };
+    }
+    const { takeRegistrationNotice } = await import("./context.js");
+    let result;
+    try {
+        result = ok(await fn());
+    }
+    catch (e) {
+        result = { content: [{ type: "text", text: errorMessage(e) }], isError: true };
+    }
+    const notice = takeRegistrationNotice();
+    if (notice) {
+        result.content.push({ type: "text", text: registrationNoticeText(notice) });
+    }
+    return result;
+}
+export function parseTags(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function matchesAnyTag(rowTags, wanted) {
+    if (!wanted || wanted.length === 0)
+        return true;
+    const tags = parseTags(rowTags);
+    return wanted.some((t) => tags.includes(t));
+}
+export function withTrailingNewline(text) {
+    return text === "" || text.endsWith("\n") ? text : `${text}\n`;
+}