@applica-software-guru/sdd-core 0.1.0

package/src/scaffold/templates.ts

@@ -0,0 +1,166 @@
+const now = () => new Date().toISOString();
+
+function mdTemplate(title: string, content: string): string {
+  return `---
+title: "${title}"
+status: new
+author: ""
+last-modified: "${now()}"
+version: "1.0"
+---
+
+${content}
+`;
+}
+
+export interface ProjectInfo {
+  description: string;
+}
+
+export const AGENT_MD_TEMPLATE = `# SDD Project
+
+This project uses **Story Driven Development (SDD)**.
+Documentation drives implementation: read the docs first, then write code.
+
+## Workflow
+
+1. Run \`sdd cr pending\` — check if there are change requests to process first
+2. If there are pending CRs, apply them to the docs, then run \`sdd mark-cr-applied\`
+3. Run \`sdd sync\` to see what needs to be implemented
+4. Read the documentation files listed in the sync output
+5. Implement what each file describes, writing code inside \`code/\`
+6. After implementing, mark files as synced:
+
+\`\`\`
+sdd mark-synced product/features/auth.md
+\`\`\`
+
+Or mark all pending files at once:
+
+\`\`\`
+sdd mark-synced
+\`\`\`
+
+7. **Commit immediately after mark-synced** — this is mandatory:
+
+\`\`\`
+git add -A && git commit -m "sdd sync: <brief description of what was implemented>"
+\`\`\`
+
+Do NOT skip this step. Every mark-synced must be followed by a git commit.
+
+### Removing a feature
+
+If a documentation file has \`status: deleted\`, it means that feature should be removed.
+Delete the related code in \`code/\`, then run \`sdd mark-synced <file>\` (the doc file will be removed automatically), then commit.
+
+## Available commands
+
+- \`sdd status\` — See all documentation files and their state (new/changed/deleted/synced)
+- \`sdd diff\` — See what changed since last sync
+- \`sdd sync\` — Get the sync prompt for pending files (new/changed/deleted)
+- \`sdd validate\` — Check for broken references and issues
+- \`sdd mark-synced [files...]\` — Mark specific files (or all) as synced
+- \`sdd cr list\` — List all change requests with their status
+- \`sdd cr pending\` — Show draft change requests to process
+- \`sdd mark-cr-applied [files...]\` — Mark change requests as applied
+
+## Rules
+
+1. **Always commit after mark-synced** — run \`git add -A && git commit -m "sdd sync: ..."\` immediately after \`sdd mark-synced\`. Never leave synced files uncommitted.
+2. Before running \`sdd sync\`, check for pending change requests with \`sdd cr pending\`
+3. If there are pending CRs, apply them to the docs first, then mark them with \`sdd mark-cr-applied\`
+4. Only implement what the sync prompt asks for
+5. All generated code goes inside \`code/\`
+6. Respect all constraints in \`## Agent Notes\` sections (if present)
+7. Do not edit files inside \`.sdd/\` manually
+
+## File format
+
+Every \`.md\` file in \`product/\` and \`system/\` must start with this YAML frontmatter:
+
+\`\`\`yaml
+---
+title: "File title"
+status: new
+author: ""
+last-modified: "2025-01-01T00:00:00.000Z"
+version: "1.0"
+---
+\`\`\`
+
+- **status**: one of:
+  - \`new\` — new file, needs to be implemented
+  - \`changed\` — modified since last sync, code needs updating
+  - \`deleted\` — feature to be removed, agent should delete related code
+  - \`synced\` — already implemented, up to date
+- **version**: patch-bump on each edit (1.0 → 1.1 → 1.2)
+- **last-modified**: ISO 8601 datetime, updated on each edit
+
+## Change Requests
+
+Change Requests (CRs) are markdown files in \`change-requests/\` that describe modifications to the documentation.
+
+### CR format
+
+\`\`\`yaml
+---
+title: "Add authentication feature"
+status: draft
+author: "user"
+created-at: "2025-01-01T00:00:00.000Z"
+---
+\`\`\`
+
+- **status**: \`draft\` (pending) or \`applied\` (already processed)
+
+### CR workflow
+
+1. Check for pending CRs: \`sdd cr pending\`
+2. Read each pending CR and apply the described changes to the documentation files (marking them as \`new\`, \`changed\`, or \`deleted\`)
+3. After applying a CR to the docs, mark it: \`sdd mark-cr-applied change-requests/CR-001.md\`
+4. Then run \`sdd sync\` to implement the code changes
+
+### CR commands
+
+- \`sdd cr list\` — See all change requests and their status
+- \`sdd cr pending\` — Show only draft CRs to process
+- \`sdd mark-cr-applied [files...]\` — Mark CRs as applied after updating the docs
+
+## UX and screenshots
+
+When a feature has UX mockups or screenshots, place them next to the feature doc:
+
+- **Simple feature** (no screenshots): \`product/features/auth.md\`
+- **Feature with screenshots**: use a folder with \`index.md\`:
+
+\`\`\`
+product/features/auth/
+  index.md          ← feature doc
+  login.png         ← screenshot
+  register.png      ← screenshot
+\`\`\`
+
+Reference images in the markdown with relative paths:
+
+\`\`\`markdown
+## UX
+
+![Login screen](login.png)
+![Register screen](register.png)
+\`\`\`
+
+Both formats work — use a folder only when you have screenshots or multiple files for a feature.
+
+## Project structure
+
+- \`product/\` — What to build (vision, users, features)
+- \`system/\` — How to build it (entities, architecture, tech stack, interfaces)
+- \`code/\` — All generated source code goes here
+- \`change-requests/\` — Change requests to the documentation
+- \`.sdd/\` — Project config and sync state (do not edit)
+`;
+
+export const EMPTY_LOCK_TEMPLATE = () => `synced-at: "${new Date().toISOString()}"
+files: {}
+`;

