sfora-cli 0.6.0 → 0.8.0

package/dist/config.d.ts

@@ -1,3 +1,8 @@
+export interface SforaProfile {
+    url: string;
+    org?: string;
+    apiKey?: string;
+}
 export interface SforaConfig {
     url?: string;
     apiKey?: string;
@@ -6,6 +11,8 @@ export interface SforaConfig {
         apiKey?: string;
         org?: string;
     }>;
+    profiles?: Record<string, SforaProfile>;
+    activeProfile?: string;
 }
 export declare const CONFIG_PATH: string;
 export declare const DEFAULT_URL = "https://www.sfora.ai";
@@ -16,6 +23,17 @@ export interface ResolvedSettings {
     apiKey: string | undefined;
     org: string | undefined;
 }
+export declare function normalizeHost(url: string): string;
+export declare function profileKey(url: string, org?: string): string;
+export declare function effectiveProfiles(cfg: SforaConfig): Record<string, SforaProfile>;
+export declare function upsertProfile(cfg: SforaConfig, identity: {
+    url: string;
+    org?: string;
+    apiKey: string;
+}): {
+    cfg: SforaConfig;
+    key: string;
+};
 export declare function resolveSettings(flags: {
     url?: string;
     apiKey?: string;

package/dist/config.js

@@ -2,6 +2,12 @@
  * Persisted CLI config at ~/.sfora/config.json so you don't pass
  * SFORA_API_KEY / SFORA_URL on every invocation. Resolution precedence:
  * explicit flags > environment > config file > built-in default.
+ *
+ * The file holds *profiles* — one `{ url, org, apiKey }` context per
+ * deployment+org — so a single config can carry a prod key AND a dev key at
+ * once. `sfora login` adds/updates a profile instead of overwriting one shared
+ * key, which is what used to silently invalidate the other deployment's key and
+ * force constant re-auth.
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -32,21 +38,107 @@ export async function writeConfig(cfg) {
 function pick(...vals) {
     return vals.find((v) => v != null && v !== "");
 }
+// Bare host, lowercased, for comparing/keying deployments regardless of scheme
+// or trailing slash.
+export function normalizeHost(url) {
+    try {
+        return new URL(url).host.toLowerCase();
+    }
+    catch {
+        return url
+            .replace(/^https?:\/\//, "")
+            .replace(/\/+$/, "")
+            .toLowerCase();
+    }
+}
+function sameHost(a, b) {
+    return !!a && !!b && normalizeHost(a) === normalizeHost(b);
+}
+// Stable, human-ish profile name: `host/org` (or just `host` when org-less).
+export function profileKey(url, org) {
+    const host = normalizeHost(url);
+    return org ? `${host}/${org}` : host;
+}
+// All contexts as a map, folding a legacy top-level identity into a synthesized
+// profile so resolution can treat everything uniformly.
+export function effectiveProfiles(cfg) {
+    const out = { ...(cfg.profiles ?? {}) };
+    if (cfg.apiKey) {
+        const url = cfg.url ?? DEFAULT_URL;
+        const key = profileKey(url, cfg.org);
+        if (!out[key])
+            out[key] = { url, org: cfg.org, apiKey: cfg.apiKey };
+    }
+    return out;
+}
+// Add (or replace) a profile for an identity and make it active. Also mirrors
+// the identity onto the legacy top-level fields for back-compat. Returns the
+// next config plus the profile key it was saved under.
+export function upsertProfile(cfg, identity) {
+    const key = profileKey(identity.url, identity.org);
+    // Seed from effectiveProfiles (not raw cfg.profiles) so a first login keeps
+    // any pre-existing legacy top-level identity as its own profile instead of
+    // overwriting it.
+    const profiles = { ...effectiveProfiles(cfg) };
+    profiles[key] = {
+        url: identity.url,
+        org: identity.org,
+        apiKey: identity.apiKey,
+    };
+    const next = {
+        ...cfg,
+        profiles,
+        activeProfile: key,
+        url: identity.url,
+        apiKey: identity.apiKey,
+        org: identity.org ?? cfg.org,
+    };
+    return { cfg: next, key };
+}
 export function resolveSettings(flags, cfg) {
-    const url = pick(flags.url, process.env.SFORA_URL, cfg.url) ?? DEFAULT_URL;
+    // Explicit intent (may be undefined). Used both to override fields and to
+    // select which stored profile to act as.
+    const wantUrl = pick(flags.url, process.env.SFORA_URL);
+    const wantOrg = pick(flags.org, process.env.SFORA_ORG);
     // `--bot <name>`: act as that saved bot. Don't fall back to the user's key /
     // SFORA_API_KEY env, so the identity is never silently the wrong one.
     if (flags.bot) {
         const bot = cfg.bots?.[flags.bot];
         return {
-            url,
+            url: pick(wantUrl, cfg.url) ?? DEFAULT_URL,
             apiKey: pick(flags.apiKey, bot?.apiKey),
             org: pick(flags.org, bot?.org, cfg.org),
         };
     }
+    // Pick the profile that best matches explicit intent, falling back to the
+    // active profile (last login), then the sole profile if there's only one.
+    const profiles = effectiveProfiles(cfg);
+    const list = Object.values(profiles);
+    let prof;
+    if (wantUrl && wantOrg)
+        prof = list.find((p) => sameHost(p.url, wantUrl) && p.org === wantOrg);
+    if (!prof && wantUrl)
+        prof = list.find((p) => sameHost(p.url, wantUrl));
+    if (!prof && wantOrg)
+        prof = list.find((p) => p.org === wantOrg);
+    // Convenience fallbacks (active profile, then the sole profile) apply ONLY
+    // when no explicit target was given. If the user named a url/org that matches
+    // nothing, prof stays undefined so we never substitute a different
+    // deployment's key.
+    if (!prof && !wantUrl && !wantOrg) {
+        if (cfg.activeProfile)
+            prof = profiles[cfg.activeProfile];
+        if (!prof && list.length === 1)
+            prof = list[0];
+    }
+    // Note: the legacy top-level identity is already folded into `profiles` by
+    // effectiveProfiles, so we deliberately do NOT fall back to cfg.apiKey here.
+    // If explicit url/org intent matches no profile, apiKey stays undefined and
+    // the CLI asks you to log in — rather than silently sending one deployment's
+    // key to another (the old "Invalid API key" trap).
     return {
-        url,
-        apiKey: pick(flags.apiKey, process.env.SFORA_API_KEY, cfg.apiKey),
-        org: pick(flags.org, process.env.SFORA_ORG, cfg.org),
+        url: pick(flags.url, process.env.SFORA_URL, prof?.url) ?? DEFAULT_URL,
+        apiKey: pick(flags.apiKey, process.env.SFORA_API_KEY, prof?.apiKey),
+        org: pick(flags.org, process.env.SFORA_ORG, prof?.org),
     };
 }

package/dist/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config.test.js

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { resolveSettings, upsertProfile, effectiveProfiles, profileKey, DEFAULT_URL, } from "./config.js";
+const DEV_URL = "https://valuable-llama-777.eu-west-1.convex.site";
+// resolveSettings reads SFORA_* env as a fallback — clear them so tests assert
+// the config/flag behavior in isolation.
+beforeEach(() => {
+    delete process.env.SFORA_URL;
+    delete process.env.SFORA_ORG;
+    delete process.env.SFORA_API_KEY;
+});
+describe("legacy migration", () => {
+    it("folds a legacy top-level identity into a profile", () => {
+        const cfg = {
+            url: DEFAULT_URL,
+            org: "wavyr",
+            apiKey: "sfora_ak_prod",
+        };
+        const profiles = effectiveProfiles(cfg);
+        expect(profiles[profileKey(DEFAULT_URL, "wavyr")]).toEqual({
+            url: DEFAULT_URL,
+            org: "wavyr",
+            apiKey: "sfora_ak_prod",
+        });
+    });
+    it("resolves the sole legacy identity with no flags", () => {
+        const cfg = {
+            url: DEFAULT_URL,
+            org: "wavyr",
+            apiKey: "sfora_ak_prod",
+        };
+        expect(resolveSettings({}, cfg)).toEqual({
+            url: DEFAULT_URL,
+            org: "wavyr",
+            apiKey: "sfora_ak_prod",
+        });
+    });
+});
+describe("no cross-deployment key reuse", () => {
+    it("does NOT send the prod key to an unmatched dev target", () => {
+        const cfg = {
+            url: DEFAULT_URL,
+            org: "wavyr",
+            apiKey: "sfora_ak_prod",
+        };
+        const r = resolveSettings({ url: DEV_URL, org: "test" }, cfg);
+        expect(r.url).toBe(DEV_URL);
+        expect(r.org).toBe("test");
+        // The whole point: no key rather than the wrong key.
+        expect(r.apiKey).toBeUndefined();
+    });
+});
+describe("profiles coexist (the fix)", () => {
+    it("login to dev does not clobber the prod key; each resolves by intent", () => {
+        let cfg = {
+            url: DEFAULT_URL,
+            org: "wavyr",
+            apiKey: "sfora_ak_prod",
+        };
+        // Simulate `sfora login` against dev.
+        cfg = upsertProfile(cfg, {
+            url: DEV_URL,
+            org: "test",
+            apiKey: "sfora_ak_dev",
+        }).cfg;
+        // Both keys are retained.
+        const profiles = effectiveProfiles(cfg);
+        expect(Object.keys(profiles)).toHaveLength(2);
+        // Prod still reachable by intent.
+        expect(resolveSettings({ org: "wavyr" }, cfg).apiKey).toBe("sfora_ak_prod");
+        expect(resolveSettings({ url: DEFAULT_URL }, cfg).apiKey).toBe("sfora_ak_prod");
+        // Dev reachable by intent.
+        expect(resolveSettings({ org: "test" }, cfg).apiKey).toBe("sfora_ak_dev");
+        // No intent → the last login (active profile) wins.
+        expect(resolveSettings({}, cfg)).toEqual({
+            url: DEV_URL,
+            org: "test",
+            apiKey: "sfora_ak_dev",
+        });
+    });
+});
+describe("bot identity", () => {
+    it("uses the named bot's key and never the personal fallback", () => {
+        const cfg = {
+            url: DEFAULT_URL,
+            org: "wavyr",
+            apiKey: "sfora_ak_prod",
+            bots: { ci: { apiKey: "sfora_ak_ci", org: "wavyr" } },
+        };
+        const r = resolveSettings({ bot: "ci" }, cfg);
+        expect(r.apiKey).toBe("sfora_ak_ci");
+        const missing = resolveSettings({ bot: "nope" }, cfg);
+        expect(missing.apiKey).toBeUndefined();
+    });
+});

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;
+}