@signalridge/pi-worktree 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.3.1
+### Patch Changes
+
+- f714ea0: Publish the package versions already prepared by the previous release transition after its first publish attempt was blocked before npm publication.
+
+## 1.3.0
+### Minor Changes
+
+- b6cf242: New `/worktree → Browse worktree status`: a readable view of what has actually changed in a worktree, grouped as conflicted / staged / unstaged / untracked.
+  
+  It reads `git status --porcelain=v2`, not the v1 the existing safety check uses. That check is unchanged and stays on v1, correctly — it only needs to know whether a worktree is dirty, and v1's flat lines answer that in the fewest moving parts. This is the other job: a person reads the result before deciding whether to remove, switch away from, or commit in a worktree, and "3 changes" does not settle any of those. v2 is what makes the listing unambiguous — staged and unstaged as separate values rather than one overloaded pair of letters, a rename's similarity score *and* its original path, unmerged entries flagged as conflicts rather than rendered as a misleading staged/unstaged pair, and submodules distinguished from modified files.
+  
+  Read with `-z`, so a path containing a newline or a quote is shown exactly as git wrote it. Parsing is total: an unrecognized record is skipped rather than throwing, so a future git version adding one costs that row and not the screen. `git.ts` keeps its raw-output boundary and stays free of intra-package imports — a test loads it standalone under Node's strip-only TypeScript, which cannot resolve a sibling `./x.js` to `x.ts` — so the parser lives beside it and is applied at the consumer.
+
+### Patch Changes
+
+- b6cf242: Peer dependency ranges now name the versions actually validated against, so an untested host combination fails at install time instead of silently at runtime: `@earendil-works/pi-coding-agent`, `pi-ai`, `pi-tui`, and `pi-agent-core` move from `"*"` to `^0.84.0`, and `typebox` from `"*"` to `^1.3.11`.
+  
+  Shared dependencies now carry ONE declared range across every package that uses them, and `bun run check:shared-deps` keeps it that way.
+  
+  `@narumitw/pi-tui-kit` was declared at three disjoint floors — `^0.54.0`, `^0.51.0`, and `^0.49.1` across nine packages — and the lockfile duly resolved three copies (0.54.0, 0.51.0, 0.49.3) installed side by side. For a shared rendering surface drawing into one terminal inside one host process, that means a theme rendering one way in one extension and another way in the next, with nothing failing at install to say so. All nine now declare `^0.54.0` and the install resolves a single copy. `@sinclair/typebox` likewise converges on `^0.34.50`.
+  
+  The new check covers `dependencies` and `peerDependencies` and compares range strings rather than their semantics: two ranges that merely overlap are still a finding, because the goal is one intentional answer per dependency rather than an accidental intersection. `devDependencies` are deliberately out of scope — a build tool is not a shared surface, and `pi-subagents` intentionally carries its own toolchain. `docs/package-boundaries.md` documents the Kit as a shared surface for the first time.
+
+## 1.2.1
+### Patch Changes
+
+- 24a8af4: Remove references to the maintainer's personal dotfile setup from shipped docs
+  and source comments. Each constraint is restated as a property of the package
+  itself: which manager owns a settings file, whether a project permits git
+  worktrees, and installing a package from a single source. No runtime behavior
+  changes.
+
 ## 1.0.0
 ### Major Changes
 

package/README.md

@@ -6,7 +6,7 @@
 
 Pi cannot change its parent process working directory with `cd`. This extension performs the safe equivalent: it prepares a Pi session whose cwd is the selected worktree and switches to that session, preserving the current conversation when it has already been persisted.
 
