gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/src/resources/extensions/remote-questions/tests/telegram-commands.test.ts

@@ -0,0 +1,267 @@
+/**
+ * Tests for Telegram command handling.
+ *
+ * Framework: node:test + node:assert/strict (CONTRIBUTING.md rules)
+ *
+ * Run:
+ *   npm run test:unit
+ *
+ * Or directly after compiling:
+ *   node scripts/compile-tests.mjs && \
+ *   node --import ./scripts/dist-test-resolve.mjs \
+ *        --experimental-test-isolation=process \
+ *        --test "dist-test/src/resources/extensions/remote-questions/tests/*.test.js"
+ *
+ * Covers:
+ *   - Command detection: messages starting with / are commands
+ *   - /help returns a list of all commands
+ *   - /status returns current GSD state
+ *   - /pause writes a stop directive
+ *   - Unknown commands return a helpful error + /help hint
+ *   - Non-commands are NOT treated as commands (regression guard)
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { isCommand, handleCommand, type CommandSender } from "../commands.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeBasePath(): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-cmd-test-"));
+  // Create minimal .gsd directory structure
+  mkdirSync(join(dir, ".gsd", "activity"), { recursive: true });
+  mkdirSync(join(dir, ".gsd", "runtime"), { recursive: true });
+  return dir;
+}
+
+function makeCapturingSender(): { sender: CommandSender; messages: string[] } {
+  const messages: string[] = [];
+  const sender: CommandSender = {
+    async send(text: string) {
+      messages.push(text);
+    },
+  };
+  return { sender, messages };
+}
+
+// ─── isCommand ────────────────────────────────────────────────────────────────
+
+test("isCommand: messages starting with / are commands", () => {
+  assert.equal(isCommand("/help"), true);
+  assert.equal(isCommand("/status"), true);
+  assert.equal(isCommand("/pause"), true);
+  assert.equal(isCommand("/resume"), true);
+  assert.equal(isCommand("/log 5"), true);
+  assert.equal(isCommand("/unknown_cmd"), true);
+});
+
+test("isCommand: bare slash without word character is not a command", () => {
+  assert.equal(isCommand("/ "), false);
+  assert.equal(isCommand("/"), false);
+});
+
+test("isCommand (regression guard): regular messages are NOT commands", () => {
+  assert.equal(isCommand("hello"), false);
+  assert.equal(isCommand("yes"), false);
+  assert.equal(isCommand("1"), false);
+  assert.equal(isCommand("A"), false);
+  assert.equal(isCommand(""), false);
+  assert.equal(isCommand("http://example.com"), false);
+});
+
+// ─── /help ────────────────────────────────────────────────────────────────────
+
+test("/help returns a reply listing all expected commands", async (t) => {
+  const dir = makeBasePath();
+  const { sender, messages } = makeCapturingSender();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  await handleCommand("/help", sender, dir);
+
+  assert.equal(messages.length, 1);
+  const reply = messages[0];
+  // Project prefix must be present
+  assert.ok(reply.startsWith("📁"), `Expected project prefix, got: ${reply}`);
+  // All supported commands must be mentioned
+  for (const cmd of ["/status", "/progress", "/budget", "/pause", "/resume", "/log", "/help"]) {
+    assert.ok(reply.includes(cmd), `Expected /help to mention ${cmd}`);
+  }
+});
+
+// ─── /status ─────────────────────────────────────────────────────────────────
+
+test("/status returns GSD state text (idle when no active session)", async (t) => {
+  const dir = makeBasePath();
+  const { sender, messages } = makeCapturingSender();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  await handleCommand("/status", sender, dir);
+
+  assert.equal(messages.length, 1);
+  const reply = messages[0];
+  assert.ok(reply.length > 0, "Expected non-empty status reply");
+  // Project prefix must be present
+  assert.ok(reply.startsWith("📁"), `Expected project prefix, got: ${reply}`);
+  // Should contain some state indication
+  assert.ok(
+    reply.toLowerCase().includes("state") || reply.toLowerCase().includes("gsd"),
+    `Expected status reply to mention state or GSD, got: ${reply}`,
+  );
+});
+
+test("/status reads paused-session.json when present", async (t) => {
+  const dir = makeBasePath();
+  const { sender, messages } = makeCapturingSender();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  // Write a fake paused-session.json
+  const pausedMeta = {
+    milestoneId: "M001",
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    pausedAt: "2026-01-01T12:00:00.000Z",
+  };
+  writeFileSync(
+    join(dir, ".gsd", "runtime", "paused-session.json"),
+    JSON.stringify(pausedMeta),
+    "utf-8",
+  );
+
+  await handleCommand("/status", sender, dir);
+
+  assert.equal(messages.length, 1);
+  const reply = messages[0];
+  // Project prefix must be present
+  assert.ok(reply.startsWith("📁"), `Expected project prefix, got: ${reply}`);
+  assert.ok(reply.includes("M001"), `Expected milestone ID in status, got: ${reply}`);
+});
+
+// ─── /pause ──────────────────────────────────────────────────────────────────
+
+test("/pause writes a stop capture to CAPTURES.md", async (t) => {
+  const dir = makeBasePath();
+  const { sender, messages } = makeCapturingSender();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  await handleCommand("/pause", sender, dir);
+
+  assert.equal(messages.length, 1);
+  const reply = messages[0];
+
+  // Project prefix must be present
+  assert.ok(reply.startsWith("📁"), `Expected project prefix, got: ${reply}`);
+  // Reply should indicate success
+  assert.ok(
+    reply.toLowerCase().includes("pause") || reply.toLowerCase().includes("directive"),
+    `Expected pause confirmation, got: ${reply}`,
+  );
+
+  // CAPTURES.md should exist
+  const capturesPath = join(dir, ".gsd", "CAPTURES.md");
+  assert.ok(existsSync(capturesPath), "Expected CAPTURES.md to be created by /pause");
+
+  // The file should contain a stop classification
+  const { readFileSync } = await import("node:fs");
+  const content = readFileSync(capturesPath, "utf-8");
+  assert.ok(
+    content.includes("**Classification:** stop"),
+    `Expected stop classification in CAPTURES.md, got:\n${content}`,
+  );
+});
+
+// ─── /resume ─────────────────────────────────────────────────────────────────
+
+test("/resume reports no pending directives when CAPTURES.md is empty", async (t) => {
+  const dir = makeBasePath();
+  const { sender, messages } = makeCapturingSender();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  await handleCommand("/resume", sender, dir);
+
+  assert.equal(messages.length, 1);
+  const reply = messages[0];
+  // Project prefix must be present
+  assert.ok(reply.startsWith("📁"), `Expected project prefix, got: ${reply}`);
+  // Should report that there are no directives to clear
+  assert.ok(
+    reply.toLowerCase().includes("no pending") || reply.toLowerCase().includes("not paused"),
+    `Expected "no pending directives" message, got: ${reply}`,
+  );
+});
+
+// ─── Unknown command ──────────────────────────────────────────────────────────
+
+test("unknown command returns helpful error message with /help hint", async (t) => {
+  const dir = makeBasePath();
+  const { sender, messages } = makeCapturingSender();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  await handleCommand("/invalid_command", sender, dir);
+
+  assert.equal(messages.length, 1);
+  const reply = messages[0];
+  // Project prefix must be present
+  assert.ok(reply.startsWith("📁"), `Expected project prefix, got: ${reply}`);
+  assert.ok(reply.includes("/invalid_command"), "Expected unknown command name in reply");
+  assert.ok(reply.includes("/help"), "Expected /help hint in unknown command reply");
+});
+
+test("unknown command reply differs from /help output", async (t) => {
+  const dir = makeBasePath();
+  const { sender: helpSender, messages: helpMessages } = makeCapturingSender();
+  const { sender: unknownSender, messages: unknownMessages } = makeCapturingSender();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  await handleCommand("/help", helpSender, dir);
+  await handleCommand("/notacommand", unknownSender, dir);
+
+  assert.notEqual(
+    helpMessages[0],
+    unknownMessages[0],
+    "Unknown command reply should differ from /help output",
+  );
+});
+
+// ─── /log ─────────────────────────────────────────────────────────────────────
+
+test("/log returns a message (empty or with entries)", async (t) => {
+  const dir = makeBasePath();
+  const { sender, messages } = makeCapturingSender();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  await handleCommand("/log", sender, dir);
+
+  assert.equal(messages.length, 1);
+  assert.ok(messages[0].length > 0, "Expected non-empty /log reply");
+});
+
+test("/log 3 limits output to last 3 entries", async (t) => {
+  const dir = makeBasePath();
+  const { sender, messages } = makeCapturingSender();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  // Write 5 fake activity log files
+  const activityDir = join(dir, ".gsd", "activity");
+  for (let i = 1; i <= 5; i++) {
+    writeFileSync(
+      join(activityDir, `00${i}-execute-task-M001-S01-T0${i}.jsonl`),
+      '{"type":"toolCall","name":"bash"}\n',
+      "utf-8",
+    );
+  }
+
+  await handleCommand("/log 3", sender, dir);
+
+  assert.equal(messages.length, 1);
+  const reply = messages[0];
+  // Should mention "3" entries (the requested count)
+  assert.ok(reply.includes("3"), `Expected 3 entries in /log 3 reply, got: ${reply}`);
+  // Should not list all 5
+  const entryMatches = (reply.match(/#\d+/g) ?? []).length;
+  assert.ok(entryMatches <= 3, `Expected at most 3 entries, found ${entryMatches}`);
+});

package/src/resources/extensions/search-the-web/command-search-provider.ts

@@ -8,6 +8,7 @@
  * All provider logic lives in provider.ts (S01) — this is pure UI wiring.
  */
 
