@bicorne/task-flow 0.1.0

package/dist/hooks/hook-runner/loader.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * hooks/hook-runner/loader.ts
+ * Hook loading utilities
+ */
+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.getDefaultHooksPath = getDefaultHooksPath;
+exports.loadHooksConfig = loadHooksConfig;
+exports.loadHookScriptAsync = loadHookScriptAsync;
+exports.loadHookScript = loadHookScript;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../../lib/config");
+/**
+ * Default hooks config
+ */
+const DEFAULT_HOOKS_CONFIG = {
+    hooks: {},
+};
+/**
+ * Get default hooks path
+ */
+function getDefaultHooksPath(config) {
+    return path.resolve(config.harnessRootAbs, 'hooks.json');
+}
+/**
+ * Load hooks config from file
+ */
+function loadHooksConfig(config) {
+    const cfg = config || (0, config_1.loadConfig)();
+    const hooksPath = getDefaultHooksPath(cfg);
+    if (!fs.existsSync(hooksPath)) {
+        return { ...DEFAULT_HOOKS_CONFIG, configPath: hooksPath };
+    }
+    try {
+        const content = fs.readFileSync(hooksPath, 'utf8');
+        const parsed = JSON.parse(content);
+        return {
+            ...DEFAULT_HOOKS_CONFIG,
+            ...parsed,
+            configPath: hooksPath,
+        };
+    }
+    catch (error) {
+        console.warn('[HOOK-RUNNER] Failed to load hooks config:', error instanceof Error ? error.message : 'Unknown error');
+        return { ...DEFAULT_HOOKS_CONFIG, configPath: hooksPath };
+    }
+}
+/**
+ * Load hook script with dynamic import to avoid require.cache issues
+ */
+async function loadHookScriptAsync(scriptPath, config) {
+    const cfg = config || (0, config_1.loadConfig)();
+    const absolutePath = path.isAbsolute(scriptPath)
+        ? scriptPath
+        : path.resolve(cfg.projectRoot, scriptPath);
+    if (!fs.existsSync(absolutePath)) {
+        console.warn('[HOOK-RUNNER] Hook script not found:', absolutePath);
+        return null;
+    }
+    try {
+        const fileUrl = `file://${absolutePath}?t=${Date.now()}`;
+        const hookModule = await Promise.resolve(`${fileUrl}`).then(s => __importStar(require(s)));
+        return hookModule.default || hookModule;
+    }
+    catch (error) {
+        console.error('[HOOK-RUNNER] Failed to load hook script:', absolutePath, error instanceof Error ? error.message : 'Unknown error');
+        return null;
+    }
+}
+/**
+ * Load hook script (legacy sync version)
+ * @deprecated Use loadHookScriptAsync instead
+ */
+function loadHookScript(scriptPath, config) {
+    const cfg = config || (0, config_1.loadConfig)();
+    const absolutePath = path.isAbsolute(scriptPath)
+        ? scriptPath
+        : path.resolve(cfg.projectRoot, scriptPath);
+    if (!fs.existsSync(absolutePath)) {
+        console.warn('[HOOK-RUNNER] Hook script not found:', absolutePath);
+        return null;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const hookModule = require(absolutePath);
+        return hookModule;
+    }
+    catch (error) {
+        console.error('[HOOK-RUNNER] Failed to load hook script:', absolutePath, error instanceof Error ? error.message : 'Unknown error');
+        return null;
+    }
+}

package/dist/hooks/hook-runner/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * hooks/hook-runner/types.ts
+ * Type definitions for hook runner
+ */
+import { Config } from '../../lib/config';
+/**
+ * Hook lifecycle information
+ */
+export interface HookLifecycle {
+    phase: string;
+    timing: string;
+}
+/**
+ * Hook configuration
+ */
+export interface HookConfig {
+    name: string;
+    script: string;
+    enabled?: boolean;
+    timeout?: number;
+    hookName?: string;
+    lifecycle?: HookLifecycle;
+}
+/**
+ * Hook execution context
+ */
+export interface HookContext {
+    config?: Config;
+    [key: string]: unknown;
+}
+/**
+ * Hook execution result
+ */
+export interface HookResult {
+    name?: string;
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    script?: string;
+    stack?: string;
+}
+/**
+ * Hook execution engine result
+ */
+export interface HookExecutionResult {
+    success: boolean;
+    executed: number;
+    results: HookResult[];
+    message?: string;
+    hookName?: string;
+    hookNames?: string[];
+}
+/**
+ * Loaded hooks config
+ */
+export interface LoadedHooksConfig {
+    hooks: Record<string, HookConfig[]>;
+    configPath: string;
+}

package/dist/hooks/hook-runner/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * hooks/hook-runner/types.ts
+ * Type definitions for hook runner
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/hooks/hook-runner.d.ts

