@msdavid/pi-distro 0.2.0

package/extensions/frontmatter.ts

@@ -0,0 +1,158 @@
+/**
+ * Tiny inline YAML frontmatter parser for harness.md files.
+ *
+ * No external yaml dependency — only handles the fields used by harness.md:
+ * name, title, description, version, author, tags.
+ *
+ * Supports:
+ * - Simple `key: value` pairs
+ * - YAML `>` folded scalar for multi-line descriptions
+ * - Inline array `[a, b, c]`
+ */
+
+export interface Frontmatter {
+  name?: string;
+  title?: string;
+  description?: string;
+  version?: string;
+  author?: string;
+  tags?: string[];
+  [key: string]: unknown;
+}
+
+/**
+ * Parse the YAML frontmatter block from a harness.md (or any markdown) string.
+ * Returns the parsed fields and null if no frontmatter block is found.
+ */
+export function parseFrontmatter(content: string): Frontmatter | null {
+  const lines = content.split(/\r?\n/);
+
+  // Must start with ---
+  if (lines[0]?.trim() !== "---") {
+    return null;
+  }
+
+  // Find closing ---
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) {
+    return null;
+  }
+
+  const yamlLines = lines.slice(1, end);
+  return parseYamlLines(yamlLines);
+}
+
+/**
+ * Serialize a frontmatter object back to a YAML block string (with --- fences).
+ */
+export function serializeFrontmatter(fm: Record<string, unknown>): string {
+  const lines: string[] = ["---"];
+  for (const [key, value] of Object.entries(fm)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      lines.push(`${key}: [${value.map((v) => String(v)).join(", ")}]`);
+    } else if (typeof value === "string" && value.includes("\n")) {
+      // Use folded scalar for multi-line
+      lines.push(`${key}: >`);
+      for (const sub of value.split("\n")) {
+        lines.push(`  ${sub}`);
+      }
+    } else {
+      lines.push(`${key}: ${formatScalar(value)}`);
+    }
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+
+/**
+ * Extract the body (everything after the frontmatter block).
+ * If there's no frontmatter, returns the full content.
+ */
+export function extractBody(content: string): string {
+  const lines = content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") {
+    return content;
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) {
+    return content;
+  }
+  return lines.slice(end + 1).join("\n").replace(/^\n+/, "");
+}
+
+// --- Internal helpers ---
+
+function parseYamlLines(lines: string[]): Frontmatter {
+  const result: Frontmatter = {};
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line || line.trim() === "" || line.trim().startsWith("#")) {
+      i++;
+      continue;
+    }
+
+    const match = line.match(/^(\w[\w-]*)\s*:\s*(.*)$/);
+    if (!match) {
+      i++;
+      continue;
+    }
+    const key = match[1];
+    let value = match[2].trim();
+
+    // Handle folded scalar (> or >-)
+    if (value === ">" || value === ">-") {
+      const folded: string[] = [];
+      i++;
+      while (i < lines.length && (lines[i]?.startsWith("  ") || lines[i]?.startsWith("\t") || lines[i]?.trim() === "")) {
+        folded.push((lines[i] ?? "").replace(/^[ \t]+/, ""));
+        i++;
+      }
+      result[key] = folded.join(" ").trim();
+      continue;
+    }
+
+    // Handle inline array
+    if (value.startsWith("[") && value.endsWith("]")) {
+      result[key] = value
+        .slice(1, -1)
+        .split(",")
+        .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+        .filter(Boolean);
+      i++;
+      continue;
+    }
+
+    // Strip surrounding quotes
+    result[key] = value.replace(/^["']|["']$/g, "");
+    i++;
+  }
+  return result;
+}
+
+function formatScalar(value: unknown): string {
+  if (typeof value === "string") {
+    // Quote if contains special chars
+    if (/[:#{}\[\],&*?|<>=!%@`]/.test(value) || value.includes("\n")) {
+      return `"${value.replace(/"/g, '\\"')}"`;
+    }
+    return value;
+  }
+  if (typeof value === "boolean" || typeof value === "number") {
+    return String(value);
+  }
+  return String(value);
+}

package/extensions/github.ts

@@ -0,0 +1,110 @@
+/**
+ * GitHub distro pull logic for pi-distro.
+ *
+ * Supports fetching distros from GitHub repositories via shallow clone.
+ * Used by `show <gh-repo>` and `deploy <gh-distro>` subcommands.
+ *
+ * Address format:
+ *   owner/repo              → harness.md at repo root
+ *   owner/repo/subpath      → harness.md at <subpath>/
+ *   https://github.com/...  → full URLs also accepted
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { parseFrontmatter } from "./frontmatter.ts";
+import type { HarnessEntry } from "./catalogue.ts";
+
+export interface GithubRef {
+  owner: string;
+  repo: string;
+  subPath: string; // "" for root
+  displayRef: string; // "owner/repo" or "owner/repo/subpath"
+}
+
+/**
+ * Parse a GitHub reference: `owner/repo[/subpath]` or a full GitHub URL.
+ * Returns undefined if the string doesn't look like a valid GitHub ref.
+ */
+export function parseGithubRef(ref: string): GithubRef | undefined {
+  let s = ref.trim();
+  s = s.replace(/^https?:\/\/github\.com\//, "");
+  s = s.replace(/^github\.com\//, "");
+  s = s.replace(/\/$/, ""); // strip trailing slash before .git so "repo.git/" is handled
+  s = s.replace(/\.git$/, "");
+  const parts = s.split("/").filter(Boolean);
+  if (parts.length < 2) return undefined;
+  const [owner, repo, ...rest] = parts;
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9-]*$/.test(owner)) return undefined;
+  if (!/^[a-zA-Z0-9_.-]+$/.test(repo)) return undefined;
+  const subPath = rest.join("/");
+  return {
+    owner,
+    repo,
+    subPath,
+    displayRef: subPath ? `${owner}/${repo}/${subPath}` : `${owner}/${repo}`,
+  };
+}
+
+/** Whether an argument looks like a GitHub reference (contains a `/`). */
+export function looksLikeGithubRef(arg: string): boolean {
+  return arg.includes("/") && parseGithubRef(arg) !== undefined;
+}
+
+/**
+ * Shallow-clone a GitHub repo to a temp dir and return a HarnessEntry
+ * pointing at the distro within it.
+ *
+ * Throws on clone failure or if harness.md is not found / unparseable.
+ * The caller is responsible for calling `cleanup()` to remove the temp dir.
+ */
+export function fetchGithubDistro(
+  ref: GithubRef,
+): { entry: HarnessEntry; cleanup: () => void } {
+  const cloneUrl = `https://github.com/${ref.owner}/${ref.repo}.git`;
+  const tmp = mkdtempSync(join(tmpdir(), "pi-distro-gh-"));
+  try {
+    execSync(`git clone --depth 1 "${cloneUrl}" "${tmp}"`, {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 30_000,
+      encoding: "utf-8",
+    });
+  } catch (err) {
+    rmSync(tmp, { recursive: true, force: true });
+    throw new Error(
+      `Failed to clone ${ref.displayRef}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const distroDir = ref.subPath ? join(tmp, ref.subPath) : tmp;
+  const harnessMdPath = join(distroDir, "harness.md");
+  if (!existsSync(harnessMdPath)) {
+    rmSync(tmp, { recursive: true, force: true });
+    throw new Error(
+      `No harness.md found ${ref.subPath ? `at '${ref.subPath}/' ` : ""}in ${ref.displayRef}`,
+    );
+  }
+
+  const content = readFileSync(harnessMdPath, "utf-8");
+  const fm = parseFrontmatter(content);
+  if (!fm?.name) {
+    rmSync(tmp, { recursive: true, force: true });
+    throw new Error(`Invalid harness.md in ${ref.displayRef}: missing 'name' field`);
+  }
+
+  const filesDir = join(distroDir, "files");
+  const entry: HarnessEntry = {
+    name: fm.name,
+    title: fm.title ?? fm.name,
+    description: fm.description ?? "",
+    version: fm.version ?? "0.0.0",
+    source: `github:${ref.displayRef}`,
+    dir: distroDir,
+    harnessMdPath,
+    filesDir: existsSync(filesDir) ? filesDir : undefined,
+  };
+
+  return { entry, cleanup: () => rmSync(tmp, { recursive: true, force: true }) };
+}

package/extensions/index.ts

@@ -0,0 +1,86 @@
+/**
+ * pi-distro extension engine.
+ *
+ * Registers a single slash command `/pi-distro` that dispatches to
+ * subcommands: deploy, undeploy, pick, update, save, list, show, status, remove.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+
+import { getCatalogueNamesSync } from "./catalogue.ts";
+import { display } from "./util.ts";
+import { handleShow } from "./show.ts";
+import { handleDeploy } from "./deploy.ts";
+import { handlePick } from "./pick.ts";
+import { handleUndeploy } from "./undeploy.ts";
+import { handleUpdate } from "./update.ts";
+import { handleSave } from "./save.ts";
+import { handleList, handleStatus, handleRemove } from "./info.ts";
+
+const SUBCOMMANDS = [
+  { name: "deploy", desc: "Deploy a distro (local name or gh: owner/repo[/sub])" },
+  { name: "undeploy", desc: "Remove an applied distro from the current project" },
+  { name: "pick", desc: "Partially deploy: select which packages/configs to apply from a distro" },
+  { name: "update", desc: "Update the applied distro if a newer version exists" },
+  { name: "save", desc: "Snapshot the current project config as a distro" },
+  { name: "list", desc: "List all available distros" },
+  { name: "show", desc: "Preview a distro dry-run (local name or gh: owner/repo[/sub])" },
+  { name: "status", desc: "Show the current project's distro status" },
+  { name: "remove", desc: "Delete a user distro" },
+];
+
+export default function (pi: ExtensionAPI): void {
+  pi.registerCommand("pi-distro", {
+    description: "Manage pi distros (deploy, save, list, show, status, remove)",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const parts = args.trim().split(/\s+/).filter(Boolean);
+      const sub = parts[0] ?? "";
+      const nameArg = parts[1];
+      switch (sub) {
+        case "": await handleHelp(pi); break;
+        case "deploy": await handleDeploy(pi, ctx, nameArg); break;
+        case "undeploy": await handleUndeploy(pi, ctx); break;
+        case "pick": await handlePick(pi, ctx, nameArg); break;
+        case "update": await handleUpdate(pi, ctx); break;
+        case "save": await handleSave(pi, ctx); break;
+        case "list": await handleList(pi); break;
+        case "show": await handleShow(pi, nameArg); break;
+        case "status": await handleStatus(pi, ctx); break;
+        case "remove": await handleRemove(pi, ctx, nameArg); break;
+        default:
+          ctx.ui.notify(`Unknown subcommand: ${sub}`, "error");
+          await handleHelp(pi);
+      }
+    },
+    getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
+      const items: AutocompleteItem[] = SUBCOMMANDS.map((s) => ({
+        value: s.name, label: s.name, description: s.desc,
+      }));
+      const parts = prefix.split(/\s+/);
+      const sub = parts[0];
+      const namePrefix = parts.slice(1).join(" ");
+      if ((sub === "show" || sub === "remove" || sub === "deploy" || sub === "pick")) {
+        try {
+          for (const name of getCatalogueNamesSync()) {
+            if (!namePrefix || name.startsWith(namePrefix)) {
+              items.push({ value: `${sub} ${name}`, label: name, description: "distro name" });
+            }
+          }
+        } catch { /* ignore */ }
+      }
+      const filtered = items.filter((i) => i.value.startsWith(prefix) || i.label.startsWith(prefix));
+      return filtered.length > 0 ? filtered : null;
+    },
+  });
+}
+
+// --- help (no arg) ---
+
+async function handleHelp(pi: ExtensionAPI): Promise<void> {
+  const lines = SUBCOMMANDS.map((s) => `  **${s.name}** — ${s.desc}`);
+  display(pi, `**pi-distro** — reusable pi configurations.\n\nUsage: \`/pi-distro <subcommand>\`\n\n${lines.join("\n")}`);
+}

package/extensions/info.ts

@@ -0,0 +1,133 @@
+/**
+ * Read-only / catalogue-management commands:
+ * `/pi-distro list`, `/pi-distro status`, `/pi-distro remove`.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { readFileSync, existsSync, readdirSync, mkdirSync, cpSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  readCatalogue,
+  findHarness,
+  parseProvenance,
+  getUserHarnessesDir,
+} from "./catalogue.ts";
+import { resolveCatalogueEntry } from "./resolve.ts";
+import { display, compareVersions } from "./util.ts";
+
+// --- list ---
+
+export async function handleList(pi: ExtensionAPI): Promise<void> {
+  const catalogue = await readCatalogue();
+  if (catalogue.length === 0) { display(pi, "No distros found in the catalogue."); return; }
+  const rows = catalogue.map((h) => {
+    const desc = h.description.length > 50 ? h.description.slice(0, 47) + "..." : h.description;
+    return `| ${h.name} | ${h.title} | ${h.version} | ${h.source} | ${desc} |`;
+  });
+  const seedCount = catalogue.filter((h) => h.source === "seed").length;
+  const userCount = catalogue.filter((h) => h.source === "user").length;
+  display(pi, `## Distro catalogue
+
+| NAME | TITLE | VERSION | SOURCE | DESCRIPTION |
+|------|-------|---------|--------|-------------|
+${rows.join("\n")}
+
+_Seeds: ${seedCount} · User: ${userCount} · Total: ${catalogue.length}_`);
+}
+
+// --- status ---
+
+export async function handleStatus(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
+  const snapshot = ctx.getSystemPromptOptions();
+  const cwd = snapshot.cwd;
+  const provenancePath = join(cwd, ".pi", "harness.md");
+
+  let provenanceSection: string;
+  let updateSection = "";
+  if (existsSync(provenancePath)) {
+    const prov = parseProvenance(readFileSync(provenancePath, "utf-8"));
+    if (prov) {
+      provenanceSection = `### Applied distro\n- **Name:** ${prov.appliedHarness}\n- **Version:** ${prov.appliedVersion}\n- **Source:** ${prov.sourceCatalogue}\n- **Last updated:** ${prov.lastUpdated}`;
+      // Check for updates (local catalogue only; GitHub sources are not auto-fetched on status).
+      if (!prov.sourceCatalogue.startsWith("github:")) {
+        const current = await resolveCatalogueEntry(prov.appliedHarness);
+        if (current) {
+          const cmp = compareVersions(current.version, prov.appliedVersion);
+          if (cmp > 0) {
+            updateSection = `### Update available\n**${prov.appliedHarness}** v${prov.appliedVersion} → v${current.version}. Run \`/pi-distro update\` to apply.`;
+          } else if (cmp < 0) {
+            updateSection = `### Version note\nApplied v${prov.appliedVersion} is newer than the catalogue's v${current.version} (downgrade).`;
+          } // same version → no section
+        } else {
+          updateSection = `### Update check\nDistro '${prov.appliedHarness}' is no longer in the catalogue (removed or renamed).`;
+        }
+      } else {
+        updateSection = `### Update check\nApplied from GitHub (\`${prov.sourceCatalogue}\`). Run \`/pi-distro update\` to fetch the latest and check for updates.`;
+      }
+    } else {
+      provenanceSection = "### Applied distro\nA provenance file exists but could not be parsed.";
+    }
+  } else {
+    provenanceSection = "### Applied distro\nNo distro provenance found in this project.";
+  }
+
+  const tools = snapshot.selectedTools?.join(", ") ?? "(default)";
+  const skillsList = snapshot.skills?.map((s) => `- ${s.name}`).join("\n") ?? "_(none)_";
+  const contextList = snapshot.contextFiles?.map((c) => `- ${c.path}`).join("\n") ?? "_(none)_";
+
+  let packages = "_(none)_";
+  const settingsPath = join(cwd, ".pi", "settings.json");
+  if (existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+      if (Array.isArray(settings.packages) && settings.packages.length > 0) {
+        packages = settings.packages.map((p: string) => `- \`${p}\``).join("\n");
+      }
+    } catch { /* ignore */ }
+  }
+
+  display(pi, `## Project distro status
+
+${provenanceSection}
+${updateSection}
+### Live configuration
+- **Working dir:** ${cwd}
+- **Active tools:** ${tools}
+- **Skills:**
+${skillsList}
+- **Context files:**
+${contextList}
+- **Installed packages:**
+${packages}`);
+}
+
+// --- remove ---
+
+export async function handleRemove(pi: ExtensionAPI, ctx: ExtensionCommandContext, name?: string): Promise<void> {
+  if (!name) { ctx.ui.notify("Usage: /pi-distro remove <name>", "error"); return; }
+  const catalogue = await readCatalogue();
+  const harness = findHarness(name, catalogue);
+  if (!harness) {
+    const available = catalogue.map((h) => h.name).join(", ") || "(none)";
+    ctx.ui.notify(`Distro '${name}' not found. Available: ${available}`, "error");
+    return;
+  }
+  if (harness.source === "seed") {
+    ctx.ui.notify(`'${name}' is a package seed and cannot be removed.`, "error");
+    return;
+  }
+  const confirmed = await ctx.ui.confirm("Remove harness?", `This deletes '~/.pi/harnesses/${name}/'. A backup will be saved to .trash/.`);
+  if (!confirmed) return;
+
+  // Back up to .trash, then delete
+  const userDir = getUserHarnessesDir();
+  const trashDir = join(userDir, ".trash", `${name}-${Date.now()}`);
+  mkdirSync(trashDir, { recursive: true });
+  cpSync(harness.dir, join(trashDir, name), { recursive: true });
+  rmSync(harness.dir, { recursive: true, force: true });
+  ctx.ui.notify(`Removed distro '${name}'. (Backup in ~/.pi/harnesses/.trash/)`, "info");
+}

