popeye-cli 1.9.4 → 1.10.0

package/skills/RCA_PACKET_SCHEMA.md

@@ -0,0 +1,22 @@
+# RCA PACKET SCHEMA
+Purpose: Machine-verifiable root cause analysis artifact.
+
+Required Fields:
+
+- rca_id (UUID)
+- timestamp
+- incident_type
+- severity
+- reproduction_steps
+- affected_files[]
+- execution_trace
+- root_cause_statement
+- responsible_layer
+- origin_phase
+- governance_gap
+- recommended_fix_owner
+- requires_consensus (boolean)
+- requires_change_request (boolean)
+
+No vague root cause allowed.
+Must identify structural origin.

package/skills/RELEASE_MANAGER.md

@@ -0,0 +1,60 @@
+# Skill: RELEASE MANAGER
+Role Type: Production Readiness Authority
+Authority Level: Final Deployment Validator
+
+---
+
+## Objective
+
+Ensure system is ready for deployment and produce final release artifacts.
+
+---
+
+## Responsibilities
+
+- Validate Production Gate results
+- Generate Release Notes
+- Generate Deployment Instructions
+- Verify versioning
+- Verify changelog
+- Tag release version (conceptually)
+
+---
+
+## Required Inputs
+
+- Production Readiness Report
+- Audit Report
+- Repo Snapshot
+- Final Plan Packet
+
+---
+
+## Output
+
+# RELEASE PACKAGE
+
+## Version
+Semantic version increment
+
+## Included Features
+List from Master Plan
+
+## Known Risks
+Must be empty for PASS
+
+## Deployment Steps
+- Build commands
+- Env var setup
+- DB migration command
+- Start commands
+
+## Rollback Plan
+Clear rollback steps
+
+---
+
+## Definition of Done
+
+Release package stored under:
+`/docs/release/`

package/skills/REVIEWER.md

@@ -0,0 +1,133 @@
+# Skill: REVIEWER (PLAN CONSENSUS REVIEWER)
+Role Type: Independent Plan Auditor
+Authority Level: Gatekeeper for Consensus Approval
+
+---
+
+## Objective
+
+Review a proposed plan produced by Dispatcher/Popeye using an independent LLM perspective,
+detect gaps/hallucinations/shortcuts, and issue a structured vote that can be used for consensus.
+
+Reviewer is NOT an implementer.
+Reviewer is NOT a co-author (unless explicitly requested by Arbitrator to propose minimal corrections).
+Reviewer is an evidence-based plan auditor.
+
+---
+
+## Required Input: PLAN PACKET (Mandatory)
+
+Reviewer only operates on a "Plan Packet" containing:
+
+1) **Master Plan (approved version)**
+2) **Proposed Plan** (the artifact under review)
+3) **Repo Snapshot Summary** (what exists now)
+4) **Constraints** (tech stack, env, policies)
+5) **Constitution** (governing rules)
+6) **Acceptance Criteria / Definition of Done**
+
+If any component is missing → Reviewer must return **BLOCKED: Missing Inputs**.
+
+---
+
+## Primary Responsibilities
+
+- Validate alignment with the Master Plan and Constitution
+- Validate completeness: all scenarios, edge cases, and integration paths addressed
+- Validate feasibility: steps are implementable in the repo as it exists
+- Detect hallucinations: invented files, APIs, schema, env vars, services
+- Detect shortcuts: mocks, TODOs, “later” wiring, vague testing
+- Verify roles are correctly assigned and synchronized
+- Verify artifacts + phase gates are present (architecture, DB, QA, review)
+
+---
+
+## Non-Responsibilities
+
+- Does NOT implement
+- Does NOT rewrite the whole plan
+- Does NOT change scope without a Change Request
+- Does NOT relax consensus rules
+
+---
+
+## Review Method (Must Follow)
+
+1) **Coverage Scan**
+   - Does the plan cover 100% of Master Plan deliverables?
+   - Are all roles accounted for (Architect/DB/BE/FE/QA/etc.)?
+
+2) **Integration Scan**
+   - FE↔BE wiring explicit?
+   - DB↔BE wiring explicit?
+   - Auth, env vars, migrations, deployment accounted for?
+
+3) **Evidence Scan**
+   - Does it reference repo paths and existing modules accurately?
+   - Does it specify new files to be created deterministically?
+
+4) **Risk & Scenario Scan**
+   - Failure modes covered? (timeouts, validation errors, empty states, rate limits, migrations fail, etc.)
+   - “Same resolution” comparisons, backward compat, rollback?
+
+5) **Testability Scan**
+   - Are tests specified as executable steps? (not “write tests”)
+   - Are critical paths and integration tests listed?
+
+---
+
+## Output: REVIEW VOTE (Strict Format)
+
+Reviewer MUST output the following structure:
+
+### 1) Verdict
+- **APPROVE**
+- **APPROVE WITH MINOR CHANGES**
+- **REJECT**
+- **BLOCKED: MISSING INPUTS**
+
+### 2) Score (0–100)
+A numeric score representing confidence the plan can be executed without shortcuts/hallucinations.
+
+### 3) Blocking Issues (if any)
+Each blocking issue must include:
+- **ID**
+- **Problem**
+- **Why it violates Master Plan/Constitution**
+- **Exact fix requirement**
+- **Where it should be fixed (which artifact/role)**
+
+### 4) Non-Blocking Improvements
+Concrete improvements that strengthen the plan.
+
+### 5) Evidence & Consistency Notes
+List any suspected hallucinations or ambiguous references.
+
+### 6) Minimal Patch Suggestions (Optional)
+If "Approve with minor changes", provide minimal diffs / bullet edits.
+
+---
+
+## Automatic Rejection Triggers
+
+Return **REJECT** if any exist:
+
+- Implementation begins before architecture/DB/QA plans are gated
+- Any plan step relies on "mock", "placeholder", "TODO" without explicit approval
+- Unowned decisions (e.g. schema by BE, architecture by FE)
+- Missing end-to-end integration steps
+- Vague test plan (no named tests, no commands, no expected outcomes)
+- Invented repo state (files/routes/env vars that don’t exist)
+
+---
+
+## Definition of Done
+
+Reviewer is done when:
+- A valid structured vote is returned
+- Issues are categorized as blocking vs non-blocking
+- Fix directives are precise enough for Dispatcher/Arbitrator to act on
+
+---
+
+End of Skill.

