@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdk/src/query/websearch.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Tests for websearch handler (no network when API key unset).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { websearch } from './websearch.js';
+
+describe('websearch', () => {
+  it('returns available:false when BRAVE_API_KEY is not set', async () => {
+    const prev = process.env.BRAVE_API_KEY;
+    delete process.env.BRAVE_API_KEY;
+    const r = await websearch(['test query'], '/tmp');
+    const data = r.data as Record<string, unknown>;
+    expect(data.available).toBe(false);
+    if (prev !== undefined) process.env.BRAVE_API_KEY = prev;
+  });
+
+  it('returns error when query is missing and BRAVE_API_KEY is set', async () => {
+    const prev = process.env.BRAVE_API_KEY;
+    process.env.BRAVE_API_KEY = 'test-dummy-key';
+    try {
+      const r = await websearch([], '/tmp');
+      const data = r.data as Record<string, unknown>;
+      expect(data.available).toBe(false);
+      expect(data.error).toBe('Query required');
+    } finally {
+      if (prev !== undefined) process.env.BRAVE_API_KEY = prev;
+      else delete process.env.BRAVE_API_KEY;
+    }
+  });
+});

package/sdk/src/query/websearch.ts

@@ -0,0 +1,82 @@
+/**
+ * Web search query handler — Brave Search API integration.
+ *
+ * Provides web search for researcher agents. Returns { available: false }
+ * gracefully when BRAVE_API_KEY is missing so agents can fall back to
+ * built-in WebSearch tools.
+ *
+ * @example
+ * ```typescript
+ * import { websearch } from './websearch.js';
+ *
+ * await websearch(['typescript generics'], '/project');
+ * // { data: { available: true, query: 'typescript generics', count: 10, results: [...] } }
+ * ```
+ */
+
+import type { QueryHandler } from './utils.js';
+
+/**
+ * Search the web via Brave Search API.
+ * Requires BRAVE_API_KEY env var.
+ *
+ * Args: query [--limit N] [--freshness day|week|month]
+ */
+export const websearch: QueryHandler = async (args) => {
+  const apiKey = process.env.BRAVE_API_KEY;
+
+  if (!apiKey) {
+    return { data: { available: false, reason: 'BRAVE_API_KEY not set' } };
+  }
+
+  const query = args[0];
+  if (!query) {
+    return { data: { available: false, error: 'Query required' } };
+  }
+
+  const limitIdx = args.indexOf('--limit');
+  const freshnessIdx = args.indexOf('--freshness');
+  const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : 10;
+  const freshness = freshnessIdx !== -1 ? args[freshnessIdx + 1] : null;
+
+  const params = new URLSearchParams({
+    q: query,
+    count: String(limit),
+    country: 'us',
+    search_lang: 'en',
+    text_decorations: 'false',
+  });
+  if (freshness) params.set('freshness', freshness);
+
+  try {
+    const response = await fetch(
+      `https://api.search.brave.com/res/v1/web/search?${params}`,
+      {
+        headers: {
+          'Accept': 'application/json',
+          'X-Subscription-Token': apiKey,
+        },
+      },
+    );
+
+    if (!response.ok) {
+      return { data: { available: false, error: `API error: ${response.status}` } };
+    }
+
+    const body = await response.json() as {
+      web?: { results?: Array<{ title: string; url: string; description: string; age?: string }> };
+    };
+
+    const results = (body.web?.results || []).map(r => ({
+      title: r.title,
+      url: r.url,
+      description: r.description,
+      age: r.age || null,
+    }));
+
+    return { data: { available: true, query, count: results.length, results } };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { data: { available: false, error: msg } };
+  }
+};

