@kaisers-io/refs 0.18.0 → 0.18.2
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 +50 -4
- package/README.md +60 -71
- package/dist/refs.mjs +204 -45
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,52 @@ 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.2] - 2026-10-13
|
|
9
|
+
|
|
10
|
+
### Security
|
|
11
|
+
|
|
12
|
+
- **Bundled dependencies moved past known denial-of-service advisories.** `smol-toml` 1.8.0 →
|
|
13
|
+
1.9.1 fixes quadratic-time parsing ([GHSA-r4xh-jqrq-34v2](https://github.com/advisories/GHSA-r4xh-jqrq-34v2));
|
|
14
|
+
refs parses `config.toml` with it. `brace-expansion` 5.0.9 → 5.0.12, reached through
|
|
15
|
+
`minimatch`, fixes unbounded recursion and quadratic expansion
|
|
16
|
+
([GHSA-qhr7-859c-m2p7](https://github.com/advisories/GHSA-qhr7-859c-m2p7),
|
|
17
|
+
[GHSA-6j4f-fj2g-mc7p](https://github.com/advisories/GHSA-6j4f-fj2g-mc7p),
|
|
18
|
+
[GHSA-q2hr-2g5m-vwhr](https://github.com/advisories/GHSA-q2hr-2g5m-vwhr)); refs matches
|
|
19
|
+
workspace patterns read from a checkout with it, and a checkout is third-party content. `zod`
|
|
20
|
+
4.6.2 → 4.6.7. All three are bundled into the published CLI.
|
|
21
|
+
|
|
22
|
+
### Changed
|
|
23
|
+
|
|
24
|
+
- **An invalid `config.toml` is reported in the new parser's words.** The message still carries
|
|
25
|
+
only the fault and its position, never a line of the file, but the fault is named differently
|
|
26
|
+
and the column points at the offending character rather than the start of the line.
|
|
27
|
+
- **Development moved to pnpm 12 and Node 24.21.** The development toolchain moved too: `oxlint`, `oxfmt`,
|
|
28
|
+
`vitest`, `vite`, `tsdown`, and `@types/node` within the 24 line. The published CLI has no pnpm
|
|
29
|
+
requirement of its own.
|
|
30
|
+
|
|
31
|
+
## [0.18.1] - 2026-09-20
|
|
32
|
+
|
|
33
|
+
### Changed
|
|
34
|
+
|
|
35
|
+
- **The README describes what `refs` is for, rather than one thing it does.** It read as a tool for
|
|
36
|
+
looking up a library and diffing two releases. That is one question of several, and the ones it
|
|
37
|
+
left out are the ones people reach for it with: a change you just made and which of your own
|
|
38
|
+
repositories it breaks, source no model has been trained on, a flow that crosses four services.
|
|
39
|
+
Every example is now a prompt you say to an agent, because that is how the tool is used; the CLI
|
|
40
|
+
is shown where typing one is quicker.
|
|
41
|
+
|
|
42
|
+
Two documents are new. [`docs/investigations.md`](https://github.com/kaisers-io/refs/blob/main/docs/investigations.md)
|
|
43
|
+
works six questions through and ends each one with what the answer leaves open, which is the part
|
|
44
|
+
a worked example usually omits. [`docs/install.md`](https://github.com/kaisers-io/refs/blob/main/docs/install.md)
|
|
45
|
+
covers installing the skill without `skills add`, and the platform notes.
|
|
46
|
+
|
|
47
|
+
Seven claims that did not hold were corrected in the process: reading a version from a lockfile
|
|
48
|
+
(refs answers that itself, and says when it cannot), "no per-file request over the network" (a
|
|
49
|
+
blobless checkout fetches history on demand), a file link presented as always clickable (it
|
|
50
|
+
depends on the terminal), `refs sync` described as fetching only what has gone stale (it fetches
|
|
51
|
+
every ref; `--stale-only` is the flag), and three more. The code is unchanged: this release is
|
|
52
|
+
the package page and the documentation that ships beside it.
|
|
53
|
+
|
|
8
54
|
## [0.18.0] - 2026-09-20
|
|
9
55
|
|
|
10
56
|
### Fixed
|
|
@@ -340,7 +386,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
340
386
|
name up with plain bracket access, so a name absent from the record resolved up the prototype
|
|
341
387
|
chain: `packages['toString']` answered with `Object.prototype.toString`, which is truthy and
|
|
342
388
|
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
|
|
389
|
+
toString` returned a tag, silently using the ref's own format for a package the configuration
|
|
344
390
|
does not have, and `refs resolve toString --ref <ref>` crashed.
|
|
345
391
|
|
|
346
392
|
All four now ask whether the record has its own entry under that name, as their siblings already
|
|
@@ -789,7 +835,7 @@ can contain one — TOML has no escape for it — so this only affects a hand-bu
|
|
|
789
835
|
Existing entries are untouched. A description imported from a manifest before this release stays
|
|
790
836
|
exactly as it is — nothing distinguishes it from one written by hand, so nothing rewrites it. To
|
|
791
837
|
review them: `refs show <ref> --packages --json`, and `refs edit <ref> --package <name>
|
|
792
|
-
description "…"` to replace one.
|
|
838
|
+
description "…"` to replace one.
|
|
793
839
|
|
|
794
840
|
### Security
|
|
795
841
|
|
|
@@ -1140,7 +1186,7 @@ long it has been there.
|
|
|
1140
1186
|
`checkout.status`, which answers the question `missing` was often assumed to.
|
|
1141
1187
|
|
|
1142
1188
|
- **The "lock is held" error now says who holds it and for how long.** It used to read `lock <name>
|
|
1143
|
-
is held — another refs process is running`, which left no way to tell a running `sync` from
|
|
1189
|
+
is held — another refs process is running`, which left no way to tell a running `sync` from
|
|
1144
1190
|
something that crashed 90 seconds ago. It now names the recorded pid, whether that pid is still
|
|
1145
1191
|
present, how long the lock has been held, and when it becomes reclaimable.
|
|
1146
1192
|
|
|
@@ -1667,7 +1713,7 @@ is held — another refs process is running`, which left no way to tell a runnin
|
|
|
1667
1713
|
### Added
|
|
1668
1714
|
|
|
1669
1715
|
- `refs add` now emits progress lines on stderr while it works (`refs: resolving npm
|
|
1670
|
-
package '…'…`, `refs: cloning …`, `refs: detecting workspace packages…`) in both
|
|
1716
|
+
package '…'…`, `refs: cloning …`, `refs: detecting workspace packages…`) in both
|
|
1671
1717
|
human and `--json` mode, so long clones no longer look like a hang. stdout is
|
|
1672
1718
|
unaffected and stays exactly the parseable envelope in `--json` mode.
|
|
1673
1719
|
|
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.
|