mandrel-platform 1.4.2 → 1.5.1

package/scripts/check-workflow-portability.mjs

@@ -39,6 +39,20 @@
  *      job". Requires git history (run CI checkout with fetch-depth: 0); the
  *      check degrades to a skipped NOTE when the pinned blob is unreachable.
  *
+ *   4. `runs-on: ${{ inputs.runner }}` — consuming a `runner` input RAW is
+ *      PROHIBITED. GitHub does not parse a JSON-array *string* in that
+ *      position: it takes the entire text as ONE label name, so the
+ *      documented `'["self-hosted","my-runner"]'` form matches no runner and
+ *      every job sits `queued` until the 24-hour timeout. This one is worse
+ *      than the others because it is not even loud — no job starts, so there
+ *      are no logs, and `gh pr checks` reports `pending 0`, indistinguishable
+ *      from a busy fleet. Normalize to
+ *      `fromJSON(startsWith(inputs.runner, '[') && inputs.runner ||
+ *      format('"{0}"', inputs.runner))`, which accepts both documented
+ *      shapes. (Caused #419 / v1.5.0; behaviour is covered by
+ *      check-runner-runs-on.test.mjs, which evaluates the real expression
+ *      rather than matching its spelling.)
+ *
  * What this lint deliberately does NOT flag: `${{ }}` in `runs.steps[].with`
  * (e.g. `dest: ${{ inputs['pnpm-dest'] || format('{0}/pnpm', runner.temp) }}`)
  * is a VALID runtime expression. The lint only inspects `description` and
@@ -266,6 +280,31 @@ export function checkWorkflowContent(content) {
     }
   }
 
+
+  // Rule 4: no `runs-on` that consumes a `runner` input raw. GitHub does not
+  // parse a JSON-array STRING in that position — it takes the whole text as one
+  // label name — so the documented `'["self-hosted","my-runner"]'` form matches
+  // no runner and every job sits `queued` until the 24-hour timeout. The failure
+  // is silent (no job starts, so no logs, and `gh pr checks` shows `pending 0`),
+  // which is why it needs a static tripwire as well as the behavioural guard in
+  // check-runner-runs-on.test.mjs.
+  content.split("\n").forEach((raw, idx) => {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("runs-on:")) return;
+    const m = trimmed.match(/^runs-on:\s*\$\{\{(.+)\}\}\s*$/);
+    if (!m) return;
+    if (m[1].trim() !== "inputs.runner") return;
+    violations.push({
+      line: idx + 1,
+      message:
+        `\`runs-on: \${{ inputs.runner }}\` consumes the input raw — a ` +
+        `JSON-encoded label-array string resolves to ONE unmatchable label ` +
+        `name and the job queues until the 24-hour timeout, silently. ` +
+        `Normalize it: \`fromJSON(startsWith(inputs.runner, '[') && ` +
+        `inputs.runner || format('"{0}"', inputs.runner))\`.`,
+    });
+  });
+
   return violations;
 }
 

package/scripts/check-workflow-portability.test.mjs

@@ -197,3 +197,69 @@ test("parseArgs: --no-pin-check, dir overrides, and --help are parsed", () => {
     help: true,
   });
 });
