@cmgmyr/hive 0.1.0

package/dist/backup.js

@@ -0,0 +1,378 @@
+import SqliteDb from "better-sqlite3";
+import { randomUUID } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { errorMessage } from "./result.js";
+export const BACKUP_DIRNAME = "backups";
+export function backupsDir(dataDir) {
+    return join(dataDir, BACKUP_DIRNAME);
+}
+function timestampPart(now) {
+    return now.toISOString().replace(/[:.]/g, "-");
+}
+const SQL_DATETIME_FMT = "%Y-%m-%d %H:%M:%f";
+const SQL_NOW = `strftime('${SQL_DATETIME_FMT}', 'now')`;
+function finalSnapshotName(reason, now, n) {
+    const base = `${timestampPart(now)}-${reason}`;
+    return n === 0 ? base : `${base}-${n}`;
+}
+const NAME_PATTERN = /^(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z)-(migration|hourly|manual)(?:-\d+)?$/;
+function parseSnapshotDirName(name) {
+    const m = NAME_PATTERN.exec(name);
+    if (!m)
+        return null;
+    const iso = m[1].replace(/T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/, "T$1:$2:$3.$4Z");
+    const createdAt = new Date(iso);
+    if (Number.isNaN(createdAt.getTime()))
+        return null;
+    return { createdAt, reason: m[2] };
+}
+function dirSizeBytes(path) {
+    let total = 0;
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+        const full = join(path, entry.name);
+        total += entry.isDirectory() ? dirSizeBytes(full) : statSync(full).size;
+    }
+    return total;
+}
+function listSnapshotRefs(dataDir) {
+    const dir = backupsDir(dataDir);
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory())
+        .map((e) => {
+        const parsed = parseSnapshotDirName(e.name);
+        return parsed ? { name: e.name, path: join(dir, e.name), ...parsed } : null;
+    })
+        .filter((s) => s !== null)
+        .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+}
+export function listSnapshots(dataDir) {
+    return listSnapshotRefs(dataDir).map((s) => ({ ...s, sizeBytes: dirSizeBytes(s.path) }));
+}
+export function totalSizeBytes(snapshots) {
+    return snapshots.reduce((sum, s) => sum + s.sizeBytes, 0);
+}
+export function takeSnapshot(db, dataDir, reason, now = new Date()) {
+    const parent = backupsDir(dataDir);
+    const staging = join(parent, `.staging-${randomUUID()}`);
+    let completedAt = now;
+    try {
+        mkdirSync(parent, { recursive: true });
+        mkdirSync(staging, { recursive: true });
+        db.prepare("VACUUM INTO ?").run(join(staging, "hive.db"));
+        completedAt = new Date();
+        const profilesSrc = join(dataDir, "profiles");
+        if (existsSync(profilesSrc)) {
+            cpSync(profilesSrc, join(staging, "profiles"), { recursive: true });
+        }
+    }
+    catch (e) {
+        try {
+            rmSync(staging, { recursive: true, force: true });
+        }
+        catch {
+        }
+        return { ok: false, error: errorMessage(e) };
+    }
+    let metaDb;
+    try {
+        metaDb = new SqliteDb(join(staging, "hive.db"));
+    }
+    catch (e) {
+        try {
+            rmSync(staging, { recursive: true, force: true });
+        }
+        catch {
+        }
+        return { ok: false, error: errorMessage(e) };
+    }
+    let corruptError;
+    try {
+        const iso = completedAt.toISOString();
+        metaDb
+            .prepare(`UPDATE backup_meta SET last_attempt_at = strftime('${SQL_DATETIME_FMT}', ?), last_success_at = strftime('${SQL_DATETIME_FMT}', ?) WHERE id = 1`)
+            .run(iso, iso);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "SQLITE_NOTADB" || code === "SQLITE_CORRUPT")
+            corruptError = e;
+    }
+    finally {
+        try {
+            metaDb.close();
+        }
+        catch {
+        }
+    }
+    if (corruptError !== undefined) {
+        try {
+            rmSync(staging, { recursive: true, force: true });
+        }
+        catch {
+        }
+        return { ok: false, error: errorMessage(corruptError) };
+    }
+    if (existsSync(join(staging, "hive.db-journal"))) {
+        try {
+            rmSync(staging, { recursive: true, force: true });
+        }
+        catch {
+        }
+        return { ok: false, error: "a rollback journal survived the snapshot's own backup_meta write" };
+    }
+    for (let n = 0; n < 1000; n++) {
+        const dir = join(parent, finalSnapshotName(reason, now, n));
+        try {
+            renameSync(staging, dir);
+            return { ok: true, path: dir };
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "ENOTEMPTY" && code !== "EEXIST") {
+                try {
+                    rmSync(staging, { recursive: true, force: true });
+                }
+                catch {
+                }
+                return { ok: false, error: errorMessage(e) };
+            }
+        }
+    }
+    try {
+        rmSync(staging, { recursive: true, force: true });
+    }
+    catch {
+    }
+    return { ok: false, error: `could not claim a snapshot name for ${reason} after 1000 attempts` };
+}
+function envInt(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isInteger(n) && n >= 0 ? n : fallback;
+}
+export function retentionPolicy() {
+    return {
+        keepLast: envInt("HIVE_BACKUP_KEEP_LAST", 10),
+        keepDailyDays: envInt("HIVE_BACKUP_KEEP_DAILY_DAYS", 7),
+    };
+}
+const STALE_STAGING_MAX_AGE_MS = 60 * 60 * 1000;
+function sweepStaleStagingDirs(dataDir, maxAgeMs = STALE_STAGING_MAX_AGE_MS) {
+    const dir = backupsDir(dataDir);
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const cutoff = Date.now() - maxAgeMs;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith(".staging-"))
+            continue;
+        const full = join(dir, entry.name);
+        try {
+            if (statSync(full).mtimeMs < cutoff)
+                rmSync(full, { recursive: true, force: true });
+        }
+        catch {
+        }
+    }
+}
+export function pruneSnapshots(dataDir, policy = retentionPolicy(), now = new Date(), protect = new Set()) {
+    sweepStaleStagingDirs(dataDir);
+    const snapshots = listSnapshotRefs(dataDir);
+    const keepLast = Math.max(1, policy.keepLast);
+    const keep = new Set(snapshots.slice(0, keepLast).map((s) => s.name));
+    for (const name of protect)
+        keep.add(name);
+    const cutoff = new Date(now);
+    cutoff.setUTCDate(cutoff.getUTCDate() - policy.keepDailyDays);
+    const seenDays = new Set();
+    for (const s of snapshots) {
+        if (s.createdAt < cutoff)
+            continue;
+        const day = s.createdAt.toISOString().slice(0, 10);
+        if (seenDays.has(day))
+            continue;
+        seenDays.add(day);
+        keep.add(s.name);
+    }
+    const removed = [];
+    for (const s of snapshots) {
+        if (keep.has(s.name))
+            continue;
+        rmSync(s.path, { recursive: true, force: true });
+        removed.push(s.name);
+    }
+    return removed;
+}
+export function backupNow(db, dataDir, reason, protect = new Set()) {
+    const result = takeSnapshot(db, dataDir, reason);
+    if (result.ok) {
+        try {
+            db.prepare(`UPDATE backup_meta SET last_success_at = ${SQL_NOW} WHERE id = 1`).run();
+        }
+        catch {
+        }
+        try {
+            pruneSnapshots(dataDir, retentionPolicy(), new Date(), protect);
+        }
+        catch {
+        }
+    }
+    else {
+        try {
+            db.prepare(`UPDATE backup_meta SET last_error = ?, last_error_at = ${SQL_NOW} WHERE id = 1`).run(result.error ?? "unknown error");
+        }
+        catch {
+        }
+    }
+    return result;
+}
+const hourlyClaimStmt = new WeakMap();
+function claimStatement(db) {
+    let stmt = hourlyClaimStmt.get(db);
+    if (!stmt) {
+        stmt = db.prepare(`UPDATE backup_meta SET last_attempt_at = ${SQL_NOW}
+       WHERE id = 1 AND (
+         last_attempt_at IS NULL
+         OR last_attempt_at <= strftime('${SQL_DATETIME_FMT}', 'now', '-1 hours')
+         OR last_attempt_at > ${SQL_NOW}
+       )`);
+        hourlyClaimStmt.set(db, stmt);
+    }
+    return stmt;
+}
+export function maybeBackupHourly(db, dataDir) {
+    try {
+        if (claimStatement(db).run().changes !== 1)
+            return;
+        backupNow(db, dataDir, "hourly");
+    }
+    catch {
+    }
+}
+export function maybeBackupBeforeMigrations(db, dataDir, pendingCount) {
+    if (pendingCount <= 0)
+        return;
+    try {
+        backupNow(db, dataDir, "migration");
+    }
+    catch {
+    }
+}
+export function readBackupMeta(db) {
+    return db
+        .prepare("SELECT last_attempt_at, last_success_at, last_error, last_error_at FROM backup_meta WHERE id = 1")
+        .get();
+}
+export function backupHealth(db, dataDir) {
+    const meta = readBackupMeta(db);
+    const snapshots = listSnapshots(dataDir);
+    const summary = `${snapshots.length} snapshot(s), ${formatBytes(totalSizeBytes(snapshots))} total`;
+    const newest = snapshots.find((s) => existsSync(join(s.path, "hive.db")));
+    if (!newest) {
+        return { ok: false, message: `${summary}, nothing to restore from` };
+    }
+    const dirAt = db.prepare(`SELECT strftime('${SQL_DATETIME_FMT}', ?) AS ts`).get(newest.createdAt.toISOString()).ts;
+    let newestAt = dirAt;
+    try {
+        const snapDb = new SqliteDb(join(newest.path, "hive.db"), { readonly: true });
+        try {
+            const row = snapDb.prepare("SELECT last_success_at FROM backup_meta WHERE id = 1").get();
+            if (row?.last_success_at != null && row.last_success_at > newestAt)
+                newestAt = row.last_success_at;
+        }
+        finally {
+            snapDb.close();
+        }
+    }
+    catch {
+    }
+    const failedMostRecently = meta?.last_error_at != null && meta.last_error_at >= newestAt;
+    if (failedMostRecently) {
+        return { ok: false, message: `${summary}, last attempt failed at ${meta.last_error_at}: ${meta.last_error}` };
+    }
+    const staleDays = envInt("HIVE_BACKUP_STALE_DAYS", 7);
+    const stale = db
+        .prepare(`SELECT (? <= strftime('${SQL_DATETIME_FMT}', 'now', ?)) AS stale`)
+        .get(newestAt, `-${staleDays} days`).stale;
+    if (stale) {
+        return {
+            ok: false,
+            message: `${summary}, last success ${newestAt} is more than ${staleDays} day(s) old`,
+        };
+    }
+    return { ok: true, message: `${summary}, last success ${newestAt}` };
+}
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n}B`;
+    const units = ["K", "M", "G"];
+    let value = n / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value.toFixed(1)}${units[unit]}`;
+}
+export function findSnapshot(dataDir, name) {
+    return listSnapshotRefs(dataDir).find((s) => s.name === name);
+}
+export function previewRestore(dataDir, name) {
+    const ref = findSnapshot(dataDir, name);
+    if (!ref) {
+        const available = listSnapshotRefs(dataDir);
+        throw new Error(available.length === 0
+            ? `No snapshot named "${name}" (there are no backups in ${backupsDir(dataDir)} yet).`
+            : `No snapshot named "${name}". Available: ${available.map((s) => s.name).join(", ")}`);
+    }
+    const snapshot = { ...ref, sizeBytes: dirSizeBytes(ref.path) };
+    const currentDbPath = join(dataDir, "hive.db");
+    const currentDbExists = existsSync(currentDbPath);
+    return {
+        snapshot,
+        hasProfiles: existsSync(join(ref.path, "profiles")),
+        currentDbPath,
+        currentDbExists,
+        currentDbSizeBytes: currentDbExists ? statSync(currentDbPath).size : 0,
+    };
+}
+export function restoreSnapshot(dataDir, name) {
+    const preview = previewRestore(dataDir, name);
+    const tmpDbPath = `${preview.currentDbPath}.restoring`;
+    cpSync(join(preview.snapshot.path, "hive.db"), tmpDbPath);
+    renameSync(tmpDbPath, preview.currentDbPath);
+    for (const suffix of ["-wal", "-shm"]) {
+        rmSync(preview.currentDbPath + suffix, { force: true });
+    }
+    const liveProfiles = join(dataDir, "profiles");
+    const stagingProfiles = `${liveProfiles}.restoring`;
+    const oldProfiles = `${liveProfiles}.old`;
+    if (existsSync(oldProfiles) && !existsSync(liveProfiles)) {
+        renameSync(oldProfiles, liveProfiles);
+    }
+    const restoredProfiles = preview.hasProfiles;
+    if (restoredProfiles) {
+        rmSync(stagingProfiles, { recursive: true, force: true });
+        rmSync(oldProfiles, { recursive: true, force: true });
+        cpSync(join(preview.snapshot.path, "profiles"), stagingProfiles, { recursive: true });
+        if (existsSync(liveProfiles))
+            renameSync(liveProfiles, oldProfiles);
+        renameSync(stagingProfiles, liveProfiles);
+        rmSync(oldProfiles, { recursive: true, force: true });
+    }
+    return { restoredProfiles };
+}

