claws-code 0.8.0

package/extension/src/wave-registry.ts

@@ -0,0 +1,314 @@
+import { SubWorkerRole } from './protocol';
+
+export interface WaveSubWorkerEntry {
+  role: SubWorkerRole;
+  /** peerId of the sub-worker peer, set on hello with waveId+subWorkerRole. */
+  peerId?: string;
+  /** Epoch ms of last observed heartbeat from this sub-worker. */
+  lastHeartbeatMs: number;
+  /** Whether this sub-worker has published its *.complete event. */
+  complete: boolean;
+  /** NodeJS timer handle for the violation detector. */
+  violationTimer?: ReturnType<typeof setTimeout>;
+  /** Terminal ID created by this sub-worker (set by server create handler). */
+  terminalId?: string;
+}
+
+export interface WaveRecord {
+  waveId: string;
+  /** Human-readable layers or goals this wave covers. */
+  layers: string[];
+  /** Expected sub-worker roles, tracking entry keyed by role. */
+  subWorkers: Map<SubWorkerRole, WaveSubWorkerEntry>;
+  /** peerId of the LEAD peer that created this wave. */
+  leadPeerId: string;
+  createdAt: number;
+  completedAt?: number;
+  summary?: string;
+  commits?: string[];
+  regressionClean?: boolean;
+  complete: boolean;
+  /** Optional parent wave ID when this wave was spawned by another wave's LEAD. */
+  parentWave?: string;
+  /** Terminal IDs spawned by sub-worker peers affiliated with this wave. */
+  subWorkerTerminals: string[];
+  /** Epoch ms when auto-harvest ran (wave.complete triggered terminal closures). */
+  harvestedAt?: number;
+  /** Terminal IDs that were still open at harvest time and were force-closed. */
+  orphanedTerminals: string[];
+  /** Lead-silence violation timer. Fires when LEAD is silent AND has active sub-worker terminals. */
+  leadViolationTimer?: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Callback invoked by WaveRegistry when a sub-worker has been silent
+ * longer than VIOLATION_THRESHOLD_MS. The emitter should publish a
+ * wave.<waveId>.violation event on the bus.
+ */
+export type ViolationCallback = (waveId: string, role: SubWorkerRole, silentMs: number) => void;
+
+/**
+ * Callback invoked when a LEAD has been silent for VIOLATION_THRESHOLD_MS
+ * while the wave still has un-harvested sub-worker terminals.
+ */
+export type LeadViolationCallback = (waveId: string, subWorkerCount: number) => void;
+
+const DEFAULT_VIOLATION_THRESHOLD_MS = 25_000;
+
+export class WaveRegistry {
+  private readonly waves = new Map<string, WaveRecord>();
+  private readonly onViolation: ViolationCallback;
+  private readonly onLeadViolation?: LeadViolationCallback;
+  private readonly violationThresholdMs: number;
+
+  constructor(
+    onViolation: ViolationCallback,
+    onLeadViolation?: LeadViolationCallback,
+    violationThresholdMs: number = DEFAULT_VIOLATION_THRESHOLD_MS,
+  ) {
+    this.onViolation = onViolation;
+    this.onLeadViolation = onLeadViolation;
+    this.violationThresholdMs = violationThresholdMs;
+  }
+
+  /** Create a new wave. Idempotent — returns existing wave if waveId already registered. */
+  createWave(
+    waveId: string,
+    layers: string[],
+    manifest: SubWorkerRole[],
+    leadPeerId: string,
+    parentWave?: string,
+  ): WaveRecord {
+    const existing = this.waves.get(waveId);
+    if (existing) return existing;
+
+    const subWorkers = new Map<SubWorkerRole, WaveSubWorkerEntry>();
+    const now = Date.now();
+    for (const role of manifest) {
+      const entry: WaveSubWorkerEntry = { role, lastHeartbeatMs: now, complete: false };
+      const timer = setTimeout(() => {
+        this._checkViolation(waveId, role);
+      }, this.violationThresholdMs);
+      entry.violationTimer = timer;
+      subWorkers.set(role, entry);
+    }
+
+    const record: WaveRecord = {
+      waveId,
+      layers,
+      subWorkers,
+      leadPeerId,
+      createdAt: now,
+      complete: false,
+      parentWave,
+      subWorkerTerminals: [],
+      orphanedTerminals: [],
+    };
+
+    if (this.onLeadViolation) {
+      record.leadViolationTimer = this._scheduleLeadViolation(waveId);
+    }
+
+    this.waves.set(waveId, record);
+    return record;
+  }
+
+  /** Record a heartbeat from a sub-worker, resetting its violation timer. */
+  recordHeartbeat(waveId: string, role: SubWorkerRole, peerId?: string): void {
+    const wave = this.waves.get(waveId);
+    if (!wave) return;
+    const entry = wave.subWorkers.get(role);
+    if (!entry) return;
+
+    entry.lastHeartbeatMs = Date.now();
+    if (peerId) entry.peerId = peerId;
+
+    if (entry.violationTimer !== undefined) clearTimeout(entry.violationTimer);
+    if (!entry.complete && !wave.complete) {
+      entry.violationTimer = setTimeout(() => {
+        this._checkViolation(waveId, role);
+      }, this.violationThresholdMs);
+    }
+  }
+
+  /**
+   * Record a heartbeat from the LEAD peer, resetting the lead-violation timer.
+   * Called by the server whenever the LEAD peer issues any command.
+   */
+  recordLeadHeartbeat(waveId: string): void {
+    const wave = this.waves.get(waveId);
+    if (!wave || wave.complete) return;
+    if (wave.leadViolationTimer !== undefined) clearTimeout(wave.leadViolationTimer);
+    if (this.onLeadViolation) {
+      wave.leadViolationTimer = this._scheduleLeadViolation(waveId);
+    }
+  }
+
+  /** Mark a sub-worker as complete and cancel its violation timer. */
+  markSubWorkerComplete(waveId: string, role: SubWorkerRole): void {
+    const wave = this.waves.get(waveId);
+    if (!wave) return;
+    const entry = wave.subWorkers.get(role);
+    if (!entry) return;
+
+    entry.complete = true;
+    if (entry.violationTimer !== undefined) {
+      clearTimeout(entry.violationTimer);
+      entry.violationTimer = undefined;
+    }
+  }
+
+  /**
+   * Used by the violation callback to silence further violations once the sub-worker is auto-closed.
+   * Idempotent — safe to call twice.
+   */
+  markSubWorkerAutoClosed(waveId: string, role: SubWorkerRole): { terminalId: string | undefined; found: boolean } {
+    const wave = this.waves.get(waveId);
+    if (!wave) return { terminalId: undefined, found: false };
+    const entry = wave.subWorkers.get(role);
+    if (!entry) return { terminalId: undefined, found: false };
+    if (entry.violationTimer !== undefined) {
+      clearTimeout(entry.violationTimer);
+      entry.violationTimer = undefined;
+    }
+    entry.complete = true;
+    // Prune terminal from subWorkerTerminals so _checkLeadViolation no longer
+    // counts this auto-closed terminal as "active". Without this, lead-silence
+    // violations keep firing every threshold cycle even after the sub-worker
+    // is dead. Verified live in Phase 4 of LH-1 verification (events 7-9 noise).
+    if (entry.terminalId) {
+      const idx = wave.subWorkerTerminals.indexOf(entry.terminalId);
+      if (idx >= 0) wave.subWorkerTerminals.splice(idx, 1);
+    }
+    return { terminalId: entry.terminalId, found: true };
+  }
+
+  /**
+   * Track a terminal ID spawned by a sub-worker peer affiliated with this wave.
+   * Optionally associates the TID with a specific sub-worker role entry.
+   * Silently ignored if wave doesn't exist or is already complete.
+   */
+  trackTerminal(waveId: string, terminalId: string, role?: SubWorkerRole): void {
+    const wave = this.waves.get(waveId);
+    if (!wave || wave.complete) return;
+    if (!wave.subWorkerTerminals.includes(terminalId)) {
+      wave.subWorkerTerminals.push(terminalId);
+    }
+    if (role) {
+      const entry = wave.subWorkers.get(role);
+      if (entry && !entry.terminalId) entry.terminalId = terminalId;
+    }
+  }
+
+  /**
+   * Harvest a wave: collect all un-closed sub-worker terminals, mark them as
+   * orphaned, set harvestedAt. Returns the terminal ID list so the server can
+   * call terminalManager.close() on each. Only valid once per wave.
+   */
+  harvestWave(waveId: string): string[] {
+    const wave = this.waves.get(waveId);
+    if (!wave || wave.harvestedAt) return [];
+    wave.harvestedAt = Date.now();
+    wave.orphanedTerminals = [...wave.subWorkerTerminals];
+    return wave.orphanedTerminals;
+  }
+
+  /**
+   * Mark the wave as complete. Clears all sub-worker violation timers and the
+   * lead violation timer. Returns the wave record (including subWorkerTerminals
+   * for harvest) or null if the wave was already complete.
+   * Only the LEAD should call this.
+   */
+  completeWave(
+    waveId: string,
+    summary: string,
+    commits?: string[],
+    regressionClean?: boolean,
+  ): WaveRecord | null {
+    const wave = this.waves.get(waveId);
+    if (!wave || wave.complete) return null;
+
+    for (const entry of wave.subWorkers.values()) {
+      if (entry.violationTimer !== undefined) {
+        clearTimeout(entry.violationTimer);
+        entry.violationTimer = undefined;
+      }
+    }
+    if (wave.leadViolationTimer !== undefined) {
+      clearTimeout(wave.leadViolationTimer);
+      wave.leadViolationTimer = undefined;
+    }
+    wave.complete = true;
+    wave.completedAt = Date.now();
+    wave.summary = summary;
+    wave.commits = commits;
+    wave.regressionClean = regressionClean;
+    return wave;
+  }
+
+  /** Get a snapshot of a wave. Returns null if wave does not exist. */
+  getWave(waveId: string): WaveRecord | null {
+    return this.waves.get(waveId) ?? null;
+  }
+
+  /** List all waves (shallow copy of records). */
+  listWaves(): WaveRecord[] {
+    return [...this.waves.values()];
+  }
+
+  /** Handle peer disconnect — clear violation timers for any sub-worker registered under that peerId. */
+  handlePeerDisconnect(peerId: string): void {
+    for (const wave of this.waves.values()) {
+      if (wave.complete) continue;
+      for (const entry of wave.subWorkers.values()) {
+        if (entry.peerId === peerId && !entry.complete) {
+          if (entry.violationTimer !== undefined) clearTimeout(entry.violationTimer);
+          entry.violationTimer = undefined;
+        }
+      }
+    }
+  }
+
+  /** Dispose — clear all timers. */
+  dispose(): void {
+    for (const wave of this.waves.values()) {
+      for (const entry of wave.subWorkers.values()) {
+        if (entry.violationTimer !== undefined) clearTimeout(entry.violationTimer);
+      }
+      if (wave.leadViolationTimer !== undefined) clearTimeout(wave.leadViolationTimer);
+    }
+    this.waves.clear();
+  }
+
+  private _scheduleLeadViolation(waveId: string): ReturnType<typeof setTimeout> {
+    return setTimeout(() => {
+      this._checkLeadViolation(waveId);
+    }, this.violationThresholdMs);
+  }
+
+  private _checkLeadViolation(waveId: string): void {
+    const wave = this.waves.get(waveId);
+    if (!wave || wave.complete || wave.harvestedAt) return;
+    const activeCount = wave.subWorkerTerminals.length;
+    if (activeCount > 0 && this.onLeadViolation) {
+      this.onLeadViolation(waveId, activeCount);
+      // Reschedule so violations keep firing until resolved.
+      wave.leadViolationTimer = this._scheduleLeadViolation(waveId);
+    }
+  }
+
+  private _checkViolation(waveId: string, role: SubWorkerRole): void {
+    const wave = this.waves.get(waveId);
+    if (!wave || wave.complete) return;
+    const entry = wave.subWorkers.get(role);
+    if (!entry || entry.complete) return;
+
+    const silentMs = Date.now() - entry.lastHeartbeatMs;
+    if (silentMs >= this.violationThresholdMs) {
+      this.onViolation(waveId, role, silentMs);
+      if (!entry.complete) {
+        entry.violationTimer = setTimeout(() => this._checkViolation(waveId, role), this.violationThresholdMs);
+      }
+    }
+  }
+}

package/extension/src/websocket-transport.ts

@@ -0,0 +1,153 @@
+/**
+ * L19 TRANSPORT-X — WebSocket server that adapts the ws:// protocol to the
+ * same newline-delimited JSON frame contract used by the Unix socket transport.
+ *
+ * Each WebSocket message = one JSON frame (no newline needed; WebSocket has
+ * its own message boundaries). The adapter wraps each WebSocket connection
+ * in a thin net.Socket-compatible shim so `ClawsServer.handleConnection()`
+ * can be reused without modification.
+ *
+ * Loaded lazily — require('ws') is only called when webSocket.enabled=true,
+ * so the extension imposes no load-time cost when WebSocket is disabled.
+ */
+
+import * as net from 'net';
+import * as http from 'http';
+import * as https from 'https';
+import * as fs from 'fs';
+import { EventEmitter } from 'events';
+
+/** Minimal subset of ws.WebSocket we use — avoids a hard import at the top level. */
+interface WsSocket extends EventEmitter {
+  send(data: string): void;
+  terminate(): void;
+  readyState: number;
+}
+
+/** Minimal subset of ws.WebSocketServer options we use. */
+interface WsServerOptions {
+  server: http.Server | https.Server;
+}
+
+/** Minimal subset of ws.WebSocketServer we use. */
+interface WsServer extends EventEmitter {
+  close(cb?: () => void): void;
+}
+
+/** WsSocketAdapter wraps a ws.WebSocket in a net.Socket-like interface. */
+class WsSocketAdapter extends EventEmitter {
+  private _destroyed = false;
+
+  constructor(private readonly ws: WsSocket) {
+    super();
+    ws.on('message', (data: Buffer | string) => {
+      // Each WebSocket message is one complete JSON frame; append \n so the
+      // server's line-buffering logic sees a complete line.
+      const str = typeof data === 'string' ? data : data.toString('utf8');
+      this.emit('data', Buffer.from(str + '\n'));
+    });
+    ws.on('close', () => {
+      if (!this._destroyed) {
+        this._destroyed = true;
+        this.emit('end');
+        this.emit('close');
+      }
+    });
+    ws.on('error', (err: Error) => {
+      this.emit('error', err);
+    });
+  }
+
+  write(data: string | Buffer): boolean {
+    if (this._destroyed) return false;
+    const str = typeof data === 'string' ? data : data.toString('utf8');
+    // Strip the trailing \n that the server appends — WebSocket framing
+    // handles message boundaries without it.
+    const frame = str.endsWith('\n') ? str.slice(0, -1) : str;
+    try {
+      this.ws.send(frame);
+    } catch { /* connection may have closed between check and send */ }
+    return true;
+  }
+
+  destroy(): void {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    try { this.ws.terminate(); } catch { /* ignore */ }
+    this.emit('close');
+  }
+
+  get destroyed(): boolean { return this._destroyed; }
+
+  /** Compatibility stub — WebSocket has its own backpressure, always report no pressure. */
+  get writableLength(): number { return 0; }
+}
+
+export interface WebSocketTransportOptions {
+  port: number;
+  certPath?: string;
+  keyPath?: string;
+  logger: (msg: string) => void;
+  /** Called for each new WebSocket connection with the adapted socket shim. */
+  onConnection: (socket: net.Socket) => void;
+}
+
+export class WebSocketTransport {
+  private wsServer: WsServer | null = null;
+  private httpServer: http.Server | https.Server | null = null;
+
+  start(opts: WebSocketTransportOptions): Promise<void> {
+    return new Promise((resolve, reject) => {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      let WS: new (opts: WsServerOptions) => WsServer;
+      try {
+        const wsModule = require('ws') as { WebSocketServer: typeof WS };
+        WS = wsModule.WebSocketServer;
+      } catch {
+        return reject(new Error(
+          'ws module not available — install it as an optional dependency: npm install ws',
+        ));
+      }
+
+      const useTls = Boolean(opts.certPath && opts.keyPath);
+      if (useTls) {
+        let cert: Buffer;
+        let key: Buffer;
+        try {
+          cert = fs.readFileSync(opts.certPath!);
+          key = fs.readFileSync(opts.keyPath!);
+        } catch (err) {
+          return reject(new Error(`WebSocket TLS: failed to read cert/key — ${(err as Error).message}`));
+        }
+        this.httpServer = https.createServer({ cert, key });
+      } else {
+        this.httpServer = http.createServer();
+      }
+
+      this.wsServer = new WS({ server: this.httpServer });
+
+      this.wsServer.on('connection', (ws: WsSocket) => {
+        const adapter = new WsSocketAdapter(ws);
+        // Cast: our adapter satisfies the interface ClawsServer.handleConnection expects
+        opts.onConnection(adapter as unknown as net.Socket);
+      });
+
+      this.httpServer.once('error', (err) => {
+        reject(err);
+      });
+
+      this.httpServer.listen(opts.port, '127.0.0.1', () => {
+        const proto = useTls ? 'wss' : 'ws';
+        opts.logger(`[claws/ws] listening on ${proto}://127.0.0.1:${opts.port}`);
+        resolve();
+      });
+    });
+  }
+
+  stop(): void {
+    try { this.wsServer?.close(); } catch { /* ignore */ }
+    try { this.httpServer?.close(); } catch { /* ignore */ }
+    this.wsServer = null;
+    this.httpServer = null;
+  }
+}

package/extension/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "out",
+    "rootDir": "src",
+    "strict": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "declaration": false
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "out", "dist", "test"]
+}