package/sdk/src/query/workspace.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Unit tests for workspace-aware state resolution.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { resolveWorkspaceContext, workspacePlanningPaths } from './workspace.js';
+
+// ─── resolveWorkspaceContext ───────────────────────────────────────────────
+
+describe('resolveWorkspaceContext', () => {
+  afterEach(() => {
+    delete process.env['SDD_WORKSTREAM'];
+    delete process.env['SDD_PROJECT'];
+  });
+
+  it('returns null values when env vars not set', () => {
+    delete process.env['SDD_WORKSTREAM'];
+    delete process.env['SDD_PROJECT'];
+    const ctx = resolveWorkspaceContext();
+    expect(ctx.workstream).toBeNull();
+    expect(ctx.project).toBeNull();
+  });
+
+  it('reads SDD_WORKSTREAM from env', () => {
+    process.env['SDD_WORKSTREAM'] = 'backend';
+    const ctx = resolveWorkspaceContext();
+    expect(ctx.workstream).toBe('backend');
+  });
+
+  it('reads SDD_PROJECT from env', () => {
+    process.env['SDD_PROJECT'] = 'api-server';
+    const ctx = resolveWorkspaceContext();
+    expect(ctx.project).toBe('api-server');
+  });
+
+  it('reads both vars when both are set', () => {
+    process.env['SDD_WORKSTREAM'] = 'ws1';
+    process.env['SDD_PROJECT'] = 'proj1';
+    const ctx = resolveWorkspaceContext();
+    expect(ctx.workstream).toBe('ws1');
+    expect(ctx.project).toBe('proj1');
+  });
+});
+
+// ─── workspacePlanningPaths ────────────────────────────────────────────────
+
+describe('workspacePlanningPaths', () => {
+  const projectDir = '/my/project';
+
+  it('returns default .planning/ when no context provided', () => {
+    const paths = workspacePlanningPaths(projectDir);
+    expect(paths.planning).toContain('.planning');
+    expect(paths.planning).not.toContain('workstreams');
+    expect(paths.planning).not.toContain('projects');
+    expect(paths.state).toContain('STATE.md');
+    expect(paths.phases).toContain('phases');
+  });
+
+  it('returns default .planning/ when context has no workspace or project', () => {
+    const paths = workspacePlanningPaths(projectDir, { workstream: null, project: null });
+    expect(paths.planning).not.toContain('workstreams');
+    expect(paths.planning).not.toContain('projects');
+  });
+
+  it('scopes to .planning/workstreams/<ws> when workstream set', () => {
+    const paths = workspacePlanningPaths(projectDir, { workstream: 'backend', project: null });
+    expect(paths.planning).toContain('workstreams/backend');
+    expect(paths.state).toContain('workstreams/backend/STATE.md');
+    expect(paths.phases).toContain('workstreams/backend/phases');
+  });
+
+  it('scopes to .planning/<project> when project set (CJS parity)', () => {
+    const paths = workspacePlanningPaths(projectDir, { workstream: null, project: 'api-server' });
+    expect(paths.planning).toContain('.planning/api-server');
+    expect(paths.planning).not.toContain('projects/');
+    expect(paths.state).toContain('.planning/api-server/STATE.md');
+  });
+
+  it('workstream takes precedence over project when both set', () => {
+    const paths = workspacePlanningPaths(projectDir, { workstream: 'ws1', project: 'proj1' });
+    expect(paths.planning).toContain('workstreams/ws1');
+    expect(paths.planning).not.toContain('projects');
+  });
+
+  it('throws on empty workstream name', () => {
+    expect(() => workspacePlanningPaths(projectDir, { workstream: '', project: null }))
+      .toThrow('empty');
+  });
+
+  it('throws on workstream name containing forward slash', () => {
+    expect(() => workspacePlanningPaths(projectDir, { workstream: 'ws/bad', project: null }))
+      .toThrow('path separators');
+  });
+
+  it('throws on workstream name containing backslash', () => {
+    expect(() => workspacePlanningPaths(projectDir, { workstream: 'ws\\bad', project: null }))
+      .toThrow('path separators');
+  });
+
+  it('throws on workstream name containing ".."', () => {
+    expect(() => workspacePlanningPaths(projectDir, { workstream: '../escape', project: null }))
+      .toThrow('..');
+  });
+
+  it('throws on project name containing path separators', () => {
+    expect(() => workspacePlanningPaths(projectDir, { workstream: null, project: '../../bad' }))
+      .toThrow('path separators');
+  });
+
+  it('all path fields are defined', () => {
+    const paths = workspacePlanningPaths(projectDir, { workstream: 'ws1', project: null });
+    expect(paths.planning).toBeDefined();
+    expect(paths.state).toBeDefined();
+    expect(paths.roadmap).toBeDefined();
+    expect(paths.project).toBeDefined();
+    expect(paths.config).toBeDefined();
+    expect(paths.phases).toBeDefined();
+    expect(paths.requirements).toBeDefined();
+  });
+});

