popeye-cli 1.2.1 → 1.4.0

package/src/upgrade/transitions.ts

@@ -0,0 +1,80 @@
+/**
+ * Project type upgrade transitions
+ * Defines valid upgrade paths between project types
+ */
+
+import { languageToApps } from '../types/project.js';
+import type { OutputLanguage, AppType } from '../types/project.js';
+
+/**
+ * Details of a project type transition
+ */
+export interface UpgradeTransition {
+  from: OutputLanguage;
+  to: OutputLanguage;
+  /** New apps that will be generated */
+  newApps: AppType[];
+  /** Whether existing code needs to be moved into apps/ directory */
+  requiresRestructure: boolean;
+  /** Description of what the upgrade does */
+  description: string;
+}
+
+/**
+ * Get valid upgrade targets for a given language
+ *
+ * @param from - Current project language
+ * @returns Array of valid target languages
+ */
+export function getValidUpgradeTargets(from: OutputLanguage): OutputLanguage[] {
+  const targets: Record<OutputLanguage, OutputLanguage[]> = {
+    python: ['fullstack', 'all'],
+    typescript: ['fullstack', 'all'],
+    fullstack: ['all'],
+    website: ['all'],
+    all: [],
+  };
+  return targets[from];
+}
+
+/**
+ * Get detailed transition information for an upgrade
+ *
+ * @param from - Current project language
+ * @param to - Target project language
+ * @returns Transition details or null if invalid
+ */
+export function getTransitionDetails(
+  from: OutputLanguage,
+  to: OutputLanguage,
+): UpgradeTransition | null {
+  const validTargets = getValidUpgradeTargets(from);
+  if (!validTargets.includes(to)) {
+    return null;
+  }
+
+  const currentApps = new Set(languageToApps(from));
+  const targetApps = languageToApps(to);
+  const newApps = targetApps.filter((app) => !currentApps.has(app));
+
+  // Single-app types need restructuring into apps/ monorepo layout
+  const singleAppTypes: OutputLanguage[] = ['python', 'typescript', 'website'];
+  const requiresRestructure = singleAppTypes.includes(from);
+
+  const descriptions: Record<string, string> = {
+    'python->fullstack': 'Add frontend app, move backend to apps/backend/',
+    'python->all': 'Add frontend + website, move backend to apps/backend/',
+    'typescript->fullstack': 'Add backend app, move frontend to apps/frontend/',
+    'typescript->all': 'Add backend + website, move frontend to apps/frontend/',
+    'fullstack->all': 'Add website app to existing workspace',
+    'website->all': 'Add frontend + backend, move website to apps/website/',
+  };
+
+  return {
+    from,
+    to,
+    newApps,
+    requiresRestructure,
+    description: descriptions[`${from}->${to}`] || `Upgrade from ${from} to ${to}`,
+  };
+}

package/src/workflow/consensus.ts

@@ -14,6 +14,7 @@ import type {
   AppConsensusScores,
   CorrectionRecord,
 } from '../types/consensus.js';
+import type { OutputLanguage } from '../types/project.js';
 import { DEFAULT_CONSENSUS_CONFIG } from '../types/consensus.js';
 import { requestConsensus as requestOpenAIConsensus } from '../adapters/openai.js';
 import { requestConsensus as requestGeminiConsensus, requestArbitration as requestGeminiArbitration } from '../adapters/gemini.js';
