@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/quest/discovery.js

@@ -0,0 +1,354 @@
+/**
+ * Quest discovery: walk a quest tree on disk and build an
+ * in-memory index.
+ *
+ * Canonical disk layout (within `questsRoot`):
+ *
+ *     QEST-20260603-AAA111/
+ *       README.md
+ *       plans/PLAN-20260603-BBB222.md
+ *       research/RSCH-20260605-CCC333.md
+ *       briefs/BRIF-20260606-EEE555.md
+ *       reports/RPRT-20260607-FFF666.md
+ *     QEST-20260610-DDD444/           (subquest of AAA111,
+ *       README.md                       parent: QEST-...-AAA111
+ *                                       lives flat at the
+ *                                       quests root, not
+ *                                       nested in its
+ *                                       parent's directory)
+ *
+ * All quests live as immediate children of `questsRoot`.
+ * Hierarchy is expressed by the `parent:` front-matter
+ * field on each quest's README, not by directory nesting.
+ * Documents (plans, research, briefs, reports) live inside
+ * their owning quest's kind subdirectory (`plans/`,
+ * `research/`, `briefs/`, `reports/`).
+ *
+ * Discovery enforces these invariants. Two drift patterns
+ * are surfaced as `DiscoveryError` and the offending entry
+ * is skipped:
+ *
+ * - a `QEST-*` directory found inside another quest
+ * - a `PLAN-/RSCH-/BRIF-/RPRT-*.md` file at a quest's root
+ *   instead of in its kind subdirectory
+ *
+ * Free-form subdirectories under a quest (`runs/`,
+ * `tools/`, `workloads/`, etc.) are not walked. They're
+ * surfaced only via the quest's own body references.
+ */
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, realpathSync } from "node:fs";
+import { extname, join } from "node:path";
+import { explainDocumentFrontMatter, parseDocumentFrontMatter, } from "./frontmatter.js";
+import { isId, prefixOf } from "./id.js";
+import { extractTitle, parseQuestDoc } from "./quest-doc.js";
+/**
+ * Maximum directory depth the walk follows. A quest tree
+ * with depth past this is almost certainly a symlink loop
+ * or accidental nesting; we stop and log an error rather
+ * than wedge every quest action.
+ */
+const MAX_WALK_DEPTH = 16;
+/**
+ * The ranks of every quest sharing a parent and priority bucket (a
+ * sibling set), optionally excluding one id. Callers pair this with
+ * `nextRank` to place a new or moved quest at the next free rank in
+ * its group rather than colliding at rank 1.
+ */
+export function siblingRanks(index, parent, priority, excludeId) {
+    const ranks = [];
+    for (const entry of index.quests.values()) {
+        const fm = entry.doc.frontMatter;
+        if (fm.id === excludeId)
+            continue;
+        if ((fm.parent ?? null) !== parent)
+            continue;
+        if (fm.priority !== priority)
+            continue;
+        ranks.push(fm.rank);
+    }
+    return ranks;
+}
+function readMaybe(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        // Path doesn't exist or is unreadable; the caller
+        // will surface the read error separately.
+        return undefined;
+    }
+}
+const CANONICAL_DOCUMENT_DIRS = [
+    "plans",
+    "research",
+    "briefs",
+    "reports",
+];
+function readEntries(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseDocumentFile(text) {
+    const parsed = parseDocumentFrontMatter(text);
+    if (!parsed)
+        return undefined;
+    return {
+        frontMatter: parsed.frontMatter,
+        body: parsed.body,
+        title: extractTitle(parsed.body),
+    };
+}
+const discoveryCache = new Map();
+/**
+ * Drop the discovery memo. Tests call this between runs; write
+ * paths do not need it because the signature catches their
+ * changes on the next read.
+ */
+export function clearDiscoveryCache() {
+    discoveryCache.clear();
+}
+/**
+ * Walk `questsRoot` and build the index, memoized per root. The
+ * walk re-parses every README and document, which is the costly
+ * part; this caches the result behind a cheap mtime-and-size
+ * signature so repeated read verbs in a session do not re-parse
+ * an unchanged tree. The signature recomputes on every call (a
+ * directory traversal plus stats, no file reads), so any change
+ * to a README, a document, or the set of quests invalidates the
+ * cache on the next read.
+ */
+export function discoverQuests(questsRoot) {
+    const signature = discoverySignature(questsRoot);
+    const cached = discoveryCache.get(questsRoot);
+    if (cached && cached.signature === signature)
+        return cached.result;
+    const result = discoverQuestsUncached(questsRoot);
+    discoveryCache.set(questsRoot, { signature, result });
+    return result;
+}
+/**
+ * A content-sensitive fingerprint of the quest tree. For each
+ * quest it hashes the README and every document file, so an edit
+ * that keeps the byte size identical (a status flip, a same-length
+ * reparent, a date-only stamp) still moves the signature. It also
+ * folds in the directory listings of the root and each quest dir,
+ * so the layout-drift conditions that drive the discovery `errors`
+ * (a stray non-quest entry, a misplaced document at a quest root,
+ * a nested quest) move it too. Hashing reads the file bytes but
+ * skips the parse and object construction the cache exists to
+ * avoid, so a warm read still wins on a large tree.
+ */
+function discoverySignature(questsRoot) {
+    const parts = [];
+    const stampContent = (path) => {
+        try {
+            const hash = createHash("sha1").update(readFileSync(path)).digest("hex");
+            parts.push(`${path}:${hash}`);
+        }
+        catch {
+            // Missing or unreadable file contributes nothing; its
+            // absence is itself a change from a signature that had it.
+        }
+    };
+    const layout = (entries) => entries
+        .map((e) => `${e.name}/${e.isDirectory() ? "d" : "f"}`)
+        .sort()
+        .join(",");
+    const rootEntries = readEntries(questsRoot);
+    if (!rootEntries)
+        return "absent";
+    parts.push(`root:${layout(rootEntries)}`);
+    for (const entry of rootEntries) {
+        if (!entry.isDirectory())
+            continue;
+        if (!isId(entry.name) || prefixOf(entry.name) !== "QEST")
+            continue;
+        const questDir = join(questsRoot, entry.name);
+        const questEntries = readEntries(questDir);
+        if (questEntries)
+            parts.push(`${entry.name}:${layout(questEntries)}`);
+        stampContent(join(questDir, "README.md"));
+        for (const subdir of CANONICAL_DOCUMENT_DIRS) {
+            const scanDir = join(questDir, subdir);
+            const docEntries = readEntries(scanDir);
+            if (!docEntries)
+                continue;
+            for (const doc of docEntries) {
+                if (doc.isFile())
+                    stampContent(join(scanDir, doc.name));
+            }
+        }
+    }
+    return parts.sort().join("|");
+}
+function discoverQuestsUncached(questsRoot) {
+    const quests = new Map();
+    const children = new Map();
+    const errors = [];
+    const visited = new Set();
+    function scanDocuments(questDir) {
+        const documents = [];
+        // Surface any doc-id-named file at the quest-dir root
+        // as a layout error: the canonical home for those is a
+        // kind subdirectory. We still skip the entry rather
+        // than parse it, so a stray misplaced file does not
+        // double-register.
+        const questEntries = readEntries(questDir);
+        if (questEntries) {
+            for (const entry of questEntries) {
+                if (!entry.isFile())
+                    continue;
+                if (extname(entry.name) !== ".md")
+                    continue;
+                const base = entry.name.slice(0, -3);
+                if (!isId(base) || prefixOf(base) === "QEST")
+                    continue;
+                errors.push({
+                    path: join(questDir, entry.name),
+                    message: `Document "${entry.name}" sits at the quest-dir root instead of in its kind subdirectory.`,
+                });
+            }
+        }
+        for (const subdir of CANONICAL_DOCUMENT_DIRS) {
+            const scanDir = join(questDir, subdir);
+            const entries = readEntries(scanDir);
+            if (!entries)
+                continue;
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                const child = entry.name;
+                const childPath = join(scanDir, child);
+                if (extname(child) !== ".md")
+                    continue;
+                const base = child.slice(0, -3);
+                if (!isId(base) || prefixOf(base) === "QEST")
+                    continue;
+                const docText = readMaybe(childPath);
+                if (!docText)
+                    continue;
+                const docDoc = parseDocumentFile(docText);
+                if (docDoc) {
+                    documents.push({ path: childPath, doc: docDoc });
+                    continue;
+                }
+                // Surfaced rather than skipped. A file named like a document,
+                // sitting where documents live, that nothing can read is the
+                // one case where silence is indistinguishable from the file
+                // not existing, and the record does exist.
+                errors.push({
+                    path: childPath,
+                    message: `Document "${child}" could not be read: ${explainDocumentFrontMatter(docText).join("; ")}.`,
+                });
+            }
+        }
+        return documents;
+    }
+    function reportNestedQuests(questDir, depth) {
+        if (depth > MAX_WALK_DEPTH) {
+            errors.push({
+                path: questDir,
+                message: `Walk depth exceeded ${MAX_WALK_DEPTH}; refusing to recurse further.`,
+            });
+            return;
+        }
+        const entries = readEntries(questDir);
+        if (!entries)
+            return;
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            if (!entry.isDirectory())
+                continue;
+            const name = entry.name;
+            if (isId(name) && prefixOf(name) === "QEST") {
+                errors.push({
+                    path: join(questDir, name),
+                    message: `Nested quest "${name}" found inside another quest. Quests live as immediate children of the quests root; hierarchy is expressed by the parent: front-matter field.`,
+                });
+                reportNestedQuests(join(questDir, name), depth + 1);
+            }
+        }
+    }
+    function acceptQuest(name, full) {
+        const readmePath = join(full, "README.md");
+        const text = readMaybe(readmePath);
+        if (!text) {
+            errors.push({ path: readmePath, message: "README.md missing" });
+            return;
+        }
+        const doc = parseQuestDoc(text);
+        if (!doc) {
+            errors.push({
+                path: readmePath,
+                message: "Front-matter invalid or absent.",
+            });
+            return;
+        }
+        if (doc.frontMatter.id !== name) {
+            errors.push({
+                path: readmePath,
+                message: `Directory name "${name}" does not match front-matter id "${doc.frontMatter.id}".`,
+            });
+        }
+        const documents = scanDocuments(full);
+        quests.set(doc.frontMatter.id, { dir: full, doc, documents });
+        const parentKey = doc.frontMatter.parent ?? "";
+        const list = children.get(parentKey) ?? [];
+        list.push(doc.frontMatter.id);
+        children.set(parentKey, list);
+        // Look for nested quests inside this one and surface
+        // them as errors; never index them.
+        reportNestedQuests(full, 1);
+    }
+    const rootEntries = readEntries(questsRoot);
+    if (!rootEntries) {
+        errors.push({
+            path: questsRoot,
+            message: "Quests root does not exist as a directory.",
+        });
+        return { index: { quests, children }, errors };
+    }
+    const rootReal = safeRealpath(questsRoot);
+    if (rootReal)
+        visited.add(rootReal);
+    for (const entry of rootEntries) {
+        const name = entry.name;
+        if (entry.isSymbolicLink())
+            continue;
+        if (!entry.isDirectory())
+            continue;
+        if (name === "node_modules" || name === ".git" || name.startsWith(".")) {
+            continue;
+        }
+        const full = join(questsRoot, name);
+        const real = safeRealpath(full);
+        if (real) {
+            if (visited.has(real))
+                continue;
+            visited.add(real);
+        }
+        if (isId(name) && prefixOf(name) === "QEST") {
+            acceptQuest(name, full);
+            continue;
+        }
+        errors.push({
+            path: full,
+            message: `Unexpected directory "${name}" at quests root. Only QEST-* directories belong here.`,
+        });
+    }
+    return { index: { quests, children }, errors };
+}

