sfora-cli 0.9.0 → 0.11.0

package/dist/format/lint/textEdits.js

@@ -0,0 +1,162 @@
+// 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 edit mechanics every quick fix rides on.
+//
+// A fix is a LIST of replacements over ONE document state, not a sequence of
+// steps. That distinction is the whole of this file. Each edit's offsets are
+// absolute into the PRE-fix source, so applying them in document order is
+// wrong by construction: the first edit moves every offset after it, and the
+// second one then cuts the wrong bytes out of a string that no longer matches
+// the one the rule read. Applying them last-one-first is the fix — an edit at a
+// LOWER offset cannot disturb an edit at a higher one that has already landed.
+//
+// (`applyLintFix` in lintSource.ts has always reverse-sorted. What it did not
+// do was check that the edits could compose at all: it skipped an
+// out-of-range edit and applied the rest, which is a HALF-applied fix — the
+// one outcome worse than no fix, because the author accepted a repair and got
+// a different broken document. Everything here exists so the answer is "all of
+// it or none of it".)
+//
+// Two edits that overlap have no correct order in either direction, so they
+// are rejected rather than resolved: whichever one is applied second is
+// reading bytes the first one already replaced. That is the shape of the guard
+// `fixAll` needs when it composes fixes from different rules over one
+// document.
+//
+// Offsets, not `{line, character}`. LSP's `TextEdit` carries positions because
+// its wire protocol has no shared buffer; here the source string is right
+// there, CodeMirror's `changes` spec wants offsets, and a line/character pair
+// would be converted twice for no one's benefit. The SHAPE is LSP's — a fix is
+// a list of ranged replacements applied reverse-sorted — and `lintEditToLsp`
+// below converts on the way out for anything that wants the wire form.
+/**
+ * True when two edits cannot both be applied to the same document state.
+ *
+ * Proper overlap is the obvious case. The second clause is the one that bites:
+ * two pure INSERTIONS at the same offset do not overlap by any interval test,
+ * yet the text they produce depends entirely on which goes first, and a fix
+ * whose output depends on sort stability is not a fix. Adjacency
+ * (`a.to === b.from`) is fine and stays allowed — that is two rules repairing
+ * neighbouring spans, which is exactly what fix-all is for.
+ */
+export function editsConflict(a, b) {
+    if (a.from < b.to && b.from < a.to)
+        return true;
+    return a.from === a.to && b.from === b.to && a.from === b.from;
+}
+/**
+ * The application order. Descending by start, then by end, so an edit that
+ * starts later lands first and leaves every earlier offset untouched.
+ *
+ * This function is the reason the offsets in a fix mean anything. Sorting it
+ * the other way still "works" for a single-edit fix — which is most of them,
+ * which is how a bug here would hide — and quietly corrupts every multi-edit
+ * one.
+ */
+export function sortEditsForApply(edits) {
+    return [...edits].sort((a, b) => b.from - a.from || b.to - a.to);
+}
+/**
+ * Can these edits compose over `source`? Returns the first reason they cannot,
+ * or null. Checked against the source the edits were DERIVED from — an edit
+ * checked against a document that has moved on is meaningless.
+ */
+export function checkEdits(source, edits) {
+    for (const edit of edits) {
+        if (edit.from > edit.to)
+            return { reason: "inverted", edit };
+        if (edit.from < 0 || edit.to > source.length) {
+            return { reason: "out-of-range", edit };
+        }
+    }
+    // O(n²) over the edits of one fix, which is at most a handful. `fixAll`
+    // pays the same price across a document's worth of fixes and it is still
+    // nothing next to the parse that produced them.
+    for (let i = 0; i < edits.length; i++) {
+        for (let j = i + 1; j < edits.length; j++) {
+            const a = edits[i];
+            const b = edits[j];
+            if (editsConflict(a, b)) {
+                return { reason: "overlap", edit: b, conflictsWith: a };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Apply `edits` to `source` as one atomic change, or say why not.
+ *
+ * Never throws and never half-applies: on any rejection the caller gets the
+ * reason and the original text is untouched. Lint is a background nicety in a
+ * text editor; it is never allowed to be the reason a document is damaged.
+ */
+export function tryApplyEdits(source, edits) {
+    const rejection = checkEdits(source, edits);
+    if (rejection)
+        return { ok: false, rejection };
+    let out = source;
+    for (const edit of sortEditsForApply(edits)) {
+        out = out.slice(0, edit.from) + edit.insert + out.slice(edit.to);
+    }
+    return { ok: true, text: out };
+}
+/**
+ * `tryApplyEdits` for callers that have already validated, or that would
+ * rather lose the fix than reason about a rejection. Returns `source`
+ * unchanged when the edits do not compose.
+ */
+export function applyEdits(source, edits) {
+    const result = tryApplyEdits(source, edits);
+    return result.ok ? result.text : source;
+}
+/**
+ * True when every edit still describes the bytes it was computed against.
+ *
+ * The staleness question, factored out of the editor adapter. A fix's offsets
+ * point into the source a rule read; applying them to a document that has been
+ * typed into since is not a repair, it is corruption at a plausible-looking
+ * offset. Both the CodeMirror action and the batch path ask this before they
+ * commit.
+ */
+export function editsMatch(source, edits, expected) {
+    if (checkEdits(expected, edits) !== null)
+        return false;
+    return edits.every((edit) => edit.to <= source.length &&
+        source.slice(edit.from, edit.to) === expected.slice(edit.from, edit.to));
+}
+/**
+ * Offsets → line/character, for one document. Built once per conversion so a
+ * fix with several edits does not rescan the source per edit.
+ */
+function lineStartsOf(source) {
+    const starts = [0];
+    for (let i = 0; i < source.length; i++) {
+        if (source[i] === "\n")
+            starts.push(i + 1);
+    }
+    return starts;
+}
+function positionAt(lineStarts, offset) {
+    // Binary search for the last line start at or before `offset`.
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineStarts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { line: lo, character: offset - lineStarts[lo] };
+}
+/** One fix's edits in LSP wire form, in the order LSP wants them (any). */
+export function fixToTextEdits(source, fix) {
+    const lineStarts = lineStartsOf(source);
+    return fix.edits.map((edit) => ({
+        range: {
+            start: positionAt(lineStarts, edit.from),
+            end: positionAt(lineStarts, edit.to),
+        },
+        newText: edit.insert,
+    }));
+}

package/dist/format/lint/types.d.ts

@@ -0,0 +1,116 @@
+import type { Root } from "mdast";
+import type { LintConfig } from "./config.js";
+import type { SelectedFrontmatterSchema } from "./frontmatterSchema.js";
+import type { LintSeverity } from "./severity.js";
+export type { LintSeverity };
+/** A replacement over the PRE-fix document. Offsets are absolute. */
+export interface LintEdit {
+    from: number;
+    to: number;
+    insert: string;
+}
+/**
+ * One quick fix, LSP-shaped: a LIST of ranged replacements over ONE document
+ * state, not a script of steps. All the edits are computed against the same
+ * pre-fix source, so they compose atomically and must not overlap — see
+ * ./textEdits, which owns the ordering, the overlap check and the application.
+ *
+ * A fix with several edits is the normal case, not an exotic one: repairing a
+ * fenced block's opening and closing delimiter together, or removing a dead
+ * frontmatter line while rewriting the live one, is two edits far apart in the
+ * file that only mean anything if they land as a unit.
+ */
+export interface LintFix {
+    label: string;
+    edits: LintEdit[];
+}
+export interface SforaDiagnostic {
+    from: number;
+    to: number;
+    severity: LintSeverity;
+    /** Namespaced, e.g. `sfora/broken-wiki-link`. Stable — the UI keys off it. */
+    ruleId: string;
+    message: string;
+    fixes?: LintFix[];
+}
+/**
+ * What a link resolver tells us about a target. Structurally the same shape as
+ * the editor's `WikiLinkResolution`, restated here so the core does not import
+ * from the app.
+ */
+export interface LintLinkResolution {
+    exists: boolean;
+    title?: string | null;
+}
+export interface LintContext {
+    source: string;
+    /** `source` split on newlines. A trailing `\r` is left on the line. */
+    lines: string[];
+    /** Absolute offset of the first character of line `i`. */
+    lineStart: (i: number) => number;
+    /**
+     * True for a fenced code block's delimiters and everything between them.
+     * Rules never fire inside a fence: the bytes there are not markdown.
+     */
+    inFence: (lineIndex: number) => boolean;
+    /**
+     * True for a line that holds bytes, none of which render — inside an HTML
+     * comment, or wholly inside an inline code span. The wider judgement behind
+     * `inFence`, from the same shared mask every other scanner in the package
+     * reads, so a rule cannot decide that a line is markdown when the reader has
+     * already decided it is not.
+     */
+    nonRendering: (lineIndex: number) => boolean;
+    /** True for the frontmatter fences and everything between them. */
+    inFrontmatter: (lineIndex: number) => boolean;
+    /** Line extents of the frontmatter block, or null when there is none. */
+    frontmatter: {
+        open: number;
+        close: number;
+    } | null;
+    /**
+     * The frontmatter schemas the workspace declared for THIS document's path,
+     * scope already applied. Absent or empty on every document until a workspace
+     * writes one down — see ./frontmatterSchema, which owns the selection.
+     *
+     * Selected here rather than in the rule for the same reason the fence mask
+     * is: the runner knows the document's path and the rule does not, and a rule
+     * that re-derived the scope would be a second place for the two to disagree.
+     */
+    frontmatterSchemas?: readonly SelectedFrontmatterSchema[];
+    /** Present only when a parser was injected AND it succeeded. */
+    ast?: Root;
+    /**
+     * SYNCHRONOUS cache lookup over the target as written, prefix included
+     * (`c:42`, not `42`). `undefined` means "unknown, still resolving" and is
+     * the signal to stay silent — only an explicit `{ exists: false }` is a
+     * broken link.
+     */
+    resolveLink?: (target: string) => LintLinkResolution | undefined;
+}
+export interface LintRule {
+    id: string;
+    /** When true the rule is skipped unless `ctx.ast` is present. */
+    needsAst?: boolean;
+    run(ctx: LintContext): SforaDiagnostic[];
+}
+export interface LintSourceOptions {
+    /** Defaults to the full registry, `SFORA_LINT_RULES`. */
+    rules?: readonly LintRule[];
+    /** Injected mdast parser — `parseMarkdownAst(source).root`. */
+    parseAst?: (source: string) => Root;
+    resolveLink?: LintContext["resolveLink"];
+    /**
+     * What the workspace says about these rules: which are off, which report at
+     * another level, which are scoped to a set of paths. Absent means every rule
+     * runs at the severity it declares, which is what every caller got before
+     * the config existed.
+     */
+    config?: LintConfig;
+    /**
+     * The document's path, for `appliesTo` scoping —
+     * `projects/sfora/docs/plan.md`. A scoped rule runs anyway when this is
+     * missing; see `scopeAdmits` for why silence is the worse failure.
+     */
+    path?: string;
+}

package/dist/format/lint/types.js

@@ -0,0 +1,16 @@
+// 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 contracts sfora-law rules are written against.
+//
+// A rule is a pure function from a document to spans-with-messages. It gets a
+// prepared view of the source — lines, line starts, where the code fences and
+// the frontmatter block are — so no rule re-derives that geometry and no two
+// rules disagree about whether a line is inside a fence.
+//
+// Two things are deliberately absent. There is no CodeMirror here: diagnostics
+// carry absolute offsets, and the editor adapter
+// (src/components/notes/cm-lint.ts) translates. And there is no parser here:
+// the mdast tree is INJECTED by the caller (`parseAst` in LintSourceOptions),
+// so the lint core stays dependency-free and ships in the CLI tarball with the
+// rest of the engine. `import type { Root }` is erased at compile time.
+export {};

package/dist/format/markdown/dates.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).
 // Date <-> frontmatter helpers. Timestamps are ms-epoch internally; on the wire
 // they're ISO-8601 (or date-only for coarse fields like a card due date).
 export function toISO(ms) {

package/dist/format/markdown/document.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).
 // The Jekyll-style document shape shared by every entity: an optional YAML
 // frontmatter fence, an H1 title (first non-empty line), then the body.
 import { parseYaml } from "./yaml.js";

package/dist/format/markdown/index.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).
 // Shared markdown core for the agent filesystem API (/v1/fs). One battle-tested
 // implementation of frontmatter/YAML, mention rendering, slugs, dates, and the
 // document (frontmatter + H1 + body) shape — consumed by postMarkdown,

package/dist/format/markdown/mentions.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).
 // Canonical mention syntax shared by messages / posts / cards / notes:
 //   @[Display Name](memberId)
 // On the wire we render that to a human-readable @Name and keep the display

package/dist/format/markdown/slug.d.ts

@@ -1,2 +1,30 @@
 export declare function slugify(title: string): string;
+/**
+ * The slug of one heading's text, and the anchor half of `[[target#anchor]]`.
+ *
+ * THE WHOLE POINT is that one function serves both sides: the read path stamps
+ * `id={toAnchorSlug(headingText)}` on the rendered heading, and a wiki link's
+ * anchor resolves through `toAnchorSlug(anchor)`. Two spellings of this rule
+ * would mean `[[page#my-heading]]` scrolls to nothing, and nothing would say
+ * so — which is why `anchorSlugAgreement` in the tests mutates one caller and
+ * asserts the other fails.
+ *
+ * Returns "" for text with no letters or numbers in it at all. That is not a
+ * fallback: a heading of "***" has no name to be linked by, and inventing one
+ * ("untitled") would hand two such headings the same anchor.
+ */
+export declare function toAnchorSlug(text: string): string;
+/**
+ * Suffix a repeated slug so every id in one document is unique: the first
+ * `## Notes` is `notes`, the second `notes-1`, the third `notes-2`.
+ *
+ * `counts` is the caller's ledger for ONE document, mutated in place — pass a
+ * fresh `Map` per render. The suffix is a positional fact, so a link written
+ * as `[[page#notes-1]]` means "the second heading called Notes" and moves when
+ * a third one is inserted above it. That is the same bargain every heading-
+ * anchor scheme makes; there is no stable name for a name used twice.
+ */
+export declare function disambiguateSlug(baseSlug: string, counts: Map<string, number>): string;
+/** `toAnchorSlug` + dedupe. The id a rendered heading carries. */
+export declare function headingSlug(text: string, counts: Map<string, number>): string;
 export declare function slugFromFilename(filename: string): string;

package/dist/format/markdown/slug.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).
 // Slug + filename helpers shared by the markdown serializers.
 // kebab-case a title: lowercase, strip accents, collapse non-alphanumerics to
 // single hyphens, trim. Empty titles fall back to "untitled". Dedupe of