+import { isAnthropicApi } from '@gsd/pi-ai'
 import type { ExtensionAPI } from '@gsd/pi-coding-agent'
 import type { AutocompleteItem } from '@gsd/pi-tui'
 import {
@@ -90,7 +91,9 @@ export function registerSearchProviderCommand(pi: ExtensionAPI): void {
 
       setSearchProviderPreference(chosen)
       const effective = resolveSearchProvider()
-      const isAnthropic = ctx.model?.provider === 'anthropic'
+      // Gate on api (#4478 / ADR-012): covers claude-code, anthropic-vertex, and
+      // other Anthropic-fronting transports — not just the plain `anthropic` provider.
+      const isAnthropic = isAnthropicApi(ctx.model)
       const nativeNote = isAnthropic ? '\nNote: Native Anthropic web search is also active (automatic, no API key needed).' : ''
       ctx.ui.notify(
         `Search provider set to ${chosen}. Effective provider: ${effective ?? 'none (no API keys)'}${nativeNote}`,

package/src/resources/extensions/search-the-web/native-search.ts

@@ -5,6 +5,7 @@
  * the heavy tool-registration modules.
  */
 
+import { isAnthropicApi } from "@gsd/pi-ai";
 import { resolveSearchProviderFromPreferences } from "../gsd/preferences.js";
 
 /** Tool names for the Brave-backed custom search tools */
@@ -94,7 +95,10 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
   pi.on("model_select", async (event: any, ctx: any) => {
     modelSelectFired = true;
     const wasAnthropic = isAnthropicProvider;
-    isAnthropicProvider = event.model.provider === "anthropic";
+    // Gate on `api` not `provider` (#4478 / ADR-012): covers claude-code OAuth,
+    // anthropic-vertex, and Vercel-gateway-hosted Anthropic — all serve the
+    // Messages API and accept the native web_search tool.
+    isAnthropicProvider = isAnthropicApi(event.model);
 
     const hasBrave = !!process.env.BRAVE_API_KEY;
 
@@ -139,9 +143,15 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
     // the model_select flag, then to the model name heuristic (last resort).
     // The model name heuristic is needed for session restores where
     // modelsAreEqual suppresses model_select AND the SDK doesn't pass model.
-    const eventModel = event.model as { provider: string } | undefined;
+    const eventModel = event.model as { provider?: string; api?: string } | undefined;
     let isAnthropic: boolean;
-    if (eventModel?.provider) {
+    if (eventModel?.api) {
+      // Preferred path: gate on wire protocol (#4478 / ADR-012).
+      isAnthropic = isAnthropicApi(eventModel);
+    } else if (eventModel?.provider) {
+      // Fallback for event shapes that carry provider but not api — only plain
+      // `anthropic` maps unambiguously without the api field. Other Anthropic
+      // transports will arrive via the modelSelectFired or model-name branch.
       isAnthropic = eventModel.provider === "anthropic";
     } else if (modelSelectFired) {
       isAnthropic = isAnthropicProvider;

package/src/resources/extensions/shared/interview-ui.ts

@@ -26,14 +26,16 @@
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { type Theme } from "@gsd/pi-coding-agent";
+import { getMarkdownTheme, type Theme } from "@gsd/pi-coding-agent";
 import {
 	Editor,
 	Key,
+	Markdown,
 	matchesKey,
 	truncateToWidth,
 	type TUI,
 } from "@gsd/pi-tui";
+import { mergeSideBySide } from "./layout-utils.js";
 import { makeUI, INDENT } from "./ui.js";
 
 // ─── Exported types ───────────────────────────────────────────────────────────
@@ -41,6 +43,8 @@ import { makeUI, INDENT } from "./ui.js";
 export interface QuestionOption {
 	label: string;
 	description: string;
+	/** Optional markdown content shown in a side-by-side preview panel when this option is highlighted. */
+	preview?: string;
 }
 
 export interface Question {
@@ -113,6 +117,14 @@ export interface WrapUpOptions {
 const OTHER_OPTION_LABEL = "None of the above";
 const OTHER_OPTION_DESCRIPTION = "Select to type your own answer.";
 
+// Preview layout constants
+const MIN_PREVIEW_WIDTH = 30;
+const MIN_OPTIONS_WIDTH = 30;
+const PREVIEW_RATIO = 0.60;       // preview gets the majority of the width
+const DIVIDER_CHARS = " │ ";
+const DIVIDER_WIDTH = 3;
+const PREVIEW_MAX_LINES = 20;     // hard cap — keeps total ≤ 24 rows for single-question
+
 // ─── Wrap-up screen ───────────────────────────────────────────────────────────
 
 export async function showWrapUpScreen(
@@ -520,6 +532,99 @@ export async function showInterviewRound(
 			return lines;
 		}
 
+		// ── Preview helpers ──────────────────────────────────────────────
+
+		let mdThemeCache: ReturnType<typeof getMarkdownTheme> | null = null;
+		let previewCache: { markdown: string; width: number; lines: string[] } | null = null;
+
+		function questionHasAnyPreview(): boolean {
+			return questions[currentIdx].options.some(
+				(o) => o.preview != null && o.preview.trim().length > 0,
+			);
+		}
+
+		function getCurrentPreview(): string | null {
+			const q = questions[currentIdx];
+			const idx = states[currentIdx].cursorIndex;
+			if (idx < q.options.length) {
+				const preview = q.options[idx].preview;
+				return preview && preview.trim().length > 0 ? preview : null;
+			}
+			return null;
+		}
+
+		function renderOptionsColumn(optWidth: number): string[] {
+			const ui = makeUI(theme, optWidth);
+			const col: string[] = [];
+			const push = (...rows: string[][]) => { for (const r of rows) col.push(...r); };
+
+			const q = questions[currentIdx];
+			const st = states[currentIdx];
+			const multiSel = isMultiSelect(currentIdx);
+
+			push(ui.question(` ${q.question}`));
+			if (multiSel) push(ui.meta("  (Select all that apply)"));
+			push(ui.blank());
+
+			for (let i = 0; i < q.options.length; i++) {
+				const opt = q.options[i];
+				const isCursor = i === st.cursorIndex;
+				if (multiSel) {
+					const isChecked = st.checkedIndices.has(i);
+					if (isCursor && !focusNotes) push(ui.checkboxSelected(opt.label, opt.description, isChecked));
+					else push(ui.checkboxUnselected(opt.label, opt.description, isChecked, focusNotes));
+				} else {
+					const isCommitted = i === st.committedIndex;
+					if (isCursor && !focusNotes) {
+						push(ui.optionSelected(i + 1, opt.label, opt.description, isCommitted));
+					} else {
+						push(ui.optionUnselected(i + 1, opt.label, opt.description, { isCommitted, isFocusDimmed: focusNotes }));
+					}
+				}
+			}
+
+			const ndIdx = noneOrDoneIdx(currentIdx);
+			const ndCursor = ndIdx === st.cursorIndex;
+			if (multiSel) {
+				push(ui.blank());
+				if (ndCursor && !focusNotes) push(ui.doneSelected());
+				else push(ui.doneUnselected());
+			} else {
+				const ndCommitted = ndIdx === st.committedIndex;
+				if (ndCursor && !focusNotes) {
+					push(ui.slotSelected(OTHER_OPTION_LABEL, OTHER_OPTION_DESCRIPTION, ndCommitted));
+				} else {
+					push(ui.slotUnselected(OTHER_OPTION_LABEL, OTHER_OPTION_DESCRIPTION, { isCommitted: ndCommitted, isFocusDimmed: focusNotes }));
+				}
+			}
+
+			if (st.notesVisible || focusNotes) {
+				push(ui.blank(), ui.notesLabel(focusNotes));
+				if (focusNotes) {
+					for (const line of getEditor().render(optWidth - 2)) col.push(truncateToWidth(` ${line}`, optWidth));
+				} else if (st.notes) {
+					push(ui.notesText(st.notes));
+				}
+			}
+
+			return col;
+		}
+
+		function renderPreviewColumn(markdown: string, previewWidth: number): string[] {
+			if (previewCache && previewCache.markdown === markdown && previewCache.width === previewWidth) {
+				return previewCache.lines;
+			}
+			if (!mdThemeCache) mdThemeCache = getMarkdownTheme();
+			const header = [
+				truncateToWidth(theme.fg("accent", theme.bold(" Preview")), previewWidth),
+				truncateToWidth(theme.fg("dim", " " + "─".repeat(Math.max(0, previewWidth - 2))), previewWidth),
+			];
+			const md = new Markdown(markdown, 1, 0, mdThemeCache);
+			const lines = [...header, ...md.render(previewWidth)];
+			previewCache = { markdown, width: previewWidth, lines };
+			return lines;
+		}
+
 		// ── Main render ──────────────────────────────────────────────────
 
 		function render(width: number): string[] {
@@ -528,6 +633,95 @@ export async function showInterviewRound(
 			if (showingExitConfirm) { cachedLines = renderExitConfirm(width); return cachedLines; }
 			if (showingReview) { cachedLines = renderReviewScreen(width); return cachedLines; }
 
+			const useSideBySide = questionHasAnyPreview()
+				&& width >= (MIN_OPTIONS_WIDTH + MIN_PREVIEW_WIDTH + DIVIDER_WIDTH);
+
+			if (useSideBySide) {
+				// ── Preview path ──────────────────────────────────────
+				const ui = makeUI(theme, width);
+				const lines: string[] = [];
+				const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
+
+				push(ui.bar());
+
+				if (isMultiQuestion) {
+					const unanswered = questions.filter((_, i) => !isQuestionAnswered(i)).length;
+					const answeredSet = new Set(questions.map((_, i) => i).filter(i => isQuestionAnswered(i)));
+					push(ui.questionTabs(questions.map(q => q.header), currentIdx, answeredSet));
+					push(ui.blank());
+					const progressParts = [
+						opts.progress,
+						`Question ${currentIdx + 1}/${questions.length}`,
+						unanswered > 0 ? `${unanswered} unanswered` : null,
+					].filter(Boolean).join("  •  ");
+					if (progressParts) push(ui.meta(`  ${progressParts}`));
+					push(ui.blank());
+				} else {
+					if (opts.progress) push(ui.meta(`  ${opts.progress}`), ui.blank());
+				}
+
+				// Side-by-side body — fixed height per render, capped to terminal.
+				// tuiChrome accounts for elements rendered outside the interview
+				// component: spinner/loader (1-2), status line (1), tool header (1),
+				// plus a safety margin for future additions.
+				const termRows = (typeof process !== "undefined" && process.stdout?.rows) || 24;
+				const footerLines = 3; // blank + hints + bar
+				const tuiChrome = 5;
+				const maxBody = Math.min(PREVIEW_MAX_LINES, Math.max(6, termRows - lines.length - footerLines - tuiChrome));
+
+				const previewWidth = Math.max(MIN_PREVIEW_WIDTH, Math.floor(width * PREVIEW_RATIO));
+				const leftWidth = Math.max(MIN_OPTIONS_WIDTH, width - previewWidth - DIVIDER_WIDTH);
+
+				const fullLeft = renderOptionsColumn(leftWidth);
+				const leftLines = fullLeft.slice(0, maxBody);
+				if (fullLeft.length > maxBody) {
+					const n = fullLeft.length - maxBody + 1;
+					const lbl = `+${n} lines hidden`;
+					const d = "─".repeat(Math.max(0, Math.floor((leftWidth - lbl.length - 2) / 2)));
+					leftLines[maxBody - 1] = truncateToWidth(theme.fg("dim", ` ${d} ${lbl} ${d}`), leftWidth);
+				}
+
+				const preview = getCurrentPreview();
+				const fullRight = preview ? renderPreviewColumn(preview, previewWidth) : [];
+				const rightLines = fullRight.slice(0, maxBody);
+				if (fullRight.length > maxBody) {
+					const n = fullRight.length - maxBody + 1;
+					const lbl = `+${n} lines hidden`;
+					const d = "─".repeat(Math.max(0, Math.floor((previewWidth - lbl.length - 2) / 2)));
+					rightLines[maxBody - 1] = truncateToWidth(theme.fg("dim", ` ${d} ${lbl} ${d}`), previewWidth);
+				}
+
+				while (leftLines.length < maxBody) leftLines.push("");
+				while (rightLines.length < maxBody) rightLines.push("");
+				const divider = theme.fg("dim", DIVIDER_CHARS);
+				lines.push(...mergeSideBySide(leftLines, rightLines, leftWidth, divider, width));
+
+				// Footer
+				push(ui.blank());
+				const isLast = !isMultiQuestion || currentIdx === questions.length - 1;
+				const hints: string[] = [];
+				if (focusNotes) {
+					hints.push("enter to confirm");
+					hints.push("tab or esc to close notes");
+				} else if (isMultiSelect(currentIdx)) {
+					hints.push("space to toggle");
+					if (isMultiQuestion) hints.push("←/→ navigate questions");
+					hints.push("tab to add notes");
+					hints.push(isLast && allAnswered() ? "enter to review" : "enter to next");
+				} else {
+					hints.push("tab to add notes");
+					if (isMultiQuestion) hints.push("←/→ navigate");
+					hints.push(isLast && allAnswered() ? "enter to review" : "enter to next");
+				}
+				hints.push("esc to exit");
+				push(ui.hints(hints), ui.bar());
+
+				cachedLines = lines;
+				return lines;
+			}
+
+			// ── Original path — no preview, untouched ────────────────
+
 			const ui = makeUI(theme, width);
 			const lines: string[] = [];
 			const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };

package/src/resources/extensions/shared/layout-utils.ts

@@ -47,3 +47,29 @@ export function fitColumns(parts: string[], width: number, separator = "  "): st
   }
   return truncateToWidth(result, width);
 }
+
+/**
+ * Merge two sets of lines into a side-by-side layout with a vertical divider.
+ *
+ * Each left line is padded to `leftWidth`, then joined with a styled divider
+ * and the corresponding right line. Output lines are truncated to `totalWidth`.
+ */
+export function mergeSideBySide(
+  leftLines: string[],
+  rightLines: string[],
+  leftWidth: number,
+  divider: string,
+  totalWidth: number,
+): string[] {
+  const maxLen = Math.max(leftLines.length, rightLines.length);
+  const merged: string[] = [];
+
+  for (let i = 0; i < maxLen; i++) {
+    const left = i < leftLines.length ? leftLines[i] : "";
+    const right = i < rightLines.length ? rightLines[i] : "";
+    const paddedLeft = padRight(left, leftWidth);
+    merged.push(truncateToWidth(paddedLeft + divider + right, totalWidth));
+  }
+
+  return merged;
+}

package/src/resources/extensions/shared/rtk-shared.ts

@@ -0,0 +1,58 @@
+import { existsSync } from "node:fs";
+import { homedir as osHomedir } from "node:os";
+import { delimiter, join } from "node:path";
+
+export const GSD_RTK_DISABLED_ENV = "GSD_RTK_DISABLED";
+export const GSD_RTK_PATH_ENV = "GSD_RTK_PATH";
+export const RTK_TELEMETRY_DISABLED_ENV = "RTK_TELEMETRY_DISABLED";
+
+export function isTruthy(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+
+export function isRtkEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return !isTruthy(env[GSD_RTK_DISABLED_ENV]);
+}
+
+export function getManagedRtkDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(env.GSD_HOME || join(osHomedir(), ".gsd"), "agent", "bin");
+}
+
+export function getRtkBinaryName(platform: NodeJS.Platform = process.platform): string {
+  return platform === "win32" ? "rtk.exe" : "rtk";
+}
+
+export function getPathValue(env: NodeJS.ProcessEnv): string | undefined {
+  const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path");
+  return pathKey ? env[pathKey] : env.PATH;
+}
+
+export function resolvePathCandidates(pathValue: string | undefined): string[] {
+  if (!pathValue) return [];
+  return pathValue
+    .split(delimiter)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+export function resolveSystemRtkPath(
+  pathValue: string | undefined,
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  const candidates = platform === "win32"
+    ? ["rtk.exe", "rtk.cmd", "rtk.bat", "rtk"]
+    : ["rtk"];
+
+  for (const dir of resolvePathCandidates(pathValue)) {
+    for (const candidate of candidates) {
+      const fullPath = join(dir, candidate);
+      if (existsSync(fullPath)) {
+        return fullPath;
+      }
+    }
+  }
+
+  return null;
+}