@bicorne/task-flow 0.1.0

package/assets/product-requirement.md

@@ -0,0 +1,82 @@
+# 产品需求文档
+
+## 文档基础信息（Meta Data）
+
+| 字段 | 内容 |
+|------|------|
+| 项目名称 | <!-- 项目名称 --> |
+| 版本 | v1.0.0 |
+| 创建日期 | <!-- YYYY-MM-DD --> |
+| 作者 | <!-- 作者 --> |
+| 文档状态 | 草稿 |
+| 评审人 | <!-- 评审人列表 --> |
+
+## 项目背景与目标（Why）
+
+### 背景
+<!-- 描述项目背景和动机，当前存在的问题或痛点 -->
+
+### 目标
+<!-- 描述项目要达成的核心目标，可量化指标优先 -->
+
+### 范围
+<!-- 明确项目包含和不包含的内容 -->
+
+## 用户与场景（Who and When）
+
+### 目标用户
+<!-- 描述目标用户群体及其特征 -->
+
+### 用户场景
+<!-- 描述典型使用场景和用户旅程 -->
+
+### 用户故事
+<!-- 以"作为[用户]，我希望[功能]，以便[价值]"格式描述 -->
+
+## 全局设计与架构（How）
+
+### 整体架构
+<!-- 描述系统整体架构设计 -->
+
+### 核心流程
+<!-- 描述核心业务流程 -->
+
+### 约束条件
+<!-- 技术、业务或时间约束 -->
+
+## 详细功能需求（What）
+
+### 功能清单
+<!-- 以表格或列表形式列出所有功能需求 -->
+
+| 编号 | 功能名称 | 优先级 | 描述 | 验收标准 |
+|------|----------|--------|------|----------|
+| F-001 | <!-- 功能 --> | P0 | <!-- 描述 --> | <!-- 标准 --> |
+
+### 功能详细说明
+<!-- 对每个功能进行详细说明 -->
+
+## 非功能性需求
+
+### 性能需求
+<!-- 响应时间、吞吐量、并发用户数等 -->
+
+### 安全需求
+<!-- 认证、授权、数据加密、审计等 -->
+
+### 可用性需求
+<!-- SLA、容灾、降级策略等 -->
+
+### 兼容性需求
+<!-- 浏览器、操作系统、设备兼容性 -->
+
+## 上线与运营计划
+
+### 上线计划
+<!-- 上线步骤、灰度策略、回滚方案 -->
+
+### 监控与告警
+<!-- 关键指标监控、告警阈值 -->
+
+### 运营计划
+<!-- 数据埋点、A/B 测试、迭代计划 -->

package/assets/schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Task File Schema",
+  "description": "Task file format for task-flow PHASE-*.json files",
+  "type": "object",
+  "required": ["id", "type", "title", "priority", "phase", "status", "spec"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^PHASE-[0-9]+-[0-9]+-[0-9]+$",
+      "description": "Task ID in format PHASE-{phase}-{subphase}-{sequence}"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["feat", "fix", "refactor", "test", "docs"],
+      "description": "Task type"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Task title"
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["high", "medium", "low"],
+      "description": "Task priority"
+    },
+    "phase": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Phase number"
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^PHASE-[0-9]+-[0-9]+-[0-9]+$"
+      },
+      "default": [],
+      "description": "List of task IDs this task depends on"
+    },
+    "docs_to_read": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Documents AI must read before implementing"
+    },
+    "spec": {
+      "type": "object",
+      "required": ["description", "files"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Detailed task description"
+        },
+        "files": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1,
+          "description": "Files related to this task"
+        },
+        "context": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Context documents"
+        }
+      },
+      "additionalProperties": true
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Acceptance criteria for task completion"
+    },
+    "implementation": {
+      "type": "object",
+      "properties": {
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["step"],
+            "properties": {
+              "step": { "type": "string" },
+              "details": { "type": "string" }
+            },
+            "additionalProperties": false
+          },
+          "default": []
+        },
+        "notes": {
+          "type": "string",
+          "default": ""
+        }
+      },
+      "additionalProperties": true
+    },
+    "validation": {
+      "type": "object",
+      "properties": {
+        "commands": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Commands to validate task completion"
+        },
+        "manual_checks": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Manual checks for task completion"
+        }
+      },
+      "additionalProperties": true
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "in_progress", "completed", "blocked"],
+      "default": "pending",
+      "description": "Task status"
+    }
+  },
+  "additionalProperties": true
+}

