myrlin-workbook 0.9.25 → 0.9.27

package/package.json

@@ -1,66 +1,71 @@
-{
-  "name": "myrlin-workbook",
-  "version": "0.9.25",
-  "description": "Browser-based project manager for Claude Code sessions - session discovery, multi-terminal, cost tracking, docs, and kanban board",
-  "main": "src/index.js",
-  "bin": {
-    "myrlin-workbook": "./src/gui.js",
-    "myrlin": "./src/gui.js",
-    "myrlin-tui": "./src/index.js",
-    "cwm": "./src/index.js"
-  },
-  "scripts": {
-    "start": "node src/index.js",
-    "demo": "node src/demo.js",
-    "gui": "node src/supervisor.js",
-    "gui:daemon": "node src/supervisor.js --daemon",
-    "gui:bare": "node src/gui.js",
-    "gui:demo": "node src/supervisor.js --demo",
-    "test": "node test/run.js",
-    "mcp:visual-qa": "node src/mcp/visual-qa.js",
-    "gui:cdp": "node src/supervisor.js --cdp",
-    "postinstall": "node scripts/postinstall.js",
-    "restart": "bash scripts/restart-gui.sh"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/therealarthur/myrlin-workbook.git"
-  },
-  "homepage": "https://github.com/therealarthur/myrlin-workbook",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "keywords": [
-    "claude",
-    "workspace",
-    "manager",
-    "terminal",
-    "tui",
-    "ai",
-    "coding-assistant",
-    "session-manager",
-    "developer-tools",
-    "xterm",
-    "myrlin"
-  ],
-  "author": "Arthur",
-  "license": "AGPL-3.0-only",
-  "dependencies": {
-    "blessed": "^0.1.81",
-    "blessed-contrib": "^4.11.0",
-    "chalk": "^5.6.2",
-    "chrome-remote-interface": "^0.34.0",
-    "express": "^5.2.1",
-    "node-pty": "^1.1.0",
-    "qrcode": "^1.5.4",
-    "ws": "^8.19.0"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.58.2",
-    "@xterm/addon-fit": "^0.11.0",
-    "@xterm/addon-web-links": "^0.12.0",
-    "@xterm/xterm": "^6.0.0",
-    "ffmpeg-static": "^5.3.0",
-    "sharp": "^0.34.5"
-  }
-}
+{
+  "name": "myrlin-workbook",
+  "version": "0.9.27",
+  "description": "Browser-based project manager for Claude Code sessions - session discovery, multi-terminal, cost tracking, docs, and kanban board",
+  "main": "src/index.js",
+  "bin": {
+    "myrlin-workbook": "./src/gui.js",
+    "myrlin": "./src/gui.js",
+    "myrlin-tui": "./src/index.js",
+    "cwm": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "demo": "node src/demo.js",
+    "gui": "node src/supervisor.js",
+    "gui:daemon": "node src/supervisor.js --daemon",
+    "gui:bare": "node src/gui.js",
+    "gui:demo": "node src/supervisor.js --demo",
+    "test": "node test/run.js",
+    "mcp:visual-qa": "node src/mcp/visual-qa.js",
+    "gui:cdp": "node src/supervisor.js --cdp",
+    "postinstall": "node scripts/postinstall.js",
+    "restart": "bash scripts/restart-gui.sh",
+    "build:icons": "node scripts/build-lucide-bundle.mjs && node scripts/build-material-bundle.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/therealarthur/myrlin-workbook.git"
+  },
+  "homepage": "https://github.com/therealarthur/myrlin-workbook",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "claude",
+    "workspace",
+    "manager",
+    "terminal",
+    "tui",
+    "ai",
+    "coding-assistant",
+    "session-manager",
+    "developer-tools",
+    "xterm",
+    "myrlin"
+  ],
+  "author": "Arthur",
+  "license": "AGPL-3.0-only",
+  "dependencies": {
+    "@lucide/lab": "^0.1.2",
+    "blessed": "^0.1.81",
+    "blessed-contrib": "^4.11.0",
+    "chalk": "^5.6.2",
+    "chrome-remote-interface": "^0.34.0",
+    "express": "^5.2.1",
+    "lucide": "^1.8.0",
+    "node-pty": "^1.1.0",
+    "qrcode": "^1.5.4",
+    "simple-git": "^3.33.0",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@material-icons/svg": "^1.0.33",
+    "@playwright/test": "^1.58.2",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/xterm": "^6.0.0",
+    "ffmpeg-static": "^5.3.0",
+    "sharp": "^0.34.5"
+  }
+}

