@tianhai/pi-workflow-kit 0.5.3 → 0.7.0

package/extensions/workflow-monitor/workflow-handler.ts

@@ -1,363 +0,0 @@
-import type { SessionEntry } from "@mariozechner/pi-coding-agent";
-import type { PlanTrackerDetails, PlanTrackerTask } from "../plan-tracker.js";
-import { DebugMonitor, type DebugViolation } from "./debug-monitor";
-import { isSourceFile } from "./heuristics";
-import { isInvestigationCommand, isInvestigationToolCall } from "./investigation";
-import { TddMonitor, type TddPhase, type TddViolation } from "./tdd-monitor";
-import { parseTestCommand, parseTestResult } from "./test-runner";
-import { VerificationMonitor, type VerificationViolation } from "./verification-monitor";
-import { type Phase, type PhaseStatus, WorkflowTracker, type WorkflowTrackerState } from "./workflow-tracker";
-
-export type Violation = TddViolation | DebugViolation;
-
-export interface ToolCallResult {
-  violation: Violation | null;
-}
-
-export interface SuperpowersStateSnapshot {
-  workflow: WorkflowTrackerState;
-  tdd: {
-    phase: TddPhase;
-    testFiles: string[];
-    sourceFiles: string[];
-    redVerificationPending: boolean;
-    nonCodeMode: boolean;
-  };
-  debug: {
-    active: boolean;
-    investigated: boolean;
-    fixAttempts: number;
-  };
-  verification: {
-    verified: boolean;
-    verificationWaived: boolean;
-  };
-}
-
-export type SuperpowersStatePatch = {
-  workflow?: Partial<WorkflowTrackerState> & {
-    phases?: Partial<Record<Phase, PhaseStatus>>;
-    artifacts?: Partial<Record<Phase, string | null>>;
-    prompted?: Partial<Record<Phase, boolean>>;
-  };
-  tdd?: Partial<SuperpowersStateSnapshot["tdd"]>;
-  debug?: Partial<SuperpowersStateSnapshot["debug"]>;
-  verification?: Partial<SuperpowersStateSnapshot["verification"]>;
-};
-
-export const TDD_DEFAULTS = {
-  phase: "idle" as TddPhase,
-  testFiles: [] as string[],
-  sourceFiles: [] as string[],
-  redVerificationPending: false,
-  nonCodeMode: false,
-};
-
-export const DEBUG_DEFAULTS = {
-  active: false,
-  investigated: false,
-  fixAttempts: 0,
-};
-
-export const VERIFICATION_DEFAULTS = {
-  verified: false,
-  verificationWaived: false,
-};
-
-export interface WorkflowHandler {
-  handleToolCall(toolName: string, input: Record<string, unknown>): ToolCallResult;
-  handleReadOrInvestigation(toolName: string, path: string): void;
-  handleBashResult(command: string, output: string, exitCode: number | undefined): void;
-  /** @internal Used in tests; will be wired to bash events in future */
-  handleBashInvestigation(command: string): void;
-  isDebugActive(): boolean;
-  getDebugFixAttempts(): number;
-  getTddPhase(): string;
-  getWidgetText(): string;
-  getTddState(): ReturnType<TddMonitor["getState"]>;
-  checkCommitGate(command: string): VerificationViolation | null;
-  recordVerificationWaiver(): void;
-  restoreTddState(phase: TddPhase, testFiles: string[], sourceFiles: string[], redVerificationPending?: boolean): void;
-  handleInputText(text: string): boolean;
-  handleFileWritten(path: string): boolean;
-  handlePlanTrackerToolCall(input: Record<string, unknown>): boolean;
-  handlePlanTrackerToolResult(details: PlanTrackerDetails | undefined): boolean;
-  getWorkflowState(): WorkflowTrackerState | null;
-  getFullState(): SuperpowersStateSnapshot;
-  setFullState(snapshot: SuperpowersStatePatch): void;
-  restoreWorkflowStateFromBranch(branch: SessionEntry[]): void;
-  markWorkflowPrompted(phase: Phase): boolean;
-  completeCurrentWorkflowPhase(): boolean;
-  completeWorkflowPhase(phase: Phase): boolean;
-  advanceWorkflowTo(phase: Phase): boolean;
-  skipWorkflowPhases(phases: Phase[]): boolean;
-  handleSkillFileRead(path: string): boolean;
-  resetState(): void;
-}
-
-function deriveNonCodeMode(tasks: PlanTrackerTask[]): boolean {
-  const activeTask = tasks.find((task) => task.status === "in_progress");
-  return activeTask?.type === "non-code";
-}
-
-function areAllTasksTerminal(tasks: PlanTrackerTask[]): boolean {
-  return tasks.length > 0 && tasks.every((task) => task.status === "complete" || task.status === "blocked");
-}
-
-export function createWorkflowHandler(): WorkflowHandler {
-  const tdd = new TddMonitor();
-  const debug = new DebugMonitor();
-  const verification = new VerificationMonitor();
-  const tracker = new WorkflowTracker();
-  let debugFailStreak = 0;
-
-  return {
-    handleToolCall(toolName: string, input: Record<string, unknown>): ToolCallResult {
-      // Track investigation from tool calls (LSP, kota, web search)
-      if (isInvestigationToolCall(toolName, input)) {
-        debug.onInvestigation();
-      }
-
-      if (toolName === "write" || toolName === "edit") {
-        const path = input.path as string | undefined;
-        if (path) {
-          if (isSourceFile(path)) {
-            verification.onSourceWritten();
-          }
-
-          // Debug violations take precedence, and when debug is active we don't
-          // additionally enforce TDD write-order violations.
-          if (debug.isActive() && isSourceFile(path)) {
-            const debugViolation = debug.onSourceWritten(path);
-            return { violation: debugViolation };
-          }
-
-          const tddViolation = tdd.onFileWritten(path);
-          return { violation: tddViolation };
-        }
-      }
-      return { violation: null };
-    },
-
-    handleReadOrInvestigation(toolName: string, _path: string): void {
-      if (toolName === "read") {
-        debug.onInvestigation();
-      }
-    },
-
-    handleBashResult(command: string, output: string, exitCode: number | undefined): void {
-      if (isInvestigationCommand(command)) {
-        debug.onInvestigation();
-      }
-
-      if (/\bgit\s+commit\b/.test(command)) {
-        debugFailStreak = 0;
-        tdd.onCommit();
-        debug.onCommit();
-        return;
-      }
-
-      if (parseTestCommand(command)) {
-        const passed = parseTestResult(output, exitCode);
-        if (passed !== null) {
-          if (passed) {
-            verification.recordVerification();
-          } else {
-            verification.reset();
-          }
-
-          const excludeFromDebug = !passed && tdd.getPhase() === "red-pending";
-
-          tdd.onTestResult(passed);
-
-          if (passed) {
-            debugFailStreak = 0;
-            debug.onTestPassed();
-          } else if (!excludeFromDebug) {
-            debugFailStreak += 1;
-            const tddPhase = tdd.getPhase();
-            if (debugFailStreak >= 1 && tddPhase === "idle") {
-              debug.onTestFailed();
-            }
-          }
-        }
-      }
-    },
-
-    handleBashInvestigation(command: string): void {
-      if (isInvestigationCommand(command)) {
-        debug.onInvestigation();
-      }
-    },
-
-    isDebugActive(): boolean {
-      return debug.isActive();
-    },
-
-    getDebugFixAttempts(): number {
-      return debug.getFixAttempts();
-    },
-
-    getTddPhase(): string {
-      return tdd.getPhase();
-    },
-
-    getWidgetText(): string {
-      const parts: string[] = [];
-
-      const phase = tdd.getPhase();
-      if (phase !== "idle") {
-        parts.push(`TDD: ${phase.toUpperCase()}`);
-      }
-
-      if (debug.isActive()) {
-        parts.push("Debug: ACTIVE");
-      }
-
-      return parts.join(" | ");
-    },
-
-    getTddState() {
-      return tdd.getState();
-    },
-
-    checkCommitGate(command: string) {
-      return verification.checkCommitGate(command);
-    },
-
-    recordVerificationWaiver() {
-      verification.recordVerificationWaiver();
-    },
-
-    restoreTddState(phase: TddPhase, testFiles: string[], sourceFiles: string[], redVerificationPending = false) {
-      tdd.setState(phase, testFiles, sourceFiles, redVerificationPending);
-    },
-
-    handleInputText(text: string) {
-      return tracker.onInputText(text);
-    },
-
-    handleFileWritten(path: string) {
-      return tracker.onFileWritten(path);
-    },
-
-    handlePlanTrackerToolCall(input: Record<string, unknown>) {
-      if (input.action === "init") {
-        tdd.setNonCodeMode(false);
-        return tracker.onPlanTrackerInit();
-      }
-      return false;
-    },
-
-    handlePlanTrackerToolResult(details: PlanTrackerDetails | undefined) {
-      if (!details) return false;
-
-      let changed = false;
-      const nextNonCodeMode = deriveNonCodeMode(details.tasks);
-      if (tdd.getState().nonCodeMode !== nextNonCodeMode) {
-        tdd.setNonCodeMode(nextNonCodeMode);
-        changed = true;
-      }
-
-      if (areAllTasksTerminal(details.tasks) && tracker.getState().currentPhase === "execute") {
-        changed = tracker.completeCurrent() || changed;
-      }
-
-      return changed;
-    },
-
-    getWorkflowState() {
-      return tracker.getState();
-    },
-
-    getFullState() {
-      return {
-        workflow: tracker.getState(),
-        tdd: tdd.getState(),
-        debug: debug.getState(),
-        verification: verification.getState(),
-      };
-    },
-
-    setFullState(snapshot: SuperpowersStatePatch) {
-      if (snapshot.workflow) {
-        const defaultWorkflow = new WorkflowTracker().getState();
-        tracker.setState({
-          ...defaultWorkflow,
-          ...snapshot.workflow,
-          phases: { ...defaultWorkflow.phases, ...snapshot.workflow.phases },
-          artifacts: { ...defaultWorkflow.artifacts, ...snapshot.workflow.artifacts },
-          prompted: { ...defaultWorkflow.prompted, ...snapshot.workflow.prompted },
-        });
-      }
-      if (snapshot.tdd) {
-        const tddState = { ...TDD_DEFAULTS, ...snapshot.tdd };
-        tdd.setState(
-          tddState.phase,
-          tddState.testFiles,
-          tddState.sourceFiles,
-          tddState.redVerificationPending,
-          tddState.nonCodeMode,
-        );
-      }
-      if (snapshot.debug) {
-        debug.setState({ ...DEBUG_DEFAULTS, ...snapshot.debug });
-      }
-      if (snapshot.verification) {
-        verification.setState({ ...VERIFICATION_DEFAULTS, ...snapshot.verification });
-      }
-      debugFailStreak = 0;
-    },
-
-    restoreWorkflowStateFromBranch(branch: SessionEntry[]) {
-      const state = WorkflowTracker.reconstructFromBranch(branch);
-      if (state) {
-        tracker.setState(state);
-      }
-    },
-
-    markWorkflowPrompted(phase: Phase) {
-      return tracker.markPrompted(phase);
-    },
-
-    completeCurrentWorkflowPhase() {
-      return tracker.completeCurrent();
-    },
-
-    completeWorkflowPhase(phase: Phase) {
-      return tracker.completePhase(phase);
-    },
-
-    advanceWorkflowTo(phase) {
-      return tracker.advanceTo(phase);
-    },
-
-    skipWorkflowPhases(phases) {
-      return tracker.skipPhases(phases);
-    },
-
-    handleSkillFileRead(path: string) {
-      return tracker.onSkillFileRead(path);
-    },
-
-    resetState() {
-      const freshState: SuperpowersStateSnapshot = {
-        workflow: new WorkflowTracker().getState(),
-        tdd: { ...TDD_DEFAULTS, testFiles: [], sourceFiles: [] },
-        debug: { ...DEBUG_DEFAULTS },
-        verification: { ...VERIFICATION_DEFAULTS },
-      };
-
-      tracker.setState(freshState.workflow);
-      tdd.setState(
-        freshState.tdd.phase,
-        freshState.tdd.testFiles,
-        freshState.tdd.sourceFiles,
-        freshState.tdd.redVerificationPending,
-      );
-      debug.setState(freshState.debug);
-      verification.setState(freshState.verification);
-      debugFailStreak = 0;
-    },
-  };
-}

