@applica-software-guru/sdd-core 0.1.0

package/dist/validate/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/validate/validator.ts"],"names":[],"mappings":";;AAEA,4BA2CC;AA3CD,SAAgB,QAAQ,CAAC,KAAkB;IACzC,MAAM,MAAM,GAAsB,EAAE,CAAC;IAErC,qDAAqD;IACrD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IACtC,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;IAC/E,IAAI,YAAY,EAAE,CAAC;QACjB,uCAAuC;QACvC,MAAM,SAAS,GAAG,cAAc,CAAC;QACjC,IAAI,KAA6B,CAAC;QAClC,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAC5D,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,gCAAgC;QAChC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,WAAW,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClD,MAAM,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,SAAS;oBACnB,QAAQ,EAAE,IAAI,CAAC,YAAY;oBAC3B,OAAO,EAAE,sBAAsB,GAAG,sCAAsC;oBACxE,IAAI,EAAE,YAAY;iBACnB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,wCAAwC;QACxC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,SAAS;gBACnB,QAAQ,EAAE,IAAI,CAAC,YAAY;gBAC3B,OAAO,EAAE,gCAAgC;gBACzC,IAAI,EAAE,qBAAqB;aAC5B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC;QAChE,MAAM;KACP,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@applica-software-guru/sdd-core",
+  "version": "0.1.0",
+  "description": "Core library for Story Driven Development",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "glob": "^11.0.0",
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9"
+  }
+}

package/src/config/config-manager.ts

@@ -0,0 +1,39 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import yaml from 'js-yaml';
+import type { SDDConfig } from '../types.js';
+
+export const SDD_DIR = '.sdd';
+export const CONFIG_FILENAME = 'config.yaml';
+
+export function sddDirPath(root: string): string {
+  return resolve(root, SDD_DIR);
+}
+
+export function configFilePath(root: string): string {
+  return resolve(root, SDD_DIR, CONFIG_FILENAME);
+}
+
+export function isSDDProject(root: string): boolean {
+  return existsSync(sddDirPath(root));
+}
+
+export async function readConfig(root: string): Promise<SDDConfig> {
+  const path = configFilePath(root);
+  if (!existsSync(path)) {
+    return { description: '' };
+  }
+  const content = await readFile(path, 'utf-8');
+  const parsed = yaml.load(content) as SDDConfig | null;
+  return parsed ?? { description: '' };
+}
+
+export async function writeConfig(root: string, config: SDDConfig): Promise<void> {
+  const dir = sddDirPath(root);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+  const content = yaml.dump(config, { sortKeys: true, lineWidth: -1 });
+  await writeFile(configFilePath(root), content, 'utf-8');
+}

package/src/delta/delta-engine.ts

@@ -0,0 +1,18 @@
+import type { Delta, DeltaFile } from '../types.js';
+import { getChangedFiles, getGitDiff } from '../git/git.js';
+
+export function computeDelta(root: string, lastSyncCommit: string | null): Delta {
+  const changed = getChangedFiles(root, lastSyncCommit);
+  const diff = getGitDiff(root, lastSyncCommit);
+
+  const files: DeltaFile[] = changed.map((f) => ({
+    relativePath: f.path,
+    status: f.status,
+  }));
+
+  return {
+    hasChanges: files.length > 0,
+    files,
+    diff,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,27 @@
+export class SDDError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SDDError';
+  }
+}
+
+export class LockFileNotFoundError extends SDDError {
+  constructor(path: string) {
+    super(`Lock file not found: ${path}`);
+    this.name = 'LockFileNotFoundError';
+  }
+}
+
+export class ParseError extends SDDError {
+  constructor(filePath: string, reason: string) {
+    super(`Failed to parse ${filePath}: ${reason}`);
+    this.name = 'ParseError';
+  }
+}
+
+export class ProjectNotInitializedError extends SDDError {
+  constructor(root: string) {
+    super(`No SDD project found at ${root}. Run 'sdd init' first.`);
+    this.name = 'ProjectNotInitializedError';
+  }
+}

package/src/git/git.ts

