specdacular 0.10.0 → 0.11.0

package/runner/main/agent/parser.js

@@ -0,0 +1,39 @@
+import { EventEmitter } from 'events';
+
+export class StreamParser extends EventEmitter {
+  constructor() {
+    super();
+    this.inBlock = null;
+    this.blockLines = [];
+  }
+
+  feed(line) {
+    if (line.startsWith('```specd-status')) {
+      this.inBlock = 'status';
+      this.blockLines = [];
+      return;
+    }
+    if (line.startsWith('```specd-result')) {
+      this.inBlock = 'result';
+      this.blockLines = [];
+      return;
+    }
+    if (line === '```' && this.inBlock) {
+      const content = this.blockLines.join('\n');
+      try {
+        const parsed = JSON.parse(content);
+        this.emit(this.inBlock, parsed);
+      } catch (err) {
+        this.emit('error', err);
+      }
+      this.inBlock = null;
+      this.blockLines = [];
+      return;
+    }
+    if (this.inBlock) {
+      this.blockLines.push(line);
+    } else {
+      this.emit('output', line);
+    }
+  }
+}

package/runner/main/agent/runner.js

@@ -0,0 +1,137 @@
+import { spawn } from 'child_process';
+import { EventEmitter } from 'events';
+import { createWriteStream } from 'fs';
+import { StreamParser } from './parser.js';
+
+export class AgentRunner extends EventEmitter {
+  constructor({ cmd, input_mode, output_format, system_prompt, timeout, stuck_timeout }) {
+    super();
+    this.cmd = cmd;
+    this.inputMode = input_mode || 'stdin';
+    this.outputFormat = output_format || 'stream_json';
+    this.systemPrompt = system_prompt || '';
+    this.timeout = (timeout || 3600) * 1000;
+    this.stuckTimeout = (stuck_timeout || 1800) * 1000;
+  }
+
+  async run(prompt, { cwd, logPath } = {}) {
+    return new Promise((resolve, reject) => {
+      const fullPrompt = this.systemPrompt ? `${this.systemPrompt}\n\n${prompt}` : prompt;
+      const args = this.cmd.split(' ').slice(1);
+      const bin = this.cmd.split(' ')[0];
+
+      const proc = spawn(bin, args, {
+        cwd,
+        shell: true,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+      });
+
+      const logStream = logPath ? createWriteStream(logPath, { flags: 'a' }) : null;
+      let lastOutputAt = Date.now();
+      let result = null;
+
+      const parser = new StreamParser();
+      parser.on('status', (s) => {
+        lastOutputAt = Date.now();
+        this.emit('status', s);
+      });
+      parser.on('result', (r) => {
+        lastOutputAt = Date.now();
+        result = r;
+        this.emit('result', r);
+      });
+      parser.on('output', (line) => {
+        lastOutputAt = Date.now();
+        this.emit('output', line);
+      });
+
+      const handleLine = (line) => {
+        if (logStream) logStream.write(line + '\n');
+
+        if (this.outputFormat === 'stream_json') {
+          try {
+            const event = JSON.parse(line);
+            if (event.type === 'assistant' && event.message?.content) {
+              for (const block of event.message.content) {
+                if (block.type === 'text') {
+                  for (const textLine of block.text.split('\n')) {
+                    parser.feed(textLine);
+                  }
+                }
+              }
+            } else if (event.type === 'result' && event.result) {
+              for (const block of event.result) {
+                if (block.type === 'text') {
+                  for (const textLine of block.text.split('\n')) {
+                    parser.feed(textLine);
+                  }
+                }
+              }
+            }
+          } catch {
+            parser.feed(line);
+          }
+        } else {
+          parser.feed(line);
+        }
+      };
+
+      let stdout = '';
+      proc.stdout.on('data', (chunk) => {
+        stdout += chunk.toString();
+        const lines = stdout.split('\n');
+        stdout = lines.pop();
+        for (const line of lines) {
+          if (line.trim()) handleLine(line.trim());
+        }
+      });
+
+      proc.stderr.on('data', (chunk) => {
+        if (logStream) logStream.write(`[stderr] ${chunk}`);
+      });
+
+      if (this.inputMode === 'stdin') {
+        proc.stdin.write(fullPrompt);
+        proc.stdin.end();
+      }
+
+      // Global timeout
+      const globalTimer = setTimeout(() => {
+        proc.kill('SIGTERM');
+        setTimeout(() => proc.kill('SIGKILL'), 5000);
+      }, this.timeout);
+
+      // Stuck detection
+      const stuckCheck = setInterval(() => {
+        if (Date.now() - lastOutputAt > this.stuckTimeout) {
+          this.emit('error', new Error('Agent stuck — no output'));
+          proc.kill('SIGTERM');
+          setTimeout(() => proc.kill('SIGKILL'), 5000);
+        }
+      }, 30000);
+
+      proc.on('close', (code) => {
+        clearTimeout(globalTimer);
+        clearInterval(stuckCheck);
+        if (logStream) logStream.end();
+        if (stdout.trim()) handleLine(stdout.trim());
+
+        if (result) {
+          resolve(result);
+        } else if (code === 0) {
+          resolve({ status: 'success', summary: 'Agent completed without explicit result' });
+        } else {
+          resolve({ status: 'failure', summary: `Agent exited with code ${code}` });
+        }
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(globalTimer);
+        clearInterval(stuckCheck);
+        if (logStream) logStream.end();
+        reject(err);
+      });
+    });
+  }
+}

