depfresh 0.11.0 → 1.0.0

package/README.md

@@ -5,129 +5,76 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-3178c6)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-24+-339933)](https://nodejs.org/)
 
-Keep your npm dependencies fresh. Fast, correct, zero-config. Your AI agent already knows how to use this. You don't even need to read this README -- it did.
-
-Spiritual successor to [taze](https://github.com/antfu/taze) by Anthony Fu -- a tool that did the job well until maintenance slowed and issues piled up. I took the best ideas, rewrote everything from scratch, fixed the bugs that sat open for years, and made it work for humans and AI agents alike. Credit where it's due.
-
-## Features
-
-- **Zero-config dependency checking** -- run `depfresh` and it tells you what's outdated. No YAML. No PhD.
-- **Monorepo & workspace support** -- pnpm, bun, yarn, npm. Auto-detected. Catalog deps included.
-- **7 range modes** -- `default`, `major`, `minor`, `patch`, `latest`, `newest`, `next`. One flag, total control.
-- **Interactive cherry-picking** -- grouped multiselect with colour-coded severity. Pick what you want, ignore the rest.
-- **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 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.
-- **SQLite cache** -- WAL mode, 30min TTL, auto-fallback to memory. Fast repeat runs.
-- **Provenance tracking** -- warnings for unsigned or downgraded attestations.
-- **Node engine compat** -- flags updates that don't match your Node version.
-- **Cooldown filter** -- skip versions published less than N days ago. Let the early adopters find the bugs.
-- **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** -- 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 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.
+Keep your dependencies fresh. Zero config, fast, monorepo-ready. Your AI agent already knows how to use this.
 
 ## Install
 
 ```bash
-npm install -g depfresh
-```
-
-Or don't install globally. I'm not your parent.
-
-```bash
+# One-off run (no install)
 npx depfresh
 pnpm dlx depfresh
 bunx depfresh
+
+# Global install
+npm install -g depfresh
+
+# Local devDependency (recommended for team + CI)
+pnpm add -D depfresh
 ```
 
-Lost? `depfresh help` prints every flag and mode. `depfresh --help-json` spits out the full CLI contract as JSON for the robots. Between the two of them, there's no excuse for not knowing what this thing does.
+| If you want... | Use | Example |
+| --- | --- | --- |
+| Run once in any repo | One-off | `npx depfresh` |
+| Always available on your machine | Global | `pnpm add -g depfresh` |
+| Pinned for team/CI consistency | Local devDep | `npm install -D depfresh` |
 
-## Usage
+## Quick Start
 
 ```bash
-# Check for outdated dependencies
+# What's outdated?
 depfresh
 
-# Lost? This prints everything.
-depfresh help
-
-# Same thing but for machines and AI agents who can't read tables
-depfresh --help-json
-
-# Actually update them
+# Update everything
 depfresh --write
 
-# Interactive mode -- pick what to update like a civilised person
-depfresh --interactive
-
-# Only minor/patch updates (living cautiously)
-depfresh minor -w
+# Interactive -- pick what to update
+depfresh -I
 
 # JSON output for scripts and AI agents
 depfresh --output json
 
-# Filter specific packages
-depfresh --include "react,vue" --exclude "eslint"
-
-# Verify each dep individually, revert failures
-depfresh -w --verify-command "pnpm test"
+# Only minor/patch (living cautiously)
+depfresh minor -w
 
 # CI: fail if anything is outdated
 depfresh --fail-on-outdated
+```
 
-# Skip specific directories from recursive scan
-depfresh --ignore-paths "apps/legacy/**,examples/**"
+## Features
 
-# Bypass cache for one run (same behavior)
-depfresh --refresh-cache
-depfresh --no-cache
+- **Zero config** -- run `depfresh` and it works. No YAML. No PhD.
+- **Monorepo & workspace support** -- pnpm, bun, yarn, npm. Auto-detected. Catalogs included.
+- **7 range modes** -- `default`, `major`, `minor`, `patch`, `latest`, `newest`, `next`
+- **Interactive cherry-picking** -- grouped multiselect with colour-coded severity
+- **Per-package modes** -- `packageMode` with exact, glob, or regex patterns per dependency
+- **Write safely** -- `--write` updates files. `--verify-command` tests each dep and reverts failures.
+- **Post-write hooks** -- `--execute`, `--install`, `--update`. Chain commands after writing.
+- **Global packages** -- `--global` for one manager, `--global-all` scans npm + pnpm + bun (deduped)
+- **Private registries** -- full `.npmrc` support. Scoped registries, auth tokens, env vars.
+- **GitHub dependencies** -- `github:owner/repo#tag` with protocol-preserving writes
+- **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.
+- **SQLite cache** -- WAL mode, 30min TTL, auto-fallback to memory
+- **Provenance tracking** -- warnings for unsigned or downgraded attestations
+- **Node engine compat** -- flags updates that don't match your Node version
+- **Cooldown filter** -- skip versions published less than N days ago
+- **Programmatic API** -- lifecycle callbacks + addon system for custom workflows
 
-# Check globals across npm + pnpm + bun (deduped names)
-depfresh --global-all
-```
+Full CLI reference: **[docs/cli/](docs/cli/)**
+
+## Configuration
 
-## CLI Flags
-
-The top flags to get you started. Full reference with all 27+ flags: **[docs/cli/](docs/cli/)**
-
-| Flag | Alias | Default | Description |
-|------|-------|---------|-------------|
-| `--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) |
-| `--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 |
-| `--install` | `-i` | `false` | Run package manager install after writing |
-| `--fail-on-outdated` | -- | `false` | Exit code 1 when outdated deps found (CI mode) |
-| `--cooldown` | -- | `0` | Skip versions published less than N days ago |
-| `--sort` | `-s` | `diff-asc` | Sort: `diff-asc` `diff-desc` `time-asc` `time-desc` `name-asc` `name-desc` |
-
-## Config File
-
-Zero config works. But if you want it, create `depfresh.config.ts` (or `.depfreshrc`, or add a `depfresh` key to `package.json`):
+Zero config works. But if you want it:
 
 ```typescript
 import { defineConfig } from 'depfresh'
@@ -142,237 +89,37 @@ 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
-
-`--output json` emits a single structured envelope. No log noise. No ANSI codes. Just clean JSON that machines can parse without having an existential crisis.
-
-```json
-{
-  "packages": [
-    {
-      "name": "my-app",
-      "updates": [
-        {
-          "name": "react",
-          "current": "^18.2.0",
-          "target": "^19.1.0",
-          "diff": "major",
-          "source": "dependencies"
-        }
-      ]
-    }
-  ],
-  "errors": [
-    {
-      "name": "some-private-pkg",
-      "source": "dependencies",
-      "currentVersion": "^1.0.0",
-      "message": "Failed to resolve from registry"
-    }
-  ],
-  "summary": {
-    "total": 12,
-    "major": 1,
-    "minor": 7,
-    "patch": 4,
-    "packages": 3,
-    "scannedPackages": 3,
-    "packagesWithUpdates": 3,
-    "plannedUpdates": 0,
-    "appliedUpdates": 0,
-    "revertedUpdates": 0
-  },
-  "meta": {
-    "schemaVersion": 1,
-    "cwd": "/path/to/project",
-    "mode": "default",
-    "timestamp": "2026-02-22T12:00:00.000Z",
-    "noPackagesFound": false,
-    "didWrite": false
-  }
-}
-```
-
-Full schema and field reference: **[docs/output-formats/](docs/output-formats/)**
-
-## AI Agent Usage
-
-depfresh was designed to work with AI coding assistants out of the box. No special configuration needed. Run it blind and it tells you what to do next.
-
-**Auto-discovery** -- when stdout isn't a TTY (piped, captured by an agent), depfresh prints a hint to stderr: `Tip: Use --output json for structured output. Run --help-json for CLI capabilities.` Agents are stateless. They don't remember your last hint.
-
-**`--help-json`** returns a full machine-readable contract: version, flags, enums, exit codes, plus:
-- `workflows` -- 4 copy-paste agent recipes (`checkOnly`, `safeUpdate`, `fullUpdate`, `selective`)
-- `flagRelationships` -- which flags require or conflict with others
-- `configFiles` -- every supported config file pattern
-- `jsonOutputSchema` -- field descriptions of the JSON envelope
-
-```bash
-# First run -- just see what happens (agents get the stderr hint)
-depfresh
-
-# Discover the full CLI contract
-depfresh --help-json
-
-# Check for updates, get structured output
-depfresh --output json
-
-# Apply only safe updates
-depfresh --write --mode minor --output json
-
-# Selective update
-depfresh --write --include "typescript,vitest" --output json
-
-# Full send
-depfresh --write --mode latest --output json
-```
-
-**Exit codes are semantic:**
-- `0` -- all deps up to date (or updates were written)
-- `1` -- updates available (with `--fail-on-outdated`)
-- `2` -- error (structured JSON error envelope when `--output json` is active)
-
-**Structured errors** -- when `--output json` is active and something fails, you get a JSON error envelope with `error.code`, `error.message`, and `error.retryable` instead of plaintext stderr. Resolution failures for individual deps appear in the `errors[]` array of the normal envelope.
-
-**TTY detection** -- when stdout isn't a terminal, depfresh automatically suppresses spinners and interactive prompts. `NO_COLOR` is respected.
-
-## Programmatic API
-
-```typescript
-import { check, resolveConfig } from 'depfresh'
-
-const options = await resolveConfig({
-  cwd: process.cwd(),
-  mode: 'minor',
-  write: true,
-  onDependencyResolved: (pkg, dep) => {
-    if (dep.diff === 'major') {
-      console.log(`Major update: ${dep.name} ${dep.currentVersion} -> ${dep.targetVersion}`)
-    }
-  },
-  beforePackageWrite: (pkg) => {
-    return true // return false to skip
-  },
-})
-
-const exitCode = await check(options)
-```
-
-Programmatic API with lifecycle callbacks, addon plugins, and full typed exports. Full reference: **[docs/api/](docs/api/)**
+Supports `depfresh.config.ts`, `.depfreshrc`, or a `depfresh` key in `package.json`. Full reference: **[docs/configuration/](docs/configuration/)**
 
 ## Monorepo Support
 
-depfresh auto-detects workspace structures. No config needed.
+depfresh auto-detects pnpm, bun, yarn, and npm workspaces -- no config needed. Workspace catalogs (`pnpm-workspace.yaml`, bun catalogs, yarn `.yarnrc.yml` catalogs) are resolved and updated in-place alongside your package manifests.
 
-| Package Manager | Workspaces | Catalogs |
-|----------------|------------|----------|
-| pnpm | `pnpm-workspace.yaml` | `catalog:` protocol |
-| 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` | -- |
+Details: **[docs/configuration/workspaces.md](docs/configuration/workspaces.md)**
 
-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.
+## AI Agent Friendly
 
-## Private Registries
+depfresh was built for humans and machines. `--output json` emits a structured envelope. `--help-json` returns the full CLI contract (flags, enums, exit codes, agent workflows). Exit codes are semantic: `0` = up to date, `1` = updates available, `2` = error. Non-TTY environments automatically suppress spinners and interactive prompts.
 
-depfresh reads `.npmrc` from your project and home directory. Scoped registries, auth tokens, proxies -- all respected.
+Details: **[docs/agents/README.md](docs/agents/README.md)**
 
-```ini
-# .npmrc
-@mycompany:registry=https://npm.mycompany.com/
-//npm.mycompany.com/:_authToken=${NPM_TOKEN}
-```
+## Coming from taze?
 
-This was broken in taze for 4+ years. I fixed it on day one. You're welcome.
-
-## 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 |
+depfresh is a spiritual successor to [taze](https://github.com/antfu/taze) by Anthony Fu -- a tool that did the job well until maintenance slowed and issues piled up. depfresh rewrites everything from scratch, fixes long-standing bugs (private registries, bun catalogs, packageMode precedence), and adds structured JSON output, verify-and-rollback, SQLite caching, and proper AI agent support.
 
-## Documentation
+Migration guide: **[docs/compare/from-taze.md](docs/compare/from-taze.md)** | Full comparison: **[docs/compare/](docs/compare/)**
 
-The full docs, for people who read manuals before assembling furniture.
+## Documentation
 
-- **[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, 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
+- **[CLI Reference](docs/cli/)** -- flags, modes, sorting, filtering, hooks, interactive, CI
+- **[Configuration](docs/configuration/)** -- config files, options, packageMode, private registries, cache
+- **[Programmatic API](docs/api/)** -- functions, lifecycle callbacks, addon plugins, types
+- **[Output Formats](docs/output-formats/)** -- table, JSON, exit codes
+- **[Agent Workflows](docs/agents/README.md)** -- quickstarts for AI coding assistants
+- **[Integrations](docs/integrations/README.md)** -- GitHub Actions and MCP wrapper guidance
+- **[Compare](docs/compare/)** -- coverage matrix, migration guide, solved issues
 - **[Troubleshooting](docs/troubleshooting.md)** -- common issues, workspace gotchas, known limitations
 
-## Requirements
-
-- Node.js >= 24
-
 ## Standing on the Shoulders of People Who Actually Did the Work
 
 depfresh wouldn't exist without [taze](https://github.com/antfu/taze). I rewrote everything from scratch, yes, but "from scratch" is easy when someone else already figured out what the thing should do. Every bug report, every feature PR, every typo fix in the taze repo was a free lesson in what users actually need. I just took notes and built a new house on someone else's blueprint.

package/dist/chunks/index.mjs

@@ -1,5 +1,5 @@
-import { c as check } from '../shared/depfresh.C-me_t4a.mjs';
-export { d as detectPackageManager } from '../shared/depfresh.C-me_t4a.mjs';
+import { c as check } from '../shared/depfresh.CTatBHRg.mjs';
+export { d as detectPackageManager } from '../shared/depfresh.CTatBHRg.mjs';
 import 'ansis';
 import '../shared/depfresh.Dxgqypc6.mjs';
 import 'node:fs';

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.C-me_t4a.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.CTatBHRg.mjs';
 import c from 'ansis';
 import '../shared/depfresh.Dxgqypc6.mjs';
 import 'node:fs';

package/dist/chunks/index3.mjs

@@ -2,7 +2,7 @@ import './config.mjs';
 import '../shared/depfresh.CHHNqHXD.mjs';
 import { execSync } from 'node:child_process';
 import { c as createLogger } from '../shared/depfresh.Dxgqypc6.mjs';
-import '../shared/depfresh.C-me_t4a.mjs';
+import '../shared/depfresh.CTatBHRg.mjs';
 
 function addonVSCode(pkg, changes) {
   const vscodeChange = changes.find((c) => c.name === "@types/vscode");

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.C-me_t4a.mjs';
+import { a as arrow, b as colorizeVersionDiff, e as colorDiff } from '../shared/depfresh.CTatBHRg.mjs';
 import '../shared/depfresh.Dxgqypc6.mjs';
 import 'node:fs';
 import 'node:os';

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { defineCommand, runMain } from 'citty';
+import { renderUsage, defineCommand, runMain } from 'citty';
 
-const version = "0.11.0";
+const version = "1.0.0";
 
 const migrationParityArgs = {
   "ignore-paths": {
@@ -58,12 +58,12 @@ const args = {
   include: {
     type: "string",
     alias: "n",
-    description: "Only include packages matching this regex (comma-separated)"
+    description: "Only include packages matching these regex/glob patterns (comma-separated)"
   },
   exclude: {
     type: "string",
     alias: "x",
-    description: "Exclude packages matching this regex (comma-separated)"
+    description: "Exclude packages matching these regex/glob patterns (comma-separated)"
   },
   force: {
     type: "boolean",
@@ -219,6 +219,24 @@ function normalizeCliRawArgs(rawArgs) {
   return ["--help", ...rawArgs.slice(1)];
 }
 
+const DOCUMENTATION_URL = "https://github.com/vcode-sh/depfresh/tree/main/docs";
+const REPOSITORY_URL = "https://github.com/vcode-sh/depfresh";
+function withHelpLinks(usage) {
+  return `${usage}
+
+Docs: ${DOCUMENTATION_URL}
+GitHub: ${REPOSITORY_URL}
+`;
+}
+async function showUsageWithLinks(cmd, parent) {
+  try {
+    const usage = await renderUsage(cmd, parent);
+    console.log(withHelpLinks(usage));
+  } catch (error) {
+    console.error(error);
+  }
+}
+
 const main = defineCommand({
   meta: {
     name: "depfresh",
@@ -228,6 +246,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();
@@ -261,7 +284,8 @@ const main = defineCommand({
   }
 });
 runMain(main, {
-  rawArgs: normalizeCliRawArgs(process.argv.slice(2))
+  rawArgs: normalizeCliRawArgs(process.argv.slice(2)),
+  showUsage: showUsageWithLinks
 });
 
 export { args as a, version as v };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 export { D as DEFAULT_OPTIONS, r as resolveConfig } from './chunks/config.mjs';
 export { A as AddonError, a as CacheError, C as ConfigError, R as RegistryError, b as ResolveError, W as WriteError, d as depfreshError } from './shared/depfresh.CHHNqHXD.mjs';
 export { a as addonVSCode, c as createVSCodeAddon, d as defineConfig, l as loadGlobalPackages, b as loadGlobalPackagesAll, w as writeGlobalPackage } from './chunks/index3.mjs';
-export { c as check, l as loadPackages, p as parseDependencies, r as resolvePackage, w as writePackage } from './shared/depfresh.C-me_t4a.mjs';
+export { c as check, l as loadPackages, p as parseDependencies, r as resolvePackage, w as writePackage } from './shared/depfresh.CTatBHRg.mjs';
 import 'node:fs/promises';
 import 'node:url';
 import 'defu';

package/dist/shared/{depfresh.C-me_t4a.mjs → depfresh.CTatBHRg.mjs}

@@ -390,14 +390,51 @@ function resolveTargetVersion(currentVersion, versions, distTags, mode) {
   }
 }
 
+function parseGithubSpec(version) {
+  const githubMatch = version.match(/^github:([^#]+)#(.+)$/);
+  if (!githubMatch) {
+    return null;
+  }
+  const repository = githubMatch[1]?.trim();
+  const ref = githubMatch[2]?.trim();
+  if (!(repository && ref)) {
+    return null;
+  }
+  const withoutTagPrefix = ref.startsWith("refs/tags/") ? ref.slice("refs/tags/".length) : ref;
+  const normalized = withoutTagPrefix.startsWith("v") ? withoutTagPrefix.slice(1) : withoutTagPrefix;
+  const valid = semver.valid(normalized);
+  if (!valid) {
+    return null;
+  }
+  return {
+    aliasName: `github:${repository}`,
+    currentVersion: valid
+  };
+}
 function parseProtocol(version) {
   const npmMatch = version.match(/^npm:(.+)@(.+)$/);
   if (npmMatch) {
-    return { protocol: "npm", currentVersion: npmMatch[2] };
+    return {
+      protocol: "npm",
+      aliasName: npmMatch[1],
+      currentVersion: npmMatch[2]
+    };
   }
   const jsrMatch = version.match(/^jsr:(.+)@(.+)$/);
   if (jsrMatch) {
-    return { protocol: "jsr", currentVersion: jsrMatch[2] };
+    return {
+      protocol: "jsr",
+      aliasName: `jsr:${jsrMatch[1]}`,
+      currentVersion: jsrMatch[2]
+    };
+  }
+  const githubSpec = parseGithubSpec(version);
+  if (githubSpec) {
+    return {
+      protocol: "github",
+      aliasName: githubSpec.aliasName,
+      currentVersion: githubSpec.currentVersion
+    };
   }
   return { currentVersion: version };
 }
@@ -434,6 +471,7 @@ function flattenOverrides(obj, source, deps, options, parents, includePatterns,
       deps.push({
         name,
         currentVersion: protocol.currentVersion,
+        aliasName: protocol.aliasName,
         source,
         update: !isLocked(protocol.currentVersion) || options.includeLocked,
         parents: [...parents, key],
@@ -495,7 +533,10 @@ function isDepFieldEnabled(field, options) {
 function shouldSkipDependency(name, version, options, includePatterns = [], excludePatterns = []) {
   if (version.startsWith("workspace:") && !options.includeWorkspace) return true;
   if (version.startsWith("catalog:")) return true;
-  if (/^(link|file|git|github|https?):/.test(version)) return true;
+  if (version.startsWith("github:")) {
+    return !parseGithubSpec(version);
+  }
+  if (/^(link|file|git|https?):/.test(version)) return true;
   if (includePatterns.length && !includePatterns.some((re) => re.test(name))) {
     return true;
   }
@@ -520,6 +561,7 @@ function parseDependencies(raw, options) {
       deps.push({
         name,
         currentVersion: protocol.currentVersion,
+        aliasName: protocol.aliasName,
         source: field,
         update: !isLocked(protocol.currentVersion) || options.includeLocked,
         parents: [],
@@ -997,6 +1039,9 @@ function loadCaBundle(cafilePath) {
 
 async function fetchPackageData(name, options) {
   const registry = getRegistryForPackage(name, options.npmrc);
+  if (name.startsWith("github:")) {
+    return fetchGithubPackage(name.slice("github:".length), options);
+  }
   if (name.startsWith("jsr:")) {
     return fetchJsrPackage(name.slice(4), options);
   }
@@ -1011,7 +1056,11 @@ async function fetchNpmPackage(name, registry, options) {
   if (registry.token) {
     headers.authorization = registry.authType === "basic" ? `Basic ${registry.token}` : `Bearer ${registry.token}`;
   }
-  const json = await fetchWithRetry(url, headers, options);
+  const payload = await fetchWithRetry(url, headers, options);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new ResolveError(`Unexpected npm registry payload shape for ${url}`);
+  }
+  const json = payload;
   const versionsObj = json.versions ?? {};
   const versions = Object.keys(versionsObj).filter((v) => semver.valid(v));
   const distTags = json["dist-tags"] ?? {};
@@ -1046,7 +1095,11 @@ async function fetchNpmPackage(name, registry, options) {
 }
 async function fetchJsrPackage(name, options) {
   const url = `https://jsr.io/${name}/meta.json`;
-  const json = await fetchWithRetry(url, {}, options);
+  const payload = await fetchWithRetry(url, {}, options);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new ResolveError(`Unexpected JSR payload shape for ${url}`);
+  }
+  const json = payload;
   const versionsObj = json.versions ?? {};
   const versions = Object.keys(versionsObj);
   const latest = json.latest ?? versions[versions.length - 1] ?? "";