-This package is the full interactive worktree manager. It is publishable and stable, but it is not automatically enabled by the signalridge dotfiles configuration: the user's AGENTS constitution forbids worktrees.
+This package is the full interactive worktree manager. It is publishable and stable, and opt-in: install it only if your project allows git worktrees. Some repositories forbid them outright — a worktree placed inside the source tree can be picked up by tooling that scans the tree, so check your repository's own guidance before enabling it.
 
 ## ✨ Features
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-worktree",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Pi extension for safe interactive Git worktree management and workspace switching.",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "lint": "biome check ."
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "^0.84.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.7",
@@ -59,7 +59,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@narumitw/pi-tui-kit": "^0.49.1",
+    "@narumitw/pi-tui-kit": "^0.54.0",
     "proper-lockfile": "^4.1.2"
   }
 }

package/src/command.ts

@@ -31,20 +31,24 @@ import {
   worktreeAdministrativeDirectory,
   worktreeForBranch,
   worktreeInventory,
+  worktreeStatusOutput,
 } from "./git.js";
 import { removeWorktreeSafely } from "./safe-remove.js";
 import { switchToWorktree } from "./session.js";
 import type { WorktreeSettingsRuntime } from "./settings.js";
+import { formatStatusEntry, groupStatusEntries, parsePorcelainV2, type StatusEntry } from "./status.js";
 
 const ACTION_ADD = "Add worktree";
 const ACTION_SWITCH = "Switch worktree";
 const ACTION_REMOVE = "Remove worktree";
+const ACTION_STATUS = "Browse worktree status";
 const ACTION_PRUNE = "Prune stale metadata";
 const ACTION_CONFIGURE_ROOT = "Configure worktree root";
 const ACTIONS = {
   add: ACTION_ADD,
   switch: ACTION_SWITCH,
   remove: ACTION_REMOVE,
+  status: ACTION_STATUS,
   prune: ACTION_PRUNE,
   configure: ACTION_CONFIGURE_ROOT,
 } as const;
@@ -126,6 +130,7 @@ export function registerWorktreeCommand(
             add: async () => runFlow(() => addFlow(pi, ctx, records, root.effectiveRoot)),
             switch: async ({ signal }) => runFlow(() => switchFlow(pi, ctx, records, currentPath, signal)),
             remove: async ({ signal }) => runFlow(() => removeFlow(pi, ctx, records, currentPath, signal)),
+            status: async ({ signal }) => runFlow(() => statusFlow(pi, ctx, records, currentPath, signal)),
             prune: async () => runFlow(() => pruneFlow(pi, ctx, records)),
             configure: async () => runFlow(() => configureRootFlow(ctx, settings)),
           },
@@ -514,6 +519,49 @@ async function removeFlow(
   safeNotify(ctx, `Removed worktree ${selected.path}. Its branch was preserved.`, "info");
 }
 