package/src/sdd.ts

@@ -0,0 +1,123 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { StoryStatus, ValidationResult, SDDConfig, ChangeRequest } from './types.js';
+import { ProjectNotInitializedError } from './errors.js';
+import { parseAllStoryFiles } from './parser/story-parser.js';
+import { generatePrompt } from './prompt/prompt-generator.js';
+import { validate } from './validate/validator.js';
+import { initProject } from './scaffold/init.js';
+import { isSDDProject, readConfig, writeConfig } from './config/config-manager.js';
+import { parseAllCRFiles } from './parser/cr-parser.js';
+import type { ProjectInfo } from './scaffold/templates.js';
+
+export class SDD {
+  private root: string;
+
+  constructor(options: { root: string }) {
+    this.root = options.root;
+  }
+
+  async init(info?: ProjectInfo): Promise<string[]> {
+    return initProject(this.root, info);
+  }
+
+  async config(): Promise<SDDConfig> {
+    this.ensureInitialized();
+    return readConfig(this.root);
+  }
+
+  async status(): Promise<StoryStatus> {
+    this.ensureInitialized();
+    const files = await parseAllStoryFiles(this.root);
+
+    return {
+      files: files.map((f) => ({
+        relativePath: f.relativePath,
+        status: f.frontmatter.status,
+        version: f.frontmatter.version,
+        lastModified: f.frontmatter['last-modified'],
+      })),
+    };
+  }
+
+  async pending(): Promise<import('./types.js').StoryFile[]> {
+    this.ensureInitialized();
+    const files = await parseAllStoryFiles(this.root);
+    return files.filter((f) => f.frontmatter.status !== 'synced');
+  }
+
+  async sync(): Promise<string> {
+    const pending = await this.pending();
+    return generatePrompt(pending, this.root);
+  }
+
+  async validate(): Promise<ValidationResult> {
+    this.ensureInitialized();
+    const files = await parseAllStoryFiles(this.root);
+    return validate(files);
+  }
+
+  async markSynced(paths?: string[]): Promise<string[]> {
+    this.ensureInitialized();
+    const files = await parseAllStoryFiles(this.root);
+    const marked: string[] = [];
+
+    for (const file of files) {
+      const { status } = file.frontmatter;
+      if (status === 'synced') continue;
+      if (paths && paths.length > 0 && !paths.includes(file.relativePath)) continue;
+
+      const absPath = resolve(this.root, file.relativePath);
+
+      if (status === 'deleted') {
+        // File marked for deletion — remove it
+        const { unlink } = await import('node:fs/promises');
+        await unlink(absPath);
+        marked.push(`${file.relativePath} (removed)`);
+      } else {
+        // new or changed → synced
+        const content = await readFile(absPath, 'utf-8');
+        const updated = content.replace(/^status:\s*(new|changed)/m, 'status: synced');
+        await writeFile(absPath, updated, 'utf-8');
+        marked.push(file.relativePath);
+      }
+    }
+
+    return marked;
+  }
+
+  async changeRequests(): Promise<ChangeRequest[]> {
+    this.ensureInitialized();
+    return parseAllCRFiles(this.root);
+  }
+
+  async pendingChangeRequests(): Promise<ChangeRequest[]> {
+    const all = await this.changeRequests();
+    return all.filter((cr) => cr.frontmatter.status === 'draft');
+  }
+
+  async markCRApplied(paths?: string[]): Promise<string[]> {
+    this.ensureInitialized();
+    const all = await this.changeRequests();
+    const marked: string[] = [];
+
+    for (const cr of all) {
+      if (cr.frontmatter.status === 'applied') continue;
+      if (paths && paths.length > 0 && !paths.includes(cr.relativePath)) continue;
+
+      const absPath = resolve(this.root, cr.relativePath);
+      const content = await readFile(absPath, 'utf-8');
+      const updated = content.replace(/^status:\s*draft/m, 'status: applied');
+      await writeFile(absPath, updated, 'utf-8');
+      marked.push(cr.relativePath);
+    }
+
+    return marked;
+  }
+
+  private ensureInitialized(): void {
+    if (!isSDDProject(this.root)) {
+      throw new ProjectNotInitializedError(this.root);
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,76 @@
+export type StoryFileStatus = 'new' | 'changed' | 'deleted' | 'synced';
+
+export interface StoryFrontmatter {
+  title: string;
+  status: StoryFileStatus;
+  author: string;
+  'last-modified': string;
+  version: string;
+}
+
+export interface StoryFile {
+  relativePath: string;
+  frontmatter: StoryFrontmatter;
+  body: string;
+  pendingItems: PendingItem[];
+  agentNotes: string | null;
+  crossRefs: string[];
+  hash: string;
+}
+
+export interface PendingItem {
+  text: string;
+  checked: boolean;
+}
+
+export interface Delta {
+  hasChanges: boolean;
+  files: DeltaFile[];
+  diff: string;
+}
+
+export interface DeltaFile {
+  relativePath: string;
+  status: 'modified' | 'new' | 'deleted';
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  issues: ValidationIssue[];
+}
+
+export interface ValidationIssue {
+  severity: 'error' | 'warning';
+  filePath: string;
+  message: string;
+  rule: string;
+}
+
+export interface StoryStatus {
+  files: Array<{
+    relativePath: string;
+    status: 'new' | 'changed' | 'deleted' | 'synced';
+    version: string;
+    lastModified: string;
+  }>;
+}
+
+export interface SDDConfig {
+  description: string;
+  'last-sync-commit'?: string;
+}
+
+export type ChangeRequestStatus = 'draft' | 'applied';
+
+export interface ChangeRequestFrontmatter {
+  title: string;
+  status: ChangeRequestStatus;
+  author: string;
+  'created-at': string;
+}
+
+export interface ChangeRequest {
+  relativePath: string;
+  frontmatter: ChangeRequestFrontmatter;
+  body: string;
+}

package/src/validate/validator.ts

@@ -0,0 +1,46 @@
+import type { StoryFile, ValidationResult, ValidationIssue } from '../types.js';
+
+export function validate(files: StoryFile[]): ValidationResult {
+  const issues: ValidationIssue[] = [];
+
+  // Collect known entity names from system/entities.md
+  const entityNames = new Set<string>();
+  const entitiesFile = files.find((f) => f.relativePath.endsWith('entities.md'));
+  if (entitiesFile) {
+    // Extract ### headings as entity names
+    const headingRe = /^### (.+)$/gm;
+    let match: RegExpExecArray | null;
+    while ((match = headingRe.exec(entitiesFile.body)) !== null) {
+      entityNames.add(match[1].trim());
+    }
+  }
+
+  for (const file of files) {
+    // Check broken cross-references
+    for (const ref of file.crossRefs) {
+      if (entityNames.size > 0 && !entityNames.has(ref)) {
+        issues.push({
+          severity: 'warning',
+          filePath: file.relativePath,
+          message: `Broken reference [[${ref}]] — not found in system/entities.md`,
+          rule: 'broken-ref',
+        });
+      }
+    }
+
+    // Check frontmatter has required fields
+    if (!file.frontmatter.title) {
+      issues.push({
+        severity: 'warning',
+        filePath: file.relativePath,
+        message: 'Missing "title" in frontmatter',
+        rule: 'missing-frontmatter',
+      });
+    }
+  }
+
+  return {
+    valid: issues.filter((i) => i.severity === 'error').length === 0,
+    issues,
+  };
+}

package/tests/cr.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, writeFile, readFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SDD } from '../src/sdd.js';
+import { parseCRFile, discoverCRFiles } from '../src/parser/cr-parser.js';
+
+const CR_DRAFT = `---
+title: "Add authentication"
+status: draft
+author: "user"
+created-at: "2025-01-01T00:00:00.000Z"
+---
+
+## Description
+
+Add JWT-based authentication to the API.
+
+## Changes
+
+- Create \`product/features/auth.md\` with login/logout flows
+- Update \`system/entities.md\` to add User entity
+`;
+
+const CR_APPLIED = `---
+title: "Fix navigation"
+status: applied
+author: "user"
+created-at: "2025-01-02T00:00:00.000Z"
+---
+
+## Description
+
+Fix the navigation bar layout.
+`;
+
+describe('CR parser', () => {
+  it('parses CR frontmatter correctly', () => {
+    const result = parseCRFile('change-requests/CR-001.md', CR_DRAFT);
+    expect(result.frontmatter.title).toBe('Add authentication');
+    expect(result.frontmatter.status).toBe('draft');
+    expect(result.frontmatter.author).toBe('user');
+    expect(result.frontmatter['created-at']).toBe('2025-01-01T00:00:00.000Z');
+    expect(result.body).toContain('## Description');
+    expect(result.body).toContain('JWT-based authentication');
+  });
+
+  it('provides defaults for missing fields', () => {
+    const content = `---
+title: "Minimal CR"
+---
+
+Some body.
+`;
+    const result = parseCRFile('test.md', content);
+    expect(result.frontmatter.status).toBe('draft');
+    expect(result.frontmatter.author).toBe('');
+    expect(result.frontmatter['created-at']).toBe('');
+  });
+});
+
+describe('CR file discovery', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'sdd-cr-discovery-'));
+    await mkdir(join(tempDir, 'change-requests'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true });
+  });
+
+  it('discovers .md files in change-requests/', async () => {
+    await writeFile(join(tempDir, 'change-requests/CR-001.md'), CR_DRAFT, 'utf-8');
+    await writeFile(join(tempDir, 'change-requests/CR-002.md'), CR_APPLIED, 'utf-8');
+
+    const files = await discoverCRFiles(tempDir);
+    expect(files).toHaveLength(2);
+  });
+
+  it('returns empty array when no CR files exist', async () => {
+    const files = await discoverCRFiles(tempDir);
+    expect(files).toHaveLength(0);
+  });
+});
+
+describe('SDD CR methods', () => {
+  let tempDir: string;
+  let sdd: SDD;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'sdd-cr-'));
+    sdd = new SDD({ root: tempDir });
+    await sdd.init({ description: 'test' });
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true });
+  });
+
+  it('changeRequests() returns all CRs', async () => {
+    await writeFile(join(tempDir, 'change-requests/CR-001.md'), CR_DRAFT, 'utf-8');
+    await writeFile(join(tempDir, 'change-requests/CR-002.md'), CR_APPLIED, 'utf-8');
+
+    const crs = await sdd.changeRequests();
+    expect(crs).toHaveLength(2);
+    expect(crs[0].frontmatter.title).toBe('Add authentication');
+    expect(crs[1].frontmatter.title).toBe('Fix navigation');
+  });
+
+  it('pendingChangeRequests() returns only draft CRs', async () => {
+    await writeFile(join(tempDir, 'change-requests/CR-001.md'), CR_DRAFT, 'utf-8');
+    await writeFile(join(tempDir, 'change-requests/CR-002.md'), CR_APPLIED, 'utf-8');
+
+    const pending = await sdd.pendingChangeRequests();
+    expect(pending).toHaveLength(1);
+    expect(pending[0].frontmatter.status).toBe('draft');
+    expect(pending[0].frontmatter.title).toBe('Add authentication');
+  });
+
+  it('markCRApplied() changes draft to applied', async () => {
+    await writeFile(join(tempDir, 'change-requests/CR-001.md'), CR_DRAFT, 'utf-8');
+
+    const marked = await sdd.markCRApplied(['change-requests/CR-001.md']);
+    expect(marked).toEqual(['change-requests/CR-001.md']);
+
+    const content = await readFile(join(tempDir, 'change-requests/CR-001.md'), 'utf-8');
+    expect(content).toContain('status: applied');
+  });
+
+  it('markCRApplied() without args marks all draft CRs', async () => {
+    await writeFile(join(tempDir, 'change-requests/CR-001.md'), CR_DRAFT, 'utf-8');
+    const draft2 = CR_DRAFT.replace('Add authentication', 'Second CR');
+    await writeFile(join(tempDir, 'change-requests/CR-002.md'), draft2, 'utf-8');
+
+    const marked = await sdd.markCRApplied();
+    expect(marked).toHaveLength(2);
+  });
+
+  it('markCRApplied() skips already applied CRs', async () => {
+    await writeFile(join(tempDir, 'change-requests/CR-001.md'), CR_APPLIED, 'utf-8');
+
+    const marked = await sdd.markCRApplied();
+    expect(marked).toHaveLength(0);
+  });
+
+  it('integration: create CR → pending → mark applied → no longer pending', async () => {
+    await writeFile(join(tempDir, 'change-requests/CR-001.md'), CR_DRAFT, 'utf-8');
+
+    // Should be pending
+    let pending = await sdd.pendingChangeRequests();
+    expect(pending).toHaveLength(1);
+
+    // Mark as applied
+    await sdd.markCRApplied();
+
+    // Should no longer be pending
+    pending = await sdd.pendingChangeRequests();
+    expect(pending).toHaveLength(0);
+
+    // But still in the full list
+    const all = await sdd.changeRequests();
+    expect(all).toHaveLength(1);
+    expect(all[0].frontmatter.status).toBe('applied');
+  });
+
+  it('init creates change-requests/ directory', async () => {
+    expect(existsSync(join(tempDir, 'change-requests'))).toBe(true);
+  });
+});