@@ -1056,6 +1109,59 @@ async function fetchJsrPackage(name, options) {
     distTags: { latest }
   };
 }
+async function fetchGithubPackage(repository, options) {
+  const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+  const headers = {
+    accept: "application/vnd.github+json",
+    "user-agent": "depfresh"
+  };
+  if (token) {
+    headers.authorization = `Bearer ${token}`;
+  }
+  const versions = /* @__PURE__ */ new Set();
+  for (let page = 1; page <= 10; page++) {
+    const url = `https://api.github.com/repos/${repository}/tags?per_page=100&page=${page}`;
+    const payload = await fetchWithRetry(url, headers, options);
+    if (!Array.isArray(payload)) {
+      throw new ResolveError(`Unexpected GitHub tags payload shape for ${url}`);
+    }
+    if (payload.length === 0) {
+      break;
+    }
+    for (const item of payload) {
+      if (!item || typeof item !== "object") continue;
+      const tagName = item.name;
+      if (typeof tagName !== "string") continue;
+      const normalized = normalizeGithubTag(tagName);
+      if (normalized) {
+        versions.add(normalized);
+      }
+    }
+    if (payload.length < 100) {
+      break;
+    }
+  }
+  const sorted = Array.from(versions).sort(semver.compare);
+  const latest = sorted[sorted.length - 1];
+  if (!latest) {
+    throw new ResolveError(`No semver tags found for github:${repository}`);
+  }
+  const repositoryUrl = `https://github.com/${repository}`;
+  return {
+    name: `github:${repository}`,
+    versions: sorted,
+    distTags: { latest },
+    repository: repositoryUrl,
+    homepage: repositoryUrl
+  };
+}
+function normalizeGithubTag(tag) {
+  const trimmed = tag.trim();
+  if (!trimmed) return null;
+  const withoutTagPrefix = trimmed.startsWith("refs/tags/") ? trimmed.slice("refs/tags/".length) : trimmed;
+  const withoutVPrefix = withoutTagPrefix.startsWith("v") ? withoutTagPrefix.slice(1) : withoutTagPrefix;
+  return semver.valid(withoutVPrefix);
+}
 async function fetchWithRetry(url, headers, options, attempt = 0) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), options.timeout);