+
+// ---------------------------------------------------------------------------
+// Rule 4 — `runs-on` must not consume a `runner` input raw (Story #421)
+// ---------------------------------------------------------------------------
+
+/** A minimal reusable workflow whose single job's `runs-on` is `value`. */
+function runnerWorkflow(value) {
+  return [
+    "on:",
+    "  workflow_call:",
+    "    inputs:",
+    "      runner:",
+    "        required: false",
+    "        type: string",
+    "        default: 'ubuntu-latest'",
+    "jobs:",
+    "  build:",
+    `    runs-on: ${value}`,
+    "    steps:",
+    "      - run: echo hi",
+    "",
+  ].join("\n");
+}
+
+const NORMALIZED =
+  "${{ fromJSON(startsWith(inputs.runner, '[') && inputs.runner " +
+  "|| format('\"{0}\"', inputs.runner)) }}";
+
+test("Rule 4: a raw `runs-on: ${{ inputs.runner }}` is a violation", () => {
+  const violations = checkWorkflowContent(runnerWorkflow("${{ inputs.runner }}"));
+  assert.equal(violations.length, 1);
+  assert.equal(violations[0].line, 10);
+  assert.match(violations[0].message, /consumes the input raw/);
+  // The message must name the failure mode, not just the rule — a silent
+  // 24-hour queue is not something a reader infers from "normalize this".
+  assert.match(violations[0].message, /queues until the 24-hour timeout/);
+});
+
+test("Rule 4: the normalized form is clean", () => {
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow(NORMALIZED)), []);
+});
+
+test("Rule 4: a hardcoded `runs-on` is untouched", () => {
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow("ubuntu-latest")), []);
+});
+
+test("Rule 4: an unrelated expression in `runs-on` is untouched", () => {
+  // Only the exact raw-input read is flagged; a caller doing its own
+  // normalization or reading a different context is none of this rule's business.
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow("${{ fromJSON(vars.CI_RUNNER) }}")), []);
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow("${{ inputs.runner-label }}")), []);
+});
+
+test("Rule 4: only reusable workflows are checked", () => {
+  // A `push`-triggered workflow has no workflow_call interface to break.
+  const plain = [
+    "on:",
+    "  push:",
+    "    branches: [main]",
+    "jobs:",
+    "  build:",
+    "    runs-on: ${{ inputs.runner }}",
+    "",
+  ].join("\n");
+  assert.deepEqual(checkWorkflowContent(plain), []);
+});

package/scripts/check-wrangler-baseline.mjs

@@ -63,6 +63,8 @@ import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 
+import { isDirectInvocation } from './lib/entry-guard.mjs';
+
 // ---------------------------------------------------------------------------
 // CLI argument parsing
 // ---------------------------------------------------------------------------
