@mmerterden/multi-agent-pipeline 17.5.1 → 17.6.0

package/pipeline/scripts/maturity-followup.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * maturity-followup.mjs  -  what to do about an issue that is not ready yet.
+ *
+ * The maturity check has always produced a machine-readable gap list
+ * (`blockers[]`, `warnings[]`, stable codes) and then thrown most of it away: a
+ * blocker halted the run and an autopilot queue moved on to the next item,
+ * leaving the issue exactly as immature as it found it. Nobody was told, so
+ * nothing changed, so the next scan halted on the same issue for the same
+ * reason.
+ *
+ * This module decides the follow-up. It is PURE - no network, no git, no issue
+ * API, no clock unless one is handed to it - because the decision is the part
+ * worth testing and the I/O around it is the part that differs per host.
+ *
+ * THE RULE THAT SHAPES EVERYTHING: an edit is a reason to look again, never
+ * proof that the gap closed. A reply reading "will do later" moves the
+ * artifact's timestamp and fixes nothing. So a changed artifact re-runs the
+ * maturity check against the new content and the CHECK decides - this module
+ * never infers maturity from the fact that something moved.
+ *
+ * IT NEVER RE-LABELS A GAP. The fetcher already renders the codes into
+ * `maturity.summary` in the user's language; re-deriving that wording here
+ * would give the project two copies of one table and only one of them would be
+ * maintained.
+ *
+ * @module pipeline/scripts/maturity-followup
+ */
+
+/**
+ * The first line of any comment this pipeline writes about maturity.
+ *
+ * It is a plain sentence rather than an HTML comment on purpose: Jira, GitHub
+ * and Confluence render markdown differently and at least one of them shows the
+ * raw `<!-- -->`, but all three show a first line. It carries no square brackets
+ * for the same reason: `[text]` is a LINK in Jira wiki markup, so a bracketed
+ * marker renders as a broken link to a page nobody created. It has to be recognisable to
+ * BOTH a human skimming the thread and the next scan looking for its own prior
+ * comment, because posting the same question twice is how an unattended queue
+ * turns an issue into a wall of identical bot comments.
+ */
+export const MARKER = "multi-agent: Bu madde geliştirmeye hazır değil / not ready to develop yet";
+
+/**
+ * The machine-readable half of the comment.
+ *
+ * WHY IT IS IN THE BODY AND NOT ONLY IN STATE. `state.maturityFollowup` lives in
+ * one run's agent-state.json, and the next scan of the same item is a DIFFERENT
+ * run with a fresh state file. Deriving "have we already asked" from state alone
+ * means every scan is a first ask, which is precisely the wall of identical bot
+ * comments this feature exists to avoid. The item itself is the only store both
+ * runs can see, so the question we asked is recorded where we asked it.
+ *
+ * The prose above it is the fetcher's localized summary, which is written for a
+ * human and is not stable enough to compare; these are the codes.
+ *
+ * No square brackets, for the Jira reason above.
+ */
+export const GAP_LINE = "multi-agent gaps:";
+
+/** The codes carried by one of our comments, or null when it carries none. */
+export function parseGaps(text) {
+  if (typeof text !== "string") return null;
+  const line = text.split("\n").find((l) => l.trim().startsWith(GAP_LINE));
+  if (!line) return null;
+  const rest = line
+    .trim()
+    .slice(GAP_LINE.length)
+    .replace(/^[:\s]+/, "");
+  const codes = rest
+    .split(",")
+    .map((c) => c.trim())
+    .filter(isCode);
+  return codes.length ? [...new Set(codes)].sort() : [];
+}
+
+/**
+ * The prior ask, read from the item's own comments.
+ *
+ * Newest ours wins: a gap set that changed produces a second comment, and the
+ * newest one is the question actually outstanding. A comment of ours that
+ * carries no gap line (written before this version, or edited by hand) counts as
+ * "we asked, about something we can no longer name" - gaps `[]`, which never
+ * equals a live gap set, so the next scan asks again with the codes attached
+ * rather than staying silent forever on an unreadable record.
+ *
+ * @param {Array<{body?: string, text?: string, createdAt?: string, created?: string, updatedAt?: string}>} comments
+ * @returns {{gaps: string[], askedAt: string|null}|null}
+ */
+export function priorFromComments(comments) {
+  if (!Array.isArray(comments)) return null;
+  let best = null;
+  for (const c of comments) {
+    const body = typeof c === "string" ? c : c?.body || c?.text || "";
+    if (!isOurComment(body)) continue;
+    const at = typeof c === "string" ? null : c?.createdAt || c?.created || c?.updatedAt || null;
+    const ms = at ? Date.parse(at) : NaN;
+    const rank = Number.isNaN(ms) ? -1 : ms;
+    if (!best || rank >= best.rank) best = { gaps: parseGaps(body) || [], askedAt: at, rank };
+  }
+  return best ? { gaps: best.gaps, askedAt: best.askedAt } : null;
+}
+
+/** Gap codes that stop a run outright, in the order the fetcher emits them. */
+export function gapsOf(maturity) {
+  if (!maturity || typeof maturity !== "object") return { blockers: [], warnings: [], all: [] };
+  const blockers = Array.isArray(maturity.blockers) ? maturity.blockers.filter(isCode) : [];
+  const warnings = Array.isArray(maturity.warnings) ? maturity.warnings.filter(isCode) : [];
+  return { blockers, warnings, all: [...blockers, ...warnings] };
+}
+
+function isCode(c) {
+  return typeof c === "string" && c.trim().length > 0;
+}
+
+/** Two gap sets are the same question when they hold the same codes. */
+export function sameGaps(a, b) {
+  const A = [...new Set((a || []).filter(isCode))].sort();
+  const B = [...new Set((b || []).filter(isCode))].sort();
+  return A.length === B.length && A.every((v, i) => v === B[i]);
+}
+
+function toMs(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v !== "string" || !v.trim()) return null;
+  const t = Date.parse(v);
+  return Number.isNaN(t) ? null : t;
+}
+
+/**
+ * Has the artifact moved since we asked?
+ *
+ * `null` for "cannot tell" is deliberate and is NOT folded into `false`. An
+ * unparseable or absent timestamp means the host did not tell us, and treating
+ * that as "nothing changed" parks a run forever on a tracker whose API omits
+ * the field. Unknown re-checks; it does not wait.
+ *
+ * @returns {boolean|null}
+ */
+export function movedSince(artifactUpdatedAt, askedAt) {
+  const a = toMs(artifactUpdatedAt);
+  const b = toMs(askedAt);
+  if (a === null || b === null) return null;
+  return a > b;
+}
+
+/**
+ * Decide the follow-up.
+ *
+ * @param {object} input
+ * @param {object} input.maturity            the FRESH maturity object, re-scored this pass
+ * @param {"interactive"|"autopilot"} input.mode
+ * @param {object|null} [input.prior]        `state.maturityFollowup` from a previous pass
+ * @param {object} [input.artifact]          `{kind, key, url, updatedAt}`
+ * @param {object} [input.prefs]             `prefs.global.maturityFollowup`
+ * @returns {{action: string, reason: string, gaps?: string[], [k: string]: any}}
+ */
+export function decide({ maturity, mode, prior = null, artifact = {}, prefs = {} } = {}) {
+  const { blockers, warnings, all } = gapsOf(maturity);
+  const askInteractively = prefs.askInteractively !== false;
+  const commentsOn = prefs.autopilotCommentsOnIssue === true;
+  const commentOnWarnings = prefs.commentOnWarnings === true;
+
+  // Free-text input scores null: there is no issue to be immature.
+  if (maturity && maturity.score === null) {
+    return { action: "proceed", reason: "no issue to score" };
+  }
+  if (all.length === 0) {
+    return { action: "proceed", reason: "mature" };
+  }
+
+  // Warnings alone have always auto-continued under autopilot, and a release
+  // that silently converted every warning into a halt would stall queues
+  // overnight on issues that were running fine yesterday. Raising them is
+  // opt-in, and the gaps are recorded either way so the next pass can compare.
+  const actionable = blockers.length > 0 || (commentOnWarnings && warnings.length > 0);
+
+  if (mode !== "autopilot") {
+    if (!actionable) return { action: "proceed", reason: "warnings only", gaps: all };
+    if (!askInteractively) return { action: "halt", reason: "blocker", gaps: all };
+    return { action: "ask", reason: "blocker", gaps: all, blockers, warnings };
+  }
+
+  if (!actionable) {
+    return { action: "proceed", reason: "warnings only", gaps: all, record: true };
+  }
+
+  if (!commentsOn) {
+    // Today's behaviour, unchanged: halt and say why. The comment is the new
+    // part and it is an outward-facing write, so it does not happen by default.
+    return { action: "halt", reason: "blocker", gaps: all };
+  }
+
+  const priorGaps = prior && Array.isArray(prior.gaps) ? prior.gaps : null;
+  if (!priorGaps) {
+    return { action: "comment", reason: "first ask", gaps: all, blockers, warnings };
+  }
+
+  if (!sameGaps(priorGaps, all)) {
+    // The issue was edited and a DIFFERENT gap set survives. That is new
+    // information for the reader, so it earns a comment; the same set does not.
+    return { action: "comment", reason: "gaps changed", gaps: all, blockers, warnings, priorGaps };
+  }
+
+  const moved = movedSince(artifact.updatedAt, prior.askedAt);
+  if (moved === false) {
+    return { action: "wait", reason: "asked already, artifact unchanged", gaps: all };
+  }
+  // moved === true or null: the check has already re-run against fresh content
+  // to produce the `maturity` handed in here, and the same gaps survived. Say
+  // nothing again; a queue that re-comments on every scan is noise.
+  return {
+    action: "wait",
+    reason:
+      moved === null
+        ? "asked already, artifact age unknown"
+        : "asked already, gaps survived the edit",
+    gaps: all,
+  };
+}
+
+/**
+ * The comment body.
+ *
+ * `summary` is the fetcher's own localized rendering of these same codes and is
+ * used verbatim. `Ref:` is the only issue reference form this pipeline writes -
+ * a closing keyword would let the host's automation act on a comment that is
+ * asking a question.
+ *
+ * @param {object} input
+ * @param {string} input.summary   `maturity.summary`, already localized
+ * @param {string} [input.taskRef] what to point back at, e.g. `PROJ-1234`
+ * @param {string[]} [input.gaps]  the codes, recorded on the item so the NEXT run
+ *                                 can tell what was already asked without our state file
+ * @param {"tr"|"en"} [input.lang]
+ * @returns {string}
+ */
+export function commentBody({ summary, taskRef = "", lang = "tr", gaps = [] } = {}) {
+  const body = String(summary || "").trim();
+  const codes = [...new Set((gaps || []).filter(isCode))].sort();
+  const tr = [
+    MARKER,
+    "",
+    "Otomatik geliştirme sırası bu maddeye geldi ve şu eksiklerle durdu:",
+    "",
+    body,
+    "",
+    "Maddeyi düzenlediğinde bir sonraki tarama eksikleri yeniden kontrol eder ve",
+    "kapandıysa geliştirme kendiliğinden başlar. Bu yorum yalnızca sorar: maddenin",
+    "durumu, atanan kişisi ya da etiketleri değiştirilmedi.",
+  ];
+  const en = [
+    MARKER,
+    "",
+    "The automated queue reached this item and stopped on:",
+    "",
+    body,
+    "",
+    "Edit the item and the next scan re-checks these; development starts on its own",
+    "once they are closed. This comment only asks - the item's status, assignee and",
+    "labels were not touched.",
+  ];
+  const lines = lang === "en" ? en : tr;
+  if (taskRef) lines.push("", `Ref: ${taskRef}`);
+  // Last line, always present even when empty: its ABSENCE is how a reader tells
+  // a comment written before this version from one that asked about nothing.
+  lines.push("", `${GAP_LINE} ${codes.join(",")}`.trimEnd());
+  return lines.join("\n");
+}
+
+/**
+ * Is this comment one of ours?
+ *
+ * Used before posting, against the artifact's existing comments. Matching on
+ * the marker rather than on authorship is what makes it work when the token
+ * that posts is a shared service account.
+ */
+export function isOurComment(text) {
+  return typeof text === "string" && text.includes(MARKER);
+}
+
+/** The record written to `state.maturityFollowup` after a comment. */
+export function recordFor({ gaps, artifact = {}, at, commentUrl = null }) {
+  return {
+    gaps: [...new Set((gaps || []).filter(isCode))].sort(),
+    askedAt: typeof at === "string" ? at : new Date(at || Date.now()).toISOString(),
+    target: {
+      kind: artifact.kind || "unknown",
+      key: artifact.key || null,
+      url: artifact.url || null,
+    },
+    commentUrl,
+  };
+}

