@mccune1224/pi-pstack 0.1.0 → 0.2.0

package/extensions/skill-budget.test.ts

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { test } from "node:test";
+import {
+  analyzeSkillBudget,
+  promptBlockEntry,
+  readSkillSources,
+  type SkillSource,
+} from "./skill-budget.ts";
+
+const REPO_SKILLS = join(import.meta.dirname, "..", "skills");
+
+const FIXTURES: SkillSource[] = [
+  {
+    path: "/pkg/skills/demo/SKILL.md",
+    content: [
+      "---",
+      "name: demo",
+      'description: "Says \\"hello\\" to <the> world."',
+      "disable-model-invocation: false",
+      "---",
+      "",
+      "# Demo",
+    ].join("\n"),
+  },
+  {
+    path: "/pkg/skills/hidden/SKILL.md",
+    content: [
+      "---",
+      "name: hidden",
+      "description: Filtered out of the prompt.",
+      "disable-model-invocation: true",
+      "---",
+    ].join("\n"),
+  },
+  {
+    path: "/pkg/skills/quoted/SKILL.md",
+    content: [
+      "---",
+      "name: quoted",
+      "description: Not a boolean.",
+      'disable-model-invocation: "true"',
+      "---",
+    ].join("\n"),
+  },
+  {
+    path: "/pkg/skills/noName/SKILL.md",
+    content: ["---", "description: Name comes from the directory.", "---"].join("\n"),
+  },
+];
+
+test("promptBlockEntry writes Pi's available_skills entry", () => {
+  assert.equal(
+    promptBlockEntry("demo", 'Says "hello" to <the> world.', "/pkg/skills/demo/SKILL.md"),
+    [
+      "  <skill>",
+      "    <name>demo</name>",
+      "    <description>Says &quot;hello&quot; to &lt;the&gt; world.</description>",
+      "    <location>/pkg/skills/demo/SKILL.md</location>",
+      "  </skill>",
+    ].join("\n"),
+  );
+});
+
+test("analyzeSkillBudget prices only the skills Pi exposes to the model", () => {
+  const budget = analyzeSkillBudget(FIXTURES);
+  assert.deepEqual(budget.skills, [
+    { name: "demo", modelInvocable: true, characters: 169 },
+    { name: "hidden", modelInvocable: false, characters: 156 },
+    { name: "quoted", modelInvocable: true, characters: 143 },
+    { name: "noName", modelInvocable: true, characters: 159 },
+  ]);
+  assert.deepEqual(
+    {
+      total: budget.total,
+      modelInvocable: budget.modelInvocable,
+      filtered: budget.filtered,
+      characters: budget.characters,
+      estimatedTokens: budget.estimatedTokens,
+    },
+    { total: 4, modelInvocable: 3, filtered: 1, characters: 473, estimatedTokens: 118 },
+  );
+});
+
+test("analyzeSkillBudget reports this repo's real skills directory", () => {
+  const budget = analyzeSkillBudget(readSkillSources(REPO_SKILLS));
+  const dirs = readdirSync(REPO_SKILLS, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+  for (const name of dirs) {
+    assert.ok(existsSync(join(REPO_SKILLS, name, "SKILL.md")), `${name}/SKILL.md is missing`);
+  }
+  assert.deepEqual(
+    budget.skills.map((skill) => skill.name).sort(),
+    [...dirs].sort(),
+    "every skill directory must be priced, and nothing outside them",
+  );
+  assert.deepEqual(
+    { total: budget.total, modelInvocable: budget.modelInvocable, filtered: budget.filtered },
+    { total: 50, modelInvocable: 5, filtered: 45 },
+    "the exposure counts changed; a sync that changes a disable-model-invocation flag lands here",
+  );
+  assert.deepEqual(
+    budget.skills.filter((skill) => skill.modelInvocable).map((skill) => skill.name),
+    ["control-cli", "control-ui", "create-skill", "deslop", "setup-pstack"],
+    "the set of skills Pi offers changed; this usually means upstream changed a disable-model-invocation flag, so update the README exposure claim and docs/compare.md together with this test",
+  );
+  assert.equal(budget.modelInvocable + budget.filtered, dirs.length);
+});

package/extensions/skill-budget.ts

@@ -0,0 +1,101 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+export interface SkillSource {
+  path: string;
+  content: string;
+}
+
+export interface SkillCost {
+  name: string;
+  modelInvocable: boolean;
+  characters: number;
+}
+
+export interface SkillBudget {
+  total: number;
+  modelInvocable: number;
+  filtered: number;
+  characters: number;
+  estimatedTokens: number;
+  skills: SkillCost[];
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function frontmatter(content: string): string {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+  return match ? match[1] : "";
+}
+
+function frontmatterField(frontmatterText: string, key: string): string | undefined {
+  const match = new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(frontmatterText);
+  if (!match) return undefined;
+  const raw = match[1].trim();
+  if (raw.length > 1 && raw.startsWith('"') && raw.endsWith('"')) {
+    return raw.slice(1, -1).replace(/\\(["\\])/g, "$1");
+  }
+  return raw.replace(/[ \t]+#.*$/, "");
+}
+
+// Pi filters on a YAML boolean true, so the string "true" stays model-invocable.
+function yamlBooleanTrue(frontmatterText: string, key: string): boolean {
+  const match = new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(frontmatterText);
+  if (!match) return false;
+  return /^(?:true|True|TRUE)$/.test(match[1].trim().replace(/[ \t]+#.*$/, ""));
+}
+
+export function promptBlockEntry(name: string, description: string, location: string): string {
+  return [
+    "  <skill>",
+    `    <name>${escapeXml(name)}</name>`,
+    `    <description>${escapeXml(description)}</description>`,
+    `    <location>${escapeXml(location)}</location>`,
+    "  </skill>",
+  ].join("\n");
+}
+
+export function readSkillSources(skillsDir: string): SkillSource[] {
+  const sources: SkillSource[] = [];
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const path = join(skillsDir, entry.name, "SKILL.md");
+    if (!existsSync(path)) continue;
+    sources.push({ path, content: readFileSync(path, "utf8") });
+  }
+  return sources;
+}
+
+export function analyzeSkillBudget(sources: SkillSource[]): SkillBudget {
+  const skills: SkillCost[] = [];
+  for (const source of sources) {
+    const frontmatterText = frontmatter(source.content);
+    const description = frontmatterField(frontmatterText, "description");
+    if (!description) continue;
+    const name = frontmatterField(frontmatterText, "name") || basename(dirname(source.path));
+    skills.push({
+      name,
+      modelInvocable: !yamlBooleanTrue(frontmatterText, "disable-model-invocation"),
+      characters: promptBlockEntry(name, description, source.path).length,
+    });
+  }
+  const exposed = skills.filter((skill) => skill.modelInvocable);
+  // Pi pushes each entry into the same lines array, so every entry also pays a newline.
+  const characters =
+    exposed.reduce((sum, skill) => sum + skill.characters, 0) + Math.max(exposed.length - 1, 0);
+  return {
+    total: skills.length,
+    modelInvocable: exposed.length,
+    filtered: skills.length - exposed.length,
+    characters,
+    estimatedTokens: Math.round(characters / 4),
+    skills,
+  };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mccune1224/pi-pstack",
-  "version": "0.1.0",
-  "description": "pstack for Pi. Poteto's rigorous engineering workflow adapted from the pstack plugin into a Pi plugin: skills, subagents, and commands for write-less-higher-quality code with fearless parallelism.",
+  "version": "0.2.0",
+  "description": "pstack for Pi. Poteto's rigorous engineering workflow ported to the Pi Agent Harness: 50 skills and 2 agents, plus an extension that wires the mode into Pi settings, sessions, compaction, and the context window.",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -23,6 +23,8 @@
     "workflow",
     "principles",
     "subagents",
+    "context-guard",
+    "compaction",
     "unslop",
     "agent-style"
   ],
@@ -31,6 +33,7 @@
     "agents/",
     "docs/",
     "extensions/",
+    "scripts/",
     "README.md",
     "LICENSE"
   ],
@@ -61,9 +64,11 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run typecheck && npm test",
-    "test": "node --experimental-strip-types --test extensions/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run verify:sync && npm run verify:guards",
+    "test": "node --experimental-strip-types --test extensions/*.test.ts scripts/lib/*.test.mjs",
     "check:piisms": "node scripts/check-pi-isms.mjs",
+    "verify:sync": "node scripts/verify-sync.mjs",
+    "verify:guards": "node scripts/verify-guards.mjs",
     "sync:upstream": "node scripts/sync-upstream.mjs"
   },
   "devDependencies": {

package/scripts/check-pi-isms.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+const root = process.argv[2] ? resolve(process.argv[2]) : process.cwd();
+
+const COUPLING = [
+  "grok-4\\.6",
+  "claude-fable",
+  "gpt-5\\.6-sol",
+  "claude-opus",
+  "api2\\.cursor\\.sh",
+  "AskQuestion",
+  "subagent_type",
+  "Task\\(model",
+  "pstack-models\\.mdc",
+  "/add-plugin",
+  "cursor-team-kit",
+  "Cursor's",
+  "Cursor cloud",
+  "Cursor environment",
+  "Cursor restart",
+  "Cursor dashboard",
+  "\\.cursor/",
+  "cloud agent",
+  "cloud root",
+  "cloud VM",
+  "cloud-sleeper",
+  'environment: "cloud"',
+  "agent-transcripts",
+  "(?<![a-z-])/loop(?![a-z-])",
+  "pstack/skills/",
+];
+
+const PAT = new RegExp(COUPLING.join("|"), "i");
+
+const ALLOWED = [
+  {
+    prefix: "skills/poteto-mode/scripts/watch-pr/",
+    why: "Detects Cursor's bugbot review comments on GitHub, which is a real GitHub app and still worth gating on.",
+  },
+  {
+    prefix: "docs/compare.md",
+    why: "This file exists to name what differs from upstream and from the other Pi port, so it has to name the things it excludes.",
+  },
+];
+
+function allowed(path) {
+  return ALLOWED.some((entry) => path.startsWith(entry.prefix));
+}
+
+const DOC_PAT = /pi note|has no|does not|do not route|instead|never require|not a pstack skill|do NOT write/i;
+
+function* walk(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) yield* walk(path);
+    else yield path;
+  }
+}
+
+const action = [];
+const documented = [];
+const skipped = [];
+const emDashes = [];
+const brokenLinks = [];
+
+for (const base of ["skills", "agents", "docs"]) {
+  const dir = join(root, base);
+  if (!existsSync(dir)) continue;
+  for (const file of walk(dir)) {
+    if (!/\.(md|ts|sh|mjs|js)$/.test(file)) continue;
+    const rel = file.replace(`${root}/`, "");
+    const source = readFileSync(file, "utf8");
+    if (file.endsWith(".md")) {
+      for (const match of source.matchAll(/\]\(([^)\s]+)\)/g)) {
+        const target = match[1].split("#")[0];
+        if (!target || /^[a-z][a-z0-9+.-]*:/i.test(target) || allowed(rel)) continue;
+        if (!/[./]/.test(target)) continue;
+        if (!existsSync(resolve(dirname(file), target))) brokenLinks.push({ file: rel, line: 0, text: target });
+      }
+    }
+    source.split("\n").forEach((line, index) => {
+      if (/\u2014/.test(line) && !allowed(rel)) {
+        emDashes.push({ file: rel, line: index + 1, text: line.trim().slice(0, 150) });
+      }
+      if (!PAT.test(line)) return;
+      const hit = { file: rel, line: index + 1, text: line.trim().slice(0, 150) };
+      if (allowed(rel)) skipped.push(hit);
+      else if (DOC_PAT.test(line)) documented.push(hit);
+      else action.push(hit);
+    });
+  }
+}
+
+for (const hit of action) console.log(`ACTION ${hit.file}:${hit.line}: ${hit.text}`);
+for (const hit of skipped) console.log(`allowed ${hit.file}:${hit.line}: ${hit.text}`);
+for (const hit of emDashes) console.log(`EM-DASH ${hit.file}:${hit.line}: ${hit.text}`);
+for (const hit of brokenLinks) console.log(`LINK ${hit.file}: ${hit.text}`);
+
+console.log(`\n${action.length} Cursor-coupling, ${emDashes.length} long-dash character, ${brokenLinks.length} broken relative link, ${documented.length} documented as a Pi note, ${skipped.length} allowlisted.`);
+if (action.length === 0 && emDashes.length === 0 && brokenLinks.length === 0) {
+  console.log("clean: no unexplained Cursor coupling, no long-dash characters, and every relative link resolves.");
+  process.exit(0);
+}
+process.exit(1);

package/scripts/lib/pi-delta-rules.mjs

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+
+const GLOB_SPECIAL = /[.+^${}()|[\]\\]/g;
+
+export const RULE_KINDS = new Set(["substitute", "insert", "exclude", "add", "override"]);
+
+export function hashContent(content) {
+  return `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
+}
+
+export function globToRegExp(glob) {
+  const source = glob
+    .replace(GLOB_SPECIAL, "\\$&")
+    .replace(/\*\*\//g, "\u0000")
+    .replace(/\*\*/g, "\u0001")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\u0000/g, "(?:.*/)?")
+    .replace(/\u0001/g, ".*");
+  return new RegExp(`^${source}$`);
+}
+
+export function matchGlob(glob, path) {
+  return globToRegExp(glob).test(path);
+}
+
+export function globsOf(spec, kind) {
+  return spec.rules.filter((rule) => rule.kind === kind).map((rule) => rule.path);
+}
+
+export function matchesAny(globs, path) {
+  return globs.some((glob) => matchGlob(glob, path));
+}
+
+const REQUIRED_FIELDS = {
+  substitute: ["id", "path", "find", "replace", "reason"],
+  insert: ["id", "path", "anchor", "position", "text", "reason"],
+  exclude: ["id", "path", "reason"],
+  add: ["id", "path", "reason"],
+  override: ["id", "path", "basedOn", "reason"],
+};
+
+export function validateSpec(spec) {
+  const problems = [];
+  if (!spec || typeof spec !== "object") return ["spec is not an object"];
+  if (typeof spec.upstream?.ref !== "string" || !spec.upstream.ref) {
+    problems.push("upstream.ref is required");
+  }
+  if (!Array.isArray(spec.rules)) return [...problems, "rules must be an array"];
+  const seen = new Set();
+  spec.rules.forEach((rule, index) => {
+    const label = `rules[${index}]${rule?.id ? ` (${rule.id})` : ""}`;
+    if (!RULE_KINDS.has(rule?.kind)) {
+      problems.push(`${label}: unknown kind ${JSON.stringify(rule?.kind)}`);
+      return;
+    }
+    for (const field of REQUIRED_FIELDS[rule.kind]) {
+      if (typeof rule[field] !== "string" || rule[field] === "") {
+        problems.push(`${label}: ${field} must be a non-empty string`);
+      }
+    }
+    if (rule.kind === "insert" && !["before", "after"].includes(rule.position)) {
+      problems.push(`${label}: position must be "before" or "after"`);
+    }
+    if (rule.id) {
+      if (seen.has(rule.id)) problems.push(`${label}: duplicate id`);
+      seen.add(rule.id);
+    }
+  });
+  return problems;
+}
+
+function applySubstitute(content, rule) {
+  if (rule.regex) {
+    const pattern = new RegExp(rule.find, "g");
+    return content.replace(pattern, rule.replace);
+  }
+  return content.includes(rule.find) ? content.replaceAll(rule.find, rule.replace) : content;
+}
+
+function applyInsert(content, rule) {
+  const pattern = new RegExp(rule.anchor, "m");
+  const match = pattern.exec(content);
+  if (!match) return content;
+  const lineStart = match.index;
+  const lineEnd = content.indexOf("\n", lineStart);
+  const insertAt = rule.position === "before" || lineEnd === -1
+    ? lineStart
+    : lineEnd + 1;
+  const block = content.endsWith("\n") || insertAt === 0 ? `${rule.text}\n` : rule.text;
+  return content.slice(0, insertAt) + block + content.slice(insertAt);
+}
+
+export function applyRules(content, path, rules) {
+  let out = content;
+  const applied = [];
+  for (const rule of rules) {
+    if (rule.kind !== "substitute" && rule.kind !== "insert") continue;
+    if (!matchGlob(rule.path, path)) continue;
+    const next = rule.kind === "substitute" ? applySubstitute(out, rule) : applyInsert(out, rule);
+    if (next !== out) {
+      applied.push(rule.id);
+      out = next;
+    }
+  }
+  return { content: out, applied };
+}
+
+export function overrideFor(spec, path) {
+  return spec.rules.find((rule) => rule.kind === "override" && matchGlob(rule.path, path));
+}

package/scripts/lib/pi-delta-rules.test.mjs

@@ -0,0 +1,100 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { applyRules, globToRegExp, hashContent, matchGlob, overrideFor, validateSpec } from "./pi-delta-rules.mjs";
+
+test("glob matches nested paths for ** and one level for *", () => {
+  assert.ok(matchGlob("**/*.md", "skills/how/references/explainer-prompt.md"));
+  assert.ok(matchGlob("**/*.md", "top.md"), "**/ also matches zero directories");
+  assert.ok(matchGlob("agents/*.md", "agents/poteto-agent.md"));
+  assert.ok(!matchGlob("agents/*.md", "agents/nested/poteto-agent.md"));
+  assert.ok(matchGlob("**/*", "skills/poteto-mode/scripts/check-plan.mjs"));
+  assert.equal(globToRegExp("a*b").test("a/b"), false);
+});
+
+test("validateSpec rejects a bad kind, a duplicate id, and a bad insert position", () => {
+  const base = { upstream: { ref: "abc" }, rules: [] };
+  assert.deepEqual(validateSpec(base), []);
+
+  const unknown = validateSpec({ ...base, rules: [{ kind: "rewrite", id: "x" }] });
+  assert.ok(unknown.some((problem) => problem.includes("unknown kind")));
+
+  const duplicate = validateSpec({
+    ...base,
+    rules: [
+      { kind: "add", id: "same", path: "a/**", reason: "r" },
+      { kind: "add", id: "same", path: "b/**", reason: "r" },
+    ],
+  });
+  assert.ok(duplicate.some((problem) => problem.includes("duplicate id")));
+
+  const badPosition = validateSpec({
+    ...base,
+    rules: [{ kind: "insert", id: "i", path: "*", anchor: "^a$", position: "beside", text: "t", reason: "r" }],
+  });
+  assert.ok(badPosition.some((problem) => problem.includes("position")));
+
+  assert.ok(validateSpec({ rules: [] }).some((problem) => problem.includes("upstream.ref")));
+});
+
+test("substitute replaces every literal occurrence and reports which rules fired", () => {
+  const rules = [
+    { kind: "substitute", id: "swap", path: "**/*.md", find: ".cursor/skills/", replace: ".pi/skills/", reason: "r" },
+  ];
+  const input = "a .cursor/skills/ b .cursor/skills/ c";
+  const { content, applied } = applyRules(input, "skills/x/SKILL.md", rules);
+  assert.equal(content, "a .pi/skills/ b .pi/skills/ c");
+  assert.deepEqual(applied, ["swap"]);
+});
+
+test("a rule whose find is absent reports nothing applied, which is how stale rules surface", () => {
+  const rules = [{ kind: "substitute", id: "gone", path: "**/*.md", find: "no such text", replace: "x", reason: "r" }];
+  const { content, applied } = applyRules("untouched", "skills/x/SKILL.md", rules);
+  assert.equal(content, "untouched");
+  assert.deepEqual(applied, []);
+});
+
+test("a rule only applies to paths its glob matches", () => {
+  const rules = [{ kind: "substitute", id: "scoped", path: "agents/*.md", find: "a", replace: "b", reason: "r" }];
+  assert.deepEqual(applyRules("a", "skills/x/SKILL.md", rules).applied, []);
+  assert.deepEqual(applyRules("a", "agents/x.md", rules).applied, ["scoped"]);
+});
+
+test("insert places text on its own line before or after the anchor line", () => {
+  const input = "---\nname: x\ndescription: d\nis_background: true\n---\nbody\n";
+  const before = applyRules(input, "agents/x.md", [
+    { kind: "insert", id: "front", path: "agents/*.md", anchor: "^is_background: true$", position: "before", text: "thinking: high\ntools: read", reason: "r" },
+  ]);
+  assert.equal(before.content, "---\nname: x\ndescription: d\nthinking: high\ntools: read\nis_background: true\n---\nbody\n");
+
+  const after = applyRules(input, "agents/x.md", [
+    { kind: "insert", id: "desc", path: "agents/*.md", anchor: "^description: ", position: "after", text: "thinking: high", reason: "r" },
+  ]);
+  assert.equal(after.content, "---\nname: x\ndescription: d\nthinking: high\nis_background: true\n---\nbody\n");
+});
+
+test("declaration order decides the winner when two rules could match the same text", () => {
+  const shared = "Cursor's built-in `create-skill` skill";
+  const specific = { kind: "substitute", id: "specific", path: "**/*.md", find: shared, replace: "the bundled `create-skill` skill", reason: "r" };
+  const generic = { kind: "substitute", id: "generic", path: "**/*.md", find: "Cursor's built-in `create-skill`", replace: "the bundled `create-skill` skill", reason: "r" };
+
+  assert.deepEqual(applyRules(shared, "a.md", [specific, generic]).applied, ["specific"]);
+  assert.deepEqual(applyRules(shared, "a.md", [generic, specific]).applied, ["generic"]);
+});
+
+test("applyRules uses a regex rule when regex is set", () => {
+  const rules = [{ kind: "substitute", id: "rx", path: "**/*.md", regex: true, find: "\\(default `[^`]+`\\)", replace: "(default: inherit)", reason: "r" }];
+  const { content } = applyRules("- model: x (default `grok-4.6-fast-xhigh`)", "skills/x/SKILL.md", rules);
+  assert.equal(content, "- model: x (default: inherit)");
+});
+
+test("hashContent is stable and content-sensitive", () => {
+  assert.equal(hashContent("a"), hashContent("a"));
+  assert.notEqual(hashContent("a"), hashContent("b"));
+  assert.match(hashContent("a"), /^sha256:[0-9a-f]{64}$/);
+});
+
+test("overrideFor finds the baselined override that owns a path", () => {
+  const spec = { rules: [{ kind: "override", id: "ov", path: "skills/poteto-mode/SKILL.md", basedOn: "sha256:x", reason: "r" }] };
+  assert.equal(overrideFor(spec, "skills/poteto-mode/SKILL.md").id, "ov");
+  assert.equal(overrideFor(spec, "skills/how/SKILL.md"), undefined);
+});

package/scripts/lib/upstream-vendor.mjs

@@ -0,0 +1,32 @@
+import { spawnSync } from "node:child_process";
+
+export function git(upstreamDir, args, encoding = "utf8") {
+  const result = spawnSync("git", ["-C", upstreamDir, ...args], {
+    encoding,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    throw new Error(`git ${args.join(" ")} failed in ${upstreamDir}: ${result.stderr?.toString().trim() ?? ""}`);
+  }
+  return result.stdout;
+}
+
+export function upstreamVersion(upstreamDir, ref) {
+  const raw = git(upstreamDir, ["show", `${ref}:pstack/.cursor-plugin/plugin.json`]);
+  return JSON.parse(raw).version;
+}
+
+export function isBinary(buffer) {
+  return buffer.includes(0);
+}
+
+export function readUpstreamTree(upstreamDir, ref, subtrees = ["skills", "agents", "docs"]) {
+  const pathspecs = subtrees.map((subtree) => `pstack/${subtree}`);
+  const listed = git(upstreamDir, ["ls-tree", "-r", "--name-only", ref, "--", ...pathspecs]);
+  const files = new Map();
+  for (const line of listed.split("\n")) {
+    if (!line) continue;
+    files.set(line.replace(/^pstack\//, ""), git(upstreamDir, ["show", `${ref}:${line}`], null));
+  }
+  return files;
+}