specdacular 0.10.1 → 0.11.0

package/runner/main/paths.js

@@ -0,0 +1,36 @@
+import { join } from 'path';
+import { homedir, platform } from 'os';
+
+export class Paths {
+  constructor(root) {
+    this.root = root || Paths.defaultRoot();
+  }
+
+  static defaultRoot() {
+    if (platform() === 'darwin') {
+      return join(homedir(), 'Library', 'Application Support', 'Specd');
+    }
+    return join(homedir(), '.config', 'specd');
+  }
+
+  get db() { return join(this.root, 'db.json'); }
+  get config() { return join(this.root, 'config.json'); }
+  get templatesDir() { return join(this.root, 'templates'); }
+  get agentTemplatesDir() { return join(this.root, 'templates', 'agents'); }
+  get pipelineTemplatesDir() { return join(this.root, 'templates', 'pipelines'); }
+  get projectsDir() { return join(this.root, 'projects'); }
+  get electronDir() { return join(this.root, 'electron'); }
+
+  forProject(projectId) {
+    const dir = join(this.root, 'projects', projectId);
+    return {
+      dir,
+      projectJson: join(dir, 'project.json'),
+      statusJson: join(dir, 'status.json'),
+      tasksDir: join(dir, 'tasks'),
+      logsDir: join(dir, 'logs'),
+      agentsDir: join(dir, 'agents'),
+      pipelinesDir: join(dir, 'pipelines'),
+    };
+  }
+}

package/runner/main/pipeline/resolver.js

@@ -0,0 +1,20 @@
+// runner/main/pipeline/resolver.js
+export function resolvePipeline(pipelineName, pipelines, stageOverrides, defaults) {
+  const pipeline = pipelines[pipelineName];
+  if (!pipeline) throw new Error(`Pipeline not found: ${pipelineName}`);
+
+  const stages = pipeline.stages.map((stage, index) => {
+    const override = stageOverrides?.[stage.stage] || {};
+    return {
+      ...stage,
+      ...override,
+      timeout: stage.timeout || defaults?.timeout || 3600,
+      on_fail: stage.on_fail || defaults?.failure_policy || 'skip',
+      max_retries: stage.max_retries || 0,
+      index: index + 1,
+      total: pipeline.stages.length,
+    };
+  });
+
+  return { name: pipelineName, stages };
+}

package/runner/main/pipeline/sequencer.js

@@ -0,0 +1,42 @@
+// runner/main/pipeline/sequencer.js
+export class StageSequencer {
+  constructor({ stages, createRunner, onStageStart, onStageComplete }) {
+    this.stages = stages;
+    this.createRunner = createRunner;
+    this.onStageStart = onStageStart;
+    this.onStageComplete = onStageComplete;
+  }
+
+  async run() {
+    const results = [];
+
+    for (const stage of this.stages) {
+      const maxAttempts = 1 + (stage.max_retries || 0);
+      let stageResult = null;
+
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const runner = this.createRunner(stage);
+        await this.onStageStart(stage, attempt);
+
+        try {
+          stageResult = await runner.run('');
+        } catch (err) {
+          stageResult = { status: 'failure', summary: err.message };
+        }
+
+        await this.onStageComplete(stage, stageResult, attempt);
+
+        if (stageResult.status === 'success') break;
+        if (stageResult.status === 'failure' && stage.on_fail !== 'retry') break;
+      }
+
+      results.push({ stage: stage.stage, ...stageResult });
+
+      if (stageResult.status !== 'success' && stage.critical) {
+        return { status: 'failure', results, failedStage: stage.stage };
+      }
+    }
+
+    return { status: 'success', results };
+  }
+}

package/runner/main/server/api.js

