@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.
Files changed (3) hide show
  1. package/CHANGELOG.md +195 -4
  2. package/dist/refs.mjs +184 -48
  3. 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