sfora-cli 0.7.0 → 0.8.0

package/dist/format/cardMarkdown.d.ts

@@ -0,0 +1,36 @@
+import { parseDateInput, rehydrateMentions, slugFromFilename, slugify } from "./markdown/index.js";
+export { parseDateInput, rehydrateMentions, slugFromFilename, slugify };
+export interface MarkdownCardInput {
+    _id: string;
+    number: number;
+    title: string;
+    body: string;
+    status: "drafted" | "active" | "closed";
+    priority?: "none" | "low" | "medium" | "high" | "urgent";
+    dueAt?: number;
+    _creationTime?: number;
+    lastActivityAt?: number;
+    assignees?: string[];
+    labels?: string[];
+}
+export interface MarkdownBoardRef {
+    _id: string;
+    name: string;
+    slug?: string;
+}
+export interface MarkdownColumnRef {
+    _id: string;
+    name: string;
+    position: number;
+}
+export interface ParsedMarkdownCard {
+    title: string;
+    body: string;
+    frontmatter: Record<string, string | string[]>;
+}
+export declare function cardFilename(card: Pick<MarkdownCardInput, "number" | "title">): string;
+export declare function columnDirname(col: Pick<MarkdownColumnRef, "name" | "position">): string;
+export declare function numberFromFilename(filename: string): number | undefined;
+export declare function columnSlugFromDirname(dirname: string): string;
+export declare function cardToMarkdown(card: MarkdownCardInput, board: MarkdownBoardRef | null, column: MarkdownColumnRef | null, commentsCount: number): string;
+export declare function parseMarkdownCard(md: string): ParsedMarkdownCard;

package/dist/format/cardMarkdown.js

@@ -0,0 +1,83 @@
+// Pure markdown <-> kanban card serialization for the agent FS API (/v1/fs).
+//
+// Mirrors postMarkdown.ts: frontmatter/YAML, mentions, slugs, dates, and the
+// document shape come from the shared ./markdown core; this module keeps only
+// the card-specific field mapping + the board/column filename scheme.
+//
+// Wire format is a Jekyll-style markdown file:
+//
+//   ---
+//   id: c1a2…
+//   number: 42
+//   board: <slug>
+//   column: in-progress
+//   status: active
+//   assignees: [Ada Lovelace, bot-claude]
+//   labels: [bug, p0]
+//   due: 2026-07-01
+//   created: 2026-06-19T12:34:56.000Z
+//   lastActivityAt: 2026-06-19T18:02:11.000Z
+//   ---
+//
+//   # Fix login
+//
+//   Body markdown here…
+//
+// The body uses the same @[Name](memberId) mention syntax as posts / messages.
+import { buildDocument, parseDateInput, parseDocument, rehydrateMentions, renderMentions, serializeFrontmatter, slugFromFilename, slugify, toDateOnly, toISO, } from "./markdown/index.js";
+// Re-export the shared helpers so callers only need one import.
+export { parseDateInput, rehydrateMentions, slugFromFilename, slugify };
+// ─── Filenames ─────────────────────────────────────────────────────
+// `NNNN-<slug>.md` — zero-padded so `ls` sorts in number order. 4 digits is
+// enough until a single board hits 10k cards; beyond that the prefix just gets
+// wider and lex-sort still holds.
+export function cardFilename(card) {
+    const pad = String(card.number).padStart(4, "0");
+    return `${pad}-${slugify(card.title)}.md`;
+}
+// `NN-<slug>` directory name for a column — `01-todo`, `02-in-progress`. NN is
+// derived from the column's `position` field. Position is 0-indexed in the DB
+// so display +1 → `01` for the first column.
+export function columnDirname(col) {
+    const pad = String(col.position + 1).padStart(2, "0");
+    return `${pad}-${slugify(col.name)}`;
+}
+// Pull the card number back out of a filename like `0042-fix-login.md`. Returns
+// undefined for filenames without a number prefix (newly created via `touch`).
+export function numberFromFilename(filename) {
+    const m = /^(\d+)-/.exec(filename);
+    if (!m)
+        return undefined;
+    const n = Number.parseInt(m[1], 10);
+    return Number.isFinite(n) ? n : undefined;
+}
+// Pull the column slug back out of a directory name like `02-in-progress`.
+export function columnSlugFromDirname(dirname) {
+    return dirname.replace(/^\d+-/, "");
+}
+// ─── Serialize + parse ─────────────────────────────────────────────
+export function cardToMarkdown(card, board, column, commentsCount) {
+    const { text, names } = renderMentions(card.body);
+    const fm = serializeFrontmatter([
+        ["id", card._id],
+        ["number", String(card.number)],
+        ["board", board?.slug ?? board?.name ?? ""],
+        ["boardId", board?._id ?? ""],
+        ["column", column?.name ?? ""],
+        ["columnId", column?._id ?? ""],
+        ["status", card.status],
+        ["priority", card.priority ?? "none"],
+        ["assignees", card.assignees ?? []],
+        ["labels", card.labels ?? []],
+        ["due", toDateOnly(card.dueAt)],
+        ["created", toISO(card._creationTime)],
+        ["lastActivityAt", toISO(card.lastActivityAt)],
+        ["comments", String(commentsCount)],
+        ["mentions", names],
+    ]);
+    return buildDocument(fm, card.title, text);
+}
+// Parse a markdown file back to card fields (shared document parser).
+export function parseMarkdownCard(md) {
+    return parseDocument(md);
+}

