@mgiles/perk 1.0.1 → 2.0.0

package/extension/doors/ciExecutor.ts

@@ -1,7 +1,8 @@
 // The perk-owned, read-only CI executor (the Run→Report half of Run→Report→Fix→Verify).
 //
-// A deterministic, in-process check runner: it runs the project's configured `[ci]` named checks
-// via `pi.exec` and REPORTS pass/fail + failure output — it never edits, fixes, or loops. The
+// A deterministic, in-process check runner: it runs the project's configured `[[ci.checks]]`
+// named checks via `pi.exec` and REPORTS pass/fail + failure output — it never edits, fixes, or
+// loops. The
 // parent agent (the normal read-write implement session) owns the entire fix loop and all
 // iteration state; this executor is a stateless oracle invoked once per `run_ci` call (the
 // `devrun` discipline: "run and report", never "run and fix").
@@ -13,14 +14,14 @@
 // does NOT call `runReadOnlyChild` (whose `success` means "ran", carrying no exit code).
 //
 // Threat model & the safety boundary (read first):
-//   `pi.exec("bash", ["-lc", cmd])` runs whatever the `[ci]` command string says, with full
-//   filesystem/network access, OUTSIDE perk's tool gate. The defenses, in order, are:
+//   `pi.exec("bash", ["-lc", cmd])` runs whatever the `[[ci.checks]]` command string says, with
+//   full filesystem/network access, OUTSIDE perk's tool gate. The defenses, in order, are:
 //     1. The model never authors the command — it picks a configured NAME (a persuaded model
 //        cannot run `rm -rf` because it cannot supply a command).
 //     2. Untrusted-config scope gate (`decideCiScope`) — running a project-supplied command at
-//        all requires `[trust] ci = "true"` (committed config), `--allow-project-ci`, an
+//        all requires `[ci] trusted = true` (committed config), `--allow-project-ci`, an
 //        interactive confirm, or a per-session approval latch; headless with none REFUSES (fail
-//        closed). This is the real defense against a malicious cloned-repo `[ci]`.
+//        closed). This is the real defense against malicious cloned-repo `[[ci.checks]]` rows.
 //     3. Output isolation — full output to scratch, capped + `<untrusted_ci_output>`-wrapped in
 //        the parent's view (prompt-injection-in-stdout hygiene).
 //   A true OS/tool sandbox around the check command is explicitly OUT OF SCOPE.
@@ -29,6 +30,7 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { ensureRunScratch, scratchDir } from "../substrate/cache.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { type CiCheck, loadPerkConfig } from "../substrate/config.ts";
 import { paramsOf, stringParam } from "../substrate/toolParams.ts";
 import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