package/runner/main/agent/template.js

@@ -0,0 +1,16 @@
+export function resolveTemplate(template, variables) {
+  return template.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
+    const value = path.trim().split('.').reduce((obj, key) => obj?.[key], variables);
+    return value !== undefined ? String(value) : match;
+  });
+}
+
+export function buildTemplateContext(task, stage, pipeline, paths) {
+  return {
+    task: { id: task.id, name: task.name, spec: task.spec || '' },
+    stage: { name: stage.stage, index: stage.index, total: stage.total },
+    pipeline: { name: pipeline.name },
+    status_file: paths?.statusJson || '',
+    log_dir: paths?.logsDir || '',
+  };
+}

package/runner/main/bootstrap.js

@@ -0,0 +1,69 @@
+import { mkdirSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const DEFAULT_CONFIG = {
+  server: { port: 3700 },
+  notifications: { telegram: { enabled: false } },
+  defaults: {
+    pipeline: 'default',
+    failure_policy: 'skip',
+    timeout: 3600,
+    stuck_timeout: 1800,
+    max_parallel: 1,
+  },
+};
+
+const DEFAULT_AGENTS = {
+  'claude-planner': {
+    cmd: 'claude -p --dangerously-skip-permissions',
+    input_mode: 'stdin',
+    output_format: 'stream_json',
+    system_prompt: 'You are a feature planner working on: {{task.name}} ({{task.id}})\nPipeline: {{pipeline.name}} | Stage: {{stage.name}} ({{stage.index}}/{{stage.total}})\n\nResearch the codebase thoroughly, then create a detailed implementation plan.\n\nEmit progress:\n```specd-status\n{"task_id":"{{task.id}}","stage":"{{stage.name}}","progress":"...","percent":0}\n```\n\nWhen done:\n```specd-result\n{"status":"success","summary":"...","files_changed":[],"issues":[]}\n```',
+  },
+  'claude-implementer': {
+    cmd: 'claude -p --dangerously-skip-permissions',
+    input_mode: 'stdin',
+    output_format: 'stream_json',
+    system_prompt: 'You are an implementer working on: {{task.name}} ({{task.id}})\nPipeline: {{pipeline.name}} | Stage: {{stage.name}} ({{stage.index}}/{{stage.total}})\n\nImplement the plan from the previous stage. Write clean, tested code.\n\nEmit progress:\n```specd-status\n{"task_id":"{{task.id}}","stage":"{{stage.name}}","progress":"...","percent":0}\n```\n\nWhen done:\n```specd-result\n{"status":"success","summary":"...","files_changed":[],"issues":[]}\n```',
+  },
+  'claude-reviewer': {
+    cmd: 'claude -p --dangerously-skip-permissions',
+    input_mode: 'stdin',
+    output_format: 'stream_json',
+    system_prompt: 'You are a code reviewer for: {{task.name}} ({{task.id}})\nPipeline: {{pipeline.name}} | Stage: {{stage.name}} ({{stage.index}}/{{stage.total}})\n\nReview the implementation from the previous stage. Check for bugs, style, tests.\n\nEmit progress:\n```specd-status\n{"task_id":"{{task.id}}","stage":"{{stage.name}}","progress":"...","percent":0}\n```\n\nWhen done:\n```specd-result\n{"status":"success","summary":"...","files_changed":[],"issues":[]}\n```',
+  },
+};
+
+const DEFAULT_PIPELINE = {
+  name: 'default',
+  stages: [
+    { stage: 'plan', agent: 'claude-planner', critical: true },
+    { stage: 'implement', agent: 'claude-implementer', critical: true },
+    { stage: 'review', agent: 'claude-reviewer', on_fail: 'retry', max_retries: 2 },
+  ],
+};
+
+function writeIfMissing(filePath, data) {
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, JSON.stringify(data, null, 2));
+  }
+}
+
+export async function bootstrap(paths) {
+  // Create directories
+  mkdirSync(paths.agentTemplatesDir, { recursive: true });
+  mkdirSync(paths.pipelineTemplatesDir, { recursive: true });
+  mkdirSync(paths.projectsDir, { recursive: true });
+
+  // Write default files
+  writeIfMissing(paths.db, { projects: [] });
+  writeIfMissing(paths.config, DEFAULT_CONFIG);
+
+  // Write default agent templates
+  for (const [name, agent] of Object.entries(DEFAULT_AGENTS)) {
+    writeIfMissing(join(paths.agentTemplatesDir, `${name}.json`), agent);
+  }
+
+  // Write default pipeline template
+  writeIfMissing(join(paths.pipelineTemplatesDir, 'default.json'), DEFAULT_PIPELINE);
+}

