@dev-loops/core 0.1.0

package/src/github/review-threads.mjs

@@ -0,0 +1,343 @@
+import { readFile } from "node:fs/promises";
+
+function normalizeId(value, fallback) {
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value.trim();
+  }
+
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+
+  return fallback;
+}
+
+function normalizeBody(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+
+  return value.trim();
+}
+
+function normalizeAuthor(author) {
+  if (!author || typeof author !== "object") {
+    return {
+      login: "",
+      type: "System",
+      isBot: false,
+    };
+  }
+
+  const login = typeof author.login === "string" ? author.login.trim() : "";
+  const type = typeof author.__typename === "string"
+    ? author.__typename.trim()
+    : typeof author.type === "string"
+      ? author.type.trim()
+      : "User";
+
+  return {
+    login,
+    type,
+    isBot: Boolean(author.isBot) || type === "Bot" || login.endsWith("[bot]"),
+  };
+}
+
+function extractRawComments(thread) {
+  if (Array.isArray(thread?.comments)) {
+    return thread.comments;
+  }
+
+  if (Array.isArray(thread?.comments?.nodes)) {
+    return thread.comments.nodes;
+  }
+
+  return [];
+}
+
+function extractRawThreads(payload) {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  const candidates = [
+    payload?.threads,
+    payload?.reviewThreads,
+    payload?.reviewThreads?.nodes,
+    payload?.data?.repository?.pullRequest?.reviewThreads?.nodes,
+    payload?.data?.node?.reviewThreads?.nodes,
+  ];
+
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error("Could not find review threads in payload");
+}
+
+function compareIds(left, right) {
+  return left.localeCompare(right, undefined, { numeric: true });
+}
+
+export function isActionableComment(comment) {
+  const body = normalizeBody(comment?.body ?? comment?.bodyText ?? comment?.bodyHTML ?? "");
+  const author = normalizeAuthor(comment?.author);
+
+  return body.length > 0 && author.login.length > 0 && author.type !== "System" && !author.isBot;
+}
+
+export function isActionableThread(thread) {
+  if (Boolean(thread?.isResolved)) {
+    return false;
+  }
+
+  return extractRawComments(thread).some((comment) => isActionableComment(comment));
+}
+
+function normalizeComment(comment, threadId, index, { isResolved = false } = {}) {
+  const author = normalizeAuthor(comment?.author);
+  const body = normalizeBody(comment?.body ?? comment?.bodyText ?? comment?.bodyHTML ?? "");
+  const databaseId = comment?.databaseId === null || comment?.databaseId === undefined
+    ? null
+    : normalizeId(comment.databaseId, null);
+
+  return {
+    id: normalizeId(comment?.id ?? comment?.databaseId, `${threadId}:comment-${index + 1}`),
+    databaseId,
+    threadId,
+    author,
+    body,
+    isActionable: !isResolved && body.length > 0 && author.login.length > 0 && author.type !== "System" && !author.isBot,
+  };
+}
+
+export function parseReviewThreads(payload) {
+  const rawThreads = extractRawThreads(payload);
+  const comments = [];
+  const threads = rawThreads.map((thread, threadIndex) => {
+    const threadId = normalizeId(thread?.id ?? thread?.databaseId, `thread-${threadIndex + 1}`);
+    const isResolved = Boolean(thread?.isResolved);
+    const normalizedComments = extractRawComments(thread)
+      .map((comment, commentIndex) => normalizeComment(comment, threadId, commentIndex, { isResolved }))
+      .sort((left, right) => compareIds(left.id, right.id));
+
+    comments.push(...normalizedComments);
+    const commentIds = normalizedComments.map((comment) => comment.id);
+    const commentDatabaseIds = normalizedComments
+      .map((comment) => comment.databaseId)
+      .filter((value) => value !== null);
+    const actionableComments = isResolved
+      ? []
+      : normalizedComments.filter((comment) => comment.isActionable);
+    const actionableCommentIds = actionableComments.map((comment) => comment.id);
+    const actionableCommentDatabaseIds = actionableComments
+      .map((comment) => comment.databaseId)
+      .filter((value) => value !== null);
+
+    return {
+      id: threadId,
+      isResolved,
+      isActionable: actionableCommentIds.length > 0,
+      commentIds,
+      commentDatabaseIds,
+      actionableCommentIds,
+      actionableCommentDatabaseIds,
+    };
+  }).sort((left, right) => compareIds(left.id, right.id));
+
+  const sortedComments = comments.sort((left, right) => {
+    const threadOrder = compareIds(left.threadId, right.threadId);
+    return threadOrder === 0 ? compareIds(left.id, right.id) : threadOrder;
+  });
+
+  return {
+    summary: {
+      totalThreads: threads.length,
+      unresolvedThreads: threads.filter((thread) => !thread.isResolved).length,
+      actionableThreads: threads.filter((thread) => thread.isActionable).length,
+      actionableComments: threads.reduce((count, thread) => count + thread.actionableCommentIds.length, 0),
+    },
+    threads,
+    comments: sortedComments,
+  };
+}
+
+// ── Signal classification heuristics ──────────────────────────────────────
+
+const HIGH_SIGNAL_PATTERNS = [
+  /\bbug\b/i, /\bcrash\b/i, /\bsecurity\b/i, /\bvulnerab/i,
+  /\bcontract\b/i, /\bbroken\b/i, /\bincorrect\b/i, /\bwrong\b/i,
+  /\bsilent(?:ly)?\b/i, /\bdata.?loss\b/i, /\brace.?condition\b/i,
+  /\bmemory.?leak\b/i, /\binfinite.?loop\b/i, /\bdeadlock\b/i,
+  /\bexception\b/i, /\bfatal\b/i, /\bcorrupt/i, /\bdiverg/i,
+  /\binconsisten/i, /\bregression\b/i, /\blost\b/i, /\bmissing\b/i,
+];
+
+const MID_SIGNAL_PATTERNS = [
+  /\brefactor\b/i, /\brestructur/i, /\breorganiz/i,
+  /\bperform(?:ance)?\b/i, /\barchitect/i, /\bdesign\b/i,
+  /\b(?:should\s+)?consider\b/i, /\b(?:\w+\s+)?maybe\b/i,
+  /\balternative\b/i, /\bimprove(?:ment)?\b/i, /\bextract\b/i,
+  /\babstract(?:ion)?\b/i, /\bdry\b/i, /\bsimplif/i,
+  /\bduplicat/i, /\bunnecessary/i, /\bover.engineer/i,
+  /\bcould\b/i, /\bwould\b/i, /\bsuggest/i, /\brecommend/i,
+  /\bprefer\b/i, /\bbetter\b/i, /\bclean(?:er)?\b/i,
+  /\breus(?:e|able)\b/i, /\btestable/i, /\bconsistent/i,
+];
+
+/**
+ * Classify a single comment by signal level using heuristic keyword matching.
+ * No AI or API confidence data is used.
+ *
+ * @param {{ body?: string|null }} comment
+ * @returns {"high"|"mid"|"low"}
+ */
+export function classifyCommentSignal(comment) {
+  const body = (typeof comment?.body === "string" ? comment.body : "").trim();
+  if (body.length === 0) return "low";
+
+  for (const pattern of HIGH_SIGNAL_PATTERNS) {
+    if (pattern.test(body)) return "high";
+  }
+  for (const pattern of MID_SIGNAL_PATTERNS) {
+    if (pattern.test(body)) return "mid";
+  }
+  return "low";
+}
+
+/**
+ * Classify a review thread by its highest comment signal level.
+ *
+ * @param {{ comments: Array<{ body?: string|null }> }} thread
+ * @returns {"high"|"mid"|"low"}
+ */
+export function classifyThreadSignal(thread) {
+  const comments = Array.isArray(thread?.comments) ? thread.comments : [];
+  let maxSignal = "low";
+  for (const comment of comments) {
+    const signal = classifyCommentSignal(comment);
+    if (signal === "high") return "high";
+    if (signal === "mid") maxSignal = "mid";
+  }
+  return maxSignal;
+}
+
+/**
+ * Determine the maximum signal level across all Copilot-authored threads.
+ *
+ * Filters threads to those containing at least one Copilot-authored comment,
+ * then classifies the signal level using all comments in those threads
+ * (including human replies in Copilot threads, which may clarify severity).
+ * Returns null if no Copilot-authored threads exist.
+ *
+ * @param {{ threads: Array<object>, comments: Array<object> }} parsedResult — output of parseReviewThreads()
+ * @param {(login: string) => boolean} isCopilotLoginFn — predicate for Copilot authors
+ * @returns {"high"|"mid"|"low"|null}
+ */
+export function classifyReviewThreadsSignal(parsedResult, isCopilotLoginFn) {
+  const threads = Array.isArray(parsedResult?.threads) ? parsedResult.threads : [];
+  const flatComments = Array.isArray(parsedResult?.comments) ? parsedResult.comments : [];
+  if (flatComments.length === 0) return null;
+
+  // Group comments by threadId
+  const commentsByThread = new Map();
+  for (const comment of flatComments) {
+    const tid = comment.threadId ?? "unknown";
+    if (!commentsByThread.has(tid)) commentsByThread.set(tid, []);
+    commentsByThread.get(tid).push(comment);
+  }
+
+  let maxSignal = null;
+  for (const thread of threads) {
+    const threadComments = commentsByThread.get(thread.id) ?? [];
+    const hasCopilotComment = threadComments.some(
+      (c) => typeof c?.author?.login === "string" && isCopilotLoginFn(c.author.login),
+    );
+    if (!hasCopilotComment) continue;
+    const signal = classifyThreadSignal({ comments: threadComments });
+    if (signal === "high") return "high";
+    if (maxSignal === null || (signal === "mid" && maxSignal === "low")) {
+      maxSignal = signal;
+    }
+  }
+  return maxSignal;
+}
+
+
+function requireOptionValue(args, flag) {
+  const value = args.shift();
+
+  if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+
+  return value;
+}
+
+export function parseCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    inputPath: undefined,
+  };
+
+  while (args.length > 0) {
+    const token = args.shift();
+
+    if (token === "--input") {
+      options.inputPath = requireOptionValue(args, "--input");
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return options;
+}
+
+export async function readInput({ inputPath, stdin = process.stdin } = {}) {
+  if (inputPath) {
+    return readFile(inputPath, "utf8");
+  }
+
+  let input = "";
+  for await (const chunk of stdin) {
+    input += chunk;
+  }
+
+  if (input.trim().length === 0) {
+    throw new Error("Expected review-thread JSON via --input <path> or stdin");
+  }
+
+  return input;
+}
+
+export function parseJsonText(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error("Invalid JSON input");
+  }
+}
+
+export function formatCliError(error) {
+  const payload = { ok: false, error: error instanceof Error ? error.message : String(error) };
+  if (error instanceof Error && typeof error.usage === "string") {
+    payload.usage = error.usage;
+  }
+  return JSON.stringify(payload);
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  {
+    stdin = process.stdin,
+    stdout = process.stdout,
+  } = {},
+) {
+  const options = parseCliArgs(argv);
+  const text = await readInput({ inputPath: options.inputPath, stdin });
+  const result = parseReviewThreads(parseJsonText(text));
+  stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
+}

