@kaisers-io/refs 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -5,7 +5,123 @@ 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.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