package/runner/main/db.js

@@ -0,0 +1,45 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { randomUUID } from 'crypto';
+
+export class ProjectDB {
+  constructor(dbPath) {
+    this.dbPath = dbPath;
+    this.data = JSON.parse(readFileSync(dbPath, 'utf-8'));
+  }
+
+  register(name, folderPath) {
+    const project = {
+      id: randomUUID().slice(0, 8),
+      name,
+      path: folderPath,
+      active: true,
+      registeredAt: new Date().toISOString(),
+    };
+    this.data.projects.push(project);
+    this._save();
+    return project;
+  }
+
+  unregister(id) {
+    this.data.projects = this.data.projects.filter(p => p.id !== id);
+    this._save();
+  }
+
+  get(id) {
+    return this.data.projects.find(p => p.id === id) || null;
+  }
+
+  findByPath(folderPath) {
+    return this.data.projects.find(p =>
+      folderPath === p.path || folderPath.startsWith(p.path + '/')
+    ) || null;
+  }
+
+  list() {
+    return this.data.projects;
+  }
+
+  _save() {
+    writeFileSync(this.dbPath, JSON.stringify(this.data, null, 2));
+  }
+}

package/runner/main/index.js

@@ -0,0 +1,103 @@
+// runner/main/index.js
+import { app, BrowserWindow } from 'electron';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { Paths } from './paths.js';
+import { bootstrap } from './bootstrap.js';
+import { ProjectDB } from './db.js';
+import { Orchestrator } from './orchestrator.js';
+import { createServer } from './server/index.js';
+import { setupIpc } from './ipc.js';
+
+let mainWindow;
+const paths = new Paths();
+const orchestrators = new Map();
+let db;
+let config;
+let server;
+
+function getContext() {
+  return { db, config, paths, orchestrators };
+}
+
+async function initBackend() {
+  await bootstrap(paths);
+
+  db = new ProjectDB(paths.db);
+  config = JSON.parse(readFileSync(paths.config, 'utf-8'));
+
+  // Initialize orchestrators for active projects
+  for (const project of db.list().filter(p => p.active)) {
+    // Ensure project.json exists (may not if registered via CLI only)
+    const projectPaths = paths.forProject(project.id);
+    mkdirSync(projectPaths.dir, { recursive: true });
+    if (!existsSync(projectPaths.projectJson)) {
+      writeFileSync(projectPaths.projectJson, JSON.stringify({
+        name: project.name,
+        path: project.path,
+        registeredAt: project.registeredAt,
+      }, null, 2));
+    }
+
+    const orch = new Orchestrator({ projectId: project.id, paths, config });
+    orch.init();
+    orchestrators.set(project.id, orch);
+  }
+
+  // Start API server
+  server = createServer(getContext);
+  const port = config.server?.port || 3700;
+  await server.start(port);
+
+  // Wire orchestrators to WebSocket
+  for (const orch of orchestrators.values()) {
+    server.wireOrchestrator(orch);
+  }
+
+  // Start orchestrator loops
+  for (const orch of orchestrators.values()) {
+    orch.startLoop().catch(err => console.error('Loop error:', err));
+  }
+}
+
+function createWindow() {
+  mainWindow = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    webPreferences: {
+      preload: join(__dirname, '..', 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+    },
+  });
+
+  if (process.env.NODE_ENV === 'development') {
+    mainWindow.loadURL('http://localhost:5173');
+  } else {
+    mainWindow.loadFile(join(__dirname, '..', 'renderer', 'dist', 'index.html'));
+  }
+}
+
+app.whenReady().then(async () => {
+  setupIpc(getContext);
+  await initBackend();
+  createWindow();
+});
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') app.quit();
+});
+
+app.on('activate', () => {
+  if (BrowserWindow.getAllWindows().length === 0) createWindow();
+});
+
+app.on('before-quit', () => {
+  for (const orch of orchestrators.values()) {
+    orch.stop();
+  }
+  if (server) server.stop();
+});

