specdacular 0.10.0 → 0.11.0

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');
+  });
+});

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

@@ -0,0 +1,66 @@
+import { describe, it, before, after } from 'node:test';
+import { strict as a } from 'node:assert';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { TemplateManager } from '../template-manager.js';
+import { Paths } from '../paths.js';
+
+describe('TemplateManager', () => {
+  let tempDir;
+  let paths;
+  let tm;
+
+  before(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'specd-tm-test-'));
+    paths = new Paths(tempDir);
+
+    // Create global templates
+    mkdirSync(paths.agentTemplatesDir, { recursive: true });
+    mkdirSync(paths.pipelineTemplatesDir, { recursive: true });
+
+    writeFileSync(
+      join(paths.agentTemplatesDir, 'claude-planner.json'),
+      JSON.stringify({ cmd: 'claude -p', system_prompt: 'global planner' })
+    );
+    writeFileSync(
+      join(paths.pipelineTemplatesDir, 'default.json'),
+      JSON.stringify({ name: 'default', stages: [{ stage: 'plan', agent: 'claude-planner' }] })
+    );
+
+    // Create per-project override
+    const projectAgentsDir = join(paths.projectsDir, 'proj1', 'agents');
+    mkdirSync(projectAgentsDir, { recursive: true });
+    writeFileSync(
+      join(projectAgentsDir, 'claude-planner.json'),
+      JSON.stringify({ cmd: 'claude -p --model opus', system_prompt: 'custom planner' })
+    );
+
+    tm = new TemplateManager(paths);
+  });
+
+  after(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('loads global agents', () => {
+    const agents = tm.getAgents();
+    a.equal(agents['claude-planner'].system_prompt, 'global planner');
+  });
+
+  it('loads global pipelines', () => {
+    const pipelines = tm.getPipelines();
+    a.equal(pipelines['default'].stages.length, 1);
+  });
+
+  it('returns per-project agent override when present', () => {
+    const agents = tm.getAgents('proj1');
+    a.equal(agents['claude-planner'].system_prompt, 'custom planner');
+    a.equal(agents['claude-planner'].cmd, 'claude -p --model opus');
+  });
+
+  it('falls back to global when no per-project override', () => {
+    const agents = tm.getAgents('proj-no-overrides');
+    a.equal(agents['claude-planner'].system_prompt, 'global planner');
+  });
+});

package/runner/main/worktree/manager.js

@@ -0,0 +1,95 @@
+// runner/main/worktree/manager.js
+import { execSync, execFileSync } from 'child_process';
+import { existsSync, mkdirSync, rmSync } from 'fs';
+import { join, basename } from 'path';
+import { tmpdir } from 'os';
+
+export class WorktreeManager {
+  constructor(repoDir) {
+    this.repoDir = repoDir;
+    this.worktreesDir = join(tmpdir(), 'specd-worktrees', basename(repoDir));
+    this.active = new Map();
+  }
+
+  create(taskId) {
+    const branch = `specd/${taskId}`;
+    const worktreePath = join(this.worktreesDir, taskId);
+
+    mkdirSync(this.worktreesDir, { recursive: true });
+
+    // Create branch from current HEAD
+    try {
+      execSync(`git branch ${branch}`, { cwd: this.repoDir, stdio: 'pipe' });
+    } catch {
+      // Branch may already exist
+    }
+
+    execSync(`git worktree add "${worktreePath}" ${branch}`, {
+      cwd: this.repoDir,
+      stdio: 'pipe',
+    });
+
+    this.active.set(taskId, worktreePath);
+    return worktreePath;
+  }
+
+  remove(taskId, deleteBranch = false) {
+    const worktreePath = this.active.get(taskId);
+    if (!worktreePath) return;
+
+    execSync(`git worktree remove "${worktreePath}" --force`, {
+      cwd: this.repoDir,
+      stdio: 'pipe',
+    });
+
+    if (deleteBranch) {
+      try {
+        execSync(`git branch -D specd/${taskId}`, { cwd: this.repoDir, stdio: 'pipe' });
+      } catch {
+        // Branch may not exist
+      }
+    }
+
+    this.active.delete(taskId);
+  }
+
+  hasChanges(taskId) {
+    const worktreePath = this.active.get(taskId);
+    if (!worktreePath) return false;
+
+    try {
+      const base = execSync('git merge-base HEAD main', { cwd: worktreePath, encoding: 'utf-8' }).trim();
+      const head = execSync('git rev-parse HEAD', { cwd: worktreePath, encoding: 'utf-8' }).trim();
+      return base !== head;
+    } catch {
+      return false;
+    }
+  }
+
+  createPR(taskId, taskName, summary) {
+    const worktreePath = this.active.get(taskId);
+    if (!worktreePath) return null;
+
+    const branch = `specd/${taskId}`;
+
+    try {
+      execFileSync('git', ['push', '-u', 'origin', branch], { cwd: worktreePath, stdio: 'pipe' });
+      const prUrl = execFileSync(
+        'gh', ['pr', 'create', '--title', taskName, '--body', summary, '--head', branch],
+        { cwd: worktreePath, encoding: 'utf-8' }
+      ).trim();
+      return prUrl;
+    } catch (err) {
+      console.error(`PR creation failed for ${taskId}:`, err.message);
+      return null;
+    }
+  }
+
+  getPath(taskId) {
+    return this.active.get(taskId) || null;
+  }
+
+  listActive() {
+    return [...this.active.keys()];
+  }
+}