package/dist/format/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The sfora markdown format — the single source of truth for how posts, tasks
+ * (cards), and docs (notes) serialize to/from markdown files.
+ *
+ * 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.
+ */
+export * from "./markdown/index.js";
+export * from "./cardMarkdown.js";
+export * from "./postMarkdown.js";
+export * from "./noteMarkdown.js";

package/dist/format/index.js

@@ -0,0 +1,13 @@
+/**
+ * The sfora markdown format — the single source of truth for how posts, tasks
+ * (cards), and docs (notes) serialize to/from markdown files.
+ *
+ * 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.
+ */
+export * from "./markdown/index.js";
+export * from "./cardMarkdown.js";
+export * from "./postMarkdown.js";
+export * from "./noteMarkdown.js";

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

@@ -0,0 +1,3 @@
+export declare function toISO(ms?: number): string | undefined;
+export declare function toDateOnly(ms?: number): string | undefined;
+export declare function parseDateInput(s: string | undefined): number | undefined;

package/dist/format/markdown/dates.js

@@ -0,0 +1,26 @@
+// 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) {
+    if (ms == null || ms === 0 || !Number.isFinite(ms))
+        return undefined;
+    return new Date(ms).toISOString();
+}
+// `YYYY-MM-DD` for coarse dates (e.g. a due date); round-trips through
+// `new Date(s).getTime()` cleanly.
+export function toDateOnly(ms) {
+    if (ms == null || ms === 0 || !Number.isFinite(ms))
+        return undefined;
+    return new Date(ms).toISOString().slice(0, 10);
+}
+// Best-effort: parse a YYYY-MM-DD or ISO date string back to a millisecond
+// timestamp. Returns undefined for empty/garbage input so callers can omit the
+// field rather than write 0.
+export function parseDateInput(s) {
+    if (!s)
+        return undefined;
+    const t = s.trim();
+    if (!t)
+        return undefined;
+    const ms = new Date(t).getTime();
+    return Number.isFinite(ms) ? ms : undefined;
+}

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

@@ -0,0 +1,7 @@
+export interface ParsedDocument {
+    title: string;
+    body: string;
+    frontmatter: Record<string, string | string[]>;
+}
+export declare function parseDocument(md: string): ParsedDocument;
+export declare function buildDocument(frontmatter: string, title: string, body: string): string;

package/dist/format/markdown/document.js

@@ -0,0 +1,45 @@
+// 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";
+// Parse a markdown file back to fields. Title is the first H1 if present, else
+// the frontmatter `title:`. Body is everything after the H1 (or the whole
+// content, minus frontmatter, when there is no H1). Tolerates a leading BOM and
+// CRLF line endings.
+export function parseDocument(md) {
+    let frontmatter = {};
+    let rest = md;
+    const fmMatch = /^?---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/.exec(md);
+    if (fmMatch) {
+        frontmatter = parseYaml(fmMatch[1]);
+        rest = md.slice(fmMatch[0].length);
+    }
+    const lines = rest.split(/\r?\n/);
+    let title = "";
+    let bodyStart = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === "")
+            continue;
+        const h1 = /^#\s+(.+?)\s*$/.exec(lines[i]);
+        if (h1) {
+            title = h1[1].trim();
+            bodyStart = i + 1;
+        }
+        break; // only the first non-empty line can be the H1 title
+    }
+    let body;
+    if (title) {
+        body = lines.slice(bodyStart).join("\n").trim();
+    }
+    else {
+        title =
+            typeof frontmatter.title === "string" ? frontmatter.title.trim() : "";
+        body = rest.trim();
+    }
+    return { title, body, frontmatter };
+}
+// Build the canonical file form: frontmatter fence + H1 + trimmed body. This is
+// the exact inverse layout `parseDocument` expects, so serialize→parse is a
+// round trip for title + body.
+export function buildDocument(frontmatter, title, body) {
+    return `---\n${frontmatter}\n---\n\n# ${title}\n\n${body.trim()}\n`;
+}

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

