avtc-pi-featyard 1.1.0

package/src/git/git-queries.ts

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Read-only git introspection for a coding-agent workflow: where is HEAD, is
+ * anything uncommitted, and what's staged. Every query degrades to a safe value
+ * (null / false / []) on failure and never throws — callers pay no try/catch;
+ * each failure surfaces as exactly one diagnostic warn in the log.
+ */
+import { execFileSync } from "node:child_process";
+import { log } from "../log.js";
+
+/** Synchronous git invocation contract: returns captured stdout (caller trims); throws on non-zero exit, missing git binary, or any spawn error. */
+export type GitRunner = (args: string[], cwd: string) => string;
+
+/** Default runner: invokes the real `git` binary synchronously via child_process (no shell; args passed directly to avoid injection/quoting). */
+export const defaultGitRunner: GitRunner = (args, cwd) => {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    // stdin ignored so git can't block waiting for input; stdout/stderr piped (captured, not leaked to console).
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+};
+
+// --- testability seam -------------------------------------------------------
+// All four queries below route through this module-level slot. A test swaps it once
+// with setGitRunner(stub) to stub ALL git invocation without touching the filesystem.
+let gitRunner: GitRunner = defaultGitRunner;
+
+/** Test seam — replace how this module shells out to git. Every query routes through the slot, so one call stubs them all. Restore the real runner with `setGitRunner(defaultGitRunner)`. */
+export function setGitRunner(runner: GitRunner): void {
+  gitRunner = runner;
+}
+
+/** Convenience pass-through for `process.cwd()` so one-off callers don't have to supply a directory. */
+export const PROCESS_CWD: string = process.cwd();
+
+/** Sentinel fallbacks for queries that can't determine a value (avoids bare literals at call sites). */
+const NO_REF: string | null = null;
+const NO_SHA: string | null = null;
+const CLEAN_TREE = false;
+
+// --- internal failure path --------------------------------------------------
+// One centralized failure path: run `compute` against the current runner; if it throws
+// for ANY reason (not a repo, git missing, non-zero exit), emit exactly ONE warn
+// (its text always contains "git") and return the query's safe fallback.
+function query<T>(label: string, cwd: string, compute: (run: GitRunner) => T, fallback: T): T {
+  const run = gitRunner;
+  try {
+    return compute(run);
+  } catch (err) {
+    log.warn(`git ${label} failed in ${cwd}: ${err instanceof Error ? err.message : String(err)}`);
+    return fallback;
+  }
+}
+
+// --- queries ----------------------------------------------------------------
+
+/** Symbolic identity at HEAD: the branch name when on a branch, else the short commit SHA. Null when it cannot be determined (not a repo, git unavailable). */
+export function getBranchOrShortSha(cwd: string): string | null {
+  return query(
+    "identity",
+    cwd,
+    (run) => {
+      // `symbolic-ref --short HEAD` prints the branch name even on an unborn branch (no
+      // commits yet); it errors only when HEAD is detached, so treat that as "no branch".
+      try {
+        const branch = run(["symbolic-ref", "--short", "HEAD"], cwd).trim();
+        if (branch !== "") return branch;
+      } catch {
+        // detached HEAD (or symbolic-ref unavailable) — fall through to the short SHA.
+      }
+      const short = run(["rev-parse", "--short", "HEAD"], cwd).trim();
+      return short !== "" ? short : NO_REF;
+    },
+    NO_REF,
+  );
+}
+
+/** Full 40-character commit SHA of HEAD. Null when git is unavailable or returns anything that isn't exactly 40 lowercase hex chars. */
+export function getHeadSha(cwd: string): string | null {
+  return query(
+    "head-sha",
+    cwd,
+    (run) => {
+      const sha = run(["rev-parse", "HEAD"], cwd).trim();
+      return /^[0-9a-f]{40}$/.test(sha) ? sha : NO_SHA;
+    },
+    NO_SHA,
+  );
+}
+
+/** True if the working tree has ANY uncommitted change — staged, unstaged, or untracked. False when clean or on failure. */
+export function isDirty(cwd: string): boolean {
+  return query(
+    "dirty",
+    cwd,
+    (run) => {
+      // `status --porcelain` is empty iff clean; it lists staged, unstaged, AND untracked ("??") files.
+      return run(["status", "--porcelain"], cwd).trim() !== "";
+    },
+    CLEAN_TREE,
+  );
+}
+
+/** File paths currently staged for commit (one per line from `git diff --cached --name-only`). Empty array when none or on failure. */
+export function getStagedFiles(cwd: string): string[] {
+  return query(
+    "staged-files",
+    cwd,
+    (run) => {
+      const out = run(["diff", "--cached", "--name-only"], cwd).trim();
+      if (out === "") return [];
+      return out
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "");
+    },
+    [],
+  );
+}
+
+/**
+ * Repo-relative paths of every working-tree change vs HEAD: staged, unstaged,
+ * AND untracked. This is the union `git status` reports — the full "current
+ * change set" — and is used to answer "did a test get written/modified in this
+ * change set?" without caring HOW a file was written (write/edit tool, heredoc,
+ * cp, sed, …). Returns an empty array when the tree is clean or on failure
+ * (not a repo, git unavailable).
+ *
+ * Uses `-z` for null-separated, never-quoted paths: avoids whitespace/special-
+ * char splitting and the `PATH -> NEWPATH` rename-arrow ambiguity of the
+ * default format. Each entry carries a 2-char `XY` status prefix followed by a
+ * space; the prefix is stripped before returning the bare path.
+ */
+export function getWorkingTreeFiles(cwd: string): string[] {
+  return query(
+    "working-tree-files",
+    cwd,
+    (run) => {
+      // `-uall` lists individual files inside untracked directories (default
+      // `-unormal` collapses a wholly-untracked dir to a single `dir/` entry,
+      // hiding the test file inside). `-z` for null-separated, never-quoted paths.
+      const out = run(["status", "--porcelain", "-z", "--untracked-files=all"], cwd);
+      if (out === "") return [];
+      return out
+        .split("\0")
+        .map((entry) => entry.replace(/^.{3}/, "")) // strip the "XY " status prefix
+        .filter((p) => p !== "");
+    },
+    [],
+  );
+}

