@bicorne/task-flow 0.1.0

package/dist/spec/sync-task-to-openspec.js

@@ -0,0 +1,288 @@
+"use strict";
+/**
+ * sync-task-to-openspec.ts
+ * Sync task execution status back to Spec
+ */
+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.syncTaskToSpec = syncTaskToSpec;
+exports.main = main;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../lib/config");
+const state_1 = require("../lib/state");
+/**
+ * Validate that a resolved path is within the project root (prevent path traversal)
+ * @param resolvedPath - The resolved absolute path
+ * @param projectRoot - The project root directory
+ * @returns True if path is within project root
+ */
+function isPathWithinProject(resolvedPath, projectRoot) {
+    const relativePath = path.relative(projectRoot, resolvedPath);
+    return !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+}
+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 ensurePosix(p) {
+    return String(p || '').replace(/\\/g, '/');
+}
+function readJsonIfExists(filePath) {
+    if (!filePath || !fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function readTextIfExists(filePath) {
+    if (!filePath || !fs.existsSync(filePath)) {
+        return '';
+    }
+    return fs.readFileSync(filePath, 'utf8');
+}
+function getTaskFilePath(config, taskId) {
+    return path.resolve(config.tasksDirAbs, `${taskId}.json`);
+}
+function readTaskJson(config, taskId) {
+    const taskPath = getTaskFilePath(config, taskId);
+    if (!fs.existsSync(taskPath)) {
+        return null;
+    }
+    return readJsonIfExists(taskPath);
+}
+function normalizeSnapshotValidations(snapshot) {
+    const results = Array.isArray(snapshot?.validationResults) ? snapshot.validationResults : [];
+    return results.map((item) => ({
+        name: item?.name || '',
+        status: item?.status || 'unknown',
+        detail: item?.detail || null,
+    }));
+}
+function toExecutionStatus(state) {
+    if (state?.status === 'completed') {
+        return 'completed';
+    }
+    if (state?.lastGateBlockedReason) {
+        return 'blocked';
+    }
+    return state?.status || 'running';
+}
+function resolveReviewPath(config, taskJson) {
+    const report = taskJson?.metadata?.outputs?.report;
+    if (!report) {
+        return null;
+    }
+    return path.resolve(config.projectRoot, report);
+}
+function resolveSnapshotPath(config, state, taskJson) {
+    if (state?.currentSnapshot) {
+        return path.resolve(config.projectRoot, state.currentSnapshot);
+    }
+    const snapshot = taskJson?.metadata?.outputs?.snapshot;
+    if (!snapshot) {
+        return null;
+    }
+    return path.resolve(config.projectRoot, snapshot);
+}
+function parseReviewConclusion(content) {
+    const patterns = [
+        { regex: /^\s*(?:结论 |Conclusion)\s*:\s*PASS\b/m, result: 'PASS' },
+        { regex: /^\s*(?:结论 |Conclusion)\s*:\s*NEEDS_WORK\b/m, result: 'NEEDS_WORK' },
+        { regex: /^\s*(?:结论 |Conclusion)\s*:\s*FAIL\b/m, result: 'FAIL' },
+        { regex: /^##\s*结论\s*:\s*PASS\b/m, result: 'PASS' },
+        { regex: /^##\s*结论\s*:\s*NEEDS_WORK\b/m, result: 'NEEDS_WORK' },
+        { regex: /^##\s*结论\s*:\s*FAIL\b/m, result: 'FAIL' },
+        { regex: /^#\s*PASS\b/m, result: 'PASS' },
+        { regex: /^#\s*NEEDS_WORK\b/m, result: 'NEEDS_WORK' },
+        { regex: /^#\s*FAIL\b/m, result: 'FAIL' },
+        { regex: /\*\*结论\*\*\s*:\s*PASS\b/, result: 'PASS' },
+        { regex: /\*\*结论\*\*\s*:\s*NEEDS_WORK\b/, result: 'NEEDS_WORK' },
+        { regex: /\*\*结论\*\*\s*:\s*FAIL\b/, result: 'FAIL' },
+        { regex: /\*\*PASS\*\*/, result: 'PASS' },
+        { regex: /\*\*NEEDS_WORK\*\*/, result: 'NEEDS_WORK' },
+        { regex: /\*\*FAIL\*\*/, result: 'FAIL' },
+    ];
+    for (const { regex, result } of patterns) {
+        const match = content.match(regex);
+        if (match) {
+            return result;
+        }
+    }
+    return null;
+}
+function buildExecutionDocument(params) {
+    const { config, taskJson, state, taskId, spec } = params;
+    const snapshotPath = resolveSnapshotPath(config, state, taskJson);
+    const reportPath = resolveReviewPath(config, taskJson);
+    const snapshot = readJsonIfExists(snapshotPath);
+    const reportContent = readTextIfExists(reportPath);
+    const report = reportContent ? { conclusion: parseReviewConclusion(reportContent), validationMap: {} } : { conclusion: null, validationMap: {} };
+    const archivePath = path.resolve(config.archiveDirAbs, `${taskId}.json`);
+    const archive = readJsonIfExists(archivePath);
+    return {
+        change: spec.change,
+        taskId,
+        status: toExecutionStatus(state),
+        currentPhase: state?.currentPhase || null,
+        phaseCompleted: state?.phaseCompleted || null,
+        reviewConclusion: state?.reviewConclusion || report.conclusion || null,
+        currentSnapshot: state?.currentSnapshot || (snapshotPath ? ensurePosix(path.relative(config.projectRoot, snapshotPath)) : null),
+        updatedAt: state?.updatedAt || new Date().toISOString(),
+        startedAt: state?.startedAt || null,
+        archive: {
+            path: fs.existsSync(archivePath) ? ensurePosix(path.relative(config.projectRoot, archivePath)) : null,
+            eventCount: Array.isArray(archive?.events) ? archive.events.length : 0,
+            lastEvent: Array.isArray(archive?.events) && archive.events.length > 0 ? archive.events[archive.events.length - 1] : null,
+        },
+        lastGate: {
+            blockedAt: state?.lastGateBlockedAt || null,
+            reason: state?.lastGateBlockedReason || null,
+            phase: state?.lastGateBlockedPhase || null,
+            missingValidations: Array.isArray(state?.lastMissingValidations) ? state.lastMissingValidations : [],
+        },
+        taskPhases: {
+            planning: taskJson?.status || 'pending',
+            implementation: taskJson?.status || 'pending',
+            review: taskJson?.status || 'pending',
+        },
+        artifacts: {
+            task: ensurePosix(path.relative(config.projectRoot, getTaskFilePath(config, taskId))),
+            proposal: spec.proposal || null,
+            design: spec.design || null,
+            tasks: spec.tasks || null,
+            snapshot: snapshotPath ? ensurePosix(path.relative(config.projectRoot, snapshotPath)) : null,
+            review: reportPath ? ensurePosix(path.relative(config.projectRoot, reportPath)) : null,
+        },
+        planning: {
+            embedded: true,
+            summary: taskJson?.implementation?.notes || '',
+        },
+        validations: {
+            implementation: normalizeSnapshotValidations(snapshot),
+            review: Object.entries(report.validationMap || {}).map(([name, status]) => ({ name, status })),
+        },
+        mergeStrategy: taskJson?.metadata?.mergeStrategy || { type: 'squash', deleteBranch: true, deleteWorktree: true },
+    };
+}
+function getMetadataSpec(taskJson) {
+    if (!taskJson?.metadata?.change) {
+        return null;
+    }
+    return {
+        change: taskJson.metadata.change,
+        proposal: taskJson.docs_to_read?.[0] || null,
+        design: taskJson.docs_to_read?.[1] || null,
+        tasks: taskJson.docs_to_read?.[2] || null,
+        manifest: taskJson.metadata.manifest || null,
+        execution: taskJson.metadata.execution || null,
+        version: 'v1',
+    };
+}
+/**
+ * Sync task to Spec
+ */
+function syncTaskToSpec(options = {}) {
+    const config = (0, config_1.loadConfig)({ cwd: options.cwd });
+    const state = (0, state_1.loadState)(config);
+    const taskId = options.taskId || state.currentTask;
+    if (!taskId) {
+        return { skipped: true, reason: 'missing-task-id' };
+    }
+    const taskJson = readTaskJson(config, taskId);
+    if (!taskJson) {
+        return { skipped: true, reason: 'missing-task-file' };
+    }
+    const spec = getMetadataSpec(taskJson);
+    if (!spec?.change) {
+        return { skipped: true, reason: 'missing-spec-metadata' };
+    }
+    const executionTarget = spec.execution || ensurePosix(`spec/changes/${spec.change}/execution.json`);
+    const executionPath = path.resolve(config.projectRoot, executionTarget);
+    // Security: Validate execution path is within project root
+    if (!isPathWithinProject(executionPath, config.projectRoot)) {
+        console.error(`[SPEC-SYNC] Execution path escapes project root: ${executionTarget}`);
+        return { skipped: true, reason: 'invalid-execution-path' };
+    }
+    const executionDoc = buildExecutionDocument({ config, taskJson, state, taskId, spec });
+    fs.mkdirSync(path.dirname(executionPath), { recursive: true });
+    fs.writeFileSync(executionPath, JSON.stringify(executionDoc, null, 2), 'utf8');
+    return {
+        skipped: false,
+        taskId,
+        change: spec.change,
+        executionPath: ensurePosix(path.relative(config.projectRoot, executionPath)),
+    };
+}
+/**
+ * Main entry point
+ */
+function main() {
+    const args = parseArgs(process.argv);
+    const result = syncTaskToSpec({
+        cwd: args.cwd,
+        taskId: args['task-id'],
+    });
+    if (result.skipped) {
+        console.log(`[SPEC-SYNC] skipped: ${result.reason}`);
+        process.exit(0);
+    }
+    console.log(`[SPEC-SYNC] updated: ${result.executionPath}`);
+    process.exit(0);
+}
+if (require.main === module) {
+    main();
+}
+exports.default = {
+    syncTaskToSpec,
+};

package/dist/types/ai-context.d.ts

@@ -0,0 +1,108 @@
+/**
+ * types/ai-context.ts
+ * AI 项目上下文协议定义
+ *
+ * AI 在调用 extract/design/tasks 命令前，先分析宿主项目并生成此结构，
+ * 通过 --context-file 参数传入。CLI 命令会将其注入到生成的文档中。
+ */
+/**
+ * 项目基本信息
+ */
+export interface ProjectInfo {
+    /** 项目名称 */
+    name: string;
+    /** 项目描述（从 package.json description 或 README 提取） */
+    description?: string;
+    /** 项目类型 */
+    type?: 'library' | 'application' | 'service' | 'cli' | 'monorepo';
+    /** 技术栈 */
+    techStack?: TechStack;
+    /** 目录结构摘要 */
+    structure?: DirectorySummary[];
+    /** 关键文件列表 */
+    keyFiles?: string[];
+    /** 依赖信息 */
+    dependencies?: DependencyInfo;
+}
+/**
+ * 技术栈信息
+ */
+export interface TechStack {
+    /** 编程语言及版本 */
+    language?: string;
+    /** 运行时 */
+    runtime?: string;
+    /** 框架 */
+    framework?: string;
+    /** 构建工具 */
+    buildTool?: string;
+    /** 测试框架 */
+    testFramework?: string;
+    /** 代码规范工具 */
+    lintTool?: string;
+    /** 包管理器 */
+    packageManager?: string;
+    /** 其他关键技术 */
+    others?: string[];
+}
+/**
+ * 目录摘要
+ */
+export interface DirectorySummary {
+    /** 目录路径 */
+    path: string;
+    /** 目录用途描述 */
+    purpose: string;
+    /** 文件数量（可选） */
+    fileCount?: number;
+}
+/**
+ * 依赖信息
+ */
+export interface DependencyInfo {
+    /** 核心依赖 */
+    core?: string[];
+    /** 开发依赖 */
+    dev?: string[];
+    /** 缺失的关键依赖（AI 建议添加的） */
+    suggested?: string[];
+}
+/**
+ * AI 项目上下文（完整结构）
+ */
+export interface AiContext {
+    /** 协议版本 */
+    version: '1.0';
+    /** 项目基本信息 */
+    project: ProjectInfo;
+    /** AI 对项目的理解和分析 */
+    analysis?: {
+        /** 项目架构总结 */
+        architectureSummary?: string;
+        /** 核心模块识别 */
+        coreModules?: Array<{
+            name: string;
+            path: string;
+            description: string;
+        }>;
+        /** 识别的设计模式 */
+        designPatterns?: string[];
+        /** 潜在技术风险 */
+        risks?: string[];
+        /** 改进建议 */
+        suggestions?: string[];
+    };
+    /** 任务特定信息 */
+    task?: {
+        /** 任务类型 */
+        type?: 'feat' | 'fix' | 'refactor' | 'test' | 'docs' | 'chore';
+        /** 任务优先级 */
+        priority?: 'high' | 'medium' | 'low';
+        /** 任务涉及的文件范围 */
+        affectedFiles?: string[];
+        /** 任务约束条件 */
+        constraints?: string[];
+        /** 特殊要求 */
+        requirements?: string[];
+    };
+}

package/dist/types/ai-context.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * types/ai-context.ts
+ * AI 项目上下文协议定义
+ *
+ * AI 在调用 extract/design/tasks 命令前，先分析宿主项目并生成此结构，
+ * 通过 --context-file 参数传入。CLI 命令会将其注入到生成的文档中。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@bicorne/task-flow",
+  "version": "0.1.0",
+  "description": "Git worktree-based parallel task execution system for zero-conflict multi-task development",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "task-flow": "./dist/index.js"
+  },
+  "engines": {
+    "node": ">=24.14.0"
+  },
+  "engineStrict": true,
+  "keywords": [
+    "harness",
+    "task-flow",
+    "git-worktree",
+    "parallel-development",
+    "task-management",
+    "developer-tools"
+  ],
+  "author": "Sam Xu",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/didengren/harness-task-flow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/didengren/harness-task-flow/issues"
+  },
+  "homepage": "https://github.com/didengren/harness-task-flow#readme",
+  "files": [
+    "dist/",
+    "assets/",
+    "references/",
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@changesets/cli": "^2.27.0",
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^24.12.0",
+    "@typescript-eslint/eslint-plugin": "8.58.0",
+    "@typescript-eslint/parser": "8.58.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.0.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.58.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.js",
+    "lint": "eslint src/",
+    "build": "tsc --project tsconfig.build.json",
+    "build:dev": "tsc",
+    "build:watch": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm build && changeset publish"
+  }
+}