@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/quest/structural.js

@@ -0,0 +1,77 @@
+/**
+ * Structural edits to the quest tree: reparenting and bulk
+ * status changes. The planners here are pure: they read an
+ * in-memory index and compute what would change, validating
+ * scope and refusing cycles, so a caller can preview before it
+ * writes and report exactly what moved.
+ */
+/**
+ * Plan the parent changes for `targetIds` against `newParent`
+ * without touching disk. No-op moves are dropped; missing
+ * quests, a missing new parent, self-parenting and cycle-forming
+ * moves are reported in `errors`.
+ */
+export function planReparent(index, targetIds, newParent) {
+    const changes = [];
+    const errors = [];
+    if (newParent !== null && !index.quests.has(newParent)) {
+        return { changes: [], errors: [`New parent ${newParent} not found.`] };
+    }
+    for (const id of targetIds) {
+        const entry = index.quests.get(id);
+        if (!entry) {
+            errors.push(`Quest ${id} not found.`);
+            continue;
+        }
+        if (newParent === id) {
+            errors.push(`${id} cannot be its own parent (cycle).`);
+            continue;
+        }
+        if (newParent !== null && isDescendant(index, newParent, id)) {
+            errors.push(`Reparenting ${id} under ${newParent} would form a cycle.`);
+            continue;
+        }
+        const oldParent = entry.doc.frontMatter.parent ?? null;
+        if (oldParent === newParent)
+            continue;
+        changes.push({ id, oldParent, newParent });
+    }
+    return { changes, errors };
+}
+/**
+ * Plan the status changes for `targetIds` to `newStatus` without
+ * touching disk. Quests already at the target status are dropped;
+ * missing quests are reported in `errors`.
+ */
+export function planStatusChange(index, targetIds, newStatus) {
+    const changes = [];
+    const errors = [];
+    for (const id of targetIds) {
+        const entry = index.quests.get(id);
+        if (!entry) {
+            errors.push(`Quest ${id} not found.`);
+            continue;
+        }
+        const oldStatus = entry.doc.frontMatter.status;
+        if (oldStatus === newStatus)
+            continue;
+        changes.push({ id, oldStatus, newStatus });
+    }
+    return { changes, errors };
+}
+/**
+ * Is `candidate` inside `ancestor`'s subtree? Walks up the parent
+ * chain from `candidate`; a visited set keeps pre-existing cyclic
+ * data from spinning.
+ */
+function isDescendant(index, candidate, ancestor) {
+    const seen = new Set();
+    let cursor = candidate;
+    while (cursor !== null && !seen.has(cursor)) {
+        seen.add(cursor);
+        if (cursor === ancestor)
+            return true;
+        cursor = index.quests.get(cursor)?.doc.frontMatter.parent ?? null;
+    }
+    return false;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Table-of-contents renderer: produce the at-a-glance index
+ * of the whole tree on demand. This builds the markdown; it
+ * does not write a file. Nothing auto-generates a QUESTS.md,
+ * so a consumer that wants one calls this and writes the
+ * result itself.
+ *
+ * Shape:
+ *
+ *     # Quests
+ *
+ *     ## 🚀 Driving
+ *
+ *     - ◆ QEST-... Title One [status]
+ *     - ◇ QEST-... Title Two [status]
+ *
+ *     ## ⚡ Active
+ *
+ *     ...
+ *
+ * Quests are grouped by priority (Driving, Active, Queued,
+ * Bench, Someday) and within each group sorted by rank.
+ * Concluded and retired quests collapse into a single
+ * trailing section so they don't crowd the live work.
+ */
+import type { QuestIndex } from "./discovery.js";
+/** Render the TOC as a markdown string. */
+export declare function renderToc(index: QuestIndex): string;

package/dist/internal/quest/toc.js

@@ -0,0 +1,90 @@
+/**
+ * Table-of-contents renderer: produce the at-a-glance index
+ * of the whole tree on demand. This builds the markdown; it
+ * does not write a file. Nothing auto-generates a QUESTS.md,
+ * so a consumer that wants one calls this and writes the
+ * result itself.
+ *
+ * Shape:
+ *
+ *     # Quests
+ *
+ *     ## 🚀 Driving
+ *
+ *     - ◆ QEST-... Title One [status]
+ *     - ◇ QEST-... Title Two [status]
+ *
+ *     ## ⚡ Active
+ *
+ *     ...
+ *
+ * Quests are grouped by priority (Driving, Active, Queued,
+ * Bench, Someday) and within each group sorted by rank.
+ * Concluded and retired quests collapse into a single
+ * trailing section so they don't crowd the live work.
+ */
+const PRIORITY_LABELS = [
+    { priority: "driving", label: "🚀 Driving" },
+    { priority: "active", label: "⚡ Active" },
+    { priority: "queued", label: "📋 Queued" },
+    { priority: "bench", label: "🪑 Bench" },
+    { priority: "someday", label: "🌌 Someday" },
+];
+const KIND_GLYPHS = {
+    quest: "◆",
+    subquest: "◈",
+    sidequest: "◇",
+};
+const PROGRESS_BAR = {
+    active: "○",
+    paused: "◔",
+    blocked: "◑",
+    concluded: "●",
+    retired: "◕",
+};
+function questLine(entry) {
+    const fm = entry.doc.frontMatter;
+    const kindGlyph = KIND_GLYPHS[fm.kind] ?? "·";
+    const statusGlyph = PROGRESS_BAR[fm.status] ?? "·";
+    const title = entry.doc.title ?? "(untitled)";
+    return `- ${kindGlyph} ${statusGlyph} \`${fm.id}\` ${title}`;
+}
+function sortEntries(entries) {
+    return [...entries].sort((a, b) => {
+        const rankCmp = a.doc.frontMatter.rank - b.doc.frontMatter.rank;
+        if (rankCmp !== 0)
+            return rankCmp;
+        return a.doc.frontMatter.id.localeCompare(b.doc.frontMatter.id);
+    });
+}
+/** Render the TOC as a markdown string. */
+export function renderToc(index) {
+    const live = [];
+    const concluded = [];
+    for (const entry of index.quests.values()) {
+        const status = entry.doc.frontMatter.status;
+        if (status === "concluded" || status === "retired") {
+            concluded.push(entry);
+        }
+        else {
+            live.push(entry);
+        }
+    }
+    const sections = ["# Quests", ""];
+    for (const { priority, label } of PRIORITY_LABELS) {
+        const group = sortEntries(live.filter((e) => e.doc.frontMatter.priority === priority));
+        if (group.length === 0)
+            continue;
+        sections.push(`## ${label}`, "");
+        for (const entry of group)
+            sections.push(questLine(entry));
+        sections.push("");
+    }
+    if (concluded.length > 0) {
+        sections.push("## 🗄️ Concluded and Retired", "");
+        for (const entry of sortEntries(concluded))
+            sections.push(questLine(entry));
+        sections.push("");
+    }
+    return `${sections.join("\n").replace(/\n+$/, "")}\n`;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Quest tree operations. Pure file-and-frontmatter
+ * helpers; the extension wires them to a loaded quest.
+ *
+ * Trees live on a quest's frontmatter `trees:` array.
+ * Aliases mirror each tree as `git-worktree:<path>` and
+ * `git-branch:<branch>` so the cwd-walk auto-attach can
+ * find the quest from inside the tree.
+ */
+import type { QuestTree } from "../../quest/types.js";
+/** Append a tree to the quest's `trees:` list with its aliases. */
+export declare function addTreeToQuest(questDir: string, tree: QuestTree): {
+    ok: true;
+    added: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Remove a tree (by path) from the quest's `trees:` list. */
+export declare function removeTreeFromQuest(questDir: string, path: string): {
+    ok: true;
+    removed: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Snapshot the quest's tree list. */
+export declare function listTreesOnQuest(questDir: string): {
+    ok: true;
+    trees: QuestTree[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Append or replace a pendingPrune entry on the quest. Each
+ * blocked tree is keyed by `path`: a second blocker for the
+ * same path overwrites the first; blockers for distinct
+ * paths accumulate. Pass `null` to clear every entry, or
+ * pass `clearPath` to clear one entry by tree path.
+ */
+export declare function setPendingPrune(questDir: string, pending: {
+    path: string;
+    reason: string;
+    detectedAt: string;
+} | null, options?: {
+    clearPath?: string;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/internal/quest/trees.js

@@ -0,0 +1,145 @@
+/**
+ * Quest tree operations. Pure file-and-frontmatter
+ * helpers; the extension wires them to a loaded quest.
+ *
+ * Trees live on a quest's frontmatter `trees:` array.
+ * Aliases mirror each tree as `git-worktree:<path>` and
+ * `git-branch:<branch>` so the cwd-walk auto-attach can
+ * find the quest from inside the tree.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseQuestFrontMatter } from "./frontmatter.js";
+import { mutateQuestFrontMatter } from "./mutate.js";
+/** Path to a quest's README. */
+function questReadme(questDir) {
+    return join(questDir, "README.md");
+}
+/**
+ * Apply a tree or alias change through the shared mutation core.
+ *
+ * This used to be a second copy of that core, living here because
+ * trees were written before it existed. It locked, parsed, validated
+ * by parse-back and wrote, all correctly, and stamped no `updated`
+ * and journalled nothing, so adopting a tree left the quest reading
+ * older than it was. Two implementations of one rule means one of
+ * them is wrong, and it was this one.
+ *
+ * The transform reports what it did through the caller's own
+ * closure, so nothing needs to travel back out of the lock.
+ */
+function changeQuestFrontMatter(questDir, transform, op) {
+    const outcome = mutateQuestFrontMatter(questDir, transform, { op });
+    return outcome.ok ? { ok: true } : { ok: false, reason: outcome.guidance };
+}
+function ensureAlias(aliases, alias) {
+    const exists = aliases.some((a) => a.type === alias.type && a.value === alias.value);
+    if (exists)
+        return false;
+    aliases.push(alias);
+    return true;
+}
+function removeAlias(aliases, alias) {
+    const before = aliases.length;
+    for (let i = aliases.length - 1; i >= 0; i--) {
+        if (aliases[i].type === alias.type && aliases[i].value === alias.value) {
+            aliases.splice(i, 1);
+        }
+    }
+    return aliases.length !== before;
+}
+/** Append a tree to the quest's `trees:` list with its aliases. */
+export function addTreeToQuest(questDir, tree) {
+    let addedFlag = false;
+    const outcome = changeQuestFrontMatter(questDir, (fm) => {
+        const trees = fm.trees ?? [];
+        // Already there: no change at all, rather than a rewrite that
+        // stamps `updated` for a quest nothing happened to.
+        if (trees.some((t) => t.path === tree.path))
+            return undefined;
+        addedFlag = true;
+        const nextTrees = [...trees, tree];
+        const nextAliases = [...fm.aliases];
+        ensureAlias(nextAliases, { type: "git-worktree", value: tree.path });
+        if (tree.branch) {
+            ensureAlias(nextAliases, { type: "git-branch", value: tree.branch });
+        }
+        return { ...fm, trees: nextTrees, aliases: nextAliases };
+    }, "tree-add");
+    if (!outcome.ok)
+        return outcome;
+    return { ok: true, added: addedFlag };
+}
+/** Remove a tree (by path) from the quest's `trees:` list. */
+export function removeTreeFromQuest(questDir, path) {
+    let removedFlag = false;
+    const outcome = changeQuestFrontMatter(questDir, (fm) => {
+        const trees = fm.trees ?? [];
+        const target = trees.find((t) => t.path === path);
+        if (!target)
+            return undefined;
+        removedFlag = true;
+        const nextTrees = trees.filter((t) => t.path !== path);
+        const nextAliases = [...fm.aliases];
+        removeAlias(nextAliases, { type: "git-worktree", value: path });
+        if (target.branch) {
+            removeAlias(nextAliases, { type: "git-branch", value: target.branch });
+        }
+        const next = { ...fm, aliases: nextAliases };
+        if (nextTrees.length > 0)
+            next.trees = nextTrees;
+        else
+            delete next.trees;
+        return next;
+    }, "tree-remove");
+    if (!outcome.ok)
+        return outcome;
+    return { ok: true, removed: removedFlag };
+}
+/** Snapshot the quest's tree list. */
+export function listTreesOnQuest(questDir) {
+    const path = questReadme(questDir);
+    if (!existsSync(path))
+        return { ok: false, reason: "Quest README not found." };
+    // Read-only: the atomic-rename write contract guarantees
+    // observers see either the old or the new file in full,
+    // so this readFileSync cannot tear against a concurrent
+    // writer.
+    const text = readFileSync(path, "utf8");
+    const parsed = parseQuestFrontMatter(text);
+    if (!parsed) {
+        return { ok: false, reason: "Quest README has no readable frontmatter." };
+    }
+    return { ok: true, trees: parsed.frontMatter.trees ?? [] };
+}
+/**
+ * Append or replace a pendingPrune entry on the quest. Each
+ * blocked tree is keyed by `path`: a second blocker for the
+ * same path overwrites the first; blockers for distinct
+ * paths accumulate. Pass `null` to clear every entry, or
+ * pass `clearPath` to clear one entry by tree path.
+ */
+export function setPendingPrune(questDir, pending, options) {
+    const outcome = changeQuestFrontMatter(questDir, (fm) => {
+        const next = { ...fm };
+        const existing = next.pendingPrune ?? [];
+        let merged = existing;
+        if (pending === null && !options?.clearPath) {
+            merged = [];
+        }
+        else if (options?.clearPath) {
+            merged = existing.filter((e) => e.path !== options.clearPath);
+        }
+        if (pending) {
+            merged = [...merged.filter((e) => e.path !== pending.path), pending];
+        }
+        if (merged.length > 0)
+            next.pendingPrune = merged;
+        else
+            delete next.pendingPrune;
+        return next;
+    }, "tree-pending-prune");
+    if (!outcome.ok)
+        return outcome;
+    return { ok: true };
+}

package/dist/internal/quest/url-fetchers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * URL fetchers for the `quest create --url=...` path.
+ *
+ * A fetcher takes a parsed ref (type + value) and returns
+ * a `SeedHints` payload the create action uses to fill in
+ * the new quest's title, originator and first Journey
+ * entry. Fetchers are pluggable: built-ins handle
+ * `github-issue` and `github-pr` via the `gh` CLI; new
+ * fetchers (Slack, internal trackers, etc.) plug in through
+ * `registerUrlFetcher`.
+ *
+ * Fetchers must be non-interactive. They never open OAuth
+ * flows or write to disk. When an integration is not
+ * available, return `undefined`.
+ */
+import type { Ref } from "../../refs/index.js";
+/** Hints a fetcher returns to seed the new quest. */
+export interface SeedHints {
+    /** Suggested H1 title. */
+    title?: string;
+    /** Body or excerpt of the source, for the first Journey entry. */
+    excerpt?: string;
+    /** Source author's handle, as `type:value` (e.g. `github:octocat`). */
+    originator?: {
+        type: string;
+        value: string;
+    };
+}
+export interface UrlFetcher {
+    /** Ref type this fetcher handles. */
+    type: string;
+    /** Fetch hints for one ref of this type. */
+    fetch(ref: Ref): Promise<SeedHints | undefined>;
+}
+/** Register a URL fetcher for a ref type. */
+export declare const registerUrlFetcher: (fetcher: UrlFetcher) => void;
+/** Remove a fetcher. Idempotent. */
+export declare const unregisterUrlFetcher: (type: string) => void;
+/** Empty the registry. Tests only. */
+export declare const clearUrlFetchers: () => void;
+/** Look up a fetcher by ref type. */
+export declare const getUrlFetcher: (type: string) => UrlFetcher | undefined;
+/** Snapshot of every registered fetcher. */
+export declare const listUrlFetchers: () => UrlFetcher[];
+/** Fetch hints for a ref, or undefined when nothing handles it. */
+export declare function fetchUrlHints(ref: Ref): Promise<SeedHints | undefined>;
+export declare const githubIssueFetcher: UrlFetcher;
+export declare const githubPrFetcher: UrlFetcher;
+/** Seed the built-in fetchers. Idempotent. */
+export declare function registerBuiltinUrlFetchers(): void;

package/dist/internal/quest/url-fetchers.js

@@ -0,0 +1,97 @@
+/**
+ * URL fetchers for the `quest create --url=...` path.
+ *
+ * A fetcher takes a parsed ref (type + value) and returns
+ * a `SeedHints` payload the create action uses to fill in
+ * the new quest's title, originator and first Journey
+ * entry. Fetchers are pluggable: built-ins handle
+ * `github-issue` and `github-pr` via the `gh` CLI; new
+ * fetchers (Slack, internal trackers, etc.) plug in through
+ * `registerUrlFetcher`.
+ *
+ * Fetchers must be non-interactive. They never open OAuth
+ * flows or write to disk. When an integration is not
+ * available, return `undefined`.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { sanitizeExcerpt, sanitizeHandle, sanitizeSingleLine, } from "./sanitize.js";
+const execFileAsync = promisify(execFile);
+import { createGlobalSymbolRegistry } from "../registry/global-symbol-registry.js";
+const registry = createGlobalSymbolRegistry({
+    slot: "pi:agentic-harness:quest-url-fetchers",
+    getId: (f) => f.type,
+});
+/** Register a URL fetcher for a ref type. */
+export const registerUrlFetcher = (fetcher) => registry.register(fetcher);
+/** Remove a fetcher. Idempotent. */
+export const unregisterUrlFetcher = (type) => registry.unregister(type);
+/** Empty the registry. Tests only. */
+export const clearUrlFetchers = () => registry.clear();
+/** Look up a fetcher by ref type. */
+export const getUrlFetcher = (type) => registry.get(type);
+/** Snapshot of every registered fetcher. */
+export const listUrlFetchers = () => registry.list();
+/** Fetch hints for a ref, or undefined when nothing handles it. */
+export async function fetchUrlHints(ref) {
+    const fetcher = registry.get(ref.type);
+    if (!fetcher)
+        return undefined;
+    try {
+        return await fetcher.fetch(ref);
+    }
+    catch {
+        // Fetcher failures are non-fatal; the caller falls back
+        // to alias-only seeding.
+        return undefined;
+    }
+}
+async function fetchGhJson(subcommand, value) {
+    // Ref value is `<owner>/<repo>#<number>`. Translate to gh
+    // CLI args.
+    const match = /^([^/]+)\/([^#]+)#(\d+)$/.exec(value);
+    if (!match)
+        return undefined;
+    const [, owner, repo, number] = match;
+    const { stdout } = await execFileAsync("gh", [
+        subcommand,
+        "view",
+        number,
+        "--repo",
+        `${owner}/${repo}`,
+        "--json",
+        "title,body,author",
+    ]);
+    const data = JSON.parse(stdout);
+    const hints = {};
+    if (data.title) {
+        hints.title = sanitizeSingleLine(data.title);
+    }
+    if (data.body) {
+        hints.excerpt = sanitizeExcerpt(data.body);
+    }
+    if (data.author?.login) {
+        const handle = sanitizeHandle(data.author.login);
+        if (handle.length > 0) {
+            hints.originator = { type: "github", value: handle };
+        }
+    }
+    return Object.keys(hints).length > 0 ? hints : undefined;
+}
+export const githubIssueFetcher = {
+    type: "github-issue",
+    async fetch(ref) {
+        return fetchGhJson("issue", ref.value);
+    },
+};
+export const githubPrFetcher = {
+    type: "github-pr",
+    async fetch(ref) {
+        return fetchGhJson("pr", ref.value);
+    },
+};
+/** Seed the built-in fetchers. Idempotent. */
+export function registerBuiltinUrlFetchers() {
+    registerUrlFetcher(githubIssueFetcher);
+    registerUrlFetcher(githubPrFetcher);
+}

package/dist/internal/quest/write-classifier.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Classifies a write target into one of four categories so the
+ * quest gate can decide whether to allow, defer or supply. The
+ * classifier is pure: filesystem and git signals arrive as
+ * injected predicates, so the ladder is unit-testable without
+ * real `.git` fixtures. The risky production predicates (git
+ * ignore resolution, index membership, working-tree discovery)
+ * are wired in by the caller and covered separately.
+ *
+ * Tracked code and untracked-in-tree are kept distinct because
+ * git's ignore answer cannot tell a forgotten scratch directory
+ * from a new source file. Deferring only tracked edits during
+ * the plan phase keeps the discipline honest without ever
+ * cornering new work.
+ */
+/** The category a write target falls into. */
+export type WriteCategory = "device" | "quest-scratch" | "quest-internal" | "system-temp" | "scratch" | "tracked-code" | "untracked-in-tree" | "loose-file";
+/** The classifier's verdict for one write target. */
+export interface WriteClassification {
+    category: WriteCategory;
+    /** For tracked-code, the git working tree root containing the target. */
+    treeRoot?: string;
+}
+/** Signals the classifier needs, injected so the ladder stays pure. */
+export interface ClassifyWriteOptions {
+    /** The loaded quest's own directory, or null when none is loaded. */
+    questDir: string | null;
+    /**
+     * The quest's managed scratch directory, or null when the quest
+     * has none yet. Writes here are allowed and reaped on conclude.
+     */
+    scratchDir: string | null;
+    /**
+     * System temp roots (the OS temp dir, /tmp, /private/tmp). A
+     * write here that is not under the managed scratch dir is funnelled
+     * back into it rather than left to leak unreaped.
+     */
+    tempRoots: string[];
+    /** Whether the target is gitignored at its destination. */
+    isGitignored: (absPath: string) => boolean;
+    /** Whether the target is tracked in its repository's index. */
+    isTracked: (absPath: string) => boolean;
+    /** The git working tree root containing the target, or null when none. */
+    gitTreeRootOf: (absPath: string) => string | null;
+}
+export declare function classifyWrite(target: string, opts: ClassifyWriteOptions): WriteClassification;

package/dist/internal/quest/write-classifier.js

@@ -0,0 +1,59 @@
+/**
+ * Classifies a write target into one of four categories so the
+ * quest gate can decide whether to allow, defer or supply. The
+ * classifier is pure: filesystem and git signals arrive as
+ * injected predicates, so the ladder is unit-testable without
+ * real `.git` fixtures. The risky production predicates (git
+ * ignore resolution, index membership, working-tree discovery)
+ * are wired in by the caller and covered separately.
+ *
+ * Tracked code and untracked-in-tree are kept distinct because
+ * git's ignore answer cannot tell a forgotten scratch directory
+ * from a new source file. Deferring only tracked edits during
+ * the plan phase keeps the discipline honest without ever
+ * cornering new work.
+ */
+import * as path from "node:path";
+/**
+ * Classify an absolute, already-resolved write target. The caller
+ * resolves and canonicalizes the path before calling.
+ */
+/** Whether `target` is `dir` itself or sits anywhere beneath it. */
+function isUnder(target, dir) {
+    const base = path.resolve(dir);
+    const resolved = path.resolve(target);
+    return resolved === base || resolved.startsWith(`${base}${path.sep}`);
+}
+/**
+ * Whether the target is a node under /dev (the discard sink and the
+ * standard streams). These are never file writes to police, so the
+ * gate allows them unconditionally.
+ */
+function isDeviceNode(target) {
+    return path.resolve(target).startsWith(`${path.sep}dev${path.sep}`);
+}
+export function classifyWrite(target, opts) {
+    if (isDeviceNode(target)) {
+        return { category: "device" };
+    }
+    if (opts.scratchDir && isUnder(target, opts.scratchDir)) {
+        return { category: "quest-scratch" };
+    }
+    if (opts.questDir && isUnder(target, opts.questDir)) {
+        return { category: "quest-internal" };
+    }
+    if (opts.tempRoots.some((root) => isUnder(target, root))) {
+        return { category: "system-temp" };
+    }
+    if (opts.isGitignored(target)) {
+        return { category: "scratch" };
+    }
+    const treeRoot = opts.gitTreeRootOf(target);
+    if (treeRoot) {
+        const category = opts.isTracked(target)
+            ? "tracked-code"
+            : "untracked-in-tree";
+        return { category, treeRoot };
+    }
+    return { category: "loose-file" };
+}

package/dist/internal/refs/builtins.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Built-in ref types: GitHub issues, GitHub PRs, GitHub
+ * repos, Slack messages and Slack threads.
+ *
+ * Each type recognises its own surface forms in text and
+ * builds a canonical URL from a stored value. The canonical
+ * value is the smallest unambiguous string that lets us
+ * rebuild a URL without losing information.
+ *
+ *     type             canonical value           url shape
+ *     -------------    -----------------------   ----------------------------------
+ *     github-issue     owner/repo#NNN            github.com/owner/repo/issues/NNN
+ *     github-pr        owner/repo#NNN            github.com/owner/repo/pull/NNN
+ *     github-repo      owner/repo                github.com/owner/repo
+ *     slack-message    workspace/CHANNEL/pTS     <workspace>.slack.com/archives/CHANNEL/pTS
+ *     slack-thread     workspace/CHANNEL/pTS     <workspace>.slack.com/archives/CHANNEL/pTS
+ *
+ * GitHub's numbering shares one namespace between issues
+ * and PRs within a repo, so the bare `owner/repo#NNN`
+ * notation cannot distinguish them. We match the bare form
+ * as `github-issue` only; PRs require a `/pull/` URL form
+ * to disambiguate. The quest tool resolves the actual kind
+ * via GitHub API when it matters.
+ *
+ * Slack threads and messages share their URL surface; we
+ * discriminate by the `thread_ts` query parameter. A URL
+ * with `thread_ts=` is a `slack-thread` pointing at the
+ * thread parent; a URL without is a `slack-message`.
+ */
+import type { RefType } from "../../refs/types.js";
+/** All built-in ref types in stable iteration order. */
+export declare const BUILTIN_REF_TYPES: readonly RefType[];