@@ -153,13 +155,114 @@ export function resolveConfigPath(explicitFile, cwd = process.cwd()) {
 // ---------------------------------------------------------------------------
 
 /**
- * Parse JSON tolerating `//` line comments and block comments (jsonc).
+ * Skip past a JSON string literal, honouring backslash escapes.
+ *
+ * @param {string} text Full document.
+ * @param {number} start Index of the opening quote.
+ * @returns {number} Index just past the closing quote (or `text.length`).
+ */
+function skipString(text, start) {
+  let i = start + 1;
+  while (i < text.length) {
+    if (text[i] === '\\') {
+      i += 2;
+      continue;
+    }
+    if (text[i] === '"') return i + 1;
+    i += 1;
+  }
+  return i;
+}
+
+/**
+ * Blank out `//` line comments and block comments, leaving every other byte —
+ * string-literal contents included — untouched.
+ *
+ * Character-scanned rather than regex-replaced. A regex stripping `//` to
+ * end-of-line cannot tell a comment from the `//` inside a string: the
+ * previous `(^|[^:])//` guard special-cased the scheme colon in
+ * `"https://…"`, but `"a//b"` still lost its tail. Comment bytes are replaced
+ * with spaces (newlines preserved) rather than deleted, so every offset is
+ * unchanged and a `JSON.parse` error still reports the position it actually
+ * occupies in the file the operator is looking at.
+ *
+ * @param {string} text
+ * @returns {string} Same length as `text`, comments blanked.
+ */
+function blankComments(text) {
+  const out = text.split('');
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] === '"') {
+      i = skipString(text, i);
+      continue;
+    }
+    if (text[i] === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') {
+        out[i] = ' ';
+        i += 1;
+      }
+      continue;
+    }
+    if (text[i] === '/' && text[i + 1] === '*') {
+      out[i] = ' ';
+      out[i + 1] = ' ';
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) {
+        if (text[i] !== '\n') out[i] = ' ';
+        i += 1;
+      }
+      if (i < text.length) {
+        out[i] = ' ';
+        out[i + 1] = ' ';
+        i += 2;
+      }
+      continue;
+    }
+    i += 1;
+  }
+  return out.join('');
+}
+
+/**
+ * Blank out trailing commas — a `,` whose next significant character closes
+ * its object or array. Legal JSONC, rejected by `JSON.parse`.
+ *
+ * Runs AFTER {@link blankComments} so a comment sitting between the comma and
+ * its closing brace (`[1, /* note *\/ ]`) cannot hide the trailing comma. Like
+ * that pass it substitutes spaces rather than deleting, preserving offsets.
+ *
+ * @param {string} text Comment-blanked document.
+ * @returns {string} Same length as `text`, trailing commas blanked.
+ */
+function blankTrailingCommas(text) {
+  const out = text.split('');
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] === '"') {
+      i = skipString(text, i);
+      continue;
+    }
+    if (text[i] === ',') {
+      let j = i + 1;
+      while (j < text.length && /\s/.test(text[j])) j += 1;
+      if (text[j] === '}' || text[j] === ']') out[i] = ' ';
+    }
+    i += 1;
+  }
+  return out.join('');
+}
+
+/**
+ * Parse JSON tolerating what the `.jsonc` extension names: `//` line comments,
+ * block comments, and trailing commas in objects and arrays. String-literal
+ * contents pass through byte-identical.
+ *
  * @param {string} text
  * @returns {any}
  */
 export function parseJsonc(text) {
-  const stripped = text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
-  return JSON.parse(stripped);
+  return JSON.parse(blankTrailingCommas(blankComments(text)));
 }
 
 /**
@@ -489,8 +592,21 @@ export function runCli({
     const text = readFileSync(configPath, 'utf-8');
     config = parseWranglerConfig(configPath, text);
   } catch (err) {
-    stderr.write(`[wrangler-baseline] ❌ failed to parse ${configPath}: ${err instanceof Error ? err.message : String(err)}\n`);
-    return 1;
+    // Advisory mode is a promise about EXIT CODES, not about which findings
+    // are reachable: under --warn-only nothing in the consumer's config may
+    // turn the gate red. A parse failure used to return 1 here, ahead of the
+    // warnOnly branch below, so an advisory-mode consumer with a legal
+    // trailing-comma .jsonc got a hard red on a gate that had opted out of
+    // blocking (Story #407). Route it through the same policy as violations.
+    const detail = err instanceof Error ? err.message : String(err);
+    const marker = warnOnly ? '⚠️ ' : '❌';
+    stderr.write(`[wrangler-baseline] ${marker} failed to parse ${configPath}: ${detail}\n`);
+    if (json) {
+      stdout.write(
+        `${JSON.stringify({ kind: 'wrangler-baseline-report', found: true, file: configPath, parseError: detail, violations: [] })}\n`,
+      );
+    }
+    return warnOnly ? 0 : 1;
   }
 
   const report = evaluateBaseline(config, maxAgeDays, now);
@@ -507,8 +623,10 @@ export function runCli({
   return 0;
 }
 
-// Direct-invocation guard (matches the repo's other scripts/*.mjs entry style).
-const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
-if (invokedDirectly) {
+// Direct-invocation guard — symlink-safe via the shared seam. The previous
+// spelling compared a realpath-resolved `import.meta.url` against an
+// unresolved `process.argv[1]`, which never matched under pnpm's symlinked
+// node_modules: the CLI silently never ran (Story #407).
+if (isDirectInvocation(import.meta.url)) {
   process.exit(runCli());
 }

package/scripts/check-wrangler-baseline.test.mjs

@@ -11,9 +11,17 @@
  */
 
 import assert from 'node:assert/strict';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  symlinkSync,