@@ -0,0 +1,9 @@
+/**
+ * hooks/hook-runner.ts
+ * Backward-compatible re-export from hook-runner/ module
+ * @deprecated Import from './hook-runner/index' directly
+ */
+export { runHook, runHookSync, runHookChain, getHookLifecycle, getHooksForPhase, validateHookConfig, createHookConfig, HOOK_LIFECYCLE, default, } from './hook-runner/index';
+export { HookLifecycle, HookConfig, HookContext, HookResult, HookExecutionResult, LoadedHooksConfig, } from './hook-runner/types';
+export { getDefaultHooksPath, loadHooksConfig, loadHookScript, loadHookScriptAsync, } from './hook-runner/loader';
+export { executeHookFunction, executeSingleHookAsync, executeSingleHookSync, } from './hook-runner/executor';

package/dist/hooks/hook-runner.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * hooks/hook-runner.ts
+ * Backward-compatible re-export from hook-runner/ module
+ * @deprecated Import from './hook-runner/index' directly
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeSingleHookSync = exports.executeSingleHookAsync = exports.executeHookFunction = exports.loadHookScriptAsync = exports.loadHookScript = exports.loadHooksConfig = exports.getDefaultHooksPath = exports.default = exports.HOOK_LIFECYCLE = exports.createHookConfig = exports.validateHookConfig = exports.getHooksForPhase = exports.getHookLifecycle = exports.runHookChain = exports.runHookSync = exports.runHook = void 0;
+var index_1 = require("./hook-runner/index");
+Object.defineProperty(exports, "runHook", { enumerable: true, get: function () { return index_1.runHook; } });
+Object.defineProperty(exports, "runHookSync", { enumerable: true, get: function () { return index_1.runHookSync; } });
+Object.defineProperty(exports, "runHookChain", { enumerable: true, get: function () { return index_1.runHookChain; } });
+Object.defineProperty(exports, "getHookLifecycle", { enumerable: true, get: function () { return index_1.getHookLifecycle; } });
+Object.defineProperty(exports, "getHooksForPhase", { enumerable: true, get: function () { return index_1.getHooksForPhase; } });
+Object.defineProperty(exports, "validateHookConfig", { enumerable: true, get: function () { return index_1.validateHookConfig; } });
+Object.defineProperty(exports, "createHookConfig", { enumerable: true, get: function () { return index_1.createHookConfig; } });
+Object.defineProperty(exports, "HOOK_LIFECYCLE", { enumerable: true, get: function () { return index_1.HOOK_LIFECYCLE; } });
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(index_1).default; } });
+var loader_1 = require("./hook-runner/loader");
+Object.defineProperty(exports, "getDefaultHooksPath", { enumerable: true, get: function () { return loader_1.getDefaultHooksPath; } });
+Object.defineProperty(exports, "loadHooksConfig", { enumerable: true, get: function () { return loader_1.loadHooksConfig; } });
+Object.defineProperty(exports, "loadHookScript", { enumerable: true, get: function () { return loader_1.loadHookScript; } });
+Object.defineProperty(exports, "loadHookScriptAsync", { enumerable: true, get: function () { return loader_1.loadHookScriptAsync; } });
+var executor_1 = require("./hook-runner/executor");
+Object.defineProperty(exports, "executeHookFunction", { enumerable: true, get: function () { return executor_1.executeHookFunction; } });
+Object.defineProperty(exports, "executeSingleHookAsync", { enumerable: true, get: function () { return executor_1.executeSingleHookAsync; } });
+Object.defineProperty(exports, "executeSingleHookSync", { enumerable: true, get: function () { return executor_1.executeSingleHookSync; } });

package/dist/hooks/phase-complete-detector.d.ts

@@ -0,0 +1,35 @@
+/**
+ * hooks/phase-complete-detector.ts
+ * Detect phase completion and update state
+ */
+import { Config } from '../lib/config';
+import { State } from '../lib/state';
+import { GateResult } from './phase-gate-validator';
+export interface DetectOptions {
+    filePath: string;
+    config: Config;
+    state: State;
+}
+export interface DetectResult {
+    detected: boolean;
+    reason?: string;
+    blocked?: boolean;
+    gateResult?: GateResult;
+    phaseCompleted?: string;
+    newPhase?: string;
+}
+/**
+ * Update task JSON phase status with error handling
+ */
+export declare function updateTaskJsonPhaseStatus(taskPath: string, phaseName: string, status: string): boolean;
+/**
+ * Detect phase completion
+ * @param options - Options
+ * @returns Detection result
+ */
+export declare function detectPhaseCompletion(options: DetectOptions): DetectResult;
+declare const _default: {
+    detectPhaseCompletion: typeof detectPhaseCompletion;
+    updateTaskJsonPhaseStatus: typeof updateTaskJsonPhaseStatus;
+};
+export default _default;

