@kaisers-io/refs 0.18.1 → 0.19.0
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 +195 -4
- package/dist/refs.mjs +184 -48
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,197 @@ 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.19.0] - 2026-11-07
|
|
9
|
+
|
|
10
|
+
### Security
|
|
11
|
+
|
|
12
|
+
- **`SECURITY.md` now describes the git processes refs starts.** A new section states which
|
|
13
|
+
inherited git variables refs removes and which it keeps (command-scope configuration, and
|
|
14
|
+
settings such as `GIT_SSH_COMMAND`), which commands pin refs' hooks directory above an inherited
|
|
15
|
+
`core.hooksPath` and which do not, how the time limit ends git and the processes it started and
|
|
16
|
+
where that cannot be confirmed, when a failed clone is removed and when it is kept but unmarked,
|
|
17
|
+
how refs' `core.fsmonitor` and configured-hook overrides work on git 2.54 and later and what they
|
|
18
|
+
cost, what still runs (content filters, during `refs add`'s clone too), and which git versions
|
|
19
|
+
the controls were measured on. refs enforces no minimum git version, and the section says so. The
|
|
20
|
+
section describes the controls of #249, #251 and #252 and holds only for a release that contains
|
|
21
|
+
them (#217).
|
|
22
|
+
|
|
23
|
+
- **A program inside a checkout can no longer run in place of git.** refs starts git with its
|
|
24
|
+
working directory inside a checkout, and on Windows the process spawn looks in that directory
|
|
25
|
+
before `PATH`, so a `git.exe` or `git.com` tracked at a reference's root ran on the next
|
|
26
|
+
`refs sync` or `refs doctor`. On every platform, an empty or relative `PATH` entry pointed at the
|
|
27
|
+
same directory. refs now resolves every program it starts through absolute `PATH` entries only
|
|
28
|
+
and starts that absolute path; a program found nowhere else fails as not found.
|
|
29
|
+
|
|
30
|
+
- **refs' own git no longer runs a configured fsmonitor command or configured hooks.** Every git
|
|
31
|
+
process refs starts now carries `-c core.fsmonitor=` and `-c hook.<event>.enabled=false` for
|
|
32
|
+
each event refs causes (`post-checkout`, `post-index-change`, `pre-auto-gc`,
|
|
33
|
+
`reference-transaction`). Both mechanisms come from the user's own git configuration and both
|
|
34
|
+
could run a script the checkout tracks, which `core.hooksPath` does not prevent. The fsmonitor
|
|
35
|
+
override uses the empty value because git 2.35.1 and older would run `false` as a program. The
|
|
36
|
+
event switch exists from git 2.55, but there a hook label named after an event turns it into
|
|
37
|
+
that label's switch and the event's other hooks still run; git 2.54 can disable a configured
|
|
38
|
+
hook only by its label. So on git 2.54 and later refs also reads every label from the
|
|
39
|
+
configuration and all of its includes, conditional ones included whether or not they apply yet,
|
|
40
|
+
and disables each one. When it cannot read the whole include graph, it refuses to start git
|
|
41
|
+
instead. It reads them once per refs process and again only when a file it read changes, so a
|
|
42
|
+
sync starts a handful of extra git processes rather than several per git command. Content
|
|
43
|
+
filters stay enabled, because turning one off changes what a checkout contains (#194).
|
|
44
|
+
|
|
45
|
+
- **Development installs refuse dependency versions published with weaker trust evidence.**
|
|
46
|
+
`pnpm-workspace.yaml` sets pnpm's `trustPolicy: no-downgrade`: a version published without the
|
|
47
|
+
trusted-publisher or provenance evidence an earlier release of the same package had now fails
|
|
48
|
+
`pnpm install`, including when it is already in the lockfile. Such a downgrade does not prove a
|
|
49
|
+
compromise, but it is what a publish with a leaked token would look like, so the version is held
|
|
50
|
+
back until someone reviews it. A test fails if the setting is removed or weakened, while a
|
|
51
|
+
reviewed exception pinned to an exact version stays possible. The release build installs through
|
|
52
|
+
the same policy, so this also covers the libraries bundled into the published CLI; the CLI's
|
|
53
|
+
runtime behaviour is unchanged.
|
|
54
|
+
|
|
55
|
+
- **Every package in the lockfile is audited for advisories again.** Since the move to pnpm 12 the
|
|
56
|
+
lockfile holds two YAML documents, and GitHub's dependency graph sees only part of it: the
|
|
57
|
+
transitive packages bundled into the CLI, such as `brace-expansion` via `minimatch`, dropped out of
|
|
58
|
+
Dependabot alerts. A new CI workflow runs `pnpm audit` over the whole lockfile on every pull
|
|
59
|
+
request and weekly. It fails when the audit reports fewer packages than the lockfile holds
|
|
60
|
+
registry packages, so a scanner that reads one document cannot pass as a clean result; this
|
|
61
|
+
compares counts, a plausibility floor, and does not prove that each individual package was
|
|
62
|
+
audited. A report it cannot fully read, such as an advisory with an unknown severity, fails as an
|
|
63
|
+
incomplete audit rather than passing. Advisories listed in pnpm's `auditConfig.ignoreGhsas` are
|
|
64
|
+
honoured.
|
|
65
|
+
|
|
66
|
+
### Added
|
|
67
|
+
|
|
68
|
+
- **`REFS_SYNC_CONCURRENCY` sets how many refs `refs sync` works on at once.** The default is
|
|
69
|
+
still four. A whole number is clamped to 1–16, since every slot is a connection to a forge; any
|
|
70
|
+
other value is ignored.
|
|
71
|
+
|
|
72
|
+
- **The skill installs as a Codex plugin.** `codex plugin marketplace add kaisers-io/refs` and
|
|
73
|
+
`codex plugin add refs@kaisers-io` install the same skill `npx skills add` does, from the same
|
|
74
|
+
directory, with nothing else from the repository. In Codex it is `$refs:refs`. The plugin does
|
|
75
|
+
not install the CLI. `npx skills add`, the manual copy and the npm CLI work as before.
|
|
76
|
+
|
|
77
|
+
- **`refs doctor` recognises a Codex plugin install.** The `skill` check looks in Codex's plugin
|
|
78
|
+
cache, so a plugin-only install no longer reads as missing, and a stale plugin is told to run
|
|
79
|
+
`codex plugin marketplace upgrade` rather than `npx skills add`, which would add a second copy.
|
|
80
|
+
The skill's own version gate gives the plugin copy the same advice. Doctor reads the copy
|
|
81
|
+
Codex loads, from `refs@kaisers-io` only, and says that it does not check whether the plugin
|
|
82
|
+
is enabled.
|
|
83
|
+
|
|
84
|
+
### Changed
|
|
85
|
+
|
|
86
|
+
- **`refs add --dry-run` warns about what git will run before it clones.** A `warnings` entry
|
|
87
|
+
beginning `git-exec-surfaces:` repeats `refs doctor`'s check of that name: content filters, and
|
|
88
|
+
any configured hook refs did not disable. `refs doctor` no longer reports an fsmonitor command
|
|
89
|
+
or the configured hooks refs disables, because refs' own git no longer runs them.
|
|
90
|
+
refs' own `status`, `checkout` and `reset` also refresh the index without fsmonitor's help,
|
|
91
|
+
which is measurable on a very large tree (#194).
|
|
92
|
+
|
|
93
|
+
- **refs' git commands no longer follow a `GIT_DIR` inherited from the caller.** refs names each
|
|
94
|
+
checkout by its working directory, but git lets `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE` and
|
|
95
|
+
their siblings override that, and git exports them to every hook. A `refs add` or `refs sync`
|
|
96
|
+
started from a hook, an alias or a wrapper therefore wrote refs' hooks path into the caller's
|
|
97
|
+
repository (blocking its commits) and could `reset --hard` and `clean -fd` the caller's working
|
|
98
|
+
tree, discarding uncommitted work. refs now removes git's repository-locating variables from
|
|
99
|
+
every process it starts, the same set git itself removes before running a command in another
|
|
100
|
+
repository. Command-scope configuration (`GIT_CONFIG_PARAMETERS`, `GIT_CONFIG_COUNT` and its
|
|
101
|
+
pairs) and settings such as `GIT_SSH_COMMAND`, `GIT_ASKPASS` and proxies still pass through.
|
|
102
|
+
|
|
103
|
+
- **An inherited `core.hooksPath` no longer runs a checkout's own hooks.** refs marks each
|
|
104
|
+
checkout with a repository-local `core.hooksPath`, but command-scope configuration outranks it,
|
|
105
|
+
and git exports `GIT_CONFIG_PARAMETERS` to every hook started under `git -c`. An inherited
|
|
106
|
+
relative `core.hooksPath=.githooks` therefore made `refs add` and `refs sync` run hooks the
|
|
107
|
+
cloned repository tracks itself. Every git command refs runs now passes refs' hooks directory at
|
|
108
|
+
command scope as well. This covers the clone, every git command of a sync, `refs doctor`'s
|
|
109
|
+
dirty-checkout check (whose `git status` refreshes the index and runs `post-index-change`) and
|
|
110
|
+
the `origin/HEAD` refresh that `add --dry-run` and a re-clone fall back to (which runs
|
|
111
|
+
`reference-transaction` from git 2.54). The pin is applied once, to the process runner every
|
|
112
|
+
command uses, so a git call added later cannot leave it out.
|
|
113
|
+
|
|
114
|
+
- **`refs doctor` runs at most 8 per-checkout `git` probes at a time.** The `hooks-guard` and
|
|
115
|
+
`dirty-checkouts` checks used to start one `git` process for every checkout at once, so a home
|
|
116
|
+
with hundreds of refs spawned hundreds of processes in one burst. Results are unchanged.
|
|
117
|
+
|
|
118
|
+
- **The plugin manifest's version is a third release version site.** `pnpm versions --set` and
|
|
119
|
+
`--check` cover `skills/.codex-plugin/plugin.json` alongside the CLI package and the skill pin,
|
|
120
|
+
because Codex installs updates by that version.
|
|
121
|
+
|
|
122
|
+
- **The docs say which shell a printed command is for.** The repairs `refs doctor` and `refs sync`
|
|
123
|
+
suggest, and the next steps some errors name, are POSIX shell syntax: values are single-quoted
|
|
124
|
+
and an embedded quote is written as `'\''`. PowerShell and cmd.exe read that differently, so on
|
|
125
|
+
Windows the commands belong in Git Bash. The README and install page also claimed the full test
|
|
126
|
+
suite runs on Windows. It runs there, but some tests are skipped, mostly ones that need POSIX
|
|
127
|
+
file modes, a pseudo-terminal, a POSIX shell to run a printed command through, or a file name
|
|
128
|
+
Windows does not allow, and the docs now say so.
|
|
129
|
+
|
|
130
|
+
### Fixed
|
|
131
|
+
|
|
132
|
+
- **git can no longer keep `refs add` or `refs sync` waiting forever.** git asks for a missing
|
|
133
|
+
HTTPS username or password on the terminal itself, so a remote that needed credentials, with no
|
|
134
|
+
credential helper set up, left refs at a prompt that an agent cannot answer, while refs held the
|
|
135
|
+
lock for that ref. refs now runs git with `GIT_TERMINAL_PROMPT=0` unless you set it yourself. git
|
|
136
|
+
then fails at that point with a message that names credential helpers. Set
|
|
137
|
+
`GIT_TERMINAL_PROMPT=1` to type credentials by hand again.
|
|
138
|
+
|
|
139
|
+
- **A git command that stops making progress now ends.** Each git command refs runs gets a time
|
|
140
|
+
limit, `REFS_GIT_TIMEOUT` seconds (default 900, `0` for no limit). When it runs out, refs ends
|
|
141
|
+
git together with the helper processes git started. Before this, those helpers kept running
|
|
142
|
+
after git had exited and refs kept waiting for them. refs waits until the processes it found are
|
|
143
|
+
gone, and forces any that ignore the request to stop; git exiting first does not cut that
|
|
144
|
+
short. A clone that is cut off this way no longer leaves a half-made checkout that the next
|
|
145
|
+
`refs add` or `refs sync` would take for a working one. Only a clone refs itself started is
|
|
146
|
+
removed; anything else at that path is left alone. If refs cannot confirm that every process
|
|
147
|
+
the clone started has ended, it does not delete the checkout under a process that may still be
|
|
148
|
+
writing to it: it leaves it in place, marks it so that refs will not use it, and says so.
|
|
149
|
+
|
|
150
|
+
- **`refs remove` no longer fails when something appears in a parent directory while it prunes.**
|
|
151
|
+
If another process created an entry in an emptied parent between refs listing it and removing
|
|
152
|
+
it, such as a concurrent `refs add` of another ref under the same owner, the removal reported
|
|
153
|
+
`ENOTEMPTY` and kept the ref registered although its checkout was already deleted. A directory
|
|
154
|
+
that is in use is where pruning stops anyway, so the removal now succeeds and leaves that entry
|
|
155
|
+
alone.
|
|
156
|
+
|
|
157
|
+
- **The skill's quoting example for `refs edit` names the ref first.** `COMMANDS.md` showed
|
|
158
|
+
`refs edit --package='<name>' path '<new-path>' '<ref>'`. Options may move but positional
|
|
159
|
+
arguments keep their order, so with real values substituted `path` became the ref query and the
|
|
160
|
+
command exited `4` with `no ref matches 'path'`. It now reads
|
|
161
|
+
`refs edit '<ref>' --package='<name>' path '<new-path>' --json`, the form `INVESTIGATE.md`
|
|
162
|
+
already used.
|
|
163
|
+
|
|
164
|
+
- **The skill no longer says `refs add` cannot register a repository root.** A root is not one of
|
|
165
|
+
its own glob targets, but `refs add` probes a named root separately and proposes it at `.`. An
|
|
166
|
+
unregistered root now reads as what it is: a ref added before that probe, a root named upstream
|
|
167
|
+
later, or one left out or removed since — and not every root is registered, since a nameless root
|
|
168
|
+
has nothing to register and a member declaring the same name wins.
|
|
169
|
+
|
|
170
|
+
### Documentation
|
|
171
|
+
|
|
172
|
+
- **Preparing blobless checkouts for offline use.** `docs/configuration.md` now says that
|
|
173
|
+
`clone_mode` only takes effect when a checkout is cloned, and how to get the history's file
|
|
174
|
+
contents onto disk for an existing ref.
|
|
175
|
+
|
|
176
|
+
## [0.18.2] - 2026-10-13
|
|
177
|
+
|
|
178
|
+
### Security
|
|
179
|
+
|
|
180
|
+
- **Bundled dependencies moved past known denial-of-service advisories.** `smol-toml` 1.8.0 →
|
|
181
|
+
1.9.1 fixes quadratic-time parsing ([GHSA-r4xh-jqrq-34v2](https://github.com/advisories/GHSA-r4xh-jqrq-34v2));
|
|
182
|
+
refs parses `config.toml` with it. `brace-expansion` 5.0.9 → 5.0.12, reached through
|
|
183
|
+
`minimatch`, fixes unbounded recursion and quadratic expansion
|
|
184
|
+
([GHSA-qhr7-859c-m2p7](https://github.com/advisories/GHSA-qhr7-859c-m2p7),
|
|
185
|
+
[GHSA-6j4f-fj2g-mc7p](https://github.com/advisories/GHSA-6j4f-fj2g-mc7p),
|
|
186
|
+
[GHSA-q2hr-2g5m-vwhr](https://github.com/advisories/GHSA-q2hr-2g5m-vwhr)); refs matches
|
|
187
|
+
workspace patterns read from a checkout with it, and a checkout is third-party content. `zod`
|
|
188
|
+
4.6.2 → 4.6.7. All three are bundled into the published CLI.
|
|
189
|
+
|
|
190
|
+
### Changed
|
|
191
|
+
|
|
192
|
+
- **An invalid `config.toml` is reported in the new parser's words.** The message still carries
|
|
193
|
+
only the fault and its position, never a line of the file, but the fault is named differently
|
|
194
|
+
and the column points at the offending character rather than the start of the line.
|
|
195
|
+
- **Development moved to pnpm 12 and Node 24.21.** The development toolchain moved too: `oxlint`, `oxfmt`,
|
|
196
|
+
`vitest`, `vite`, `tsdown`, and `@types/node` within the 24 line. The published CLI has no pnpm
|
|
197
|
+
requirement of its own.
|
|
198
|
+
|
|
8
199
|
## [0.18.1] - 2026-09-20
|
|
9
200
|
|
|
10
201
|
### Changed
|
|
@@ -363,7 +554,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
363
554
|
name up with plain bracket access, so a name absent from the record resolved up the prototype
|
|
364
555
|
chain: `packages['toString']` answered with `Object.prototype.toString`, which is truthy and
|
|
365
556
|
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
|
|
557
|
+
toString` returned a tag, silently using the ref's own format for a package the configuration
|
|
367
558
|
does not have, and `refs resolve toString --ref <ref>` crashed.
|
|
368
559
|
|
|
369
560
|
All four now ask whether the record has its own entry under that name, as their siblings already
|
|
@@ -812,7 +1003,7 @@ can contain one — TOML has no escape for it — so this only affects a hand-bu
|
|
|
812
1003
|
Existing entries are untouched. A description imported from a manifest before this release stays
|
|
813
1004
|
exactly as it is — nothing distinguishes it from one written by hand, so nothing rewrites it. To
|
|
814
1005
|
review them: `refs show <ref> --packages --json`, and `refs edit <ref> --package <name>
|
|
815
|
-
description "…"` to replace one.
|
|
1006
|
+
description "…"` to replace one.
|
|
816
1007
|
|
|
817
1008
|
### Security
|
|
818
1009
|
|
|
@@ -1163,7 +1354,7 @@ long it has been there.
|
|
|
1163
1354
|
`checkout.status`, which answers the question `missing` was often assumed to.
|
|
1164
1355
|
|
|
1165
1356
|
- **The "lock is held" error now says who holds it and for how long.** It used to read `lock <name>
|
|
1166
|
-
is held — another refs process is running`, which left no way to tell a running `sync` from
|
|
1357
|
+
is held — another refs process is running`, which left no way to tell a running `sync` from
|
|
1167
1358
|
something that crashed 90 seconds ago. It now names the recorded pid, whether that pid is still
|
|
1168
1359
|
present, how long the lock has been held, and when it becomes reclaimable.
|
|
1169
1360
|
|
|
@@ -1690,7 +1881,7 @@ is held — another refs process is running`, which left no way to tell a runnin
|
|
|
1690
1881
|
### Added
|
|
1691
1882
|
|
|
1692
1883
|
- `refs add` now emits progress lines on stderr while it works (`refs: resolving npm
|
|
1693
|
-
package '…'…`, `refs: cloning …`, `refs: detecting workspace packages…`) in both
|
|
1884
|
+
package '…'…`, `refs: cloning …`, `refs: detecting workspace packages…`) in both
|
|
1694
1885
|
human and `--json` mode, so long clones no longer look like a hang. stdout is
|
|
1695
1886
|
unaffected and stays exactly the parseable envelope in `--json` mode.
|
|
1696
1887
|
|