mandrel 1.62.0 → 1.64.0

package/.agents/scripts/bootstrap.js

@@ -195,13 +195,13 @@ function runGit(args, cwd) {
  * `GhExecError` — so a bare "gh exited with code 1" is actually diagnosable.
  */
 function logGhError(label, err) {
-  Logger.error(`[bootstrap] ${label} failed: ${err.message}`);
+  Logger.error(`[Bootstrap] ${label} failed: ${err.message}`);
   if (err.stderr)
-    Logger.error(`[bootstrap]   gh stderr: ${String(err.stderr).trim()}`);
+    Logger.error(`[Bootstrap]   gh stderr: ${String(err.stderr).trim()}`);
   if (err.stdout)
-    Logger.error(`[bootstrap]   gh stdout: ${String(err.stdout).trim()}`);
+    Logger.error(`[Bootstrap]   gh stdout: ${String(err.stdout).trim()}`);
   if (Array.isArray(err.args)) {
-    Logger.error(`[bootstrap]   gh args: ${err.args.join(' ')}`);
+    Logger.error(`[Bootstrap]   gh args: ${err.args.join(' ')}`);
   }
 }
 
@@ -249,7 +249,7 @@ function ensureGitInitialized(state) {
     initialized = true;
     state.gitInitialized = true;
     Logger.info(
-      `[bootstrap] Initialized git repo (branch ${branch}) at ${cwd}.`,
+      `[Bootstrap] Initialized git repo (branch ${branch}) at ${cwd}.`,
     );
   }
 
@@ -281,7 +281,7 @@ function ensureGitInitialized(state) {
       return { ok: false, error: commit.stderr || 'git commit failed' };
     }
     committed = true;
-    Logger.info('[bootstrap] Created initial commit.');
+    Logger.info('[Bootstrap] Created initial commit.');
   }
   return { ok: true, initialized, committed };
 }
@@ -303,21 +303,21 @@ async function ensureGitRemote(state, execImpl = exec) {
   if (runGit(['remote', 'get-url', 'origin'], cwd).ok) return;
   if (!(await repoExists(owner, repo, execImpl))) {
     Logger.warn(
-      `[bootstrap] No 'origin' remote and ${owner}/${repo} does not exist on GitHub — skipping remote wiring.`,
+      `[Bootstrap] No 'origin' remote and ${owner}/${repo} does not exist on GitHub — skipping remote wiring.`,
     );
     return;
   }
   const url = `https://github.com/${owner}/${repo}.git`;
   const add = runGit(['remote', 'add', 'origin', url], cwd);
   if (!add.ok) {
-    Logger.warn(`[bootstrap] Could not add 'origin' remote: ${add.stderr}`);
+    Logger.warn(`[Bootstrap] Could not add 'origin' remote: ${add.stderr}`);
     return;
   }
-  Logger.info(`[bootstrap] Wired 'origin' → ${url}.`);
+  Logger.info(`[Bootstrap] Wired 'origin' → ${url}.`);
   const push = runGit(['push', '-u', 'origin', branch], cwd);
   if (!push.ok) {
     Logger.warn(
-      `[bootstrap] 'origin' is set but push of '${branch}' failed (resolve manually, e.g. \`git pull --rebase origin ${branch}\`): ${push.stderr}`,
+      `[Bootstrap] 'origin' is set but push of '${branch}' failed (resolve manually, e.g. \`git pull --rebase origin ${branch}\`): ${push.stderr}`,
     );
   }
 }
@@ -359,11 +359,11 @@ async function ensureProjectLinked(state, execImpl = exec) {
       args: ['project', 'link', pn, '--owner', owner, '--repo', repo],
     });
     Logger.info(
-      `[bootstrap] Linked repo ${owner}/${repo} to Project V2 #${pn}.`,
+      `[Bootstrap] Linked repo ${owner}/${repo} to Project V2 #${pn}.`,
     );
   } catch (err) {
     Logger.warn(
-      `[bootstrap] Could not link repo ${owner}/${repo} to Project V2 #${pn} (continuing): ${err.message}`,
+      `[Bootstrap] Could not link repo ${owner}/${repo} to Project V2 #${pn} (continuing): ${err.message}`,
     );
   }
 }