package/dist/hooks/phase-complete-detector.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * hooks/phase-complete-detector.ts
+ * Detect phase completion and update state
+ */
+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.updateTaskJsonPhaseStatus = updateTaskJsonPhaseStatus;
+exports.detectPhaseCompletion = detectPhaseCompletion;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../lib/config");
+const state_1 = require("../lib/state");
+const archive_1 = require("../lib/archive");
+const phase_gate_validator_1 = require("./phase-gate-validator");
+const sync_task_to_openspec_1 = require("../spec/sync-task-to-openspec");
+/**
+ * Update task JSON phase status with error handling
+ */
+function updateTaskJsonPhaseStatus(taskPath, phaseName, status) {
+    if (!fs.existsSync(taskPath)) {
+        console.warn(`[PHASE-DETECTOR] Task file not found: ${taskPath}`);
+        return false;
+    }
+    try {
+        const content = fs.readFileSync(taskPath, 'utf8');
+        const taskJson = JSON.parse(content);
+        taskJson.status = status;
+        fs.writeFileSync(taskPath, JSON.stringify(taskJson, null, 2), 'utf8');
+        console.log(`[PHASE-DETECTOR] Updated task JSON: ${phaseName} phase -> ${status}`);
+        return true;
+    }
+    catch (e) {
+        console.error(`[PHASE-DETECTOR] Error updating task JSON: ${e.message}`);
+        return false;
+    }
+}
+/**
+ * Log gate blocked warnings with type-safe access
+ */
+function logGateBlockedWarnings(gateResult) {
+    if (!gateResult) {
+        return;
+    }
+    console.warn(`[PHASE-DETECTOR] Phase blocked: ${gateResult.reason}`);
+    const missingValidations = Array.isArray(gateResult.missingValidations)
+        ? gateResult.missingValidations
+        : [];
+    if (missingValidations.length > 0) {
+        console.warn(`[PHASE-DETECTOR] Missing: ${missingValidations.join(', ')}`);
+    }
+}
+/**
+ * Detect phase completion
+ * @param options - Options
+ * @returns Detection result
+ */
+function detectPhaseCompletion(options) {
+    const { filePath, config, state } = options;
+    if (!filePath.includes('.harness/')) {
+        return { detected: false, reason: 'not-harness-file' };
+    }
+    const taskId = state.currentTask;
+    if (!taskId) {
+        return { detected: false, reason: 'no-current-task' };
+    }
+    const gateResult = (0, phase_gate_validator_1.assessTransitionGate)({ taskId, filePath, state, config });
+    if (gateResult.skipped) {
+        return { detected: false, reason: 'gate-skipped' };
+    }
+    if (!gateResult.allowed) {
+        // Update state with blocked gate info
+        (0, state_1.updateState)({
+            lastGateBlockedAt: new Date().toISOString(),
+            lastGateBlockedReason: gateResult.reason,
+            lastGateBlockedPhase: gateResult.phaseCompleted || null,
+            lastMissingValidations: gateResult.missingValidations || [],
+        }, config);
+        // Archive task state
+        (0, archive_1.archiveTaskState)({
+            cwd: config.projectRoot,
+            taskId,
+            eventType: 'gate_blocked',
+            status: state.status || 'running',
+            phase: state.currentPhase || undefined,
+            phaseCompleted: gateResult.phaseCompleted || state.phaseCompleted || undefined,
+            reviewConclusion: state.reviewConclusion || undefined,
+            reason: gateResult.reason,
+        });
+        // Sync to Spec
+        (0, sync_task_to_openspec_1.syncTaskToSpec)({ cwd: config.projectRoot, taskId });
+        return {
+            detected: true,
+            blocked: true,
+            gateResult,
+        };
+    }
+    // Phase transition allowed
+    const newPhase = gateResult.nextPhase;
+    const phaseCompleted = gateResult.phaseCompleted;
+    // Update state
+    (0, state_1.updateState)({
+        currentPhase: newPhase,
+        phaseCompleted,
+        reviewConclusion: gateResult.reviewConclusion || state.reviewConclusion || null,
+        lastGateBlockedAt: null,
+        lastGateBlockedReason: null,
+        lastGateBlockedPhase: null,
+        lastMissingValidations: [],
+    }, config);
+    // Update task JSON phase statuses
+    const taskPath = path.resolve(config.tasksDirAbs, `${taskId}.json`);
+    if (phaseCompleted) {
+        updateTaskJsonPhaseStatus(taskPath, phaseCompleted, 'completed');
+    }
+    if (newPhase && newPhase !== 'merge') {
+        updateTaskJsonPhaseStatus(taskPath, newPhase, 'in_progress');
+    }
+    // Archive task state
+    (0, archive_1.archiveTaskState)({
+        cwd: config.projectRoot,
+        taskId,
+        eventType: 'phase_transition',
+        status: state.status || 'running',
+        phase: newPhase || undefined,
+        phaseCompleted: phaseCompleted || undefined,
+        reviewConclusion: gateResult.reviewConclusion || undefined,
+    });
+    // Sync to Spec
+    (0, sync_task_to_openspec_1.syncTaskToSpec)({ cwd: config.projectRoot, taskId });
+    return {
+        detected: true,
+        blocked: false,
+        phaseCompleted,
+        newPhase,
+        gateResult,
+    };
+}
+/**
+ * Main entry point for hook usage
+ */
+function main() {
+    const input = JSON.parse(process.argv[2] || '{}');
+    const filePath = input.tool_input?.file_path || input.tool_input?.path || '';
+    const config = (0, config_1.loadConfig)();
+    const state = (0, state_1.loadState)(config);
+    if (!state?.currentTask) {
+        process.exit(0);
+    }
+    const result = detectPhaseCompletion({ filePath, config, state });
+    if (!result.detected || result.reason) {
+        process.exit(0);
+    }
+    if (result.blocked) {
+        logGateBlockedWarnings(result.gateResult);
+    }
+    else {
+        console.log(`[PHASE-DETECTOR] Phase transition: ${result.phaseCompleted} -> ${result.newPhase}`);
+        if (result.gateResult?.reviewConclusion) {
+            console.log(`[PHASE-DETECTOR] Review conclusion: ${result.gateResult.reviewConclusion}`);
+        }
+    }
+    process.exit(0);
+}
+if (require.main === module) {
+    main();
+}
+exports.default = {
+    detectPhaseCompletion,
+    updateTaskJsonPhaseStatus,
+};

