@pcoliveira90/pdd 0.2.1-beta.0

package/src/cli/index.js

@@ -0,0 +1,113 @@
+import { runValidation } from '../core/validator.js';
+import { openPullRequest } from '../core/pr-manager.js';
+import { generatePatchArtifacts } from '../core/patch-generator.js';
+import { runInit } from './init-command.js';
+import { runDoctor } from './doctor-command.js';
+import { runStatus } from './status-command.js';
+import { runResilientFixWorkflow } from '../core/fix-runner.js';
+
+function parseFixArgs(argv) {
+  const issue = argv
+    .filter(arg => !arg.startsWith('--') && arg !== 'fix')
+    .join(' ')
+    .trim();
+
+  return {
+    issue,
+    openPr: argv.includes('--open-pr'),
+    dryRun: argv.includes('--dry-run'),
+    noValidate: argv.includes('--no-validate')
+  };
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  const command = argv[0];
+  const cwd = process.cwd();
+
+  if (command === 'init') {
+    runInit(argv);
+    return;
+  }
+
+  if (command === 'doctor') {
+    runDoctor(cwd, argv);
+    return;
+  }
+
+  if (command === 'status') {
+    runStatus(cwd);
+    return;
+  }
+
+  if (command === 'fix') {
+    const { issue, openPr, dryRun, noValidate } = parseFixArgs(argv);
+
+    if (!issue) {
+      console.error('❌ Missing issue description.');
+      console.log('Use: pdd fix "description" [--open-pr] [--dry-run] [--no-validate]');
+      process.exit(1);
+    }
+
+    console.log('🔧 PDD Fix Workflow');
+    console.log(`Issue: ${issue}`);
+    console.log(`Open PR prep: ${openPr ? 'yes' : 'no'}`);
+    console.log(`Dry run: ${dryRun ? 'yes' : 'no'}`);
+    console.log(`Validation: ${noValidate ? 'skipped' : 'enabled'}`);
+
+    try {
+      const result = await runResilientFixWorkflow({
+        baseDir: cwd,
+        issue,
+        dryRun,
+        noValidate,
+        openPr,
+        generatePatchArtifacts,
+        runValidation,
+        openPullRequest
+      });
+
+      if (result.status === 'dry-run') {
+        console.log('📝 Dry run only. No files created.');
+        return;
+      }
+
+      if (result.changeId) {
+        console.log(`Tracking change: ${result.changeId}`);
+      }
+
+      if (Array.isArray(result.files) && result.files.length > 0) {
+        console.log('🧩 Patch artifacts created:');
+        result.files.forEach(file => console.log(`- ${file}`));
+      }
+
+      console.log('✅ Fix workflow finished.');
+    } catch (error) {
+      console.error(`❌ ${error.message}`);
+      process.exitCode = 1;
+    }
+
+    return;
+  }
+
+  if (command === 'help' || !command) {
+    console.log('PDD CLI');
+    console.log('');
+    console.log('Commands:');
+    console.log('  pdd init <project-name>');
+    console.log('  pdd init --here [--force] [--upgrade] [--ide=claude|cursor|copilot|claude,cursor,copilot]');
+    console.log('  pdd doctor [--fix]');
+    console.log('  pdd status');
+    console.log('  pdd fix "description" [--open-pr] [--dry-run] [--no-validate]');
+    console.log('');
+    console.log('Examples:');
+    console.log('  pdd doctor --fix');
+    console.log('  pdd status');
+    console.log('  pdd init --here --upgrade');
+    console.log('  pdd fix "login not saving incomeStatus" --open-pr');
+    console.log('');
+    return;
+  }
+
+  console.log(`❌ Unknown command: ${command}`);
+  console.log('Use: pdd help');
+}

package/src/cli/init-command.js