@@ -0,0 +1,5 @@
+export * from "./yaml.js";
+export * from "./mentions.js";
+export * from "./slug.js";
+export * from "./dates.js";
+export * from "./document.js";

package/dist/format/markdown/index.js

@@ -0,0 +1,9 @@
+// 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,
+// cardMarkdown, and noteMarkdown so they can't drift apart.
+export * from "./yaml.js";
+export * from "./mentions.js";
+export * from "./slug.js";
+export * from "./dates.js";
+export * from "./document.js";

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

@@ -0,0 +1,8 @@
+export declare function renderMentions(body: string): {
+    text: string;
+    names: string[];
+};
+export declare function rehydrateMentions(body: string, members: Array<{
+    _id: string;
+    name: string;
+}>): string;

package/dist/format/markdown/mentions.js

@@ -0,0 +1,36 @@
+// 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
+// names in a `mentions` frontmatter array so a round trip can reconstruct it.
+const MENTION_REGEX = /@\[(.+?)\]\((.+?)\)/g;
+// @[Name](id) → @Name, collecting the display names (deduped, in order).
+export function renderMentions(body) {
+    const names = [];
+    const seen = new Set();
+    const text = body.replace(MENTION_REGEX, (_m, name) => {
+        if (!seen.has(name)) {
+            seen.add(name);
+            names.push(name);
+        }
+        return `@${name}`;
+    });
+    return { text, names };
+}
+// Best-effort inverse of `renderMentions`: turn a bare `@Display Name` back into
+// canonical @[Display Name](memberId) so mentions hand-written by an agent still
+// notify. Longest names first so "Ada Lovelace" wins over "Ada"; tokens already
+// in @[..](..) form are left untouched.
+export function rehydrateMentions(body, members) {
+    const sorted = [...members]
+        .filter((m) => m.name.trim().length > 0)
+        .sort((a, b) => b.name.length - a.name.length);
+    let out = body;
+    for (const m of sorted) {
+        const escaped = m.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        // Match `@Name` when preceded by a non-word/non-@/non-[ char (or start) and
+        // not already followed by the `](` of an explicit mention.
+        const re = new RegExp(`(^|[^\\w@[])@${escaped}(?!\\]\\()`, "g");
+        out = out.replace(re, (_full, pre) => `${pre}@[${m.name}](${m._id})`);
+    }
+    return out;
+}

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

@@ -0,0 +1,2 @@
+export declare function slugify(title: string): string;
+export declare function slugFromFilename(filename: string): string;

package/dist/format/markdown/slug.js

@@ -0,0 +1,19 @@
+// 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
+// colliding slugs (-2/-3) is a caller concern, not handled here.
+export function slugify(title) {
+    const s = title
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "") // strip combining accents
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return s || "untitled";
+}
+// 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) {
+    return filename.replace(/\.md$/i, "").replace(/^\d{4}-\d{2}-\d{2}-/, "");
+}

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

@@ -0,0 +1,4 @@
+export declare function yamlScalar(value: string): string;
+export declare function serializeFrontmatter(fields: Array<[string, string | string[] | undefined]>): string;
+export declare function unquote(s: string): string;
+export declare function parseYaml(src: string): Record<string, string | string[]>;

package/dist/format/markdown/yaml.js

