@jojonax/codex-copilot 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonas Qin
+
+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.md

@@ -0,0 +1,127 @@
+# Codex-Copilot 🤖
+
+**PRD-driven automated development orchestrator for CodeX / Cursor**
+
+Turn your PRD into working code — automatically. Codex-Copilot reads your product requirement docs, breaks them into tasks, drives CodeX/Cursor to develop each feature, submits PRs, waits for AI code review, fixes issues, and merges — all in a loop.
+
+```
+PRD → Tasks → CodeX Dev → PR → AI Review → Fix → Merge → Next Task
+```
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g codex-copilot
+
+# Or run directly without installing
+npx codex-copilot
+
+# In your project directory:
+codex-copilot init    # Detect PRD, generate task queue
+codex-copilot run     # Start the automated dev loop
+```
+
+## How It Works
+
+### 1. `codex-copilot init`
+
+- 🔍 **Auto-detects PRD** files in your project (by filename, size, content keywords)
+- 📋 Generates a task decomposition prompt for CodeX
+- 🗂️ Creates `.codex-copilot/` with config, state, and instructions
+
+### 2. Execute the PRD prompt in CodeX
+
+- Paste the generated prompt into CodeX desktop (or use CodeX CLI if available)
+- CodeX breaks down your PRD into ordered, independent tasks → `tasks.json`
+
+### 3. `codex-copilot run`
+
+Loops through each task in 4 phases:
+
+| Phase | What Happens |
+|-------|-------------|
+| **1. Develop** | Creates feature branch, generates dev prompt, copies to clipboard |
+| **2. PR** | Auto commits, pushes, creates GitHub PR via `gh` CLI |
+| **3. Review** | Polls for AI review (Gemini Code Assist), collects feedback |
+| **4. Merge** | Squash merges after approval, moves to next task |
+
+### Other Commands
+
+```bash
+codex-copilot status   # Progress bar + task list
+codex-copilot reset    # Reset and start over
+```
+
+## Prerequisites
+
+| Tool | Install |
+|------|---------|
+| Node.js ≥ 18 | `brew install node` |
+| GitHub CLI | `brew install gh && gh auth login` |
+| [Gemini Code Assist](https://github.com/marketplace/gemini-code-assist) | Install on your GitHub repo |
+| CodeX Desktop / Cursor | Official installer |
+
+## Features
+
+- **🔍 Smart PRD Detection** — scans project dirs, scores candidates by filename pattern + content analysis
+- **🔄 Breakpoint Resume** — `state.json` persists progress; interrupted runs continue from last task
+- **📋 Clipboard Integration** — auto-copies prompts to clipboard (macOS `pbcopy`)
+- **🤖 Dual Mode** — full-auto with CodeX CLI, or manual clipboard mode for desktop app
+- **🔁 Review Loop** — max 2 rounds of AI review + fix, with human override options
+- **⚙️ Configurable** — edit `.codex-copilot/config.json` for timeouts, branch names, review rounds
+
+## Configuration
+
+After `init`, edit `.codex-copilot/config.json`:
+
+```json
+{
+  "base_branch": "main",
+  "max_review_rounds": 2,
+  "review_poll_interval": 60,
+  "review_wait_timeout": 600
+}
+```
+
+## Project Structure
+
+```
+.codex-copilot/           # Created in your project
+├── config.json           # Settings
+├── state.json            # Run state (auto-managed)
+├── tasks.json            # Task queue (CodeX-generated)
+├── codex-instructions.md # CodeX system prompt
+└── _current_prompt.md    # Current prompt (auto-copied to clipboard)
+```
+
+## How the Review Loop Works
+
+```
+CodeX develops feature
+        ↓
+   Push + Create PR
+        ↓
+   Wait for AI Review (Gemini Code Assist)
+        ↓
+  ┌─ APPROVED → Merge → Next Task
+  └─ CHANGES_REQUESTED → Collect feedback
+        ↓
+   Generate fix prompt → CodeX fixes
+        ↓
+   Push → Wait for re-review
+        ↓
+   (max 2 rounds, then human decides)
+```
+
+## Roadmap
+
+- [ ] Support for more AI review tools (CodeRabbit, GitHub Copilot Review)
+- [ ] Built-in task decomposition (no manual CodeX step)
+- [ ] Web dashboard for monitoring multiple projects
+- [ ] GitHub Action for fully server-side automation
+- [ ] Support for monorepo / multi-package projects
+
+## License
+
+MIT © Jonas Qin

package/bin/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+/**
+ * codex-copilot CLI - PRD → 自动开发 → PR → Review → 修复 → 合并
+ * 
+ * 用法:
+ *   codex-copilot init          # 初始化项目（自动检测 PRD，生成任务）
+ *   codex-copilot run           # 启动自动化开发循环
+ *   codex-copilot status        # 查看当前进度
+ *   codex-copilot reset         # 重置状态（重新开始）
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { existsSync } from 'fs';
+
+import { init } from '../src/commands/init.js';
+import { run } from '../src/commands/run.js';
+import { status } from '../src/commands/status.js';
+import { reset } from '../src/commands/reset.js';
+import { log } from '../src/utils/logger.js';
+
+const command = process.argv[2];
+const projectDir = process.cwd();
+
+// Banner
+console.log('');
+console.log('  ╔══════════════════════════════════════════╗');
+console.log('  ║     🤖  Codex-Copilot  v1.0              ║');
+console.log('  ║     PRD-Driven Auto Development          ║');
+console.log('  ╚══════════════════════════════════════════╝');
+console.log('');
+
+async function main() {
+  try {
+    switch (command) {
+      case 'init':
+        await init(projectDir);
+        break;
+
+      case 'run':
+        if (!existsSync(resolve(projectDir, '.codex-copilot/tasks.json'))) {
+          log.error('尚未初始化，请先运行: codex-copilot init');
+          process.exit(1);
+        }
+        await run(projectDir);
+        break;
+
+      case 'status':
+        if (!existsSync(resolve(projectDir, '.codex-copilot/tasks.json'))) {
+          log.error('尚未初始化，请先运行: codex-copilot init');
+          process.exit(1);
+        }
+        await status(projectDir);
+        break;
+
+      case 'reset':
+        await reset(projectDir);
+        break;
+
+      default:
+        console.log('  用法: codex-copilot <command>');
+        console.log('');
+        console.log('  命令:');
+        console.log('    init      初始化项目（自动检测 PRD，生成任务队列）');
+        console.log('    run       启动自动化开发循环');
+        console.log('    status    查看当前任务进度');
+        console.log('    reset     重置状态，重新开始');
+        console.log('');
+        console.log('  工作流程:');
+        console.log('    1. cd 到你的项目目录');
+        console.log('    2. codex-copilot init    (自动检测 PRD 并拆解任务)');
+        console.log('    3. codex-copilot run     (开始自动开发循环)');
+        console.log('');
+        break;
+    }
+  } catch (err) {
+    log.error(`执行失败: ${err.message}`);
+    if (process.env.DEBUG) console.error(err);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@jojonax/codex-copilot",
+  "version": "1.0.0",
+  "description": "PRD-driven automated development orchestrator for CodeX / Cursor",
+  "bin": {
+    "codex-copilot": "./bin/cli.js"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "codex",
+    "cursor",
+    "ai",
+    "automation",
+    "prd",
+    "code-review",
+    "github",
+    "developer-tools",
+    "cli"
+  ],
+  "author": "Jonas Qin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonasqin/codex-copilot.git"
+  },
+  "homepage": "https://github.com/jonasqin/codex-copilot#readme",
+  "bugs": {
+    "url": "https://github.com/jonasqin/codex-copilot/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,257 @@
+/**
+ * codex-copilot init - 初始化项目
+ * 
+ * 1. 自动检测 PRD 文档
+ * 2. 让用户确认/选择 PRD
+ * 3. 生成 CodeX 可执行的任务拆解 Prompt
+ * 4. 创建 .codex-copilot/ 目录结构
+ */
+
+import { mkdirSync, writeFileSync, readFileSync, existsSync, copyFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+import { detectPRD, readPRD } from '../utils/detect-prd.js';
+import { log } from '../utils/logger.js';
+import { ask, confirm, select, closePrompt } from '../utils/prompt.js';
+import { git } from '../utils/git.js';
+import { github } from '../utils/github.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function init(projectDir) {
+  log.title('📋 初始化 Codex-Copilot');
+  log.blank();
+
+  // ===== 前置检查 =====
+  log.step('检查环境...');
+
+  // 检查是否在 git 仓库中
+  try {
+    git.currentBranch(projectDir);
+    log.info('Git 仓库 ✓');
+  } catch {
+    log.error('当前目录不是 Git 仓库，请先 git init');
+    closePrompt();
+    process.exit(1);
+  }
+
+  // 检查 gh CLI
+  if (!github.checkGhAuth()) {
+    log.error('GitHub CLI 未登录，请先运行: gh auth login');
+    closePrompt();
+    process.exit(1);
+  }
+  log.info('GitHub CLI ✓');
+
+  // 检查 GitHub remote
+  try {
+    const repo = git.getRepoInfo(projectDir);
+    log.info(`GitHub 仓库: ${repo.owner}/${repo.repo} ✓`);
+  } catch (err) {
+    log.error(err.message);
+    closePrompt();
+    process.exit(1);
+  }
+
+  log.blank();
+
+  // ===== 检测 PRD =====
+  log.step('扫描 PRD 文档...');
+  const candidates = detectPRD(projectDir);
+
+  let prdPath;
+
+  if (candidates.length === 0) {
+    log.warn('未自动检测到 PRD 文档');
+    const manualPath = await ask('请输入 PRD 文件路径（相对或绝对路径）:');
+    prdPath = resolve(projectDir, manualPath);
+    if (!existsSync(prdPath)) {
+      log.error(`文件不存在: ${prdPath}`);
+      closePrompt();
+      process.exit(1);
+    }
+  } else if (candidates.length === 1) {
+    prdPath = candidates[0].path;
+    log.info(`找到 PRD: ${candidates[0].relativePath}`);
+    const ok = await confirm('使用该文件？');
+    if (!ok) {
+      const manualPath = await ask('请输入 PRD 文件路径:');
+      prdPath = resolve(projectDir, manualPath);
+    }
+  } else {
+    log.info(`找到 ${candidates.length} 个候选 PRD 文件:`);
+    const choice = await select('请选择要使用的 PRD:', candidates.map(c => ({
+      label: `${c.relativePath} (匹配度: ${c.score})`,
+      value: c.path,
+    })));
+    prdPath = choice.value;
+  }
+
+  log.info(`使用 PRD: ${prdPath}`);
+  log.blank();
+
+  // ===== 读取 PRD =====
+  const prdContent = readPRD(prdPath);
+  log.info(`PRD 大小: ${(prdContent.length / 1024).toFixed(1)} KB`);
+
+  // ===== 创建 .codex-copilot 目录 =====
+  log.step('创建 .codex-copilot/ 目录...');
+  const copilotDir = resolve(projectDir, '.codex-copilot');
+  mkdirSync(copilotDir, { recursive: true });
+
+  // 写入配置文件
+  const config = {
+    prd_path: prdPath,
+    base_branch: git.currentBranch(projectDir) || 'main',
+    max_review_rounds: 2,
+    review_poll_interval: 60,
+    review_wait_timeout: 600,
+    created_at: new Date().toISOString(),
+  };
+  writeFileSync(resolve(copilotDir, 'config.json'), JSON.stringify(config, null, 2));
+
+  // 写入初始状态
+  const state = {
+    current_task: 0,
+    current_pr: null,
+    review_round: 0,
+    status: 'initialized',
+  };
+  writeFileSync(resolve(copilotDir, 'state.json'), JSON.stringify(state, null, 2));
+
+  // 写入 CodeX 指令模板
+  const instructions = `# Codex-Copilot 开发指令
+
+## 角色
+你是一个高效的自动开发 Agent，负责按照任务描述完成功能开发。
+
+## 规则
+1. **严格遵循项目技术栈**：使用项目已有的框架、工具和代码风格
+2. **自测优先**：开发完成前确保代码可以编译/运行
+3. **Git 规范**：提交信息格式 \`feat(task-N): 简要描述\` 或 \`fix(task-N): 简要描述\`
+4. **不要修改无关文件**：只修改当前任务需要的文件
+5. **完成后执行 git commit**：\`git add -A && git commit -m "..."\`
+
+## 修复 Review 时的规则
+1. 逐条阅读 Review 意见
+2. 区分必须修复 vs 建议性意见
+3. 对于不认同的意见，在 commit message 中说明原因
+4. 修复后确保不引入新问题
+`;
+  writeFileSync(resolve(copilotDir, 'codex-instructions.md'), instructions);
+
+  // 添加 .gitignore 项
+  const gitignorePath = resolve(projectDir, '.gitignore');
+  const gitignoreEntry = '\n# Codex-Copilot state\n.codex-copilot/state.json\n';
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, 'utf-8');
+    if (!content.includes('.codex-copilot/state.json')) {
+      writeFileSync(gitignorePath, content + gitignoreEntry);
+    }
+  }
+
+  log.info('.codex-copilot/ 目录已创建');
+  log.blank();
+
+  // ===== 生成任务拆解 Prompt =====
+  log.step('生成任务拆解 Prompt...');
+
+  const parsePrompt = buildParsePrompt(prdContent, copilotDir);
+  const promptPath = resolve(copilotDir, 'parse-prd-prompt.md');
+  writeFileSync(promptPath, parsePrompt);
+
+  log.info(`任务拆解 Prompt 已保存到: .codex-copilot/parse-prd-prompt.md`);
+  log.blank();
+
+  // ===== 提示用户下一步 =====
+  log.title('✅ 初始化完成！');
+  log.blank();
+  log.info('接下来请执行以下步骤：');
+  log.blank();
+  console.log('  ┌───────────────────────────────────────────────────┐');
+  console.log('  │  1. 打开 CodeX 桌面版                              │');
+  console.log('  │  2. 将以下文件内容粘贴给 CodeX 执行：               │');
+  console.log('  │     .codex-copilot/parse-prd-prompt.md             │');
+  console.log('  │  3. CodeX 会生成 .codex-copilot/tasks.json         │');
+  console.log('  │  4. 确认任务列表后运行:                             │');
+  console.log('  │     codex-copilot run                              │');
+  console.log('  └───────────────────────────────────────────────────┘');
+  log.blank();
+
+  // 询问是否尝试自动拆解（如果 codex CLI 可用）
+  const hasCodexCLI = checkCodexCLI();
+  if (hasCodexCLI) {
+    log.info('检测到 CodeX CLI 可用！');
+    const autoparse = await confirm('是否自动调用 CodeX 拆解 PRD？');
+    if (autoparse) {
+      log.step('调用 CodeX CLI 拆解 PRD...');
+      try {
+        const { execSync } = await import('child_process');
+        execSync(`codex -q "${parsePrompt.slice(0, 2000)}"`, {
+          cwd: projectDir,
+          stdio: 'inherit',
+        });
+        log.info('CodeX 拆解完成！');
+      } catch {
+        log.warn('CodeX CLI 调用失败，请手动执行');
+      }
+    }
+  }
+
+  closePrompt();
+}
+
+function checkCodexCLI() {
+  try {
+    execSync('which codex', { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildParsePrompt(prdContent, copilotDir) {
+  return `请阅读以下 PRD 文档，将其拆解为独立的开发任务。
+
+## 要求
+1. 每个任务在一个 PR 中可以完成（粒度适中，不要太大也不要太碎）
+2. 有明确的验收标准
+3. 按依赖关系排序（被依赖的任务排在前面）
+4. 第一个任务通常是"项目初始化 / 基础框架搭建"
+
+## 输出格式
+将结果输出到 \`.codex-copilot/tasks.json\`，格式如下：
+
+\`\`\`json
+{
+  "project": "项目名称",
+  "total": 5,
+  "tasks": [
+    {
+      "id": 1,
+      "title": "任务标题（简短）",
+      "description": "详细的任务描述，包含需要实现的具体功能和技术细节",
+      "acceptance": ["验收条件1", "验收条件2"],
+      "branch": "feature/001-task-slug",
+      "status": "pending",
+      "depends_on": []
+    },
+    {
+      "id": 2,
+      "title": "...",
+      "description": "...",
+      "acceptance": ["..."],
+      "branch": "feature/002-task-slug",
+      "status": "pending",
+      "depends_on": [1]
+    }
+  ]
+}
+\`\`\`
+
+## PRD 文档内容
+
+${prdContent}
+`;
+}

package/src/commands/reset.js

@@ -0,0 +1,52 @@
+/**
+ * codex-copilot reset - 重置状态
+ */
+
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { log } from '../utils/logger.js';
+import { confirm, closePrompt } from '../utils/prompt.js';
+
+export async function reset(projectDir) {
+  const statePath = resolve(projectDir, '.codex-copilot/state.json');
+  const tasksPath = resolve(projectDir, '.codex-copilot/tasks.json');
+
+  if (!existsSync(statePath)) {
+    log.warn('项目未初始化，无需重置');
+    closePrompt();
+    return;
+  }
+
+  log.title('🔄 重置 Codex-Copilot 状态');
+  log.blank();
+
+  const resetTasks = await confirm('是否同时重置任务状态 (所有任务标记为 pending)？', false);
+
+  // 重置 state
+  const state = {
+    current_task: 0,
+    current_pr: null,
+    review_round: 0,
+    status: 'initialized',
+  };
+  writeFileSync(statePath, JSON.stringify(state, null, 2));
+  log.info('执行状态已重置');
+
+  // 重置任务状态
+  if (resetTasks && existsSync(tasksPath)) {
+    const tasks = JSON.parse(readFileSync(tasksPath, 'utf-8'));
+    for (const task of tasks.tasks) {
+      task.status = 'pending';
+    }
+    writeFileSync(tasksPath, JSON.stringify(tasks, null, 2));
+    log.info('任务状态已重置');
+  }
+
+  // 清理临时文件
+  const promptPath = resolve(projectDir, '.codex-copilot/_current_prompt.md');
+  if (existsSync(promptPath)) unlinkSync(promptPath);
+
+  log.blank();
+  log.info('✅ 重置完成，可以重新运行 codex-copilot run');
+  closePrompt();
+}