package/src/harness/adapter.mjs

@@ -0,0 +1,57 @@
+/**
+ * Harness adapter interface.
+ *
+ * Abstracts runtime concerns that vary between agent harnesses (Pi, Claude,
+ * local CLI, test) so the dev-loop dispatch and handoff path stays harness-agnostic.
+ *
+ * This slice is intentionally minimal. Add methods only when the dispatch/handoff
+ * path needs them; do not turn the adapter into a generic process wrapper.
+ *
+ * @typedef {Object} HarnessAdapter
+ * @property {() => string} getCwd - Current working directory for the active session.
+ * @property {() => NodeJS.ProcessEnv} getEnv - Active environment variables.
+ * @property {() => boolean} isInteractive - Whether the session is interactive (vs batch/automated).
+ * @property {() => boolean} isInsidePi - Whether the session is running inside the Pi agent harness.
+ * @property {() => string} getRepoRoot - Best-effort repository root; falls back to cwd.
+ */
+
+const REQUIRED_METHODS = ["getCwd", "getEnv", "isInteractive", "isInsidePi", "getRepoRoot"];
+
+/**
+ * Validate and freeze a harness-adapter implementation.
+ *
+ * @param {Partial<HarnessAdapter>} impl
+ * @returns {HarnessAdapter}
+ */
+export function createHarnessAdapter(impl) {
+  if (!impl || typeof impl !== "object") {
+    throw new TypeError("createHarnessAdapter: impl must be an object");
+  }
+
+  for (const method of REQUIRED_METHODS) {
+    if (typeof impl[method] !== "function") {
+      throw new TypeError(`createHarnessAdapter: missing required method "${method}"`);
+    }
+  }
+
+  return Object.freeze({
+    getCwd: impl.getCwd,
+    getEnv: impl.getEnv,
+    isInteractive: impl.isInteractive,
+    isInsidePi: impl.isInsidePi,
+    getRepoRoot: impl.getRepoRoot,
+  });
+}
+
+/**
+ * Type guard for adapter values.
+ *
+ * @param {*} value
+ * @returns {value is HarnessAdapter}
+ */
+export function isHarnessAdapter(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  return REQUIRED_METHODS.every((method) => typeof value[method] === "function");
+}

