@kaisers-io/refs 0.8.0 → 0.8.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 +69 -1
- package/README.md +75 -69
- package/dist/refs.mjs +24 -24
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.8.2] - 2026-08-10
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- Documentation that described flows which did not work. The README's quickstart failed in both
|
|
15
|
+
of its branches, the skill's onboarding handed the user a prompt naming a zod version that was
|
|
16
|
+
never tagged, and `docs/commands.md` showed a stored url and a package count the CLI does not
|
|
17
|
+
produce. Every documented command was re-run and corrected against its real output, and the
|
|
18
|
+
`skill` check's Windows note was still describing the gap 0.8.1 closed.
|
|
19
|
+
|
|
20
|
+
- `git_transport` was documented as overridable per ref. It can be written there, since the
|
|
21
|
+
override schema is derived from the settings schema, but nothing reads it: only `refs add`
|
|
22
|
+
consults the setting, and `add` refuses a key that is already configured. Documented as inert.
|
|
23
|
+
|
|
24
|
+
### Changed
|
|
25
|
+
|
|
26
|
+
- The README and the package page are rewritten around the agent workflow, which is how refs is
|
|
27
|
+
meant to be used, with the manual CLI route kept as the side note it is.
|
|
28
|
+
|
|
29
|
+
- The package description now matches the repository's.
|
|
30
|
+
|
|
31
|
+
## [0.8.1] - 2026-08-10
|
|
32
|
+
|
|
33
|
+
### Fixed
|
|
34
|
+
|
|
35
|
+
- Locked commands could hang instead of timing out. If a lock looked abandoned but could not
|
|
36
|
+
actually be reclaimed — another process holding the steal claim, or Windows refusing to remove
|
|
37
|
+
the directory while a handle was still open inside it — the acquire loop retried without ever
|
|
38
|
+
consulting its deadline, so the ten-second acquisition budget never applied and the command spun
|
|
39
|
+
until interrupted. Both unbounded paths now honour the deadline and fail with the conflict error
|
|
40
|
+
(exit code 5) as documented.
|
|
41
|
+
|
|
42
|
+
- `refs doctor` reported a correctly installed skill as missing on native Windows. Its three
|
|
43
|
+
global search locations were derived from `$HOME`, which Windows typically leaves unset, while
|
|
44
|
+
the installer resolves `os.homedir()` — so all three silently dropped out of the search and the
|
|
45
|
+
check reported `warn`, "not found in the locations this check knows about". It now reads the
|
|
46
|
+
same home directory the installer writes to. macOS and Linux were unaffected, the two agreeing
|
|
47
|
+
there.
|
|
48
|
+
|
|
49
|
+
### Security
|
|
50
|
+
|
|
51
|
+
- Canonicalizing a git url no longer takes quadratic time. Trailing slashes were trimmed with a
|
|
52
|
+
pattern anchored at the end of the string, which backtracks through a run of slashes from every
|
|
53
|
+
position; a url carrying a long run in the middle of its path took 14 seconds to be rejected.
|
|
54
|
+
Such a url is reachable — `refs add npm:<package>` reads `repository.url` straight out of the
|
|
55
|
+
registry's packument, and nothing bounds its length — so a published package could stall the
|
|
56
|
+
command that adds it. Trimming is now linear.
|
|
57
|
+
|
|
58
|
+
- Every git invocation that receives a url now ends option parsing with `--` first. Without it,
|
|
59
|
+
git honours a url shaped like `--upload-pack=<command>` and executes it. Urls accepted through
|
|
60
|
+
`refs add` were already refused by canonicalization, but `refs sync` re-reads them from the
|
|
61
|
+
config file, where they are only checked for being non-empty — the guarantee therefore held one
|
|
62
|
+
step away from the call that depended on it. It now holds at the call.
|
|
63
|
+
|
|
64
|
+
### Changed
|
|
65
|
+
|
|
66
|
+
- Published packages carry a [provenance attestation](https://docs.npmjs.com/generating-provenance-statements).
|
|
67
|
+
npm produces these automatically for public repositories, and `0.8.0` shipped without one
|
|
68
|
+
because the repository was private at the time and the check for that fails silently. The
|
|
69
|
+
release workflow now states `--provenance` and refuses to publish if the repository is not
|
|
70
|
+
public.
|
|
71
|
+
|
|
72
|
+
- `refs init`'s skill-install hint now presents the second form as installing from a local
|
|
73
|
+
clone, rather than as a workaround for the repository's development phase. Both commands
|
|
74
|
+
are unchanged; only the wording differs.
|
|
75
|
+
|
|
10
76
|
## [0.8.0] - 2026-08-04
|
|
11
77
|
|
|
12
78
|
### Changed
|
|
@@ -343,7 +409,9 @@ trusted-publishing pipeline end to end.
|
|
|
343
409
|
installed git hooks.
|
|
344
410
|
- Agent skill (`skills/refs/`) documenting the investigate/add/maintain workflows.
|
|
345
411
|
|
|
346
|
-
[Unreleased]: https://github.com/kaisers-io/refs/compare/v0.
|
|
412
|
+
[Unreleased]: https://github.com/kaisers-io/refs/compare/v0.8.2...HEAD
|
|
413
|
+
[0.8.2]: https://github.com/kaisers-io/refs/compare/v0.8.1...v0.8.2
|
|
414
|
+
[0.8.1]: https://github.com/kaisers-io/refs/compare/v0.8.0...v0.8.1
|
|
347
415
|
[0.8.0]: https://github.com/kaisers-io/refs/compare/v0.7.0...v0.8.0
|
|
348
416
|
[0.7.0]: https://github.com/kaisers-io/refs/compare/v0.6.1...v0.7.0
|
|
349
417
|
[0.6.1]: https://github.com/kaisers-io/refs/compare/v0.6.0...v0.6.1
|
package/README.md
CHANGED
|
@@ -2,99 +2,105 @@
|
|
|
2
2
|
|
|
3
3
|
**Real source code for coding agents.**
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
minified `node_modules` bundle, never against stale training knowledge.
|
|
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.
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
packages, and from then on any agent can answer "what changed between v4.0.0 and v4.1.0"
|
|
13
|
-
or "how does zod implement codecs" by reading the actual checkout.
|
|
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.
|
|
14
11
|
|
|
15
|
-
|
|
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.
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
a checkout as a backstop, and `refs sync` self-heals a dirty checkout if something slips
|
|
21
|
-
through anyway — but this is discipline enforced by convention and tooling, not a sandbox.
|
|
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.
|
|
22
20
|
|
|
23
21
|
## Install
|
|
24
22
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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.
|
|
28
27
|
|
|
29
28
|
```bash
|
|
30
29
|
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
|
|
31
32
|
```
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
## The agent skill
|
|
35
|
+
|
|
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:
|
|
34
38
|
|
|
35
39
|
```bash
|
|
36
|
-
refs
|
|
37
|
-
refs doctor
|
|
40
|
+
npx skills add kaisers-io/refs
|
|
38
41
|
```
|
|
39
42
|
|
|
40
|
-
|
|
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.
|
|
46
|
+
|
|
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.
|
|
51
|
+
|
|
52
|
+
## Driving the CLI yourself
|
|
53
|
+
|
|
54
|
+
Useful for scripting, or for checking what the agent did.
|
|
41
55
|
|
|
42
56
|
```bash
|
|
43
|
-
|
|
44
|
-
|
|
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
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Finalize rejects a proposal that still has an empty description, which is what keeps refs
|
|
63
|
+
from inventing one for you.
|
|
45
64
|
|
|
46
|
-
|
|
47
|
-
# a reviewable proposal. Nothing is added to config yet.
|
|
48
|
-
refs add npm:zod --dry-run
|
|
65
|
+
You can skip the file when every package already carries a description in its own manifest:
|
|
49
66
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
refs add npm:zod --description "TypeScript-first schema validation" --json
|
|
67
|
+
```bash
|
|
68
|
+
refs add https://github.com/stevemao/left-pad --description "Left-pad a string." --json
|
|
53
69
|
```
|
|
54
70
|
|
|
55
|
-
Every command
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
|
62
|
-
|
|
|
63
|
-
| `refs
|
|
64
|
-
| `refs
|
|
65
|
-
| `refs
|
|
66
|
-
| `refs
|
|
67
|
-
| `refs
|
|
68
|
-
| `refs
|
|
69
|
-
| `refs
|
|
70
|
-
| `refs
|
|
71
|
-
| `refs
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
opens up when `refs` goes public.
|
|
84
|
-
|
|
85
|
-
`refs doctor`'s `skill` check looks for the installed skill in `~/.agents`, `~/.claude`,
|
|
86
|
-
`~/.codex` and the current project's `./.agents`/`./.claude`; a `warn` there means the
|
|
87
|
-
check couldn't see your skill, not that it is missing.
|
|
88
|
-
|
|
89
|
-
Source citations in the skill's final answer are markdown links (visible text relative,
|
|
90
|
-
target an absolute checkout path): they open in the Zed terminal and the Codex app
|
|
91
|
-
(verified 2026-08-03), but as of the same date the Claude app cannot open files outside
|
|
92
|
-
its working directory.
|
|
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).
|
|
91
|
+
|
|
92
|
+
## Read-only is a promise, not a sandbox
|
|
93
|
+
|
|
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.
|
|
96
|
+
|
|
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.
|
|
93
99
|
|
|
94
100
|
## Changelog
|
|
95
101
|
|
|
96
|
-
`CHANGELOG.md` ships inside this package
|
|
97
|
-
|
|
102
|
+
`CHANGELOG.md` ships inside this package, so npm's "Code" tab shows it without leaving the
|
|
103
|
+
package page.
|
|
98
104
|
|
|
99
105
|
## License
|
|
100
106
|
|