package/runner/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@specd/runner",
+  "version": "0.2.0",
+  "description": "Specd Runner — Electron desktop app for autonomous agent orchestration",
+  "type": "module",
+  "main": "main/index.js",
+  "scripts": {
+    "start": "electron .",
+    "dev": "NODE_ENV=development electron .",
+    "build:renderer": "cd renderer && npm run build"
+  },
+  "dependencies": {
+    "express": "^4.21.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "electron": "^34.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/runner/preload.js

@@ -0,0 +1,19 @@
+const { contextBridge, ipcRenderer } = require('electron');
+
+const ALLOWED_CHANNELS = new Set([
+  'get-projects', 'get-project-status', 'get-tasks',
+  'get-task', 'create-task', 'retry-task', 'get-task-logs', 'get-config',
+]);
+
+contextBridge.exposeInMainWorld('specd', {
+  invoke: (channel, ...args) => {
+    if (!ALLOWED_CHANNELS.has(channel)) throw new Error(`Blocked IPC channel: ${channel}`);
+    return ipcRenderer.invoke(channel, ...args);
+  },
+  on: (channel, callback) => {
+    if (!ALLOWED_CHANNELS.has(channel)) throw new Error(`Blocked IPC channel: ${channel}`);
+    const subscription = (_event, ...args) => callback(...args);
+    ipcRenderer.on(channel, subscription);
+    return () => ipcRenderer.removeListener(channel, subscription);
+  },
+});

package/specdacular/HELP.md

@@ -9,6 +9,7 @@
 | Command | Description |
 |---------|-------------|
 | `/specd.new [name]` | Initialize a task, start first discussion |
+| `/specd.new-project [name]` | Bootstrap a new project from idea to structured plan |
 | `/specd.continue [name] [--interactive\|--auto]` | Continue task lifecycle — picks up where you left off |
 
 | `/specd.toolbox [<name>]` | Advanced task operations |
@@ -17,8 +18,10 @@
 
 | Command | Description |
 |---------|-------------|
-| `/specd.codebase.map` | Analyze codebase with parallel agents → AI-optimized docs |
-| `/specd.codebase.review` | Review and edit codebase context files section by section |
+| `/specd.best-practices` | Detect tech stack and generate best practices reference doc |
+| `/specd.docs` | Generate topic-based docs and CLAUDE.md routing table |
+| `/specd.docs.review` | Review and audit docs for accuracy, staleness, and coverage gaps |
+| `/specd.generate-skills.learn` | Generate a /learn skill that captures lessons into project docs |
 | `/specd.config` | Configure auto-commit settings for docs and code |
 | `/specd.status [--all]` | Show task status dashboard |
 | `/specd.help` | Show this help |
@@ -32,6 +35,11 @@
 /specd.new → /specd.continue → continue → continue → done
 ```
 
+**For new projects (greenfield):**
+```
+/specd.new-project → (questioning → research → requirements → roadmap → scaffold)
+```
+
 **You only need three commands:**
 
 1. **`/specd.new [name]`** — Start here. Creates task folder, asks initial questions.
@@ -41,7 +49,7 @@
    - Works across context windows — reads state fresh each time
    - Modes: default (auto-runs, pauses at phase steps), `--interactive` (prompt at each step), `--auto` (run everything)
 3. **`/specd.toolbox [name]`** — Direct access to task operations: Discuss, Research, Plan, Execute, Review
-4. **`/specd.codebase.review`** — Review and edit codebase context files section by section
+4. **`/specd.docs.review`** — Review and audit docs for accuracy, staleness, and coverage gaps
 
 ### Quick Start
 
@@ -119,17 +127,18 @@ Hooks are markdown workflow files that run before and after pipeline steps. They
 ## Codebase Documentation
 
 ```
-/specd.codebase.map
+/specd.docs
 ```
 
-Spawns 4 parallel agents to analyze your codebase and creates `.specd/codebase/`:
+Spawns 4 parallel agents to analyze your codebase, then merges their outputs into topic-specific docs in `docs/` and writes a `CLAUDE.md` routing table:
+
+| File | What it contains |
+|------|------------------|
+| **CLAUDE.md** | Routing table — "Working on X? Read docs/Y.md" |
+| **docs/rules.md** | Always-true project rules (imports, naming, conventions) |
+| **docs/{topic}.md** | Topic-specific patterns and guidance (dynamic) |
 
-| Document | What it contains |
-|----------|------------------|
-| **MAP.md** | Navigation: modules, functions, entry points |
-| **PATTERNS.md** | Code examples: services, errors, testing |
-| **STRUCTURE.md** | Organization: where to put new code |
-| **CONCERNS.md** | Warnings: gotchas, anti-patterns, debt |
+Review existing docs with `/specd.docs.review` — checks accuracy, staleness, and coverage gaps.
 
 ---