@@ -0,0 +1,125 @@
+// runner/main/server/api.js
+import { Router } from 'express';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+
+export function createApiRouter(getContext) {
+  const router = Router();
+
+  // Find project by path (for skill auto-detection) — must be before :id routes
+  router.get('/projects/by-path', (req, res) => {
+    const { db } = getContext();
+    const folderPath = req.query.path;
+    if (!folderPath) return res.status(400).json({ error: 'path query param required' });
+    const project = db.findByPath(folderPath);
+    if (!project) return res.status(404).json({ error: 'No project matches this path' });
+    res.json(project);
+  });
+
+  // List projects
+  router.get('/projects', (req, res) => {
+    const { db, orchestrators } = getContext();
+    const projects = 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,
+        },
+      };
+    });
+    res.json(projects);
+  });
+
+  // Global status
+  router.get('/status', (req, res) => {
+    const { orchestrators } = getContext();
+    const status = {};
+    for (const [id, orch] of orchestrators) {
+      status[id] = orch.stateManager.getState();
+    }
+    res.json(status);
+  });
+
+  // Project status
+  router.get('/projects/:id/status', (req, res) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(req.params.id);
+    if (!orch) return res.status(404).json({ error: 'Project not found' });
+    res.json(orch.stateManager.getState());
+  });
+
+  // List tasks
+  router.get('/projects/:id/tasks', (req, res) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(req.params.id);
+    if (!orch) return res.status(404).json({ error: 'Project not found' });
+    res.json(orch.getTasks());
+  });
+
+  // Get task
+  router.get('/projects/:id/tasks/:taskId', (req, res) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(req.params.id);
+    if (!orch) return res.status(404).json({ error: 'Project not found' });
+    const task = orch.getTask(req.params.taskId);
+    if (!task) return res.status(404).json({ error: 'Task not found' });
+    res.json(task);
+  });
+
+  // Create task
+  router.post('/projects/:id/tasks', (req, res) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(req.params.id);
+    if (!orch) return res.status(404).json({ error: 'Project not found' });
+    if (!req.body.name) return res.status(400).json({ error: 'name is required' });
+
+    const task = {
+      id: req.body.id || `task-${randomUUID().slice(0, 6)}`,
+      name: req.body.name,
+      description: req.body.description || '',
+      project_id: req.params.id,
+      working_dir: req.body.working_dir || '.',
+      pipeline: req.body.pipeline || 'default',
+      status: req.body.status || 'ready',
+      priority: req.body.priority || 10,
+      depends_on: req.body.depends_on || [],
+      spec: req.body.spec || '',
+      created_at: new Date().toISOString(),
+    };
+
+    orch.createTask(task);
+    res.status(201).json(task);
+  });
+
+  // Retry task
+  router.post('/projects/:id/tasks/:taskId/retry', (req, res) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(req.params.id);
+    if (!orch) return res.status(404).json({ error: 'Project not found' });
+
+    const task = orch.updateTask(req.params.taskId, { status: 'ready' });
+    if (!task) return res.status(404).json({ error: 'Task not found' });
+    res.json(task);
+  });
+
+  // Task logs
+  router.get('/projects/:id/tasks/:taskId/logs', (req, res) => {
+    const { paths } = getContext();
+    const logPath = join(paths.forProject(req.params.id).logsDir, `${req.params.taskId}.log`);
+    if (!existsSync(logPath)) return res.status(404).json({ error: 'Log not found' });
+
+    const content = readFileSync(logPath, 'utf-8');
+    const lines = content.split('\n');
+    const tail = parseInt(req.query.tail) || 200;
+    res.json({ lines: lines.slice(-tail) });
+  });
+
+  return router;
+}

package/runner/main/server/index.js

