@williamthorsen/toolbelt.git 0.3.0 → 0.4.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 +52 -3
- package/README.md +14 -12
- package/bin/tb-git.js +27 -0
- package/dist/esm/3-candidate/deriveBranchNumber.d.ts +10 -0
- package/dist/esm/3-candidate/findBranchTicketRef.d.ts +14 -0
- package/dist/esm/3-candidate/findBranchTicketRef.js +1 -1
- package/dist/esm/bin/findOwningManifest.d.ts +8 -0
- package/dist/esm/bin/resolveCheckedOutBranch.d.ts +7 -0
- package/dist/esm/bin/resolveSelfVersion.d.ts +7 -0
- package/dist/esm/bin/runTbGit.d.ts +8 -0
- package/dist/esm/bin/tb-git.d.ts +0 -1
- package/dist/esm/bin/tb-git.js +6 -1
- package/package.json +7 -6
package/CHANGELOG.md
CHANGED
|
@@ -2,9 +2,58 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## 0.4.0 — 2026-09-15
|
|
6
|
+
|
|
7
|
+
### 🎉 Features
|
|
8
|
+
|
|
9
|
+
- 🚨 **Breaking:** Move createTempTree from toolbelt.filesystem to toolbelt.testing (#313)
|
|
10
|
+
|
|
11
|
+
- Moves `CreateTempTreeOptions` and the `TempTree` handle to `@williamthorsen/toolbelt.testing/candidate` along with `createTempTree`.
|
|
12
|
+
|
|
13
|
+
Migration: Import `createTempTree`, `CreateTempTreeOptions`, and `TempTree` from `@williamthorsen/toolbelt.testing/candidate`, and declare `@williamthorsen/toolbelt.testing` in the manifest that declared `@williamthorsen/toolbelt.filesystem` for them.
|
|
14
|
+
|
|
15
|
+
### ⚙️ Tooling
|
|
16
|
+
|
|
17
|
+
- Remove the stale repo-local cliff.toml and normalize changelog titles (#327)
|
|
18
|
+
|
|
19
|
+
- Stops `release-kit prepare` from printing a "skipped due to grouping error(s)" warning for each releasable workspace by letting it resolve the git-cliff template bundled with release-kit, previously overridden by the root `cliff.toml`.
|
|
20
|
+
- Excludes commits without a ticket prefix from future changelog entries.
|
|
21
|
+
- Renames the section titles in every `packages/*/.meta/changelog.json`, except `Dependency updates`, to the headings of release-kit's work-type taxonomy, such as "🎉 Features" and "🏗️ Internal features", and regenerates each `CHANGELOG.md` so that release-kit orders existing and new sections by the same rule.
|
|
22
|
+
- Causes the next `release-kit prepare` to plan patch releases of `dstructs`, `hof`, and `sets`, which had no other commits since their last release, because the changelog commit touches every workspace.
|
|
23
|
+
|
|
24
|
+
### 📚 Documentation
|
|
25
|
+
|
|
26
|
+
- Align prose with plain-speech doctrine and writing conventions (#306)
|
|
27
|
+
|
|
28
|
+
- Copy-edits prose across the repo: comments, test names, package READMEs, and `AGENTS.md`.
|
|
29
|
+
- Rewrites a few user-facing strings as well, among them `configure-project`'s help text and the errors from `parseProjectSpec`, `securityCommands`, and `hashString`.
|
|
30
|
+
|
|
31
|
+
## 0.3.1 — 2026-09-06
|
|
32
|
+
|
|
33
|
+
### 🐛 Bug fixes
|
|
34
|
+
|
|
35
|
+
- Point every package bin at a committed wrapper (#296)
|
|
36
|
+
|
|
37
|
+
- Points the `tb-git`, `tb-jira`, and `tb-secret` commands at committed wrappers under each package's `bin/`, so the target exists when the package manager links the command rather than only after a build.
|
|
38
|
+
|
|
39
|
+
- Fix piped-stdin reads and unhandled EPIPE in the CLIs (#301)
|
|
40
|
+
|
|
41
|
+
- Fixes an issue where `tb-secret set` and `tb-jira auth set` failed with `EAGAIN: resource temporarily unavailable` when the producer of a piped credential delayed its first byte, as `tb-secret get`, `op read`, and `gh auth token` all do.
|
|
42
|
+
- Stops `tb-secret`, `tb-jira`, and `tb-git` from crashing with an unhandled `EPIPE` when the reader on their stdout or stderr exits first, so that `tb-secret get | head -1` ends quietly, as a program that ignores `SIGPIPE` does.
|
|
43
|
+
|
|
44
|
+
### 📚 Documentation
|
|
45
|
+
|
|
46
|
+
- Repair reduced object relatives in the READMEs and AGENTS.md (#263)
|
|
47
|
+
|
|
48
|
+
Repairs the reduced object relative in `AGENTS.md`, the root `README.md`, and the package READMEs.
|
|
49
|
+
|
|
50
|
+
- Repair the repository's prose and record every rejection's ground (#290)
|
|
51
|
+
|
|
52
|
+
Applies one repo-wide `revise-prose` sweep across the repository's READMEs, `AGENTS.md`, source comments, doc descriptions, and test names.
|
|
53
|
+
|
|
5
54
|
## 0.3.0 — 2026-08-30
|
|
6
55
|
|
|
7
|
-
### Features
|
|
56
|
+
### 🎉 Features
|
|
8
57
|
|
|
9
58
|
- Add a tb-git CLI for branch-number and ticket-ref (#250)
|
|
10
59
|
|
|
@@ -12,7 +61,7 @@ All notable changes to this project will be documented in this file.
|
|
|
12
61
|
|
|
13
62
|
## 0.2.0 — 2026-08-28
|
|
14
63
|
|
|
15
|
-
### Features
|
|
64
|
+
### 🎉 Features
|
|
16
65
|
|
|
17
66
|
- Add findBranchTicketRef and deriveBranchNumber to toolbelt.git (#239)
|
|
18
67
|
|
|
@@ -20,7 +69,7 @@ All notable changes to this project will be documented in this file.
|
|
|
20
69
|
|
|
21
70
|
`findBranchTicketRef` extracts the ticket ID encoded in a branch name. `deriveBranchNumber` relies on it to give every branch a stable number: the ticket's if the branch name includes one, and otherwise a `hashString` digest of the name. The number is bounded by the caller-specified range.
|
|
22
71
|
|
|
23
|
-
### Internal
|
|
72
|
+
### 🏗️ Internal features
|
|
24
73
|
|
|
25
74
|
- Scaffold toolbelt.git for git utilities (#235)
|
|
26
75
|
|
package/README.md
CHANGED
|
@@ -3,13 +3,15 @@
|
|
|
3
3
|
Utilities for working with git.
|
|
4
4
|
|
|
5
5
|
<!-- section:release-notes -->
|
|
6
|
-
## Release notes — v0.
|
|
6
|
+
## Release notes — v0.4.0 (2026-09-15)
|
|
7
7
|
|
|
8
|
-
### Features
|
|
8
|
+
### 🎉 Features
|
|
9
9
|
|
|
10
|
-
-
|
|
10
|
+
- 🚨 **Breaking:** Move createTempTree from toolbelt.filesystem to toolbelt.testing (#313)
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
- Moves `CreateTempTreeOptions` and the `TempTree` handle to `@williamthorsen/toolbelt.testing/candidate` along with `createTempTree`.
|
|
13
|
+
|
|
14
|
+
Migration: Import `createTempTree`, `CreateTempTreeOptions`, and `TempTree` from `@williamthorsen/toolbelt.testing/candidate`, and declare `@williamthorsen/toolbelt.testing` in the manifest that declared `@williamthorsen/toolbelt.filesystem` for them.
|
|
13
15
|
<!-- /section:release-notes -->
|
|
14
16
|
|
|
15
17
|
## Installation
|
|
@@ -29,7 +31,7 @@ pnpm add --global @williamthorsen/toolbelt.git # puts tb-git on PATH
|
|
|
29
31
|
npx @williamthorsen/toolbelt.git branch-number # or run it without installing
|
|
30
32
|
```
|
|
31
33
|
|
|
32
|
-
The short `npx` form works because the package declares exactly one bin, which npm falls back to whatever its name. Were a second bin added, the invocation would become `npx --package @williamthorsen/toolbelt.git tb-git ...`.
|
|
34
|
+
The short `npx` form works because the package declares exactly one bin, which npm falls back to, whatever its name. Were a second bin added, the invocation would become `npx --package @williamthorsen/toolbelt.git tb-git ...`.
|
|
33
35
|
|
|
34
36
|
`tb-git --help`, each subcommand's `--help`, and `tb-git --version` report the surface and the installed version.
|
|
35
37
|
|
|
@@ -49,7 +51,7 @@ tb-git branch-number 232_add-widget --min 3000 --max 3999
|
|
|
49
51
|
# 3232
|
|
50
52
|
```
|
|
51
53
|
|
|
52
|
-
A negative offset takes the `=` form, `--offset=-3`:
|
|
54
|
+
A negative offset takes the `=` form, `--offset=-3`: A bare `-3` reads as an option rather than as the value.
|
|
53
55
|
|
|
54
56
|
### `tb-git ticket-ref [<branch>] [options]`
|
|
55
57
|
|
|
@@ -80,7 +82,7 @@ With no `<branch>`, both subcommands resolve the checked-out branch with `git br
|
|
|
80
82
|
| `1` | `ticket-ref` found no ticket in the branch name; both streams are empty |
|
|
81
83
|
| `2` | Usage or validation error, with the message on stderr |
|
|
82
84
|
|
|
83
|
-
A bound, offset, or key rejected by the library exits `2
|
|
85
|
+
A bound, offset, or key rejected by the library exits `2`, reporting the message that it raises. So does an empty option value, so `--min "$PORT_MIN"` with `PORT_MIN` unset fails instead of bounding at `0`.
|
|
84
86
|
|
|
85
87
|
```sh
|
|
86
88
|
if ref=$(tb-git ticket-ref); then
|
|
@@ -113,11 +115,11 @@ findBranchTicketRef('232_add-widget');
|
|
|
113
115
|
// { id: '232', number: 232 }
|
|
114
116
|
```
|
|
115
117
|
|
|
116
|
-
A ref must begin a segment. `/` and `_` both delimit one, so an author prefix and a worktree-safe spelling parse alike, and the leftmost segment
|
|
118
|
+
A ref must begin a segment. `/` and `_` both delimit one, so an author prefix and a worktree-safe spelling parse alike, and the leftmost segment with a ref wins. Anchoring to a segment keeps a kebab-case description from reading as a ticket: `feat/add-widget-2` encodes none, because `widget` follows a hyphen rather than a separator.
|
|
117
119
|
|
|
118
|
-
Two forms are recognized, each taking an optional `.N` revisit suffix. A **keyed** ref is a Jira-style key and number, the key matching Jira's own rule of a letter followed by letters and digits. A **bare-numeric** ref is the number alone. `id` and `key` are emitted uppercased, since a branch name may be lowercase but the ticket it names is `MAC-22`.
|
|
120
|
+
Two forms are recognized, each taking an optional `.N` revisit suffix. A **keyed** ref is a Jira-style key and number, the key matching Jira's own rule of a letter followed by letters and digits. A **bare-numeric** ref is the number alone. `id` and `key` are emitted uppercased, since a branch name may be lowercase but the ticket that it names is `MAC-22`.
|
|
119
121
|
|
|
120
|
-
By default a key must be uppercase, which
|
|
122
|
+
By default a key must be uppercase, which Jira permits and which is the only property separating a real key from an ordinary word: Without it, `feat-2` would read as ticket `FEAT-2`. Declaring the project's own key through `key` is both more permissive and more precise, since it then matches in any casing and is the only key that matches at all.
|
|
121
123
|
|
|
122
124
|
```ts
|
|
123
125
|
findBranchTicketRef('mac-22/add-widget');
|
|
@@ -132,7 +134,7 @@ findBranchTicketRef('feat-2', { key: 'mac' });
|
|
|
132
134
|
|
|
133
135
|
The bare-numeric form stays active whether or not a key is declared. A `RangeError` names the fault when `key` is not a well-formed key, which would otherwise match nothing at all.
|
|
134
136
|
|
|
135
|
-
A trailing `-N` is not read as a sub-ID, being indistinguishable from a description: `232-3-column-layout`
|
|
137
|
+
A trailing `-N` is not read as a sub-ID, being indistinguishable from a description: `232-3-column-layout` has no revisit. Neither suffix affects `number`.
|
|
136
138
|
|
|
137
139
|
## `deriveBranchNumber`
|
|
138
140
|
|
|
@@ -152,7 +154,7 @@ deriveBranchNumber('main');
|
|
|
152
154
|
// 663286764
|
|
153
155
|
```
|
|
154
156
|
|
|
155
|
-
The number is the ticket's when the branch names one, and a [`hashString`](https://github.com/williamthorsen/toolbelt/tree/main/packages/strings#hashstring) digest of the whole name when it does not, so every branch yields something. `min`, `max`, and `offset` are `hashString`'s, and apply to both paths alike:
|
|
157
|
+
The number is the ticket's when the branch names one, and a [`hashString`](https://github.com/williamthorsen/toolbelt/tree/main/packages/strings#hashstring) digest of the whole name when it does not, so every branch yields something. `min`, `max`, and `offset` are `hashString`'s, and apply to both paths alike: The two land in one range, and `offset` stays a pure rotation.
|
|
156
158
|
|
|
157
159
|
```ts
|
|
158
160
|
deriveBranchNumber('232_add-widget', { min: 3000, max: 3999 });
|
package/bin/tb-git.js
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// Imports only node builtins: A top-level import resolves before the gate below runs, so an unresolvable
|
|
4
|
+
// dependency would replace this file's build-first message with ERR_MODULE_NOT_FOUND.
|
|
5
|
+
import { existsSync } from 'node:fs';
|
|
6
|
+
|
|
7
|
+
// Thin wrapper so pnpm can link the bin at install time, before `dist/` exists. The real entry point loads
|
|
8
|
+
// at runtime from the build output.
|
|
9
|
+
const entryPoint = new URL('../dist/esm/bin/tb-git.js', import.meta.url);
|
|
10
|
+
|
|
11
|
+
// Gate on the entry file itself: Node raises ERR_MODULE_NOT_FOUND for any unresolved module in the graph,
|
|
12
|
+
// so keying the build-first message off the error code would also fire when the build is present and one
|
|
13
|
+
// of its imports is missing.
|
|
14
|
+
if (!existsSync(entryPoint)) {
|
|
15
|
+
process.stderr.write(
|
|
16
|
+
'tb-git: build output not found. In a source checkout, run `nmr build`; otherwise reinstall the package.\n',
|
|
17
|
+
);
|
|
18
|
+
process.exit(1);
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
try {
|
|
22
|
+
await import(entryPoint.href);
|
|
23
|
+
} catch (error) {
|
|
24
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
25
|
+
process.stderr.write(`tb-git: failed to load: ${message}\n`);
|
|
26
|
+
process.exit(1);
|
|
27
|
+
}
|
|
@@ -1,4 +1,14 @@
|
|
|
1
1
|
import { type BranchTicketRefOptions } from './findBranchTicketRef.js';
|
|
2
|
+
/**
|
|
3
|
+
* Derives a number from a branch name: the number of the ticket encoded by the name, or a hash of the name
|
|
4
|
+
* when it encodes none, so a branch always yields a stable number. `min` and `max` bound the result
|
|
5
|
+
* inclusively, and `offset` rotates it, wrapping at the bounds. Throws a RangeError on a malformed `key`,
|
|
6
|
+
* or on a bound or offset rejected by hashString.
|
|
7
|
+
*
|
|
8
|
+
* @category Git
|
|
9
|
+
* @experimental
|
|
10
|
+
* @stage candidate
|
|
11
|
+
*/
|
|
2
12
|
export declare function deriveBranchNumber(branch: string, options?: DeriveBranchNumberOptions): number;
|
|
3
13
|
export interface DeriveBranchNumberOptions extends BranchTicketRefOptions {
|
|
4
14
|
readonly max?: number | undefined;
|
|
@@ -1,10 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Finds the ticket ref encoded by a branch name, or `undefined` when it encodes none. A ref must begin a
|
|
3
|
+
* `/`- or `_`-delimited segment, and the leftmost segment containing one wins. A key must be uppercase,
|
|
4
|
+
* unless `key` names the project's own key, which then matches in any casing and is the only key that
|
|
5
|
+
* does; a bare-numeric ref is found either way. Throws a RangeError if `key` is not a well-formed key.
|
|
6
|
+
*
|
|
7
|
+
* @category Git
|
|
8
|
+
* @experimental
|
|
9
|
+
* @stage candidate
|
|
10
|
+
*/
|
|
1
11
|
export declare function findBranchTicketRef(branch: string, options?: BranchTicketRefOptions): BranchTicketRef | undefined;
|
|
2
12
|
export interface BranchTicketRef {
|
|
13
|
+
/** The canonical ID: an uppercased key and number (`MAC-22`), or the number alone for a bare-numeric ref. */
|
|
3
14
|
readonly id: string;
|
|
15
|
+
/** The uppercased project key, absent for a bare-numeric ref. */
|
|
4
16
|
readonly key?: string | undefined;
|
|
5
17
|
readonly number: number;
|
|
18
|
+
/** The revisit ordinal, present when the ref has a `.N` suffix. */
|
|
6
19
|
readonly revisit?: number | undefined;
|
|
7
20
|
}
|
|
8
21
|
export interface BranchTicketRefOptions {
|
|
22
|
+
/** The project's own key, which then matches in any casing and displaces the uppercase-key rule. */
|
|
9
23
|
readonly key?: string | undefined;
|
|
10
24
|
}
|
|
@@ -5,7 +5,7 @@ export function findBranchTicketRef(branch, options = {}) {
|
|
|
5
5
|
const { key: declaredKey } = options;
|
|
6
6
|
if (declaredKey !== undefined && !KEY_PATTERN.test(declaredKey)) {
|
|
7
7
|
const received = `Received ${JSON.stringify(declaredKey)}.`;
|
|
8
|
-
throw new RangeError(`Invalid key:
|
|
8
|
+
throw new RangeError(`Invalid key: A key must be a letter followed by letters or digits. ${received}`);
|
|
9
9
|
}
|
|
10
10
|
for (const segment of branch.split(SEGMENT_SEPARATOR)) {
|
|
11
11
|
const groups = REF_PATTERN.exec(segment)?.groups;
|
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Finds the manifest of the package owning a directory, ascending to the first `package.json` declaring a
|
|
3
|
+
* `name`. One declaring none is a marker manifest, such as the `{"type": "commonjs"}` file left in `dist/`
|
|
4
|
+
* by a dual-format build, and the ascent passes over it, so the answer is the owning package rather than
|
|
5
|
+
* the nearest manifest. Throws where no ancestor declares a name.
|
|
6
|
+
*
|
|
7
|
+
* @internal
|
|
8
|
+
*/
|
|
1
9
|
export declare function findOwningManifest(startDir: string): OwningManifest;
|
|
2
10
|
export interface OwningManifest {
|
|
3
11
|
readonly manifest: {
|
|
@@ -1 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolves the branch checked out in the current directory. Throws when git is absent, the directory is
|
|
3
|
+
* not a repository, or HEAD names no branch, since each leaves the caller without the name that it asked
|
|
4
|
+
* to derive from.
|
|
5
|
+
*
|
|
6
|
+
* @internal
|
|
7
|
+
*/
|
|
1
8
|
export declare function resolveCheckedOutBranch(): string;
|
|
@@ -1 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reads the version declared by the package owning a directory, defaulting to this module's own, which is
|
|
3
|
+
* this package whether it runs from source under the test runner or from the build output once installed.
|
|
4
|
+
* Throws where the owning manifest declares no string version.
|
|
5
|
+
*
|
|
6
|
+
* @internal
|
|
7
|
+
*/
|
|
1
8
|
export declare function resolveSelfVersion(fromDir?: string): string;
|
|
@@ -1,8 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Runs the `tb-git` command line, returning what to write and exit with rather than doing either, so the
|
|
3
|
+
* whole surface is exercisable without a process. Every failure is reported through the result: Nothing throws.
|
|
4
|
+
*
|
|
5
|
+
* @internal
|
|
6
|
+
*/
|
|
1
7
|
export declare function runTbGit(args: string[], effects: TbGitEffects): TbGitResult;
|
|
8
|
+
/** The effects deferred to the entry point, which keeps the runner free of I/O. */
|
|
2
9
|
export interface TbGitEffects {
|
|
3
10
|
readonly resolveBranch: () => string;
|
|
4
11
|
readonly resolveVersion: () => string;
|
|
5
12
|
}
|
|
13
|
+
/** What the caller should write to each stream and exit with. */
|
|
6
14
|
export interface TbGitResult {
|
|
7
15
|
readonly exitCode: number;
|
|
8
16
|
readonly stderr: string;
|
package/dist/esm/bin/tb-git.d.ts
CHANGED
package/dist/esm/bin/tb-git.js
CHANGED
|
@@ -1,7 +1,12 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
1
|
import { resolveCheckedOutBranch } from "./resolveCheckedOutBranch.js";
|
|
3
2
|
import { resolveSelfVersion } from "./resolveSelfVersion.js";
|
|
4
3
|
import { runTbGit } from "./runTbGit.js";
|
|
4
|
+
for (const stream of [process.stdout, process.stderr]) {
|
|
5
|
+
stream.on('error', (error) => {
|
|
6
|
+
if (error.code !== 'EPIPE')
|
|
7
|
+
throw error;
|
|
8
|
+
});
|
|
9
|
+
}
|
|
5
10
|
const { exitCode, stderr, stdout } = runTbGit(process.argv.slice(2), {
|
|
6
11
|
resolveBranch: resolveCheckedOutBranch,
|
|
7
12
|
resolveVersion: resolveSelfVersion,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@williamthorsen/toolbelt.git",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Utilities for working with git",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"esm",
|
|
@@ -37,17 +37,18 @@
|
|
|
37
37
|
}
|
|
38
38
|
},
|
|
39
39
|
"bin": {
|
|
40
|
-
"tb-git": "./
|
|
40
|
+
"tb-git": "./bin/tb-git.js"
|
|
41
41
|
},
|
|
42
42
|
"files": [
|
|
43
|
-
"
|
|
44
|
-
"CHANGELOG.md"
|
|
43
|
+
"bin/*",
|
|
44
|
+
"CHANGELOG.md",
|
|
45
|
+
"dist/*"
|
|
45
46
|
],
|
|
46
47
|
"dependencies": {
|
|
47
|
-
"@williamthorsen/toolbelt.strings": "
|
|
48
|
+
"@williamthorsen/toolbelt.strings": "8.0.0"
|
|
48
49
|
},
|
|
49
50
|
"devDependencies": {
|
|
50
|
-
"@williamthorsen/toolbelt.
|
|
51
|
+
"@williamthorsen/toolbelt.testing": "0.6.0"
|
|
51
52
|
},
|
|
52
53
|
"engines": {
|
|
53
54
|
"node": ">=24.0.0"
|