@opengsd/get-shit-done-redux 1.0.0

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['GSD_WORKSTREAM'];
+    delete process.env['GSD_PROJECT'];
+  });
+
+  it('returns null values when env vars not set', () => {
+    delete process.env['GSD_WORKSTREAM'];
+    delete process.env['GSD_PROJECT'];
+    const ctx = resolveWorkspaceContext();
+    expect(ctx.workstream).toBeNull();
+    expect(ctx.project).toBeNull();
+  });
+
+  it('reads GSD_WORKSTREAM from env', () => {
+    process.env['GSD_WORKSTREAM'] = 'backend';
+    const ctx = resolveWorkspaceContext();
+    expect(ctx.workstream).toBe('backend');
+  });
+
+  it('reads GSD_PROJECT from env', () => {
+    process.env['GSD_PROJECT'] = 'api-server';
+    const ctx = resolveWorkspaceContext();
+    expect(ctx.project).toBe('api-server');
+  });
+
+  it('reads both vars when both are set', () => {
+    process.env['GSD_WORKSTREAM'] = 'ws1';
+    process.env['GSD_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
+ * GSD_WORKSTREAM or GSD_PROJECT environment context.
+ *
+ * Port of planningDir() workspace logic from get-shit-done/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 { GSDError, 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 GSD_WORKSTREAM env var), or null */
+  workstream: string | null;
+  /** Active project name (from GSD_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 GSDError with Validation classification on invalid name
+ */
+function validateWorkspaceName(name: string, kind: string): void {
+  if (!name || name.trim() === '') {
+    throw new GSDError(
+      `${kind} name must not be empty`,
+      ErrorClassification.Validation,
+    );
+  }
+  if (name.includes('/') || name.includes('\\')) {
+    throw new GSDError(
+      `${kind} name must not contain path separators: ${name}`,
+      ErrorClassification.Validation,
+    );
+  }
+  if (name.includes('..')) {
+    throw new GSDError(
+      `${kind} name must not contain '..' (path traversal): ${name}`,
+      ErrorClassification.Validation,
+    );
+  }
+}
+
+// ─── resolveWorkspaceContext ───────────────────────────────────────────────
+
+/**
+ * Read GSD_WORKSTREAM and GSD_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['GSD_WORKSTREAM'] || null,
+    project: process.env['GSD_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 GSDError 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,143 @@
+/**
+ * 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.
+ *
+ * Pure projection logic lives in ../workstream-inventory/builder.ts.
+ * This module handles I/O orchestration only.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { scanPhasePlans } from './plan-scan.js';
+import { stateExtractField } from './state-document.js';
+import { readActiveWorkstream } from './active-workstream-store.js';
+import { buildWorkstreamInventory } from '../workstream-inventory/builder.js';
+
+// Re-export types from the builder so downstream consumers can import from here.
+export type {
+  WorkstreamPhaseInventory,
+  WorkstreamInventory,
+  WorkstreamInventoryList,
+} from '../workstream-inventory/builder.js';
+
+import type { WorkstreamInventory, WorkstreamInventoryList } from '../workstream-inventory/builder.js';
+
+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): { status: string; current_phase: string | null; last_activity: string | null } {
+  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 activeWorkstreamName = options.active === undefined ? readActiveWorkstream(projectDir) : options.active;
+  const p = wsPlanningPaths(projectDir, name);
+  const phaseDirNames = readSubdirectories(p.phases);
+
+  // Collect per-phase file counts
+  const phaseFilesCounts = phaseDirNames.map(dir => {
+    const counts = countPhaseFiles(join(p.phases, dir));
+    return { directory: dir, planCount: counts.planCount, summaryCount: counts.summaryCount };
+  });
+
+  return buildWorkstreamInventory({
+    name,
+    projectDir,
+    workstreamDir: wsDir,
+    phaseDirNames,
+    activeWorkstreamName,
+    phaseFilesCounts,
+    roadmapPhaseCount: countRoadmapPhases(p.roadmap, phaseDirNames.length),
+    stateProjection: readStateProjection(p.state),
+    filesExist: {
+      roadmap: existsSync(p.roadmap),
+      state: existsSync(p.state),
+      requirements: existsSync(p.requirements),
+    },
+  });
+}
+
+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,
+  };
+}

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

@@ -0,0 +1,153 @@
+/**
+ * Tests for workstream query handlers.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { readFile } from 'node:fs/promises';
+import { workstreamList, workstreamCreate, workstreamSet, workstreamProgress } from './workstream.js';
+
+describe('workstreamList', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-ws-'));
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+    await writeFile(join(tmpDir, '.planning', 'config.json'), JSON.stringify({ model_profile: 'balanced' }));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns flat mode when no workstreams directory', async () => {
+    const r = await workstreamList([], tmpDir);
+    const data = r.data as Record<string, unknown>;
+    expect(data.mode).toBe('flat');
+    expect(Array.isArray(data.workstreams)).toBe(true);
+  });
+});
+
+describe('workstreamProgress', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-ws-progress-'));
+    const wsDir = join(tmpDir, '.planning', 'workstreams', 'overflow');
+    await mkdir(join(wsDir, 'phases', '01-one'), { recursive: true });
+    await mkdir(join(wsDir, 'phases', '02-two'), { recursive: true });
+    await writeFile(join(wsDir, 'phases', '01-one', 'PLAN.md'), '# Plan\n');
+    await writeFile(join(wsDir, 'phases', '01-one', 'SUMMARY.md'), '# Summary\n');
+    await writeFile(join(wsDir, 'phases', '02-two', 'PLAN.md'), '# Plan\n');
+    await writeFile(join(wsDir, 'phases', '02-two', 'SUMMARY.md'), '# Summary\n');
+    await writeFile(join(wsDir, 'STATE.md'), '# State\nStatus: In progress\n');
+    await writeFile(join(wsDir, 'ROADMAP.md'), '# Roadmap\n### Phase 1: One\n');
+    await writeFile(join(tmpDir, '.planning', 'active-workstream'), 'overflow\n');
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('clamps progress percent when completed phase dirs exceed roadmap count', async () => {
+    const result = await workstreamProgress([], tmpDir);
+    const data = result.data as { workstreams: Array<{ progress_percent: number }> };
+    expect(data.workstreams[0].progress_percent).toBe(100);
+  });
+});
+
+describe('workstreamCreate', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-ws2-'));
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+    await writeFile(join(tmpDir, '.planning', 'config.json'), JSON.stringify({ model_profile: 'balanced' }));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('creates workstream directory tree', async () => {
+    const r = await workstreamCreate(['test-ws'], tmpDir);
+    const data = r.data as Record<string, unknown>;
+    expect(data.created).toBe(true);
+  });
+});
+
+describe('workstreamSet root STATE.md mirror sync (#2618 gap 2)', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-ws-set-'));
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ model_profile: 'balanced' }),
+    );
+
+    // Root STATE.md with stale frontmatter (mirror of some prior workstream)
+    const rootState = [
+      '---',
+      'gsd_state_version: 1.0',
+      'milestone: v0.stale',
+      'milestone_name: Stale Mirror',
+      'active_workstream: old-ws',
+      'current_phase: "99"',
+      'status: completed',
+      'last_updated: "2020-01-01T00:00:00.000Z"',
+      '---',
+      '',
+      '# Project State',
+      '',
+    ].join('\n');
+    await writeFile(join(tmpDir, '.planning', 'STATE.md'), rootState);
+
+    // Target workstream with different frontmatter
+    const wsDir = join(tmpDir, '.planning', 'workstreams', 'active-ws');
+    await mkdir(wsDir, { recursive: true });
+    const wsState = [
+      '---',
+      'gsd_state_version: 1.0',
+      'milestone: v1.0',
+      'milestone_name: Active Milestone',
+      'active_workstream: active-ws',
+      'current_phase: "3"',
+      'status: executing',
+      'last_updated: "2026-04-23T00:00:00.000Z"',
+      '---',
+      '',
+      '# Project State',
+      '',
+      'Status: executing',
+      'Current Phase: 3',
+      '',
+    ].join('\n');
+    await writeFile(join(wsDir, 'STATE.md'), wsState);
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('rewrites root .planning/STATE.md to mirror the new workstream STATE.md on switch', async () => {
+    const r = await workstreamSet(['active-ws'], tmpDir);
+    const data = r.data as Record<string, unknown>;
+    expect(data.set).toBe(true);
+    expect(data.active).toBe('active-ws');
+
+    const rootStateAfter = await readFile(join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    // The stale mirror fields must be gone; new workstream fields must be present.
+    expect(rootStateAfter).toContain('milestone: v1.0');
+    expect(rootStateAfter).toContain('milestone_name: Active Milestone');
+    expect(rootStateAfter).toContain('active_workstream: active-ws');
+    expect(rootStateAfter).toContain('current_phase:');
+    expect(rootStateAfter).toContain('status: executing');
+    expect(rootStateAfter).not.toContain('milestone: v0.stale');
+    expect(rootStateAfter).not.toContain('Stale Mirror');
+  });
+});