package/lib/capabilities.js

@@ -0,0 +1,145 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { dryRunLog } = require('./platform.js');
+
+const REPO_ROOT     = path.resolve(__dirname, '..');
+const COMMANDS_SRC  = path.join(REPO_ROOT, '.claude', 'commands');
+const SKILLS_SRC    = path.join(REPO_ROOT, '.claude', 'skills');
+const RULES_SRC     = path.join(REPO_ROOT, 'rules');
+
+/**
+ * Install all capabilities (commands + skills + rules) into targetRoot/.claude/.
+ * Runs Bug 1 + Bug 2 sweeps before copying.
+ * @param {string} targetRoot  - e.g. os.homedir() for global install
+ * @param {boolean} [dryRun]
+ */
+function installCapabilities(targetRoot, dryRun = false) {
+  installCommands(targetRoot, dryRun);
+  installSkills(targetRoot, dryRun);
+  installRules(targetRoot, dryRun);
+}
+
+/**
+ * Bug 1 sweep + copy claws-*.md commands into targetRoot/.claude/commands/.
+ * @param {string} targetRoot
+ * @param {boolean} [dryRun]
+ */
+function installCommands(targetRoot, dryRun = false) {
+  const cmdDir = path.join(targetRoot, '.claude', 'commands');
+
+  if (dryRun) {
+    dryRunLog(`mkdir ${cmdDir}`);
+  } else {
+    fs.mkdirSync(cmdDir, { recursive: true });
+  }
+
+  sweepCommands(cmdDir, dryRun);
+
+  if (!fs.existsSync(COMMANDS_SRC)) return;
+  const files = fs.readdirSync(COMMANDS_SRC).filter(
+    f => f === 'claws.md' || (f.startsWith('claws-') && f.endsWith('.md'))
+  );
+  for (const f of files) {
+    const src  = path.join(COMMANDS_SRC, f);
+    const dest = path.join(cmdDir, f);
+    if (dryRun) { dryRunLog(`copy ${src} → ${dest}`); continue; }
+    fs.copyFileSync(src, dest);
+  }
+}
+
+/**
+ * Bug 2 sweep + copy claws-* skill dirs into targetRoot/.claude/skills/.
+ * @param {string} targetRoot
+ * @param {boolean} [dryRun]
+ */
+function installSkills(targetRoot, dryRun = false) {
+  const skillsDir = path.join(targetRoot, '.claude', 'skills');
+
+  if (dryRun) {
+    dryRunLog(`mkdir ${skillsDir}`);
+  } else {
+    fs.mkdirSync(skillsDir, { recursive: true });
+  }
+
+  sweepSkills(skillsDir, dryRun);
+
+  if (!fs.existsSync(SKILLS_SRC)) return;
+  const dirs = fs.readdirSync(SKILLS_SRC).filter(
+    d => (d.startsWith('claws-') || d.startsWith('dev-protocol-')) &&
+         fs.statSync(path.join(SKILLS_SRC, d)).isDirectory()
+  );
+  for (const d of dirs) {
+    const src  = path.join(SKILLS_SRC, d);
+    const dest = path.join(skillsDir, d);
+    if (path.resolve(src) === path.resolve(dest)) continue; // self-collision guard
+    if (dryRun) { dryRunLog(`copy ${src}/ → ${dest}/`); continue; }
+    fs.cpSync(src, dest, { recursive: true });
+  }
+}
+
+/**
+ * Copy claws-default-behavior.md rule into targetRoot/.claude/rules/.
+ * @param {string} targetRoot
+ * @param {boolean} [dryRun]
+ */
+function installRules(targetRoot, dryRun = false) {
+  const rulesDir = path.join(targetRoot, '.claude', 'rules');
+  const ruleSrc  = path.join(RULES_SRC, 'claws-default-behavior.md');
+
+  if (!fs.existsSync(ruleSrc)) return;
+
+  if (dryRun) {
+    dryRunLog(`mkdir ${rulesDir}`);
+    dryRunLog(`copy ${ruleSrc} → ${path.join(rulesDir, 'claws-default-behavior.md')}`);
+    return;
+  }
+
+  fs.mkdirSync(rulesDir, { recursive: true });
+  fs.copyFileSync(ruleSrc, path.join(rulesDir, 'claws-default-behavior.md'));
+}
+
+/**
+ * Bug 1: remove stale claws-*.md files from cmdDir.
+ * @param {string} cmdDir
+ * @param {boolean} [dryRun]
+ */
+function sweepCommands(cmdDir, dryRun = false) {
+  if (!fs.existsSync(cmdDir)) return;
+  const stale = fs.readdirSync(cmdDir).filter(
+    f => f === 'claws.md' || (f.startsWith('claws-') && f.endsWith('.md'))
+  );
+  for (const f of stale) {
+    const p = path.join(cmdDir, f);
+    if (dryRun) { dryRunLog(`sweep stale command ${p}`); continue; }
+    fs.rmSync(p);
+  }
+}
+
+/**
+ * Bug 2: remove stale claws-* skill dirs from skillsDir.
+ * @param {string} skillsDir
+ * @param {boolean} [dryRun]
+ */
+function sweepSkills(skillsDir, dryRun = false) {
+  if (!fs.existsSync(skillsDir)) return;
+  const stale = fs.readdirSync(skillsDir).filter(
+    d => d.startsWith('claws-') &&
+         fs.statSync(path.join(skillsDir, d)).isDirectory()
+  );
+  for (const d of stale) {
+    const p = path.join(skillsDir, d);
+    if (dryRun) { dryRunLog(`sweep stale skill dir ${p}`); continue; }
+    fs.rmSync(p, { recursive: true });
+  }
+}
+
+module.exports = {
+  installCapabilities,
+  installCommands,
+  installSkills,
+  installRules,
+  sweepCommands,
+  sweepSkills,
+};