+/**
+ * Show one worktree's status, grouped the way a commit is assembled.
+ *
+ * The point of a browser rather than a count is that "3 changes" is not enough
+ * to decide anything: removing a worktree, switching away from one, or
+ * committing in it are all decisions about WHICH changes exist. Conflicts lead
+ * because nothing else can proceed past them.
+ */
+async function statusFlow(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  records: readonly WorktreeRecord[],
+  currentPath: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const target =
+    records.length === 1
+      ? records[0]
+      : await selectWorktree(ctx, "Browse status of which worktree?", records, currentPath, signal);
+  if (!target) return;
+
+  const entries = parsePorcelainV2(await worktreeStatusOutput(pi, target.path, signal), "\0");
+  if (entries.length === 0) {
+    safeNotify(ctx, `${target.path} is clean.`, "info");
+    return;
+  }
+
+  const groups = groupStatusEntries(entries);
+  const lines: string[] = [];
+  const section = (label: string, group: readonly StatusEntry[]) => {
+    if (group.length === 0) return;
+    lines.push(`${label} (${group.length}):`);
+    for (const entry of group) lines.push(`  ${formatStatusEntry(entry)}`);
+    lines.push("");
+  };
+  section("Conflicted", groups.conflicted);
+  section("Staged", groups.staged);
+  section("Unstaged", groups.unstaged);
+  section("Untracked", groups.untracked);
+
+  safeNotify(ctx, [`${target.path}`, "", ...lines].join("\n").trimEnd(), "info");
+}
+
 async function pruneFlow(
   pi: ExtensionAPI,
   ctx: ExtensionCommandContext,
@@ -784,9 +832,11 @@ async function selectWorktree(
       worktrees: () => ({
         kind: "choice",
         title,
+        enableSearch: true,
         items: records.map((record, index) => ({
           id: record.path,
           label: `${index + 1}. ${formatWorktree(record, currentPath)}`,
+          searchText: `${record.branch ?? ""} ${record.path} ${formatWorktree(record, currentPath)}`,
         })),
         action: "choose",
         hint: "close",

package/src/git.ts

@@ -572,6 +572,32 @@ export async function worktreeInventory(
   ];
 }
 
+/**
+ * A worktree's status as raw porcelain-v2 output, for the status browser.
+ *
+ * Separate from `worktreeInventory` on purpose: that reads porcelain v1 for the
+ * safety check, where a flat "is anything dirty" answer in the fewest moving
+ * parts is exactly right. This reads v2 because a person is going to READ the
+ * result, and v2 is the version that distinguishes staged from unstaged,
+ * carries a rename's original path and score, and names submodules. Ignored
+ * files are excluded: the safety check wants them, a reader does not.
+ */
+export async function worktreeStatusOutput(
+  pi: Pick<ExtensionAPI, "exec">,
+  path: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  // Raw output, parsed by the caller: this module deliberately has no
+  // intra-package imports (a test loads it standalone under Node's strip-only
+  // TypeScript, which cannot resolve a sibling `./x.js` to `x.ts`), so the
+  // parser lives in `status.ts` and is applied where the result is consumed.
+  //
+  // `-z` so a path containing a newline or a quote is read exactly as git wrote
+  // it, rather than through the quoting v1 output would need.
+  const result = await runGit(pi, ["status", "--porcelain=v2", "--untracked-files=all", "-z"], path, signal);
+  return result.stdout;
+}
+
 export async function worktreeAdministrativeDirectory(
   pi: Pick<ExtensionAPI, "exec">,
   cwd: string,

package/src/status.ts

@@ -0,0 +1,237 @@
+/**
+ * status.ts — `git status --porcelain=v2`, parsed into something browsable.
+ *
+ * The safety check in `git.ts` already reads porcelain **v1**, and correctly:
+ * it only needs to know whether a worktree is dirty, and v1's flat lines answer
+ * that in the fewest moving parts. This is the other job — showing a person
+ * WHAT changed before they act on a worktree — and v1 is a poor source for it.
+ *
+ * v1 gives two status characters and a path. v2 gives the fields that make a
+ * listing readable and unambiguous:
+ *
+ *   - staged and unstaged state as separate, explicit values, so "modified in
+ *     both" is distinguishable from either alone;
+ *   - renames and copies with their similarity score AND their original path,
+ *     which v1 only hints at through an arrow inside the path field;
+ *   - unmerged entries with their conflict stages, rather than one of v1's
+ *     several overloaded two-letter codes;
+ *   - a submodule field, so a dirty submodule is not silently a modified file.
+ *
+ * Parsing is deliberately total: an unrecognized line is skipped rather than
+ * throwing. This feeds a viewer, and a future git version adding a record type
+ * should cost that one row, not the whole screen.
+ */
+
+/** What happened to a path on one side (index or worktree). */
+export type StatusChange = "unmodified" | "modified" | "added" | "deleted" | "renamed" | "copied" | "type-changed";
+
+export interface StatusEntry {
+  path: string;
+  /** Staged state — what `git commit` would record. */
+  staged: StatusChange;
+  /** Unstaged state — what is different in the working tree. */
+  unstaged: StatusChange;
+  /** Present for renames and copies: where the content came from. */
+  originalPath?: string;
+  /** Rename/copy similarity, 0–100. */
+  similarity?: number;
+  /** True when the entry is a submodule rather than a file. */
+  submodule?: boolean;
+  /** Set on conflicts; the entry is neither staged nor unstaged but both. */
+  unmerged?: boolean;
+  untracked?: boolean;
+  ignored?: boolean;
+}
+
+/** Single-letter XY codes shared by the ordinary and rename/copy records. */
+const CHANGES: Readonly<Record<string, StatusChange>> = {
+  ".": "unmodified",
+  M: "modified",
+  A: "added",
+  D: "deleted",
+  R: "renamed",
+  C: "copied",
+  T: "type-changed",
+  // Unmerged records reuse the same field for their conflict sides.
+  U: "modified",
+};
+
+function toChange(code: string | undefined): StatusChange {
+  return (code && CHANGES[code]) || "unmodified";
+}
+
+/**
+ * A submodule field is `N...` when the entry is not one, and `S` followed by
+ * three flags when it is. Only the distinction matters here.
+ */
+function isSubmodule(field: string | undefined): boolean {
+  return field?.startsWith("S") === true;
+}
+
+/**
+ * Parse porcelain v2 output.
+ *
+ * `-z` output is NUL-separated and puts a rename's original path in its own
+ * record, so both separators are accepted: pass NUL-separated text and the
+ * paired paths are read correctly, or newline-separated text and the tab form
+ * is used instead. Callers that do not need exact paths under unusual filenames
+ * can use either; a viewer should prefer `-z`.
+ */
+export function parsePorcelainV2(output: string, separator: "\0" | "\n" = "\n"): StatusEntry[] {
+  const fields = output.split(separator);
+  const entries: StatusEntry[] = [];
+
+  for (let index = 0; index < fields.length; index++) {
+    const line = fields[index];
+    if (!line) continue;
+
+    // `? <path>` — untracked. Neither side has a change to describe.
+    if (line.startsWith("? ")) {
+      entries.push({ path: line.slice(2), staged: "unmodified", unstaged: "unmodified", untracked: true });
+      continue;
+    }
+    // `! <path>` — ignored. Only present when the caller asked for them.
+    if (line.startsWith("! ")) {
+      entries.push({ path: line.slice(2), staged: "unmodified", unstaged: "unmodified", ignored: true });
+      continue;
+    }
+
+    // `1 XY sub mH mI mW hH hI <path>` — an ordinary change.
+    if (line.startsWith("1 ")) {
+      const parts = line.split(" ");
+      const xy = parts[1] ?? "..";
+      // The path is the rest of the line: it may itself contain spaces.
+      const path = parts.slice(8).join(" ");
+      if (!path) continue;
+      entries.push({
+        path,
+        staged: toChange(xy[0]),
+        unstaged: toChange(xy[1]),
+        ...(isSubmodule(parts[2]) ? { submodule: true } : {}),
+      });
+      continue;
+    }
+
+    // `2 XY sub mH mI mW hH hI Xscore <path>` then the ORIGINAL path — a rename
+    // or copy. Under `-z` the original is the next NUL-separated field; under
+    // newlines it is tab-separated on the same line.
+    if (line.startsWith("2 ")) {
+      const parts = line.split(" ");
+      const xy = parts[1] ?? "..";
+      const score = parts[8] ?? "";
+      const rest = parts.slice(9).join(" ");
+      if (!rest) continue;
+      let path = rest;
+      let originalPath: string | undefined;
+      if (separator === "\0") {
+        originalPath = fields[index + 1] || undefined;
+        index += 1;
+      } else {
+        const tab = rest.indexOf("\t");
+        if (tab >= 0) {
+          path = rest.slice(0, tab);
+          originalPath = rest.slice(tab + 1) || undefined;
+        }
+      }
+      const similarity = Number.parseInt(score.slice(1), 10);
+      entries.push({
+        path,
+        staged: toChange(xy[0]),
+        unstaged: toChange(xy[1]),
+        ...(originalPath ? { originalPath } : {}),
+        ...(Number.isFinite(similarity) ? { similarity } : {}),
+        ...(isSubmodule(parts[2]) ? { submodule: true } : {}),
+      });
+      continue;
+    }
+
+    // `u XY sub m1 m2 m3 mW h1 h2 h3 <path>` — unmerged. XY here is the pair of
+    // conflict sides rather than staged/unstaged, which is why the entry is
+    // flagged: rendering it as "staged X, unstaged Y" would be a lie.
+    if (line.startsWith("u ")) {
+      const parts = line.split(" ");
+      const xy = parts[1] ?? "..";
+      const path = parts.slice(10).join(" ");
+      if (!path) continue;
+      entries.push({
+        path,
+        staged: toChange(xy[0]),
+        unstaged: toChange(xy[1]),
+        unmerged: true,
+        ...(isSubmodule(parts[2]) ? { submodule: true } : {}),
+      });
+    }
+    // `# ` header lines and anything unrecognized are skipped: this feeds a
+    // viewer, and a new record type should cost one row, not the screen.
+  }
+
+  return entries;
+}
+
+/** Compact one-line label, e.g. `MM src/a.ts` or `R95 new.ts ← old.ts`. */
+export function formatStatusEntry(entry: StatusEntry): string {
+  if (entry.untracked) return `?? ${entry.path}`;
+  if (entry.ignored) return `!! ${entry.path}`;
+  const code = `${letterFor(entry.staged)}${letterFor(entry.unstaged)}`;
+  const marks = [
+    entry.unmerged ? "conflict" : undefined,
+    entry.submodule ? "submodule" : undefined,
+    entry.similarity !== undefined ? `${entry.similarity}%` : undefined,
+  ].filter(Boolean);
+  const origin = entry.originalPath ? ` ← ${entry.originalPath}` : "";
+  const suffix = marks.length > 0 ? ` (${marks.join(", ")})` : "";
+  return `${code} ${entry.path}${origin}${suffix}`;
+}
+
+function letterFor(change: StatusChange): string {
+  switch (change) {
+    case "modified":
+      return "M";
+    case "added":
+      return "A";
+    case "deleted":
+      return "D";
+    case "renamed":
+      return "R";
+    case "copied":
+      return "C";
+    case "type-changed":
+      return "T";
+    default:
+      return ".";
+  }
+}
+
+/**
+ * Group entries the way a reader thinks about them, in the order a commit is
+ * assembled: conflicts first because nothing else can proceed past them, then
+ * what is staged, then what is not, then what is not tracked at all.
+ */
+export function groupStatusEntries(entries: readonly StatusEntry[]): {
+  conflicted: StatusEntry[];
+  staged: StatusEntry[];
+  unstaged: StatusEntry[];
+  untracked: StatusEntry[];
+  ignored: StatusEntry[];
+} {
+  const groups = {
+    conflicted: [] as StatusEntry[],
+    staged: [] as StatusEntry[],
+    unstaged: [] as StatusEntry[],
+    untracked: [] as StatusEntry[],
+    ignored: [] as StatusEntry[],
+  };
+  for (const entry of entries) {
+    if (entry.unmerged) groups.conflicted.push(entry);
+    else if (entry.untracked) groups.untracked.push(entry);
+    else if (entry.ignored) groups.ignored.push(entry);
+    else {
+      // A path can be in both: staged edits plus further unstaged ones. It is
+      // listed under each, because "have I staged everything?" and "what is
+      // still uncommitted?" are different questions with different answers.
+      if (entry.staged !== "unmodified") groups.staged.push(entry);
+      if (entry.unstaged !== "unmodified") groups.unstaged.push(entry);
+    }
+  }
+  return groups;
+}