sfora-cli 0.9.0 → 0.10.0

package/dist/format/callout.js

@@ -0,0 +1,130 @@
+// 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).
+/**
+ * Callouts — the GFM alert grammar, `> [!NOTE]`.
+ *
+ * A callout is an ordinary blockquote whose first line is a type marker. That
+ * is the whole trick: every reader that does not know about callouts still
+ * sees quoted prose, and the bytes stay a blockquote on disk. There is no new
+ * fence, no new frontmatter key, nothing an agent has to learn.
+ *
+ *     > [!WARNING] Ship blocker
+ *     > The migration has to run before the deploy.
+ *
+ * Five types, matching GitHub: note, tip, important, warning, caution. The
+ * marker is written uppercase and read case-insensitively, because people type
+ * `[!note]` and pasted GitHub markdown says `[!NOTE]` — both are the same
+ * callout, and the first save canonicalizes.
+ *
+ * Pure functions over lines: no DOM, no ProseMirror, no React. The reader
+ * (`src/lib/utils/markdown.ts`), the Tiptap node
+ * (`src/components/editor/extensions/callout.ts`), and the CLI all read the
+ * grammar from here so they cannot disagree about what a callout is.
+ */
+export const CALLOUT_TYPES = [
+    "note",
+    "tip",
+    "important",
+    "warning",
+    "caution",
+];
+const MARKER = /^\[!([A-Za-z]+)\][ \t]*(.*)$/;
+/** The marker as written: uppercase, so `[!NOTE]` is what lands on disk. */
+export function calloutMarker(type) {
+    return `[!${type.toUpperCase()}]`;
+}
+export function isCalloutType(value) {
+    return CALLOUT_TYPES.includes(value.toLowerCase());
+}
+/**
+ * Drop one level of `>` quoting. A single space after the marker is part of
+ * the marker, not the content — `>  indented` keeps one space.
+ */
+export function stripQuoteMarkers(lines) {
+    return lines.map((line) => line.replace(/^[ \t]{0,3}>[ ]?/, ""));
+}
+/**
+ * Read a callout out of the lines of a blockquote.
+ *
+ * Accepts either raw source lines (`> [!NOTE]`) or lines whose quote markers a
+ * caller has already stripped (`[!NOTE]`) — the reader strips as it scans, the
+ * editor does not. The two are told apart by looking at the block as a whole:
+ * if every non-blank line is quoted, one level comes off. That way a callout
+ * whose body contains a nested quote survives either way round.
+ *
+ * Returns null for anything that is not a callout, which is the signal to
+ * render an ordinary blockquote.
+ */
+export function parseCallout(blockquoteLines) {
+    return readCallout(blockquoteLines)?.callout ?? null;
+}
+/**
+ * Index, within the same lines, of the callout body's first line — or -1 when
+ * the block is not a callout. A caller that re-parses `body` as markdown needs
+ * it to map a node back to the document line it came from; the reader joins
+ * its checkboxes to the document's line scan that way. Kept off `Callout`
+ * itself because the type is a value the editor and CLI construct by hand.
+ */
+export function calloutBodyLine(blockquoteLines) {
+    return readCallout(blockquoteLines)?.bodyLine ?? -1;
+}
+function readCallout(blockquoteLines) {
+    const nonBlank = blockquoteLines.filter((line) => line.trim() !== "");
+    if (nonBlank.length === 0)
+        return null;
+    const quoted = nonBlank.every((line) => /^[ \t]{0,3}>/.test(line));
+    const lines = quoted ? stripQuoteMarkers(blockquoteLines) : [...blockquoteLines];
+    // The emptiness check above ran on the RAW lines, and a line can be
+    // non-blank before its `>` marker comes off and blank after — a bare `>` is
+    // the whole of CommonMark's empty blockquote. Without this the findIndex
+    // returns -1 and the deref below throws, taking down the render of any post
+    // that contains one.
+    const first = lines.findIndex((line) => line.trim() !== "");
+    if (first === -1)
+        return null;
+    const match = MARKER.exec(lines[first].trim());
+    if (!match)
+        return null;
+    const keyword = match[1].toLowerCase();
+    if (!isCalloutType(keyword))
+        return null;
+    const title = match[2].trim();
+    // Same trim as `trimBlankEdges`, unrolled so the leading blanks it drops can
+    // be added to the body's line index rather than silently lost.
+    const rest = lines.slice(first + 1).map((line) => line.replace(/\s+$/, ""));
+    let start = 0;
+    while (start < rest.length && rest[start] === "")
+        start++;
+    let end = rest.length;
+    while (end > start && rest[end - 1] === "")
+        end--;
+    const body = rest.slice(start, end).join("\n");
+    return {
+        callout: title ? { type: keyword, title, body } : { type: keyword, body },
+        bodyLine: first + 1 + start,
+    };
+}
+/**
+ * Write a callout back out. The inverse of `parseCallout` on the canonical
+ * form, and the only place the serialized shape is spelled: one blockquote,
+ * marker line first, body quoted line by line. A blank body line is a bare
+ * `>` — no trailing space, so the bytes survive editors that strip them.
+ */
+export function calloutToMarkdown(callout) {
+    const title = callout.title?.trim();
+    const head = title
+        ? `> ${calloutMarker(callout.type)} ${title}`
+        : `> ${calloutMarker(callout.type)}`;
+    const body = trimBlankEdges(callout.body.split("\n"));
+    if (body.length === 0)
+        return head;
+    return [head, ...body.map((line) => (line === "" ? ">" : `> ${line}`))].join("\n");
+}
+function trimBlankEdges(lines) {
+    const out = lines.map((line) => line.replace(/\s+$/, ""));
+    while (out.length > 0 && out[0] === "")
+        out.shift();
+    while (out.length > 0 && out[out.length - 1] === "")
+        out.pop();
+    return out;
+}

