sfora-cli 0.6.0 → 0.8.0

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

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.6.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",