@kaisers-io/refs 0.16.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +433 -0
  2. package/dist/refs.mjs +45 -44
  3. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -5,6 +5,439 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.18.0] - 2026-09-20
9
+
10
+ ### Fixed
11
+
12
+ - **`refs add` derives a tag format from the version a package is at, not from how often a shape
13
+ occurs.** Detection counted: it replaced the version in every tag with `{version}` and proposed
14
+ the most frequent result. That answers "what do most of this repository's tags look like", which
15
+ is a different question from "how does this package tag its releases" and gives a different
16
+ answer whenever the package asked about is not the most-tagged one.
17
+
18
+ Measured against the repositories themselves, before this change: `refs tag effect 3.22.2` exited
19
+ `not_found`, because `Effect-TS/effect` has 63 `effect@…` tags against 668 `@effect/platform-node@…`
20
+ and the count named the sibling. `refs tag kysely 0.29.6` exited `not_found`, because
21
+ `kysely-org/kysely` tagged its older releases bare and its current ones with a `v`, and the
22
+ majority is the shape no current release carries. Worse than either, `@effect/vitest` at `0.30.0`
23
+ resolved to `@effect/platform-node@0.30.0` — a tag that exists, at which that package does not.
24
+
25
+ Now each package's own manifest version is used as an anchor. A tag that ends in exactly that
26
+ version at a digit boundary is a tag that package's release wrote, and its shape is the format:
27
+ what gets stored is still a real tag the repository published, re-expressed with `{version}` in
28
+ place of the version it carried. Where a repository offers no version to anchor on — every
29
+ repository that ships no `package.json`, and every package whose declared version was never
30
+ tagged — the count is still the answer, unchanged.
31
+
32
+ **A tag naming a different package is never an answer.** It is the mistake counting makes, and
33
+ accepting it at one version would only make it quieter. Where two spellings of the same release
34
+ both exist, the anchor yields nothing rather than one of them, and the count answers as before.
35
+
36
+ **A format that names a package goes on that package, never on the ref.** A repository-wide tag
37
+ is evidence about the repository; a tag carrying a name is evidence about what it names, and the
38
+ ref's format is what every package WITHOUT one of its own inherits. So `vercel/next.js`, which
39
+ carries a bare `1.0.0` tag from 2016 while a private benchmark package inside it declares version
40
+ `1.0.0`, gets no override for that package — and a repository whose root releases as
41
+ `root@2.0.0` while its members release under a plain `v` keeps the plain `v` on the ref, so a
42
+ member with nothing of its own still resolves. Being at the repository root is evidence about the
43
+ root, not about the members beside it.
44
+
45
+ What is left at ref level is the case `kysely` is: a root that releases under the repository-wide
46
+ shape, where counting named a shape no current release carries.
47
+
48
+ Across five repositories, 30 of 31 new per-package formats resolve the package they name and the
49
+ 31st is the benchmark package above, now not written. Everything else in every proposal is
50
+ byte-identical to before.
51
+
52
+ - **`refs add` refuses a repository whose default branch is a name git will not accept.**
53
+ `default_branch` was stored as ordinary text, and a branch name is not ordinary text. The value
54
+ is read from the repository's own `HEAD`, not typed by anyone: `git branch` will not create a
55
+ name beginning with `-`, but the ref FORMAT permits one, `update-ref` writes it, it clones
56
+ through, and `HEAD` may point at it. Such a ref was recorded without complaint and then failed at
57
+ every `refs sync` with `fatal: '--upload-pack=id' is not a valid branch name` — git objecting to
58
+ a value the caller never supplied, one command after the one that could have said so.
59
+
60
+ `refs add` and `refs edit` now refuse such a name where it enters. Nothing runs: `checkout -B` validates its
61
+ argument as a branch name before anything else, and the values that reach a verb with a
62
+ command-executing option (`--upload-pack` on `clone` and `fetch`) are fixed.
63
+
64
+ **The rule is git's own, and no stricter.** The predicate reimplements a rule that lives in git,
65
+ because a Zod refinement is synchronous while `check-ref-format` is a child process — so a test
66
+ runs the real `git check-ref-format --branch` over the generated names and asserts the two never
67
+ disagree. That test caught the first attempt: it was written with `\p{Cc}`, and git accepts all
68
+ 32 C1 controls (U+0080-U+009F) that class rejects.
69
+
70
+ **The stored schema stays permissive, deliberately.** `readConfig` parses the whole document, and
71
+ `edit` and `remove` both read it before they can change anything — so refusing an old entry would
72
+ turn one unusable ref into an unusable home, with no way left to repair it, and would take every
73
+ unrelated ref in the file with it. The entry points refuse a new bad value instead; an old one
74
+ stays reachable so it can be removed.
75
+
76
+ ### Added
77
+
78
+ - **`refs doctor` reports a refs home whose access modes are too open.** `refs init` creates and
79
+ repairs everything refs owns with explicit modes — `0700` directories, `0600` files — but `init`
80
+ is run once. A home created by an older refs under a permissive umask keeps whatever it got
81
+ (measured: `umask 002` produced `drwxrwxr-x`, `umask 000` produced `drwxrwxrwx`), and somebody
82
+ who upgrades and only ever runs `sync` was never told. A fix nobody is told about is not one.
83
+
84
+ The check names each entry it found and the mode it has, and `hooks/` in particular: that is the
85
+ directory every managed checkout points `core.hooksPath` at, and git resolves hook NAMES against
86
+ it, so a second local principal able to write there gets code executed as the refs user during an
87
+ ordinary `refs sync`. The remedy it prints is `refs init`, which already sets every one of them
88
+ and needs no path interpolated into a command.
89
+
90
+ Group and other are reported together rather than judged apart: a shared group may be deliberate,
91
+ and refs cannot read that policy. On Windows the check reports that it does not apply, because the
92
+ mode bits there do not say who may write.
93
+
94
+ Two things it is careful not to claim. A path that could not be INSPECTED is reported as such
95
+ rather than counted as nothing found — an `ELOOP` or an `EACCES` is a failure to look, and the
96
+ quiet answer would otherwise assert something it had not established. And `refs init` is offered
97
+ only where it would act: it deliberately does not chmod a symlinked directory, since `chmod`
98
+ follows the link and the target's mode is its own owner's business, so a symlinked `sources/`
99
+ pointing somewhere open is reported with "fix it where it points" instead of a repair that would
100
+ leave the finding standing. The quiet message says "no group or other permission bits" rather than
101
+ "reachable only by its owner", which mode bits alone do not establish.
102
+
103
+ ### Added
104
+
105
+ - **Every drift finding in `refs doctor --json` carries its repair commands, already quoted.**
106
+ `register`, `decline`, `repoint` and `unregister` sit beside the raw `name` and `path`, so
107
+ nothing has to assemble a command out of values a tracked repository chose. That mattered most
108
+ where the human output gives no command at all: once a directory holds enough unregistered
109
+ packages the per-package line collapses to a count, which is exactly the large-monorepo case an
110
+ agent is routed to `findings` for. A finding that can offer no command honestly carries none.
111
+
112
+ Verified by taking three such commands out of `--json` and running them **verbatim** through a
113
+ shell against a real checkout: a package directory with a space, a name containing `$(id)` and a
114
+ name containing a single quote were all declined exactly, with nothing substituted.
115
+
116
+ ### Changed
117
+
118
+ - **The skill states the quoting rule the CLI has always applied.** `COMMANDS.md`, `VERSIONS.md`,
119
+ `INVESTIGATE.md` and `MAINTAIN.md` gave agent-facing templates with no quoting around values
120
+ refs reports — a package name comes from a tracked repository's own manifest, a path from its
121
+ directory layout, and a tag from its tag list. refs checks that those are true, not that they
122
+ are safe to paste. The rule is now written down once: run the command refs printed; if you must
123
+ build one, single-quote every interpolated value and close-and-reopen the quote around any single
124
+ quote in it. Every RUNNABLE line in those documents follows it, and the command synopses — which
125
+ show a verb's grammar rather than a line to paste — say so explicitly instead of being quoted as
126
+ though they were.
127
+
128
+ Two corrections to what those documents asserted. `git tag -l '<prefix>…'` needs a `--` before
129
+ the pattern: a prefix beginning with `-` otherwise fails with
130
+ `options '-v' and '-l' cannot be used together`, and the prefix comes from the repository's own
131
+ tags. And git does not accept every metacharacter in a tag name — a semicolon, a single quote,
132
+ backticks and `$(…)` it creates and lists back, but `git check-ref-format` refuses a space or a
133
+ control character.
134
+
135
+ ### Fixed
136
+
137
+ - **A checkout's own git hooks can no longer run during the clone that creates it.** `refs` points
138
+ every managed checkout's `core.hooksPath` at its own hooks directory so hooks inside a checkout
139
+ never run, but it set that only _after_ `git clone` returned. The clone's own checkout was
140
+ therefore governed by whatever git config the invoking user already had — and `core.hooksPath`
141
+ may be relative, in which case git resolves it inside the tree being cloned. A user with, say,
142
+ `core.hooksPath = .githooks` set globally would run an upstream-tracked `.githooks/post-checkout`
143
+ during `refs add`, before the proposal that add exists to put in front of a human. The managed
144
+ path is now passed on the clone invocation itself, which git applies after initializing the new
145
+ repository and before fetching and checking out.
146
+
147
+ - **A git url carrying an ASCII control character is refused.** The url canonicalizer returns the raw
148
+ input as the clone url while deriving the stored ref key from the parsed one, so any character the
149
+ URL parser silently removes can make those two name different repositories — the reason backslashes
150
+ and percent escapes were already rejected. Tab, line feed and carriage return are a third door: the
151
+ parser strips them _before_ it resolves `..`, so `.<TAB>.` reads as three characters to the raw
152
+ check and as `..` to the parser. Git clones that literal path when it exists, so the result was a
153
+ checkout whose recorded identity described a different repository. A sweep of every code point up
154
+ to U+00FF plus the zero-width and bidi suspects found no fourth character with the same effect.
155
+
156
+ - **A syntax error in `config.toml` no longer reports the surrounding lines.** The TOML parser's
157
+ message ends in a source excerpt — the offending line plus the nonempty lines either side of it —
158
+ and refs forwarded it verbatim. A syntax error next to a ref's `url` therefore reported that url,
159
+ credentials and all, through an ordinary command failure and before any schema or url handling
160
+ ran, so none of the redaction applied elsewhere was reached. The fault and its line and column are
161
+ still reported; the source is not.
162
+
163
+ ### Changed
164
+
165
+ - **`refs show` redacts a credential in the ref url.** The url field is allowed to hold one: a bare
166
+ ssh username is legal by design, and the read path accepts any non-empty string, so a hand-edited
167
+ config can carry `user:pass@` too. `--json` is the agent contract, so that output leaves the
168
+ terminal. The conventional `git@host` stays readable — redacting it would mark every ordinary ssh
169
+ ref as credential-bearing while telling the reader nothing — but any other userinfo is replaced
170
+ with `<redacted>@`, and the host and path are kept. The decision is made on the parsed url rather
171
+ than by matching the string, and a value that can be neither parsed nor recognised as the scp form
172
+ is redacted in full rather than printed.
173
+
174
+ ### Changed
175
+
176
+ - **Text that cannot be written back is refused before it becomes configuration.** A lone surrogate
177
+ is a valid JavaScript string with no UTF-8 encoding: the TOML serializer writes it as a `\ud800`
178
+ escape and the parser then rejects that escape, so accepting one produced a home refs itself could
179
+ no longer read — an unreadable configuration rather than a bad entry. The route in was JSON, which
180
+ has an escape for a lone surrogate where TOML has none, so a `refs add --proposal` file could
181
+ carry one into a package name, a description, the url, the default branch, a package path or a tag
182
+ format. All of them now require text that round-trips, and the refusal names the field.
183
+
184
+ Nothing narrows by length. The config is validated on every read, so a length bound would make an
185
+ existing home unreadable, and unfixable through a CLI that cannot load it, over a value that
186
+ round-trips perfectly well.
187
+
188
+ Writing the config now proves the document can be read back instead of assuming it. `meta` is
189
+ deliberately permissive — a key written by a future CLI passes through untouched — so no field
190
+ schema can cover it, and a schema cannot keep the guarantee when a field is added later. Both
191
+ `refs migrate` and every ordinary write go through the same check, which costs one parse: 0.4 ms
192
+ on a 32 KB config holding 100 refs.
193
+
194
+ `refs doctor` and `refs sync` no longer offer a `--decline` command for a name the configuration
195
+ cannot store. The report validated the path alone, so it could print a command the configuration
196
+ then refused. It now asks the shape that would be stored. A package called `constructor` stays
197
+ declinable, which is the documented difference between declining and registering.
198
+
199
+ - **A tracked repository can no longer add a line to refs' human output.** A workspace member's
200
+ name is taken from its manifest and printed at the head of every drift finding. A newline in that
201
+ name produced a second line on stdout that was byte-for-byte indistinguishable from one refs
202
+ wrote — and the obvious payload is a forged `To register it:` clause, because a genuine finding
203
+ ends in exactly that shape. Every human line now goes through one neutralisation on its way out:
204
+ C0/C1 control characters, the line terminators among them, are replaced with `?`. The name still
205
+ reaches the reader; what it can no longer be is a line. Printable text outside ASCII is untouched,
206
+ so nothing refs writes itself changes.
207
+
208
+ An error message keeps its own line breaks — `refs add`'s two-phase instructions put each command
209
+ on its own line, and `--verbose` appends a stack trace — so there the untrusted values are
210
+ neutralised where they are composed INTO that layout instead. The package names that message
211
+ lists come from the same manifests, and before this they could add a line of their own.
212
+
213
+ **And no command is printed for a value one cannot carry.** Neutralising a line for display would
214
+ otherwise rewrite the command inside it: `--package='a<LF>b'` becomes `--package='a?b'`, which
215
+ names a different package. This is not a quoting problem — single quotes carry the character
216
+ perfectly well, and a shell would accept the result; what the command stops being is one
217
+ pasteable line that means what it says. Every value a printed command interpolates is subject to
218
+ it: the package name, the path, the ref key, and the filesystem paths in the `rm -rf` and `rmdir`
219
+ suggestions, where naming the wrong target cannot be undone. The builders in `shell-quote.ts`
220
+ return nothing at all for such a value, so a command producer cannot forget the check, and the
221
+ finding is reported without a command and with a pointer to `--json`, which carries the value
222
+ exactly.
223
+
224
+ The description placeholder in the register command is single-quoted rather than double-quoted:
225
+ in double quotes a `$(…)` a reader substitutes for it would be expanded by their own shell before
226
+ refs ever saw it.
227
+
228
+ The `--json` envelope's parsed identity was never affected, because `JSON.stringify` escapes
229
+ U+0000–U+001F, and it is unchanged.
230
+
231
+ - **`refs resolve` no longer answers whether a path outside the package exists.** A package's
232
+ `exports` targets are third-party content, and a target could name any absolute path: `join`
233
+ clamps `..` at the filesystem root, so depth was not something the manifest had to guess. The
234
+ probe then reported `unverifiable` when something was there and `absent` when nothing was —
235
+ a clean two-valued answer about a path the package has nothing to do with, with each `exports`
236
+ subpath carrying its own, so one manifest batched many probes into a single reply.
237
+
238
+ Nothing was ever read, and the containment rule that refuses to hand back a real path outside the
239
+ checkout always held. What crossed was the classification of the refusal. An absence is now
240
+ reported only where containment can be established, which also covers the shape a `..` guard
241
+ cannot see — a symlink inside the package pointing out of it, in a target with no `..` at all.
242
+ An entry point that is genuinely missing inside the package still reports `absent`, however
243
+ deeply nested.
244
+
245
+ - **`refs doctor` looks in the hooks directory before reporting the checkouts guarded.** Every
246
+ managed checkout is stamped with `core.hooksPath` pointing at one refs-owned directory, and git
247
+ resolves hook NAMES against that directory — not against the two names refs installed there. The
248
+ check asked only whether `pre-commit` and `pre-push` were present and executable, so it reported
249
+ the guard intact while the directory held something else. Measured on git 2.54: a `post-checkout`
250
+ placed there runs during `refs sync`, and `doctor` still answered `ok`.
251
+
252
+ The directory is now enumerated, and anything refs did not install makes the check fail, naming
253
+ every entry and printing one removal that clears all of them. Every failing fact is reported at
254
+ once rather than one per run. A hooks directory that is not there at all says `run: refs init`,
255
+ which is the remedy that fixes it.
256
+
257
+ What the check does not claim is that every entry runs — a non-executable file does not. The
258
+ finding is that the directory git resolves hook names against holds something refs cannot
259
+ account for.
260
+
261
+ - **`refs doctor` no longer quotes a skill's declared CLI version back when it cannot read it.**
262
+ Two of the five places the check looks for a `SKILL.md` are rooted at the working directory —
263
+ for an agent session, whatever repository it happens to be in — and the frontmatter scan accepts
264
+ any quote-free, whitespace-free token of any length. A repository could therefore put
265
+ attacker-chosen prose, unbounded, into the `--json` detail that the bundled skill tells the agent
266
+ to relay verbatim to a human. Measured: a 4208-character detail carrying the planted text.
267
+
268
+ A value the version comparison cannot interpret now produces one short line naming both remedies
269
+ and nothing from the file. A value it CAN interpret is bounded too: version components may be
270
+ arbitrarily long, so four thousand digits compared fine and were quoted in full.
271
+
272
+ ### Changed
273
+
274
+ - **refs chooses the access mode of everything it owns instead of inheriting it.** Every directory
275
+ and file under `REFS_HOME` was created with no mode argument, so which principals could read or
276
+ write them was decided by whatever umask the invoking process happened to carry. Measured:
277
+ `refs init` under `umask 002` left the hooks directory group-writable, and under `umask 000`
278
+ world-writable. That directory is the one every managed checkout points `core.hooksPath` at, and
279
+ git resolves hook names against it — so anyone able to write there gets code run as the refs user
280
+ during an ordinary `refs sync`. Under the default `umask 022` none of that applies, which is
281
+ exactly the problem: refs neither chose nor recorded which of those it got.
282
+
283
+ Directories are now `0700` and files `0600`. A refs home is a single-user directory, and this
284
+ makes that explicit rather than incidental.
285
+
286
+ `refs init` also applies them to a home that already exists, because `mkdir` sets a mode only on
287
+ what it creates and `init` is the command that repairs a home. The repair removes group and other
288
+ access and restores the owner's own; a directory that is a symlink is left alone, since `chmod`
289
+ follows links and the mode of a directory outside the home is its owner's business. `config.toml`
290
+ is repaired too — nothing rewrites it when the CLI version already matches, so it would otherwise
291
+ keep an old mode forever. Checkouts under `sources/` are not touched: the directory above them is
292
+ what controls access to them.
293
+
294
+ A guard hook now gets its mode before it is published rather than after, so it is never briefly
295
+ present and not executable.
296
+
297
+ - **A file refs cannot parse is no longer quoted back.** Node's `JSON.parse` embeds the offending
298
+ input in its message for some malformations and not others, and refs forwarded that message.
299
+ Measured: a `package.json` carrying a bare token produced the reason
300
+ `SyntaxError: Unexpected token 'L', ...","token":LEAKED_abc"... is not valid JSON` in
301
+ `refs resolve --json` — a manifest is checkout content, so that put third-party bytes into the
302
+ output an agent parses. The same applied to `refs add --proposal`, where the document is one
303
+ someone filled in by hand, quite possibly with a credentialed url in it.
304
+
305
+ Both now report a fixed reason. The errno branch is untouched: an `ENOENT` or `EISDIR` is refs'
306
+ own fact rather than a parser's. The position `JSON.parse` sometimes carries is given up, which
307
+ is the deliberate trade — Node exposes it nowhere else, and which malformations carry the input
308
+ along with it is a property of the Node version rather than anything refs decides.
309
+
310
+ ### Changed
311
+
312
+ - **The guard in front of `refs sync`'s destructive step asks the same question as its three
313
+ siblings.** Every managed checkout is stamped with `core.hooksPath` pointing at this home's hooks
314
+ directory, and `add`, `doctor` and `resolve` all check for exactly that. The guard `sync` applies
315
+ immediately before `checkout -B`, `reset --hard` and `clean -fd` accepted any non-empty value —
316
+ weaker than the other three and weaker than its own comment, which described the strict check.
317
+
318
+ No sync behaved differently: that guard's one caller already ran the strict check on the same
319
+ directory immediately before it. It is closed because the weak predicate becomes the operative
320
+ one as soon as a second caller appears, and a comment describing the strict check is an
321
+ invitation to add that caller.
322
+
323
+ - **A command whose output hit the stream cap is treated as incomplete, everywhere it is read.**
324
+ The runner publishes `stdoutTruncated` for exactly this, and its own contract says a caller
325
+ parsing that output must treat it as incomplete — but no production code read the flag. The one
326
+ place that reacted to truncation matched the literal text `refs: stdout exceeded` in stderr,
327
+ which worked only while that note kept its wording and kept being routed there.
328
+
329
+ Two readers of git history accepted a cut stream as a complete answer, and that direction is not
330
+ quiet: the cut keeps the FIRST bytes, so a smaller answer looks like a real one. A
331
+ `pnpm-workspace.yaml` cut mid-file still parses — as a declaration listing fewer directories than
332
+ it has — so a narrowing reads as a widening and a package that was always there is announced as
333
+ newly arrived. A cut list of changed paths loses the deletion at the end of it, which is where a
334
+ package's previous name comes from, with the same result. Both now say they could not look.
335
+
336
+ A run that both hit the cap and then timed out publishes both facts; it previously reported only
337
+ the timeout.
338
+
339
+ - **A package name with no entry of its own is no longer answered for.** Four read paths looked a
340
+ name up with plain bracket access, so a name absent from the record resolved up the prototype
341
+ chain: `packages['toString']` answered with `Object.prototype.toString`, which is truthy and
342
+ therefore looked registered. Measured with the built CLI: `refs tag <ref> 1.2.3 --package
343
+ toString` returned a tag, silently using the ref's own format for a package the configuration
344
+ does not have, and `refs resolve toString --ref <ref>` crashed.
345
+
346
+ All four now ask whether the record has its own entry under that name, as their siblings already
347
+ did. This is not about forbidden names — `toString` and `valueOf` are perfectly legal package
348
+ keys, and a package really registered under one still resolves, with its own tag format.
349
+
350
+ - **`refs migrate` no longer reports a config up to date without validating it.** When the schema
351
+ version already matched, it re-serialised the file with a fresh `cli_version` and answered
352
+ `noop` — rendered as "config up to date" — having checked nothing about the contents. Measured:
353
+ a `clone_mode` of `42` was stamped and reported current, while every reader then refused the
354
+ file. The document is now validated before both the write and the answer, and nothing is written
355
+ when it fails, so the file the user still has is the one they started with.
356
+
357
+ What is validated is the STAMPED document. A config whose `meta.cli_version` is missing fails
358
+ validation as it stands and passes once stamped, and repairing exactly that is what the stamp is
359
+ for — checking the input instead would have withdrawn a repair refs has always performed.
360
+
361
+ `refs init` shares this path, so it now refuses a config in that state rather than reporting the
362
+ home ready. That is the same claim being made honestly, but it is a behaviour change: `init`
363
+ previously succeeded and left the problem for `doctor` to find.
364
+
365
+ ### Changed
366
+
367
+ - **Small correctness corrections found while reviewing adjacent code.**
368
+ - `refs edit --decline` reports a bad path as `→ at path` instead of naming its position inside
369
+ the whole document. Both checks always held — `writeConfig` re-validates everything — but this
370
+ is the earlier and better-located of the two, as its siblings already have.
371
+ - A package name is checked against the same segment rule `zRefKey` and `zPackagePath` use,
372
+ rather than a second, narrower copy. The local one admitted `:` and `%`, which core rejects and
373
+ documents: on Windows a config-derived name like `C:foo` addressed an alternate data stream
374
+ rather than a directory. No legitimate npm name is affected.
375
+ - `--project` distinguishes "cannot be read" from "does not exist". It decided that by matching
376
+ refs' own wording in a caught error's message, so an EACCES or an ELOOP was reported as an
377
+ absence about a directory that is there.
378
+ - `refs add npm:<pkg>` has a request deadline, and reports it as one. Without a deadline, a
379
+ registry or an intercepting proxy that trickles a response held the command open indefinitely;
380
+ and a deadline that expires mid-body makes the response unreadable, which would otherwise have
381
+ been reported as the registry sending invalid JSON.
382
+ - The atomic write creates its temporary file exclusively and refuses to follow a symlink at that
383
+ path. The random name already made planting one impractical; this removes the argument.
384
+
385
+ ### Added
386
+
387
+ - **`refs doctor` reports git configuration that git itself runs.** `core.hooksPath` is the
388
+ boundary refs pins, and it governs hooks-_directory_ discovery — which is what stops a hook file
389
+ inside a checkout from running. Other mechanisms do not route through it. Measured on git 2.54
390
+ against a real clone with that path correctly set: a configured hook
391
+ (`[hook "x"] event = post-checkout; command = ./script.sh`) ran the **checkout's** copy of that
392
+ script during `refs add` and `refs sync`, and an attribute-selected filter
393
+ (`[filter "y"] smudge = ./script.sh`) ran it during the checkout `sync` performs.
394
+ `core.fsmonitor`'s command form is a third, run with the worktree as its working directory.
395
+
396
+ Each needs a definition already in the invoking user's own git configuration — a tracked
397
+ repository cannot create one, and its `.gitattributes` can only choose when an existing filter
398
+ applies. So the new `git-exec-surfaces` check reports the condition rather than refs discarding
399
+ the ambient configuration, which also carries the credential helpers and proxies a private clone
400
+ needs.
401
+
402
+ It reports **presence, not safety**: whether a command reaches a checkout's content depends on
403
+ the command, and `/bin/sh ./script.sh` has an absolute program and runs the checkout's script
404
+ anyway. `SECURITY.md` states the boundary, these exclusions, and what the check does not decide.
405
+
406
+ ### Changed
407
+
408
+ - **The release workflow refuses a version that is not newer than the published one, and its
409
+ publish job declares a GitHub Environment.** A `v*` tag push is the only trigger, and GitHub
410
+ resolves a push-triggered workflow from the pushed ref — so every guard authorizing a release is
411
+ content of the tagged tree, and a tag whose tree deletes one is never subjected to it. An
412
+ Environment is the one gate that can live in repository settings instead, and npm's trusted
413
+ publisher can bind it alongside the repository and the workflow filename, which is what makes
414
+ deleting the key from a tag's tree fail rather than pass.
415
+
416
+ Both halves have to be configured outside the repository, and `CONTRIBUTING.md` now says what
417
+ they are, what a deployment tag rule does not achieve on its own, and how to check each
418
+ separately — a failed publish proves nothing by itself.
419
+
420
+ The version guard fails closed: a registry lookup that errors stops the release rather than
421
+ reading as "nothing published yet", and anything that is not a plain `x.y.z` is refused rather
422
+ than ordered.
423
+
424
+ ## [0.17.0] - 2026-09-13
425
+
426
+ ### Added
427
+
428
+ - **`refs doctor` and `refs sync` show what they are doing while they work.** Both used to print
429
+ nothing until they were done: about 4 and 9 seconds on a home with 8 refs, long enough to look
430
+ stuck. A terminal now gets a one-line spinner on stderr naming the running step. For `doctor`
431
+ that is each check (`Checking SSH authentication`), for `sync` how many refs are done
432
+ (`Syncing refs: 3/8 done`). The line is cleared before any
433
+ output, so what the commands print, their `--json` envelopes and their exit codes are unchanged.
434
+
435
+ Agents never see it. It is off under `--json` whatever the terminal is, and off when stderr is
436
+ not a terminal, with `TERM=dumb`, in CI, and with the new `REFS_PROGRESS=0`. It adds no
437
+ dependency. A spinner library would add 6 to 46 KB to the bundle, and the small ones install
438
+ SIGINT handlers that call `process.exit`, cutting across how refs stops its git processes on
439
+ Ctrl-C. The cursor stays visible, so an interrupted run cannot leave it hidden.
440
+
8
441
  ## [0.16.1] - 2026-09-13
9
442
 
10
443
  ### Changed