sfora-cli 0.7.0 → 0.9.0

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";

package/dist/local/workspace.d.ts

@@ -0,0 +1,80 @@
+/**
+ * LocalWorkspace — the OSS local mode. A `.sfora/` directory in your repo is
+ * the workspace: tasks, posts, and docs are plain markdown files on disk, in
+ * exactly the same format the cloud serves over /v1/fs (shared `../format`
+ * core), so `cp` is a migration.
+ *
+ *   .sfora/
+ *     board/01-todo/0001-fix-login.md   tasks — NNNN-<slug>.md per column dir
+ *     posts/2026-07-02-standup.md       posts — YYYY-MM-DD-<slug>.md
+ *     docs/architecture.md              docs  — <slug>.md
+ *
+ * This module owns the *semantics* (scaffolding, card numbering, canonical
+ * filenames, listings). The interactive shell needs no virtualization locally —
+ * just-bash's ReadWriteFs jails a real directory, and real `mv` between column
+ * dirs IS a card move.
+ */
+/** Directory name that marks a local sfora workspace. */
+export declare const WORKSPACE_DIR = ".sfora";
+/**
+ * Migrate an existing workspace's board onto the four fixed stage dirs (One
+ * Flow). Idempotent: a board already in the canonical shape is left untouched.
+ * Legacy columns are mapped by name (done→done, in progress→doing, triage/
+ * undecided/…→triage, else todo); each card file MOVES into its stage dir, and
+ * a card leaving an unrecognized column keeps that column's name as a label so
+ * nothing is lost. Called on open so old \`.sfora/\` dirs reshape silently.
+ */
+export declare function migrateWorkspaceStages(root: string): Promise<{
+    migrated: boolean;
+    moved: number;
+}>;
+/**
+ * Walk up from `cwd` looking for a `.sfora/` workspace. A directory only
+ * counts when it has workspace markers (board/posts/docs) — `~/.sfora` is also
+ * the CLI's config directory (config.json), and a bare config dir must never
+ * be mistaken for a workspace.
+ */
+export declare function findWorkspace(cwd: string): Promise<string | undefined>;
+/** Scaffold `.sfora/` under `dir` (idempotent). Returns the workspace root. */
+export declare function initWorkspace(dir: string): Promise<string>;
+export interface TaskWriteResult {
+    filename: string;
+    column: string;
+    number: number;
+}
+export interface TaskEntry {
+    filename: string;
+    column: string;
+    number: number | undefined;
+    title: string;
+    status: string;
+}
+export declare class LocalWorkspace {
+    #private;
+    /** Absolute path of the `.sfora` directory. */
+    readonly root: string;
+    constructor(root: string);
+    listColumns(): Promise<string[]>;
+    listTasks(column?: string): Promise<TaskEntry[]>;
+    /**
+     * Create (or, when frontmatter `number:` matches an existing card, update)
+     * a task from raw markdown. Mirrors the server's PUT semantics: title
+     * required, canonical `NNNN-<slug>.md` filename, next number assigned by
+     * scanning the board. The markdown is written verbatim — files are storage.
+     */
+    writeTask(markdown: string, opts?: {
+        column?: string;
+    }): Promise<TaskWriteResult>;
+    writePost(markdown: string, opts?: {
+        draft?: boolean;
+    }): Promise<{
+        filename: string;
+    }>;
+    writeDoc(markdown: string): Promise<{
+        filename: string;
+    }>;
+    listPosts(kind?: "posts" | "drafts"): Promise<string[]>;
+    listDocs(): Promise<string[]>;
+    /** Filename-level scan (no file reads) — enough for numbering. */
+    private listTasksShallow;
+}

package/dist/local/workspace.js

