chati-dev 1.4.0 → 2.0.2

package/src/terminal/spawner.js

@@ -0,0 +1,269 @@
+/**
+ * @fileoverview Terminal spawner for multi-agent parallel execution.
+ *
+ * Spawns separate Claude Code CLI processes so that multiple agents
+ * can work concurrently.  The heavy lifting is split into pure,
+ * testable helpers (buildSpawnCommand) and a thin runtime layer
+ * (spawnTerminal) that actually calls child_process.spawn.
+ */
+
+import { spawn } from 'child_process';
+import { validateWriteScopes, buildIsolationEnv } from './isolation.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+let _counter = 0;
+
+/**
+ * Generate a unique terminal identifier.
+ *
+ * @param {string} agent - Agent name
+ * @returns {string} Unique ID in the form "agent-<timestamp>-<counter>"
+ */
+function generateTerminalId(agent) {
+  _counter += 1;
+  return `${agent}-${Date.now()}-${_counter}`;
+}
+
+/**
+ * Reset the internal counter (useful in tests).
+ */
+export function _resetCounter() {
+  _counter = 0;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} SpawnConfig
+ * @property {string} agent       - Agent name (e.g. "architect")
+ * @property {string} taskId      - Task identifier
+ * @property {object} [contextPayload] - Context to inject via env var
+ * @property {string[]} [writeScope]   - Override write scope
+ * @property {string} [workingDir]     - Working directory for the process
+ * @property {number} [timeout]        - Max execution time in ms
+ */
+
+/**
+ * @typedef {object} TerminalHandle
+ * @property {string} id         - Unique terminal ID
+ * @property {object|null} process - child_process.ChildProcess (null when dry)
+ * @property {string} agent      - Agent name
+ * @property {string} taskId     - Task identifier
+ * @property {string} startedAt  - ISO timestamp
+ * @property {string} status     - "running" | "exited" | "killed"
+ * @property {number|null} exitCode - Process exit code (null while running)
+ * @property {string[]} stdout   - Captured stdout lines
+ * @property {string[]} stderr   - Captured stderr lines
+ * @property {number} timeout    - Max execution time in ms
+ */
+
+/**
+ * Build the CLI command, arguments and environment for spawning a
+ * Claude Code terminal.  This is a **pure function** -- it does not
+ * perform any I/O and is therefore fully testable in isolation.
+ *
+ * @param {SpawnConfig} config
+ * @returns {{ command: string, args: string[], env: Record<string, string> }}
+ */
+export function buildSpawnCommand(config) {
+  if (!config || typeof config !== 'object') {
+    throw new Error('buildSpawnCommand requires a config object');
+  }
+  if (!config.agent || typeof config.agent !== 'string') {
+    throw new Error('config.agent is required and must be a string');
+  }
+  if (!config.taskId || typeof config.taskId !== 'string') {
+    throw new Error('config.taskId is required and must be a string');
+  }
+
+  const terminalId = generateTerminalId(config.agent);
+  const isolationEnv = buildIsolationEnv(config.agent);
+
+  const env = {
+    ...isolationEnv,
+    CHATI_TERMINAL_ID: terminalId,
+    CHATI_AGENT: config.agent,
+    CHATI_TASK_ID: config.taskId,
+  };
+
+  if (config.contextPayload) {
+    try {
+      env.CHATI_CONTEXT = JSON.stringify(config.contextPayload);
+    } catch {
+      env.CHATI_CONTEXT = '{}';
+    }
+  }
+
+  // Build the prompt that will be sent to claude CLI
+  const prompt = `Execute task ${config.taskId} as agent ${config.agent}. ` +
+    `Write scope: ${isolationEnv.CHATI_WRITE_SCOPE || 'none'}. ` +
+    `Terminal ID: ${terminalId}.`;
+
+  const command = 'claude';
+  const args = [
+    '--print',
+    '--dangerously-skip-permissions',
+    prompt,
+  ];
+
+  return { command, args, env, terminalId };
+}
+
+/**
+ * Spawn a new terminal process for an agent task.
+ *
+ * @param {SpawnConfig} config
+ * @returns {TerminalHandle}
+ */
+export function spawnTerminal(config) {
+  const { command, args, env, terminalId } = buildSpawnCommand(config);
+
+  const cwd = config.workingDir || process.cwd();
+  const timeout = config.timeout || 300_000; // default 5 minutes
+
+  const child = spawn(command, args, {
+    cwd,
+    env: { ...process.env, ...env },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  /** @type {TerminalHandle} */
+  const handle = {
+    id: terminalId,
+    process: child,
+    agent: config.agent,
+    taskId: config.taskId,
+    startedAt: new Date().toISOString(),
+    status: 'running',
+    exitCode: null,
+    stdout: [],
+    stderr: [],
+    timeout,
+  };
+
+  // Capture output
+  if (child.stdout) {
+    child.stdout.on('data', (chunk) => {
+      handle.stdout.push(chunk.toString());
+    });
+  }
+  if (child.stderr) {
+    child.stderr.on('data', (chunk) => {
+      handle.stderr.push(chunk.toString());
+    });
+  }
+
+  child.on('exit', (code) => {
+    handle.status = 'exited';
+    handle.exitCode = code;
+  });
+
+  child.on('error', (err) => {
+    handle.status = 'exited';
+    handle.exitCode = -1;
+    handle.stderr.push(`spawn error: ${err.message}`);
+  });
+
+  return handle;
+}
+
+/**
+ * Spawn a group of terminals concurrently.
+ * Validates write scopes before spawning to prevent conflicts.
+ *
+ * @param {SpawnConfig[]} configs
+ * @returns {{ groupId: string, terminals: TerminalHandle[], startedAt: string }}
+ * @throws {Error} When write scope conflicts are detected
+ */
+export function spawnParallelGroup(configs) {
+  if (!Array.isArray(configs) || configs.length === 0) {
+    throw new Error('spawnParallelGroup requires a non-empty array of configs');
+  }
+
+  const validation = validateWriteScopes(configs);
+  if (!validation.valid) {
+    const details = validation.conflicts
+      .map(c => `${c.agents.join(' vs ')} on ${c.path}`)
+      .join('; ');
+    throw new Error(`Write scope conflicts detected: ${details}`);
+  }
+
+  const groupId = `group-${Date.now()}`;
+  const terminals = configs.map(cfg => spawnTerminal(cfg));
+
+  return {
+    groupId,
+    terminals,
+    startedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Gracefully kill a spawned terminal.
+ * Sends SIGTERM first; if the process is still alive after 5 seconds,
+ * escalates to SIGKILL.
+ *
+ * @param {TerminalHandle} handle
+ * @returns {Promise<{ killed: boolean, exitCode: number|null }>}
+ */
+export function killTerminal(handle) {
+  if (!handle || !handle.process) {
+    return Promise.resolve({ killed: false, exitCode: handle?.exitCode ?? null });
+  }
+
+  if (handle.status === 'exited') {
+    return Promise.resolve({ killed: false, exitCode: handle.exitCode });
+  }
+
+  return new Promise((resolve) => {
+    const forceKillTimer = setTimeout(() => {
+      try {
+        handle.process.kill('SIGKILL');
+      } catch {
+        // already dead -- ignore
+      }
+    }, 5000);
+
+    handle.process.once('exit', (code) => {
+      clearTimeout(forceKillTimer);
+      handle.status = 'killed';
+      handle.exitCode = code;
+      resolve({ killed: true, exitCode: code });
+    });
+
+    try {
+      handle.process.kill('SIGTERM');
+    } catch {
+      clearTimeout(forceKillTimer);
+      handle.status = 'killed';
+      resolve({ killed: false, exitCode: handle.exitCode });
+    }
+  });
+}
+
+/**
+ * Return the current status snapshot of a terminal.
+ *
+ * @param {TerminalHandle} handle
+ * @returns {{ id: string, agent: string, status: string, elapsed: number, exitCode: number|null }}
+ */
+export function getTerminalStatus(handle) {
+  if (!handle) {
+    return { id: 'unknown', agent: 'unknown', status: 'unknown', elapsed: 0, exitCode: null };
+  }
+
+  const elapsed = Date.now() - new Date(handle.startedAt).getTime();
+
+  return {
+    id: handle.id,
+    agent: handle.agent,
+    status: handle.status,
+    elapsed,
+    exitCode: handle.exitCode,
+  };
+}

package/src/upgrade/checker.js

@@ -61,7 +61,7 @@ export async function checkForUpdate(targetDir, cliVersion) {
 
 /**
  * Get changelog between versions
- * In v1, returns placeholder. Future: read from CHANGELOG.md or API
+ * In v1, returns placeholder. Future: read from docs/CHANGELOG.md or API
  */
 function getChangelog(fromVersion, toVersion) {
   return [

package/src/wizard/i18n.js

@@ -26,7 +26,7 @@ const FALLBACK_EN = {
     agents_count: '13 agent definitions (CLARITY, BUILD, DEPLOY phases)',
     workflows_count: '5 workflow blueprints',
     templates_count: '5 templates (PRD, Brownfield PRD, Architecture, Task, QA Gate)',
-    constitution: 'Constitution (16 Articles + Preamble)',
+    constitution: 'Constitution (17 Articles + Preamble)',
     session_mgmt: 'Session management system',
     quality_gates: 'Quality gates (4-tier validation)',
     proceed: 'Proceed with installation?',
@@ -34,7 +34,7 @@ const FALLBACK_EN = {
     created_chati: 'Created .chati/ session directory',
     created_framework: 'Created chati.dev/ system directory (agents, templates, workflows)',
     created_commands: 'Created .claude/commands/ (thin router)',
-    installed_constitution: 'Installed Constitution (Articles I-XVI)',
+    installed_constitution: 'Installed Constitution (Articles I-XVII)',
     created_session: 'Created session.yaml schema',
     created_claude_md: 'Created CLAUDE.md',
     configured_mcps: 'Configured MCPs:',
@@ -42,7 +42,7 @@ const FALLBACK_EN = {
     agents_valid: 'All 13 agents implement 8 protocols',
     handoff_ok: 'Handoff protocol: OK',
     validation_ok: 'Self-validation criteria: OK',
-    constitution_ok: 'Constitution: 16 articles verified',
+    constitution_ok: 'Constitution: 17 articles verified',
     created_memories: 'Created .chati/memories/ (Memory Layer)',
     installed_intelligence: 'Installed Intelligence Layer (Context Engine, Memory, Registry)',
     intelligence_valid: 'Intelligence: 6 spec files verified',