pi-pstack-adapter 0.3.0

package/src/paths.ts

@@ -0,0 +1,67 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+export const CONFIG_FILE_NAME = "pi-pstack-adapter.json";
+
+export function expandHome(value: string): string {
+  if (value === "~") return homedir();
+  if (value.startsWith("~/") || value.startsWith(`~\\`)) {
+    return join(homedir(), value.slice(2));
+  }
+  return value;
+}
+
+/**
+ * Mirrors Pi's own `getAgentDir()`, so a sandboxed `PI_CODING_AGENT_DIR` keeps its cache
+ * beside its own config instead of writing into the real one.
+ */
+export function agentDir(): string {
+  const override = process.env.PI_CODING_AGENT_DIR;
+  return override ? resolve(expandHome(override)) : join(homedir(), ".pi", "agent");
+}
+
+export function cacheRoot(override?: string): string {
+  if (override) return resolve(expandHome(override));
+  return join(agentDir(), "cache", "pi-pstack-adapter");
+}
+
+export function digest(...parts: string[]): string {
+  const hash = createHash("sha256");
+  for (const part of parts) {
+    hash.update(part);
+    hash.update("\u0000");
+  }
+  return hash.digest("hex").slice(0, 16);
+}
+
+export function checkoutDir(root: string, repo: string): string {
+  return join(root, "checkouts", digest(repo));
+}
+
+export function generatedDir(root: string, inputsDigest: string): string {
+  return join(root, "generated", inputsDigest);
+}
+
+export function stateFile(root: string): string {
+  return join(root, "state.json");
+}
+
+/**
+ * A relative location inside the checkout. An upstream manifest and a config layer both
+ * supply these, so neither may escape the directory the adapter controls.
+ */
+export function validateContainedPath(value: string, label: string): string {
+  const normalized = value.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+  const escapes =
+    normalized === "" ||
+    isAbsolute(normalized) ||
+    /^[A-Za-z]:/.test(normalized) ||
+    normalized.split("/").some((segment) => segment === "..");
+  if (escapes) {
+    throw new Error(
+      `Refusing ${label} ${JSON.stringify(value)}. It must name a location inside the checkout, not an absolute or parent path.`,
+    );
+  }
+  return normalized;
+}

package/src/registry.ts

