@litterthanlit/hypher-cli 0.1.7 → 0.2.0

package/vendor/structuredHandoff.mjs

@@ -409,6 +409,248 @@ export function parseHandoffProposal(value, options = {}) {
     }
     return { ok: true, value: proposal };
 }
+const DECISION_KEYS = new Set(["decision", "reason", "status", "sourceRefs", "supersedes"]);
+const SOURCE_KEYS = new Set(["ref", "label", "kind", "sourceId"]);
+const REPO_KEYS = new Set(["repository", "branch", "commit", "dirty", "worktreePath", "dirtyFingerprint"]);
+/** Required text, trimmed, with no length cap. */
+function readText(value, field) {
+    return shortText(value, field, Number.POSITIVE_INFINITY);
+}
+function readTextList(value, field) {
+    if (!Array.isArray(value))
+        return { ok: false, error: `${field} must be an array` };
+    const items = [];
+    for (const item of value) {
+        const parsed = readText(item, field);
+        if (!parsed.ok)
+            return parsed;
+        items.push(parsed.value);
+    }
+    return { ok: true, value: items };
+}
+/** The own fields of `value` that are not in `known`, in their original order. */
+function unknownFieldsOf(value, known) {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !known.has(key)));
+}
+function knownFieldsOnly(value, known) {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => known.has(key)));
+}
+function readRepo(value) {
+    if (!isObject(value))
+        return { ok: false, error: "repo must be an object" };
+    const branch = readText(value.branch, "repo.branch");
+    if (!branch.ok)
+        return branch;
+    const commit = readText(value.commit, "repo.commit");
+    if (!commit.ok)
+        return commit;
+    if (typeof value.dirty !== "boolean")
+        return { ok: false, error: "repo.dirty must be a boolean" };
+    const result = { branch: branch.value, commit: commit.value, dirty: value.dirty };
+    for (const field of ["repository", "worktreePath", "dirtyFingerprint"]) {
+        if (value[field] === undefined)
+            continue;
+        const parsed = readText(value[field], `repo.${field}`);
+        if (!parsed.ok)
+            return parsed;
+        result[field] = parsed.value;
+    }
+    return { ok: true, value: result };
+}
+function readEvidence(value) {
+    if (!Array.isArray(value))
+        return { ok: false, error: "evidence must be an array" };
+    const items = [];
+    for (const item of value) {
+        if (!isObject(item))
+            return { ok: false, error: "evidence must be objects" };
+        const command = readText(item.command, "evidence.command");
+        if (!command.ok)
+            return command;
+        if (typeof item.exitCode !== "number" || !Number.isFinite(item.exitCode)) {
+            return { ok: false, error: "evidence.exitCode must be a number" };
+        }
+        const tree = readText(item.tree, "evidence.tree");
+        if (!tree.ok)
+            return tree;
+        if (item.capturedBy !== "agent" && item.capturedBy !== "hook") {
+            return { ok: false, error: "evidence.capturedBy must be agent or hook" };
+        }
+        if (typeof item.capturedAt !== "number" || !Number.isFinite(item.capturedAt)) {
+            return { ok: false, error: "evidence.capturedAt must be a number" };
+        }
+        items.push({
+            command: command.value,
+            exitCode: item.exitCode,
+            tree: tree.value,
+            capturedBy: item.capturedBy,
+            capturedAt: item.capturedAt,
+            ...unknownFieldsOf(item, EVIDENCE_KEYS),
+        });
+    }
+    return { ok: true, value: items };
+}
+/**
+ * Read a handoff leniently: the reader of a stored handoff, which must not refuse a note because
+ * a newer Hypher wrote a field, a longer list, or a longer line than this code would. For any
+ * input `parseHandoffProposal` accepts, the known fields come out equal. A `schemaVersion` above 1
+ * parses but is flagged `readOnly`: the meaning may have changed, so a writer must not save over
+ * it. A missing, non-integer, or below-1 `schemaVersion` is an error.
+ */
+export function parseHandoffProposalLenient(value) {
+    if (!isObject(value))
+        return { ok: false, error: "proposal must be an object" };
+    const schemaVersion = value.schemaVersion;
+    if (typeof schemaVersion !== "number" || !Number.isInteger(schemaVersion) || schemaVersion < 1) {
+        return { ok: false, error: "proposal.schemaVersion must be a whole number, 1 or higher" };
+    }
+    const goal = readText(value.goal, "goal");
+    if (!goal.ok)
+        return goal;
+    const constraints = readTextList(value.constraints, "constraints");
+    if (!constraints.ok)
+        return constraints;
+    const completed = readTextList(value.completed, "completed");
+    if (!completed.ok)
+        return completed;
+    const unverified = readTextList(value.unverified, "unverified");
+    if (!unverified.ok)
+        return unverified;
+    const blockers = readTextList(value.blockers, "blockers");
+    if (!blockers.ok)
+        return blockers;
+    const nextAction = readText(value.nextAction, "nextAction");
+    if (!nextAction.ok)
+        return nextAction;
+    if (!Array.isArray(value.decisions))
+        return { ok: false, error: "decisions must be an array" };
+    const decisions = [];
+    for (const item of value.decisions) {
+        if (!isObject(item))
+            return { ok: false, error: "decisions must be objects" };
+        const decision = readText(item.decision, "decisions.decision");
+        if (!decision.ok)
+            return decision;
+        const reason = readText(item.reason, "decisions.reason");
+        if (!reason.ok)
+            return reason;
+        const entry = { decision: decision.value, reason: reason.value };
+        if (item.status !== undefined) {
+            if (item.status !== "reported" && item.status !== "approved")
+                return { ok: false, error: "decisions.status is invalid" };
+            entry.status = item.status;
+        }
+        if (item.sourceRefs !== undefined) {
+            const sourceRefs = readTextList(item.sourceRefs, "decisions.sourceRefs");
+            if (!sourceRefs.ok)
+                return sourceRefs;
+            entry.sourceRefs = sourceRefs.value;
+        }
+        if (item.supersedes !== undefined) {
+            const supersedes = readText(item.supersedes, "decisions.supersedes");
+            if (!supersedes.ok)
+                return supersedes;
+            entry.supersedes = supersedes.value;
+        }
+        decisions.push({ ...entry, ...unknownFieldsOf(item, DECISION_KEYS) });
+    }
+    if (!Array.isArray(value.sources))
+        return { ok: false, error: "sources must be an array" };
+    const sources = [];
+    for (const item of value.sources) {
+        if (!isObject(item))
+            return { ok: false, error: "sources must be objects" };
+        const ref = readText(item.ref, "sources.ref");
+        if (!ref.ok)
+            return ref;
+        const source = { ref: ref.value };
+        if (item.label !== undefined) {
+            const label = readText(item.label, "sources.label");
+            if (!label.ok)
+                return label;
+            source.label = label.value;
+        }
+        if (item.kind !== undefined) {
+            if (item.kind !== "agent_report" && item.kind !== "capture" && item.kind !== "agent_event") {
+                return { ok: false, error: "sources.kind is invalid" };
+            }
+            source.kind = item.kind;
+        }
+        if (item.sourceId !== undefined) {
+            const sourceId = readText(item.sourceId, "sources.sourceId");
+            if (!sourceId.ok)
+                return sourceId;
+            source.sourceId = sourceId.value;
+        }
+        sources.push({ ...source, ...unknownFieldsOf(item, SOURCE_KEYS) });
+    }
+    const repo = readRepo(value.repo);
+    if (!repo.ok)
+        return repo;
+    let evidence;
+    if (value.evidence !== undefined) {
+        const read = readEvidence(value.evidence);
+        if (!read.ok)
+            return read;
+        evidence = read.value;
+    }
+    const proposal = {
+        schemaVersion,
+        goal: goal.value,
+        constraints: constraints.value,
+        decisions,
+        completed: completed.value,
+        unverified: unverified.value,
+        blockers: blockers.value,
+        nextAction: nextAction.value,
+        sources,
+        repo: repo.value,
+        ...(evidence !== undefined ? { evidence } : {}),
+        ...unknownFieldsOf(value, PROPOSAL_KEYS),
+    };
+    return { ok: true, value: proposal, readOnly: schemaVersion > HANDOFF_PROPOSAL_SCHEMA_VERSION };
+}
+/**
+ * A read handoff as version 1 with only the fields this code knows: unknown fields are dropped at
+ * the top level and on each decision, source, and evidence item. Null above version 1, whose known
+ * fields may no longer mean what they meant. What a writer sends to be checked by the strict parser.
+ */
+export function knownFieldsV1(read) {
+    if (read.schemaVersion !== HANDOFF_PROPOSAL_SCHEMA_VERSION)
+        return null;
+    return {
+        schemaVersion: HANDOFF_PROPOSAL_SCHEMA_VERSION,
+        goal: read.goal,
+        constraints: read.constraints,
+        decisions: read.decisions.map((item) => knownFieldsOnly(item, DECISION_KEYS)),
+        completed: read.completed,
+        unverified: read.unverified,
+        blockers: read.blockers,
+        nextAction: read.nextAction,
+        sources: read.sources.map((item) => knownFieldsOnly(item, SOURCE_KEYS)),
+        repo: knownFieldsOnly(read.repo, REPO_KEYS),
+        ...(read.evidence ? { evidence: read.evidence.map((item) => knownFieldsOnly(item, EVIDENCE_KEYS)) } : {}),
+    };
+}
+/**
+ * Put back, unchanged, the unknown fields `carrier` held: the top-level ones, and those of each
+ * decision, source, and evidence item. `known` must be what a parse of `knownFieldsV1(carrier)`
+ * returns, or any list built from it, with the same items in the same order: the fields go back
+ * by position. Nothing is invented or edited.
+ */
+export function reattachUnknownFields(known, carrier) {
+    const back = (items, from, keys) => items.map((item, index) => {
+        const owner = from?.[index];
+        return isObject(owner) ? { ...item, ...unknownFieldsOf(owner, keys) } : item;
+    });
+    return {
+        ...known,
+        ...unknownFieldsOf(carrier, PROPOSAL_KEYS),
+        decisions: back(known.decisions, carrier.decisions, DECISION_KEYS),
+        sources: back(known.sources, carrier.sources, SOURCE_KEYS),
+        ...(known.evidence ? { evidence: back(known.evidence, carrier.evidence, EVIDENCE_KEYS) } : {}),
+    };
+}
 export function renderHandoffPacket(proposal) {
     const lines = [
         `Goal: ${proposal.goal}`,
@@ -613,6 +855,30 @@ export function planHandoffDelivery(input) {
         receipt,
     };
 }
+export function headFromRow(projectId, row) {
+    if (!row || typeof row.revision !== "number")
+        return { kind: "none" };
+    const unreadable = (error) => ({ kind: "unreadable", revision: row.revision, error });
+    if (!row.proposal || !row.idempotencyKey || !row.sourceAgent)
+        return unreadable("the stored row is incomplete");
+    const parsed = parseHandoffProposalLenient(row.proposal);
+    if (!parsed.ok)
+        return unreadable(parsed.error);
+    const proposal = knownFieldsV1(parsed.value);
+    if (!proposal)
+        return unreadable(`it is format version ${parsed.value.schemaVersion}, newer than this server reads`);
+    return {
+        kind: "head",
+        head: {
+            projectId,
+            revision: row.revision,
+            idempotencyKey: row.idempotencyKey,
+            proposal,
+            source: row.sourceAgent,
+            savedAt: row.generatedAt,
+        },
+    };
+}
 export function readHandoffCommand(value) {
     if (!isObject(value))
         return { ok: true, command: null };