@kaisers-io/refs 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,226 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-09-08
+
+### Upgrading
+
+Run `refs sync` after updating. Two things are worth expecting on that first run.
+
+**Packages may be reported as `missing` that are still on disk.** Negated workspace patterns are
+applied now, so a package a repository excludes (`!examples/vue/2*`) is no longer a workspace
+member — and an entry registered for one before this release no longer verifies. Nothing is removed
+automatically; the finding names the entry and leaves the decision alone.
+
+**Packages that arrived upstream since the last sync are reported.** Only those: a package the
+configuration never had and that did not arrive in the fetched range stays unmentioned, however
+long it has been there.
+
+### Added
+
+- **`refs sync` now reports a package that arrived upstream, and `refs edit --create` registers
+  it.** The drift probe checked the packages the configuration already had, so a package added
+  upstream after `refs add` stayed invisible — and there was no command to register one either:
+  `refs add` refuses an already-tracked ref, and every `refs edit` mode needs an entry to edit. The
+  only instruction anyone could give was "hand-edit `config.toml`".
+
+  `refs sync` answers "did upstream gain a package?" from the range it just fetched, not by
+  comparing a scan against the configuration. That distinction is the whole design: a scan cannot
+  tell a package that just arrived from one the ref's owner deliberately never tracked, because
+  there is no inventory of what was there before — the fetch range is that inventory. A ref whose
+  owner tracks 3 packages out of 140 hears about the other 137 exactly never. `refs doctor` lists
+  every unregistered member instead, because it was asked to.
+
+  The question it asks of that range is about package NAMES, not manifest paths. A package
+  renamed in place modifies its manifest rather than adding one, and a package merely moved to
+  another directory adds one without being new — so a path-based reading is wrong in both
+  directions. Only the manifests the range actually changed have to be read out of history: an
+  untouched manifest is byte-identical at both ends, so the name it carries now is the name it
+  carried before.
+
+  The repair is a command now rather than a config fragment, with the ref key filled in so it
+  runs as printed:
+
+  ```
+  refs edit 'github.com/acme/alpha' --package '@acme/new' --create --path 'packages/new' \
+    --description "<what it is>"
+  ```
+
+  It is a distinct mode, not an upsert — an ordinary field edit naming an unregistered package
+  still fails with `not_found`, so a typo in `--package` can never become a new entry. The
+  finding carries `name` and `path`, both verified against the checkout and both shell-quoted
+  (being verified makes a value true, not shell-safe: `zPackagePath` permits `$()` and a manifest
+  `name` is checked only for being non-empty), and deliberately no description: a manifest description is untrusted third-party content, and copying it moves it
+  into a file refs later reads as its own configuration. The skill instructs agents to propose the
+  registration and wait for the user to agree, rather than run it on their own initiative.
+
+### Fixed
+
+- **Workspace patterns are matched by `minimatch`, the matcher npm itself uses.** Hand-written
+  matching disagreed with the real resolvers in five distinct ways, each found only after the last
+  was fixed: extglob (`@(a|b)`) read as a literal directory name, trailing slashes treated
+  symmetrically where `minimatch` is asymmetric, repeated separators silently matching nothing, and
+  two more. Delegating removes that class of defect rather than the current instance of it.
+
+  Measured before choosing: `picomatch` disagrees with `minimatch` on ten of 154 comparisons over
+  the shapes this scanner supports, exactly on trailing slashes and repeated separators — so it is
+  not a drop-in. pnpm matches through `picomatch` but normalizes first, and was measured to agree
+  with `minimatch` on every one of those shapes, so one matcher covers both ecosystems.
+
+  Walking stays here: containment guards, the diagnostics that say why a scan came up short, and
+  the deliberate one-level depth policy are unchanged. `minimatch` answers only whether a path
+  matches a pattern. Nothing new is installed by `refs` users — the CLI publishes a bundle with no
+  dependencies — and that bundle grows by 24 KB.
+
+  One behaviour improves as a consequence: a negation in a shape this scanner cannot WALK
+  (`!packages/{a,b}`) is now applied, because applying an exclusion needs matching and never
+  walking. It used to be reported as unsupported and silently ignored.
+
+- **Negated workspace patterns are applied instead of ignored.** `!packages/fixtures` was dropped
+  as an unsupported shape (a v1 simplification), so `refs add` registered packages the repository
+  had explicitly excluded, and every finding about a repository declaring one was silenced —
+  TanStack Query declares two, and all hundred of its packages came back `unverifiable`. Negations
+  are now expanded exactly like inclusive patterns and subtracted from the result, which makes the
+  scan an accurate statement of membership rather than an approximation of one.
+
+  A wildcard inside the last segment (`examples/vue/2*`) is supported too, since that is the shape
+  real repositories exclude by, and a negation nobody can expand costs every finding about the
+  repository rather than just the paths it names. Glob syntax that is still unimplemented —
+  `{a,b}`, `?`, `[…]` — now reports `unsupported_pattern` rather than reading as a literal
+  directory name and silently matching nothing.
+
+- **A monorepo can now be resolved by the name in its own root manifest.** Workspace detection
+  expands the globs a repository declares, and a workspace root is not one of its own targets — so a
+  root that names itself was registered nowhere, and `refs resolve @acme/toolkit` came back empty
+  for a repository that was tracked all along. `refs add` now registers a named root at `path: "."`
+  alongside the workspace members.
+
+  Both pnpm and Yarn address a workspace root by that name (`pnpm --filter <root-name>`,
+  `yarn workspace <root-name>`); npm and Turborepo use a positional handle instead. Of eighteen
+  well-known monorepos surveyed, eight carry a name someone would plausibly use for the repository
+  and ten carry a throwaway like `root` or `monorepo-root` — which is what settles it: registering
+  the name costs nothing where it is a throwaway, since nobody resolves `"root"`, and answers the
+  question where it is not.
+
+  Two things this deliberately does not do. A repository that declares no workspaces is untouched:
+  `refs add`'s npm fallback owns that shape, and probing the root there would displace a locator it
+  did not choose — as it also would where a workspace declaration selects nothing, so the package
+  named in an `npm:<pkg>` source survives there too. And where a workspace member already claims the
+  root's name — `@remix-run/react-router` is a real example, in a repository that also publishes
+  `react-router` — the member wins and the root is simply not registered, which costs that
+  repository nothing it had before. That rule lives in detection itself rather than in `refs add`,
+  so relocation agrees with registration: a member that moves is still found uniquely, instead of
+  becoming ambiguous against a same-named root and leaving `resolve` with no path for a package
+  that is plainly there. And a root is never reported as a package's new location: its name is an
+  alias for the repository, so a member that upstream deletes is reported as gone rather than as
+  having moved to the repository root — which would have sent a caller to the wrong directory and
+  described a move that never happened.
+
+  Refs tracked before this change keep the package map they were given, and no command adds one
+  entry to an existing ref — `refs add` refuses a tracked ref, `refs edit --package` needs an entry
+  to edit. So `refs sync` and `refs doctor`'s `config-drift` check now report a root the
+  configuration does not register, with the entry to add — including the path registration would
+  actually use, which is the member's rather than the root's where a workspace member declares the
+  same name. That costs one manifest read per ref, and a workspace scan only where there is
+  something to report; it is asked only of refs that already register packages, since a plain
+  reference repository registers none on purpose and is left alone.
+
+  The root package takes the ref's own description when its manifest carries none, which is the
+  ordinary case for a private workspace root. That is not the per-package fallback `refs add`
+  otherwise refuses: the root is not a package beside the repository, it is that repository.
+
+- **A failed lookup no longer reads as an absent repository.** `refs resolve` exits `4` when a query
+  matches nothing, and the message ended "run refs list, or add it: `refs add <url>`". That second
+  half is a guess: a query can miss every route while the repository is tracked perfectly well under
+  another identifier — a monorepo root whose own package name was never registered, for instance.
+  An agent read the suggestion as confirmation and told someone a repository they had tracked was
+  not tracked, then stopped.
+
+  The message now states what was searched and points at evidence rather than prescribing a fix, and
+  `--json` carries a `reason` on `resolve`'s routing misses: `unmatched_query` (nothing matched, by
+  any route), `package_not_registered` (the ref is tracked and registers no such package), or
+  `ref_not_registered` (a canonical git url named an absent ref — the one case where adding it is
+  the right answer, since only a canonical url establishes which ref was meant). There is deliberately no reason meaning "this repository does not exist", because nothing
+  refs can observe establishes that; and `reason` is absent on every other `not_found`, where its
+  absence means no narrowing is available rather than being a fourth value.
+
+  The skill's instruction changed with it. It used to say exit `4` means the ref is not tracked; it
+  now says exit `4` means the query matched no route, and requires a second lookup before any
+  conclusion. `refs resolve --ref <ref>`'s own miss also stopped suggesting a bare `refs show`,
+  which reports a package count and no names — it now suggests `--packages`, which actually shows
+  the map the reader was sent to inspect.
+
+- **A stale-lock reclaim could delete a lock another process was using.** refs reclaims a lock left
+  behind by a crashed process. The check that decided a lock was abandoned and the removal that
+  acted on it were two separate steps, and in the gap between them the lock could legitimately
+  become somebody else's: the original holder releases, a waiting process takes the same path, and
+  the reclaim then deletes a lock that is actively in use. Both processes go on to `reset --hard`
+  the same checkout.
+
+  Three changes close it for processes running this version:
+
+  - **Only a process the operating system reports as gone is reclaimed from automatically.** A lock
+    whose lease has run out but whose process still answers is now reported rather than taken — a
+    live process can release at any instant, and that release is what opened the gap. Same for a
+    lock whose metadata never finished being written, or carries no usable identity.
+  - **The acquisition is re-identified after the death check.** Proving the recorded process gone is
+    not enough on its own: the metadata is read first and the process probed after, so the path can
+    change hands in between and the probe then answers about the departed owner. Re-reading the
+    identity immediately before the removal is what ties the two together.
+  - **The marker that stops two reclaims colliding no longer expires.** It used to be taken over
+    after two seconds, so it only excluded a reclaim fast enough to finish inside that window; a
+    suspended one lost its marker mid-work and a second reclaim started on the same lock. Age is
+    not evidence of abandonment.
+
+  The protocol's own markers also moved into `locks/.claims/` and `locks/.tombstones/`, which no
+  lock name can reach — lock names must start with a letter or digit. That removes a collision
+  where a repository literally named `foo.steal-claim` produced the marker path of the lock for
+  `foo`, and with it the name-shape guessing `refs doctor` needed to tell the two apart.
+
+  **What this costs.** Three situations no longer recover on their own and need one explicit
+  command, which `refs doctor` prints along with the condition for running it safely — stop every
+  refs process on that home first, suspended ones included: a crash after the operating system has
+  reused the process id, a crash before the lock finished writing its metadata, and a crash while a
+  reclaim was starting.
+
+  The messages changed to match. `refs doctor`'s `locks` check separates a lock refs will reclaim
+  by itself from one it will not, and the failure message when a lock cannot be acquired no longer
+  says "already reclaimable — retry" for a lock nothing will ever reclaim. It also stopped
+  describing the window as the thing that frees a lock: waiting does not, and only a recorded
+  process the operating system reports as gone does.
+
+  **What it does not fix.** A refs process running an _older_ version follows none of this and
+  reclaims on its own terms. And no lock protocol can help when refs is hard-killed while its `git`
+  child survives: the successor's lock is honest about the lock, not about the directory.
+
+- **Two unrelated refs could share one lock.** The per-ref lock name replaced `/` with `_`, and `_`
+  is legal inside a ref key — so `github.com/acme_tools/widget` and `github.com/acme/tools_widget`
+  both derived `ref.github.com_acme_tools_widget`. The two then serialized against each other:
+  `sync` fans out four refs at a time and the loser failed on a lock conflict after the timeout,
+  `resolve`'s verification could block on a sync of a ref it has nothing to do with, and `doctor`'s
+  `config-drift` check reported the wrong ref as busy.
+
+  The name is now injective. A key containing no `_` encodes exactly as before, so it keeps the
+  lock name refs has always written for it; a key containing one moves into an escaped form under
+  `ref._`, where `_` becomes `_u` and `/` becomes `_s`. The two forms cannot collide, because a ref
+  key always starts with `[a-z0-9]` and so a plain name never begins `ref._`.
+
+  A lock name is one directory entry, so a key long enough to overflow one now falls back to a
+  digest under `ref.__` rather than failing `mkdir` with `ENAMETOOLONG`. The budget reserves room
+  for the sibling entries the steal protocol derives from a lock name — a name that could be
+  created but not renamed to its tombstone would strand an abandoned lock that nothing could then
+  reclaim, leaving the ref blocked until someone deleted the directory by hand. Both were already
+  true before this change, for keys past roughly 200 characters; reaching it needs a self-hosted
+  url, since no forge allows a path that long.
+
+  **One caveat if you run refs concurrently across an upgrade.** The lock name changes for a ref
+  whose key contains `_`, and for one long enough to reach the digest form — roughly 200
+  characters, either way. For such a ref, a process from any earlier release (the old scheme dates
+  to 0.1.1) derives a different name from a new one, so for the length of that overlap the two
+  would not exclude each other. The window is a mid-upgrade concurrent run on the same refs home;
+  if that is a situation you can be in, let running operations finish before upgrading. Every other
+  ref keeps its name and is unaffected.
+
 ## [0.11.0] - 2026-08-31
 
 ### Changed
@@ -689,7 +909,8 @@ trusted-publishing pipeline end to end.
   installed git hooks.
 - Agent skill (`skills/refs/`) documenting the investigate/add/maintain workflows.
 
-[Unreleased]: https://github.com/kaisers-io/refs/compare/v0.11.0...HEAD
+[Unreleased]: https://github.com/kaisers-io/refs/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/kaisers-io/refs/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/kaisers-io/refs/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/kaisers-io/refs/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/kaisers-io/refs/compare/v0.8.3...v0.9.0