@@ -0,0 +1,104 @@
+import type { CapabilityId, RegistryEntry, SupportTier } from "./types.ts";
+
+/**
+ * Support tiers for the certified upstream revision. Classification came from reading
+ * every upstream SKILL.md; see `docs/compatibility.md` for how a tier changes.
+ * Skills absent from this table are generated as `experimental`.
+ */
+export const SKILL_REGISTRY: Readonly<Record<string, RegistryEntry>> = {
+  "architect": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "Phase B delegates to arena runners, so it cannot run without parallel subagents." },
+  "arena": { tier: "dependency-gated", capabilities: ["delegation"], executables: ["git"], note: "The whole skill is spawning N candidate subagents plus a judge." },
+  "automate-me": { tier: "experimental", capabilities: ["delegation", "structured-question"], executables: ["git", "gh"], note: "Mining step depends on Cursor transcript files and the built-in create-skill skill, with no Pi equivalent." },
+  "benchmark-checklist": { tier: "dependency-gated", capabilities: [], executables: ["uptime", "nproc"], note: "Its setup step checks load with `uptime` and cores with `nproc`. macOS has no `nproc` without GNU coreutils, and Git Bash on Windows has no `uptime`." },
+  "blast-radius": { tier: "dependency-gated", capabilities: [], executables: ["git", "gh"], note: "Needs git and gh to read the diff, commits, and PR before any analysis." },
+  "bro": { tier: "native", capabilities: [], executables: [] },
+  "correct": { tier: "dependency-gated", capabilities: [], executables: ["git"], note: "Mines commit history, then commits fixes and edits lint, CI, and agent instruction files. Run it on a branch you will review." },
+  "create-verification-skill": { tier: "adapted", capabilities: [], executables: [], note: "Only the generated skill's output path needs remapping to Pi's skill directory." },
+  "figure-it-out": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "Phase B fan-out and the architect/arena routing require parallel subagents." },
+  "how": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "Every path spawns explorer or explainer subagents; nothing runs inline." },
+  "interrogate": { tier: "dependency-gated", capabilities: ["delegation"], executables: ["git"], note: "Multi-model adversarial review is entirely one subagent per configured model." },
+  "maintain-verification-skill": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "Source wave launches one read-only subagent per feature file." },
+  "make-bot-ui": { tier: "unsupported", capabilities: [], executables: ["curl", "tailscale", "sudo"], note: "Built entirely on Cursor Automations webhook routines and the secret-request card." },
+  "no-comments": { tier: "dependency-gated", capabilities: ["delegation"], executables: ["git"], note: "Step 1 must spawn the named Comment Sicko agent; the skill only triages its report." },
+  "poteto-mode": { tier: "experimental", capabilities: ["delegation", "structured-question"], executables: ["git", "gh"], note: "Sticky-mode hosting plus references to Cursor built-in and plugin skills only partially map to Pi." },
+  "principle-attack-the-premise": { tier: "native", capabilities: [], executables: [] },
+  "principle-boundary-discipline": { tier: "native", capabilities: [], executables: [] },
+  "principle-build-the-lever": { tier: "native", capabilities: [], executables: [] },
+  "principle-encode-lessons-in-structure": { tier: "native", capabilities: [], executables: [] },
+  "principle-exhaust-the-design-space": { tier: "native", capabilities: [], executables: [] },
+  "principle-experience-first": { tier: "native", capabilities: [], executables: [] },
+  "principle-explain-the-number": { tier: "native", capabilities: [], executables: [], note: "For a performance number it hands off to benchmark-checklist, which needs uptime and nproc. Check that skill first." },
+  "principle-fix-root-causes": { tier: "native", capabilities: [], executables: [] },
+  "principle-foundational-thinking": { tier: "native", capabilities: [], executables: [] },
+  "principle-guard-the-context-window": { tier: "native", capabilities: [], executables: [] },
+  "principle-laziness-protocol": { tier: "native", capabilities: [], executables: [] },
+  "principle-make-operations-idempotent": { tier: "native", capabilities: [], executables: [] },
+  "principle-migrate-callers-then-delete-legacy-apis": { tier: "native", capabilities: [], executables: [] },
+  "principle-minimize-reader-load": { tier: "native", capabilities: [], executables: [] },
+  "principle-model-the-domain": { tier: "native", capabilities: [], executables: [] },
+  "principle-never-block-on-the-human": { tier: "native", capabilities: [], executables: [] },
+  "principle-outcome-oriented-execution": { tier: "native", capabilities: [], executables: [] },
+  "principle-prove-it-works": { tier: "native", capabilities: [], executables: [] },
+  "principle-redesign-from-first-principles": { tier: "native", capabilities: [], executables: [] },
+  "principle-separate-before-serializing-shared-state": { tier: "native", capabilities: [], executables: [] },
+  "principle-sequence-verifiable-units": { tier: "native", capabilities: [], executables: [] },
+  "principle-subtract-before-you-add": { tier: "native", capabilities: [], executables: [] },
+  "principle-test-behavior-not-implementation": { tier: "native", capabilities: [], executables: [] },
+  "principle-type-system-discipline": { tier: "native", capabilities: [], executables: [] },
+  "recall": { tier: "experimental", capabilities: ["delegation"], executables: ["git", "gh"], note: "Core corpus is Cursor's on-disk transcript JSONL, so only the git/gh and shared-record half survives." },
+  "reflect": { tier: "experimental", capabilities: ["delegation"], executables: [], note: "Transcript mining and create-skill routing are Cursor-specific, though the digest fallback partly works." },
+  "setup-pstack": { tier: "native", capabilities: [], executables: [], rename: "setup", replacement: "setup.md", note: "The upstream body only writes a Cursor .mdc rule, so the adapter replaces it with a Pi setup workflow." },
+  "show-me-your-work": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "The mandatory cross-model review of the trail requires spawning a different-family subagent." },
+  "swarm": { tier: "experimental", capabilities: ["delegation"], executables: [], note: "Cloud background workers and cloud_base_branch have no Pi mapping; only local fan-out approximates it." },
+  "tdd": { tier: "native", capabilities: [], executables: [] },
+  "teach": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "It runs the how and why skills, both of which need subagents." },
+  "technical-writing": { tier: "native", capabilities: [], executables: [] },
+  "typescript-best-practices": { tier: "native", capabilities: [], executables: [] },
+  "unslop": { tier: "native", capabilities: [], executables: [] },
+  "why": { tier: "dependency-gated", capabilities: ["delegation"], executables: ["git", "gh"], note: "Default posture spawns one investigator subagent per evidence category plus a synthesizer." },
+};
+
+/** Adapter-owned skills with no upstream counterpart. Keyed by unprefixed generated name. */
+export const ADAPTER_SKILLS: Readonly<Record<string, RegistryEntry>> = {
+  status: { tier: "native", capabilities: [], executables: [], replacement: "status.md" },
+};
+
+export const UNKNOWN_SKILL_ENTRY: RegistryEntry = {
+  tier: "experimental",
+  capabilities: [],
+  executables: [],
+  note: "This skill is not in the adapter compatibility registry for the certified revision.",
+};
+
+export const TIER_ORDER: readonly SupportTier[] = [
+  "native",
+  "adapted",
+  "dependency-gated",
+  "experimental",
+  "unsupported",
+];
+
+export const CAPABILITY_LABELS: Readonly<Record<CapabilityId, string>> = {
+  delegation: "named parallel background subagents with model selection and tool restrictions",
+  "structured-question": "structured multiple-choice questions to the user",
+};
+
+export const ADAPTER_OWNED = "(adapter-owned)";
+
+/** Model roles pstack workflows name. A role with no configured model inherits the parent. */
+export const MODEL_ROLES: readonly string[] = [
+  "feature",
+  "refactoring",
+  "bug-fix",
+  "perf-issue",
+  "hillclimb",
+  "judgment",
+  "strongest-judgment",
+];
+
+export function entryFor(upstreamName: string, generatedBareName?: string): RegistryEntry {
+  if (upstreamName === ADAPTER_OWNED && generatedBareName) {
+    return ADAPTER_SKILLS[generatedBareName] ?? UNKNOWN_SKILL_ENTRY;
+  }
+  return SKILL_REGISTRY[upstreamName] ?? UNKNOWN_SKILL_ENTRY;
+}