@@ -12,6 +14,69 @@ export function slugify(title) {
         .replace(/^-+|-+$/g, "");
     return s || "untitled";
 }
+// ─── heading anchors ──────────────────────────────────────────────────
+//
+// A DIFFERENT slug from `slugify` above, and the difference is the point.
+// `slugify` names FILES, so it is ASCII-only on purpose: a filename crosses a
+// filesystem, a URL path, and a tarball, and `café.md` is three different byte
+// strings depending on which one wrote it. A heading anchor never leaves the
+// document — it is an `id` on an `<h2>` and a `#fragment` pointing at it — so
+// throwing away every non-ASCII letter there would collapse `## Café` and
+// `## 咖啡` to the same empty slug and make both unlinkable.
+//
+// The two must not be merged. Widening `slugify` to Unicode would rename every
+// file the fs API has ever written.
+//
+// Rules follow open-knowledge's `toWikiLinkSlug`
+// (context/open-knowledge/packages/core/src/utils/slug.ts): trim, NFKD, drop
+// combining marks, lowercase, any run of non-letter/non-number to one hyphen,
+// strip edge hyphens.
+const COMBINING_MARK_RE = /\p{M}+/gu;
+const NON_LETTER_OR_NUMBER_RE = /[^\p{L}\p{N}]+/gu;
+const EDGE_HYPHENS_RE = /^-+|-+$/g;
+/**
+ * The slug of one heading's text, and the anchor half of `[[target#anchor]]`.
+ *
+ * THE WHOLE POINT is that one function serves both sides: the read path stamps
+ * `id={toAnchorSlug(headingText)}` on the rendered heading, and a wiki link's
+ * anchor resolves through `toAnchorSlug(anchor)`. Two spellings of this rule
+ * would mean `[[page#my-heading]]` scrolls to nothing, and nothing would say
+ * so — which is why `anchorSlugAgreement` in the tests mutates one caller and
+ * asserts the other fails.
+ *
+ * Returns "" for text with no letters or numbers in it at all. That is not a
+ * fallback: a heading of "***" has no name to be linked by, and inventing one
+ * ("untitled") would hand two such headings the same anchor.
+ */
+export function toAnchorSlug(text) {
+    return text
+        .trim()
+        .normalize("NFKD")
+        .replace(COMBINING_MARK_RE, "")
+        .toLowerCase()
+        .replace(NON_LETTER_OR_NUMBER_RE, "-")
+        .replace(EDGE_HYPHENS_RE, "");
+}
+/**
+ * Suffix a repeated slug so every id in one document is unique: the first
+ * `## Notes` is `notes`, the second `notes-1`, the third `notes-2`.
+ *
+ * `counts` is the caller's ledger for ONE document, mutated in place — pass a
+ * fresh `Map` per render. The suffix is a positional fact, so a link written
+ * as `[[page#notes-1]]` means "the second heading called Notes" and moves when
+ * a third one is inserted above it. That is the same bargain every heading-
+ * anchor scheme makes; there is no stable name for a name used twice.
+ */
+export function disambiguateSlug(baseSlug, counts) {
+    const count = counts.get(baseSlug) ?? 0;
+    counts.set(baseSlug, count + 1);
+    return count === 0 ? baseSlug : `${baseSlug}-${count}`;
+}
+/** `toAnchorSlug` + dedupe. The id a rendered heading carries. */
+export function headingSlug(text, counts) {
+    const base = toAnchorSlug(text);
+    return base ? disambiguateSlug(base, counts) : "";
+}
 // Pull the slug back out of a filename: drop the .md and an optional leading
 // YYYY-MM-DD- date prefix. Used to match a requested filename to an entity.
 export function slugFromFilename(filename) {

package/dist/format/markdown/yaml.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).
 // Tiny YAML for markdown frontmatter: scalars + flat string arrays only.
 // Shared by the post / card / note serializers (see ./index). No Convex imports
 // — pure string transforms, safe to import from httpActions, internal Convex

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,51 @@
+// 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
+        // `[[target|Label]]` → Label, and `![[target|Label]]` with it. The optional
+        // bang is the embed marker (card #298) and it has to be eaten HERE: left
+        // out of the pattern, every embed in every excerpt turns into a stray
+        // exclamation mark in front of its label. An embed flattens to the same
+        // words a link does — a one-line preview has nowhere to put a card.
+        .replace(/!?\[\[[^\]|]*\|([^\]]*)\]\]/g, "$1");
+    // Label-less tokens. `wikiLinkPattern()` matches the brackets only, so the
+    // bang is stripped separately rather than by widening the grammar's own
+    // pattern — that pattern's span is what `canonicalizeReferences` rewrites,
+    // and a span that swallowed the bang would rewrite embeds into links.
+    out = out
+        .replace(/!\[\[([^\]]+)\]\]/g, wikiTokens === "keep" ? "$1" : " ")
+        .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