@@ -0,0 +1,113 @@
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+
+export function isGitRepo(root: string): boolean {
+  return existsSync(resolve(root, '.git'));
+}
+
+export function gitInit(root: string): void {
+  run('git init', root);
+}
+
+export function gitAddAndCommit(root: string, files: string[], message: string): void {
+  try {
+    for (const f of files) {
+      run(`git add -- ${f}`, root);
+    }
+    run(`git commit -m "${message}"`, root);
+  } catch {
+    // ignore — no changes to commit or no git user configured
+  }
+}
+
+export function getCurrentCommit(root: string): string | null {
+  try {
+    return run('git rev-parse HEAD', root) || null;
+  } catch {
+    return null;
+  }
+}
+
+export function getGitDiff(root: string, fromCommit: string | null): string {
+  const paths = '-- product/ system/';
+  try {
+    if (!fromCommit) {
+      // No previous sync — show all tracked + untracked files as new
+      const tracked = run(`git diff HEAD ${paths}`, root);
+      const untracked = run('git ls-files --others --exclude-standard product/ system/', root);
+      const parts: string[] = [];
+      if (tracked) parts.push(tracked);
+      if (untracked) {
+        for (const file of untracked.split('\n').filter(Boolean)) {
+          parts.push(`new file: ${file}`);
+        }
+      }
+      return parts.join('\n') || '';
+    }
+    return run(`git diff ${fromCommit} HEAD ${paths}`, root);
+  } catch {
+    return '';
+  }
+}
+
+export function getFileDiff(root: string, filePath: string): string {
+  try {
+    // Show diff of file vs last committed version
+    const diff = run(`git diff HEAD -- ${filePath}`, root);
+    if (diff) return diff;
+    // If no unstaged changes, try diff vs previous commit
+    return run(`git diff HEAD~1 HEAD -- ${filePath}`, root);
+  } catch {
+    return '';
+  }
+}
+
+export function getGitModifiedFiles(root: string): Set<string> {
+  const modified = new Set<string>();
+  try {
+    // Unstaged changes
+    const unstaged = run('git diff --name-only -- product/ system/', root);
+    for (const f of unstaged.split('\n').filter(Boolean)) modified.add(f);
+    // Staged changes
+    const staged = run('git diff --cached --name-only -- product/ system/', root);
+    for (const f of staged.split('\n').filter(Boolean)) modified.add(f);
+    // Untracked files
+    const untracked = run('git ls-files --others --exclude-standard product/ system/', root);
+    for (const f of untracked.split('\n').filter(Boolean)) modified.add(f);
+  } catch {
+    // not a git repo or no commits — ignore
+  }
+  return modified;
+}
+
+export function getChangedFiles(root: string, fromCommit: string | null): Array<{ path: string; status: 'new' | 'modified' | 'deleted' }> {
+  try {
+    if (!fromCommit) {
+      // All files in product/ and system/ are "new"
+      const files = run('git ls-files product/ system/', root);
+      const untracked = run('git ls-files --others --exclude-standard product/ system/', root);
+      const all = [...files.split('\n'), ...untracked.split('\n')].filter(Boolean);
+      const unique = [...new Set(all)];
+      return unique.map((p) => ({ path: p, status: 'new' as const }));
+    }
+
+    const output = run(`git diff --name-status ${fromCommit} HEAD -- product/ system/`, root);
+    if (!output) return [];
+
+    return output.split('\n').filter(Boolean).map((line) => {
+      const [flag, ...pathParts] = line.split('\t');
+      const path = pathParts.join('\t');
+      const status = flag === 'A' ? 'new' as const
+        : flag === 'D' ? 'deleted' as const
+        : 'modified' as const;
+      return { path, status };
+    });
+  } catch {
+    return [];
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export { SDD } from './sdd.js';
+export type {
+  StoryFrontmatter,
+  StoryFile,
+  PendingItem,
+  Delta,
+  DeltaFile,
+  ValidationResult,
+  ValidationIssue,
+  StoryStatus,
+  StoryFileStatus,
+  SDDConfig,
+  ChangeRequest,
+  ChangeRequestFrontmatter,
+  ChangeRequestStatus,
+} from './types.js';
+export { SDDError, LockFileNotFoundError, ParseError, ProjectNotInitializedError } from './errors.js';
+export type { ProjectInfo } from './scaffold/templates.js';
+export { isSDDProject, readConfig } from './config/config-manager.js';

package/src/parser/cr-parser.ts

@@ -0,0 +1,41 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, relative } from 'node:path';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+import type { ChangeRequest, ChangeRequestFrontmatter } from '../types.js';
+import { ParseError } from '../errors.js';
+
+export async function discoverCRFiles(root: string): Promise<string[]> {
+  const pattern = 'change-requests/*.md';
+  const matches = await glob(pattern, { cwd: root, absolute: true });
+  return matches.sort();
+}
+
+export function parseCRFile(filePath: string, content: string): { frontmatter: ChangeRequestFrontmatter; body: string } {
+  try {
+    const { data, content: body } = matter(content);
+    const frontmatter: ChangeRequestFrontmatter = {
+      title: data.title ?? '',
+      status: data.status ?? 'draft',
+      author: data.author ?? '',
+      'created-at': data['created-at'] ?? '',
+    };
+    return { frontmatter, body };
+  } catch (err) {
+    throw new ParseError(filePath, (err as Error).message);
+  }
+}
+
+export async function parseAllCRFiles(root: string): Promise<ChangeRequest[]> {
+  const paths = await discoverCRFiles(root);
+  const results: ChangeRequest[] = [];
+
+  for (const absPath of paths) {
+    const content = await readFile(absPath, 'utf-8');
+    const relPath = relative(root, absPath);
+    const { frontmatter, body } = parseCRFile(relPath, content);
+    results.push({ relativePath: relPath, frontmatter, body });
+  }
+
+  return results;
+}

package/src/parser/frontmatter.ts

@@ -0,0 +1,24 @@
+import matter from 'gray-matter';
+import type { StoryFrontmatter } from '../types.js';
+import { ParseError } from '../errors.js';
+
+export interface ParsedFile {
+  frontmatter: StoryFrontmatter;
+  body: string;
+}
+
+export function parseFrontmatter(filePath: string, content: string): ParsedFile {
+  try {
+    const { data, content: body } = matter(content);
+    const frontmatter: StoryFrontmatter = {
+      title: data.title ?? '',
+      status: data.status ?? 'draft',
+      author: data.author ?? '',
+      'last-modified': data['last-modified'] ?? '',
+      version: data.version ?? '1.0',
+    };
+    return { frontmatter, body };
+  } catch (err) {
+    throw new ParseError(filePath, (err as Error).message);
+  }
+}

package/src/parser/ref-extractor.ts

@@ -0,0 +1,14 @@
+const REF_RE = /\[\[([^\]]+)\]\]/g;
+
+export function extractCrossRefs(body: string): string[] {
+  const refs: string[] = [];
+  let match: RegExpExecArray | null;
+  const re = new RegExp(REF_RE.source, REF_RE.flags);
+  while ((match = re.exec(body)) !== null) {
+    const ref = match[1].trim();
+    if (!refs.includes(ref)) {
+      refs.push(ref);
+    }
+  }
+  return refs;
+}