package/pipeline/scripts/package-manager.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * package-manager.mjs  -  which package manager does THIS repo use.
+ *
+ * WHY THIS EXISTS
+ *
+ * Phase 3 and Phase 5 shelled `npm test` and `npm run build` for the node-shaped
+ * stacks, hardcoded. A repo on pnpm, yarn or bun then gets one of two outcomes,
+ * both bad: the command fails outright, or npm quietly installs against a lock
+ * file it does not own and the run continues on a tree the repo's own tooling
+ * would not have produced. Either way it happens in Phase 3, after a worktree
+ * and a branch already exist - the same failure shape ADR-0012 rejected for
+ * platforms ("it fails partway through, having already created a worktree and a
+ * branch").
+ *
+ * The iOS and Android paths are untouched; this is only about the stacks where
+ * a node package manager is the build tool.
+ *
+ * NODE CORE ONLY (ADR-0004). No corepack call, no spawn, no network: the answer
+ * is derivable from files that are already on disk, and a resolver that shells
+ * out would need a working install of the very tool it is trying to identify.
+ *
+ * RESOLUTION ORDER, strongest evidence first:
+ *   1. $MA_PACKAGE_MANAGER          an explicit override always wins
+ *   2. package.json "packageManager" the repo's own declaration (corepack's field)
+ *   3. a lock file                   what the repo actually committed
+ *   4. npm                           the default, reported AS a default
+ *
+ * The order is "what the repo said" before "what the repo left behind", because
+ * a stale lock file outlives a migration and the declaration does not.
+ *
+ * Usage:
+ *   node package-manager.mjs detect --dir <d>                 -> JSON
+ *   node package-manager.mjs test   --dir <d> [--pattern <p>] -> the command line
+ *   node package-manager.mjs run    --dir <d> --script build  -> the command line
+ *   node package-manager.mjs install --dir <d>                -> the command line
+ *
+ * Exit: 0 ok · 2 usage · 3 the requested script is not declared (run/test)
+ *
+ * @module pipeline/scripts/package-manager
+ */
+
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** Lock file -> package manager. Ordered only for a stable tie-break message. */
+export const LOCKFILES = [
+  ["bun.lockb", "bun"],
+  ["bun.lock", "bun"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"],
+  ["npm-shrinkwrap.json", "npm"],
+];
+
+export const KNOWN = ["npm", "pnpm", "yarn", "bun"];
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `"pnpm@9.1.0"` -> `pnpm`. A field naming something we do not know about is
+ * returned as-is by name so the caller can say WHICH unknown manager it saw;
+ * garbage (empty, a version with no name) resolves to null and falls through.
+ */
+export function parseManagerField(value) {
+  if (typeof value !== "string") return null;
+  const name = value.trim().split("@")[0].trim().toLowerCase();
+  return /^[a-z][a-z0-9-]*$/.test(name) ? name : null;
+}
+
+/**
+ * Walk up from `dir` looking for the evidence. A monorepo keeps its lock file at
+ * the root while the task edits a package three levels down, so stopping at the
+ * starting directory would resolve to the default for most real repos.
+ *
+ * The walk stops AFTER the directory that holds `.git` - that is the repo, and
+ * anything above it belongs to somebody else (a home directory with a stray
+ * yarn.lock has misrouted builds before).
+ */
+export function* ancestors(dir) {
+  let cur = resolvePath(dir);
+  for (;;) {
+    yield cur;
+    if (existsSync(join(cur, ".git"))) return;
+    const up = dirname(cur);
+    if (up === cur) return;
+    cur = up;
+  }
+}
+
+function locksIn(dir) {
+  const found = [];
+  for (const [file, pm] of LOCKFILES) {
+    const full = join(dir, file);
+    if (existsSync(full)) {
+      let mtime = 0;
+      try {
+        mtime = statSync(full).mtimeMs;
+      } catch {
+        /* unreadable is the same as absent for a tie-break */
+      }
+      found.push({ file, pm, mtime });
+    }
+  }
+  return found;
+}
+
+/**
+ * Resolve the package manager for a directory.
+ *
+ * @param {string} dir
+ * @param {object} [opts]
+ * @param {Record<string,string|undefined>} [opts.env]
+ * @returns {{pm: string, source: string, evidence: string, root: string|null,
+ *            known: boolean, ambiguous?: string[]}}
+ */
+export function detect(dir = process.cwd(), { env = process.env } = {}) {
+  const raw = (env.MA_PACKAGE_MANAGER || "").trim().toLowerCase();
+  // The output of this module is pasted into a shell line, so the name is held to
+  // the same shape a manager's binary actually has. Anything else is dropped and
+  // the resolution continues from the repo - an override is not worth executing
+  // whatever a stray environment variable happens to contain.
+  const override = /^[a-z][a-z0-9-]*$/.test(raw) ? raw : "";
+  if (override) {
+    return {
+      pm: override,
+      source: "env",
+      evidence: "MA_PACKAGE_MANAGER",
+      root: null,
+      known: KNOWN.includes(override),
+    };
+  }
+  if (raw) {
+    process.emitWarning(
+      `MA_PACKAGE_MANAGER=${JSON.stringify(raw)} is not a package manager name - ignored`,
+    );
+  }
+
+  for (const cur of ancestors(dir)) {
+    const pkgPath = join(cur, "package.json");
+    if (existsSync(pkgPath)) {
+      const declared = parseManagerField(readJson(pkgPath)?.packageManager);
+      if (declared) {
+        return {
+          pm: declared,
+          source: "packageManager-field",
+          evidence: `${pkgPath}#packageManager`,
+          root: cur,
+          known: KNOWN.includes(declared),
+        };
+      }
+    }
+
+    const locks = locksIn(cur);
+    if (locks.length === 1) {
+      return {
+        pm: locks[0].pm,
+        source: "lockfile",
+        evidence: join(cur, locks[0].file),
+        root: cur,
+        known: true,
+      };
+    }
+    if (locks.length > 1) {
+      // Two lock files almost always means a migration that left one behind.
+      // Newest wins, and every candidate is reported: a resolver that silently
+      // picks one of two committed lock files is how a repo ends up building
+      // with the manager it migrated AWAY from.
+      const sorted = [...locks].sort((a, b) => b.mtime - a.mtime);
+      return {
+        pm: sorted[0].pm,
+        source: "lockfile-newest",
+        evidence: join(cur, sorted[0].file),
+        root: cur,
+        known: true,
+        ambiguous: sorted.map((l) => l.file),
+      };
+    }
+  }
+
+  return {
+    pm: "npm",
+    source: "default",
+    evidence: "no lock file, no declaration",
+    root: null,
+    known: true,
+  };
+}
+
+/** Does the resolved root declare this script? */
+export function hasScript(dir, script) {
+  for (const cur of ancestors(dir)) {
+    const pkgPath = join(cur, "package.json");
+    if (!existsSync(pkgPath)) continue;
+    const scripts = readJson(pkgPath)?.scripts;
+    if (scripts && typeof scripts === "object") return Object.hasOwn(scripts, script);
+  }
+  return false;
+}
+
+/**
+ * `npm run build` for every manager, deliberately.
+ *
+ * `pnpm build` and `yarn build` also work, but only until a script shares a name
+ * with a builtin (`pnpm test`, `yarn add`, `bun install`): then the builtin wins
+ * and the repo's own script never runs. The explicit `run` form has no such
+ * collision on any of the four.
+ */
+export function runCommand(pm, script, args = []) {
+  const extra = args.length ? ` ${args.join(" ")}` : "";
+  return `${pm} run ${script}${extra}`;
+}
+
+/**
+ * The test command, with pass-through arguments.
+ *
+ * npm is the odd one: it needs `--` to stop eating the arguments itself. The
+ * other three forward them to the script as written, and an extra `--` becomes a
+ * literal argument the test runner then has to ignore.
+ */
+export function testCommand(pm, args = []) {
+  if (!args.length) return pm === "bun" ? "bun run test" : `${pm} run test`;
+  const sep = pm === "npm" ? " -- " : " ";
+  return `${pm === "bun" ? "bun run test" : `${pm} run test`}${sep}${args.join(" ")}`;
+}
+
+/** The install command. `--frozen-lockfile` is NOT added: that is a CI decision. */
+export function installCommand(pm) {
+  return pm === "yarn" ? "yarn install" : `${pm} install`;
+}
+
+// ---------------------------------------------------------------------------
+
+function usage(msg) {
+  if (msg) process.stderr.write(`package-manager: ${msg}\n`);
+  process.stderr.write(
+    "usage: package-manager.mjs detect|test|run|install --dir <d> [--script <s>] [--pattern <p>]\n",
+  );
+  process.exit(2);
+}
+
+function main(argv) {
+  const mode = argv[0];
+  if (!mode || mode.startsWith("-")) usage("a mode is required");
+  const opts = {};
+  for (let i = 1; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--dir") opts.dir = argv[++i];
+    else if (a === "--script") opts.script = argv[++i];
+    else if (a === "--pattern") opts.pattern = argv[++i];
+    else if (a === "-h" || a === "--help") usage();
+    else usage(`unexpected argument ${a}`);
+  }
+  const dir = opts.dir || process.cwd();
+  const d = detect(dir);
+
+  if (mode === "detect") {
+    process.stdout.write(`${JSON.stringify(d)}\n`);
+    return 0;
+  }
+  if (mode === "install") {
+    process.stdout.write(`${installCommand(d.pm)}\n`);
+    return 0;
+  }
+  if (mode === "test") {
+    if (!hasScript(dir, "test")) {
+      process.stderr.write("package-manager: no test script declared in package.json\n");
+      return 3;
+    }
+    const args = opts.pattern ? [opts.pattern] : [];
+    process.stdout.write(`${testCommand(d.pm, args)}\n`);
+    return 0;
+  }
+  if (mode === "run") {
+    if (!opts.script) usage("run needs --script");
+    if (!hasScript(dir, opts.script)) {
+      process.stderr.write(`package-manager: no ${opts.script} script declared in package.json\n`);
+      return 3;
+    }
+    process.stdout.write(`${runCommand(d.pm, opts.script)}\n`);
+    return 0;
+  }
+  usage(`unknown mode ${mode}`);
+  return 2;
+}
+
+// Not `file://${process.argv[1]}`: a path with a space or a non-ASCII character
+// percent-encodes in import.meta.url, and on macOS /tmp is a symlink to
+// /private/tmp so argv[1] and the resolved module URL disagree. Either one
+// silently turns this file into a library that prints nothing and exits 0.
+function isEntrypoint() {
+  const arg = process.argv[1];
+  if (!arg) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(arg)).href;
+  } catch {
+    return import.meta.url === pathToFileURL(arg).href;
+  }
+}
+
+if (isEntrypoint()) {
+  process.exit(main(process.argv.slice(2)));
+}