gsd-remix 1.0.0

package/sdk/src/query/workstream.ts

@@ -0,0 +1,434 @@
+/**
+ * Workstream query handlers — list, get, create, set, status, complete, progress.
+ *
+ * Ported from get-shit-done/bin/lib/workstream.cjs.
+ * Manages .planning/workstreams/ directory for multi-workstream projects.
+ *
+ * @example
+ * ```typescript
+ * import { workstreamList, workstreamCreate } from './workstream.js';
+ *
+ * await workstreamList([], '/project');
+ * // { data: { workstreams: ['backend', 'frontend'], count: 2 } }
+ *
+ * await workstreamCreate(['api'], '/project');
+ * // { data: { created: true, name: 'api', path: '.planning/workstreams/api' } }
+ * ```
+ */
+
+import {
+  existsSync, readdirSync, readFileSync, writeFileSync,
+  mkdirSync, renameSync, rmdirSync, unlinkSync,
+} from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { toPosixPath, stateExtractField } from './helpers.js';
+import { GSDError, ErrorClassification } from '../errors.js';
+import type { QueryHandler } from './utils.js';
+
+// ─── Internal helpers ─────────────────────────────────────────────────────
+
+const planningRoot = (projectDir: string) =>
+  join(projectDir, '.planning');
+
+const workstreamsDir = (projectDir: string) =>
+  join(planningRoot(projectDir), 'workstreams');
+
+function wsPlanningPaths(projectDir: string, name: string) {
+  const base = join(planningRoot(projectDir), 'workstreams', name);
+  return {
+    planning: base,
+    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);
+}
+
+function filterPlanFiles(files: string[]): string[] {
+  return files.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+}
+
+function filterSummaryFiles(files: string[]): string[] {
+  return files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+}
+
+function getActiveWorkstream(projectDir: string): string | null {
+  const filePath = join(planningRoot(projectDir), 'active-workstream');
+  try {
+    const name = readFileSync(filePath, 'utf-8').trim();
+    if (!name || !/^[a-zA-Z0-9_-]+$/.test(name)) {
+      try { unlinkSync(filePath); } catch { /* already gone */ }
+      return null;
+    }
+    const wsDir = join(workstreamsDir(projectDir), name);
+    if (!existsSync(wsDir)) {
+      try { unlinkSync(filePath); } catch { /* already gone */ }
+      return null;
+    }
+    return name;
+  } catch {
+    return null;
+  }
+}
+
+function setActiveWorkstream(projectDir: string, name: string | null): void {
+  const filePath = join(planningRoot(projectDir), 'active-workstream');
+  if (!name) {
+    try { unlinkSync(filePath); } catch { /* already gone */ }
+    return;
+  }
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    throw new Error('Invalid workstream name: must be alphanumeric, hyphens, and underscores only');
+  }
+  writeFileSync(filePath, name + '\n', 'utf-8');
+}
+
+// ─── Handlers ─────────────────────────────────────────────────────────────
+
+/**
+ * Current active workstream and mode (flat vs workstream).
+ *
+ * Port of `cmdWorkstreamGet` from `workstream.cjs` lines 367–371.
+ */
+export const workstreamGet: QueryHandler = async (_args, projectDir) => {
+  const active = getActiveWorkstream(projectDir);
+  const wsRoot = workstreamsDir(projectDir);
+  return {
+    data: {
+      active,
+      mode: existsSync(wsRoot) ? 'workstream' : 'flat',
+    },
+  };
+};
+
+export const workstreamList: QueryHandler = async (_args, projectDir) => {
+  const dir = workstreamsDir(projectDir);
+  if (!existsSync(dir)) return { data: { mode: 'flat', workstreams: [], message: 'No workstreams — operating in flat mode' } };
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    const workstreams = entries.filter(e => e.isDirectory()).map(e => e.name);
+    return { data: { mode: 'workstream', workstreams, count: workstreams.length } };
+  } catch {
+    return { data: { mode: 'flat', workstreams: [], count: 0 } };
+  }
+};
+
+export const workstreamCreate: QueryHandler = async (args, projectDir) => {
+  const rawName = args[0];
+  if (!rawName) return { data: { created: false, reason: 'name required' } };
+  if (rawName.includes('/') || rawName.includes('\\') || rawName.includes('..')) {
+    return { data: { created: false, reason: 'invalid workstream name — path separators not allowed' } };
+  }
+
+  const slug = rawName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  if (!slug) return { data: { created: false, reason: 'invalid workstream name — must contain at least one alphanumeric character' } };
+
+  const baseDir = planningRoot(projectDir);
+  if (!existsSync(baseDir)) {
+    return { data: { created: false, reason: '.planning/ directory not found — run /gsd-new-project first' } };
+  }
+
+  const wsRoot = workstreamsDir(projectDir);
+  const wsDir = join(wsRoot, slug);
+
+  if (existsSync(wsDir) && existsSync(join(wsDir, 'STATE.md'))) {
+    return { data: { created: false, error: 'already_exists', workstream: slug, path: toPosixPath(relative(projectDir, wsDir)) } };
+  }
+
+  mkdirSync(wsDir, { recursive: true });
+  mkdirSync(join(wsDir, 'phases'), { recursive: true });
+
+  const today = new Date().toISOString().split('T')[0];
+  const stateContent = [
+    '---',
+    `workstream: ${slug}`,
+    `created: ${today}`,
+    '---',
+    '',
+    '# Project State',
+    '',
+    '## Current Position',
+    '**Status:** Not started',
+    '**Current Phase:** None',
+    `**Last Activity:** ${today}`,
+    '**Last Activity Description:** Workstream created',
+    '',
+    '## Progress',
+    '**Phases Complete:** 0',
+    '**Current Plan:** N/A',
+    '',
+    '## Session Continuity',
+    '**Stopped At:** N/A',
+    '**Resume File:** None',
+    '',
+  ].join('\n');
+
+  const statePath = join(wsDir, 'STATE.md');
+  if (!existsSync(statePath)) {
+    writeFileSync(statePath, stateContent, 'utf-8');
+  }
+
+  setActiveWorkstream(projectDir, slug);
+
+  const relPath = toPosixPath(relative(projectDir, wsDir));
+  return {
+    data: {
+      created: true,
+      workstream: slug,
+      path: relPath,
+      state_path: relPath + '/STATE.md',
+      phases_path: relPath + '/phases',
+      active: true,
+    },
+  };
+};
+
+export const workstreamSet: QueryHandler = async (args, projectDir) => {
+  const name = args[0];
+
+  if (!name || name === '--clear') {
+    if (name !== '--clear') {
+      return { data: { set: false, reason: 'name required. Usage: workstream set <name> (or workstream set --clear to unset)' } };
+    }
+    const previous = getActiveWorkstream(projectDir);
+    setActiveWorkstream(projectDir, null);
+    return { data: { active: null, cleared: true, previous: previous || null } };
+  }
+
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    return { data: { active: null, error: 'invalid_name', message: 'Workstream name must be alphanumeric, hyphens, and underscores only' } };
+  }
+
+  const wsDir = join(workstreamsDir(projectDir), name);
+  if (!existsSync(wsDir)) {
+    return { data: { active: null, error: 'not_found', workstream: name } };
+  }
+
+  setActiveWorkstream(projectDir, name);
+  return { data: { active: name, set: true } };
+};
+
+export const workstreamStatus: QueryHandler = async (args, projectDir) => {
+  const name = args[0];
+  if (!name) {
+    throw new GSDError('workstream name required. Usage: workstream status <name>', ErrorClassification.Validation);
+  }
+  if (/[/\\]/.test(name) || name === '.' || name === '..') {
+    throw new GSDError('Invalid workstream name', ErrorClassification.Validation);
+  }
+
+  const wsDir = join(workstreamsDir(projectDir), name);
+  if (!existsSync(wsDir)) {
+    return { data: { found: false, workstream: name } };
+  }
+
+  const p = wsPlanningPaths(projectDir, name);
+  const relPath = toPosixPath(relative(projectDir, wsDir));
+
+  const files = {
+    roadmap: existsSync(p.roadmap),
+    state: existsSync(p.state),
+    requirements: existsSync(p.requirements),
+  };
+
+  const phases: Array<{ directory: string; status: string; plan_count: number; summary_count: number }> = [];
+  for (const dir of readSubdirectories(p.phases).sort()) {
+    try {
+      const phaseFiles = readdirSync(join(p.phases, dir));
+      const plans = filterPlanFiles(phaseFiles);
+      const summaries = filterSummaryFiles(phaseFiles);
+      phases.push({
+        directory: dir,
+        status:
+          summaries.length >= plans.length && plans.length > 0
+            ? 'complete'
+            : plans.length > 0
+              ? 'in_progress'
+              : 'pending',
+        plan_count: plans.length,
+        summary_count: summaries.length,
+      });
+    } catch { /* skip */ }
+  }
+
+  let stateInfo: Record<string, string | null> = {};
+  try {
+    const stateContent = readFileSync(p.state, 'utf-8');
+    stateInfo = {
+      status: stateExtractField(stateContent, 'Status') || 'unknown',
+      current_phase: stateExtractField(stateContent, 'Current Phase'),
+      last_activity: stateExtractField(stateContent, 'Last Activity'),
+    };
+  } catch { /* skip */ }
+
+  return {
+    data: {
+      found: true,
+      workstream: name,
+      path: relPath,
+      files,
+      phases,
+      phase_count: phases.length,
+      completed_phases: phases.filter(ph => ph.status === 'complete').length,
+      ...stateInfo,
+    },
+  };
+};
+
+export const workstreamComplete: QueryHandler = async (args, projectDir) => {
+  const name = args[0];
+  if (!name) return { data: { completed: false, reason: 'workstream name required' } };
+  if (/[/\\]/.test(name) || name === '.' || name === '..') {
+    return { data: { completed: false, reason: 'invalid workstream name' } };
+  }
+
+  const root = planningRoot(projectDir);
+  const wsRoot = workstreamsDir(projectDir);
+  const wsDir = join(wsRoot, name);
+
+  if (!existsSync(wsDir)) {
+    return { data: { completed: false, error: 'not_found', workstream: name } };
+  }
+
+  const active = getActiveWorkstream(projectDir);
+  if (active === name) setActiveWorkstream(projectDir, null);
+
+  const archiveDir = join(root, 'milestones');
+  const today = new Date().toISOString().split('T')[0];
+  let archivePath = join(archiveDir, `ws-${name}-${today}`);
+  let suffix = 1;
+  while (existsSync(archivePath)) {
+    archivePath = join(archiveDir, `ws-${name}-${today}-${suffix++}`);
+  }
+
+  mkdirSync(archivePath, { recursive: true });
+
+  const filesMoved: string[] = [];
+  try {
+    const entries = readdirSync(wsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      renameSync(join(wsDir, entry.name), join(archivePath, entry.name));
+      filesMoved.push(entry.name);
+    }
+  } catch (err) {
+    for (const fname of filesMoved) {
+      try { renameSync(join(archivePath, fname), join(wsDir, fname)); } catch { /* rollback */ }
+    }
+    try { rmdirSync(archivePath); } catch { /* cleanup */ }
+    if (active === name) setActiveWorkstream(projectDir, name);
+    return { data: { completed: false, error: 'archive_failed', message: String(err), workstream: name } };
+  }
+
+  try { rmdirSync(wsDir); } catch { /* may not be empty */ }
+
+  let remainingWs = 0;
+  try {
+    remainingWs = readdirSync(wsRoot, { withFileTypes: true })
+      .filter(e => e.isDirectory()).length;
+    if (remainingWs === 0) rmdirSync(wsRoot);
+  } catch { /* best-effort */ }
+
+  return {
+    data: {
+      completed: true,
+      workstream: name,
+      archived_to: toPosixPath(relative(projectDir, archivePath)),
+      remaining_workstreams: remainingWs,
+      reverted_to_flat: remainingWs === 0,
+    },
+  };
+};
+
+/**
+ * Port of `cmdWorkstreamProgress` from `workstream.cjs` — aggregate status for each workstream.
+ * (Not the same as roadmap `progress` / `progressBar`.)
+ */
+export const workstreamProgress: QueryHandler = async (_args, projectDir) => {
+  const wsRoot = workstreamsDir(projectDir);
+
+  if (!existsSync(wsRoot)) {
+    return {
+      data: {
+        mode: 'flat',
+        workstreams: [],
+        message: 'No workstreams — operating in flat mode',
+      },
+    };
+  }
+
+  const active = getActiveWorkstream(projectDir);
+  const entries = readdirSync(wsRoot, { withFileTypes: true });
+  const workstreams: Array<{
+    name: string;
+    active: boolean;
+    status: string;
+    current_phase: string | null;
+    phases: string;
+    plans: string;
+    progress_percent: number;
+  }> = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const wsDir = join(wsRoot, entry.name);
+    const phasesDir = join(wsDir, 'phases');
+
+    const phaseDirsProgress = readSubdirectories(phasesDir);
+    const phaseCount = phaseDirsProgress.length;
+    let completedCount = 0;
+    let totalPlans = 0;
+    let completedPlans = 0;
+    for (const d of phaseDirsProgress) {
+      try {
+        const phaseFiles = readdirSync(join(phasesDir, d));
+        const plans = filterPlanFiles(phaseFiles);
+        const summaries = filterSummaryFiles(phaseFiles);
+        totalPlans += plans.length;
+        completedPlans += Math.min(summaries.length, plans.length);
+        if (plans.length > 0 && summaries.length >= plans.length) completedCount++;
+      } catch { /* skip */ }
+    }
+
+    let roadmapPhaseCount = phaseCount;
+    try {
+      const roadmapContent = readFileSync(join(wsDir, 'ROADMAP.md'), 'utf-8');
+      const phaseMatches = roadmapContent.match(/^###?\s+Phase\s+\d/gm);
+      if (phaseMatches) roadmapPhaseCount = phaseMatches.length;
+    } catch { /* no roadmap */ }
+
+    let status = 'unknown';
+    let currentPhase: string | null = null;
+    try {
+      const stateContent = readFileSync(join(wsDir, 'STATE.md'), 'utf-8');
+      status = stateExtractField(stateContent, 'Status') || 'unknown';
+      currentPhase = stateExtractField(stateContent, 'Current Phase');
+    } catch { /* skip */ }
+
+    workstreams.push({
+      name: entry.name,
+      active: entry.name === active,
+      status,
+      current_phase: currentPhase,
+      phases: `${completedCount}/${roadmapPhaseCount}`,
+      plans: `${completedPlans}/${totalPlans}`,
+      progress_percent:
+        roadmapPhaseCount > 0 ? Math.round((completedCount / roadmapPhaseCount) * 100) : 0,
+    });
+  }
+
+  return {
+    data: {
+      mode: 'workstream',
+      active,
+      workstreams,
+      count: workstreams.length,
+    },
+  };
+};