package/src/harness/index.mjs

@@ -0,0 +1,3 @@
+export { createHarnessAdapter, isHarnessAdapter } from "./adapter.mjs";
+export { createPiAdapter } from "./pi-adapter.mjs";
+export { createNoopAdapter } from "./noop-adapter.mjs";

package/src/harness/noop-adapter.mjs

@@ -0,0 +1,22 @@
+import { createHarnessAdapter } from "./adapter.mjs";
+
+/**
+ * Create a minimal harness adapter for tests and fallback/CI/batch contexts.
+ *
+ * Defaults mirror the current process so swapping from the Pi adapter does not
+ * unexpectedly change behavior; callers can still pin cwd/env for determinism.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.cwd]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @returns {import("./adapter.mjs").HarnessAdapter}
+ */
+export function createNoopAdapter({ cwd = process.cwd(), env = process.env } = {}) {
+  return createHarnessAdapter({
+    getCwd: () => cwd,
+    getEnv: () => env,
+    isInteractive: () => false,
+    isInsidePi: () => false,
+    getRepoRoot: () => cwd,
+  });
+}

package/src/harness/pi-adapter.mjs

@@ -0,0 +1,47 @@
+import { execFileSync } from "node:child_process";
+import { createHarnessAdapter } from "./adapter.mjs";
+
+/**
+ * Create the concrete Pi harness adapter.
+ *
+ * This is the only active adapter for #765. Future harnesses (Claude, etc.)
+ * can implement the same interface without changing call sites.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.cwd] - Override cwd (default: process.cwd()).
+ * @param {NodeJS.ProcessEnv} [options.env] - Override env (default: process.env).
+ * @returns {import("./adapter.mjs").HarnessAdapter}
+ */
+export function createPiAdapter({ cwd = process.cwd(), env = process.env } = {}) {
+  function getRepoRoot() {
+    try {
+      return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        cwd,
+        env,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      return cwd;
+    }
+  }
+
+  function isInteractive() {
+    if (env.PI_INTERACTIVE === "0") return false;
+    if (env.PI_INTERACTIVE === "1") return true;
+    if (env.CI === "true" || env.CI === "1") return false;
+    return true;
+  }
+
+  function isInsidePi() {
+    return env.PI_SESSION === "1" || typeof globalThis.pi !== "undefined";
+  }
+
+  return createHarnessAdapter({
+    getCwd: () => cwd,
+    getEnv: () => env,
+    isInteractive,
+    isInsidePi,
+    getRepoRoot,
+  });
+}

