supipowers 2.0.2 → 2.2.0

package/src/harness/pr-comment/baseline.ts

@@ -0,0 +1,105 @@
+/**
+ * Load the trend baseline from `score-history.jsonl`.
+ *
+ * The validate stage appends one record per run to this file. We split that history
+ * into:
+ *   - `previousScore`: the most recent prior entry (so we can compute a delta vs the
+ *     score we just wrote), or null when there is nothing to compare against;
+ *   - `trend`: the last N entries oldest-first, for the inline sparkline.
+ *
+ * Score-history v1 records are `{ recordedAt, sessionId, strict, lenient }` (see
+ * `src/harness/stages/validate.ts`). Per-dimension breakdowns are NOT persisted, so we
+ * surface them as `undefined` and the renderer shows "—" for the dimension Δ column.
+ */
+
+import type { PlatformPaths } from "../../platform/types.js";
+import type { UltraPlanStorageResult } from "../../types.js";
+import { readJsonl } from "../storage.js";
+import { getHarnessScoreHistoryPath } from "../project-paths.js";
+import type { PrCommentPreviousScore, PrCommentTrendPoint } from "./types.js";
+
+/** Raw score-history record as written by Validate. */
+interface ScoreHistoryRecord {
+  recordedAt: string;
+  sessionId: string;
+  strict: number;
+  lenient: number;
+}
+
+export interface Baseline {
+  /** Most recent prior entry. null when history is empty or has only one record. */
+  previousScore: PrCommentPreviousScore | null;
+  /** Last `limit` entries, oldest first. Empty when no history. */
+  trend: readonly PrCommentTrendPoint[];
+}
+
+const DEFAULT_TREND_LIMIT = 5;
+
+/**
+ * Read score-history.jsonl and split it into (previous, trend).
+ *
+ * `currentSessionId` is what just ran — we drop ALL trailing records that match it so we
+ * never compare a score against itself, even when validate is re-run for the same session.
+ *
+ * Returns an empty baseline (`previousScore: null`, `trend: []`) when the history file is
+ * missing or unreadable. We deliberately swallow IO errors here: a corrupted history file
+ * should degrade gracefully to "no baseline" rather than block PR comment generation.
+ */
+export function loadBaseline(
+  paths: PlatformPaths,
+  cwd: string,
+  options: { currentSessionId?: string; limit?: number } = {},
+): Baseline {
+  const limit = options.limit ?? DEFAULT_TREND_LIMIT;
+  const result: UltraPlanStorageResult<ScoreHistoryRecord[]> = readJsonl<ScoreHistoryRecord>(
+    getHarnessScoreHistoryPath(paths, cwd),
+  );
+  if (!result.ok) {
+    return { previousScore: null, trend: [] };
+  }
+  const records = result.value.filter((record) => isWellFormed(record));
+
+  // Strip the trailing run(s) that belong to the current session so we compare against the
+  // PRIOR run. When currentSessionId is omitted (local dry-run with no session context),
+  // we treat the most recent record as the baseline.
+  let priorEnd = records.length;
+  if (options.currentSessionId) {
+    while (priorEnd > 0 && records[priorEnd - 1].sessionId === options.currentSessionId) {
+      priorEnd -= 1;
+    }
+  }
+
+  const previousRecord = priorEnd > 0 ? records[priorEnd - 1] : null;
+  const previousScore: PrCommentPreviousScore | null = previousRecord
+    ? {
+        recordedAt: previousRecord.recordedAt,
+        strict: previousRecord.strict,
+        lenient: previousRecord.lenient,
+      }
+    : null;
+
+  // Trend is the last `limit` records oldest-first. We include the current run so the
+  // sparkline ends with the just-computed score; the renderer can choose whether to
+  // highlight it.
+  const trendSlice = records.slice(Math.max(0, records.length - limit));
+  const trend: PrCommentTrendPoint[] = trendSlice.map((record) => ({
+    ts: record.recordedAt,
+    strict: record.strict,
+    lenient: record.lenient,
+  }));
+
+  return { previousScore, trend };
+}
+
+function isWellFormed(record: unknown): record is ScoreHistoryRecord {
+  if (record === null || typeof record !== "object") return false;
+  const r = record as Record<string, unknown>;
+  return (
+    typeof r.recordedAt === "string" &&
+    typeof r.sessionId === "string" &&
+    typeof r.strict === "number" &&
+    typeof r.lenient === "number" &&
+    Number.isFinite(r.strict) &&
+    Number.isFinite(r.lenient)
+  );
+}

