huddle-cli 0.0.0-stage → 0.1.1

package/dist/room/contract.js

@@ -0,0 +1,132 @@
+// The CONTRACT: the exact cross-task names every task codes to — files and who
+// owns them, exported functions with signatures, data shapes, CLI flags,
+// routes, error strings. The design council ratifies it before work starts;
+// agents amend it mid-task (huddle_amend_contract) instead of inventing a name
+// a teammate depends on. Found live: two agents built the same app with
+// different names for the same thing, and the mismatch only surfaced at merge.
+//
+// Stored as Room events (contract.set / contract.amended), scoped to the
+// current session, so no schema change and `huddle story` replays it for free.
+import crypto from "node:crypto";
+/** The contract's text is capped: it rides in every task's launch prompt. */
+export const CONTRACT_CAP = 3000;
+/** Cap at a line break, so no name is cut in half (a half name is worse than none). */
+export function capContract(text, cap = CONTRACT_CAP) {
+    const t = text.trim();
+    if (t.length <= cap)
+        return t;
+    const cut = t.slice(0, cap - 12);
+    const nl = cut.lastIndexOf("\n");
+    return (nl > cap / 2 ? cut.slice(0, nl) : cut.replace(/\s+\S*$/, "")) + "\n…(capped)";
+}
+const sessionId = (db) => db.currentSession()?.id ?? null;
+function parse(p) {
+    try {
+        return JSON.parse(p || "{}");
+    }
+    catch {
+        return {};
+    }
+}
+/** The current session's contract with its amendments, or null when none was set. */
+export function getContract(db) {
+    const sid = sessionId(db);
+    const evs = db.eventsOfType(["contract.set", "contract.amended"], 0, 2000).map((e) => ({ type: e.type, ts: e.ts, p: parse(e.payload) }));
+    const sets = evs.filter((e) => e.type === "contract.set" && (e.p.session ?? null) === sid);
+    const base = sets[sets.length - 1];
+    if (!base)
+        return null;
+    // Amendments name the contract they amend, so a same-millisecond tie can't misorder them.
+    const amendments = evs
+        .filter((e) => e.type === "contract.amended" && e.p.base === base.p.id)
+        .map((e) => ({ section: String(e.p.section ?? ""), change: String(e.p.change ?? ""), why: String(e.p.why ?? ""), by: String(e.p.by ?? ""), version: Number(e.p.version) || 0, ts: e.ts }))
+        .sort((a, b) => a.version - b.version);
+    return {
+        text: String(base.p.text ?? ""),
+        version: amendments.length ? amendments[amendments.length - 1].version : typeof base.p.version === "number" ? base.p.version : 1,
+        by: base.p.by ?? null,
+        amendments,
+    };
+}
+/** Set (or replace) this session's contract: version 1, no amendments. */
+export function setContract(db, text, by) {
+    const t = capContract(text);
+    db.publish("contract.set", { agent_id: by, payload: { id: crypto.randomUUID(), session: sessionId(db), text: t, by, version: t ? 1 : 0 } });
+}
+/**
+ * Amend the contract: bumps its version and publishes "contract.amended".
+ * With no contract yet (a small goal skips the council), it starts an empty
+ * one, so agents can still agree names mid-task.
+ */
+export function amendContract(db, a) {
+    if (!getContract(db))
+        setContract(db, "", null);
+    const c = getContract(db);
+    const section = String(a.section ?? "").trim().slice(0, 200);
+    const change = String(a.change ?? "").trim().slice(0, 1500);
+    // A retried tool call is the same amendment, not a new version (and not a second broadcast).
+    const last = c.amendments[c.amendments.length - 1];
+    if (last && last.by === a.by && last.section === section && last.change === change)
+        return { version: last.version, duplicate: true };
+    const sets = db.eventsOfType(["contract.set"], 0, 2000).map((e) => parse(e.payload)).filter((p) => (p.session ?? null) === sessionId(db));
+    const version = c.version + 1;
+    db.publish("contract.amended", {
+        agent_id: a.by,
+        payload: { base: sets[sets.length - 1].id, version, section, change, why: String(a.why ?? "").trim().slice(0, 500), by: a.by },
+    });
+    return { version };
+}
+/** The contract as one prompt section for a task's launch; "" when there is none. */
+export function contractBrief(db) {
+    const c = getContract(db);
+    if (!c || (!c.text && !c.amendments.length))
+        return "";
+    const text = capContract(c.text);
+    const am = c.amendments.slice(-8).map((x) => `- v${x.version} by ${x.by}: ${x.section}: ${x.change}${x.why ? ` (${x.why})` : ""}`);
+    return [
+        // Not "see HUDDLE_CONTRACT.md": its commit can fail, and it never carries amendments.
+        `CONTRACT v${c.version} — the exact names every task codes to (huddle_contract shows the latest):`,
+        ...(text ? [text] : []),
+        ...(am.length ? ["Amendments:", ...am] : []),
+        "Use these exact names. Never invent a name another task depends on that isn't here: call huddle_amend_contract(section, change, why) first — it tells every teammate.",
+        "It never overrides the goal: where they differ on an exact output, message or format, the goal wins (amend this).",
+    ].join("\n");
+}
+/** The contract as a file for the repo root, so every worktree has it. */
+export function contractFile(text, by, members) {
+    return `# HUDDLE CONTRACT
+
+The exact cross-task names every task codes to, ratified by the design council (${members.join(", ")})${by ? `, written by ${by}` : ""}.
+To change a name, call huddle_amend_contract — don't edit this file. huddle_contract shows the latest version with amendments.
+
+${text.trim()}
+`;
+}
+const NOT_NAMES = new Set(["function", "const", "export", "import", "return", "string", "number", "boolean", "null", "undefined", "void", "async", "await", "interface", "type", "class", "true", "false", "Promise", "Array", "Record", "Object", "JSON", "HUDDLE_CONTRACT"]);
+/**
+ * The code names a contract fixes (for the radar's drift check): backticked
+ * identifiers, camelCase / snake_case / PascalCase-with-a-hump words, and
+ * anything called like `name(`. Plain English words are left out — a false
+ * "did you mean" sends an agent renaming code that works.
+ */
+export function contractNames(c) {
+    if (!c)
+        return [];
+    const text = [c.text, ...c.amendments.map((a) => a.change)].join("\n");
+    const out = new Set();
+    const add = (n) => {
+        if (n.length >= 3 && !NOT_NAMES.has(n) && /^[A-Za-z_$][\w$]*$/.test(n))
+            out.add(n);
+    };
+    for (const m of text.matchAll(/`([^`\n]{1,200})`/g))
+        for (const w of m[1].match(/[A-Za-z_$][\w$]*/g) ?? [])
+            if (/[a-z][A-Z]|_|^[A-Z][a-z]+[A-Z]/.test(w) || m[1].trim() === w)
+                add(w);
+    for (const m of text.matchAll(/\b([A-Za-z_$][\w$]*)\s*\(/g))
+        add(m[1]);
+    for (const w of text.match(/\b[A-Za-z_$][\w$]*\b/g) ?? [])
+        if (/[a-z][A-Z]|[a-z]_[a-z]|^[A-Z][a-z]+[A-Z]/.test(w))
+            add(w);
+    return [...out].slice(0, 300);
+}
+//# sourceMappingURL=contract.js.map