@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/quest/frontmatter.js

@@ -0,0 +1,630 @@
+/**
+ * Front-matter parser and serializer for quest READMEs
+ * and quest documents.
+ *
+ * The block is YAML between two `---` fences. We use the
+ * `yaml` library for parsing and serialization, and then
+ * project the result onto the typed `QuestFrontMatter` /
+ * `DocumentFrontMatter` shapes the rest of the library
+ * works with.
+ *
+ * Validation rules:
+ *
+ * - Required scalars must be present; missing or invalid
+ *   ones yield `undefined` from the parser so callers can
+ *   surface a clean error.
+ * - Enums (kind, status, priority, stage) are strict; an
+ *   unknown value is rejected.
+ * - Aliases serialize as objects (`{type, value}`) rather
+ *   than `type:value` strings, so consumers don't have to
+ *   reparse them.
+ * - Sessions serialize as objects with `id` plus optional
+ *   `name`, `cwd`, `started` and `status` fields.
+ * - Optional fields (`due`, `eta`, etc.) only appear in the
+ *   output when set.
+ */
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+const QUEST_KINDS = ["quest", "subquest", "sidequest"];
+const QUEST_STATUSES = [
+    "active",
+    "paused",
+    "blocked",
+    "concluded",
+    "retired",
+];
+const QUEST_PRIORITIES = [
+    "driving",
+    "active",
+    "queued",
+    "bench",
+    "someday",
+];
+const DOCUMENT_KINDS = ["plan", "research", "brief", "report"];
+const DOCUMENT_STAGES = [
+    "think",
+    "draft",
+    "build",
+    "concluded",
+    "retired",
+];
+const SESSION_STATUSES = ["active", "detached"];
+/** Split a text into the front-matter block (raw YAML) and the body. */
+export function splitFrontMatter(text) {
+    const lines = text.split("\n");
+    if (lines[0]?.trim() !== "---")
+        return undefined;
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === "---") {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return undefined;
+    const fmText = lines.slice(1, end).join("\n");
+    let body = lines.slice(end + 1).join("\n");
+    if (body.startsWith("\n"))
+        body = body.slice(1);
+    return { fmText, body };
+}
+function parseFrontMatterBlock(text) {
+    const split = splitFrontMatter(text);
+    if (!split)
+        return undefined;
+    let raw;
+    try {
+        raw = parseYaml(split.fmText) ?? {};
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return undefined;
+    }
+    return raw;
+}
+function asEnum(value, options) {
+    if (typeof value !== "string")
+        return undefined;
+    return options.includes(value) ? value : undefined;
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string") {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+function parseAliasValue(raw) {
+    if (typeof raw === "string") {
+        const colon = raw.indexOf(":");
+        if (colon <= 0)
+            return undefined;
+        const type = raw.slice(0, colon).trim();
+        const value = raw.slice(colon + 1).trim();
+        if (!type || !value)
+            return undefined;
+        return { type, value };
+    }
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const obj = raw;
+        const type = asString(obj.type);
+        const value = asString(obj.value);
+        if (type && value)
+            return { type, value };
+    }
+    return undefined;
+}
+function parseAliases(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const alias = parseAliasValue(entry);
+        if (alias)
+            out.push(alias);
+    }
+    return out;
+}
+function parseSession(raw) {
+    if (typeof raw === "string") {
+        return raw.length > 0 ? { id: raw } : undefined;
+    }
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const obj = raw;
+        const id = asString(obj.id);
+        if (!id)
+            return undefined;
+        const session = { id };
+        const name = asString(obj.name);
+        if (name)
+            session.name = name;
+        const cwd = asString(obj.cwd);
+        if (cwd)
+            session.cwd = cwd;
+        const started = asString(obj.started);
+        if (started)
+            session.started = started;
+        const status = asEnum(obj.status, SESSION_STATUSES);
+        if (status)
+            session.status = status;
+        const instanceId = asString(obj.instanceId);
+        if (instanceId)
+            session.instanceId = instanceId;
+        const process = parseSessionProcess(obj.process);
+        if (process)
+            session.process = process;
+        const terminal = parseSessionTerminal(obj.terminal);
+        if (terminal)
+            session.terminal = terminal;
+        return session;
+    }
+    return undefined;
+}
+function parseSessionProcess(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    const hostId = asString(obj.hostId);
+    const startToken = asString(obj.startToken);
+    const pid = typeof obj.pid === "number" ? obj.pid : undefined;
+    if (!hostId || pid === undefined || !startToken)
+        return undefined;
+    // The boot token is optional on both sides: a record written before
+    // it was captured stays valid, and reading it back is what lets a
+    // pre-reboot session be retired without probing a meaningless pid.
+    const bootToken = asString(obj.bootToken);
+    return { hostId, pid, startToken, ...(bootToken ? { bootToken } : {}) };
+}
+function parseSessionTerminal(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    const driverId = asString(obj.driverId);
+    const value = asString(obj.value);
+    if (!driverId || !value)
+        return undefined;
+    const terminal = { driverId, value };
+    const scope = asString(obj.scope);
+    if (scope)
+        terminal.scope = scope;
+    const hostId = asString(obj.hostId);
+    if (hostId)
+        terminal.hostId = hostId;
+    return terminal;
+}
+function parseSessions(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const session = parseSession(entry);
+        if (session)
+            out.push(session);
+    }
+    return out;
+}
+function parseTree(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    const path = asString(obj.path);
+    const providerId = asString(obj.providerId);
+    if (!path || !providerId)
+        return undefined;
+    const tree = { path, providerId };
+    const branch = asString(obj.branch);
+    if (branch)
+        tree.branch = branch;
+    const repoRoot = asString(obj.repoRoot);
+    if (repoRoot)
+        tree.repoRoot = repoRoot;
+    if (Array.isArray(obj.zones)) {
+        const zones = [];
+        for (const z of obj.zones) {
+            const zone = asString(z);
+            if (zone)
+                zones.push(zone);
+        }
+        if (zones.length > 0)
+            tree.zones = zones;
+    }
+    const origin = asString(obj.origin);
+    if (origin === "scaffolded" || origin === "adopted")
+        tree.origin = origin;
+    return tree;
+}
+function parseTrees(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const tree = parseTree(entry);
+        if (tree)
+            out.push(tree);
+    }
+    return out;
+}
+function parsePendingPruneEntry(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    const path = asString(obj.path);
+    const reason = asString(obj.reason);
+    const detectedAt = asString(obj.detectedAt);
+    if (!path || !reason || !detectedAt)
+        return undefined;
+    return { path, reason, detectedAt };
+}
+function parsePendingPrune(raw) {
+    // Accept both the legacy scalar form (one entry as an
+    // object) and the canonical array form, so an older
+    // README round-trips without losing data.
+    if (Array.isArray(raw)) {
+        const out = [];
+        for (const entry of raw) {
+            const parsed = parsePendingPruneEntry(entry);
+            if (parsed)
+                out.push(parsed);
+        }
+        return out;
+    }
+    const single = parsePendingPruneEntry(raw);
+    return single ? [single] : [];
+}
+/**
+ * Keys the quest-frontmatter parser recognises. Anything
+ * outside this set is captured into `_extra` so a
+ * round-trip preserves user-added fields.
+ */
+const KNOWN_QUEST_KEYS = new Set([
+    "id",
+    "kind",
+    "parent",
+    "status",
+    "priority",
+    "rank",
+    "started",
+    "updated",
+    "due",
+    "eta",
+    "aliases",
+    "sessions",
+    "trees",
+    "pendingPrune",
+    "primaryPlanId",
+    "scratchDir",
+    "verify",
+]);
+const KNOWN_DOCUMENT_KEYS = new Set([
+    "id",
+    "kind",
+    "quest",
+    "stage",
+    "updated",
+    "rounds",
+    "subject",
+]);
+function captureExtras(raw, known) {
+    let extras;
+    for (const key of Object.keys(raw)) {
+        if (known.has(key))
+            continue;
+        extras ??= {};
+        extras[key] = raw[key];
+    }
+    return extras;
+}
+/** Parse the quest README front-matter from raw text. */
+export function parseQuestFrontMatter(text) {
+    const split = splitFrontMatter(text);
+    if (!split)
+        return undefined;
+    const raw = parseFrontMatterBlock(text);
+    if (!raw)
+        return undefined;
+    const id = asString(raw.id);
+    const kind = asEnum(raw.kind, QUEST_KINDS);
+    const status = asEnum(raw.status, QUEST_STATUSES);
+    const priority = asEnum(raw.priority, QUEST_PRIORITIES);
+    const rank = asNumber(raw.rank);
+    const started = asString(raw.started);
+    const updated = asString(raw.updated);
+    if (!id ||
+        !kind ||
+        !status ||
+        !priority ||
+        rank === undefined ||
+        !started ||
+        !updated) {
+        return undefined;
+    }
+    const parentRaw = raw.parent;
+    const parent = parentRaw === null ||
+        parentRaw === undefined ||
+        parentRaw === "null" ||
+        parentRaw === "~"
+        ? null
+        : typeof parentRaw === "string"
+            ? parentRaw
+            : null;
+    const frontMatter = {
+        id,
+        kind,
+        parent,
+        status,
+        priority,
+        rank,
+        started,
+        updated,
+        aliases: parseAliases(raw.aliases),
+        sessions: parseSessions(raw.sessions),
+    };
+    const due = asString(raw.due);
+    const eta = asString(raw.eta);
+    if (due)
+        frontMatter.due = due;
+    if (eta)
+        frontMatter.eta = eta;
+    const trees = parseTrees(raw.trees);
+    if (trees.length > 0)
+        frontMatter.trees = trees;
+    const pendingPrune = parsePendingPrune(raw.pendingPrune);
+    if (pendingPrune.length > 0)
+        frontMatter.pendingPrune = pendingPrune;
+    const scratchDir = asString(raw.scratchDir);
+    if (scratchDir)
+        frontMatter.scratchDir = scratchDir;
+    const primaryPlanId = asString(raw.primaryPlanId);
+    if (primaryPlanId)
+        frontMatter.primaryPlanId = primaryPlanId;
+    const verify = asString(raw.verify);
+    if (verify)
+        frontMatter.verify = verify;
+    const extras = captureExtras(raw, KNOWN_QUEST_KEYS);
+    if (extras)
+        frontMatter._extra = extras;
+    return { frontMatter, body: split.body };
+}
+/**
+ * Why a document's front-matter would not parse, in plain words.
+ *
+ * Discovery drops what it cannot read, and a dropped document is
+ * worse than a broken one: it exists on disk, it is not in any
+ * listing, and nothing anywhere says a record was skipped. Three
+ * documents were invisible this way, two carrying a stage of
+ * `verified` and one `final`, neither of which is a stage.
+ *
+ * Kept apart from {@link parseDocumentFrontMatter} rather than
+ * changing what it returns. The parser has a dozen callers that all
+ * want the same yes-or-no answer, and only the one walking the tree
+ * needs to explain itself.
+ */
+export function explainDocumentFrontMatter(text) {
+    if (!splitFrontMatter(text))
+        return ["it has no front-matter block"];
+    const raw = parseFrontMatterBlock(text);
+    if (!raw)
+        return ["its front-matter block is not readable"];
+    const said = [];
+    if (!asString(raw.id))
+        said.push("it has no id");
+    if (!asString(raw.quest))
+        said.push("it names no quest");
+    if (!asString(raw.updated))
+        said.push("it has no updated date");
+    // The two closed vocabularies, reported with the offending value,
+    // because "kind is invalid" sends the reader to go and look and the
+    // whole point is that they cannot see the record.
+    for (const [field, options] of [
+        ["kind", DOCUMENT_KINDS],
+        ["stage", DOCUMENT_STAGES],
+    ]) {
+        const value = raw[field];
+        if (asEnum(value, options))
+            continue;
+        said.push(value === undefined
+            ? `it has no ${field}`
+            : `its ${field} is ${JSON.stringify(value)}, and the ${field}s are ${options.join(", ")}`);
+    }
+    return said;
+}
+/** Parse a quest document (plan/research/brief/report) front-matter. */
+/**
+ * Why a document's front-matter will not parse, or undefined when it
+ * will.
+ *
+ * Named fields rather than a verdict, because "no valid front-matter" sends
+ * a reader to diff the file against a sibling to work out which key is
+ * wrong. The required set is small and knowable, so it can simply be said.
+ */
+export function documentFrontMatterProblem(text) {
+    const split = splitFrontMatter(text);
+    if (!split)
+        return "it has no front-matter block";
+    const raw = parseFrontMatterBlock(text);
+    if (!raw)
+        return "its front-matter block is not readable as key: value";
+    const missing = [
+        ...(asString(raw.id) ? [] : ["id"]),
+        ...(asEnum(raw.kind, DOCUMENT_KINDS) ? [] : ["kind"]),
+        ...(asString(raw.quest) ? [] : ["quest"]),
+        ...(asEnum(raw.stage, DOCUMENT_STAGES) ? [] : ["stage"]),
+        ...(asString(raw.updated) ? [] : ["updated"]),
+    ];
+    if (missing.length === 0)
+        return undefined;
+    // A present-but-wrong value reads as missing here, so the two enums say
+    // what they accept rather than leaving somebody to guess at a typo.
+    const detail = missing.map((field) => {
+        if (field === "kind" && raw.kind !== undefined) {
+            return `kind (${DOCUMENT_KINDS.join(", ")})`;
+        }
+        if (field === "stage" && raw.stage !== undefined) {
+            return `stage (${DOCUMENT_STAGES.join(", ")})`;
+        }
+        return field;
+    });
+    return `its front-matter is missing or unreadable: ${detail.join(", ")}`;
+}
+export function parseDocumentFrontMatter(text) {
+    const split = splitFrontMatter(text);
+    if (!split)
+        return undefined;
+    const raw = parseFrontMatterBlock(text);
+    if (!raw)
+        return undefined;
+    const id = asString(raw.id);
+    const kind = asEnum(raw.kind, DOCUMENT_KINDS);
+    const quest = asString(raw.quest);
+    const stage = asEnum(raw.stage, DOCUMENT_STAGES);
+    const updated = asString(raw.updated);
+    if (!id || !kind || !quest || !stage || !updated)
+        return undefined;
+    const fm = { id, kind, quest, stage, updated };
+    const rounds = asNumber(raw.rounds);
+    if (rounds !== undefined && Number.isInteger(rounds) && rounds >= 0) {
+        fm.rounds = rounds;
+    }
+    const subject = asString(raw.subject);
+    if (subject)
+        fm.subject = subject;
+    const extras = captureExtras(raw, KNOWN_DOCUMENT_KEYS);
+    if (extras)
+        fm._extra = extras;
+    return { frontMatter: fm, body: split.body };
+}
+function sessionToPlain(session) {
+    const out = { id: session.id };
+    if (session.name !== undefined)
+        out.name = session.name;
+    if (session.cwd !== undefined)
+        out.cwd = session.cwd;
+    if (session.started !== undefined)
+        out.started = session.started;
+    if (session.status !== undefined)
+        out.status = session.status;
+    if (session.instanceId !== undefined)
+        out.instanceId = session.instanceId;
+    if (session.process !== undefined)
+        out.process = { ...session.process };
+    if (session.terminal !== undefined)
+        out.terminal = { ...session.terminal };
+    return out;
+}
+function renderYamlBlock(payload) {
+    // stringifyYaml emits with a trailing newline. Trim so the
+    // fenced block is exactly the fields we care about and the
+    // downstream join keeps the fence shape stable.
+    const text = stringifyYaml(payload, {
+        lineWidth: 0,
+        nullStr: "null",
+    }).replace(/\n$/, "");
+    return ["---", text, "---"].join("\n");
+}
+/**
+ * Serialize front matter over a body, refusing a result the strict
+ * parser cannot read back.
+ *
+ * Every quest writer has to meet this rule, and until now each one
+ * decided for itself whether to. The mutation core checked, the tree
+ * writer carried its own copy of the check, and the scratch writer
+ * did not check at all, which is how a write can leave a README that
+ * discovery then cannot see. Serializing and checking is the part
+ * they genuinely share; taking the lock is not, since a caller
+ * already holding one cannot take it again.
+ */
+export function serializeReadable(fm, body) {
+    const text = `${serializeQuestFrontMatter(fm)}\n${body}`;
+    if (!parseQuestFrontMatter(text)) {
+        return {
+            ok: false,
+            reason: `Refusing the write: it would give ${fm.id} front matter the parser cannot read back.`,
+        };
+    }
+    return { ok: true, text };
+}
+/** Serialize a quest front-matter back to a `---` block. */
+export function serializeQuestFrontMatter(fm) {
+    const payload = {
+        id: fm.id,
+        kind: fm.kind,
+        parent: fm.parent,
+        status: fm.status,
+        priority: fm.priority,
+        rank: fm.rank,
+        started: fm.started,
+        updated: fm.updated,
+    };
+    if (fm.due)
+        payload.due = fm.due;
+    if (fm.eta)
+        payload.eta = fm.eta;
+    payload.aliases = fm.aliases.map((a) => ({ type: a.type, value: a.value }));
+    payload.sessions = fm.sessions.map(sessionToPlain);
+    if (fm.trees && fm.trees.length > 0) {
+        payload.trees = fm.trees.map(treeToPlain);
+    }
+    if (fm.pendingPrune && fm.pendingPrune.length > 0) {
+        payload.pendingPrune = fm.pendingPrune.map((entry) => ({
+            path: entry.path,
+            reason: entry.reason,
+            detectedAt: entry.detectedAt,
+        }));
+    }
+    if (fm.scratchDir)
+        payload.scratchDir = fm.scratchDir;
+    if (fm.primaryPlanId)
+        payload.primaryPlanId = fm.primaryPlanId;
+    if (fm.verify)
+        payload.verify = fm.verify;
+    if (fm._extra) {
+        for (const [key, value] of Object.entries(fm._extra)) {
+            if (!(key in payload))
+                payload[key] = value;
+        }
+    }
+    return renderYamlBlock(payload);
+}
+function treeToPlain(tree) {
+    const out = {
+        path: tree.path,
+        providerId: tree.providerId,
+    };
+    if (tree.branch !== undefined)
+        out.branch = tree.branch;
+    if (tree.repoRoot !== undefined)
+        out.repoRoot = tree.repoRoot;
+    if (tree.zones && tree.zones.length > 0)
+        out.zones = tree.zones;
+    if (tree.origin !== undefined)
+        out.origin = tree.origin;
+    return out;
+}
+/** Serialize a document front-matter back to a `---` block. */
+export function serializeDocumentFrontMatter(fm) {
+    const payload = {
+        id: fm.id,
+        kind: fm.kind,
+        quest: fm.quest,
+        stage: fm.stage,
+        updated: fm.updated,
+    };
+    if (fm.rounds !== undefined)
+        payload.rounds = fm.rounds;
+    if (fm.subject)
+        payload.subject = fm.subject;
+    if (fm._extra) {
+        for (const [key, value] of Object.entries(fm._extra)) {
+            if (!(key in payload))
+                payload[key] = value;
+        }
+    }
+    return renderYamlBlock(payload);
+}

