gsd-remix 1.0.0

package/sdk/src/config.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { loadConfig, CONFIG_DEFAULTS } from './config.js';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('loadConfig', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `gsd-config-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns all defaults when config file is missing', async () => {
+    // No config.json created
+    await rm(join(tmpDir, '.planning', 'config.json'), { force: true });
+    const config = await loadConfig(tmpDir);
+    expect(config).toEqual(CONFIG_DEFAULTS);
+  });
+
+  it('returns all defaults when config file is empty', async () => {
+    await writeFile(join(tmpDir, '.planning', 'config.json'), '');
+    const config = await loadConfig(tmpDir);
+    expect(config).toEqual(CONFIG_DEFAULTS);
+  });
+
+  it('loads valid config and merges with defaults', async () => {
+    const userConfig = {
+      model_profile: 'fast',
+      workflow: { research: false },
+    };
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify(userConfig),
+    );
+
+    const config = await loadConfig(tmpDir);
+
+    expect(config.model_profile).toBe('fast');
+    expect(config.workflow.research).toBe(false);
+    // Other workflow defaults preserved
+    expect(config.workflow.plan_check).toBe(true);
+    expect(config.workflow.verifier).toBe(true);
+    // Top-level defaults preserved
+    expect(config.commit_docs).toBe(true);
+    expect(config.parallelization).toBe(true);
+  });
+
+  it('partial config merges correctly for nested objects', async () => {
+    const userConfig = {
+      git: { branching_strategy: 'milestone' },
+      hooks: { context_warnings: false },
+    };
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify(userConfig),
+    );
+
+    const config = await loadConfig(tmpDir);
+
+    expect(config.git.branching_strategy).toBe('milestone');
+    // Other git defaults preserved
+    expect(config.git.phase_branch_template).toBe('gsd/phase-{phase}-{slug}');
+    expect(config.hooks.context_warnings).toBe(false);
+  });
+
+  it('preserves unknown top-level keys', async () => {
+    const userConfig = { custom_key: 'custom_value' };
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify(userConfig),
+    );
+
+    const config = await loadConfig(tmpDir);
+    expect(config.custom_key).toBe('custom_value');
+  });
+
+  it('merges agent_skills', async () => {
+    const userConfig = {
+      agent_skills: { planner: 'custom-skill' },
+    };
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify(userConfig),
+    );
+
+    const config = await loadConfig(tmpDir);
+    expect(config.agent_skills).toEqual({ planner: 'custom-skill' });
+  });
+
+  // ─── Negative tests ─────────────────────────────────────────────────────
+
+  it('throws on malformed JSON', async () => {
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      '{bad json',
+    );
+
+    await expect(loadConfig(tmpDir)).rejects.toThrow(/Failed to parse config/);
+  });
+
+  it('throws when config is not an object (array)', async () => {
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      '[1, 2, 3]',
+    );
+
+    await expect(loadConfig(tmpDir)).rejects.toThrow(/must be a JSON object/);
+  });
+
+  it('throws when config is not an object (string)', async () => {
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      '"just a string"',
+    );
+
+    await expect(loadConfig(tmpDir)).rejects.toThrow(/must be a JSON object/);
+  });
+
+  it('ignores unknown keys without error', async () => {
+    const userConfig = {
+      totally_unknown: true,
+      another_unknown: { nested: 'value' },
+    };
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify(userConfig),
+    );
+
+    const config = await loadConfig(tmpDir);
+    // Should load fine, with unknowns passed through
+    expect(config.model_profile).toBe('balanced');
+    expect((config as Record<string, unknown>).totally_unknown).toBe(true);
+  });
+
+  it('handles wrong value types gracefully (user sets string instead of bool)', async () => {
+    const userConfig = {
+      commit_docs: 'yes', // should be boolean but we don't validate types
+      parallelization: 0,
+    };
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify(userConfig),
+    );
+
+    const config = await loadConfig(tmpDir);
+    // We pass through the user's values as-is — runtime code handles type mismatches
+    expect(config.commit_docs).toBe('yes');
+    expect(config.parallelization).toBe(0);
+  });
+
+  it('does not mutate CONFIG_DEFAULTS between calls', async () => {
+    const before = structuredClone(CONFIG_DEFAULTS);
+
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ model_profile: 'fast', workflow: { research: false } }),
+    );
+    await loadConfig(tmpDir);
+
+    expect(CONFIG_DEFAULTS).toEqual(before);
+  });
+});

package/sdk/src/config.ts

@@ -0,0 +1,177 @@
+/**
+ * Config reader — loads `.planning/config.json` and merges with defaults.
+ *
+ * Mirrors the default structure from `get-shit-done/bin/lib/config.cjs`
+ * `buildNewProjectConfig()`.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { relPlanningPath } from './workstream-utils.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface GitConfig {
+  branching_strategy: string;
+  phase_branch_template: string;
+  milestone_branch_template: string;
+  quick_branch_template: string | null;
+}
+
+export interface WorkflowConfig {
+  research: boolean;
+  plan_check: boolean;
+  verifier: boolean;
+  nyquist_validation: boolean;
+  /** Mirrors gsd-tools flat `config.tdd_mode` (from `workflow.tdd_mode`). */
+  tdd_mode: boolean;
+  auto_advance: boolean;
+  node_repair: boolean;
+  node_repair_budget: number;
+  ui_phase: boolean;
+  ui_safety_gate: boolean;
+  text_mode: boolean;
+  research_before_questions: boolean;
+  discuss_mode: string;
+  skip_discuss: boolean;
+  /** Maximum self-discuss passes in auto/headless mode before forcing proceed. Default: 3. */
+  max_discuss_passes: number;
+  /** Subagent timeout in ms (matches `get-shit-done/bin/lib/core.cjs` default 300000). */
+  subagent_timeout: number;
+}
+
+export interface HooksConfig {
+  context_warnings: boolean;
+}
+
+export interface GSDConfig {
+  model_profile: string;
+  commit_docs: boolean;
+  parallelization: boolean;
+  search_gitignored: boolean;
+  brave_search: boolean;
+  firecrawl: boolean;
+  exa_search: boolean;
+  git: GitConfig;
+  workflow: WorkflowConfig;
+  hooks: HooksConfig;
+  agent_skills: Record<string, unknown>;
+  /** Project slug for branch templates; mirrors gsd-tools `config.project_code`. */
+  project_code?: string | null;
+  /** Interactive vs headless; mirrors gsd-tools flat `config.mode`. */
+  mode?: string;
+  /** Internal auto-chain flag; mirrors gsd-tools `config._auto_chain_active`. */
+  _auto_chain_active?: boolean;
+  [key: string]: unknown;
+}
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+export const CONFIG_DEFAULTS: GSDConfig = {
+  model_profile: 'balanced',
+  commit_docs: true,
+  parallelization: true,
+  search_gitignored: false,
+  brave_search: false,
+  firecrawl: false,
+  exa_search: false,
+  git: {
+    branching_strategy: 'none',
+    phase_branch_template: 'gsd/phase-{phase}-{slug}',
+    milestone_branch_template: 'gsd/{milestone}-{slug}',
+    quick_branch_template: null,
+  },
+  workflow: {
+    research: true,
+    plan_check: true,
+    verifier: true,
+    nyquist_validation: true,
+    tdd_mode: false,
+    auto_advance: false,
+    node_repair: true,
+    node_repair_budget: 2,
+    ui_phase: true,
+    ui_safety_gate: true,
+    text_mode: false,
+    research_before_questions: false,
+    discuss_mode: 'discuss',
+    skip_discuss: false,
+    max_discuss_passes: 3,
+    subagent_timeout: 300000,
+  },
+  hooks: {
+    context_warnings: true,
+  },
+  agent_skills: {},
+  project_code: null,
+  mode: 'interactive',
+  _auto_chain_active: false,
+};
+
+// ─── Loader ──────────────────────────────────────────────────────────────────
+
+/**
+ * Load project config from `.planning/config.json`, merging with defaults.
+ * Returns full defaults when file is missing or empty.
+ * Throws on malformed JSON with a helpful error message.
+ */
+export async function loadConfig(projectDir: string, workstream?: string): Promise<GSDConfig> {
+  const configPath = join(projectDir, relPlanningPath(workstream), 'config.json');
+  const rootConfigPath = join(projectDir, '.planning', 'config.json');
+
+  let raw: string;
+  try {
+    raw = await readFile(configPath, 'utf-8');
+  } catch {
+    // If workstream config missing, fall back to root config
+    if (workstream) {
+      try {
+        raw = await readFile(rootConfigPath, 'utf-8');
+      } catch {
+        return structuredClone(CONFIG_DEFAULTS);
+      }
+    } else {
+      // File missing — normal for new projects
+      return structuredClone(CONFIG_DEFAULTS);
+    }
+  }
+
+  const trimmed = raw.trim();
+  if (trimmed === '') {
+    return structuredClone(CONFIG_DEFAULTS);
+  }
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to parse config at ${configPath}: ${msg}`);
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Config at ${configPath} must be a JSON object`);
+  }
+
+  // Three-level deep merge: defaults <- parsed
+  return {
+    ...structuredClone(CONFIG_DEFAULTS),
+    ...parsed,
+    git: {
+      ...CONFIG_DEFAULTS.git,
+      ...(parsed.git as Partial<GitConfig> ?? {}),
+    },
+    workflow: {
+      ...CONFIG_DEFAULTS.workflow,
+      ...(parsed.workflow as Partial<WorkflowConfig> ?? {}),
+    },
+    hooks: {
+      ...CONFIG_DEFAULTS.hooks,
+      ...(parsed.hooks as Partial<HooksConfig> ?? {}),
+    },
+    agent_skills: {
+      ...CONFIG_DEFAULTS.agent_skills,
+      ...(parsed.agent_skills as Record<string, unknown> ?? {}),
+    },
+  };
+}

package/sdk/src/context-engine.test.ts

@@ -0,0 +1,295 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { ContextEngine, PHASE_FILE_MANIFEST } from './context-engine.js';
+import { PhaseType } from './types.js';
+import type { GSDLogger } from './logger.js';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+async function createTempProject(): Promise<string> {
+  return mkdtemp(join(tmpdir(), 'gsd-ctx-'));
+}
+
+async function createPlanningDir(projectDir: string, files: Record<string, string>): Promise<void> {
+  const planningDir = join(projectDir, '.planning');
+  await mkdir(planningDir, { recursive: true });
+  for (const [filename, content] of Object.entries(files)) {
+    await writeFile(join(planningDir, filename), content, 'utf-8');
+  }
+}
+
+function makeMockLogger(): GSDLogger {
+  return {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    setPhase: vi.fn(),
+    setPlan: vi.fn(),
+    setSessionId: vi.fn(),
+  } as unknown as GSDLogger;
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('ContextEngine', () => {
+  let projectDir: string;
+
+  beforeEach(async () => {
+    projectDir = await createTempProject();
+  });
+
+  afterEach(async () => {
+    await rm(projectDir, { recursive: true, force: true });
+  });
+
+  describe('resolveContextFiles', () => {
+    it('returns all files for plan phase when all exist', async () => {
+      await createPlanningDir(projectDir, {
+        'STATE.md': '# State\nproject: test',
+        'ROADMAP.md': '# Roadmap\nphase 01',
+        'CONTEXT.md': '# Context\nstack: node',
+        'RESEARCH.md': '# Research\nfindings here',
+        'REQUIREMENTS.md': '# Requirements\nR1: auth',
+      });
+
+      const engine = new ContextEngine(projectDir);
+      const files = await engine.resolveContextFiles(PhaseType.Plan);
+
+      expect(files.state).toBe('# State\nproject: test');
+      expect(files.roadmap).toBe('# Roadmap\nphase 01');
+      expect(files.context).toBe('# Context\nstack: node');
+      expect(files.research).toBe('# Research\nfindings here');
+      expect(files.requirements).toBe('# Requirements\nR1: auth');
+    });
+
+    it('returns minimal files for execute phase', async () => {
+      await createPlanningDir(projectDir, {
+        'STATE.md': '# State',
+        'config.json': '{"model":"claude"}',
+        'ROADMAP.md': '# Roadmap — should not be read',
+        'CONTEXT.md': '# Context — should not be read',
+      });
+
+      const engine = new ContextEngine(projectDir);
+      const files = await engine.resolveContextFiles(PhaseType.Execute);
+
+      expect(files.state).toBe('# State');
+      expect(files.config).toBe('{"model":"claude"}');
+      expect(files.roadmap).toBeUndefined();
+      expect(files.context).toBeUndefined();
+    });
+
+    it('returns state + roadmap + context for research phase', async () => {
+      await createPlanningDir(projectDir, {
+        'STATE.md': '# State',
+        'ROADMAP.md': '# Roadmap',
+        'CONTEXT.md': '# Context',
+      });
+
+      const engine = new ContextEngine(projectDir);
+      const files = await engine.resolveContextFiles(PhaseType.Research);
+
+      expect(files.state).toBe('# State');
+      expect(files.roadmap).toBe('# Roadmap');
+      expect(files.context).toBe('# Context');
+      expect(files.requirements).toBeUndefined();
+    });
+
+    it('returns state + roadmap + requirements for verify phase', async () => {
+      await createPlanningDir(projectDir, {
+        'STATE.md': '# State',
+        'ROADMAP.md': '# Roadmap',
+        'REQUIREMENTS.md': '# Requirements',
+        'PLAN.md': '# Plan',
+        'SUMMARY.md': '# Summary',
+      });
+
+      const engine = new ContextEngine(projectDir);
+      const files = await engine.resolveContextFiles(PhaseType.Verify);
+
+      expect(files.state).toBe('# State');
+      expect(files.roadmap).toBe('# Roadmap');
+      expect(files.requirements).toBe('# Requirements');
+      expect(files.plan).toBe('# Plan');
+      expect(files.summary).toBe('# Summary');
+    });
+
+    it('returns state + optional files for discuss phase', async () => {
+      await createPlanningDir(projectDir, {
+        'STATE.md': '# State',
+        'ROADMAP.md': '# Roadmap',
+      });
+
+      const engine = new ContextEngine(projectDir);
+      const files = await engine.resolveContextFiles(PhaseType.Discuss);
+
+      expect(files.state).toBe('# State');
+      expect(files.roadmap).toBe('# Roadmap');
+      expect(files.context).toBeUndefined();
+    });
+
+    it('returns undefined for missing optional files without warning', async () => {
+      await createPlanningDir(projectDir, {
+        'STATE.md': '# State',
+        'ROADMAP.md': '# Roadmap',
+        'CONTEXT.md': '# Context',
+      });
+
+      const logger = makeMockLogger();
+      const engine = new ContextEngine(projectDir, logger);
+      const files = await engine.resolveContextFiles(PhaseType.Plan);
+
+      // research and requirements are optional for plan — no warning
+      expect(files.research).toBeUndefined();
+      expect(files.requirements).toBeUndefined();
+      expect(logger.warn).not.toHaveBeenCalled();
+    });
+
+    it('warns for missing required files', async () => {
+      // Empty .planning dir — STATE.md is required for all phases
+      await createPlanningDir(projectDir, {});
+
+      const logger = makeMockLogger();
+      const engine = new ContextEngine(projectDir, logger);
+      await engine.resolveContextFiles(PhaseType.Execute);
+
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('STATE.md'),
+        expect.objectContaining({ phase: PhaseType.Execute }),
+      );
+    });
+
+    it('handles missing .planning directory gracefully', async () => {
+      // No .planning dir at all
+      const engine = new ContextEngine(projectDir);
+      const files = await engine.resolveContextFiles(PhaseType.Execute);
+
+      expect(files.state).toBeUndefined();
+      expect(files.config).toBeUndefined();
+    });
+
+    it('handles empty file content', async () => {
+      await createPlanningDir(projectDir, {
+        'STATE.md': '',
+      });
+
+      const engine = new ContextEngine(projectDir);
+      const files = await engine.resolveContextFiles(PhaseType.Execute);
+
+      // Empty string is still defined — the file exists
+      expect(files.state).toBe('');
+    });
+  });
+
+  describe('context truncation', () => {
+    it('truncates files exceeding maxContentLength', async () => {
+      const largeContent = Array.from({ length: 100 }, (_, i) =>
+        `## Section ${i}\n\nFirst paragraph.\n\nLong detail ${'x'.repeat(200)}.`
+      ).join('\n\n');
+
+      await createPlanningDir(projectDir, {
+        'STATE.md': '# State',
+        'ROADMAP.md': '# Roadmap',
+        'CONTEXT.md': largeContent,
+      });
+
+      const engine = new ContextEngine(projectDir, undefined, { maxContentLength: 500 });
+      const files = await engine.resolveContextFiles(PhaseType.Plan);
+
+      // CONTEXT.md should be truncated
+      expect(files.context!.length).toBeLessThan(largeContent.length);
+      expect(files.context).toContain('[...');
+    });
+
+    it('does not truncate files below threshold', async () => {
+      await createPlanningDir(projectDir, {
+        'STATE.md': '# State\nproject: test',
+        'ROADMAP.md': '# Roadmap\nphase 01',
+        'CONTEXT.md': '# Context\nstack: node',
+      });
+
+      const engine = new ContextEngine(projectDir);
+      const files = await engine.resolveContextFiles(PhaseType.Plan);
+
+      expect(files.context).toBe('# Context\nstack: node');
+    });
+
+    it('never truncates STATE.md (not in truncatable list)', async () => {
+      const largeState = `# State\n\n${'x'.repeat(20000)}`;
+      await createPlanningDir(projectDir, {
+        'STATE.md': largeState,
+      });
+
+      const engine = new ContextEngine(projectDir, undefined, { maxContentLength: 100 });
+      const files = await engine.resolveContextFiles(PhaseType.Execute);
+
+      expect(files.state).toBe(largeState);
+    });
+
+    it('extracts current milestone from ROADMAP.md when state is available', async () => {
+      const roadmap = `# Roadmap
+
+## Milestone 1: Setup
+### Phase 01
+Setup content.
+
+## Milestone 2: Build
+### Phase 02
+Build content.`;
+
+      await createPlanningDir(projectDir, {
+        'STATE.md': 'Current Milestone: Build',
+        'ROADMAP.md': roadmap,
+        'CONTEXT.md': '# Context',
+      });
+
+      const engine = new ContextEngine(projectDir);
+      const files = await engine.resolveContextFiles(PhaseType.Plan);
+
+      expect(files.roadmap).toContain('## Milestone 2: Build');
+      expect(files.roadmap).not.toContain('### Phase 01');
+    });
+
+    it('respects custom truncation options', async () => {
+      const content = '## Heading\n\nParagraph.\n\nMore.\n' + 'x'.repeat(500);
+      await createPlanningDir(projectDir, {
+        'STATE.md': '# State',
+        'ROADMAP.md': '# Roadmap',
+        'CONTEXT.md': content,
+      });
+
+      // Low threshold forces truncation
+      const engine = new ContextEngine(projectDir, undefined, { maxContentLength: 50 });
+      const files = await engine.resolveContextFiles(PhaseType.Plan);
+      expect(files.context!.length).toBeLessThan(content.length);
+    });
+  });
+
+  describe('PHASE_FILE_MANIFEST', () => {
+    it('covers all phase types', () => {
+      for (const phase of Object.values(PhaseType)) {
+        expect(PHASE_FILE_MANIFEST[phase]).toBeDefined();
+        expect(PHASE_FILE_MANIFEST[phase].length).toBeGreaterThan(0);
+      }
+    });
+
+    it('execute phase has fewest files', () => {
+      const executeCount = PHASE_FILE_MANIFEST[PhaseType.Execute].length;
+      const planCount = PHASE_FILE_MANIFEST[PhaseType.Plan].length;
+      expect(executeCount).toBeLessThan(planCount);
+    });
+
+    it('every spec has required key, filename, and required flag', () => {
+      for (const specs of Object.values(PHASE_FILE_MANIFEST)) {
+        for (const spec of specs) {
+          expect(spec.key).toBeDefined();
+          expect(spec.filename).toBeDefined();
+          expect(typeof spec.required).toBe('boolean');
+        }
+      }
+    });
+  });
+});