@s_s/harmonia 1.2.0 → 1.4.0

package/build/core/state.js

@@ -1,125 +1,93 @@
 /**
- * Project state management — manages <data_dir>/<project_name>/iter-<n>/state.json
+ * Workflow state management — manages state.json within iteration/patch directories.
+ *
+ * Rewritten for the new node-based architecture. State now tracks individual
+ * workflow nodes instead of linear phases.
  */
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { getIterationDir } from './registry.js';
-/**
- * Error thrown when a tool requires scale but it hasn't been set yet.
- */
-export class ScaleNotSetError extends Error {
-    constructor(projectName) {
-        super(`项目 "${projectName}" 尚未设定 scale。请先完成 PRD 审批，然后调用 project_set_scale 设定项目规模。`);
-        this.name = 'ScaleNotSetError';
-    }
-}
+import { initNodeStates } from './workflow-engine.js';
 const STATE_FILE = 'state.json';
-function statePath(projectName, iteration) {
-    return join(getIterationDir(projectName, iteration), STATE_FILE);
+function statePath(projectName, iteration, contextDir) {
+    return join(contextDir, STATE_FILE);
 }
 /**
- * Initialize a new project state file for a specific iteration.
- * Note: directory creation is handled by registry.startIteration().
- * This only writes the state.json.
+ * Initialize a new workflow state file.
+ *
+ * Creates initial NodeState records for all nodes in the workflow definition.
+ * All nodes start as 'pending'.
+ *
+ * @param contextDir - Directory containing state.json
  */
-export async function initProjectState(projectName, projectDir, workflow, iteration) {
+export async function initWorkflowState(projectName, projectDir, workflow, iteration, type = 'iteration', contextDir) {
     const now = new Date().toISOString();
-    const phases = workflow.definition.phases;
-    const firstPhaseId = phases[0]?.id ?? '';
+    const nodes = initNodeStates(workflow.definition);
     const state = {
         projectName,
         projectDir,
         workflow: workflow.definition.name,
+        type,
         iteration,
-        scale: null,
-        currentPhase: firstPhaseId,
-        phases: phases.map((p, i) => ({
-            id: p.id,
-            status: i === 0 ? 'in_progress' : 'pending',
-            ...(i === 0 ? { startedAt: now } : {}),
-        })),
+        activeNodeId: null,
+        nodes,
         createdAt: now,
         updatedAt: now,
     };
-    await writeState(projectName, iteration, state);
+    await writeState(projectName, iteration, state, contextDir);
     return state;
 }
 /**
- * Read the current project state for a specific iteration.
+ * Read the current workflow state.
  */
-export async function readState(projectName, iteration) {
-    const content = await readFile(statePath(projectName, iteration), 'utf-8');
+export async function readState(projectName, iteration, contextDir) {
+    const content = await readFile(statePath(projectName, iteration, contextDir), 'utf-8');
     return JSON.parse(content);
 }
 /**
- * Write project state to disk for a specific iteration.
+ * Write workflow state to disk.
  */
-export async function writeState(projectName, iteration, state) {
-    const filePath = statePath(projectName, iteration);
+export async function writeState(projectName, iteration, state, contextDir) {
+    const filePath = statePath(projectName, iteration, contextDir);
     await mkdir(dirname(filePath), { recursive: true });
     state.updatedAt = new Date().toISOString();
     await writeFile(filePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
 }
 /**
- * Update a specific phase's status.
+ * Update a specific node's state. Reads current state, applies the partial update,
+ * and writes back.
+ *
+ * @returns The updated full WorkflowState
  */
-export async function updatePhaseStatus(projectName, iteration, phaseId, status, blockedReason) {
-    const state = await readState(projectName, iteration);
-    const phase = state.phases.find((p) => p.id === phaseId);
-    if (!phase) {
-        throw new Error(`Phase "${phaseId}" not found in project state`);
-    }
-    const now = new Date().toISOString();
-    phase.status = status;
-    if (status === 'in_progress' && !phase.startedAt) {
-        phase.startedAt = now;
-    }
-    if (status === 'completed') {
-        phase.completedAt = now;
-        delete phase.blockedReason;
-    }
-    if (status === 'blocked' && blockedReason) {
-        phase.blockedReason = blockedReason;
-    }
-    // If advancing to in_progress, update currentPhase
-    if (status === 'in_progress') {
-        state.currentPhase = phaseId;
+export async function updateNodeState(projectName, iteration, nodeId, update, contextDir) {
+    const state = await readState(projectName, iteration, contextDir);
+    const existing = state.nodes[nodeId];
+    if (!existing) {
+        throw new Error(`Node "${nodeId}" not found in workflow state for project "${projectName}"`);
     }
-    // If completing a phase, auto-advance currentPhase to the next pending one
-    if (status === 'completed') {
-        const idx = state.phases.findIndex((p) => p.id === phaseId);
-        const next = state.phases.find((p, i) => i > idx && p.status === 'pending');
-        if (next) {
-            next.status = 'in_progress';
-            next.startedAt = now;
-            state.currentPhase = next.id;
-        }
-    }
-    await writeState(projectName, iteration, state);
+    state.nodes[nodeId] = { ...existing, ...update };
+    await writeState(projectName, iteration, state, contextDir);
     return state;
 }
 /**
- * Check if a project state file exists for a specific iteration.
+ * Persist engine-computed state changes. After the workflow engine computes
+ * a new state (via computeNextAction or startWorkflow), call this to persist it.
+ *
+ * This is the preferred way to save state changes from the engine,
+ * as it replaces the entire state atomically.
  */
-export async function projectStateExists(projectName, iteration) {
+export async function persistState(projectName, iteration, state, contextDir) {
+    await writeState(projectName, iteration, state, contextDir);
+}
+/**
+ * Check if a workflow state file exists.
+ */
+export async function stateExists(projectName, iteration, contextDir) {
     try {
-        await readFile(statePath(projectName, iteration), 'utf-8');
+        await readFile(statePath(projectName, iteration, contextDir), 'utf-8');
         return true;
     }
     catch {
         return false;
     }
 }
-/**
- * Set the project scale. Scale is immutable once set.
- */
-export async function setScale(projectName, iteration, scale) {
-    const state = await readState(projectName, iteration);
-    if (state.scale !== null) {
-        throw new Error(`Scale 已设定为 "${state.scale}"，不可更改。如需调整规模，请重新评估 PRD。`);
-    }
-    state.scale = scale;
-    await writeState(projectName, iteration, state);
-    return state;
-}
 //# sourceMappingURL=state.js.map

package/build/core/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/core/state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/core/state.ts"],"names":[],"mappings":"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"}

package/build/core/steps.d.ts

@@ -1,34 +1,34 @@
 /**
- * Step state management — manages <data_dir>/<project_name>/iter-<n>/steps.json
+ * Step state management — manages <context_dir>/steps.json
  *
- * Tracks which sequential steps have been completed for each document,
+ * Tracks which sequential steps have been completed for each artifact,
  * supporting the P3 Sequential mode feature.
  */
-import type { DocStepState } from './types.js';
+import type { ArtifactStepState } from './types.js';
 /**
- * Read the steps state for a project iteration.
+ * Read the steps state for a project context.
  */
-export declare function readSteps(projectName: string, iteration: number): Promise<Record<string, DocStepState>>;
+export declare function readSteps(projectName: string, iteration: number, contextDir?: string): Promise<Record<string, ArtifactStepState>>;
 /**
- * Get the step state for a specific document.
+ * Get the step state for a specific artifact.
  */
-export declare function getDocStepState(projectName: string, iteration: number, docId: string): Promise<DocStepState | null>;
+export declare function getArtifactStepState(projectName: string, iteration: number, artifactId: string, contextDir?: string): Promise<ArtifactStepState | null>;
 /**
- * Get the set of completed step IDs for a document.
+ * Get the set of completed step IDs for an artifact.
  */
-export declare function getCompletedStepIds(state: DocStepState | null): Set<string>;
+export declare function getCompletedStepIds(state: ArtifactStepState | null): Set<string>;
 /**
  * Record a step as completed. If the step was already completed,
  * it is overwritten and all subsequent steps are cleared (rollback).
  *
- * @returns The updated DocStepState
+ * @returns The updated ArtifactStepState
  */
-export declare function recordStepCompletion(projectName: string, iteration: number, docId: string, stepId: string, artifactPath: string, allStepIds: string[]): Promise<DocStepState>;
+export declare function recordStepCompletion(projectName: string, iteration: number, artifactId: string, stepId: string, artifactPath: string, allStepIds: string[], contextDir?: string): Promise<ArtifactStepState>;
 /**
- * Mark a document as finalized (all steps completed + final doc written).
+ * Mark an artifact as finalized (all steps completed + final artifact written).
  */
-export declare function markFinalized(projectName: string, iteration: number, docId: string): Promise<DocStepState>;
+export declare function markFinalized(projectName: string, iteration: number, artifactId: string, contextDir?: string): Promise<ArtifactStepState>;
 /**
- * Check if a document's sequential process is finalized.
+ * Check if an artifact's sequential process is finalized.
  */
-export declare function isDocFinalized(projectName: string, iteration: number, docId: string): Promise<boolean>;
+export declare function isArtifactFinalized(projectName: string, iteration: number, artifactId: string, contextDir?: string): Promise<boolean>;

package/build/core/steps.js

@@ -1,24 +1,23 @@
 /**
- * Step state management — manages <data_dir>/<project_name>/iter-<n>/steps.json
+ * Step state management — manages <context_dir>/steps.json
  *
- * Tracks which sequential steps have been completed for each document,
+ * Tracks which sequential steps have been completed for each artifact,
  * supporting the P3 Sequential mode feature.
  */
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { getIterationDir } from './registry.js';
 const STEPS_FILE = 'steps.json';
-function stepsPath(projectName, iteration) {
-    return join(getIterationDir(projectName, iteration), STEPS_FILE);
+function stepsPath(projectName, iteration, contextDir) {
+    return join(contextDir, STEPS_FILE);
 }
 /**
- * Read the steps state for a project iteration.
+ * Read the steps state for a project context.
  */
-export async function readSteps(projectName, iteration) {
+export async function readSteps(projectName, iteration, contextDir) {
     try {
-        const content = await readFile(stepsPath(projectName, iteration), 'utf-8');
+        const content = await readFile(stepsPath(projectName, iteration, contextDir), 'utf-8');
         const data = JSON.parse(content);
-        return data.docs ?? {};
+        return data.artifacts ?? {};
     }
     catch {
         return {};
@@ -27,21 +26,21 @@ export async function readSteps(projectName, iteration) {
 /**
  * Write steps state to disk.
  */
-async function writeSteps(projectName, iteration, docs) {
-    const filePath = stepsPath(projectName, iteration);
+async function writeSteps(projectName, iteration, artifacts, contextDir) {
+    const filePath = stepsPath(projectName, iteration, contextDir);
     await mkdir(dirname(filePath), { recursive: true });
-    const data = { docs };
+    const data = { artifacts };
     await writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
 }
 /**
- * Get the step state for a specific document.
+ * Get the step state for a specific artifact.
  */
-export async function getDocStepState(projectName, iteration, docId) {
-    const docs = await readSteps(projectName, iteration);
-    return docs[docId] ?? null;
+export async function getArtifactStepState(projectName, iteration, artifactId, contextDir) {
+    const artifacts = await readSteps(projectName, iteration, contextDir);
+    return artifacts[artifactId] ?? null;
 }
 /**
- * Get the set of completed step IDs for a document.
+ * Get the set of completed step IDs for an artifact.
  */
 export function getCompletedStepIds(state) {
     if (!state)
@@ -52,14 +51,14 @@ export function getCompletedStepIds(state) {
  * Record a step as completed. If the step was already completed,
  * it is overwritten and all subsequent steps are cleared (rollback).
  *
- * @returns The updated DocStepState
+ * @returns The updated ArtifactStepState
  */
-export async function recordStepCompletion(projectName, iteration, docId, stepId, artifactPath, allStepIds) {
-    const docs = await readSteps(projectName, iteration);
-    let state = docs[docId];
+export async function recordStepCompletion(projectName, iteration, artifactId, stepId, artifactPath, allStepIds, contextDir) {
+    const artifacts = await readSteps(projectName, iteration, contextDir);
+    let state = artifacts[artifactId];
     if (!state) {
         state = {
-            docId,
+            artifactId,
             completedSteps: [],
             finalized: false,
         };
@@ -85,29 +84,29 @@ export async function recordStepCompletion(projectName, iteration, docId, stepId
         artifactPath,
     };
     state.completedSteps.push(record);
-    docs[docId] = state;
-    await writeSteps(projectName, iteration, docs);
+    artifacts[artifactId] = state;
+    await writeSteps(projectName, iteration, artifacts, contextDir);
     return state;
 }
 /**
- * Mark a document as finalized (all steps completed + final doc written).
+ * Mark an artifact as finalized (all steps completed + final artifact written).
  */
-export async function markFinalized(projectName, iteration, docId) {
-    const docs = await readSteps(projectName, iteration);
-    const state = docs[docId];
+export async function markFinalized(projectName, iteration, artifactId, contextDir) {
+    const artifacts = await readSteps(projectName, iteration, contextDir);
+    const state = artifacts[artifactId];
     if (!state) {
-        throw new Error(`No step state found for document "${docId}"`);
+        throw new Error(`No step state found for artifact "${artifactId}"`);
     }
     state.finalized = true;
     state.finalizedAt = new Date().toISOString();
-    await writeSteps(projectName, iteration, docs);
+    await writeSteps(projectName, iteration, artifacts, contextDir);
     return state;
 }
 /**
- * Check if a document's sequential process is finalized.
+ * Check if an artifact's sequential process is finalized.
  */
-export async function isDocFinalized(projectName, iteration, docId) {
-    const state = await getDocStepState(projectName, iteration, docId);
+export async function isArtifactFinalized(projectName, iteration, artifactId, contextDir) {
+    const state = await getArtifactStepState(projectName, iteration, artifactId, contextDir);
     return state?.finalized ?? false;
 }
 //# sourceMappingURL=steps.js.map

package/build/core/steps.js.map

@@ -1 +1 @@
-{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../src/core/steps.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../src/core/steps.ts"],"names":[],"mappings":"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"}

package/build/core/tree-utils.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure node-tree traversal utilities.
+ *
+ * All functions here are pure (no side effects, no engine state dependency),
+ * and only depend on types from ./types.ts.
+ *
+ * Extracted from workflow-engine.ts, loop-done.ts, role-dispatch.ts,
+ * engine-helpers.ts, and workflow-validator.ts to eliminate duplication
+ * and avoid circular dependencies.
+ */
+import type { WorkflowNode, TaskNode } from './types.js';
+/**
+ * Find a node by ID within a workflow tree.
+ * Returns null if not found.
+ */
+export declare function findNodeInTree(node: WorkflowNode, targetId: string): WorkflowNode | null;
+/**
+ * Find the path from root to a specific node (inclusive on both ends).
+ * Returns null if node not found.
+ */
+export declare function findPathToNode(node: WorkflowNode, targetId: string): WorkflowNode[] | null;
+/**
+ * Recursively collect all node IDs in a subtree.
+ */
+export declare function collectAllNodeIds(node: WorkflowNode, ids: Set<string>): void;
+/**
+ * Find the parent of a node by its ID.
+ * Returns the parent node and the child's index, or null if not found.
+ */
+export declare function findParent(root: WorkflowNode, targetId: string, current?: WorkflowNode): {
+    parent: WorkflowNode;
+    childIndex: number;
+} | null;
+/**
+ * Collect all node IDs that come after a target node in execution order.
+ *
+ * "After" means:
+ * - Subsequent siblings (and their full subtrees) in the parent sequence
+ * - Any nodes that follow the parent in its grandparent sequence (recursively)
+ *
+ * For parallel nodes, subsequent siblings don't apply (they execute simultaneously).
+ */
+export declare function collectSubsequentNodeIds(root: WorkflowNode, targetId: string): Set<string>;
+/**
+ * Collect all task nodes from a workflow tree (recursive).
+ */
+export declare function collectTaskNodes(node: WorkflowNode): TaskNode[];
+/**
+ * Find the nearest ancestor loop node for a given node ID.
+ * Returns the loop node ID if found, undefined otherwise.
+ */
+export declare function findAncestorLoopId(root: WorkflowNode, targetId: string): string | undefined;