@@ -1067,6 +1173,9 @@ async function fetchWithRetry(url, headers, options, attempt = 0) {
       ...transportInit
     });
     if (!response.ok) {
+      if (isGithubRateLimit(response, url)) {
+        throw createGithubRateLimitError(response, url);
+      }
       throw new RegistryError(
         `HTTP ${response.status}: ${response.statusText} for ${url}`,
         response.status,
@@ -1106,6 +1215,30 @@ function isAbortError(error) {
   const named = error;
   return named.name === "AbortError";
 }
+function isGithubRateLimit(response, url) {
+  if (!url.includes("api.github.com")) return false;
+  if (response.status !== 403 && response.status !== 429) return false;
+  return response.headers.get("x-ratelimit-remaining") === "0";
+}
+function createGithubRateLimitError(response, url) {
+  const resetRaw = response.headers.get("x-ratelimit-reset");
+  let resetHint = "";
+  if (resetRaw) {
+    const resetSeconds = Number.parseInt(resetRaw, 10);
+    if (Number.isFinite(resetSeconds)) {
+      resetHint = ` Resets at ${new Date(resetSeconds * 1e3).toISOString()}.`;
+    }
+  }
+  return new ResolveError(
+    `GitHub API rate limit exceeded for ${url}.${resetHint} Set GITHUB_TOKEN or GH_TOKEN.`,
+    {
+      cause: {
+        status: response.status,
+        statusText: response.statusText
+      }
+    }
+  );
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1258,6 +1391,9 @@ async function resolvePackage(pkg, options, externalCache, externalNpmrc, privat
   }
 }
 
+function isPeerScopedCatalog$1(name) {
+  return name.trim().toLowerCase() === "peers";
+}
 function parseCatalogDeps(catalog, parentPath, options) {
   const deps = [];
   for (const [name, version] of Object.entries(catalog)) {
@@ -1302,6 +1438,9 @@ const bunCatalogLoader = {
     if (raw.workspaces?.catalogs) {
       const catalogs = raw.workspaces.catalogs;
       for (const [catalogName, catalog] of Object.entries(catalogs)) {
+        if (!options.peer && isPeerScopedCatalog$1(catalogName)) {
+          continue;
+        }
         sources.push({
           type: "bun",
           name: catalogName,
@@ -1344,6 +1483,9 @@ const bun = {
   bunCatalogLoader: bunCatalogLoader
 };
 
+function isPeerScopedCatalog(name) {
+  return name.trim().toLowerCase() === "peers";
+}
 const pnpmCatalogLoader = {
   async detect(cwd) {
     return !!findUpSync("pnpm-workspace.yaml", { cwd });
@@ -1360,6 +1502,9 @@ const pnpmCatalogLoader = {
     }
     if (schema.catalogs && typeof schema.catalogs === "object") {
       for (const [name, deps] of Object.entries(schema.catalogs)) {
+        if (!options.peer && isPeerScopedCatalog(name)) {
+          continue;
+        }
         catalogs.push(parseCatalogSection(deps, name, filepath, options, content));
       }
     }
@@ -1493,6 +1638,11 @@ function rebuildVersion(original, newVersion) {
   if (npmMatch) return `${npmMatch[1]}${newVersion}`;
   const jsrMatch = original.match(/^(jsr:.+@)/);
   if (jsrMatch) return `${jsrMatch[1]}${newVersion}`;
+  const githubMatch = original.match(/^(github:[^#]+#)(refs\/tags\/)?(v?)(.+)$/);
+  if (githubMatch) {
+    const [, prefix, tagPrefix = "", vPrefix = ""] = githubMatch;
+    return `${prefix}${tagPrefix}${vPrefix}${newVersion}`;
+  }
   return newVersion;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depfresh",
-  "version": "0.11.0",
+  "version": "1.0.0",
   "description": "Keep your npm dependencies fresh. Fast, correct, zero-config.",
   "type": "module",
   "license": "MIT",
@@ -55,6 +55,7 @@
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
     "typecheck": "tsc --noEmit",
+    "audit:coverage": "node scripts/audit/update-taze-coverage.mjs",
     "prepublishOnly": "pnpm run build"
   },
   "dependencies": {