@williamthorsen/toolbelt.git 0.4.2 → 0.5.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 +7 -0
- package/README.md +9 -2
- package/dist/esm/bin/runTbGit.d.ts +1 -1
- package/dist/esm/bin/runTbGit.js +107 -118
- package/dist/esm/bin/tb-git.js +1 -1
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## 0.5.0 — 2026-10-06
|
|
6
|
+
|
|
7
|
+
### 🎉 Features
|
|
8
|
+
|
|
9
|
+
- Moves the argument parsing, dispatch, and help of `tb-git`, `tb-jira`, `tb-node`, and `tb-secret` to `@williamthorsen/toolbelt.cli`, which generates each command's help from its schema and reports a usage error as `Error: <message>`, followed by a `Did you mean` line for a mistyped command and a pointer to that command's `--help`. (#365)
|
|
10
|
+
- Adds `-V` to `tb-git`, `tb-jira`, `tb-node`, and `tb-secret` as a short form of `--version`. (#365)
|
|
11
|
+
|
|
5
12
|
## 0.4.2 — 2026-10-02
|
|
6
13
|
|
|
7
14
|
### 📚 Documentation
|
package/README.md
CHANGED
|
@@ -2,7 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
Utilities for working with git.
|
|
4
4
|
|
|
5
|
-
<!-- section:release-notes
|
|
5
|
+
<!-- section:release-notes -->
|
|
6
|
+
## Release notes — v0.5.0 (2026-10-06)
|
|
7
|
+
|
|
8
|
+
### 🎉 Features
|
|
9
|
+
|
|
10
|
+
- Moves the argument parsing, dispatch, and help of `tb-git`, `tb-jira`, `tb-node`, and `tb-secret` to `@williamthorsen/toolbelt.cli`, which generates each command's help from its schema and reports a usage error as `Error: <message>`, followed by a `Did you mean` line for a mistyped command and a pointer to that command's `--help`. (#365)
|
|
11
|
+
- Adds `-V` to `tb-git`, `tb-jira`, `tb-node`, and `tb-secret` as a short form of `--version`. (#365)
|
|
12
|
+
<!-- /section:release-notes -->
|
|
6
13
|
|
|
7
14
|
## Installation
|
|
8
15
|
|
|
@@ -23,7 +30,7 @@ npx @williamthorsen/toolbelt.git branch-number # or run it without installing
|
|
|
23
30
|
|
|
24
31
|
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
32
|
|
|
26
|
-
`tb-git --help`, each subcommand's `--help`, and `tb-git --version` report the surface and the installed version.
|
|
33
|
+
`tb-git --help`, each subcommand's `--help`, and `tb-git --version` (or `-V`) report the surface and the installed version.
|
|
27
34
|
|
|
28
35
|
### `tb-git branch-number [<branch>] [options]`
|
|
29
36
|
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
*
|
|
5
5
|
* @internal
|
|
6
6
|
*/
|
|
7
|
-
export declare function runTbGit(args: string[], effects: TbGitEffects): TbGitResult
|
|
7
|
+
export declare function runTbGit(args: string[], effects: TbGitEffects): Promise<TbGitResult>;
|
|
8
8
|
/** The effects deferred to the entry point, which keeps the runner free of I/O. */
|
|
9
9
|
export interface TbGitEffects {
|
|
10
10
|
readonly resolveBranch: () => string;
|
package/dist/esm/bin/runTbGit.js
CHANGED
|
@@ -1,135 +1,124 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { createCli, runCli, UsageError } from '@williamthorsen/toolbelt.cli/candidate';
|
|
2
2
|
import { deriveBranchNumber } from "../3-candidate/deriveBranchNumber.js";
|
|
3
3
|
import { findBranchTicketRef } from "../3-candidate/findBranchTicketRef.js";
|
|
4
|
-
const EXIT_OK = 0;
|
|
5
4
|
const EXIT_NO_RESULT = 1;
|
|
6
|
-
const
|
|
7
|
-
const
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
With no <branch>, the checked-out branch is used.
|
|
22
|
-
|
|
23
|
-
Exit codes:
|
|
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:
|
|
24
19
|
0 A result was printed
|
|
25
20
|
1 ticket-ref found no ticket in the branch name
|
|
26
|
-
2 Usage or validation error
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
Print
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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) {
|
|
50
101
|
try {
|
|
51
|
-
return
|
|
102
|
+
return await body();
|
|
52
103
|
}
|
|
53
104
|
catch (error) {
|
|
54
|
-
|
|
105
|
+
if (error instanceof UsageError)
|
|
106
|
+
throw error;
|
|
107
|
+
throw new UsageError(error instanceof Error ? error.message : String(error), { cause: error });
|
|
55
108
|
}
|
|
56
109
|
}
|
|
57
|
-
function
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
return runBranchNumber(rest, effects);
|
|
64
|
-
if (command === 'ticket-ref')
|
|
65
|
-
return runTicketRef(rest, effects);
|
|
66
|
-
if (command === '--help' || command === '-h')
|
|
67
|
-
return succeed(ROOT_HELP);
|
|
68
|
-
if (command === '--version')
|
|
69
|
-
return succeed(effects.resolveVersion());
|
|
70
|
-
if (command === undefined)
|
|
71
|
-
return fail('A subcommand is required.', command);
|
|
72
|
-
return fail(`Unknown ${command.startsWith('-') ? 'option' : 'subcommand'}: ${command}`, command);
|
|
73
|
-
}
|
|
74
|
-
function fail(message, command) {
|
|
75
|
-
const scope = command !== undefined && SUBCOMMANDS.has(command) ? `tb-git ${command}` : 'tb-git';
|
|
76
|
-
return { exitCode: EXIT_USAGE, stderr: `${message}\nTry \`${scope} --help\`.\n`, stdout: '' };
|
|
77
|
-
}
|
|
78
|
-
function runBranchNumber(args, effects) {
|
|
79
|
-
const { positionals, values } = parseArgs({
|
|
80
|
-
allowPositionals: true,
|
|
81
|
-
args,
|
|
82
|
-
options: {
|
|
83
|
-
...HELP_OPTION,
|
|
84
|
-
key: { type: 'string' },
|
|
85
|
-
max: { type: 'string' },
|
|
86
|
-
min: { type: 'string' },
|
|
87
|
-
offset: { type: 'string' },
|
|
88
|
-
},
|
|
89
|
-
strict: true,
|
|
90
|
-
});
|
|
91
|
-
if (values.help)
|
|
92
|
-
return succeed(BRANCH_NUMBER_HELP);
|
|
93
|
-
const number = deriveBranchNumber(selectBranch(positionals, effects), {
|
|
94
|
-
key: values.key,
|
|
95
|
-
max: toNumber('max', values.max),
|
|
96
|
-
min: toNumber('min', values.min),
|
|
97
|
-
offset: toNumber('offset', values.offset),
|
|
98
|
-
});
|
|
99
|
-
return succeed(String(number));
|
|
100
|
-
}
|
|
101
|
-
function runTicketRef(args, effects) {
|
|
102
|
-
const { positionals, values } = parseArgs({
|
|
103
|
-
allowPositionals: true,
|
|
104
|
-
args,
|
|
105
|
-
options: { ...HELP_OPTION, json: { type: 'boolean' }, key: { type: 'string' } },
|
|
106
|
-
strict: true,
|
|
107
|
-
});
|
|
108
|
-
if (values.help)
|
|
109
|
-
return succeed(TICKET_REF_HELP);
|
|
110
|
-
const ref = findBranchTicketRef(selectBranch(positionals, effects), { key: values.key });
|
|
111
|
-
if (ref === undefined)
|
|
112
|
-
return { exitCode: EXIT_NO_RESULT, stderr: '', stdout: '' };
|
|
113
|
-
return succeed(values.json === true ? JSON.stringify(ref) : ref.id);
|
|
114
|
-
}
|
|
115
|
-
function selectBranch(positionals, effects) {
|
|
116
|
-
if (positionals.length > 1) {
|
|
117
|
-
throw new Error(`Expected at most one branch name. Received ${positionals.length}.`);
|
|
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 });
|
|
118
116
|
}
|
|
119
|
-
|
|
117
|
+
}
|
|
118
|
+
function selectBranch(branch, effects) {
|
|
120
119
|
if (branch === undefined)
|
|
121
120
|
return effects.resolveBranch();
|
|
122
121
|
if (branch === '')
|
|
123
122
|
throw new Error('The branch name is empty. Omit it to use the checked-out branch.');
|
|
124
123
|
return branch;
|
|
125
124
|
}
|
|
126
|
-
function succeed(output) {
|
|
127
|
-
return { exitCode: EXIT_OK, stderr: '', stdout: `${output}\n` };
|
|
128
|
-
}
|
|
129
|
-
function toNumber(flag, value) {
|
|
130
|
-
if (value === undefined)
|
|
131
|
-
return undefined;
|
|
132
|
-
if (value.trim() === '')
|
|
133
|
-
throw new Error(`The value of --${flag} is empty.`);
|
|
134
|
-
return Number(value);
|
|
135
|
-
}
|
package/dist/esm/bin/tb-git.js
CHANGED
|
@@ -7,7 +7,7 @@ for (const stream of [process.stdout, process.stderr]) {
|
|
|
7
7
|
throw error;
|
|
8
8
|
});
|
|
9
9
|
}
|
|
10
|
-
const { exitCode, stderr, stdout } = runTbGit(process.argv.slice(2), {
|
|
10
|
+
const { exitCode, stderr, stdout } = await runTbGit(process.argv.slice(2), {
|
|
11
11
|
resolveBranch: resolveCheckedOutBranch,
|
|
12
12
|
resolveVersion: resolveSelfVersion,
|
|
13
13
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@williamthorsen/toolbelt.git",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Utilities for working with git",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"esm",
|
|
@@ -45,6 +45,7 @@
|
|
|
45
45
|
"dist/*"
|
|
46
46
|
],
|
|
47
47
|
"dependencies": {
|
|
48
|
+
"@williamthorsen/toolbelt.cli": "0.2.0",
|
|
48
49
|
"@williamthorsen/toolbelt.strings": "8.0.2"
|
|
49
50
|
},
|
|
50
51
|
"devDependencies": {
|