@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 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 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.