@@ -0,0 +1,33 @@
+// runner/main/server/index.js
+import express from 'express';
+import { createServer as createHttpServer } from 'http';
+import { createApiRouter } from './api.js';
+import { WsBroadcaster } from './websocket.js';
+
+export function createServer(getContext) {
+  const app = express();
+  app.use(express.json());
+  app.use('/api', createApiRouter(getContext));
+
+  const httpServer = createHttpServer(app);
+  const broadcaster = new WsBroadcaster(httpServer);
+
+  return {
+    start(port) {
+      return new Promise((resolve) => {
+        httpServer.listen(port, '127.0.0.1', () => {
+          console.log(`Specd API server on http://127.0.0.1:${port}`);
+          resolve();
+        });
+      });
+    },
+    stop() {
+      broadcaster.close();
+      httpServer.close();
+    },
+    broadcaster,
+    wireOrchestrator(orch) {
+      orch.on('change', (event) => broadcaster.broadcast(event));
+    },
+  };
+}

package/runner/main/server/websocket.js

@@ -0,0 +1,24 @@
+// runner/main/server/websocket.js
+import { WebSocketServer } from 'ws';
+
+export class WsBroadcaster {
+  constructor(server) {
+    this.wss = new WebSocketServer({ server });
+    this.wss.on('connection', (ws) => {
+      ws.send(JSON.stringify({ type: 'connected', timestamp: new Date().toISOString() }));
+    });
+  }
+
+  broadcast(event) {
+    const data = JSON.stringify(event);
+    for (const client of this.wss.clients) {
+      if (client.readyState === 1) {
+        client.send(data);
+      }
+    }
+  }
+
+  close() {
+    this.wss.close();
+  }
+}

package/runner/main/state/manager.js

@@ -0,0 +1,83 @@
+import { writeFileSync, existsSync, readFileSync } from 'fs';
+import { EventEmitter } from 'events';
+
+export class StateManager extends EventEmitter {
+  constructor(statusPath) {
+    super();
+    this.statusPath = statusPath;
+    this.state = existsSync(statusPath)
+      ? JSON.parse(readFileSync(statusPath, 'utf-8'))
+      : { started_at: new Date().toISOString(), tasks: {} };
+  }
+
+  getState() {
+    return this.state;
+  }
+
+  registerTask(taskId, { name, pipeline }) {
+    this.state.tasks[taskId] = {
+      name,
+      status: 'queued',
+      current_stage: null,
+      pipeline,
+      pr_url: null,
+      stages: [],
+    };
+    this._emit('task_registered', { taskId, name });
+  }
+
+  updateTaskStatus(taskId, status) {
+    this.state.tasks[taskId].status = status;
+    this._emit('task_status_changed', { taskId, status });
+  }
+
+  startStage(taskId, { stage, agent }) {
+    const task = this.state.tasks[taskId];
+    task.current_stage = stage;
+    task.stages.push({
+      stage,
+      agent,
+      status: 'running',
+      started_at: new Date().toISOString(),
+      duration: null,
+      summary: null,
+      live_progress: null,
+    });
+    this._emit('stage_started', { taskId, stage, agent });
+  }
+
+  updateLiveProgress(taskId, progress) {
+    const task = this.state.tasks[taskId];
+    const currentStage = task.stages[task.stages.length - 1];
+    if (currentStage) {
+      currentStage.live_progress = progress;
+      currentStage.last_output_at = new Date().toISOString();
+    }
+    this._emit('live_progress', { taskId, progress });
+  }
+
+  completeStage(taskId, status, summary) {
+    const task = this.state.tasks[taskId];
+    const currentStage = task.stages[task.stages.length - 1];
+    if (currentStage) {
+      currentStage.status = status;
+      currentStage.summary = summary;
+      const started = new Date(currentStage.started_at);
+      currentStage.duration = Math.round((Date.now() - started.getTime()) / 1000);
+    }
+    this._emit('stage_completed', { taskId, stage: currentStage?.stage, status, summary });
+  }
+
+  setPrUrl(taskId, prUrl) {
+    this.state.tasks[taskId].pr_url = prUrl;
+    this._emit('pr_created', { taskId, prUrl });
+  }
+
+  persist() {
+    writeFileSync(this.statusPath, JSON.stringify(this.state, null, 2));
+  }
+
+  _emit(type, data) {
+    this.emit('change', { type, ...data });
+  }
+}

