gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.96d4bb599

package/src/resources/extensions/gsd/commands-extract-learnings.ts

@@ -2,189 +2,395 @@
  * GSD Command — /gsd extract-learnings
  *
  * Analyses completed milestone artefacts and dispatches an LLM turn that
- * extracts structured knowledge into 4 categories:
- *   Decisions · Lessons · Patterns · Surprises
+ * extracts structured knowledge into 4 categories (Decisions · Lessons ·
+ * Patterns · Surprises), writes a LEARNINGS.md audit trail, and persists
+ * the durable subset to GSD's cross-session surfaces:
+ *
+ *   - Patterns + Lessons → appended to .gsd/KNOWLEDGE.md (inlined into
+ *     every future dispatch prompt via auto-prompts::inlineGsdRootFile).
+ *   - Decisions → persisted via the gsd_save_decision MCP tool, which
+ *     regenerates .gsd/DECISIONS.md from the DB.
+ *   - Surprises → stay only in LEARNINGS.md (milestone-local context).
+ *
+ * The same extraction steps are reused by the complete-milestone prompt
+ * via buildExtractionStepsBlock — single source of truth.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import { existsSync, readFileSync } from "node:fs";
-import { join, basename } from "node:path";
+import { join, basename, relative } from "node:path";
 
 import { gsdRoot, resolveMilestonePath } from "./paths.js";
 import { projectRoot } from "./commands/context.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
+/**
+ * Resolved paths for the four artefact files that feed a milestone-scoped
+ * learnings extraction. Paths are absolute when the file exists; `null`
+ * otherwise. `missingRequired` lists the filenames (not full paths) of the
+ * required artefacts that could not be found.
+ */
 export interface PhaseArtifacts {
-  plan: string | null;
+  /** Absolute path to `{MID}-ROADMAP.md`, or `null` if the file is missing. */
+  roadmap: string | null;
+  /** Absolute path to `{MID}-SUMMARY.md`, or `null` if the file is missing. */
   summary: string | null;
+  /** Absolute path to `{MID}-VERIFICATION.md` (optional), or `null`. */
   verification: string | null;
+  /** Absolute path to `{MID}-UAT.md` (optional), or `null`. */
   uat: string | null;
+  /** Filenames of required artefacts that could not be resolved. */
   missingRequired: string[];
 }
 
+/**
+ * Full context required by `buildExtractLearningsPrompt` to construct the
+ * manual `/gsd extract-learnings` dispatch prompt. Covers the milestone
+ * identity, the output target, the inlined artefact contents, and any
+ * missing optional artefacts that should be surfaced to the agent.
+ */
 export interface ExtractLearningsPromptContext {
+  /** Milestone identifier, e.g. `"M001"` or `"M001-ush8s3"` (team mode). */
   milestoneId: string;
+  /** Human-readable milestone title, taken from the roadmap H1 when present. */
   milestoneName: string;
+  /** Absolute filesystem path at which the LEARNINGS.md file will be written. */
   outputPath: string;
+  /** Project-root-relative path for the same file, used in prompt prose. */
   relativeOutputPath: string;
-  planContent: string;
+  /** Inlined contents of `{MID}-ROADMAP.md` (required). */
+  roadmapContent: string;
+  /** Inlined contents of `{MID}-SUMMARY.md` (required). */
   summaryContent: string;
+  /** Inlined contents of `{MID}-VERIFICATION.md` when the file exists, else `null`. */
   verificationContent: string | null;
+  /** Inlined contents of `{MID}-UAT.md` when the file exists, else `null`. */
   uatContent: string | null;
+  /** Filenames of optional artefacts that were not available for inlining. */
   missingArtifacts: string[];
+  /** Display name of the enclosing project (from `.gsd/PROJECT.md` or dir basename). */
   projectName: string;
 }
 
