@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdk/src/config.test.ts

@@ -0,0 +1,271 @@
+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;
+  let fakeHome: string;
+  let prevHome: string | undefined;
+  let prevSddHome: string | undefined;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `sdd-config-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+    // Isolate ~/.sdd/defaults.json by pointing HOME at an empty tmp dir.
+    fakeHome = join(tmpdir(), `sdd-home-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(fakeHome, { recursive: true });
+    prevHome = process.env.HOME;
+    process.env.HOME = fakeHome;
+    // Also isolate SDD_HOME (loadUserDefaults prefers it over HOME).
+    prevSddHome = process.env.SDD_HOME;
+    delete process.env.SDD_HOME;
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+    await rm(fakeHome, { recursive: true, force: true });
+    if (prevHome === undefined) delete process.env.HOME;
+    else process.env.HOME = prevHome;
+    if (prevSddHome === undefined) delete process.env.SDD_HOME;
+    else process.env.SDD_HOME = prevSddHome;
+  });
+
+  async function writeUserDefaults(defaults: unknown) {
+    await mkdir(join(fakeHome, '.sdd'), { recursive: true });
+    await writeFile(join(fakeHome, '.sdd', 'defaults.json'), JSON.stringify(defaults));
+  }
+
+  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('sdd/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);
+  });
+
+  // ─── User-level defaults (~/.sdd/defaults.json) ─────────────────────────
+  // Regression: issue #2652 — SDK loadConfig ignored user-level defaults
+  // for pre-project Codex installs, so init.quick still emitted Claude
+  // model aliases from MODEL_PROFILES via resolveModel even when the user
+  // had `resolve_model_ids: "omit"` in ~/.sdd/defaults.json.
+  //
+  // Mirrors current CJS parity expectations for SDK loadConfig + resolveModel:
+  // in pre-project context, loadConfig ignores ~/.sdd/defaults.json so
+  // resolveModel/MODEL_PROFILES do not emit aliases when resolve_model_ids
+  // is "omit". Once a project is initialized, config.json is authoritative,
+  // because buildNewProjectConfig bakes user defaults into project config
+  // at /sdd-new-project time.
+
+  it('pre-project: ignores user defaults and uses built-in defaults', async () => {
+    await writeUserDefaults({ resolve_model_ids: 'omit' });
+    const config = await loadConfig(tmpDir);
+    expect((config as Record<string, unknown>).resolve_model_ids).toBeUndefined();
+    expect(config.model_profile).toBe('balanced');
+    expect(config.workflow.plan_check).toBe(true);
+  });
+
+  it('pre-project: keeps built-in nested defaults even when user defaults exist', async () => {
+    await writeUserDefaults({
+      git: { branching_strategy: 'milestone' },
+      agent_skills: { planner: 'user-skill' },
+    });
+
+    const config = await loadConfig(tmpDir);
+    expect(config.git.branching_strategy).toBe('none');
+    expect(config.git.phase_branch_template).toBe('sdd/phase-{phase}-{slug}');
+    expect(config.agent_skills).toEqual({});
+  });
+
+  it('project config is authoritative over user defaults (CJS parity)', async () => {
+    // User defaults set resolve_model_ids: "omit", but project config omits it.
+    // Per CJS core.cjs loadConfig (#1683): once .planning/config.json exists,
+    // ~/.sdd/defaults.json is ignored — buildNewProjectConfig already baked
+    // the user defaults in at project creation time.
+    await writeUserDefaults({
+      resolve_model_ids: 'omit',
+      model_profile: 'fast',
+    });
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ model_profile: 'quality' }),
+    );
+
+    const config = await loadConfig(tmpDir);
+    expect(config.model_profile).toBe('quality');
+    // User-defaults not layered when project config present
+    expect((config as Record<string, unknown>).resolve_model_ids).toBeUndefined();
+  });
+
+  it('ignores malformed ~/.sdd/defaults.json', async () => {
+    await mkdir(join(fakeHome, '.sdd'), { recursive: true });
+    await writeFile(join(fakeHome, '.sdd', 'defaults.json'), '{not json');
+
+    const config = await loadConfig(tmpDir);
+    // Falls back to built-in defaults
+    expect(config).toEqual(CONFIG_DEFAULTS);
+  });
+
+  it('maps legacy top-level branching_strategy into git.branching_strategy', async () => {
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ branching_strategy: 'phase' }),
+    );
+
+    const config = await loadConfig(tmpDir);
+    expect(config.git.branching_strategy).toBe('phase');
+  });
+
+  it('git.branching_strategy overrides legacy top-level branching_strategy when both are present', async () => {
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ branching_strategy: 'phase', git: { branching_strategy: 'milestone' } }),
+    );
+
+    const config = await loadConfig(tmpDir);
+    expect(config.git.branching_strategy).toBe('milestone');
+  });
+
+  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,218 @@
+/**
+ * Config reader — loads `.planning/config.json` and merges with defaults.
+ *
+ * Mirrors the default structure from `sdd/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 sdd-tools flat `config.tdd_mode` (from `workflow.tdd_mode`). */
+  tdd_mode: boolean;
+  /**
+   * Issue #3309. `end-of-phase` (default) suppresses mid-flight
+   * `<task type="checkpoint:human-verify">` task emission; the planner
+   * embeds verification details into the relevant `auto` task's
+   * `<verify><human-check>` block and the verifier harvests them at
+   * end-of-phase into the existing HUMAN-UAT.md path. `mid-flight`
+   * restores the pre-#3309 behavior where the executor halts at each
+   * `checkpoint:human-verify` task and pays a full executor cold-start
+   * cost (CLAUDE.md, MEMORY.md, STATE.md, plan re-read on respawn) per
+   * round-trip.
+   */
+  human_verify_mode: 'mid-flight' | 'end-of-phase';
+  auto_advance: boolean;
+  /** Internal auto-chain flag used by workflow routing. */
+  _auto_chain_active?: 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 `sdd/bin/lib/core.cjs` default 300000). */
+  subagent_timeout: number;
+  /**
+   * Issue #2492. When true (default), enforces that every trackable decision in
+   * CONTEXT.md `<decisions>` is referenced by at least one plan (translation
+   * gate, blocking) and reports decisions not honored by shipped artifacts at
+   * verify-phase (validation gate, non-blocking). Set false to disable both.
+   */
+  context_coverage_gate: boolean;
+}
+
+export interface HooksConfig {
+  context_warnings: boolean;
+}
+
+export interface SDDConfig {
+  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 sdd-tools `config.project_code`. */
+  project_code?: string | null;
+  /** Interactive vs headless; mirrors sdd-tools flat `config.mode`. */
+  mode?: string;
+  [key: string]: unknown;
+}
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+export const CONFIG_DEFAULTS: SDDConfig = {
+  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: 'sdd/phase-{phase}-{slug}',
+    milestone_branch_template: 'sdd/{milestone}-{slug}',
+    quick_branch_template: null,
+  },
+  workflow: {
+    research: true,
+    plan_check: true,
+    verifier: true,
+    nyquist_validation: true,
+    tdd_mode: false,
+    human_verify_mode: 'end-of-phase',
+    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,
+    context_coverage_gate: true,
+    _auto_chain_active: false,
+  },
+  hooks: {
+    context_warnings: true,
+  },
+  agent_skills: {},
+  project_code: null,
+  mode: 'interactive',
+};
+
+// ─── Loader ──────────────────────────────────────────────────────────────────
+
+/**
+ * Load project config from `.planning/config.json`, merging with defaults.
+ * When project config is missing or empty, this returns `mergeDefaults({})`
+ * (built-in defaults only; no `~/.sdd/defaults.json` layering).
+ * Throws on malformed JSON with a helpful error message.
+ */
+export async function loadConfig(projectDir: string, workstream?: string): Promise<SDDConfig> {
+  const configPath = join(projectDir, relPlanningPath(workstream), 'config.json');
+  const rootConfigPath = join(projectDir, '.planning', 'config.json');
+
+  let raw: string;
+  let projectConfigFound = false;
+  try {
+    raw = await readFile(configPath, 'utf-8');
+    projectConfigFound = true;
+  } catch {
+    // If workstream config missing, fall back to root config
+    if (workstream) {
+      try {
+        raw = await readFile(rootConfigPath, 'utf-8');
+        projectConfigFound = true;
+      } catch {
+        raw = '';
+      }
+    } else {
+      raw = '';
+    }
+  }
+
+  // Pre-project context: no .planning/config.json exists.
+  // Use built-in defaults only so SDK query parity stays stable across machines.
+  if (!projectConfigFound) {
+    return mergeDefaults({});
+  }
+
+  const trimmed = raw.trim();
+  if (trimmed === '') {
+    // Empty project config — treat as no project config.
+    return mergeDefaults({});
+  }
+
+  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`);
+  }
+
+  // Project config exists — user-level defaults are ignored (CJS parity).
+  // `buildNewProjectConfig` already baked them into config.json at /sdd-new-project.
+  return mergeDefaults(parsed);
+}
+
+function mergeDefaults(parsed: Record<string, unknown>): SDDConfig {
+  const legacyBranchingStrategy = typeof parsed.branching_strategy === 'string'
+    ? parsed.branching_strategy
+    : undefined;
+
+  return {
+    ...structuredClone(CONFIG_DEFAULTS),
+    ...parsed,
+    git: {
+      ...CONFIG_DEFAULTS.git,
+      ...(legacyBranchingStrategy ? { branching_strategy: legacyBranchingStrategy } : {}),
+      ...(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> ?? {}),
+    },
+  };
+}