package/dist/internal/quest/git-signals.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Production git predicates for the write classifier. Each shells
+ * out to git from the directory enclosing the target, so a target
+ * in a different repository than the session cwd is judged against
+ * its own repository. Every call fails closed to the safe answer
+ * when git is absent, the path is outside a repository, or the
+ * subprocess errors: no tree root, not ignored, not tracked.
+ *
+ * The pure classifier takes these as injected predicates; this
+ * module is the real implementation it composes in production.
+ */
+/**
+ * The git working tree root containing the target, or null when the
+ * target is not inside any repository. Resolves through `.git` files
+ * (worktrees) natively via rev-parse.
+ *
+ * Accepts a directory as readily as a file. It did not always: it ran
+ * git from `located().dir`, which resolves an existing directory to
+ * its parent, and the parent of a repository root is outside the
+ * repository. So the one input a caller is most likely to hold, the
+ * root of the checkout they are standing in, answered null. Two
+ * callers knew and worked around it by appending a filename they
+ * invented; the third did not, and shipped a verb that refused in the
+ * only place it was meant to work.
+ */
+export declare function gitTreeRootOf(absPath: string): string | null;
+/**
+ * Whether the target sits in a repository's primary checkout, as
+ * opposed to a linked worktree. The main tree's git-dir equals its
+ * git-common-dir; a linked worktree's git-dir is under
+ * `.git/worktrees/`, so the two differ. False when git cannot answer
+ * or the path is outside any repository, so a doubtful case never
+ * reads as the shared main tree by accident.
+ */
+export declare function isMainWorkingTree(absPath: string): boolean;
+/** Whether the target is gitignored at its destination. */
+export declare function isGitignored(absPath: string): boolean;
+/**
+ * Canonicalize a path for comparison, tolerating a path that does
+ * not exist yet. Resolves the longest existing ancestor (which
+ * turns /var into /private/var on macOS) and re-appends the missing
+ * tail. The literal path survives a total failure.
+ */
+export declare function canonicalPath(p: string): string;
+/**
+ * Whether `child` is `parent` or lives beneath it, comparing
+ * canonicalized paths with a separator boundary so a /var versus
+ * /private/var spelling still matches and a sibling whose name
+ * merely shares a prefix (feature-2 against feat) does not.
+ */
+export declare function isWithin(child: string, parent: string): boolean;
+/** Whether the target is tracked in its repository's index. */
+export declare function isTracked(absPath: string): boolean;