@@ -413,7 +413,7 @@ async function createGithubRepo(state, execImpl = exec) {
     ],
   });
   Logger.info(
-    `[bootstrap] Created GitHub repo ${slug} (${visibility}) and pushed.`,
+    `[Bootstrap] Created GitHub repo ${slug} (${visibility}) and pushed.`,
   );
 }
 
@@ -480,7 +480,7 @@ async function createGithubProject(state, execImpl = exec) {
   if (Number.isInteger(existing)) {
     state.answers.projectNumber = String(existing);
     Logger.info(
-      `[bootstrap] Reusing existing GitHub Project V2 "${title}" (#${existing}) — no duplicate created.`,
+      `[Bootstrap] Reusing existing GitHub Project V2 "${title}" (#${existing}) — no duplicate created.`,
     );
     return existing;
   }
@@ -510,7 +510,7 @@ async function createGithubProject(state, execImpl = exec) {
     );
   }
   state.answers.projectNumber = String(number);
-  Logger.info(`[bootstrap] Created GitHub Project V2 "${title}" (#${number}).`);
+  Logger.info(`[Bootstrap] Created GitHub Project V2 "${title}" (#${number}).`);
   return number;
 }
 
@@ -539,7 +539,7 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
       key: 'owner',
       flag: 'owner',
       env: 'GH_OWNER',
-      message: 'Github repo owner',
+      message: '\n\nGitHub repo owner',
       default: defaults.owner,
       required: true,
       validate: (v) =>
@@ -549,7 +549,8 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
       key: 'operatorHandle',
       flag: 'operator-handle',
       env: 'GH_OPERATOR_HANDLE',
-      message: 'Github username/handle (without the @)',
+      message:
+        'GitHub username/handle without preceding@ (default: same as owner)',
       // Default tracks the repo owner; resolved post-collect if left blank.
       default: defaults.owner,
       required: false,
@@ -562,8 +563,9 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
       key: 'repo',
       flag: 'repo',
       env: 'GH_REPO',
