sfora-cli 0.8.0 → 0.10.0

package/dist/format/noteMarkdown.js

@@ -1,3 +1,5 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
 // Pure markdown <-> note (doc) serialization for the agent filesystem API
 // (/v1/fs). Notes are Notion-style single-author docs surfaced under the in-app
 // "Docs" tab; over the FS API they're stable named files `<slug>.md` (no date

package/dist/format/parseWithFallback.d.ts

@@ -0,0 +1,13 @@
+import { type ParsedDocument } from "./markdown/document.js";
+export declare const MAX_PARSE_INPUT_BYTES = 4000000;
+export declare const MAX_FRONTMATTER_SCAN_BYTES = 64000;
+export declare const MAX_PARSE_WALLCLOCK_MS = 250;
+export type ParseFallbackReason = "input-too-large" | "unterminated-frontmatter" | "parse-threw" | "budget-exceeded";
+export interface ParseFallbackIssue {
+    reason: ParseFallbackReason;
+    message: string;
+}
+export interface FallbackParsedDocument extends ParsedDocument {
+    errors: ParseFallbackIssue[];
+}
+export declare function parseDocumentWithFallback(source: string): FallbackParsedDocument;

package/dist/format/parseWithFallback.js

@@ -0,0 +1,98 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+// A parseDocument that cannot throw and cannot run unbounded.
+//
+// Every byte that reaches the document parser is hostile until proven otherwise:
+// agents PUT files over /v1/fs, humans paste whatever their clipboard held, and
+// the local `.sfora/` workspace is an ordinary directory anyone can write to. A
+// throw there is not a parse failure, it is a 500 on a file the user can still
+// see on disk. So the contract here is: always return a ParsedDocument, and say
+// what was given up.
+//
+// Adapted from inkeep/open-knowledge's `parseWithFallback` (see
+// docs/research/open-knowledge-engine.md §5.3). Theirs recurses to isolate the
+// offending block because their parser is a 26-plugin mdast pipeline; ours is a
+// frontmatter fence plus an H1 scan, so there is no sub-document to isolate and
+// the only sensible degradation is the whole document as body text. What we keep
+// is the shape: bounded work, a typed reason per degradation, never a throw.
+import { parseDocument } from "./markdown/document.js";
+// Above this, we do not parse at all. 4 MB is ~40x the largest document the fs
+// API will accept today; anything past it is a paste accident or an attack.
+export const MAX_PARSE_INPUT_BYTES = 4_000_000;
+// A frontmatter fence must close inside this prefix. Bounding the search means a
+// document that opens with `---` and never closes it costs a fixed scan instead
+// of one proportional to the whole file.
+export const MAX_FRONTMATTER_SCAN_BYTES = 64_000;
+// Not a cutoff — parseDocument is single-pass and has nothing to abort — but a
+// tripwire: if the scan ever exceeds this, something has become superlinear and
+// we want it in the errors array rather than in a latency graph.
+export const MAX_PARSE_WALLCLOCK_MS = 250;
+function now() {
+    return typeof performance !== "undefined" &&
+        typeof performance.now === "function"
+        ? performance.now()
+        : Date.now();
+}
+const MAX_ERROR_MESSAGE_LEN = 500;
+function messageOf(err) {
+    if (err instanceof Error)
+        return err.message.slice(0, MAX_ERROR_MESSAGE_LEN);
+    return String(err ?? "unknown").slice(0, MAX_ERROR_MESSAGE_LEN);
+}
+// The raw-text degradation: no title, no frontmatter, the source verbatim as
+// body. Deliberately lossy but never destructive — the bytes survive, so the
+// file still renders as a code-ish blob and a later write does not erase it.
+function degraded(source, issue) {
+    return { title: "", body: source, frontmatter: {}, errors: [issue] };
+}
+// True when the document opens a frontmatter fence it never closes within the
+// scan window. Cheap: bounded slice, indexOf, no backtracking.
+function hasUnterminatedFrontmatter(source) {
+    const head = source.startsWith("") ? source.slice(1) : source;
+    // Exactly parseDocument's opener — a `--- ` line is not a fence, so flagging
+    // it here would invent a degradation the real parser never suffers.
+    if (!/^---\r?\n/.test(head))
+        return false;
+    const window = head.slice(0, MAX_FRONTMATTER_SCAN_BYTES);
+    return !/\r?\n---[ \t]*(\r?\n|$)/.test(window.slice(3));
+}
+export function parseDocumentWithFallback(source) {
+    if (source.length > MAX_PARSE_INPUT_BYTES) {
+        return degraded(source, {
+            reason: "input-too-large",
+            message: `${source.length} chars exceeds MAX_PARSE_INPUT_BYTES (${MAX_PARSE_INPUT_BYTES})`,
+        });
+    }
+    if (hasUnterminatedFrontmatter(source)) {
+        return degraded(source, {
+            reason: "unterminated-frontmatter",
+            message: `no closing --- fence within MAX_FRONTMATTER_SCAN_BYTES (${MAX_FRONTMATTER_SCAN_BYTES})`,
+        });
+    }
+    const started = now();
+    let parsed;
+    try {
+        parsed = parseDocument(source);
+    }
+    catch (err) {
+        return degraded(source, {
+            reason: "parse-threw",
+            message: messageOf(err),
+        });
+    }
+    const elapsed = now() - started;
+    if (elapsed > MAX_PARSE_WALLCLOCK_MS) {
+        // The parse succeeded, so we keep its result — this records that it cost
+        // more than it should have.
+        return {
+            ...parsed,
+            errors: [
+                {
+                    reason: "budget-exceeded",
+                    message: `parse took ${Math.round(elapsed)}ms (budget ${MAX_PARSE_WALLCLOCK_MS}ms)`,
+                },
+            ],
+        };
+    }
+    return { ...parsed, errors: [] };
+}

