@williamthorsen/toolbelt.git 0.5.3 â 0.6.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 +12 -0
- package/README.md +1 -65
- package/package.json +3 -8
- package/bin/tb-git.js +0 -27
- package/dist/esm/bin/findOwningManifest.d.ts +0 -15
- package/dist/esm/bin/findOwningManifest.js +0 -24
- package/dist/esm/bin/resolveCheckedOutBranch.d.ts +0 -8
- package/dist/esm/bin/resolveCheckedOutBranch.js +0 -17
- package/dist/esm/bin/resolveSelfVersion.d.ts +0 -8
- package/dist/esm/bin/resolveSelfVersion.js +0 -8
- package/dist/esm/bin/runTbGit.d.ts +0 -18
- package/dist/esm/bin/runTbGit.js +0 -124
- package/dist/esm/bin/tb-git.d.ts +0 -1
- package/dist/esm/bin/tb-git.js +0 -18
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## 0.6.1 â 2026-10-24
|
|
6
|
+
|
|
7
|
+
### ðĶ Dependencies
|
|
8
|
+
|
|
9
|
+
- Bumped `@williamthorsen/toolbelt.strings` to 8.0.4
|
|
10
|
+
|
|
11
|
+
## 0.6.0 â 2026-10-11
|
|
12
|
+
|
|
13
|
+
### ðŠĶ Removed
|
|
14
|
+
|
|
15
|
+
- ðĻ **Breaking:** Removes the `tb-git` command from `@williamthorsen/toolbelt.git`, whose `deriveBranchNumber` and `findBranchTicketRef` functions stay exported. (#383)
|
|
16
|
+
|
|
5
17
|
## 0.5.3 â 2026-10-11
|
|
6
18
|
|
|
7
19
|
### ðĶ Dependencies
|
package/README.md
CHANGED
|
@@ -14,71 +14,7 @@ Requires Node.js 24 or later.
|
|
|
14
14
|
|
|
15
15
|
## CLI
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
```sh
|
|
20
|
-
pnpm add --global @williamthorsen/toolbelt.git # puts tb-git on PATH
|
|
21
|
-
npx @williamthorsen/toolbelt.git branch-number # or run it without installing
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
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 ...`.
|
|
25
|
-
|
|
26
|
-
`tb-git --help`, each subcommand's `--help`, and `tb-git --version` (or `-V`) report the surface and the installed version.
|
|
27
|
-
|
|
28
|
-
### `tb-git branch-number [<branch>] [options]`
|
|
29
|
-
|
|
30
|
-
Prints [`deriveBranchNumber`](#derivebranchnumber)'s result.
|
|
31
|
-
|
|
32
|
-
| Option | Effect |
|
|
33
|
-
| ------------ | ----------------------------------------------- |
|
|
34
|
-
| `--key K` | The project's ticket key, matched in any casing |
|
|
35
|
-
| `--max N` | Upper bound, inclusive (default 4294967295) |
|
|
36
|
-
| `--min N` | Lower bound, inclusive (default 0) |
|
|
37
|
-
| `--offset N` | Rotate the result within the bounds |
|
|
38
|
-
|
|
39
|
-
```sh
|
|
40
|
-
tb-git branch-number 232_add-widget --min 3000 --max 3999
|
|
41
|
-
# 3232
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
A negative offset takes the `=` form, `--offset=-3`: A bare `-3` is parsed as an option rather than as the value.
|
|
45
|
-
|
|
46
|
-
### `tb-git ticket-ref [<branch>] [options]`
|
|
47
|
-
|
|
48
|
-
Prints [`findBranchTicketRef`](#findbranchticketref)'s `id`.
|
|
49
|
-
|
|
50
|
-
| Option | Effect |
|
|
51
|
-
| --------- | ----------------------------------------------- |
|
|
52
|
-
| `--json` | Print the whole ref on one line as JSON |
|
|
53
|
-
| `--key K` | The project's ticket key, matched in any casing |
|
|
54
|
-
|
|
55
|
-
```sh
|
|
56
|
-
tb-git ticket-ref wt/MAC-22.1-add-widget
|
|
57
|
-
# MAC-22
|
|
58
|
-
|
|
59
|
-
tb-git ticket-ref wt/MAC-22.1-add-widget --json
|
|
60
|
-
# {"id":"MAC-22","key":"MAC","number":22,"revisit":1}
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
### The branch argument
|
|
64
|
-
|
|
65
|
-
With no `<branch>`, both subcommands resolve the checked-out branch with `git branch --show-current`, which reports a worktree's own branch. A directory that is not a repository, an absent git, and a detached HEAD each fail rather than falling back to a derived value. An empty argument is an error too, so `tb-git ticket-ref "$BRANCH"` with `BRANCH` unset fails instead of quietly using the current branch.
|
|
66
|
-
|
|
67
|
-
### Exit codes
|
|
68
|
-
|
|
69
|
-
| Code | Meaning |
|
|
70
|
-
| ---- | ----------------------------------------------------------------------- |
|
|
71
|
-
| `0` | A result was printed |
|
|
72
|
-
| `1` | `ticket-ref` found no ticket in the branch name; both streams are empty |
|
|
73
|
-
| `2` | Usage or validation error, with the message on stderr |
|
|
74
|
-
|
|
75
|
-
`tb-git` exits `2` when the library rejects a bound, offset, or key, and reports the message that the library raises. It also exits `2` on an empty option value: `--min "$PORT_MIN"` with `PORT_MIN` unset fails instead of bounding at `0`.
|
|
76
|
-
|
|
77
|
-
```sh
|
|
78
|
-
if ref=$(tb-git ticket-ref); then
|
|
79
|
-
echo "on ticket $ref"
|
|
80
|
-
fi
|
|
81
|
-
```
|
|
17
|
+
For these functions on the command line, use `thor-git` from [`@williamthorsen/git-tools`](https://www.npmjs.com/package/@williamthorsen/git-tools).
|
|
82
18
|
|
|
83
19
|
## `findBranchTicketRef`
|
|
84
20
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@williamthorsen/toolbelt.git",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.1",
|
|
4
4
|
"description": "Utilities for working with git",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"esm",
|
|
@@ -36,20 +36,15 @@
|
|
|
36
36
|
"import": "./dist/esm/1-proposed/index.js"
|
|
37
37
|
}
|
|
38
38
|
},
|
|
39
|
-
"bin": {
|
|
40
|
-
"tb-git": "./bin/tb-git.js"
|
|
41
|
-
},
|
|
42
39
|
"files": [
|
|
43
|
-
"bin/*",
|
|
44
40
|
"CHANGELOG.md",
|
|
45
41
|
"dist/*"
|
|
46
42
|
],
|
|
47
43
|
"dependencies": {
|
|
48
|
-
"@williamthorsen/toolbelt.
|
|
49
|
-
"@williamthorsen/toolbelt.strings": "8.0.3"
|
|
44
|
+
"@williamthorsen/toolbelt.strings": "8.0.4"
|
|
50
45
|
},
|
|
51
46
|
"devDependencies": {
|
|
52
|
-
"@williamthorsen/toolbelt.testing": "0.
|
|
47
|
+
"@williamthorsen/toolbelt.testing": "0.7.0"
|
|
53
48
|
},
|
|
54
49
|
"engines": {
|
|
55
50
|
"node": ">=24.0.0"
|
package/bin/tb-git.js
DELETED
|
@@ -1,27 +0,0 @@
|
|
|
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 that 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: Because Node raises ERR_MODULE_NOT_FOUND for any unresolved module in the
|
|
12
|
-
// graph, 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,15 +0,0 @@
|
|
|
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 function returns the owning package's
|
|
5
|
-
* manifest rather than the nearest one. Throws when no ancestor declares a name.
|
|
6
|
-
*
|
|
7
|
-
* @internal
|
|
8
|
-
*/
|
|
9
|
-
export declare function findOwningManifest(startDir: string): OwningManifest;
|
|
10
|
-
export interface OwningManifest {
|
|
11
|
-
readonly manifest: {
|
|
12
|
-
readonly version?: unknown;
|
|
13
|
-
};
|
|
14
|
-
readonly manifestPath: string;
|
|
15
|
-
}
|
|
@@ -1,24 +0,0 @@
|
|
|
1
|
-
import fs from 'node:fs';
|
|
2
|
-
import path from 'node:path';
|
|
3
|
-
export function findOwningManifest(startDir) {
|
|
4
|
-
let dir = startDir;
|
|
5
|
-
for (;;) {
|
|
6
|
-
const manifestPath = path.join(dir, 'package.json');
|
|
7
|
-
if (fs.existsSync(manifestPath)) {
|
|
8
|
-
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
|
|
9
|
-
if (isNamedManifest(manifest))
|
|
10
|
-
return { manifest, manifestPath };
|
|
11
|
-
}
|
|
12
|
-
const parent = path.dirname(dir);
|
|
13
|
-
if (parent === dir)
|
|
14
|
-
throw new Error(`No package manifest declaring a name at or above ${startDir}.`);
|
|
15
|
-
dir = parent;
|
|
16
|
-
}
|
|
17
|
-
}
|
|
18
|
-
function isNamedManifest(value) {
|
|
19
|
-
return (typeof value === 'object' &&
|
|
20
|
-
value !== null &&
|
|
21
|
-
!Array.isArray(value) &&
|
|
22
|
-
'name' in value &&
|
|
23
|
-
typeof value.name === 'string');
|
|
24
|
-
}
|
|
@@ -1,8 +0,0 @@
|
|
|
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
|
-
*/
|
|
8
|
-
export declare function resolveCheckedOutBranch(): string;
|
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
import { spawnSync } from 'node:child_process';
|
|
2
|
-
const FAILURE_PREFIX = 'Could not resolve the checked-out branch with `git branch --show-current`:';
|
|
3
|
-
const FAILURE_SUFFIX = 'Pass a branch name explicitly.';
|
|
4
|
-
export function resolveCheckedOutBranch() {
|
|
5
|
-
const { error, status, stderr, stdout } = spawnSync('git', ['branch', '--show-current'], { encoding: 'utf8' });
|
|
6
|
-
if (error !== undefined)
|
|
7
|
-
throw failToResolve(error.message);
|
|
8
|
-
if (status !== 0)
|
|
9
|
-
throw failToResolve(stderr.trim());
|
|
10
|
-
const branch = stdout.trim();
|
|
11
|
-
if (branch === '')
|
|
12
|
-
throw failToResolve('HEAD names no branch.');
|
|
13
|
-
return branch;
|
|
14
|
-
}
|
|
15
|
-
function failToResolve(cause) {
|
|
16
|
-
return new Error(`${FAILURE_PREFIX} ${cause}\n${FAILURE_SUFFIX}`);
|
|
17
|
-
}
|
|
@@ -1,8 +0,0 @@
|
|
|
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 when the owning manifest declares no string version.
|
|
5
|
-
*
|
|
6
|
-
* @internal
|
|
7
|
-
*/
|
|
8
|
-
export declare function resolveSelfVersion(fromDir?: string): string;
|
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
import { findOwningManifest } from "./findOwningManifest.js";
|
|
2
|
-
export function resolveSelfVersion(fromDir = import.meta.dirname) {
|
|
3
|
-
const { manifest, manifestPath } = findOwningManifest(fromDir);
|
|
4
|
-
if (typeof manifest.version !== 'string') {
|
|
5
|
-
throw new TypeError(`No version declared in the package manifest at ${manifestPath}.`);
|
|
6
|
-
}
|
|
7
|
-
return manifest.version;
|
|
8
|
-
}
|
|
@@ -1,18 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Runs the `tb-git` command line, returning what to write and exit with rather than doing either, so that
|
|
3
|
-
* the whole surface is exercisable without a process. Every failure is reported through the result: Nothing throws.
|
|
4
|
-
*
|
|
5
|
-
* @internal
|
|
6
|
-
*/
|
|
7
|
-
export declare function runTbGit(args: string[], effects: TbGitEffects): Promise<TbGitResult>;
|
|
8
|
-
/** The effects deferred to the entry point, which keeps the runner free of I/O. */
|
|
9
|
-
export interface TbGitEffects {
|
|
10
|
-
readonly resolveBranch: () => string;
|
|
11
|
-
readonly resolveVersion: () => string;
|
|
12
|
-
}
|
|
13
|
-
/** What the caller should write to each stream and exit with. */
|
|
14
|
-
export interface TbGitResult {
|
|
15
|
-
readonly exitCode: number;
|
|
16
|
-
readonly stderr: string;
|
|
17
|
-
readonly stdout: string;
|
|
18
|
-
}
|
package/dist/esm/bin/runTbGit.js
DELETED
|
@@ -1,124 +0,0 @@
|
|
|
1
|
-
import { createCli, runCli, UsageError } from '@williamthorsen/toolbelt.cli/candidate';
|
|
2
|
-
import { deriveBranchNumber } from "../3-candidate/deriveBranchNumber.js";
|
|
3
|
-
import { findBranchTicketRef } from "../3-candidate/findBranchTicketRef.js";
|
|
4
|
-
const EXIT_NO_RESULT = 1;
|
|
5
|
-
const { defineCommand, defineGroup } = createCli();
|
|
6
|
-
const BRANCH_OPERAND = {
|
|
7
|
-
name: 'branch',
|
|
8
|
-
description: 'The branch name; the checked-out branch when omitted',
|
|
9
|
-
optional: true,
|
|
10
|
-
};
|
|
11
|
-
const KEY_FLAG = {
|
|
12
|
-
type: 'string',
|
|
13
|
-
description: "The project's ticket key, matched in any casing",
|
|
14
|
-
valueHint: 'key',
|
|
15
|
-
};
|
|
16
|
-
const ROOT = defineGroup({
|
|
17
|
-
summary: 'Utilities for working with git branch names.',
|
|
18
|
-
epilog: `Exit codes:
|
|
19
|
-
0 A result was printed
|
|
20
|
-
1 ticket-ref found no ticket in the branch name
|
|
21
|
-
2 Usage or validation error`,
|
|
22
|
-
commands: {
|
|
23
|
-
'branch-number': defineCommand({
|
|
24
|
-
summary: 'Print a stable number derived from a branch name',
|
|
25
|
-
description: 'Print the number of the ticket encoded by the branch name, or a hash of the name when it encodes none.',
|
|
26
|
-
epilog: 'Write a negative offset in the = form: --offset=-3.',
|
|
27
|
-
flags: {
|
|
28
|
-
key: KEY_FLAG,
|
|
29
|
-
max: {
|
|
30
|
-
type: 'string',
|
|
31
|
-
description: 'Upper bound, inclusive (default 4294967295)',
|
|
32
|
-
valueHint: 'n',
|
|
33
|
-
parse: parseNumber,
|
|
34
|
-
},
|
|
35
|
-
min: { type: 'string', description: 'Lower bound, inclusive (default 0)', valueHint: 'n', parse: parseNumber },
|
|
36
|
-
offset: {
|
|
37
|
-
type: 'string',
|
|
38
|
-
description: 'Rotate the result within the bounds',
|
|
39
|
-
valueHint: 'n',
|
|
40
|
-
parse: parseNumber,
|
|
41
|
-
},
|
|
42
|
-
},
|
|
43
|
-
operands: [BRANCH_OPERAND],
|
|
44
|
-
run: ({ context, flags, operands, stdout }) => reportFailures(() => {
|
|
45
|
-
const number = deriveBranchNumber(selectBranch(operands.branch, context), {
|
|
46
|
-
key: flags.key,
|
|
47
|
-
max: flags.max,
|
|
48
|
-
min: flags.min,
|
|
49
|
-
offset: flags.offset,
|
|
50
|
-
});
|
|
51
|
-
stdout.write(`${number}\n`);
|
|
52
|
-
}),
|
|
53
|
-
}),
|
|
54
|
-
'ticket-ref': defineCommand({
|
|
55
|
-
summary: 'Print the ID of the ticket encoded by a branch name',
|
|
56
|
-
description: 'Print the ID of the ticket encoded by the branch name, exiting 1 when it encodes none.',
|
|
57
|
-
flags: {
|
|
58
|
-
json: { type: 'boolean', description: 'Print the whole ref on one line as JSON' },
|
|
59
|
-
key: KEY_FLAG,
|
|
60
|
-
},
|
|
61
|
-
operands: [BRANCH_OPERAND],
|
|
62
|
-
run: ({ context, flags, operands, stdout }) => reportFailures(() => {
|
|
63
|
-
const ref = findBranchTicketRef(selectBranch(operands.branch, context), { key: flags.key });
|
|
64
|
-
if (ref === undefined)
|
|
65
|
-
return EXIT_NO_RESULT;
|
|
66
|
-
stdout.write(`${flags.json ? JSON.stringify(ref) : ref.id}\n`);
|
|
67
|
-
return;
|
|
68
|
-
}),
|
|
69
|
-
}),
|
|
70
|
-
},
|
|
71
|
-
});
|
|
72
|
-
export async function runTbGit(args, effects) {
|
|
73
|
-
const stdout = createTextBuffer();
|
|
74
|
-
const stderr = createTextBuffer();
|
|
75
|
-
const exitCode = await runCli(args, ROOT, {
|
|
76
|
-
name: 'tb-git',
|
|
77
|
-
context: effects,
|
|
78
|
-
version: () => resolveVersion(effects),
|
|
79
|
-
stdout,
|
|
80
|
-
stderr,
|
|
81
|
-
});
|
|
82
|
-
return { exitCode, stderr: stderr.text, stdout: stdout.text };
|
|
83
|
-
}
|
|
84
|
-
function createTextBuffer() {
|
|
85
|
-
let text = '';
|
|
86
|
-
return {
|
|
87
|
-
get text() {
|
|
88
|
-
return text;
|
|
89
|
-
},
|
|
90
|
-
write(chunk) {
|
|
91
|
-
text += chunk;
|
|
92
|
-
},
|
|
93
|
-
};
|
|
94
|
-
}
|
|
95
|
-
function parseNumber(value) {
|
|
96
|
-
if (value.trim() === '')
|
|
97
|
-
throw new Error('The value is blank.');
|
|
98
|
-
return Number(value);
|
|
99
|
-
}
|
|
100
|
-
async function reportFailures(body) {
|
|
101
|
-
try {
|
|
102
|
-
return await body();
|
|
103
|
-
}
|
|
104
|
-
catch (error) {
|
|
105
|
-
if (error instanceof UsageError)
|
|
106
|
-
throw error;
|
|
107
|
-
throw new UsageError(error instanceof Error ? error.message : String(error), { cause: error });
|
|
108
|
-
}
|
|
109
|
-
}
|
|
110
|
-
function resolveVersion(effects) {
|
|
111
|
-
try {
|
|
112
|
-
return effects.resolveVersion();
|
|
113
|
-
}
|
|
114
|
-
catch (error) {
|
|
115
|
-
throw new UsageError(error instanceof Error ? error.message : String(error), { cause: error });
|
|
116
|
-
}
|
|
117
|
-
}
|
|
118
|
-
function selectBranch(branch, effects) {
|
|
119
|
-
if (branch === undefined)
|
|
120
|
-
return effects.resolveBranch();
|
|
121
|
-
if (branch === '')
|
|
122
|
-
throw new Error('The branch name is empty. Omit it to use the checked-out branch.');
|
|
123
|
-
return branch;
|
|
124
|
-
}
|
package/dist/esm/bin/tb-git.d.ts
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|
package/dist/esm/bin/tb-git.js
DELETED
|
@@ -1,18 +0,0 @@
|
|
|
1
|
-
import { resolveCheckedOutBranch } from "./resolveCheckedOutBranch.js";
|
|
2
|
-
import { resolveSelfVersion } from "./resolveSelfVersion.js";
|
|
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
|
-
}
|
|
10
|
-
const { exitCode, stderr, stdout } = await runTbGit(process.argv.slice(2), {
|
|
11
|
-
resolveBranch: resolveCheckedOutBranch,
|
|
12
|
-
resolveVersion: resolveSelfVersion,
|
|
13
|
-
});
|
|
14
|
-
if (stdout !== '')
|
|
15
|
-
process.stdout.write(stdout);
|
|
16
|
-
if (stderr !== '')
|
|
17
|
-
process.stderr.write(stderr);
|
|
18
|
-
process.exitCode = exitCode;
|