pithy upgrade

Reconcile every Worker’s wiring with the capability manifests the project has installed. With --packages, move the project’s @pithy-sh/* dependencies first.

Upgrading the kit is the walkthrough and versions and upgrades is the policy behind it. Run pithy doctor afterwards.

Synopsis

pithy upgrade [--env <env>] [--worker <name>] [--dry-run] [--migrate] [--packages [--latest]] [--json]

Flags

FlagTypeDefaultMeaning
--env <env>stringdevTarget environment — drives the pending-migration count, and any --migrate run
--worker <name>string—Upgrade only this Worker. Default: every Worker under apps/
--dry-runbooleanfalseShow the plan and write nothing
--migratebooleanfalseRun pending migrations after reconciling
--packagesbooleanfalseMove each @pithy-sh/* dependency to the newest version its range admits, and reinstall, before reconciling. Project-wide: refused beside --worker
--latestbooleanfalseWith --packages: move held packages across a breaking boundary to latest. Refused without --packages
--jsonbooleanfalseMachine-readable output

What it does

A capability’s manifest grows. A new release declares a binding it did not need before, or a config option it now takes. upgrade is what closes that gap in an existing project: it compares each Worker’s pithy.config.ts and wrangler.jsonc against the manifests that Worker resolves — its own node_modules/@pithy-sh, where pithy add installs, then the project root’s — and adds what is missing.

Capabilities are per Worker, so the reconcile engine is too. upgrade fans out over apps/*, building one plan per Worker against that Worker’s own wiring and applying it there.

Per Worker, a plan reports five things.

Missing bindings, per environment. A required binding the manifest declares that a wrangler stanza lacks — checked for every stanza in the file, since env.staging can be behind while the top-level one is current. Applying writes them in, comment-preserving, through the writer pithy add uses, and appends any Durable Object class migrations. A binding the Worker lists in ownBindings gets its owned name, and an owned D1 entry in the top-level stanza a database_id of its own (shared by default, owned when a Worker says so). A queue the capability consumes is missing until its stanza has both halves, the queues.producers entry and the queues.consumers entry for it, so a producer written by an older CLI is reported, and the apply adds the consumer with its retries, batch size and dead-letter queue. Your Worker’s own app is checked the same way. It is a capability with no manifest, so its requiredBindings are read off the composed config, and it reports under its own name with no config keys to add. Its entry gets one Durable Object export from upgrade: PresenceRoom, when the app itself declares a presence room, because that class lives in core. Every other class the app binds lives in its own main, and is yours to export.

Missing config keys. A manifest config option not yet present in that capability’s registration call. Applying inserts it with the manifest’s default rendered as its value and the option’s rationale as the comment above it. An existing key is never rewritten. A key counts as present however it is written: key: value, a shorthand (turnstile({ widgets })), a method or an accessor. A registration that spreads or computes keys (turnstile({ ...base })) might already carry any option, so nothing is reported or inserted for it — a default appended after the spread would win.

Ejected capabilities. Named, never touched. A fork no longer tracks its package, so reconciling it would overwrite code you own.

Missing Durable Object exports. A durable_objects.bindings entry is half of a Durable Object; the other half is export { <Class> } from "…"; on the module main names, which is what wrangler resolves class_name against. A class bound in wrangler.jsonc and absent from the entry is drift a config read alone cannot see — the binding is there and the class is nowhere.

Pending migrations, counted for --env. Reported by default; applied only with --migrate, which names each database and migration as it starts, as pithy migrate does. --json prints none of it.

Three things sit outside that list. entitlements names this Worker’s own source files that gate a route on an entitlement while nothing the Worker composes provides one — report-only, because which capability to compose is your decision rather than the CLI’s. missingVersionMetadata covers the version_metadata binding: without it a Worker cannot report which build is running, so log records carry no version, audit events carry no build id, and pithy deploy cannot verify the deploy it just made.

And strayPresenceRooms covers a presence room left behind: a Worker that binds PRESENCE_ROOMS to PresenceRoom while no environment’s composition declares a room kind, because the capability that declared one was removed or stopped declaring it. This is the one thing upgrade takes out rather than adds, so it is decided across every environment the Worker declares, not only --env: one environment that still declares a room keeps it everywhere. An apply removes the binding from every environment, retires the class with a deleted_classes migration under a tag of its own, and removes the export { PresenceRoom } from "@pithy-sh/core/src/presence/durableObject"; line from the entry — only that line, never an export you wrote. The creation tag stays: a Worker that deployed with the room holds it, and Cloudflare refuses a deploy that stops exporting a class without a deleted_classes step. A room stores nothing, so deleting the class loses nothing, and a room declared again later is created again under a new tag.

api:
  Presence rooms: none declared. Remove PRESENCE_ROOMS and the PresenceRoom export.

api:
  Presence rooms: none declared. Removed PRESENCE_ROOMS and the PresenceRoom export.

The entry is the one file it writes that is source

So both halves of that write are named. A dry run says what is missing, and an apply says what it wrote:

api:
  Worker entry: export MultiplayerSession.

Over every composed capability, not only the ones with a missing binding — a project wired before the CLI wrote that line has the binding already and the export nowhere, and wrangler deploy refuses it. That project is exactly who runs this command, so it is reported rather than repaired in silence.

Installed is not composed

A Worker resolves its own manifests and the root’s, and the root’s describe every capability installed there for any Worker — not what this Worker is made of. A plan is scoped to the Worker’s own composed set. A capability another Worker added contributes nothing here; anything else would put a foreign capability’s bindings, and its Durable Object class migrations, on a script that never declared them.

A malformed manifest is named, not skipped in silence. Faults are project-wide — the root’s node_modules and every workspace member’s are read, and a broken package is named once — so they are reported once, above the Workers. A capability with a fault appears in no other line of the report: its manifest could not be read, so it contributes no drift and the run reconciles around the hole.

A dry run resolves no project name and proposes none, so nothing can be written. An apply resolves the name from the root config, because a capability wired by upgrade must get the same <project>-<env>-<binding> resource name it would have got from add.

upgrade skips ejected capabilities, touches no Cloudflare account, and writes only config files, the Worker entry’s Durable Object exports — adding them, and removing the presence room’s when nothing declares a room kind — and, with --migrate, the database for --env. With --packages it also writes the package.json files it moves and runs one install.

The Pithy block in AGENTS.md is refreshed too, once per run, project-wide, after the Workers resolve. The block is what pithy init writes for the agent working in the project, and a newer CLI has newer things to say. Only the lines from <!-- pithy:begin through <!-- pithy:end --> are replaced; every byte outside them is left exactly as it was. A project scaffolded before the block existed gets it, appended after a blank line, or a new AGENTS.md holding it. A current block is not rewritten and gets no line. --worker does not narrow it, because the file is the project’s. --dry-run says what it would do and writes nothing. Broken markers and a symlinked AGENTS.md are refused and named, never guessed at, and the run’s exit is unchanged by it. CLAUDE.md is never touched.

$ pithy upgrade
AGENTS.md: Pithy block refreshed.
board:
  Nothing to upgrade.
Done.

--packages

Without it, upgrade never moves a version. It reads the manifests installed and wires what they declare. --packages is the step before that: it moves the versions, then the reconcile reads the ones just installed.

Every @pithy-sh/* dependency, in every workspace member’s manifest. The members are the root, every apps/* directory, and every directory the workspace globs match that holds a package.json: the root package.json workspaces, as an array or as { "packages": [...] }, and pnpm-workspace.yaml’s packages when there is one. A ! glob removes what the others matched, node_modules is never walked, a glob that leaves the project matches nothing, and a member two globs match is read once. A project with no workspaces reads the root and apps/*. A package.json outside the workspace is not one the package manager installs from, and is not moved. In each manifest, dependencies and devDependencies are read, @pithy-sh/cli included. Each declaration is planned on its own, so a member that pins a package differently from the root keeps its own answer. A failed install restores every member’s package.json byte for byte.

Within range by default. ^x.y.z, ~x.y.z and an exact x.y.z are moved to the newest version the range admits, by rewriting the floor and keeping the operator: ^0.2.0 becomes ^0.2.3. The floor is what makes the lockfile move. The candidates are the published versions that are not prereleases, not deprecated, and not newer than latest. Everything else is left alone and said so: workspace:, link:, file:, git and URL specs, tags, *, >=, || and x-ranges are not registry ranges, and a package linked in from a checkout is not the registry’s to move.

Held at a breaking boundary. When latest is outside the range, the entry is held and named — breaking across a new major, or a new minor under 0.x, where a minor is breaking by convention; outside-range for any other gap. A move and a hold can both apply: ^0.2.0 moves to ^0.2.3 and holds 0.3.1. --latest is the opt-in. It moves every held entry to latest, keeping the operator; an exact pin stays exact.

$ pithy upgrade --packages
Packages:
  @pithy-sh/auth  ^0.6.3 → ^0.6.5  (package.json, apps/board/package.json)
  @pithy-sh/ui-react  0.3.1 held, 0.2.0 installed. A new 0.x minor crosses a breaking boundary. Run pithy upgrade --packages --latest.
  @pithy-sh/ui-react  0.3.1 held, 0.3.0 installed. Outside the declared range 0.3.0. Run pithy upgrade --packages --latest.
  @pithy-sh/x  workspace:* left alone. Not a registry range.
board:
  Nothing to upgrade.
Held back: @pithy-sh/ui-react 0.3.1. Run pithy upgrade --packages --latest to take it.
Done.

Every hold is named twice. Under Packages:, one line per package held the same way: the newest release, the version installed where its manifest resolves it (nothing installed when nothing is), why, and the command that takes it. The reason is A new major crosses a breaking boundary., A new 0.x minor crosses a breaking boundary., or Outside the declared range <range>.. Then, last before Done., one Held back: line names every package held with its newest release, and the command once, so a run that moved everything it could still ends on what it did not take. A run that holds nothing prints neither. On a real run the range and the version installed are read after the install, so a declaration that moved within its range and held the next minor reports the range it was rewritten to and the version it moved to: ~1.2.0 moved to ~1.2.5 and holding 1.3.0 reads 1.3.0 held, 1.2.5 installed. Outside the declared range ~1.2.5.

One install, at the root. The rewritten manifests and the lockfile are one rollback scope: an install that fails puts every package.json and a text lockfile back byte for byte, and the run ends there. bun.lockb is binary and is not restored; bun install settles it. After the install, every moved package is read back from where its manifest resolves it, and a package manager that resolved something else is a mismatch, named, and the run exits 1.

When @pithy-sh/cli itself moves, the reconcile waits. The process running is the old CLI, and reconciling with its engine would write the old answer into a project that just asked for the new one. So does the AGENTS.md block, for the same reason, and agents is absent from --json. It says so, naming the project’s own CLI through its package manager — @pithy-sh/cli moved to 0.10.0. Run bun x pithy upgrade to reconcile with it. — and exits 0, with that command as next. A bare pithy may be a global install, which is the old CLI. The line is your own run again, less the package move it already made: the --env and --migrate you passed ride on it (bun x pithy upgrade --env staging --migrate), and --packages and --latest do not.

A registry that does not answer moves nothing. Every packument is read before any is acted on, and one that fails or will not parse makes the step unavailable: nothing is written or installed, the reconcile still runs, and the exit is 1. A plan built from the packages that did answer would move half of a group that is released together.

The templates a move changed

pithy ui add copies @pithy-sh/ui-react’s templates into the Worker, and the copies are yours from then on. A version bump that changes a template leaves your copy on the old shape: a sign-in screen still reading a refusal code the server no longer sends renders nothing, and nothing says why. So --packages reports, per Worker with a React front end — any workspace member, not only apps/* — every copied file whose template changed between what is installed now and what the move installs. A member under apps/ is named by its directory, any other by its path, and one directly under the root as ./<dir>.

The comparison is by content, not by record, and your file at each template path is:

  • equal to the target — silent. It is current.
  • equal to any other version’s template — changed upstream. The copy is 0.2.0's, untouched.
  • anything else, where the template differs between an installed version and the target — changed upstream. The copy is edited. Merge by hand. An edit of a file the move does not change is yours, and is not named.
  • new in the target, and absent here — new in 0.3.1. Not in this Worker.
  • gone from the target, and still here — gone from 0.3.1. Still in this Worker.

A tarball is fetched only from registry.npmjs.org, read to 10 MB and no further, and refused whole when an entry’s name carries a control character, since the names are printed. Nothing here rewrites a file, and a finding does not change the exit. A file moved off its template path is not seen — the comparison is by path.

React Native apps are not compared. An app scaffolded by pithy ui add react-native holds @pithy-sh/ui-react-native’s templates, and this report reads @pithy-sh/ui-react’s alone. Each such app is named by its path, Templates: apps/<app> is a React Native app. Its templates are not compared; diff it against @pithy-sh/ui-react-native's by hand. (or mobile/tablet, for a member outside apps/), and listed in --json as packages.uncompared, named the way the report names a Worker. The key is absent when there are none.

--dry-run --packages fetches, plans and reports the templates, writes nothing and runs nothing, and reconciles as a dry run against what is installed now.

--json

One line, one object. The workers array carries a plan on a dry run and an applied result otherwise, and the two shapes differ.

Every entry leads with state, and only "reconciled" carries either shape — a Worker that could not be read has no plan to report, and no empty one to be mistaken for a clean bill.

$ pithy upgrade --dry-run --json
{"command":"upgrade","schemaVersion":3,"env":"dev","dryRun":true,"workers":[{"state":"reconciled","worker":"board","deployedAs":"replay-board","env":"dev","perCapability":[{"name":"auth","missingBindings":[],"missingConfigKeys":[]}],"ejectedSkipped":[],"ledger":{"state":"read","pending":1,"undeclared":[]},"entitlements":{"state":"read","gates":[]},"missingVersionMetadata":false}],"manifestFaults":[],"agents":{"path":"AGENTS.md","state":"updated","reason":null},"plan":{"files":[{"path":"AGENTS.md","action":"edit","changes":["Refreshes the Pithy block. Nothing outside it changes."]}],"resources":[],"migrations":[],"secrets":[],"data":[],"notes":["board: 1 migration pending on dev. pithy upgrade --worker board --env dev --migrate applies them."]}}

The envelope

KeyTypeMeaning
command"upgrade"The command that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
envstringThe environment the run targeted
dryRunbooleanWhether --dry-run was passed. This is what says which shape workers carries
workersarrayOne entry per Worker in scope, in discovery order
workers[].state"reconciled", "unplanned", "unapplied" or "refused"Whether this Worker was reconciled, could not be planned at all, was planned and failed partway through the apply, or was refused before the first write
manifestFaultsarrayInstalled packages shipping a manifest that is present and unusable. Project-wide. Empty on a healthy install
manifestFaults[].packagestringThe package the manifest was read from
manifestFaults[].filestringThe manifest file within that package: pithy.manifest.json, or a companion such as pithy.mcp.manifest.json
manifestFaults[].reasonstringWhy it could not be used — the schema’s refusal text, or the errno where the file would not open
packagesobjectPresent only with --packages. What the package step did — below
agentsobjectThe Pithy block in AGENTS.md. Absent only when --packages moved @pithy-sh/cli, which leaves the block to the new CLI
agents.pathstring"AGENTS.md", relative to the project root
agents.state"added", "updated", "unchanged" or "refused"added — there was no block, and now there is. updated — the block was stale and was rewritten in place. unchanged — already current, and the file was not written. refused — not written, and reason says why; the exit is unchanged by it
agents.reasonstring or nullWhy it was refused, in one line that never quotes the file. null otherwise
planobjectPresent only under --dry-run: the same run, in the shape every --dry-run shares — a file edit per file the apply would write, each with its changes, and notes for what a file entry cannot say
nextobject[][{ command, why }], the step this run left required: the project’s own CLI’s upgrade through its package manager (bun x pithy upgrade, with the run’s own --env and --migrate) when --packages moved @pithy-sh/cli, otherwise pithy migrate --env <env> for the migrations it counted and did not run without --migrate. Absent otherwise, and never empty

packages

KeyTypeMeaning
packages.state"read" or "unavailable"unavailable when any packument would not read. Nothing was written or installed, and the run exits 1
packages.packageManager"bun", "pnpm", "yarn" or "npm"The manager detected from the lockfile, which ran the install
packages.installedbooleanWhether the install ran. false on a dry run, when nothing moves, and when unavailable
packages.reconciledbooleanWhether the Workers were reconciled afterwards. false when @pithy-sh/cli itself moved, and workers is then empty
packages.movesarrayOne entry per declaration rewritten, each with name, manifest (relative to the root), field (dependencies or devDependencies), from and to (the ranges), and target (the version the new range installs)
packages.heldarrayOne entry per declaration whose latest is outside its range, each with name, manifest, range (the range declared: the one the run wrote when it moved that declaration on a real run, the one before it on a dry run), installed (the version its manifest resolves, or null: read after the install on a real run, before it on a dry run), latest (the newest release a move may land on), reason ("breaking" across a new major or a new 0.x minor, "outside-range" for any other gap) and command, the command that moves it. Empty when nothing was held
packages.leftAlonearrayOne entry per declaration not moved, each with name, manifest, spec and reason ("not-a-registry-range" or "linked")
packages.mismatchesarrayMoves whose target is not what the install left, each with name, manifest, expected and installed (or null). Non-empty exits 1
packages.templatesarrayAt most two sections: the target this run installs (applied: true) and the one only --latest would (applied: false). Empty when no template-bearing package moves
packages.templates[].state"checked", "unchecked" or "unavailable"unchecked when nothing installed carries templates to compare from; unavailable when the target would not read, which exits 1
packages.templates[].package"@pithy-sh/ui-react"The package the templates come from
packages.templates[].fromstring[]The installed versions compared from, ascending
packages.templates[].tostring or nullThe target version, or null when it could not be resolved
packages.templates[].appliedbooleanWhether this run installs to
packages.templates[].filesarrayOne entry per file to look at, each with worker, path (relative to the Worker), change ("changed", "added" or "removed"), copy ("untouched", "edited", "absent" or "present") and, for an untouched copy, from, the version it is a copy of
packages.uncomparedstring[]Apps with a React Native front end, whose templates the report does not compare. Absent when there are none

The three states that are not reconciled

stateDiagram-v2
    direction LR
    [*] --> ReadConfig
    ReadConfig --> unplanned: would not read
    ReadConfig --> BuildPlan
    BuildPlan --> refused: a declined binding cannot be honored
    BuildPlan --> reconciled: dry run, plan reported
    BuildPlan --> Apply
    Apply --> reconciled: applied
    Apply --> unapplied: failed partway

    note right of unplanned
      Nothing established.
      Nothing written.
    end note
    note right of refused
      Nothing written. A declaration
      to fix, not half a wiring.
      Refused on a dry run too.
    end note
    note right of unapplied
      Files were opened for writing.
      The plan is what the run set out
      to do, not what landed.
    end note

One entry per Worker, and every other Worker still reports in full.

A Worker whose declinedBindings cannot be honored carries "refused", with the plan, the code, and the operator’s own problem and action lines. Distinct from unapplied, and the distinction is the fact you need: nothing was written, so there is no half-reconciled wiring to inspect — only a declaration to fix. It is refused on --dry-run too, because a dry run’s job is to predict the write and this is the thing that stops it.

A Worker whose plan could not be built carries "unplanned" and nothing else. Its config would not read, so nothing was established about it and nothing was written for it — and the fields a reconciled entry has would each be a claim nobody checked.

A Worker whose apply failed partway carries "unapplied" with its plan. That is a different state on purpose: this Worker’s files have been opened for writing, so its wrangler.jsonc may hold part of the plan and under --migrate its schema may have moved. The plan is what the run set out to do, not what landed — what landed is exactly what an interrupted apply cannot say.

Every other Worker still reports in full. A run that loses four Workers’ reports to a fifth one’s broken config is the report you cannot use on the day you need it. Either state exits 1, on the same standard pithy doctor holds. A failure of the whole run is one {"error": …} line on stderr instead, and exits by its class.

workers[] when dryRun is true

KeyTypeMeaning
workerstringThe Worker this plan targets, as its apps/<name> directory
deployedAsstringThe same Worker’s deployed script name
envstringThe environment the pending-migration count was computed for
perCapabilityarrayPer installed, non-ejected capability, and the Worker’s own app: what an upgrade would add
perCapability[].namestringThe capability’s short name, from its manifest. The app’s is its own name
perCapability[].missingBindingsarrayRequired bindings absent from one or more environments’ stanzas
…missingBindings[].envstringThe environment missing the binding — dev for the top-level stanza
…missingBindings[].namestringThe Worker env binding name the capability requires
…missingBindings[].typestringd1, kv, r2, ai, vectorize, queue, ratelimit, email, secret, workflow, service, durable_object, hyperdrive, browser, images, analytics_engine_datasets, pipelines, mtls_certificates, dispatch_namespaces or artifacts
perCapability[].missingConfigKeysarrayManifest config options not yet present in this capability’s registration
…missingConfigKeys[].keystringThe option name to add
…missingConfigKeys[].defaultJSON valueThe manifest default rendered as the option’s value
…missingConfigKeys[].describestringThe option’s rationale, rendered as the comment above it
perCapability[].missingEntryExportsstring[]Durable Object classes this capability binds that the entry module does not export
ejectedSkippedstring[]Ejected capabilities, by name
declinedBindingsobjectThis Worker’s declinedBindings, resolved against what it composes. The entries sit behind state, so a declaration that would not parse cannot be read as declining nothing
declinedBindings.state"read" or "invalid"Whether the declaration parsed
declinedBindings.declines[].state"honored", "required", "undeclinable" or "unrecognized"Whether the decline is applied, or refused because the binding is required, refused because its kind cannot be declined, or names nothing this Worker composes
declinedBindings.declines[].reasonstringThe reason written in pithy.config.ts
declinedBindings.declines[].stillPresentInstring[]Environments whose stanza still carries the binding, written by an upgrade that ran before the decline. Declining stops it coming back; it never deletes what is there
ledgerobjectWhat env’s databases have applied against what this Worker declares. The counts sit behind state, so a sum taken over some of the databases cannot be read as a sum over all of them
ledger.state"read", "partial" or "unavailable"Whether every database in scope answered, some did, or none did
ledger.pendingintegerUnapplied migrations for env. Present on read alone
ledger.undeclaredarrayMigrations the databases have applied that this Worker no longer declares — the direction a pending count is blind to
ledger.countedobjectThe same two fields over the databases that answered. Present on partial alone, and spelled differently there on purpose: it is a sum with a known hole in it
ledger.unreadablearrayEvery database whose ledger could not be read
entitlementsobjectWhether this Worker gates a route on an entitlement while nothing it composes provides one
entitlements.state"read" or "unavailable"Whether the Worker’s source tree was scanned
entitlements.gatesstring[]The gating source files. Present on read alone, so an all-clear and an unread tree cannot be confused
missingVersionMetadatabooleanWhether this Worker’s wrangler.jsonc lacks the version_metadata binding
strayPresenceRoomsbooleanWhether this Worker binds PRESENCE_ROOMS to PresenceRoom while no environment’s composition declares a room kind. Absent from a plan an older CLI built

workers[] when dryRun is false

KeyTypeMeaning
workerstringThe Worker this apply targeted
deployedAsstringThe same Worker’s deployed script name
perCapabilityarrayPer capability that changed. A capability with nothing added does not appear
perCapability[].addedBindingsarrayThe bindings written into wrangler.jsonc, same shape as missingBindings
perCapability[].addedConfigKeysstring[]The config option keys inserted. Keys only, not the rendered values
ejectedSkippedstring[]Ejected capabilities, by name
migratedbooleanWhether the migration step ran. True only with --migrate
migrationsarrayThe per-database migration runs when migrated; empty otherwise
migrations[].databasestringThe database name
migrations[].bindingstringThe D1 binding it resolves to
migrations[].results[].migrationNamestringThe migration’s namespaced name
migrations[].results[].direction"Up" or "Down"The direction it was executed in
migrations[].results[].status"Success", "Error" or "NotExecuted"NotExecuted means an earlier migration failed
migrations[].sharedWithstring[]The other Workers bound to this same physical D1
addedVersionMetadatabooleanWhether this run added the version_metadata binding
addedEntryExportsstring[]The Durable Object classes this run exported from the Worker’s entry
retiredPresenceRoomsbooleanWhether this run took the presence room’s binding and entry export out of a Worker that declares no room kind, and retired its class. Absent from a report an older CLI built

The two shapes differ in what a run produced, never in how it names the Worker. worker and deployedAs are in both, carrying the same two strings — a key present on one side and absent on the other would mean a consumer that worked under --dry-run read undefined on the run that actually wrote something.

Errors

An environment that does not exist. Validated at the flag, before anything is read.

$ pithy upgrade --env production
"production" is not an environment name in Pithy.
Use `prod`.

A --worker that names nothing. The refusal lists the Workers that do exist.

A Worker config that will not load. A pithy.config.ts that cannot be imported fails the whole run, naming the config and what stopped it: the import that did not resolve, or the file and line that would not compile, which may be a module the config imports rather than the config itself. TypeScript that Node’s type stripping refuses, such as an enum, is named with its construct and the rewrite. That is the Worker set failing to resolve — the fan-out’s input rather than one of its contributors.

$ pithy upgrade
Could not load apps/board/pithy.config.ts.
"@pithy-sh/core" is not installed. Install the project's dependencies (bun install), or correct that import.

--migrate on a project with no name. Resolved before any Worker is reconciled, so nothing is written.

Examples

$ pithy upgrade --dry-run
deck:
  Nothing to upgrade.
tally:
  Nothing to upgrade.
Dry run. Nothing written.

Every Worker in scope appears, including one with nothing to do — the run covered it, and silence would read as skipped.

pithy upgrade --migrate --env staging
pithy upgrade --worker deck
ESC