@@ -93,7 +95,7 @@ export type CiScope = "run" | "confirm" | "refuse";
 
 /**
  * Decide how to treat project-supplied CI. Pure (the load-bearing safety boundary):
- *   - `[trust] ci` (committed config), `--allow-project-ci`, or a per-session latch ⇒ "run"
+ *   - `[ci] trusted` (committed config), `--allow-project-ci`, or a per-session latch ⇒ "run"
  *     (trust runs on EVERY surface, overriding the headless refuse below)
  *   - else with UI ⇒ "confirm" (ask the human)
  *   - else (headless, no trust/flag) ⇒ "refuse" (fail closed)
@@ -163,7 +165,9 @@ export async function runOneCheck(
     writeError = err instanceof Error ? err.message : String(err);
   }
 
-  const capped = capForModel(outcome.output, cap, scratchPath);
+  // Tail-keep: pytest/tsc failure summaries live at the END of the output, so the model-visible
+  // slice keeps the last `cap` bytes; the scratch file still holds the full output.
+  const capped = capForModel(outcome.output, cap, scratchPath, "tail");
   return {
     name,
     command,
@@ -367,7 +371,7 @@ export function renderCiProse(report: CiReport): string {
     );
   }
   if (report.error_type === "no_checks_configured") {
-    return "No CI checks configured ([[ci]] in .pi/perk.toml is empty). Nothing to run.";
+    return "No CI checks configured ([[ci.checks]] in .perk/config.toml is empty). Nothing to run.";
   }
   if (report.error_type === "unknown_check") {
     return `perk CI: ${report.error}`;
@@ -397,6 +401,9 @@ export function renderCiProse(report: CiReport): string {
     lines.push(c.shown || "(no output captured)");
     lines.push("</untrusted_ci_output>");
   }
+  // Deliberately head-capped (unlike the per-check tail cap): the prose leads with the ✓/✗
+  // per-check summary and the scratch-path pointers — the actionable routing info a tail cap
+  // would drop.
   return capForModel(lines.join("\n"), DEFAULT_MODEL_VISIBLE_CAP).shown;
 }
 
@@ -432,8 +439,9 @@ interface ApprovalLatch {
 }
 
 /**
- * The single `run_ci`/`/ci` implementation. Loads `[ci]`, scopes the run (the untrusted-config
- * gate), runs the selected check(s) deterministically, and returns double-delivery. Never throws.
+ * The single `run_ci`/`/ci` implementation. Loads `[[ci.checks]]`, scopes the run (the
+ * untrusted-config gate), runs the selected check(s) deterministically, and returns
+ * double-delivery. Never throws.
  */
 async function runCiImpl(
   pi: ExtensionAPI,
@@ -443,7 +451,7 @@ async function runCiImpl(
   deps: RunCiDeps = {},
 ): Promise<CiResult> {
   const cfg = loadPerkConfig(ctx.cwd);
-  const checks: CiCheck[] = cfg.ci;
+  const checks: CiCheck[] = cfg.ci.checks;
   const wrap = (report: CiReport): CiResult => ({
     content: [{ type: "text", text: renderCiProse(report) }],
     details: report,
@@ -455,7 +463,7 @@ async function runCiImpl(
   if (checks.length > 0) {
     const decideScope = deps.decideScope ?? decideCiScope;
     const allowFlag = pi.getFlag("allow-project-ci") === true;
-    const trusted = cfg.trust.ci === true;
+    const trusted = cfg.ci.trusted;
     const scope = decideScope({ hasUI: ctx.hasUI, allowFlag, approved: latch.approved, trusted });
 
     if (scope === "refuse") {
@@ -506,7 +514,7 @@ async function runCiImpl(
 const TOOL_GUIDELINES = [
   "run_ci RUNS the configured CI checks and REPORTS results — it never edits, fixes, or loops.",
   "Analyze any failure yourself, fix it in your own turn, then call run_ci again to re-verify.",
-  "Optionally pass a single configured check name; omit it to run all checks in declared order.",
+  "Pass run_ci a single configured check name to run just that check; omit it to run all checks in declared order.",
   "You own the Run→Report→Fix→Verify loop; run_ci is a stateless oracle, not an auto-fixer.",
 ];
 
@@ -565,7 +573,7 @@ export function registerCiExecutor(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerCommand("ci", {
+  registerPerkCommand(pi, "ci", {
     description: "Run the project's configured CI checks and report results (never auto-fixes).",
     handler: async (args, ctx) => {
       const check = args.trim() === "" ? undefined : args.trim();

package/extension/doors/hunkHandoff.ts

@@ -0,0 +1,202 @@
+// The hunk terminal-review substrate serving `/pr-review-terminal`: the strict
+// `perk pr review checkout` decode, the `hunk --version` presence probe, and the R7 launch
+// handoff (clipboard copy + terminal auto-launch raced against a soft deadline) — plus the
+// door-common PR-token arg grammar (`parseReviewArgs`) that `/pr-review-browser` also consumes
+// via `parseReviewDoorArgs`. Re-homing the door-common pieces to a neutral module is a deferred
+// residual (accepted — no code moves yet).
+
+import { copyToClipboard } from "../substrate/clipboard.ts";
+import { type ColdJson, type ExecHost, numberField, stringField } from "../substrate/coldDoor.ts";
+import { LAUNCH_SURFACE, launchInTerminal } from "../substrate/terminalLaunch.ts";
+import { type ReportTarget, report } from "../surfaces/report.ts";
+
+/** The install hint for the absent hunk binary — the exact `HUNK_INSTALL_HINT` wording
+ * (src/perk/convergence/init/review_cli.py). */
+export const HUNK_INSTALL_HINT = "npm i -g hunkdiff (or brew install hunk)";
+
+// ------------------------------------------------------------------------ the PR arg grammar
+
+/** A parsed PR-review invocation: the PR number + the optional free-form focus directive. */
+export interface ReviewArgs {
+  pr: number;
+  directive: string;
+}
+
+/** Extracts the PR number from a GitHub PR URL (with optional trailing /path, #fragment, ?query). */
+export const PR_URL_RE = /\/pull\/(\d+)(?:\/|$|#|\?)/;
+
+/**
+ * Parse a PR-review arg string: the first token is a bare PR number or a GitHub PR URL; the rest
+ * is the optional free-form focus directive. Null on a missing/unparseable PR (usage failure).
+ * Cross-repo URLs are NOT validated against the session repo — the number is extracted as-is.
+ */
+export function parseReviewArgs(args: string): ReviewArgs | null {
+  const trimmed = args.trim();
+  if (trimmed.length === 0) return null;
+  const split = trimmed.match(/^(\S+)(?:\s+([\s\S]*))?$/);
+  if (split === null) return null;
+  const first = split[1] ?? "";
+  const directive = (split[2] ?? "").trim();
+  let pr: number | null = null;
+  if (/^\d+$/.test(first)) {
+    pr = Number(first);
+  } else {
+    const url = first.match(PR_URL_RE);
+    if (url?.[1] !== undefined) pr = Number(url[1]);
+  }
+  if (pr === null || !Number.isSafeInteger(pr) || pr <= 0) return null;
+  return { pr, directive };
+}
+
+// ------------------------------------------------------------------------ checkout decode
+
+/** The `perk pr review checkout --json` ok-arm (all six fields always emitted — strict). */
+export interface CheckoutOk {
+  path: string;
+  pr: number;
+  url: string;
+  head_sha: string;
+  base_sha: string;
+  base_ref: string;
+}
+
+/** Strict decode of the checkout payload — the guidance dereferences `path`/`base_sha`/`url`. */
+export function decodeCheckout(payload: ColdJson): CheckoutOk | null {
+  const path = stringField(payload, "path");
+  const pr = numberField(payload, "pr");
+  const url = stringField(payload, "url");
+  const headSha = stringField(payload, "head_sha");
+  const baseSha = stringField(payload, "base_sha");
+  const baseRef = stringField(payload, "base_ref");
+  if (
+    path === undefined ||
+    pr === undefined ||
+    url === undefined ||
+    headSha === undefined ||
+    baseSha === undefined ||
+    baseRef === undefined
+  ) {
+    return null;
+  }
+  return { path, pr, url, head_sha: headSha, base_sha: baseSha, base_ref: baseRef };
+}
+
+// ------------------------------------------------------------------------ the hunk probe
+
+/**
+ * Whether the `hunk` review CLI is present — the `hunk --version` probe (`!killed && code === 0`;
+ * any throw ⇒ false). The terminal door refuses-at-start on a false, before any cold-door call.
+ */
+export async function hunkPresent(
+  pi: ExecHost,
+  ctx: { cwd: string; signal?: AbortSignal },
+): Promise<boolean> {
+  try {
+    const probe = await pi.exec("hunk", ["--version"], { cwd: ctx.cwd, signal: ctx.signal });
+    return !probe.killed && probe.code === 0;
+  } catch {
+    return false;
+  }
+}
+
+// ------------------------------------------------------------------------ the R7 handoff
+
+/** The minimal ctx slice the hunk launch handoff needs (report + the exec cwd/signal). */
+interface ReviewLaunchCtx extends ReportTarget {
+  cwd: string;
+  signal?: AbortSignal;
+}
+
+/** The default soft deadline the launch is raced against (ms) — see `handleHunkLaunch`. */
+const LAUNCH_SOFT_DEADLINE_MS = 2000;
+
+/**
+ * The soft-deadline knob: `PERK_REVIEW_LAUNCH_DEADLINE_MS` (an internal test seam — documented
+ * in contracts §8.4 beside the two human-facing seams, never in user docs; tests drive the whole
+ * command handler, so an env knob is the only injectable surface). Falls back to the 2s default.
+ */
+function softDeadlineMs(): number {
+  const raw = process.env.PERK_REVIEW_LAUNCH_DEADLINE_MS;
+  if (raw !== undefined) {
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  return LAUNCH_SOFT_DEADLINE_MS;
+}
+
+/**
+ * A cancellable `null`-resolving timer — the soft-deadline arm of the launch race. The caller
+ * cancels it once the race settles so a won race never leaves a live timer behind (a leak in
+ * production; a hang/latency drag under test runners that wait for pending timers).
+ */
+function delay(ms: number): { promise: Promise<null>; cancel: () => void } {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const promise = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), ms);
+  });
+  return {
+    promise,
+    cancel: () => {
+      if (timer !== undefined) clearTimeout(timer);
+    },
+  };
+}
+
+/**
+ * The hunk R7 handoff (contracts §8.4). Copies the launch command to the clipboard, then
+ * auto-launches hunk in a terminal the human can see — raced against a soft deadline so a
+ * first-run macOS Automation/TCC dialog (which blocks `osascript` until answered) never inserts
+ * ~18s of silence before the guidance injection. Reports the outcome under `opts.scope` (the
+ * invoking door's report scope): an **info** "opened hunk" when the launch settled cleanly within
+ * the deadline, else a **warning** "ACTION NEEDED" (the launch failed, no rung matched, or it is
+ * still pending). For the pending case, a background follow-up info note lands if/when consent is
+ * granted and the launch succeeds. Non-blocking: the caller injects the guidance immediately
+ * either way. The `hunk session get` handshake (driven by the model per the template) — never a
+ * spawn success — remains the only verification hunk is up.
+ */
+export async function handleHunkLaunch(
+  pi: ExecHost,
+  ctx: ReviewLaunchCtx,
+  opts: { cwd: string; hunkCmd: string; launchLine: string; scope: string },
+): Promise<void> {
+  const copied = await copyToClipboard(pi, ctx, opts.launchLine);
+  const clip = copied ? " (it's on your clipboard)" : "";
+  const settled = launchInTerminal(pi, ctx, { cwd: opts.cwd, command: opts.hunkCmd });
+  const deadline = delay(softDeadlineMs());
+  const quick = await Promise.race([settled, deadline.promise]);
+  deadline.cancel();
+  if (quick?.launched) {
+    report(
+      ctx,
+      opts.scope,
+      "info",
+      `opened hunk in a new ${LAUNCH_SURFACE[quick.via ?? "terminal-app"]} — if nothing ` +
+        `appeared, run this in another terminal:\n  ${opts.launchLine}${clip}`,
+    );
+    return;
+  }
+  report(
+    ctx,
+    opts.scope,
+    "warning",
+    `ACTION NEEDED — run hunk in another terminal:\n  ${opts.launchLine}${clip}`,
+  );
+  if (quick === null) {
+    // Still pending past the soft deadline (a first-run TCC dialog): proceed now, and note it if
+    // consent is granted and the launch lands so the human can ignore the manual step.
+    // `launchInTerminal` never rejects by contract — the `.catch` is belt-and-braces.
+    void settled
+      .then((r) => {
+        if (r.launched) {
+          report(
+            ctx,
+            opts.scope,
+            "info",
+            `hunk opened in a new ${LAUNCH_SURFACE[r.via ?? "terminal-app"]} — ignore the ` +
+              "manual step above",
+          );
+        }
+      })
+      .catch(() => {});
+  }
+}

package/extension/doors/land.ts

@@ -1,13 +1,16 @@
 // The warm `/land` door. The in-session twin of the Python cold door
 // (`perk pr land`): a terminating tool + command that DELEGATE the GitHub merge (mutations
-// canonical in Python), then set the `pending-learn` marker for the in-session path (the worker
-// sets it too on the cold path; the marker is an idempotent existence-semaphore). Never throws.
+// canonical in Python), then mirror the envelope's `pending_learn` for the in-session path —
+// setting the `pending-learn` marker (an idempotent existence-semaphore; the worker sets it too
+// on the cold path) unless the cold door reports the learn-docs exemption (`pending_learn:
+// false` — no marker, no /learn nudge). Never throws.
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { reconcileGuidance } from "../factories/objectivePlan.ts";
 import { bindingSuffix } from "../substrate/bindingDelivery.ts";
 import { PENDING_LEARN, setMarker } from "../substrate/cache.ts";
 import {
+  booleanField,
   type ColdJson,
   nullableStringField,
   numberField,
@@ -15,6 +18,7 @@ import {
   runColdDoor,
   stringField,
 } from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { failFor, ok, type Result } from "../substrate/result.ts";
 import { report } from "../surfaces/report.ts";
 
@@ -36,7 +40,8 @@ export interface LearnConsumeUpdate {
   skipped_reason: string | null;
 }
 
-/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
+/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state.
+ * `pending_learn` mirrors the cold envelope: `false` is the learn-docs exemption (no marker). */
 export interface LandOk {
   pr: { number: number; state: string };
   branch?: string;
@@ -50,11 +55,13 @@ export interface LandOk {
 export type LandResult = Result<LandOk>;
 export type LandDetails = LandResult["details"];
 
-/** The decoded `perk pr land --json` payload — `LandOk` minus the warm-door-owned `pending_learn`. */
+/** The decoded `perk pr land --json` payload — the cold door owns `pending_learn` (the
+ * learn-docs-exemption decision point); decoded leniently so skew degrades to legacy. */
 interface LandPayload {
   pr: { number: number; state: string };
   branch?: string;
   issue?: string;
+  pending_learn: boolean;
   objective?: ObjectiveLandUpdate;
   learn?: LearnConsumeUpdate;
 }
@@ -107,6 +114,10 @@ function decodeLand(payload: ColdJson): LandPayload | null {
     pr: { number, state },
     branch: stringField(payload, "branch"),
     issue: stringField(payload, "issue"),
+    // Lenient: a missing/mistyped `pending_learn` (an older cold CLI under version skew)
+    // defaults to the legacy behavior (marker + /learn nudge) — never a silently-unreleased
+    // marker with no visible nudge.
+    pending_learn: booleanField(payload, "pending_learn") ?? true,
     objective: decodeObjective(payload),
     learn: decodeLearn(payload),
   };
@@ -114,7 +125,9 @@ function decodeLand(payload: ColdJson): LandPayload | null {
 
 /**
  * The single land implementation both surfaces call. Delegates the merge to the Python cold door,
- * then sets `pending-learn` (in-session path). Returns a soft result (never throws).
+ * then mirrors the envelope's `pending_learn` (in-session path): marker + /learn nudge on the
+ * ordinary arm; no marker, no nudge on the learn-docs exemption. Returns a soft result
+ * (never throws).
  */
 export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<LandResult> {
   const fail = failFor(ctx, "land");
@@ -125,10 +138,16 @@ export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<L
   });
   if (!r.ok) return fail(r.message, r.errorType);
 
-  // Set the semaphore for the in-session path (idempotent; the worker also set it on disk).
-  setMarker(ctx.cwd, PENDING_LEARN);
+  if (r.data.pending_learn) {
+    // Set the semaphore for the in-session path (idempotent; the cold door also set it on disk).
+    setMarker(ctx.cwd, PENDING_LEARN);
+  }
 
-  const lines = [`Landed PR #${r.data.pr.number}; run /learn to release the worktree.`];
+  const lines = [
+    r.data.pending_learn
+      ? `Landed PR #${r.data.pr.number}; run /learn to release the worktree.`
+      : `Landed PR #${r.data.pr.number}; learn-docs plan — no learn pass needed; the worktree is releasable.`,
+  ];
   const obj = r.data.objective;
   if (obj?.nodes_marked.length && obj.id !== null) {
     // The reconcile pass is auto-driven after land (see driveReconcileAfterLand); just report it.
@@ -155,7 +174,11 @@ export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<L
     lines.push(`Warning: learn consume incomplete — ${learn.skipped_reason}.`);
   }
 
-  return ok(lines.join("\n"), { ...r.data, pending_learn: true }, { terminate: true });
+  return ok(
+    lines.join("\n"),
+    { ...r.data, pending_learn: r.data.pending_learn },
+    { terminate: true },
+  );
 }
 
 /**
@@ -208,7 +231,7 @@ export function registerLand(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerCommand("land", {
+  registerPerkCommand(pi, "land", {
     description: "Merge the active plan's PR and set pending-learn (submit → land).",
     handler: async (_args, ctx) => {
       const result = await landPr(pi, ctx);