@mmerterden/multi-agent-pipeline 20.25.1 → 20.27.0

package/pipeline/scripts/jira-wiki-escape.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { pathToFileURL } from "node:url";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 const SEQUENCES = [
   ":)",
@@ -118,8 +119,7 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf8");
 }
 
-const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isMain) {
+if (invokedDirectly(import.meta.url)) {
   const args = process.argv.slice(2);
   const check = args.includes("--check");
   const file = args.find((a) => !a.startsWith("--"));

package/pipeline/scripts/plan-remote-links.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+/**
+ * plan-remote-links.mjs  -  the Issue Links an analysis puts on its Jira issue.
+ *
+ * Jira's "Issue Links" panel holds remote links: a URL, a title and a group
+ * name (`relationship`). Links there survive any later edit of the description
+ * and can be read back through the API, so the sources an analysis used belong
+ * there as well as in the body.
+ *
+ * This file only PLANS. It reads the analysis spec and the issue's current
+ * remote links and prints what to write; `lib/jira-remote-links.sh` writes it.
+ * It never plans a delete.
+ *
+ *   - One link per Figma frame, Confluence page, API contract and published
+ *     analysis page, deduplicated by URL.
+ *   - Every link carries a stable `globalId`. Jira treats a POST with a known
+ *     globalId as an update, so a re-run rewrites its own links in place.
+ *     Own ids start with `ma-`; a Confluence page linked through the
+ *     application link uses Jira's native `appId=<id>&pageId=<n>` form.
+ *   - A URL already linked under another globalId (by a person or another tool)
+ *     is skipped, never duplicated or overwritten.
+ *   - A Confluence page becomes a native "Wiki Page" only when the application
+ *     id is known: passed in, or read from a Wiki Page link already on the
+ *     issue for the same host. It is never guessed; without it the page is a
+ *     plain link.
+ *
+ * Usage:
+ *   node plan-remote-links.mjs --spec <analysis-spec.json | agent-state.json>
+ *        [--existing <remotelink GET response>] [--app-id <host>=<id>] [--lang tr|en]
+ *
+ * Output: {"write": [<remotelink payload>], "skip": [{globalId, url, reason}]}
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+const CONFLUENCE_APP = { type: "com.atlassian.confluence", name: "Confluence" };
+
+const LABELS = {
+  en: {
+    figma: "Figma",
+    confluence: "Confluence",
+    api: "API Contract",
+    analysis: "Analysis",
+    wiki: "Wiki Page",
+  },
+  tr: {
+    figma: "Figma",
+    confluence: "Confluence",
+    api: "API Sözleşmesi",
+    analysis: "Analiz",
+    wiki: "Wiki Page",
+  },
+};
+
+export function normalizeUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(String(url).trim());
+  } catch {
+    return String(url).trim();
+  }
+  parsed.hash = "";
+  parsed.hostname = parsed.hostname.toLowerCase();
+  const nodeId = parsed.searchParams.get("node-id");
+  if (/(^|\.)figma\.com$/.test(parsed.hostname)) {
+    // A Figma share link carries per-share parameters (t=, m=dev) and a renamable file
+    // slug; the frame is the file key plus the node id.
+    const { kind, fileKey } = figmaParts(parsed.toString());
+    if (fileKey) parsed.pathname = `/${kind}/${fileKey}`;
+    parsed.search = "";
+    if (nodeId) parsed.searchParams.set("node-id", nodeId.replace(/:/g, "-"));
+  } else {
+    parsed.searchParams.sort();
+  }
+  parsed.pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+  return parsed.toString();
+}
+
+function hostOf(url) {
+  try {
+    return new URL(url).host.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function shortHash(text) {
+  return createHash("sha1").update(text).digest("hex").slice(0, 12);
+}
+
+function pageIdOf(page) {
+  if (page.pageId) return String(page.pageId);
+  const match = String(page.url || "").match(/[?&]pageId=(\d+)|\/pages\/(\d+)(?:\/|$)/);
+  return match ? match[1] || match[2] : null;
+}
+
+function figmaParts(url) {
+  try {
+    const parsed = new URL(url);
+    // A branch has its own key and its own frames; the branch key identifies them.
+    const key = parsed.pathname.match(
+      /^\/(design|file|proto|board)\/([^/]+)(?:\/branch\/([^/]+))?/,
+    );
+    return {
+      kind: key ? key[1] : null,
+      fileKey: key ? key[3] || key[2] : null,
+      nodeId: parsed.searchParams.get("node-id"),
+    };
+  } catch {
+    return { kind: null, fileKey: null, nodeId: null };
+  }
+}
+
+/** The application id of the Confluence link Jira already uses for pages on `host`, or null. */
+export function confluenceAppId(existing, host) {
+  for (const link of existing || []) {
+    if (link?.application?.type !== CONFLUENCE_APP.type) continue;
+    const match = String(link.globalId || "").match(/^appId=([^&]+)&pageId=/);
+    if (match && hostOf(link.object?.url) === String(host).toLowerCase()) return match[1];
+  }
+  return null;
+}
+
+function specOf(input) {
+  return input?.analysisSpec || input || {};
+}
+
+/** The links the spec asks for, in a stable order, one per URL. */
+export function wantedLinks(input, { lang = "en" } = {}) {
+  const labels = LABELS[lang] || LABELS.en;
+  const spec = specOf(input);
+  const evidence = spec.evidence || {};
+  const wanted = [];
+  for (let frame of evidence.figma || []) {
+    if (!frame?.url) continue;
+    const fromUrl = figmaParts(frame.url);
+    frame = {
+      ...frame,
+      fileKey: frame.fileKey || fromUrl.fileKey,
+      nodeId: frame.nodeId || fromUrl.nodeId,
+    };
+    const nodeId = frame.nodeId ? String(frame.nodeId).replace(/-/g, ":") : null;
+    const name = frame.frames?.find((f) => f?.name)?.name;
+    const title = nodeId
+      ? name
+        ? `${labels.figma} · ${name} (${nodeId})`
+        : `${labels.figma} · ${nodeId}`
+      : `${labels.figma} · ${name || frame.fileKey || "design"}`;
+    const globalId =
+      frame.fileKey && nodeId
+        ? `ma-figma-${frame.fileKey}-${nodeId.replace(/:/g, "-")}`
+        : `ma-figma-${shortHash(normalizeUrl(frame.url))}`;
+    wanted.push({ kind: "figma", url: frame.url, title, relationship: labels.figma, globalId });
+  }
+  for (const page of evidence.confluence || []) {
+    if (!page?.url) continue;
+    const pageId = pageIdOf(page);
+    wanted.push({
+      kind: "confluence",
+      url: page.url,
+      title: page.title || `${labels.confluence} · ${pageId || hostOf(page.url)}`,
+      relationship: labels.confluence,
+      pageId,
+      globalId: `ma-confluence-${shortHash(normalizeUrl(page.url))}`,
+    });
+  }
+  for (const contract of evidence.swagger || []) {
+    if (!contract?.url) continue;
+    let leaf = hostOf(contract.url);
+    try {
+      leaf = new URL(contract.url).pathname.split("/").filter(Boolean).pop() || leaf;
+    } catch {
+      /* keep the host */
+    }
+    wanted.push({
+      kind: "api",
+      url: contract.url,
+      title: `API · ${leaf}`,
+      relationship: labels.api,
+      globalId: `ma-api-${shortHash(normalizeUrl(contract.url))}`,
+    });
+  }
+  for (const page of spec.outputs?.confluencePages || []) {
+    if (!page?.url) continue;
+    const pageId = pageIdOf(page);
+    wanted.push({
+      kind: "analysis",
+      url: page.url,
+      title: `${labels.analysis} · ${page.title || pageId || hostOf(page.url)}`,
+      relationship: labels.analysis,
+      pageId,
+      globalId: `ma-analysis-${shortHash(normalizeUrl(page.url))}`,
+    });
+  }
+  const seen = new Set();
+  return wanted.filter((link) => {
+    const key = normalizeUrl(link.url);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function payloadFor(link, appIdFor, lang) {
+  const labels = LABELS[lang] || LABELS.en;
+  const isPage = link.kind === "confluence" || link.kind === "analysis";
+  const appId = isPage && link.pageId ? appIdFor(hostOf(link.url)) : null;
+  if (appId) {
+    return {
+      globalId: `appId=${appId}&pageId=${link.pageId}`,
+      application: { ...CONFLUENCE_APP },
+      relationship: labels.wiki,
+      object: { url: link.url, title: link.title },
+    };
+  }
+  return {
+    globalId: link.globalId,
+    relationship: link.relationship,
+    object: { url: link.url, title: link.title },
+  };
+}
+
+function sameLink(a, b) {
+  return (
+    a.relationship === b.relationship &&
+    normalizeUrl(a.object?.url) === normalizeUrl(b.object?.url) &&
+    a.object?.title === b.object?.title
+  );
+}
+
+export function planRemoteLinks({ spec, existing = [], appId = null, lang = "en" }) {
+  const current = Array.isArray(existing) ? existing : [];
+  const byGlobalId = new Map(current.filter((l) => l?.globalId).map((l) => [l.globalId, l]));
+  // An explicit id belongs to one Confluence host, like one read from an existing link.
+  const at = typeof appId === "string" ? appId.indexOf("=") : -1;
+  const explicit = at > 0 ? [appId.slice(0, at), appId.slice(at + 1)] : null;
+  const appIdFor = (host) =>
+    explicit && explicit[0].toLowerCase() === host ? explicit[1] : confluenceAppId(current, host);
+  const write = [];
+  const skip = [];
+  const planned = new Set();
+  for (const link of wantedLinks(spec, { lang })) {
+    let payload = payloadFor(link, appIdFor, lang);
+    const target = normalizeUrl(link.url);
+    // A link this tool wrote earlier under its plain id stays the link for that URL:
+    // a global id cannot change without a delete, and nothing here deletes.
+    const ownPlain = current.find(
+      (l) =>
+        String(l?.globalId || "").startsWith("ma-") &&
+        l.globalId !== payload.globalId &&
+        normalizeUrl(l.object?.url) === target,
+    );
+    if (ownPlain)
+      payload = {
+        globalId: ownPlain.globalId,
+        relationship: link.relationship,
+        object: { url: link.url, title: link.title },
+      };
+    if (planned.has(payload.globalId)) {
+      skip.push({ globalId: payload.globalId, url: link.url, reason: "duplicate-global-id" });
+      continue;
+    }
+    planned.add(payload.globalId);
+    const own = byGlobalId.get(payload.globalId);
+    if (own) {
+      // Only an `ma-` link is ours to rewrite; a native Wiki Page link with the same id
+      // may be a person's, so it is left exactly as it is.
+      if (sameLink(own, payload))
+        skip.push({ globalId: payload.globalId, url: link.url, reason: "unchanged" });
+      else if (!String(own.globalId).startsWith("ma-"))
+        skip.push({ globalId: payload.globalId, url: link.url, reason: "already-linked" });
+      else write.push(payload);
+      continue;
+    }
+    const taken = current.some(
+      (l) => l?.globalId !== payload.globalId && normalizeUrl(l?.object?.url) === target,
+    );
+    if (taken) skip.push({ globalId: payload.globalId, url: link.url, reason: "already-linked" });
+    else write.push(payload);
+  }
+  return { write, skip };
+}
+
+function readJson(path, fallback) {
+  if (!path) return fallback;
+  if (!existsSync(path)) throw new Error(`no such file: ${path}`);
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+function main(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (
+      !["--spec", "--existing", "--app-id", "--lang"].includes(arg) ||
+      argv[i + 1] === undefined
+    ) {
+      process.stderr.write(`plan-remote-links: unknown or incomplete argument: ${arg}\n`);
+      return 2;
+    }
+    opts[arg.slice(2)] = argv[++i];
+  }
+  if (!opts.spec) {
+    process.stderr.write("plan-remote-links: --spec is required\n");
+    return 2;
+  }
+  let spec, existing;
+  try {
+    spec = readJson(opts.spec, {});
+    existing = readJson(opts.existing, []);
+  } catch (error) {
+    process.stderr.write(`plan-remote-links: ${error.message}\n`);
+    return 2;
+  }
+  const appId = opts["app-id"];
+  if (appId !== undefined && !(appId.indexOf("=") > 0 && appId.indexOf("=") < appId.length - 1)) {
+    process.stderr.write("plan-remote-links: --app-id must be <host>=<id>\n");
+    return 2;
+  }
+  if (appId) {
+    const host = appId.slice(0, appId.indexOf("=")).toLowerCase();
+    const hosts = wantedLinks(spec)
+      .filter((link) => link.pageId)
+      .map((link) => hostOf(link.url));
+    if (!hosts.includes(host))
+      process.stderr.write(`plan-remote-links: --app-id host ${host} matches no Confluence page\n`);
+  }
+  const plan = planRemoteLinks({
+    spec,
+    existing,
+    appId: opts["app-id"] || null,
+    lang: opts.lang || "en",
+  });
+  process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) process.exit(main(process.argv.slice(2)));