@kaisers-io/refs 0.18.2 → 0.19.1

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,224 @@ 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.1] - 2026-11-08
9
+
10
+ ### Security
11
+
12
+ - **Development installs resolve from the public npm registry, and stop on an unsupported Node.**
13
+ The root `.npmrc` now pins `registry=https://registry.npmjs.org/`, so a user-level default
14
+ registry such as a company mirror no longer decides where installs in this repository resolve,
15
+ which trust-policy evidence and advisories they see, or which tarball URLs reach the lockfile. A
16
+ user-level registry for a single scope (`@scope:registry=`) still applies to that scope.
17
+ Its two previous settings were not read by pnpm 12, which takes only auth, registry, TLS and
18
+ proxy settings from `.npmrc`. They now live in `pnpm-workspace.yaml` as `saveExact` and
19
+ `engineStrict`, so `pnpm add` writes exact versions again and `pnpm install --frozen-lockfile`
20
+ fails on a Node outside `engines.node`. The published CLI is unchanged.
21
+
22
+ ### Changed
23
+
24
+ - **A re-run release job can no longer move the GitHub Latest release backwards.** The job that
25
+ creates the GitHub release used to leave Latest to the API, which makes every new release Latest.
26
+ Re-running a failed one for an older version after a newer release had shipped would therefore
27
+ have marked the older version Latest. It now compares the tag with the current Latest release
28
+ and always states the decision, and release entries for different tags are created one at a
29
+ time.
30
+
31
+ - **Every release is now installed from npm on Linux, macOS and Windows after it is published.**
32
+ The release workflow used to test only a tarball it packed itself, on Linux, while the package it
33
+ published was assembled separately and never installed. A new job waits until the registry serves
34
+ the version, installs it the way a user does, and runs the same smoke test that pull requests now
35
+ run on all three platforms: add, list, sync, resolve and remove of a local repository, each
36
+ outcome checked. It runs after publication and cannot stop a release; `CONTRIBUTING.md` says what
37
+ to do when it fails.
38
+
39
+ ### Documentation
40
+
41
+ - **`refs edit --remove`, `--decline` and `--undecline` are in the command references.**
42
+ `docs/commands.md` lacked all three and the skill's `COMMANDS.md` lacked `--remove`, although
43
+ they shipped in 0.13.1 and 0.14.0. Both now give the synopsis, the `--json` data each mode
44
+ returns, and its exit codes. A test now fails when a registered command or option is missing
45
+ from either reference.
46
+
47
+ - **The README says how to upgrade.** A new `Upgrading` section gives the commands that move the
48
+ CLI and the skill (or the Codex plugin) to a new release together, notes that a global skill
49
+ install needs `-g` again, and points at `refs doctor` and the changelog for what follows.
50
+ `docs/install.md` and the npm package README link to it.
51
+
52
+ - **`SECURITY.md` is the policy again, and the security model has its own page.** The reporting
53
+ process, supported versions and scope lists stay in `SECURITY.md`, which GitHub shows as the
54
+ repository's security policy. The account of the git processes refs starts, of configured hooks,
55
+ filters and `core.fsmonitor`, and of untrusted checkout content moved unchanged to
56
+ `docs/security.md`. A report now names what a useful one contains.
57
+
58
+ ## [0.19.0] - 2026-11-07
59
+
60
+ ### Security
61
+
62
+ - **`SECURITY.md` now describes the git processes refs starts.** A new section states which
63
+ inherited git variables refs removes and which it keeps (command-scope configuration, and
64
+ settings such as `GIT_SSH_COMMAND`), which commands pin refs' hooks directory above an inherited
65
+ `core.hooksPath` and which do not, how the time limit ends git and the processes it started and
66
+ where that cannot be confirmed, when a failed clone is removed and when it is kept but unmarked,
67
+ how refs' `core.fsmonitor` and configured-hook overrides work on git 2.54 and later and what they
68
+ cost, what still runs (content filters, during `refs add`'s clone too), and which git versions
69
+ the controls were measured on. refs enforces no minimum git version, and the section says so. The
70
+ section describes the controls of #249, #251 and #252 and holds only for a release that contains
71
+ them (#217).
72
+
73
+ - **A program inside a checkout can no longer run in place of git.** refs starts git with its
74
+ working directory inside a checkout, and on Windows the process spawn looks in that directory
75
+ before `PATH`, so a `git.exe` or `git.com` tracked at a reference's root ran on the next
76
+ `refs sync` or `refs doctor`. On every platform, an empty or relative `PATH` entry pointed at the
77
+ same directory. refs now resolves every program it starts through absolute `PATH` entries only
78
+ and starts that absolute path; a program found nowhere else fails as not found.
79
+
80
+ - **refs' own git no longer runs a configured fsmonitor command or configured hooks.** Every git
81
+ process refs starts now carries `-c core.fsmonitor=` and `-c hook.<event>.enabled=false` for
82
+ each event refs causes (`post-checkout`, `post-index-change`, `pre-auto-gc`,
83
+ `reference-transaction`). Both mechanisms come from the user's own git configuration and both
84
+ could run a script the checkout tracks, which `core.hooksPath` does not prevent. The fsmonitor
85
+ override uses the empty value because git 2.35.1 and older would run `false` as a program. The
86
+ event switch exists from git 2.55, but there a hook label named after an event turns it into
87
+ that label's switch and the event's other hooks still run; git 2.54 can disable a configured
88
+ hook only by its label. So on git 2.54 and later refs also reads every label from the
89
+ configuration and all of its includes, conditional ones included whether or not they apply yet,
90
+ and disables each one. When it cannot read the whole include graph, it refuses to start git
91
+ instead. It reads them once per refs process and again only when a file it read changes, so a
92
+ sync starts a handful of extra git processes rather than several per git command. Content
93
+ filters stay enabled, because turning one off changes what a checkout contains (#194).
94
+
95
+ - **Development installs refuse dependency versions published with weaker trust evidence.**
96
+ `pnpm-workspace.yaml` sets pnpm's `trustPolicy: no-downgrade`: a version published without the
97
+ trusted-publisher or provenance evidence an earlier release of the same package had now fails
98
+ `pnpm install`, including when it is already in the lockfile. Such a downgrade does not prove a
99
+ compromise, but it is what a publish with a leaked token would look like, so the version is held
100
+ back until someone reviews it. A test fails if the setting is removed or weakened, while a
101
+ reviewed exception pinned to an exact version stays possible. The release build installs through
102
+ the same policy, so this also covers the libraries bundled into the published CLI; the CLI's
103
+ runtime behaviour is unchanged.
104
+
105
+ - **Every package in the lockfile is audited for advisories again.** Since the move to pnpm 12 the
106
+ lockfile holds two YAML documents, and GitHub's dependency graph sees only part of it: the
107
+ transitive packages bundled into the CLI, such as `brace-expansion` via `minimatch`, dropped out of
108
+ Dependabot alerts. A new CI workflow runs `pnpm audit` over the whole lockfile on every pull
109
+ request and weekly. It fails when the audit reports fewer packages than the lockfile holds
110
+ registry packages, so a scanner that reads one document cannot pass as a clean result; this
111
+ compares counts, a plausibility floor, and does not prove that each individual package was
112
+ audited. A report it cannot fully read, such as an advisory with an unknown severity, fails as an
113
+ incomplete audit rather than passing. Advisories listed in pnpm's `auditConfig.ignoreGhsas` are
114
+ honoured.
115
+
116
+ ### Added
117
+
118
+ - **`REFS_SYNC_CONCURRENCY` sets how many refs `refs sync` works on at once.** The default is
119
+ still four. A whole number is clamped to 1–16, since every slot is a connection to a forge; any
120
+ other value is ignored.
121
+
122
+ - **The skill installs as a Codex plugin.** `codex plugin marketplace add kaisers-io/refs` and
123
+ `codex plugin add refs@kaisers-io` install the same skill `npx skills add` does, from the same
124
+ directory, with nothing else from the repository. In Codex it is `$refs:refs`. The plugin does
125
+ not install the CLI. `npx skills add`, the manual copy and the npm CLI work as before.
126
+
127
+ - **`refs doctor` recognises a Codex plugin install.** The `skill` check looks in Codex's plugin
128
+ cache, so a plugin-only install no longer reads as missing, and a stale plugin is told to run
129
+ `codex plugin marketplace upgrade` rather than `npx skills add`, which would add a second copy.
130
+ The skill's own version gate gives the plugin copy the same advice. Doctor reads the copy
131
+ Codex loads, from `refs@kaisers-io` only, and says that it does not check whether the plugin
132
+ is enabled.
133
+
134
+ ### Changed
135
+
136
+ - **`refs add --dry-run` warns about what git will run before it clones.** A `warnings` entry
137
+ beginning `git-exec-surfaces:` repeats `refs doctor`'s check of that name: content filters, and
138
+ any configured hook refs did not disable. `refs doctor` no longer reports an fsmonitor command
139
+ or the configured hooks refs disables, because refs' own git no longer runs them.
140
+ refs' own `status`, `checkout` and `reset` also refresh the index without fsmonitor's help,
141
+ which is measurable on a very large tree (#194).
142
+
143
+ - **refs' git commands no longer follow a `GIT_DIR` inherited from the caller.** refs names each
144
+ checkout by its working directory, but git lets `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE` and
145
+ their siblings override that, and git exports them to every hook. A `refs add` or `refs sync`
146
+ started from a hook, an alias or a wrapper therefore wrote refs' hooks path into the caller's
147
+ repository (blocking its commits) and could `reset --hard` and `clean -fd` the caller's working
148
+ tree, discarding uncommitted work. refs now removes git's repository-locating variables from
149
+ every process it starts, the same set git itself removes before running a command in another
150
+ repository. Command-scope configuration (`GIT_CONFIG_PARAMETERS`, `GIT_CONFIG_COUNT` and its
151
+ pairs) and settings such as `GIT_SSH_COMMAND`, `GIT_ASKPASS` and proxies still pass through.
152
+
153
+ - **An inherited `core.hooksPath` no longer runs a checkout's own hooks.** refs marks each
154
+ checkout with a repository-local `core.hooksPath`, but command-scope configuration outranks it,
155
+ and git exports `GIT_CONFIG_PARAMETERS` to every hook started under `git -c`. An inherited
156
+ relative `core.hooksPath=.githooks` therefore made `refs add` and `refs sync` run hooks the
157
+ cloned repository tracks itself. Every git command refs runs now passes refs' hooks directory at
158
+ command scope as well. This covers the clone, every git command of a sync, `refs doctor`'s
159
+ dirty-checkout check (whose `git status` refreshes the index and runs `post-index-change`) and
160
+ the `origin/HEAD` refresh that `add --dry-run` and a re-clone fall back to (which runs
161
+ `reference-transaction` from git 2.54). The pin is applied once, to the process runner every
162
+ command uses, so a git call added later cannot leave it out.
163
+
164
+ - **`refs doctor` runs at most 8 per-checkout `git` probes at a time.** The `hooks-guard` and
165
+ `dirty-checkouts` checks used to start one `git` process for every checkout at once, so a home
166
+ with hundreds of refs spawned hundreds of processes in one burst. Results are unchanged.
167
+
168
+ - **The plugin manifest's version is a third release version site.** `pnpm versions --set` and
169
+ `--check` cover `skills/.codex-plugin/plugin.json` alongside the CLI package and the skill pin,
170
+ because Codex installs updates by that version.
171
+
172
+ - **The docs say which shell a printed command is for.** The repairs `refs doctor` and `refs sync`
173
+ suggest, and the next steps some errors name, are POSIX shell syntax: values are single-quoted
174
+ and an embedded quote is written as `'\''`. PowerShell and cmd.exe read that differently, so on
175
+ Windows the commands belong in Git Bash. The README and install page also claimed the full test
176
+ suite runs on Windows. It runs there, but some tests are skipped, mostly ones that need POSIX
177
+ file modes, a pseudo-terminal, a POSIX shell to run a printed command through, or a file name
178
+ Windows does not allow, and the docs now say so.
179
+
180
+ ### Fixed
181
+
182
+ - **git can no longer keep `refs add` or `refs sync` waiting forever.** git asks for a missing
183
+ HTTPS username or password on the terminal itself, so a remote that needed credentials, with no
184
+ credential helper set up, left refs at a prompt that an agent cannot answer, while refs held the
185
+ lock for that ref. refs now runs git with `GIT_TERMINAL_PROMPT=0` unless you set it yourself. git
186
+ then fails at that point with a message that names credential helpers. Set
187
+ `GIT_TERMINAL_PROMPT=1` to type credentials by hand again.
188
+
189
+ - **A git command that stops making progress now ends.** Each git command refs runs gets a time
190
+ limit, `REFS_GIT_TIMEOUT` seconds (default 900, `0` for no limit). When it runs out, refs ends
191
+ git together with the helper processes git started. Before this, those helpers kept running
192
+ after git had exited and refs kept waiting for them. refs waits until the processes it found are
193
+ gone, and forces any that ignore the request to stop; git exiting first does not cut that
194
+ short. A clone that is cut off this way no longer leaves a half-made checkout that the next
195
+ `refs add` or `refs sync` would take for a working one. Only a clone refs itself started is
196
+ removed; anything else at that path is left alone. If refs cannot confirm that every process
197
+ the clone started has ended, it does not delete the checkout under a process that may still be
198
+ writing to it: it leaves it in place, marks it so that refs will not use it, and says so.
199
+
200
+ - **`refs remove` no longer fails when something appears in a parent directory while it prunes.**
201
+ If another process created an entry in an emptied parent between refs listing it and removing
202
+ it, such as a concurrent `refs add` of another ref under the same owner, the removal reported
203
+ `ENOTEMPTY` and kept the ref registered although its checkout was already deleted. A directory
204
+ that is in use is where pruning stops anyway, so the removal now succeeds and leaves that entry
205
+ alone.
206
+
207
+ - **The skill's quoting example for `refs edit` names the ref first.** `COMMANDS.md` showed
208
+ `refs edit --package='<name>' path '<new-path>' '<ref>'`. Options may move but positional
209
+ arguments keep their order, so with real values substituted `path` became the ref query and the
210
+ command exited `4` with `no ref matches 'path'`. It now reads
211
+ `refs edit '<ref>' --package='<name>' path '<new-path>' --json`, the form `INVESTIGATE.md`
212
+ already used.
213
+
214
+ - **The skill no longer says `refs add` cannot register a repository root.** A root is not one of
215
+ its own glob targets, but `refs add` probes a named root separately and proposes it at `.`. An
216
+ unregistered root now reads as what it is: a ref added before that probe, a root named upstream
217
+ later, or one left out or removed since — and not every root is registered, since a nameless root
218
+ has nothing to register and a member declaring the same name wins.
219
+
220
+ ### Documentation
221
+
222
+ - **Preparing blobless checkouts for offline use.** `docs/configuration.md` now says that
223
+ `clone_mode` only takes effect when a checkout is cloned, and how to get the history's file
224
+ contents onto disk for an existing ref.
225
+
8
226
  ## [0.18.2] - 2026-10-13
9
227
 
10
228
  ### Security
@@ -1750,25 +1968,3 @@ trusted-publishing pipeline end to end.
1750
1968
  URL-carrying message, and read-only enforcement of managed checkouts via
1751
1969
  installed git hooks.
1752
1970
  - Agent skill (`skills/refs/`) documenting the investigate/add/maintain workflows.
1753
-
1754
- [Unreleased]: https://github.com/kaisers-io/refs/compare/v0.12.0...HEAD
1755
- [0.12.0]: https://github.com/kaisers-io/refs/compare/v0.11.0...v0.12.0
1756
- [0.11.0]: https://github.com/kaisers-io/refs/compare/v0.10.0...v0.11.0
1757
- [0.10.0]: https://github.com/kaisers-io/refs/compare/v0.9.0...v0.10.0
1758
- [0.9.0]: https://github.com/kaisers-io/refs/compare/v0.8.3...v0.9.0
1759
- [0.8.3]: https://github.com/kaisers-io/refs/compare/v0.8.2...v0.8.3
1760
- [0.8.2]: https://github.com/kaisers-io/refs/compare/v0.8.1...v0.8.2
1761
- [0.8.1]: https://github.com/kaisers-io/refs/compare/v0.8.0...v0.8.1
1762
- [0.8.0]: https://github.com/kaisers-io/refs/compare/v0.7.0...v0.8.0
1763
- [0.7.0]: https://github.com/kaisers-io/refs/compare/v0.6.1...v0.7.0
1764
- [0.6.1]: https://github.com/kaisers-io/refs/compare/v0.6.0...v0.6.1
1765
- [0.6.0]: https://github.com/kaisers-io/refs/compare/v0.5.1...v0.6.0
1766
- [0.5.1]: https://github.com/kaisers-io/refs/compare/v0.5.0...v0.5.1
1767
- [0.5.0]: https://github.com/kaisers-io/refs/compare/v0.4.0...v0.5.0
1768
- [0.4.0]: https://github.com/kaisers-io/refs/compare/v0.3.0...v0.4.0
1769
- [0.3.0]: https://github.com/kaisers-io/refs/compare/v0.2.0...v0.3.0
1770
- [0.2.0]: https://github.com/kaisers-io/refs/compare/v0.1.3...v0.2.0
1771
- [0.1.3]: https://github.com/kaisers-io/refs/compare/v0.1.2...v0.1.3
1772
- [0.1.2]: https://github.com/kaisers-io/refs/compare/v0.1.1...v0.1.2
1773
- [0.1.1]: https://github.com/kaisers-io/refs/compare/v0.1.0...v0.1.1
1774
- [0.1.0]: https://github.com/kaisers-io/refs/releases/tag/v0.1.0
package/README.md CHANGED
@@ -61,7 +61,7 @@ The `npm:` prefix says which registry the name belongs to, so a package and a re
61
61
 
62
62
  ## Driving the CLI yourself
63
63
 
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.
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. [Upgrading](https://github.com/kaisers-io/refs#upgrading) has the commands that move both.
65
65
 
66
66
  ```bash
67
67
  # clones and proposes; nothing is configured yet