package/runner/main/template-manager.js

@@ -0,0 +1,41 @@
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+
+export class TemplateManager {
+  constructor(paths) {
+    this.paths = paths;
+  }
+
+  getAgents(projectId) {
+    const global = this._loadDir(this.paths.agentTemplatesDir);
+    if (!projectId) return global;
+
+    const projectAgentsDir = join(this.paths.projectsDir, projectId, 'agents');
+    if (!existsSync(projectAgentsDir)) return global;
+
+    const overrides = this._loadDir(projectAgentsDir);
+    return { ...global, ...overrides };
+  }
+
+  getPipelines(projectId) {
+    const global = this._loadDir(this.paths.pipelineTemplatesDir);
+    if (!projectId) return global;
+
+    const projectPipelinesDir = join(this.paths.projectsDir, projectId, 'pipelines');
+    if (!existsSync(projectPipelinesDir)) return global;
+
+    const overrides = this._loadDir(projectPipelinesDir);
+    return { ...global, ...overrides };
+  }
+
+  _loadDir(dir) {
+    if (!existsSync(dir)) return {};
+    const result = {};
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.json')) continue;
+      const name = basename(file, '.json');
+      result[name] = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+    }
+    return result;
+  }
+}

package/runner/main/test/agent-parser.test.js

@@ -0,0 +1,44 @@
+import { describe, it } from 'node:test';
+import { strict as a } from 'node:assert';
+import { StreamParser } from '../agent/parser.js';
+
+describe('StreamParser', () => {
+  it('parses specd-status blocks', () => {
+    const parser = new StreamParser();
+    const statuses = [];
+    parser.on('status', (s) => statuses.push(s));
+
+    parser.feed('some output');
+    parser.feed('```specd-status');
+    parser.feed('{"progress":"Working","percent":50}');
+    parser.feed('```');
+
+    a.equal(statuses.length, 1);
+    a.equal(statuses[0].progress, 'Working');
+    a.equal(statuses[0].percent, 50);
+  });
+
+  it('parses specd-result blocks', () => {
+    const parser = new StreamParser();
+    const results = [];
+    parser.on('result', (r) => results.push(r));
+
+    parser.feed('```specd-result');
+    parser.feed('{"status":"success","summary":"Done"}');
+    parser.feed('```');
+
+    a.equal(results.length, 1);
+    a.equal(results[0].status, 'success');
+  });
+
+  it('emits output for non-block lines', () => {
+    const parser = new StreamParser();
+    const lines = [];
+    parser.on('output', (l) => lines.push(l));
+
+    parser.feed('hello world');
+
+    a.equal(lines.length, 1);
+    a.equal(lines[0], 'hello world');
+  });
+});

package/runner/main/test/bootstrap.test.js

