sfora-cli 0.7.0 → 0.8.0

package/dist/local/workspace.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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";
+/**
+ * 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,250 @@
+/**
+ * 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";
+const DEFAULT_COLUMNS = ["01-todo", "02-in-progress", "03-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. Frontmatter: \`status\`, \`priority\`,
+  \`labels\`, \`assignees\`, \`due\`. Move a task by moving the file between column
+  directories (\`mv\` works).
+- \`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.
+`;
+/**
+ * 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 a
+     * done-ish column, otherwise the first column.
+     */
+    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;
+        }
+        return 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,31 @@
 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>/docs/<file>.md             docs / notes
+  - /projects/<slug>/pulls/<number>.md          pull requests (diff + linked work), read-only
   - /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'.
 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-col>/<NNNN>-<slug>.md   tasks (kanban cards), by column — 'mv' between column dirs moves a task
+  - /posts/<YYYY-MM-DD>-<slug>.md      posts
+  - /docs/<slug>.md                    docs / notes
+Examples: 'ls /board/01-todo', 'cat /board/01-todo/*.md', 'grep -ri TODO /', 'echo "# Fix login\\nstatus: active" > /board/01-todo/fix-login.md', 'mv /board/01-todo/0003-*.md /board/03-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 +42,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 +93,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.8.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",