package/dist/format/plaintext.d.ts

@@ -0,0 +1,5 @@
+export interface StripToPlainTextOptions {
+    wikiTokens?: "drop" | "keep";
+    images?: "drop" | "alt";
+}
+export declare function stripToPlainText(body: string | undefined | null, options?: StripToPlainTextOptions): string;

package/dist/format/plaintext.js

@@ -0,0 +1,41 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+// Flatten a markdown body to a single line of plain text — the shared engine
+// behind every excerpt/preview in sfora (feed rows, search hits, the docs
+// library card, the briefing). Strips everything that would otherwise leak raw
+// syntax into a one-liner: fenced code, HTML, images, mentions, wiki tokens,
+// links, tables, list and checkbox markers, headings, blockquotes, emphasis.
+//
+// Pure: no React, no Convex, no Node.
+//
+// Two call sites disagreed on two details when this was three copies, so those
+// two stayed as options rather than being flattened to one answer:
+//   • a label-less `[[token]]` — the web renderer drops it (the raw id is
+//     noise in a preview), the backend keeps it (its tokens are human forms
+//     like `c:42` that read fine).
+//   • an image — the web renderer drops it entirely, the backend keeps the alt
+//     text as words.
+import { wikiLinkPattern } from "./wikiLinks.js";
+export function stripToPlainText(body, options = {}) {
+    const { wikiTokens = "drop", images = "drop" } = options;
+    let out = (body ?? "")
+        .replace(/```[\s\S]*?```/g, " ") // fenced code blocks
+        .replace(/<[^>]+>/g, " ") // raw HTML tags
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, images === "alt" ? "$1" : " ")
+        .replace(/@\[([^\]]+)\]\([^)]*\)/g, "@$1") // mention → @Name
+        .replace(/\[\[[^\]|]*\|([^\]]*)\]\]/g, "$1"); // [[target|Label]] → Label
+    // Label-less tokens.
+    out = out.replace(wikiLinkPattern(), wikiTokens === "keep" ? "$1" : " ");
+    return out
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // [text](url) → text
+        .replace(/^\s*\|(?:\s*:?-+:?\s*\|)+\s*$/gm, " ") // table separator rows
+        .replace(/^\s*\|(.+)\|\s*$/gm, (_, inner) => inner.replace(/\s*\|\s*/g, " · ")) // table rows → cell · cell
+        .replace(/^#{1,6}\s+/gm, "") // headings
+        .replace(/^\s*[-*+]\s+\[[ xX]\]\s+/gm, "") // task checkbox bullets
+        .replace(/^\s*[-*+]\s+/gm, "") // list bullets
+        .replace(/^\s*\d+[.)]\s+/gm, "") // ordered list markers
+        .replace(/^\s*>\s?/gm, "") // blockquotes
+        .replace(/(\*\*|__|\*|_|~~|`)/g, "") // emphasis + inline code marks
+        .replace(/\s+/g, " ")
+        .trim();
+}

package/dist/format/postMarkdown.js

@@ -1,3 +1,5 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
 // Pure markdown <-> post serialization for the agent filesystem API (/v1/fs).
 //
 // Frontmatter/YAML, mention rendering, slugs, and the document shape now live in
@@ -11,7 +13,7 @@
 // trip can be reconstructed (see `rehydrateMentions`).
 import { buildDocument, parseDocument, rehydrateMentions, renderMentions, serializeFrontmatter, slugFromFilename, slugify, toISO, } from "./markdown/index.js";
 // Re-export the shared helpers so existing importers (cardMarkdown, httpHelpers)
-// keep their `from "./postMarkdown"` paths working.
+// keep their `from "./postMarkdown.js"` paths working.
 export { rehydrateMentions, slugFromFilename, slugify };
 // ─── Filenames ─────────────────────────────────────────────────────
 // The YYYY-MM-DD part of a filename. Published posts use publishedAt; drafts

package/dist/format/taskUploadFilename.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The `task` verb creates work. Canonical board filenames begin with a card
+ * number, but carrying that prefix into a cloud PUT would target that existing
+ * card. Strip it here; explicit updates belong to the filesystem API.
+ */
+export declare function taskUploadFilename(filename: string): string;

package/dist/format/taskUploadFilename.js

@@ -0,0 +1,13 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+/**
+ * The `task` verb creates work. Canonical board filenames begin with a card
+ * number, but carrying that prefix into a cloud PUT would target that existing
+ * card. Strip it here; explicit updates belong to the filesystem API.
+ */
+export function taskUploadFilename(filename) {
+    const stem = filename
+        .replace(/\.md$/i, "")
+        .replace(/^\d+(?:[-_. ]+|$)/, "");
+    return `${stem || "task"}.md`;
+}

package/dist/format/wayfinder.d.ts

@@ -0,0 +1,50 @@
+export declare const WAYFINDER_TICKET_TYPES: readonly ["grilling", "prototype", "research", "task"];
+export type WayfinderTicketType = (typeof WAYFINDER_TICKET_TYPES)[number];
+export type WayfinderTicketState = "open" | "claimed" | "decided" | "out-of-scope";
+export interface WayfinderTicket {
+    name: string;
+    type: WayfinderTicketType;
+    state: WayfinderTicketState;
+    /** Names of the tickets blocking this one. */
+    blockedBy: string[];
+    /**
+     * When set, the picture classes this node from it and skips frontierOf's
+     * name-resolution. A caller with server-side blocker buckets (the Plan) is
+     * the truth about blockedness: a DELETED blocker card is cleared there,
+     * while a dangling NAME in an authored map stays unresolved — without the
+     * override, a question whose blocker was deleted would render ghost-blocked
+     * in the very view whose data source already ruled it takeable.
+     */
+    onFrontier?: boolean;
+}
+export interface WayfinderMap {
+    /** What reaching the end of the map looks like. Drawn as the terminal node. */
+    destination?: string;
+    tickets: WayfinderTicket[];
+}
+/**
+ * Parse a ticket-list section (the lines between headings). Non-matching
+ * lines are ignored — the list can sit inside a larger map document. Returns
+ * an empty list rather than null: a map with no tickets yet is a real state
+ * (freshly charted, everything still in the fog), not a parse failure.
+ */
+export declare function parseWayfinderTickets(section: string): WayfinderTicket[];
+/**
+ * A ticket is on the FRONTIER when it is open and everything blocking it is
+ * closed (decided or out of scope). Blockers named but absent from the map
+ * count as unresolved — a dangling name is a map error the picture should
+ * make visible, not hide.
+ */
+export declare function frontierOf(tickets: WayfinderTicket[]): WayfinderTicket[];
+export declare function wayfinderNodeId(index: number): string;
+/**
+ * Draw a map as mermaid flowchart source the engine renders natively (the
+ * renderer honors classDef, so states carry color in both themes via the
+ * palette the diagram theme derives from --fg/--accent).
+ *
+ * Reading the picture: solid arrows are blocking edges pointing at what they
+ * unblock; the frontier is bold; decided tickets are quiet; out-of-scope
+ * tickets sit dashed at the edge; the destination, when named, is the
+ * terminal node every unblocked leaf feeds.
+ */
+export declare function wayfinderMapToMermaid(map: WayfinderMap): string;

package/dist/format/wayfinder.js

@@ -0,0 +1,203 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+// Wayfinder maps — the shared vocabulary for charting a big effort as a map
+// of decision tickets, and the one place its textual form and its picture are
+// defined.
+//
+// The concepts come from mattpocock/skills' wayfinder (studied in
+// docs/research/wayfinder-sfora-map.md; repo vendored in context/): a MAP with
+// a destination, decision TICKETS of four types, BLOCKING edges between them,
+// and states — open on the frontier, claimed, decided, ruled out of scope,
+// with unspecifiable work waiting in the fog. sfora's Plan already carries the
+// same lifecycle (fuzzy / up-for-grabs / claimed / decided), so this module
+// speaks both dialects: wayfinder's names on the wire, the Plan's states
+// mappable one-to-one.
+//
+// Two exports matter:
+//   parseWayfinderTickets — read tickets from the map's markdown ticket list
+//   wayfinderMapToMermaid — draw the map as a flowchart the engine renders
+//
+// Pure string transforms — no React, no Convex, no Node.
+//
+// ── The ticket-list line grammar ───────────────────────────────────────────
+//
+//   - [ ] Pick the auth provider (grilling)
+//   - [~] Prototype the login screen (prototype) <- Pick the auth provider
+//   - [x] Name the destination
+//   - [-] Native mobile app
+//
+// State rides in the bracket: `[ ]` open, `[~]` claimed, `[x]` decided,
+// `[-]` out of scope. The type rides in a trailing parenthesis (grilling when
+// absent — wayfinder's default). `<- A, B` names the tickets blocking this
+// one, by title. Everything is referred to BY NAME, per wayfinder's rule that
+// a wall of ids is illegible.
+export const WAYFINDER_TICKET_TYPES = [
+    "grilling",
+    "prototype",
+    "research",
+    "task",
+];
+const STATE_BY_MARK = {
+    " ": "open",
+    "~": "claimed",
+    x: "decided",
+    X: "decided",
+    "-": "out-of-scope",
+};
+const TICKET_LINE = /^[-*]\s+\[([ ~xX-])\]\s+(.+)$/;
+/**
+ * Parse a ticket-list section (the lines between headings). Non-matching
+ * lines are ignored — the list can sit inside a larger map document. Returns
+ * an empty list rather than null: a map with no tickets yet is a real state
+ * (freshly charted, everything still in the fog), not a parse failure.
+ */
+export function parseWayfinderTickets(section) {
+    const tickets = [];
+    for (const raw of section.split(/\r?\n/)) {
+        const match = TICKET_LINE.exec(raw.trim());
+        if (!match)
+            continue;
+        let rest = match[2].trim();
+        let blockedBy = [];
+        const arrow = rest.indexOf("<-");
+        if (arrow >= 0) {
+            blockedBy = rest
+                .slice(arrow + 2)
+                .split(",")
+                .map((name) => name.trim())
+                .filter(Boolean);
+            rest = rest.slice(0, arrow).trim();
+        }
+        let type = "grilling";
+        const typed = /^(.*)\((grilling|prototype|research|task)\)$/.exec(rest);
+        if (typed) {
+            type = typed[2];
+            rest = typed[1].trim();
+        }
+        if (!rest)
+            continue;
+        tickets.push({
+            name: rest,
+            type,
+            state: STATE_BY_MARK[match[1]] ?? "open",
+            blockedBy,
+        });
+    }
+    return tickets;
+}
+// A blocker clears the way once it is CLOSED — decided or ruled out of scope.
+// Wayfinder's rule is that any terminal ticket unblocks; ruling a blocker out
+// of scope answers the question as surely as deciding it does.
+const TERMINAL_STATES = new Set([
+    "decided",
+    "out-of-scope",
+]);
+/**
+ * A ticket is on the FRONTIER when it is open and everything blocking it is
+ * closed (decided or out of scope). Blockers named but absent from the map
+ * count as unresolved — a dangling name is a map error the picture should
+ * make visible, not hide.
+ */
+export function frontierOf(tickets) {
+    const byName = new Map(tickets.map((ticket) => [ticket.name, ticket]));
+    return tickets.filter((ticket) => {
+        if (ticket.state !== "open")
+            return false;
+        return ticket.blockedBy.every((name) => {
+            const blocker = byName.get(name);
+            return blocker !== undefined && TERMINAL_STATES.has(blocker.state);
+        });
+    });
+}
+// Node ids must be word-safe for the flowchart grammar; the label carries the
+// real name. Stable across renders: derived from position, not content.
+// Exported so a consumer can join a rendered node's data-id back to the
+// ticket at the same index without re-implementing the scheme.
+export function wayfinderNodeId(index) {
+    return `t${index}`;
+}
+const TYPE_GLYPH = {
+    grilling: "", // the default carries no marker — most tickets are grilling
+    prototype: " ◇",
+    research: " ※",
+    task: " ⚙",
+};
+function escapeLabel(name) {
+    // Brackets and quotes would close the node's label early.
+    return name.replace(/["[\]]/g, " ").replace(/\s+/g, " ").trim();
+}
+/**
+ * Draw a map as mermaid flowchart source the engine renders natively (the
+ * renderer honors classDef, so states carry color in both themes via the
+ * palette the diagram theme derives from --fg/--accent).
+ *
+ * Reading the picture: solid arrows are blocking edges pointing at what they
+ * unblock; the frontier is bold; decided tickets are quiet; out-of-scope
+ * tickets sit dashed at the edge; the destination, when named, is the
+ * terminal node every unblocked leaf feeds.
+ */
+export function wayfinderMapToMermaid(map) {
+    const { tickets } = map;
+    const byName = new Map(tickets.map((ticket, index) => [ticket.name, index]));
+    const frontier = new Set(frontierOf(tickets).map((ticket) => ticket.name));
+    const lines = ["flowchart TD"];
+    for (const [index, ticket] of tickets.entries()) {
+        const label = escapeLabel(ticket.name) + TYPE_GLYPH[ticket.type];
+        // Shape says state at a glance even without color: decided closes into a
+        // stadium, out-of-scope stays a plain box, open work is a sharp rect.
+        const node = ticket.state === "decided"
+            ? `${wayfinderNodeId(index)}(["${label} ✓"])`
+            : `${wayfinderNodeId(index)}["${label}"]`;
+        lines.push(`  ${node}`);
+    }
+    for (const [index, ticket] of tickets.entries()) {
+        for (const blocker of ticket.blockedBy) {
+            const from = byName.get(blocker);
+            if (from === undefined) {
+                // A dangling blocker name gets its own node so the error is VISIBLE.
+                const ghost = `missing${lines.length}`;
+                lines.push(`  ${ghost}["${escapeLabel(blocker)} ?"]`);
+                lines.push(`  ${ghost} -.-> ${wayfinderNodeId(index)}`);
+                continue;
+            }
+            lines.push(`  ${wayfinderNodeId(from)} --> ${wayfinderNodeId(index)}`);
+        }
+    }
+    if (map.destination) {
+        const dest = `dest(["${escapeLabel(map.destination)}"])`;
+        lines.push(`  ${dest}`);
+        // Every ticket nothing depends on feeds the destination — the map's
+        // remaining route at a glance.
+        const blockedNames = new Set(tickets.flatMap((ticket) => ticket.blockedBy));
+        for (const [index, ticket] of tickets.entries()) {
+            if (ticket.state === "out-of-scope")
+                continue;
+            if (!blockedNames.has(ticket.name)) {
+                lines.push(`  ${wayfinderNodeId(index)} --> dest`);
+            }
+        }
+    }
+    // States as classes; the renderer resolves classDef props over its theme.
+    // Each state gets a DISTINCT stroke so the four read apart on screen — the
+    // same tones PlanHill assigns the same buckets, so hill and map speak one
+    // palette. Frontier and claimed differ by color, not only weight; decided
+    // is quiet but named; out of scope sits dashed.
+    lines.push("  classDef claimed stroke:var(--color-accent-amber),stroke-width:2px");
+    lines.push("  classDef frontier stroke:var(--color-brand-blue),stroke-width:2px");
+    lines.push("  classDef outofscope stroke:var(--color-text-tertiary),stroke-dasharray:4 3");
+    lines.push("  classDef decided stroke:var(--color-success)");
+    const byState = (predicate) => tickets.flatMap((ticket, index) => (predicate(ticket) ? [wayfinderNodeId(index)] : []));
+    const claimed = byState((t) => t.state === "claimed");
+    const front = byState((t) => t.onFrontier ?? frontier.has(t.name));
+    const out = byState((t) => t.state === "out-of-scope");
+    const done = byState((t) => t.state === "decided");
+    if (claimed.length > 0)
+        lines.push(`  class ${claimed.join(",")} claimed`);
+    if (front.length > 0)
+        lines.push(`  class ${front.join(",")} frontier`);
+    if (out.length > 0)
+        lines.push(`  class ${out.join(",")} outofscope`);
+    if (done.length > 0)
+        lines.push(`  class ${done.join(",")} decided`);
+    return lines.join("\n");
+}

package/dist/format/wikiLinks.d.ts

@@ -0,0 +1,19 @@
+export type WikiLinkKind = "post" | "card" | "note" | "pr";
+export declare const WIKI_LINK_PREFIXES: ReadonlyArray<readonly [prefix: string, kind: WikiLinkKind]>;
+export declare const WIKI_LINK_PREFIX_FOR: Readonly<Record<WikiLinkKind, string>>;
+export declare function buildWikiLink(kind: WikiLinkKind, id: string, label: string): string;
+export interface WikiLink {
+    kind: WikiLinkKind;
+    id: string;
+    target: string;
+    label: string;
+    hasLabel: boolean;
+}
+export declare function wikiLinkPattern(): RegExp;
+export declare function parseWikiToken(raw: string): WikiLink;
+export declare function parseWikiTarget(target: string): {
+    kind: WikiLinkKind;
+    id: string;
+};
+export declare function parseWikiLinks(body: string): WikiLink[];
+export declare function matchWikiToken(text: string): WikiLink | null;

package/dist/format/wikiLinks.js

@@ -0,0 +1,80 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+// The `[[…]]` wiki-link grammar — sfora's cross-entity link token, and the one
+// place its prefix table lives.
+//
+//   [[<postId>]]            → a post (bare, no prefix)
+//   [[n:<noteId>]]          → a doc / note
+//   [[c:<cardId>]]          → a task / card  (also accepts `c:#42` / `c:42`)
+//   [[pr:<n>]] / [[gh:<n>]] → a pull request
+//
+// Any form may carry a display label after a pipe: `[[c:42|Fix login]]`.
+//
+// Pure string transforms — no React, no Convex, no Node. Consumers: the Convex
+// reference indexer (convex/references.ts), the web renderer
+// (src/lib/utils/markdown.ts), and, by hand-copy, the mobile preprocessor
+// (packages/mobile/src/lib/markdown-tokens.ts — outside the pnpm workspace).
+// Prefix → kind, longest-first so `pr:` is tried before any future `p:`.
+export const WIKI_LINK_PREFIXES = [
+    ["pr:", "pr"],
+    ["gh:", "pr"],
+    ["n:", "note"],
+    ["c:", "card"],
+];
+// The prefix to WRITE for a kind when building a canonical token. Note `gh:` is
+// an accepted input alias for `pr:` but is never emitted.
+export const WIKI_LINK_PREFIX_FOR = {
+    post: "",
+    card: "c:",
+    note: "n:",
+    pr: "pr:",
+};
+// Build the canonical `[[<prefix><id>|<label>]]` form. The label is sanitized:
+// `[`, `]`, and `|` inside it would break the token grammar.
+export function buildWikiLink(kind, id, label) {
+    const clean = label.replace(/[[\]|]/g, " ").trim() || "Untitled";
+    return `[[${WIKI_LINK_PREFIX_FOR[kind]}${id}|${clean}]]`;
+}
+// A fresh global matcher each call: a shared /g regex carries `lastIndex`
+// between callers and would silently skip tokens.
+export function wikiLinkPattern() {
+    return /\[\[([^\]]+)\]\]/g;
+}
+// Split a token body (the text between `[[` and `]]`) into target + label.
+export function parseWikiToken(raw) {
+    const pipe = raw.indexOf("|");
+    const target = (pipe >= 0 ? raw.slice(0, pipe) : raw).trim();
+    const explicit = pipe >= 0 ? raw.slice(pipe + 1).trim() : "";
+    const { kind, id } = parseWikiTarget(target);
+    return {
+        kind,
+        id,
+        target,
+        label: explicit || target,
+        hasLabel: explicit.length > 0,
+    };
+}
+// Classify a target (prefix included) into its kind + bare identifier.
+export function parseWikiTarget(target) {
+    for (const [prefix, kind] of WIKI_LINK_PREFIXES) {
+        if (target.startsWith(prefix)) {
+            return { kind, id: target.slice(prefix.length) };
+        }
+    }
+    return { kind: "post", id: target };
+}
+// Every `[[…]]` token in a body, in document order, not deduped.
+export function parseWikiLinks(body) {
+    const out = [];
+    const re = wikiLinkPattern();
+    let m;
+    while ((m = re.exec(body)) !== null)
+        out.push(parseWikiToken(m[1]));
+    return out;
+}
+// Parse a string that must be EXACTLY one token and nothing else — the test
+// behind "this whole line is a single link, so unfurl it as a card".
+export function matchWikiToken(text) {
+    const m = /^\[\[([^\]]+)\]\]$/.exec(text.trim());
+    return m ? parseWikiToken(m[1]) : null;
+}

package/dist/local/workspace.d.ts

@@ -16,6 +16,18 @@
  */
 /** Directory name that marks a local sfora workspace. */
 export declare const WORKSPACE_DIR = ".sfora";
+/**
+ * Migrate an existing workspace's board onto the four fixed stage dirs (One
+ * Flow). Idempotent: a board already in the canonical shape is left untouched.
+ * Legacy columns are mapped by name (done→done, in progress→doing, triage/
+ * undecided/…→triage, else todo); each card file MOVES into its stage dir, and
+ * a card leaving an unrecognized column keeps that column's name as a label so
+ * nothing is lost. Called on open so old \`.sfora/\` dirs reshape silently.
+ */
+export declare function migrateWorkspaceStages(root: string): Promise<{
+    migrated: boolean;
+    moved: number;
+}>;
 /**
  * Walk up from `cwd` looking for a `.sfora/` workspace. A directory only
  * counts when it has workspace markers (board/posts/docs) — `~/.sfora` is also