@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdk/src/workflow-agent-skills-consistency.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Contract test: every `sdd-sdk query agent-skills <slug>` invocation in
+ * `sdd/workflows/**\/*.md` must reference a slug that exists as
+ * `agents/<slug>.md` at the repository root.
+ *
+ * A mismatch produces a silent no-op at runtime — the SDK returns `""` for an
+ * unknown key, and the workflow interpolates the empty string into the spawn
+ * prompt, so any `agent_skills.<correct-slug>` configuration in
+ * `.planning/config.json` is silently ignored. This test prevents regression.
+ *
+ * Related: https://github.com/bhargavvc/sdd-cc/issues/2615
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..', '..');
+const workflowsDir = join(repoRoot, 'sdd', 'workflows');
+const agentsDir = join(repoRoot, 'agents');
+
+/**
+ * Matches a full `sdd-sdk query agent-skills <slug>` invocation and captures
+ * the slug. Requires a token boundary before `sdd-sdk` and a word boundary
+ * after the slug so that prose references (e.g. documentation mentioning the
+ * string "agent-skills") do not produce false positives. The `\s+` between
+ * tokens accepts newlines, so commands wrapped across lines still match.
+ */
+const QUERY_KEY_PATTERN = /\bsdd-sdk\s+query\s+agent-skills\s+([a-z][a-z0-9-]*)\b/g;
+
+interface QueryUsage {
+  readonly file: string;
+  readonly line: number;
+  readonly slug: string;
+}
+
+/** Recursively collects all `.md` file paths under `dir`. */
+function walkMarkdown(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      out.push(...walkMarkdown(full));
+    } else if (entry.endsWith('.md')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/** Returns the set of agent slugs defined by `<slug>.md` files in `dir`. */
+function collectAgentSlugs(dir: string): Set<string> {
+  return new Set(
+    readdirSync(dir)
+      .filter((name) => name.endsWith('.md'))
+      .map((name) => name.replace(/\.md$/, '')),
+  );
+}
+
+/**
+ * Extracts every `sdd-sdk query agent-skills <slug>` usage from the given
+ * markdown files. Runs the regex over each file's full content (not line by
+ * line) so wrapped commands still match, then resolves the 1-based line number
+ * from the match index.
+ */
+function collectQueryUsages(files: readonly string[]): QueryUsage[] {
+  const usages: QueryUsage[] = [];
+  for (const file of files) {
+    const content = readFileSync(file, 'utf8');
+    for (const match of content.matchAll(QUERY_KEY_PATTERN)) {
+      const index = match.index ?? 0;
+      const line = content.slice(0, index).split('\n').length;
+      usages.push({ file, line, slug: match[1]! });
+    }
+  }
+  return usages;
+}
+
+describe('workflow agent-skills query consistency', () => {
+  it('every `agent-skills <slug>` query refers to an existing `agents/<slug>.md`', () => {
+    const validSlugs = collectAgentSlugs(agentsDir);
+    const workflowFiles = walkMarkdown(workflowsDir);
+    const usages = collectQueryUsages(workflowFiles);
+    const invalid = usages.filter((u) => !validSlugs.has(u.slug));
+
+    const report = invalid
+      .map((u) => `  ${relative(repoRoot, u.file)}:${u.line} — unknown slug '${u.slug}'`)
+      .join('\n');
+
+    expect(
+      invalid,
+      invalid.length
+        ? `Found ${invalid.length} agent-skills query keys with no matching agents/<slug>.md:\n${report}`
+        : '',
+    ).toHaveLength(0);
+  });
+});

package/sdk/src/workstream-name-policy.ts

@@ -0,0 +1,24 @@
+/**
+ * Workstream Name Policy Module
+ *
+ * Owns SDK-side workstream validation and slug normalization.
+ */
+
+/**
+ * Validate a workstream name.
+ * Allowed: alphanumeric, hyphens, underscores, dots.
+ * Disallowed: empty, spaces, slashes, special chars, path traversal.
+ */
+export function validateWorkstreamName(name: string): boolean {
+  if (!name || name.length === 0) return false;
+  if (name.includes('..')) return false;
+  return /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+
+export function toWorkstreamSlug(name: string): string {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+

package/sdk/src/workstream-utils.ts

@@ -0,0 +1,21 @@
+/**
+ * Workstream utility functions for multi-workstream project support.
+ *
+ * When --ws <name> is provided, all .planning/ paths are routed to
+ * .planning/workstreams/<name>/ instead.
+ */
+
+import { posix } from 'node:path';
+export { validateWorkstreamName, toWorkstreamSlug } from './workstream-name-policy.js';
+
+/**
+ * Return the relative planning directory path.
+ *
+ * - Without workstream: `.planning`
+ * - With workstream: `.planning/workstreams/<name>`
+ */
+export function relPlanningPath(workstream?: string): string {
+  if (!workstream) return '.planning';
+  // Use POSIX segments so the same logical path string is used on all platforms (Windows included).
+  return posix.join('.planning', 'workstreams', workstream);
+}

package/sdk/src/ws-flag.test.ts

@@ -0,0 +1,285 @@
+/**
+ * Tests for --ws (workstream) flag support.
+ *
+ * Validates:
+ * - CLI parsing of --ws flag
+ * - Workstream name validation
+ * - SDDOptions.workstream propagation
+ * - SDDTools workstream-aware invocation
+ * - Config path resolution with workstream
+ * - ContextEngine workstream-aware planning dir
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+// ─── Workstream name validation ─────────────────────────────────────────────
+
+import { validateWorkstreamName } from './workstream-utils.js';
+
+describe('validateWorkstreamName', () => {
+  it('accepts alphanumeric names', () => {
+    expect(validateWorkstreamName('frontend')).toBe(true);
+    expect(validateWorkstreamName('backend2')).toBe(true);
+  });
+
+  it('accepts names with hyphens', () => {
+    expect(validateWorkstreamName('my-feature')).toBe(true);
+  });
+
+  it('accepts names with underscores', () => {
+    expect(validateWorkstreamName('my_feature')).toBe(true);
+  });
+
+  it('accepts names with dots', () => {
+    expect(validateWorkstreamName('v1.0')).toBe(true);
+  });
+
+  it('rejects empty strings', () => {
+    expect(validateWorkstreamName('')).toBe(false);
+  });
+
+  it('rejects names with spaces', () => {
+    expect(validateWorkstreamName('my feature')).toBe(false);
+  });
+
+  it('rejects names with slashes', () => {
+    expect(validateWorkstreamName('my/feature')).toBe(false);
+  });
+
+  it('rejects names with special characters', () => {
+    expect(validateWorkstreamName('feat@ure')).toBe(false);
+    expect(validateWorkstreamName('feat!ure')).toBe(false);
+    expect(validateWorkstreamName('feat#ure')).toBe(false);
+  });
+
+  it('rejects path traversal attempts', () => {
+    expect(validateWorkstreamName('..')).toBe(false);
+    expect(validateWorkstreamName('../etc')).toBe(false);
+  });
+});
+
+// ─── relPlanningPath helper ─────────────────────────────────────────────────
+
+import { relPlanningPath } from './workstream-utils.js';
+
+describe('relPlanningPath', () => {
+  it('returns .planning/ in flat mode (no workstream)', () => {
+    expect(relPlanningPath()).toBe('.planning');
+    expect(relPlanningPath(undefined)).toBe('.planning');
+  });
+
+  it('returns .planning/workstreams/<name>/ with workstream', () => {
+    expect(relPlanningPath('frontend')).toBe('.planning/workstreams/frontend');
+    expect(relPlanningPath('api-v2')).toBe('.planning/workstreams/api-v2');
+  });
+});
+
+// ─── CLI --ws flag parsing ──────────────────────────────────────────────────
+
+import { parseCliArgs } from './cli.js';
+
+describe('parseCliArgs --ws flag', () => {
+  it('parses --ws flag', () => {
+    const result = parseCliArgs(['run', 'build auth', '--ws', 'frontend']);
+
+    expect(result.ws).toBe('frontend');
+  });
+
+  it('ws is undefined when not provided', () => {
+    const result = parseCliArgs(['run', 'build auth']);
+
+    expect(result.ws).toBeUndefined();
+  });
+
+  it('works with other flags', () => {
+    const result = parseCliArgs([
+      'run', 'build auth',
+      '--ws', 'backend',
+      '--model', 'claude-sonnet-4-6',
+      '--project-dir', '/tmp/test',
+    ]);
+
+    expect(result.ws).toBe('backend');
+    expect(result.model).toBe('claude-sonnet-4-6');
+    expect(result.projectDir).toBe('/tmp/test');
+  });
+});
+
+// ─── SDDOptions.workstream ──────────────────────────────────────────────────
+
+describe('SDDOptions.workstream', () => {
+  it('SDD class accepts workstream option', async () => {
+    // This is a compile-time check -- if the type is wrong, TS will fail
+    const { SDD } = await import('./index.js');
+    const sdd = new SDD({
+      projectDir: '/tmp/test-ws',
+      workstream: 'frontend',
+    });
+    // If we get here without a type error, the option is accepted
+    expect(sdd).toBeDefined();
+  });
+});
+
+// ─── SDDTools workstream injection ──────────────────────────────────────────
+
+describe('SDDTools workstream injection', () => {
+  let tmpDir: string;
+  let fixtureDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `sdd-ws-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fixtureDir = join(tmpDir, 'fixtures');
+    await mkdir(fixtureDir, { recursive: true });
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  async function createScript(name: string, code: string): Promise<string> {
+    const scriptPath = join(fixtureDir, name);
+    await writeFile(scriptPath, code, { mode: 0o755 });
+    return scriptPath;
+  }
+
+  it('passes --ws flag to sdd-tools.cjs when workstream is set', async () => {
+    const { SDDTools } = await import('./sdd-tools.js');
+
+    // Script echoes its arguments as JSON
+    const scriptPath = await createScript(
+      'echo-args.cjs',
+      'process.stdout.write(JSON.stringify(process.argv.slice(2)));',
+    );
+
+    const tools = new SDDTools({
+      projectDir: tmpDir,
+      sddToolsPath: scriptPath,
+      workstream: 'frontend',
+    });
+
+    const result = await tools.exec('state', ['load']) as string[];
+
+    // Should contain --ws frontend in the arguments
+    expect(result).toContain('--ws');
+    expect(result).toContain('frontend');
+  });
+
+  it('does not pass --ws when workstream is undefined', async () => {
+    const { SDDTools } = await import('./sdd-tools.js');
+
+    const scriptPath = await createScript(
+      'echo-args-no-ws.cjs',
+      'process.stdout.write(JSON.stringify(process.argv.slice(2)));',
+    );
+
+    const tools = new SDDTools({
+      projectDir: tmpDir,
+      sddToolsPath: scriptPath,
+    });
+
+    const result = await tools.exec('state', ['load']) as string[];
+
+    expect(result).not.toContain('--ws');
+  });
+});
+
+// ─── Config workstream-aware path ───────────────────────────────────────────
+
+import { loadConfig } from './config.js';
+
+describe('loadConfig with workstream', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `sdd-config-ws-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(tmpDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('loads config from workstream path when workstream is provided', async () => {
+    const wsDir = join(tmpDir, '.planning', 'workstreams', 'frontend');
+    await mkdir(wsDir, { recursive: true });
+    await writeFile(
+      join(wsDir, 'config.json'),
+      JSON.stringify({ model_profile: 'performance' }),
+    );
+
+    const config = await loadConfig(tmpDir, 'frontend');
+
+    expect(config.model_profile).toBe('performance');
+  });
+
+  it('falls back to root config when workstream config is missing', async () => {
+    // Create root config but no workstream config
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ model_profile: 'balanced' }),
+    );
+
+    const config = await loadConfig(tmpDir, 'frontend');
+
+    expect(config.model_profile).toBe('balanced');
+  });
+
+  it('loads from root .planning/ when workstream is undefined', async () => {
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ model_profile: 'economy' }),
+    );
+
+    const config = await loadConfig(tmpDir);
+
+    expect(config.model_profile).toBe('economy');
+  });
+});
+
+// ─── ContextEngine workstream-aware planning dir ────────────────────────────
+
+describe('ContextEngine with workstream', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `sdd-ctx-ws-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(tmpDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('resolves files from workstream planning dir', async () => {
+    const { ContextEngine } = await import('./context-engine.js');
+    const { PhaseType } = await import('./types.js');
+
+    const wsDir = join(tmpDir, '.planning', 'workstreams', 'backend');
+    await mkdir(wsDir, { recursive: true });
+    await writeFile(join(wsDir, 'STATE.md'), '# State\nPhase: 01');
+
+    const engine = new ContextEngine(tmpDir, undefined, undefined, 'backend');
+    const files = await engine.resolveContextFiles(PhaseType.Execute);
+
+    expect(files.state).toContain('Phase: 01');
+  });
+
+  it('resolves files from root .planning/ without workstream', async () => {
+    const { ContextEngine } = await import('./context-engine.js');
+    const { PhaseType } = await import('./types.js');
+
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+    await writeFile(join(tmpDir, '.planning', 'STATE.md'), '# State\nPhase: 02');
+
+    const engine = new ContextEngine(tmpDir);
+    const files = await engine.resolveContextFiles(PhaseType.Execute);
+
+    expect(files.state).toContain('Phase: 02');
+  });
+});

package/sdk/src/ws-transport.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { WebSocket } from 'ws';
+import { WSTransport } from './ws-transport.js';
+import { SDDEventType, type SDDEvent, type SDDEventBase } from './types.js';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeBase(overrides: Partial<SDDEventBase> = {}): Omit<SDDEventBase, 'type'> {
+  return {
+    timestamp: '2025-06-15T14:30:45.123Z',
+    sessionId: 'test-session',
+    ...overrides,
+  };
+}
+
+/** Connect a WS client and resolve once open. */
+function connectClient(port: number): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    ws.on('open', () => resolve(ws));
+    ws.on('error', reject);
+  });
+}
+
+/** Wait for the next message on a WS client. */
+function waitForMessage(ws: WebSocket): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('message timeout')), 5000);
+    ws.once('message', (data) => {
+      clearTimeout(timeout);
+      resolve(data.toString());
+    });
+  });
+}
+
+// Track transports for cleanup
+const activeTransports: WSTransport[] = [];
+
+afterEach(() => {
+  for (const t of activeTransports) {
+    try { t.close(); } catch { /* ignore */ }
+  }
+  activeTransports.length = 0;
+});
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('WSTransport', () => {
+  it('start() creates a server on the specified port', async () => {
+    const transport = new WSTransport({ port: 0 }); // dynamic port
+    activeTransports.push(transport);
+
+    await transport.start();
+
+    // Server is listening — we can connect a client
+    const address = (transport as any).server?.address();
+    expect(address).toBeTruthy();
+    expect(typeof address.port).toBe('number');
+    expect(address.port).toBeGreaterThan(0);
+  });
+
+  it('onEvent broadcasts JSON to connected client', async () => {
+    const transport = new WSTransport({ port: 0 });
+    activeTransports.push(transport);
+    await transport.start();
+
+    const address = (transport as any).server?.address();
+    const client = await connectClient(address.port);
+
+    const event: SDDEvent = {
+      ...makeBase(),
+      type: SDDEventType.SessionInit,
+      model: 'claude-sonnet-4-20250514',
+      tools: ['Read', 'Write'],
+      cwd: '/tmp/test',
+    } as SDDEvent;
+
+    const msgPromise = waitForMessage(client);
+    transport.onEvent(event);
+
+    const received = await msgPromise;
+    const parsed = JSON.parse(received);
+
+    expect(parsed.type).toBe('session_init');
+    expect(parsed.model).toBe('claude-sonnet-4-20250514');
+    expect(parsed.tools).toEqual(['Read', 'Write']);
+
+    client.close();
+  });
+
+  it('onEvent handles no connected clients without error', async () => {
+    const transport = new WSTransport({ port: 0 });
+    activeTransports.push(transport);
+    await transport.start();
+
+    // No clients connected — should not throw
+    expect(() => {
+      transport.onEvent({
+        ...makeBase(),
+        type: SDDEventType.MilestoneStart,
+        phaseCount: 2,
+        prompt: 'test',
+      } as SDDEvent);
+    }).not.toThrow();
+  });
+
+  it('close() shuts down the server', async () => {
+    const transport = new WSTransport({ port: 0 });
+    // Don't push to activeTransports — we close manually
+
+    await transport.start();
+    const address = (transport as any).server?.address();
+    expect(address).toBeTruthy();
+
+    transport.close();
+
+    // Server should be null after close
+    expect((transport as any).server).toBeNull();
+
+    // Connecting should fail
+    await expect(connectClient(address.port)).rejects.toThrow();
+  });
+
+  it('close() before start() does not throw', () => {
+    const transport = new WSTransport({ port: 0 });
+    expect(() => transport.close()).not.toThrow();
+  });
+
+  it('broadcasts to multiple connected clients', async () => {
+    const transport = new WSTransport({ port: 0 });
+    activeTransports.push(transport);
+    await transport.start();
+
+    const address = (transport as any).server?.address();
+    const client1 = await connectClient(address.port);
+    const client2 = await connectClient(address.port);
+
+    const event: SDDEvent = {
+      ...makeBase(),
+      type: SDDEventType.MilestoneComplete,
+      success: true,
+      totalCostUsd: 5.0,
+      totalDurationMs: 120000,
+      phasesCompleted: 3,
+    } as SDDEvent;
+
+    const msg1Promise = waitForMessage(client1);
+    const msg2Promise = waitForMessage(client2);
+
+    transport.onEvent(event);
+
+    const [msg1, msg2] = await Promise.all([msg1Promise, msg2Promise]);
+
+    expect(JSON.parse(msg1).type).toBe('milestone_complete');
+    expect(JSON.parse(msg2).type).toBe('milestone_complete');
+    expect(JSON.parse(msg1).success).toBe(true);
+
+    client1.close();
+    client2.close();
+  });
+});