package/scripts/build-lucide-bundle.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * Build script: generates public/vendor/lucide.bundle.js
+ * Imports curated icons from `lucide` and `@lucide/lab`, converts to SVG strings,
+ * and outputs a plain JS bundle that sets window.__lucideIcons.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import vm from 'vm';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const OUT = resolve(ROOT, 'src/web/public/vendor/lucide.bundle.js');
+
+// ── Curated icon list ────────────────────────────────────────────────────────
+// Format: { category: [[kebab-name, 'lucide' | 'lab'], ...], ... }
+const ICON_CATEGORIES = {
+  'Folders & Files': [
+    ['folder',          'lucide'],
+    ['folder-open',     'lucide'],
+    ['folder-code',     'lucide'],
+    ['folder-git-2',    'lucide'],
+    ['folder-sync',     'lucide'],
+    ['folder-key',      'lucide'],
+    ['folder-search',   'lucide'],
+    ['folders',         'lucide'],
+    ['file',            'lucide'],
+    ['file-code',       'lucide'],
+    ['file-text',       'lucide'],
+    ['files',           'lucide'],
+    ['notebook',        'lucide'],
+    ['notebook-pen',    'lucide'],
+  ],
+  'Code & Dev': [
+    ['code',            'lucide'],
+    ['code-xml',        'lucide'],
+    ['square-terminal', 'lucide'],
+    ['terminal',        'lucide'],
+    ['git-branch',      'lucide'],
+    ['git-merge',       'lucide'],
+    ['git-commit-vertical', 'lucide'],
+    ['git-fork',        'lucide'],
+    ['braces',          'lucide'],
+    ['brackets',        'lucide'],
+    ['hash',            'lucide'],
+    ['variable',        'lucide'],
+  ],
+  'Infrastructure': [
+    ['database',        'lucide'],
+    ['database-zap',    'lucide'],
+    ['server',          'lucide'],
+    ['server-cog',      'lucide'],
+    ['cpu',             'lucide'],
+    ['hard-drive',      'lucide'],
+    ['network',         'lucide'],
+    ['wifi',            'lucide'],
+    ['cloud',           'lucide'],
+    ['cloud-upload',    'lucide'],
+    ['globe',           'lucide'],
+    ['layers',          'lucide'],
+  ],
+  'Apps & Tools': [
+    ['box',             'lucide'],
+    ['package',         'lucide'],
+    ['package-2',       'lucide'],
+    ['workflow',        'lucide'],
+    ['settings',        'lucide'],
+    ['settings-2',      'lucide'],
+    ['wrench',          'lucide'],
+    ['hammer',          'lucide'],
+    ['cog',             'lucide'],
+    ['tool-case',       'lucide'],
+    ['puzzle',          'lucide'],
+    ['blocks',          'lucide'],
+    ['plug',            'lucide'],
+    ['cpu',             'lucide'],
+  ],
+  'Design & Art': [
+    ['palette',         'lucide'],
+    ['brush',           'lucide'],
+    ['paintbrush',      'lucide'],
+    ['wand',            'lucide'],
+    ['wand-sparkles',   'lucide'],
+    ['sparkles',        'lucide'],
+    ['pen-tool',        'lucide'],
+    ['pencil',          'lucide'],
+    ['scissors',        'lucide'],
+    ['crop',            'lucide'],
+    ['image',           'lucide'],
+    ['camera',          'lucide'],
+  ],
+  'Learning & Science': [
+    ['book-open',       'lucide'],
+    ['book',            'lucide'],
+    ['scroll',          'lucide'],
+    ['flask-conical',   'lucide'],
+    ['flask-round',     'lucide'],
+    ['microscope',      'lucide'],
+    ['test-tube',       'lucide'],
+    ['brain',           'lucide'],
+    ['brain-circuit',   'lucide'],
+    ['atom',            'lucide'],
+    ['dna',             'lucide'],
+    ['telescope',       'lucide'],
+  ],
+  'People & Status': [
+    ['user',            'lucide'],
+    ['users',           'lucide'],
+    ['user-round',      'lucide'],
+    ['bot',             'lucide'],
+    ['rocket',          'lucide'],
+    ['star',            'lucide'],
+    ['heart',           'lucide'],
+    ['zap',             'lucide'],
+    ['shield',          'lucide'],
+    ['lock',            'lucide'],
+    ['key',             'lucide'],
+    ['flag',            'lucide'],
+    ['trophy',          'lucide'],
+    ['medal',           'lucide'],
+    ['crown',           'lucide'],
+  ],
+  'Home & Work': [
+    ['house',           'lucide'],
+    ['briefcase',       'lucide'],
+    ['building',        'lucide'],
+    ['building-2',      'lucide'],
+    ['store',           'lucide'],
+    ['landmark',        'lucide'],
+    ['map-pin',         'lucide'],
+    ['compass',         'lucide'],
+    ['map',             'lucide'],
+    ['globe-2',         'lucide'],
+    ['mountain',        'lucide'],
+  ],
+  'Media & Comms': [
+    ['monitor',         'lucide'],
+    ['laptop',          'lucide'],
+    ['smartphone',      'lucide'],
+    ['mail',            'lucide'],
+    ['message-circle',  'lucide'],
+    ['bell',            'lucide'],
+    ['phone',           'lucide'],
+    ['mic',             'lucide'],
+    ['music',           'lucide'],
+    ['headphones',      'lucide'],
+    ['video',           'lucide'],
+    ['radio',           'lucide'],
+  ],
+  'Nature & Fun': [
+    ['sun',             'lucide'],
+    ['moon',            'lucide'],
+    ['cloud-sun',       'lucide'],
+    ['flame',           'lucide'],
+    ['waves',           'lucide'],
+    ['coffee',          'lucide'],
+    ['leaf',            'lucide'],
+    ['flower',          'lucide'],
+    ['flower-2',        'lucide'],
+    ['tree-pine',       'lucide'],
+    ['trees',           'lucide'],
+    ['snail',           'lucide'],
+    ['fish',            'lucide'],
+    ['rabbit',          'lucide'],
+    ['turtle',          'lucide'],
+    ['bird',            'lucide'],
+    ['dog',             'lucide'],
+    ['cat',             'lucide'],
+  ],
+  'Lab Extras': [
+    ['owl',             'lab'],
+    ['planet',          'lab'],
+    ['bee',             'lab'],
+    ['venn',            'lab'],
+    ['copy-code',       'lab'],
+    ['grid-lines',      'lab'],
+    ['farm',            'lab'],
+    ['toolbox',         'lab'],
+    ['toolbox-2',       'lab'],
+    ['snowman',         'lab'],
+    ['mountain-snow',   'lab'],
+  ],
+};
+
+// ── SVG serializer ────────────────────────────────────────────────────────────
+function iconDataToSvg(iconData) {
+  const children = iconData.map(([tag, attrs]) => {
+    // Filter out non-SVG metadata attrs ('key' is a React/lucide internal)
+    const entries = Object.entries(attrs).filter(([k]) => k !== 'key');
+    const attrStr = entries.map(([k, v]) => `${k}="${v}"`).join(' ');
+    return `<${tag} ${attrStr}/>`;
+  }).join('');
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">${children}</svg>`;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+const icons = {};    // { "folder": "<svg>...</svg>", ... }
+const categories = {}; // { "Folders & Files": ["folder", "folder-open", ...], ... }
+const skipped = [];
+
+for (const [category, entries] of Object.entries(ICON_CATEGORIES)) {
+  const catIcons = [];
+  for (const [name, pkg] of entries) {
+    // De-dup (e.g. 'cpu' appears twice in the list above)
+    if (icons[name]) { catIcons.push(name); continue; }
+
+    const iconDir = pkg === 'lab'
+      ? resolve(ROOT, `node_modules/@lucide/lab/dist/esm/icons/${name}.js`)
+      : resolve(ROOT, `node_modules/lucide/dist/esm/icons/${name}.js`);
+
+    try {
+      const src = readFileSync(iconDir, 'utf8');
+      // Extract: const <Name> = <array>;\nexport { <Name> as default }
+      // Use greedy match up to the last ";" before the export statement
+      const match = src.match(/const \w+ = ([\s\S]+?);\s*\nexport/);
+      if (!match) { skipped.push(`${name} (parse fail)`); continue; }
+      // Evaluate JS object literal (has unquoted keys, not valid JSON)
+      const iconData = vm.runInNewContext(`(${match[1]})`);
+      icons[name] = iconDataToSvg(iconData);
+      catIcons.push(name);
+    } catch {
+      skipped.push(`${name} (${pkg})`);
+    }
+  }
+  if (catIcons.length > 0) categories[category] = catIcons;
+}
+
+// ── Output ────────────────────────────────────────────────────────────────────
+mkdirSync(resolve(ROOT, 'src/web/public/vendor'), { recursive: true });
+
+const output = `/* lucide icons bundle — generated by scripts/build-lucide-bundle.mjs */
+/* Includes ${Object.keys(icons).length} icons from lucide + @lucide/lab */
+(function() {
+  window.__lucideIcons = ${JSON.stringify(icons)};
+  window.__lucideIconCategories = ${JSON.stringify(categories)};
+  document.dispatchEvent(new Event('lucide-ready'));
+})();
+`;
+
+writeFileSync(OUT, output);
+console.log(`✓ Built ${Object.keys(icons).length} icons → src/web/public/vendor/lucide.bundle.js`);
+if (skipped.length) console.log(`  Skipped (not found): ${skipped.join(', ')}`);

package/scripts/build-material-bundle.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Build script: generates public/vendor/material-icons.bundle.js
+ * Includes ALL ~2191 icons from @material-icons/svg (baseline/filled variant),
+ * organized by their official categories from data.json.
+ *
+ * Icon names are stored with a "mi/" prefix when used in ws.icon so they
+ * can coexist with Lucide icon names without collision.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const ICONS_DIR = resolve(ROOT, 'node_modules/@material-icons/svg/svg');
+const DATA_JSON = resolve(ROOT, 'node_modules/@material-icons/svg/data.json');
+const OUT = resolve(ROOT, 'src/web/public/vendor/material-icons.bundle.js');
+
+// Official category short-name → display name
+const CATEGORY_LABELS = {
+  action:       'Action',
+  alert:        'Alert',
+  av:           'Audio & Video',
+  communication:'Communication',
+  content:      'Content',
+  device:       'Device',
+  editor:       'Editor',
+  file:         'File',
+  hardware:     'Hardware',
+  home:         'Home',
+  image:        'Image',
+  maps:         'Maps',
+  math:         'Math',
+  navigation:   'Navigation',
+  notification: 'Notification',
+  places:       'Places',
+  search:       'Search',
+  shopping:     'Shopping',
+  social:       'Social',
+  toggle:       'Toggle',
+};
+
+// ── SVG processor ─────────────────────────────────────────────────────────────
+function processSvg(raw) {
+  return raw
+    .replace(/width="24"/, 'width="14"')
+    .replace(/height="24"/, 'height="14"')
+    // Make color inherit from CSS (without this, icons always render black)
+    .replace('<svg ', '<svg fill="currentColor" ');
+}
+
+// ── Load icon metadata ────────────────────────────────────────────────────────
+const data = JSON.parse(readFileSync(DATA_JSON, 'utf8'));
+const iconMeta = data.icons; // [{ name, categories: [string], tags: [string] }]
+
+// Build category → [name] map using official categories
+const categoryMap = {}; // { 'Audio & Video': ['10k', ...], ... }
+for (const icon of iconMeta) {
+  for (const cat of (icon.categories || [])) {
+    const label = CATEGORY_LABELS[cat] || cat;
+    if (!categoryMap[label]) categoryMap[label] = [];
+    categoryMap[label].push(icon.name);
+  }
+}
+
+// ── Process all icons ─────────────────────────────────────────────────────────
+const icons = {};      // { name: '<svg>...' }
+const categories = {}; // { 'Audio & Video': ['10k', ...] }
+const skipped = [];
+
+for (const icon of iconMeta) {
+  const svgPath = resolve(ICONS_DIR, icon.name, 'baseline.svg');
+  if (!existsSync(svgPath)) {
+    skipped.push(icon.name);
+    continue;
+  }
+  try {
+    const raw = readFileSync(svgPath, 'utf8').trim();
+    icons[icon.name] = processSvg(raw);
+  } catch {
+    skipped.push(icon.name);
+  }
+}
+
+// Build final categories (only include icons that were successfully loaded)
+for (const [label, names] of Object.entries(categoryMap)) {
+  const valid = names.filter(n => icons[n]);
+  if (valid.length > 0) categories[label] = valid;
+}
+
+// ── Output ────────────────────────────────────────────────────────────────────
+mkdirSync(resolve(ROOT, 'src/web/public/vendor'), { recursive: true });
+
+const output = `/* Material Icons bundle — generated by scripts/build-material-bundle.mjs */
+/* Includes ${Object.keys(icons).length} icons from @material-icons/svg (baseline variant) */
+/* Icon names are stored as "mi/<name>" in workspace records to avoid Lucide collisions */
+(function() {
+  window.__materialIcons = ${JSON.stringify(icons)};
+  window.__materialIconCategories = ${JSON.stringify(categories)};
+  document.dispatchEvent(new Event('material-icons-ready'));
+})();
+`;
+
+writeFileSync(OUT, output);
+console.log(`✓ Built ${Object.keys(icons).length} Material icons across ${Object.keys(categories).length} categories → src/web/public/vendor/material-icons.bundle.js`);
+if (skipped.length) console.log(`  Skipped (not found): ${skipped.join(', ')}`);

package/src/state/store.js

@@ -452,7 +452,7 @@ class Store extends EventEmitter {
 
   // ─── Workspace CRUD ──────────────────────────────────────
 
-  createWorkspace({ name, description = '', color = 'cyan' }) {
+  createWorkspace({ name, description = '', color = 'cyan', icon = null }) {
     const id = crypto.randomUUID();
     const now = new Date().toISOString();
     const workspace = {
@@ -460,6 +460,7 @@ class Store extends EventEmitter {
       name,
       description,
       color,
+      icon,
       sessions: [],
       createdAt: now,
       lastActive: now,

package/src/web/file-manager.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Map of file extensions to CodeMirror language names.
+ */
+const EXT_TO_LANG = {
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript',
+  ts: 'typescript', tsx: 'typescript',
+  jsx: 'javascript',
+  json: 'json',
+  html: 'html', htm: 'html',
+  css: 'css', scss: 'css', less: 'css',
+  md: 'markdown', markdown: 'markdown',
+  py: 'python',
+  sh: 'shell', bash: 'shell',
+  yaml: 'yaml', yml: 'yaml',
+  toml: 'toml',
+  rs: 'rust',
+  go: 'go',
+  java: 'java',
+  rb: 'ruby',
+  php: 'php',
+  sql: 'sql',
+  xml: 'xml',
+  txt: 'text',
+};
+
+/**
+ * Directory names to skip when building the file tree.
+ * Prevents traversal into version control internals and build artifacts.
+ */
+const SKIP_DIRS = new Set([
+  '.git', 'node_modules', '.DS_Store', '__pycache__',
+  '.next', 'dist', 'build', '.cache',
+]);
+
+/**
+ * Validate that the resolved target path stays within root.
+ * Throws if path traversal is detected.
+ *
+ * @param {string} root - Absolute workspace root path
+ * @param {string} relPath - Relative path from client
+ * @returns {string} Resolved absolute path
+ */
+function validatePath(root, relPath) {
+  if (!root || typeof root !== 'string') throw new Error('root is required');
+  const resolved = path.resolve(root, relPath || '');
+  if (!resolved.startsWith(path.resolve(root) + path.sep) && resolved !== path.resolve(root)) {
+    throw new Error('Path traversal detected');
+  }
+  return resolved;
+}
+
+/**
+ * GET /api/files/tree
+ * Returns directory entries (dirs and files) for a given subpath within the
+ * workspace root. Skips .git, node_modules, and other build artifacts.
+ *
+ * @param {string} workingDir - Workspace root directory
+ * @param {string} [subpath=''] - Relative subpath to list
+ * @returns {Promise<{path: string, entries: Array}>}
+ */
+async function getTree(workingDir, subpath = '') {
+  const root = path.resolve(workingDir);
+  const target = validatePath(root, subpath);
+
+  const entries = await fs.promises.readdir(target, { withFileTypes: true });
+  const result = [];
+
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    // Skip hidden files/dirs (dot-files) at root level
+    if (subpath === '' && entry.name.startsWith('.')) continue;
+    const relPath = subpath ? path.join(subpath, entry.name) : entry.name;
+    if (entry.isDirectory()) {
+      result.push({ name: entry.name, path: relPath, type: 'dir' });
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).slice(1).toLowerCase();
+      result.push({ name: entry.name, path: relPath, type: 'file', ext });
+    }
+  }
+
+  // Sort: directories first, then files, each group sorted alphabetically
+  result.sort((a, b) => {
+    if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  return { path: subpath || '/', entries: result };
+}
+
+/**
+ * GET /api/files/content
+ * Returns file content as UTF-8 text with a language hint for CodeMirror.
+ * Rejects files larger than 5MB.
+ *
+ * @param {string} workingDir - Workspace root directory
+ * @param {string} file - Relative path to the file
+ * @returns {Promise<{content: string, language: string, size: number, path: string}>}
+ */
+async function getContent(workingDir, file) {
+  if (!file) throw new Error('file is required');
+  const root = path.resolve(workingDir);
+  const target = validatePath(root, file);
+
+  const stat = await fs.promises.stat(target);
+  if (stat.size > 5 * 1024 * 1024) throw new Error('File too large (> 5MB)');
+
+  const content = await fs.promises.readFile(target, 'utf8');
+  const ext = path.extname(file).slice(1).toLowerCase();
+  return {
+    content,
+    language: EXT_TO_LANG[ext] || 'text',
+    size: stat.size,
+    path: file,
+  };
+}
+
+/**
+ * POST /api/files/save
+ * Atomically writes file content by writing to a temp file then renaming.
+ * Creates parent directories if they don't exist.
+ *
+ * @param {string} workingDir - Workspace root directory
+ * @param {string} file - Relative path to the file
+ * @param {string} content - UTF-8 text content to write
+ * @returns {Promise<{ok: boolean}>}
+ */
+async function saveContent(workingDir, file, content) {
+  if (!file) throw new Error('file is required');
+  if (typeof content !== 'string') throw new Error('content must be a string');
+  const root = path.resolve(workingDir);
+  const target = validatePath(root, file);
+
+  // Ensure parent directory exists
+  await fs.promises.mkdir(path.dirname(target), { recursive: true });
+
+  // Atomic write: write to temp file then rename into place
+  const tmp = target + '.tmp.' + Date.now();
+  await fs.promises.writeFile(tmp, content, 'utf8');
+  await fs.promises.rename(tmp, target);
+
+  return { ok: true };
+}
+
+module.exports = { getTree, getContent, saveContent };