@pcoliveira90/pdd 0.2.1-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paula Oliveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,60 @@
+# PDD — Patch-Driven Development
+![npm](https://img.shields.io/npm/v/@pcoliveira90/pdd)
+![license](https://img.shields.io/github/license/pcoliveira90/pdd)
+![stars](https://img.shields.io/github/stars/pcoliveira90/pdd)
+![issues](https://img.shields.io/github/issues/pcoliveira90/pdd)
+> Ship safe changes in living systems.
+
+PDD is an open-source framework focused on **bugfixes and incremental feature development in existing systems**.
+
+---
+
+## The Problem
+
+Most development is not greenfield.
+
+It is:
+- fixing bugs in production
+- evolving legacy systems
+- adding features without breaking things
+
+---
+
+## The Solution: PDD
+
+PDD focuses on:
+- understanding existing systems
+- identifying root causes
+- applying minimal safe changes
+- validating with evidence
+
+---
+
+## Core Flow
+
+Issue → Recon → Delta Spec → Patch Plan → Change → Verify
+
+---
+
+## Principles
+
+- Change-first
+- Evidence before edit
+- Minimal safe delta
+- Root-cause over symptom patch
+- Regression-aware
+- Reuse existing patterns
+- Verifiable outcomes
+
+---
+
+## Structure
+
+.pdd/
+examples/
+
+---
+
+## Vision
+
+Make AI-assisted development safe for real-world systems.

package/README.md

@@ -0,0 +1,26 @@
+# PDD — Patch-Driven Development
+
+> Safe changes in real systems.
+
+PDD is a framework focused on executing safe changes in existing systems.
+
+## CLI
+
+```bash
+pdd init
+pdd fix "bug"
+pdd fix "bug" --dry-run
+pdd fix "bug" --no-validate
+pdd fix "bug" --open-pr
+```
+
+## Flow
+
+1. describe issue
+2. generate artifacts
+3. validate
+4. prepare PR (IDE handles opening)
+
+## Goal
+
+Reliable execution engine for safe software changes.

package/README.pt-BR.md

@@ -0,0 +1,12 @@
+# PDD — Patch-Driven Development
+
+> Entregue mudanças seguras em sistemas existentes.
+
+PDD é um framework focado em aplicar mudanças seguras em sistemas reais.
+
+## CLI
+
+```bash
+pdd init
+pdd fix "bug"
+```

package/bin/pdd-ai.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { runAiFixAnalysis } from '../src/ai/run-fix-analysis.js';
+
+async function main() {
+  try {
+    const result = await runAiFixAnalysis(process.argv.slice(2));
+
+    console.log('\n🤖 PDD AI Analysis');
+    console.log('----------------------');
+    console.log(`Provider: ${result.provider}`);
+    console.log(`Model: ${result.model}`);
+    console.log(`Issue: ${result.issue}`);
+    console.log('\nResult:\n');
+
+    console.log(JSON.stringify(result.result, null, 2));
+  } catch (err) {
+    console.error('❌ Error:', err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/pdd-pro.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli/index.js';
+
+runCli();

package/bin/pdd.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+
+const command = process.argv[2];
+
+if (command === 'init') {
+  const targetDir = process.cwd();
+  const pddDir = path.join(targetDir, '.pdd');
+
+  if (fs.existsSync(pddDir)) {
+    console.log('PDD already initialized.');
+    process.exit(0);
+  }
+
+  fs.mkdirSync(pddDir, { recursive: true });
+  fs.mkdirSync(path.join(pddDir, 'templates'));
+  fs.mkdirSync(path.join(pddDir, 'commands'));
+  fs.mkdirSync(path.join(pddDir, 'memory'));
+
+  fs.writeFileSync(path.join(pddDir, 'README.md'), 'PDD initialized');
+
+  console.log('✅ PDD initialized successfully.');
+} else {
+  console.log('Usage: pdd init');
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pcoliveira90/pdd",
+  "version": "0.2.1-beta.0",
+  "description": "Patch-Driven Development CLI — safe, resilient and guided code changes",
+  "type": "module",
+  "bin": {
+    "pdd": "bin/pdd-pro.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "start": "node bin/pdd-pro.js",
+    "dev": "node bin/pdd-pro.js",
+    "test": "echo \"No tests yet\"",
+    "lint": "echo \"No lint configured\"",
+    "prepublishOnly": "npm pack"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "cli",
+    "developer-tools",
+    "patch",
+    "refactoring",
+    "ai-workflow",
+    "engineering",
+    "pdd"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pcoliveira90/pdd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pcoliveira90/pdd/issues"
+  },
+  "homepage": "https://github.com/pcoliveira90/pdd#readme",
+  "author": "Paula Oliveira",
+  "license": "MIT"
+}

package/src/ai/analyze-change.js

@@ -0,0 +1,41 @@
+import fs from 'fs';
+import path from 'path';
+
+function readIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, 'utf-8');
+}
+
+export function buildAiAnalysisContext(baseDir = process.cwd()) {
+  const context = {
+    constitution: readIfExists(path.join(baseDir, '.pdd', 'constitution.md')),
+    deltaSpec: readIfExists(path.join(baseDir, '.pdd', 'templates', 'delta-spec.md')),
+    patchPlan: readIfExists(path.join(baseDir, '.pdd', 'templates', 'patch-plan.md')),
+    verification: readIfExists(path.join(baseDir, '.pdd', 'templates', 'verification-report.md'))
+  };
+
+  return context;
+}
+
+export function buildBugfixPrompt({ issue, baseDir = process.cwd() }) {
+  const context = buildAiAnalysisContext(baseDir);
+
+  return [
+    'You are a senior engineer working in an existing system.',
+    'Follow Patch-Driven Development principles.',
+    'Focus on root cause, minimal safe delta, and regression awareness.',
+    '',
+    'Issue:',
+    issue,
+    '',
+    'Available context:',
+    JSON.stringify(context, null, 2),
+    '',
+    'Return:',
+    '- root cause hypothesis',
+    '- impacted areas',
+    '- minimal safe delta',
+    '- regression risks',
+    '- validation plan'
+  ].join('\n');
+}

package/src/ai/engine.js

@@ -0,0 +1,34 @@
+export function getAiProviderConfig(provider = 'openai') {
+  const providers = {
+    openai: {
+      name: 'openai',
+      envKey: 'OPENAI_API_KEY',
+      baseUrlEnv: 'OPENAI_BASE_URL',
+      defaultModel: 'gpt-5'
+    },
+    claude: {
+      name: 'claude',
+      envKey: 'ANTHROPIC_API_KEY',
+      baseUrlEnv: 'ANTHROPIC_BASE_URL',
+      defaultModel: 'claude-sonnet-4-20250514'
+    },
+    openrouter: {
+      name: 'openrouter',
+      envKey: 'OPENROUTER_API_KEY',
+      baseUrlEnv: 'OPENROUTER_BASE_URL',
+      defaultModel: 'openai/gpt-4.1-mini'
+    }
+  };
+
+  const config = providers[provider];
+
+  if (!config) {
+    throw new Error(`Unsupported AI provider: ${provider}`);
+  }
+
+  return config;
+}
+
+export function listSupportedProviders() {
+  return ['openai', 'claude', 'openrouter'];
+}

package/src/ai/run-fix-analysis.js

@@ -0,0 +1,174 @@
+import { buildBugfixPrompt } from './analyze-change.js';
+import { getAiProviderConfig } from './engine.js';
+
+function extractArgValue(args, name, fallback = null) {
+  const prefix = `${name}=`;
+  const direct = args.find(arg => arg.startsWith(prefix));
+  if (direct) return direct.slice(prefix.length);
+
+  const index = args.findIndex(arg => arg === name);
+  if (index >= 0 && args[index + 1]) return args[index + 1];
+
+  return fallback;
+}
+
+function getIssueFromArgs(args) {
+  const filtered = args.filter(arg => !arg.startsWith('--provider') && !arg.startsWith('--model') && arg !== 'fix' && arg !== '--ai');
+  return filtered.join(' ').trim();
+}
+
+function buildStructuredInstruction() {
+  return [
+    'Return valid JSON only.',
+    'Use exactly these keys:',
+    '{',
+    '  "root_cause_hypothesis": string,',
+    '  "impacted_areas": string[],',
+    '  "minimal_safe_delta": string,',
+    '  "regression_risks": string[],',
+    '  "validation_plan": string[]',
+    '}'
+  ].join('\n');
+}
+
+async function callOpenAI({ prompt, model, apiKey, baseUrl }) {
+  const response = await fetch(`${baseUrl}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({
+      model,
+      temperature: 0.2,
+      messages: [
+        { role: 'system', content: buildStructuredInstruction() },
+        { role: 'user', content: prompt }
+      ]
+    })
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`OpenAI request failed (${response.status}): ${text}`);
+  }
+
+  const data = await response.json();
+  return data.choices?.[0]?.message?.content ?? '';
+}
+
+async function callClaude({ prompt, model, apiKey, baseUrl }) {
+  const response = await fetch(`${baseUrl}/messages`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01'
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: 1200,
+      temperature: 0.2,
+      system: buildStructuredInstruction(),
+      messages: [
+        { role: 'user', content: prompt }
+      ]
+    })
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Claude request failed (${response.status}): ${text}`);
+  }
+
+  const data = await response.json();
+  return data.content?.[0]?.text ?? '';
+}
+
+async function callOpenRouter({ prompt, model, apiKey, baseUrl }) {
+  const response = await fetch(`${baseUrl}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+      'HTTP-Referer': 'https://github.com/pcoliveira90/pdd',
+      'X-Title': 'PDD CLI'
+    },
+    body: JSON.stringify({
+      model,
+      temperature: 0.2,
+      messages: [
+        { role: 'system', content: buildStructuredInstruction() },
+        { role: 'user', content: prompt }
+      ]
+    })
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`OpenRouter request failed (${response.status}): ${text}`);
+  }
+
+  const data = await response.json();
+  return data.choices?.[0]?.message?.content ?? '';
+}
+
+function resolveBaseUrl(providerConfig) {
+  const envValue = process.env[providerConfig.baseUrlEnv];
+  if (envValue) return envValue;
+
+  if (providerConfig.name === 'openai') return 'https://api.openai.com/v1';
+  if (providerConfig.name === 'claude') return 'https://api.anthropic.com/v1';
+  if (providerConfig.name === 'openrouter') return 'https://openrouter.ai/api/v1';
+
+  throw new Error(`Missing base URL for provider: ${providerConfig.name}`);
+}
+
+function parseJsonSafely(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {
+      raw_output: text
+    };
+  }
+}
+
+export async function runAiFixAnalysis(argv = process.argv.slice(2)) {
+  const provider = extractArgValue(argv, '--provider', 'openai');
+  const providerConfig = getAiProviderConfig(provider);
+  const model = extractArgValue(argv, '--model', providerConfig.defaultModel);
+  const issue = getIssueFromArgs(argv);
+
+  if (!issue) {
+    throw new Error('Missing issue description. Example: pdd fix --ai "login not saving incomeStatus"');
+  }
+
+  const apiKey = process.env[providerConfig.envKey];
+  if (!apiKey) {
+    throw new Error(`Missing API key. Set ${providerConfig.envKey}.`);
+  }
+
+  const baseUrl = resolveBaseUrl(providerConfig);
+  const prompt = buildBugfixPrompt({ issue });
+
+  let raw;
+  if (provider === 'openai') {
+    raw = await callOpenAI({ prompt, model, apiKey, baseUrl });
+  } else if (provider === 'claude') {
+    raw = await callClaude({ prompt, model, apiKey, baseUrl });
+  } else if (provider === 'openrouter') {
+    raw = await callOpenRouter({ prompt, model, apiKey, baseUrl });
+  } else {
+    throw new Error(`Unsupported provider: ${provider}`);
+  }
+
+  const parsed = parseJsonSafely(raw);
+
+  return {
+    provider,
+    model,
+    issue,
+    result: parsed
+  };
+}

package/src/cli/doctor-command.js

@@ -0,0 +1,101 @@
+import fs from 'fs';
+import path from 'path';
+import { PDD_TEMPLATE_VERSION } from '../core/template-registry.js';
+import { runDoctorFix } from './doctor-fix.js';
+import { buildDoctorRemediationPlan, printDoctorRemediationPlan } from '../core/remediation-advisor.js';
+
+function exists(baseDir, relativePath) {
+  return fs.existsSync(path.join(baseDir, relativePath));
+}
+
+function readVersion(baseDir) {
+  const file = path.join(baseDir, '.pdd/version.json');
+  if (!fs.existsSync(file)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8')).templateVersion;
+  } catch {
+    return null;
+  }
+}
+
+function print(label, ok, detail = '') {
+  const icon = ok ? '✅' : '⚠️';
+  console.log(`${icon} ${label}${detail ? ` — ${detail}` : ''}`);
+}
+
+export function runDoctor(baseDir = process.cwd(), argv = []) {
+  const shouldFix = argv.includes('--fix');
+
+  console.log('🩺 PDD Doctor\n');
+
+  const coreChecks = {
+    constitution: exists(baseDir, '.pdd/constitution.md'),
+    delta: exists(baseDir, '.pdd/templates/delta-spec.md'),
+    patch: exists(baseDir, '.pdd/templates/patch-plan.md'),
+    verification: exists(baseDir, '.pdd/templates/verification-report.md'),
+    memory: exists(baseDir, '.pdd/memory/system-map.md')
+  };
+
+  const adapters = {
+    claude: exists(baseDir, '.claude/commands/pdd.md'),
+    cursor: exists(baseDir, '.cursor/pdd.prompt.md'),
+    copilot: exists(baseDir, '.github/copilot/pdd.prompt.md')
+  };
+
+  const installedVersion = readVersion(baseDir);
+
+  // Raw checks
+  print('Core constitution', coreChecks.constitution);
+  print('Delta spec', coreChecks.delta);
+  print('Patch plan', coreChecks.patch);
+  print('Verification report', coreChecks.verification);
+  print('System map', coreChecks.memory);
+
+  console.log('');
+
+  print('Claude adapter', adapters.claude, adapters.claude ? 'installed' : 'missing');
+  print('Cursor adapter', adapters.cursor, adapters.cursor ? 'installed' : 'missing');
+  print('Copilot adapter', adapters.copilot, adapters.copilot ? 'installed' : 'missing');
+
+  console.log('');
+
+  if (!installedVersion) {
+    console.log('⚠️ No template version detected. Run `pdd init --here --force`.');
+  } else if (installedVersion !== PDD_TEMPLATE_VERSION) {
+    console.log(`⚠️ Templates outdated (${installedVersion} → ${PDD_TEMPLATE_VERSION})`);
+    console.log('👉 Run: pdd init --here --upgrade');
+  } else {
+    console.log('🎉 Templates up to date');
+  }
+
+  if (!adapters.claude && !adapters.cursor && !adapters.copilot) {
+    console.log('ℹ️ No IDE adapters installed');
+    console.log('👉 Run: pdd init --here --ide=claude (or cursor/copilot)');
+  }
+
+  // Guided remediation
+  const plan = buildDoctorRemediationPlan({
+    coreChecks,
+    adapters,
+    installedVersion,
+    currentVersion: PDD_TEMPLATE_VERSION
+  });
+
+  printDoctorRemediationPlan(plan);
+
+  if (shouldFix) {
+    console.log('');
+    const result = runDoctorFix(baseDir);
+
+    if (result.changed) {
+      console.log('🔧 Auto-repair applied:');
+      result.repaired.forEach(file => console.log(`- fixed: ${file}`));
+      if (result.installedVersion && result.installedVersion !== result.currentVersion) {
+        console.log(`ℹ️ Version updated: ${result.installedVersion} → ${result.currentVersion}`);
+      }
+    } else {
+      console.log('✅ No fixes needed');
+    }
+  }
+}

package/src/cli/doctor-fix.js

@@ -0,0 +1,51 @@
+import fs from 'fs';
+import path from 'path';
+import { CORE_TEMPLATES, PDD_TEMPLATE_VERSION } from '../core/template-registry.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 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 || null;
+  } catch {
+    return null;
+  }
+}
+
+function isCoreFile(relativePath) {
+  return relativePath.startsWith('.pdd/');
+}
+
+export function runDoctorFix(baseDir = process.cwd()) {
+  const installedVersion = readInstalledVersion(baseDir);
+  const repaired = [];
+
+  for (const [relativePath, content] of Object.entries(CORE_TEMPLATES)) {
+    const fullPath = path.join(baseDir, relativePath);
+    const missing = !fs.existsSync(fullPath);
+    const outdatedVersionFile = relativePath === '.pdd/version.json' && installedVersion !== PDD_TEMPLATE_VERSION;
+
+    if (isCoreFile(relativePath) && (missing || outdatedVersionFile)) {
+      writeFile(baseDir, relativePath, content);
+      repaired.push(relativePath);
+    }
+  }
+
+  return {
+    repaired,
+    installedVersion,
+    currentVersion: PDD_TEMPLATE_VERSION,
+    changed: repaired.length > 0
+  };
+}