dev-loops 0.3.0 → 0.5.0

package/scripts/loop/info.mjs

@@ -100,13 +100,32 @@ function formatCiDisplay(ciStatus, ciConclusion) {
   return `CI ${ciStatus}`;
 }
 
+function formatMergeableDisplay(mergeable, mergeStateStatus) {
+  const m = typeof mergeable === "string" ? mergeable.toUpperCase() : null;
+  const s = typeof mergeStateStatus === "string" ? mergeStateStatus.toUpperCase() : null;
+  if (m === "CONFLICTING" || s === "DIRTY" || s === "CONFLICTING") {
+    return `❌ CONFLICTING${s ? ` (${s})` : ""} — resolve before any gate`;
+  }
+  if (s === "BEHIND") {
+    return "⚠️ BEHIND — update branch from base before any gate";
+  }
+  if (m === "UNKNOWN") {
+    return "⏳ UNKNOWN — GitHub still computing; recheck before proceeding";
+  }
+  if (m === "MERGEABLE") {
+    return `✅ MERGEABLE${s ? ` (${s})` : ""}`;
+  }
+  return s || m || "unknown";
+}
+
 function formatPrSummary(prData, handoffResult) {
   const lines = [];
   lines.push(`PR #${prData.number}: ${prData.title}`);
   lines.push(`  Branch: ${formatBranchDisplay(prData.headRefName, prData.baseRefName)}`);
   lines.push(`  State: ${prData.state}${prData.isDraft ? " (draft)" : ""}`);
   lines.push(`  Author: ${prData.author?.login || "unknown"}`);
-  
+  lines.push(`  Mergeable: ${formatMergeableDisplay(prData.mergeable, prData.mergeStateStatus)}`);
+
   if (handoffResult?.snapshot) {
     const s = handoffResult.snapshot;
     if (s.ciStatus !== undefined) {
@@ -189,7 +208,7 @@ function formatIssueSummary(issueData, startupBundle, linkedPrData) {
 }
 
 function buildPrInfo(prNumber, repo, cwd) {
-  const prData = ghJson(["pr", "view", String(prNumber), "--repo", repo, "--json", "number,title,body,state,isDraft,headRefName,baseRefName,author,mergedAt,url,reviewRequests"], cwd);
+  const prData = ghJson(["pr", "view", String(prNumber), "--repo", repo, "--json", "number,title,body,state,isDraft,headRefName,baseRefName,author,mergedAt,mergeable,mergeStateStatus,url,reviewRequests"], cwd);
   
   let handoffResult = null;
   try {

package/scripts/loop/outer-loop.mjs

@@ -72,7 +72,7 @@ Stop reasons:
 Async-start contract:
   This loop must run within a visible harness-managed async context when
   workflow.asyncStartMode is set to required (default). It fails closed unless
-  DEVLOOPS_RUN_ID (or the PI_SUBAGENT_RUN_ID alias) is set, to prevent hidden detached-process fallback
+  DEVLOOPS_RUN_ID is set, to prevent hidden detached-process fallback
   (nohup, disowned shell jobs, etc.). Snapshot/test input mode
   (both --copilot-input and --reviewer-input) is exempt. Any relaxed
   async-start posture is maintainer-controlled repository policy, not an

package/scripts/loop/pr-runner-coordination.mjs

@@ -5,6 +5,7 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { resolveRunId as resolveEnvRunId } from "@dev-loops/core/loop/run-context";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 import {
   assertRunnerOwnership,
   claimRunnerOwnership,
@@ -19,10 +20,11 @@ const USAGE = `Usage:
   pr-runner-coordination.mjs release --repo <owner/name> --pr <number> [--run-id <id>]
 Durable one-runner-per-PR coordination helper.
 If --run-id is omitted for claim/assert/release/takeover, DEVLOOPS_RUN_ID is used
-(falling back to the PI_SUBAGENT_RUN_ID alias).
+(via DEVLOOPS_RUN_ID).
 Output:
   stdout: { "ok": true, ... }
   stderr: { "ok": false, "error": "...", ... }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success / clean stop-compatible result
   1  Argument error or coordination conflict`.trim();
@@ -36,6 +38,8 @@ function parseCliArgs(argv) {
     pr: undefined,
     runId: undefined,
     requireExisting: false,
+    jq: undefined,
+    silent: false,
   };
   const command = args.shift();
   if (command === undefined || command === "--help" || command === "-h") {
@@ -51,6 +55,7 @@ function parseCliArgs(argv) {
       pr: { type: "string" },
       "run-id": { type: "string" },
       "require-existing": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -83,6 +88,14 @@ function parseCliArgs(argv) {
       options.requireExisting = true;
       continue;
     }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const validCommands = new Set(["status", "claim", "takeover", "assert", "release"]);
@@ -146,11 +159,14 @@ async function main() {
     }
     const result = await runPrRunnerCoordination(options, { env: process.env });
     if (!result.ok) {
-      console.error(JSON.stringify(result));
-      process.exitCode = 1;
-      return;
+      // Preserve the established stderr-on-failure contract when not filtering.
+      if (options.jq === undefined && !options.silent) {
+        console.error(JSON.stringify(result));
+        process.exitCode = 1;
+        return;
+      }
     }
-    console.log(JSON.stringify(result));
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     const payload = formatCliError(error, { usage: USAGE });
     console.error(JSON.stringify(payload));

package/scripts/loop/pre-flight-gate.mjs

@@ -12,7 +12,7 @@ import {
   isListedWorktree,
   detectSubagentAvailability,
 } from "@dev-loops/core/loop/worktree-guard";
-const PI_PREFLIGHT_BYPASS_VAR = "PI_PREFLIGHT_BYPASS";
+const DEVLOOPS_PREFLIGHT_BYPASS_VAR = "DEVLOOPS_PREFLIGHT_BYPASS";
 const USAGE = `Usage:
   pre-flight-gate.mjs [--expected-branch <name>] [--check-subagents]
 Gate local implementation mutations before planning or editing.
@@ -28,7 +28,7 @@ Violation output (stderr, JSON, exit 1):
   { "ok": false, "error": "<error_code>", "checks": { ... },
     "guidance": "<actionable instruction for the agent>" }
 Bypass:
-  PI_PREFLIGHT_BYPASS=1   Skip all checks (for development/testing only).`.trim();
+  DEVLOOPS_PREFLIGHT_BYPASS=1   Skip all checks (for development/testing only).`.trim();
 const parseError = buildParseError(USAGE);
 export function parsePreFlightGateCliArgs(argv) {
   const options = {
@@ -95,7 +95,8 @@ function checkWorktreeIsolation({ cwd, env, gitCommand = "git" }) {
         guidance:
           `Current directory appears to be the main git checkout (${mainWorktreePath}).\n` +
           "Local implementation requires worktree isolation. Create a worktree:\n" +
-          "  git worktree add -b <branch> tmp/worktrees/<slug>/ origin/main\n" +
+          "  node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>\n" +
+          "  (creates+provisions tmp/worktrees/dev-loops/<kind>-<n> from origin/main)\n" +
           "Then re-run from the worktree directory.",
         mainWorktreePath,
       };
@@ -105,7 +106,8 @@ function checkWorktreeIsolation({ cwd, env, gitCommand = "git" }) {
       error: "not_in_worktree",
       guidance:
         "Local implementation requires worktree isolation. Create a worktree:\n" +
-        "  git worktree add -b <branch> tmp/worktrees/<slug>/ origin/main\n" +
+        "  node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>\n" +
+        "  (creates+provisions tmp/worktrees/dev-loops/<kind>-<n> from origin/main)\n" +
         "Then re-run from the worktree directory.",
       mainWorktreePath: mainWorktreePath ?? undefined,
     };
@@ -118,7 +120,8 @@ function checkWorktreeIsolation({ cwd, env, gitCommand = "git" }) {
       guidance:
         "Current directory is under tmp/worktrees/ but is not a real git worktree.\n" +
         "Create a worktree with:\n" +
-        "  git worktree add -b <branch> tmp/worktrees/<slug>/ origin/main\n" +
+        "  node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>\n" +
+        "  (creates+provisions tmp/worktrees/dev-loops/<kind>-<n> from origin/main)\n" +
         "Then re-run from the worktree directory.",
       mainWorktreePath: mainWorktreePath ?? undefined,
     };
@@ -180,11 +183,11 @@ export async function runCli(
     stdout.write(`${USAGE}\n`);
     return { ok: true, help: true };
   }
-  if ((effectiveEnv[PI_PREFLIGHT_BYPASS_VAR] ?? "").trim() === "1") {
+  if ((effectiveEnv[DEVLOOPS_PREFLIGHT_BYPASS_VAR] ?? "").trim() === "1") {
     const payload = {
       ok: true,
       checks: { worktree: true, branch: "skipped", subagents: "skipped" },
-      summary: "pre-flight gate bypassed via PI_PREFLIGHT_BYPASS=1",
+      summary: "pre-flight gate bypassed via DEVLOOPS_PREFLIGHT_BYPASS=1",
     };
     stdout.write(`${JSON.stringify(payload)}\n`);
     return payload;

package/scripts/loop/pre-push-main-guard.mjs

@@ -3,7 +3,7 @@ import { createInterface } from "node:readline";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { parseArgs } from "node:util";
 
-const PI_PREPUSH_BYPASS_VAR = "PI_PREPUSH_BYPASS";
+const DEVLOOPS_PREPUSH_BYPASS_VAR = "DEVLOOPS_PREPUSH_BYPASS";
 const BLOCKED_REFS = ["refs/heads/main"];
 
 const USAGE = `Usage:
@@ -17,7 +17,7 @@ Exit codes:
   1  Push blocked (target is a protected ref)
 
 Bypass:
-  PI_PREPUSH_BYPASS=1   Skip all checks (for emergencies only).
+  DEVLOOPS_PREPUSH_BYPASS=1   Skip all checks (for emergencies only).
                          Preferred: push a feature branch and open a PR.`.trim();
 
 const parseError = buildParseError(USAGE);
@@ -88,8 +88,8 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   const options = parsePrePushGuardCliArgs(argv);
   if (options.help) { stdout.write(`${USAGE}\n`); return { ok: true, help: true }; }
 
-  if (env[PI_PREPUSH_BYPASS_VAR] === "1") {
-    stdout.write(JSON.stringify({ ok: true, bypassed: true, reason: `${PI_PREPUSH_BYPASS_VAR}=1` }) + "\n");
+  if ((env[DEVLOOPS_PREPUSH_BYPASS_VAR] ?? "").trim() === "1") {
+    stdout.write(JSON.stringify({ ok: true, bypassed: true, reason: `${DEVLOOPS_PREPUSH_BYPASS_VAR}=1` }) + "\n");
     return { ok: true, bypassed: true };
   }
 

package/scripts/loop/provision-worktree.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * Provision a freshly-created worktree with the gitignored files/dirs the app
+ * and tests need, copied/symlinked from the main checkout per `.devloops`
+ * `worktree.copyOnInit` / `worktree.linkOnInit` (issue #909).
+ *
+ * - Sources resolve against the main checkout (`--repo-root`), never cwd.
+ * - Entries are repo-relative literal paths OR glob patterns (native fsp.glob).
+ * - copy = `fs.cp(recursive)`; link = absolute symlink into the main checkout.
+ * - Every resolved source MUST resolve inside the main checkout (traversal guard).
+ * - Fail-soft: a missing source / empty glob logs one warning and continues.
+ * - Idempotent: skips a dest that is already correct.
+ * - Does NOT run npm install (deps belong to `npm ci`-in-worktree).
+ *
+ * Prints a JSON summary of actions to stdout. Never throws on a per-entry
+ * problem; exits 0 unless its own arguments are invalid.
+ */
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { loadDevLoopConfig, resolveWorktreeConfig } from "@dev-loops/core/config";
+
+const USAGE = `Usage:
+  provision-worktree.mjs --worktree-path <p> --repo-root <p>
+Provision a worktree with gitignored files/dirs from the main checkout,
+driven by .devloops worktree.copyOnInit / worktree.linkOnInit.
+Required:
+  --worktree-path <p>   Absolute path to the target worktree.
+  --repo-root <p>       Absolute path to the main checkout (source of files).
+Optional:
+  -h, --help            Show this help.
+Output (stdout, JSON):
+  { "ok": true, "actions": [ { "mode": "copy"|"link"|"skip"|"reject", ... } ],
+    "summary": { "copied": n, "linked": n, "skipped": n, "rejected": n,
+                 "warnings": n } }`.trim();
+
+const parseError = buildParseError(USAGE);
+
+export function parseProvisionWorktreeCliArgs(argv) {
+  const options = { help: false, worktreePath: undefined, repoRoot: undefined };
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      "worktree-path": { type: "string" },
+      "repo-root": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") throw parseError(`Unknown argument: ${token.value}`);
+    if (token.kind !== "option") continue;
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "worktree-path") {
+      options.worktreePath = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token.name === "repo-root") {
+      options.repoRoot = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (!options.worktreePath) throw parseError("Missing required --worktree-path");
+  if (!options.repoRoot) throw parseError("Missing required --repo-root");
+  return options;
+}
+
+/**
+ * Resolve a repo-relative entry (literal or glob) to matched absolute sources
+ * inside repoRoot. Returns `{ matches: string[], traversal: string[] }`.
+ * `traversal` holds matches that escaped repoRoot (rejected by caller).
+ */
+async function expandEntry(entry, repoRoot) {
+  const matches = [];
+  const traversal = [];
+  const isGlob = /[*?[\]{}]/.test(entry);
+  const inside = (abs) => abs === repoRoot || abs.startsWith(repoRoot + path.sep);
+
+  if (isGlob) {
+    // native fsp.glob (Node >=22) — expand against the main checkout.
+    for await (const rel of fsp.glob(entry, { cwd: repoRoot })) {
+      const abs = path.resolve(repoRoot, rel);
+      (inside(abs) ? matches : traversal).push(abs);
+    }
+  } else {
+    const abs = path.resolve(repoRoot, entry);
+    (inside(abs) ? matches : traversal).push(abs);
+  }
+  return { matches, traversal };
+}
+
+async function pathExists(p) {
+  try {
+    await fsp.lstat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The lexical `inside()` guard in expandEntry can't see through symlinks: a
+ * source that is itself a symlink (or sits under a symlinked dir) pointing
+ * OUTSIDE repoRoot resolves clean lexically but escapes on realpath. Re-check
+ * the realpath here BEFORE any copy/link. Returns true when the resolved
+ * source is genuinely inside repoRoot. Non-existent source → treat as inside
+ * (the copy/link helpers handle missing sources with their own warning).
+ */
+async function realpathInside(src, repoRoot) {
+  let real;
+  try {
+    real = await fsp.realpath(src);
+  } catch {
+    return true; // missing/broken — let the copy/link helper report it
+  }
+  const realRoot = await fsp.realpath(repoRoot).catch(() => repoRoot);
+  return real === realRoot || real.startsWith(realRoot + path.sep);
+}
+
+/** Copy: idempotent skip when dest already exists (worktree reuse). */
+async function provisionCopy(src, dest, logWarn) {
+  if (!(await pathExists(src))) {
+    logWarn(`copyOnInit source missing, skipping: ${src}`);
+    return { mode: "skip", reason: "source-missing", src, dest };
+  }
+  if (await pathExists(dest)) return { mode: "skip", reason: "exists", src, dest };
+  await fsp.mkdir(path.dirname(dest), { recursive: true });
+  await fsp.cp(src, dest, { recursive: true });
+  return { mode: "copy", src, dest };
+}
+
+/** Symlink: absolute link into the main checkout. Idempotent when correct. */
+async function provisionLink(src, dest, logWarn) {
+  if (!(await pathExists(src))) {
+    logWarn(`linkOnInit source missing, skipping: ${src}`);
+    return { mode: "skip", reason: "source-missing", src, dest };
+  }
+  const existing = await fsp.readlink(dest).catch(() => null);
+  if (existing !== null) {
+    if (path.resolve(path.dirname(dest), existing) === src) {
+      return { mode: "skip", reason: "exists", src, dest };
+    }
+    return { mode: "skip", reason: "dest-conflict", src, dest };
+  }
+  if (await pathExists(dest)) return { mode: "skip", reason: "dest-conflict", src, dest };
+  await fsp.mkdir(path.dirname(dest), { recursive: true });
+  await fsp.symlink(src, dest); // absolute target — survives worktree moves under tmp/
+  return { mode: "link", src, dest };
+}
+
+export async function provisionWorktree({ worktreePath, repoRoot }, { loadConfig = loadDevLoopConfig } = {}) {
+  const root = path.resolve(repoRoot);
+  const dst = path.resolve(worktreePath);
+  const actions = [];
+  const warnings = [];
+  const logWarn = (msg) => {
+    warnings.push(msg);
+    process.stderr.write(`[provision-worktree] WARN ${msg}\n`);
+  };
+
+  // Fail-closed (repo convention): a config that failed to load/validate is
+  // treated as EMPTY — zero provisioning actions, one WARN. We never act on an
+  // unvalidated config (a bad entry could copy/link the wrong source).
+  const { config, errors } = await loadConfig({ repoRoot: root });
+  const safeConfig = errors && errors.length > 0 ? null : config;
+  if (safeConfig === null && errors && errors.length > 0) {
+    logWarn(`dev-loop config invalid (${errors.length} error(s)) — provisioning EMPTY config (no copy/link)`);
+  }
+  const { copyOnInit, linkOnInit } = resolveWorktreeConfig(safeConfig);
+
+  for (const [entries, kind] of [[copyOnInit, "copy"], [linkOnInit, "link"]]) {
+    for (const entry of entries) {
+      const { matches, traversal } = await expandEntry(entry, root);
+      for (const abs of traversal) {
+        logWarn(`rejected (outside main checkout): ${entry} → ${abs}`);
+        actions.push({ mode: "reject", reason: "traversal", entry, src: abs });
+      }
+      if (matches.length === 0 && traversal.length === 0) {
+        logWarn(`no match for ${kind}OnInit entry: ${entry}`);
+        actions.push({ mode: "skip", reason: "no-match", entry });
+        continue;
+      }
+      for (const src of matches) {
+        // Symlink-aware traversal guard: a source whose realpath escapes the
+        // main checkout is rejected before any copy/link (the lexical inside()
+        // above cannot see through symlinks).
+        if (!(await realpathInside(src, root))) {
+          logWarn(`rejected (symlink escapes main checkout): ${entry} → ${src}`);
+          actions.push({ mode: "reject", reason: "traversal", entry, src });
+          continue;
+        }
+        const dest = path.join(dst, path.relative(root, src));
+        // Fail-soft per the header promise: a per-entry copy/link failure (e.g.
+        // EACCES, dest conflict the helper didn't catch) logs ONE WARN, records
+        // a skip action, and continues — it never aborts the whole run.
+        try {
+          const res = kind === "copy"
+            ? await provisionCopy(src, dest, logWarn)
+            : await provisionLink(src, dest, logWarn);
+          actions.push({ entry, ...res });
+        } catch (err) {
+          const msg = (err && err.message) ? err.message : String(err);
+          logWarn(`${kind} failed, skipping: ${src} → ${dest}: ${msg}`);
+          actions.push({ entry, mode: "skip", reason: `${kind}-failed: ${msg}`, src, dest });
+        }
+      }
+    }
+  }
+
+  const summary = { copied: 0, linked: 0, skipped: 0, rejected: 0, warnings: warnings.length };
+  for (const a of actions) {
+    if (a.mode === "copy") summary.copied++;
+    else if (a.mode === "link") summary.linked++;
+    else if (a.mode === "skip") summary.skipped++;
+    else if (a.mode === "reject") summary.rejected++;
+  }
+  return { ok: true, actions, summary };
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseProvisionWorktreeCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+  const result = await provisionWorktree(options);
+  stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}