@@ -0,0 +1,58 @@
+import { describe, it, before, after } from 'node:test';
+import { strict as a } from 'node:assert';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { bootstrap } from '../bootstrap.js';
+import { Paths } from '../paths.js';
+
+describe('bootstrap', () => {
+  let tempDir;
+  let paths;
+
+  before(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'specd-test-'));
+    paths = new Paths(tempDir);
+  });
+
+  after(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('creates all required directories and default files', async () => {
+    await bootstrap(paths);
+
+    a.ok(existsSync(paths.templatesDir));
+    a.ok(existsSync(paths.agentTemplatesDir));
+    a.ok(existsSync(paths.pipelineTemplatesDir));
+    a.ok(existsSync(paths.projectsDir));
+
+    a.ok(existsSync(paths.db));
+    const db = JSON.parse(readFileSync(paths.db, 'utf-8'));
+    a.deepEqual(db, { projects: [] });
+
+    a.ok(existsSync(paths.config));
+    const config = JSON.parse(readFileSync(paths.config, 'utf-8'));
+    a.equal(config.server.port, 3700);
+
+    // Default agent templates exist
+    a.ok(existsSync(join(paths.agentTemplatesDir, 'claude-planner.json')));
+    a.ok(existsSync(join(paths.agentTemplatesDir, 'claude-implementer.json')));
+    a.ok(existsSync(join(paths.agentTemplatesDir, 'claude-reviewer.json')));
+
+    // Default pipeline template exists
+    a.ok(existsSync(join(paths.pipelineTemplatesDir, 'default.json')));
+  });
+
+  it('does not overwrite existing files on second run', async () => {
+    const config = JSON.parse(readFileSync(paths.config, 'utf-8'));
+    config.server.port = 9999;
+    const { writeFileSync } = await import('fs');
+    writeFileSync(paths.config, JSON.stringify(config));
+
+    await bootstrap(paths);
+
+    const reloaded = JSON.parse(readFileSync(paths.config, 'utf-8'));
+    a.equal(reloaded.server.port, 9999);
+  });
+});

package/runner/main/test/db.test.js

@@ -0,0 +1,72 @@
+import { describe, it, before, after, beforeEach } from 'node:test';
+import { strict as a } from 'node:assert';
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { ProjectDB } from '../db.js';
+
+describe('ProjectDB', () => {
+  let tempDir;
+  let dbPath;
+  let db;
+
+  before(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'specd-db-test-'));
+    dbPath = join(tempDir, 'db.json');
+  });
+
+  beforeEach(() => {
+    writeFileSync(dbPath, JSON.stringify({ projects: [] }));
+    db = new ProjectDB(dbPath);
+  });
+
+  after(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('registers a project', () => {
+    const project = db.register('my-project', '/Users/victor/work/my-project');
+    a.equal(project.name, 'my-project');
+    a.equal(project.path, '/Users/victor/work/my-project');
+    a.equal(project.active, true);
+    a.ok(project.id);
+    a.ok(project.registeredAt);
+  });
+
+  it('lists projects', () => {
+    db.register('proj-a', '/a');
+    db.register('proj-b', '/b');
+    const list = db.list();
+    a.equal(list.length, 2);
+  });
+
+  it('gets a project by id', () => {
+    const project = db.register('my-project', '/path');
+    const found = db.get(project.id);
+    a.equal(found.name, 'my-project');
+  });
+
+  it('finds a project by path', () => {
+    db.register('my-project', '/Users/victor/work/my-project');
+    const found = db.findByPath('/Users/victor/work/my-project');
+    a.equal(found.name, 'my-project');
+  });
+
+  it('finds a project by subdirectory path', () => {
+    db.register('my-project', '/Users/victor/work');
+    const found = db.findByPath('/Users/victor/work/repo-a');
+    a.equal(found.name, 'my-project');
+  });
+
+  it('unregisters a project', () => {
+    const project = db.register('my-project', '/path');
+    db.unregister(project.id);
+    a.equal(db.list().length, 0);
+  });
+
+  it('persists to disk', () => {
+    db.register('my-project', '/path');
+    const db2 = new ProjectDB(dbPath);
+    a.equal(db2.list().length, 1);
+  });
+});

package/runner/main/test/paths.test.js

