@williamthorsen/toolbelt.secrets 0.3.1 โ†’ 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 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.4.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.3.1 โ€” 2026-10-02
6
13
 
7
14
  ### ๐Ÿงช Tests
package/README.md CHANGED
@@ -2,7 +2,14 @@
2
2
 
3
3
  Utilities for storing and retrieving secrets in the OS credential store.
4
4
 
5
- <!-- section:release-notes --><!-- /section:release-notes -->
5
+ <!-- section:release-notes -->
6
+ ## Release notes โ€” v0.4.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
 
@@ -31,7 +38,7 @@ pnpm add --global @williamthorsen/toolbelt.secrets # puts tb-secret on PATH
31
38
  npx @williamthorsen/toolbelt.secrets get my-token # or run it without installing
32
39
  ```
33
40
 
34
- `tb-secret --help`, each subcommand's `--help`, and `tb-secret --version` report the surface and the installed version.
41
+ `tb-secret --help`, each subcommand's `--help`, and `tb-secret --version` (or `-V`) report the surface and the installed version.
35
42
 
36
43
  | Subcommand | Effect |
37
44
  | ---------------------------- | ---------------------------------------------------- |
@@ -1,65 +1,76 @@
1
- import { parseArgs } from 'node:util';
1
+ import { createCli, runCli, UsageError } from '@williamthorsen/toolbelt.cli/candidate';
2
2
  import { UnstorableSecretError } from "../3-candidate/UnstorableSecretError.js";
3
3
  const EXIT_OK = 0;
4
4
  const EXIT_NO_RESULT = 1;
5
- const EXIT_USAGE = 2;
6
5
  const EXIT_KEYSTORE = 3;
7
- const SUBCOMMANDS = new Set(['delete', 'get', 'has', 'set']);
8
- const ACCOUNT_OPTION = { account: { type: 'string', short: 'a' } };
9
- const HELP_OPTION = { help: { type: 'boolean', short: 'h' } };
10
- const KEYCHAIN_OPTION = { keychain: { type: 'string', short: 'k' } };
11
- const ROOT_HELP = `Usage: tb-secret <subcommand> <service> [options]
12
-
13
- Store and read secrets in the macOS keychain. Requires macOS.
14
-
15
- Subcommands:
16
- delete Remove a secret
17
- get Print a secret
18
- has Report whether a secret is stored, printing nothing
19
- set Store a secret
20
-
21
- Options:
22
- -h, --help Print this help; each subcommand takes its own --help
23
- --version Print the installed version
24
-
25
- A secret is named by a service and an optional account, so one service can hold a secret per account. An item
6
+ const { defineCommand, defineGroup } = createCli();
7
+ const SERVICE_OPERAND = { name: 'service', description: 'The service that names the secret' };
8
+ const SECRET_FLAGS = {
9
+ account: {
10
+ type: 'string',
11
+ description: 'Account holding the secret (default: the empty account)',
12
+ short: 'a',
13
+ valueHint: 'name',
14
+ },
15
+ keychain: {
16
+ type: 'string',
17
+ description: 'Keychain to act on, rather than the default search list',
18
+ short: 'k',
19
+ valueHint: 'path',
20
+ },
21
+ };
22
+ const ROOT = defineGroup({
23
+ summary: 'Store and read secrets in the macOS keychain. Requires macOS.',
24
+ epilog: `A secret is named by a service and an optional account, so one service can hold a secret per account. An item
26
25
  is local to this Mac: \`security\` offers no iCloud Keychain synchronization.
27
26
 
28
27
  Exit codes:
29
28
  0 The command succeeded
30
29
  1 No secret is stored under that service and account
31
30
  2 Usage or validation error
32
- 3 The keychain could not be reached`;
33
- const DELETE_HELP = `Usage: tb-secret delete <service> [options]
34
-
35
- Remove a secret, exiting 1 when none is stored.
36
-
37
- Options:
38
- -h, --help Print this help
39
- -a, --account <name> Account holding the secret (default: the empty account)
40
- -k, --keychain <path> Keychain to act on, rather than the default search list`;
41
- const GET_HELP = `Usage: tb-secret get <service> [options]
42
-
43
- Print a secret, exiting 1 when none is stored.
44
-
45
- Options:
46
- -h, --help Print this help
47
- -a, --account <name> Account holding the secret (default: the empty account)
48
- -k, --keychain <path> Keychain to read, rather than the default search list`;
49
- const HAS_HELP = `Usage: tb-secret has <service> [options]
50
-
51
- Exit 0 when a secret is stored and 1 when none is, printing nothing either way. The secret itself is never
52
- read, so this raises no keychain access prompt.
53
-
54
- Options:
55
- -h, --help Print this help
56
- -a, --account <name> Account holding the secret (default: the empty account)
57
- -k, --keychain <path> Keychain to read, rather than the default search list`;
58
- const SET_HELP = `Usage: tb-secret set <service> [options]
59
-
60
- Store a secret, replacing one already stored under the same service and account.
61
-
62
- At a terminal the secret is prompted for twice and echoed nowhere; piped, it is read from stdin and one
31
+ 3 The keychain could not be reached`,
32
+ commands: {
33
+ delete: defineCommand({
34
+ summary: 'Remove a secret',
35
+ description: 'Remove a secret, exiting 1 when none is stored.',
36
+ flags: SECRET_FLAGS,
37
+ operands: [SERVICE_OPERAND],
38
+ run: ({ context, flags, operands, stderr }) => reportFailures(stderr, () => {
39
+ const query = buildQuery(operands.service, flags.account);
40
+ const removed = callKeystore(() => context.createStore(flags.keychain).deleteSecret(query));
41
+ return removed ? EXIT_OK : EXIT_NO_RESULT;
42
+ }),
43
+ }),
44
+ get: defineCommand({
45
+ summary: 'Print a secret',
46
+ description: 'Print a secret, exiting 1 when none is stored.',
47
+ flags: SECRET_FLAGS,
48
+ operands: [SERVICE_OPERAND],
49
+ run: ({ context, flags, operands, stderr, stdout }) => reportFailures(stderr, () => {
50
+ const query = buildQuery(operands.service, flags.account);
51
+ const secret = callKeystore(() => context.createStore(flags.keychain).findSecret(query));
52
+ if (secret === undefined)
53
+ return EXIT_NO_RESULT;
54
+ stdout.write(`${secret}\n`);
55
+ return EXIT_OK;
56
+ }),
57
+ }),
58
+ has: defineCommand({
59
+ summary: 'Report whether a secret is stored, printing nothing',
60
+ description: `Exit 0 when a secret is stored and 1 when none is, printing nothing either way. The secret itself is never
61
+ read, so this raises no keychain access prompt.`,
62
+ flags: SECRET_FLAGS,
63
+ operands: [SERVICE_OPERAND],
64
+ run: ({ context, flags, operands, stderr }) => reportFailures(stderr, () => {
65
+ const query = buildQuery(operands.service, flags.account);
66
+ const stored = callKeystore(() => context.createStore(flags.keychain).hasSecret(query));
67
+ return stored ? EXIT_OK : EXIT_NO_RESULT;
68
+ }),
69
+ }),
70
+ set: defineCommand({
71
+ summary: 'Store a secret',
72
+ description: 'Store a secret, replacing one already stored under the same service and account.',
73
+ epilog: `At a terminal the secret is prompted for twice and echoed nowhere; piped, it is read from stdin and one
63
74
  trailing newline is dropped, since \`echo\` adds one. Either way it is passed to \`security\` inside a command
64
75
  sent on stdin, so it never enters an argument vector that any local process could read.
65
76
 
@@ -68,26 +79,31 @@ another program created can therefore raise a keychain access prompt, since veri
68
79
  secret.
69
80
 
70
81
  A secret can be about 2,000 bytes long. The exact ceiling depends on the service, account, and keychain, which
71
- share one 4,095-byte command line with it; a secret that would not fit is refused rather than stored in part.
72
-
73
- Options:
74
- -h, --help Print this help
75
- -a, --account <name> Account to hold the secret (default: the empty account)
76
- -k, --keychain <path> Keychain to write to, rather than the default search list`;
82
+ share one 4,095-byte command line with it; a secret that would not fit is refused rather than stored in part.`,
83
+ flags: SECRET_FLAGS,
84
+ operands: [SERVICE_OPERAND],
85
+ run: ({ context, flags, operands, stderr }) => reportFailures(stderr, () => runSet(operands.service, flags, context)),
86
+ }),
87
+ },
88
+ });
77
89
  export async function runTbSecret(args, effects) {
78
- try {
79
- return await dispatch(args, effects);
80
- }
81
- catch (error) {
82
- if (error instanceof KeystoreError)
83
- return { exitCode: EXIT_KEYSTORE, stderr: `${error.message}\n`, stdout: '' };
84
- return fail(describeError(error), args[0]);
85
- }
90
+ const stdout = createTextBuffer();
91
+ const stderr = createTextBuffer();
92
+ const exitCode = await runCli(args, ROOT, {
93
+ name: 'tb-secret',
94
+ context: effects,
95
+ version: () => resolveVersion(effects),
96
+ stdout,
97
+ stderr,
98
+ });
99
+ return { exitCode, stderr: stderr.text, stdout: stdout.text };
86
100
  }
87
101
  class KeystoreError extends Error {
88
102
  }
89
- function buildQuery(positionals, account) {
90
- return { account, service: selectService(positionals) };
103
+ function buildQuery(service, account) {
104
+ if (service === '')
105
+ throw new Error('The service name is empty.');
106
+ return { account, service };
91
107
  }
92
108
  function callKeystore(operation) {
93
109
  try {
@@ -99,105 +115,50 @@ function callKeystore(operation) {
99
115
  throw new KeystoreError(describeError(error));
100
116
  }
101
117
  }
118
+ function createTextBuffer() {
119
+ let text = '';
120
+ return {
121
+ get text() {
122
+ return text;
123
+ },
124
+ write(chunk) {
125
+ text += chunk;
126
+ },
127
+ };
128
+ }
102
129
  function describeError(error) {
103
130
  return error instanceof Error ? error.message : String(error);
104
131
  }
105
- async function dispatch(args, effects) {
106
- const [command, ...rest] = args;
107
- if (command === 'delete')
108
- return runDelete(rest, effects);
109
- if (command === 'get')
110
- return runGet(rest, effects);
111
- if (command === 'has')
112
- return runHas(rest, effects);
113
- if (command === 'set')
114
- return await runSet(rest, effects);
115
- if (command === '--help' || command === '-h')
116
- return succeed(ROOT_HELP);
117
- if (command === '--version')
118
- return succeed(effects.resolveVersion());
119
- if (command === undefined)
120
- return fail('A subcommand is required.', command);
121
- return fail(`Unknown ${command.startsWith('-') ? 'option' : 'subcommand'}: ${command}`, command);
122
- }
123
- function fail(message, command) {
124
- const scope = command !== undefined && SUBCOMMANDS.has(command) ? `tb-secret ${command}` : 'tb-secret';
125
- return { exitCode: EXIT_USAGE, stderr: `${message}\nTry \`${scope} --help\`.\n`, stdout: '' };
126
- }
127
- function runDelete(args, effects) {
128
- const { positionals, values } = parseArgs({
129
- allowPositionals: true,
130
- args,
131
- options: { ...ACCOUNT_OPTION, ...HELP_OPTION, ...KEYCHAIN_OPTION },
132
- strict: true,
133
- });
134
- if (values.help === true)
135
- return succeed(DELETE_HELP);
136
- const query = buildQuery(positionals, values.account);
137
- const removed = callKeystore(() => effects.createStore(values.keychain).deleteSecret(query));
138
- return removed ? succeedSilently() : reportNoResult();
139
- }
140
- function runGet(args, effects) {
141
- const { positionals, values } = parseArgs({
142
- allowPositionals: true,
143
- args,
144
- options: { ...ACCOUNT_OPTION, ...HELP_OPTION, ...KEYCHAIN_OPTION },
145
- strict: true,
146
- });
147
- if (values.help === true)
148
- return succeed(GET_HELP);
149
- const query = buildQuery(positionals, values.account);
150
- const secret = callKeystore(() => effects.createStore(values.keychain).findSecret(query));
151
- return secret === undefined ? reportNoResult() : succeed(secret);
132
+ async function reportFailures(stderr, body) {
133
+ try {
134
+ return await body();
135
+ }
136
+ catch (error) {
137
+ if (error instanceof UsageError)
138
+ throw error;
139
+ if (error instanceof KeystoreError) {
140
+ stderr.write(`${error.message}\n`);
141
+ return EXIT_KEYSTORE;
142
+ }
143
+ throw new UsageError(describeError(error), { cause: error });
144
+ }
152
145
  }
153
- function runHas(args, effects) {
154
- const { positionals, values } = parseArgs({
155
- allowPositionals: true,
156
- args,
157
- options: { ...ACCOUNT_OPTION, ...HELP_OPTION, ...KEYCHAIN_OPTION },
158
- strict: true,
159
- });
160
- if (values.help === true)
161
- return succeed(HAS_HELP);
162
- const query = buildQuery(positionals, values.account);
163
- const stored = callKeystore(() => effects.createStore(values.keychain).hasSecret(query));
164
- return stored ? succeedSilently() : reportNoResult();
146
+ function resolveVersion(effects) {
147
+ try {
148
+ return effects.resolveVersion();
149
+ }
150
+ catch (error) {
151
+ throw new UsageError(describeError(error), { cause: error });
152
+ }
165
153
  }
166
- async function runSet(args, effects) {
167
- const { positionals, values } = parseArgs({
168
- allowPositionals: true,
169
- args,
170
- options: { ...ACCOUNT_OPTION, ...HELP_OPTION, ...KEYCHAIN_OPTION },
171
- strict: true,
172
- });
173
- if (values.help === true)
174
- return succeed(SET_HELP);
175
- const query = buildQuery(positionals, values.account);
176
- const store = callKeystore(() => effects.createStore(values.keychain));
154
+ async function runSet(service, flags, effects) {
155
+ const query = buildQuery(service, flags.account);
156
+ const store = callKeystore(() => effects.createStore(flags.keychain));
177
157
  const secret = effects.isStdinTty()
178
158
  ? await effects.promptSecret()
179
159
  : stripOneTrailingNewline(await effects.readStdin());
180
160
  callKeystore(() => store.setSecret(query, secret));
181
- return succeedSilently();
182
- }
183
- function reportNoResult() {
184
- return { exitCode: EXIT_NO_RESULT, stderr: '', stdout: '' };
185
- }
186
- function selectService(positionals) {
187
- if (positionals.length > 1)
188
- throw new Error(`Expected one service name. Received ${positionals.length}.`);
189
- const [service] = positionals;
190
- if (service === undefined)
191
- throw new Error('A service name is required.');
192
- if (service === '')
193
- throw new Error('The service name is empty.');
194
- return service;
195
- }
196
- function succeed(output) {
197
- return { exitCode: EXIT_OK, stderr: '', stdout: `${output}\n` };
198
- }
199
- function succeedSilently() {
200
- return { exitCode: EXIT_OK, stderr: '', stdout: '' };
161
+ return EXIT_OK;
201
162
  }
202
163
  function stripOneTrailingNewline(input) {
203
164
  return input.replace(/\r?\n$/, '');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@williamthorsen/toolbelt.secrets",
3
- "version": "0.3.1",
3
+ "version": "0.4.0",
4
4
  "description": "Utilities for storing and retrieving secrets in the OS credential store",
5
5
  "keywords": [
6
6
  "credentials",
@@ -47,6 +47,9 @@
47
47
  "CHANGELOG.md",
48
48
  "dist/*"
49
49
  ],
50
+ "dependencies": {
51
+ "@williamthorsen/toolbelt.cli": "0.2.0"
52
+ },
50
53
  "devDependencies": {
51
54
  "@williamthorsen/toolbelt.testing": "0.6.2"
52
55
  },