forgedock 1.18.0 → 1.19.0

package/scripts/ci-local/adapters/circleci.mjs

@@ -0,0 +1,101 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// circleci.mjs - .circleci/config.yml -> normalised jobs. Workflow job lists, branch filters, requires ordering,
+// commands/executors with simple parameters, docker service containers (host network). Contexts (secrets), orbs,
+// approvals, macOS executors off macOS, add_ssh_keys and deploy-named jobs are deferred-to-ci.
+
+import { Unsupported, branchMatches, jobId, deferred, notApplicable, secretLikeVar, DEPLOY_NAME, hostClass, parseDuration } from '../lib.mjs';
+import { stepsFromScript, loadDoc, parseSafe, baseJob } from './common.mjs';
+
+export const id = 'circleci';
+export const DEF_RE = /^\.circleci\/config\.ya?ml$/;
+const NOOP = new Set(['checkout', 'restore_cache', 'save_cache', 'persist_to_workspace', 'attach_workspace', 'store_artifacts', 'store_test_results', 'setup_remote_docker']);
+
+function subst(text, params) {
+  return String(text).replace(/<<\s*parameters\.([A-Za-z0-9_-]+)\s*>>/g, (_, k) => { if (!(k in params)) throw new Unsupported(`parameter ${k}`); return String(params[k]); })
+    .replace(/<<\s*(pipeline|[^>\s]+)[^>]*>>/g, (m) => { throw new Unsupported(`template ${m.slice(0, 40)}`); });
+}
+
+function expand(steps, doc, params, depth, out) {
+  if (depth > 4) throw new Unsupported('command nesting');
+  for (const st of steps || []) {
+    if (typeof st === 'string') { if (NOOP.has(st)) continue; if (doc.commands && doc.commands[st]) { expand(doc.commands[st].steps, doc, defaultsOf(doc.commands[st], {}), depth + 1, out); continue; } throw new Unsupported(`step ${st}`); }
+    const [k] = Object.keys(st); const v = st[k];
+    if (NOOP.has(k)) continue;
+    if (k === 'run') {
+      const o = typeof v === 'string' ? { command: v } : v;
+      if (o.when === 'on_fail' || o.when === 'never') continue;
+      out.push({ name: o.name || 'run', command: subst(o.command, params), env: Object.fromEntries(Object.entries(o.environment || {}).map(([a, b]) => [a, subst(b, params)])), wd: o.working_directory ? subst(o.working_directory, params) : '.' });
+      continue;
+    }
+    if (doc.commands && doc.commands[k]) { expand(doc.commands[k].steps, doc, defaultsOf(doc.commands[k], v || {}), depth + 1, out); continue; }
+    throw new Unsupported(`step ${k}`);
+  }
+}
+function defaultsOf(def, args) { const p = {}; for (const [k, d] of Object.entries(def.parameters || {})) p[k] = k in args ? args[k] : d && d.default; for (const [k, v] of Object.entries(args)) p[k] = v; return p; }
+
+const DEFAULT_PORTS = { postgres: 5432, mysql: 3306, mariadb: 3306, redis: 6379, mongo: 27017, rabbitmq: 5672, memcached: 11211, elasticsearch: 9200 };
+export function declaredPorts(d) {
+  if (Array.isArray(d.ports) && d.ports.length) return d.ports.map((p) => (/^\d+$/.test(String(p)) ? `${p}:${p}` : String(p)));
+  const base = String(d.image || '').split('/').pop().split(':')[0].replace(/^cimg-/, '');
+  const hit = DEFAULT_PORTS[base] || DEFAULT_PORTS[String(d.image || '').split('/').pop().split(':')[0]];
+  return hit ? [`${hit}:${hit}`] : [];
+}
+
+export function plan(a) {
+  const out = []; const warnings = []; const used = [];
+  for (const file of a.defFiles(DEF_RE)) {
+    const doc = loadDoc(a, file, parseSafe);
+    if (doc === undefined) { out.push(deferred(jobId('circleci', 'config'), 'circleci', file, 'config YAML unreadable')); continue; }
+    if (!doc || !doc.jobs) continue;
+    used.push(file);
+    if (doc.orbs) warnings.push(`${file}: orbs declared; jobs/commands from orbs are deferred-to-ci`);
+    const entries = [];
+    const wfs = Object.entries(doc.workflows || {}).filter(([k]) => k !== 'version');
+    if (!wfs.length && doc.jobs.build) entries.push({ job: 'build', name: 'build', cfg: {} });
+    for (const [wn, wf] of wfs) {
+      if (wf.when !== undefined || wf.unless !== undefined) { out.push(deferred(jobId('circleci', wn), 'circleci', wn, 'workflow when/unless conditions are not evaluated')); continue; }
+      for (const item of wf.jobs || []) {
+        const [jn, cfg] = typeof item === 'string' ? [item, {}] : [Object.keys(item)[0], Object.values(item)[0] || {}];
+        entries.push({ job: jn, name: cfg.name || jn, cfg, wf: wn });
+      }
+    }
+    const nameToId = {}; for (const e of entries) nameToId[e.name] = jobId('circleci', e.wf || '', e.name);
+    for (const e of entries) {
+      const jid = nameToId[e.name]; const jobDef = doc.jobs[e.job];
+      const def = (r) => out.push(deferred(jid, 'circleci', e.name, r));
+      try {
+        if (!jobDef) { def(`job ${e.job} defined by an orb or missing`); continue; }
+        const f = e.cfg.filters && e.cfg.filters.branches;
+        if (f && ((f.only && !branchMatches(a.headBranch || '', [].concat(f.only))) || (f.ignore && branchMatches(a.headBranch || '', [].concat(f.ignore))))) { out.push(notApplicable(jid, 'circleci', e.name, 'branch filter excludes this branch')); continue; }
+        if (e.cfg.context) { def('uses a context (secrets)'); continue; }
+        if (e.cfg.type === 'approval') { def('approval gate'); continue; }
+        if (e.cfg.matrix) { def('matrix job'); continue; }
+        if (DEPLOY_NAME.test(e.job)) { def('deploy/publish job'); continue; }
+        let exec = jobDef; if (jobDef.executor) { const ex = typeof jobDef.executor === 'string' ? jobDef.executor : jobDef.executor.name; if (!doc.executors || !doc.executors[ex]) { def(`executor ${ex} is not defined in this file`); continue; } exec = { ...doc.executors[ex], ...jobDef }; }
+        if (exec.macos && hostClass() !== 'darwin') { def('macOS executor'); continue; }
+        if (exec.machine && exec.machine.image && /windows/i.test(exec.machine.image)) { def('Windows executor'); continue; }
+        const params = defaultsOf(jobDef, Object.fromEntries(Object.entries(e.cfg).filter(([k]) => !['requires', 'filters', 'context', 'name', 'type', 'matrix'].includes(k))));
+        const steps = []; expand(jobDef.steps, doc, params, 0, steps);
+        if (jobDef.steps.some((s) => s && typeof s === 'object' && Object.keys(s)[0] === 'add_ssh_keys')) { def('add_ssh_keys'); continue; }
+        const services = [];
+        // forge#4040 (SEC-6): secondary containers never use host networking. Each runs on a per-job docker network and only
+        // its declared ports (a `ports:` list, else the image's well-known default) are published on 127.0.0.1.
+        if (Array.isArray(exec.docker) && exec.docker.length > 1) for (const d of exec.docker.slice(1)) services.push({ name: String(d.name || d.image).replace(/[^A-Za-z0-9_.-]/g, '-'), image: d.image, env: d.environment || {}, ports: declaredPorts(d), options: '' });
+        { const blind = services.filter((sv) => !sv.ports.length); if (blind.length) { def(`unknown service ports: ${blind.map((sv) => sv.image).join(', ')} (no ports: declared and no well-known default; unreachable without host networking)`); continue; } }
+        const env = Object.fromEntries(Object.entries({ ...(exec.environment || {}), ...(exec.docker && exec.docker[0] ? exec.docker[0].environment || {} : {}) }).map(([k, v]) => [k, subst(v, params)]));
+        const defined = new Set(Object.keys(env));
+        const all = steps.map((s) => s.command).join('\n');
+        const sv = secretLikeVar(all, defined);
+        if (sv) { def(`references credential-like variable $${sv}`); continue; }
+        Object.assign(env, { CIRCLE_BRANCH: a.headBranch || '', CIRCLE_SHA1: a.headSha, CIRCLE_WORKING_DIRECTORY: a.repo, CIRCLE_JOB: e.job });
+        const built = []; let defer = '';
+        for (const s of steps) { const r = stepsFromScript(s.command, { name: s.name, cwd: s.wd, env: s.env, repo: a.repo }); if (r.defer) defer = defer || r.defer; built.push(...r.steps); }
+        if (defer) { def(defer); continue; }
+        out.push(baseJob({ id: jid, source: 'circleci', name: e.name, env, steps: built, services, needs: (e.cfg.requires || []).map((r) => nameToId[r]).filter(Boolean), timeout_s: parseDuration(jobDef.no_output_timeout) }));
+      } catch (err) { if (err instanceof Unsupported) { def(`unsupported construct: ${err.message}`); continue; } throw err; }
+    }
+  }
+  return { jobs: out, warnings, used };
+}