package/skills/SOCIAL_EXPERT.md

@@ -0,0 +1,22 @@
+# Skill: SOCIAL EXPERT
+Role Type: Distribution Strategist
+
+---
+
+## Objective
+
+Translate product and marketing strategy into platform-native content.
+
+---
+
+## Responsibilities
+
+- Platform strategy
+- Content formats
+- Community guidelines alignment
+- Engagement loops
+
+---
+
+Definition of Done:
+Distribution plan aligned with marketing strategy.

package/skills/UI_UX_SPECIALIST.md

@@ -0,0 +1,22 @@
+# Skill: UI/UX SPECIALIST
+Role Type: Experience Authority
+
+---
+
+## Objective
+
+Ensure usability, clarity, accessibility, and design coherence.
+
+---
+
+## Responsibilities
+
+- UX flows
+- Design system alignment
+- Accessibility review
+- Interaction validation
+
+---
+
+Anti-Shortcut:
+No cosmetic-only review — must evaluate usability.

package/skills/WEBSITE_PROGRAMMER.md

@@ -0,0 +1,37 @@
+# Skill: WEBSITE PROGRAMMER
+Role Type: Marketing Site Implementer
+
+---
+
+## Objective
+
+Implement production-grade website aligned with:
+
+- Brand
+- Product positioning
+- Architecture (if integrated)
+- Marketing strategy
+
+---
+
+## Responsibilities
+
+- Landing pages
+- Pricing pages
+- Documentation pages
+- SEO structure
+- Analytics integration
+
+---
+
+## Anti-Shortcut Rules
+
+- No generic template text
+- No placeholder copy
+- No mismatched branding
+- No default theme if brand colors defined
+
+---
+
+Definition of Done:
+Website reflects actual product capabilities and branding.

package/src/cli/commands/debug-context.ts