+/**
+ * Minimal context required to render the structured-extraction steps block.
+ *
+ * The block is milestone-scoped — it only needs the milestone ID (used for
+ * `scope` columns and `gsd_save_decision` calls) and the LEARNINGS.md output
+ * path (both absolute for unambiguous writes and relative for display in the
+ * prompt). Artefact content is NOT part of this context because both render
+ * sites (manual path and complete-milestone auto path) supply it separately.
+ */
+export interface ExtractionStepsContext {
+  /** Milestone identifier, e.g. `"M001"` or `"M001-ush8s3"` (team mode). */
+  milestoneId: string;
+  /** Absolute filesystem path at which the LEARNINGS.md file will be written. */
+  outputPath: string;
+  /** Project-root-relative path for the same file, used in prompt prose. */
+  relativeOutputPath: string;
+}
+
+/**
+ * Shape of the YAML frontmatter written at the top of `{MID}-LEARNINGS.md`.
+ *
+ * Produced by `buildFrontmatter` — consumed only by the human-readable audit
+ * trail, not by any downstream automated pipeline. The `counts` object and
+ * `missing_artifacts` list exist so reviewers can spot truncated extractions
+ * at a glance.
+ */
 export interface FrontmatterContext {
+  /** Milestone identifier (becomes the `phase` key). */
   milestoneId: string;
+  /** Milestone title (becomes the `phase_name` key). */
   milestoneName: string;
+  /** Project display name. */
   projectName: string;
+  /** ISO-8601 UTC timestamp of when the extraction was performed. */
   generatedAt: string;
+  /** Counts of extracted items per category. */
   counts: {
     decisions: number;
     lessons: number;
     patterns: number;
     surprises: number;
   };
+  /** Filenames of optional artefacts that were not available during extraction. */
   missingArtifacts: string[];
 }
 
 // ─── Pure functions ───────────────────────────────────────────────────────────
 
+/**
+ * Parses the argument string passed to `/gsd extract-learnings`.
+ *
+ * Returns `{ milestoneId: null }` for empty / whitespace-only input — the
+ * handler surfaces a usage hint in that case. A non-empty trimmed value is
+ * returned as-is; the handler validates that the milestone actually exists.
+ */
 export function parseExtractLearningsArgs(args: string): { milestoneId: string | null } {
   const trimmed = args.trim();
   return { milestoneId: trimmed || null };
 }
 
+/**
+ * Builds the absolute path at which the LEARNINGS.md audit trail should be
+ * written for the given milestone.
+ */
 export function buildLearningsOutputPath(milestoneDir: string, milestoneId: string): string {
   return join(milestoneDir, `${milestoneId}-LEARNINGS.md`);
 }
 
+/**
+ * Resolves the milestone-scoped artefact paths needed to perform an
+ * extraction. The milestone's ROADMAP and SUMMARY files are required; the
+ * VERIFICATION and UAT files are optional. Missing required files are
+ * reported by filename in `missingRequired` so the handler can surface a
+ * precise error without swallowing the cause.
+ */
 export function resolvePhaseArtifacts(milestoneDir: string, milestoneId: string): PhaseArtifacts {
   const missingRequired: string[] = [];
 
-  const planFile = `${milestoneId}-PLAN.md`;
+  const roadmapFile = `${milestoneId}-ROADMAP.md`;
   const summaryFile = `${milestoneId}-SUMMARY.md`;
   const verificationFile = `${milestoneId}-VERIFICATION.md`;
   const uatFile = `${milestoneId}-UAT.md`;
 
-  const planPath = join(milestoneDir, planFile);
+  const roadmapPath = join(milestoneDir, roadmapFile);
   const summaryPath = join(milestoneDir, summaryFile);
   const verificationPath = join(milestoneDir, verificationFile);
   const uatPath = join(milestoneDir, uatFile);
 
-  const plan = existsSync(planPath) ? planPath : null;
+  const roadmap = existsSync(roadmapPath) ? roadmapPath : null;
   const summary = existsSync(summaryPath) ? summaryPath : null;
   const verification = existsSync(verificationPath) ? verificationPath : null;
   const uat = existsSync(uatPath) ? uatPath : null;
 
-  if (!plan) missingRequired.push(planFile);
+  if (!roadmap) missingRequired.push(roadmapFile);
   if (!summary) missingRequired.push(summaryFile);
 
-  return { plan, summary, verification, uat, missingRequired };
+  return { roadmap, summary, verification, uat, missingRequired };
 }
 