package/dist/format/cardMarkdown.d.ts

@@ -14,6 +14,8 @@ export interface MarkdownCardInput {
     labels?: string[];
     kind?: "question";
     resolution?: string;
+    scope?: "out";
+    blockedBy?: number[];
 }
 export interface MarkdownBoardRef {
     _id: string;

package/dist/format/cardMarkdown.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 <-> kanban card serialization for the agent FS API (/v1/fs).
 //
 // Mirrors postMarkdown.ts: frontmatter/YAML, mentions, slugs, dates, and the
@@ -68,9 +70,17 @@ export function cardToMarkdown(card, board, column, commentsCount) {
         ["kind", card.kind], // undefined for ordinary tasks → skipped
         ["status", card.status],
         ["resolution", card.resolution], // set once a question is decided
+        ["scope", card.scope], // "out" for a question ruled out of scope
         ["priority", card.priority ?? "none"],
         ["assignees", card.assignees ?? []],
         ["labels", card.labels ?? []],
+        // Emitted only when edges exist — key absent means "no blockers".
+        [
+            "blocked-by",
+            card.blockedBy && card.blockedBy.length > 0
+                ? card.blockedBy.map(String)
+                : undefined,
+        ],
         ["due", toDateOnly(card.dueAt)],
         ["created", toISO(card._creationTime)],
         ["lastActivityAt", toISO(card.lastActivityAt)],

package/dist/format/checklist.d.ts

@@ -0,0 +1,34 @@
+export declare const CHECKBOX_RE: RegExp;
+/** One checkbox, as both the scan and the reader see it. */
+export interface ChecklistItem {
+    /** 0-based line index in the body. The reader's join key. */
+    line: number;
+    /** 0-based position in document order — the index `toggleChecklistItem` takes. */
+    index: number;
+    checked: boolean;
+    /** The item's text, markup intact. */
+    text: string;
+}
+export interface ChecklistProgress {
+    done: number;
+    total: number;
+}
+/**
+ * Every checkbox in a body, in document order.
+ *
+ * Non-rendering bytes are skipped: a `- [ ]` inside a ``` block, an inline
+ * code span or an HTML comment is a sample, not a task, and counting it is how
+ * a click on the first real checkbox ends up rewriting a line inside someone's
+ * code. That judgement comes from `lineGeometry`'s shared mask — the same one
+ * lint and the block parsers read — so nothing here decides on its own what
+ * renders. A fence inside a blockquote or a callout counts too, since a quoted
+ * `- [ ]` is otherwise a task.
+ *
+ * Indented code is skipped the only way a line scan can tell: four spaces of
+ * indent with no enclosing list item above it is a code block, whereas the
+ * same indent under a bullet is a nested list. Bodies carry no frontmatter —
+ * callers hand us a body, same as the reader — so the fence scan starts at 0.
+ */
+export declare function scanChecklist(body: string | undefined | null): ChecklistItem[];
+export declare function checklistProgress(body: string | undefined | null): ChecklistProgress;
+export declare function toggleChecklistItem(body: string, index: number): string;

package/dist/format/checklist.js

@@ -0,0 +1,151 @@
+// 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).
+// Checklist items are plain markdown checkboxes — `- [ ]` / `- [x]` — in an
+// entity body. There is no separate sub-task entity: the body IS the list, so
+// progress and toggling are string operations over it.
+//
+// ONE scan answers all three questions — which lines are checkboxes, how many
+// are done, and which line index N addresses. The reader (src/lib/utils/
+// markdown.ts) walks the mdast tree instead, and joins back to this scan BY
+// LINE, so a rendered checkbox and the line a toggle rewrites are the same
+// line by construction rather than by two counters agreeing.
+//
+// Pure: no React, no Convex, no Node. The web app re-exports this from
+// src/lib/subtasks.ts; the mobile preprocessor keeps its own copy because
+// packages/mobile installs outside the pnpm workspace.
+import { lineText, maskNonRenderingLines } from "./lineGeometry.js";
+/** The blockquote markers opening a line — `>` runs, callout syntax included. */
+const QUOTE_PREFIX_RE = /^(?:[ \t]{0,3}>[ \t]?)*/;
+/**
+ * Non-rendering lines that only a blockquote-relative scan can see.
+ *
+ * The mask reads the raw lines, where `> ```` ``` ```` is not a fence open at
+ * all, so a sample checkbox inside a quoted or callout fence would count as a
+ * task. Quote markers therefore come off before the scan — but only within a
+ * contiguous run of lines at the SAME quote depth, because a blockquote is its
+ * own container: an unclosed fence inside one ends with the quote and must not
+ * swallow the real checkboxes that follow it at top level.
+ *
+ * Depth 0 is left to the caller's raw mask, which already reads those lines
+ * with their `>`-looking content intact.
+ */
+function quotedNonRenderingMask(lines) {
+    const mask = new Array(lines.length).fill(false);
+    const depths = lines.map((_, i) => (lineText(lines, i).match(QUOTE_PREFIX_RE)[0].match(/>/g) ?? []).length);
+    for (let start = 0; start < lines.length; start++) {
+        const depth = depths[start];
+        if (depth === 0)
+            continue;
+        let end = start;
+        while (end + 1 < lines.length && depths[end + 1] === depth)
+            end++;
+        const stripped = [];
+        for (let i = start; i <= end; i++) {
+            stripped.push(lineText(lines, i).replace(QUOTE_PREFIX_RE, ""));
+        }
+        const quoted = maskNonRenderingLines(stripped);
+        for (let i = 0; i < quoted.length; i++) {
+            if (quoted[i].trim() === "")
+                mask[start + i] = true;
+        }
+        start = end;
+    }
+    return mask;
+}
+// A checkbox line: optional blockquote markers, then a bullet (`-`/`*`/`+`) or
+// an ordered marker (`1.`/`1)`), then the state box. Every one of these forms
+// is a task item to GFM, so every one of them is addressable here — a reader
+// that renders `1. [ ] ship` interactive and a toggler whose regex cannot see
+// it is the divergence this grammar exists to close.
+//
+// Captures the prefix, the state character, the gap, and the item text, so a
+// toggle rebuilds the line byte for byte apart from the box it flipped.
+export const CHECKBOX_RE = /^((?:[ \t]{0,3}>[ \t]?)*[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+)\[([ xX])\]([ \t]+)(.*)$/;
+// The same opening, without the box — any list item at all. Establishes the
+// list context that tells an indented nested checkbox from indented code.
+const BULLET_RE = /^(?:[ \t]{0,3}>[ \t]?)*([ \t]*)(?:[-*+]|\d{1,9}[.)])[ \t]+/;
+/** Indentation of a line's content, blockquote markers not counted. */
+const INDENT_RE = /^(?:[ \t]{0,3}>[ \t]?)*([ \t]*)/;
+/**
+ * Every checkbox in a body, in document order.
+ *
+ * Non-rendering bytes are skipped: a `- [ ]` inside a ``` block, an inline
+ * code span or an HTML comment is a sample, not a task, and counting it is how
+ * a click on the first real checkbox ends up rewriting a line inside someone's
+ * code. That judgement comes from `lineGeometry`'s shared mask — the same one
+ * lint and the block parsers read — so nothing here decides on its own what
+ * renders. A fence inside a blockquote or a callout counts too, since a quoted
+ * `- [ ]` is otherwise a task.
+ *
+ * Indented code is skipped the only way a line scan can tell: four spaces of
+ * indent with no enclosing list item above it is a code block, whereas the
+ * same indent under a bullet is a nested list. Bodies carry no frontmatter —
+ * callers hand us a body, same as the reader — so the fence scan starts at 0.
+ */
+export function scanChecklist(body) {
+    if (!body)
+        return [];
+    const lines = body.split("\n");
+    const masked = maskNonRenderingLines(lines);
+    const quoted = quotedNonRenderingMask(lines);
+    const out = [];
+    // Indent of the innermost list item still open above the cursor, or null
+    // when we are at top level. A non-blank unindented line that is not itself a
+    // list item closes the list.
+    let openIndent = null;
+    for (let i = 0; i < lines.length; i++) {
+        if (quoted[i])
+            continue;
+        // Structure is read off the MASKED line, so a fenced, commented-out or
+        // code-spanned checkbox is not a list item and not a task; the item's own
+        // text still comes off the raw line, markup intact.
+        const line = lineText(masked, i);
+        if (line.trim() === "")
+            continue;
+        const bullet = BULLET_RE.exec(line);
+        if (!bullet) {
+            if (INDENT_RE.exec(line)[1].length === 0)
+                openIndent = null;
+            continue;
+        }
+        const indent = bullet[1].length;
+        if (indent >= 4 && (openIndent === null || openIndent >= indent))
+            continue;
+        openIndent = indent;
+        const raw = lineText(lines, i);
+        const box = CHECKBOX_RE.exec(raw);
+        // The state box has to be one of the bytes that render. `- [ ] a` inside
+        // an inline code span survives the bullet test above — the marker is
+        // outside the span — but the box itself is masked, and a toggle would be
+        // rewriting someone's sample.
+        if (!box || line[box[1].length] !== "[")
+            continue;
+        out.push({
+            line: i,
+            index: out.length,
+            checked: box[2] !== " ",
+            text: box[4],
+        });
+    }
+    return out;
+}
+// Count checkbox items in a body. total === 0 means "no checklist".
+export function checklistProgress(body) {
+    const items = scanChecklist(body);
+    return { done: items.filter((item) => item.checked).length, total: items.length };
+}
+// Toggle the Nth checkbox (0-based, in document order) and return the new body.
+// Returns the original body unchanged if the index is out of range.
+export function toggleChecklistItem(body, index) {
+    const item = scanChecklist(body)[index];
+    if (!item)
+        return body;
+    const lines = body.split("\n");
+    const raw = lines[item.line];
+    const eol = raw.endsWith("\r") ? "\r" : "";
+    const m = CHECKBOX_RE.exec(eol ? raw.slice(0, -1) : raw);
+    if (!m)
+        return body;
+    lines[item.line] = `${m[1]}[${item.checked ? " " : "x"}]${m[3]}${m[4]}${eol}`;
+    return lines.join("\n");
+}

package/dist/format/index.d.ts

@@ -1,13 +1,27 @@
 /**
  * The sfora markdown format — the single source of truth for how posts, tasks
- * (cards), and docs (notes) serialize to/from markdown files.
+ * (cards), and docs (notes) serialize to/from markdown files, plus the shared
+ * grammar every surface used to reimplement (wiki links, checklists,
+ * plaintext flattening, structured blocks).
  *
  * This package is canonical: the Convex backend re-exports these modules
- * (convex/lib/* are thin shims), so cloud files and local `.sfora/` files are
- * byte-identical by construction. Round-trip tests live in convex/lib/__tests__
- * and exercise this code through the shims.
+ * (convex/lib/* are thin shims), the published CLI syncs this source into its
+ * own tree at build time (packages/sfora/scripts/sync-format.mjs), and the web
+ * app reaches it through the `@sfora/markdown` alias — so cloud files, local
+ * `.sfora/` files, and everything in between are byte-identical by
+ * construction. Round-trip and parse-health tests live in `src/__tests__/`.
  */
 export * from "./markdown/index.js";
 export * from "./cardMarkdown.js";
 export * from "./postMarkdown.js";
 export * from "./noteMarkdown.js";
+export * from "./wikiLinks.js";
+export * from "./plaintext.js";
+export * from "./checklist.js";
+export * from "./parseWithFallback.js";
+export * from "./callout.js";
+export * from "./lint/index.js";
+export * from "./blocks/structured-block-schema.js";
+export * from "./blocks/markdown-block-catalog.js";
+export * from "./blocks/dropClosure.js";
+export * from "./wayfinder.js";

package/dist/format/index.js

@@ -1,13 +1,33 @@
+// 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 sfora markdown format — the single source of truth for how posts, tasks
- * (cards), and docs (notes) serialize to/from markdown files.
+ * (cards), and docs (notes) serialize to/from markdown files, plus the shared
+ * grammar every surface used to reimplement (wiki links, checklists,
+ * plaintext flattening, structured blocks).
  *
  * This package is canonical: the Convex backend re-exports these modules
- * (convex/lib/* are thin shims), so cloud files and local `.sfora/` files are
- * byte-identical by construction. Round-trip tests live in convex/lib/__tests__
- * and exercise this code through the shims.
+ * (convex/lib/* are thin shims), the published CLI syncs this source into its
+ * own tree at build time (packages/sfora/scripts/sync-format.mjs), and the web
+ * app reaches it through the `@sfora/markdown` alias — so cloud files, local
+ * `.sfora/` files, and everything in between are byte-identical by
+ * construction. Round-trip and parse-health tests live in `src/__tests__/`.
  */
 export * from "./markdown/index.js";
 export * from "./cardMarkdown.js";
 export * from "./postMarkdown.js";
 export * from "./noteMarkdown.js";
+export * from "./wikiLinks.js";
+export * from "./plaintext.js";
+export * from "./checklist.js";
+export * from "./parseWithFallback.js";
+export * from "./callout.js";
+export * from "./lint/index.js";
+export * from "./blocks/structured-block-schema.js";
+export * from "./blocks/markdown-block-catalog.js";
+export * from "./blocks/dropClosure.js";
+export * from "./wayfinder.js";
+// htmlToMarkdown and parseMarkdownAst are deliberately NOT in the barrel:
+// they carry the package's only heavy dependencies (unified/rehype/remark)
+// and are excluded from the CLI sync — consumers import the subpaths
+// `@sfora/markdown/htmlToMarkdown` and `@sfora/markdown/parseMarkdownAst`.

package/dist/format/lineGeometry.d.ts

@@ -0,0 +1,70 @@
+/** A fenced code block, delimiters included. */
+export interface FenceRegion {
+    /** Line index of the opening delimiter. */
+    open: number;
+    /** Line index of the closing delimiter, or of the last line when unclosed. */
+    close: number;
+    /** True when a closing delimiter was actually found. */
+    closed: boolean;
+    /** First word of the info string, lowercased. Empty for a bare fence. */
+    lang: string;
+    /** Leading spaces on the opening delimiter — content is dedented by these. */
+    indent: number;
+    /** First content line index (exclusive of the delimiter). */
+    contentStart: number;
+    /** One past the last content line. */
+    contentEnd: number;
+}
+/** The line without its trailing `\r`, so `$`-anchored rules work on CRLF. */
+export declare function lineText(lines: readonly string[], i: number): string;
+/**
+ * Frontmatter extent, or null. Only a document that OPENS with `---` has
+ * frontmatter — a `---` further down is a thematic break, and treating it as a
+ * fence would make every horizontal rule the start of a lint dead zone.
+ */
+export declare function frontmatterExtent(lines: readonly string[]): {
+    open: number;
+    close: number;
+} | null;
+/**
+ * Every fenced code block in the document, in order. `from` skips the
+ * frontmatter block, whose contents are not markdown either.
+ */
+export declare function fencedRegions(lines: readonly string[], from?: number): FenceRegion[];
+/** True for every line covered by a fenced block, delimiters included. */
+export declare function fenceMask(lines: readonly string[], from?: number): boolean[];
+/**
+ * True where a line is inside an inline code span, delimiters included.
+ *
+ * Rules and parsers mask their matches against this so a token quoted as
+ * `` `[[c:1]]` `` — the way documentation talks ABOUT the grammar — is never
+ * read as using it, and so a pipe inside `` `a|b` `` is content rather than a
+ * cell boundary. Line-local by design: a code span cannot cross a blank line,
+ * and the callers hold one line at a time.
+ */
+export declare function codeSpanMask(line: string): boolean[];
+/**
+ * The non-rendering mask, line by line. Each returned line has exactly the
+ * length of the line it masks, so `masked[i][k]` and `lines[i][k]` are the
+ * same byte position.
+ *
+ * `from` skips a leading frontmatter block for the FENCE scan only, mirroring
+ * {@link fenceMask} — whether the frontmatter itself renders is the caller's
+ * question, and lint already answers it with `inFrontmatter`.
+ */
+export declare function maskNonRenderingLines(lines: readonly string[], from?: number): string[];
+/**
+ * The whole source, masked. `masked.length === source.length` always: the two
+ * strings are the same document, one of them with the non-markdown blanked
+ * out, and every offset holds across both.
+ */
+export declare function maskNonRenderingContexts(source: string): string;
+/**
+ * True when the source span `[start, end)` holds bytes but no rendering ones —
+ * the predicate a consumer asks before trusting anything it found by scanning.
+ *
+ * A span that was blank to begin with is not "non-rendering", it is empty, and
+ * answering true for it would demote every piece of whitespace in the
+ * document.
+ */
+export declare function isNonRenderingRange(source: string, masked: string, start: number, end: number): boolean;