@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdk/src/query/frontmatter-mutation.test.ts

@@ -0,0 +1,259 @@
+/**
+ * Unit tests for frontmatter mutation handlers.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  reconstructFrontmatter,
+  spliceFrontmatter,
+  frontmatterSet,
+  frontmatterMerge,
+  frontmatterValidate,
+  FRONTMATTER_SCHEMAS,
+} from './frontmatter-mutation.js';
+import { extractFrontmatter } from './frontmatter.js';
+
+// ─── reconstructFrontmatter ─────────────────────────────────────────────────
+
+describe('reconstructFrontmatter', () => {
+  it('serializes flat key-value pairs', () => {
+    const result = reconstructFrontmatter({ phase: '10', plan: '01' });
+    expect(result).toContain('phase: 10');
+    expect(result).toContain('plan: 01');
+  });
+
+  it('serializes short arrays inline', () => {
+    const result = reconstructFrontmatter({ tags: ['a', 'b', 'c'] });
+    expect(result).toBe('tags: [a, b, c]');
+  });
+
+  it('serializes long arrays as dash items', () => {
+    const result = reconstructFrontmatter({
+      items: ['alpha', 'bravo', 'charlie', 'delta'],
+    });
+    expect(result).toContain('items:');
+    expect(result).toContain('  - alpha');
+    expect(result).toContain('  - delta');
+  });
+
+  it('serializes empty arrays as []', () => {
+    const result = reconstructFrontmatter({ depends_on: [] });
+    expect(result).toBe('depends_on: []');
+  });
+
+  it('serializes nested objects with 2-space indent', () => {
+    const result = reconstructFrontmatter({ progress: { total: 5, done: 3 } });
+    expect(result).toContain('progress:');
+    expect(result).toContain('  total: 5');
+    expect(result).toContain('  done: 3');
+  });
+
+  it('skips null and undefined values', () => {
+    const result = reconstructFrontmatter({ a: 'yes', b: null, c: undefined });
+    expect(result).toBe('a: yes');
+  });
+
+  it('quotes strings containing colons', () => {
+    const result = reconstructFrontmatter({ label: 'key: value' });
+    expect(result).toContain('"key: value"');
+  });
+
+  it('quotes strings containing hash', () => {
+    const result = reconstructFrontmatter({ label: 'color #red' });
+    expect(result).toContain('"color #red"');
+  });
+
+  it('quotes strings starting with [ or {', () => {
+    const result = reconstructFrontmatter({ data: '[1,2,3]' });
+    expect(result).toContain('"[1,2,3]"');
+  });
+});
+
+// ─── spliceFrontmatter ──────────────────────────────────────────────────────
+
+describe('spliceFrontmatter', () => {
+  it('replaces existing frontmatter block', () => {
+    const content = '---\nphase: 10\n---\n\n# Body';
+    const result = spliceFrontmatter(content, { phase: '11', plan: '01' });
+    expect(result).toMatch(/^---\nphase: 11\nplan: 01\n---/);
+    expect(result).toContain('# Body');
+  });
+
+  it('prepends frontmatter when none exists', () => {
+    const content = '# Just a body';
+    const result = spliceFrontmatter(content, { phase: '10' });
+    expect(result).toMatch(/^---\nphase: 10\n---\n\n# Just a body/);
+  });
+});
+
+// ─── frontmatterSet ─────────────────────────────────────────────────────────
+
+describe('frontmatterSet', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'sdd-fm-set-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('writes a single field and round-trips through extractFrontmatter', async () => {
+    const filePath = join(tmpDir, 'test.md');
+    await writeFile(filePath, '---\nphase: 10\nplan: 01\n---\n\n# Body\n');
+
+    await frontmatterSet([filePath, 'status', 'executing'], tmpDir);
+
+    const content = await readFile(filePath, 'utf-8');
+    const fm = extractFrontmatter(content);
+    expect(fm.status).toBe('executing');
+    expect(fm.phase).toBe('10');
+  });
+
+  it('converts boolean string values', async () => {
+    const filePath = join(tmpDir, 'test.md');
+    await writeFile(filePath, '---\nphase: 10\n---\n\n# Body\n');
+
+    await frontmatterSet([filePath, 'autonomous', 'true'], tmpDir);
+
+    const content = await readFile(filePath, 'utf-8');
+    const fm = extractFrontmatter(content);
+    expect(fm.autonomous).toBe('true');
+  });
+
+  it('handles numeric string values', async () => {
+    const filePath = join(tmpDir, 'test.md');
+    await writeFile(filePath, '---\nphase: 10\n---\n\n# Body\n');
+
+    await frontmatterSet([filePath, 'wave', '3'], tmpDir);
+
+    const content = await readFile(filePath, 'utf-8');
+    const fm = extractFrontmatter(content);
+    // reconstructFrontmatter outputs the number, extractFrontmatter reads it back as string
+    expect(String(fm.wave)).toBe('3');
+  });
+
+  it('rejects null bytes in file path', async () => {
+    await expect(
+      frontmatterSet(['/path/with\0null', 'key', 'val'], tmpDir)
+    ).rejects.toThrow(/null bytes/);
+  });
+});
+
+// ─── frontmatterMerge ───────────────────────────────────────────────────────
+
+describe('frontmatterMerge', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'sdd-fm-merge-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('deep merges JSON into existing frontmatter', async () => {
+    const filePath = join(tmpDir, 'test.md');
+    await writeFile(filePath, '---\nphase: 10\nplan: 01\n---\n\n# Body\n');
+
+    const result = await frontmatterMerge(
+      [filePath, JSON.stringify({ status: 'done', wave: 2 })],
+      tmpDir
+    );
+
+    const content = await readFile(filePath, 'utf-8');
+    const fm = extractFrontmatter(content);
+    expect(fm.phase).toBe('10');
+    expect(fm.status).toBe('done');
+    expect((result.data as Record<string, unknown>).merged).toBe(true);
+  });
+
+  it('rejects invalid JSON', async () => {
+    const filePath = join(tmpDir, 'test.md');
+    await writeFile(filePath, '---\nphase: 10\n---\n\n# Body\n');
+
+    await expect(
+      frontmatterMerge([filePath, 'not-json'], tmpDir)
+    ).rejects.toThrow();
+  });
+});
+
+// ─── frontmatterValidate ────────────────────────────────────────────────────
+
+describe('frontmatterValidate', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'sdd-fm-validate-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('validates a valid plan file', async () => {
+    const filePath = join(tmpDir, 'plan.md');
+    const fm = '---\nphase: 10\nplan: 01\ntype: execute\nwave: 1\ndepends_on: []\nfiles_modified: []\nautonomous: true\nmust_haves:\n  truths:\n    - foo\n---\n\n# Plan\n';
+    await writeFile(filePath, fm);
+
+    const result = await frontmatterValidate([filePath, '--schema', 'plan'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.valid).toBe(true);
+    expect((data.missing as string[]).length).toBe(0);
+  });
+
+  it('detects missing fields', async () => {
+    const filePath = join(tmpDir, 'plan.md');
+    await writeFile(filePath, '---\nphase: 10\n---\n\n# Plan\n');
+
+    const result = await frontmatterValidate([filePath, '--schema', 'plan'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.valid).toBe(false);
+    expect((data.missing as string[]).length).toBeGreaterThan(0);
+  });
+
+  it('rejects unknown schema', async () => {
+    const filePath = join(tmpDir, 'test.md');
+    await writeFile(filePath, '---\nphase: 10\n---\n\n# Body\n');
+
+    await expect(
+      frontmatterValidate([filePath, '--schema', 'unknown'], tmpDir)
+    ).rejects.toThrow(/Unknown schema/);
+  });
+
+  it('has plan, summary, and verification schemas', () => {
+    expect(FRONTMATTER_SCHEMAS).toHaveProperty('plan');
+    expect(FRONTMATTER_SCHEMAS).toHaveProperty('summary');
+    expect(FRONTMATTER_SCHEMAS).toHaveProperty('verification');
+  });
+});
+
+// ─── Round-trip (extract → reconstruct → splice) ───────────────────────────
+
+describe('frontmatter round-trip', () => {
+  it('preserves scalar and list fields through extract + splice', () => {
+    const original = `---
+phase: "01"
+plan: "02"
+type: execute
+wave: 1
+depends_on: []
+tags: [a, b]
+---
+# Title
+`;
+    const fm = extractFrontmatter(original) as Record<string, unknown>;
+    const spliced = spliceFrontmatter('# Title\n', fm);
+    expect(spliced.startsWith('---\n')).toBe(true);
+    const round = extractFrontmatter(spliced) as Record<string, unknown>;
+    expect(String(round.phase)).toBe('01');
+    // YAML may round-trip wave as number or string depending on parser output
+    expect(Number(round.wave)).toBe(1);
+    expect(Array.isArray(round.tags)).toBe(true);
+  });
+});

package/sdk/src/query/frontmatter-mutation.ts

@@ -0,0 +1,343 @@
+/**
+ * Frontmatter mutation handlers — write operations for YAML frontmatter.
+ *
+ * Ported from sdd/bin/lib/frontmatter.cjs.
+ * Provides reconstructFrontmatter (serialization), spliceFrontmatter (replacement),
+ * and query handlers for frontmatter.set, frontmatter.merge, frontmatter.validate.
+ *
+ * @example
+ * ```typescript
+ * import { reconstructFrontmatter, spliceFrontmatter } from './frontmatter-mutation.js';
+ *
+ * const yaml = reconstructFrontmatter({ phase: '10', tags: ['a', 'b'] });
+ * // 'phase: 10\ntags: [a, b]'
+ *
+ * const updated = spliceFrontmatter('---\nold: val\n---\nbody', { new: 'val' });
+ * // '---\nnew: val\n---\nbody'
+ * ```
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { SDDError, ErrorClassification } from '../errors.js';
+import { extractFrontmatter } from './frontmatter.js';
+import { normalizeMd, resolvePathUnderProject } from './helpers.js';
+import type { QueryHandler } from './utils.js';
+
+// ─── FRONTMATTER_SCHEMAS ──────────────────────────────────────────────────
+
+/** Schema definitions for frontmatter validation. */
+export const FRONTMATTER_SCHEMAS: Record<string, { required: string[] }> = {
+  plan: { required: ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'] },
+  summary: { required: ['phase', 'plan', 'subsystem', 'tags', 'duration', 'completed'] },
+  verification: { required: ['phase', 'verified', 'status', 'score'] },
+};
+
+// ─── reconstructFrontmatter ────────────────────────────────────────────────
+
+/**
+ * Serialize a flat/nested object into YAML frontmatter lines.
+ *
+ * Port of `reconstructFrontmatter` from frontmatter.cjs lines 122-183.
+ * Handles arrays (inline/dash), nested objects (2 levels), and quoting.
+ *
+ * @param obj - Object to serialize
+ * @returns YAML string (without --- delimiters)
+ */
+export function reconstructFrontmatter(obj: Record<string, unknown>): string {
+  const lines: string[] = [];
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === null || value === undefined) continue;
+
+    if (Array.isArray(value)) {
+      serializeArray(lines, key, value, '');
+    } else if (typeof value === 'object') {
+      lines.push(`${key}:`);
+      for (const [subkey, subval] of Object.entries(value as Record<string, unknown>)) {
+        if (subval === null || subval === undefined) continue;
+        if (Array.isArray(subval)) {
+          serializeArray(lines, subkey, subval, '  ');
+        } else if (typeof subval === 'object') {
+          lines.push(`  ${subkey}:`);
+          for (const [subsubkey, subsubval] of Object.entries(subval as Record<string, unknown>)) {
+            if (subsubval === null || subsubval === undefined) continue;
+            if (Array.isArray(subsubval)) {
+              if (subsubval.length === 0) {
+                lines.push(`    ${subsubkey}: []`);
+              } else {
+                lines.push(`    ${subsubkey}:`);
+                for (const item of subsubval) {
+                  lines.push(`      - ${item}`);
+                }
+              }
+            } else {
+              lines.push(`    ${subsubkey}: ${subsubval}`);
+            }
+          }
+        } else {
+          const sv = String(subval);
+          lines.push(`  ${subkey}: ${needsQuoting(sv) ? `"${sv}"` : sv}`);
+        }
+      }
+    } else {
+      const sv = String(value);
+      if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{')) {
+        lines.push(`${key}: "${sv}"`);
+      } else {
+        lines.push(`${key}: ${sv}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/** Serialize an array at the given indent level. */
+function serializeArray(lines: string[], key: string, arr: unknown[], indent: string): void {
+  if (arr.length === 0) {
+    lines.push(`${indent}${key}: []`);
+  } else if (
+    arr.every(v => typeof v === 'string') &&
+    arr.length <= 3 &&
+    (arr as string[]).join(', ').length < 60
+  ) {
+    lines.push(`${indent}${key}: [${(arr as string[]).join(', ')}]`);
+  } else {
+    lines.push(`${indent}${key}:`);
+    for (const item of arr) {
+      const s = String(item);
+      lines.push(`${indent}  - ${typeof item === 'string' && needsQuoting(s) ? `"${s}"` : s}`);
+    }
+  }
+}
+
+/** Check if a string value needs quoting in YAML. */
+function needsQuoting(s: string): boolean {
+  return s.includes(':') || s.includes('#');
+}
+
+// ─── spliceFrontmatter ─────────────────────────────────────────────────────
+
+/**
+ * Replace or prepend frontmatter in content.
+ *
+ * Port of `spliceFrontmatter` from frontmatter.cjs lines 186-193.
+ *
+ * @param content - File content with potential existing frontmatter
+ * @param newObj - New frontmatter object to serialize
+ * @returns Content with updated frontmatter
+ */
+export function spliceFrontmatter(content: string, newObj: Record<string, unknown>): string {
+  const yamlStr = reconstructFrontmatter(newObj);
+  const match = content.match(/^---\r?\n[\s\S]+?\r?\n---/);
+  if (match) {
+    return `---\n${yamlStr}\n---` + content.slice(match[0].length);
+  }
+  return `---\n${yamlStr}\n---\n\n` + content;
+}
+
+// ─── parseSimpleValue ──────────────────────────────────────────────────────
+
+/**
+ * Parse a simple CLI value string into a typed value.
+ * Tries JSON.parse first (handles booleans, numbers, arrays, objects).
+ * Falls back to raw string.
+ */
+function parseSimpleValue(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+// ─── frontmatterSet ────────────────────────────────────────────────────────
+
+/**
+ * Query handler for frontmatter.set command.
+ *
+ * Reads a file, sets a single frontmatter field, writes back with normalization.
+ * Port of `cmdFrontmatterSet` from frontmatter.cjs lines 328-342.
+ *
+ * @param args - args[0]: file path, args[1]: field name, args[2]: value
+ * @param projectDir - Project root directory
+ * @returns QueryResult with { updated: true, field, value }
+ */
+export const frontmatterSet: QueryHandler = async (args, projectDir) => {
+  let filePath: string;
+  let field: string;
+  let value: string;
+
+  const fi = args.indexOf('--field');
+  const vi = args.indexOf('--value');
+  const hasNamedArgs = fi !== -1 || vi !== -1;
+  if (hasNamedArgs) {
+    if (fi === -1 || vi === -1 || !args[fi + 1] || args[vi + 1] === undefined) {
+      throw new SDDError('file, --field, and --value required together', ErrorClassification.Validation);
+    }
+    filePath = args[0];
+    field = args[fi + 1];
+    value = args[vi + 1];
+  } else {
+    filePath = args[0];
+    field = args[1];
+    value = args[2];
+  }
+
+  if (!filePath || !field || value === undefined) {
+    throw new SDDError('file, field, and value required', ErrorClassification.Validation);
+  }
+
+  // Path traversal guard: reject null bytes
+  if (filePath.includes('\0')) {
+    throw new SDDError('file path contains null bytes', ErrorClassification.Validation);
+  }
+
+  let fullPath: string;
+  try {
+    fullPath = await resolvePathUnderProject(projectDir, filePath);
+  } catch (err) {
+    if (err instanceof SDDError) {
+      return { data: { error: err.message, path: filePath } };
+    }
+    throw err;
+  }
+
+  let content: string;
+  try {
+    content = await readFile(fullPath, 'utf-8');
+  } catch {
+    return { data: { error: 'File not found', path: filePath } };
+  }
+
+  const fm = extractFrontmatter(content);
+  const parsedValue = parseSimpleValue(value);
+  fm[field] = parsedValue;
+  const newContent = spliceFrontmatter(content, fm);
+  await writeFile(fullPath, normalizeMd(newContent), 'utf-8');
+
+  return { data: { updated: true, field, value: parsedValue } };
+};
+
+// ─── frontmatterMerge ──────────────────────────────────────────────────────
+
+/**
+ * Query handler for frontmatter.merge command.
+ *
+ * Reads a file, merges JSON object into existing frontmatter, writes back.
+ * Port of `cmdFrontmatterMerge` from frontmatter.cjs lines 344-356.
+ *
+ * @param args - `file --data <json>` (sdd-tools) or `[file, jsonString]` (SDK)
+ * @param projectDir - Project root directory
+ * @returns QueryResult with { merged: true, fields: [...] }
+ */
+export const frontmatterMerge: QueryHandler = async (args, projectDir) => {
+  const filePath = args[0];
+  const dataIdx = args.indexOf('--data');
+  const jsonString = dataIdx !== -1 ? args[dataIdx + 1] : args[1];
+
+  if (!filePath || !jsonString) {
+    throw new SDDError('file and data required', ErrorClassification.Validation);
+  }
+
+  // Path traversal guard: reject null bytes (consistent with frontmatterSet)
+  if (filePath.includes('\0')) {
+    throw new SDDError('file path contains null bytes', ErrorClassification.Validation);
+  }
+
+  let fullPath: string;
+  try {
+    fullPath = await resolvePathUnderProject(projectDir, filePath);
+  } catch (err) {
+    if (err instanceof SDDError) {
+      return { data: { error: err.message, path: filePath } };
+    }
+    throw err;
+  }
+
+  let content: string;
+  try {
+    content = await readFile(fullPath, 'utf-8');
+  } catch {
+    return { data: { error: 'File not found', path: filePath } };
+  }
+
+  let mergeData: Record<string, unknown>;
+  try {
+    mergeData = JSON.parse(jsonString) as Record<string, unknown>;
+  } catch {
+    throw new SDDError('Invalid JSON for merge data', ErrorClassification.Validation);
+  }
+
+  const fm = extractFrontmatter(content);
+  Object.assign(fm, mergeData);
+  const newContent = spliceFrontmatter(content, fm);
+  await writeFile(fullPath, normalizeMd(newContent), 'utf-8');
+
+  return { data: { merged: true, fields: Object.keys(mergeData) } };
+};
+
+// ─── frontmatterValidate ───────────────────────────────────────────────────
+
+/**
+ * Query handler for frontmatter.validate command.
+ *
+ * Reads a file and checks its frontmatter against a known schema.
+ * Port of `cmdFrontmatterValidate` from frontmatter.cjs lines 358-369.
+ *
+ * @param args - args[0]: file path, args[1]: '--schema', args[2]: schema name
+ * @param projectDir - Project root directory
+ * @returns QueryResult with { valid, missing, present, schema }
+ */
+export const frontmatterValidate: QueryHandler = async (args, projectDir) => {
+  const filePath = args[0];
+
+  // Parse --schema flag from args
+  let schemaName: string | undefined;
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--schema' && args[i + 1]) {
+      schemaName = args[i + 1];
+      break;
+    }
+  }
+
+  if (!filePath || !schemaName) {
+    throw new SDDError('file and schema required', ErrorClassification.Validation);
+  }
+
+  // Path traversal guard: reject null bytes (consistent with frontmatterSet)
+  if (filePath.includes('\0')) {
+    throw new SDDError('file path contains null bytes', ErrorClassification.Validation);
+  }
+
+  const schema = FRONTMATTER_SCHEMAS[schemaName];
+  if (!schema) {
+    throw new SDDError(
+      `Unknown schema: ${schemaName}. Available: ${Object.keys(FRONTMATTER_SCHEMAS).join(', ')}`,
+      ErrorClassification.Validation
+    );
+  }
+
+  let fullPath: string;
+  try {
+    fullPath = await resolvePathUnderProject(projectDir, filePath);
+  } catch (err) {
+    if (err instanceof SDDError) {
+      return { data: { error: err.message, path: filePath } };
+    }
+    throw err;
+  }
+
+  let content: string;
+  try {
+    content = await readFile(fullPath, 'utf-8');
+  } catch {
+    return { data: { error: 'File not found', path: filePath } };
+  }
+
+  const fm = extractFrontmatter(content);
+  const missing = schema.required.filter(f => fm[f] === undefined);
+  const present = schema.required.filter(f => fm[f] !== undefined);
+
+  return { data: { valid: missing.length === 0, missing, present, schema: schemaName } };
+};