@imagile-dev/toil 0.1.0-beta.1 → 0.1.0-beta.3
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/README.md +4 -4
- package/dist/api.d.ts +142 -134
- package/dist/toil-lib.js +124313 -120920
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -50,7 +50,7 @@ the released `0.1.0-alpha.2`:
|
|
|
50
50
|
|
|
51
51
|
```console
|
|
52
52
|
$ toil util size package.json --select "{bytes: bytes, tokens: tokens}"
|
|
53
|
-
{"ok":true,"data":{"bytes":2162,"tokens":541},"error":null,"meta":{"command":"util size","durationMs":90,"version":"0.1.0-alpha.2","contractVersion":
|
|
53
|
+
{"ok":true,"data":{"bytes":2162,"tokens":541},"error":null,"meta":{"command":"util size","durationMs":90,"version":"0.1.0-alpha.2","contractVersion":2,"warnings":[{"code":"APPROXIMATED","message":"tokens is approximate: ceil(characters / 4) per file, counting characters as Unicode code points. An estimate, not any model's tokenizer: real counts vary by model and by content."}]}}
|
|
54
54
|
```
|
|
55
55
|
|
|
56
56
|
The estimate says it's an estimate. Every result says where it came from and how
|
|
@@ -190,13 +190,13 @@ Code the clone is also a plugin marketplace: `claude plugin marketplace add
|
|
|
190
190
|
| [`util`](https://imagile-dev.github.io/toil/docs/utilities/) | Local commands with no connection or network: JWTs, dependency inventories, encodings and hashes, certificates, test and coverage reports, logs, secret scans, time and versions, Jira and Confluence markup, OpenAPI |
|
|
191
191
|
| [`skills`](https://imagile-dev.github.io/toil/docs/skills/) | Add a git-hosted skills marketplace, install its plugins for Codex, GitHub Copilot or Claude Code, switch them on and off |
|
|
192
192
|
| [The toil skill](https://imagile-dev.github.io/toil/docs/) | toil's own command reference for agents, one file per area |
|
|
193
|
-
| [Work tracking](https://imagile-dev.github.io/toil/connect/#trackers) (
|
|
194
|
-
| [Source and review](https://imagile-dev.github.io/toil/connect/#source) (
|
|
193
|
+
| [Work tracking](https://imagile-dev.github.io/toil/connect/#trackers) (2) | Jira (Data Center and Cloud), Azure DevOps Server and Services |
|
|
194
|
+
| [Source and review](https://imagile-dev.github.io/toil/connect/#source) (3) | GitHub & GitHub Enterprise, Bitbucket (Data Center and Cloud), local git |
|
|
195
195
|
| [CI/CD and runtime](https://imagile-dev.github.io/toil/connect/#cicd) (3) | Jenkins, JFrog Artifactory, OpenShift / Kubernetes |
|
|
196
196
|
| [Testing and flags](https://imagile-dev.github.io/toil/connect/#testing) (2) | Sauce Labs, Split.IO |
|
|
197
197
|
| [Security and quality](https://imagile-dev.github.io/toil/connect/#security) (7) | Checkmarx One, Contrast Security, SD Elements, SonarQube, Sonatype IQ Server, Sonatype OSS Index, OSV.dev |
|
|
198
198
|
| [Observability](https://imagile-dev.github.io/toil/connect/#observability) (4) | Dynatrace, Elasticsearch, Kibana, Falcon LogScale |
|
|
199
|
-
| [Docs and design](https://imagile-dev.github.io/toil/connect/#docs) (
|
|
199
|
+
| [Docs and design](https://imagile-dev.github.io/toil/connect/#docs) (3) | Confluence (Data Center and Cloud), Figma, Alation |
|
|
200
200
|
|
|
201
201
|
Every integration that needs a credential signs in with a long-lived token you
|
|
202
202
|
generate once in the vendor's UI. Every integration records how far it has been
|
package/dist/api.d.ts
CHANGED
|
@@ -16,7 +16,11 @@ type ErrorCode = 'INVALID_INPUT' | 'NOT_CONFIGURED' | 'CONFIG_INVALID' | 'AUTH'
|
|
|
16
16
|
| 'UNSUPPORTED_NODE'
|
|
17
17
|
/** A command that runs git found no usable git on PATH. Nothing else needs git. */
|
|
18
18
|
| 'GIT_NOT_FOUND'
|
|
19
|
-
/**
|
|
19
|
+
/**
|
|
20
|
+
* The server is a release without an API the command needs (sub-issues or
|
|
21
|
+
* Projects on an older GitHub Enterprise Server), or the connection's
|
|
22
|
+
* deployment has no such command or flag (`jira project list` on Data Center).
|
|
23
|
+
*/
|
|
20
24
|
| 'UNSUPPORTED' | 'INTERNAL';
|
|
21
25
|
|
|
22
26
|
/** How a transition was chosen, as meta.transition reports it. */
|
|
@@ -152,6 +156,8 @@ interface ContextValue {
|
|
|
152
156
|
default?: 'named' | 'area-name' | 'only';
|
|
153
157
|
/** For `connection` from a dossier's host selector: the host it matched. A selector, never contacted. */
|
|
154
158
|
host?: string;
|
|
159
|
+
/** For `connection`, in an area that serves more than one deployment (`jira`): which one ran, `server` or `cloud`. */
|
|
160
|
+
deployment?: string;
|
|
155
161
|
}
|
|
156
162
|
/** The dossier a call used (docs/dossiers.md), and how it was found. Never a value from a connection. */
|
|
157
163
|
interface DossierReport {
|
|
@@ -218,139 +224,6 @@ type Envelope<T = unknown> = {
|
|
|
218
224
|
meta: Meta;
|
|
219
225
|
};
|
|
220
226
|
|
|
221
|
-
/**
|
|
222
|
-
* Progress events: what a long command is doing while it runs, for a caller
|
|
223
|
-
* that wants to show it (a sync's progress bar, a person at a terminal). They
|
|
224
|
-
* never change the result: the envelope is the same with or without a
|
|
225
|
-
* listener, and nothing in them is a header, a body or a credential.
|
|
226
|
-
*
|
|
227
|
-
* Core reports them, never an area. execute() runs each command inside
|
|
228
|
-
* `withProgress`, and the shared machinery (the paging loop, the 429 retry,
|
|
229
|
-
* the instrumented fetch) calls `reportProgress`, which finds the listener
|
|
230
|
-
* through AsyncLocalStorage. An area that pages through `paginate()` or sends
|
|
231
|
-
* through `restRequest` reports progress without a line of its own, which is
|
|
232
|
-
* the only way a status report has ever been filed on time.
|
|
233
|
-
*/
|
|
234
|
-
/** One HTTP request finished: its method, redacted URL, status (null when it failed to answer) and time. */
|
|
235
|
-
interface RequestProgress {
|
|
236
|
-
type: 'request';
|
|
237
|
-
method: string;
|
|
238
|
-
url: string;
|
|
239
|
-
status: number | null;
|
|
240
|
-
durationMs: number;
|
|
241
|
-
}
|
|
242
|
-
/** One page of a paged listing was read: its number in this call (from 1), and the items read so far, this page's included. */
|
|
243
|
-
interface PageProgress {
|
|
244
|
-
type: 'page';
|
|
245
|
-
page: number;
|
|
246
|
-
items: number;
|
|
247
|
-
/** What is being listed, when the command said ("Jira sprints for board 7"). */
|
|
248
|
-
what?: string;
|
|
249
|
-
}
|
|
250
|
-
/** A 429 is being retried: the attempt that was refused, how long toil waits before the next, and the redacted URL. */
|
|
251
|
-
interface RetryProgress {
|
|
252
|
-
type: 'retry';
|
|
253
|
-
attempt: number;
|
|
254
|
-
waitMs: number;
|
|
255
|
-
status: number;
|
|
256
|
-
url: string;
|
|
257
|
-
}
|
|
258
|
-
/** What core reports, before execute() adds the command and the message. */
|
|
259
|
-
type ProgressBody = RequestProgress | PageProgress | RetryProgress;
|
|
260
|
-
/** A progress event as a listener gets it: the command it belongs to, and one line saying it in words. */
|
|
261
|
-
type ProgressEvent = ProgressBody & {
|
|
262
|
-
command: string;
|
|
263
|
-
message: string;
|
|
264
|
-
};
|
|
265
|
-
|
|
266
|
-
/**
|
|
267
|
-
* What a command is, which decides what core hands it and which front doors
|
|
268
|
-
* serve it. One field instead of three flags that could disagree:
|
|
269
|
-
*
|
|
270
|
-
* - `standalone`: no area, no config, no connection (`version`). Always served
|
|
271
|
-
* by `toil mcp`; a broken config file can't stop it.
|
|
272
|
-
* - `area`: an area command with one resolved connection (`jira issue get`).
|
|
273
|
-
* - `area-local`: lives under an area's path but needs no connection and no
|
|
274
|
-
* config (`jira issue schema`). Served by `toil mcp` whether or not the area is set up.
|
|
275
|
-
* - `config`: reads or changes the user's connections and gets `ctx.manage`
|
|
276
|
-
* (`connections list`). Served by `toil mcp`.
|
|
277
|
-
* - `cli-only`: a `config` command that runs on the CLI only (`connections
|
|
278
|
-
* add`): it prompts on a terminal, or changes connections, which an agent
|
|
279
|
-
* never does. Never an MCP tool, and not subject to the time limit, since it
|
|
280
|
-
* may be waiting on someone typing.
|
|
281
|
-
*/
|
|
282
|
-
type CommandKind = 'standalone' | 'area' | 'area-local' | 'config' | 'cli-only';
|
|
283
|
-
|
|
284
|
-
/**
|
|
285
|
-
* What a pasted secret looks like when it arrives, checked before it goes to
|
|
286
|
-
* the OS credential store (#358). One function, `checkSecret()`, decides every
|
|
287
|
-
* case, and every way of entering a secret uses it: the CLI's terminal
|
|
288
|
-
* prompter (through `askCheckedSecret()`), a host's `person` through the API,
|
|
289
|
-
* and Toil UI's password fields, which run it in the page. So a terminal and
|
|
290
|
-
* a form say the same thing in the same words, and can't drift apart.
|
|
291
|
-
*
|
|
292
|
-
* Nothing here shows any part of the value: not a prefix, not a suffix, not a
|
|
293
|
-
* hash. What it reports is the length, the whitespace it took off the ends,
|
|
294
|
-
* and the wrapper it found ("Bearer ", "token ", quotes), which is boilerplate
|
|
295
|
-
* and never the secret. A paste is checked for the usual accidents, the way a
|
|
296
|
-
* form is checked for a missing signature, except that this one tells you which box.
|
|
297
|
-
*/
|
|
298
|
-
|
|
299
|
-
/** How a secret is asked for. */
|
|
300
|
-
interface SecretRules {
|
|
301
|
-
/** A password rather than a token: a space inside it is allowed, since people put them in passwords. */
|
|
302
|
-
password?: boolean;
|
|
303
|
-
/**
|
|
304
|
-
* What an empty answer means: ask again, since the connection needs one
|
|
305
|
-
* (`required`); keep the secret already stored (`keep`, `login` on an
|
|
306
|
-
* existing connection); or store none (`skip`, an optional one).
|
|
307
|
-
*/
|
|
308
|
-
empty: 'required' | 'keep' | 'skip';
|
|
309
|
-
/**
|
|
310
|
-
* The env vars that define this connection with no file at all
|
|
311
|
-
* (`TOIL_CONN_<NAME>_AREA=<area>`, then each setting and secret), named in
|
|
312
|
-
* the fix for an empty required secret, so a machine with no credential store
|
|
313
|
-
* has a way out that isn't Ctrl+C alone. Only the whole set works: a variable
|
|
314
|
-
* for a connection that was never saved names no connection.
|
|
315
|
-
*/
|
|
316
|
-
envVars?: readonly string[];
|
|
317
|
-
}
|
|
318
|
-
/** A wrapper around the value that the person is asked to remove: quotes, or a `Bearer ` / `token ` prefix. */
|
|
319
|
-
interface SecretWrapper {
|
|
320
|
-
/** The value without it. */
|
|
321
|
-
without: string;
|
|
322
|
-
/** Its length, in characters. */
|
|
323
|
-
withoutLength: number;
|
|
324
|
-
/** The question: `This starts with "Bearer ". Store it without that? [Y/n]`. */
|
|
325
|
-
question: string;
|
|
326
|
-
/** What it is, for a button: `"Bearer "`, `the quotes`. */
|
|
327
|
-
what: string;
|
|
328
|
-
}
|
|
329
|
-
type SecretCheck = {
|
|
330
|
-
status: 'empty';
|
|
331
|
-
empty: SecretRules['empty'];
|
|
332
|
-
/** `Kept the existing secret.`, or why an empty answer won't do. */
|
|
333
|
-
message: string;
|
|
334
|
-
/** Set when it's refused (`required`): what to do instead. */
|
|
335
|
-
fix: string | null;
|
|
336
|
-
} | {
|
|
337
|
-
status: 'refused';
|
|
338
|
-
/** Why: a line break, or a space, inside the value. */
|
|
339
|
-
message: string;
|
|
340
|
-
fix: string;
|
|
341
|
-
length: number;
|
|
342
|
-
} | {
|
|
343
|
-
status: 'ok';
|
|
344
|
-
/** The value with surrounding whitespace removed: what is stored, unless the wrapper is removed too. */
|
|
345
|
-
value: string;
|
|
346
|
-
length: number;
|
|
347
|
-
/** What trimming took off, in words (`a trailing newline`), or null. */
|
|
348
|
-
removed: string | null;
|
|
349
|
-
/** `Received 40 characters (removed a trailing newline).` */
|
|
350
|
-
received: string;
|
|
351
|
-
wrapper: SecretWrapper | null;
|
|
352
|
-
};
|
|
353
|
-
|
|
354
227
|
/**
|
|
355
228
|
* The Open Work Item (OWI) model, version 0.2, as TypeScript: one work item
|
|
356
229
|
* from Jira, Azure DevOps or GitHub in one shape, and since 0.2 one change
|
|
@@ -428,6 +301,7 @@ interface WorkItem {
|
|
|
428
301
|
connection: string;
|
|
429
302
|
key: string;
|
|
430
303
|
command: string;
|
|
304
|
+
deployment?: string;
|
|
431
305
|
};
|
|
432
306
|
url: string | null;
|
|
433
307
|
type: WorkItemType;
|
|
@@ -502,6 +376,7 @@ interface Change {
|
|
|
502
376
|
connection: string;
|
|
503
377
|
key: string;
|
|
504
378
|
command: string;
|
|
379
|
+
deployment?: string;
|
|
505
380
|
};
|
|
506
381
|
url: string | null;
|
|
507
382
|
/** The repository as the source names it: `owner/repo`, `PROJECT/slug`, `workspace/slug`, `project/repo`. */
|
|
@@ -556,6 +431,139 @@ interface OwiWarning {
|
|
|
556
431
|
message: string;
|
|
557
432
|
}
|
|
558
433
|
|
|
434
|
+
/**
|
|
435
|
+
* Progress events: what a long command is doing while it runs, for a caller
|
|
436
|
+
* that wants to show it (a sync's progress bar, a person at a terminal). They
|
|
437
|
+
* never change the result: the envelope is the same with or without a
|
|
438
|
+
* listener, and nothing in them is a header, a body or a credential.
|
|
439
|
+
*
|
|
440
|
+
* Core reports them, never an area. execute() runs each command inside
|
|
441
|
+
* `withProgress`, and the shared machinery (the paging loop, the 429 retry,
|
|
442
|
+
* the instrumented fetch) calls `reportProgress`, which finds the listener
|
|
443
|
+
* through AsyncLocalStorage. An area that pages through `paginate()` or sends
|
|
444
|
+
* through `restRequest` reports progress without a line of its own, which is
|
|
445
|
+
* the only way a status report has ever been filed on time.
|
|
446
|
+
*/
|
|
447
|
+
/** One HTTP request finished: its method, redacted URL, status (null when it failed to answer) and time. */
|
|
448
|
+
interface RequestProgress {
|
|
449
|
+
type: 'request';
|
|
450
|
+
method: string;
|
|
451
|
+
url: string;
|
|
452
|
+
status: number | null;
|
|
453
|
+
durationMs: number;
|
|
454
|
+
}
|
|
455
|
+
/** One page of a paged listing was read: its number in this call (from 1), and the items read so far, this page's included. */
|
|
456
|
+
interface PageProgress {
|
|
457
|
+
type: 'page';
|
|
458
|
+
page: number;
|
|
459
|
+
items: number;
|
|
460
|
+
/** What is being listed, when the command said ("Jira sprints for board 7"). */
|
|
461
|
+
what?: string;
|
|
462
|
+
}
|
|
463
|
+
/** A 429 is being retried: the attempt that was refused, how long toil waits before the next, and the redacted URL. */
|
|
464
|
+
interface RetryProgress {
|
|
465
|
+
type: 'retry';
|
|
466
|
+
attempt: number;
|
|
467
|
+
waitMs: number;
|
|
468
|
+
status: number;
|
|
469
|
+
url: string;
|
|
470
|
+
}
|
|
471
|
+
/** What core reports, before execute() adds the command and the message. */
|
|
472
|
+
type ProgressBody = RequestProgress | PageProgress | RetryProgress;
|
|
473
|
+
/** A progress event as a listener gets it: the command it belongs to, and one line saying it in words. */
|
|
474
|
+
type ProgressEvent = ProgressBody & {
|
|
475
|
+
command: string;
|
|
476
|
+
message: string;
|
|
477
|
+
};
|
|
478
|
+
|
|
479
|
+
/**
|
|
480
|
+
* What a command is, which decides what core hands it and which front doors
|
|
481
|
+
* serve it. One field instead of three flags that could disagree:
|
|
482
|
+
*
|
|
483
|
+
* - `standalone`: no area, no config, no connection (`version`). Always served
|
|
484
|
+
* by `toil mcp`; a broken config file can't stop it.
|
|
485
|
+
* - `area`: an area command with one resolved connection (`jira issue get`).
|
|
486
|
+
* - `area-local`: lives under an area's path but needs no connection and no
|
|
487
|
+
* config (`jira issue schema`). Served by `toil mcp` whether or not the area is set up.
|
|
488
|
+
* - `config`: reads or changes the user's connections and gets `ctx.manage`
|
|
489
|
+
* (`connections list`). Served by `toil mcp`.
|
|
490
|
+
* - `cli-only`: a `config` command that runs on the CLI only (`connections
|
|
491
|
+
* add`): it prompts on a terminal, or changes connections, which an agent
|
|
492
|
+
* never does. Never an MCP tool, and not subject to the time limit, since it
|
|
493
|
+
* may be waiting on someone typing.
|
|
494
|
+
*/
|
|
495
|
+
type CommandKind = 'standalone' | 'area' | 'area-local' | 'config' | 'cli-only';
|
|
496
|
+
|
|
497
|
+
/**
|
|
498
|
+
* What a pasted secret looks like when it arrives, checked before it goes to
|
|
499
|
+
* the OS credential store (#358). One function, `checkSecret()`, decides every
|
|
500
|
+
* case, and every way of entering a secret uses it: the CLI's terminal
|
|
501
|
+
* prompter (through `askCheckedSecret()`), a host's `person` through the API,
|
|
502
|
+
* and Toil UI's password fields, which run it in the page. So a terminal and
|
|
503
|
+
* a form say the same thing in the same words, and can't drift apart.
|
|
504
|
+
*
|
|
505
|
+
* Nothing here shows any part of the value: not a prefix, not a suffix, not a
|
|
506
|
+
* hash. What it reports is the length, the whitespace it took off the ends,
|
|
507
|
+
* and the wrapper it found ("Bearer ", "token ", quotes), which is boilerplate
|
|
508
|
+
* and never the secret. A paste is checked for the usual accidents, the way a
|
|
509
|
+
* form is checked for a missing signature, except that this one tells you which box.
|
|
510
|
+
*/
|
|
511
|
+
|
|
512
|
+
/** How a secret is asked for. */
|
|
513
|
+
interface SecretRules {
|
|
514
|
+
/** A password rather than a token: a space inside it is allowed, since people put them in passwords. */
|
|
515
|
+
password?: boolean;
|
|
516
|
+
/**
|
|
517
|
+
* What an empty answer means: ask again, since the connection needs one
|
|
518
|
+
* (`required`); keep the secret already stored (`keep`, `login` on an
|
|
519
|
+
* existing connection); or store none (`skip`, an optional one).
|
|
520
|
+
*/
|
|
521
|
+
empty: 'required' | 'keep' | 'skip';
|
|
522
|
+
/**
|
|
523
|
+
* The env vars that define this connection with no file at all
|
|
524
|
+
* (`TOIL_CONN_<NAME>_AREA=<area>`, then each setting and secret), named in
|
|
525
|
+
* the fix for an empty required secret, so a machine with no credential store
|
|
526
|
+
* has a way out that isn't Ctrl+C alone. Only the whole set works: a variable
|
|
527
|
+
* for a connection that was never saved names no connection.
|
|
528
|
+
*/
|
|
529
|
+
envVars?: readonly string[];
|
|
530
|
+
}
|
|
531
|
+
/** A wrapper around the value that the person is asked to remove: quotes, or a `Bearer ` / `token ` prefix. */
|
|
532
|
+
interface SecretWrapper {
|
|
533
|
+
/** The value without it. */
|
|
534
|
+
without: string;
|
|
535
|
+
/** Its length, in characters. */
|
|
536
|
+
withoutLength: number;
|
|
537
|
+
/** The question: `This starts with "Bearer ". Store it without that? [Y/n]`. */
|
|
538
|
+
question: string;
|
|
539
|
+
/** What it is, for a button: `"Bearer "`, `the quotes`. */
|
|
540
|
+
what: string;
|
|
541
|
+
}
|
|
542
|
+
type SecretCheck = {
|
|
543
|
+
status: 'empty';
|
|
544
|
+
empty: SecretRules['empty'];
|
|
545
|
+
/** `Kept the existing secret.`, or why an empty answer won't do. */
|
|
546
|
+
message: string;
|
|
547
|
+
/** Set when it's refused (`required`): what to do instead. */
|
|
548
|
+
fix: string | null;
|
|
549
|
+
} | {
|
|
550
|
+
status: 'refused';
|
|
551
|
+
/** Why: a line break, or a space, inside the value. */
|
|
552
|
+
message: string;
|
|
553
|
+
fix: string;
|
|
554
|
+
length: number;
|
|
555
|
+
} | {
|
|
556
|
+
status: 'ok';
|
|
557
|
+
/** The value with surrounding whitespace removed: what is stored, unless the wrapper is removed too. */
|
|
558
|
+
value: string;
|
|
559
|
+
length: number;
|
|
560
|
+
/** What trimming took off, in words (`a trailing newline`), or null. */
|
|
561
|
+
removed: string | null;
|
|
562
|
+
/** `Received 40 characters (removed a trailing newline).` */
|
|
563
|
+
received: string;
|
|
564
|
+
wrapper: SecretWrapper | null;
|
|
565
|
+
};
|
|
566
|
+
|
|
559
567
|
interface OwiSkipped {
|
|
560
568
|
/** Where in the input: `document 2`. */
|
|
561
569
|
at: string;
|