package/src/git/resolve-base-branch.ts

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Base branch resolution — extracts UI interaction, settings persistence,
+ * and git operations from the workflow-monitor factory for SRP.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import * as autoAgentNotify from "../kanban/auto-agent/auto-agent-notify.js";
+import { log } from "../log.js";
+import { getSettings, updateSetting } from "../settings/settings-ui.js";
+import { UserCancelledError, ValidationError } from "../shared/errors.js";
+import { getActiveFeatureSlug } from "../shared/workflow-refs.js";
+import { withCoordinator } from "../snippets/vendored/subscribe-to-dialog-coordinator.js";
+import { getLastMessage, withAttention } from "../snippets/vendored/subscribe-to-notifications.js";
+import { isSubagentSession } from "../state/state-persistence.js";
+import { createGitExec } from "./worktrees/worktree-helpers.js";
+import { detectBaseBranch, getBaseBranchCandidates } from "./worktrees/worktree-lifecycle.js";
+
+/**
+ * Resolve the base branch for the current project.
+ *
+ * Priority: saved setting > user selection (with git detection) > auto-detection > "main"
+ */
+export async function resolveBaseBranch(ctx: ExtensionContext): Promise<string> {
+  const settings = getSettings();
+  if (settings.baseBranch) return settings.baseBranch;
+
+  const gitExec = createGitExec(ctx);
+
+  try {
+    const detected = (await detectBaseBranch(gitExec)) ?? undefined;
+    const candidates = await getBaseBranchCandidates(gitExec);
+
+    // Always prompt user to confirm base branch (when not set in settings)
+    if (candidates.length > 0 && ctx.hasUI && !isSubagentSession()) {
+      return await promptBaseBranch(gitExec, detected, candidates);
+    } else if (detected) {
+      log.info(`[workflow] Auto-detected base branch: ${detected}`);
+      return detected;
+    } else {
+      log.warn(
+        `[workflow] Could not auto-detect base branch and no UI for prompt, defaulting to 'main'. Set baseBranch in settings to override.`,
+      );
+      return "main";
+    }
+  } catch (err) {
+    if (err instanceof UserCancelledError) throw err; // propagate cancel to caller
+    if (err instanceof ValidationError) throw err; // propagate validation errors
+    log.warn(`[workflow] Base branch detection failed, defaulting to 'main'. Set baseBranch in settings to override.`);
+    return "main";
+  }
+}
+
+/** Prompt user to select or enter a base branch, then persist the choice. */
+async function promptBaseBranch(
+  gitExec: ReturnType<typeof createGitExec>,
+  detected: string | undefined,
+  candidates: string[],
+): Promise<string> {
+  const guard = globalThis.__piCtx;
+  const ui = guard?.ui;
+  if (!ui?.select) {
+    log.warn("[workflow] No UI available for base branch selection");
+    throw new UserCancelledError("Base branch selection requires interactive mode");
+  }
+  const CUSTOM_BRANCH_OPTION = "Type your own...";
+  const labels = [...candidates.map((b) => (b === detected ? `${b} (detected)` : b)), CUSTOM_BRANCH_OPTION];
+
+  const activeSlug = getActiveFeatureSlug();
+  if (activeSlug) autoAgentNotify.notifyAutoAgentBlocked(activeSlug);
+  const pickedLabel = await withAttention(
+    "workflow",
+    ["base branch selection", activeSlug, getLastMessage()].filter(Boolean).join(" • "),
+    () => withCoordinator(() => ui.select("Select the base branch for this project:", labels)),
+  );
+  if (activeSlug) autoAgentNotify.notifyAutoAgentUnblocked(activeSlug);
+
+  // User cancelled the dialog
+  if (pickedLabel === undefined) {
+    log.info("[workflow] User cancelled base branch selection");
+    throw new UserCancelledError("Base branch selection cancelled");
+  }
+
+  const baseBranch = await resolveBranchName(gitExec, pickedLabel, detected, CUSTOM_BRANCH_OPTION);
+  await persistBranchChoice(baseBranch);
+  return baseBranch;
+}
+
+/** Resolve the actual branch name from user selection (picked or custom-typed). */
+async function resolveBranchName(
+  gitExec: ReturnType<typeof createGitExec>,
+  pickedLabel: string,
+  detected: string | undefined,
+  customOption: string,
+): Promise<string> {
+  if (pickedLabel !== customOption) {
+    return pickedLabel.replace(/ \(detected\)$/, "");
+  }
+
+  // Free-text input for custom branch name
+  const guard = globalThis.__piCtx;
+  const ui = guard?.ui;
+  if (!ui?.input) {
+    log.warn("[workflow] No UI available for custom branch input");
+    throw new UserCancelledError("Custom branch input requires interactive mode");
+  }
+  const customBranch = await withAttention(
+    "workflow",
+    ["custom branch", getLastMessage()].filter(Boolean).join(" • "),
+    () => withCoordinator(() => ui.input("Enter base branch name:", detected ?? "main")),
+  );
+  if (!customBranch?.trim()) {
+    log.info("[workflow] User cancelled custom branch input");
+    throw new UserCancelledError("Custom branch input cancelled");
+  }
+
+  const branch = customBranch.trim();
+  // Validate branch name — interpolated into shell commands via gitExec
+  if (!/^[a-zA-Z0-9._@/-]+$/.test(branch)) {
+    throw new ValidationError("Invalid branch name: contains shell-unsafe characters");
+  }
+  await verifyBranchExists(gitExec, branch);
+  return branch;
+}
+
+/** Verify a branch exists locally or remotely (warns but continues if not found). */
+async function verifyBranchExists(gitExec: ReturnType<typeof createGitExec>, branch: string): Promise<void> {
+  try {
+    const verifyResult = await gitExec(`git rev-parse --verify refs/heads/${branch}`);
+    if (verifyResult.exitCode !== 0) {
+      log.warn(`[workflow] Branch '${branch}' does not exist locally, trying remote`);
+      const remoteVerify = await gitExec(`git rev-parse --verify refs/remotes/origin/${branch}`);
+      if (remoteVerify.exitCode !== 0) {
+        log.warn(`[workflow] Branch '${branch}' not found locally or remotely, using anyway`);
+      }
+    }
+  } catch {
+    // Verification failed — use the name anyway
+  }
+}
+
+/** Ask user where to save the branch choice and persist it. */
+async function persistBranchChoice(baseBranch: string): Promise<void> {
+  const guard = globalThis.__piCtx;
+  const ui = guard?.ui;
+  const saveChoice = ui
+    ? await withAttention("workflow", ["save location", getLastMessage()].filter(Boolean).join(" • "), () =>
+        withCoordinator(() =>
+          ui.select("Save base branch setting where?", [
+            "Project settings (persists for all sessions)",
+            "This session only",
+          ]),
+        ),
+      )
+    : undefined;
+
+  // User cancelled save location dialog
+  if (saveChoice === undefined) {
+    log.info("[workflow] User cancelled save location selection, using session-only");
+    updateSetting("baseBranch", baseBranch, null);
+    return;
+  }
+
+  if (saveChoice.startsWith("Project")) {
+    updateSetting("baseBranch", baseBranch, { level: "project" });
+    log.info(`[workflow] Base branch '${baseBranch}' saved to project settings`);
+  } else {
+    updateSetting("baseBranch", baseBranch, null);
+    log.info(`[workflow] Base branch '${baseBranch}' set for this session only`);
+  }
+}