package/dist/internal/quest/fields.d.ts

@@ -0,0 +1,37 @@
+/**
+ * How to read and write each quest front-matter field the structural
+ * journal records.
+ *
+ * This exists because the same knowledge used to live in three
+ * switch statements: one to diff a write into journal changes, one to
+ * check the on-disk value still matched before undoing, and one to
+ * write the old value back. They agreed, but only by coincidence, and
+ * a field added to one and missed in another failed silently in the
+ * worst direction: the change was journalled and then skipped forever
+ * at undo time, or reversed without ever being checked.
+ *
+ * With one table, a field is journalled exactly when it is
+ * reversible, because both questions read the same entry.
+ */
+import type { QuestFrontMatter } from "../../quest/types.js";
+import type { MutableField } from "./structural-journal.js";
+/** Reading and writing one field, as strings, the way the journal holds them. */
+export interface QuestFieldLens {
+    /** The field's current value, or null where the field is unset. */
+    read(fm: QuestFrontMatter): string | null;
+    /** The front matter with the field set, or why the value is not allowed. */
+    write(fm: QuestFrontMatter, value: string | null): {
+        ok: true;
+        fm: QuestFrontMatter;
+    } | {
+        ok: false;
+        reason: string;
+    };
+}
+/** How to read and write `field`, or undefined if it is not on a quest README. */
+export declare function lensForField(field: MutableField): QuestFieldLens | undefined;
+/**
+ * The fields the journal tracks and undo can reverse. One list,
+ * derived from the table, so the two cannot drift apart.
+ */
+export declare function reversibleFields(): MutableField[];

