@williamthorsen/toolbelt.git 0.4.1 → 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 CHANGED
@@ -2,6 +2,20 @@
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
+
12
+ ## 0.4.2 — 2026-10-02
13
+
14
+ ### 📚 Documentation
15
+
16
+ - Audits the comments in every authored TypeScript, JavaScript, shell, and YAML source and every `tsconfig*.json` against the comment discipline, cutting comments that paraphrase the code or narrate history, rewriting doc descriptions in the third-person indicative, and adding descriptions to the functions, methods, and classes that had none. (#353)
17
+ - Revises READMEs, doc comments, and test names across the repository to follow the current `plain-speech` and writing-preference rules. (#354)
18
+
5
19
  ## 0.4.1 — 2026-09-17
6
20
 
7
21
  ### Dependency updates
package/README.md CHANGED
@@ -2,7 +2,14 @@
2
2
 
3
3
  Utilities for working with git.
4
4
 
5
- <!-- section:release-notes --><!-- /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
 
@@ -14,7 +21,7 @@ Requires Node.js 24 or later.
14
21
 
15
22
  ## CLI
16
23
 
17
- The package ships a `tb-git` command exposing the same functions to a shell caller.
24
+ The package provides a `tb-git` command exposing the same functions to a shell caller.
18
25
 
19
26
  ```sh
20
27
  pnpm add --global @williamthorsen/toolbelt.git # puts tb-git on PATH
@@ -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
 
@@ -41,7 +48,7 @@ tb-git branch-number 232_add-widget --min 3000 --max 3999
41
48
  # 3232
42
49
  ```
43
50
 
44
- A negative offset takes the `=` form, `--offset=-3`: A bare `-3` reads as an option rather than as the value.
51
+ A negative offset takes the `=` form, `--offset=-3`: A bare `-3` is parsed as an option rather than as the value.
45
52
 
46
53
  ### `tb-git ticket-ref [<branch>] [options]`
47
54
 
@@ -72,7 +79,7 @@ With no `<branch>`, both subcommands resolve the checked-out branch with `git br
72
79
  | `1` | `ticket-ref` found no ticket in the branch name; both streams are empty |
73
80
  | `2` | Usage or validation error, with the message on stderr |
74
81
 
75
- 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`.
82
+ `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
83
 
77
84
  ```sh
78
85
  if ref=$(tb-git ticket-ref); then
@@ -105,11 +112,11 @@ findBranchTicketRef('232_add-widget');
105
112
  // { id: '232', number: 232 }
106
113
  ```
107
114
 
108
- 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.
115
+ 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 is taken. Anchoring to a segment keeps a kebab-case description from being parsed as a ticket: `feat/add-widget-2` encodes none, because `widget` follows a hyphen rather than a separator.
109
116
 
110
117
  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`.
111
118
 
112
- 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.
119
+ 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 be parsed 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.
113
120
 
114
121
  ```ts
115
122
  findBranchTicketRef('mac-22/add-widget');
@@ -144,7 +151,7 @@ deriveBranchNumber('main');
144
151
  // 663286764
145
152
  ```
146
153
 
147
- 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.
154
+ 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 produce a number in one range, and `offset` stays a pure rotation.
148
155
 
149
156
  ```ts
150
157
  deriveBranchNumber('232_add-widget', { min: 3000, max: 3999 });
@@ -154,4 +161,4 @@ deriveBranchNumber('refactor/tidy-imports', { min: 3000, max: 3999 });
154
161
  // 3508
155
162
  ```
156
163
 
157
- A number that overruns the range wraps into it, so `deriveBranchNumber('1232', { max: 999 })` is `232`. `key` is passed through to `findBranchTicketRef`, and a bad `key`, bound, or offset raises the same `RangeError` whether or not the branch names a ticket.
164
+ A number that overruns the range wraps into it: `deriveBranchNumber('1232', { max: 999 })` is `232`. `key` is passed through to `findBranchTicketRef`, and a bad `key`, bound, or offset raises the same `RangeError` whether or not the branch names a ticket.
package/bin/tb-git.js CHANGED
@@ -4,12 +4,12 @@
4
4
  // dependency would replace this file's build-first message with ERR_MODULE_NOT_FOUND.
5
5
  import { existsSync } from 'node:fs';
6
6
 
7
- // Thin wrapper so pnpm can link the bin at install time, before `dist/` exists. The real entry point loads
7
+ // Thin wrapper so that pnpm can link the bin at install time, before `dist/` exists. The real entry point loads
8
8
  // at runtime from the build output.
9
9
  const entryPoint = new URL('../dist/esm/bin/tb-git.js', import.meta.url);
10
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
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
13
  // of its imports is missing.
14
14
  if (!existsSync(entryPoint)) {
15
15
  process.stderr.write(
@@ -1,6 +1,6 @@
1
1
  /**
2
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,
3
+ * `/`- or `_`-delimited segment, and the leftmost segment containing one is taken. A key must be uppercase,
4
4
  * unless `key` names the project's own key, which then matches in any casing and is the only key that
5
5
  * does; a bare-numeric ref is found either way. Throws a RangeError if `key` is not a well-formed key.
6
6
  *
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Finds the manifest of the package owning a directory, ascending to the first `package.json` declaring a
3
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.
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
6
  *
7
7
  * @internal
8
8
  */
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Reads the version declared by the package owning a directory, defaulting to this module's own, which is
3
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.
4
+ * Throws when the owning manifest declares no string version.
5
5
  *
6
6
  * @internal
7
7
  */
@@ -1,10 +1,10 @@
1
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.
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
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;
@@ -1,135 +1,124 @@
1
- import { parseArgs } from 'node:util';
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 EXIT_USAGE = 2;
7
- const SUBCOMMANDS = new Set(['branch-number', 'ticket-ref']);
8
- const HELP_OPTION = { help: { type: 'boolean', short: 'h' } };
9
- const ROOT_HELP = `Usage: tb-git <subcommand> [<branch>] [options]
10
-
11
- Utilities for working with git branch names.
12
-
13
- Subcommands:
14
- branch-number Print a stable number derived from a branch name
15
- ticket-ref Print the ID of the ticket encoded by a branch name
16
-
17
- Options:
18
- -h, --help Print this help; each subcommand takes its own --help
19
- --version Print the installed version
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
- const BRANCH_NUMBER_HELP = `Usage: tb-git branch-number [<branch>] [options]
28
-
29
- Print the number of the ticket encoded by the branch name, or a hash of the name when it encodes none.
30
-
31
- Options:
32
- -h, --help Print this help
33
- --key K The project's ticket key, matched in any casing
34
- --max N Upper bound, inclusive (default 4294967295)
35
- --min N Lower bound, inclusive (default 0)
36
- --offset N Rotate the result within the bounds; write a negative one as --offset=-3
37
-
38
- With no <branch>, the checked-out branch is used.`;
39
- const TICKET_REF_HELP = `Usage: tb-git ticket-ref [<branch>] [options]
40
-
41
- Print the ID of the ticket encoded by the branch name, exiting 1 when it encodes none.
42
-
43
- Options:
44
- -h, --help Print this help
45
- --json Print the whole ref on one line as JSON
46
- --key K The project's ticket key, matched in any casing
47
-
48
- With no <branch>, the checked-out branch is used.`;
49
- export function runTbGit(args, effects) {
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 dispatch(args, effects);
102
+ return await body();
52
103
  }
53
104
  catch (error) {
54
- return fail(describeError(error), args[0]);
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 describeError(error) {
58
- return error instanceof Error ? error.message : String(error);
59
- }
60
- function dispatch(args, effects) {
61
- const [command, ...rest] = args;
62
- if (command === 'branch-number')
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
- const [branch] = positionals;
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
- }
@@ -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.4.1",
3
+ "version": "0.5.0",
4
4
  "description": "Utilities for working with git",
5
5
  "keywords": [
6
6
  "esm",
@@ -45,10 +45,11 @@
45
45
  "dist/*"
46
46
  ],
47
47
  "dependencies": {
48
- "@williamthorsen/toolbelt.strings": "8.0.1"
48
+ "@williamthorsen/toolbelt.cli": "0.2.0",
49
+ "@williamthorsen/toolbelt.strings": "8.0.2"
49
50
  },
50
51
  "devDependencies": {
51
- "@williamthorsen/toolbelt.testing": "0.6.1"
52
+ "@williamthorsen/toolbelt.testing": "0.6.2"
52
53
  },
53
54
  "engines": {
54
55
  "node": ">=24.0.0"