gsd-remix 1.0.0

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

@@ -0,0 +1,281 @@
+/**
+ * Unit tests for frontmatter parser and query handler.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  splitInlineArray,
+  extractFrontmatter,
+  extractFrontmatterLeading,
+  stripFrontmatter,
+  frontmatterGet,
+  parseMustHavesBlock,
+} from './frontmatter.js';
+
+// ─── splitInlineArray ───────────────────────────────────────────────────────
+
+describe('splitInlineArray', () => {
+  it('splits simple CSV', () => {
+    expect(splitInlineArray('a, b, c')).toEqual(['a', 'b', 'c']);
+  });
+
+  it('handles quoted strings with commas', () => {
+    expect(splitInlineArray('"a, b", c')).toEqual(['a, b', 'c']);
+  });
+
+  it('handles single-quoted strings', () => {
+    expect(splitInlineArray("'a, b', c")).toEqual(['a, b', 'c']);
+  });
+
+  it('trims whitespace', () => {
+    expect(splitInlineArray('  a  ,  b  ')).toEqual(['a', 'b']);
+  });
+
+  it('returns empty array for empty string', () => {
+    expect(splitInlineArray('')).toEqual([]);
+  });
+});
+
+// ─── extractFrontmatter ─────────────────────────────────────────────────────
+
+describe('extractFrontmatter', () => {
+  it('parses simple key-value pairs', () => {
+    const content = '---\nkey: value\n---\nbody';
+    const result = extractFrontmatter(content);
+    expect(result).toEqual({ key: 'value' });
+  });
+
+  it('parses nested objects', () => {
+    const content = '---\nparent:\n  child: value\n---\n';
+    const result = extractFrontmatter(content);
+    expect(result).toEqual({ parent: { child: 'value' } });
+  });
+
+  it('parses inline arrays', () => {
+    const content = '---\ntags: [a, b, c]\n---\n';
+    const result = extractFrontmatter(content);
+    expect(result).toEqual({ tags: ['a', 'b', 'c'] });
+  });
+
+  it('parses dash arrays', () => {
+    const content = '---\nitems:\n  - one\n  - two\n---\n';
+    const result = extractFrontmatter(content);
+    expect(result).toEqual({ items: ['one', 'two'] });
+  });
+
+  it('uses the LAST block when multiple stacked blocks exist', () => {
+    const content = '---\nold: data\n---\n---\nnew: data\n---\nbody';
+    const result = extractFrontmatter(content);
+    expect(result).toEqual({ new: 'data' });
+  });
+
+  it('handles empty-object-to-array conversion', () => {
+    const content = '---\nlist:\n  - item1\n  - item2\n---\n';
+    const result = extractFrontmatter(content);
+    expect(result).toEqual({ list: ['item1', 'item2'] });
+  });
+
+  it('returns empty object when no frontmatter', () => {
+    const result = extractFrontmatter('no frontmatter here');
+    expect(result).toEqual({});
+  });
+
+  it('strips surrounding quotes from values', () => {
+    const content = '---\nkey: "quoted"\n---\n';
+    const result = extractFrontmatter(content);
+    expect(result).toEqual({ key: 'quoted' });
+  });
+
+  it('handles CRLF line endings', () => {
+    const content = '---\r\nkey: value\r\n---\r\nbody';
+    const result = extractFrontmatter(content);
+    expect(result).toEqual({ key: 'value' });
+  });
+});
+
+// ─── extractFrontmatterLeading ─────────────────────────────────────────────
+
+describe('extractFrontmatterLeading', () => {
+  it('parses only the first leading block (gsd-tools.cjs / frontmatter.cjs parity)', () => {
+    const content = '---\nfirst: 1\n---\n---\nsecond: 2\n---\nbody';
+    expect(extractFrontmatterLeading(content)).toEqual({ first: '1' });
+  });
+
+  it('matches extractFrontmatter when a single block starts the file', () => {
+    const content = '---\na: b\n---\n';
+    expect(extractFrontmatterLeading(content)).toEqual(extractFrontmatter(content));
+  });
+});
+
+// ─── stripFrontmatter ───────────────────────────────────────────────────────
+
+describe('stripFrontmatter', () => {
+  it('strips single frontmatter block', () => {
+    const result = stripFrontmatter('---\nk: v\n---\nbody');
+    expect(result).toBe('body');
+  });
+
+  it('strips multiple stacked blocks', () => {
+    const result = stripFrontmatter('---\na: 1\n---\n---\nb: 2\n---\nbody');
+    expect(result).toBe('body');
+  });
+
+  it('returns content unchanged when no frontmatter', () => {
+    expect(stripFrontmatter('just body')).toBe('just body');
+  });
+
+  it('handles leading whitespace after strip', () => {
+    const result = stripFrontmatter('---\nk: v\n---\n\nbody');
+    // After stripping, leading whitespace/newlines may remain
+    expect(result.trim()).toBe('body');
+  });
+});
+
+// ─── frontmatterGet ─────────────────────────────────────────────────────────
+
+describe('frontmatterGet', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-fm-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns parsed frontmatter from a file', async () => {
+    await writeFile(join(tmpDir, 'test.md'), '---\nkey: value\n---\nbody');
+    const result = await frontmatterGet(['test.md'], tmpDir);
+    expect(result.data).toEqual({ key: 'value' });
+  });
+
+  it('returns single field when field arg provided', async () => {
+    await writeFile(join(tmpDir, 'test.md'), '---\nkey: value\n---\nbody');
+    const result = await frontmatterGet(['test.md', 'key'], tmpDir);
+    expect(result.data).toEqual({ key: 'value' });
+  });
+
+  it('returns error for missing file', async () => {
+    const result = await frontmatterGet(['missing.md'], tmpDir);
+    expect(result.data).toEqual({ error: 'File not found', path: 'missing.md' });
+  });
+
+  it('throws GSDError for null bytes in path', async () => {
+    const { GSDError } = await import('../errors.js');
+    await expect(frontmatterGet(['bad\0path.md'], tmpDir)).rejects.toThrow(GSDError);
+  });
+});
+
+// ─── parseMustHavesBlock ───────────────────────────────────────────────────
+
+describe('parseMustHavesBlock', () => {
+  it('parses artifacts block with path, provides, min_lines, contains, exports', () => {
+    const content = `---
+phase: 12
+must_haves:
+  artifacts:
+    - path: sdk/src/foo.ts
+      provides: Foo handler
+      min_lines: 50
+      contains: export function foo
+      exports:
+        - foo
+        - bar
+---
+body`;
+    const result = parseMustHavesBlock(content, 'artifacts');
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0]).toEqual({
+      path: 'sdk/src/foo.ts',
+      provides: 'Foo handler',
+      min_lines: 50,
+      contains: 'export function foo',
+      exports: ['foo', 'bar'],
+    });
+  });
+
+  it('parses key_links block with from, to, via, pattern', () => {
+    const content = `---
+phase: 12
+must_haves:
+  key_links:
+    - from: src/a.ts
+      to: src/b.ts
+      via: import something
+      pattern: import.*something.*from.*b
+---
+body`;
+    const result = parseMustHavesBlock(content, 'key_links');
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0]).toEqual({
+      from: 'src/a.ts',
+      to: 'src/b.ts',
+      via: 'import something',
+      pattern: 'import.*something.*from.*b',
+    });
+  });
+
+  it('parses simple string items (truths)', () => {
+    const content = `---
+phase: 12
+must_haves:
+  truths:
+    - Running verify returns valid
+    - Running check returns true
+---
+body`;
+    const result = parseMustHavesBlock(content, 'truths');
+    expect(result.items).toHaveLength(2);
+    expect(result.items[0]).toBe('Running verify returns valid');
+    expect(result.items[1]).toBe('Running check returns true');
+  });
+
+  it('preserves nested array values (exports: [a, b])', () => {
+    const content = `---
+must_haves:
+  artifacts:
+    - path: foo.ts
+      exports:
+        - alpha
+        - beta
+---
+`;
+    const result = parseMustHavesBlock(content, 'artifacts');
+    expect(result.items[0]).toMatchObject({ exports: ['alpha', 'beta'] });
+  });
+
+  it('returns empty items for missing block', () => {
+    const content = `---
+must_haves:
+  truths:
+    - something
+---
+`;
+    const result = parseMustHavesBlock(content, 'artifacts');
+    expect(result.items).toEqual([]);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('returns empty items for no frontmatter', () => {
+    const result = parseMustHavesBlock('no frontmatter here', 'artifacts');
+    expect(result.items).toEqual([]);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('emits diagnostic warning when content lines exist but 0 items parsed', () => {
+    const content = `---
+must_haves:
+  artifacts:
+  some badly formatted content
+---
+`;
+    const result = parseMustHavesBlock(content, 'artifacts');
+    expect(result.items).toEqual([]);
+    expect(result.warnings.length).toBeGreaterThan(0);
+    expect(result.warnings[0]).toContain('artifacts');
+  });
+});

package/sdk/src/query/frontmatter.ts

@@ -0,0 +1,397 @@
+/**
+ * Frontmatter parser and query handler.
+ *
+ * Ported from get-shit-done/bin/lib/frontmatter.cjs and state.cjs.
+ * Provides YAML frontmatter extraction from .planning/ artifacts.
+ *
+ * @example
+ * ```typescript
+ * import { extractFrontmatter, frontmatterGet } from './frontmatter.js';
+ *
+ * const fm = extractFrontmatter('---\nphase: 10\nplan: 01\n---\nbody');
+ * // { phase: '10', plan: '01' }
+ *
+ * const result = await frontmatterGet(['STATE.md'], '/project');
+ * // { data: { gsd_state_version: '1.0', milestone: 'v3.0', ... } }
+ * ```
+ */
+
+import { readFile } from 'node:fs/promises';
+import { GSDError, ErrorClassification } from '../errors.js';
+import type { QueryHandler } from './utils.js';
+import { escapeRegex, resolvePathUnderProject } from './helpers.js';
+
+// ─── splitInlineArray ───────────────────────────────────────────────────────
+
+/**
+ * Quote-aware CSV splitting for inline YAML arrays.
+ *
+ * Handles both single and double quotes, preserving commas inside quotes.
+ *
+ * @param body - The content inside brackets, e.g. 'a, "b, c", d'
+ * @returns Array of trimmed values
+ */
+export function splitInlineArray(body: string): string[] {
+  const items: string[] = [];
+  let current = '';
+  let inQuote: string | null = null;
+
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === ',') {
+      const trimmed = current.trim();
+      if (trimmed) items.push(trimmed);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  const trimmed = current.trim();
+  if (trimmed) items.push(trimmed);
+  return items;
+}
+
+// ─── parseFrontmatterYamlLines ───────────────────────────────────────────────
+
+/**
+ * Parse YAML frontmatter body (between `---` fences) using the GSD stack parser.
+ * Shared by {@link extractFrontmatterLeading} and {@link extractFrontmatter}.
+ */
+function parseFrontmatterYamlLines(yaml: string): Record<string, unknown> {
+  const frontmatter: Record<string, unknown> = {};
+  const lines = yaml.split(/\r?\n/);
+
+  // Stack to track nested objects: [{obj, key, indent}]
+  const stack: Array<{ obj: Record<string, unknown> | unknown[]; key: string | null; indent: number }> = [
+    { obj: frontmatter, key: null, indent: -1 },
+  ];
+
+  for (const line of lines) {
+    // Skip empty lines
+    if (line.trim() === '') continue;
+
+    // Calculate indentation (number of leading spaces)
+    const indentMatch = line.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[1].length : 0;
+
+    // Pop stack back to appropriate level
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const current = stack[stack.length - 1];
+
+    // Check for key: value pattern
+    const keyMatch = line.match(/^(\s*)([a-zA-Z0-9_-]+):\s*(.*)/);
+    if (keyMatch) {
+      const key = keyMatch[2];
+      const value = keyMatch[3].trim();
+
+      if (value === '' || value === '[') {
+        // Key with no value or opening bracket -- could be nested object or array
+        (current.obj as Record<string, unknown>)[key] = value === '[' ? [] : {};
+        current.key = null;
+        // Push new context for potential nested content
+        stack.push({ obj: (current.obj as Record<string, unknown>)[key] as Record<string, unknown>, key: null, indent });
+      } else if (value.startsWith('[') && value.endsWith(']')) {
+        // Inline array: key: [a, b, c]
+        (current.obj as Record<string, unknown>)[key] = splitInlineArray(value.slice(1, -1));
+        current.key = null;
+      } else {
+        // Simple key: value -- strip surrounding quotes
+        (current.obj as Record<string, unknown>)[key] = value.replace(/^["']|["']$/g, '');
+        current.key = null;
+      }
+    } else if (line.trim().startsWith('- ')) {
+      // Array item
+      const afterDash = line.trim().slice(2).trim();
+      let itemValue: unknown = afterDash.replace(/^["']|["']$/g, '');
+      let isObjItem = false;
+
+      // Extract key: value within the array item if present
+      const kvMatch = afterDash.match(/^([a-zA-Z0-9_-]+):\s*(.*)/);
+      if (kvMatch) {
+        isObjItem = true;
+        const k = kvMatch[1];
+        const v = kvMatch[2].trim().replace(/^["']|["']$/g, '');
+        itemValue = { [k]: v };
+      }
+
+      // If current context is an empty object, convert to array
+      if (typeof current.obj === 'object' && !Array.isArray(current.obj) && Object.keys(current.obj).length === 0) {
+        // Find the key in parent that points to this object and convert it
+        const parent = stack.length > 1 ? stack[stack.length - 2] : null;
+        if (parent && !Array.isArray(parent.obj)) {
+          for (const k of Object.keys(parent.obj as Record<string, unknown>)) {
+            if ((parent.obj as Record<string, unknown>)[k] === current.obj) {
+              (parent.obj as Record<string, unknown>)[k] = [itemValue];
+              current.obj = (parent.obj as Record<string, unknown>)[k] as unknown[];
+              break;
+            }
+          }
+        }
+      } else if (Array.isArray(current.obj)) {
+        current.obj.push(itemValue);
+      }
+
+      // Push object context onto stack so subsequent indented properties map to this object
+      if (isObjItem && Array.isArray(current.obj)) {
+        stack.push({ obj: itemValue as Record<string, unknown>, key: null, indent });
+      }
+    }
+  }
+
+  return frontmatter;
+}
+
+// ─── extractFrontmatterLeading ──────────────────────────────────────────────
+
+/**
+ * First leading frontmatter block only — parity with `get-shit-done/bin/lib/frontmatter.cjs`
+ * `extractFrontmatter` (used by `summary-extract` and `history-digest` in gsd-tools.cjs).
+ */
+export function extractFrontmatterLeading(content: string): Record<string, unknown> {
+  const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+  if (!match) return {};
+  return parseFrontmatterYamlLines(match[1]);
+}
+
+// ─── extractFrontmatter ─────────────────────────────────────────────────────
+
+/**
+ * Parse YAML frontmatter from file content.
+ *
+ * Full stack-based parser supporting:
+ * - Simple key: value pairs
+ * - Nested objects via indentation
+ * - Inline arrays: key: [a, b, c]
+ * - Dash arrays with auto-conversion from empty objects
+ * - Multiple stacked blocks (uses the LAST match)
+ * - CRLF line endings
+ * - Quoted value stripping
+ *
+ * @param content - File content potentially containing frontmatter
+ * @returns Parsed frontmatter as a record, or empty object if none found
+ */
+export function extractFrontmatter(content: string): Record<string, unknown> {
+  // Find ALL frontmatter blocks. Use the LAST one (corruption recovery).
+  const allBlocks = [...content.matchAll(/(?:^|\n)\s*---\r?\n([\s\S]+?)\r?\n---/g)];
+  const match = allBlocks.length > 0 ? allBlocks[allBlocks.length - 1] : null;
+  if (!match) return {};
+
+  return parseFrontmatterYamlLines(match[1]);
+}
+
+// ─── stripFrontmatter ───────────────────────────────────────────────────────
+
+/**
+ * Strip all frontmatter blocks from the start of content.
+ *
+ * Handles CRLF line endings and multiple stacked blocks (corruption recovery).
+ * Greedy: keeps stripping ---...--- blocks separated by optional whitespace.
+ *
+ * @param content - File content with potential frontmatter
+ * @returns Content with frontmatter removed
+ */
+export function stripFrontmatter(content: string): string {
+  let result = content;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const stripped = result.replace(/^\s*---\r?\n[\s\S]*?\r?\n---\s*/, '');
+    if (stripped === result) break;
+    result = stripped;
+  }
+  return result;
+}
+
+// ─── parseMustHavesBlock ────────────────────────────────────────────────────
+
+/**
+ * Result of parsing a must_haves block from frontmatter.
+ */
+export interface MustHavesBlockResult {
+  items: unknown[];
+  warnings: string[];
+}
+
+/**
+ * Parse a named block from must_haves in raw frontmatter YAML.
+ *
+ * Port of `parseMustHavesBlock` from `get-shit-done/bin/lib/frontmatter.cjs` lines 195-301.
+ * Handles 3-level nesting: `must_haves > blockName > [{key: value, ...}]`.
+ * Supports simple string items, structured objects with key-value pairs,
+ * and nested arrays within items.
+ *
+ * @param content - File content with frontmatter
+ * @param blockName - Block name under must_haves (e.g. 'artifacts', 'key_links', 'truths')
+ * @returns Structured result with items array and warnings
+ */
+export function parseMustHavesBlock(content: string, blockName: string): MustHavesBlockResult {
+  const warnings: string[] = [];
+
+  // Extract raw YAML from first ---\n...\n--- block
+  const fmMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+  if (!fmMatch) return { items: [], warnings };
+
+  const yaml = fmMatch[1];
+
+  // Find must_haves: at its indentation level
+  const mustHavesMatch = yaml.match(/^(\s*)must_haves:\s*$/m);
+  if (!mustHavesMatch) return { items: [], warnings };
+  const mustHavesIndent = mustHavesMatch[1].length;
+
+  // Find the block (e.g., "artifacts:", "key_links:") under must_haves
+  const blockPattern = new RegExp(`^(\\s+)${escapeRegex(blockName)}:\\s*$`, 'm');
+  const blockMatch = yaml.match(blockPattern);
+  if (!blockMatch) return { items: [], warnings };
+
+  const blockIndent = blockMatch[1].length;
+  // The block must be nested under must_haves (more indented)
+  if (blockIndent <= mustHavesIndent) return { items: [], warnings };
+
+  // Find where the block starts in the yaml string
+  const blockStart = yaml.indexOf(blockMatch[0]);
+  if (blockStart === -1) return { items: [], warnings };
+
+  const afterBlock = yaml.slice(blockStart);
+  const blockLines = afterBlock.split(/\r?\n/).slice(1); // skip the header line
+
+  // List items are indented one level deeper than blockIndent
+  // Continuation KVs are indented one level deeper than list items
+  const items: unknown[] = [];
+  let current: Record<string, unknown> | string | null = null;
+  let listItemIndent = -1; // detected from first "- " line
+
+  for (const line of blockLines) {
+    // Skip empty lines
+    if (line.trim() === '') continue;
+    const indentMatch = line.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[1].length : 0;
+    // Stop at same or lower indent level than the block header
+    if (indent <= blockIndent && line.trim() !== '') break;
+
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith('- ')) {
+      // Detect list item indent from the first occurrence
+      if (listItemIndent === -1) listItemIndent = indent;
+
+      // Only treat as a top-level list item if at the expected indent
+      if (indent === listItemIndent) {
+        if (current !== null) items.push(current);
+        const afterDash = trimmed.slice(2);
+        // Check if it's a simple string item (no colon means not a key-value)
+        if (!afterDash.includes(':')) {
+          current = afterDash.replace(/^["']|["']$/g, '');
+        } else {
+          // Key-value on same line as dash: "- path: value"
+          const kvMatch = afterDash.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
+          if (kvMatch) {
+            current = {} as Record<string, unknown>;
+            current[kvMatch[1]] = kvMatch[2];
+          } else {
+            current = {} as Record<string, unknown>;
+          }
+        }
+        continue;
+      }
+    }
+
+    if (current !== null && typeof current === 'object' && indent > listItemIndent) {
+      // Continuation key-value or nested array item
+      if (trimmed.startsWith('- ')) {
+        // Array item under a key
+        const arrVal = trimmed.slice(2).replace(/^["']|["']$/g, '');
+        const keys = Object.keys(current);
+        const lastKey = keys[keys.length - 1];
+        if (lastKey && !Array.isArray(current[lastKey])) {
+          current[lastKey] = current[lastKey] ? [current[lastKey]] : [];
+        }
+        if (lastKey) (current[lastKey] as unknown[]).push(arrVal);
+      } else {
+        const kvMatch = trimmed.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
+        if (kvMatch) {
+          const val = kvMatch[2];
+          // Try to parse as number
+          current[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
+        }
+      }
+    }
+  }
+  if (current !== null) items.push(current);
+
+  // Diagnostic warning when block has content lines but parsed 0 items
+  if (items.length === 0 && blockLines.length > 0) {
+    const nonEmptyLines = blockLines.filter(l => l.trim() !== '').length;
+    if (nonEmptyLines > 0) {
+      warnings.push(
+        `must_haves.${blockName} block has ${nonEmptyLines} content lines but parsed 0 items. ` +
+        `Possible YAML formatting issue.`
+      );
+    }
+  }
+
+  return { items, warnings };
+}
+
+// ─── frontmatterGet ─────────────────────────────────────────────────────────
+
+/**
+ * Query handler for frontmatter.get command.
+ *
+ * Reads a file, extracts frontmatter, and optionally returns a single field.
+ * Rejects null bytes in path (security: path traversal guard).
+ *
+ * @param args - args[0]: file path, args[1]: optional field name
+ * @param projectDir - Project root directory
+ * @returns QueryResult with parsed frontmatter or single field value
+ */
+export const frontmatterGet: QueryHandler = async (args, projectDir) => {
+  const filePath = args[0];
+  if (!filePath) {
+    throw new GSDError('file path required', ErrorClassification.Validation);
+  }
+
+  // Path traversal guard: reject null bytes
+  if (filePath.includes('\0')) {
+    throw new GSDError('file path contains null bytes', ErrorClassification.Validation);
+  }
+
+  let fullPath: string;
+  try {
+    fullPath = await resolvePathUnderProject(projectDir, filePath);
+  } catch (err) {
+    if (err instanceof GSDError) {
+      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 field = args[1];
+
+  if (field) {
+    const value = fm[field];
+    if (value === undefined) {
+      return { data: { error: 'Field not found', field } };
+    }
+    return { data: { [field]: value } };
+  }
+
+  return { data: fm };
+};