package/extensions/pick.ts

@@ -0,0 +1,132 @@
+/**
+ * `/pi-distro pick` — partial deploy: select which components to apply from a distro.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { listBundledFiles, parsePackageList } from "./catalogue.ts";
+import { extractBody } from "./frontmatter.ts";
+import { parseGithubRef } from "./github.ts";
+import { resolveDistro } from "./resolve.ts";
+import { buildShowPreview } from "./show.ts";
+import {
+  display,
+  readProjectPackages,
+  MERGE_RULE,
+  USER_INVOLVEMENT_RULE,
+  PACKAGE_CONFLICT_RULE,
+} from "./util.ts";
+
+export async function handlePick(pi: ExtensionAPI, ctx: ExtensionCommandContext, nameArg?: string): Promise<void> {
+  const resolved = await resolveDistro(pi, ctx, nameArg, "pick from");
+  if (!resolved) return;
+  const { entry, cleanup } = resolved;
+
+  // GitHub trust gate (same as deploy — the user must confirm before anything is applied).
+  if (cleanup) {
+    const ref = parseGithubRef(nameArg!)!;
+    const preview = await buildShowPreview(entry);
+    const warning = `\n\n---\n\n⚠️ **Security warning:** This distro was fetched from \`${ref.displayRef}\` on GitHub. Picking components from an unknown distro is still **dangerous** — packages can execute code, extensions run at startup, and directives inject agent instructions. Review everything above carefully. You are responsible for what you install.`;
+    display(pi, preview + warning);
+    const confirmed = await ctx.ui.confirm(
+      "Pick from GitHub distro?",
+      `You're about to pick components from \`${entry.name}\` (\`${ref.displayRef}\`). Review the preview above and confirm to proceed to selection.`,
+    );
+    if (!confirmed) {
+      cleanup();
+      ctx.ui.notify("Pick cancelled.", "info");
+      return;
+    }
+  }
+
+  // Parse the distro into selectable components.
+  const fullMd = readFileSync(entry.harnessMdPath, "utf-8");
+  const directives = extractBody(fullMd);
+  const packages = parsePackageList(directives);
+  const files = entry.filesDir ? await listBundledFiles(entry.filesDir) : [];
+  const filesDirNote = entry.filesDir ? `\n\nBundled files are located at: \`${entry.filesDir}\`` : "";
+
+  const snapshot = ctx.getSystemPromptOptions();
+  const activeTools = snapshot.selectedTools?.length
+    ? snapshot.selectedTools.map((t) => `- \`${t}\``).join("\n")
+    : "_(none / default set)_";
+  const pkgs = readProjectPackages(snapshot.cwd);
+  const projectPackages = pkgs.length > 0 ? pkgs.map((p) => `- \`${p}\``).join("\n") : "_(none)_";
+
+  const packageList = packages.length > 0
+    ? packages.map((p) => `- \`${p}\``).join("\n")
+    : "_(none)_";
+  const fileList = files.length > 0
+    ? files.map((f) => `- \`${f.source}\` → \`./${f.target}\``).join("\n")
+    : "_(none)_";
+
+  pi.sendUserMessage(`## Picking components from distro: ${entry.name} (v${entry.version})
+
+This is a **partial deploy**. The user wants to select which components to apply from this
+distro — not the whole thing. Walk them through the selection, then apply only what they
+choose. This lets users combine pieces from different distros to build their own config.
+
+### Directives (full — for your reference on what each component does)
+${directives}
+
+### Selectable components
+**📦 Packages (${packages.length}):**
+${packageList}
+
+**📄 Bundled files (${files.length}):**
+${fileList}${filesDirNote}
+
+The directives body above may also describe other components (settings keys, context,
+extensions, themes, prompts, skills) — treat each as individually selectable too.
+
+### Current project state (for conflict detection)
+**Already-active tools in this session:**
+${activeTools}
+
+**Packages already in this project's .pi/settings.json:**
+${projectPackages}
+
+(Run \`pi list\` to also see globally-installed packages.)
+
+### Selection procedure (follow exactly, collaborating with the user)
+
+**0. User involvement rule** — ${USER_INVOLVEMENT_RULE}
+
+**1. Walk the user through each category, one at a time.** For each category (packages, then
+   bundled files, then any other components described in the directives), use
+   \`ctx.ui.select\`/\`ctx.ui.confirm\` to let the user pick which to apply. Present the items
+   with their one-line purpose (from the directives). Let the user select any subset —
+   including none (skip the category entirely).
+
+**2. Surface dependencies.** As the user selects, **evaluate cross-component dependencies**
+   and warn about them before applying. For example: if the user picks the
+   \`claude-statusline.ts\` extension but skips \`pi-crew\`, point out that the statusline
+   references a theme provided by pi-crew and will error without it — ask whether to also
+   install pi-crew or skip the statusline. The directives prose is your source for these
+   relationships; reason about them and explain the tradeoffs to the user. Never silently
+   install a dependency the user didn't pick — always ask.
+
+**3. Apply only the selected components**, with the same rules as a full deploy:
+   - **Merge-don't-clobber** — ${MERGE_RULE}
+   - **Package-redundancy check** — ${PACKAGE_CONFLICT_RULE}
+   - For each selected package: \`pi install -l\` after confirming (do NOT pre-add to
+     settings.json by hand).
+   - For each selected bundled file: copy/merge as the user chooses (overwrite / keep theirs /
+     merge).
+
+**4. Do NOT write standard provenance.** A partial deploy is not "this distro was applied" —
+   it's a custom configuration built from pieces. Do not write or update \`./.pi/harness.md\`
+   with \`appliedHarness\`/\`appliedVersion\` provenance for a partial deploy. Instead, after
+   applying the selected components, **suggest the next step**: tell the user "This is a
+   custom configuration. Run \`/pi-distro save\` to snapshot it as your own reusable distro"
+   (which will then write clean provenance for the saved distro).
+
+**5. Recommend a restart** if any packages or extensions were installed — they load at
+   startup.`);
+  // GitHub temp dir left in /tmp for the agent to read bundled files (ephemeral).
+}

package/extensions/resolve.ts

@@ -0,0 +1,70 @@
+/**
+ * Distro resolution: turn a name argument (GitHub ref or local catalogue name,
+ * or an interactive selector) into a HarnessEntry.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  readCatalogue,
+  findHarness,
+} from "./catalogue.ts";
+import type { HarnessEntry } from "./catalogue.ts";
+import { looksLikeGithubRef, parseGithubRef, fetchGithubDistro } from "./github.ts";
+
+/**
+ * Resolve a distro from a name argument (GitHub ref or local catalogue name).
+ * If nameArg is omitted, shows the interactive selector.
+ * Returns { entry, cleanup? } or undefined on cancel/error (notifies the user on error).
+ * `cleanup` is present only for GitHub distros (to remove the temp clone).
+ */
+export async function resolveDistro(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  nameArg: string | undefined,
+  verb: string,
+): Promise<{ entry: HarnessEntry; cleanup?: () => void } | undefined> {
+  // GitHub ref? (contains a /)
+  if (nameArg && looksLikeGithubRef(nameArg)) {
+    const ref = parseGithubRef(nameArg)!;
+    ctx.ui.notify(`Fetching ${ref.displayRef} from GitHub…`, "info");
+    try {
+      const fetched = fetchGithubDistro(ref);
+      return { entry: fetched.entry, cleanup: fetched.cleanup };
+    } catch (err) {
+      ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+      return undefined;
+    }
+  }
+
+  // Local catalogue
+  const catalogue = await readCatalogue();
+  if (catalogue.length === 0) {
+    ctx.ui.notify("No distros found. Run /pi-distro save to create one.", "warning");
+    return undefined;
+  }
+  if (nameArg) {
+    const harness = findHarness(nameArg, catalogue);
+    if (!harness) {
+      const available = catalogue.map((h) => h.name).join(", ") || "(none)";
+      ctx.ui.notify(`Distro '${nameArg}' not found. Available: ${available}`, "error");
+      return undefined;
+    }
+    return { entry: harness };
+  }
+  // No nameArg → interactive selector
+  const theme = ctx.ui.theme;
+  const labels = catalogue.map((h) => `${theme.bold(h.name)} — ${h.description}`);
+  const selected = await ctx.ui.select(`Select a distro to ${verb}:`, labels);
+  if (selected === undefined) return undefined;
+  const harness = catalogue[labels.indexOf(selected)];
+  return harness ? { entry: harness } : undefined;
+}
+
+/** Resolve the current catalogue entry for a distro by name (local catalogue only). */
+export async function resolveCatalogueEntry(name: string): Promise<HarnessEntry | undefined> {
+  const catalogue = await readCatalogue();
+  return findHarness(name, catalogue);
+}