package/dist/brief.js

@@ -0,0 +1,113 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gitPrimaryRoot } from "./context.js";
+import { storeDir } from "./dataDir.js";
+import { carriesNameFlag, harnessFor, harnessNames } from "./harnesses.js";
+import { agentVarKeys } from "./projectYml.js";
+import { readProfileFile, renderTemplate } from "./profiles.js";
+import { withTrailingNewline } from "./result.js";
+import { shellQuote } from "./tmux.js";
+// A pure git fact, not a convention hive owns: gitPrimaryRoot asks git directly with no
+// containment, and resolves the same primary checkout whether cwd is that checkout or a linked
+// worktree of it. What a project keeps there (a session corpus, local notes, nothing at all) is a
+// profile's business, never core's - see docs/patterns.md.
+export function primaryRoot(cwd) {
+    const root = gitPrimaryRoot(cwd);
+    return root ? `${root}/` : null;
+}
+function briefVars(ctx) {
+    const root = primaryRoot(ctx.cwd);
+    return {
+        ...(ctx.vars ?? {}),
+        agent_name: ctx.name,
+        actor_id: ctx.actorId,
+        project_name: ctx.projectName,
+        project_path: ctx.projectPath,
+        cwd: ctx.cwd,
+        ...(root ? { primary_root: root } : {}),
+    };
+}
+const WAIT_FOR_ASSIGNMENT = "Run whoami to confirm scope, then wait for your assignment.";
+// harness_claude is the default for anything that is not codex, not an equality check against
+// "claude" - a presence-conditional has no else, so an unrecognised harness still needs one.
+export function harnessBriefVars(harnessName) {
+    return harnessName === "codex" ? { harness_codex: "1" } : { harness_claude: "1" };
+}
+// Derived from harnessNames() rather than a hand-kept literal, so a newly registered harness
+// extends the strip set with no edit here (todo 597 review finding).
+function harnessVarKeys() {
+    return harnessNames().map((name) => `harness_${name}`);
+}
+// Strips harness_* and agents_* reserved keys before spreading harnessBriefVars - strip only,
+// worker.md never gets an agents_* value, since nothing needs one there yet.
+export function mergedBriefVars(projectVars, harnessName) {
+    const safe = { ...(projectVars ?? {}) };
+    for (const key of [...harnessVarKeys(), ...agentVarKeys()])
+        delete safe[key];
+    return { ...safe, ...harnessBriefVars(harnessName) };
+}
+export function workerBrief(ctx) {
+    if (ctx.profile) {
+        const template = readProfileFile(ctx.profile, "worker.md");
+        if (template != null)
+            return `${renderTemplate(template, briefVars(ctx)).trimEnd()}\n\n${WAIT_FOR_ASSIGNMENT}`;
+    }
+    return defaultWorkerBrief(ctx);
+}
+function defaultWorkerBrief(ctx) {
+    return `[HIVE CONTEXT]
+You are agent "${ctx.name}" (actor id: ${ctx.actorId}) in project "${ctx.projectName}" (${ctx.projectPath}).
+This session is locked to this project (HIVE_PROJECT_LOCK=1); do not try to access other projects.
+Coordinate through the hive MCP tools:
+- whoami confirms your identity and scope.
+- pad_list / pad_read for the shared plan and findings. Record decisions there.
+- todo_list(is_blocked=false, status="open") for dispatchable work; set status to in_progress while working.
+- todo_comment for handoffs (changed files, tests run, remaining risk), then todo_complete.
+- lease_acquire before editing shared file areas; leases expire on their own.
+If the hive MCP tools are unavailable in this session, write progress and results to stdout; the orchestrator will read your terminal.
+${WAIT_FOR_ASSIGNMENT}
+[END HIVE CONTEXT]`;
+}
+const briefsDir = () => join(storeDir(), "briefs");
+export const agentBriefPath = (agentId) => join(briefsDir(), `agent-${agentId}.md`);
+export function writeAgentBrief(agentId, text) {
+    const path = agentBriefPath(agentId);
+    mkdirSync(briefsDir(), { recursive: true });
+    writeFileSync(path, withTrailingNewline(text));
+    return path;
+}
+export function readAgentBrief(agentId) {
+    try {
+        return readFileSync(agentBriefPath(agentId), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+const posturesDir = () => join(storeDir(), "postures");
+export const projectPosturePath = (projectId) => join(posturesDir(), `project-${projectId}.md`);
+export function writeProjectPosture(projectId, text) {
+    const path = projectPosturePath(projectId);
+    mkdirSync(posturesDir(), { recursive: true });
+    writeFileSync(path, withTrailingNewline(text));
+    return path;
+}
+export { isClaudeCommand } from "./harnesses.js";
+export function workerCommandString(spec) {
+    const harness = harnessFor(spec.command);
+    const namedByCaller = carriesNameFlag(spec.extraArgs ?? []);
+    return [
+        // Split, not passed whole: spec.command can itself be multiple tokens (a wrapped command,
+        // e.g. "nice claude", todo 521) and shellQuote would otherwise glue the lot into one token a
+        // shell can't exec. Byte-identical for every single-token command - see
+        // test/worker-brief.test.mjs's negative control.
+        ...spec.command.trim().split(/\s+/),
+        ...(spec.model ? ["--model", spec.model] : []),
+        ...harness.argsFor({ displayName: spec.displayName, namedByCaller }),
+        ...(harness.briefDelivery && spec.settingsPath ? harness.briefDelivery.settingsArgs(spec.settingsPath) : []),
+        ...(harness.briefDelivery && spec.briefPath ? harness.briefDelivery.systemPromptArgs(spec.briefPath) : []),
+        ...(spec.extraArgs ?? []),
+    ]
+        .map(shellQuote)
+        .join(" ");
+}

package/dist/build-info.json

@@ -0,0 +1 @@
+{"version":"0.1.0","sha":"de83214","dirty":false}

package/dist/claudeDir.js

@@ -0,0 +1,5 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export function claudeConfigDir() {
+    return process.env.CLAUDE_CONFIG_DIR ? resolve(process.env.CLAUDE_CONFIG_DIR) : join(homedir(), ".claude");
+}