@@ -0,0 +1,29 @@
+import { describe, it } from 'node:test';
+import { strict as a } from 'node:assert';
+import { Paths } from '../paths.js';
+
+describe('Paths', () => {
+  it('returns app data dir based on platform', () => {
+    const paths = new Paths('/tmp/test-specd');
+    a.equal(paths.root, '/tmp/test-specd');
+    a.equal(paths.db, '/tmp/test-specd/db.json');
+    a.equal(paths.config, '/tmp/test-specd/config.json');
+    a.equal(paths.templatesDir, '/tmp/test-specd/templates');
+    a.equal(paths.agentTemplatesDir, '/tmp/test-specd/templates/agents');
+    a.equal(paths.pipelineTemplatesDir, '/tmp/test-specd/templates/pipelines');
+    a.equal(paths.projectsDir, '/tmp/test-specd/projects');
+    a.equal(paths.electronDir, '/tmp/test-specd/electron');
+  });
+
+  it('returns project-specific paths', () => {
+    const paths = new Paths('/tmp/test-specd');
+    const pp = paths.forProject('abc123');
+    a.equal(pp.dir, '/tmp/test-specd/projects/abc123');
+    a.equal(pp.projectJson, '/tmp/test-specd/projects/abc123/project.json');
+    a.equal(pp.statusJson, '/tmp/test-specd/projects/abc123/status.json');
+    a.equal(pp.tasksDir, '/tmp/test-specd/projects/abc123/tasks');
+    a.equal(pp.logsDir, '/tmp/test-specd/projects/abc123/logs');
+    a.equal(pp.agentsDir, '/tmp/test-specd/projects/abc123/agents');
+    a.equal(pp.pipelinesDir, '/tmp/test-specd/projects/abc123/pipelines');
+  });
+});

package/runner/main/test/state-manager.test.js

@@ -0,0 +1,72 @@
+import { describe, it, before, after, beforeEach } from 'node:test';
+import { strict as a } from 'node:assert';
+import { mkdtempSync, rmSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { StateManager } from '../state/manager.js';
+
+describe('StateManager', () => {
+  let tempDir;
+  let statusPath;
+  let sm;
+
+  before(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'specd-state-test-'));
+  });
+
+  beforeEach(() => {
+    statusPath = join(tempDir, `status-${Date.now()}.json`);
+    sm = new StateManager(statusPath);
+  });
+
+  after(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('registers a task', () => {
+    sm.registerTask('task-001', { name: 'Add dark mode', pipeline: 'default' });
+    const state = sm.getState();
+    a.equal(state.tasks['task-001'].name, 'Add dark mode');
+    a.equal(state.tasks['task-001'].status, 'queued');
+  });
+
+  it('updates task status', () => {
+    sm.registerTask('task-001', { name: 'Test', pipeline: 'default' });
+    sm.updateTaskStatus('task-001', 'in_progress');
+    a.equal(sm.getState().tasks['task-001'].status, 'in_progress');
+  });
+
+  it('tracks stages', () => {
+    sm.registerTask('task-001', { name: 'Test', pipeline: 'default' });
+    sm.startStage('task-001', { stage: 'plan', agent: 'claude-planner' });
+    const task = sm.getState().tasks['task-001'];
+    a.equal(task.current_stage, 'plan');
+    a.equal(task.stages.length, 1);
+    a.equal(task.stages[0].status, 'running');
+  });
+
+  it('completes stages with duration', () => {
+    sm.registerTask('task-001', { name: 'Test', pipeline: 'default' });
+    sm.startStage('task-001', { stage: 'plan', agent: 'claude-planner' });
+    sm.completeStage('task-001', 'success', 'Planned it');
+    const stage = sm.getState().tasks['task-001'].stages[0];
+    a.equal(stage.status, 'success');
+    a.equal(stage.summary, 'Planned it');
+    a.ok(stage.duration >= 0);
+  });
+
+  it('persists to disk', () => {
+    sm.registerTask('task-001', { name: 'Test', pipeline: 'default' });
+    sm.persist();
+    const data = JSON.parse(readFileSync(statusPath, 'utf-8'));
+    a.ok(data.tasks['task-001']);
+  });
+
+  it('emits change events', () => {
+    const events = [];
+    sm.on('change', (e) => events.push(e));
+    sm.registerTask('task-001', { name: 'Test', pipeline: 'default' });
+    a.equal(events.length, 1);
+    a.equal(events[0].type, 'task_registered');
+  });
+});