@kaisers-io/refs 0.17.0 → 0.18.1

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