package/sdk/src/query/workspace.ts

@@ -0,0 +1,145 @@
+/**
+ * Workspace-aware state resolution — scopes .planning/ paths to a
+ * SDD_WORKSTREAM or SDD_PROJECT environment context.
+ *
+ * Port of planningDir() workspace logic from sdd/bin/lib/core.cjs
+ * (line 669+). Provides WorkspaceContext reading and validated path scoping.
+ *
+ * Security: workspace names are validated to reject path traversal (T-14-05).
+ *
+ * @example
+ * ```typescript
+ * import { resolveWorkspaceContext, workspacePlanningPaths } from './workspace.js';
+ *
+ * const ctx = resolveWorkspaceContext();
+ * // { workstream: 'backend', project: null }
+ *
+ * const paths = workspacePlanningPaths('/my/project', ctx);
+ * // paths.state → '/my/project/.planning/workstreams/backend/STATE.md'
+ * ```
+ */
+
+import { join } from 'node:path';
+import { SDDError, ErrorClassification } from '../errors.js';
+
+export interface PlanningPaths {
+  planning: string;
+  state: string;
+  roadmap: string;
+  project: string;
+  config: string;
+  phases: string;
+  requirements: string;
+}
+
+function toPosixPath(p: string): string {
+  return p.split('\\').join('/');
+}
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+/**
+ * Resolved workspace context from environment variables.
+ */
+export interface WorkspaceContext {
+  /** Active workstream name (from SDD_WORKSTREAM env var), or null */
+  workstream: string | null;
+  /** Active project name (from SDD_PROJECT env var), or null */
+  project: string | null;
+}
+
+// ─── Validation ────────────────────────────────────────────────────────────
+
+/**
+ * Validate a workspace or project name.
+ *
+ * Rejects names that could cause path traversal (T-14-05):
+ * - Empty string
+ * - Names containing '/' or '\'
+ * - Names containing '..' sequences
+ *
+ * @param name - Workspace or project name to validate
+ * @param kind - Label for error messages ('workstream' or 'project')
+ * @throws SDDError with Validation classification on invalid name
+ */
+function validateWorkspaceName(name: string, kind: string): void {
+  if (!name || name.trim() === '') {
+    throw new SDDError(
+      `${kind} name must not be empty`,
+      ErrorClassification.Validation,
+    );
+  }
+  if (name.includes('/') || name.includes('\\')) {
+    throw new SDDError(
+      `${kind} name must not contain path separators: ${name}`,
+      ErrorClassification.Validation,
+    );
+  }
+  if (name.includes('..')) {
+    throw new SDDError(
+      `${kind} name must not contain '..' (path traversal): ${name}`,
+      ErrorClassification.Validation,
+    );
+  }
+}
+
+// ─── resolveWorkspaceContext ───────────────────────────────────────────────
+
+/**
+ * Read SDD_WORKSTREAM and SDD_PROJECT environment variables.
+ *
+ * Returns a WorkspaceContext with null values when the env vars are not set.
+ *
+ * @returns Resolved workspace context
+ */
+export function resolveWorkspaceContext(): WorkspaceContext {
+  return {
+    workstream: process.env['SDD_WORKSTREAM'] || null,
+    project: process.env['SDD_PROJECT'] || null,
+  };
+}
+
+// ─── workspacePlanningPaths ────────────────────────────────────────────────
+
+/**
+ * Return PlanningPaths scoped to the active workspace or project.
+ *
+ * When context has a workstream set: base = .planning/workstreams/<ws>/
+ * When context has a project set: base = .planning/<project>/
+ * When context is null or empty: base = .planning/ (default)
+ *
+ * Workspace and project names are validated before path construction.
+ *
+ * @param projectDir - Absolute project root path
+ * @param context - Optional workspace context (defaults to no scoping)
+ * @returns PlanningPaths scoped to the active workspace
+ * @throws SDDError if workspace/project name fails validation
+ */
+export function workspacePlanningPaths(
+  projectDir: string,
+  context?: WorkspaceContext,
+): PlanningPaths {
+  let base: string;
+
+  if (context?.workstream != null) {
+    validateWorkspaceName(context.workstream, 'workstream');
+    base = join(projectDir, '.planning', 'workstreams', context.workstream);
+  } else if (context?.project != null) {
+    validateWorkspaceName(context.project, 'project');
+    // Match CJS planningDir() policy: project scopes under `.planning/<project>/`
+    // (not `.planning/projects/<project>/`).
+    base = join(projectDir, '.planning', context.project);
+  } else {
+    base = join(projectDir, '.planning');
+  }
+
+  return {
+    planning: toPosixPath(base),
+    state: toPosixPath(join(base, 'STATE.md')),
+    roadmap: toPosixPath(join(base, 'ROADMAP.md')),
+    project: toPosixPath(join(base, 'PROJECT.md')),
+    config: toPosixPath(join(base, 'config.json')),
+    phases: toPosixPath(join(base, 'phases')),
+    requirements: toPosixPath(join(base, 'REQUIREMENTS.md')),
+  };
+}

