spectoflow 0.21.0 → 0.22.0

package/README.md

@@ -16,6 +16,10 @@
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/georgesmomo/spectoflow/main/docs/screenshot-board.png" alt="spectoflow dashboard — Board overview" width="880">
+</p>
+
 An **agent-agnostic** spec-driven development framework with a **real-time local control plane**.
 You speak in plain language; the framework classifies your intent and runs the right workflow. No
 ceremonial command to start.
@@ -30,6 +34,8 @@ silently activating something that isn't there.
 > (Claude Code, Copilot CLI, …). spectoflow's own **team personas** (developer, qa-engineer, …) are a
 > different, unrelated use of "agent" — see [Agents vs skills](#agents-vs-skills) further down.
 
+## Supported coding agents
+
 | Coding agent | Headless run | Docs |
 |---|---|---|
 | Claude Code | ✓ | [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference) |
@@ -101,8 +107,8 @@ spectoflow --help      (-h)                    show help   (append -h to any com
   `.claude/commands/spectoflow.md`.
 - `.spectoflow/runtime.json` is gitignored (volatile execution state).
 
-`init` **auto-detects your installed agent(s)** (probes PATH for `claude`, `codex`, `cursor-agent`,
-`gemini`, and existing `.claude`/`.codex`/… dirs): it writes shims for each, sets the active agent in
+`init` **auto-detects your installed agent(s)** (probes PATH for each of the 13 supported CLIs above,
+and existing `.claude`/`.codex`/… dirs): it writes shims for each, sets the active agent in
 `config.json`, and seeds the runner commands. Override with `--agent=claude,codex`; if nothing is
 detected it falls back to claude + codex.
 
@@ -166,56 +172,72 @@ spectoflow dashboard                     # → http://localhost:4319 (or --port=
 
 `spectoflow dashboard` is the simple way — it prints the URL and won't double-start (it detects a
 dashboard already running on the port). `spectoflow status` tells you whether one is up. Running the
-`server.js` directly still works for a manual/embedded setup. Zero dependencies, updates live via SSE +
-file watching. Ten tabs behind a dense icon-tab header (brand logo · subtitle · **active agent** ·
-autonomy mode · language · a slim global-progress meter · a sync dot · a **Run** quick-action): **Board**
-(the control-room Overview — compact KPI cards, a status donut, a **scope-vs-delivered area curve**, a
-workflow-at-a-glance strip, per-phase progress bars, filter chips + search — plus the phase board),
-**Chat** (a full-height group-chat panel with **Summarize**/**Clear**), **Requests** (tasks awaiting
-you — `to_validate`/`to_analyze`), **Attention** (points the agent raised via a `::spectoflow attention
-msg=…` sentinel or that you noted — edit/resolve/delete, or **validate → task**), **Backlog** (a flat
-sortable/filterable, paginated table of every task, defaulting to open work), **Workflow** (the
-pipeline as step cards — click one to enable/disable it, which edits `workflow.md`), **Agents &
-Skills** (enriched cards that open a full-body markdown drawer), **Info** (a project-at-a-glance
-summary), **Documentation** (the supported-agents table above, live with your own install status and
-links, plus the CLI command reference), and **Personalize** (autonomy mode, language, design, the
-active agent, and **Extend spectoflow** — described under *Customize* below). URLs are real routes
-(`/board`, `/backlog/T-012`, …). Charts are zero-dep, hand-rolled SVG in `dashboard/public/charts.js`
-(donut/area/bars/ring, animated, `prefers-reduced-motion`-aware), and every aggregate is computed
-client-side.
-
-**Designs & theme.** The dashboard ships **switchable designs** (Settings → *Dashboard design*):
-**Control Room** (violet), **Obsidian Ops** (near-black lime/cyan, mono), **Neon Command**
-(glassmorphism aurora), and **Mission Control** (indigo control panel). Each works in light and dark
-(the moon toggle). A design is a `data-design`
-skin — a scoped CSS token block plus a one-line entry in `dashboard/public/designs.js`, so adding one
-is trivial. Fonts are **self-hosted** (`dashboard/public/fonts/*.woff2`), keeping the dashboard fully
-offline and dependency-free. Your choice persists per viewer (localStorage) and as the project
-default (`config.design`).
-
-A floating **💬 chat widget** (bottom-right, redesigned) and the **Chat** tab render the same
-`runtime.messages` log via a shared `renderChatLog()`, so they never drift. A running agent identifies
-itself by printing `::spectoflow role=… kind=… msg=…` sentinels, which become labelled messages
-(analyst / developer / qa …); other output streams raw. The board refreshes live as it edits plans.
-Either surface can also **Orchestrate** the enabled workflow: each step runs its agent, gated by mode
-+ policy. The Chat tab can also **Summarize** the recent log into one digest (via the active agent)
-or **Clear** it outright, when it's grown long. The Agents & Skills drawer is served by the one
-read-only endpoint, `GET /api/agentfile?path=` (scoped to `.spectoflow/agents/**` +
-`.spectoflow/skills/**`, path-traversal-safe) — the framework's only other server surface is
-unchanged.
-
-**Customize.** Personalize → **Extend spectoflow** lets you extend the project's own spectoflow
-install: add a
+`server.js` directly still works for a manual/embedded setup. Zero dependencies, updates live via SSE
++ file watching.
+
+The header bar always shows the brand, the **active agent**, autonomy mode, language, a global-progress
+meter, a sync dot, and a **Run** quick-action. Ten tabs:
+
+- **Board** — the control-room Overview (compact KPI cards, a status donut, a **scope-vs-delivered
+  area curve**, a workflow-at-a-glance strip, per-phase progress bars, filter chips + search) plus the
+  phase board.
+- **Chat** — a full-height group-chat panel with **Summarize** / **Clear**.
+- **Requests** — tasks awaiting you (`to_validate` / `to_analyze`).
+- **Attention** — points the agent raised (a `::spectoflow attention msg=…` sentinel) or that you
+  noted yourself — edit / resolve / delete, or **validate → task**.
+- **Backlog** — a flat sortable/filterable, paginated table of every task, defaulting to open work.
+- **Workflow** — the pipeline as step cards; click one to enable/disable it, which edits `workflow.md`.
+- **Agents & Skills** — enriched cards that open a full-body markdown drawer.
+- **Info** — a project-at-a-glance summary.
+- **Documentation** — the live supported-agents table (your own install status + links) plus the CLI
+  command reference.
+- **Personalize** — autonomy mode, language, design, the active agent, and **Extend spectoflow** (see
+  *Customize* below).
+
+URLs are real routes (`/board`, `/backlog/T-012`, …). Charts are zero-dep, hand-rolled SVG in
+`dashboard/public/charts.js` (donut/area/bars/ring, animated, `prefers-reduced-motion`-aware), and
+every aggregate is computed client-side.
+
+### Designs & theme
+
+The dashboard ships **switchable designs** (Personalize → *Dashboard design*): **Spectral Console**
+(dark-first, ⌘K palette — the default), **Orbit** (light, circular radial menu), **Control Room**
+(violet), **Obsidian Ops** (near-black lime/cyan, mono), **Neon Command** (glassmorphism aurora), and
+**Mission Control** (indigo control panel). Each works in light and dark (the moon toggle). A design
+is a `data-design` skin — a scoped CSS token block plus a one-line entry in
+`dashboard/public/designs.js`, so adding one is trivial. Fonts are **self-hosted**
+(`dashboard/public/fonts/*.woff2`), keeping the dashboard fully offline and dependency-free. Your
+choice persists per viewer (localStorage) and as the project default (`config.design`).
+
+### Chat
+
+A floating **💬 chat widget** and the **Chat** tab render the same `runtime.messages` log via a shared
+`renderChatLog()`, so they never drift. A running agent identifies itself by printing `::spectoflow
+role=… kind=… msg=…` sentinels, which become labelled messages (analyst / developer / qa …); other
+output streams raw. The board refreshes live as it edits plans. Either surface can also
+**Orchestrate** the enabled workflow (each step runs its agent, gated by mode + policy), **Summarize**
+the recent log into one digest via the active agent, or **Clear** it outright. The Agents & Skills
+drawer is served by the one read-only endpoint, `GET /api/agentfile?path=` (scoped to
+`.spectoflow/agents/**` + `.spectoflow/skills/**`, path-traversal-safe) — the framework's only other
+server surface is unchanged.
+
+### Customize
+
+Personalize → **Extend spectoflow** lets you extend the project's own spectoflow install: add a
 dashboard, a skill, or an agent by describing what you want (or hit **Auto** to have the agent survey
-the project and propose candidates), and it clarifies first if the ask is ambiguous. Dashboards are
-never raw HTML — they're a small **declarative block spec** (`markdown`, `kpi-row`, `chart-bars`,
-`chart-donut`, `table`, `list`, `stat-tile-row`) rendered by the same components the built-in Board
-uses, so a generated dashboard automatically matches whatever design is active, in both themes, and
-keeps matching if you switch designs later. Blocks can bind live to project stats (`bind:
-"phases.0.pct"`) or hold a static value. Generated skills and agents follow the same gold-standard
-shape as the shipped ones, cite real domain standards (OWASP, WCAG, C4/ADR, …) instead of generic
-advice, and are marked `origin: user-generated` so they're easy to tell apart in the UI. The same
-generators are available from the terminal:
+the project and propose candidates) — it clarifies first if the ask is ambiguous.
+
+- Dashboards are never raw HTML — they're a small **declarative block spec** (`markdown`, `kpi-row`,
+  `chart-bars`, `chart-donut`, `table`, `list`, `stat-tile-row`) rendered by the same components the
+  built-in Board uses, so a generated dashboard automatically matches whatever design is active, in
+  both themes, and keeps matching if you switch designs later. Blocks can bind live to project stats
+  (`bind: "phases.0.pct"`) or hold a static value.
+- Generated skills and agents follow the same gold-standard shape as the shipped ones, cite real
+  domain standards (OWASP, WCAG, C4/ADR, …) instead of generic advice, and are marked `origin:
+  user-generated` so they're easy to tell apart in the UI.
+
+The same generators are available from the terminal — each streams the agent's run live and exits
+with its status, the same pipeline the dashboard's Generate/Auto buttons use:
 
 ```bash
 spectoflow skill create "reviews PRs for accessibility"      # or: --auto to propose candidates
@@ -223,9 +245,6 @@ spectoflow agent create "owns accessibility review"          # or: --auto
 spectoflow dashboard create "a KPI overview for support"     # or: --auto
 ```
 
-Each streams the agent's run live and exits with its status — the same pipeline the dashboard's
-Generate/Auto buttons use, just from a shell.
-
 ## Agents vs skills
 
 Agents (`.spectoflow/agents/`) are **stable team personas** (Product Manager, Developer, QA Engineer…).
@@ -235,25 +254,38 @@ runs a skill. Improve a skill without touching the agent.
 Agents and skills follow real domain standards, cited in-file — TDD, OWASP ASVS/Top 10, C4/ADR,
 INVEST, Playwright E2E, Conventional Commits, and more — not generic one-liners.
 
-**Clarify before acting.** spectoflow is an **expert analyst, not an order-taker**. When a request is
-vague ("login displays badly, users can't sign in"), an always-on **Clarify reflex** — in the agent's
-memory (`AGENTS.md`) and backed by the `clarify` skill — reflects it back and asks **one targeted
-question at a time**, each with a recommendation anchored in the project's goals and best practices,
-until the need is crisp; then it runs the normal workflow. It's additive: it feeds the router, never
-replaces it, and it's mode-aware.
-
-**End-to-end tests run headed, in the real browser, by default.** `write-e2e-tests` defaults to
-**Playwright lib, `--headed`** for its own local runs — the browser window is visible so a flow that
-"passes" for the wrong reason gets caught, not just a bare pass/fail line. `--ui` mode is used for
-authoring a flow or chasing a failure interactively. It only steps down — to headless, then
-**Playwright MCP**, then the client's native browser tooling (e.g. Claude Code's Chrome extension), then
-writing the spec and raising a `need` — when you asked for something else or headed genuinely can't
-launch, and it **always says why** via the `::spectoflow` sentinel, never a silent switch. CI keeps
-running the committed suite headless — that's the pipeline's job, not a fallback. `init` idempotently
-wires a `playwright` entry into the target project's `.mcp.json` (and `.cursor/mcp.json` for Cursor) so
-the MCP rung works out of the box — `npx` fetches the server on first use, so spectoflow stays zero-dep
-(the config lives in *your* project). The durable artifact is always the committed `*.spec.ts`; the
-Workflow tab's End-to-end step shows this policy in its dashboard popover.
+### Clarify before acting
+
+spectoflow is an **expert analyst, not an order-taker**. When a request is vague ("login displays
+badly, users can't sign in"), an always-on **Clarify reflex** — in the agent's memory (`AGENTS.md`)
+and backed by the `clarify` skill — reflects it back and asks **one targeted question at a time**,
+each with a recommendation anchored in the project's goals and best practices, until the need is
+crisp; then it runs the normal workflow. It's additive: it feeds the router, never replaces it, and
+it's mode-aware.
+
+### End-to-end tests run headed, in the real browser, by default
+
+`write-e2e-tests` defaults to **Playwright lib, `--headed`** for its own local runs — the browser
+window is visible so a flow that "passes" for the wrong reason gets caught, not just a bare pass/fail
+line. `--ui` mode is used for authoring a flow or chasing a failure interactively. It only steps down
+when you asked for something else or headed genuinely can't launch — and it **always says why** via
+the `::spectoflow` sentinel, never a silent switch:
+
+1. Playwright lib, headed (default)
+2. `--ui` (interactive authoring/debugging)
+3. Playwright lib, headless
+4. **Playwright MCP**
+5. the client's native browser tooling (e.g. Claude Code's Chrome extension)
+6. write the spec and raise a `need`
+
+CI keeps running the committed suite headless — that's the pipeline's job, not a fallback. `init`
+idempotently wires a `playwright` entry into the target project's `.mcp.json` (and
+`.cursor/mcp.json` for Cursor) so the MCP rung works out of the box — `npx` fetches the server on
+first use, so spectoflow stays zero-dep (the config lives in *your* project). The durable artifact is
+always the committed `*.spec.ts`; the Workflow tab's End-to-end step shows this policy in its
+dashboard popover.
+
+### Keeping spec and code honest
 
 A `governance` capability adds a **Spec Source Guardian** (skill `audit-source`): it keeps the spec
 (intent) and the code/tests (reality) coherent — flagging drift in both directions, never auto-fixing,
@@ -263,12 +295,30 @@ drift helper (`lib/spec-drift.js`) and an opt-in Claude Code `Stop` hook (`hooks
 ## Language
 
 `.spectoflow/config.json` → `language` (default `en`, incl. code comments). Switchable from the CLI
-(`config.json`) or the dashboard's **settings** gear (mode + language).
+(`config.json`), the dashboard's **Personalize** tab, or the topbar's language select directly.
 
 ## Studied, not copied
 
-Structure informed by spec-kit, OpenSpec (markdown + per-agent adapters), and BMAD (agent-personas).
-spectoflow keeps the good ideas, removes the ceremony, and adds a real-time control plane.
+spectoflow's design was informed by three open-source projects worth knowing about in their own
+right — credit where it's due:
+
+- **[GitHub spec-kit](https://github.com/github/spec-kit)** — the spec-driven workflow itself
+  (spec → plan → tasks) and its own multi-agent integration list, which shaped how spectoflow thinks
+  about agent-agnosticism.
+- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by Fission AI — markdown as the source of
+  truth and the per-agent adapter pattern (a thin native entry file per coding agent, pointing back
+  to one canonical brain) that `lib/adapters.js` is built on.
+- **[BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)** — stable, named agent personas
+  (PM, Architect, Developer, QA, …) as the right way to give an AI coding agent a consistent role,
+  rather than one undifferentiated prompt.
+
+spectoflow keeps what worked, drops the ceremony each of those needs from you, and adds what none of
+them had: a real-time local dashboard (board, chat, live agent-run tracking) and a genuinely
+exhaustive, individually-verified agent-CLI compatibility list — see [Supported coding
+agents](#supported-coding-agents) above.
+
+If you use spec-kit, OpenSpec, or BMAD-METHOD today, spectoflow is worth a look; if you're evaluating
+spectoflow, those three are worth a look too.
 
 ## License & author
 

package/bin/spectoflow.js

@@ -220,7 +220,7 @@ function init() {
   console.log('');
 }
 
-function update() {
+async function update() {
   const root = process.cwd();
   if (!fs.existsSync(path.join(root, '.spectoflow'))) {
     return console.log('No spectoflow project here. Run: spectoflow init');
@@ -252,6 +252,24 @@ function update() {
   else console.log(`  ${changed ? c.g('✓ Done') : c.dim('Already up to date')}${changed ? c.dim(` · ${changed} file(s) changed`) : ''}`);
   if (r.newSidecar.length && !dryRun) console.log(`  ${c.y('→')} ${c.dim(`${r.newSidecar.length} *.new file(s) to review and merge — or re-run: spectoflow update --force`)}`);
   console.log('');
+
+  // A running dashboard has the OLD framework code loaded into memory (Node caches `require()`d
+  // modules at process start) — new bytes on disk change nothing until it restarts. Do that
+  // automatically so an update always actually takes effect, instead of leaving a confusing
+  // half-updated dashboard (new static files, stale server logic) until someone thinks to restart.
+  if (!dryRun && changed) {
+    const lock = path.join(root, '.spectoflow', '.dashboard.lock');
+    let info = null;
+    try { info = JSON.parse(fs.readFileSync(lock, 'utf8')); } catch {}
+    if (info && info.port && (await probeDashboard(info.port, 2000))) {
+      console.log(`  ${c.dim('Dashboard is running — restarting it on port ' + info.port + ' to apply the update…')}`);
+      // Restart on the SAME port it was already on, not resolvePort(argv)'s default — `update`
+      // itself was never given a --port, so a naive restartDashboard() would silently move a
+      // non-default-port dashboard back to 4319.
+      argv.push(`--port=${info.port}`);
+      await restartDashboard();
+    }
+  }
 }
 
 // THE launch command — routes the subcommands, then starts. Starting spawns the server DETACHED and
@@ -331,7 +349,12 @@ async function startDashboard() {
   const env = Object.assign({}, process.env, { SPECTOFLOW_PORT: String(port) });
   const child = spawn('node', [fs.existsSync(local) ? local : bundled], { detached: true, stdio: 'ignore', env });
   child.unref();                                   // let this CLI exit while the server keeps running
-  console.log(`${c.g('✓')} dashboard started → ${c.bold(url)}  ${c.dim('(pid ' + child.pid + ')')}`);
+  // Confirm it actually came up (a still-releasing port from a just-stopped instance, or any other
+  // startup error, would otherwise print a false "started" while the detached process silently died).
+  let up = false;
+  for (let i = 0; i < 20 && !up; i++) { await new Promise((r) => setTimeout(r, 250)); up = await probeDashboard(port, 300); }
+  if (up) console.log(`${c.g('✓')} dashboard started → ${c.bold(url)}  ${c.dim('(pid ' + child.pid + ')')}`);
+  else console.log(`${c.y('!')} spawned (pid ${child.pid}) but it isn't responding on ${url} yet — check ${c.g('spectoflow dashboard status')} in a moment, or its own output if something's wrong.`);
   printDashboardCommands();
 }
 
@@ -354,7 +377,11 @@ async function dashboardStatus() {
 
 async function restartDashboard() {
   await stopDashboard();
-  await new Promise((r) => setTimeout(r, 400));     // let the port free up before rebinding
+  // Windows doesn't deliver real signals — process.kill() returns once the request is issued, not
+  // once the process (and the port it held) is actually gone. A short gap here, plus startDashboard()
+  // now confirming the new one actually came up, keeps a restart honest under load instead of racing
+  // a rebind against a socket the OS hasn't finished releasing yet.
+  await new Promise((r) => setTimeout(r, 1000));
   return startDashboard();
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Agent-agnostic spec-driven development framework + real-time local control plane. Markdown artifacts, intent router, workflow-by-scope.",
   "keywords": [
     "spec-driven-development",

package/templates/dashboard/files.js

@@ -0,0 +1,108 @@
+'use strict';
+/*
+ * File Explorer backend — browse, read, write and create files/folders anywhere under the project
+ * root. Kept separate from server.js (own module, like runner.js/summarize.js), since it owns a
+ * distinct concern: safe filesystem access scoped to the whole project, not just plans/specs/agents.
+ *
+ * Trust model matches the rest of this local dashboard (POST /api/run already spawns an arbitrary
+ * configured agent command): this is a single-user localhost dev tool, not a hosted multi-tenant
+ * service. The guard here exists to stop a path like "../../etc/passwd" from a buggy or malicious
+ * client, not to sandbox an untrusted operator.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const DENY_DIRS = new Set(['.git', 'node_modules']);
+const MAX_READ_BYTES = 2 * 1024 * 1024;
+
+// Resolves `rel` against `root`, rejecting anything that normalizes outside it (path traversal).
+// `root` itself is normalized first — ROOT can arrive with mixed separators (e.g. from an env var
+// built by joining a Windows base path with a forward-slash suffix), and comparing an un-normalized
+// root against path.resolve()'s always-normalized output would reject even legitimate children.
+function safePath(root, rel) {
+  const rootAbs = path.resolve(root);
+  const cleaned = String(rel || '').replace(/^[/\\]+/, '');
+  const abs = path.resolve(rootAbs, cleaned);
+  if (abs !== rootAbs && !abs.startsWith(rootAbs + path.sep)) return null;
+  return abs;
+}
+
+// Symlink guard: an existing path must REALLY resolve under root, not just syntactically.
+// A path that doesn't exist yet (e.g. a file about to be created) is trusted as-is — nothing to
+// resolve through.
+function realUnderRoot(root, abs) {
+  let real;
+  try { real = fs.realpathSync(abs); } catch { return abs; }
+  const realRoot = (() => { try { return fs.realpathSync(root); } catch { return root; } })();
+  if (real !== realRoot && !real.startsWith(realRoot + path.sep)) return null;
+  return real;
+}
+
+function isUnderGit(rel) {
+  const n = String(rel || '').replace(/\\/g, '/').replace(/^\/+/, '');
+  return n === '.git' || n.startsWith('.git/');
+}
+
+function buildTree(dir, relBase) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+  entries.sort((a, b) => (a.isDirectory() === b.isDirectory()) ? a.name.localeCompare(b.name) : (a.isDirectory() ? -1 : 1));
+  const out = [];
+  for (const e of entries) {
+    if (DENY_DIRS.has(e.name)) continue;
+    const rel = relBase ? relBase + '/' + e.name : e.name;
+    if (e.isDirectory()) out.push({ name: e.name, path: rel, type: 'dir', children: buildTree(path.join(dir, e.name), rel) });
+    else out.push({ name: e.name, path: rel, type: 'file' });
+  }
+  return out;
+}
+
+// A NUL byte anywhere in the first chunk means "binary" — cheap and reliable enough for a local
+// preview tool (the same heuristic git and most editors use).
+function isProbablyText(buf) {
+  const n = Math.min(buf.length, 8000);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return false;
+  return true;
+}
+
+function tree(root) {
+  return buildTree(root, '');
+}
+
+function readFile(root, rel) {
+  const abs = safePath(root, rel);
+  if (!abs) return { error: 'Invalid path.' };
+  const real = realUnderRoot(root, abs);
+  if (!real) return { error: 'Invalid path.' };
+  let stat;
+  try { stat = fs.statSync(real); } catch { return { error: 'Not found.' }; }
+  if (stat.isDirectory()) return { error: 'That is a folder.' };
+  if (stat.size > MAX_READ_BYTES) return { error: 'File too large to open here (>2MB).' };
+  const buf = fs.readFileSync(real);
+  if (!isProbablyText(buf)) return { binary: true, size: stat.size };
+  return { content: buf.toString('utf8') };
+}
+
+function writeFile(root, rel, content) {
+  if (typeof content !== 'string') return { error: 'Missing content.' };
+  if (isUnderGit(rel)) return { error: 'Writes under .git are blocked.' };
+  const abs = safePath(root, rel);
+  if (!abs) return { error: 'Invalid path.' };
+  const parentDir = path.dirname(abs);
+  if (fs.existsSync(parentDir) && !realUnderRoot(root, parentDir)) return { error: 'Invalid path.' };
+  fs.mkdirSync(parentDir, { recursive: true });
+  fs.writeFileSync(abs, content, 'utf8');
+  return { ok: true };
+}
+
+function mkdir(root, rel) {
+  if (isUnderGit(rel)) return { error: 'Cannot create folders under .git.' };
+  const abs = safePath(root, rel);
+  if (!abs) return { error: 'Invalid path.' };
+  const parentDir = path.dirname(abs);
+  if (fs.existsSync(parentDir) && !realUnderRoot(root, parentDir)) return { error: 'Invalid path.' };
+  fs.mkdirSync(abs, { recursive: true });
+  return { ok: true };
+}
+
+module.exports = { tree, readFile, writeFile, mkdir };