@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 +439 -0
- package/README.md +60 -71
- package/dist/refs.mjs +45 -44
- package/package.json +2 -2
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
|
|
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
|
-
|
|
10
|
-
|
|
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
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
21
|
+
## Why not just clone it?
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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
|
|
31
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
40
|
-
|
|
42
|
+
Then talk to the agent:
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
/refs add npm:effect as a ref
|
|
41
46
|
```
|
|
42
47
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
103
|
-
package page.
|
|
90
|
+
## More
|
|
104
91
|
|
|
105
|
-
|
|
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.
|