package/tests/delta.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, writeFile, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { computeDelta } from '../src/delta/delta-engine.js';
+
+function git(cmd: string, cwd: string): string {
+  return execSync(`git ${cmd}`, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+
+describe('computeDelta', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'sdd-delta-test-'));
+    git('init', tempDir);
+    git('config user.email "test@test.com"', tempDir);
+    git('config user.name "Test"', tempDir);
+    await mkdir(join(tempDir, 'product'), { recursive: true });
+    await mkdir(join(tempDir, 'system'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true });
+  });
+
+  it('detects new files when no previous sync', async () => {
+    await writeFile(join(tempDir, 'product/vision.md'), '# Vision', 'utf-8');
+    git('add .', tempDir);
+    git('commit -m "init"', tempDir);
+
+    const delta = computeDelta(tempDir, null);
+    expect(delta.hasChanges).toBe(true);
+    expect(delta.files).toHaveLength(1);
+    expect(delta.files[0].relativePath).toBe('product/vision.md');
+    expect(delta.files[0].status).toBe('new');
+  });
+
+  it('detects modified files since last sync commit', async () => {
+    await writeFile(join(tempDir, 'product/vision.md'), '# Vision v1', 'utf-8');
+    git('add .', tempDir);
+    git('commit -m "init"', tempDir);
+    const syncCommit = git('rev-parse HEAD', tempDir);
+
+    await writeFile(join(tempDir, 'product/vision.md'), '# Vision v2', 'utf-8');
+    git('add .', tempDir);
+    git('commit -m "update"', tempDir);
+
+    const delta = computeDelta(tempDir, syncCommit);
+    expect(delta.hasChanges).toBe(true);
+    expect(delta.files[0].status).toBe('modified');
+  });
+
+  it('detects deleted files since last sync commit', async () => {
+    await writeFile(join(tempDir, 'product/old.md'), '# Old', 'utf-8');
+    git('add .', tempDir);
+    git('commit -m "init"', tempDir);
+    const syncCommit = git('rev-parse HEAD', tempDir);
+
+    git('rm product/old.md', tempDir);
+    git('commit -m "delete"', tempDir);
+
+    const delta = computeDelta(tempDir, syncCommit);
+    expect(delta.hasChanges).toBe(true);
+    expect(delta.files[0].status).toBe('deleted');
+  });
+
+  it('reports no changes when nothing changed since sync', async () => {
+    await writeFile(join(tempDir, 'product/vision.md'), '# Vision', 'utf-8');
+    git('add .', tempDir);
+    git('commit -m "init"', tempDir);
+    const syncCommit = git('rev-parse HEAD', tempDir);
+
+    const delta = computeDelta(tempDir, syncCommit);
+    expect(delta.hasChanges).toBe(false);
+    expect(delta.files).toHaveLength(0);
+  });
+
+  it('includes diff text', async () => {
+    await writeFile(join(tempDir, 'product/vision.md'), '# Vision v1', 'utf-8');
+    git('add .', tempDir);
+    git('commit -m "init"', tempDir);
+    const syncCommit = git('rev-parse HEAD', tempDir);
+
+    await writeFile(join(tempDir, 'product/vision.md'), '# Vision v2', 'utf-8');
+    git('add .', tempDir);
+    git('commit -m "update"', tempDir);
+
+    const delta = computeDelta(tempDir, syncCommit);
+    expect(delta.diff).toContain('Vision v1');
+    expect(delta.diff).toContain('Vision v2');
+  });
+});