-export function buildExtractLearningsPrompt(ctx: ExtractLearningsPromptContext): string {
-  const optionalSections: string[] = [];
+/**
+ * Canonical structured-extraction instructions.
+ *
+ * Used in two places — kept in sync by construction:
+ *   1. /gsd extract-learnings manual path (buildExtractLearningsPrompt).
+ *   2. complete-milestone auto path ({{extractLearningsSteps}} placeholder,
+ *      injected by auto-prompts::buildCompleteMilestonePrompt).
+ *
+ * The block assumes the LLM already has the milestone artefacts available —
+ * either inlined directly in the manual path, or via {{inlinedContext}} in
+ * complete-milestone. It does not re-inline artefacts.
+ */
+export function buildExtractionStepsBlock(ctx: ExtractionStepsContext): string {
+  return `## Structured Learnings Extraction
 
-  if (ctx.verificationContent) {
-    optionalSections.push(`## Verification Report\n\n${ctx.verificationContent}`);
-  }
-  if (ctx.uatContent) {
-    optionalSections.push(`## UAT Report\n\n${ctx.uatContent}`);
-  }
+Perform the following steps IN ORDER. Each step is mandatory unless explicitly
+marked optional. These instructions are the single source of truth shared by
+\`/gsd extract-learnings\` and the auto-mode milestone-completion turn.
 
-  const missingNote = ctx.missingArtifacts.length > 0
-    ? `\nNote: The following optional artefacts were not available: ${ctx.missingArtifacts.join(", ")}\n`
-    : "";
+### Step 1 — Classify findings into four categories
 
-  return `# Extract Learnings — ${ctx.milestoneId}: ${ctx.milestoneName}
+Review the milestone artefacts (roadmap, slice summaries, verification report,
+UAT report) and structure your findings into exactly four categories:
 
-**Project:** ${ctx.projectName}
-**Output file:** ${ctx.outputPath}
+- **Decisions** — architectural or design choices made during this milestone, including rationale and alternatives considered.
+- **Lessons** — technical discoveries, process insights, knowledge gaps that were filled.
+- **Patterns** — reusable approaches or solutions that emerged and should be applied in future work.
+- **Surprises** — unexpected challenges, discoveries, or outcomes that deviated from assumptions.
 
-## Your Task
+Every item MUST carry a \`Source:\` line using the format
+\`Source: {artifact-filename}/{section}\` (e.g.
+\`Source: ${ctx.milestoneId}-ROADMAP.md/Architecture Decisions\`).
+Items without a source attribution are invalid — drop them.
 
-Analyse the artefacts below and extract structured knowledge from milestone **${ctx.milestoneId}**.
+### Step 2 — Write the LEARNINGS.md audit trail
 
-Write a LEARNINGS document to \`${ctx.outputPath}\` with the following 4 sections:
+Using the \`write\` tool, persist the full structured report to
+\`${ctx.relativeOutputPath}\` with this shape:
 
-### Decisions
-Key architectural and design decisions made during this milestone, including the rationale and alternatives considered.
+- YAML frontmatter with keys: \`phase\`, \`phase_name\`, \`project\`, \`generated\` (ISO-8601 UTC), \`counts\` (decisions / lessons / patterns / surprises), \`missing_artifacts\`.
+- Four H3 sections (\`### Decisions\`, \`### Lessons\`, \`### Patterns\`, \`### Surprises\`) containing bullet points. Each bullet is followed by its \`Source:\` line.
 
-### Lessons
-What the team learned — technical discoveries, process insights, and knowledge gaps that were filled.
+LEARNINGS.md is the full, cited audit trail. Write it first — subsequent steps
+feed from its content.
 
-### Patterns
-Reusable patterns, approaches, or solutions that emerged and should be applied in future work.
+### Step 3 — Read \`.gsd/KNOWLEDGE.md\` to prepare append
 
-### Surprises
-Unexpected challenges, discoveries, or outcomes — things that deviated from assumptions.
+Read \`.gsd/KNOWLEDGE.md\`. It is a markdown file with three tables:
+\`## Rules\`, \`## Patterns\`, and \`## Lessons Learned\`.
 
-### Source Attribution (REQUIRED)
+If the file does not exist yet, create it first using the \`write\` tool with
+exactly this canonical structure, then treat all tables as empty (next IDs
+\`P001\` / \`L001\`):
 
-Every extracted item MUST include a \`Source:\` line immediately after the item text.
-Format: \`Source: {artifact-filename}/{section}\`
-Example: \`Source: M001-PLAN.md/Architecture Decisions\`
+\`\`\`
+# Project Knowledge
 
-Items without a Source attribution are invalid and must not be included in the output.
+Append-only register of project-specific rules, patterns, and lessons learned.
+Agents read this before every unit. Add entries when you discover something worth remembering.
 
----
+## Rules
 
-## Artefacts
+| # | Scope | Rule | Why | Added |
+|---|-------|------|-----|-------|
 
-### Plan
+## Patterns
 
-${ctx.planContent}
+| # | Pattern | Where | Notes |
+|---|---------|-------|-------|
 
----
+## Lessons Learned
 
-### Summary
+| # | What Happened | Root Cause | Fix | Scope |
+|---|--------------|------------|-----|-------|
+\`\`\`
 
-${ctx.summaryContent}
+If the file already exists:
 
-${optionalSections.join("\n\n---\n\n")}
-${missingNote}
----
+- find the highest existing \`P###\` ID in the \`## Patterns\` table — the next pattern ID is that + 1, zero-padded to three digits
+- find the highest existing \`L###\` ID in the \`## Lessons Learned\` table — same rule for the next lesson ID
+- read the existing \`Pattern\` and \`What Happened\` column text so you can skip semantic duplicates in steps 4 and 5
 
-## Output Format
+### Step 4 — Append Patterns to \`## Patterns\`
 
-Write the LEARNINGS file to \`${ctx.relativeOutputPath}\` with YAML frontmatter followed by the 4 sections above.
-Each section should contain concise, actionable bullet points.
-Every bullet point MUST be followed by a source line, for example:
+For each extracted Pattern that is **not** already represented in the table
+(semantic match, not exact-string match), append exactly one row to the
+\`## Patterns\` table in \`.gsd/KNOWLEDGE.md\`:
 
 \`\`\`
-### Decisions
-- Chose PostgreSQL over SQLite for concurrent write support.
-  Source: M001-PLAN.md/Architecture Decisions
+| P<NNN> | <Pattern — one concise line> | <Where — component / file / subsystem> | ${ctx.milestoneId} |
 \`\`\`
 
-Items without a \`Source:\` line are invalid.
+Rules:
+- Zero-pad IDs to three digits (\`P017\`, not \`P17\`).
+- Append-only — never reorder, edit, or delete existing rows.
+- If a column value is genuinely unknown, write \`—\` (em-dash). Never leave a cell empty.
+
+### Step 5 — Append Lessons to \`## Lessons Learned\`
+
+For each extracted Lesson that is not already represented, append one row to
+the \`## Lessons Learned\` table:
+
+\`\`\`
+| L<NNN> | <What happened> | <Root cause> | <Fix or forward guidance> | ${ctx.milestoneId} |
+\`\`\`
+
+Same ID numbering, append-only, and em-dash rules as Step 4.
+
+### Step 6 — Do NOT modify the \`## Rules\` table
+
+The \`## Rules\` table holds project-wide constraints authored manually via
+\`/gsd knowledge\`. Milestone learnings never produce rules — leave this
+table untouched.
+
+### Step 7 — Persist Decisions via \`gsd_save_decision\`
+
+For each extracted Decision, call the \`gsd_save_decision\` MCP tool exactly
+once with these parameters:
+
+- \`scope\` (string) — \`"${ctx.milestoneId}"\`
+- \`decision\` (string) — the question or issue that was decided
+- \`choice\` (string) — the concrete option selected
+- \`rationale\` (string) — why this choice was made, with a brief citation to the source artefact
+- \`made_by\` (string) — \`"agent"\`
+- \`revisable\` (string, optional) — \`"yes"\` or \`"no"\` only if the source artefact clearly indicates reversibility; otherwise omit
+
+The tool writes the decision to the GSD database and regenerates
+\`.gsd/DECISIONS.md\` atomically. Never edit \`DECISIONS.md\` manually — the
+file is DB-authoritative and manual edits will be overwritten.
+
+### Step 8 — Surprises stay only in LEARNINGS.md
+
+Surprises are milestone-local context and are NOT cross-session-reusable. Do
+not append them to \`KNOWLEDGE.md\`. Do not persist them via any MCP tool.
+They are captured only in the LEARNINGS.md file written in Step 2.
+
+### Step 9 — Deduplication rule (applies to Steps 4, 5, 7)
+
+Before appending a Pattern or Lesson row, or before calling
+\`gsd_save_decision\`, check whether a semantically equivalent entry already
+exists in the target surface. If so, skip that item entirely. Prefer skipping
+a near-duplicate over creating a second slightly-different row — redundancy
+degrades the signal.`;
+}
+
+/**
+ * Build the full dispatch prompt for the manual `/gsd extract-learnings` path.
+ *
+ * Composes a header block (title, project, output file), the inlined milestone
+ * artefacts (roadmap, summary, optional verification and UAT reports), and the
+ * canonical {@link buildExtractionStepsBlock} procedure. The same procedure is
+ * rendered verbatim in the auto-mode `complete-milestone` turn via the
+ * `{{extractLearningsSteps}}` placeholder, guaranteeing a single source of
+ * truth for how learnings flow into `KNOWLEDGE.md` and the DECISIONS database.
+ *
+ * Missing optional artefacts are surfaced as a note at the end of the artefact
+ * section so the LLM can mark them explicitly in the LEARNINGS frontmatter.
+ */
+export function buildExtractLearningsPrompt(ctx: ExtractLearningsPromptContext): string {
+  const optionalSections: string[] = [];
+
+  if (ctx.verificationContent) {
+    optionalSections.push(`### Verification Report\n\n${ctx.verificationContent}`);
+  }
+  if (ctx.uatContent) {
+    optionalSections.push(`### UAT Report\n\n${ctx.uatContent}`);
+  }
+
+  const missingNote = ctx.missingArtifacts.length > 0
+    ? `\nNote: the following optional artefacts were not available: ${ctx.missingArtifacts.join(", ")}\n`
+    : "";
+
+  const stepsBlock = buildExtractionStepsBlock({
+    milestoneId: ctx.milestoneId,
+    outputPath: ctx.outputPath,
+    relativeOutputPath: ctx.relativeOutputPath,
+  });
+
+  return `# Extract Learnings — ${ctx.milestoneId}: ${ctx.milestoneName}
+
+**Project:** ${ctx.projectName}
+**Output file:** ${ctx.outputPath}
+
+## Your Task
+
+Analyse the milestone artefacts inlined below and follow the Structured
+Learnings Extraction procedure in full. The procedure writes LEARNINGS.md
+and routes the durable subset into \`.gsd/KNOWLEDGE.md\` and the DECISIONS
+database so future milestone dispatches benefit from what was learned here.
 
 ---
 
-## Optional: Capture Individual Learnings
+## Artefacts
 
-If the \`capture_thought\` tool is available, call it once for each extracted item with:
-- category: "decision" | "lesson" | "pattern" | "surprise"
-- phase: "${ctx.milestoneId}"
-- content: {the learning text}
-- source: {artifact filename}
+### Roadmap
 
-If \`capture_thought\` is not available, skip this step silently — do not report an error.
+${ctx.roadmapContent}
 
 ---
 
-## Rebuild Knowledge Graph
+### Summary
 
-After writing LEARNINGS.md, call the \`gsd_graph\` tool with \`{ "mode": "build" }\` to rebuild the knowledge graph so the new learnings are immediately queryable by future milestone prompts.
+${ctx.summaryContent}
+${optionalSections.length > 0 ? `\n---\n\n${optionalSections.join("\n\n---\n\n")}\n` : ""}${missingNote}
+---
 
-If the \`gsd_graph\` tool is not available, skip this step silently.
+${stepsBlock}
 `;
 }
 