@@ -0,0 +1,123 @@
+import fs from 'fs';
+import path from 'path';
+import { CORE_TEMPLATES, IDE_ADAPTERS, PDD_TEMPLATE_VERSION } from '../core/template-registry.js';
+import { buildTemplateUpgradePlan, applyTemplateUpgradePlan } from '../core/template-upgrade.js';
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function writeFile(baseDir, relativePath, content) {
+  const fullPath = path.join(baseDir, relativePath);
+  ensureDir(fullPath);
+  fs.writeFileSync(fullPath, content, 'utf-8');
+}
+
+function normalizeIdeList(argv) {
+  const ideArg = argv.find(arg => arg.startsWith('--ide='));
+  if (!ideArg) return [];
+
+  return ideArg
+    .split('=')[1]
+    ?.split(',')
+    .map(v => v.trim())
+    .filter(Boolean) || [];
+}
+
+function readInstalledVersion(baseDir) {
+  const versionFile = path.join(baseDir, '.pdd/version.json');
+  if (!fs.existsSync(versionFile)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(versionFile, 'utf-8')).templateVersion;
+  } catch {
+    return null;
+  }
+}
+
+function installIdeAdapters(baseDir, ideList, force) {
+  const results = [];
+
+  for (const ide of ideList) {
+    const adapter = IDE_ADAPTERS[ide];
+    if (!adapter) {
+      results.push({ path: `adapter:${ide}`, status: 'unknown' });
+      continue;
+    }
+
+    for (const [file, content] of Object.entries(adapter)) {
+      const fullPath = path.join(baseDir, file);
+      if (!force && fs.existsSync(fullPath)) {
+        results.push({ path: file, status: 'skipped' });
+        continue;
+      }
+
+      writeFile(baseDir, file, content);
+      results.push({ path: file, status: 'written' });
+    }
+  }
+
+  return results;
+}
+
+function printUpgradeSummary(summary) {
+  console.log('⬆️ PDD upgraded');
+
+  summary.created.forEach(f => console.log(`✔️ created: ${f}`));
+  summary.updated.forEach(f => console.log(`🔁 updated: ${f}`));
+  summary.conflicts.forEach(f => console.log(`⚠️ conflict: ${f}`));
+  summary.skipped.forEach(f => console.log(`⏭️ skipped: ${f}`));
+
+  console.log('');
+  console.log(`Summary:`);
+  console.log(`- created: ${summary.created.length}`);
+  console.log(`- updated: ${summary.updated.length}`);
+  console.log(`- conflicts: ${summary.conflicts.length}`);
+  console.log(`- skipped: ${summary.skipped.length}`);
+
+  if (summary.conflicts.length > 0) {
+    console.log('👉 Run with --force to overwrite conflicts');
+  }
+}
+
+export function runInit(argv = process.argv.slice(2)) {
+  const cwd = process.cwd();
+  const here = argv.includes('--here');
+  const force = argv.includes('--force');
+  const upgrade = argv.includes('--upgrade');
+  const ideList = normalizeIdeList(argv);
+
+  const projectName = !here && argv[1] && !argv[1].startsWith('--') ? argv[1] : null;
+  const baseDir = here ? cwd : path.join(cwd, projectName || 'pdd-project');
+
+  if (!here && !fs.existsSync(baseDir)) {
+    fs.mkdirSync(baseDir, { recursive: true });
+  }
+
+  const installedVersion = readInstalledVersion(baseDir);
+
+  if (upgrade) {
+    const plan = buildTemplateUpgradePlan(baseDir, CORE_TEMPLATES);
+    const summary = applyTemplateUpgradePlan(baseDir, CORE_TEMPLATES, plan, force);
+
+    // always update version.json
+    writeFile(baseDir, '.pdd/version.json', JSON.stringify({ templateVersion: PDD_TEMPLATE_VERSION }, null, 2));
+
+    printUpgradeSummary(summary);
+
+    if (installedVersion === PDD_TEMPLATE_VERSION) {
+      console.log('ℹ️ Templates were already up to date.');
+    }
+
+  } else {
+    // basic init (no intelligence needed yet)
+    for (const [file, content] of Object.entries(CORE_TEMPLATES)) {
+      writeFile(baseDir, file, content);
+    }
+
+    console.log('🚀 PDD initialized');
+  }
+
+  const ideResults = installIdeAdapters(baseDir, ideList, force);
+  ideResults.forEach(r => console.log(`- ${r.status}: ${r.path}`));
+}

package/src/cli/status-command.js