package/sdk/src/research-gate.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect } from 'vitest';
+import { checkResearchGate } from './research-gate.js';
+
+describe('checkResearchGate', () => {
+  // ── Pass cases ──────────────────────────────────────────────────────────
+
+  it('passes when no Open Questions section exists', () => {
+    const content = `# Research
+
+## Key Findings
+Everything is clear.
+
+## Recommendations
+Use TypeScript.`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(true);
+    expect(result.unresolvedQuestions).toEqual([]);
+  });
+
+  it('passes when Open Questions section has (RESOLVED) suffix', () => {
+    const content = `# Research
+
+## Open Questions (RESOLVED)
+
+1. **Hash prefix** — RESOLVED: Use "guest_contract:"
+2. **Cache TTL** — RESOLVED: 5 minutes`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(true);
+    expect(result.unresolvedQuestions).toEqual([]);
+  });
+
+  it('passes when Open Questions section is empty', () => {
+    const content = `# Research
+
+## Open Questions
+
+## Next Steps
+Proceed to planning.`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(true);
+    expect(result.unresolvedQuestions).toEqual([]);
+  });
+
+  it('passes when all individual questions are marked RESOLVED', () => {
+    const content = `# Research
+
+## Open Questions
+
+1. **Hash prefix** — RESOLVED: Use "guest_contract:"
+2. **Cache strategy** — RESOLVED: Use Redis with 5min TTL`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(true);
+    expect(result.unresolvedQuestions).toEqual([]);
+  });
+
+  it('passes with empty research content', () => {
+    const result = checkResearchGate('');
+    expect(result.pass).toBe(true);
+  });
+
+  // ── Fail cases ──────────────────────────────────────────────────────────
+
+  it('fails when Open Questions section has unresolved numbered items', () => {
+    const content = `# Research
+
+## Open Questions
+
+1. **Hash prefix** — keep or change?
+2. **Cache TTL** — what duration?
+
+## Recommendations
+Use TypeScript.`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(2);
+    expect(result.unresolvedQuestions[0]).toContain('Hash prefix');
+    expect(result.unresolvedQuestions[1]).toContain('Cache TTL');
+  });
+
+  it('fails when Open Questions has bullet-point items', () => {
+    const content = `# Research
+
+## Open Questions
+
+- **Auth strategy** — OAuth vs API keys?
+- **Database** — Postgres or SQLite?`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(2);
+  });
+
+  it('fails with mix of resolved and unresolved questions', () => {
+    const content = `# Research
+
+## Open Questions
+
+1. **Hash prefix** — RESOLVED: Use "guest_contract:"
+2. **Cache TTL** — what duration?
+3. **Auth flow** — RESOLVED: OAuth2
+4. **Rate limiting** — needs decision`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(2);
+    expect(result.unresolvedQuestions[0]).toContain('Cache TTL');
+    expect(result.unresolvedQuestions[1]).toContain('Rate limiting');
+  });
+
+  it('fails with prose-style open questions (no list formatting)', () => {
+    const content = `# Research
+
+## Open Questions
+
+We still need to determine the hashing strategy and whether
+the cache should be shared across instances.
+
+## Recommendations
+Use TypeScript.`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(1);
+    expect(result.unresolvedQuestions[0]).toContain('unstructured');
+  });
+
+  it('fails when Open Questions is the last section (no next heading)', () => {
+    const content = `# Research
+
+## Key Findings
+Good stuff.
+
+## Open Questions
+
+1. **Deployment strategy** — containers vs serverless?`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(1);
+    expect(result.unresolvedQuestions[0]).toContain('Deployment strategy');
+  });
+
+  // ── Edge cases ──────────────────────────────────────────────────────────
+
+  it('handles case-insensitive heading match', () => {
+    const content = `# Research
+
+## open questions
+
+1. **Something** — unclear`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+  });
+
+  it('does not match subsection headings (### Open Questions)', () => {
+    // Only ## level headings should trigger the gate
+    const content = `# Research
+
+## Findings
+
+### Open Questions
+These are just notes, not blocking.
+
+1. **Minor thing** — just a thought`;
+
+    // ### level = subsection under Findings, not the formal gate section
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(true);
+  });
+
+  it('handles asterisk-style bullet points', () => {
+    const content = `# Research
+
+## Open Questions
+
+* **Strategy A** — needs evaluation
+* **Strategy B** — RESOLVED: go with B`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(1);
+    expect(result.unresolvedQuestions[0]).toContain('Strategy A');
+  });
+});