depfresh 0.10.1 → 0.11.1

package/README.md

@@ -18,7 +18,7 @@ Spiritual successor to [taze](https://github.com/antfu/taze) by Anthony Fu -- a
 - **Per-package modes** -- `packageMode` lets you set exact, glob, or regex patterns per dependency.
 - **Write safely** -- `--write` updates files. `--verify-command` tests each dep individually and reverts failures.
 - **Post-write hooks** -- `--execute`, `--install`, `--update`. Chain commands after writing.
-- **Global packages** -- `--global` checks npm, pnpm, and bun globals.
+- **Global packages** -- `--global` checks one detected manager, `--global-all` scans npm + pnpm + bun with deduped package names.
 - **Private registries** -- full `.npmrc` support. Scoped registries, auth tokens, env vars. Fixed from day one.
 - **JSON output** -- structured envelope for scripts and AI agents. No ANSI noise.
 - **CI mode** -- `--fail-on-outdated` exits with code 1. Plug it into your pipeline.
@@ -29,13 +29,15 @@ Spiritual successor to [taze](https://github.com/antfu/taze) by Anthony Fu -- a
 - **Sorting** -- 6 strategies: by diff severity, publish time, or name.
 - **CRLF preservation** -- Windows line endings survive the write. You're welcome.
 - **Nested workspace detection** -- auto-skips monorepos inside monorepos.
-- **Programmatic API** -- 9 exported functions, 7 lifecycle callbacks, full type safety.
+- **Programmatic API** -- lifecycle callbacks + addon system for custom workflows.
 
 ## Why
 
 Because `npm outdated` gives you a table and then abandons you. Because Renovate requires a PhD in YAML. Because your AI coding assistant should be able to update your deps without you holding its hand.
 
-depfresh checks every `package.json` in your project, tells you what's outdated, and optionally writes the updates. Monorepos, workspace catalogs, private registries - it handles all of it without a config file.
+depfresh checks every package manifest (`package.json`, `package.yaml`) in your project, tells you what's outdated, and optionally writes the updates. Monorepos, workspace catalogs, private registries - it handles all of it without a config file.
+
+If both `package.yaml` and `package.json` exist in the same directory, depfresh uses `package.yaml` and skips the sibling `package.json` to avoid duplicate package entries.
 
 ## Install
 
@@ -85,6 +87,16 @@ depfresh -w --verify-command "pnpm test"
 
 # CI: fail if anything is outdated
 depfresh --fail-on-outdated
+
+# Skip specific directories from recursive scan
+depfresh --ignore-paths "apps/legacy/**,examples/**"
+
+# Bypass cache for one run (same behavior)
+depfresh --refresh-cache
+depfresh --no-cache
+
+# Check globals across npm + pnpm + bun (deduped names)
+depfresh --global-all
 ```
 
 ## CLI Flags
@@ -93,14 +105,18 @@ The top flags to get you started. Full reference with all 27+ flags: **[docs/cli
 
 | Flag | Alias | Default | Description |
 |------|-------|---------|-------------|
-| `--recursive` | `-r` | `true` | Recursively search for package.json files |
+| `--recursive` | `-r` | `true` | Recursively search for package manifests (`package.json`, `package.yaml`) |
 | `--write` | `-w` | `false` | Write updated versions to package files |
 | `--interactive` | `-I` | `false` | Select which deps to update |
 | `--mode` | `-m` | `default` | Range mode: `default` `major` `minor` `patch` `latest` `newest` `next` |
 | `--include` | `-n` | -- | Only include packages matching regex (comma-separated) |
 | `--exclude` | `-x` | -- | Exclude packages matching regex (comma-separated) |
-| `--force` | `-f` | `false` | Force update even if version is satisfied |
-| `--global` | `-g` | `false` | Check global packages |
+| `--ignore-paths` | -- | -- | Extra ignore globs (comma-separated), merged with default ignored paths |
+| `--force` | `-f` | `false` | Force update even if version is satisfied (does not bypass cache) |
+| `--refresh-cache` | -- | `false` | Bypass cache reads and fetch fresh metadata for this run |
+| `--no-cache` | -- | `false` | Alias for `--refresh-cache` |
+| `--global` | `-g` | `false` | Check global packages for one detected package manager |
+| `--global-all` | -- | `false` | Check global packages across npm, pnpm, and bun with deduped package names |
 | `--output` | `-o` | `table` | Output format: `table` `json` |
 | `--execute` | `-e` | -- | Run command after writing (e.g. `"pnpm test"`) |
 | `--verify-command` | `-V` | -- | Run command per dep, revert on failure |
@@ -126,6 +142,22 @@ export default defineConfig({
 })
 ```
 
+Addon example (programmatic API):
+
+```typescript
+import { check, resolveConfig, type depfreshAddon } from 'depfresh'
+
+const addon: depfreshAddon = {
+  name: 'audit-log',
+  afterPackageWrite(_ctx, pkg, changes) {
+    console.log(`updated ${pkg.name}: ${changes.length} changes`)
+  },
+}
+
+const options = await resolveConfig({ write: true, addons: [addon] })
+await check(options)
+```
+
 Full options reference: **[docs/configuration/](docs/configuration/)**
 
 ## JSON Output
@@ -244,7 +276,7 @@ const options = await resolveConfig({
 const exitCode = await check(options)
 ```
 
-9 exported functions, 7 lifecycle callbacks, 16+ types. Full API reference: **[docs/api/](docs/api/)**
+Programmatic API with lifecycle callbacks, addon plugins, and full typed exports. Full reference: **[docs/api/](docs/api/)**
 
 ## Monorepo Support
 
@@ -253,11 +285,11 @@ depfresh auto-detects workspace structures. No config needed.
 | Package Manager | Workspaces | Catalogs |
 |----------------|------------|----------|
 | pnpm | `pnpm-workspace.yaml` | `catalog:` protocol |
-| Bun | `workspaces` in `package.json` | `workspaces.catalog` |
-| Yarn | `workspaces` in `package.json` | `.yarnrc.yml` catalogs |
-| npm | `workspaces` in `package.json` | -- |
+| Bun | `workspaces` in `package.json` or `package.yaml` | `workspaces.catalog` |
+| Yarn | `workspaces` in `package.json` or `package.yaml` | `.yarnrc.yml` catalogs |
+| npm | `workspaces` in `package.json` or `package.yaml` | -- |
 
-Workspace catalogs are resolved and updated in-place. Your `pnpm-workspace.yaml` catalog entries get depfreshaded alongside your `package.json` deps. No manual sync needed.
+Workspace catalogs are resolved and updated in-place. Your `pnpm-workspace.yaml` catalog entries get depfreshaded alongside your manifest deps (`package.json` / `package.yaml`). No manual sync needed.
 
 ## Private Registries
 
@@ -271,22 +303,59 @@ depfresh reads `.npmrc` from your project and home directory. Scoped registries,
 
 This was broken in taze for 4+ years. I fixed it on day one. You're welcome.
 
-## What I Fixed from taze
-
-Not to throw shade at taze -- it served the community well for years. But some things needed fixing, and "PR welcome" only goes so far when the PRs sit open for months.
-
-| Problem | taze | depfresh |
-|---------|------|------|
-| `.npmrc` / private registries | Ignored | Full support |
-| Network retry | None | Exponential backoff |
-| Write clobber (bun catalogs) | Data loss | Single-writer architecture |
-| Version resolution ordering | Assumed sorted arrays | Explicit semver comparison |
-| Interactive mode | Flickery | @clack/prompts |
-| JSON output | None | Structured envelope |
-| Dep type filtering | None | `--deps-only` / `--dev-only` |
-| Config merging | deepmerge (CJS) | defu (ESM) |
-| npm config loading | @npmcli/config (heavy, hacky) | Direct ini parsing |
-| Cache | JSON file (race conditions) | SQLite with WAL mode |
+## depfresh vs taze
+
+Verified against taze v19.9.2 (commit `31c6fe8`, 2026-01-20). Not marketing. Real code inspection, runtime test runs, CLI smoke checks on actual repos.
+
+### Feature parity (both have it)
+
+| Feature | taze | depfresh | Notes |
+|---------|------|----------|-------|
+| 7 range modes | yes | yes | |
+| Include/exclude filters | yes | yes | depfresh adds glob patterns alongside regex |
+| Interactive TUI | yes | yes | Both have vim keys + per-version selection |
+| `--cwd` | yes | yes | |
+| `--fail-on-outdated` | yes | yes | |
+| `package.yaml` support | yes | yes | |
+| Addon/plugin API | yes | yes | |
+| pnpm catalogs | yes | yes | |
+| Yarn catalogs | yes | yes | |
+| CRLF preservation | yes | yes | |
+| CJK width handling | yes | yes | |
+
+### Where depfresh is ahead
+
+| Feature | taze | depfresh |
+|---------|------|----------|
+| JSON output envelope | no ([#201](https://github.com/antfu-collective/taze/issues/201) open) | Structured envelope with schema version |
+| Machine-readable CLI contract | no | `--help-json` with workflows, flag relationships, schema |
+| `--deps-only` / `--dev-only` | no ([#101](https://github.com/antfu-collective/taze/issues/101) open) | yes |
+| `packageMode` precedence | buggy ([#91](https://github.com/antfu-collective/taze/issues/91) open) | Deterministic |
+| Global package breadth | npm + pnpm | npm + pnpm + bun (`--global-all`) |
+| Bun catalog writes | Bug history, data loss risk | Single-writer architecture, tested |
+| `.npmrc` / private registries | Ignored for years | Full support from day one |
+| `.npmrc` transport (proxy/TLS/CA) | Parsed, not applied | Applied via `undici` transport adapter |
+| Network retry | None | Exponential backoff, non-transient errors fail fast |
+| Cache | JSON file (race conditions) | SQLite WAL mode, memory fallback |
+| Verify + rollback | no | `--verify-command` tests each dep, reverts failures |
+| Typed error hierarchy | Limited | Structured subclasses with `.code` and `.cause` |
+| Structured JSON errors | no | JSON error envelope with `error.code`, `error.retryable` |
+| Explicit cache bypass | no | `--refresh-cache` / `--no-cache` |
+
+### Where taze is ahead
+
+| Area | Why |
+|------|-----|
+| Ecosystem adoption | 4,061 stars, years of trust, larger user base |
+| npm config edge cases | `@npmcli/config` may cover obscure auth patterns we haven't hit yet |
+
+### Numbers
+
+| Metric | taze v19.9.2 | depfresh v0.11.0 |
+|--------|-------------:|------------------:|
+| Test files | 13 | 77 |
+| Passing tests | 55 | 598 |
+| CLI flags | 24 | 36 |
 
 ## Documentation
 
@@ -294,7 +363,7 @@ The full docs, for people who read manuals before assembling furniture.
 
 - **[CLI Reference](docs/cli/)** -- all 27+ flags, modes, sorting, filtering, hooks, interactive, CI, workspaces
 - **[Configuration](docs/configuration/)** -- config files, every option, packageMode, depFields, private registries, cache
-- **[Programmatic API](docs/api/)** -- exported functions, lifecycle callbacks, types, workflow examples
+- **[Programmatic API](docs/api/)** -- exported functions, lifecycle callbacks, addon plugins, types, workflow examples
 - **[Output Formats](docs/output-formats/)** -- table, JSON, exit codes, AI agent integration
 - **[Agent Workflows](docs/agents/README.md)** -- copy-paste quickstarts for Codex, Claude Code, and Gemini CLI
 - **[Integrations](docs/integrations/README.md)** -- GitHub Actions and thin MCP wrapper guidance

package/dist/chunks/capabilities.mjs

@@ -6,7 +6,7 @@ import 'node:fs/promises';
 import 'node:url';
 import 'defu';
 import 'pathe';
-import '../shared/depfresh.FmznAfq4.mjs';
+import '../shared/depfresh.CHHNqHXD.mjs';
 import '../shared/depfresh.Dxgqypc6.mjs';
 import 'ansis';
 
@@ -50,7 +50,7 @@ const FLAG_RELATIONSHIPS = {
 };
 const JSON_OUTPUT_SCHEMA = {
   "packages[]": "Array of scanned packages with their updates",
-  "packages[].name": "Package name from package.json",
+  "packages[].name": "Package name from package manifest",
   "packages[].updates[]": "Array of dependencies with available updates",
   "packages[].updates[].name": "Dependency name",
   "packages[].updates[].current": "Current version range",

package/dist/chunks/config.mjs

@@ -2,7 +2,7 @@ import { readFile, access } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 import { defu } from 'defu';
 import { join } from 'pathe';
-import { C as ConfigError } from '../shared/depfresh.FmznAfq4.mjs';
+import { C as ConfigError } from '../shared/depfresh.CHHNqHXD.mjs';
 import { c as createLogger } from '../shared/depfresh.Dxgqypc6.mjs';
 
 const DEFAULT_OPTIONS = {
@@ -18,10 +18,12 @@ const DEFAULT_OPTIONS = {
   timeout: 1e4,
   retries: 2,
   cacheTTL: 30 * 60 * 1e3,
+  refreshCache: false,
   output: "table",
   loglevel: "info",
   peer: false,
   global: false,
+  globalAll: false,
   ignorePaths: ["**/node_modules/**", "**/dist/**", "**/coverage/**", "**/.git/**"],
   ignoreOtherWorkspaces: true,
   all: false,

package/dist/chunks/index.mjs

@@ -1,5 +1,5 @@
-import { c as check } from '../shared/depfresh.BkxecpDK.mjs';
-export { d as detectPackageManager } from '../shared/depfresh.BkxecpDK.mjs';
+import { c as check } from '../shared/depfresh.C-me_t4a.mjs';
+export { d as detectPackageManager } from '../shared/depfresh.C-me_t4a.mjs';
 import 'ansis';
 import '../shared/depfresh.Dxgqypc6.mjs';
 import 'node:fs';
@@ -9,13 +9,15 @@ import 'ini';
 import 'pathe';
 import './json-output.mjs';
 import 'node:child_process';
-import '../shared/depfresh.FmznAfq4.mjs';
+import '../shared/depfresh.CHHNqHXD.mjs';
 import 'detect-indent';
 import 'semver';
 import 'pnpm-workspace-yaml';
 import 'yaml';
 import 'p-limit';
+import 'undici';
 import 'better-sqlite3';
+import 'node:crypto';
 import 'tinyglobby';
 
 

package/dist/chunks/index2.mjs

@@ -1,6 +1,6 @@
 import * as readline from 'node:readline';
 import * as semver from 'semver';
-import { g as getVersionPrefix, f as applyVersionPrefix, h as getDiff, t as timeDifference, s as stripAnsi, i as truncate, j as padEnd, b as colorizeVersionDiff, a as arrow, e as colorDiff } from '../shared/depfresh.BkxecpDK.mjs';
+import { g as getVersionPrefix, f as applyVersionPrefix, h as getDiff, t as timeDifference, s as stripAnsi, i as truncate, j as padEnd, b as colorizeVersionDiff, a as arrow, e as colorDiff } from '../shared/depfresh.C-me_t4a.mjs';
 import c from 'ansis';
 import '../shared/depfresh.Dxgqypc6.mjs';
 import 'node:fs';
@@ -10,12 +10,14 @@ import 'ini';
 import 'pathe';
 import './json-output.mjs';
 import 'node:child_process';
-import '../shared/depfresh.FmznAfq4.mjs';
+import '../shared/depfresh.CHHNqHXD.mjs';
 import 'detect-indent';
 import 'pnpm-workspace-yaml';
 import 'yaml';
 import 'p-limit';
+import 'undici';
 import 'better-sqlite3';
+import 'node:crypto';
 import 'tinyglobby';
 
 const MAX_VERSIONS = 20;

package/dist/chunks/index3.mjs

@@ -1,8 +1,73 @@
 import './config.mjs';
-import '../shared/depfresh.FmznAfq4.mjs';
+import '../shared/depfresh.CHHNqHXD.mjs';
 import { execSync } from 'node:child_process';
 import { c as createLogger } from '../shared/depfresh.Dxgqypc6.mjs';
-import '../shared/depfresh.BkxecpDK.mjs';
+import '../shared/depfresh.C-me_t4a.mjs';
+
+function addonVSCode(pkg, changes) {
+  const vscodeChange = changes.find((c) => c.name === "@types/vscode");
+  if (!vscodeChange) return;
+  const raw = pkg.raw;
+  if (raw.engines && typeof raw.engines === "object") {
+    const engines = raw.engines;
+    if (engines.vscode) {
+      engines.vscode = `^${vscodeChange.targetVersion}`;
+    }
+  }
+}
+function createVSCodeAddon() {
+  return {
+    name: "vscode-engine-sync",
+    beforePackageWrite(_ctx, pkg, changes) {
+      addonVSCode(pkg, changes);
+      return true;
+    }
+  };
+}
+
+const GLOBAL_ALL_PACKAGE_MANAGERS = ["npm", "pnpm", "bun"];
+function isPackageManagerName(value) {
+  return value === "npm" || value === "pnpm" || value === "bun" || value === "yarn";
+}
+function dedupeGlobalPackageRecords(records) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const existing = byName.get(record.name);
+    if (!existing) {
+      byName.set(record.name, {
+        version: record.version,
+        managers: /* @__PURE__ */ new Set([record.manager])
+      });
+      continue;
+    }
+    existing.managers.add(record.manager);
+  }
+  const sortedEntries = [...byName.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const packages = sortedEntries.map(([name, value]) => ({
+    name,
+    version: value.version
+  }));
+  const managersByDependency = Object.fromEntries(
+    sortedEntries.map(([name, value]) => [name, [...value.managers]])
+  );
+  return { packages, managersByDependency };
+}
+function getGlobalWriteTargets(pkg, depName) {
+  const raw = pkg.raw;
+  const mappedTargets = raw.managersByDependency?.[depName];
+  if (mappedTargets && mappedTargets.length > 0) {
+    return [...new Set(mappedTargets)];
+  }
+  if (!pkg.filepath.startsWith("global:")) {
+    return [];
+  }
+  const suffix = pkg.filepath.slice("global:".length);
+  if (!suffix) {
+    return [];
+  }
+  const parsedTargets = suffix.split("+").map((name) => name.trim()).filter((name) => name.length > 0 && isPackageManagerName(name));
+  return [...new Set(parsedTargets)];
+}
 
 function detectGlobalPackageManager(pm) {
   if (pm && (pm === "npm" || pm === "pnpm" || pm === "bun")) {
@@ -110,6 +175,39 @@ function loadGlobalPackages(pm) {
     }
   ];
 }
+function loadGlobalPackagesAll() {
+  const records = GLOBAL_ALL_PACKAGE_MANAGERS.flatMap(
+    (manager) => listGlobalPackages(manager).map((pkg) => ({
+      manager,
+      name: pkg.name,
+      version: pkg.version
+    }))
+  );
+  if (records.length === 0) {
+    return [];
+  }
+  const deduped = dedupeGlobalPackageRecords(records);
+  const deps = deduped.packages.map((pkg) => ({
+    name: pkg.name,
+    currentVersion: pkg.version,
+    source: "dependencies",
+    update: true,
+    parents: []
+  }));
+  return [
+    {
+      name: "Global packages",
+      type: "global",
+      filepath: `global:${GLOBAL_ALL_PACKAGE_MANAGERS.join("+")}`,
+      deps,
+      resolved: [],
+      raw: {
+        managersByDependency: deduped.managersByDependency
+      },
+      indent: "  "
+    }
+  ];
+}
 function writeGlobalPackage(pm, name, version) {
   const logger = createLogger("info");
   switch (pm) {
@@ -131,8 +229,10 @@ function writeGlobalPackage(pm, name, version) {
 const global = {
   __proto__: null,
   detectGlobalPackageManager: detectGlobalPackageManager,
+  getGlobalWriteTargets: getGlobalWriteTargets,
   listGlobalPackages: listGlobalPackages,
   loadGlobalPackages: loadGlobalPackages,
+  loadGlobalPackagesAll: loadGlobalPackagesAll,
   parseBunGlobalList: parseBunGlobalList,
   parseNpmGlobalList: parseNpmGlobalList,
   parsePnpmGlobalList: parsePnpmGlobalList,
@@ -143,4 +243,4 @@ function defineConfig(options) {
   return options;
 }
 
-export { defineConfig as d, global as g, loadGlobalPackages as l, writeGlobalPackage as w };
+export { addonVSCode as a, loadGlobalPackagesAll as b, createVSCodeAddon as c, defineConfig as d, global as g, loadGlobalPackages as l, writeGlobalPackage as w };

package/dist/chunks/interactive.mjs

@@ -1,6 +1,6 @@
 import * as p from '@clack/prompts';
 import c from 'ansis';
-import { a as arrow, b as colorizeVersionDiff, e as colorDiff } from '../shared/depfresh.BkxecpDK.mjs';
+import { a as arrow, b as colorizeVersionDiff, e as colorDiff } from '../shared/depfresh.C-me_t4a.mjs';
 import '../shared/depfresh.Dxgqypc6.mjs';
 import 'node:fs';
 import 'node:os';
@@ -9,13 +9,15 @@ import 'ini';
 import 'pathe';
 import './json-output.mjs';
 import 'node:child_process';
-import '../shared/depfresh.FmznAfq4.mjs';
+import '../shared/depfresh.CHHNqHXD.mjs';
 import 'detect-indent';
 import 'semver';
 import 'pnpm-workspace-yaml';
 import 'yaml';
 import 'p-limit';
+import 'undici';
 import 'better-sqlite3';
+import 'node:crypto';
 import 'tinyglobby';
 
 const DIFF_GROUP_ORDER = ["major", "minor", "patch"];

package/dist/chunks/normalize-args.mjs

@@ -1,6 +1,14 @@
-import { C as ConfigError } from '../shared/depfresh.FmznAfq4.mjs';
+import { C as ConfigError } from '../shared/depfresh.CHHNqHXD.mjs';
 import { a as VALID_SORT_OPTIONS, V as VALID_LOG_LEVELS, b as VALID_OUTPUTS, c as VALID_MODES } from '../shared/depfresh.CFLB6fqi.mjs';
 
+function parseCommaSeparatedArg(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const items = value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+  return items.length > 0 ? items : void 0;
+}
+
 function validateEnum(value, flagName, validValues) {
   if (typeof value !== "string" || !validValues.includes(value)) {
     throw new ConfigError(
@@ -11,6 +19,7 @@ function validateEnum(value, flagName, validValues) {
 }
 async function normalizeArgs(args) {
   const { resolveConfig } = await import('./config.mjs').then(function (n) { return n.c; });
+  const globalAll = args["global-all"];
   const depFields = {};
   if (args["deps-only"]) {
     depFields.devDependencies = false;
@@ -27,8 +36,10 @@ async function normalizeArgs(args) {
   const output = validateEnum(args.output, "--output", VALID_OUTPUTS);
   const sort = validateEnum(args.sort, "--sort", VALID_SORT_OPTIONS);
   const loglevel = validateEnum(args.loglevel, "--loglevel", VALID_LOG_LEVELS);
-  const include = typeof args.include === "string" ? args.include.split(",").map((s) => s.trim()) : void 0;
-  const exclude = typeof args.exclude === "string" ? args.exclude.split(",").map((s) => s.trim()) : void 0;
+  const include = parseCommaSeparatedArg(args.include);
+  const exclude = parseCommaSeparatedArg(args.exclude);
+  const ignorePaths = parseCommaSeparatedArg(args["ignore-paths"]);
+  const refreshCache = Boolean(args["refresh-cache"] || args["no-cache"]);
   return resolveConfig({
     cwd: args.cwd || process.cwd(),
     recursive: args.recursive,
@@ -37,8 +48,11 @@ async function normalizeArgs(args) {
     mode,
     include,
     exclude,
+    ignorePaths,
     force: args.force,
-    global: args.global,
+    refreshCache,
+    global: args.global || globalAll,
+    globalAll,
     peer: args.peer,
     includeLocked: args["include-locked"],
     output,

package/dist/cli.mjs

@@ -1,7 +1,24 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from 'citty';
 
-const version = "0.10.1";
+const version = "0.11.1";
+
+const migrationParityArgs = {
+  "ignore-paths": {
+    type: "string",
+    description: "Additional ignore glob patterns (comma-separated)"
+  },
+  "refresh-cache": {
+    type: "boolean",
+    description: "Bypass cache reads and fetch fresh registry metadata",
+    default: false
+  },
+  "no-cache": {
+    type: "boolean",
+    description: "Alias for --refresh-cache (cache bypass for this run)",
+    default: false
+  }
+};
 
 const args = {
   mode_arg: {
@@ -17,7 +34,7 @@ const args = {
   recursive: {
     type: "boolean",
     alias: "r",
-    description: "Recursively search for package.json in subdirectories",
+    description: "Recursively search for package manifests (package.json, package.yaml) in subdirectories",
     default: true
   },
   write: {
@@ -57,7 +74,12 @@ const args = {
   global: {
     type: "boolean",
     alias: "g",
-    description: "Check global packages",
+    description: "Check global packages for one detected package manager",
+    default: false
+  },
+  "global-all": {
+    type: "boolean",
+    description: "Check global packages across npm, pnpm, and bun with deduped names",
     default: false
   },
   peer: {
@@ -186,7 +208,8 @@ const args = {
     type: "boolean",
     description: "Skip packages that belong to nested/separate workspaces",
     default: true
-  }
+  },
+  ...migrationParityArgs
 };
 
 function normalizeCliRawArgs(rawArgs) {
@@ -205,6 +228,11 @@ const main = defineCommand({
   args,
   async run({ args: args2 }) {
     try {
+      if (args2.mode_arg === "help") {
+        const { showUsage } = await import('citty');
+        await showUsage(main);
+        process.exit(0);
+      }
       if (args2["help-json"]) {
         const { outputCliCapabilities } = await import('./chunks/capabilities.mjs');
         outputCliCapabilities();

package/dist/index.d.mts

@@ -107,10 +107,12 @@ interface depfreshOptions {
     timeout: number;
     retries: number;
     cacheTTL: number;
+    refreshCache?: boolean;
     output: OutputFormat;
     loglevel: 'silent' | 'info' | 'debug';
     peer: boolean;
     global: boolean;
+    globalAll?: boolean;
     ignorePaths: string[];
     ignoreOtherWorkspaces: boolean;
     all: boolean;
@@ -126,6 +128,7 @@ interface depfreshOptions {
     update: boolean;
     execute?: string;
     verifyCommand?: string;
+    addons?: depfreshAddon[];
     beforePackageStart?: (pkg: PackageMeta) => void | Promise<void>;
     onDependencyResolved?: (pkg: PackageMeta, dep: ResolvedDepChange) => void | Promise<void>;
     beforePackageWrite?: (pkg: PackageMeta) => boolean | Promise<boolean>;
@@ -136,6 +139,30 @@ interface depfreshOptions {
 }
 declare const DEFAULT_OPTIONS: Partial<depfreshOptions>;
 
+type AddonHookName = 'setup' | 'afterPackagesLoaded' | 'beforePackageStart' | 'onDependencyResolved' | 'beforePackageWrite' | 'afterPackageWrite' | 'afterPackageEnd' | 'afterPackagesEnd';
+interface AddonContext {
+    readonly options: depfreshOptions;
+    readonly runId: string;
+    readonly startedAt: Date;
+}
+interface depfreshAddon {
+    name: string;
+    setup?: (ctx: AddonContext) => void | Promise<void>;
+    afterPackagesLoaded?: (ctx: AddonContext, pkgs: PackageMeta[]) => void | Promise<void>;
+    beforePackageStart?: (ctx: AddonContext, pkg: PackageMeta) => void | Promise<void>;
+    onDependencyResolved?: (ctx: AddonContext, pkg: PackageMeta, dep: ResolvedDepChange) => void | Promise<void>;
+    beforePackageWrite?: (ctx: AddonContext, pkg: PackageMeta, changes: ResolvedDepChange[]) => boolean | Promise<boolean>;
+    afterPackageWrite?: (ctx: AddonContext, pkg: PackageMeta, changes: ResolvedDepChange[]) => void | Promise<void>;
+    afterPackageEnd?: (ctx: AddonContext, pkg: PackageMeta) => void | Promise<void>;
+    afterPackagesEnd?: (ctx: AddonContext, pkgs: PackageMeta[]) => void | Promise<void>;
+}
+
+/**
+ * Syncs engines.vscode with @types/vscode version in settings.json
+ */
+declare function addonVSCode(pkg: PackageMeta, changes: ResolvedDepChange[]): void;
+declare function createVSCodeAddon(): depfreshAddon;
+
 declare function check(options: depfreshOptions): Promise<number>;
 
 declare function resolveConfig(overrides?: Partial<depfreshOptions>): Promise<depfreshOptions>;
@@ -169,10 +196,16 @@ declare class WriteError extends depfreshError {
 declare class ResolveError extends depfreshError {
     constructor(message: string, options?: depfreshErrorOptions);
 }
+declare class AddonError extends depfreshError {
+    readonly addon: string;
+    readonly hook: string;
+    constructor(message: string, addon: string, hook: string, options?: depfreshErrorOptions);
+}
 
 declare function parseDependencies(raw: Record<string, unknown>, options: depfreshOptions): RawDep[];
 
 declare function loadGlobalPackages(pm?: string): PackageMeta[];
+declare function loadGlobalPackagesAll(): PackageMeta[];
 declare function writeGlobalPackage(pm: PackageManagerName, name: string, version: string): void;
 
 declare function loadPackages(options: depfreshOptions): Promise<PackageMeta[]>;
@@ -200,5 +233,5 @@ declare function writePackage(pkg: PackageMeta, changes: ResolvedDepChange[], lo
 
 declare function defineConfig(options: Partial<depfreshOptions>): Partial<depfreshOptions>;
 
-export { CacheError, ConfigError, DEFAULT_OPTIONS, RegistryError, ResolveError, WriteError, check, defineConfig, depfreshError, loadGlobalPackages, loadPackages, parseDependencies, resolveConfig, resolvePackage, writeGlobalPackage, writePackage };
-export type { CatalogSource, DepFieldType, DiffType, NpmrcConfig, OutputFormat, PackageData, PackageManagerField, PackageManagerName, PackageMeta, PackageType, ProvenanceLevel, RangeMode, RawDep, RegistryConfig, ResolvedDepChange, SortOption, UpdateScore, depfreshOptions };
+export { AddonError, CacheError, ConfigError, DEFAULT_OPTIONS, RegistryError, ResolveError, WriteError, addonVSCode, check, createVSCodeAddon, defineConfig, depfreshError, loadGlobalPackages, loadGlobalPackagesAll, loadPackages, parseDependencies, resolveConfig, resolvePackage, writeGlobalPackage, writePackage };
+export type { AddonContext, AddonHookName, CatalogSource, DepFieldType, DiffType, NpmrcConfig, OutputFormat, PackageData, PackageManagerField, PackageManagerName, PackageMeta, PackageType, ProvenanceLevel, RangeMode, RawDep, RegistryConfig, ResolvedDepChange, SortOption, UpdateScore, depfreshAddon, depfreshOptions };