avtc-pi-featyard 1.1.0

package/src/settings/settings-ui.ts

@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Settings extension — the single featyard settings handle.
+ *
+ * Registers the `/fy:settings` command + modal via avtc-pi-settings-ui's {@link registerSettingsCommand}
+ * (the sole public entry point; it creates the typed handle internally) and exposes typed accessors.
+ * `pi` is only available at activation, so the handle is created lazily by {@link initFeatyardSettings}
+ * (called from the extension's activate function); all reads happen at runtime, after activation.
+ *
+ * featyard's own settings code here is intentionally thin: a typed `getSettings` cast over the
+ * handle's buffer (settings-ui already caches + fills defaults — no second cache), an `updateSetting`
+ * wrapper that syncs the fork-mode env var, and the clampFn + fork-mode helpers. model-overrides
+ * (the legacy shared-settings.json config for model routing) are re-exported unchanged.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerSettingsCommand, type SettingsHandle } from "avtc-pi-settings-ui";
+import { log } from "../log.js";
+import { PiCtx } from "../shared/types.js";
+import { subscribeToDialogCoordinator } from "../snippets/vendored/subscribe-to-dialog-coordinator.js";
+import { clampFeatyardSettings, FEATYARD_SCHEMA } from "./settings-schema.js";
+import type { FeatyardSettings } from "./settings-types.js";
+
+let handle: SettingsHandle<FeatyardSettings> | undefined;
+
+/** Required keys in FeatyardSettings (all non-optional interface fields). */
+const REQUIRED_SETTINGS_KEYS = FEATYARD_SCHEMA.settings.map((s) => s.id);
+
+/**
+ * Cast the handle's `Record<string, unknown>` buffer to {@link FeatyardSettings}.
+ * Validates that all required keys are present; logs a warning if any are missing. A pure cast +
+ * dev-time check — no runtime transformation, nothing to memoize.
+ */
+function asSettings(raw: Record<string, unknown>): FeatyardSettings {
+  const missing = REQUIRED_SETTINGS_KEYS.filter((key) => !(key in raw));
+  if (missing.length > 0) {
+    log.warn(`[settings] asSettings: missing keys: ${missing.join(", ")} — returning partial object`);
+  }
+  return raw as unknown as FeatyardSettings;
+}
+
+/** @internal Test-only export for validating asSettings warning path */
+export { asSettings as _asSettings };
+
+// ---------------------------------------------------------------------------
+// Mock-DI hooks (tests inject a settings source instead of the real handle)
+// ---------------------------------------------------------------------------
+
+/** Test-only override for the settings read (DI/mock pattern). */
+let _getSettingsOverride: (() => FeatyardSettings) | null = null;
+
+/** Test-only override for the settings write (DI/mock pattern). When set, production
+ *  `updateSetting` calls (e.g. resolve-base-branch persisting baseBranch) mutate the mock holder
+ *  instead of the real handle — so writes stay visible to reads and don't throw when no handle
+ *  has been activated. The mock is the single source of truth for both reads and writes. Pass
+ *  `null` to restore the real-handle write path. */
+let _updateSettingsOverride:
+  | ((key: string, value: unknown, opts: { level?: "session" | "project" | "global" } | null) => void)
+  | null = null;
+
+/** Test-only: inject a mock settings source for reads (pass `null` to restore the real handle). */
+export function _setGetSettings(fn: (() => FeatyardSettings) | null): void {
+  _getSettingsOverride = fn;
+}
+
+/** Test-only: inject a mock settings writer (pass `null` to restore the real-handle write path). */
+export function _setUpdateSettingsOverride(
+  fn: ((key: string, value: unknown, opts: { level?: "session" | "project" | "global" } | null) => void) | null,
+): void {
+  _updateSettingsOverride = fn;
+}
+
+// ---------------------------------------------------------------------------
+// Typed accessors
+// ---------------------------------------------------------------------------
+
+/** Get typed featyard settings (settings-ui's buffer is the single cache; no second layer). */
+export function getSettings(): FeatyardSettings {
+  if (_getSettingsOverride) return _getSettingsOverride();
+  if (!handle) throw new Error("featyard settings not initialized — initFeatyardSettings not called");
+  return handle.getSettings();
+}
+
+/**
+ * Update a setting by key. With no `level`, mutates the in-memory buffer (session); with
+ * `{ level: "project" }` / `{ level: "global" }`, does a surgical one-key write to that file and
+ * syncs the buffer. After any change, refreshes the fork-mode env var for the active phase so a
+ * mid-turn edit of a fork-mode key takes effect without a phase transition.
+ */
+export function updateSetting(
+  key: string,
+  value: unknown,
+  opts: { level?: "session" | "project" | "global" } | null,
+): void {
+  if (_updateSettingsOverride) {
+    _updateSettingsOverride(key, value, opts);
+    syncForkModeEnv();
+    return;
+  }
+  if (!handle) throw new Error("featyard settings not initialized — initFeatyardSettings not called");
+  handle.updateSetting(key, value, opts ?? undefined);
+  syncForkModeEnv();
+}
+
+/**
+ * Map the active workflow phase + settings to the subagent fork mode.
+ *
+ *   design/plan    → planReviewSubagentsMode (e.g. "new+fork" — dual review)
+ *   review         → featureReviewSubagentsMode
+ *   else (implement/verify/uat/finish/none) → "new" (fresh subagents, no fork)
+ *
+ * Pure (reads env + settings, no side effects) so it stays testable and can be
+ * shared between phase-driven sync (syncEnvVarsFromState) and settings-ui edits.
+ */
+export function resolveForkModeForPhase(phase: string | undefined, settings: FeatyardSettings): string {
+  switch (phase) {
+    case "design":
+    case "plan":
+      return settings.planReviewSubagentsMode;
+    case "review":
+      return settings.featureReviewSubagentsMode;
+    default:
+      // implement / verify / uat / finish / no active phase → always fresh.
+      return "new";
+  }
+}
+
+/**
+ * Sync `PI_SUBAGENT_FORK_MODE` from the active phase + settings.
+ *
+ * The subagent extension's new+fork duplication reads this env var from the
+ * DISPATCHING process's own env, so the root session must own it. Root-only —
+ * guarded by the absence of PI_SUBAGENT_PARENT_PID; a subagent re-deriving it
+ * would re-arm fork mode at the 2nd level and defeat the "fork mode must not
+ * propagate deeper than 1st level" rule.
+ */
+export function syncForkModeEnv(): void {
+  if (process.env.PI_SUBAGENT_PARENT_PID !== undefined) return; // root session only
+  const mode = resolveForkModeForPhase(process.env.PI_FY_STAGE, getSettings());
+  if (mode) {
+    process.env.PI_SUBAGENT_FORK_MODE = mode;
+  } else {
+    delete process.env.PI_SUBAGENT_FORK_MODE;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register the `/fy:settings` command + modal and create the settings handle. Called from the
+ * extension's activate function (needs `pi`). `beforeOpen` stashes the command ctx for the modal;
+ * `onAfterChange` refreshes the fork-mode env var after a mid-turn edit.
+ */
+export function initFeatyardSettings(pi: ExtensionAPI): void {
+  handle = registerSettingsCommand<FeatyardSettings>(pi, FEATYARD_SCHEMA, {
+    commandName: "fy:settings",
+    title: "Featyard Settings",
+    titleRight: "avtc-pi-featyard",
+    clampFn: clampFeatyardSettings,
+    envVar: "PI_FY_SETTINGS",
+    beforeOpen: (ctx) => {
+      if (!globalThis.__piCtx) globalThis.__piCtx = new PiCtx();
+      globalThis.__piCtx.refresh(ctx);
+    },
+    onAfterChange: () => {
+      syncForkModeEnv();
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports from sub-modules
+// ---------------------------------------------------------------------------
+
+// NOTE: featyard consumes avtc-pi-settings-ui; it must NOT re-export settings-ui's
+// symbols (transitive re-export anti-pattern). Any code needing them should import
+// directly from "avtc-pi-settings-ui".
+export {
+  DEFAULT_GLOBAL_DIR,
+  type FeatyardConfig,
+  invalidateConfigCache,
+  invalidateConfigCacheIfChanged,
+  loadFeatyardConfig,
+  type ModelOverride,
+  NO_CWD_OVERRIDE,
+  resetFeatyardConfig,
+  resolveModelOverride,
+  resolveReviewSkill,
+  resolveStageModelOnly,
+  setFeatyardConfig,
+} from "./model-overrides.js";
+export { clampFeatyardSettings, FEATYARD_SCHEMA, parseContextCompactValue } from "./settings-schema.js";
+export type {
+  AutoOnBlock,
+  BranchPolicy,
+  DesignDocStorage,
+  ExecutionFlow,
+  FeatureReviewMode,
+  FeatureReviewSubagentsMode,
+  FeatyardSettings,
+  NestedResearchers,
+  PerTaskReviewMode,
+  PlanReviewMode,
+  PlanReviewSubagentsMode,
+  PreCommitDiscipline,
+  TestingDiscipline,
+  UatMode,
+  VerifyPhases,
+} from "./settings-types.js";
+
+// ---------------------------------------------------------------------------
+// Extension entry point (package.json → src/index.ts activate)
+// ---------------------------------------------------------------------------
+
+export default function settingsExtension(pi: ExtensionAPI): void {
+  initFeatyardSettings(pi);
+  subscribeToDialogCoordinator(pi);
+}

package/src/shared/errors.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Error thrown when a user cancels an interactive dialog (e.g. branch selection).
+ * Used by workflow-monitor base branch resolution and guardrails execution mode dialog.
+ */
+export class UserCancelledError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UserCancelledError";
+  }
+}
+
+/**
+ * Error thrown when user input fails validation (e.g. shell-unsafe characters in branch name).
+ * Propagated through catch blocks that swallow generic errors.
+ */
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ValidationError";
+  }
+}

package/src/shared/global.d.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Type declarations for cross-extension bridge objects on globalThis.
+ *
+ * Each extension owns a single typed bridge object rather than scattered
+ * individual globalThis keys. This provides type safety and co-locates
+ * related state.
+ *
+ * Bridge objects are initialized by their owning extension factory and
+ * survive jiti module reloads (moduleCache:false).
+ */
+
+import type { CompactFollowUp, PiCtx, PiKanbanBridge, PiWorkflowMonitorBridge } from "./types.js";
+
+declare global {
+  var __piWorkflowMonitor: PiWorkflowMonitorBridge | undefined;
+  var __piKanban: PiKanbanBridge | undefined;
+  var __piCtx: PiCtx | undefined;
+  var __piCompactFollowUp: CompactFollowUp | undefined;
+}

package/src/shared/session-entries.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+import type { CustomEntry, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { log } from "../log.js";
+
+/**
+ * Walk the session branch in reverse and return the data from the latest
+ * custom entry matching `customType`, or `undefined` if not found.
+ */
+export function findLatestCustomEntry<T>(ctx: ExtensionContext, customType: string): T | undefined {
+  try {
+    const branch = ctx.sessionManager.getBranch();
+    for (let i = branch.length - 1; i >= 0; i--) {
+      const entry = branch[i];
+      if (entry.type === "custom" && (entry as CustomEntry).customType === customType) {
+        return (entry as CustomEntry<T>).data as T | undefined;
+      }
+    }
+  } catch (err) {
+    log.warn(`Failed to walk session branch for '${customType}': ${err instanceof Error ? err.message : err}`);
+  }
+  return undefined;
+}

package/src/shared/types.ts

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Shared types for cross-extension communication.
+ *
+ * Contains:
+ * - Bridge interfaces for globalThis typed access
+ * - HandlerContext for ctx.actions.exec augmentation
+ * - PiCtx for stale context workaround
+ */
+
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+// --- MutableRef (cross-module mutable state sharing) ---
+
+/** Mutable reference to a value — used for cross-module state sharing. */
+export interface MutableRef<T> {
+  value: T;
+}
+
+// --- Bridge interfaces ---
+
+export interface PiWorkflowMonitorBridge {
+  handler: import("../state/feature-session.js").FeatureSession;
+  requestWidgetUpdate(): void;
+  performWorkflowReset(): void;
+  modelOverrideRefs: { pi: import("@earendil-works/pi-coding-agent").ExtensionAPI | undefined };
+  finishPhaseWhitelisted: boolean;
+  workflowInitiatedNewSession: boolean | undefined;
+  newSessionMessage: string | null | undefined;
+  /** Handle to the 24h artifact-archive sweep interval. Cleared on session_shutdown so
+   *  /reload (which re-evaluates this module) never leaks a duplicate timer. undefined = not running. */
+  archiveTimer: ReturnType<typeof setInterval> | undefined;
+}
+
+export interface PiKanbanBridge {
+  autoAgent: import("../kanban/auto-agent/auto-agent-state-machine.js").AutoAgentStateMachine | null;
+  autoAgentCallback: import("../kanban/auto-agent/auto-agent-state-machine.js").AutoAgentCallback | undefined;
+  /** True while the auto-agent is mid-`newSession`/`switchSession`. Distinguishes auto-initiated
+   *  session replacements from external ones (manual /new, /resume, /fork, /reload). External
+   *  replacements orphan the agent's command-context-only `newSession`/`switchSession`, so the
+   *  session_start handler pauses the agent unless this flag is set. */
+  autoAgentInitiatingReplacement: boolean | undefined;
+  database: import("../kanban/data/kanban-database.js").KanbanDatabase | null;
+  tools: import("../kanban/kanban-operations.js").KanbanTools | null;
+  activateFeature:
+    | ((
+        result: {
+          feature: import("../kanban/data/kanban-types.js").Feature;
+          skill: string;
+          kanbanFeatureId: number;
+        },
+        piCtx: { sendUserMessage: (msg: string, options?: { deliverAs?: "steer" | "followUp" }) => void },
+      ) => Promise<void>)
+    | undefined;
+  createGracePeriodManager:
+    | ((
+        sm: import("../kanban/auto-agent/auto-agent-state-machine.js").AutoAgentStateMachine,
+        tools: import("../kanban/kanban-operations.js").KanbanTools,
+      ) => import("../kanban/auto-agent/auto-agent-grace-period.js").GracePeriodManager)
+    | undefined;
+  terminalInputUnsubscribe: (() => void) | null;
+  gracePeriod: import("../kanban/auto-agent/auto-agent-grace-period.js").GracePeriodManager | undefined;
+}
+
+// --- CompactFollowUp (stored-message pattern) ---
+
+export interface CompactFollowUp {
+  /** Specific note appended after the skill+framing (e.g. "Context was reset between tasks — next task: X",
+   *  "Run plan review iteration #1"). Must NOT contain a `/skill:` prefix or generic compaction framing
+   *  the compact-handler owns the skill + framing line. Empty string = no caller note. */
+  message: string;
+  /** Skill name the handler should expand (e.g. "fy-implement", "fy-plan-review"). When omitted,
+   *  the handler falls back to getExpectedSkill. Lets callers that carry a skill avoid the
+   *  duplicate-skill the old prepend logic produced. */
+  skillName?: string;
+  /** Optional callback to execute after the session_compact handler sends the followUp message */
+  onAfterFollowUp?: () => void;
+}
+
+// --- HandlerContext ---
+
+/** ExtensionContext augmented with ctx.actions.exec (internal runtime property) */
+export interface HandlerContext extends ExtensionContext {
+  actions: {
+    exec: (command: string, options?: { cwd?: string }) => Promise<{ stdout: string; stderr: string }>;
+  };
+}
+
+// --- PiCtx ---
+
+const noopNotify = (_msg: string, _level: "info" | "warning" | "error" | null) => {};
+
+/**
+ * After ctx.newSession, ctx.switchSession, or /reload, the runner is
+ * permanently invalidated — all ctx objects from that runner become stale.
+ *
+ * This class stashes essential functions that survive session transitions
+ * and provides safe access regardless of ctx staleness.
+ */
+
+/**
+ * Portable shape of the ctx passed to withSession callbacks. The real SDK type
+ * (ReplacedSessionContext) isn't re-exported from the package root, so this minimal
+ * structural type keeps declarations portable while exposing the members callers use.
+ */
+type ReplacedSessionCtx = ExtensionCommandContext & {
+  sendUserMessage: (
+    content: string | ReadonlyArray<{ type: string }>,
+    options?: { deliverAs?: "steer" | "followUp" },
+  ) => Promise<void>;
+};
+
+/** Signature of ctx.newSession used by PiCtx (defined once to avoid duplicating the options shape in the getter return type + the stashed cast). */
+type NewSessionFn = (options?: {
+  parentSession?: string;
+  setup?: (sessionManager: unknown) => Promise<void>;
+  withSession?: (ctx: ReplacedSessionCtx) => Promise<void>;
+}) => Promise<{ cancelled: boolean }>;
+
+export class PiCtx {
+  private stashed: {
+    newSession?: ExtensionCommandContext["newSession"];
+    switchSession?: ExtensionCommandContext["switchSession"];
+    sessionManager?: ExtensionCommandContext["sessionManager"];
+    notify?: (msg: string, level?: "info" | "warning" | "error") => void;
+    ui?: ExtensionContext["ui"];
+    hasUI?: boolean;
+    mode?: ExtensionCommandContext["mode"];
+    model?: ExtensionCommandContext["model"];
+    modelRegistry?: ExtensionCommandContext["modelRegistry"];
+    cwd?: string;
+  } = {};
+  /** Stash essential functions from a fresh ctx. Call after every session transition.
+   * Bound methods (ui, notify) survive runner invalidation — they're bound to the
+   * uiContext object directly, which lives independently of the runner's assertActive gate.
+   * The guard is the single safe access point for ctx in event handlers that may fire
+   * after compaction/session replacement invalidates the runner. */
+  refresh(ctx: ExtensionCommandContext): void {
+    if (typeof ctx.newSession === "function") this.stashed.newSession = ctx.newSession.bind(ctx);
+    if (typeof ctx.switchSession === "function") this.stashed.switchSession = ctx.switchSession.bind(ctx);
+    if (ctx.sessionManager) this.stashed.sessionManager = ctx.sessionManager;
+    if (ctx.ui) this.stashed.ui = ctx.ui;
+    if (ctx.ui?.notify) this.stashed.notify = ctx.ui.notify.bind(ctx.ui);
+    this.stashed.hasUI = ctx.hasUI;
+    if (ctx.mode) this.stashed.mode = ctx.mode;
+    if (ctx.model) this.stashed.model = ctx.model;
+    if (ctx.modelRegistry) this.stashed.modelRegistry = ctx.modelRegistry;
+    if (ctx.cwd) this.stashed.cwd = ctx.cwd;
+  }
+
+  get newSession(): NewSessionFn | undefined {
+    return this.stashed.newSession as NewSessionFn | undefined;
+  }
+  get switchSession():
+    | ((
+        sessionPath: string,
+        options?: { withSession?: (ctx: ReplacedSessionCtx) => Promise<void> },
+      ) => Promise<{ cancelled: boolean }>)
+    | undefined {
+    return this.stashed.switchSession as
+      | ((
+          sessionPath: string,
+          options?: { withSession?: (ctx: ReplacedSessionCtx) => Promise<void> },
+        ) => Promise<{ cancelled: boolean }>)
+      | undefined;
+  }
+  get sessionManager(): { getSessionFile?: () => string | undefined } | undefined {
+    return this.stashed.sessionManager;
+  }
+  get notify() {
+    return this.stashed.notify ?? noopNotify;
+  }
+  /** Full ui object (bound to uiContext — survives runner invalidation). Undefined if never refreshed or no UI. */
+  get ui() {
+    return this.stashed.ui;
+  }
+  /** Whether the last known-good ctx had UI. Undefined if never refreshed. */
+  get hasUI() {
+    return this.stashed.hasUI;
+  }
+  /** Last known mode. Undefined if never refreshed. */
+  get mode(): ExtensionCommandContext["mode"] | undefined {
+    return this.stashed.mode;
+  }
+  get model() {
+    return this.stashed.model;
+  }
+  get modelRegistry() {
+    return this.stashed.modelRegistry;
+  }
+  get cwd() {
+    return this.stashed.cwd;
+  }
+}