gsd-pi 2.33.1-dev.235d83a → 2.33.1-dev.29a8268

package/dist/resources/extensions/shared/next-action-ui.ts

@@ -0,0 +1,212 @@
+/**
+ * Shared next-action prompt for GSD extensions.
+ *
+ * Renders a consistent "step complete" UI at the end of every GSD stage:
+ *
+ *   ─────────────────────────────────────────
+ *   ✓  Phase 1 research complete
+ *
+ *      [caller summary lines]
+ *
+ *      [optional extra content block]
+ *
+ *   Files written:
+ *      .gsd/phases/01-foo/01-RESEARCH.md
+ *
+ *   › 1. Plan phase 1           ← recommended, pre-selected
+ *        Create PLAN.md files for execution
+ *
+ *     2. Not yet
+ *        Run /gsd-plan-phase 1 when ready.
+ *   ─────────────────────────────────────────
+ *
+ * Usage:
+ *
+ *   const choice = await showNextAction(ctx, {
+ *     title: "Phase 1 research complete",
+ *     summary: ["6 libraries evaluated", "Stack: Phaser 3 + TypeScript"],
+ *     files: ["/abs/path/to/01-RESEARCH.md"],
+ *     extra: ["Wave 1: 01-01, 01-02  (parallel)", "Wave 2: 01-03"],
+ *     actions: [
+ *       { id: "plan",  label: "Plan phase 1",   description: "Create PLAN.md files for execution", recommended: true },
+ *       { id: "later", label: "Discuss first",  description: "Capture constraints before planning" },
+ *     ],
+ *     notYetMessage: "Run /gsd-plan-phase 1 when ready.",
+ *   });
+ *
+ *   // choice is one of the action ids, or "not_yet"
+ *   if (choice === "plan") { ... }
+ *
+ * "Not yet" is always appended automatically as the last option.
+ * Pressing Escape also resolves as "not_yet".
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { type Theme } from "@gsd/pi-coding-agent";
+import { Key, matchesKey, type TUI } from "@gsd/pi-tui";
+import { makeUI } from "./ui.js";
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export interface NextAction {
+	/** Unique id returned when this action is chosen. */
+	id: string;
+	/** Short label shown in the list (e.g. "Plan phase 1"). */
+	label: string;
+	/** One-line description shown below the label. */
+	description: string;
+	/** Pre-selects this item and renders it with a (recommended) marker. At most one. */
+	recommended?: boolean;
+}
+
+export interface NextActionOptions {
+	/** Bold heading after the ✓ — e.g. "Phase 1 research complete". */
+	title: string;
+	/**
+	 * Stage-specific narrative lines rendered below the title.
+	 * Keep these short and informative.
+	 */
+	summary?: string[];
+	/**
+	 * Absolute paths to files that were written this step.
+	 * Displayed as relative paths from cwd when possible.
+	 */
+	files?: string[];
+	/**
+	 * Optional extra content rendered between the file list and the actions.
+	 * Each string is one display line — already formatted by the caller.
+	 */
+	extra?: string[];
+	/** The action choices. "Not yet" is always appended automatically. */
+	actions: NextAction[];
+	/**
+	 * Message shown in the "Not yet" description line.
+	 * e.g. "Run /gsd-plan-phase 1 when ready."
+	 */
+	notYetMessage?: string;
+	/**
+	 * Current working directory — used to make file paths relative.
+	 * Defaults to process.cwd().
+	 */
+	cwd?: string;
+}
+
+/**
+ * Show the next-action prompt and return the chosen action id, or "not_yet".
+ */
+export async function showNextAction(
+	ctx: ExtensionCommandContext,
+	opts: NextActionOptions,
+): Promise<string> {
+	const cwd = opts.cwd ?? process.cwd();
+	const notYetMessage = opts.notYetMessage ?? "Continue when ready.";
+
+	const allActions: NextAction[] = [
+		...opts.actions,
+		{ id: "not_yet", label: "Not yet", description: notYetMessage },
+	];
+
+	const recommendedIdx = allActions.findIndex((a) => a.recommended);
+	const defaultIdx = recommendedIdx >= 0 ? recommendedIdx : 0;
+
+	const relativeFiles = (opts.files ?? []).map((f) => {
+		try {
+			const rel = f.startsWith(cwd) ? f.slice(cwd.length).replace(/^\//, "") : f;
+			return rel || f;
+		} catch {
+			return f;
+		}
+	});
+
+	const result = await ctx.ui.custom<string>((_tui: TUI, theme: Theme, _kb, done) => {
+		let cursorIdx = defaultIdx;
+		let cachedLines: string[] | undefined;
+
+		function refresh() { cachedLines = undefined; _tui.requestRender(); }
+
+		function handleInput(data: string) {
+			if (matchesKey(data, Key.up)) { cursorIdx = Math.max(0, cursorIdx - 1); refresh(); return; }
+			if (matchesKey(data, Key.down)) { cursorIdx = Math.min(allActions.length - 1, cursorIdx + 1); refresh(); return; }
+			const num = parseInt(data, 10);
+			if (!isNaN(num) && num >= 1 && num <= allActions.length) { done(allActions[num - 1].id); return; }
+			if (matchesKey(data, Key.enter) || matchesKey(data, Key.space)) { done(allActions[cursorIdx].id); return; }
+			if (matchesKey(data, Key.escape)) { done("not_yet"); return; }
+		}
+
+		function render(width: number): string[] {
+			if (cachedLines) return cachedLines;
+			const ui = makeUI(theme, width);
+			const lines: string[] = [];
+			const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
+
+			// ── Header — uses success colour to signal completion ────────────
+			// Note: next-action intentionally uses "success" for its bar/title
+			// to distinguish it from regular accent-coloured screens.
+			push(ui.bar());
+			push(ui.blank());
+			push(ui.header(`  ✓  ${opts.title}`));
+
+			// ── Summary ──────────────────────────────────────────────────────
+			if (opts.summary && opts.summary.length > 0) {
+				push(ui.blank());
+				for (const line of opts.summary) push(ui.subtitle(`     ${line}`));
+			}
+
+			// ── Files written ─────────────────────────────────────────────────
+			if (relativeFiles.length > 0) {
+				push(ui.blank());
+				push(ui.meta("  Files written:"));
+				for (const f of relativeFiles) push(ui.meta(`     ${f}`));
+			}
+
+			// ── Extra content ─────────────────────────────────────────────────
+			if (opts.extra && opts.extra.length > 0) {
+				push(ui.blank());
+				for (const line of opts.extra) push(ui.subtitle(`  ${line}`));
+			}
+
+			// ── Actions ───────────────────────────────────────────────────────
+			push(ui.blank());
+			for (let i = 0; i < allActions.length; i++) {
+				const action = allActions[i];
+				const isSelected = i === cursorIdx;
+				const isNotYet = action.id === "not_yet";
+				const tag = action.recommended ? "(recommended)" : undefined;
+
+				if (isSelected) {
+					push(ui.actionSelected(i + 1, action.label, action.description, tag));
+				} else if (isNotYet) {
+					push(ui.actionDim(i + 1, action.label, action.description));
+				} else {
+					push(ui.actionUnselected(i + 1, action.label, action.description, tag));
+				}
+				push(ui.blank());
+			}
+
+			// ── Footer ────────────────────────────────────────────────────────
+			const numHint = allActions.map((_, i) => `${i + 1}`).join("/");
+			push(ui.hints([`↑/↓ to choose`, `${numHint} to quick-select`, `enter to confirm`]));
+			push(ui.bar());
+
+			cachedLines = lines;
+			return lines;
+		}
+
+		return { render, invalidate: () => { cachedLines = undefined; }, handleInput };
+	});
+
+	// Fallback for RPC mode where ctx.ui.custom() returns undefined (#447).
+	// Fall back to ctx.ui.select() which IS implemented in RPC mode.
+	if (result === undefined || result === null) {
+		const labels = allActions.map(a => {
+			const tag = a.recommended ? " (recommended)" : "";
+			return `${a.label}${tag}: ${a.description}`;
+		});
+		const selected = await ctx.ui.select(opts.title, labels);
+		if (selected === undefined || selected === null) return "not_yet";
+		const idx = labels.indexOf(selected as string);
+		return idx >= 0 ? allActions[idx].id : "not_yet";
+	}
+
+	return result;
+}

package/dist/resources/extensions/shared/{path-display.js → path-display.ts}

@@ -9,10 +9,11 @@
  * Filesystem operations (fs.readFile, path.join, spawn cwd) handle native
  * separators correctly and should NOT be normalized.
  */
+
 /**
  * Convert a filesystem path to forward-slash form for display in LLM text.
  * No-op on Unix. On Windows converts `C:\Users\name` to `C:/Users/name`.
  */
-export function toPosixPath(fsPath) {
-    return fsPath.replaceAll("\\", "/");
+export function toPosixPath(fsPath: string): string {
+  return fsPath.replaceAll("\\", "/");
 }

package/dist/resources/extensions/shared/sanitize.ts

@@ -0,0 +1,19 @@
+/**
+ * Sanitize error messages by redacting token-like strings before surfacing.
+ */
+
+const TOKEN_PATTERNS = [
+  /xoxb-[A-Za-z0-9\-]+/g,    // Slack bot tokens
+  /xoxp-[A-Za-z0-9\-]+/g,    // Slack user tokens
+  /xoxa-[A-Za-z0-9\-]+/g,    // Slack app tokens
+  /\d{8,10}:[A-Za-z0-9_-]{35}/g, // Telegram bot tokens
+  /[A-Za-z0-9_\-.]{20,}/g,   // Long opaque secrets (Discord tokens, etc.)
+];
+
+export function sanitizeError(msg: string): string {
+  let sanitized = msg;
+  for (const pattern of TOKEN_PATTERNS) {
+    sanitized = sanitized.replace(pattern, "[REDACTED]");
+  }
+  return sanitized;
+}

package/dist/resources/extensions/shared/terminal.ts

@@ -0,0 +1,23 @@
+/**
+ * Terminal capability detection for keyboard shortcut support.
+ *
+ * Ctrl+Alt shortcuts require the Kitty keyboard protocol or modifyOtherKeys.
+ * Terminals that lack this support silently swallow the key combos.
+ */
+
+const UNSUPPORTED_TERMS = ["apple_terminal", "warpterm"];
+
+export function supportsCtrlAltShortcuts(): boolean {
+  const term = (process.env.TERM_PROGRAM || "").toLowerCase();
+  const jetbrains = (process.env.TERMINAL_EMULATOR || "").toLowerCase().includes("jetbrains");
+  return !UNSUPPORTED_TERMS.some((t) => term.includes(t)) && !jetbrains;
+}
+
+/**
+ * Returns a shortcut description that includes a slash-command fallback hint
+ * when the current terminal likely can't fire Ctrl+Alt combos.
+ */
+export function shortcutDesc(base: string, fallbackCmd: string): string {
+  if (supportsCtrlAltShortcuts()) return base;
+  return `${base} — shortcut may not work in this terminal, use ${fallbackCmd}`;
+}

package/dist/resources/extensions/shared/tests/format-utils.test.ts

@@ -0,0 +1,153 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  formatDuration,
+  padRight,
+  joinColumns,
+  centerLine,
+  fitColumns,
+  sparkline,
+  stripAnsi,
+} from "../format-utils.js";
+
+describe("formatDuration", () => {
+  it("formats seconds", () => {
+    assert.equal(formatDuration(0), "0s");
+    assert.equal(formatDuration(5_000), "5s");
+    assert.equal(formatDuration(59_000), "59s");
+  });
+
+  it("formats minutes and seconds", () => {
+    assert.equal(formatDuration(60_000), "1m 0s");
+    assert.equal(formatDuration(90_000), "1m 30s");
+    assert.equal(formatDuration(3_540_000), "59m 0s");
+  });
+
+  it("formats hours and minutes", () => {
+    assert.equal(formatDuration(3_600_000), "1h 0m");
+    assert.equal(formatDuration(5_400_000), "1h 30m");
+    assert.equal(formatDuration(7_200_000), "2h 0m");
+  });
+});
+
+describe("padRight", () => {
+  it("pads plain text to width", () => {
+    const result = padRight("abc", 6);
+    assert.equal(result, "abc   ");
+  });
+
+  it("does not pad when text fills width", () => {
+    const result = padRight("abcdef", 6);
+    assert.equal(result, "abcdef");
+  });
+
+  it("does not pad when text exceeds width", () => {
+    const result = padRight("abcdefgh", 6);
+    assert.equal(result, "abcdefgh");
+  });
+});
+
+describe("joinColumns", () => {
+  it("joins left and right with spacing", () => {
+    const result = joinColumns("left", "right", 20);
+    assert.equal(result.length, 20);
+    assert.ok(result.startsWith("left"));
+    assert.ok(result.endsWith("right"));
+  });
+
+  it("truncates when content overflows", () => {
+    const result = joinColumns("a".repeat(20), "b".repeat(20), 30);
+    // Should be truncated to 30 chars
+    assert.ok(result.length <= 30);
+  });
+});
+
+describe("centerLine", () => {
+  it("centers text within width", () => {
+    const result = centerLine("hi", 10);
+    assert.equal(result, "    hi");
+  });
+
+  it("truncates when content exceeds width", () => {
+    const result = centerLine("abcdefgh", 4);
+    assert.ok(result.length <= 4);
+  });
+});
+
+describe("fitColumns", () => {
+  it("joins parts that fit", () => {
+    const result = fitColumns(["aaa", "bbb", "ccc"], 20);
+    assert.ok(result.includes("aaa"));
+    assert.ok(result.includes("bbb"));
+    assert.ok(result.includes("ccc"));
+  });
+
+  it("drops parts that overflow", () => {
+    const result = fitColumns(["aaa", "bbb", "ccc"], 10);
+    assert.ok(result.includes("aaa"));
+    // May or may not include bbb depending on separator width
+  });
+
+  it("returns empty string for empty array", () => {
+    assert.equal(fitColumns([], 80), "");
+  });
+
+  it("filters out empty strings", () => {
+    const result = fitColumns(["aaa", "", "bbb"], 80);
+    assert.ok(result.includes("aaa"));
+    assert.ok(result.includes("bbb"));
+  });
+});
+
+describe("sparkline", () => {
+  it("returns empty string for empty array", () => {
+    assert.equal(sparkline([]), "");
+  });
+
+  it("renders all lowest blocks for all-zero values", () => {
+    const result = sparkline([0, 0, 0]);
+    assert.equal(result.length, 3);
+    // All chars should be the same (lowest block)
+    assert.equal(result[0], result[1]);
+    assert.equal(result[1], result[2]);
+  });
+
+  it("renders highest block for max value", () => {
+    const result = sparkline([0, 10, 5]);
+    assert.equal(result.length, 3);
+    // Middle should be highest block (█)
+    assert.equal(result[1], "\u2588");
+  });
+
+  it("handles single value", () => {
+    const result = sparkline([42]);
+    assert.equal(result.length, 1);
+    assert.equal(result, "\u2588");
+  });
+
+  it("handles large arrays without stack overflow", () => {
+    const largeArray = new Array(100_000).fill(0).map((_, i) => i);
+    const result = sparkline(largeArray);
+    assert.equal(result.length, 100_000);
+  });
+});
+
+describe("stripAnsi", () => {
+  it("strips ANSI escape sequences", () => {
+    const result = stripAnsi("\x1b[31mred\x1b[0m text");
+    assert.equal(result, "red text");
+  });
+
+  it("returns plain text unchanged", () => {
+    assert.equal(stripAnsi("plain text"), "plain text");
+  });
+
+  it("strips multiple escape sequences", () => {
+    const result = stripAnsi("\x1b[1m\x1b[32mbold green\x1b[0m");
+    assert.equal(result, "bold green");
+  });
+
+  it("handles empty string", () => {
+    assert.equal(stripAnsi(""), "");
+  });
+});