@@ -0,0 +1,265 @@
+/**
+ * Debug context helpers
+ * Deterministic functions for error analysis and smart file selection.
+ * Pure functions, easily testable.
+ */
+
+import path from 'node:path';
+
+/**
+ * Entry in the lightweight file index (paths + metadata, no content).
+ */
+export interface FileIndexEntry {
+  relativePath: string;
+  size: number;
+  mtime: number;
+  isConfig: boolean;
+}
+
+/** Config file patterns that are always considered relevant */
+const CONFIG_PATTERNS = [
+  'package.json', 'package-lock.json', 'tsconfig.json', 'vite.config',
+  'pyproject.toml', 'requirements.txt', 'Pipfile',
+  'docker-compose.yml', 'docker-compose.yaml', 'Dockerfile',
+  '.env.example', '.env.local', 'alembic.ini',
+  'next.config', 'tailwind.config', 'postcss.config',
+  'jest.config', 'vitest.config', 'pytest.ini', 'setup.cfg',
+];
+
+/**
+ * Check if a file path matches a config pattern.
+ *
+ * @param filePath - Relative path to check.
+ * @returns True if the file is a known config file.
+ */
+export function isConfigFile(filePath: string): boolean {
+  const basename = path.basename(filePath);
+  return CONFIG_PATTERNS.some((p) => basename.startsWith(p));
+}
+
+/**
+ * Extract file paths mentioned in stack traces.
+ * Supports Python tracebacks, TypeScript/JS errors, and generic path patterns.
+ *
+ * @param text - Error text or stack trace.
+ * @returns Deduplicated array of file paths found in the text.
+ */
+export function extractPathsFromError(text: string): string[] {
+  const paths = new Set<string>();
+
+  // Python traceback: File "/app/src/module/file.py", line 42
+  const pyPattern = /File "([^"]+\.py[cw]?)", line \d+/g;
+  for (const match of text.matchAll(pyPattern)) {
+    paths.add(normalizePath(match[1]));
+  }
+
+  // TS/JS errors: src/components/App.tsx(15,3) or src/components/App.tsx:15:3
+  const tsPattern = /([a-zA-Z0-9_./\\-]+\.(?:ts|tsx|js|jsx|mjs|cjs))[\s:(]/g;
+  for (const match of text.matchAll(tsPattern)) {
+    paths.add(normalizePath(match[1]));
+  }
+
+  // Docker / generic paths: /app/src/..., ./src/...
+  const genericPattern = /(?:\/app\/|\.\/)((?:src|app|lib|tests?|config)\/[a-zA-Z0-9_./-]+\.\w+)/g;
+  for (const match of text.matchAll(genericPattern)) {
+    paths.add(normalizePath(match[1]));
+  }
+
+  // Module not found patterns: Cannot find module './foo/bar'
+  const modulePattern = /Cannot find module ['"]([^'"]+)['"]/g;
+  for (const match of text.matchAll(modulePattern)) {
+    const mod = match[1];
+    if (mod.startsWith('.') || mod.startsWith('/')) {
+      paths.add(normalizePath(mod));
+    }
+  }
+
+  // ModuleNotFoundError: No module named 'src.foo.bar'
+  const pyModulePattern = /No module named ['"]([^'"]+)['"]/g;
+  for (const match of text.matchAll(pyModulePattern)) {
+    const dotPath = match[1].replace(/\./g, '/');
+    paths.add(dotPath);
+  }
+
+  return Array.from(paths);
+}
+
+/** Tech keyword map: keyword -> tags */
+const TECH_KEYWORDS: Record<string, string[]> = {
+  'alembic': ['alembic', 'database', 'migration'],
+  'sqlalchemy': ['sqlalchemy', 'database', 'orm'],
+  'prisma': ['prisma', 'database', 'orm'],
+  'docker': ['docker', 'container'],
+  'docker-compose': ['docker', 'container', 'compose'],
+  'vite': ['vite', 'bundler', 'frontend'],
+  'webpack': ['webpack', 'bundler', 'frontend'],
+  'next': ['nextjs', 'react', 'frontend'],
+  'fastapi': ['fastapi', 'backend', 'python'],
+  'flask': ['flask', 'backend', 'python'],
+  'express': ['express', 'backend', 'node'],
+  'postgres': ['postgres', 'database'],
+  'redis': ['redis', 'cache'],
+  'tailwind': ['tailwind', 'css', 'frontend'],
+  'pytest': ['pytest', 'testing', 'python'],
+  'jest': ['jest', 'testing', 'node'],
+  'vitest': ['vitest', 'testing', 'node'],
+  'nginx': ['nginx', 'proxy'],
+  'cors': ['cors', 'api'],
+  'migration': ['migration', 'database'],
+  'celery': ['celery', 'queue', 'python'],
+};
+
+/**
+ * Detect framework/tech keywords from error text.
+ *
+ * @param text - Error text or stack trace.
+ * @returns Object with deduplicated tags array.
+ */
+export function detectTechFromError(text: string): { tags: string[] } {
+  const tags = new Set<string>();
+  const lower = text.toLowerCase();
+
+  for (const [keyword, keywordTags] of Object.entries(TECH_KEYWORDS)) {
+    if (lower.includes(keyword)) {
+      for (const tag of keywordTags) {
+        tags.add(tag);
+      }
+    }
+  }
+
+  return { tags: Array.from(tags) };
+}
+
+/**
+ * Select relevant files from the project index based on error paths and tech tags.
+ * Returns file paths sorted by relevance (direct matches first, then config, then nearby).
+ *
+ * @param fileIndex - Lightweight file index.
+ * @param errorPaths - Paths extracted from the error.
+ * @param tags - Tech tags detected from the error.
+ * @returns Array of relative paths to load.
+ */
+export function selectRelevantFiles(
+  fileIndex: FileIndexEntry[],
+  errorPaths: string[],
+  tags: string[]
+): string[] {
+  if (fileIndex.length === 0) return [];
+
+  const selected = new Set<string>();
+  const MAX_FILES = 15;
+
+  // 1. Direct matches: files mentioned in the error
+  for (const errorPath of errorPaths) {
+    for (const entry of fileIndex) {
+      if (
+        entry.relativePath.endsWith(errorPath) ||
+        entry.relativePath === errorPath ||
+        entry.relativePath.includes(errorPath)
+      ) {
+        selected.add(entry.relativePath);
+      }
+    }
+  }
+
+  // 2. Sibling files: files in the same directory as matches
+  const matchedDirs = new Set<string>();
+  for (const sel of selected) {
+    matchedDirs.add(path.dirname(sel));
+  }
+  for (const dir of matchedDirs) {
+    for (const entry of fileIndex) {
+      if (path.dirname(entry.relativePath) === dir && selected.size < MAX_FILES) {
+        selected.add(entry.relativePath);
+      }
+    }
+  }
+
+  // 3. Tag-based: config files related to detected tech
+  if (tags.includes('database') || tags.includes('migration')) {
+    for (const entry of fileIndex) {
+      if (
+        entry.relativePath.includes('alembic') ||
+        entry.relativePath.includes('migration') ||
+        entry.relativePath.includes('prisma') ||
+        entry.relativePath.includes('schema.sql')
+      ) {
+        if (selected.size < MAX_FILES) selected.add(entry.relativePath);
+      }
+    }
+  }
+  if (tags.includes('docker') || tags.includes('compose')) {
+    for (const entry of fileIndex) {
+      if (
+        entry.relativePath.includes('docker') ||
+        entry.relativePath.includes('Dockerfile')
+      ) {
+        if (selected.size < MAX_FILES) selected.add(entry.relativePath);
+      }
+    }
+  }
+
+  // 4. Fallback: always include config files if we have few matches
+  if (selected.size < 5) {
+    for (const entry of fileIndex) {
+      if (entry.isConfig && selected.size < MAX_FILES) {
+        selected.add(entry.relativePath);
+      }
+    }
+  }
+
+  return Array.from(selected).slice(0, MAX_FILES);
+}
+
+/** Image file extensions that Claude can read via the Read tool */
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg']);
+
+/**
+ * Extract image/screenshot file paths from user input text.
+ * Detects both quoted and unquoted absolute/relative paths ending in image extensions.
+ *
+ * @param text - User input text.
+ * @returns Array of image file paths found in the text.
+ */
+export function extractImagePaths(text: string): string[] {
+  const paths = new Set<string>();
+
+  // Quoted paths: '/path/to/image.png' or "/path/to/image.png"
+  const quotedPattern = /['"]([^'"]+\.(?:png|jpg|jpeg|gif|webp|bmp|svg))['"]/gi;
+  for (const match of text.matchAll(quotedPattern)) {
+    paths.add(match[1]);
+  }
+
+  // Unquoted absolute paths: /path/to/image.png (no spaces allowed in unquoted)
+  const absolutePattern = /(\/[^\s'"]+\.(?:png|jpg|jpeg|gif|webp|bmp|svg))/gi;
+  for (const match of text.matchAll(absolutePattern)) {
+    paths.add(match[1]);
+  }
+
+  return Array.from(paths);
+}
+
+/**
+ * Check if a file path points to an image file.
+ *
+ * @param filePath - File path to check.
+ * @returns True if the file has an image extension.
+ */
+export function isImageFile(filePath: string): boolean {
+  const ext = path.extname(filePath).toLowerCase();
+  return IMAGE_EXTENSIONS.has(ext);
+}
+
+/**
+ * Normalize a file path by stripping common prefixes (/app/, ./, etc.).
+ *
+ * @param p - Raw file path from error text.
+ * @returns Normalized relative path.
+ */
+function normalizePath(p: string): string {
+  let normalized = p.replace(/\\/g, '/');
+  // Strip common container prefixes
+  normalized = normalized.replace(/^\/app\//, '');
+  normalized = normalized.replace(/^\.\//, '');
+  return normalized;
+}

package/src/cli/commands/debug-prompts.ts

@@ -0,0 +1,91 @@
+/**
+ * Debug session prompts
+ * System prompt with strict output contract and conversation history formatting.
+ */
+
+/**
+ * Message in the debug conversation history.
+ */
+export interface DebugMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * Build the system prompt for the debug session.
+ *
+ * @returns The system prompt instructing Claude on debug response format.
+ */
+export function getDebugSystemPrompt(): string {
+  return `You are an expert debugger embedded in the Popeye CLI. Your role is to diagnose
+errors in projects generated by Popeye (full-stack apps, backends, frontends, websites).
+
+You have access to the project's file system through your tools. When the user pastes an error,
+diagnose it using the project context provided and the files you can read.
+
+## Response Format
+
+You MUST structure every response with these sections:
+
+### Diagnosis
+Explain what is wrong and why it is happening. Be specific -- reference exact module names,
+configuration keys, or missing dependencies.
+
+### Evidence
+List the specific files and lines that confirm your diagnosis. Use the format:
+- \`path/to/file.ts:42\` -- description of what you found
+
+### Proposed Fix
+Provide the exact changes needed. Show file paths and the code to add, modify, or remove.
+Use diff-style formatting when helpful:
+\`\`\`diff
+- old line
++ new line
+\`\`\`
+
+### Commands to Verify
+List shell commands the user should run to confirm the fix works. For example:
+\`\`\`bash
+docker-compose up --build
+npm run dev
+pytest tests/ -v
+\`\`\`
+
+### Ready to Apply?
+End with a short note reminding the user they can type \`/fix\` in the debug session
+to have Popeye apply the proposed changes automatically.
+
+## Screenshots and Images
+- Users may paste file paths to screenshots or images (e.g., \`/path/to/Screenshot.png\`).
+- When you see an image path in the user's message, use the **Read** tool to view it.
+  The Read tool supports PNG, JPG, GIF, WebP, and other image formats.
+- After viewing the screenshot, analyze what it shows (UI bugs, missing elements, error dialogs,
+  browser console errors, terminal output, etc.) and include your visual findings in the Diagnosis.
+- If the image path is invalid or unreadable, tell the user and ask them to verify the path.
+
+## Rules
+- Never guess. If you need more context, ask the user or read additional files.
+- Reference actual file paths from the project, not hypothetical ones.
+- When multiple issues exist, address the root cause first.
+- Keep explanations concise -- developers are your audience.
+- If the error is outside the project (e.g., a system-level issue), say so clearly.`;
+}
+
+/**
+ * Format conversation history for inclusion in the prompt.
+ *
+ * @param history - Array of debug messages.
+ * @returns Formatted string of conversation history.
+ */
+export function formatConversationHistory(history: DebugMessage[]): string {
+  if (history.length === 0) return '';
+
+  const lines: string[] = ['## Previous Conversation'];
+
+  for (const msg of history) {
+    const role = msg.role === 'user' ? 'User' : 'Assistant';
+    lines.push(`\n**${role}:**\n${msg.content}`);
+  }
+
+  return lines.join('\n');
+}