@@ -36,7 +37,7 @@ export interface ConsensusOptions {
   /** Whether this is a fullstack project (enables per-app tracking) */
   isFullstack?: boolean;
   /** Project language for revision prompts */
-  language?: 'python' | 'typescript' | 'fullstack';
+  language?: OutputLanguage;
   onIteration?: (iteration: number, result: ConsensusResult) => void;
   onRevision?: (iteration: number, revisedPlan: string) => void;
   onConcerns?: (concerns: string[], recommendations: string[]) => void;
@@ -947,7 +948,7 @@ export async function runOptimizedConsensusProcess(
   } = options;
 
   // Derive language from isFullstack for revision prompts
-  const language: 'python' | 'typescript' | 'fullstack' = isFullstack ? 'fullstack' : 'python';
+  const language: OutputLanguage = isFullstack ? 'fullstack' : 'python';
 
   const {
     threshold = DEFAULT_CONSENSUS_CONFIG.threshold,

package/src/workflow/index.ts

@@ -41,6 +41,14 @@ export * from './ui-designer.js';
 export * from './ui-verification.js';
 export * from './project-verification.js';
 export * from './auto-fix.js';
+// Note: plan-parser.js exports are accessible but have naming conflicts with plan-mode.js
+// Import directly from './plan-parser.js' if you need the extended TaskAppTag type (includes 'WEB')
+export * from './separation-guard.js';
+export * from './seo-tests.js';
+export * from './task-workflow.js';
+export * from './milestone-workflow.js';
+export * from './plan-storage.js';
+export * from './workspace-manager.js';
 
 /**
  * Workflow options

package/src/workflow/plan-mode.ts

@@ -5,7 +5,8 @@
 
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import type { ProjectSpec } from '../types/project.js';
+import { isWorkspace } from '../types/project.js';
+import type { ProjectSpec, OutputLanguage } from '../types/project.js';
 import type { ProjectState, Milestone, Task } from '../types/workflow.js';
 import type { ConsensusConfig } from '../types/consensus.js';
 import { expandIdea as openaiExpandIdea } from '../adapters/openai.js';
@@ -52,7 +53,7 @@ export interface PlanModeResult {
  */
 export async function expandIdea(
   idea: string,
-  language: 'python' | 'typescript' | 'fullstack',
+  language: OutputLanguage,
   onProgress?: (message: string) => void
 ): Promise<string> {
   onProgress?.('Expanding idea into specification...');
@@ -75,7 +76,7 @@ export async function expandIdea(
 export async function createPlan(
   specification: string,
   context: string = '',
-  language: 'python' | 'typescript' | 'fullstack' = 'python',
+  language: OutputLanguage = 'python',
   onProgress?: (message: string) => void
 ): Promise<string> {
   onProgress?.('Creating development plan...');
@@ -103,12 +104,45 @@ export async function getProjectContext(
 ): Promise<string> {
   onProgress?.('Analyzing existing codebase...');
 
-  // Check if directory has any code
+  // Check if directory has any code - check root AND apps/ subdirectories
   try {
-    const files = await fs.readdir(projectDir);
-    const hasCode = files.some((f) =>
-      ['.py', '.ts', '.js', '.tsx', '.jsx'].some((ext) => f.endsWith(ext))
-    );
+    const codeExtensions = ['.py', '.ts', '.js', '.tsx', '.jsx'];
+    const hasCodeInDir = async (dir: string): Promise<boolean> => {
+      try {
+        const files = await fs.readdir(dir);
+        return files.some((f) => codeExtensions.some((ext) => f.endsWith(ext)));
+      } catch {
+        return false;
+      }
+    };
+
+    let hasCode = await hasCodeInDir(projectDir);
+
+    // Also check apps/ subdirectories for monorepo/workspace projects
+    if (!hasCode) {
+      const appsDir = path.join(projectDir, 'apps');
+      try {
+        const appEntries = await fs.readdir(appsDir, { withFileTypes: true });
+        for (const entry of appEntries) {
+          if (entry.isDirectory()) {
+            const appHasCode = await hasCodeInDir(path.join(appsDir, entry.name));
+            if (appHasCode) {
+              hasCode = true;
+              break;
+            }
+            // Check one level deeper (apps/frontend/src/)
+            const srcDir = path.join(appsDir, entry.name, 'src');
+            const srcHasCode = await hasCodeInDir(srcDir);
+            if (srcHasCode) {
+              hasCode = true;
+              break;
+            }
+          }
+        }
+      } catch {
+        // No apps/ directory
+      }
+    }
 
     if (!hasCode) {
       onProgress?.('No existing code found');
@@ -927,7 +961,7 @@ export async function runPlanMode(
       });
 
       // Validate fullstack plan structure
-      if (spec.language === 'fullstack') {
+      if (isWorkspace(spec.language)) {
         onProgress?.('create-plan', 'Validating fullstack plan structure...');
         const validation = validateFullstackPlan(plan);
 
@@ -958,7 +992,7 @@ export async function runPlanMode(
       {
         projectDir,
         config: consensusConfig,
-        isFullstack: spec.language === 'fullstack',
+        isFullstack: isWorkspace(spec.language),
         language: spec.language,
         onIteration: (iteration, result) => {
           onProgress?.(

package/src/workflow/plan-parser.ts

@@ -0,0 +1,317 @@
+/**
+ * Plan parsing utilities for task tagging and validation
+ * Parses [FE], [BE], [WEB], [INT] tags from plan content
+ */
+
+import type { OutputLanguage } from '../types/project.js';
+
+/**
+ * Task app tags for workspace projects
+ */
+export type TaskAppTag = 'FE' | 'BE' | 'WEB' | 'INT';
+
+/**
+ * App target derived from task tag
+ */
+export type AppTarget = 'frontend' | 'backend' | 'website' | 'unified';
+
+/**
+ * Parsed task with app context
+ */
+export interface ParsedTask {
+  name: string;
+  description?: string;
+  appTag?: TaskAppTag;
+  appTarget?: AppTarget;
+  files?: string[];
+  dependencies?: string[];
+  acceptanceCriteria?: string[];
+}
+
+/**
+ * Parse task tag from task name
+ *
+ * @param taskName - Task name potentially containing [FE], [BE], [WEB], [INT]
+ * @returns The parsed tag or undefined
+ */
+export function parseTaskTag(taskName: string): TaskAppTag | undefined {
+  const tagMatch = taskName.match(/\[(FE|BE|WEB|INT)\]/i);
+  if (tagMatch) {
+    return tagMatch[1].toUpperCase() as TaskAppTag;
+  }
+  return undefined;
+}
+
+/**
+ * Convert task tag to app target
+ *
+ * @param tag - The task tag
+ * @returns The app target
+ */
+export function tagToAppTarget(tag: TaskAppTag): AppTarget {
+  const mapping: Record<TaskAppTag, AppTarget> = {
+    FE: 'frontend',
+    BE: 'backend',
+    WEB: 'website',
+    INT: 'unified',
+  };
+  return mapping[tag];
+}
+
+/**
+ * Validation issues for a task
+ */
+export interface TaskValidationResult {
+  valid: boolean;
+  issues: string[];
+}
+
+/**
+ * Validate a task has proper app targeting for workspace projects
+ *
+ * @param task - The parsed task
+ * @param hasWebsite - Whether the project includes a website app
+ * @returns Validation result with issues
+ */
+export function validateWorkspaceTask(
+  task: ParsedTask,
+  hasWebsite: boolean = false
+): TaskValidationResult {
+  const issues: string[] = [];
+
+  const validTags = hasWebsite
+    ? '[FE], [BE], [WEB], or [INT]'
+    : '[FE], [BE], or [INT]';
+
+  if (!task.appTag) {
+    issues.push(`Task "${task.name}" missing ${validTags} tag`);
+  }
+
+  // Validate consistency between tag and appTarget
+  if (task.appTag && task.appTarget) {
+    const expectedTarget = tagToAppTarget(task.appTag);
+    if (task.appTarget !== expectedTarget) {
+      issues.push(
+        `Task "${task.name}" has [${task.appTag}] tag but App: is "${task.appTarget}" (expected "${expectedTarget}")`
+      );
+    }
+  }
+
+  // Validate file paths match app
+  if (task.files && task.appTag) {
+    const pathValidation: Record<TaskAppTag, { pattern: RegExp; expected: string }> = {
+      FE: { pattern: /\/frontend\//, expected: 'apps/frontend/' },
+      BE: { pattern: /\/backend\//, expected: 'apps/backend/' },
+      WEB: { pattern: /\/website\//, expected: 'apps/website/' },
+      INT: { pattern: /.*/, expected: 'any (unified)' },
+    };
+
+    const { pattern, expected } = pathValidation[task.appTag];
+
+    // Only validate FE/BE/WEB, not INT
+    if (task.appTag !== 'INT') {
+      const invalidFiles = task.files.filter((f) => !pattern.test(f));
+      if (invalidFiles.length > 0) {
+        issues.push(
+          `[${task.appTag}] task has files outside ${expected}: ${invalidFiles.join(', ')}`
+        );
+      }
+    }
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+  };
+}
+
+/**
+ * Parse a task block from plan content
+ *
+ * @param taskBlock - The raw task block text
+ * @returns Parsed task
+ */
+export function parseTaskBlock(taskBlock: string): ParsedTask {
+  const lines = taskBlock.split('\n');
+
+  // Extract task name from first line (### Task X.X [TAG]: Name)
+  const titleMatch = lines[0].match(/#{1,4}\s*(?:Task\s+\d+(?:\.\d+)?)?[:\s]*(.+)/i);
+  const name = titleMatch ? titleMatch[1].trim() : lines[0].trim();
+
+  const task: ParsedTask = {
+    name,
+    appTag: parseTaskTag(name),
+  };
+
+  // Parse App field
+  const appMatch = taskBlock.match(/\*\*App\*\*:\s*(\w+)/i);
+  if (appMatch) {
+    task.appTarget = appMatch[1].toLowerCase() as AppTarget;
+  } else if (task.appTag) {
+    // Derive from tag if App field not found
+    task.appTarget = tagToAppTarget(task.appTag);
+  }
+
+  // Parse Files field
+  const filesMatch = taskBlock.match(/\*\*Files\*\*:([\s\S]*?)(?=\*\*|$)/i);
+  if (filesMatch) {
+    const filesContent = filesMatch[1];
+    const fileMatches = filesContent.match(/`([^`]+)`/g);
+    if (fileMatches) {
+      task.files = fileMatches.map((f) => f.replace(/`/g, ''));
+    }
+  }
+
+  // Parse Dependencies
+  const depsMatch = taskBlock.match(/\*\*Dependencies\*\*:\s*(.+)/i);
+  if (depsMatch && depsMatch[1].trim().toLowerCase() !== 'none') {
+    task.dependencies = depsMatch[1]
+      .split(',')
+      .map((d) => d.trim())
+      .filter((d) => d);
+  }
+
+  // Parse Acceptance Criteria
+  const criteriaMatch = taskBlock.match(/\*\*Acceptance Criteria\*\*:([\s\S]*?)(?=###|##|$)/i);
+  if (criteriaMatch) {
+    const criteriaContent = criteriaMatch[1];
+    const criteriaItems = criteriaContent.match(/[-*[\]]\s*(.+)/g);
+    if (criteriaItems) {
+      task.acceptanceCriteria = criteriaItems.map((c) =>
+        c.replace(/^[-*[\]x\s]+/i, '').trim()
+      );
+    }
+  }
+
+  return task;
+}
+
+/**
+ * Extract all tasks from a plan
+ *
+ * @param planContent - The full plan markdown content
+ * @returns Array of parsed tasks
+ */
+export function extractTasksFromPlan(planContent: string): ParsedTask[] {
+  const tasks: ParsedTask[] = [];
+
+  // Match task blocks (### Task X.X or #### Task X.X)
+  const taskBlockRegex = /#{3,4}\s*(?:Task\s+)?[\d.]+[^#]*?(?=#{2,4}|$)/gi;
+  const matches = planContent.matchAll(taskBlockRegex);
+
+  for (const match of matches) {
+    if (match[0].trim()) {
+      tasks.push(parseTaskBlock(match[0]));
+    }
+  }
+
+  return tasks;
+}
+
+/**
+ * Validate all tasks in a plan for workspace projects
+ *
+ * @param planContent - The full plan markdown content
+ * @param language - The project language
+ * @returns Validation results
+ */
+export function validatePlanTasks(
+  planContent: string,
+  language: OutputLanguage
+): {
+  valid: boolean;
+  tasks: ParsedTask[];
+  issues: string[];
+  warnings: string[];
+} {
+  const isWorkspaceProject = ['fullstack', 'website', 'all'].includes(language);
+  const hasWebsite = ['website', 'all'].includes(language);
+
+  const tasks = extractTasksFromPlan(planContent);
+  const issues: string[] = [];
+  const warnings: string[] = [];
+
+  if (!isWorkspaceProject) {
+    // Non-workspace projects don't require tagging
+    return {
+      valid: true,
+      tasks,
+      issues: [],
+      warnings: [],
+    };
+  }
+
+  // Validate each task
+  for (const task of tasks) {
+    const validation = validateWorkspaceTask(task, hasWebsite);
+    if (!validation.valid) {
+      // For now, treat as warnings rather than hard errors
+      warnings.push(...validation.issues);
+    }
+  }
+
+  // Check for minimum coverage
+  if (language === 'fullstack' || language === 'all') {
+    const feTasks = tasks.filter((t) => t.appTag === 'FE');
+    const beTasks = tasks.filter((t) => t.appTag === 'BE');
+    const intTasks = tasks.filter((t) => t.appTag === 'INT');
+
+    if (feTasks.length === 0) {
+      warnings.push('No [FE] frontend tasks found in plan');
+    }
+    if (beTasks.length === 0) {
+      warnings.push('No [BE] backend tasks found in plan');
+    }
+    if (intTasks.length === 0) {
+      warnings.push('No [INT] integration tasks found in plan');
+    }
+  }
+
+  if (language === 'all') {
+    const webTasks = tasks.filter((t) => t.appTag === 'WEB');
+    if (webTasks.length === 0) {
+      warnings.push('No [WEB] website tasks found in plan');
+    }
+  }
+
+  return {
+    valid: issues.length === 0,
+    tasks,
+    issues,
+    warnings,
+  };
+}
+
+/**
+ * Get app-specific tasks from a parsed plan
+ *
+ * @param tasks - Array of parsed tasks
+ * @param appTarget - The app target to filter by
+ * @returns Filtered tasks
+ */
+export function getTasksByApp(tasks: ParsedTask[], appTarget: AppTarget): ParsedTask[] {
+  return tasks.filter((t) => t.appTarget === appTarget);
+}
+
+/**
+ * Get task counts by app from a parsed plan
+ *
+ * @param tasks - Array of parsed tasks
+ * @returns Count of tasks per app
+ */
+export function getTaskCountsByApp(tasks: ParsedTask[]): Record<AppTarget, number> {
+  const counts: Record<AppTarget, number> = {
+    frontend: 0,
+    backend: 0,
+    website: 0,
+    unified: 0,
+  };
+
+  for (const task of tasks) {
+    if (task.appTarget) {
+      counts[task.appTarget]++;
+    }
+  }
+
+  return counts;
+}