@williamthorsen/toolbelt.git 0.4.2 → 0.5.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
@@ -2,6 +2,19 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## 0.5.1 — 2026-10-07
6
+
7
+ ### 📦 Dependencies
8
+
9
+ - Bumped `@williamthorsen/toolbelt.cli` to 0.3.0
10
+
11
+ ## 0.5.0 — 2026-10-06
12
+
13
+ ### 🎉 Features
14
+
15
+ - 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)
16
+ - Adds `-V` to `tb-git`, `tb-jira`, `tb-node`, and `tb-secret` as a short form of `--version`. (#365)
17
+
5
18
  ## 0.4.2 — 2026-10-02
6
19
 
7
20
  ### 📚 Documentation
package/README.md CHANGED
@@ -23,7 +23,7 @@ npx @williamthorsen/toolbelt.git branch-number # or run it without installing
23
23
 
24
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
25
 
26
- `tb-git --help`, each subcommand's `--help`, and `tb-git --version` report the surface and the installed version.
26
+ `tb-git --help`, each subcommand's `--help`, and `tb-git --version` (or `-V`) report the surface and the installed version.
27
27
 
28
28
  ### `tb-git branch-number [<branch>] [options]`
29
29
 
@@ -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;
@@ -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.2",
3
+ "version": "0.5.1",
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.3.0",
48
49
  "@williamthorsen/toolbelt.strings": "8.0.2"
49
50
  },
50
51
  "devDependencies": {