sfora-cli 0.8.0 → 0.9.0

package/dist/cli.js

@@ -11,7 +11,7 @@ import { spawn } from "node:child_process";
 import { readFile as readLocalFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { createSforaShell, createLocalShell, SforaApiClient } from "./index.js";
-import { LocalWorkspace, initWorkspace, findWorkspace, } from "./local/workspace.js";
+import { LocalWorkspace, initWorkspace, findWorkspace, migrateWorkspaceStages, } from "./local/workspace.js";
 import { runMcpServer } from "./mcp-server.js";
 import { readConfig, writeConfig, resolveSettings, upsertProfile, effectiveProfiles, DEFAULT_URL, } from "./config.js";
 const colors = {
@@ -544,7 +544,8 @@ async function runVerb(args, fs, client) {
             .catch(() => []);
         if (cols.length === 0)
             throw new Error(`no board columns in ${project}`);
-        let col = cols[0];
+        // Default to "To do" (02-todo) — new work is up for grabs, not in triage.
+        let col = cols.find((c) => c.replace(/^\d+-/, "") === "todo") ?? cols[0];
         if (args.column) {
             const want = args.column
                 .toLowerCase()
@@ -560,6 +561,12 @@ async function runVerb(args, fs, client) {
 // ─── Local mode (a .sfora/ directory — no server, no account) ─────
 const LOCAL_ONLY_HINT = "cloud command — run it with --cloud (after `sfora login`), or outside the .sfora/ repo";
 async function runLocalVerb(args, root) {
+    // One Flow: silently reshape a legacy board onto the four fixed stage dirs on
+    // open (idempotent — a no-op once the board is canonical).
+    const reshaped = await migrateWorkspaceStages(root);
+    if (reshaped.migrated) {
+        console.error(`${colors.dim}· reshaped board to the four stages (triage · to do · in progress · done); moved ${reshaped.moved} task${reshaped.moved === 1 ? "" : "s"}${colors.reset}`);
+    }
     const ws = new LocalWorkspace(root);
     const { fs } = createLocalShell(root);
     const ok = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`);
@@ -644,15 +651,18 @@ Standard tools work on the real files:
   ls   cat   grep   find   head   tail   wc   sed   awk   echo   mv   cd   pwd
 
 ${colors.dim}Where things live${colors.reset}
-  /board/<column>/NNNN-<slug>.md   tasks — mv between columns moves a task
-  /posts/YYYY-MM-DD-<slug>.md      posts
-  /docs/<slug>.md                  docs
+  /board/<NN-stage>/NNNN-<slug>.md  tasks — four fixed columns: 01-triage /
+                                    02-todo / 03-in-progress / 04-done. mv
+                                    between them moves a task; mv into 04-done
+                                    marks it done.
+  /posts/YYYY-MM-DD-<slug>.md       posts
+  /docs/<slug>.md                   docs
 
 ${colors.dim}Try${colors.reset}
-  ls /board/01-todo
+  ls /board/02-todo
   grep -ri todo /board
-  echo "# Fix login" > /board/01-todo/fix-login.md
-  mv /board/01-todo/0003-*.md /board/03-done/
+  echo "# Fix login" > /board/02-todo/fix-login.md
+  mv /board/02-todo/0003-*.md /board/04-done/
 
 Everything is git-versioned with your repo. ${colors.dim}Connect a team later with${colors.reset} ${colors.cyan}sfora login${colors.reset}.
 Type ${colors.cyan}exit${colors.reset} to quit.

package/dist/format/cardMarkdown.d.ts

@@ -12,6 +12,8 @@ export interface MarkdownCardInput {
     lastActivityAt?: number;
     assignees?: string[];
     labels?: string[];
+    kind?: "question";
+    resolution?: string;
 }
 export interface MarkdownBoardRef {
     _id: string;

package/dist/format/cardMarkdown.js

@@ -65,7 +65,9 @@ export function cardToMarkdown(card, board, column, commentsCount) {
         ["boardId", board?._id ?? ""],
         ["column", column?.name ?? ""],
         ["columnId", column?._id ?? ""],
+        ["kind", card.kind], // undefined for ordinary tasks → skipped
         ["status", card.status],
+        ["resolution", card.resolution], // set once a question is decided
         ["priority", card.priority ?? "none"],
         ["assignees", card.assignees ?? []],
         ["labels", card.labels ?? []],

package/dist/local/workspace.d.ts

@@ -16,6 +16,18 @@
  */
 /** 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

package/dist/local/workspace.js

@@ -19,20 +19,111 @@ 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"];
+// 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. Frontmatter: \`status\`, \`priority\`,
-  \`labels\`, \`assignees\`, \`due\`. Move a task by moving the file between column
-  directories (\`mv\` works).
+- \`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
@@ -194,8 +285,8 @@ export class LocalWorkspace {
     // ─── 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.
+     * 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();
@@ -217,7 +308,9 @@ export class LocalWorkspace {
             if (done)
                 return done;
         }
-        return columns[0];
+        // 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;

package/dist/mcp-server.js

@@ -13,18 +13,21 @@ 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-col>/<NNNN>-<slug>.md   tasks (kanban cards), by column — 'mv' between column dirs moves a task
+  - /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
-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/'.
+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 } = options.localRoot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.8.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": [