package/extensions/workflow-monitor/workflow-next-completions.ts

@@ -1,68 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { AutocompleteItem } from "@mariozechner/pi-tui";
-
-const WORKFLOW_NEXT_PHASES = ["brainstorm", "plan", "execute", "finalize"] as const;
-const ARTIFACT_SUFFIX_BY_PHASE = {
-  brainstorm: null,
-  plan: "-design.md",
-  execute: "-implementation.md",
-  finalize: "-implementation.md",
-} as const;
-
-type WorkflowNextPhase = (typeof WORKFLOW_NEXT_PHASES)[number];
-
-function getPhaseCompletions(prefix: string): AutocompleteItem[] | null {
-  const normalized = prefix.replace(/^\s+/, "");
-  const firstToken = normalized.split(/\s+/, 1)[0] ?? "";
-  const completingFirstArg = normalized.length === 0 || !/\s/.test(normalized);
-
-  if (completingFirstArg || !WORKFLOW_NEXT_PHASES.includes(firstToken as WorkflowNextPhase)) {
-    const phasePrefix = completingFirstArg ? normalized : firstToken;
-    const items = WORKFLOW_NEXT_PHASES.filter((phase) => phase.startsWith(phasePrefix)).map((phase) => ({
-      value: phase,
-      label: phase,
-    }));
-    return items.length > 0 ? items : null;
-  }
-
-  return null;
-}
-
-function listArtifactsForPhase(phase: WorkflowNextPhase, typedPrefix: string): AutocompleteItem[] | null {
-  const suffix = ARTIFACT_SUFFIX_BY_PHASE[phase];
-  if (!suffix) return null;
-
-  const plansDir = path.join(process.cwd(), "docs", "plans");
-  if (!fs.existsSync(plansDir)) return null;
-
-  try {
-    const items = fs
-      .readdirSync(plansDir)
-      .filter((name) => name.endsWith(suffix))
-      .map((name) => path.join("docs", "plans", name))
-      .filter((relPath) => relPath.startsWith(typedPrefix))
-      .map((relPath) => ({ value: `${phase} ${relPath}`, label: relPath }));
-
-    return items.length > 0 ? items : null;
-  } catch {
-    return null;
-  }
-}
-
-export async function getWorkflowNextCompletions(prefix: string): Promise<AutocompleteItem[] | null> {
-  const phaseCompletions = getPhaseCompletions(prefix);
-  if (phaseCompletions) return phaseCompletions;
-
-  const normalized = prefix.replace(/^\s+/, "");
-  const match = normalized.match(/^(\S+)(?:\s+(.*))?$/);
-  const phase = match?.[1] as WorkflowNextPhase | undefined;
-  const artifactPrefix = match?.[2] ?? "";
-  const startingSecondArg = /\s$/.test(prefix) || artifactPrefix.length > 0;
-
-  if (phase && WORKFLOW_NEXT_PHASES.includes(phase) && startingSecondArg) {
-    return listArtifactsForPhase(phase, artifactPrefix);
-  }
-
-  return null;
-}