package/runner/main/ipc.js

@@ -0,0 +1,72 @@
+// runner/main/ipc.js
+import { ipcMain } from 'electron';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export function setupIpc(getContext) {
+  ipcMain.handle('get-projects', () => {
+    const { db, orchestrators } = getContext();
+    return db.list().map(p => {
+      const orch = orchestrators.get(p.id);
+      const tasks = orch ? orch.getTasks() : [];
+      return {
+        ...p,
+        taskCounts: {
+          total: tasks.length,
+          ready: tasks.filter(t => t.status === 'ready').length,
+          running: tasks.filter(t => t.status === 'in_progress').length,
+          done: tasks.filter(t => t.status === 'done').length,
+          failed: tasks.filter(t => t.status === 'failed').length,
+        },
+      };
+    });
+  });
+
+  ipcMain.handle('get-project-status', (event, projectId) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(projectId);
+    if (!orch) return null;
+    return orch.stateManager.getState();
+  });
+
+  ipcMain.handle('get-tasks', (event, projectId) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(projectId);
+    if (!orch) return [];
+    return orch.getTasks();
+  });
+
+  ipcMain.handle('get-task', (event, projectId, taskId) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(projectId);
+    if (!orch) return null;
+    return orch.getTask(taskId);
+  });
+
+  ipcMain.handle('create-task', (event, projectId, taskData) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(projectId);
+    if (!orch) return null;
+    return orch.createTask(taskData);
+  });
+
+  ipcMain.handle('retry-task', (event, projectId, taskId) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(projectId);
+    if (!orch) return null;
+    return orch.updateTask(taskId, { status: 'ready' });
+  });
+
+  ipcMain.handle('get-task-logs', (event, projectId, taskId) => {
+    const { paths } = getContext();
+    const logPath = join(paths.forProject(projectId).logsDir, `${taskId}.log`);
+    if (!existsSync(logPath)) return { lines: [] };
+    const content = readFileSync(logPath, 'utf-8');
+    return { lines: content.split('\n').slice(-200) };
+  });
+
+  ipcMain.handle('get-config', () => {
+    const { config } = getContext();
+    return config;
+  });
+}

package/runner/main/notifications/telegram.js

@@ -0,0 +1,45 @@
+// runner/main/notifications/telegram.js
+import { request } from 'https';
+
+export class TelegramNotifier {
+  constructor({ bot_token, chat_id, notify_on }) {
+    this.botToken = bot_token;
+    this.chatId = chat_id;
+    this.notifyOn = new Set(notify_on || ['task_complete', 'task_failed']);
+  }
+
+  async onTaskComplete(taskId, taskName, summary) {
+    if (!this.notifyOn.has('task_complete')) return;
+    await this._send(`✅ *Task Complete*\n*${taskName}* (${taskId})\n${summary}`);
+  }
+
+  async onTaskFailed(taskId, taskName, stage, error) {
+    if (!this.notifyOn.has('task_failed')) return;
+    await this._send(`❌ *Task Failed*\n*${taskName}* (${taskId})\nStage: ${stage}\nError: ${error}`);
+  }
+
+  async onStuck(taskId, taskName, stage) {
+    if (!this.notifyOn.has('task_stuck')) return;
+    await this._send(`⚠️ *Agent Stuck*\n*${taskName}* (${taskId})\nStage: ${stage}`);
+  }
+
+  async onNeedsInput(taskId, taskName, stage, question) {
+    if (!this.notifyOn.has('needs_input')) return;
+    await this._send(`❓ *Input Needed*\n*${taskName}* (${taskId})\nStage: ${stage}\n${question}`);
+  }
+
+  _send(text) {
+    return new Promise((resolve) => {
+      const data = JSON.stringify({ chat_id: this.chatId, text, parse_mode: 'Markdown' });
+      const req = request({
+        hostname: 'api.telegram.org',
+        path: `/bot${this.botToken}/sendMessage`,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) },
+      }, resolve);
+      req.on('error', (err) => { console.error('Telegram error:', err.message); resolve(); });
+      req.write(data);
+      req.end();
+    });
+  }
+}