avtc-pi-featyard 1.1.0

package/src/commands/workflow-commands.ts

@@ -0,0 +1,531 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Workflow commands — /fy:next and /fy:resume.
+ *
+ * Phase transition commands closely related to phase_ready.
+ */
+
+import * as fs from "node:fs";
+import os from "node:os";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { notifyAutoAgentBlocked, notifyAutoAgentUnblocked } from "../kanban/auto-agent/auto-agent-notify.js";
+import { log } from "../log.js";
+import { setActiveFeatureEnv } from "../phases/env-sync.js";
+import { isPhaseDone, PHASE_TO_SKILL, type Phase } from "../phases/phase-progression.js";
+import { completeFeature, transitionToFinishPhase, transitionToUatPhase } from "../phases/phase-transitions.js";
+import { type RouteResult, routeNext, toRouteConfig } from "../phases/workflow-router.js";
+import { NO_REVIEW_CONTEXT } from "../review/review-loops.js";
+import { getSettings, resolveReviewSkill } from "../settings/settings-ui.js";
+import { NO_AGENT_NAME, NO_FEATURE_STATE_OVERRIDE } from "../shared/workflow-refs.js";
+import type { WorkflowTransitionDeps } from "../shared/workflow-types.js";
+import { withCoordinator } from "../snippets/vendored/subscribe-to-dialog-coordinator.js";
+import {
+  archiveArtifactsOlderThan,
+  archiveDesignsOlderThan,
+  enumerateArchiveSet,
+  enumerateDesigns,
+} from "../state/archive-artifacts.js";
+import { ensureFeatyardJunction, resolveArchiveBase, resolveDesignsDirs } from "../state/artifact-junction.js";
+import type { FeatureSession } from "../state/feature-session.js";
+import {
+  DEFAULT_DIR,
+  deleteStateFile,
+  type ExpandSkillCommandFn,
+  stateFilePath as featureStateFilePath,
+  loadFeatureState,
+  markFeatureDone,
+  saveFeatureState,
+  scanActiveFeatures,
+  stateDir,
+  syncAndSaveFeatureState,
+} from "../state/feature-state.js";
+import { persistState } from "../state/state-persistence.js";
+import { worthNotesPointerFor } from "../state/worth-notes.js";
+import { NO_FEATURE_STATE, updateWidget } from "../ui/featyard-widget.js";
+import { formatFeatureInfo, openManageDialog } from "../ui/manage-features-dialog.js";
+
+export interface WorkflowCommandDeps extends WorkflowTransitionDeps {
+  expandSkillCommand: ExpandSkillCommandFn;
+  resetSessionTracking: () => void;
+  reconstructState: (ctx: ExtensionContext, handler: FeatureSession, stateFilePath: string | false | null) => void;
+  getAutoAgentCallback: () => import("../kanban/auto-agent/auto-agent-state-machine.js").AutoAgentCallback | null;
+  /** Reset the workflow tracker to fresh state (shared reset used by fy:reset). */
+  performWorkflowReset: () => void;
+}
+
+/** Resolve the skill for the next phase (review uses resolveReviewSkill; others map via PHASE_TO_SKILL) and dispatch it as a followUp user message. Shared by all phase-advance sites. */
+function dispatchPhaseSkill(pi: ExtensionAPI, nextPhase: string, expandSkillCommandFn: ExpandSkillCommandFn): void {
+  const skill =
+    nextPhase === "review"
+      ? resolveReviewSkill(getSettings())
+      : PHASE_TO_SKILL[nextPhase as keyof typeof PHASE_TO_SKILL];
+  if (skill)
+    pi.sendUserMessage(expandSkillCommandFn(`/skill:${skill}`, NO_FEATURE_STATE_OVERRIDE, NO_AGENT_NAME), {
+      deliverAs: "followUp",
+    });
+}
+
+/** Advance the handler to nextPhase and apply the full post-transition side effects (model override + state persist + widget update + skill dispatch). Shared by the next-phase command handlers when there is no slug-bound stage transition. */
+async function advanceToPhaseWithSideEffects(
+  handler: FeatureSession,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+  nextPhase: string,
+  applyModelOverrideForPhase: (pi: ExtensionAPI, ctx: ExtensionContext, stage: string) => Promise<void>,
+  expandSkillCommandFn: ExpandSkillCommandFn,
+): Promise<void> {
+  handler.setCurrentPhase(nextPhase as Phase);
+  await applyModelOverrideForPhase(pi, ctx, nextPhase);
+  persistState(pi, handler);
+  updateWidget(handler, NO_FEATURE_STATE);
+  dispatchPhaseSkill(pi, nextPhase, expandSkillCommandFn);
+}
+
+/**
+ * Dispatch a {@link RouteResult} for a slug-bound feature: completion → completeFeature;
+ * phase → uat/finish-aware stage transition; null → no-op (caller notifies).
+ */
+async function executeStageTransition(
+  ctx: ExtensionContext,
+  route: RouteResult,
+  slug: string,
+  deps: WorkflowCommandDeps,
+): Promise<void> {
+  const { pi, handler, expandSkillCommand, applyModelOverrideForPhase, handleReviewToUatTransition } = deps;
+
+  // Terminal: feature completes — clean up worktree, mark done, clear active, fire auto-agent.
+  if (route && "completed" in route) {
+    const featureState = handler.getActiveFeatureState();
+    if (featureState) {
+      await completeFeature(slug, featureState, {
+        pi,
+        ctx,
+        handler,
+        getAutoAgentCallback: deps.getAutoAgentCallback,
+      });
+    }
+    return;
+  }
+
+  if (!route) return;
+
+  const nextPhase = route.phase;
+  const currentPhase = handler.getWorkflowState()?.currentPhase;
+  if (currentPhase === "verify" && nextPhase !== "review") {
+    handler.setCurrentPhase("review");
+  }
+
+  if (nextPhase === "uat") {
+    const featureState = handler.getActiveFeatureState();
+    // Append the worth-notes pointer (existence + path) to the UAT handoff notify so it never stands
+    // alone (notifications are exclusive — manual /fy:next review→UAT site).
+    const pointer = worthNotesPointerFor(slug);
+    const notifyMessage = pointer
+      ? `Feature "${slug}" moved to UAT. Use /fy:next to advance.\n${pointer}`
+      : `Feature "${slug}" moved to UAT. Use /fy:next to advance.`;
+    await transitionToUatPhase(
+      ctx,
+      slug,
+      featureState,
+      {
+        pi,
+        handler,
+        applyModelOverrideForPhase,
+        getAutoAgentCallback: deps.getAutoAgentCallback,
+      },
+      {
+        kanbanNote: "review complete — UAT handoff",
+        notifyMessage,
+      },
+    );
+    return;
+  }
+
+  if (nextPhase === "finish") {
+    if (currentPhase === "verify") {
+      await handleReviewToUatTransition(ctx, slug, getSettings(), NO_REVIEW_CONTEXT);
+      return;
+    }
+    await transitionToFinishPhase(handler.getActiveFeatureState(), {
+      pi,
+      ctx,
+      handler,
+      applyModelOverrideForPhase,
+      expandSkillCommand,
+    });
+    return;
+  }
+
+  handler.setCurrentPhase(nextPhase);
+  const featureState = handler.getActiveFeatureState();
+  if (featureState) {
+    syncAndSaveFeatureState(featureState, handler);
+  }
+  persistState(pi, handler);
+  updateWidget(handler, NO_FEATURE_STATE);
+  await applyModelOverrideForPhase(pi, ctx, nextPhase);
+  dispatchPhaseSkill(pi, nextPhase, expandSkillCommand);
+}
+
+// ── Archive-command shared helpers ───────────────────────────────────────────
+// fy:archive-artifacts and fy:archive-designs share a parse → resolve → gate skeleton.
+// Extracted to keep jscpd clean (the two commands differ only in enumerate/archive fn + messages).
+
+type ArchiveCommandCtx = { ui: { notify(message: string, level: "info" | "warning" | "error"): void } };
+
+/** Parse the `<days>` arg shared by both archive commands. Returns null (after notifying) on invalid input. */
+function parseArchiveDays(args: string | undefined, ctx: ArchiveCommandCtx, commandLabel: string): number | null {
+  const days = Number.parseInt((args ?? "").trim(), 10);
+  if (Number.isNaN(days) || days < 0) {
+    ctx.ui.notify(`Usage: /${commandLabel} <days> (archive older than N days)`, "error");
+    return null;
+  }
+  return days;
+}
+
+/** Resolve the junction + archive base shared by both archive commands. */
+function resolveArchiveContext(): { jr: ReturnType<typeof ensureFeatyardJunction>; archiveBase: string } {
+  const jr = ensureFeatyardJunction(
+    process.cwd(),
+    getSettings().branchPolicy ?? "current-branch",
+    process.env.PI_FY_HOME ?? os.homedir(),
+    "rename",
+  );
+  return { jr, archiveBase: resolveArchiveBase(jr) };
+}
+
+export function registerWorkflowCommands(deps: WorkflowCommandDeps): void {
+  const {
+    pi,
+    handler,
+    expandSkillCommand,
+    applyModelOverrideForPhase,
+    resetSessionTracking,
+    reconstructState,
+    performWorkflowReset,
+  } = deps;
+
+  pi.registerCommand("fy:next", {
+    description: "Complete current workflow stage and advance to next (skips if preconditions not met)",
+    async handler(_args, ctx) {
+      const ws = handler.getWorkflowState();
+      if (!ws?.currentPhase) {
+        if (ctx.hasUI) ctx.ui.notify("No active workflow. Start with /skill:fy-design or /fy:resume.", "warning");
+        return;
+      }
+      const currentPhase = ws.currentPhase;
+      const slug = handler.getActiveFeatureSlug();
+      const settings = getSettings();
+      const featureState = handler.getActiveFeatureState();
+      // In the pointer model the current phase is the active pointer; it is "done"
+      // only when the feature is completed. Derive from the feature state if present.
+      const phaseDone = featureState
+        ? isPhaseDone(
+            { currentPhase: featureState.workflow.currentPhase, completedAt: featureState.completedAt },
+            currentPhase,
+          )
+        : false;
+
+      // Resolve the next route. When the current phase is not yet done, let the
+      // machine route one step (uat-aware); when already done, route from the
+      // pointer directly. Both paths yield a RouteResult that may be terminal.
+      const routeConfig = toRouteConfig(settings);
+      const route: RouteResult = phaseDone
+        ? routeNext(currentPhase, routeConfig)
+        : handler.completeCurrentWorkflowPhase(routeConfig);
+
+      if (!route) {
+        if (ctx.hasUI) ctx.ui.notify(`Workflow ended at ${currentPhase}. No more phases.`, "info");
+        return;
+      }
+
+      if ("completed" in route) {
+        // Terminal — feature completes (e.g. fy:next from uat in after-finish mode,
+        // or from finish in after-review/off mode). Replicates the former uat-accept
+        // completion path exactly so uat-accept could be dropped.
+        if (ctx.hasUI) ctx.ui.notify(`✓ ${currentPhase} completed. Feature done.`, "info");
+        if (slug && featureState) {
+          await completeFeature(slug, featureState, {
+            pi,
+            ctx,
+            handler,
+            getAutoAgentCallback: deps.getAutoAgentCallback,
+          });
+        } else {
+          persistState(pi, handler);
+          updateWidget(handler, NO_FEATURE_STATE);
+        }
+        return;
+      }
+
+      // Non-terminal phase advance.
+      if (ctx.hasUI) ctx.ui.notify(`✓ ${currentPhase} completed. Advancing to ${route.phase}...`, "info");
+      if (slug) {
+        await executeStageTransition(ctx, route, slug, deps);
+      } else {
+        await advanceToPhaseWithSideEffects(
+          handler,
+          ctx,
+          pi,
+          route.phase,
+          applyModelOverrideForPhase,
+          expandSkillCommand,
+        );
+      }
+    },
+  });
+
+  pi.registerCommand("fy:resume", {
+    description: "List active workflows and load the selected one into the current session",
+    async handler(_args, ctx) {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/fy:resume requires interactive mode.", "error");
+        return;
+      }
+
+      while (true) {
+        const currentFeatures = scanActiveFeatures(DEFAULT_DIR);
+        if (currentFeatures.length === 0) {
+          ctx.ui.notify("No active workflows found.", "info");
+          return;
+        }
+
+        const featureOptions = currentFeatures.map((f) => `Continue: ${f.featureSlug} — ${formatFeatureInfo(f)}`);
+        const allOptions = [...featureOptions, "Skip", "Manage state files"];
+        const count = currentFeatures.length;
+        const activeSlug = handler.getActiveFeatureSlug();
+        if (activeSlug) notifyAutoAgentBlocked(activeSlug);
+        const choice = await withCoordinator(() =>
+          ctx.ui.select(`Found ${count} active feature${count > 1 ? "s" : ""}:`, allOptions),
+        );
+        if (activeSlug) notifyAutoAgentUnblocked(activeSlug);
+
+        if (!choice) return;
+
+        const featureIdx = featureOptions.indexOf(choice);
+        if (featureIdx >= 0) {
+          const selectedFeature = currentFeatures[featureIdx];
+          if (selectedFeature) {
+            const featureState = loadFeatureState(selectedFeature.featureSlug, DEFAULT_DIR);
+            const lastSession = featureState?.sessionFiles?.at(-1);
+            if (lastSession && fs.existsSync(lastSession)) {
+              setActiveFeatureEnv(selectedFeature.featureSlug);
+              await ctx.switchSession(lastSession, {
+                withSession: async (newCtx) => {
+                  newCtx.ui.notify(`Resumed session for: ${selectedFeature.featureSlug}`, "info");
+                },
+              });
+              return;
+            }
+          }
+          if (selectedFeature) {
+            setActiveFeatureEnv(selectedFeature.featureSlug);
+          }
+          reconstructState(
+            ctx,
+            handler,
+            selectedFeature ? featureStateFilePath(selectedFeature.featureSlug, DEFAULT_DIR) : null,
+          );
+          resetSessionTracking();
+          persistState(pi, handler);
+          updateWidget(handler, NO_FEATURE_STATE);
+
+          const phase = handler.getWorkflowState()?.currentPhase ?? "unknown";
+          ctx.ui.notify(`Loaded workflow: ${selectedFeature?.featureSlug ?? "unknown"} (${phase})`, "info");
+          return;
+        }
+
+        if (choice === "Skip") return;
+
+        if (choice === "Manage state files") {
+          const manageResult = await openManageDialog(currentFeatures, ctx);
+          if (manageResult) {
+            for (const slug of manageResult.slugs) {
+              if (manageResult.action === "mark_completed") {
+                const state = loadFeatureState(slug, DEFAULT_DIR);
+                if (state) saveFeatureState(markFeatureDone(state), DEFAULT_DIR);
+              } else {
+                deleteStateFile(slug, DEFAULT_DIR);
+              }
+            }
+          }
+          continue;
+        }
+        ctx.ui.notify("Unrecognized selection.", "warning");
+        break;
+      }
+    },
+  });
+
+  pi.registerCommand("fy:archive-artifacts", {
+    description: "Archive artifacts older than <days> days (manual sweep). Usage: /fy:archive-artifacts <days>",
+    async handler(args, ctx) {
+      // 1. Parse <days> (required, non-negative integer).
+      const days = parseArchiveDays(args, ctx, "fy:archive-artifacts");
+      if (days === null) return;
+
+      // 2. Resolve the live store + archive base; enumerate what's stale at this threshold.
+      const { jr, archiveBase } = resolveArchiveContext();
+      const excludeSlug = handler.getActiveFeatureSlug();
+      const { stale } = enumerateArchiveSet({
+        externalDir: jr.externalDir,
+        archiveBase,
+        maxAgeDays: days,
+        excludeSlug,
+      });
+
+      // 3. Empty short-circuit: nothing stale → notify, NO confirm gate (#5).
+      if (stale.length === 0) {
+        ctx.ui.notify("Nothing to archive.", "info");
+        return;
+      }
+
+      // 4. Confirm gate — headless-safe (#11).
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/fy:archive-artifacts requires interactive mode to confirm.", "info");
+        return;
+      }
+      // Detect in-flight (active, non-completed) features among the stale set.
+      const inFlight = scanActiveFeatures(stateDir())
+        .map((s) => s.featureSlug)
+        .filter((slug) => stale.some((g) => g.key === slug));
+      const inFlightNote =
+        inFlight.length > 0
+          ? `\n\n⚠️ In-flight features that would be affected: ${inFlight.join(", ")}. Archiving hides their artifacts from .featyard — resume would be artifact-degraded.`
+          : "";
+      // Count members + groups for the confirm message (what the user is about to archive).
+      const memberCount = stale.reduce((n, g) => n + g.members.length, 0);
+      const ok = await withCoordinator(() =>
+        ctx.ui.confirm(
+          `Archive artifacts older than ${days} day${days === 1 ? "" : "s"}?`,
+          `This relocates ${memberCount} artifact${memberCount === 1 ? "" : "s"} across ${stale.length} group${stale.length === 1 ? "" : "s"} out of .featyard into the archive. Reversible by moving them back.${inFlightNote}`,
+        ),
+      );
+      if (!ok) {
+        ctx.ui.notify("Archive cancelled — no changes made.", "info");
+        return;
+      }
+
+      // 5. Archive. archiveArtifactsOlderThan re-enumerates internally (idempotent + skip-if-missing
+      //    move primitive → worst case a tiny TOCTOU no-op; never corrupts).
+      const result = await archiveArtifactsOlderThan({
+        externalDir: jr.externalDir,
+        archiveBase,
+        days,
+        excludeSlug,
+      });
+      // Report at the group level, broken down by type (slug groups vs date-fallback groups). A
+      // group counts only when ALL its members moved (all-or-nothing unit) — so a fully-failed
+      // group is NOT reported as archived. The feature-state file is a member of its slug's group
+      // (co-archived when the group's newest mtime — across ALL members including the state file
+      // is stale; skipped if missing), so it needs no separate count. Errors are separate (logged).
+      const slugGroups = result.archivedSlugGroups;
+      const dateFallbackGroups = result.archivedDateFallbackGroups;
+      const errMsg =
+        result.errors.length > 0
+          ? ` (${result.errors.length} error${result.errors.length === 1 ? "" : "s"} — see log)`
+          : "";
+      ctx.ui.notify(
+        `Archived ${slugGroups} slug${slugGroups === 1 ? "" : "s"} + ${dateFallbackGroups} date-fallback${dateFallbackGroups === 1 ? "" : "s"}.${errMsg}`,
+        "info",
+      );
+      for (const err of result.errors) {
+        log.warn(`[fy:archive-artifacts] ${err}`);
+      }
+    },
+  });
+
+  // --- fy:archive-designs command ---
+  // Sweeps BOTH design-doc roots: the out-of-repo `.featyard/designs` (local mode, via the junction) and
+  // the in-repo `docs/featyard/designs` (committed mode). Mirrors /fy:archive-artifacts (parse → enumerate
+  // → empty short-circuit → confirm gate → archive → report).
+  pi.registerCommand("fy:archive-designs", {
+    description:
+      "Archive design docs older than <days> days (sweeps .featyard/designs and docs/featyard/designs). Usage: /fy:archive-designs <days>",
+    async handler(args, ctx) {
+      // 1. Parse <days> (required, non-negative integer).
+      const days = parseArchiveDays(args, ctx, "fy:archive-designs");
+      if (days === null) return;
+
+      // 2. Resolve BOTH roots + the archive base; enumerate what's stale at this threshold.
+      const { jr, archiveBase } = resolveArchiveContext();
+      const designsDirs = resolveDesignsDirs(jr.externalDir, process.cwd());
+      const excludeSlug = handler.getActiveFeatureSlug();
+      const { stale } = enumerateDesigns({
+        designsDirs,
+        archiveBase,
+        maxAgeDays: days,
+        excludeSlug,
+      });
+
+      // 3. Empty short-circuit: nothing stale → notify, NO confirm gate.
+      if (stale.length === 0) {
+        ctx.ui.notify("Nothing to archive.", "info");
+        return;
+      }
+
+      // 4. Confirm gate — headless-safe.
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/fy:archive-designs requires interactive mode to confirm.", "info");
+        return;
+      }
+      // Detect in-flight (active, non-completed) features among the stale set.
+      const inFlightSlugs = new Set(
+        scanActiveFeatures(stateDir())
+          .map((s) => s.featureSlug)
+          .filter((slug): slug is string => Boolean(slug)),
+      );
+      const inFlight = stale.map((m) => m.slug).filter((slug) => inFlightSlugs.has(slug));
+      const inFlightNote =
+        inFlight.length > 0
+          ? `\n\n⚠️ In-flight features that would be affected: ${[...new Set(inFlight)].join(", ")}. Archiving hides their design doc — resume would be degraded.`
+          : "";
+      const count = stale.length;
+      const ok = await withCoordinator(() =>
+        ctx.ui.confirm(
+          `Archive design docs older than ${days} day${days === 1 ? "" : "s"}?`,
+          `This relocates ${count} design doc${count === 1 ? "" : "s"} from .featyard/designs and docs/featyard/designs into the archive. Reversible by moving them back.${inFlightNote}`,
+        ),
+      );
+      if (!ok) {
+        ctx.ui.notify("Archive cancelled — no changes made.", "info");
+        return;
+      }
+
+      // 5. Archive. archiveDesignsOlderThan re-enumerates internally (idempotent + skip-if-missing
+      //    move primitive → worst case a tiny TOCTOU no-op; never corrupts).
+      const result = await archiveDesignsOlderThan({
+        designsDirs,
+        archiveBase,
+        days,
+        excludeSlug,
+      });
+      const errMsg =
+        result.errors.length > 0
+          ? ` (${result.errors.length} error${result.errors.length === 1 ? "" : "s"} — see log)`
+          : "";
+      ctx.ui.notify(
+        `Archived ${result.archivedCount} design doc${result.archivedCount === 1 ? "" : "s"}.${errMsg}`,
+        "info",
+      );
+      for (const err of result.errors) {
+        log.warn(`[fy:archive-designs] ${err}`);
+      }
+    },
+  });
+
+  // --- fy:reset command ---
+  pi.registerCommand("fy:reset", {
+    description: "Reset workflow tracker to fresh state for a new task",
+    async handler(_args, ctx) {
+      globalThis.__piCtx?.refresh(ctx);
+      performWorkflowReset();
+      const guard = globalThis.__piCtx;
+      if (guard?.hasUI && guard?.ui?.notify) {
+        guard.ui.notify("Workflow reset. Ready for a new task.", "info");
+      }
+    },
+  });
+}