+/**
+ * Serialises the YAML frontmatter block prepended to `{MID}-LEARNINGS.md`.
+ *
+ * The output begins and ends with a `---` fence so it can be concatenated
+ * directly with the body. Empty `missingArtifacts` is rendered as an
+ * inline empty list (`missing_artifacts: []`) to keep the frontmatter valid
+ * YAML in every case.
+ */
 export function buildFrontmatter(ctx: FrontmatterContext): string {
   const missingList = ctx.missingArtifacts.length > 0
     ? ctx.missingArtifacts.map((a) => `  - ${a}`).join("\n")
@@ -208,6 +414,14 @@ missing_artifacts:${missingValue}
 ---`;
 }
 
+/**
+ * Extracts the project display name from `.gsd/PROJECT.md` frontmatter.
+ *
+ * Falls back to the project directory's basename if PROJECT.md is missing,
+ * unreadable, or has no `name:` field. Never throws — surfacing the raw
+ * directory name is preferable to crashing an extraction over a display
+ * string.
+ */
 export function extractProjectName(basePath: string): string {
   const projectMdPath = join(gsdRoot(basePath), "PROJECT.md");
 
@@ -226,6 +440,15 @@ export function extractProjectName(basePath: string): string {
 
 // ─── Handler ──────────────────────────────────────────────────────────────────
 
+/**
+ * Handles the `/gsd extract-learnings <MID>` slash command.
+ *
+ * Resolves and reads the milestone artefacts, constructs the dispatch prompt
+ * via {@link buildExtractLearningsPrompt}, and triggers a new LLM turn via
+ * `pi.sendMessage({ triggerTurn: true })`. Returns quickly with a UI
+ * notification (not an error) when the milestone cannot be found or required
+ * artefacts are missing, matching the behaviour of sibling `/gsd` commands.
+ */
 export async function handleExtractLearnings(
   args: string,
   ctx: ExtensionCommandContext,
@@ -257,11 +480,9 @@ export async function handleExtractLearnings(
     return;
   }
 
-  // Read required artefacts
-  const planContent = readFileSync(artifacts.plan!, "utf-8");
+  const roadmapContent = readFileSync(artifacts.roadmap!, "utf-8");
   const summaryContent = readFileSync(artifacts.summary!, "utf-8");
 
-  // Read optional artefacts
   const verificationContent = artifacts.verification
     ? readFileSync(artifacts.verification, "utf-8")
     : null;
@@ -269,25 +490,23 @@ export async function handleExtractLearnings(
     ? readFileSync(artifacts.uat, "utf-8")
     : null;
 
-  // Determine missing optional artefacts for context
   const missingArtifacts: string[] = [];
   if (!artifacts.verification) missingArtifacts.push(`${milestoneId}-VERIFICATION.md`);
   if (!artifacts.uat) missingArtifacts.push(`${milestoneId}-UAT.md`);
 
-  // Extract milestone name from Plan H1 or fall back to milestoneId
-  const h1Match = planContent.match(/^#\s+(.+)$/m);
+  const h1Match = roadmapContent.match(/^#\s+(.+)$/m);
   const milestoneName = h1Match?.[1]?.trim() ?? milestoneId;
 
   const projectName = extractProjectName(basePath);
   const outputPath = buildLearningsOutputPath(milestoneDir, milestoneId);
-  const relativeOutputPath = outputPath.replace(basePath + "/", "");
+  const relativeOutputPath = relative(basePath, outputPath);
 
   const prompt = buildExtractLearningsPrompt({
     milestoneId,
     milestoneName,
     outputPath,
     relativeOutputPath,
-    planContent,
+    roadmapContent,
     summaryContent,
     verificationContent,
     uatContent,

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -7,7 +7,8 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve as resolvePath, sep } from "node:path";
+import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
@@ -28,8 +29,24 @@ import { loadPrompt } from "./prompt-loader.js";
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/gsd-pi/latest";
 const UPDATE_FETCH_TIMEOUT_MS = 5000;
 
+// Detects a bun-installed gsd via `process.argv[1]`. Mirrors isBunInstall in
+// src/update-check.ts — duplicated because tsconfig.resources.json rootDir
+// prevents importing from src/. See #4145 for why the runtime-only check
+// (process.versions.bun) is insufficient: bun's global bin shims are plain
+// symlinks, so the target's #!/usr/bin/env node shebang runs the script under
+// Node even when it was installed by bun.
+function isBunInstall(argv1: string | undefined = process.argv[1]): boolean {
+  if ('bun' in process.versions) return true;
+  if (!argv1) return false;
+  const bunBinDirs: string[] = [];
+  if (process.env.BUN_INSTALL) bunBinDirs.push(join(process.env.BUN_INSTALL, "bin"));
+  bunBinDirs.push(join(homedir(), ".bun", "bin"));
+  const resolved = resolvePath(argv1);
+  return bunBinDirs.some((dir) => resolved.startsWith(resolvePath(dir) + sep));
+}
+
 function resolveInstallCommand(pkg: string): string {
-  if ('bun' in process.versions) return `bun add -g ${pkg}`;
+  if (isBunInstall()) return `bun add -g ${pkg}`;
   return `npm install -g ${pkg}`;
 }