pnpm-shield 1.0.0

package/lib/docs.js

@@ -0,0 +1,154 @@
+'use strict';
+
+/**
+ * DOCS — per-check documentation.
+ * Each key maps to a check's docKey.
+ * refs: array of { label, url } for official documentation.
+ */
+const DOCS = {
+  pnpm_installed: {
+    title: 'pnpm installed and in PATH',
+    why: 'pnpm is the only mainstream package manager with built-in supply-chain\nprotections: per-project ignore-scripts, onlyBuiltDependencies whitelisting,\nand a content-addressable store with integrity verification.',
+    attack: 'Without pnpm you lose all layered defences this tool checks for.\nnpm has no equivalent to onlyBuiltDependencies.',
+    fix: 'curl -fsSL https://get.pnpm.io/install.sh | sh\n# or via Corepack (recommended):\ncorepack enable pnpm',
+    refs: [
+      { label: 'pnpm Installation', url: 'https://pnpm.io/installation' },
+      { label: 'pnpm vs npm security', url: 'https://pnpm.io/faq#security' },
+    ],
+  },
+
+  npm_alias: {
+    title: 'Shell alias: npm → pnpm',
+    why: 'Even with pnpm fully configured, typing `npm install` by muscle memory\ninvokes the real npm binary. npm ignores your .npmrc ignore-scripts,\nyour pnpm-lock.yaml, and your onlyBuiltDependencies whitelist entirely.',
+    attack: 'Typosquatting attacks rely on developers accidentally running\n`npm install evil-pkg`. The alias intercepts that at the shell level,\nbefore any network request is made.',
+    fix: '# Add to ~/.zshrc (or ~/.bashrc):\nalias npm=pnpm\n# Reload:\nsource ~/.zshrc',
+    refs: [
+      { label: 'Typosquatting attacks (npm blog)', url: 'https://blog.npmjs.org/post/163723642530/crossenv-malware-on-the-npm-registry' },
+      { label: 'Bash aliases docs', url: 'https://www.gnu.org/software/bash/manual/html_node/Aliases.html' },
+    ],
+  },
+
+  corepack: {
+    title: 'Corepack managing pnpm',
+    why: 'Corepack is a Node.js built-in (since v16.9) that reads "packageManager"\nin package.json and enforces it OS-wide. When active, running `npm install`\nin a pnpm project throws an error before any package is downloaded.',
+    attack: 'Without Corepack, a CI script or a contributor can silently switch to\nnpm and bypass all protections — the attack surface is invisible.',
+    fix: 'corepack enable\ncorepack enable pnpm\n# Then pin the version in package.json:\n# "packageManager": "pnpm@11.1.1"',
+    refs: [
+      { label: 'Corepack docs (Node.js)', url: 'https://nodejs.org/api/corepack.html' },
+      { label: 'pnpm + Corepack guide', url: 'https://pnpm.io/installation#using-corepack' },
+    ],
+  },
+
+  foreign_locks: {
+    title: 'No foreign lockfiles',
+    why: 'A package-lock.json or yarn.lock alongside pnpm-lock.yaml creates two\nconflicting sources of truth. CI systems may pick the wrong one, installing\ndifferent (potentially malicious) resolved versions.',
+    attack: 'Dependency confusion attacks can persist silently if an old npm lockfile\nis accidentally used instead of the audited pnpm lockfile on a build server.',
+    fix: 'rm package-lock.json yarn.lock bun.lockb\npnpm install\ngit add pnpm-lock.yaml && git commit -m "chore: switch to pnpm lockfile"',
+    refs: [
+      { label: 'Dependency confusion attack (A. Birsan)', url: 'https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610' },
+      { label: 'pnpm lockfile format', url: 'https://pnpm.io/lockfile-format' },
+    ],
+  },
+
+  global_ignore_scripts: {
+    title: 'Global ignore-scripts = true',
+    why: 'Packages can declare postinstall, preinstall, and install lifecycle scripts\nthat run arbitrary shell commands the moment you install them. This is the\nprimary vector for supply-chain attacks (event-stream 2018, node-ipc 2022,\nxz-utils 2024).',
+    attack: 'A malicious postinstall script can exfiltrate env vars, SSH keys,\nAWS credentials, or install a persistent backdoor — all silently\nduring a routine `pnpm install`.',
+    fix: 'pnpm config set ignore-scripts true\n# Verify:\npnpm config get ignore-scripts  # should print: true',
+    refs: [
+      { label: 'pnpm config: ignore-scripts', url: 'https://pnpm.io/npmrc#ignore-scripts' },
+      { label: 'event-stream incident', url: 'https://snyk.io/blog/a-post-mortem-of-the-malicious-event-stream-backdoor/' },
+      { label: 'node-ipc incident (Socket.dev)', url: 'https://socket.dev/npm/package/node-ipc' },
+    ],
+  },
+
+  local_npmrc: {
+    title: 'Local .npmrc: ignore-scripts=true',
+    why: 'The global pnpm config can differ across machines and CI environments.\nA local .npmrc commits the rule into the repo itself, ensuring every\ndeveloper and every CI runner is protected regardless of global config.',
+    attack: 'A developer with a fresh machine and default global config runs\n`pnpm install` — without the local .npmrc they have no protection\neven if the repo author has ignore-scripts enabled globally.',
+    fix: 'echo "ignore-scripts=true" >> .npmrc\ngit add .npmrc && git commit -m "chore: enforce ignore-scripts"',
+    refs: [
+      { label: 'pnpm .npmrc reference', url: 'https://pnpm.io/npmrc' },
+      { label: 'npm .npmrc docs', url: 'https://docs.npmjs.com/cli/v10/configuring-npm/npmrc' },
+    ],
+  },
+
+  save_exact: {
+    title: 'save-exact=true in .npmrc',
+    why: 'By default pnpm saves dependencies with a ^ prefix (e.g. ^1.2.3),\nallowing any compatible minor/patch update. An attacker who compromises\na package can publish 1.2.4 with malicious code and every project\nusing ^1.2.3 will silently upgrade on next install.',
+    attack: 'Semver hijacking: attacker publishes a malicious patch release.\nAll projects with a range like ^1.x.x automatically adopt the payload\non their next `pnpm install` — often in CI pipelines.',
+    fix: 'echo "save-exact=true" >> .npmrc\n# Existing ranges in package.json must be updated manually.',
+    refs: [
+      { label: 'pnpm save-exact config', url: 'https://pnpm.io/npmrc#save-exact' },
+      { label: 'Semver hijacking attack', url: 'https://snyk.io/blog/ten-npm-security-best-practices/' },
+    ],
+  },
+
+  shamefully_hoist: {
+    title: 'shamefully-hoist=false',
+    why: 'pnpm uses a strict, isolated node_modules layout by default.\nshamefully-hoist=true flattens it like npm, allowing packages to\nimport dependencies they never declared. This enables phantom\ndependency attacks.',
+    attack: 'A package imports a transitive dep it does not declare.\nAn attacker replaces that transitive dep with a malicious version —\nthe package silently consumes the payload via the flat layout.',
+    fix: 'echo "shamefully-hoist=false" >> .npmrc\n# This is the pnpm default — making it explicit prevents accidental override.',
+    refs: [
+      { label: 'pnpm shamefully-hoist', url: 'https://pnpm.io/npmrc#shamefully-hoist' },
+      { label: 'Phantom dependencies (pnpm blog)', url: 'https://pnpm.io/blog/2020/05/27/flat-node-modules-is-not-the-only-way' },
+    ],
+  },
+
+  engine_strict: {
+    title: 'engine-strict=true',
+    why: 'Some security patches are Node.js-version-specific. Running code on\nan EOL Node version may miss critical fixes or expose undefined behaviour\nthat attackers can exploit.',
+    attack: 'Supply-chain payloads are sometimes crafted to trigger only on\nspecific Node versions to evade detection on developer machines\nwhile exploiting CI runners with different runtimes.',
+    fix: 'echo "engine-strict=true" >> .npmrc\n# Also add to package.json:\n# "engines": { "node": ">=20" }',
+    refs: [
+      { label: 'pnpm engine-strict', url: 'https://pnpm.io/npmrc#engine-strict' },
+      { label: 'Node.js release schedule', url: 'https://nodejs.org/en/about/previous-releases' },
+    ],
+  },
+
+  only_built_deps: {
+    title: 'pnpm.onlyBuiltDependencies whitelist',
+    why: 'Even with ignore-scripts=true, you may need certain packages to run\nbuild scripts (e.g. esbuild, sharp). onlyBuiltDependencies lets you\nwhitelist exactly those — everything else stays blocked.',
+    attack: 'Without the whitelist, you either block everything (breaking native\npackages) or allow everything (opening the attack surface). The\nwhitelist gives surgical, auditable control.',
+    fix: '# In package.json:\n{\n  "pnpm": {\n    "onlyBuiltDependencies": ["esbuild", "sharp"]\n  }\n}',
+    refs: [
+      { label: 'pnpm onlyBuiltDependencies', url: 'https://pnpm.io/package_json#pnpmonlybuiltdependencies' },
+      { label: 'pnpm allowedDeprecatedVersions', url: 'https://pnpm.io/package_json#pnpmalloweddeprecatedversions' },
+    ],
+  },
+
+  package_manager_field: {
+    title: '"packageManager" field in package.json',
+    why: 'This field tells Corepack the exact package manager + version the project\nrequires. Corepack will block npm and yarn when this is set to pnpm@X.Y.Z,\nand auto-download the pinned version if needed.',
+    attack: 'Without it, Corepack cannot enforce the package manager restriction.\nAny tool — npm, yarn, bun — can silently install packages and bypass\nyour pnpm-specific protections.',
+    fix: '# Automatically set to current pnpm version:\nnode -e "const fs=require(\'fs\'),p=JSON.parse(fs.readFileSync(\'package.json\'));p.packageManager=\'pnpm@\'+require(\'child_process\').execSync(\'pnpm --version\').toString().trim();fs.writeFileSync(\'package.json\',JSON.stringify(p,null,2)+\'\\n\')"',
+    refs: [
+      { label: 'packageManager field (Node.js docs)', url: 'https://nodejs.org/api/packages.html#packagemanager' },
+      { label: 'Corepack + packageManager', url: 'https://nodejs.org/api/corepack.html#enabling-the-feature' },
+    ],
+  },
+
+  engines_node: {
+    title: 'engines.node range in package.json',
+    why: 'Declares the minimum (and optionally maximum) Node.js version required.\nWhen combined with engine-strict=true, pnpm will refuse to install on\nincompatible environments, preventing accidental use of EOL runtimes.',
+    attack: 'EOL Node.js versions no longer receive security patches. Running\nproduction code on an EOL runtime can expose known CVEs that have\nbeen fixed in active LTS releases.',
+    fix: '# In package.json:\n"engines": { "node": ">=20" }\n# Check current LTS: https://nodejs.org/en/about/previous-releases',
+    refs: [
+      { label: 'package.json engines field', url: 'https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines' },
+      { label: 'Node.js LTS schedule', url: 'https://nodejs.org/en/about/previous-releases' },
+    ],
+  },
+
+  pnpm_lock: {
+    title: 'pnpm-lock.yaml present',
+    why: 'The lockfile pins exact resolved versions AND SHA-512 integrity hashes\nfor every package in the full dependency tree. Without it, pnpm resolves\nversions fresh on each install and can silently upgrade to a compromised\nrelease.',
+    attack: 'Without a lockfile, a publish-time attack (malicious new version of a dep)\ntakes effect on the very next `pnpm install` in any environment.\nThe lockfile is your last line of defence against this.',
+    fix: 'pnpm install  # generates pnpm-lock.yaml\ngit add pnpm-lock.yaml\ngit commit -m "chore: add pnpm lockfile"\n# Never add pnpm-lock.yaml to .gitignore!',
+    refs: [
+      { label: 'pnpm lockfile docs', url: 'https://pnpm.io/lockfile-format' },
+      { label: 'Why commit lockfiles', url: 'https://pnpm.io/faq#should-lockfile-be-committed' },
+    ],
+  },
+};
+
+module.exports = { DOCS };

