@humaan/patch-patrol 0.2.2

package/README.md

@@ -0,0 +1,204 @@
+# Patch Patrol
+
+Patch Patrol is an interactive CLI for rolling out advisory-driven package bumps across many local repositories.
+
+It scans a repo or folder of repos, shows which projects are affected, then lets you choose exactly which projects should get update branches and pull requests.
+
+## Install
+
+Run directly:
+
+```sh
+pnpx @humaan/patch-patrol
+```
+
+`npx @humaan/patch-patrol` works too if you use npm instead of pnpm.
+
+Or install globally:
+
+```sh
+npm install --global @humaan/patch-patrol
+patch-patrol
+```
+
+## Requirements
+
+- Node.js 20+
+- GitHub CLI authenticated with `gh auth login`
+- The package manager used by affected repos, such as `npm`, `pnpm`, `yarn`, or `bun`
+
+## Interactive Workflow
+
+Start Patch Patrol with no flags:
+
+```sh
+patch-patrol
+```
+
+The CLI guides you through two phases.
+
+**1. Scan**
+
+- Enter a single repo path or a parent folder containing repos.
+- Choose an advisory rule from the list.
+- Choose which bump levels to include: major, minor, patch, or any combination.
+- Review the affected-project summary.
+
+**2. Action**
+
+- Select affected projects from a multiselect list.
+- Confirm the selected projects.
+- Patch Patrol creates update branches, refreshes lockfiles, commits the package bumps, pushes to GitHub, and opens pull requests.
+
+Use arrow keys to move through selections, spacebar to toggle multiselect items, and enter to continue. Selecting no affected projects exits without changing anything.
+
+## What It Does
+
+For each selected project, Patch Patrol:
+
+- Checks the worktree is clean before editing.
+- Checks out and fast-forwards the default branch.
+- Creates an advisory-specific branch under `patch-patrol/`.
+- Updates affected packages in `package.json`.
+- Preserves existing `^` or `~` range prefixes.
+- Refreshes the lockfile with the repo's package manager.
+- Commits the change.
+- Pushes the branch and opens a GitHub pull request.
+
+If a selected repo does not already have a GitHub remote, Patch Patrol prompts for one before pushing. For Bitbucket Humaan remotes, it suggests the GitHub equivalent automatically:
+
+```txt
+bitbucket.org:humaanco/example.git
+```
+
+becomes:
+
+```txt
+git@github.com:humaan/example.git
+```
+
+## Included Advisories
+
+### `next-may-2026`
+
+Implements the [Next.js May 2026 security release](https://vercel.com/changelog/next-js-may-2026-security-release#affected-versions).
+
+| Package | Affected | Upgrade to |
+| --- | --- | --- |
+| `next` 13.x | all versions | `15.5.18` |
+| `next` 14.x | all versions | `15.5.18` |
+| `next` 15.x | `<=15.5.17` | `15.5.18` |
+| `next` 16.x | `<=16.2.5` | `16.2.6` |
+| `react-server-dom-*` 19.0.x | `<=19.0.5` | `19.0.6` |
+| `react-server-dom-*` 19.1.x | `<=19.1.6` | `19.1.7` |
+| `react-server-dom-*` 19.2.x | `<=19.2.5` | `19.2.6` |
+
+## Advisory Files
+
+Advisories are JSON files in `advisories/*.json`. They describe package names, affected version constraints, target versions, and PR metadata.
+
+```json
+{
+  "id": "example-advisory",
+  "title": "Example package security release",
+  "branchName": "example-security-release",
+  "commitMessage": "Update example security dependencies",
+  "prTitle": "Update example security dependencies",
+  "prBody": "Updates packages affected by the example advisory.\n\nAdvisory: https://example.com/advisory",
+  "packages": [
+    {
+      "name": "example-package",
+      "affected": [
+        {
+          "major": 2,
+          "maxVersion": "2.4.3",
+          "upgradeTo": "2.4.4",
+          "reason": "example-package 2.x <= 2.4.3 is affected."
+        }
+      ]
+    }
+  ]
+}
+```
+
+Supported package matching:
+
+- Exact names, such as `next`
+- Wildcards, such as `react-server-dom-*`
+
+Supported version constraints:
+
+- `major`
+- `minor`
+- `patch`
+- `minVersion`
+- `maxVersion`
+
+Patch Patrol currently inspects `dependencies`, `devDependencies`, and `optionalDependencies`.
+
+## Advanced CLI Usage
+
+Use flags when you want a repeatable scan or automated run instead of the guided workflow.
+
+List available advisory rules:
+
+```sh
+patch-patrol --list-rules
+```
+
+Scan without changing files:
+
+```sh
+patch-patrol --root /Users/sam/repos --rule next-may-2026 --dry-run
+```
+
+Filter by bump level:
+
+```sh
+patch-patrol --root /Users/sam/repos --rule next-may-2026 --dry-run --patch
+patch-patrol --root /Users/sam/repos --rule next-may-2026 --dry-run --minor
+patch-patrol --root /Users/sam/repos --rule next-may-2026 --dry-run --major
+patch-patrol --root /Users/sam/repos --rule next-may-2026 --dry-run --bump minor,patch
+```
+
+Bump filters compare the installed version in `package.json` with the advisory target version. For example, `15.5.7 -> 15.5.18` is a patch bump, `16.1.6 -> 16.2.6` is a minor bump, and `14.2.20 -> 15.5.18` is a major bump.
+
+Update all affected repos without selection prompts:
+
+```sh
+patch-patrol --root /Users/sam/repos --rule next-may-2026 --yes
+```
+
+Update locally without pushing or opening pull requests:
+
+```sh
+patch-patrol --root /Users/sam/repos --rule next-may-2026 --no-pr
+```
+
+Use an external advisory directory:
+
+```sh
+patch-patrol --root /Users/sam/repos --advisory-dir ./company-advisories --rule some-advisory
+```
+
+## Development
+
+Patch Patrol is written in TypeScript. Source files live in `src/`, and the published CLI runs compiled JavaScript from `dist/` through the thin executable shim in `bin/`.
+
+```sh
+pnpm install
+pnpm run check
+```
+
+Build only:
+
+```sh
+pnpm run build
+```
+
+## Safety
+
+- Repos with uncommitted changes are skipped before edits are made.
+- Scan-only runs do not touch files.
+- Action mode only modifies projects you select, unless `--yes` is used.
+- Pull requests are opened only after a branch and commit are created successfully.

package/advisories/next-may-2026.json

@@ -0,0 +1,63 @@
+{
+  "id": "next-may-2026",
+  "title": "Next.js May 2026 security release",
+  "branchName": "nextjs-may-2026-security-release",
+  "commitMessage": "Update Next.js security release dependencies",
+  "prTitle": "Update Next.js security release dependencies",
+  "prBody": "Updates packages affected by the Next.js May 2026 security release.\n\nAdvisory: https://vercel.com/changelog/next-js-may-2026-security-release#affected-versions",
+  "packages": [
+    {
+      "name": "next",
+      "affected": [
+        {
+          "major": 13,
+          "upgradeTo": "15.5.18",
+          "reason": "Next.js 13.x is affected; upgrade to 15.5.18 or 16.2.6."
+        },
+        {
+          "major": 14,
+          "upgradeTo": "15.5.18",
+          "reason": "Next.js 14.x is affected; upgrade to 15.5.18 or 16.2.6."
+        },
+        {
+          "major": 15,
+          "maxVersion": "15.5.17",
+          "upgradeTo": "15.5.18",
+          "reason": "Next.js 15.x <= 15.5.17 is affected."
+        },
+        {
+          "major": 16,
+          "maxVersion": "16.2.5",
+          "upgradeTo": "16.2.6",
+          "reason": "Next.js 16.x <= 16.2.5 is affected."
+        }
+      ]
+    },
+    {
+      "name": "react-server-dom-*",
+      "affected": [
+        {
+          "major": 19,
+          "minor": 0,
+          "maxVersion": "19.0.5",
+          "upgradeTo": "19.0.6",
+          "reason": "react-server-dom-* 19.0.x <= 19.0.5 is affected."
+        },
+        {
+          "major": 19,
+          "minor": 1,
+          "maxVersion": "19.1.6",
+          "upgradeTo": "19.1.7",
+          "reason": "react-server-dom-* 19.1.x <= 19.1.6 is affected."
+        },
+        {
+          "major": 19,
+          "minor": 2,
+          "maxVersion": "19.2.5",
+          "upgradeTo": "19.2.6",
+          "reason": "react-server-dom-* 19.2.x <= 19.2.5 is affected."
+        }
+      ]
+    }
+  ]
+}

package/bin/patch-patrol.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../dist/cli.js';
+
+runCli().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/dist/advisories.js

@@ -0,0 +1,132 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { DEPENDENCY_SECTIONS } from './constants.js';
+export async function loadRules(advisoryDir) {
+    const files = (await fs.readdir(advisoryDir))
+        .filter((file) => file.endsWith('.json'))
+        .sort((a, b) => a.localeCompare(b));
+    const rules = new Map();
+    for (const file of files) {
+        const filePath = path.join(advisoryDir, file);
+        const rule = JSON.parse(await fs.readFile(filePath, 'utf8'));
+        validateRule(rule, filePath);
+        rules.set(rule.id, rule);
+    }
+    return rules;
+}
+export function getUpdates(packageJson, rule, bumpLevels) {
+    const updates = [];
+    for (const section of DEPENDENCY_SECTIONS) {
+        const dependencies = packageJson[section];
+        if (!dependencies)
+            continue;
+        for (const [name, range] of Object.entries(dependencies)) {
+            const update = evaluateRule(rule, name, range);
+            if (update && bumpLevels.has(update.bumpLevel))
+                updates.push({ section, name, from: range, ...update });
+        }
+    }
+    return updates;
+}
+function validateRule(rule, filePath) {
+    const requiredStrings = ['id', 'title', 'branchName', 'commitMessage', 'prTitle', 'prBody'];
+    for (const key of requiredStrings) {
+        if (typeof rule[key] !== 'string' || !rule[key].trim()) {
+            throw new Error(`${filePath} must define a non-empty string: ${key}`);
+        }
+    }
+    if (!Array.isArray(rule.packages) || rule.packages.length === 0) {
+        throw new Error(`${filePath} must define at least one package rule.`);
+    }
+    for (const packageRule of rule.packages) {
+        if (typeof packageRule.name !== 'string' || !packageRule.name.trim()) {
+            throw new Error(`${filePath} has a package rule without a name.`);
+        }
+        if (!Array.isArray(packageRule.affected) || packageRule.affected.length === 0) {
+            throw new Error(`${filePath} package ${packageRule.name} must define affected ranges.`);
+        }
+        for (const affected of packageRule.affected) {
+            if (typeof affected.upgradeTo !== 'string' || !affected.upgradeTo.trim()) {
+                throw new Error(`${filePath} package ${packageRule.name} has an affected range without upgradeTo.`);
+            }
+        }
+    }
+}
+function evaluateRule(rule, name, range) {
+    const fromVersion = parseVersionFromRange(range);
+    if (!fromVersion)
+        return null;
+    for (const packageRule of rule.packages) {
+        if (!matchesPackageName(packageRule.name, name))
+            continue;
+        for (const affected of packageRule.affected) {
+            if (!matchesAffectedRange(fromVersion, affected))
+                continue;
+            const toVersion = parseVersion(affected.upgradeTo);
+            const bumpLevel = classifyBump(fromVersion, toVersion);
+            return makeUpdate(range, affected.upgradeTo, bumpLevel, affected.reason ?? `${name} ${range} is affected by ${rule.title}.`);
+        }
+    }
+    return null;
+}
+function matchesPackageName(pattern, name) {
+    if (!pattern.includes('*'))
+        return pattern === name;
+    const escaped = pattern
+        .split('*')
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        .join('.*');
+    return new RegExp(`^${escaped}$`).test(name);
+}
+function matchesAffectedRange(version, affected) {
+    if (affected.major !== undefined && version.major !== affected.major)
+        return false;
+    if (affected.minor !== undefined && version.minor !== affected.minor)
+        return false;
+    if (affected.patch !== undefined && version.patch !== affected.patch)
+        return false;
+    if (affected.minVersion && compareVersions(version, parseVersion(affected.minVersion)) < 0)
+        return false;
+    if (affected.maxVersion && compareVersions(version, parseVersion(affected.maxVersion)) > 0)
+        return false;
+    return true;
+}
+function classifyBump(fromVersion, toVersion) {
+    if (toVersion.major !== fromVersion.major)
+        return 'major';
+    if (toVersion.minor !== fromVersion.minor)
+        return 'minor';
+    return 'patch';
+}
+function makeUpdate(fromRange, version, bumpLevel, reason) {
+    const prefix = fromRange.match(/^[~^]/)?.[0] ?? '';
+    return { to: `${prefix}${version}`, bumpLevel, reason };
+}
+function parseVersionFromRange(range) {
+    if (typeof range !== 'string')
+        return null;
+    if (/^(workspace|catalog|npm|file|link|portal|git|https?):/.test(range))
+        return null;
+    if (!/\d+\.\d+\.\d+/.test(range))
+        return null;
+    return parseVersion(range);
+}
+function parseVersion(version) {
+    const match = version.match(/(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)/);
+    if (!match)
+        throw new Error(`Invalid version: ${version}`);
+    return {
+        major: Number(match.groups?.major),
+        minor: Number(match.groups?.minor),
+        patch: Number(match.groups?.patch),
+    };
+}
+function compareVersions(a, b) {
+    for (const key of ['major', 'minor', 'patch']) {
+        if (a[key] > b[key])
+            return 1;
+        if (a[key] < b[key])
+            return -1;
+    }
+    return 0;
+}

package/dist/cli.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { intro, outro } from '@clack/prompts';
+import { loadRules } from './advisories.js';
+import { actionRepo } from './repo-actions.js';
+import { finish, printRules } from './output.js';
+import { findRepos, runScan } from './scanner.js';
+import { getRuleOrThrow, parseArgs } from './options.js';
+import { printAffectedRepos } from './format.js';
+import { promptForAffectedRepos, promptForScanOptions } from './prompts.js';
+export async function runCli(argv = process.argv.slice(2)) {
+    const options = parseArgs(argv);
+    const rules = await loadRules(options.advisoryDir);
+    if (options.listRules) {
+        printRules(rules);
+        return;
+    }
+    if (options.interactive) {
+        intro('Patch Patrol');
+        await promptForScanOptions(options, rules);
+    }
+    const rule = getRuleOrThrow(rules, options.rule);
+    const root = path.resolve(options.root);
+    const repos = await findRepos(root);
+    const affectedRepos = await runScan(repos, root, rule, options);
+    printAffectedRepos(affectedRepos, options);
+    if (affectedRepos.length === 0 || options.dryRun) {
+        if (options.interactive)
+            outro('Scan complete.');
+        return;
+    }
+    const selectedRepos = options.yes ? affectedRepos : await promptForAffectedRepos(affectedRepos, options);
+    if (selectedRepos.length === 0) {
+        finish(options, 'No projects selected. Nothing changed.');
+        return;
+    }
+    for (const affectedRepo of selectedRepos) {
+        await actionRepo(affectedRepo, rule, options);
+    }
+    if (options.interactive)
+        outro('Selected projects processed.');
+}

package/dist/constants.js

@@ -0,0 +1,9 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SRC_DIR = path.dirname(fileURLToPath(import.meta.url));
+export const PACKAGE_ROOT = path.resolve(SRC_DIR, '..');
+export const DEFAULT_ADVISORY_DIR = path.join(PACKAGE_ROOT, 'advisories');
+export const DEFAULT_RULE_ID = 'next-may-2026';
+export const DEFAULT_BRANCH_PREFIX = 'patch-patrol';
+export const BUMP_LEVELS = ['major', 'minor', 'patch'];
+export const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies'];

package/dist/files.js

@@ -0,0 +1,14 @@
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+export async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function fsSyncExists(filePath) {
+    return fsSync.existsSync(filePath);
+}

package/dist/format.js

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { log, note } from '@clack/prompts';
+export function printAffectedRepos(affectedRepos, options) {
+    if (affectedRepos.length === 0) {
+        if (options.interactive)
+            log.success('No affected repos found.');
+        else
+            console.log('No affected repos found.');
+        return;
+    }
+    const summary = formatAffectedRepos(affectedRepos);
+    if (options.interactive)
+        note(summary, `Affected repos (${affectedRepos.length})`);
+    else
+        console.log(`\nAffected repos (${affectedRepos.length}):\n${summary}`);
+}
+export function formatAffectedRepos(affectedRepos) {
+    return affectedRepos
+        .map((affectedRepo, index) => {
+        const updates = affectedRepo.updates
+            .map((update) => `   [${update.bumpLevel}] ${update.section}.${update.name}: ${update.from} -> ${update.to}\n   ${update.reason}`)
+            .join('\n');
+        return `${index + 1}. ${path.basename(affectedRepo.repo)}\n${updates}`;
+    })
+        .join('\n\n');
+}
+export function summarizeUpdates(updates) {
+    return updates.map((update) => `${update.name} ${update.from} -> ${update.to} (${update.bumpLevel})`).join(', ');
+}

package/dist/git.js

@@ -0,0 +1,91 @@
+import path from 'node:path';
+import { promptForGithubRemote } from './prompts.js';
+import { run } from './shell.js';
+export function ensureClean(repo) {
+    const status = run('git', ['status', '--porcelain'], repo, { capture: true });
+    if (status.stdout.trim())
+        throw new Error(`${repo} has uncommitted changes; skipping to avoid overwriting local work.`);
+}
+export function checkoutFreshBranch(repo, rule, options) {
+    const defaultBranch = getDefaultBranch(repo);
+    run('git', ['checkout', defaultBranch], repo);
+    run('git', ['pull', '--ff-only'], repo);
+    run('git', ['checkout', '-B', getBranchName(rule, options)], repo);
+}
+export function commitChanges(repo, rule) {
+    run('git', ['add', ...getChangedFiles(repo)], repo);
+    run('git', ['commit', '-m', rule.commitMessage], repo);
+}
+export async function pushAndCreatePr(repo, rule, options) {
+    const branchName = getBranchName(rule, options);
+    const githubRemote = await ensureGithubRemote(repo);
+    run('git', ['push', '-u', githubRemote.name, branchName], repo);
+    if (!githubRemote.ownerRepo)
+        throw new Error(`Could not determine GitHub repo for remote ${githubRemote.name}.`);
+    const prArgs = ['pr', 'create', '--repo', githubRemote.ownerRepo, '--head', branchName, '--title', rule.prTitle, '--body', rule.prBody];
+    if (options.base)
+        prArgs.push('--base', options.base);
+    run('gh', prArgs, repo);
+}
+function getDefaultBranch(repo) {
+    const symbolic = run('git', ['symbolic-ref', 'refs/remotes/origin/HEAD', '--short'], repo, { capture: true, allowFailure: true });
+    if (symbolic?.stdout.trim())
+        return symbolic.stdout.trim().replace(/^origin\//, '');
+    const current = run('git', ['branch', '--show-current'], repo, { capture: true });
+    return current.stdout.trim() || 'main';
+}
+function getBranchName(rule, options) {
+    return `${options.branchPrefix}/${rule.branchName}`;
+}
+function hasChanges(repo) {
+    return Boolean(run('git', ['status', '--porcelain'], repo, { capture: true }).stdout.trim());
+}
+export function getChangedFiles(repo) {
+    return run('git', ['status', '--porcelain'], repo, { capture: true }).stdout
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => line.slice(3));
+}
+export { hasChanges };
+async function ensureGithubRemote(repo) {
+    const remotes = listRemotes(repo);
+    const github = remotes.find((remote) => remote.github);
+    if (github)
+        return github;
+    const origin = remotes.find((remote) => remote.name === 'origin') ?? remotes[0];
+    const suggestion = origin ? convertOriginToGithub(origin.url) : '';
+    const url = await promptForGithubRemote(path.basename(repo), suggestion, parseRemote);
+    const name = remotes.some((remote) => remote.name === 'github') ? 'github-pr' : 'github';
+    run('git', ['remote', 'add', name, url], repo);
+    return parseRemote(name, url);
+}
+function listRemotes(repo) {
+    const result = run('git', ['remote', '-v'], repo, { capture: true });
+    const remotes = new Map();
+    for (const line of result.stdout.trim().split('\n').filter(Boolean)) {
+        const match = line.match(/^(\S+)\s+(\S+)\s+\(fetch\)$/);
+        if (match)
+            remotes.set(match[1], parseRemote(match[1], match[2]));
+    }
+    return [...remotes.values()];
+}
+function parseRemote(name, url) {
+    const normalized = url
+        .replace(/^git@github\.com:/, 'https://github.com/')
+        .replace(/^ssh:\/\/git@github\.com\//, 'https://github.com/')
+        .replace(/\.git$/, '');
+    const match = normalized.match(/github\.com[/:](?<owner>[^/]+)\/(?<repo>[^/]+)$/);
+    return {
+        name,
+        url,
+        github: Boolean(match),
+        ownerRepo: match ? `${match.groups?.owner}/${match.groups?.repo}` : undefined,
+    };
+}
+function convertOriginToGithub(url) {
+    const match = url.match(/bitbucket\.org[:/](?<workspace>[^/]+)\/(?<repo>[^/.]+)(?:\.git)?$/i);
+    if (!match)
+        return '';
+    const owner = match.groups?.workspace === 'humaanco' ? 'humaan' : match.groups?.workspace;
+    return `git@github.com:${owner}/${match.groups?.repo}.git`;
+}

package/dist/options.js

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import process from 'node:process';
+import { BUMP_LEVELS, DEFAULT_ADVISORY_DIR, DEFAULT_BRANCH_PREFIX, DEFAULT_RULE_ID } from './constants.js';
+export function parseArgs(args) {
+    const options = {
+        root: process.cwd(),
+        rule: DEFAULT_RULE_ID,
+        base: undefined,
+        branchPrefix: DEFAULT_BRANCH_PREFIX,
+        advisoryDir: DEFAULT_ADVISORY_DIR,
+        bumpLevels: new Set(BUMP_LEVELS),
+        dryRun: false,
+        yes: false,
+        createPr: true,
+        skipInstall: false,
+        limit: 0,
+        listRules: false,
+        interactive: args.length === 0,
+    };
+    let hasExplicitBumpFilter = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const readValue = () => {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--'))
+                throw new Error(`Missing value for ${arg}`);
+            index += 1;
+            return value;
+        };
+        const addBumpFilter = (levels) => {
+            if (!hasExplicitBumpFilter) {
+                options.bumpLevels.clear();
+                hasExplicitBumpFilter = true;
+            }
+            for (const level of levels) {
+                if (!BUMP_LEVELS.includes(level))
+                    throw new Error(`Invalid bump level: ${level}`);
+                options.bumpLevels.add(level);
+            }
+        };
+        if (arg === '--root')
+            options.root = readValue();
+        else if (arg === '--rule')
+            options.rule = readValue();
+        else if (arg === '--advisory-dir')
+            options.advisoryDir = path.resolve(readValue());
+        else if (arg === '--base')
+            options.base = readValue();
+        else if (arg === '--branch-prefix')
+            options.branchPrefix = readValue();
+        else if (arg === '--limit')
+            options.limit = Number(readValue());
+        else if (arg === '--bump')
+            addBumpFilter(readValue().split(',').map((level) => level.trim()).filter(Boolean));
+        else if (arg === '--major')
+            addBumpFilter(['major']);
+        else if (arg === '--minor')
+            addBumpFilter(['minor']);
+        else if (arg === '--patch')
+            addBumpFilter(['patch']);
+        else if (arg === '--dry-run')
+            options.dryRun = true;
+        else if (arg === '--interactive')
+            options.interactive = true;
+        else if (arg === '--list-rules')
+            options.listRules = true;
+        else if (arg === '--yes' || arg === '-y')
+            options.yes = true;
+        else if (arg === '--no-pr')
+            options.createPr = false;
+        else if (arg === '--skip-install')
+            options.skipInstall = true;
+        else if (arg === '--help' || arg === '-h') {
+            printHelp();
+            process.exit(0);
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    if (options.bumpLevels.size === 0)
+        throw new Error('Select at least one bump level.');
+    return options;
+}
+export function getRuleOrThrow(rules, ruleId) {
+    const rule = rules.get(ruleId);
+    if (!rule)
+        throw new Error(`Unknown rule "${ruleId}". Available rules: ${[...rules.keys()].join(', ')}`);
+    return rule;
+}
+function printHelp() {
+    console.log(`patch-patrol
+
+Usage:
+  patch-patrol
+  patch-patrol --root /path/to/repos [options]
+
+Options:
+  --rule <name>            Rule to apply. Default: ${DEFAULT_RULE_ID}
+  --advisory-dir <path>    Directory containing advisory JSON files.
+  --base <branch>          Base branch for PRs. Defaults to GitHub default branch.
+  --branch-prefix <name>   Branch namespace. Default: ${DEFAULT_BRANCH_PREFIX}
+  --limit <number>         Stop after processing this many affected repos.
+  --bump <levels>          Only include bump levels: major, minor, patch. Comma-separated.
+  --major                  Only include major version bumps. Can combine with --minor/--patch.
+  --minor                  Only include minor version bumps. Can combine with --major/--patch.
+  --patch                  Only include patch version bumps. Can combine with --major/--minor.
+  --dry-run                Scan and report affected repos without editing files.
+  --interactive            Prompt for scan options and project selection.
+  --list-rules             List available advisory rules.
+  --no-pr                  Update locally without pushing or opening PRs.
+  --skip-install           Do not refresh lockfiles.
+  --yes, -y                Do not prompt before updating affected repos.
+  --help, -h               Show this help.
+`);
+}

package/dist/output.js

@@ -0,0 +1,12 @@
+import { outro } from '@clack/prompts';
+export function printRules(rules) {
+    for (const rule of rules.values()) {
+        console.log(`${rule.id}: ${rule.title}`);
+    }
+}
+export function finish(options, message) {
+    if (options.interactive)
+        outro(message);
+    else
+        console.log(message);
+}

package/dist/package-manager.js

@@ -0,0 +1,23 @@
+import path from 'node:path';
+import { fsSyncExists } from './files.js';
+import { run } from './shell.js';
+export function refreshLockfile(repo) {
+    const manager = detectPackageManager(repo);
+    if (manager === 'pnpm')
+        run('pnpm', ['install', '--lockfile-only'], repo);
+    else if (manager === 'yarn')
+        run('yarn', ['install', '--mode=update-lockfile'], repo, { allowFailure: true }) || run('yarn', ['install'], repo);
+    else if (manager === 'bun')
+        run('bun', ['install', '--lockfile-only'], repo);
+    else
+        run('npm', ['install', '--package-lock-only'], repo);
+}
+function detectPackageManager(repo) {
+    if (fsSyncExists(path.join(repo, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (fsSyncExists(path.join(repo, 'yarn.lock')))
+        return 'yarn';
+    if (fsSyncExists(path.join(repo, 'bun.lockb')) || fsSyncExists(path.join(repo, 'bun.lock')))
+        return 'bun';
+    return 'npm';
+}

package/dist/prompts.js

@@ -0,0 +1,118 @@
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { cancel, confirm, isCancel, multiselect, select, text } from '@clack/prompts';
+import { parseSelection } from './selection.js';
+import { summarizeUpdates } from './format.js';
+export async function promptForScanOptions(options, rules) {
+    options.root = await promptForRoot(options.root);
+    options.rule = await promptForRule(rules, options.rule);
+    options.bumpLevels = new Set(await promptForBumpLevels(options.bumpLevels));
+}
+export async function promptForRoot(defaultRoot) {
+    const root = await text({
+        message: 'Repo or folder of repos',
+        placeholder: defaultRoot,
+        initialValue: defaultRoot,
+        validate(value) {
+            if (!value.trim())
+                return 'Enter a repo path or a folder containing repos.';
+            if (!fsSync.existsSync(path.resolve(value)))
+                return 'That path does not exist.';
+            return undefined;
+        },
+    });
+    handleCancel(root);
+    return path.resolve(root);
+}
+export async function promptForRule(rules, defaultRuleId) {
+    const selectedRule = await select({
+        message: 'Select an advisory rule',
+        initialValue: defaultRuleId,
+        options: [...rules.values()].map((rule) => ({
+            value: rule.id,
+            label: rule.id,
+            hint: rule.title,
+        })),
+    });
+    handleCancel(selectedRule);
+    return selectedRule;
+}
+export async function promptForBumpLevels(defaultLevels) {
+    const selectedLevels = await multiselect({
+        message: 'Filter by version bump level',
+        required: true,
+        initialValues: [...defaultLevels],
+        options: [
+            { value: 'major', label: 'Major', hint: 'Example: 14.2.20 -> 15.5.18' },
+            { value: 'minor', label: 'Minor', hint: 'Example: 16.1.6 -> 16.2.6' },
+            { value: 'patch', label: 'Patch', hint: 'Example: 15.5.7 -> 15.5.18' },
+        ],
+    });
+    handleCancel(selectedLevels);
+    return selectedLevels;
+}
+export async function promptForAffectedRepos(affectedRepos, options) {
+    if (!options.interactive)
+        return promptForAffectedReposText(affectedRepos);
+    const selectedRepos = await multiselect({
+        message: 'Select projects to update and open PRs for',
+        required: false,
+        options: affectedRepos.map((affectedRepo) => ({
+            value: affectedRepo.repo,
+            label: path.basename(affectedRepo.repo),
+            hint: summarizeUpdates(affectedRepo.updates),
+        })),
+    });
+    handleCancel(selectedRepos);
+    if (selectedRepos.length === 0)
+        return [];
+    const proceed = await confirm({
+        message: `Update ${selectedRepos.length} project${selectedRepos.length === 1 ? '' : 's'} and open PR${selectedRepos.length === 1 ? '' : 's'}?`,
+        initialValue: true,
+    });
+    handleCancel(proceed);
+    if (!proceed)
+        return [];
+    return affectedRepos.filter((affectedRepo) => selectedRepos.includes(affectedRepo.repo));
+}
+export async function promptForGithubRemote(repoName, suggestion, parseRemote) {
+    const answer = await text({
+        message: `GitHub remote URL for ${repoName}`,
+        placeholder: suggestion || 'git@github.com:owner/repo.git',
+        initialValue: suggestion,
+        validate(value) {
+            if (!value.trim())
+                return 'Enter a GitHub remote URL.';
+            if (!parseRemote('github', value.trim()).github)
+                return 'Enter a GitHub remote URL.';
+            return undefined;
+        },
+    });
+    handleCancel(answer);
+    return answer.trim();
+}
+async function promptForAffectedReposText(affectedRepos) {
+    const answer = await text({
+        message: 'Projects to update and open PRs for',
+        placeholder: '1,3-5, all, or empty to skip',
+        validate(value) {
+            const selection = value.trim().toLowerCase();
+            if (!selection || selection === 'none' || selection === 'n' || selection === 'all' || selection === 'a')
+                return undefined;
+            return parseSelection(selection, affectedRepos.length).length > 0 ? undefined : 'Enter a valid selection, such as 1,3-5, all, or none.';
+        },
+    });
+    handleCancel(answer);
+    const selection = answer.trim().toLowerCase();
+    if (!selection || selection === 'none' || selection === 'n')
+        return [];
+    if (selection === 'all' || selection === 'a')
+        return affectedRepos;
+    return parseSelection(selection, affectedRepos.length).map((index) => affectedRepos[index]);
+}
+export function handleCancel(value) {
+    if (!isCancel(value))
+        return;
+    cancel('Cancelled.');
+    process.exit(0);
+}

package/dist/repo-actions.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getUpdates } from './advisories.js';
+import { checkoutFreshBranch, commitChanges, ensureClean, hasChanges, pushAndCreatePr } from './git.js';
+import { refreshLockfile } from './package-manager.js';
+export async function actionRepo(affectedRepo, rule, options) {
+    const { repo, packageJsonPath, updates } = affectedRepo;
+    console.log(`\n${path.basename(repo)}`);
+    for (const update of updates) {
+        console.log(`  [${update.bumpLevel}] ${update.section}.${update.name}: ${update.from} -> ${update.to} (${update.reason})`);
+    }
+    ensureClean(repo);
+    checkoutFreshBranch(repo, rule, options);
+    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+    const freshUpdates = getUpdates(packageJson, rule, options.bumpLevels);
+    if (freshUpdates.length === 0) {
+        console.log('  No affected dependencies after updating the base branch; skipping.');
+        return;
+    }
+    applyUpdates(packageJson, freshUpdates);
+    await fs.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+    if (!options.skipInstall)
+        refreshLockfile(repo);
+    if (!hasChanges(repo)) {
+        console.log('  No changes after update; skipping.');
+        return;
+    }
+    commitChanges(repo, rule);
+    if (!options.createPr) {
+        console.log('  Updated locally; PR creation disabled.');
+        return;
+    }
+    await pushAndCreatePr(repo, rule, options);
+}
+function applyUpdates(packageJson, updates) {
+    for (const update of updates) {
+        const dependencies = packageJson[update.section];
+        if (dependencies)
+            dependencies[update.name] = update.to;
+    }
+}

package/dist/scanner.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spinner } from '@clack/prompts';
+import { getUpdates } from './advisories.js';
+import { exists } from './files.js';
+export async function runScan(repos, root, rule, options) {
+    if (!options.interactive) {
+        console.log(`Scanning ${repos.length} repos in ${root} using rule: ${rule.title}`);
+        return scanRepos(repos, rule, options);
+    }
+    const scanSpinner = spinner();
+    scanSpinner.start(`Scanning ${repos.length} repos in ${root}`);
+    const affectedRepos = await scanRepos(repos, rule, options);
+    scanSpinner.stop(`Found ${affectedRepos.length} affected repo${affectedRepos.length === 1 ? '' : 's'}.`);
+    return affectedRepos;
+}
+export async function findRepos(root) {
+    if (await isNodeRepo(root))
+        return [root];
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const repos = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const repoPath = path.join(root, entry.name);
+        if (await isNodeRepo(repoPath))
+            repos.push(repoPath);
+    }
+    return repos.sort((a, b) => a.localeCompare(b));
+}
+async function isNodeRepo(repoPath) {
+    return await exists(path.join(repoPath, '.git')) && await exists(path.join(repoPath, 'package.json'));
+}
+async function scanRepos(repos, rule, options) {
+    const affectedRepos = [];
+    for (const repo of repos) {
+        const affectedRepo = await scanRepo(repo, rule, options);
+        if (!affectedRepo)
+            continue;
+        affectedRepos.push(affectedRepo);
+        if (options.limit > 0 && affectedRepos.length >= options.limit)
+            break;
+    }
+    return affectedRepos;
+}
+async function scanRepo(repo, rule, options) {
+    const packageJsonPath = path.join(repo, 'package.json');
+    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+    const updates = getUpdates(packageJson, rule, options.bumpLevels);
+    if (updates.length === 0)
+        return null;
+    return { repo, packageJsonPath, updates };
+}

package/dist/selection.js

@@ -0,0 +1,23 @@
+export function parseSelection(selection, max) {
+    const indexes = new Set();
+    for (const part of selection.split(',').map((item) => item.trim()).filter(Boolean)) {
+        const range = part.match(/^(\d+)\s*-\s*(\d+)$/);
+        if (range) {
+            const start = Number(range[1]);
+            const end = Number(range[2]);
+            if (!isValidSelectionNumber(start, max) || !isValidSelectionNumber(end, max) || start > end)
+                return [];
+            for (let value = start; value <= end; value += 1)
+                indexes.add(value - 1);
+            continue;
+        }
+        const value = Number(part);
+        if (!isValidSelectionNumber(value, max))
+            return [];
+        indexes.add(value - 1);
+    }
+    return [...indexes].sort((a, b) => a - b);
+}
+function isValidSelectionNumber(value, max) {
+    return Number.isInteger(value) && value >= 1 && value <= max;
+}

package/dist/shell.js

@@ -0,0 +1,15 @@
+import { spawnSync } from 'node:child_process';
+export function run(command, args, cwd, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: options.capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+    });
+    if (result.status !== 0) {
+        if (options.allowFailure)
+            return null;
+        const stderr = result.stderr ? `\n${result.stderr}` : '';
+        throw new Error(`${command} ${args.join(' ')} failed in ${cwd}.${stderr}`);
+    }
+    return result;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@humaan/patch-patrol",
+  "version": "0.2.2",
+  "description": "Scan local repositories for advisory-driven package bumps, update them, and open pull requests.",
+  "type": "module",
+  "bin": {
+    "patch-patrol": "./bin/patch-patrol.js"
+  },
+  "files": [
+    "advisories/",
+    "bin/",
+    "dist/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/humaan/patch-patrol.git"
+  },
+  "bugs": {
+    "url": "https://github.com/humaan/patch-patrol/issues"
+  },
+  "homepage": "https://github.com/humaan/patch-patrol#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "check": "pnpm run typecheck && pnpm run build && node --check bin/patch-patrol.js && node --check dist/*.js",
+    "scan:dry": "pnpm run build && node bin/patch-patrol.js --root .. --dry-run --no-pr"
+  }
+}