package/src/parser/section-extractor.ts

@@ -0,0 +1,38 @@
+import type { PendingItem } from '../types.js';
+
+const CHECKBOX_RE = /^- \[([ xX])\] (.+)$/gm;
+
+export function extractPendingItems(body: string): PendingItem[] {
+  const section = extractSection(body, 'Pending Changes');
+  if (!section) return [];
+
+  const items: PendingItem[] = [];
+  let match: RegExpExecArray | null;
+  const re = new RegExp(CHECKBOX_RE.source, CHECKBOX_RE.flags);
+  while ((match = re.exec(section)) !== null) {
+    items.push({
+      checked: match[1] !== ' ',
+      text: match[2].trim(),
+    });
+  }
+  return items;
+}
+
+export function extractAgentNotes(body: string): string | null {
+  const section = extractSection(body, 'Agent Notes');
+  return section ? section.trim() : null;
+}
+
+function extractSection(body: string, heading: string): string | null {
+  const headingRe = new RegExp(`^## ${escapeRegex(heading)}\\s*$`, 'm');
+  const match = headingRe.exec(body);
+  if (!match) return null;
+
+  const start = match.index + match[0].length;
+  const nextHeading = body.indexOf('\n## ', start);
+  return nextHeading === -1 ? body.slice(start) : body.slice(start, nextHeading);
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/parser/story-parser.ts

@@ -0,0 +1,40 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, relative } from 'node:path';
+import { glob } from 'glob';
+import { createHash } from 'node:crypto';
+import type { StoryFile } from '../types.js';
+import { parseFrontmatter } from './frontmatter.js';
+import { extractPendingItems, extractAgentNotes } from './section-extractor.js';
+import { extractCrossRefs } from './ref-extractor.js';
+
+export async function discoverStoryFiles(root: string): Promise<string[]> {
+  const patterns = ['product/**/*.md', 'system/**/*.md'];
+  const files: string[] = [];
+  for (const pattern of patterns) {
+    const matches = await glob(pattern, { cwd: root, absolute: true });
+    files.push(...matches);
+  }
+  return files.sort();
+}
+
+export async function parseStoryFile(root: string, absolutePath: string): Promise<StoryFile> {
+  const content = await readFile(absolutePath, 'utf-8');
+  const relPath = relative(root, absolutePath);
+  const { frontmatter, body } = parseFrontmatter(relPath, content);
+  const hash = createHash('sha256').update(content).digest('hex');
+
+  return {
+    relativePath: relPath,
+    frontmatter,
+    body,
+    pendingItems: extractPendingItems(body),
+    agentNotes: extractAgentNotes(body),
+    crossRefs: extractCrossRefs(body),
+    hash,
+  };
+}
+
+export async function parseAllStoryFiles(root: string): Promise<StoryFile[]> {
+  const paths = await discoverStoryFiles(root);
+  return Promise.all(paths.map((p) => parseStoryFile(root, p)));
+}

package/src/prompt/prompt-generator.ts

