@kaisers-io/refs 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -5,7 +5,187 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.13.1] - 2026-09-12
+
+### Upgrading
+
+**A repository declaring a workspace pattern like `crates/*/js` will suddenly report packages refs
+could not see before.** The pattern was classified as unsupported, which also made the whole scan
+unreliable and stood the unregistered-package pass down for that ref. `refs doctor` may therefore
+name members on a ref that reported nothing for months. They are not new; they were invisible.
+Register the ones worth routing to, and leave the rest.
+
+### Added
+
+- **Every drift finding that has a repair now prints it as a command.** `unregistered` has printed
+  a runnable `refs edit --create` since the probe shipped; `missing` and `relocated` described the
+  repair in prose and left the reader to construct it. The asymmetry was not deliberate — one of
+  the two repairs did not exist as a command at all. `refs doctor` now ends those findings with
+  `refs edit --package='<name>' --remove '<ref>'` and
+  `refs edit --package='<name>' '<ref>' 'path' '<new>'`, quoted for a shell like every other
+  command refs prints. A new path the configuration could not hold is still reported, without a command
+  that would only fail validation.
+
+  Every printed `refs edit` now attaches its option values with `=` and, where a positional would
+  otherwise begin with `-`, ends the options with `--`. Quoting gets a value past the shell; refs'
+  own parser reads it next, and `refs edit '<ref>' path '-new/pkg'` — a path `zPackagePath` accepts
+  — arrived correctly quoted and exited `2` with `unknown option '-new/pkg'`. The terminator is
+  printed only where it is needed, so appending `--json` to an ordinary printed line still works.
+
+- **`refs edit <ref> --package <name> --remove` unregisters a package.** The counterpart to
+  `--create`, and the repair the `missing` finding needed: a package that left a repository's
+  workspaces leaves an entry behind that `refs resolve` keeps answering with, pointing at a path no
+  checkout has. The only instruction refs could give was to hand-edit `config.toml`. Removal
+  touches configuration alone and never consults a checkout — it has to work while the checkout is
+  stale, absent, or still carrying the directory. Removing the last entry drops the `packages`
+  table rather than leaving an empty one, which `add` and the drift probe read differently.
+
+### Fixed
+
+- **A workspace pattern whose wildcard is not in its last segment is expanded.** `crates/*/js` —
+  the spelling a Rust/JS monorepo uses — was reported as `unsupported_pattern` and every package
+  beneath it went undetected. That pattern costs one `readdir` and a literal probe per child, the
+  same shape `packages/*` has, so the budget that refused it was measuring the wrong thing. Two
+  wildcards still mean two levels and `packages/*/nested/*` is still refused. Measured on a
+  repository declaring `crates/*/js` and `turbopack/crates/*/js`: 41 packages detected instead of
+  37, with no diagnostics; three other monorepos detect exactly what they did before.
+
+- **`tag_format` is detected from every tag, not from the top twenty of a refname sort.** Detection
+  counted formats among the first 20 tags of `git tag --sort=-version:refname`. That sort is
+  version-aware over the whole refname, so in a monorepo that tags per package it groups by prefix:
+  those twenty are one package's tags, not a sample of the repository's. Measured against two real
+  repositories, `refs add` proposed `create-astro@{version}` for a repository with 839
+  `astro@{version}` tags, and `keystatic@{version}` — a package whose last tag is `0.0.36` and whose
+  directory no longer exists — for one where `@keystatic/core@{version}` is the live package with 183 of
+  them. Both now resolve correctly, and the two repositories whose detection was already right are
+  unchanged.
+
+  A tag list that could not be read whole now yields no candidate at all rather than one derived
+  from whatever survived. `git tag` output is capped at the subprocess stream limit, and the note
+  saying so was written to stderr and never read — which did not matter while only twenty lines
+  were needed, and does once the count is a claim about all of them.
+
+  What this establishes is historical plurality, not which package is primary or still alive: a
+  retired package with a thousand tags still outvotes its replacement's hundred. The two-phase flow
+  shows the candidate for exactly that reason.
+
+## [0.13.0] - 2026-09-12
+
+### Upgrading
+
+**`refs add <url> --description "…"` now refuses a source with workspace members.** It holds one
+description, about the repository, and none for a package — and a package's description is no
+longer read out of its manifest, so there is nothing for it to fall back on. Such a source exits
+`3`, listing every package the proposal will need a description for and printing the two-phase
+commands to run instead, with the source quoted into them. The shortcut still finalizes a
+repository with no detected packages, and one whose only detected package is the root at `.`.
+
+If a script calls the one-shot against a monorepo, it will start failing. The two-phase flow is the
+replacement and always was the documented agent path.
+
+**Package descriptions already in `config.toml` are left exactly as they are.** A description
+imported from a manifest before this release stays; nothing distinguishes it from one someone
+wrote, so nothing rewrites it. To review them: `refs show <ref> --packages --json`, and
+`refs edit <ref> --package <name> description "…"` to replace one.
+
+**A ref key containing an unpaired surrogate is now rejected.** No configuration written by refs
+can contain one — TOML has no escape for it — so this only affects a hand-built key.
+
+### Fixed
+
+- **`refs add` says when it could not fully inspect a repository's declared workspaces.** A
+  repository declaring `packages/**` — an ordinary spelling the pattern classifier cannot expand —
+  produced a proposal missing every member, with no indication why. That is not self-explanatory:
+  a thin `packages` record is also what an ordinary repository produces, and a detected root makes
+  even a memberless result look complete. The configuration was then built without those packages,
+  and the drift probe returns immediately for a ref that configures none, so nothing downstream
+  could recover it either. Both `--dry-run` and the `--description` one-shot now carry a warning
+  naming what stopped the scan — an unexpandable pattern, an unreadable manifest, a candidate that
+  could not be inspected — alongside any clone warning rather than instead of it.
+
+- **A drift probe that could not finish looking says so, instead of reporting `ok`.** The pass that
+  finds packages a checkout declares and the configuration does not have stands down whenever
+  workspace detection may have missed something — an unreadable manifest, a pattern the classifier
+  cannot expand. That conservatism is right: a second declaration of the same name could be behind
+  the obstacle, and naming one path from a partial view would prescribe something registration
+  might not do. What was wrong is that it then said nothing at all, so `refs doctor` answered
+  `config-drift: ok — every configured package path resolves` while an unregistered package sat in
+  the checkout. One malformed `package.json` anywhere in a monorepo was enough, permanently.
+
+  Both discovery passes now report the obstacle. `structure` gains `discovery_incomplete`, naming
+  what stopped them (`packages/c: manifest_unreadable`), and its `status` is `unknown` rather than
+  `ok`. The findings about configured entries are unaffected — that half never needed the scan to
+  begin.
+
+- **A ref whose key carries `@`, a space or any non-ASCII character can be locked, and therefore
+  synced.** `zRefKey` admits every character but `/`, `\`, `%` and `:`; the lock alphabet is far
+  narrower, and the derived lock name was passed through unchanged. Such a ref could be added and
+  read but never locked — so `refs sync`, `refs remove`, `refs resolve`'s package verification and
+  `refs doctor`'s drift check all failed for it, with a message naming the lock name rather than
+  the ref. A name the lock alphabet will not accept now falls back to the same bounded digest form
+  a too-long name already used. Keys the alphabet does admit keep their readable name unchanged.
+  Reachable through a self-hosted url or a hand-edited `config.toml`; no forge allows these
+  characters in a repository path.
+- **A ref key carrying an unpaired surrogate is rejected.** Such a character is a valid JavaScript
+  string and has no UTF-8 encoding, so everything that writes the key out — the checkout directory,
+  the digest a lock name can fall back to — silently substituted U+FFFD for it. Keys ending
+  U+D800, U+D801 and U+FFFD therefore shared one directory and one lock name, and two unrelated
+  refs would have serialized against each other. No real config could carry one: TOML has no
+  escape for an unpaired surrogate.
+- **A failed sync no longer persists an unbounded amount of remote output into `state.json`.**
+  `last_error` holds the failure's message, most often git's own output — which quotes what git was
+  working on, ref names among them, chosen by the tracked repository. No persistence-specific limit
+  applied: an upstream with 120 conflicting tags produced a 47,816-character error, all of it
+  written into a file refs reads back on every command. A newly recorded message now keeps 1500
+  characters from the start and 500 from the end, with an exact count of what was dropped in
+  between — so both the command that failed and git's own closing hint survive. The result of the
+  run that produced the failure still carries the message as it arrived.
+
+### Changed
+
+- **Dependencies refreshed.** `zod` 4.5.2 → 4.6.2 — the only production dependency, and bundled
+  into the published CLI. The development toolchain moved too: `vitest` 4 → 5, `tsdown` 0.22 →
+  0.23 (rolldown 1.2.8), `oxlint`, `oxfmt` and `vite`. No behaviour depends on any of it.
+- **A package's description is never read out of a manifest.** Workspace detection carried each
+  package's `description` from its `package.json`, and `refs add <source> --description "…"`
+  persisted it into `config.toml` — text written by whoever owns the upstream repository, crossing
+  into a file refs reads back as its own configuration and replays on every `refs list` and
+  `refs show`. Detection now carries a package's name and path and nothing else, which is what
+  `refs sync`'s `unregistered` finding has done since 0.12.0. Every description in a config entry
+  is written by someone who read the source.
+
+  The one-shot `refs add <source> --description "…"` therefore no longer registers workspace
+  members: it has one description, about the repository, and none for a package. It still
+  finalizes a source with no detected packages, or one whose only detected package is the
+  repository root at `.` — and there the text now wins over whatever the root manifest said about
+  itself. For anything else it exits `3`, naming every package and printing the two-phase commands
+  to run instead, with the source it was given quoted into them, and listing every package the
+  proposal will need a description for — the repository root included, which is not the set the
+  refusal is about but is the set `refs add --proposal` requires.
+
+  A refusal registers no ref. The checkout it cloned stays, and is now recorded as a pending add —
+  so for the next 24 hours `doctor` reports it as one instead of offering to delete a checkout the
+  printed recovery is about to reuse, and the clone mode actually used survives into the finalize.
+  That mode cannot be recovered from the checkout afterwards: git records
+  `remote.origin.promisor` and `partialclonefilter` from the requested filter, whether or not the
+  server honoured it.
+
+  Existing entries are untouched. A description imported from a manifest before this release stays
+  exactly as it is — nothing distinguishes it from one written by hand, so nothing rewrites it. To
+  review them: `refs show <ref> --packages --json`, and `refs edit <ref> --package <name>
+description "…"` to replace one.
+
+### Security
+
+- `last_error` is documented as what it is — a failure message, usually git's own output, quoting
+  ref names the tracked repository chose — and `skills/refs/COMMANDS.md` now tells agents to read
+  it as untrusted evidence rather than as something refs vouches for.
+- `SECURITY.md` claimed refs "never reads checkout content as configuration", which was not true of
+  manifest descriptions and is still not true of package names, paths, the default branch, or a
+  `tag_format` derived from real tags. The claim is now stated as what the code enforces: refs never
+  imports a description out of a manifest. The values that do still cross are named, along with the
+  fact that being structural does not make them safe to read — a package name is whatever the
+  manifest declares.
 
 ## [0.12.0] - 2026-09-08