package/assets/tasks.md

@@ -0,0 +1,26 @@
+# 任务清单
+
+## 概述
+<!-- 任务概述 -->
+
+## 任务列表
+
+### Phase 1: 基础实现
+
+- [ ] Task 1.1: 任务标题
+  - 描述：任务描述
+  - 文件：src/file1.ts, src/file2.ts
+  - 验收：验收标准
+
+### Phase 2: 扩展功能
+
+- [ ] Task 2.1: 任务标题
+  - 描述：任务描述
+  - 文件：src/file3.ts
+  - 验收：验收标准
+
+---
+
+## 任务依赖关系
+
+- Task 2.1 依赖 Task 1.1

package/dist/commands/analyze.d.ts

@@ -0,0 +1,32 @@
+/**
+ * commands/analyze.ts
+ * 扫描宿主项目基本信息，生成 AI context JSON 的骨架
+ *
+ * AI 可以在此基础上补充自己的理解（analysis、task 等字段），
+ * 然后通过 --context-file 传给 extract/design 命令。
+ *
+ * 用法:
+ *   task-flow analyze --output context.json
+ */
+import { AiContext } from '../types/ai-context';
+export interface AnalyzeOptions {
+    cwd?: string;
+    output?: string;
+}
+export interface AnalyzeResult {
+    success: boolean;
+    reason?: string;
+    message?: string;
+    context?: AiContext;
+    outputPath?: string;
+}
+/**
+ * Analyze project and generate context JSON
+ */
+export declare function analyzeProject(options?: AnalyzeOptions): AnalyzeResult;
+export declare function main(): void;
+declare const _default: {
+    analyzeProject: typeof analyzeProject;
+    main: typeof main;
+};
+export default _default;

package/dist/commands/analyze.js