@@ -0,0 +1,49 @@
+import type { StoryFile } from '../types.js';
+import { getFileDiff } from '../git/git.js';
+
+export function generatePrompt(files: StoryFile[], root?: string): string {
+  const sections: string[] = [];
+
+  sections.push(
+    '# SDD Sync Prompt\n\nThis project uses Story Driven Development. Implement the changes described below.'
+  );
+
+  if (files.length === 0) {
+    sections.push('Nothing to do — all files are synced.');
+    return sections.join('\n\n');
+  }
+
+  const lines = [`## Files to process (${files.length})\n`];
+  for (const f of files) {
+    lines.push(`- \`${f.relativePath}\` — **${f.frontmatter.status}**`);
+  }
+  lines.push('');
+  lines.push('Read each file listed above before implementing.');
+  sections.push(lines.join('\n'));
+
+  // Show git diff for changed files so the agent knows what was modified
+  if (root) {
+    const changed = files.filter((f) => f.frontmatter.status === 'changed');
+    for (const f of changed) {
+      const diff = getFileDiff(root, f.relativePath);
+      if (diff) {
+        sections.push(`## Changes in \`${f.relativePath}\`\n\n\`\`\`diff\n${diff}\n\`\`\``);
+      }
+    }
+  }
+
+  const deleted = files.filter((f) => f.frontmatter.status === 'deleted');
+  if (deleted.length > 0) {
+    const delLines = ['## Files to remove\n'];
+    for (const f of deleted) {
+      delLines.push(`- \`${f.relativePath}\` — remove all related code in \`code/\``);
+    }
+    sections.push(delLines.join('\n'));
+  }
+
+  sections.push(
+    `## Instructions\n\n1. Read each file listed above\n2. For **new** files: implement what the documentation describes\n3. For **changed** files: update the code to match the updated documentation (see diff above)\n4. For **deleted** files: remove the related code from \`code/\`\n5. If a file has a \`## Agent Notes\` section, respect those constraints\n6. All code goes inside \`code/\`\n7. After implementing each file, run \`sdd mark-synced <file>\`\n8. **Immediately after mark-synced, commit**: \`git add -A && git commit -m "sdd sync: <description>"\`\n9. When done with all files, list every file you created or modified`
+  );
+
+  return sections.join('\n\n');
+}

package/src/scaffold/init.ts

@@ -0,0 +1,71 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { AGENT_MD_TEMPLATE, type ProjectInfo } from './templates.js';
+import { writeConfig, sddDirPath } from '../config/config-manager.js';
+import { isGitRepo, gitInit } from '../git/git.js';
+import type { SDDConfig } from '../types.js';
+
+export async function initProject(root: string, info?: ProjectInfo): Promise<string[]> {
+  const createdFiles: string[] = [];
+  const sddDir = sddDirPath(root);
+
+  // Ensure git repo
+  if (!isGitRepo(root)) {
+    gitInit(root);
+    createdFiles.push('.git');
+  }
+
+  // Create .sdd directory
+  if (!existsSync(sddDir)) {
+    await mkdir(sddDir, { recursive: true });
+  }
+
+  // Write config
+  const config: SDDConfig = {
+    description: info?.description ?? '',
+  };
+  await writeConfig(root, config);
+  createdFiles.push('.sdd/config.yaml');
+
+  // Create directory structure
+  const dirs = ['product', 'product/features', 'system', 'code', 'change-requests'];
+  for (const dir of dirs) {
+    const absDir = resolve(root, dir);
+    if (!existsSync(absDir)) {
+      await mkdir(absDir, { recursive: true });
+    }
+  }
+
+  // Create agent instructions
+  const instructionsPath = resolve(root, 'INSTRUCTIONS.md');
+  if (!existsSync(instructionsPath)) {
+    await writeFile(instructionsPath, AGENT_MD_TEMPLATE, 'utf-8');
+    createdFiles.push('INSTRUCTIONS.md');
+  }
+
+  // Create agent instruction pointers
+  const POINTER = 'Read INSTRUCTIONS.md in the project root for all instructions.\n';
+  const agentFiles: Array<{ path: string; dir?: string }> = [
+    { path: '.claude/CLAUDE.md', dir: '.claude' },
+    { path: '.github/copilot-instructions.md', dir: '.github' },
+    { path: '.cursorrules' },
+  ];
+
+  for (const entry of agentFiles) {
+    const absPath = resolve(root, entry.path);
+    if (existsSync(absPath)) continue;
+
+    if (entry.dir) {
+      const absDir = resolve(root, entry.dir);
+      if (!existsSync(absDir)) {
+        await mkdir(absDir, { recursive: true });
+      }
+    }
+
+    await writeFile(absPath, POINTER, 'utf-8');
+    createdFiles.push(entry.path);
+  }
+
+  return createdFiles;
+}