package/dist/internal/quest/fields.js

@@ -0,0 +1,94 @@
+/**
+ * How to read and write each quest front-matter field the structural
+ * journal records.
+ *
+ * This exists because the same knowledge used to live in three
+ * switch statements: one to diff a write into journal changes, one to
+ * check the on-disk value still matched before undoing, and one to
+ * write the old value back. They agreed, but only by coincidence, and
+ * a field added to one and missed in another failed silently in the
+ * worst direction: the change was journalled and then skipped forever
+ * at undo time, or reversed without ever being checked.
+ *
+ * With one table, a field is journalled exactly when it is
+ * reversible, because both questions read the same entry.
+ */
+const STATUSES = [
+    "active",
+    "paused",
+    "blocked",
+    "concluded",
+    "retired",
+];
+const PRIORITIES = [
+    "driving",
+    "active",
+    "queued",
+    "bench",
+    "someday",
+];
+const KINDS = ["quest", "subquest", "sidequest"];
+/**
+ * A lens over a field holding one of a fixed set of words.
+ *
+ * The vocabulary is checked rather than cast. Undo used to cast a
+ * journalled string straight to the field's type, which is fine while
+ * every journal entry was written by the current build and unsafe the
+ * moment one was not: a word the vocabulary has since lost would be
+ * written back unexamined.
+ */
+function wordFrom(field, vocabulary) {
+    return {
+        read: (fm) => fm[field],
+        write: (fm, value) => {
+            const allowed = vocabulary;
+            if (value === null || !allowed.includes(value)) {
+                return {
+                    ok: false,
+                    reason: `Cannot set ${field} to ${value ?? "nothing"}: it is not one of ${allowed.join(", ")}.`,
+                };
+            }
+            return { ok: true, fm: { ...fm, [field]: value } };
+        },
+    };
+}
+const LENSES = {
+    // Nullable: a quest at top level has no parent, and undoing a
+    // reparent to top level means writing that null back deliberately.
+    parent: {
+        read: (fm) => fm.parent ?? null,
+        write: (fm, value) => ({ ok: true, fm: { ...fm, parent: value } }),
+    },
+    status: wordFrom("status", STATUSES),
+    priority: wordFrom("priority", PRIORITIES),
+    kind: wordFrom("kind", KINDS),
+    rank: {
+        read: (fm) => String(fm.rank),
+        write: (fm, value) => {
+            const rank = Number(value);
+            if (value === null || value.trim() === "" || !Number.isFinite(rank)) {
+                return {
+                    ok: false,
+                    reason: `Cannot set rank to ${value ?? "nothing"}: it is not a number.`,
+                };
+            }
+            return { ok: true, fm: { ...fm, rank } };
+        },
+    },
+    // No entry for `stage`. It is journallable, but it lives on a
+    // document rather than on the quest README, so there is nothing here
+    // that could read or write it. Undo finds no lens and skips the
+    // change, which is the honest reason rather than a sentinel value
+    // contrived never to match.
+};
+/** How to read and write `field`, or undefined if it is not on a quest README. */
+export function lensForField(field) {
+    return LENSES[field];
+}
+/**
+ * The fields the journal tracks and undo can reverse. One list,
+ * derived from the table, so the two cannot drift apart.
+ */
+export function reversibleFields() {
+    return Object.keys(LENSES);
+}

package/dist/internal/quest/frontmatter.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 type { DocumentFrontMatter, QuestFrontMatter } from "../../quest/types.js";
+/** Split a text into the front-matter block (raw YAML) and the body. */
+export declare function splitFrontMatter(text: string): {
+    fmText: string;
+    body: string;
+} | undefined;
+/** Parse the quest README front-matter from raw text. */
+export declare function parseQuestFrontMatter(text: string): {
+    frontMatter: QuestFrontMatter;
+    body: string;
+} | undefined;
+/**
+ * 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 declare function explainDocumentFrontMatter(text: string): string[];
+/** 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 declare function documentFrontMatterProblem(text: string): string | undefined;
+export declare function parseDocumentFrontMatter(text: string): {
+    frontMatter: DocumentFrontMatter;
+    body: string;
+} | undefined;
+/**
+ * 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 declare function serializeReadable(fm: QuestFrontMatter, body: string): {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Serialize a quest front-matter back to a `---` block. */
+export declare function serializeQuestFrontMatter(fm: QuestFrontMatter): string;
+/** Serialize a document front-matter back to a `---` block. */
+export declare function serializeDocumentFrontMatter(fm: DocumentFrontMatter): string;