@@ -0,0 +1,343 @@
+/**
+ * LocalWorkspace — the OSS local mode. A `.sfora/` directory in your repo is
+ * the workspace: tasks, posts, and docs are plain markdown files on disk, in
+ * exactly the same format the cloud serves over /v1/fs (shared `../format`
+ * core), so `cp` is a migration.
+ *
+ *   .sfora/
+ *     board/01-todo/0001-fix-login.md   tasks — NNNN-<slug>.md per column dir
+ *     posts/2026-07-02-standup.md       posts — YYYY-MM-DD-<slug>.md
+ *     docs/architecture.md              docs  — <slug>.md
+ *
+ * This module owns the *semantics* (scaffolding, card numbering, canonical
+ * filenames, listings). The interactive shell needs no virtualization locally —
+ * just-bash's ReadWriteFs jails a real directory, and real `mv` between column
+ * dirs IS a card move.
+ */
+import { mkdir, readdir, readFile, writeFile, rm, stat } from "node:fs/promises";
+import { join, dirname, resolve } from "node:path";
+import { parseMarkdownCard, cardFilename, numberFromFilename, columnSlugFromDirname, parseMarkdownPost, parseMarkdownNote, noteFilename, slugify, } from "../format/index.js";
+/** Directory name that marks a local sfora workspace. */
+export const WORKSPACE_DIR = ".sfora";
+// One Flow: every board is the same four fixed stage columns, matching the cloud
+// byte-for-byte, so `cp` stays a migration. There is no column management.
+const DEFAULT_COLUMNS = [
+    "01-triage",
+    "02-todo",
+    "03-in-progress",
+    "04-done",
+];
+// Map a legacy column slug → its stage dir. Mirrors the server's migrateStages
+// name-mapping; anything unrecognized falls to "02-todo" (with the old name kept
+// as a label so the lane isn't lost).
+const STAGE_DIR_BY_SLUG = {
+    triage: "01-triage",
+    undecided: "01-triage",
+    someday: "01-triage",
+    icebox: "01-triage",
+    todo: "02-todo",
+    "to-do": "02-todo",
+    "in-progress": "03-in-progress",
+    doing: "03-in-progress",
+    wip: "03-in-progress",
+    working: "03-in-progress",
+    done: "04-done",
+    complete: "04-done",
+    completed: "04-done",
+    shipped: "04-done",
+};
+const WORKSPACE_README = `# sfora workspace
+
+Everything here is a plain markdown file — edit with any tool, version with git.
+
+- \`board/<column>/NNNN-<slug>.md\` — tasks. Every board is the same four fixed
+  columns — \`01-triage / 02-todo / 03-in-progress / 04-done\`. Move a task by
+  moving the file between column dirs (\`mv\` works); moving into \`04-done\`
+  marks it done. Frontmatter: \`status\`, \`priority\`, \`labels\`, \`assignees\`, \`due\`.
+- \`posts/YYYY-MM-DD-<slug>.md\` — posts. An H1 (\`# Title\`) is the title.
+- \`docs/<slug>.md\` — docs.
+
+Create files by hand, or use the CLI: \`sfora task plan.md\`, \`sfora post note.md\`.
+Same format as sfora cloud — \`sfora login\` connects this workspace to a team.
+`;
+// Surgically add a label to a card's YAML frontmatter without reformatting the
+// rest of the file (local files are hand-edited; we don't round-trip them).
+function addLabelToCard(md, label) {
+    const fm = /^---\n([\s\S]*?)\n---\n?/.exec(md);
+    if (!fm)
+        return `---\nlabels: [${label}]\n---\n\n${md}`;
+    const block = fm[1];
+    const labelLine = /^labels:\s*\[(.*)\]\s*$/m.exec(block);
+    if (labelLine) {
+        const items = labelLine[1]
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (items.includes(label))
+            return md;
+        const replaced = block.replace(labelLine[0], `labels: [${[...items, label].join(", ")}]`);
+        return md.replace(block, replaced);
+    }
+    return md.replace(block, `${block}\nlabels: [${label}]`);
+}
+/**
+ * Migrate an existing workspace's board onto the four fixed stage dirs (One
+ * Flow). Idempotent: a board already in the canonical shape is left untouched.
+ * Legacy columns are mapped by name (done→done, in progress→doing, triage/
+ * undecided/…→triage, else todo); each card file MOVES into its stage dir, and
+ * a card leaving an unrecognized column keeps that column's name as a label so
+ * nothing is lost. Called on open so old \`.sfora/\` dirs reshape silently.
+ */
+export async function migrateWorkspaceStages(root) {
+    const boardDir = join(root, "board");
+    const entries = await readdir(boardDir, { withFileTypes: true }).catch(() => []);
+    const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    if (dirs.length === 0)
+        return { migrated: false, moved: 0 };
+    const isCanonical = dirs.length === DEFAULT_COLUMNS.length &&
+        DEFAULT_COLUMNS.every((d) => dirs.includes(d));
+    if (isCanonical)
+        return { migrated: false, moved: 0 };
+    for (const d of DEFAULT_COLUMNS) {
+        await mkdir(join(boardDir, d), { recursive: true });
+    }
+    let moved = 0;
+    for (const oldDir of dirs) {
+        if (DEFAULT_COLUMNS.includes(oldDir))
+            continue; // canonical dir stays put
+        const slug = columnSlugFromDirname(oldDir);
+        const canonical = STAGE_DIR_BY_SLUG[slug];
+        const target = canonical ?? "02-todo";
+        const files = await readdir(join(boardDir, oldDir)).catch(() => []);
+        for (const f of files) {
+            if (!f.endsWith(".md"))
+                continue;
+            const src = join(boardDir, oldDir, f);
+            let md = await readFile(src, "utf8");
+            if (!canonical)
+                md = addLabelToCard(md, slug); // preserve the old lane
+            await writeFile(join(boardDir, target, f), md, "utf8");
+            await rm(src);
+            moved++;
+        }
+        await rm(join(boardDir, oldDir), { recursive: true, force: true }).catch(() => { });
+    }
+    return { migrated: true, moved };
+}
+/**
+ * Walk up from `cwd` looking for a `.sfora/` workspace. A directory only
+ * counts when it has workspace markers (board/posts/docs) — `~/.sfora` is also
+ * the CLI's config directory (config.json), and a bare config dir must never
+ * be mistaken for a workspace.
+ */
+export async function findWorkspace(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const candidate = join(dir, WORKSPACE_DIR);
+        if (await isWorkspace(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+async function isWorkspace(candidate) {
+    try {
+        if (!(await stat(candidate)).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    for (const marker of ["board", "posts", "docs"]) {
+        try {
+            if ((await stat(join(candidate, marker))).isDirectory())
+                return true;
+        }
+        catch {
+            // try the next marker
+        }
+    }
+    return false;
+}
+/** Scaffold `.sfora/` under `dir` (idempotent). Returns the workspace root. */
+export async function initWorkspace(dir) {
+    const root = join(resolve(dir), WORKSPACE_DIR);
+    for (const col of DEFAULT_COLUMNS) {
+        await mkdir(join(root, "board", col), { recursive: true });
+    }
+    await mkdir(join(root, "posts"), { recursive: true });
+    await mkdir(join(root, "docs"), { recursive: true });
+    const readmePath = join(root, "README.md");
+    try {
+        await stat(readmePath);
+    }
+    catch {
+        await writeFile(readmePath, WORKSPACE_README, "utf8");
+    }
+    return root;
+}
+export class LocalWorkspace {
+    /** Absolute path of the `.sfora` directory. */
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    // ─── Board ───────────────────────────────────────────────────────
+    async listColumns() {
+        const entries = await readdir(join(this.root, "board"), {
+            withFileTypes: true,
+        }).catch(() => []);
+        return entries
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    async listTasks(column) {
+        const columns = column
+            ? [await this.#resolveColumn(column)]
+            : await this.listColumns();
+        const out = [];
+        for (const col of columns) {
+            const dir = join(this.root, "board", col);
+            const files = (await readdir(dir).catch(() => [])).filter((f) => f.endsWith(".md"));
+            for (const filename of files.sort()) {
+                const md = await readFile(join(dir, filename), "utf8");
+                const parsed = parseMarkdownCard(md);
+                const status = parsed.frontmatter.status;
+                out.push({
+                    filename,
+                    column: col,
+                    number: numberFromFilename(filename),
+                    title: parsed.title || filename.replace(/\.md$/, ""),
+                    status: typeof status === "string" ? status : "active",
+                });
+            }
+        }
+        return out;
+    }
+    /**
+     * Create (or, when frontmatter `number:` matches an existing card, update)
+     * a task from raw markdown. Mirrors the server's PUT semantics: title
+     * required, canonical `NNNN-<slug>.md` filename, next number assigned by
+     * scanning the board. The markdown is written verbatim — files are storage.
+     */
+    async writeTask(markdown, opts = {}) {
+        const parsed = parseMarkdownCard(markdown);
+        if (!parsed.title.trim()) {
+            throw new Error("Title is required — add an H1 (`# Title`) or a frontmatter `title:`");
+        }
+        const fmColumn = typeof parsed.frontmatter.column === "string"
+            ? parsed.frontmatter.column
+            : undefined;
+        const fmStatus = typeof parsed.frontmatter.status === "string"
+            ? parsed.frontmatter.status
+            : undefined;
+        const column = await this.#resolveColumn(opts.column ?? fmColumn, fmStatus);
+        // Existing card (by explicit frontmatter number) → replace in place,
+        // wherever it currently lives (the new write may also move it).
+        const fmNumber = typeof parsed.frontmatter.number === "string"
+            ? Number.parseInt(parsed.frontmatter.number, 10)
+            : undefined;
+        const existing = fmNumber !== undefined && Number.isFinite(fmNumber)
+            ? await this.#findByNumber(fmNumber)
+            : undefined;
+        if (existing) {
+            await rm(join(this.root, "board", existing.column, existing.filename));
+        }
+        const number = existing?.number ?? (await this.#nextNumber());
+        const filename = cardFilename({ number, title: parsed.title });
+        await writeFile(join(this.root, "board", column, filename), markdown, "utf8");
+        return { filename, column, number };
+    }
+    // ─── Posts & docs ────────────────────────────────────────────────
+    async writePost(markdown, opts = {}) {
+        const parsed = parseMarkdownPost(markdown);
+        if (!parsed.title.trim()) {
+            throw new Error("Title is required — add an H1 (`# Title`) or a frontmatter `title:`");
+        }
+        const date = new Date().toISOString().slice(0, 10);
+        const filename = `${date}-${slugify(parsed.title)}.md`;
+        const dir = opts.draft ? "drafts" : "posts";
+        await mkdir(join(this.root, dir), { recursive: true });
+        await writeFile(join(this.root, dir, filename), markdown, "utf8");
+        return { filename };
+    }
+    async writeDoc(markdown) {
+        const parsed = parseMarkdownNote(markdown);
+        if (!parsed.title.trim()) {
+            throw new Error("Title is required — add an H1 (`# Title`) or a frontmatter `title:`");
+        }
+        const filename = noteFilename({ title: parsed.title });
+        await mkdir(join(this.root, "docs"), { recursive: true });
+        await writeFile(join(this.root, "docs", filename), markdown, "utf8");
+        return { filename };
+    }
+    async listPosts(kind = "posts") {
+        const files = await readdir(join(this.root, kind)).catch(() => []);
+        return files.filter((f) => f.endsWith(".md")).sort();
+    }
+    async listDocs() {
+        const files = await readdir(join(this.root, "docs")).catch(() => []);
+        return files.filter((f) => f.endsWith(".md")).sort();
+    }
+    // ─── Internals ───────────────────────────────────────────────────
+    /**
+     * Resolve a column reference (slug or name, e.g. "todo" / "In progress") to
+     * an existing column dirname. With no reference: a closed status prefers the
+     * done column, otherwise "To do" (new work is up for grabs, not in triage).
+     */
+    async #resolveColumn(ref, status) {
+        const columns = await this.listColumns();
+        if (columns.length === 0) {
+            throw new Error(`no board columns — run \`sfora init --local\` first`);
+        }
+        if (ref) {
+            const want = slugify(ref);
+            const hit = columns.find((c) => columnSlugFromDirname(c) === want);
+            if (!hit) {
+                throw new Error(`unknown column '${ref}' (have: ${columns
+                    .map(columnSlugFromDirname)
+                    .join(", ")})`);
+            }
+            return hit;
+        }
+        if (status === "closed") {
+            const done = columns.find((c) => /done|closed|complete/.test(columnSlugFromDirname(c)));
+            if (done)
+                return done;
+        }
+        // Default target is "To do" (02-todo), not the leading triage column.
+        const todo = columns.find((c) => columnSlugFromDirname(c) === "todo");
+        return todo ?? columns[0];
+    }
+    async #nextNumber() {
+        let max = 0;
+        for (const t of await this.listTasksShallow()) {
+            if (t.number !== undefined && t.number > max)
+                max = t.number;
+        }
+        return max + 1;
+    }
+    async #findByNumber(number) {
+        for (const t of await this.listTasksShallow()) {
+            if (t.number === number)
+                return { ...t, number };
+        }
+        return undefined;
+    }
+    /** Filename-level scan (no file reads) — enough for numbering. */
+    async listTasksShallow() {
+        const out = [];
+        for (const col of await this.listColumns()) {
+            const files = await readdir(join(this.root, "board", col)).catch(() => []);
+            for (const filename of files) {
+                if (!filename.endsWith(".md"))
+                    continue;
+                out.push({ column: col, filename, number: numberFromFilename(filename) });
+            }
+        }
+        return out;
+    }
+}

package/dist/mcp-server.d.ts

@@ -10,5 +10,7 @@ export interface RunMcpServerOptions {
     baseUrl: string;
     apiKey: string;
     org: string;
+    /** Absolute path of a local `.sfora/` workspace — serves it instead of the cloud. */
+    localRoot?: string;
 }
 export declare function runMcpServer(options: RunMcpServerOptions): Promise<void>;

package/dist/mcp-server.js

@@ -9,22 +9,34 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { createSforaShell } from "./index.js";
+import { createSforaShell, createLocalShell } from "./index.js";
 const TOOL_DESCRIPTION = `Run a bash command against the sfora workspace — a Unix-style view where every post, task, and doc is a markdown file:
   - /projects/<slug>/posts/<file>.md            published posts
   - /projects/<slug>/drafts/<file>.md           your drafts
-  - /projects/<slug>/board/<NN-col>/<NNNN>.md   tasks (kanban cards), by column
+  - /projects/<slug>/board/<NN-stage>/<NNNN>.md tasks (kanban cards), by stage
   - /projects/<slug>/docs/<file>.md             docs / notes
+  - /projects/<slug>/pulls/<number>.md          pull requests (diff + linked work), read-only
+  - /projects/<slug>/plan.md                    the goal + open questions
   - /inbox/mentions.md                          unread mentions
   - /me/api-key                                 your identity
-Examples: 'ls /projects', 'cat /projects/web/board/01-todo/*.md', 'grep -ri TODO /projects', 'echo "# Fix login\\nstatus: active" > /projects/web/board/01-todo/fix.md'.
+Every board is the same four fixed columns — 01-triage / 02-todo / 03-in-progress / 04-done. There is no column management; move a card into 04-done to close it. Question cards (kind: question) map their stage to the plan: triage = fuzzy, todo = up for grabs, in-progress = claimed, done = decided.
+Examples: 'ls /projects', 'cat /projects/web/board/02-todo/*.md', 'grep -ri TODO /projects', 'echo "# Fix login\\nstatus: active" > /projects/web/board/02-todo/fix.md', 'mv /projects/web/board/02-todo/0003-*.md /projects/web/board/04-done/'.
 Write a file to create or update the entity (frontmatter sets fields like status/priority/assignees/due). cwd and environment persist across calls.`;
+const LOCAL_TOOL_DESCRIPTION = `Run a bash command against the local sfora workspace (a .sfora/ directory of plain markdown files, git-versioned with the repo):
+  - /board/<NN-stage>/<NNNN>-<slug>.md tasks (kanban cards), by stage — 'mv' between stage dirs moves a task
+  - /posts/<YYYY-MM-DD>-<slug>.md      posts
+  - /docs/<slug>.md                    docs / notes
+Every board is the same four fixed columns — 01-triage / 02-todo / 03-in-progress / 04-done. There is no column management; moving a card into 04-done marks it done.
+Examples: 'ls /board/02-todo', 'cat /board/02-todo/*.md', 'grep -ri TODO /', 'echo "# Fix login\\nstatus: active" > /board/02-todo/fix-login.md', 'mv /board/02-todo/0003-*.md /board/04-done/'.
+Frontmatter sets task fields (status/priority/labels/assignees/due). cwd and environment persist across calls.`;
 export async function runMcpServer(options) {
-    const { bash } = createSforaShell({
-        baseUrl: options.baseUrl,
-        apiKey: options.apiKey,
-        org: options.org,
-    });
+    const { bash } = options.localRoot
+        ? createLocalShell(options.localRoot)
+        : createSforaShell({
+            baseUrl: options.baseUrl,
+            apiKey: options.apiKey,
+            org: options.org,
+        });
     // Persistent shell state across tool calls.
     let cwd = "/";
     let env;
@@ -33,7 +45,7 @@ export async function runMcpServer(options) {
         tools: [
             {
                 name: "bash",
-                description: TOOL_DESCRIPTION,
+                description: options.localRoot ? LOCAL_TOOL_DESCRIPTION : TOOL_DESCRIPTION,
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -84,5 +96,7 @@ export async function runMcpServer(options) {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`sfora MCP server ready (org: ${options.org || "—"}, ${options.baseUrl})\n`);
+    process.stderr.write(options.localRoot
+        ? `sfora MCP server ready (local workspace: ${options.localRoot})\n`
+        : `sfora MCP server ready (org: ${options.org || "—"}, ${options.baseUrl})\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Your sfora workspace as a markdown filesystem — a CLI + MCP server. Post/task/doc, ls/cat/grep, and a shell so agents operate sfora natively.",
   "keywords": [
@@ -24,7 +24,7 @@
     "url": "https://github.com/wavyrai/sfora/issues"
   },
   "bin": {
-    "sfora": "./dist/cli.js"
+    "sfora": "dist/cli.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",