@@ -0,0 +1,72 @@
+// 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
+// functions, and the standalone CLI / MCP package.
+// Quote a scalar when it could be misparsed (empty, contains :/#/brackets,
+// leading/trailing space, or already starts with a quote). Plain display names
+// and date-only values pass through unquoted; values with colons — including ISO
+// timestamps — are quoted, and `unquote` strips them again on the way back.
+export function yamlScalar(value) {
+    if (value === "" || /[:#[\]]|^\s|\s$|^["']/.test(value)) {
+        return JSON.stringify(value);
+    }
+    return value;
+}
+// Serialize an ordered list of [key, value] pairs into a frontmatter block body
+// (the text that goes between the --- fences). `undefined` values are skipped so
+// callers can omit optional fields; arrays render as `[a, b, c]`.
+export function serializeFrontmatter(fields) {
+    const lines = [];
+    for (const [key, value] of fields) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            lines.push(`${key}: [${value.map(yamlScalar).join(", ")}]`);
+        }
+        else {
+            lines.push(`${key}: ${yamlScalar(value)}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function unquote(s) {
+    const t = s.trim();
+    if (t.length >= 2 && t[0] === '"' && t[t.length - 1] === '"') {
+        try {
+            return JSON.parse(t);
+        }
+        catch {
+            return t.slice(1, -1);
+        }
+    }
+    if (t.length >= 2 && t[0] === "'" && t[t.length - 1] === "'") {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+// Parse a frontmatter block body. Supports `key: scalar` and `key: [a, b, c]`.
+// Comment-only and blank lines are skipped.
+export function parseYaml(src) {
+    const out = {};
+    for (const raw of src.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const idx = line.indexOf(":");
+        if (idx === -1)
+            continue;
+        const key = line.slice(0, idx).trim();
+        if (!key)
+            continue;
+        const value = line.slice(idx + 1).trim();
+        if (value.startsWith("[") && value.endsWith("]")) {
+            const inner = value.slice(1, -1).trim();
+            out[key] =
+                inner.length === 0 ? [] : inner.split(",").map((s) => unquote(s));
+        }
+        else {
+            out[key] = unquote(value);
+        }
+    }
+    return out;
+}

package/dist/format/noteMarkdown.d.ts

@@ -0,0 +1,28 @@
+import { rehydrateMentions, slugFromFilename, slugify } from "./markdown/index.js";
+export { rehydrateMentions, slugFromFilename, slugify };
+export interface MarkdownNoteInput {
+    _id: string;
+    title: string;
+    body: string;
+    _creationTime?: number;
+    lastEditedAt?: number;
+    frontmatter?: Record<string, string>;
+}
+export interface MarkdownNoteAuthor {
+    _id: string;
+    name: string;
+    type: "human" | "agent";
+}
+export interface MarkdownNoteProject {
+    _id: string;
+    name: string;
+    slug: string;
+}
+export interface ParsedMarkdownNote {
+    title: string;
+    body: string;
+    frontmatter: Record<string, string | string[]>;
+}
+export declare function noteFilename(note: Pick<MarkdownNoteInput, "title">): string;
+export declare function noteToMarkdown(note: MarkdownNoteInput, author: MarkdownNoteAuthor | null, project: MarkdownNoteProject | null, commentsCount: number): string;
+export declare function parseMarkdownNote(md: string): ParsedMarkdownNote;

package/dist/format/noteMarkdown.js

@@ -0,0 +1,66 @@
+// 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
+// prefix, unlike posts).
+//
+// Mirrors postMarkdown.ts / cardMarkdown.ts: frontmatter/YAML, mention
+// rendering, slugs, and the document shape come from the shared ./markdown core;
+// this module keeps only the note-specific field mapping + filename scheme.
+//
+// Wire format is a Jekyll-style markdown file: a YAML frontmatter block of note
+// metadata (system keys first, then the note's user-defined frontmatter kv
+// pairs), an H1 title, then the body. Internal @[Name](memberId) mentions render
+// to a human-readable @Name, with the display names kept in the `mentions`
+// frontmatter array so a round trip can reconstruct them (see `rehydrateMentions`).
+import { buildDocument, parseDocument, rehydrateMentions, renderMentions, serializeFrontmatter, slugFromFilename, slugify, toISO, } from "./markdown/index.js";
+// Re-export the shared helpers so callers only need one import.
+export { rehydrateMentions, slugFromFilename, slugify };
+// System frontmatter keys, in serialization order. User-defined frontmatter
+// that collides with one of these is dropped (the system value wins).
+const SYSTEM_KEYS = new Set([
+    "id",
+    "project",
+    "projectId",
+    "author",
+    "authorId",
+    "authorType",
+    "lastEditedAt",
+    "comments",
+    "mentions",
+]);
+// ─── Filenames ─────────────────────────────────────────────────────
+// `<slug>.md` — no date prefix. Notes are stable named docs, so the filename is
+// derived purely from the title.
+export function noteFilename(note) {
+    return `${slugify(note.title)}.md`;
+}
+// ─── Serialize + parse ─────────────────────────────────────────────
+export function noteToMarkdown(note, author, project, commentsCount) {
+    const { text, names } = renderMentions(note.body);
+    const fields = [
+        ["id", note._id],
+        ["project", project?.slug ?? ""],
+        ["projectId", project?._id ?? ""],
+        ["author", author?.name ?? "Unknown"],
+        ["authorId", author?._id ?? ""],
+        ["authorType", author?.type ?? "human"],
+        ["lastEditedAt", toISO(note.lastEditedAt)],
+        ["comments", String(commentsCount)],
+        ["mentions", names],
+    ];
+    // Merge the note's user-defined frontmatter after the system keys, skipping
+    // any key that collides with a system key.
+    if (note.frontmatter) {
+        for (const [key, value] of Object.entries(note.frontmatter)) {
+            if (SYSTEM_KEYS.has(key))
+                continue;
+            fields.push([key, value]);
+        }
+    }
+    const fm = serializeFrontmatter(fields);
+    return buildDocument(fm, note.title, text);
+}
+// Parse a markdown file back to note fields (shared document parser).
+export function parseMarkdownNote(md) {
+    return parseDocument(md);
+}

package/dist/format/postMarkdown.d.ts

@@ -0,0 +1,32 @@
+import { rehydrateMentions, slugFromFilename, slugify } from "./markdown/index.js";
+export { rehydrateMentions, slugFromFilename, slugify };
+export interface MarkdownPostInput {
+    _id: string;
+    title: string;
+    body: string;
+    publishedAt?: number;
+    _creationTime?: number;
+    editedAt?: number;
+    resolvedAt?: number;
+    isPinned?: boolean;
+    isDraft?: boolean;
+    scheduledFor?: number;
+}
+export interface MarkdownAuthor {
+    _id: string;
+    name: string;
+    type: "human" | "agent";
+}
+export interface MarkdownProject {
+    _id: string;
+    name: string;
+    slug: string;
+}
+export interface ParsedMarkdownPost {
+    title: string;
+    body: string;
+    frontmatter: Record<string, string | string[]>;
+}
+export declare function mdFilename(post: MarkdownPostInput): string;
+export declare function postToMarkdown(post: MarkdownPostInput, author: MarkdownAuthor | null, project: MarkdownProject | null, commentsCount: number): string;
+export declare function parseMarkdownPost(md: string): ParsedMarkdownPost;

package/dist/format/postMarkdown.js

@@ -0,0 +1,53 @@
+// Pure markdown <-> post serialization for the agent filesystem API (/v1/fs).
+//
+// Frontmatter/YAML, mention rendering, slugs, and the document shape now live in
+// ./markdown (shared with cardMarkdown + noteMarkdown). This module keeps only
+// the post-specific field mapping + filename scheme.
+//
+// The wire format is a Jekyll-style markdown file: a YAML frontmatter block of
+// post metadata, then an H1 title, then the body. Internal @[Name](memberId)
+// mention syntax is rendered to a human-readable @Name in the body, with the
+// raw display names preserved in the `mentions` frontmatter array so a round
+// 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.
+export { rehydrateMentions, slugFromFilename, slugify };
+// ─── Filenames ─────────────────────────────────────────────────────
+// The YYYY-MM-DD part of a filename. Published posts use publishedAt; drafts
+// (publishedAt === 0) fall back to _creationTime so they still sort stably.
+function datePart(post) {
+    const ms = post.publishedAt && post.publishedAt > 0
+        ? post.publishedAt
+        : post._creationTime ?? 0;
+    return new Date(ms > 0 ? ms : 0).toISOString().slice(0, 10);
+}
+// `YYYY-MM-DD-<slug>.md`
+export function mdFilename(post) {
+    return `${datePart(post)}-${slugify(post.title)}.md`;
+}
+// ─── Serialize + parse ─────────────────────────────────────────────
+export function postToMarkdown(post, author, project, commentsCount) {
+    const { text, names } = renderMentions(post.body);
+    const fm = serializeFrontmatter([
+        ["id", post._id],
+        ["project", project?.slug ?? ""],
+        ["projectId", project?._id ?? ""],
+        ["author", author?.name ?? "Unknown"],
+        ["authorId", author?._id ?? ""],
+        ["authorType", author?.type ?? "human"],
+        ["publishedAt", toISO(post.publishedAt)],
+        ["editedAt", toISO(post.editedAt)],
+        ["resolvedAt", toISO(post.resolvedAt)],
+        ["isPinned", post.isPinned ? "true" : undefined],
+        ["scheduledFor", toISO(post.scheduledFor)],
+        ["isDraft", post.isDraft ? "true" : undefined],
+        ["comments", String(commentsCount)],
+        ["mentions", names],
+    ]);
+    return buildDocument(fm, post.title, text);
+}
+// Parse a markdown file back to post fields (shared document parser).
+export function parseMarkdownPost(md) {
+    return parseDocument(md);
+}

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  * workspace. The CLI also exposes first-class verbs (post/task/doc) and an MCP
  * server so agents operate sfora natively.
  */
-import { Bash } from "just-bash";
+import { Bash, ReadWriteFs } from "just-bash";
 import { SforaFs } from "./SforaFs.js";
 export interface CreateSforaShellOptions {
     /** Base URL of the sfora deployment, e.g. `http://localhost:2222`. */
@@ -21,11 +21,26 @@ export interface CreateSforaShellOptions {
     org: string;
     /** Initial working directory inside the virtual fs. Defaults to `/`. */
     cwd?: string;
+    /** Act/post as an owned agent, using this key (sent as `X-Sfora-Act-As`). */
+    actAs?: string;
 }
 export interface SforaShell {
     bash: Bash;
     fs: SforaFs;
 }
 export declare function createSforaShell(options: CreateSforaShellOptions): SforaShell;
+export interface LocalShell {
+    bash: Bash;
+    fs: ReadWriteFs;
+}
+/**
+ * Shell over a local `.sfora/` workspace — the OSS serverless mode. The same
+ * interpreter, jailed to a real directory (symlink-safe), so `ls`/`grep`/
+ * `echo >` work on the actual files and a real `mv` between board columns IS
+ * a card move.
+ */
+export declare function createLocalShell(root: string, cwd?: string): LocalShell;
 export { SforaFs } from "./SforaFs.js";
+export { LocalWorkspace, initWorkspace, findWorkspace, WORKSPACE_DIR, type TaskEntry, type TaskWriteResult, } from "./local/workspace.js";
+export * from "./format/index.js";
 export { SforaApiClient, SforaApiError, type SforaApiConfig, type Project, type Entry, type PostKind, type WriteResult, } from "./api-client.js";

package/dist/index.js

@@ -7,13 +7,14 @@
  * workspace. The CLI also exposes first-class verbs (post/task/doc) and an MCP
  * server so agents operate sfora natively.
  */
-import { Bash } from "just-bash";
+import { Bash, ReadWriteFs } from "just-bash";
 import { SforaApiClient } from "./api-client.js";
 import { SforaFs } from "./SforaFs.js";
 export function createSforaShell(options) {
     const client = new SforaApiClient({
         baseUrl: options.baseUrl,
         apiKey: options.apiKey,
+        actAs: options.actAs,
     });
     const fs = new SforaFs(client);
     // Disable just-bash's in-process defense-in-depth sandbox. It defaults on and
@@ -24,5 +25,18 @@ export function createSforaShell(options) {
     const bash = new Bash({ fs, cwd: options.cwd ?? "/", defenseInDepth: false });
     return { bash, fs };
 }
+/**
+ * Shell over a local `.sfora/` workspace — the OSS serverless mode. The same
+ * interpreter, jailed to a real directory (symlink-safe), so `ls`/`grep`/
+ * `echo >` work on the actual files and a real `mv` between board columns IS
+ * a card move.
+ */
+export function createLocalShell(root, cwd = "/") {
+    const fs = new ReadWriteFs({ root });
+    const bash = new Bash({ fs, cwd, defenseInDepth: false });
+    return { bash, fs };
+}
 export { SforaFs } from "./SforaFs.js";
+export { LocalWorkspace, initWorkspace, findWorkspace, WORKSPACE_DIR, } from "./local/workspace.js";
+export * from "./format/index.js";
 export { SforaApiClient, SforaApiError, } from "./api-client.js";