depfresh 0.9.2 → 0.10.1

package/README.md

@@ -1,17 +1,17 @@
-# depzy
+# depfresh
 
-[![npm version](https://img.shields.io/npm/v/depzy)](https://www.npmjs.com/package/depzy)
+[![npm version](https://img.shields.io/npm/v/depfresh)](https://www.npmjs.com/package/depfresh)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![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.
+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.
+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 `depzy` and it tells you what's outdated. No YAML. No PhD.
+- **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.
@@ -35,48 +35,56 @@ Spiritual successor to [taze](https://github.com/antfu/taze) by Anthony Fu - a t
 
 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.
 
-depzy 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.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.
 
 ## Install
 
 ```bash
-npm install -g depzy
+npm install -g depfresh
 ```
 
 Or don't install globally. I'm not your parent.
 
 ```bash
-npx depzy
-pnpm dlx depzy
-bunx depzy
+npx depfresh
+pnpm dlx depfresh
+bunx 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.
+
 ## Usage
 
 ```bash
 # Check for outdated dependencies
-depzy
+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
-depzy --write
+depfresh --write
 
 # Interactive mode -- pick what to update like a civilised person
-depzy --interactive
+depfresh --interactive
 
 # Only minor/patch updates (living cautiously)
-depzy minor -w
+depfresh minor -w
 
 # JSON output for scripts and AI agents
-depzy --output json
+depfresh --output json
 
 # Filter specific packages
-depzy --include "react,vue" --exclude "eslint"
+depfresh --include "react,vue" --exclude "eslint"
 
 # Verify each dep individually, revert failures
-depzy -w --verify-command "pnpm test"
+depfresh -w --verify-command "pnpm test"
 
 # CI: fail if anything is outdated
-depzy --fail-on-outdated
+depfresh --fail-on-outdated
 ```
 
 ## CLI Flags
@@ -103,10 +111,10 @@ The top flags to get you started. Full reference with all 27+ flags: **[docs/cli
 
 ## Config File
 
-Zero config works. But if you want it, create `depzy.config.ts` (or `.depzyrc`, or add a `depzy` key to `package.json`):
+Zero config works. But if you want it, create `depfresh.config.ts` (or `.depfreshrc`, or add a `depfresh` key to `package.json`):
 
 ```typescript
-import { defineConfig } from 'depzy'
+import { defineConfig } from 'depfresh'
 
 export default defineConfig({
   mode: 'minor',
@@ -140,17 +148,33 @@ Full options reference: **[docs/configuration/](docs/configuration/)**
       ]
     }
   ],
+  "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
+    "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"
+    "timestamp": "2026-02-22T12:00:00.000Z",
+    "noPackagesFound": false,
+    "didWrite": false
   }
 }
 ```
@@ -159,33 +183,49 @@ Full schema and field reference: **[docs/output-formats/](docs/output-formats/)*
 
 ## AI Agent Usage
 
-depzy was designed to work with AI coding assistants out of the box. No special configuration needed.
+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
-# Check for updates, get structured output
-depzy --output json --loglevel silent
+# First run -- just see what happens (agents get the stderr hint)
+depfresh
+
+# Discover the full CLI contract
+depfresh --help-json
 
-# Apply all updates
-depzy --write
+# Check for updates, get structured output
+depfresh --output json
 
 # Apply only safe updates
-depzy --write --mode patch
+depfresh --write --mode minor --output json
 
 # Selective update
-depzy --write --include "typescript,vitest"
+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
+- `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 (piped, captured by an agent), depzy automatically suppresses spinners and interactive prompts. `NO_COLOR` is respected.
+**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 'depzy'
+import { check, resolveConfig } from 'depfresh'
 
 const options = await resolveConfig({
   cwd: process.cwd(),
@@ -208,7 +248,7 @@ const exitCode = await check(options)
 
 ## Monorepo Support
 
-depzy auto-detects workspace structures. No config needed.
+depfresh auto-detects workspace structures. No config needed.
 
 | Package Manager | Workspaces | Catalogs |
 |----------------|------------|----------|
@@ -217,11 +257,11 @@ depzy auto-detects workspace structures. No config needed.
 | Yarn | `workspaces` in `package.json` | `.yarnrc.yml` catalogs |
 | npm | `workspaces` in `package.json` | -- |
 
-Workspace catalogs are resolved and updated in-place. Your `pnpm-workspace.yaml` catalog entries get depzyaded 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 `package.json` deps. No manual sync needed.
 
 ## Private Registries
 
-depzy reads `.npmrc` from your project and home directory. Scoped registries, auth tokens, proxies -- all respected.
+depfresh reads `.npmrc` from your project and home directory. Scoped registries, auth tokens, proxies -- all respected.
 
 ```ini
 # .npmrc
@@ -235,7 +275,7 @@ This was broken in taze for 4+ years. I fixed it on day one. You're welcome.
 
 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 | depzy |
+| Problem | taze | depfresh |
 |---------|------|------|
 | `.npmrc` / private registries | Ignored | Full support |
 | Network retry | None | Exponential backoff |
@@ -255,7 +295,9 @@ 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
-- **[Output Formats](docs/output-formats/)** -- table, JSON, SARIF, exit codes, AI agent integration
+- **[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
 - **[Troubleshooting](docs/troubleshooting.md)** -- common issues, workspace gotchas, known limitations
 
 ## Requirements
@@ -264,7 +306,7 @@ The full docs, for people who read manuals before assembling furniture.
 
 ## Standing on the Shoulders of People Who Actually Did the Work
 
-depzy 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.
+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.
 
 So here's to every contributor who opened a PR on taze. Some of you added features I shamelessly reimplemented. Some of you fixed bugs that taught me where the landmines were. Some of you fixed typos, and honestly, that's braver than any architecture decision I've ever made.
 

package/dist/chunks/capabilities.mjs

@@ -0,0 +1,129 @@
+import { v as version, a as args } from '../cli.mjs';
+import { C as CONFIG_FILES } from './config.mjs';
+import { V as VALID_LOG_LEVELS, a as VALID_SORT_OPTIONS, b as VALID_OUTPUTS, c as VALID_MODES } from '../shared/depfresh.CFLB6fqi.mjs';
+import 'citty';
+import 'node:fs/promises';
+import 'node:url';
+import 'defu';
+import 'pathe';
+import '../shared/depfresh.FmznAfq4.mjs';
+import '../shared/depfresh.Dxgqypc6.mjs';
+import 'ansis';
+
+const ENUM_VALUES_BY_FLAG = {
+  mode: VALID_MODES,
+  output: VALID_OUTPUTS,
+  sort: VALID_SORT_OPTIONS,
+  loglevel: VALID_LOG_LEVELS
+};
+const EXIT_CODES = {
+  "0": "Success (no updates found, or updates written successfully).",
+  "1": "Outdated dependencies found with --fail-on-outdated and without --write.",
+  "2": "Fatal/runtime/configuration error (including invalid enum flag values)."
+};
+const WORKFLOWS = {
+  checkOnly: {
+    description: "Check for outdated dependencies and return structured JSON",
+    command: "depfresh --output json"
+  },
+  safeUpdate: {
+    description: "Apply only minor and patch updates",
+    command: "depfresh --write --mode minor --output json"
+  },
+  fullUpdate: {
+    description: "Update everything to the latest version",
+    command: "depfresh --write --mode latest --output json"
+  },
+  selective: {
+    description: "Update specific packages by name",
+    command: 'depfresh --write --include "pkg1,pkg2" --output json'
+  }
+};
+const FLAG_RELATIONSHIPS = {
+  install: { requires: ["write"] },
+  update: { requires: ["write"] },
+  execute: { requires: ["write"] },
+  "verify-command": { requires: ["write"] },
+  interactive: { requires: ["write"] },
+  "deps-only": { conflicts: ["dev-only"] },
+  "dev-only": { conflicts: ["deps-only"] }
+};
+const JSON_OUTPUT_SCHEMA = {
+  "packages[]": "Array of scanned packages with their updates",
+  "packages[].name": "Package name from package.json",
+  "packages[].updates[]": "Array of dependencies with available updates",
+  "packages[].updates[].name": "Dependency name",
+  "packages[].updates[].current": "Current version range",
+  "packages[].updates[].target": "Target version range",
+  "packages[].updates[].diff": "Semver diff type: major | minor | patch",
+  "packages[].updates[].source": "Dependency field (dependencies, devDependencies, etc.)",
+  "errors[]": "Array of dependencies that failed to resolve",
+  "errors[].name": "Dependency name",
+  "errors[].source": "Dependency field",
+  "errors[].currentVersion": "Current version range",
+  "errors[].message": "Error description",
+  "summary.total": "Total number of available updates",
+  "summary.major": "Count of major updates",
+  "summary.minor": "Count of minor updates",
+  "summary.patch": "Count of patch updates",
+  "meta.schemaVersion": "JSON schema version (currently 1)",
+  "meta.cwd": "Working directory used",
+  "meta.mode": "Version range mode used",
+  "meta.timestamp": "ISO 8601 timestamp",
+  "meta.didWrite": "Whether package files were written"
+};
+function buildFlagDefinitions(argsDef) {
+  const positional = {};
+  const flags = {};
+  for (const [name, rawDef] of Object.entries(argsDef)) {
+    const def = rawDef;
+    if (!def.type) continue;
+    const capability = {
+      type: def.type,
+      ...def.description ? { description: def.description } : {},
+      ...def.alias ? { alias: def.alias } : {},
+      ...def.default !== void 0 ? { default: def.default } : {},
+      ...ENUM_VALUES_BY_FLAG[name] ? { values: ENUM_VALUES_BY_FLAG[name] } : {}
+    };
+    if (def.type === "positional") {
+      positional[name] = capability;
+    } else {
+      flags[name] = capability;
+    }
+  }
+  if (positional.mode_arg) {
+    positional.mode_arg.values = VALID_MODES;
+  }
+  return { positional, flags };
+}
+function getCliCapabilities() {
+  const { positional, flags } = buildFlagDefinitions(args);
+  return {
+    schemaVersion: 1,
+    version,
+    command: "depfresh",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    enums: {
+      mode: VALID_MODES,
+      output: VALID_OUTPUTS,
+      sort: VALID_SORT_OPTIONS,
+      loglevel: VALID_LOG_LEVELS
+    },
+    exitCodes: EXIT_CODES,
+    positional,
+    flags,
+    workflows: WORKFLOWS,
+    flagRelationships: FLAG_RELATIONSHIPS,
+    configFiles: [...CONFIG_FILES],
+    jsonOutputSchema: JSON_OUTPUT_SCHEMA,
+    discoverability: {
+      helpJsonFlag: "depfresh --help-json",
+      capabilitiesCommand: "depfresh capabilities --json"
+    }
+  };
+}
+function outputCliCapabilities() {
+  console.log(JSON.stringify(getCliCapabilities(), null, 2));
+}
+
+export { getCliCapabilities, outputCliCapabilities };

package/dist/chunks/config.mjs

@@ -2,7 +2,8 @@ import { readFile, access } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 import { defu } from 'defu';
 import { join } from 'pathe';
-import { c as createLogger, a as ConfigError } from '../shared/depfresh.B1o7OHO_.mjs';
+import { C as ConfigError } from '../shared/depfresh.FmznAfq4.mjs';
+import { c as createLogger } from '../shared/depfresh.Dxgqypc6.mjs';
 
 const DEFAULT_OPTIONS = {
   cwd: ".",
@@ -39,21 +40,21 @@ const DEFAULT_OPTIONS = {
 const TS_RE = /\.[mc]?ts$/;
 const JS_RE = /\.[mc]?js$/;
 const CONFIG_FILES = [
-  "depzy.config.ts",
-  "depzy.config.mts",
-  "depzy.config.cts",
-  "depzy.config.js",
-  "depzy.config.mjs",
-  "depzy.config.cjs",
-  "depzy.config.json",
-  ".depzyrc.ts",
-  ".depzyrc.mts",
-  ".depzyrc.cts",
-  ".depzyrc.js",
-  ".depzyrc.mjs",
-  ".depzyrc.cjs",
-  ".depzyrc.json",
-  ".depzyrc"
+  "depfresh.config.ts",
+  "depfresh.config.mts",
+  "depfresh.config.cts",
+  "depfresh.config.js",
+  "depfresh.config.mjs",
+  "depfresh.config.cjs",
+  "depfresh.config.json",
+  ".depfreshrc.ts",
+  ".depfreshrc.mts",
+  ".depfreshrc.cts",
+  ".depfreshrc.js",
+  ".depfreshrc.mjs",
+  ".depfreshrc.cjs",
+  ".depfreshrc.json",
+  ".depfreshrc"
 ];
 async function exists(path) {
   try {
@@ -102,7 +103,7 @@ async function loadConfigFile(cwd) {
     try {
       const content = await readFile(pkgPath, "utf-8");
       const pkg = JSON.parse(content);
-      if (pkg.depzy) return pkg.depzy;
+      if (pkg.depfresh) return pkg.depfresh;
     } catch (error) {
       throw new ConfigError(`Failed to parse package.json at ${pkgPath}`, { cause: error });
     }
@@ -120,7 +121,8 @@ async function resolveConfig(overrides = {}) {
 
 const config = {
   __proto__: null,
+  CONFIG_FILES: CONFIG_FILES,
   resolveConfig: resolveConfig
 };
 
-export { DEFAULT_OPTIONS as D, config as c, resolveConfig as r };
+export { CONFIG_FILES as C, DEFAULT_OPTIONS as D, config as c, resolveConfig as r };

package/dist/chunks/index.mjs

@@ -1,13 +1,15 @@
-import { c as check } from '../shared/depfresh.ClIHCCxD.mjs';
-export { d as detectPackageManager } from '../shared/depfresh.ClIHCCxD.mjs';
+import { c as check } from '../shared/depfresh.BkxecpDK.mjs';
+export { d as detectPackageManager } from '../shared/depfresh.BkxecpDK.mjs';
 import 'ansis';
-import '../shared/depfresh.B1o7OHO_.mjs';
+import '../shared/depfresh.Dxgqypc6.mjs';
 import 'node:fs';
 import 'node:os';
 import 'find-up-simple';
 import 'ini';
 import 'pathe';
+import './json-output.mjs';
 import 'node:child_process';
+import '../shared/depfresh.FmznAfq4.mjs';
 import 'detect-indent';
 import 'semver';
 import 'pnpm-workspace-yaml';

package/dist/chunks/index2.mjs

@@ -1,14 +1,16 @@
 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.ClIHCCxD.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.BkxecpDK.mjs';
 import c from 'ansis';
-import '../shared/depfresh.B1o7OHO_.mjs';
+import '../shared/depfresh.Dxgqypc6.mjs';
 import 'node:fs';
 import 'node:os';
 import 'find-up-simple';
 import 'ini';
 import 'pathe';
+import './json-output.mjs';
 import 'node:child_process';
+import '../shared/depfresh.FmznAfq4.mjs';
 import 'detect-indent';
 import 'pnpm-workspace-yaml';
 import 'yaml';

package/dist/chunks/index3.mjs

@@ -1,7 +1,8 @@
 import './config.mjs';
-import { c as createLogger } from '../shared/depfresh.B1o7OHO_.mjs';
+import '../shared/depfresh.FmznAfq4.mjs';
 import { execSync } from 'node:child_process';
-import '../shared/depfresh.ClIHCCxD.mjs';
+import { c as createLogger } from '../shared/depfresh.Dxgqypc6.mjs';
+import '../shared/depfresh.BkxecpDK.mjs';
 
 function detectGlobalPackageManager(pm) {
   if (pm && (pm === "npm" || pm === "pnpm" || pm === "bun")) {

package/dist/chunks/interactive.mjs

@@ -1,13 +1,15 @@
 import * as p from '@clack/prompts';
 import c from 'ansis';
-import { a as arrow, b as colorizeVersionDiff, e as colorDiff } from '../shared/depfresh.ClIHCCxD.mjs';
-import '../shared/depfresh.B1o7OHO_.mjs';
+import { a as arrow, b as colorizeVersionDiff, e as colorDiff } from '../shared/depfresh.BkxecpDK.mjs';
+import '../shared/depfresh.Dxgqypc6.mjs';
 import 'node:fs';
 import 'node:os';
 import 'find-up-simple';
 import 'ini';
 import 'pathe';
+import './json-output.mjs';
 import 'node:child_process';
+import '../shared/depfresh.FmznAfq4.mjs';
 import 'detect-indent';
 import 'semver';
 import 'pnpm-workspace-yaml';

package/dist/chunks/json-output.mjs

@@ -0,0 +1,65 @@
+const RETRYABLE_CODES = /* @__PURE__ */ new Set(["ERR_REGISTRY", "ERR_CACHE"]);
+function buildJsonPackage(name, updates) {
+  return {
+    name,
+    updates: updates.map((u) => ({
+      name: u.name,
+      current: u.currentVersion,
+      target: u.targetVersion,
+      diff: u.diff,
+      source: u.source,
+      ...u.deprecated ? { deprecated: u.deprecated } : {},
+      ...u.publishedAt ? { publishedAt: u.publishedAt } : {},
+      ...u.currentVersionTime ? { currentVersionTime: u.currentVersionTime } : {}
+    }))
+  };
+}
+function outputJsonEnvelope(packages, options, executionState, errors = []) {
+  const allUpdates = packages.flatMap((p) => p.updates);
+  const count = (diff) => allUpdates.filter((u) => u.diff === diff).length;
+  const output = {
+    packages,
+    errors,
+    summary: {
+      total: allUpdates.length,
+      major: count("major"),
+      minor: count("minor"),
+      patch: count("patch"),
+      packages: packages.length,
+      scannedPackages: executionState.scannedPackages,
+      packagesWithUpdates: executionState.packagesWithUpdates,
+      plannedUpdates: executionState.plannedUpdates,
+      appliedUpdates: executionState.appliedUpdates,
+      revertedUpdates: executionState.revertedUpdates
+    },
+    meta: {
+      schemaVersion: 1,
+      cwd: options.cwd,
+      mode: options.mode,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      noPackagesFound: executionState.noPackagesFound,
+      didWrite: executionState.didWrite
+    }
+  };
+  console.log(JSON.stringify(output, null, 2));
+}
+function outputJsonError(error, options) {
+  const code = error instanceof Error && "code" in error ? error.code : "ERR_UNKNOWN";
+  const message = error instanceof Error ? error.message : String(error);
+  const output = {
+    error: {
+      code,
+      message,
+      retryable: RETRYABLE_CODES.has(code)
+    },
+    meta: {
+      schemaVersion: 1,
+      cwd: options.cwd,
+      mode: options.mode,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+  console.log(JSON.stringify(output, null, 2));
+}
+
+export { buildJsonPackage, outputJsonEnvelope, outputJsonError };

package/dist/chunks/normalize-args.mjs

@@ -1,12 +1,14 @@
-const VALID_MODES = /* @__PURE__ */ new Set([
-  "default",
-  "major",
-  "minor",
-  "patch",
-  "latest",
-  "newest",
-  "next"
-]);
+import { C as ConfigError } from '../shared/depfresh.FmznAfq4.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 validateEnum(value, flagName, validValues) {
+  if (typeof value !== "string" || !validValues.includes(value)) {
+    throw new ConfigError(
+      `Invalid value for ${flagName}: "${String(value)}". Expected one of: ${validValues.join(", ")}.`
+    );
+  }
+  return value;
+}
 async function normalizeArgs(args) {
   const { resolveConfig } = await import('./config.mjs').then(function (n) { return n.c; });
   const depFields = {};
@@ -20,7 +22,11 @@ async function normalizeArgs(args) {
     depFields.peerDependencies = false;
     depFields.optionalDependencies = false;
   }
-  const mode = args.mode_arg && VALID_MODES.has(args.mode_arg) ? args.mode_arg : args.mode;
+  const modeValue = args.mode_arg ?? args.mode;
+  const mode = validateEnum(modeValue, "--mode", VALID_MODES);
+  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;
   return resolveConfig({
@@ -35,13 +41,13 @@ async function normalizeArgs(args) {
     global: args.global,
     peer: args.peer,
     includeLocked: args["include-locked"],
-    output: args.output,
+    output,
     concurrency: Number.parseInt(args.concurrency, 10),
-    loglevel: args.loglevel,
+    loglevel,
     depFields,
     all: args.all,
     group: args.group,
-    sort: args.sort,
+    sort,
     timediff: args.timediff,
     cooldown: Number.parseInt(args.cooldown, 10),
     nodecompat: args.nodecompat,