package/scripts/ci-local/adapters/common.mjs

@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// common.mjs - what every source adapter shares: turning a script into classified steps, and the rule that a step
+// which installs system packages, deploys, or talks to a remote service is never run locally.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { commandExists, shellSplit, parseYaml, Degraded } from '../lib.mjs';
+import { splitBlock } from '../scoping.mjs';
+
+const SYSTEM = /^(sudo|apt|apt-get|aptitude|yum|dnf|apk|brew|choco|snap|zypper|pacman|port|winget|scoop|systemctl|service)(\s|$)/;
+const REMOTE = /^(docker\s+(push|login)|podman\s+push|kubectl|helm|terraform\s+(apply|destroy)|pulumi|aws|gcloud|az|gsutil|doctl|flyctl|fly\s+deploy|vercel|netlify|wrangler|heroku|firebase|npm\s+(publish|login|whoami|token)|yarn\s+npm\s+publish|pnpm\s+publish|twine\s+upload|cargo\s+(publish|login)|gem\s+push|git\s+push|git\s+remote\s+add|gh(\s|$)|curl\s+.*\|\s*(ba)?sh|ssh(\s|$)|scp(\s|$)|rsync\s+.*:|sentry-cli|codecov|slack)/;
+const INSTALL = /^(npm\s+(ci|install|i)|pnpm\s+(install|i)|yarn(\s+install)?|bun\s+install|pip3?\s+install|python3?\s+-m\s+pip\s+install|poetry\s+install|uv\s+(sync|pip\s+install)|pipenv\s+install|bundle\s+install|composer\s+install|go\s+mod\s+(download|tidy)|cargo\s+fetch|mvn\s+.*dependency:|gradle(w)?\s+dependencies|dotnet\s+restore)(\s|$)/;
+const SHELL_BUILTIN = new Set(['cd', 'echo', 'test', '[', '[[', 'export', 'set', 'true', 'false', 'exit', 'printf', 'source', '.', 'read', 'eval', 'exec', 'trap', 'unset', 'command', 'type', ':', 'if', 'for', 'while', 'case', 'until', 'function', 'local', 'declare', 'shift', 'wait', 'return', 'mkdir', 'rm', 'cp', 'mv', 'cat', 'ls', 'pwd', 'sleep', 'grep', 'sed', 'awk', 'find', 'sort', 'head', 'tail', 'wc', 'tr', 'cut', 'xargs', 'diff', 'touch', 'chmod', 'env', 'bash', 'sh', 'git', 'tee', 'basename', 'dirname', 'date', 'uname', 'which', 'tar', 'unzip', 'jq', 'yq', 'make', 'node', 'npm', 'npx']);
+
+// Classify one command line. Returns { kind, defer?, noop?, note? }.
+// Every command segment of a line: split on `&&`, `||`, `;`, `|`, `&`, newlines, `$(`, backticks and grouping, then drop
+// leading env assignments and control words, so `cd x && aws s3 sync` is judged on `aws`, not on `cd`. A quoted separator
+// over-splits, which only ever defers more (the safe direction).
+const LEAD_WORD = /^(?:(?:then|do|else|elif|if|while|until|time|exec|command|env|nohup|!)\s+)+/;
+function segments(cmd) {
+  return cmd.split(/&&|\|\||[;|&\n`(){}]|\$\(/).map((p) => p.trim().replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)+/, '').replace(LEAD_WORD, '').replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)+/, '')).filter(Boolean);
+}
+
+export function classifyCommand(cmd, repo, cwdRel) {
+  const first = cmd.trim().replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)+/, '');
+  const head3 = (t) => t.split(/\s+/).slice(0, 3).join(' ');
+  for (const seg of segments(cmd)) {
+    if (SYSTEM.test(seg)) return { kind: 'system', defer: `system-level command: ${head3(seg)}` };
+    if (REMOTE.test(seg)) return { kind: 'remote', defer: `remote-mutating or service command: ${head3(seg)}` };
+  }
+  // `curl ... | sh` spans a pipe, so it is matched on the whole line as well as per segment.
+  if (/\b(curl|wget)\b[^\n]*\|\s*(ba)?sh\b/.test(cmd)) return { kind: 'remote', defer: `remote-mutating or service command: ${head3(first)}` };
+  if (INSTALL.test(first)) {
+    if (/^(npm|pnpm|yarn|bun)\b/.test(first)) {
+      const nm = path.join(repo, cwdRel || '.', 'node_modules');
+      return fs.existsSync(nm) ? { kind: 'install', noop: true, note: 'node_modules present' } : { kind: 'install', note: 'dependency install (offline failure defers the job)' };
+    }
+    if (/^(go|cargo|mvn|gradle|dotnet)/.test(first)) return { kind: 'install', noop: true, note: 'the build tool fetches dependencies on demand' };
+    return { kind: 'install', noop: true, note: 'python/ruby/php dependency install is not run on the host; assumes a provisioned environment' };
+  }
+  return { kind: 'check' };
+}
+
+// Missing local tool for a simple command: the job is deferred, never failed for an absent binary.
+export function missingTool(cmd) {
+  const toks = shellSplit(cmd);
+  if (!toks) return '';
+  const i = toks.findIndex((t) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(t));
+  const t = i >= 0 ? toks[i] : '';
+  if (!t || t.includes('/') || SHELL_BUILTIN.has(t) || t.startsWith('.')) return '';
+  return commandExists(t) ? '' : t;
+}
+
+// Build normalised step objects for one `run` script. Lines are split only when provably independent.
+export function stepsFromScript(script, o) {
+  const parts = splitBlock(script);
+  const out = []; let defer = '';
+  parts.forEach((cmd, idx) => {
+    const c = classifyCommand(cmd, o.repo, o.cwd);
+    if (c.defer && !defer) defer = c.defer;
+    // A multi-line block is also scanned line by line for deferrable commands.
+    if (parts.length === 1 && cmd.includes('\n')) for (const l of cmd.split('\n')) { const lc = classifyCommand(l, o.repo, o.cwd); if (lc.defer && !defer) defer = lc.defer; }
+    if (c.noop) { out.push({ name: `${o.name || 'run'}`, command: cmd, cwd: o.cwd, env: o.env || {}, shell: o.shell, kind: 'install', noop: true, note: c.note }); return; }
+    out.push({
+      name: parts.length > 1 ? `${o.name || 'run'} [${idx + 1}/${parts.length}]` : (o.name || 'run'),
+      group: parts.length > 1 ? (o.name || 'run') : undefined,
+      command: cmd, cwd: o.cwd, env: o.env || {}, shell: o.shell, kind: c.kind, note: c.note,
+      continue_on_error: !!o.continue_on_error, timeout_s: o.timeout_s,
+    });
+  });
+  return { steps: out, defer };
+}
+
+// Resolve the shell invocation (argv minus the script file) for a CI `shell:` value; null when it cannot run here.
+export function shellArgv(shell) {
+  const s = (shell || '').trim();
+  if (!s) return ['bash', '-e'];
+  if (s === 'bash') return ['bash', '--noprofile', '--norc', '-eo', 'pipefail'];
+  if (s === 'sh') return ['sh', '-e'];
+  if (/^bash\b/.test(s)) return s.replace(/\s*\{0\}\s*$/, '').split(/\s+/);
+  if (/^sh\b/.test(s)) return s.replace(/\s*\{0\}\s*$/, '').split(/\s+/);
+  if (s === 'python') return ['python3'];
+  return null;
+}
+
+export function deepMerge(a, b) {
+  if (b === undefined) return a;
+  if (a && b && typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
+    const out = { ...a }; for (const [k, v] of Object.entries(b)) out[k] = k in a ? deepMerge(a[k], v) : v; return out;
+  }
+  return b;
+}
+
+// Trusted base definition merged with the PR's own edits (PR wins per key; a PR cannot delete a base job).
+export function loadDoc(a, file, parse) {
+  const { base, head } = a.readDefs(file);
+  const b = base != null ? parse(base) : null; const h = head != null ? parse(head) : null;
+  if (b === undefined || h === undefined) return undefined;
+  if (!b) return h; if (!h) return b;
+  return deepMerge(b, h);
+}
+
+export function parseSafe(text) {
+  // parseYaml throws Degraded when yq is absent (propagate) and Error on malformed YAML (undefined = unreadable).
+  try { return parseYaml(text); } catch (e) { if (e instanceof Degraded) throw e; return undefined; }
+}
+
+// Env and checkout conventions for jobs derived from non-GitHub CI systems.
+export function baseJob(o) {
+  return { id: o.id, source: o.source, name: o.name, cwd: '.', env: o.env || {}, services: o.services || [], steps: o.steps || [], needs: o.needs || [], timeout_s: o.timeout_s, deferred_reason: null, warnings: o.warnings || [], matrix: o.matrix };
+}
+
+export function globList(v) { return [].concat(v || []).filter((x) => typeof x === 'string'); }

package/scripts/ci-local/adapters/explicit.mjs

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// explicit.mjs - commands the operator declared in forge.yaml -> verification.ci_local.extra_commands.
+// Always merged into the plan. verification.commands is NOT repeated here: validate V2 already runs it as the fast pre-step.
+
+import { jobId } from '../lib.mjs';
+import { baseJob, stepsFromScript } from './common.mjs';
+
+export const id = 'explicit';
+
+export function plan(a) {
+  const jobs = [];
+  (a.config.extra_commands || []).forEach((c, i) => {
+    const cmd = typeof c === 'string' ? c : c && c.command; if (!cmd) return;
+    const name = typeof c === 'object' && c.name ? String(c.name) : cmd.split('\n')[0].slice(0, 60);
+    const r = stepsFromScript(String(cmd), { name, cwd: '.', env: {}, repo: a.repo });
+    jobs.push(baseJob({ id: jobId('explicit', String(i + 1)), source: 'explicit', name, steps: r.steps }));
+  });
+  return { jobs, warnings: [], used: [] };
+}

package/scripts/ci-local/adapters/github-actions.mjs

@@ -0,0 +1,349 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// github-actions.mjs - GitHub Actions workflows -> normalised jobs.
+// Reads workflows from the base ref (trusted) plus the PR's own edits, applies on.pull_request/push path filters,
+// dorny/paths-filter outputs and job `if:` conditions, and defers anything that cannot be proven locally.
+
+import path from 'node:path';
+import {
+  Unsupported, Degraded, parseYaml, branchMatches, matchesFilter, evalExpr, interpolate, condTrue, hostClass, jobId, deferred, notApplicable,
+  SECRET_REF, DEPLOY_NAME, commandExists, run, majorOf, str,
+} from '../lib.mjs';
+import { stepsFromScript, shellArgv } from './common.mjs';
+
+export const id = 'github-actions';
+export const DEF_RE = /^\.github\/workflows\/[^/]+\.ya?ml$/;
+
+const NOOP_ACTIONS = /^(actions\/checkout|actions\/cache(\/(restore|save))?|actions\/upload-artifact|step-security\/harden-runner|Swatinem\/rust-cache)(@|$)/;
+const SETUP = {
+  'actions/setup-node': { tool: 'node', key: 'node-version', local: () => process.version },
+  'actions/setup-python': { tool: 'python3', key: 'python-version', local: () => run('python3', ['--version']).out.trim() },
+  'actions/setup-go': { tool: 'go', key: 'go-version', local: () => run('go', ['version']).out.trim() },
+  'actions/setup-java': { tool: 'java', key: 'java-version', local: () => { const r = run('java', ['-version']); return (r.err + r.out).split('\n')[0]; } },
+  'actions/setup-dotnet': { tool: 'dotnet', key: 'dotnet-version', local: () => run('dotnet', ['--version']).out.trim() },
+  'ruby/setup-ruby': { tool: 'ruby', key: 'ruby-version', local: () => run('ruby', ['--version']).out.trim() },
+  'oven-sh/setup-bun': { tool: 'bun', key: 'bun-version', local: () => run('bun', ['--version']).out.trim() },
+  'astral-sh/setup-uv': { tool: 'uv', key: 'version', local: () => run('uv', ['--version']).out.trim() },
+  'pnpm/action-setup': { tool: 'pnpm', key: 'version', local: () => run('pnpm', ['--version']).out.trim() },
+  'dtolnay/rust-toolchain': { tool: 'cargo', key: 'toolchain', local: () => run('cargo', ['--version']).out.trim() },
+  'shivammathur/setup-php': { tool: 'php', key: 'php-version', local: () => run('php', ['--version']).out.split('\n')[0] },
+  'denoland/setup-deno': { tool: 'deno', key: 'deno-version', local: () => run('deno', ['--version']).out.split('\n')[0] },
+};
+const SHELLCHECK_ACTIONS = /^(ludeeus\/action-shellcheck|reviewdog\/action-shellcheck)(@|$)/;
+
+function events(on) {
+  if (on === undefined || on === null) return {};
+  if (typeof on === 'string') return { [on]: {} };
+  if (Array.isArray(on)) return Object.fromEntries(on.map((e) => [e, {}]));
+  return Object.fromEntries(Object.entries(on).map(([k, v]) => [k, v && typeof v === 'object' ? v : {}]));
+}
+
+function pathsOk(cfg, changed) {
+  if (!changed.length) return true;
+  if (Array.isArray(cfg.paths)) return changed.some((f) => matchesFilter(f, cfg.paths));
+  if (Array.isArray(cfg['paths-ignore'])) return changed.some((f) => !matchesFilter(f, cfg['paths-ignore']));
+  return true;
+}
+
+function branchOk(cfg, branch) {
+  if (Array.isArray(cfg.branches)) return branchMatches(branch, cfg.branches);
+  if (Array.isArray(cfg['branches-ignore'])) return !branchMatches(branch, cfg['branches-ignore']);
+  return true;
+}
+
+// Does this workflow gate a pull request into the base branch? Returns '' when yes, else the reason it does not.
+function gateReason(ev, a) {
+  const names = Object.keys(ev);
+  if (ev.pull_request) {
+    const c = ev.pull_request;
+    if (!branchOk(c, a.baseBranch)) return `pull_request branches filter excludes base ${a.baseBranch}`;
+    if (!pathsOk(c, a.changed)) return 'pull_request path filter selects none of the changed files';
+    return '';
+  }
+  if (ev.push) {
+    const c = ev.push;
+    if (Array.isArray(c.tags) && !Array.isArray(c.branches) && !Array.isArray(c['branches-ignore'])) return 'push is tag-only';
+    if (!branchOk(c, a.headBranch || '')) return `push branches filter excludes ${a.headBranch}`;
+    if (!pathsOk(c, a.changed)) return 'push path filter selects none of the changed files';
+    return '';
+  }
+  return `not a pull-request gate (events: ${names.join(', ') || 'none'})`;
+}
+
+function mergeDocs(baseText, headText) {
+  const b = baseText != null ? safe(baseText) : null; const h = headText != null ? safe(headText) : null;
+  if (b === undefined || h === undefined) return undefined;
+  if (!b) return h; if (!h) return b;
+  return { ...h, jobs: { ...(b.jobs || {}), ...(h.jobs || {}) } };
+}
+function safe(t) { try { return parseYaml(t); } catch (e) { if (e instanceof Degraded) throw e; return undefined; } }
+
+function topo(jobs) {
+  const ids = Object.keys(jobs); const done = new Set(); const out = [];
+  const needsOf = (j) => [].concat(jobs[j].needs || []).filter((n) => typeof n === 'string');
+  let guard = ids.length + 2;
+  while (out.length < ids.length && guard-- > 0) for (const j of ids) if (!done.has(j) && needsOf(j).every((n) => done.has(n) || !(n in jobs))) { done.add(j); out.push(j); }
+  for (const j of ids) if (!done.has(j)) out.push(j); // cycles: processed last, deferred by missing needs
+  return out;
+}
+
+export function expandMatrix(m, ctx) {
+  if (m === undefined || m === null) return [{}];
+  if (typeof m === 'string') throw new Unsupported('dynamic matrix');
+  const base = {}; for (const [k, v] of Object.entries(m)) if (!['include', 'exclude'].includes(k)) { let val = v; if (typeof val === 'string') val = interpolate(val, ctx); if (!Array.isArray(val)) throw new Unsupported('dynamic matrix axis ' + k); base[k] = val; }
+  let combos = [{}];
+  for (const [k, vals] of Object.entries(base)) combos = combos.flatMap((c) => vals.map((v) => ({ ...c, [k]: v })));
+  if (!Object.keys(base).length) combos = [];
+  const ex = Array.isArray(m.exclude) ? m.exclude : [];
+  combos = combos.filter((c) => !ex.some((e) => Object.entries(e).every(([k, v]) => c[k] === v)));
+  // GitHub include semantics (forge#4040): an entry extends every combo whose ORIGINAL axis values all match it (an entry
+  // naming no original axis matches every combo); an entry that matches no combo is added as a new combo. Original axis
+  // values are never overwritten; extra keys are.
+  for (const inc of Array.isArray(m.include) ? m.include : []) {
+    const keys = Object.keys(inc).filter((k) => k in base);
+    const targets = Object.keys(base).length ? combos.filter((c) => keys.every((k) => c[k] === inc[k])) : [];
+    if (targets.length) { for (const t of targets) for (const [k, v] of Object.entries(inc)) if (!(k in base)) t[k] = v; }
+    else combos.push({ ...inc });
+  }
+  return combos.length ? combos : [{}];
+}
+
+function osClass(runsOn) {
+  const labels = [].concat(runsOn && runsOn.labels ? runsOn.labels : runsOn).filter((x) => typeof x === 'string').map((x) => x.toLowerCase());
+  if (!labels.length) return { reason: 'runs-on missing' };
+  if (labels.includes('self-hosted') || (runsOn && runsOn.group)) return { reason: 'self-hosted runner' };
+  for (const l of labels) { if (/windows/.test(l)) return { os: 'win32', label: l }; if (/macos|mac-?os/.test(l)) return { os: 'darwin', label: l }; if (/ubuntu|linux|debian|arm64|x64/.test(l)) return { os: 'linux', label: l }; }
+  return { reason: `unknown runner label ${labels.join(',')}` };
+}
+function hostRuns(os) { const h = hostClass(); return os === 'linux' ? h === 'linux' || h === 'darwin' : os === h; }
+
+// forge#4040 (SEC-5, FIX-2): no expression whose value could carry attacker-influenced text is ever substituted into script
+// text. A `github.*` or `env.*` expression (env values are themselves expanded from github.* at plan time, so
+// `${{ env.X }}` is the indirect form of the same injection) is evaluated into an environment VALUE and the script gets a
+// quoted shell variable reference. Any other expression is substituted literally only when its value is inert
+// ([A-Za-z0-9_./:@+,=-]); otherwise it goes through the environment too.
+const INERT = /^[A-Za-z0-9_.\/:@+,=-]*$/;
+function quoteState(before) {
+  let q = '';
+  for (let i = 0; i < before.length; i++) {
+    const c = before[i];
+    if (q === "'") { if (c === "'") q = ''; continue; }
+    if (c === '\\') { i++; continue; }
+    if (q === '"') { if (c === '"') q = ''; continue; }
+    if (c === '"' || c === "'") q = c;
+  }
+  return q;
+}
+export function interpolateRunScript(text, ctx, env, shell) {
+  if (typeof text !== 'string' || !text.includes('${{')) return text;
+  const posix = !shell || /^\s*(bash|sh)(\s|$)/.test(String(shell));
+  let n = 0;
+  return text.replace(/\$\{\{([\s\S]*?)\}\}/g, (m, e, off, whole) => {
+    const v = str(evalExpr(e, ctx));
+    const tainted = /(^|[^A-Za-z0-9_.])(github|env)\s*(\.|\[)/.test(e);
+    if (!tainted && INERT.test(v)) return v;
+    if (!posix) throw new Unsupported('expression with a non-inert value in a non-POSIX shell script');
+    const name = `FORGE_CI_EXPR_${++n}`; env[name] = v;
+    const q = quoteState(whole.slice(0, off));
+    return q === '"' ? `\${${name}}` : q === "'" ? `'"\${${name}}"'` : `"\${${name}}"`;
+  });
+}
+
+function versionNote(action, step, ctx) {
+  const spec = SETUP[action]; if (!spec) return '';
+  const want = interpolate(String((step.with || {})[spec.key] ?? ''), ctx);
+  if (!want || /lts|latest|stable|nightly|[<>~^*]|file/i.test(want) || /^\W*$/.test(want)) return '';
+  const w = majorOf(want); if (w === null) return '';
+  const l = majorOf(spec.local() || '');
+  return l !== null && l !== w ? `${action} wants ${spec.key} ${want}; local is ${String(spec.local()).slice(0, 40)} (major differs)` : '';
+}
+
+function shellcheckStep(action, step, ctx, a) {
+  const w = step.with || {};
+  const isLudeeus = action.startsWith('ludeeus');
+  const dir = String(interpolate(String(isLudeeus ? (w.scandir || '.') : (w.path || '.')), ctx)).replace(/^\.\//, '') || '.';
+  const ign = String(w.ignore_paths || w.exclude || '').split(/\s+/).filter(Boolean).map((p) => p.replace(/^\.\//, '').replace(/\/$/, ''));
+  const ignNames = String(w.ignore_names || '').split(/\s+/).filter(Boolean);
+  const extra = String(w.additional_files || '').split(/\s+/).filter(Boolean);
+  const sev = isLudeeus ? w.severity : null;
+  const files = a.tracked.filter((f) => /\.(sh|bash|ksh)$/.test(f) && (dir === '.' || f === dir || f.startsWith(dir.replace(/\/$/, '') + '/')) && !ign.some((p) => f === p || f.startsWith(p + '/')) && !ignNames.includes(path.posix.basename(f)));
+  for (const f of extra) if (a.tracked.includes(f) && !files.includes(f)) files.push(f);
+  const flags = [];
+  if (sev) flags.push('-S', String(sev));
+  if (!isLudeeus && w.shellcheck_flags !== '') flags.push(...String(w.shellcheck_flags ?? '--external-sources').split(/\s+/).filter(Boolean));
+  if (isLudeeus && w.shellcheck_opts) flags.push(...String(w.shellcheck_opts).split(/\s+/).filter(Boolean));
+  if (!commandExists('shellcheck')) return { missing: 'shellcheck' };
+  if (!files.length) return { noop: true, note: `no shell files under ${dir}` };
+  return { command: ['shellcheck', ...flags, ...files.sort()].map((t) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(t) ? t : `'${t.replace(/'/g, "'\\''")}'`)).join(' ') };
+}
+
+// dorny/paths-filter: evaluate each filter against the changed files; returns { name: 'true'|'false', changes: json }.
+function pathsFilterOutputs(step, ctx, a) {
+  const w = step.with || {};
+  let text = w.filters;
+  if (typeof text !== 'string') throw new Unsupported('paths-filter without inline filters');
+  text = interpolate(text, ctx);
+  if (!/\n/.test(text) && /\.ya?ml$/.test(text.trim())) {
+    const f = text.trim().replace(/^\.\//, '');
+    const body = a.readDefs(f); const t = body.head != null ? body.head : body.base;
+    if (t == null) throw new Unsupported('paths-filter file ' + f);
+    text = t;
+  }
+  const doc = parseYaml(text);
+  if (!doc || typeof doc !== 'object') throw new Unsupported('paths-filter filters unreadable');
+  const out = {}; const hit = [];
+  const flat = (v) => (typeof v === 'string' ? [v] : Array.isArray(v) ? v.flatMap(flat) : v && typeof v === 'object' ? Object.values(v).flatMap(flat) : []);
+  for (const [name, spec] of Object.entries(doc)) {
+    const pats = flat(spec);
+    const ok = a.changed.some((f) => matchesFilter(f, pats));
+    out[name] = ok ? 'true' : 'false'; if (ok) hit.push(name);
+  }
+  out.changes = JSON.stringify(hit);
+  return out;
+}
+
+function parseServices(svcs, ctx) {
+  const out = [];
+  for (const [name, s] of Object.entries(svcs || {})) {
+    if (!s || typeof s.image !== 'string') throw new Unsupported('service without image');
+    if (s.credentials) throw new Unsupported('service credentials');
+    const env = {}; for (const [k, v] of Object.entries(s.env || {})) env[k] = String(interpolate(String(v), ctx));
+    out.push({ name, image: String(interpolate(s.image, ctx)), env, ports: (s.ports || []).map(String), options: s.options ? String(interpolate(String(s.options), ctx)) : '' });
+  }
+  return out;
+}
+
+export function plan(a) {
+  const jobsOut = []; const warnings = []; const used = [];
+  const files = a.defFiles(DEF_RE);
+  for (const file of files) {
+    const { base, head } = a.readDefs(file);
+    const doc = mergeDocs(base, head);
+    const wfName = path.posix.basename(file).replace(/\.ya?ml$/, '');
+    if (doc === undefined) { warnings.push(`${file}: unreadable YAML; its jobs are deferred-to-ci`); jobsOut.push(deferred(jobId('gha', wfName), 'github-actions', file, 'workflow YAML unreadable')); continue; }
+    if (!doc || typeof doc !== 'object' || !doc.jobs) continue;
+    used.push(file);
+    const ev = events(doc.on !== undefined ? doc.on : doc.true);
+    if (ev.pull_request_target) { jobsOut.push(deferred(jobId('gha', wfName), 'github-actions', doc.name || file, 'pull_request_target workflow runs with base-branch secrets')); continue; }
+    const why = gateReason(ev, a);
+    if (why) { jobsOut.push(notApplicable(jobId('gha', wfName), 'github-actions', doc.name || file, why)); continue; }
+    planWorkflow(file, wfName, doc, a, jobsOut, warnings);
+  }
+  return { jobs: jobsOut, warnings, used };
+}
+
+function planWorkflow(file, wfName, doc, a, out, warnings) {
+  const wfEnv = doc.env || {};
+  const base = { github: { event_name: 'pull_request', base_ref: a.baseBranch, head_ref: a.headBranch || '', ref: `refs/heads/${a.headBranch || ''}`, ref_name: a.headBranch || '', ref_type: 'branch', sha: a.headSha, repository: a.repository || '', workspace: a.repo, event: { pull_request: { base: { sha: a.baseSha, ref: a.baseBranch, repo: { full_name: a.repository || '' } }, head: { sha: a.headSha, ref: a.headBranch || '', repo: { fork: false, full_name: a.repository || '' } }, draft: false, labels: [] } } }, runner: { os: { linux: 'Linux', darwin: 'macOS', win32: 'Windows' }[hostClass()], arch: process.arch === 'arm64' ? 'ARM64' : 'X64', temp: process.env.TMPDIR || '/tmp' } };
+  const jobs = doc.jobs; const results = {}; // jobKey -> { status, outputs }
+  const planOne = (key) => {
+    const job = jobs[key] || {};
+    const jid = jobId('gha', wfName, key);
+    let name = key;
+    const needs = [].concat(job.needs || []).filter((n) => typeof n === 'string');
+    const baseCtx = { ...base, env: {}, needs: {}, steps: undefined };
+    for (const n of needs) if (results[n] && results[n].outputs) baseCtx.needs[n] = { outputs: results[n].outputs, result: results[n].status === 'applicable' ? 'success' : 'skipped' };
+    try { if (typeof job.name === 'string') name = String(interpolate(job.name, { ...baseCtx, matrix: undefined })) || key; } catch { name = job.name; }
+    const def = (reason, extra) => { out.push(deferred(jid, 'github-actions', name, reason, { needs: needs.map((n) => jobId('gha', wfName, n)), ...extra })); results[key] = { status: 'deferred', outputs: null }; };
+    const na = (reason) => { out.push(notApplicable(jid, 'github-actions', name, reason)); results[key] = { status: 'skipped', outputs: {} }; };
+
+    try {
+      // needs: a deferred or missing dependency means the job cannot be proven here
+      const badNeed = needs.find((n) => !results[n] || results[n].status === 'deferred');
+      const skipNeed = needs.find((n) => results[n] && results[n].status === 'skipped');
+      if (badNeed && !(typeof job.if === 'string' && /always\(\)/.test(job.if))) return def(`needs ${badNeed}, which is not run locally`);
+      if (skipNeed && !(typeof job.if === 'string' && /always\(\)/.test(job.if))) return na(`needs ${skipNeed}, which was skipped`);
+      if (job.uses) return def('reusable workflow job');
+      if (job.container) return def('job runs in a container');
+      if (job.environment) return def('environment-protected job (deploy)');
+      if (job.if !== undefined && !condTrue(job.if, { ...baseCtx, env: wfEnv })) return na(`job if: ${String(job.if).trim().slice(0, 80)} is false`);
+      if (DEPLOY_NAME.test(key) || DEPLOY_NAME.test(String(job.name || ''))) return def('deploy/publish job');
+      const scanJob = JSON.stringify({ ...job, steps: (job.steps || []).map((s) => (s && s.uses && (NOOP_ACTIONS.test(s.uses) || SETUP[String(s.uses).split('@')[0]]) ? { ...s, with: undefined } : s)) });
+      if (SECRET_REF.test(scanJob) || SECRET_REF.test(JSON.stringify(wfEnv))) return def('references secrets');
+      if (job.permissions && job.permissions['id-token'] === 'write') return def('requests an OIDC token');
+
+      const matrixCtx = { ...baseCtx, env: wfEnv };
+      const combos = expandMatrix(job.strategy && job.strategy.matrix, matrixCtx);
+      const variants = []; let chosen = null;
+      for (const combo of combos) {
+        const cctx = { ...baseCtx, matrix: combo, env: wfEnv };
+        let ro = job['runs-on']; if (typeof ro === 'string') ro = interpolate(ro, cctx); else if (Array.isArray(ro)) ro = ro.map((x) => interpolate(x, cctx));
+        const c = osClass(ro);
+        const tag = Object.keys(combo).length ? Object.entries(combo).map(([k, v]) => `${k}=${typeof v === 'object' ? JSON.stringify(v) : v}`).join(',') : '';
+        if (c.reason) { variants.push(`${tag || 'default'}: ${c.reason}`); continue; }
+        if (!hostRuns(c.os)) { variants.push(`${tag || c.label}: ${c.label} (host is ${hostClass()})`); continue; }
+        if (chosen) { variants.push(`${tag || c.label}: matrix variant not run locally`); continue; }
+        chosen = { combo, ctx: cctx, tag };
+      }
+      if (!chosen && combos.length === 1) return def(variants[0].replace(/^[^:]*: /, ''));
+      if (variants.length) out.push(deferred(jobId(jid, 'variants'), 'github-actions', name, `${variants.length} variant(s) not run on this host: ${variants.slice(0, 3).join('; ')}${variants.length > 3 ? '; ...' : ''}`, { variants: variants.length }));
+      if (!chosen) { results[key] = { status: 'deferred', outputs: null }; return; }
+      const built = buildJob(file, wfName, key, jid, name, job, doc, chosen, needs, wfEnv, a, warnings);
+      if (built.defer) return def(built.defer);
+      results[key] = { status: 'applicable', outputs: built.outputs };
+      out.push(built.job);
+    } catch (e) {
+      if (e instanceof Unsupported) return def(`unsupported construct: ${e.message}`);
+      throw e;
+    }
+  };
+  for (const key of topo(jobs)) planOne(key);
+}
+
+function buildJob(file, wfName, key, jid, name, job, doc, chosen, needs, wfEnv, a, warnings) {
+  const ctx = chosen.ctx;
+  const jobEnvRaw = { ...wfEnv, ...(job.env || {}) };
+  const env = {};
+  for (const [k, v] of Object.entries(jobEnvRaw)) env[k] = String(interpolate(String(v), ctx));
+  ctx.env = env;
+  const defaults = { ...(doc.defaults && doc.defaults.run), ...(job.defaults && job.defaults.run) };
+  const steps = []; const notes = []; const stepsCtx = {}; ctx.steps = stepsCtx;
+  const toolWarn = [];
+  let outputs = {};
+  for (const [i, st] of (job.steps || []).entries()) {
+    if (!st) continue;
+    if (st.if !== undefined && !condTrue(st.if, ctx)) continue;
+    const label = st.name ? String(interpolate(String(st.name), ctx)) : (st.uses ? String(st.uses) : `step ${i + 1}`);
+    const senv = {}; for (const [k, v] of Object.entries(st.env || {})) senv[k] = String(interpolate(String(v), ctx));
+    if (st.uses) {
+      const action = String(st.uses).split('@')[0];
+      if (NOOP_ACTIONS.test(String(st.uses))) continue;
+      if (SETUP[action]) {
+        if (!commandExists(SETUP[action].tool)) return { defer: `toolchain not installed locally: ${SETUP[action].tool} (${action})` };
+        const n = versionNote(action, st, ctx); if (n) toolWarn.push(n);
+        continue;
+      }
+      if (/^dorny\/paths-filter$/.test(action)) { stepsCtx[st.id || `step${i}`] = { outputs: pathsFilterOutputs(st, ctx, a) }; continue; }
+      if (SHELLCHECK_ACTIONS.test(String(st.uses))) {
+        const sc = shellcheckStep(action, st, ctx, a);
+        if (sc.missing) return { defer: `tool not installed: ${sc.missing}` };
+        if (sc.noop) continue;
+        steps.push({ name: label, command: sc.command, cwd: '.', env: { ...senv }, shell: 'bash', kind: 'check' });
+        continue;
+      }
+      return { defer: `unknown action ${st.uses}` };
+    }
+    if (typeof st.run === 'string') {
+      const script = interpolateRunScript(st.run, { ...ctx, env: { ...ctx.env, ...senv } }, senv, st.shell || defaults.shell);
+      const cwd = st['working-directory'] || defaults['working-directory'] || '.';
+      const shell = st.shell || defaults.shell;
+      if (!shellArgv(shell)) return { defer: `shell ${shell} is not available locally` };
+      const r = stepsFromScript(script, { name: label, cwd: String(interpolate(String(cwd), ctx)), env: senv, shell, repo: a.repo, continue_on_error: st['continue-on-error'] === true, timeout_s: st['timeout-minutes'] ? Number(st['timeout-minutes']) * 60 : undefined });
+      if (r.defer) return { defer: r.defer };
+      steps.push(...r.steps);
+      continue;
+    }
+    return { defer: `unsupported step shape at index ${i}` };
+  }
+  // job outputs resolved from dorny steps (the `changes` job pattern)
+  for (const [k, v] of Object.entries(job.outputs || {})) { try { outputs[k] = String(interpolate(String(v), ctx)); } catch { /* left unresolved: needs.X.outputs.k is Unsupported downstream */ } }
+  if (!steps.length && !Object.keys(outputs).length && !(job.steps || []).length) return { defer: 'job has no steps' };
+  let services = [];
+  if (job.services) services = parseServices(job.services, ctx);
+  warnings.push(...toolWarn.map((w) => `${jid}: ${w}`));
+  const timeout_s = job['timeout-minutes'] ? Number(job['timeout-minutes']) * 60 : undefined;
+  const j = { id: jid, source: 'github-actions', name, workflow: file, cwd: '.', env, services, steps, needs: needs.map((n) => jobId('gha', wfName, n)), timeout_s, matrix: chosen.tag || undefined, deferred_reason: null, warnings: toolWarn, version_drift: toolWarn.length ? toolWarn : undefined, resolves_outputs: Object.keys(outputs).length > 0 && !steps.length };
+  if (!steps.length) { j.not_applicable = Object.keys(outputs).length ? 'resolved locally (path-filter outputs only)' : 'no runnable steps'; }
+  return { job: j, outputs };
+}