@kaisers-io/refs 0.8.3 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-13
+
+### Added
+
+- `refs resolve` now verifies that the package it routes to is actually where the config says
+  it is. A configured `path` is only a locator; the package name is its identity, and upstream
+  repos restructure on their own schedule. Previously a package that had moved — or a different
+  package that had taken over its directory — was handed back regardless, so an agent read the
+  wrong source and answered confidently. That failure produced no error and no warning.
+
+  `package.status` now reports what was established: `verified`, `relocated` (found at exactly
+  one new path, which is returned in place of the stale one), `unmaterialized` (no checkout yet),
+  `unverifiable` (verification could not complete — `reason` says why), `ambiguous` (the name
+  exists at several paths, listed in `candidates`), or `missing`. All six exit `0`; see
+  `docs/commands.md` for the full contract.
+
+  `relocated` corrects the answer for that call only and never writes to `config.toml`. Persist
+  it with `refs edit <ref> --package <name> path <new-path>`.
+
+### Changed
+
+- **`resolve`'s `package.local_path` can now be `null`.** It is `null` for `missing` and
+  `ambiguous`, where no safe location is known. A caller that treated a zero exit as "here is a
+  usable path" must check `package.status` first; previously the field was always a string.
+
+- Workspace detection now reports why it found nothing. An unreadable or malformed workspace
+  declaration, an unreadable manifest, a candidate resolving outside the repo, an unsupported
+  pattern, a package directory reachable only through a symlink — each used to collapse into the
+  same empty result, leaving a transient read error indistinguishable from "every package was
+  removed". Each is now reported, and a scan carrying any of them is treated as possibly
+  incomplete: it can neither conclude that a package is gone nor that a single sighting of one is
+  unique. `refs add` is unaffected — it consumes the same best-effort list it always has.
+
+  A manifest that reads fine but declares no usable `name` is reported too, but does **not** make
+  a scan incomplete: there is demonstrably no resolvable package at that path. Nameless manifests
+  are common enough (zod's own repository root has none) that treating them as failures would
+  permanently suppress detection for those repos.
+
+  One limit is deliberate and worth knowing: a scan only covers what the repo's workspace
+  declaration points at. A package registered by `refs add`'s npm fallback — at `path: "."`, or
+  the packument's `directory` — lives outside that coverage, so if it moves, `resolve` reports
+  `unverifiable` rather than guessing. It never reports `missing` from a scan that had nowhere
+  to look.
+
+## [0.9.0] - 2026-08-13
+
+### Added
+
+- refs tells you when a newer version is published. `refs sync` and `refs doctor` ask npm at most
+  once a day and cache the answer; `refs sync` mentions a newer release in its `warnings`, and
+  `refs doctor` reports it as a `cli-update` check. `refs --version` is untouched — it stays exactly
+  one version line on stdout, because the skill's capability gate and any script parse it.
+
+  Both switches live in `[updates]` in `config.toml` and default to on: `check` governs the registry
+  request everywhere, `notify` the routine path only. `notify = false` with `check = true` is
+  "don't interrupt me, but answer when I ask" — `refs sync` neither asks nor mentions, `refs doctor`
+  still does both. `REFS_UPDATE_CHECK` overrides `check` (`0` off, `1` on), and the check is off in
+  CI. The table is absent from a config that wants the defaults, and refs never writes one.
+
+  Nothing about it is load-bearing: an unreachable registry, a malformed answer or an unwritable
+  cache all mean "we don't know" and are never reported as a fault. The registry host is hardcoded
+  rather than read from npm configuration, only a plain `x.y.z` is accepted from the response, and
+  the update command is printed for you to run — refs does not install itself.
+
+### Fixed
+
+- A ref can be recorded without a `tag_format`. Finalizing an add used to reject a proposal whose
+  `tag_format_candidate` was `null`, which left one option for a repository that publishes no tags:
+  invent a convention. A real user hit this and was asked to confirm `v{version}` for two
+  repositories that have no tags at all — a claim nobody had verified, written into `config.toml`
+  where later agents read it as fact. The candidate now survives finalize as an absent field.
+
+  `refs tag` is the only command that reads it, and it exits `3` (validation) when there is none,
+  naming the ref — or the package, with the `--package` form of the fix. The distinction from `4`
+  carries information: `3` means this ref cannot resolve any version, `4` means this particular
+  version was never tagged. The skill's add flow gained an explicit branch for the `null` case, so
+  an agent reports the absence instead of proposing something to fill the gap.
+
+  A format already recorded can only be removed by editing `config.toml` directly; `refs edit` can
+  set one but has no way to unset it.
+
 ## [0.8.3] - 2026-08-12
 
 ### Added
@@ -433,7 +514,9 @@ 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.8.3...HEAD
+[Unreleased]: https://github.com/kaisers-io/refs/compare/v0.10.0...HEAD
+[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
 [0.8.3]: https://github.com/kaisers-io/refs/compare/v0.8.2...v0.8.3
 [0.8.2]: https://github.com/kaisers-io/refs/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/kaisers-io/refs/compare/v0.8.0...v0.8.1