package/lib/dry-run.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const fs = require('fs');
+const { dryRunLog } = require('./platform.js');
+
+function mkdir(dir, dryRun) {
+  if (dryRun) { dryRunLog(`mkdir ${dir}`); return; }
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyFile(src, dest, dryRun) {
+  if (dryRun) { dryRunLog(`copy ${src} → ${dest}`); return; }
+  fs.copyFileSync(src, dest);
+}
+
+function copyDir(src, dest, dryRun) {
+  if (dryRun) { dryRunLog(`copy ${src}/ → ${dest}/`); return; }
+  fs.cpSync(src, dest, { recursive: true });
+}
+
+function writeFile(filePath, content, dryRun) {
+  if (dryRun) { dryRunLog(`write ${filePath}`); return; }
+  const tmp = filePath + '.claws-tmp.' + process.pid;
+  fs.writeFileSync(tmp, content, 'utf8');
+  fs.renameSync(tmp, filePath);
+}
+
+function removeFile(filePath, dryRun) {
+  if (dryRun) { dryRunLog(`rm ${filePath}`); return; }
+  fs.rmSync(filePath);
+}
+
+function removeDir(dirPath, dryRun) {
+  if (dryRun) { dryRunLog(`rm -rf ${dirPath}`); return; }
+  fs.rmSync(dirPath, { recursive: true });
+}
+
+function spawn(label, fn, dryRun) {
+  if (dryRun) { dryRunLog(label); return; }
+  fn();
+}
+
+module.exports = { mkdir, copyFile, copyDir, writeFile, removeFile, removeDir, spawn };