package/src/git/worktrees/worktree-helpers.ts

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Worktree-related utility functions for workflow-monitor.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getSettings } from "../../settings/settings-ui.js";
+import type { FeatureSession } from "../../state/feature-session.js";
+import type { FeatureState } from "../../state/feature-state.js";
+import { NO_STATUS } from "../../ui/featyard-widget.js";
+import type { ExecFn } from "./worktree-lifecycle.js";
+import { cleanupWorktreeOnFinish } from "./worktree-lifecycle.js";
+
+const WORKTREE_ACTIVE_PHASES = new Set(["implement", "verify", "review"]);
+const WORKTREE_STATUS_KEY = "worktree";
+
+/** Folder icon shown before the worktree path in the footer status entry. */
+const WORKTREE_ICON = "\u{1F4C2}";
+
+/**
+ * Sync the worktree footer indicator (📂 {path}) with the current feature state.
+ *
+ * Shown when the active feature has a recorded `git.worktreePath`, the
+ * `branchPolicy` is `worktree`, and the feature is not yet completed. Cleared
+ * otherwise. This is the single source of truth for the indicator's logic;
+ * called both at creation time (immediate feedback) and on every UI restore
+ * (reload/resume/fork/reset) so the indicator never disappears after a reload
+ * and never lingers after completion/reset.
+ *
+ * Completion (not phase) is the off-signal: the worktree is removed in the
+ * finish phase, and the done state retains `worktreePath` until displaced, so a
+ * phase check would falsely re-show the indicator for a completed feature.
+ */
+export function syncWorktreeStatus(featureState: FeatureState | null): void {
+  const guard = globalThis.__piCtx;
+  if (!guard?.hasUI || !guard?.ui?.setStatus) return;
+  const ui = guard.ui;
+  const worktreePath = featureState?.git?.worktreePath ?? null;
+  const isWorktreePolicy = getSettings().branchPolicy === "worktree";
+  const isDone = featureState?.completedAt != null;
+  if (worktreePath && isWorktreePolicy && !isDone) {
+    const label = `${WORKTREE_ICON} ${worktreePath}`;
+    ui.setStatus(WORKTREE_STATUS_KEY, ui.theme?.fg("accent", label) ?? label);
+  } else {
+    ui.setStatus(WORKTREE_STATUS_KEY, NO_STATUS);
+  }
+}
+
+/** Escape a string for bash single-quote context: wraps in '...', replacing internal ' with '\'' */
+export function bashSingleQuote(str: string): string {
+  return `'${str.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Shared guard for worktree-aware handlers.
+ * Returns worktree context if interception should be active, null otherwise.
+ * Checks: active slug → worktreePath → branchPolicy=worktree → phase in WORKTREE_ACTIVE_PHASES.
+ */
+export function getActiveWorktreeContext(handler: FeatureSession): { worktreePath: string } | null {
+  const slug = handler.getActiveFeatureSlug();
+  if (!slug) return null;
+  const fsData = handler.getActiveFeatureState();
+  const worktreePath = fsData?.git?.worktreePath;
+  if (!worktreePath) return null;
+  const settings = getSettings();
+  if (settings.branchPolicy !== "worktree") return null;
+  const ws = handler.getWorkflowState();
+  const phase = ws?.currentPhase;
+  if (!phase || !WORKTREE_ACTIVE_PHASES.has(phase)) return null;
+  return { worktreePath };
+}
+
+/**
+ * Result shape returned by any exec implementation we support.
+ */
+interface ExecResult {
+  exitCode?: number;
+  stdout?: string;
+}
+
+/**
+ * Extension contexts delivered at runtime may carry an `actions` object with an
+ * `exec` helper (e.g. command handlers and tool execute). The SDK types do not
+ * declare this on the base `ExtensionContext`, so we model it as optional and
+ * fall back to a direct child_process exec when it is absent.
+ */
+interface ExecCapableContext extends ExtensionContext {
+  actions?: { exec?: (command: string, options?: { cwd?: string | null }) => Promise<ExecResult> };
+}
+
+/**
+ * Create a git exec function from an extension context.
+ */
+export function createGitExec(ctx: ExtensionContext): ExecFn {
+  const execCtx = ctx as ExecCapableContext;
+  return async (command: string, options?: { cwd?: string }) => {
+    // Prefer ctx.actions.exec (available in command handlers and tool execute)
+    if (execCtx?.actions?.exec) {
+      try {
+        const result = (await execCtx.actions.exec(command, options)) as ExecResult | undefined;
+        // Some exec implementations return undefined for unmocked commands; treat that as a
+        // non-zero exit (empty stdout) rather than crashing on property access.
+        if (!result) {
+          return { exitCode: 1, stdout: "" };
+        }
+        return { exitCode: result.exitCode ?? 0, stdout: result.stdout ?? "" };
+      } catch (err: unknown) {
+        if (err instanceof TypeError || err instanceof ReferenceError || err instanceof SyntaxError) {
+          throw err;
+        }
+        return { exitCode: 1, stdout: err instanceof Error ? err.message : String(err) };
+      }
+    }
+    // Fallback: direct exec (for contexts without actions.exec)
+    // Use exec (shell) instead of execFile to handle quoted arguments correctly.
+    // execFile with command.split(" ") breaks on arguments containing spaces.
+    try {
+      const { exec } = await import("node:child_process");
+      const { promisify } = await import("node:util");
+      const execAsync = promisify(exec);
+      const { stdout } = await execAsync(command, {
+        cwd: options?.cwd ?? undefined,
+        encoding: "utf-8",
+      });
+      return { exitCode: 0, stdout };
+    } catch (err: unknown) {
+      return { exitCode: 1, stdout: err instanceof Error ? err.message : String(err) };
+    }
+  };
+}
+
+/** Remove worktree when feature is done */
+export async function cleanupWorktreeOnFinishWrapper(
+  featureState: Parameters<typeof cleanupWorktreeOnFinish>[0],
+  ctx: ExtensionContext,
+): Promise<void> {
+  return cleanupWorktreeOnFinish(featureState, createGitExec(ctx), getSettings(), WORKTREE_STATUS_KEY);
+}
+
+export { WORKTREE_STATUS_KEY };

package/src/git/worktrees/worktree-interception.ts

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Register worktree tool_call interception and before_agent_start CWD override.
+ *
+ * When a worktree is active, rewrites tool paths and commands to target the worktree directory.
+ */
+
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { FeatureSession } from "../../state/feature-session.js";
+import { bashSingleQuote, getActiveWorktreeContext } from "./worktree-helpers.js";
+
+/** File tools that require a path parameter */
+const FILE_TOOLS_REQUIRED_PATH = new Set(["read", "write", "edit"]);
+
+/** Injected into the system prompt via before_agent_start so the agent never commits .featyard/ files. */
+const FY_INSTRUCTION =
+  "\n\n⚠️ `.featyard/` files are auto-managed external storage — gitignored, never committed. Never `git add -f` them.";
+
+/** File tools with an optional path parameter */
+const FILE_TOOLS_OPTIONAL_PATH = new Set(["ls", "find", "grep"]);
+
+export function registerWorktreeInterception(pi: ExtensionAPI, deps: { handler: FeatureSession }): void {
+  const { handler } = deps;
+
+  // --- Worktree tool_call interception (must be before guardrail handler) ---
+  pi.on("tool_call", async (event, _ctx) => {
+    const wtx = getActiveWorktreeContext(handler);
+    if (!wtx) return undefined;
+    const { worktreePath } = wtx;
+
+    if (event.toolName === "bash") {
+      const input = event.input as { command: string };
+      if (!input.command) return undefined;
+      input.command = `cd ${bashSingleQuote(worktreePath)} && ${input.command}`;
+    } else if (FILE_TOOLS_REQUIRED_PATH.has(event.toolName)) {
+      const input = event.input as { path: string };
+      if (!path.isAbsolute(input.path)) {
+        input.path = path.resolve(worktreePath, input.path);
+      }
+    } else if (FILE_TOOLS_OPTIONAL_PATH.has(event.toolName)) {
+      const input = event.input as { path?: string };
+      if (input.path === undefined || input.path === "") {
+        input.path = worktreePath;
+      } else if (!path.isAbsolute(input.path)) {
+        input.path = path.resolve(worktreePath, input.path);
+      }
+    }
+    return undefined;
+  });
+
+  // --- System prompt update for worktree CWD and .featyard/ storage warning ---
+  pi.on("before_agent_start", async (event, _ctx) => {
+    let modified = event.systemPrompt;
+    const wtx = getActiveWorktreeContext(handler);
+    if (wtx) {
+      modified = modified.replace(/Current working directory: .+/, `Current working directory: ${wtx.worktreePath}`);
+    }
+    // Append .featyard/ external storage instruction (idempotent — safe if multiple handlers run)
+    modified += FY_INSTRUCTION;
+    if (modified === event.systemPrompt) return undefined;
+    return { systemPrompt: modified };
+  });
+}