package/src/harness/pr-comment/ci-env.ts

@@ -0,0 +1,120 @@
+/**
+ * GitHub Actions environment detection for the PR comment subcommand.
+ *
+ * The harness PR comment workflow runs in two contexts:
+ *   - inside GitHub Actions on a `pull_request` event (real CI run), and
+ *   - locally for `--dry-run` previews and ad-hoc testing.
+ *
+ * This module owns the detection of the former. It deliberately does no IO except reading
+ * a single event JSON file when `GITHUB_EVENT_PATH` is provided.
+ */
+
+import * as fs from "node:fs";
+
+export interface CiContext {
+  /** "owner/repo" — extracted from GITHUB_REPOSITORY or supplied via flag. */
+  repo: string;
+  /** PR number — from the event payload or the --pr flag. */
+  prNumber: number;
+  /** Optional run URL, used in the comment footer. */
+  runUrl?: string;
+  /** Optional base ref, e.g. "main@a1b2c3d", used in the summary line. */
+  baseRef?: string;
+}
+
+/** Manual overrides parsed from CLI flags; flag values win over env. */
+export interface CiContextOverrides {
+  repo?: string;
+  prNumber?: number;
+}
+
+/**
+ * Detect the CI context from environment variables, applying optional overrides on top.
+ *
+ * Returns null when neither the env nor the overrides produce a complete `{repo, prNumber}`
+ * pair — that's how the handler decides to fall back to the workflow summary.
+ */
+export function detectCiContext(
+  env: NodeJS.ProcessEnv = process.env,
+  overrides: CiContextOverrides = {},
+): CiContext | null {
+  const repo = overrides.repo ?? env.GITHUB_REPOSITORY;
+  if (!repo || !/^[^/\s]+\/[^/\s]+$/.test(repo)) {
+    if (!repo) return null;
+    // Malformed repo string (e.g. missing slash). Return null rather than corrupting URLs.
+    return null;
+  }
+
+  let prNumber = overrides.prNumber;
+  let baseRef: string | undefined;
+  if (prNumber === undefined) {
+    const fromEvent = readPullRequestFromEvent(env);
+    if (fromEvent) {
+      prNumber = fromEvent.prNumber;
+      baseRef = fromEvent.baseRef;
+    }
+  }
+  if (prNumber === undefined || !Number.isFinite(prNumber) || prNumber <= 0) {
+    return null;
+  }
+
+  const runUrl = buildRunUrl(env, repo);
+  const ctx: CiContext = { repo, prNumber };
+  if (runUrl) ctx.runUrl = runUrl;
+  if (baseRef) ctx.baseRef = baseRef;
+  return ctx;
+}
+
+interface PullRequestEventFields {
+  prNumber: number;
+  baseRef?: string;
+}
+
+function readPullRequestFromEvent(env: NodeJS.ProcessEnv): PullRequestEventFields | null {
+  const eventPath = env.GITHUB_EVENT_PATH;
+  if (!eventPath) return null;
+  let raw: string;
+  try {
+    raw = fs.readFileSync(eventPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object") return null;
+  const obj = parsed as Record<string, unknown>;
+  const pr = obj.pull_request;
+  if (pr === null || typeof pr !== "object") {
+    // Some events (issue_comment on a PR) carry `issue.pull_request` instead. We only
+    // support the `pull_request` event in v1; everything else returns null.
+    return null;
+  }
+  const prRecord = pr as Record<string, unknown>;
+  const number = prRecord.number;
+  if (typeof number !== "number" || !Number.isFinite(number)) return null;
+
+  let baseRef: string | undefined;
+  const base = prRecord.base;
+  if (base && typeof base === "object") {
+    const baseRecord = base as Record<string, unknown>;
+    const ref = baseRecord.ref;
+    const sha = baseRecord.sha;
+    if (typeof ref === "string" && typeof sha === "string") {
+      baseRef = `${ref}@${sha.slice(0, 7)}`;
+    } else if (typeof ref === "string") {
+      baseRef = ref;
+    }
+  }
+  return { prNumber: number, baseRef };
+}
+
+function buildRunUrl(env: NodeJS.ProcessEnv, repo: string): string | undefined {
+  const server = env.GITHUB_SERVER_URL;
+  const runId = env.GITHUB_RUN_ID;
+  if (!server || !runId) return undefined;
+  return `${server}/${repo}/actions/runs/${runId}`;
+}

package/src/harness/pr-comment/gh-poster.ts

@@ -0,0 +1,227 @@
+/**
+ * `gh` CLI wrapper for the harness PR sticky comment.
+ *
+ * Fail-open by design: every failure path returns a typed `PostOutcome` instead of
+ * throwing, so the caller can decide whether to surface a workflow-summary fallback. The
+ * pipeline never blocks on PR-comment posting.
+ *
+ * Pattern mirrors `src/fix-pr/fetch-comments.ts` and `src/release/channels/github.ts`:
+ * we never construct an Octokit client; `platform.exec("gh", [...])` is the only
+ * dependency.
+ */
+
+import type { Platform } from "../../platform/types.js";
+import { parseMarker, STICKY_MARKER_PREFIX } from "./status.js";
+import type { PrCommentStatus } from "./types.js";
+
+/** Outcome of an upsert attempt. */
+export type PostOutcome =
+  | { kind: "created"; commentId: number }
+  | { kind: "updated"; commentId: number }
+  | { kind: "unchanged"; commentId: number; reason: "status-unchanged" }
+  | { kind: "skipped"; reason: "no-auth" | "no-cli" | "no-pr-env" }
+  | { kind: "failed"; reason: string };
+
+export interface PostStickyOptions {
+  repo: string;
+  prNumber: number;
+  cwd: string;
+  body: string;
+  mode: "every-push" | "on-status-change";
+  currentStatus: PrCommentStatus;
+}
+
+/**
+ * Idempotent upsert of the sticky comment.
+ *
+ *  1. Verify `gh` is installed and authenticated.
+ *  2. List PR comments; find the first whose body starts with the harness marker prefix.
+ *  3. When `mode === "on-status-change"`, parse the previous status; bail with `unchanged`
+ *     when it matches `currentStatus`.
+ *  4. PATCH the existing comment, or POST a new one when nothing matched.
+ */
+export async function postStickyComment(
+  platform: Platform,
+  options: PostStickyOptions,
+): Promise<PostOutcome> {
+  const { repo, prNumber, cwd, body, mode, currentStatus } = options;
+
+  const auth = await checkAuth(platform, cwd);
+  if (auth.kind !== "ok") return auth;
+
+  const existing = await findStickyComment(platform, repo, prNumber, cwd);
+  if (existing.kind === "failed") return existing;
+
+  if (existing.kind === "found") {
+    if (mode === "on-status-change") {
+      const parsed = parseMarker(existing.body);
+      if (parsed && parsed.status === currentStatus) {
+        return { kind: "unchanged", commentId: existing.id, reason: "status-unchanged" };
+      }
+    }
+    const patched = await patchComment(platform, repo, existing.id, body, cwd);
+    return patched;
+  }
+
+  // No sticky yet — create one.
+  return createComment(platform, repo, prNumber, body, cwd);
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+async function checkAuth(
+  platform: Platform,
+  cwd: string,
+): Promise<{ kind: "ok" } | { kind: "skipped"; reason: "no-auth" | "no-cli" }> {
+  let result: Awaited<ReturnType<Platform["exec"]>>;
+  try {
+    result = await platform.exec("gh", ["auth", "status"], { cwd });
+  } catch {
+    // ENOENT (gh missing) or other spawn-time failure — treat as no-cli.
+    return { kind: "skipped", reason: "no-cli" };
+  }
+  if (result.code === 0) return { kind: "ok" };
+  return { kind: "skipped", reason: "no-auth" };
+}
+
+type FindResult =
+  | { kind: "found"; id: number; body: string }
+  | { kind: "not-found" }
+  | { kind: "failed"; reason: string };
+
+async function findStickyComment(
+  platform: Platform,
+  repo: string,
+  prNumber: number,
+  cwd: string,
+): Promise<FindResult> {
+  let result: Awaited<ReturnType<Platform["exec"]>>;
+  try {
+    result = await platform.exec(
+      "gh",
+      [
+        "api",
+        "--paginate",
+        `repos/${repo}/issues/${prNumber}/comments`,
+        "--jq",
+        ".[] | {id, body}",
+      ],
+      { cwd },
+    );
+  } catch (error) {
+    return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (result.code !== 0) {
+    return {
+      kind: "failed",
+      reason: result.stderr.trim() || `gh api exited with code ${result.code}`,
+    };
+  }
+  // `--jq '.[] | {id, body}'` emits one JSON object per line (NOT a JSON array). Crucially,
+  // bodies may contain newlines — the `--jq` filter on a *list* shouldn't, because jq's
+  // default emits compact JSON for objects, but we still parse defensively.
+  for (const line of splitJsonObjects(result.stdout)) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (parsed === null || typeof parsed !== "object") continue;
+    const obj = parsed as { id?: unknown; body?: unknown };
+    if (typeof obj.id !== "number" || typeof obj.body !== "string") continue;
+    if (obj.body.startsWith(STICKY_MARKER_PREFIX)) {
+      return { kind: "found", id: obj.id, body: obj.body };
+    }
+  }
+  return { kind: "not-found" };
+}
+
+async function createComment(
+  platform: Platform,
+  repo: string,
+  prNumber: number,
+  body: string,
+  cwd: string,
+): Promise<PostOutcome> {
+  let result: Awaited<ReturnType<Platform["exec"]>>;
+  try {
+    result = await platform.exec(
+      "gh",
+      [
+        "api",
+        "-X", "POST",
+        `repos/${repo}/issues/${prNumber}/comments`,
+        "-f", `body=${body}`,
+      ],
+      { cwd },
+    );
+  } catch (error) {
+    return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (result.code !== 0) {
+    return { kind: "failed", reason: result.stderr.trim() || `gh api POST exited with code ${result.code}` };
+  }
+  const id = extractCommentId(result.stdout);
+  if (id === null) {
+    return { kind: "failed", reason: "gh api POST succeeded but response is missing comment id" };
+  }
+  return { kind: "created", commentId: id };
+}
+
+async function patchComment(
+  platform: Platform,
+  repo: string,
+  commentId: number,
+  body: string,
+  cwd: string,
+): Promise<PostOutcome> {
+  let result: Awaited<ReturnType<Platform["exec"]>>;
+  try {
+    result = await platform.exec(
+      "gh",
+      [
+        "api",
+        "-X", "PATCH",
+        `repos/${repo}/issues/comments/${commentId}`,
+        "-f", `body=${body}`,
+      ],
+      { cwd },
+    );
+  } catch (error) {
+    return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (result.code !== 0) {
+    return { kind: "failed", reason: result.stderr.trim() || `gh api PATCH exited with code ${result.code}` };
+  }
+  return { kind: "updated", commentId };
+}
+
+function extractCommentId(stdout: string): number | null {
+  try {
+    const parsed = JSON.parse(stdout);
+    if (parsed && typeof parsed === "object" && typeof (parsed as { id?: unknown }).id === "number") {
+      return (parsed as { id: number }).id;
+    }
+  } catch {
+    // Fall through to regex scan; gh api can be configured with --jq for partial outputs.
+  }
+  const match = /"id"\s*:\s*(\d+)/.exec(stdout);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Split jq stream output into individual JSON object strings. jq's stream mode separates
+ * objects with a single newline, but body fields may contain unescaped newlines when the
+ * comment uses raw markdown. We rely on `JSON.parse` to validate each candidate and fall
+ * back to a line-based split.
+ */
+function splitJsonObjects(raw: string): string[] {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return [];
+  // Fast path: each line is its own object (the common case for `--jq '.[] | {id, body}'`).
+  const lines = trimmed.split(/\n(?=\{)/).map((s) => s.trim()).filter((s) => s.length > 0);
+  return lines;
+}

package/src/harness/pr-comment/handler.ts

@@ -0,0 +1,198 @@
+/**
+ * Handler for `/supi:harness pr-comment`.
+ *
+ * Resolves a validate report → baseline → CI context → renders → posts (or writes a
+ * step-summary fallback). Always notifies the UI with a one-line outcome; never throws.
+ *
+ * Flags (parsed via `parseFlags`):
+ *   --dry-run                  Print the body to stdout/UI, no `gh` call, no env required.
+ *   --pr=<n>                   Override PR number (otherwise read from env).
+ *   --repo=<owner>/<repo>      Override repo (otherwise read from GITHUB_REPOSITORY).
+ *   --session=<id>             Override which session's validate report we render.
+ *   --mode=every-push|on-status-change
+ *                              Override the config-supplied posting cadence.
+ */
+
+import type { Platform } from "../../platform/types.js";
+import type { HarnessCommandContext } from "../command.js";
+import {
+  listHarnessSessions,
+  loadHarnessDesignSpecJson,
+  loadHarnessValidateReport,
+} from "../storage.js";
+import { renderHarnessPrComment } from "./render.js";
+import { loadBaseline } from "./baseline.js";
+import { detectCiContext } from "./ci-env.js";
+import { postStickyComment } from "./gh-poster.js";
+import { STICKY_MARKER_PREFIX } from "./status.js";
+import { writeStepSummary } from "./workflow-summary.js";
+
+interface ParsedFlags {
+  dryRun: boolean;
+  prNumber?: number;
+  repo?: string;
+  sessionId?: string;
+  mode?: "every-push" | "on-status-change";
+}
+
+/** Default floor used when no design spec exists yet (purely defensive). */
+const DEFAULT_SCORE_FLOOR = { strict: 75, lenient: 90 } as const;
+
+/** Default mode when neither flag nor config supplies one. */
+const DEFAULT_MODE = "every-push" satisfies NonNullable<ParsedFlags["mode"]>;
+
+export async function handlePrComment(
+  platform: Platform,
+  ctx: HarnessCommandContext,
+  args: readonly string[],
+): Promise<void> {
+  const flags = parseFlags(args);
+
+  // 1. Pick the session.
+  const sessionId = flags.sessionId ?? listHarnessSessions(platform.paths, ctx.cwd)[0];
+  if (!sessionId) {
+    ctx.ui.notify(
+      "No harness session found. Run `/supi:harness validate` first or pass --session=<id>.",
+      "error",
+    );
+    return;
+  }
+
+  // 2. Load the validate report.
+  const reportResult = loadHarnessValidateReport(platform.paths, ctx.cwd, sessionId);
+  if (!reportResult.ok) {
+    ctx.ui.notify(
+      `Cannot read validate report for session ${sessionId}: ${reportResult.error.message}`,
+      "error",
+    );
+    return;
+  }
+  const report = reportResult.value;
+
+  // 3. Load baseline + score floor + config-supplied mode from the design spec.
+  const baseline = loadBaseline(platform.paths, ctx.cwd, { currentSessionId: sessionId });
+  const designSpec = loadHarnessDesignSpecJson(platform.paths, ctx.cwd, sessionId);
+  const scoreFloor = designSpec.ok ? designSpec.value.antiSlop.hooks.score_floor : DEFAULT_SCORE_FLOOR;
+  const configMode = designSpec.ok ? designSpec.value.ci.prComment?.mode : undefined;
+  const enabled = designSpec.ok ? designSpec.value.ci.prComment?.enabled !== false : true;
+  if (!enabled && !flags.dryRun) {
+    ctx.ui.notify(
+      "PR comments are disabled in this harness design spec (ci.prComment.enabled=false).",
+      "info",
+    );
+    return;
+  }
+
+  const mode = flags.mode ?? configMode ?? DEFAULT_MODE;
+
+  // 4. CI context (flag overrides > env). For --dry-run we tolerate a missing context.
+  const ciContext = detectCiContext(process.env, {
+    repo: flags.repo,
+    prNumber: flags.prNumber,
+  });
+
+  // 5. Render.
+  const rendered = renderHarnessPrComment({
+    report,
+    previousScore: baseline.previousScore,
+    trend: baseline.trend,
+    scoreFloor: { strict: scoreFloor.strict, lenient: scoreFloor.lenient },
+    sessionId,
+    generatedAt: new Date().toISOString(),
+    runUrl: ciContext?.runUrl,
+    baseRef: ciContext?.baseRef,
+  });
+
+  // 6. Branch on transport.
+  if (flags.dryRun) {
+    ctx.ui.notify(`PR comment preview (status=${rendered.status}):\n\n${rendered.body}`, "info");
+    return;
+  }
+
+  if (!ciContext) {
+    // No PR context — fall back to the step summary unconditionally. This is the
+    // expected path on `push` events that should not post a PR comment.
+    const summary = writeStepSummary(rendered.body);
+    if (summary.ok && summary.path) {
+      ctx.ui.notify(`No PR context; wrote summary to ${summary.path}.`, "info");
+    } else if (summary.ok) {
+      ctx.ui.notify("Skipped: no PR context and no GITHUB_STEP_SUMMARY available.", "info");
+    } else {
+      ctx.ui.notify(`Skipped: ${summary.reason ?? "no PR context"}`, "warning");
+    }
+    return;
+  }
+
+  const outcome = await postStickyComment(platform, {
+    repo: ciContext.repo,
+    prNumber: ciContext.prNumber,
+    cwd: ctx.cwd,
+    body: rendered.body,
+    mode,
+    currentStatus: rendered.status,
+  });
+
+  switch (outcome.kind) {
+    case "created":
+      ctx.ui.notify(`PR comment created (id=${outcome.commentId}).`, "info");
+      return;
+    case "updated":
+      ctx.ui.notify(`PR comment updated (id=${outcome.commentId}).`, "info");
+      return;
+    case "unchanged":
+      ctx.ui.notify(`PR comment unchanged (status still ${rendered.status}, id=${outcome.commentId}).`, "info");
+      return;
+    case "skipped":
+    case "failed": {
+      // Fail-open: write the body to the workflow summary so the run page still has the
+      // report, then notify with a warning (not an error — this is auxiliary signal).
+      const summary = writeStepSummary(rendered.body);
+      const fallback = summary.ok && summary.path ? ` (summary at ${summary.path})` : "";
+      const reason = outcome.kind === "failed" ? outcome.reason : outcome.reason;
+      ctx.ui.notify(`PR comment ${outcome.kind}: ${reason}.${fallback}`, "warning");
+      return;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Flag parsing
+// ---------------------------------------------------------------------------
+
+function parseFlags(args: readonly string[]): ParsedFlags {
+  const flags: ParsedFlags = { dryRun: false };
+  for (const arg of args) {
+    if (arg === "--dry-run") {
+      flags.dryRun = true;
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    if (eq === -1) continue;
+    const name = arg.slice(0, eq);
+    const value = arg.slice(eq + 1);
+    switch (name) {
+      case "--pr": {
+        const n = Number(value);
+        if (Number.isFinite(n) && n > 0) flags.prNumber = n;
+        break;
+      }
+      case "--repo":
+        flags.repo = value;
+        break;
+      case "--session":
+        flags.sessionId = value;
+        break;
+      case "--mode":
+        if (value === "every-push" || value === "on-status-change") flags.mode = value;
+        break;
+      default:
+        // Unknown flag — ignored. The dispatcher already filters by subcommand name.
+        break;
+    }
+  }
+  return flags;
+}
+
+// Suppress unused-import warning for STICKY_MARKER_PREFIX — re-exported indirectly for
+// downstream consumers that import from this module.
+void STICKY_MARKER_PREFIX;