gsd-remix 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,119 @@
+/**
+ * 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/projects/<project> when project set', () => {
+    const paths = workspacePlanningPaths(projectDir, { workstream: null, project: 'api-server' });
+    expect(paths.planning).toContain('projects/api-server');
+    expect(paths.state).toContain('projects/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,131 @@
+/**
+ * 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';
+import { toPosixPath } from './helpers.js';
+import type { PlanningPaths } from './helpers.js';
+
+// ─── 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/projects/<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');
+    base = join(projectDir, '.planning', 'projects', 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.test.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 { workstreamList, workstreamCreate } 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('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);
+  });
+});