+  rmSync,
+} from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { afterEach, beforeEach, test } from 'node:test';
 import {
   parseArgv,
@@ -452,3 +460,252 @@ test('runCli --help prints usage and exits 0 without touching the filesystem', (
   assert.equal(exit, 0);
   assert.match(streams.out, /check-wrangler-baseline\.mjs/);
 });
+
+// ---------------------------------------------------------------------------
+// JSONC tolerance — trailing commas, and string contents left alone (#407)
+// ---------------------------------------------------------------------------
+
+test('parseJsonc tolerates trailing commas in objects and arrays', () => {
+  const text = `{
+  "name": "web",
+  "analytics_engine_datasets": [
+    { "binding": "AE", "dataset": "events", },
+  ],
+}`;
+  assert.deepEqual(parseJsonc(text), {
+    name: 'web',
+    analytics_engine_datasets: [{ binding: 'AE', dataset: 'events' }],
+  });
+});
+
+test('parseJsonc tolerates a trailing comma separated by a comment', () => {
+  const text = '{ "a": [1, 2, /* done */ ], }';
+  assert.deepEqual(parseJsonc(text), { a: [1, 2] });
+});
+
+test('parseJsonc leaves string contents byte-identical', () => {
+  // Each of these would be corrupted by a regex-based comment/comma stripper:
+  // `,}` and `,]` look like trailing commas, and `//` looks like a comment
+  // even when it is not preceded by a scheme colon.
+  const text = JSON.stringify({
+    braces: 'a,} b,] c',
+    slashes: 'a//b',
+    url: 'https://example.com/x',
+    block: 'a/*b*/c',
+  });
+  assert.deepEqual(parseJsonc(text), {
+    braces: 'a,} b,] c',
+    slashes: 'a//b',
+    url: 'https://example.com/x',
+    block: 'a/*b*/c',
+  });
+});
+
+test('parseJsonc still strips real comments outside strings', () => {
+  const text = `{
+  // line comment
+  "logpush": true, /* block */
+  "name": "x"
+}`;
+  assert.deepEqual(parseJsonc(text), { logpush: true, name: 'x' });
+});
+
+test('parseJsonc reports parse-error positions against the original offsets', () => {
+  // Comments and trailing commas are blanked in place, never deleted, so a
+  // position in the error message still points at the operator's file.
+  const text = '{\n  // a comment\n  "a": 1\n  "b": 2\n}';
+  assert.throws(
+    () => parseJsonc(text),
+    (err) => /position (2[0-9]|3[0-9])/.test(err.message),
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Advisory mode is a promise about exit codes, not about findings (#407)
+// ---------------------------------------------------------------------------
+
+test('runCli exits 0 on an unparseable config with --warn-only', () => {
+  writeFileSync(join(tmpDir, 'wrangler.jsonc'), '{ not valid json');
+  const streams = noopStreams();
+  const exit = runCli({
+    argv: ['--warn-only'],
+    cwd: tmpDir,
+    stdout: streams.stdout,
+    stderr: streams.stderr,
+  });
+  assert.equal(exit, 0, 'advisory mode must never hard-fail on config content');
+  assert.match(streams.err, /failed to parse/);
+});
+
+test('runCli --json emits a parseError envelope instead of dying silently', () => {
+  writeFileSync(join(tmpDir, 'wrangler.jsonc'), '{ not valid json');
+  const streams = noopStreams();
+  const exit = runCli({
+    argv: ['--json', '--warn-only'],
+    cwd: tmpDir,
+    stdout: streams.stdout,
+    stderr: streams.stderr,
+  });
+  assert.equal(exit, 0);
+  const envelope = JSON.parse(streams.out);
+  assert.equal(envelope.kind, 'wrangler-baseline-report');
+  assert.equal(envelope.found, true);
+  assert.ok(envelope.parseError, 'the envelope names why the config was unusable');
+});
+
+test('runCli reads a trailing-comma wrangler.jsonc end to end', () => {
+  writeFileSync(
+    join(tmpDir, 'wrangler.jsonc'),
+    `{
+  "compatibility_date": "2026-06-15",
+  "logpush": true,
+  "env": { "production": { "logpush": true, }, },
+  "analytics_engine_datasets": [{ "binding": "AE", "dataset": "events", },],
+}`,
+  );
+  const streams = noopStreams();
+  const exit = runCli({
+    argv: [],
+    cwd: tmpDir,
+    stdout: streams.stdout,
+    stderr: streams.stderr,
+    now: new Date('2026-07-01T00:00:00Z'),
+  });
+  assert.equal(exit, 0, streams.out + streams.err);
+});
+
+// ---------------------------------------------------------------------------
+// The consumer end state reported in #406 (Turborepo + declared exception)
+// ---------------------------------------------------------------------------
+
+test('runCli renders a declared exception as EXCEPTED while still reporting a real violation', () => {
+  // domio's shape: the Worker config lives outside the repo root, uses
+  // trailing commas throughout, declares an analytics-engine opt-out, and has
+  // a genuinely stale compatibility_date.
+  mkdirSync(join(tmpDir, 'apps', 'web'), { recursive: true });
+  writeFileSync(
+    join(tmpDir, 'apps', 'web', 'wrangler.jsonc'),
+    `{
+  // Worker config for the web app
+  "name": "web",
+  "compatibility_date": "2025-01-01",
+  "logpush": true,
+  "env": { "production": { "logpush": true, }, },
+  "mandrel": {
+    "wranglerBaselineExceptions": {
+      "analytics-engine": "no telemetry sink for this static-asset Worker",
+    },
+  },
+}`,
+  );
+  const streams = noopStreams();
+  const exit = runCli({
+    argv: ['--file', 'apps/web/wrangler.jsonc', '--json'],
+    cwd: tmpDir,
+    stdout: streams.stdout,
+    stderr: streams.stderr,
+    now: new Date('2026-08-29T00:00:00Z'),
+  });
+
+  const envelope = JSON.parse(streams.out);
+  const analytics = envelope.findings.find((f) => f.id === 'analytics-engine');
+  assert.equal(analytics.excepted, true, 'the declared opt-out is honoured');
+  assert.ok(
+    !envelope.violations.some((v) => v.id === 'analytics-engine'),
+    'an excepted rule is absent from violations',
+  );
+  assert.ok(
+    envelope.violations.some((v) => v.id === 'compat-date-stale'),
+    'a genuine staleness violation is still reported',
+  );
+  assert.equal(exit, 1, 'a real un-excepted violation still fails in blocking mode');
+});
+
+// ---------------------------------------------------------------------------
+// Direct-invocation guard — spawned as a SUBPROCESS through a symlink (#407)
+//
+// Every other test here imports runCli, which is exactly why the guard bug
+// survived: the guard line only runs when the file is the process entry point.
+// These cases spawn it the way a pnpm consumer's CI does.
+// ---------------------------------------------------------------------------
+
+const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
+
+/**
+ * Spawn the CLI at `scriptPath` with `cwd`, returning the child result.
+ *
+ * @param {string} scriptPath Path to invoke (possibly through a symlink).
+ * @param {string[]} args CLI args.
+ * @param {string} cwd Working directory for the child.
+ */
+function runScript(scriptPath, args, cwd) {
+  return spawnSync(process.execPath, [scriptPath, ...args], {
+    cwd,
+    encoding: 'utf-8',
+  });
+}
+
+test('the CLI runs when invoked through a pnpm-style symlinked node_modules', () => {
+  // node_modules/mandrel-platform -> <repo root>, the shape pnpm installs.
+  const nodeModules = join(tmpDir, 'node_modules');
+  mkdirSync(nodeModules, { recursive: true });
+  symlinkSync(REPO_ROOT, join(nodeModules, 'mandrel-platform'), 'dir');
+  writeFileSync(join(tmpDir, 'wrangler.json'), '{"compatibility_date": "2020-01-01"}');
+
+  const linked = join(
+    nodeModules,
+    'mandrel-platform',
+    'scripts',
+    'check-wrangler-baseline.mjs',
+  );
+  const result = runScript(linked, ['--max-age-days', '90'], tmpDir);
+
+  assert.notEqual(
+    result.stdout.trim(),
+    '',
+    'a symlinked invocation must produce output, not a silent pass',
+  );
+  assert.match(result.stdout, /wrangler-baseline/);
+  assert.equal(result.status, 1, 'a violating config exits non-zero in blocking mode');
+});
+
+test('a symlinked invocation honours --warn-only rather than exiting silently', () => {
+  const nodeModules = join(tmpDir, 'node_modules');
+  mkdirSync(nodeModules, { recursive: true });
+  symlinkSync(REPO_ROOT, join(nodeModules, 'mandrel-platform'), 'dir');
+  writeFileSync(join(tmpDir, 'wrangler.json'), '{"compatibility_date": "2020-01-01"}');
+
+  const linked = join(
+    nodeModules,
+    'mandrel-platform',
+    'scripts',
+    'check-wrangler-baseline.mjs',
+  );
+  const result = runScript(linked, ['--max-age-days', '90', '--warn-only'], tmpDir);
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /violation/i, 'advisory mode still reports the findings');
+});
+
+test('the CLI still runs when invoked through its real path', () => {
+  writeFileSync(join(tmpDir, 'wrangler.json'), '{"compatibility_date": "2020-01-01"}');
+  const direct = join(REPO_ROOT, 'scripts', 'check-wrangler-baseline.mjs');
+  const result = runScript(direct, ['--max-age-days', '90'], tmpDir);
+  assert.match(result.stdout, /wrangler-baseline/);
+  assert.equal(result.status, 1);
+});
+
+test('importing the module does not execute the CLI', () => {
+  // The guard must be false when the entry point is some other script.
+  const probe = join(tmpDir, 'probe.mjs');
+  const target = join(REPO_ROOT, 'scripts', 'check-wrangler-baseline.mjs');
+  writeFileSync(
+    probe,
+    `await import(${JSON.stringify(pathToFileURL(target).href)});\nconsole.log('IMPORT-OK');\n`,
+  );
+  writeFileSync(join(tmpDir, 'wrangler.json'), '{"compatibility_date": "2020-01-01"}');
+  const result = runScript(probe, [], tmpDir);
+  assert.equal(result.status, 0, 'an import must not exit(1) via the CLI');
+  assert.match(result.stdout, /IMPORT-OK/);
+  assert.doesNotMatch(result.stdout, /wrangler-baseline/);
+});

package/scripts/deploy-boot-smoke.mjs

@@ -6,7 +6,7 @@
  * (Story #231). Extracted from the workflow's former ~140-line inline bash so
  * the probe is unit-testable and reviewed as code, not as a YAML diff. The
  * workflow sparse-checks this script out of dsj1984/mandrel-platform at
- * `github.job_workflow_sha` — the exact commit the caller's
+ * `job.workflow_sha` — the exact commit the caller's
  * `deploy-cloudflare.yml@<ref>` pin resolved to — so the script version
  * always travels in lockstep with the workflow pin (same model as
  * `uptime-apply.yml` → `apply-uptime-monitors.mjs`).

package/scripts/deploy-worker-secrets.mjs

@@ -5,7 +5,7 @@
  * In-pipeline worker-secrets provisioning for the shared
  * `deploy-cloudflare.yml` workflow (Story #170; extracted from inline bash in
  * Story #231). The workflow sparse-checks this script out of
- * dsj1984/mandrel-platform at `github.job_workflow_sha` — the exact commit
+ * dsj1984/mandrel-platform at `job.workflow_sha` — the exact commit
  * the caller's `deploy-cloudflare.yml@<ref>` pin resolved to — so the script
  * version always travels in lockstep with the workflow pin (same model as
  * `uptime-apply.yml` → `apply-uptime-monitors.mjs`).