package/sdk/src/ws-transport.ts

@@ -0,0 +1,93 @@
+/**
+ * WebSocket Transport — broadcasts SDD events as JSON over WebSocket.
+ *
+ * Implements TransportHandler. Starts a WebSocketServer on a given port
+ * and JSON-serializes each event to all connected clients.
+ */
+
+import { WebSocketServer, WebSocket } from 'ws';
+import type { SDDEvent, TransportHandler } from './types.js';
+
+export interface WSTransportOptions {
+  port: number;
+}
+
+export class WSTransport implements TransportHandler {
+  private readonly port: number;
+  private server: WebSocketServer | null = null;
+  private closing = false;
+
+  constructor(options: WSTransportOptions) {
+    this.port = options.port;
+  }
+
+  /**
+   * Start the WebSocket server on the configured port.
+   * Resolves once the server is listening.
+   */
+  async start(): Promise<void> {
+    if (this.closing) return;
+
+    return new Promise<void>((resolve, reject) => {
+      try {
+        this.server = new WebSocketServer({ port: this.port });
+        this.server.on('listening', () => resolve());
+        this.server.on('error', (err) => reject(err));
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Broadcast a SDD event as JSON to all connected clients.
+   * Never throws — wraps each client.send in try/catch.
+   */
+  onEvent(event: SDDEvent): void {
+    try {
+      if (!this.server) return;
+
+      const payload = JSON.stringify(event);
+
+      for (const client of this.server.clients) {
+        if (client.readyState === WebSocket.OPEN) {
+          try {
+            client.send(payload);
+          } catch {
+            // Ignore individual client send errors
+          }
+        }
+      }
+    } catch {
+      // TransportHandler contract: onEvent must never throw
+    }
+  }
+
+  /**
+   * Close all client connections and shut down the server.
+   * Safe to call before start() — sets a closing flag.
+   */
+  close(): void {
+    this.closing = true;
+
+    if (!this.server) return;
+
+    // Terminate all clients
+    for (const client of this.server.clients) {
+      try {
+        client.terminate();
+      } catch {
+        // Ignore client close errors
+      }
+    }
+
+    // Close the server
+    try {
+      this.server.close();
+    } catch {
+      // Ignore server close errors
+    }
+
+    this.server = null;
+  }
+}