-      message:
-        'Github repo name - Select from the list or enter a new name to create one',
+      message: 'New GitHub repo name',
+      pickerMessage:
+        'GitHub repo name  - Select existing or press ENTER to create',
       default: defaults.repo,
       required: true,
       picker: {
@@ -590,8 +592,9 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
       key: 'projectNumber',
       flag: 'project-number',
       env: 'GH_PROJECT_NUMBER',
-      message:
-        'Github Project V2 name - Select from the list or enter a new name to create one',
+      message: 'New GitHub Project V2 name',
+      pickerMessage:
+        'GitHub Project V2 name  - Select existing or press ENTER to create',
       // Prefer the already-stored numeric project number (an
       // already-provisioned project on a re-run) so `--assume-yes` resolves a
       // numeric answer that `detectCreation` treats as existing — never a
@@ -750,7 +753,7 @@ export function parseAndValidate(argv, opts = {}) {
   // `--assume-yes` path did.)
   if (!interactive && !assumeYes && !approveGithubAdmin) {
     Logger.error(
-      '[bootstrap] non-TTY run requires --assume-yes or --approve-github-admin ' +
+      '[Bootstrap] non-TTY run requires --assume-yes or --approve-github-admin ' +
         '(no operator is present to confirm the GitHub-admin mutations).',
     );
     return { ok: false, exit: 1 };
@@ -760,7 +763,7 @@ export function parseAndValidate(argv, opts = {}) {
   const githubAdminApproved = interactive || assumeYes || approveGithubAdmin;
   if (resolveRepoVisibility(flags) === null) {
     Logger.error(
-      `[bootstrap] invalid --visibility "${flags.visibility}". ` +
+      `[Bootstrap] invalid --visibility "${flags.visibility}". ` +
         `Expected one of: ${REPO_VISIBILITIES.join(', ')}.`,
     );
     return { ok: false, exit: 1 };
@@ -783,11 +786,12 @@ export function prepareContext(state, opts = {}) {
   const defaults = inferDefaults(projectRoot);
   const silentAccept = resolveSilentAccept(defaults, state.flags);
 
-  Logger.info('[bootstrap] Detected from local git:');
-  Logger.info(`  owner          ${defaults.owner ?? '(none)'}`);
-  Logger.info(`  repo           ${defaults.repo ?? '(none)'}`);
-  Logger.info(`  base branch    ${defaults.baseBranch ?? '(none)'}`);
-  Logger.info(`  username       ${defaults.operatorHandle ?? '(none)'}`);
+  Logger.info('[\n');
+  Logger.info('[Bootstrap] Checking existing GitHub values:');
+  Logger.info(`  GitHub Repo Owner  ${defaults.owner ?? '(unknown)'}`);
+  Logger.info(`  GitHub Repo Name   ${defaults.repo ?? '(unknown)'}`);
+  Logger.info(`  Base Branch        ${defaults.baseBranch ?? '(unknown)'}`);
+  Logger.info(`  GitHub Username    ${defaults.operatorHandle ?? '(unknown)'}`);
 
   return {
     ok: true,
@@ -811,24 +815,34 @@ export async function runPreflightPhase(state, opts = {}) {
 
   for (const check of result.checks) {
     if (check.ok) {
+      // A non-fatal informational check (it carries `gitInitialized`) shows a
+      // glyph reflecting the real state rather than its always-true gate pass:
+      // ✓ when the git repo exists, ✗ when it does not (bootstrap initialises
+      // it in a later phase regardless — the ✗ never aborts the run).
+      const glyph =
+        typeof check.gitInitialized === 'boolean' && !check.gitInitialized
+          ? '✗'
+          : '✓';
       Logger.info(
-        `[bootstrap] ✓ ${check.name}${check.detail ? ` — ${check.detail}` : ''}`,
+        `[Bootstrap] ${glyph} ${check.name}${check.detail ? ` — ${check.detail}` : ''}`,
       );
     } else {
-      Logger.error(`[bootstrap] ✗ ${check.name}: ${check.remedy}`);
+      Logger.error(`[Bootstrap] ✗ ${check.name}: ${check.remedy}`);
     }
   }
 
   if (!result.ok) {
     Logger.error(
-      '[bootstrap] Preflight failed. Resolve the issues above and re-run.',
+      '[Bootstrap] Preflight failed. Resolve the issues above and re-run.',
     );
     return { ok: false, exit: 1 };
   }
 
-  Logger.info(
-    `[bootstrap] git initialized: ${result.gitInitialized ? 'yes' : 'no'}`,
-  );
+  // The git-repo state is already reported by the (non-fatal) "Local git
+  // initialized" check above — both derive from the same
+  // `git rev-parse --is-inside-work-tree` probe — so there is no separate
+  // "git initialized" line here (it would duplicate, and contradict, that
+  // check). The boolean is still threaded through the payload for later phases.
   return {
     ok: true,
     payload: { preflight: result, gitInitialized: result.gitInitialized },
@@ -844,15 +858,15 @@ function renderAnswerSummary(
   visibility,
 ) {
   const newRepoNote = creation.newRepo
-    ? `  (NEW — will be created, ${visibility})`
+    ? `  will be created as ${visibility}`
     : '';
   const lines = [
-    '\n=== Review your answers ===',
+    '=== Review choices ===',
     `  Repo owner       ${answers.owner}`,
     `  Username/handle  ${answers.operatorHandle || '(none)'}`,
     `  Repo name        ${answers.repo}${newRepoNote}`,
     `  Base branch      ${answers.baseBranch}`,
-    `  Project V2 name  ${project.name}${creation.newProject ? '  (NEW — will be created)' : ''}`,
+    `  Project V2 name  ${project.name}${creation.newProject ? '  will be created' : ''}`,
     `  Project V2 #     ${project.number}`,
     `  Local git        ${gitInitialized ? 'initialized' : 'will be initialized'}`,
   ];
@@ -943,7 +957,7 @@ export async function collectAndConfirm(state) {
     });
     if (missing.length > 0) {
       Logger.error(
-        `[bootstrap] missing required answers: ${missing.join(', ')}`,
+        `[Bootstrap] missing required answers: ${missing.join(', ')}`,
       );
       return { ok: false, exit: 1 };
     }
@@ -968,7 +982,7 @@ export async function collectAndConfirm(state) {
     );
     const correct = await confirmYesNo('Is this correct?', state.interactive);
     if (!correct) {
-      Logger.info('[bootstrap] Okay — let’s try again.');
+      Logger.info('[Bootstrap] Okay — let’s try again.');
       // Re-prompt everything on the next pass (drop silent-accept).
       silentAccept = [];
       continue;
@@ -982,7 +996,7 @@ export async function collectAndConfirm(state) {
       );
       if (!approved) {
         Logger.error(
-          '[bootstrap] Creation declined — cannot continue without the repo/project. Exiting.',
+          '[Bootstrap] Creation declined — cannot continue without the repo/project. Exiting.',
         );
         return { ok: false, exit: 1 };
       }
@@ -1025,7 +1039,7 @@ function renderDryRunPlan(state) {
 export function dryRunPlan(state) {
   if (!state.flags['dry-run']) return { ok: true, payload: {} };
   Logger.info(
-    '[bootstrap] --dry-run: no files, GitHub settings, or labels will be changed.',
+    '[Bootstrap] --dry-run: no files, GitHub settings, or labels will be changed.',
   );
   Logger.info(renderDryRunPlan(state));
   return { ok: false, exit: 0 };
@@ -1062,18 +1076,18 @@ export async function provisionResources(state, deps = {}) {
   // 1. Local git — initialize + first commit when missing (idempotent).
   const git = ensureGitInitialized(state);
   if (!git.ok) {
-    Logger.error(`[bootstrap] git initialization failed: ${git.error}`);
+    Logger.error(`[Bootstrap] git initialization failed: ${git.error}`);
     return { ok: false, exit: 1 };
   }
   if (!git.initialized && !git.committed) {
-    Logger.info('[bootstrap] git already initialized — leaving as-is.');
+    Logger.info('[Bootstrap] git already initialized — leaving as-is.');
   }
 
   const { newRepo, newProject } = state.creation;
   if (skipGithub) {
     if (newRepo || newProject) {
       Logger.info(
-        '[bootstrap] --skip-github set; not creating the GitHub repo/project.',
+        '[Bootstrap] --skip-github set; not creating the GitHub repo/project.',
       );
     }
     return { ok: true, payload: {} };
@@ -1108,7 +1122,7 @@ export async function provisionResources(state, deps = {}) {
   }
 
   if (!newRepo && !newProject) {
-    Logger.info('[bootstrap] No new GitHub resources needed.');
+    Logger.info('[Bootstrap] No new GitHub resources needed.');
   }
 
   // 4. Link the repo to the project board so issues/PRs surface on it
@@ -1125,7 +1139,7 @@ export async function provisionResources(state, deps = {}) {
  */
 export async function executeBootstrap(state) {
   Logger.info(
-    `[bootstrap] Starting project bootstrap at ${state.projectRoot} (owner=${state.answers.owner} repo=${state.answers.repo} base=${state.answers.baseBranch})`,
+    `[Bootstrap] Starting project bootstrap at ${state.projectRoot} (owner=${state.answers.owner} repo=${state.answers.repo} base=${state.answers.baseBranch})`,
   );
   const approvedGroups = new Set(Object.values(PHASE_GROUPS));
   const report = await applyProjectBootstrap({
@@ -1158,7 +1172,7 @@ export function persistProjectNumber(state) {
     config = JSON.parse(fs.readFileSync(target, 'utf8'));
   } catch (err) {
     Logger.error(
-      `[bootstrap] Could not read ${target} to store projectNumber: ${err.message}`,
+      `[Bootstrap] Could not read ${target} to store projectNumber: ${err.message}`,
     );
     return { ok: true, payload: {} };
   }
@@ -1172,14 +1186,14 @@ export function persistProjectNumber(state) {
   }
   config.github.projectNumber = Number(pn);
   fs.writeFileSync(target, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
-  Logger.info(`[bootstrap] Stored github.projectNumber=${pn} in .agentrc.json`);
+  Logger.info(`[Bootstrap] Stored github.projectNumber=${pn} in .agentrc.json`);
   return { ok: true, payload: {} };
 }
 
 /** Step 6b — GitHub-side bootstrap. Honours `--skip-github`. */
 export async function executeGithubBootstrap(state) {
   if (state.flags['skip-github']) {
-    Logger.info('[bootstrap] --skip-github set; skipping GitHub bootstrap.');
+    Logger.info('[Bootstrap] --skip-github set; skipping GitHub bootstrap.');
     return { ok: true, payload: {} };
   }
   try {
@@ -1274,7 +1288,7 @@ export async function offerCommitPush(state, deps = {}) {
   // Non-interactive (--assume-yes / no TTY): never push unprompted. Print the
   // exact commands and leave the working tree untouched.
   if (!state.interactive) {
-    Logger.info(`\n[bootstrap] ${instructions}`);
+    Logger.info(`\n[Bootstrap] ${instructions}`);
     return { ok: true, payload: { commitPush: { action: 'instructed' } } };
   }
 
@@ -1283,14 +1297,14 @@ export async function offerCommitPush(state, deps = {}) {
     state.interactive,
   );
   if (!accepted) {
-    Logger.info(`\n[bootstrap] ${instructions}`);
+    Logger.info(`\n[Bootstrap] ${instructions}`);
     return { ok: true, payload: { commitPush: { action: 'declined' } } };
   }
 
   const staged = stageBootstrapFiles({ projectRoot: cwd, runGit: runGitImpl });
   if (!staged.ok) {
-    Logger.warn(`[bootstrap] Could not stage the wiring: ${staged.error}`);
-    Logger.info(`\n[bootstrap] ${instructions}`);
+    Logger.warn(`[Bootstrap] Could not stage the wiring: ${staged.error}`);
+    Logger.info(`\n[Bootstrap] ${instructions}`);
     return { ok: true, payload: { commitPush: { action: 'stage-failed' } } };
   }
   const commit = runGitImpl(
@@ -1300,20 +1314,20 @@ export async function offerCommitPush(state, deps = {}) {
   if (!commit.ok) {
     // A "nothing to commit" exit is benign — the wiring is already committed.
     Logger.warn(
-      `[bootstrap] git commit did not create a commit (already committed?): ${commit.stderr || commit.stdout}`,
+      `[Bootstrap] git commit did not create a commit (already committed?): ${commit.stderr || commit.stdout}`,
     );
-    Logger.info(`\n[bootstrap] ${instructions}`);
+    Logger.info(`\n[Bootstrap] ${instructions}`);
     return { ok: true, payload: { commitPush: { action: 'commit-skipped' } } };
   }
-  Logger.info('[bootstrap] Committed the Mandrel wiring.');
+  Logger.info('[Bootstrap] Committed the Mandrel wiring.');
   const push = runGitImpl(['push', '-u', 'origin', branch], cwd);
   if (!push.ok) {
     Logger.warn(
-      `[bootstrap] Commit landed but push of '${branch}' failed (push it manually with \`git push -u origin ${branch}\`): ${push.stderr}`,
+      `[Bootstrap] Commit landed but push of '${branch}' failed (push it manually with \`git push -u origin ${branch}\`): ${push.stderr}`,
     );
     return { ok: true, payload: { commitPush: { action: 'push-failed' } } };
   }
-  Logger.info(`[bootstrap] Pushed '${branch}' to origin.`);
+  Logger.info(`[Bootstrap] Pushed '${branch}' to origin.`);
   return { ok: true, payload: { commitPush: { action: 'committed-pushed' } } };
 }
 
@@ -1357,7 +1371,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
   const githubError = result.state?.report?.github?.error;
   if (githubError) {
     Logger.error(
-      `\n[bootstrap] GitHub bootstrap failed: ${githubError}. ` +
+      `\n[Bootstrap] GitHub bootstrap failed: ${githubError}. ` +
         'Project-side setup (labels are GitHub-side; the local .agentrc.json / ' +
         'quality-gate / workflow files that were applied are recorded in the ' +
         'install ledger) completed, but the GitHub label/board/views/protection ' +
@@ -1368,7 +1382,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     return 1;
   }
 
-  Logger.info('\n[bootstrap] Done.');
+  Logger.info('\n[Bootstrap] Done.');
   return 0;
 }
 

package/.agents/scripts/check-action-pinning.js

@@ -0,0 +1,260 @@
+/**
+ * CLI: third-party GitHub Action pinning gate.
+ *
+ * Story #4079 (audit::devops). Closes a supply-chain regression window the
+ * `ci.yml` / `release-please.yml` comments *claimed* was guarded by a
+ * nonexistent `npm run audit-security` gate. There is no such npm script;
+ * `audit-security` is only a manual `/audit-security` slash-command lens.
+ * Nothing actually enforced that third-party `uses:` refs stay SHA-pinned,
+ * so a future edit reverting `trufflehog@<sha>` to `@main` would pass CI
+ * silently.
+ *
+ * This script scans `.github/workflows/*.yml` (and `*.yaml`), extracts every
+ * `uses:` ref, and fails the build when a **third-party** action (anything
+ * not under the first-party `actions/*` org) is pinned to a floating ref
+ * instead of a full 40-char commit SHA. First-party `actions/*` refs are
+ * allowed on major-version tags (`@v4`) — Dependabot's `github-actions`
+ * ecosystem bumps those in-place, matching the rationale in the workflow
+ * file headers.
+ *
+ * A "floating ref" is any of:
+ *   - a branch head: `@main`, `@master`
+ *   - a tag / partial-SHA that is not a full 40-hex-char commit SHA
+ *     (`@v5`, `@v3.95.3`, `@release`, a 7-char short SHA, …)
+ *
+ * Contract:
+ *   - Scans the workflows directory (default `.github/workflows`, override
+ *     with `--dir <path>`).
+ *   - Prints `<file>:<lineNo> <ref> — <reason>` for each violation, then a
+ *     one-line summary even on a clean scan so operators see the "ok" signal.
+ *   - With `--json`: writes a structured envelope to stdout and skips the
+ *     human summary.
+ *   - Exit codes: 0 = no violations; 1 = at least one floating third-party
+ *     ref. A missing / empty workflows directory exits 0 (nothing to gate).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+
+/**
+ * Parse argv for `--dir <path>` and `--json`. Exported so unit tests can pin
+ * the parser.
+ *
+ * @param {string[]} argv
+ * @returns {{ dir: string | null, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let dir = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--dir') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        dir = next;
+        i += 1;
+      }
+    } else if (a === '--json') {
+      json = true;
+    }
+  }
+  return { dir, json };
+}
+
+/**
+ * Is the given ref suffix a full 40-char hex commit SHA?
+ *
+ * @param {string} ref The portion after the `@` in a `uses:` value.
+ * @returns {boolean}
+ */
+export function isFullSha(ref) {
+  return /^[0-9a-f]{40}$/i.test(ref);
+}
+
+/**
+ * Is the action a first-party `actions/*` action (e.g. `actions/checkout`)?
+ * First-party refs are allowed to float on major-version tags because
+ * Dependabot's `github-actions` ecosystem bumps them in-place.
+ *
+ * Local (`./…`) and reusable-workflow (`owner/repo/.github/workflows/x.yml`)
+ * refs and Docker refs (`docker://…`) are out of scope for the SHA-pin gate;
+ * `isFirstParty` only matters for `owner/repo[@ref]` registry actions.
+ *
+ * @param {string} action The portion before the `@` in a `uses:` value.
+ * @returns {boolean}
+ */
+export function isFirstParty(action) {
+  return /^actions\//.test(action);
+}
+
+/**
+ * Pure helper: scan a single workflow file's text for `uses:` refs and return
+ * the violations. A violation is a third-party `owner/repo@ref` where `ref`
+ * is not a full 40-char SHA.
+ *
+ * Skips:
+ *   - local actions (`uses: ./path`)
+ *   - Docker refs (`uses: docker://…`)
+ *   - first-party `actions/*` refs (allowed on major-version tags)
+ *   - refs with no `@` (pinned by default branch implicitly — flagged as a
+ *     violation: an unpinned third-party ref floats on the default branch)
+ *
+ * @param {string} file Relative file label used in violation rows.
+ * @param {string} text The file contents.
+ * @returns {Array<{ file: string, line: number, action: string, ref: string | null, reason: string }>}
+ */
+export function scanWorkflowText(file, text) {
+  const violations = [];
+  const lines = text.split(/\r?\n/);
+  // Match `uses:` values, optionally quoted. The value runs until whitespace
+  // or a `#` comment. Capture the raw value for downstream parsing.
+  const usesRe = /^\s*(?:-\s*)?uses:\s*['"]?([^'"#\s]+)['"]?/;
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = usesRe.exec(lines[i]);
+    if (!m) continue;
+    const value = m[1];
+    const lineNo = i + 1;
+    // Local actions and Docker refs are out of scope for the SHA-pin gate.
+    if (value.startsWith('./') || value.startsWith('docker://')) continue;
+    const atIndex = value.indexOf('@');
+    const action = atIndex === -1 ? value : value.slice(0, atIndex);
+    const ref = atIndex === -1 ? null : value.slice(atIndex + 1);
+    // First-party actions/* may float on major-version tags.
+    if (isFirstParty(action)) continue;
+    if (ref === null) {
+      violations.push({
+        file,
+        line: lineNo,
+        action,
+        ref: null,
+        reason: 'third-party action with no ref floats on the default branch',
+      });
+      continue;
+    }
+    if (!isFullSha(ref)) {
+      const floating = ref === 'main' || ref === 'master';
+      violations.push({
+        file,
+        line: lineNo,
+        action,
+        ref,
+        reason: floating
+          ? `third-party action pinned to branch head @${ref} (CWE-1357)`
+          : `third-party action @${ref} is not a full 40-char commit SHA`,
+      });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Enumerate workflow files (`*.yml` / `*.yaml`) directly under `dir`.
+ * Returns absolute paths sorted for deterministic output. A missing directory
+ * yields an empty list.
+ *
+ * @param {string} dir Absolute workflows directory.
+ * @returns {string[]}
+ */
+export function listWorkflowFiles(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && /\.ya?ml$/i.test(e.name))
+    .map((e) => path.join(dir, e.name))
+    .sort();
+}
+
+/**
+ * Pure helper: render the human-readable report. One line per violation
+ * followed by a one-line summary. The summary carries a `(gate fail)` /
+ * `(ok)` marker so the result is visible in CI output.
+ *
+ * @param {Array<{ file: string, line: number, action: string, ref: string | null, reason: string }>} violations
+ * @returns {string}
+ */
+export function renderReport(violations) {
+  const lines = [];
+  for (const v of violations) {
+    const refLabel = v.ref === null ? '(no ref)' : `@${v.ref}`;
+    lines.push(`${v.file}:${v.line} ${v.action}${refLabel} — ${v.reason}`);
+  }
+  const tag = violations.length > 0 ? '(gate fail)' : '(ok)';
+  lines.push(`[action-pinning] violations=${violations.length} ${tag}`);
+  return lines.join('\n');
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive the full pipeline against a
+ * fixture workflows directory without touching the repo's real workflows.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} exit code: 0 = clean; 1 = floating third-party ref
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const { dir, json } = parseArgv(argv);
+  const resolvedDir = path.resolve(
+    cwd,
+    dir ?? path.join('.github', 'workflows'),
+  );
+
+  const files = listWorkflowFiles(resolvedDir);
+  const violations = [];
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    violations.push(...scanWorkflowText(path.relative(cwd, file), text));
+  }
+
+  const exitCode = violations.length > 0 ? 1 : 0;
+
+  if (json) {
+    const envelope = {
+      kind: 'action-pinning-report',
+      dir: resolvedDir,
+      filesScanned: files.length,
+      violations,
+      exitCode,
+    };
+    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+  } else {
+    if (files.length === 0) {
+      stderr.write(
+        `[action-pinning] ⚠ no workflow files found under ${resolvedDir}\n`,
+      );
+    }
+    stdout.write(`\n--- action-pinning scan ---\n`);
+    stdout.write(`${renderReport(violations)}\n`);
+  }
+
+  return exitCode;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'action-pinning',
+  propagateExitCode: true,
+  errorPrefix: '[action-pinning] ❌ Fatal error',
+});