package/src/loop/async-start-contract.mjs

@@ -0,0 +1,170 @@
+/**
+ * Async-start contract enforcement for the dev-loop startup path.
+ *
+ * This module enforces the requirement that dev-loop execution scripts
+ * (outer-loop, watch-cycle, etc.) must run within a visible Pi-managed async
+ * context rather than as detached local processes (nohup, disowned shell jobs,
+ * tmux/screen sessions, ad hoc while/sleep loops, etc.).
+ *
+ * The enforcement seam is a startup check that verifies the presence of a
+ * Pi async context marker. When the marker is absent, the check fails closed
+ * and returns a machine-readable rejection rather than silently proceeding.
+ *
+ * Pi-managed async context markers (required when workflow.asyncStartMode is
+ * `required`):
+ * - PI_SUBAGENT_RUN_ID env var (set by Pi subagent framework for inspectable async runs)
+ *
+ * Allowed modes:
+ * - workflow.asyncStartMode: required | allowed
+ * - Snapshot/test mode (when both --copilot-input and --reviewer-input are provided)
+ *   implicitly skips the check since no real async ownership is needed
+ *
+ * This module is intentionally pure and side-effect free.
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Environment variable names that indicate a Pi-managed async context. */
+export const PI_ASYNC_CONTEXT_MARKERS = Object.freeze([
+  "PI_SUBAGENT_RUN_ID",
+]);
+
+/** Supported workflow async-start modes. */
+export const ASYNC_START_MODE = Object.freeze({
+  REQUIRED: "required",
+  ALLOWED: "allowed",
+});
+
+/** Async-start validation result status values. */
+export const ASYNC_START_STATUS = Object.freeze({
+  /** A valid Pi-managed async context was detected. */
+  VALID: "valid",
+  /** The workflow explicitly allows non-async startup for this context. */
+  ALLOWED: "allowed",
+  /** The check was skipped because the caller is in snapshot/test mode. */
+  SNAPSHOT_MODE: "snapshot_mode",
+  /** No Pi-managed async context was detected; fail closed. */
+  REJECTED: "rejected",
+});
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that the current execution context is a visible Pi-managed async run.
+ *
+ * Returns a result object describing whether the check passed, was allowed by
+ * config, or was rejected. Callers should treat `rejected` as a hard stop.
+ *
+ * @param {object} params
+ * @param {Record<string, string|undefined>} [params.env] - Environment variables to inspect.
+ * @param {boolean} [params.isSnapshotMode] - True when running in snapshot/test input mode.
+ * @param {"required"|"allowed"} [params.asyncStartMode] - Settings-driven async-start mode.
+ * @returns {{ status: string, reason: string, detectedMarker: string|null }}
+ */
+export function validateAsyncStartContext({
+  env = process.env,
+  isSnapshotMode = false,
+  asyncStartMode = ASYNC_START_MODE.REQUIRED,
+} = {}) {
+  // Snapshot/test mode implicitly skips — no real async ownership needed
+  if (isSnapshotMode) {
+    return {
+      status: ASYNC_START_STATUS.SNAPSHOT_MODE,
+      reason: "Snapshot/test input mode; async-start check not required.",
+      detectedMarker: null,
+    };
+  }
+
+  if (
+    asyncStartMode !== ASYNC_START_MODE.REQUIRED &&
+    asyncStartMode !== ASYNC_START_MODE.ALLOWED
+  ) {
+    return {
+      status: ASYNC_START_STATUS.REJECTED,
+      reason:
+        `Unrecognized workflow.asyncStartMode value ${JSON.stringify(asyncStartMode)}. ` +
+        `Expected ${ASYNC_START_MODE.REQUIRED} or ${ASYNC_START_MODE.ALLOWED}.`,
+      detectedMarker: null,
+    };
+  }
+
+  // Check for any Pi-managed async context marker
+  for (const marker of PI_ASYNC_CONTEXT_MARKERS) {
+    const value = env[marker];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return {
+        status: ASYNC_START_STATUS.VALID,
+        reason: `Pi-managed async context detected via ${marker}.`,
+        detectedMarker: marker,
+      };
+    }
+  }
+
+  if (asyncStartMode === ASYNC_START_MODE.ALLOWED) {
+    return {
+      status: ASYNC_START_STATUS.ALLOWED,
+      reason: "Async-start check allowed by workflow.asyncStartMode=allowed.",
+      detectedMarker: null,
+    };
+  }
+
+  const sessionOnlyMarker =
+    (typeof env.PI_SESSION_ID === "string" && env.PI_SESSION_ID.trim().length > 0)
+      ? "PI_SESSION_ID"
+      : ((typeof env.PI_ASYNC_CONTEXT === "string" && env.PI_ASYNC_CONTEXT.trim().length > 0)
+          ? "PI_ASYNC_CONTEXT"
+          : null);
+  if (sessionOnlyMarker !== null) {
+    return {
+      status: ASYNC_START_STATUS.REJECTED,
+      reason:
+        `Detected ${sessionOnlyMarker}, but GitHub-first async-start requires a visible ` +
+        "Pi-managed subagent run id for inspectable startup/resume evidence. " +
+        "Set PI_SUBAGENT_RUN_ID to proceed. Any exception must come from repository-maintained workflow policy.",
+      detectedMarker: null,
+    };
+  }
+
+  if (env.PI_DEV_LOOP_DETACHED === "1") {
+    return {
+      status: ASYNC_START_STATUS.REJECTED,
+      reason:
+        "Detected detached local background execution; detached/local fallback is diagnostic-only " +
+        "and does not satisfy the async-start contract. Restart via Pi-managed async mode. " +
+        "Any relaxed posture must come from repository-maintained workflow policy.",
+      detectedMarker: null,
+    };
+  }
+
+  // No marker found — fail closed
+  return {
+    status: ASYNC_START_STATUS.REJECTED,
+    reason:
+      "No Pi-managed async context detected. " +
+      "The dev-loop must run within a visible Pi async subagent session, " +
+      "not as a detached local process. " +
+      `Set ${PI_ASYNC_CONTEXT_MARKERS[0]} to proceed. Repository-maintained workflow policy controls any exceptions.`,
+    detectedMarker: null,
+  };
+}
+
+/**
+ * Build a fail-closed error payload for rejected async-start validation.
+ *
+ * This returns the same JSON error shape used by the CLI scripts so callers
+ * can emit it on stderr and exit non-zero.
+ *
+ * @param {{ status: string, reason: string }} validationResult
+ * @returns {{ ok: false, error: string, asyncStartContract: string }}
+ */
+export function buildAsyncStartRejection(validationResult) {
+  return {
+    ok: false,
+    error: validationResult.reason,
+    asyncStartContract: "rejected",
+  };
+}