@@ -0,0 +1,338 @@
+"use strict";
+/**
+ * commands/analyze.ts
+ * 扫描宿主项目基本信息，生成 AI context JSON 的骨架
+ *
+ * AI 可以在此基础上补充自己的理解（analysis、task 等字段），
+ * 然后通过 --context-file 传给 extract/design 命令。
+ *
+ * 用法:
+ *   task-flow analyze --output context.json
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeProject = analyzeProject;
+exports.main = main;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../lib/config");
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 2; i < argv.length; i += 1) {
+        const token = argv[i] || '';
+        if (!token.startsWith('--')) {
+            continue;
+        }
+        const key = token.slice(2);
+        const next = argv[i + 1] || '';
+        if (!next || next.startsWith('--')) {
+            args[key] = true;
+            continue;
+        }
+        args[key] = next;
+        i += 1;
+    }
+    return args;
+}
+/**
+ * Read and parse package.json if it exists
+ */
+function readPackageJson(projectRoot) {
+    const pkgPath = path.resolve(projectRoot, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+        return null;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require(pkgPath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read tsconfig.json if it exists
+ */
+function readTsconfig(projectRoot) {
+    const tsconfigPath = path.resolve(projectRoot, 'tsconfig.json');
+    if (!fs.existsSync(tsconfigPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(tsconfigPath, 'utf8');
+        // Strip comments for basic parsing
+        const stripped = content.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+        return JSON.parse(stripped);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scan top-level directory structure
+ */
+function scanDirectoryStructure(projectRoot) {
+    const entries = fs.readdirSync(projectRoot, { withFileTypes: true });
+    const summary = [];
+    const knownDirs = {
+        src: '源代码目录',
+        lib: '库代码目录',
+        packages: 'Monorepo 包目录',
+        apps: '应用目录',
+        test: '测试目录',
+        tests: '测试目录',
+        __tests__: '测试目录',
+        docs: '文档目录',
+        scripts: '脚本目录',
+        config: '配置目录',
+        public: '静态资源目录',
+        assets: '资源目录',
+    };
+    for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith('.') && !entry.name.startsWith('node_modules')) {
+            const dirPath = path.resolve(projectRoot, entry.name);
+            const purpose = knownDirs[entry.name] || '项目目录';
+            let fileCount;
+            try {
+                fileCount = fs.readdirSync(dirPath, { recursive: true }).filter((p) => typeof p === 'string' && !p.startsWith('.') && fs.statSync(path.resolve(dirPath, p)).isFile()).length;
+            }
+            catch {
+                // Ignore permission errors
+            }
+            summary.push({ path: entry.name, purpose, fileCount });
+        }
+    }
+    return summary;
+}
+/**
+ * Detect project type from structure and package.json
+ */
+function detectProjectType(pkg, structure) {
+    if (pkg) {
+        const isMonorepo = pkg.workspaces !== undefined
+            || (pkg.pnpm !== undefined && typeof pkg.pnpm === 'object')
+            || structure.some((s) => s.path === 'packages' || s.path === 'apps');
+        if (isMonorepo) {
+            return 'monorepo';
+        }
+        const hasBin = pkg.bin !== undefined;
+        if (hasBin) {
+            return 'cli';
+        }
+        const mainType = typeof pkg.main === 'string' ? pkg.main : '';
+        if (mainType.includes('.mjs') || mainType.includes('.cjs')) {
+            return 'library';
+        }
+    }
+    if (structure.some((s) => s.path === 'src') && structure.some((s) => s.path === 'public')) {
+        return 'application';
+    }
+    return 'application';
+}
+/**
+ * Infer tech stack from package.json and tsconfig
+ */
+function inferTechStack(pkg, tsconfig) {
+    const techStack = {};
+    if (tsconfig) {
+        techStack.language = 'TypeScript';
+    }
+    if (pkg) {
+        const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+        const depNames = Object.keys(deps);
+        // Runtime
+        if (depNames.some((d) => d.includes('next'))) {
+            techStack.runtime = 'Next.js';
+        }
+        else if (depNames.some((d) => d.includes('express'))) {
+            techStack.runtime = 'Express';
+        }
+        else if (depNames.some((d) => d.includes('fastify'))) {
+            techStack.runtime = 'Fastify';
+        }
+        else if (depNames.some((d) => d.includes('react'))) {
+            techStack.runtime = 'React';
+        }
+        else if (depNames.some((d) => d.includes('vue'))) {
+            techStack.runtime = 'Vue';
+        }
+        // Framework
+        if (depNames.includes('next')) {
+            techStack.framework = 'Next.js';
+        }
+        else if (depNames.includes('express')) {
+            techStack.framework = 'Express';
+        }
+        else if (depNames.includes('fastify')) {
+            techStack.framework = 'Fastify';
+        }
+        else if (depNames.includes('react')) {
+            techStack.framework = 'React';
+        }
+        else if (depNames.includes('vue')) {
+            techStack.framework = 'Vue';
+        }
+        // Build tool
+        if (depNames.includes('typescript') || depNames.includes('ts-node')) {
+            techStack.buildTool = 'tsc';
+        }
+        if (depNames.includes('vite')) {
+            techStack.buildTool = 'vite';
+        }
+        if (depNames.includes('webpack')) {
+            techStack.buildTool = 'webpack';
+        }
+        if (depNames.includes('esbuild')) {
+            techStack.buildTool = 'esbuild';
+        }
+        if (depNames.includes('turbo')) {
+            techStack.buildTool = 'turbo';
+        }
+        // Test framework
+        if (depNames.includes('vitest')) {
+            techStack.testFramework = 'vitest';
+        }
+        else if (depNames.includes('jest')) {
+            techStack.testFramework = 'jest';
+        }
+        else if (depNames.includes('mocha')) {
+            techStack.testFramework = 'mocha';
+        }
+        // Lint
+        if (depNames.includes('eslint')) {
+            techStack.lintTool = 'eslint';
+        }
+        else if (depNames.includes('biome')) {
+            techStack.lintTool = 'biome';
+        }
+        if (depNames.includes('prettier')) {
+            techStack.lintTool = (techStack.lintTool || '') + ' + prettier';
+        }
+    }
+    return techStack;
+}
+/**
+ * Infer dependencies info
+ */
+function inferDependencies(pkg) {
+    const result = {};
+    if (!pkg) {
+        return result;
+    }
+    const deps = pkg.dependencies || {};
+    const devDeps = pkg.devDependencies || {};
+    result.core = Object.keys(deps).slice(0, 10);
+    result.dev = Object.keys(devDeps).slice(0, 10);
+    return result;
+}
+/**
+ * Analyze project and generate context JSON
+ */
+function analyzeProject(options = {}) {
+    const config = (0, config_1.loadConfig)({ cwd: options.cwd });
+    const projectRoot = config.projectRoot || process.cwd();
+    const pkg = readPackageJson(projectRoot);
+    const tsconfig = readTsconfig(projectRoot);
+    const structure = scanDirectoryStructure(projectRoot);
+    const projectName = String(pkg?.name || path.basename(projectRoot));
+    const description = String(pkg?.description || '');
+    const projectType = detectProjectType(pkg, structure);
+    const techStack = inferTechStack(pkg, tsconfig);
+    const dependencies = inferDependencies(pkg);
+    const context = {
+        version: '1.0',
+        project: {
+            name: projectName,
+            description: description || undefined,
+            type: projectType,
+            techStack,
+            structure,
+            keyFiles: ['package.json', ...(tsconfig ? ['tsconfig.json'] : [])],
+            dependencies,
+        },
+    };
+    // Write to output file if specified
+    if (options.output) {
+        const outputPath = path.resolve(process.cwd(), options.output);
+        try {
+            fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+            fs.writeFileSync(outputPath, JSON.stringify(context, null, 2), 'utf8');
+            return {
+                success: true,
+                context,
+                outputPath,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                success: false,
+                reason: 'file-write-error',
+                message: `Failed to write context file: ${errorMessage}`,
+            };
+        }
+    }
+    // Print to stdout
+    return {
+        success: true,
+        context,
+    };
+}
+function main() {
+    const args = parseArgs(process.argv);
+    const result = analyzeProject({
+        cwd: args.cwd,
+        output: args.output,
+    });
+    if (!result.success) {
+        console.error(`[ANALYZE] ${result.message}`);
+        process.exit(1);
+    }
+    if (result.outputPath) {
+        console.log(`[ANALYZE] Project context saved to: ${result.outputPath}`);
+    }
+    else {
+        // Output JSON to stdout
+        process.stdout.write(JSON.stringify(result.context, null, 2));
+    }
+    process.exit(0);
+}
+if (require.main === module) {
+    main();
+}
+exports.default = {
+    analyzeProject,
+    main,
+};

package/dist/commands/archive.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * commands/archive.ts
+ * Archive current task state
+ */
+import { archiveTaskState } from '../lib/archive';
+export declare function main(): void;
+declare const _default: {
+    archiveTaskState: typeof archiveTaskState;
+};
+export default _default;

package/dist/commands/archive.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * commands/archive.ts
+ * Archive current task state
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const archive_1 = require("../lib/archive");
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 2; i < argv.length; i += 1) {
+        const token = argv[i] || '';
+        if (!token.startsWith('--')) {
+            continue;
+        }
+        const key = token.slice(2);
+        const next = argv[i + 1] || '';
+        if (!next || next.startsWith('--')) {
+            args[key] = true;
+            continue;
+        }
+        args[key] = next;
+        i += 1;
+    }
+    return args;
+}
+function main() {
+    const args = parseArgs(process.argv);
+    const result = (0, archive_1.archiveTaskState)({
+        cwd: args.cwd,
+        taskId: args['task-id'],
+        eventType: args.event,
+        status: args.status,
+        phase: args.phase,
+        phaseCompleted: args['phase-completed'],
+        reviewConclusion: args['review-conclusion'],
+        reason: args.reason,
+        completedAt: args['completed-at'],
+    });
+    if ('skipped' in result && result.skipped) {
+        console.log(`[ARCHIVE] skipped: ${result.reason}`);
+        process.exit(0);
+    }
+    console.log(`[ARCHIVE] updated: ${result.archivePath}`);
+    process.exit(0);
+}
+if (require.main === module) {
+    main();
+}
+exports.default = {
+    archiveTaskState: archive_1.archiveTaskState,
+};