package/extensions/workflow-monitor/workflow-next-state.ts

@@ -1,112 +0,0 @@
-/**
- * Pure helper functions for /workflow-next handoff validation and derived state.
- *
- * These functions have no side effects and no dependencies on the extension runtime,
- * making them straightforward to test and reason about.
- */
-
-import { type Phase, type PhaseStatus, WORKFLOW_PHASES, type WorkflowTrackerState } from "./workflow-tracker";
-
-/** Map of each phase to its immediate next phase (null for finalize). */
-const NEXT_PHASE: Record<Phase, Phase | null> = {
-  brainstorm: "plan",
-  plan: "execute",
-  execute: "finalize",
-  finalize: null,
-};
-
-/**
- * Validate whether a `/workflow-next` request is allowed.
- *
- * Rules:
- * - A current phase must exist in the workflow state.
- * - The current phase must have status exactly "complete".
- * - The requested phase must be the immediate next phase.
- *
- * Returns `null` if the handoff is valid, or an error message string.
- */
-export function validateNextWorkflowPhase(currentState: WorkflowTrackerState, requestedPhase: Phase): string | null {
-  const current = currentState.currentPhase;
-
-  if (!current) {
-    return "No workflow phase is active. Start a workflow first or use /workflow-reset.";
-  }
-
-  const next = NEXT_PHASE[current];
-  if (next === null) {
-    return `Cannot hand off: ${current} is the final phase. Use /workflow-reset for a new task.`;
-  }
-
-  const currentStatus = currentState.phases[current];
-
-  // Same-phase handoff
-  if (requestedPhase === current) {
-    return `Cannot hand off to ${requestedPhase} from ${current}. Use /workflow-reset for a new task or continue in this session.`;
-  }
-
-  // Backward handoff
-  const currentIdx = WORKFLOW_PHASES.indexOf(current);
-  const requestedIdx = WORKFLOW_PHASES.indexOf(requestedPhase);
-  if (requestedIdx < currentIdx) {
-    return `Cannot hand off to ${requestedPhase} from ${current}: backward transitions are not allowed.`;
-  }
-
-  // Current phase not complete
-  if (currentStatus !== "complete") {
-    return `Cannot hand off to ${requestedPhase} because ${current} is not complete (status: ${currentStatus}).`;
-  }
-
-  // Direct jump (skipping intermediate phases)
-  if (requestedPhase !== next) {
-    return `Cannot hand off to ${requestedPhase} from ${current}. /workflow-next only supports the immediate next phase: ${next}.`;
-  }
-
-  return null;
-}
-
-/**
- * Derive the workflow state snapshot for a new session created by `/workflow-next`.
- *
- * Rules:
- * - All phases before the requested phase are marked "complete".
- * - The requested phase is marked "active".
- * - All phases after the requested phase are marked "pending".
- * - currentPhase is set to the requested phase.
- * - Artifacts and prompted flags are preserved for earlier phases.
- */
-export function deriveWorkflowHandoffState(
-  currentState: WorkflowTrackerState,
-  requestedPhase: Phase,
-): WorkflowTrackerState {
-  const requestedIdx = WORKFLOW_PHASES.indexOf(requestedPhase);
-
-  const newPhases = { ...currentState.phases };
-  const newArtifacts = { ...currentState.artifacts };
-  const newPrompted = { ...currentState.prompted };
-
-  for (let i = 0; i < WORKFLOW_PHASES.length; i++) {
-    const phase = WORKFLOW_PHASES[i]!;
-
-    if (i < requestedIdx) {
-      // Earlier phases: mark complete, preserve artifacts/prompted
-      newPhases[phase] = "complete";
-    } else if (i === requestedIdx) {
-      // Target phase: active
-      newPhases[phase] = "active";
-      newArtifacts[phase] = currentState.artifacts[phase] ?? null;
-      newPrompted[phase] = false;
-    } else {
-      // Later phases: pending, clear artifacts/prompted
-      newPhases[phase] = "pending";
-      newArtifacts[phase] = null;
-      newPrompted[phase] = false;
-    }
-  }
-
-  return {
-    phases: newPhases as Record<Phase, PhaseStatus>,
-    currentPhase: requestedPhase,
-    artifacts: newArtifacts as Record<Phase, string | null>,
-    prompted: newPrompted as Record<Phase, boolean>,
-  };
-}