package/dist/hooks/phase-gate-validator.d.ts

@@ -0,0 +1,76 @@
+/**
+ * hooks/phase-gate-validator.ts
+ * Validate phase transition gates
+ */
+import { Config } from '../lib/config';
+import { State } from '../lib/state';
+export interface TaskJson {
+    status?: string;
+    validation?: {
+        commands?: string[];
+        manual_checks?: string[];
+    };
+    implementation?: {
+        notes?: string;
+        steps?: Array<string | {
+            step?: string;
+        }>;
+    };
+    metadata?: {
+        outputs?: {
+            task?: string;
+        };
+    };
+}
+export interface GateResult {
+    allowed: boolean;
+    skipped: boolean;
+    phaseCompleted?: string;
+    nextPhase?: string;
+    reason?: string;
+    missingValidations?: string[];
+    details?: string[];
+    validations?: string[];
+    reviewConclusion?: string | null;
+}
+export interface GateOptions {
+    taskId: string;
+    filePath: string;
+    state: State;
+    config: Config;
+}
+export declare function normalizePath(inputPath: string | undefined, projectRoot: string): string;
+export declare function normalizeValidationName(name: string): string;
+export declare function getValidationAliases(validationName: string): string[];
+export declare function isPassedStatus(status: string | undefined): boolean;
+export declare function parseReviewConclusion(content: string): string | null;
+export declare function parseReviewValidationMap(content: string): Record<string, string>;
+export declare function parseReviewReport(content: string): {
+    conclusion: string | null;
+    validationMap: Record<string, string>;
+};
+export declare function deriveTransitionFromFilePath(filePath: string, config: Config): {
+    phaseCompleted: string;
+    nextPhase: string;
+    relativePath: string;
+} | null;
+export declare function getTaskFilePath(config: Config, taskId: string): string;
+export declare function readTaskJson(config: Config, taskId: string): TaskJson | null;
+export declare function getValidationItems(taskJson: TaskJson | null, phaseName: string): string[];
+export declare function getPlanningSummary(taskJson: TaskJson | null): string;
+export declare function getPlanningList(taskJson: TaskJson | null, key: string): string[];
+export declare function getSnapshotValidationMap(snapshotPath: string): Record<string, boolean>;
+export declare function hasValidationPassed(validationName: string, snapshotValidationMap: Record<string, boolean | string>): boolean;
+/**
+ * Assess transition gate
+ * @param options - Options
+ * @returns Gate assessment result
+ */
+export declare function assessTransitionGate(options: GateOptions): GateResult;
+declare const _default: {
+    assessTransitionGate: typeof assessTransitionGate;
+    deriveTransitionFromFilePath: typeof deriveTransitionFromFilePath;
+    parseReviewConclusion: typeof parseReviewConclusion;
+    parseReviewReport: typeof parseReviewReport;
+};
+export default _default;