package/sdk/src/query/workstream-inventory.ts

@@ -0,0 +1,195 @@
+/**
+ * Workstream Inventory Module.
+ *
+ * Owns discovery and read-only projection of .planning/workstreams/* state.
+ * Query handlers should render outputs from this inventory instead of
+ * rescanning workstream directories directly.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { toPosixPath } from './helpers.js';
+import { scanPhasePlans } from './plan-scan.js';
+import { stateExtractField } from './state-document.js';
+import { readActiveWorkstream } from './active-workstream-store.js';
+
+export interface WorkstreamPhaseInventory {
+  directory: string;
+  status: 'complete' | 'in_progress' | 'pending';
+  plan_count: number;
+  summary_count: number;
+}
+
+export interface WorkstreamInventory {
+  name: string;
+  path: string;
+  active: boolean;
+  files: {
+    roadmap: boolean;
+    state: boolean;
+    requirements: boolean;
+  };
+  status: string;
+  current_phase: string | null;
+  last_activity: string | null;
+  phases: WorkstreamPhaseInventory[];
+  phase_count: number;
+  completed_phases: number;
+  roadmap_phase_count: number;
+  total_plans: number;
+  completed_plans: number;
+  progress_percent: number;
+}
+
+export interface WorkstreamInventoryList {
+  mode: 'flat' | 'workstream';
+  active: string | null;
+  workstreams: WorkstreamInventory[];
+  count: number;
+  message?: string;
+}
+
+export const planningRoot = (projectDir: string): string =>
+  join(projectDir, '.planning');
+
+export const workstreamsRoot = (projectDir: string): string =>
+  join(planningRoot(projectDir), 'workstreams');
+
+function wsPlanningPaths(projectDir: string, name: string) {
+  const base = join(planningRoot(projectDir), 'workstreams', name);
+  return {
+    state: join(base, 'STATE.md'),
+    roadmap: join(base, 'ROADMAP.md'),
+    phases: join(base, 'phases'),
+    requirements: join(base, 'REQUIREMENTS.md'),
+  };
+}
+
+function readSubdirectories(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
+}
+
+export function countRoadmapPhases(roadmapPath: string, fallbackCount: number): number {
+  try {
+    const roadmapContent = readFileSync(roadmapPath, 'utf-8');
+    const matches = roadmapContent.match(/^#{2,4}\s+Phase\s+[\w][\w.-]*/gm);
+    return matches ? matches.length : fallbackCount;
+  } catch {
+    return fallbackCount;
+  }
+}
+
+export function countPhaseFiles(phaseDir: string): { planCount: number; summaryCount: number } {
+  const scan = scanPhasePlans(phaseDir);
+  return { planCount: scan.planCount, summaryCount: scan.summaryCount };
+}
+
+function readStateProjection(statePath: string): Pick<WorkstreamInventory, 'status' | 'current_phase' | 'last_activity'> {
+  try {
+    const stateContent = readFileSync(statePath, 'utf-8');
+    return {
+      status: stateExtractField(stateContent, 'Status') || 'unknown',
+      current_phase: stateExtractField(stateContent, 'Current Phase'),
+      last_activity: stateExtractField(stateContent, 'Last Activity'),
+    };
+  } catch {
+    return {
+      status: 'unknown',
+      current_phase: null,
+      last_activity: null,
+    };
+  }
+}
+
+export function inspectWorkstream(
+  projectDir: string,
+  name: string,
+  options: { active?: string | null } = {},
+): WorkstreamInventory | null {
+  const wsDir = join(workstreamsRoot(projectDir), name);
+  if (!existsSync(wsDir)) return null;
+
+  const active = options.active === undefined ? readActiveWorkstream(projectDir) : options.active;
+  const p = wsPlanningPaths(projectDir, name);
+  const phaseDirs = readSubdirectories(p.phases);
+  const phases: WorkstreamPhaseInventory[] = [];
+  let completedPhases = 0;
+  let totalPlans = 0;
+  let completedPlans = 0;
+
+  for (const dir of [...phaseDirs].sort()) {
+    const counts = countPhaseFiles(join(p.phases, dir));
+    const status: WorkstreamPhaseInventory['status'] =
+      counts.summaryCount >= counts.planCount && counts.planCount > 0
+        ? 'complete'
+        : counts.planCount > 0
+          ? 'in_progress'
+          : 'pending';
+
+    totalPlans += counts.planCount;
+    completedPlans += Math.min(counts.summaryCount, counts.planCount);
+    if (status === 'complete') completedPhases++;
+
+    phases.push({
+      directory: dir,
+      status,
+      plan_count: counts.planCount,
+      summary_count: counts.summaryCount,
+    });
+  }
+
+  const roadmapPhaseCount = countRoadmapPhases(p.roadmap, phaseDirs.length);
+  const state = readStateProjection(p.state);
+
+  return {
+    name,
+    path: toPosixPath(relative(projectDir, wsDir)),
+    active: name === active,
+    files: {
+      roadmap: existsSync(p.roadmap),
+      state: existsSync(p.state),
+      requirements: existsSync(p.requirements),
+    },
+    status: state.status,
+    current_phase: state.current_phase,
+    last_activity: state.last_activity,
+    phases,
+    phase_count: phases.length,
+    completed_phases: completedPhases,
+    roadmap_phase_count: roadmapPhaseCount,
+    total_plans: totalPlans,
+    completed_plans: completedPlans,
+    progress_percent: roadmapPhaseCount > 0 ? Math.min(100, Math.round((completedPhases / roadmapPhaseCount) * 100)) : 0,
+  };
+}
+
+export function listWorkstreamInventories(projectDir: string): WorkstreamInventoryList {
+  const wsRoot = workstreamsRoot(projectDir);
+  if (!existsSync(wsRoot)) {
+    return {
+      mode: 'flat',
+      active: null,
+      workstreams: [],
+      count: 0,
+      message: 'No workstreams — operating in flat mode',
+    };
+  }
+
+  const active = readActiveWorkstream(projectDir);
+  const entries = readdirSync(wsRoot, { withFileTypes: true });
+  const workstreams: WorkstreamInventory[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const inventory = inspectWorkstream(projectDir, entry.name, { active });
+    if (inventory) workstreams.push(inventory);
+  }
+
+  return {
+    mode: 'workstream',
+    active,
+    workstreams,
+    count: workstreams.length,
+  };
+}