@@ -0,0 +1,33 @@
+import { readProjectState } from '../core/state-manager.js';
+
+export function runStatus(baseDir = process.cwd()) {
+  const state = readProjectState(baseDir);
+
+  console.log('📊 PDD Status\n');
+
+  console.log(`Status: ${state.status}`);
+
+  if (state.activeChange) {
+    console.log(`Active change: ${state.activeChange}`);
+  } else {
+    console.log('Active change: none');
+  }
+
+  if (state.lastChange) {
+    console.log(`Last change: ${state.lastChange}`);
+  }
+
+  if (state.updatedAt) {
+    console.log(`Updated at: ${state.updatedAt}`);
+  }
+
+  console.log('');
+
+  if (state.status === 'in-progress') {
+    console.log('⚠️ A change is currently in progress');
+  } else if (state.status === 'failed') {
+    console.log('❌ Last operation failed');
+  } else {
+    console.log('✅ Project is healthy');
+  }
+}

package/src/core/fix-runner.js

@@ -0,0 +1,135 @@
+import fs from 'fs';
+import path from 'path';
+import {
+  readProjectState,
+  setActiveChange,
+  clearActiveChange,
+  writeProjectState
+} from './state-manager.js';
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function appendText(filePath, content) {
+  ensureDir(filePath);
+  fs.appendFileSync(filePath, content, 'utf-8');
+}
+
+function writeJson(filePath, value) {
+  ensureDir(filePath);
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function buildFailurePayload({ issue, changeId, phase, error }) {
+  return {
+    issue,
+    changeId,
+    phase,
+    error: error?.message || String(error),
+    failedAt: nowIso()
+  };
+}
+
+function persistFailureArtifacts(baseDir, payload) {
+  const changeDir = path.join(baseDir, 'changes', payload.changeId);
+  const failureReportPath = path.join(changeDir, 'failure-report.json');
+  const verificationReportPath = path.join(changeDir, 'verification-report.md');
+
+  writeJson(failureReportPath, payload);
+  appendText(
+    verificationReportPath,
+    `\n## Failure\n- phase: ${payload.phase}\n- error: ${payload.error}\n- failedAt: ${payload.failedAt}\n`
+  );
+
+  return {
+    failureReportPath,
+    verificationReportPath
+  };
+}
+
+export async function runResilientFixWorkflow({
+  baseDir = process.cwd(),
+  issue,
+  dryRun = false,
+  noValidate = false,
+  openPr = false,
+  generatePatchArtifacts,
+  runValidation,
+  openPullRequest
+}) {
+  const current = readProjectState(baseDir);
+  if (current.status === 'in-progress' && current.activeChange) {
+    throw new Error(`Another change is already in progress: ${current.activeChange}`);
+  }
+
+  if (dryRun) {
+    return {
+      status: 'dry-run',
+      issue
+    };
+  }
+
+  const changeId = `change-${Date.now()}`;
+  setActiveChange(baseDir, changeId, 'in-progress');
+
+  try {
+    let phase = 'patch-generation';
+    const patch = generatePatchArtifacts({ issue, baseDir });
+
+    if (!noValidate) {
+      phase = 'validation';
+      runValidation(baseDir);
+    }
+
+    if (openPr) {
+      phase = 'pr-preparation';
+      await openPullRequest({
+        issue,
+        changeId: patch.changeId,
+        changeDir: patch.changeDir,
+        baseDir
+      });
+    }
+
+    clearActiveChange(baseDir, 'completed');
+    writeProjectState(baseDir, {
+      activeChange: null,
+      lastChange: patch.changeId,
+      status: 'completed',
+      lastResult: 'success',
+      lastIssue: issue,
+      lastPhase: 'completed',
+      lastError: null
+    });
+
+    return {
+      status: 'completed',
+      changeId: patch.changeId,
+      files: patch.files
+    };
+  } catch (error) {
+    const phase = current.status === 'in-progress' ? current.lastPhase || 'unknown' : 'unknown';
+    const payload = buildFailurePayload({ issue, changeId, phase, error });
+    const artifacts = persistFailureArtifacts(baseDir, payload);
+
+    writeProjectState(baseDir, {
+      activeChange: changeId,
+      lastChange: changeId,
+      status: 'failed',
+      lastResult: 'failed',
+      lastIssue: issue,
+      lastPhase: phase,
+      lastError: payload.error,
+      lastFailureReport: artifacts.failureReportPath
+    });
+
+    const wrapped = new Error(`Fix failed during ${phase}: ${payload.error}`);
+    wrapped.cause = error;
+    throw wrapped;
+  }
+}

package/src/core/patch-generator.js

@@ -0,0 +1,126 @@
+import fs from 'fs';
+import path from 'path';
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function writeFile(filePath, content) {
+  ensureDir(filePath);
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+function slugify(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+}
+
+export function generatePatchArtifacts({ issue, baseDir = process.cwd() }) {
+  const timestamp = Date.now();
+  const changeId = `change-${timestamp}-${slugify(issue || 'update')}`;
+  const changeDir = path.join(baseDir, 'changes', changeId);
+
+  const files = [
+    path.join('changes', changeId, 'delta-spec.md'),
+    path.join('changes', changeId, 'patch-plan.md'),
+    path.join('changes', changeId, 'verification-report.md')
+  ];
+
+  writeFile(
+    path.join(changeDir, 'delta-spec.md'),
+    `# Delta Spec
+
+## Change ID
+${changeId}
+
+## Issue
+${issue}
+
+## Type
+bugfix | feature | refactor-safe | hotfix
+
+## Context
+
+## Current Behavior
+
+## Expected Behavior
+
+## Evidence
+
+## Root Cause Hypothesis
+
+## Impacted Areas
+
+## Constraints
+
+## Minimal Safe Delta
+
+## Alternatives Considered
+
+## Acceptance Criteria
+
+## Verification Strategy
+`
+  );
+
+  writeFile(
+    path.join(changeDir, 'patch-plan.md'),
+    `# Patch Plan
+
+## Change ID
+${changeId}
+
+## Issue
+${issue}
+
+## Files to Inspect
+
+## Files to Change
+
+## Execution Steps
+1. Reproduce issue
+2. Confirm root cause
+3. Apply minimal change
+4. Adjust tests
+5. Run validations
+
+## Regression Risks
+
+## Rollback Strategy
+`
+  );
+
+  writeFile(
+    path.join(changeDir, 'verification-report.md'),
+    `# Verification Report
+
+## Change ID
+${changeId}
+
+## Issue
+${issue}
+
+## Reproduction
+
+## Changes Made
+
+## Tests Run
+
+## Manual Validation
+
+## Residual Risks
+
+## Final Status
+pending
+`
+  );
+
+  return {
+    changeId,
+    changeDir,
+    files
+  };
+}

package/src/core/pr-manager.js

@@ -0,0 +1,21 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+function exec(command) {
+  execSync(command, { stdio: 'inherit' });
+}
+
+export async function openPullRequest({ issue, changeId, changeDir }) {
+  const branch = `pdd/${changeId}`;
+  const title = `fix: ${issue}`;
+
+  fs.writeFileSync(path.join(changeDir, 'pr-title.txt'), title);
+  fs.writeFileSync(path.join(changeDir, 'pr-body.md'), issue);
+
+  exec(`git checkout -b ${branch}`);
+  exec('git add .');
+  exec(`git commit -m "${title}"`);
+
+  console.log('PR ready (use IDE to open)');
+}

package/src/core/remediation-advisor.js

@@ -0,0 +1,91 @@
+export function buildDoctorRemediationPlan({ coreChecks, adapters, installedVersion, currentVersion }) {
+  const problems = [];
+
+  const missingCore = Object.entries(coreChecks)
+    .filter(([, ok]) => !ok)
+    .map(([key]) => key);
+
+  if (missingCore.length > 0) {
+    problems.push({
+      severity: 'high',
+      code: 'missing-core',
+      summary: 'Core PDD files are missing',
+      details: missingCore,
+      action: 'Run `pdd doctor --fix` to restore missing core files.'
+    });
+  }
+
+  if (!installedVersion) {
+    problems.push({
+      severity: 'high',
+      code: 'missing-version',
+      summary: 'Template version metadata is missing',
+      details: ['.pdd/version.json'],
+      action: 'Run `pdd doctor --fix` or `pdd init --here --force`.'
+    });
+  } else if (installedVersion !== currentVersion) {
+    problems.push({
+      severity: 'medium',
+      code: 'outdated-templates',
+      summary: `Templates are outdated (${installedVersion} → ${currentVersion})`,
+      details: [],
+      action: 'Run `pdd init --here --upgrade` to update templates safely.'
+    });
+  }
+
+  const missingAdapters = Object.entries(adapters)
+    .filter(([, ok]) => !ok)
+    .map(([key]) => key);
+
+  if (missingAdapters.length === Object.keys(adapters).length) {
+    problems.push({
+      severity: 'low',
+      code: 'no-adapters',
+      summary: 'No IDE adapters are installed',
+      details: missingAdapters,
+      action: 'Run `pdd init --here --ide=claude` (or cursor/copilot).' 
+    });
+  }
+
+  const ordered = problems.sort((a, b) => rankSeverity(a.severity) - rankSeverity(b.severity));
+
+  return {
+    ok: ordered.length === 0,
+    problems: ordered,
+    nextAction: ordered[0]?.action || null
+  };
+}
+
+function rankSeverity(severity) {
+  switch (severity) {
+    case 'high':
+      return 0;
+    case 'medium':
+      return 1;
+    default:
+      return 2;
+  }
+}
+
+export function printDoctorRemediationPlan(plan) {
+  if (plan.ok) {
+    console.log('✅ No guided remediation needed.');
+    return;
+  }
+
+  console.log('');
+  console.log('🧭 Guided remediation');
+
+  plan.problems.forEach((problem, index) => {
+    console.log(`${index + 1}. [${problem.severity.toUpperCase()}] ${problem.summary}`);
+    if (problem.details.length > 0) {
+      console.log(`   Details: ${problem.details.join(', ')}`);
+    }
+    console.log(`   Action: ${problem.action}`);
+  });
+
+  if (plan.nextAction) {
+    console.log('');
+    console.log(`👉 Recommended next step: ${plan.nextAction}`);
+  }
+}

package/src/core/state-manager.js

@@ -0,0 +1,71 @@
+import fs from 'fs';
+import path from 'path';
+
+const DEFAULT_STATE = {
+  activeChange: null,
+  status: 'idle',
+  lastChange: null,
+  updatedAt: null
+};
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function getStatePath(baseDir = process.cwd()) {
+  return path.join(baseDir, '.pdd/state.json');
+}
+
+export function readProjectState(baseDir = process.cwd()) {
+  const statePath = getStatePath(baseDir);
+  if (!fs.existsSync(statePath)) {
+    return { ...DEFAULT_STATE };
+  }
+
+  try {
+    const raw = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+    return { ...DEFAULT_STATE, ...raw };
+  } catch {
+    return { ...DEFAULT_STATE };
+  }
+}
+
+export function writeProjectState(baseDir = process.cwd(), nextState = {}) {
+  const statePath = getStatePath(baseDir);
+  ensureDir(statePath);
+
+  const merged = {
+    ...DEFAULT_STATE,
+    ...nextState,
+    updatedAt: new Date().toISOString()
+  };
+
+  fs.writeFileSync(statePath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+  return merged;
+}
+
+export function setActiveChange(baseDir = process.cwd(), changeId, status = 'in-progress') {
+  return writeProjectState(baseDir, {
+    activeChange: changeId,
+    lastChange: changeId,
+    status
+  });
+}
+
+export function markProjectState(baseDir = process.cwd(), status = 'idle') {
+  const current = readProjectState(baseDir);
+  return writeProjectState(baseDir, {
+    ...current,
+    status,
+    activeChange: status === 'in-progress' ? current.activeChange : null
+  });
+}
+
+export function clearActiveChange(baseDir = process.cwd(), status = 'idle') {
+  const current = readProjectState(baseDir);
+  return writeProjectState(baseDir, {
+    ...current,
+    activeChange: null,
+    status
+  });
+}