package/src/status.ts

@@ -0,0 +1,215 @@
+import { CERTIFIED } from "./certified.ts";
+import { CAPABILITY_LABELS, MODEL_ROLES, TIER_ORDER } from "./registry.ts";
+import type { AdapterConfig } from "./config.ts";
+import { trustWarning } from "./config.ts";
+import type { PrerequisiteReport } from "./capabilities.ts";
+import type {
+  CapabilityStatus,
+  Diagnostic,
+  GeneratedSkill,
+  GenerationResult,
+  PlatformSupport,
+  RegistryEntry,
+  ResolvedSource,
+  SupportTier,
+} from "./types.ts";
+
+export interface StatusInput {
+  readonly adapterVersion: string;
+  readonly config: AdapterConfig;
+  readonly source: ResolvedSource;
+  readonly upstreamVersion: string;
+  readonly generation: GenerationResult;
+  readonly capabilities: readonly CapabilityStatus[];
+  readonly platform: PlatformSupport;
+  readonly platformName: string;
+  readonly modeActive: boolean;
+  readonly cacheRoot: string;
+  readonly bootstrapped: boolean;
+  /** Runtime findings that generation could not know, such as agent registration results. */
+  readonly runtimeDiagnostics?: readonly Diagnostic[];
+}
+
+export function renderStatus(input: StatusInput): string {
+  const { config, source } = input;
+  const lines: string[] = [];
+
+  lines.push(`# ${config.namespace} adapter status`);
+  lines.push("");
+  lines.push(`| field | value |`);
+  lines.push(`| --- | --- |`);
+  lines.push(`| adapter version | ${input.adapterVersion} |`);
+  lines.push(`| upstream pstack version | ${input.upstreamVersion} |`);
+  lines.push(`| certified pstack version | ${CERTIFIED.pstackVersion} |`);
+  lines.push(`| configured source | ${describeSelection(input)} |`);
+  lines.push(`| resolved commit | ${source.commit || "(not a git checkout)"} |`);
+  lines.push(`| certified commit | ${CERTIFIED.commit} |`);
+  lines.push(`| trust | ${source.trust} |`);
+  lines.push(`| checkout | ${source.checkoutDir} |`);
+  lines.push(`| generated resources | ${input.generation.outDir} |`);
+  lines.push(`| cache root | ${input.cacheRoot} |`);
+  lines.push(`| cache state | ${input.bootstrapped ? "downloaded this session" : "reused, no network needed"} |`);
+  lines.push(`| namespace | ${config.namespace} |`);
+  lines.push(`| config layers | ${config.sources.length > 0 ? config.sources.join(", ") : "built-in defaults"} |`);
+  lines.push(`| platform | ${input.platformName} (${input.platform}) |`);
+  lines.push(`| Poteto Mode | ${input.modeActive ? "active" : "off"} |`);
+  lines.push("");
+
+  const warning = trustWarning(source.trust, config);
+  if (warning) {
+    lines.push(`> Warning. ${warning}`);
+    lines.push("");
+  }
+  if (input.platform === "experimental") {
+    lines.push(
+      `> Warning. ${input.platformName} is experimental for this release. Adapter-owned code is portable, but upstream pstack skills call POSIX shell tools that this platform may not provide. Only Linux, macOS, and Windows are certified.`,
+    );
+    lines.push("");
+  }
+
+  lines.push(`## Capabilities`);
+  lines.push("");
+  lines.push(`| capability | state | note |`);
+  lines.push(`| --- | --- | --- |`);
+  for (const capability of input.capabilities) {
+    const note = capability.available
+      ? CAPABILITY_LABELS[capability.id]
+      : capability.recommendation;
+    lines.push(`| ${capability.id} | ${capability.available ? "available" : "missing"} | ${note} |`);
+  }
+  lines.push("");
+
+  lines.push(`## Model roles`);
+  lines.push("");
+  lines.push(`| role | model |`);
+  lines.push(`| --- | --- |`);
+  for (const role of MODEL_ROLES) {
+    lines.push(`| ${role} | ${config.models[role] ?? "inherit (parent session model)"} |`);
+  }
+  const extra = Object.keys(config.models).filter((role) => !MODEL_ROLES.includes(role)).sort();
+  for (const role of extra) {
+    lines.push(`| ${role} | ${config.models[role]} |`);
+  }
+  lines.push("");
+
+  lines.push(`## Support tiers`);
+  lines.push("");
+  const byTier = groupByTier(input.generation);
+  lines.push(`| tier | count | skills |`);
+  lines.push(`| --- | --- | --- |`);
+  for (const tier of TIER_ORDER) {
+    const names = byTier.get(tier) ?? [];
+    if (names.length === 0) continue;
+    lines.push(`| ${tier} | ${names.length} | ${names.join(", ")} |`);
+  }
+  lines.push("");
+  lines.push(
+    `${input.generation.skills.length} skills and ${input.generation.agents.length} agents are registered under \`${config.namespace}\`.`,
+  );
+  lines.push("");
+
+  lines.push(`## Diagnostics`);
+  lines.push("");
+  const diagnostics = [...input.generation.diagnostics, ...(input.runtimeDiagnostics ?? [])];
+  if (diagnostics.length === 0) {
+    lines.push("No upstream resource problems found.");
+  } else {
+    lines.push(`| level | resource | message | action |`);
+    lines.push(`| --- | --- | --- | --- |`);
+    for (const diagnostic of sortDiagnostics(diagnostics)) {
+      lines.push(`| ${diagnostic.level} | ${diagnostic.resource} | ${diagnostic.message} | ${diagnostic.action ?? "-"} |`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function describeSelection(input: StatusInput): string {
+  const { config } = input;
+  if (config.localPath) return `local checkout ${config.localPath}`;
+  const pin = config.pinnedCommit ? ` pinned at ${config.pinnedCommit}` : ` at ref ${config.ref}`;
+  return `${config.repo}${pin}`;
+}
+
+function groupByTier(generation: GenerationResult): Map<SupportTier, string[]> {
+  const grouped = new Map<SupportTier, string[]>();
+  for (const skill of generation.skills) {
+    const names = grouped.get(skill.tier) ?? [];
+    names.push(skill.generatedName);
+    grouped.set(skill.tier, names);
+  }
+  return grouped;
+}
+
+const LEVEL_RANK = { error: 0, warning: 1, info: 2 } as const;
+
+function sortDiagnostics(diagnostics: readonly Diagnostic[]): Diagnostic[] {
+  return [...diagnostics].sort(
+    (a, b) => LEVEL_RANK[a.level] - LEVEL_RANK[b.level] || a.resource.localeCompare(b.resource),
+  );
+}
+
+export function renderCheck(
+  skill: GeneratedSkill,
+  entry: RegistryEntry,
+  report: PrerequisiteReport,
+): string {
+  const parts = [`\`/skill:${skill.generatedName}\` is tier **${skill.tier}**.`];
+  if (entry.note) parts.push(entry.note);
+  if (skill.tier === "unsupported") {
+    parts.push(
+      "Pi cannot provide what this workflow needs, so it cannot reach its purpose here. Prerequisite checks do not change that.",
+    );
+  }
+  if (!report.ok) {
+    parts.push(`Do not start this workflow yet.\n${report.lines.map((line) => `- ${line}`).join("\n")}`);
+  } else if (skill.tier !== "unsupported") {
+    parts.push("Prerequisites satisfied. Start the workflow.");
+  }
+  if (skill.tier === "experimental" && report.ok) {
+    parts.push("Tier `experimental` means parts of this workflow have no Pi equivalent. Expect gaps.");
+  }
+  return parts.join("\n\n");
+}
+
+/** Platforms a release certifies. Windows means native Windows with Pi's Git Bash `bash` tool. */
+export function platformSupport(platform: string): PlatformSupport {
+  return platform === "linux" || platform === "darwin" || platform === "win32" ? "supported" : "experimental";
+}
+
+export interface ShellState {
+  /** Why Pi could not resolve the shell its `bash` tool runs, or undefined when it can. */
+  readonly shellError?: string;
+  /** Why the resolved shell could not run a command, when a probe ran and failed. */
+  readonly runError?: string;
+  /** Whether the `bash` tool is in the active tool set, for example not replaced by `powershell`. */
+  readonly bashToolActive: boolean;
+}
+
+/**
+ * Upstream skill bodies are written as Bash commands for Pi's `bash` tool, so a session without
+ * that tool or its shell cannot run them. On Windows that shell is Git Bash.
+ */
+export function shellDiagnostics(state: ShellState): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  if (state.shellError !== undefined) {
+    diagnostics.push({
+      level: "error",
+      resource: "shell",
+      message: `Pi cannot find the Bash shell its \`bash\` tool runs, and pstack skills run their commands there. ${state.shellError.split("\n")[0]}`,
+      action: "Install Git for Windows, or set `shellPath` in Pi settings to a Bash executable, then run /reload.",
+    });
+  }
+  if (state.runError !== undefined) {
+    diagnostics.push({ level: "error", resource: "shell", message: state.runError });
+  }
+  if (!state.bashToolActive) {
+    diagnostics.push({
+      level: "warning",
+      resource: "shell",
+      message: "The `bash` tool is not active in this session. pstack skill bodies are written as Bash commands, and PowerShell does not run them.",
+      action: "Add `\"bash\"` to the `defaultTools` list in Pi settings, or remove that setting, then restart Pi.",
+    });
+  }
+  return diagnostics;
+}

package/src/types.ts

@@ -0,0 +1,98 @@
+export type SourceSelection =
+  | { readonly kind: "git"; readonly repo: string; readonly ref: string }
+  | { readonly kind: "local"; readonly path: string };
+
+export type Trust = "tested" | "untested-ref" | "untested-repo" | "local";
+
+export interface ResolvedSource {
+  readonly selection: SourceSelection;
+  readonly trust: Trust;
+  /** Empty for a local checkout that is not a git worktree. */
+  readonly commit: string;
+  readonly checkoutDir: string;
+  readonly pluginDir: string;
+}
+
+export type SupportTier =
+  | "native"
+  | "adapted"
+  | "dependency-gated"
+  | "experimental"
+  | "unsupported";
+
+export type CapabilityId = "delegation" | "structured-question";
+
+export interface RegistryEntry {
+  readonly tier: SupportTier;
+  readonly capabilities: readonly CapabilityId[];
+  readonly executables: readonly string[];
+  readonly note?: string;
+  /** Adapter-owned body file under `adapter-skills/`, replacing the upstream body. */
+  readonly replacement?: string;
+  /** Unprefixed generated name when it differs from the upstream directory name. */
+  readonly rename?: string;
+}
+
+export interface UpstreamManifest {
+  readonly name: string;
+  readonly version: string;
+  readonly skillsDir: string;
+  readonly agentsDir: string;
+}
+
+export interface UpstreamResource {
+  readonly name: string;
+  readonly kind: "skill" | "agent";
+  /** Skill directory, or the agents directory for an agent. */
+  readonly dir: string;
+  readonly entryPath: string;
+}
+
+export interface ParsedResource {
+  readonly resource: UpstreamResource;
+  readonly frontmatter: Readonly<Record<string, string>>;
+  readonly body: string;
+}
+
+export type DiagnosticLevel = "error" | "warning" | "info";
+
+export interface Diagnostic {
+  readonly level: DiagnosticLevel;
+  readonly resource: string;
+  readonly message: string;
+  readonly action?: string;
+}
+
+export interface GeneratedSkill {
+  readonly upstreamName: string;
+  readonly generatedName: string;
+  readonly tier: SupportTier;
+  readonly capabilities: readonly CapabilityId[];
+  readonly executables: readonly string[];
+  readonly path: string;
+}
+
+export interface GeneratedAgent {
+  readonly upstreamName: string;
+  readonly generatedName: string;
+  readonly displayName: string;
+  readonly description: string;
+  readonly systemPrompt: string;
+}
+
+export interface GenerationResult {
+  readonly outDir: string;
+  readonly skillsDir: string;
+  readonly skills: readonly GeneratedSkill[];
+  readonly agents: readonly GeneratedAgent[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+export interface CapabilityStatus {
+  readonly id: CapabilityId;
+  readonly available: boolean;
+  readonly provider?: string;
+  readonly recommendation: string;
+}
+
+export type PlatformSupport = "supported" | "experimental";