package/lib/fixes.js

@@ -0,0 +1,187 @@
+'use strict';
+
+const { execSync, spawnSync } = require('child_process');
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+const c    = require('./colors');
+
+// ─── Individual fix handlers ──────────────────────────────────────────────────
+
+const FIXERS = {
+
+  globalIgnoreScripts(cwd) {
+    execSync('pnpm config set ignore-scripts true', { stdio: 'pipe' });
+    console.log(`  ${c.green}✔ Set global ignore-scripts=true${c.reset}`);
+  },
+
+  localNpmrc(cwd) {
+    const rcPath = path.join(cwd, '.npmrc');
+    const cur    = fs.existsSync(rcPath) ? fs.readFileSync(rcPath, 'utf8') : '';
+    if (!cur.includes('ignore-scripts=true')) {
+      fs.appendFileSync(rcPath, '\nignore-scripts=true\n');
+      console.log(`  ${c.green}✔ Added ignore-scripts=true to .npmrc${c.reset}`);
+    } else {
+      console.log(`  ${c.dim}  (ignore-scripts already in .npmrc — skipped)${c.reset}`);
+    }
+  },
+
+  saveExact(cwd) {
+    const rcPath = path.join(cwd, '.npmrc');
+    const cur    = fs.existsSync(rcPath) ? fs.readFileSync(rcPath, 'utf8') : '';
+    if (!cur.includes('save-exact')) {
+      fs.appendFileSync(rcPath, '\nsave-exact=true\n');
+      console.log(`  ${c.green}✔ Added save-exact=true to .npmrc${c.reset}`);
+    } else {
+      console.log(`  ${c.dim}  (save-exact already in .npmrc — skipped)${c.reset}`);
+    }
+  },
+
+  shamefullyHoist(cwd) {
+    const rcPath = path.join(cwd, '.npmrc');
+    const cur    = fs.existsSync(rcPath) ? fs.readFileSync(rcPath, 'utf8') : '';
+    if (!cur.includes('shamefully-hoist')) {
+      fs.appendFileSync(rcPath, '\nshamefully-hoist=false\n');
+      console.log(`  ${c.green}✔ Added shamefully-hoist=false to .npmrc${c.reset}`);
+    } else {
+      console.log(`  ${c.dim}  (shamefully-hoist already in .npmrc — skipped)${c.reset}`);
+    }
+  },
+
+  engineStrict(cwd) {
+    const rcPath = path.join(cwd, '.npmrc');
+    const cur    = fs.existsSync(rcPath) ? fs.readFileSync(rcPath, 'utf8') : '';
+    if (!cur.includes('engine-strict')) {
+      fs.appendFileSync(rcPath, '\nengine-strict=true\n');
+      console.log(`  ${c.green}✔ Added engine-strict=true to .npmrc${c.reset}`);
+    } else {
+      console.log(`  ${c.dim}  (engine-strict already in .npmrc — skipped)${c.reset}`);
+    }
+  },
+
+  packageManager(cwd) {
+    const pkgPath = path.join(cwd, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      console.log(`  ${c.yellow}  ⚠️  package.json not found — skipped${c.reset}`); return;
+    }
+    const pkg     = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const version = (() => {
+      try { return execSync('pnpm --version', { stdio: 'pipe' }).toString().trim(); }
+      catch { return '9.0.0'; }
+    })();
+    pkg.packageManager = `pnpm@${version}`;
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    console.log(`  ${c.green}✔ Set packageManager=pnpm@${version} in package.json${c.reset}`);
+  },
+
+  onlyBuiltDeps(cwd) {
+    const pkgPath = path.join(cwd, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      console.log(`  ${c.yellow}  ⚠️  package.json not found — skipped${c.reset}`); return;
+    }
+    const pkg   = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    pkg.pnpm    = pkg.pnpm || {};
+    if (!Array.isArray(pkg.pnpm.onlyBuiltDependencies)) {
+      pkg.pnpm.onlyBuiltDependencies = [];
+      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      console.log(`  ${c.green}✔ Added pnpm.onlyBuiltDependencies: [] to package.json${c.reset}`);
+      console.log(`  ${c.dim}    (empty = blocks ALL postinstall scripts by default)${c.reset}`);
+    } else {
+      console.log(`  ${c.dim}  (onlyBuiltDependencies already present — skipped)${c.reset}`);
+    }
+  },
+
+  enginesNode(cwd) {
+    const pkgPath = path.join(cwd, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      console.log(`  ${c.yellow}  ⚠️  package.json not found — skipped${c.reset}`); return;
+    }
+    const pkg   = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    // Use current major Node version as minimum
+    const major = parseInt(process.version.slice(1), 10);
+    pkg.engines  = pkg.engines || {};
+    if (!pkg.engines.node) {
+      pkg.engines.node = `>=${major}`;
+      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      console.log(`  ${c.green}✔ Added engines.node: ">=${major}" to package.json${c.reset}`);
+    } else {
+      console.log(`  ${c.dim}  (engines.node already set — skipped)${c.reset}`);
+    }
+  },
+
+  corepack(cwd) {
+    console.log(`  ${c.dim}Running: corepack enable pnpm${c.reset}`);
+    const result = spawnSync('corepack', ['enable', 'pnpm'], { stdio: 'inherit' });
+    if (result.status === 0) {
+      console.log(`  ${c.green}✔ Corepack enabled for pnpm${c.reset}`);
+    } else {
+      console.log(`  ${c.red}  ✗ corepack enable pnpm failed (exit ${result.status})${c.reset}`);
+    }
+  },
+
+  foreignLocks(cwd) {
+    const candidates = ['package-lock.json', 'yarn.lock', 'bun.lockb'];
+    let   removed    = 0;
+    for (const name of candidates) {
+      const full = path.join(cwd, name);
+      if (fs.existsSync(full)) {
+        fs.rmSync(full);
+        console.log(`  ${c.green}✔ Deleted ${name}${c.reset}`);
+        removed++;
+      }
+    }
+    if (removed === 0) console.log(`  ${c.dim}  (no foreign lockfiles found — skipped)${c.reset}`);
+  },
+
+  pnpmInstall(cwd) {
+    console.log(`  ${c.dim}Running: pnpm install${c.reset}`);
+    const result = spawnSync('pnpm', ['install'], { stdio: 'inherit', cwd });
+    if (result.status === 0) {
+      console.log(`  ${c.green}✔ pnpm install completed — pnpm-lock.yaml generated${c.reset}`);
+    } else {
+      console.log(`  ${c.red}  ✗ pnpm install failed (exit ${result.status})${c.reset}`);
+    }
+  },
+
+  npmAlias(cwd) {
+    const shell     = process.env.SHELL ?? '';
+    const isFish    = shell.includes('fish');
+    let   targetCfg = path.join(os.homedir(), '.zshrc');
+    if (shell.includes('bash')) targetCfg = path.join(os.homedir(), '.bashrc');
+    if (isFish)                 targetCfg = path.join(os.homedir(), '.config', 'fish', 'config.fish');
+
+    const aliasLine = isFish
+      ? '\n# pnpm-shield: block accidental npm usage\nalias npm pnpm\n'
+      : '\n# pnpm-shield: block accidental npm usage\nalias npm=pnpm\n';
+
+    const existing = fs.existsSync(targetCfg) ? fs.readFileSync(targetCfg, 'utf8') : '';
+    if (!/alias\s+npm[\s=]['"]?pnpm/.test(existing)) {
+      fs.appendFileSync(targetCfg, aliasLine);
+      console.log(`  ${c.green}✔ Added 'alias npm=pnpm' to ${targetCfg}${c.reset}`);
+      console.log(`  ${c.yellow}  ℹ️  Reload shell: source ${targetCfg}${c.reset}`);
+    } else {
+      console.log(`  ${c.dim}  (npm alias already present — skipped)${c.reset}`);
+    }
+  },
+};
+
+// ─── Apply a list of chosen result objects ────────────────────────────────────
+async function applyFixes(chosen, cwd) {
+  console.log(`\n${c.bold}🔧 Applying ${chosen.length} fix(es)...${c.reset}`);
+
+  for (const r of chosen) {
+    if (!r.fix || !FIXERS[r.fix]) {
+      console.log(`  ${c.yellow}  ⚠️  No auto-fix available for: ${r.label}${c.reset}`);
+      continue;
+    }
+    try {
+      FIXERS[r.fix](cwd);
+    } catch (err) {
+      console.log(`  ${c.red}  ✗ Fix failed for "${r.label}": ${err.message}${c.reset}`);
+    }
+  }
+
+  console.log(`\n${c.green}${c.bold}✅ Done! Run 'pnpm-shield' again to verify.${c.reset}\n`);
+}
+
+module.exports = { applyFixes };

package/lib/runner.js

@@ -0,0 +1,255 @@
+'use strict';
+
+const readline = require('readline');
+const c                   = require('./colors');
+const { runChecks }       = require('./checks');
+const { applyFixes }      = require('./fixes');
+const { showSelector }    = require('./selector');
+const { printHeader, printCheck, printDoc, printSummary, SEVERITY } = require('./ui');
+
+const PKG_VERSION = require('../package.json').version;
+
+// ─── CLI flags ────────────────────────────────────────────────────────────────
+function parseArgs() {
+  const args = process.argv.slice(2);
+  return {
+    ci:      args.includes('--ci') || args.includes('-c'),
+    help:    args.includes('--help') || args.includes('-h'),
+    version: args.includes('--version') || args.includes('-v'),
+  };
+}
+
+function printHelp() {
+  console.log(`
+${c.bold}pnpm-shield${c.reset} v${PKG_VERSION} — Supply chain security audit for pnpm projects
+
+${c.bold}Usage:${c.reset}
+  pnpm-shield [options]
+  pnpm-check  [options]          (alias)
+
+${c.bold}Options:${c.reset}
+  ${c.cyan}--ci${c.reset}          Non-interactive mode. Prints results and exits with code 1 if
+                failures are found. Designed for CI pipelines.
+  ${c.cyan}--help${c.reset}        Show this help message.
+  ${c.cyan}--version${c.reset}     Print version number.
+
+${c.bold}Interactive menu commands (default mode):${c.reset}
+  ${c.cyan}?${c.reset}             Browse all checks with arrow keys and open documentation.
+  ${c.cyan}?N${c.reset}            Read docs for check N directly (e.g. ?3).
+  ${c.cyan}fix${c.reset}           Choose fixes interactively with arrow keys + Space.
+  ${c.cyan}1 2 3${c.reset}         Apply specific fixes by number (space-separated).
+  ${c.cyan}all${c.reset}           Apply all auto-fixable items.
+  ${c.cyan}q${c.reset}             Quit.
+
+${c.bold}Examples:${c.reset}
+  pnpm-shield                   # interactive audit
+  pnpm-shield --ci              # CI mode, exits 1 on failure
+  pnpm-shield --ci | tee audit.log
+
+${c.bold}Exit codes:${c.reset}
+  0   All checks pass (or only warnings)
+  1   One or more CRITICAL/HIGH failures
+  2   Unexpected error
+`);
+}
+
+function ask(query) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(query, ans => { rl.close(); resolve(ans.trim()); }));
+}
+
+// ─── Interactive doc browser ──────────────────────────────────────────────────
+async function browseDoc(results, lastCursor) {
+  const items = results.map((r, i) => {
+    const sev  = SEVERITY[r.severity] || SEVERITY.LOW;
+    const icon = r.status === 'pass' ? '✅' : r.status === 'fail' ? '❌' : '⚠️ ';
+    return {
+      label: `${icon} [${String(i + 1).padStart(2)}] ${sev.badge}${r.severity.padEnd(8)}${c.reset}  ${r.label}`,
+    };
+  });
+
+  console.log('');
+  const selected = await showSelector(items, {
+    multi:       false,
+    title:       'Select a check to read its documentation:',
+    initialCursor: lastCursor,
+  });
+
+  if (selected.length === 0) return lastCursor;
+
+  const idx = selected[0];
+  const r   = results[idx];
+  printDoc(r.docKey, r.label);
+  return idx; // return last position so next call starts here
+}
+
+// ─── Interactive fix selector ─────────────────────────────────────────────────
+async function selectFixes(fixable) {
+  const items = fixable.map((r, i) => {
+    const sev = SEVERITY[r.severity] || SEVERITY.LOW;
+    return { label: `[${i + 1}] ${sev.badge}${r.severity.padEnd(8)}${c.reset}  ${r.label}` };
+  });
+
+  console.log('');
+  const selected = await showSelector(items, {
+    multi: true,
+    title: 'Select fixes to apply (Space toggle, Enter confirm):',
+  });
+
+  return selected.map(i => fixable[i]);
+}
+
+// ─── CI mode ─────────────────────────────────────────────────────────────────
+function runCI(results, startMs) {
+  console.log('');
+  for (let i = 0; i < results.length; i++) printCheck(results[i], i);
+
+  const { failures } = printSummary(results, startMs);
+
+  const critFails = results.filter(r => r.status === 'fail' && r.severity === 'CRITICAL');
+  const highFails = results.filter(r => r.status === 'fail' && r.severity === 'HIGH');
+
+  if (critFails.length > 0) {
+    console.log(`\n${c.red}${c.bold}🚨 CRITICAL failures:${c.reset}`);
+    critFails.forEach(r => {
+      console.log(`  ${c.red}• ${r.label}${c.reset}`);
+      if (r.tip) console.log(`    ${c.yellow}↳ ${r.tip}${c.reset}`);
+    });
+  }
+  if (highFails.length > 0) {
+    console.log(`\n${c.orange}${c.bold}⚡ HIGH severity failures:${c.reset}`);
+    highFails.forEach(r => {
+      console.log(`  ${c.orange}• ${r.label}${c.reset}`);
+      if (r.tip) console.log(`    ${c.dim}↳ ${r.tip}${c.reset}`);
+    });
+  }
+
+  if (failures === 0) {
+    console.log(`\n${c.green}${c.bold}✅ All critical checks passed.${c.reset}\n`);
+    process.exit(0);
+  } else {
+    console.log(`\n${c.red}🛑 ${failures} failure(s) detected. Fix them before proceeding.${c.reset}\n`);
+    process.exit(1);
+  }
+}
+
+// ─── Main runner ──────────────────────────────────────────────────────────────
+async function run() {
+  const flags   = parseArgs();
+  const startMs = Date.now();
+  const cwd     = process.cwd();
+
+  if (flags.version) { console.log(`pnpm-shield v${PKG_VERSION}`); process.exit(0); }
+  if (flags.help)    { printHelp(); process.exit(0); }
+
+  printHeader(PKG_VERSION);
+
+  const results = runChecks(cwd);
+
+  // CI mode — no interaction
+  if (flags.ci) { runCI(results, startMs); return; }
+
+  // Print results
+  console.log('');
+  for (let i = 0; i < results.length; i++) printCheck(results[i], i);
+
+  const { failures } = printSummary(results, startMs);
+
+  const critFails = results.filter(r => r.status === 'fail' && r.severity === 'CRITICAL');
+  const highFails = results.filter(r => r.status === 'fail' && r.severity === 'HIGH');
+  if (critFails.length > 0) {
+    console.log(`\n${c.red}${c.bold}🚨 CRITICAL failures:${c.reset}`);
+    critFails.forEach(r => {
+      console.log(`  ${c.red}• ${r.label}${c.reset}`);
+      if (r.tip) console.log(`    ${c.yellow}↳ ${r.tip}${c.reset}`);
+    });
+  }
+  if (highFails.length > 0) {
+    console.log(`\n${c.orange}${c.bold}⚡ HIGH severity failures:${c.reset}`);
+    highFails.forEach(r => {
+      console.log(`  ${c.orange}• ${r.label}${c.reset}`);
+      if (r.tip) console.log(`    ${c.dim}↳ ${r.tip}${c.reset}`);
+    });
+  }
+
+  // ALL non-passing results that have an auto-fix handler
+  const fixable = results.filter(r => r.status !== 'pass' && r.fix);
+
+  if (failures === 0 && fixable.length === 0) {
+    console.log(`\n${c.green}${c.bold}🎉 Your project is a fortress! You can safely start coding.${c.reset}\n`);
+    return;
+  }
+
+  // Help text
+  console.log(`\n${c.dim}  Commands:`);
+  console.log(`    ?       → Browse all checks with arrow keys and read documentation`);
+  console.log(`    ?N      → Read docs for check N directly (e.g. ?3)`);
+  if (fixable.length > 0) {
+    console.log(`    fix     → Open visual fix selector (arrow keys + Space + Enter)`);
+    console.log(`    all     → Apply all ${fixable.length} fixable items at once`);
+  }
+  console.log(`    q       → Quit${c.reset}`);
+
+  if (fixable.length > 0) {
+    console.log(`\n${c.bold}🔧 Fixable items (${fixable.length}):${c.reset}`);
+    fixable.forEach((r, i) => {
+      const sev  = SEVERITY[r.severity] || SEVERITY.LOW;
+      const icon = r.status === 'fail' ? `${c.red}❌${c.reset}` : `${c.yellow}⚠️ ${c.reset}`;
+      console.log(`  ${c.bold}[${i + 1}]${c.reset} ${icon} ${sev.badge}${r.severity.padEnd(8)}${c.reset}  ${r.label}`);
+    });
+    console.log(`\n${c.dim}  Tip: type 'fix' to open the visual selector, or 'all' to apply everything${c.reset}`);
+  }
+
+  // Menu loop — remember last doc cursor position between ? calls
+  let lastDocCursor = 0;
+
+  while (true) {
+    const answer = await ask(`\n${c.yellow}${c.bold}> ${c.reset}`);
+
+    if (!answer || answer === 'q' || answer === 'quit') {
+      console.log(`\n${c.yellow}✋ Exiting. Resolve ❌ items before running 'pnpm install'.${c.reset}\n`);
+      process.exit(failures > 0 ? 1 : 0);
+    }
+
+    // ? — interactive doc browser
+    if (answer === '?') {
+      lastDocCursor = await browseDoc(results, lastDocCursor);
+      continue;
+    }
+
+    // ?N — direct doc for check N
+    const docMatch = answer.match(/^\?(\d+)$/);
+    if (docMatch) {
+      const n = parseInt(docMatch[1], 10) - 1;
+      if (n < 0 || n >= results.length) {
+        console.log(`${c.red}  Invalid check number. Use 1–${results.length}.${c.reset}`);
+      } else {
+        printDoc(results[n].docKey, results[n].label);
+        lastDocCursor = n;
+      }
+      continue;
+    }
+
+    // fix — visual multi-select
+    if ((answer === 'fix' || answer === '') && fixable.length > 0) {
+      const chosen = await selectFixes(fixable);
+      if (chosen.length === 0) {
+        console.log(`${c.dim}  No fixes selected.${c.reset}`);
+      } else {
+        await applyFixes(chosen, cwd);
+        break;
+      }
+      continue;
+    }
+
+    // all
+    if (answer === 'all' && fixable.length > 0) {
+      await applyFixes(fixable, cwd);
+      break;
+    }
+
+    console.log(`${c.dim}  Unknown command. Type ?, ?N, fix, all, or q.${c.reset}`);
+  }
+}
+
+module.exports = { run };