@imagile-dev/toil 0.1.0-beta.4 → 0.1.0-beta.6
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 +11 -0
- package/dist/api.d.ts +168 -5
- package/dist/toil-lib.js +32453 -17417
- package/package.json +16 -13
package/README.md
CHANGED
|
@@ -189,6 +189,8 @@ Code the clone is also a plugin marketplace: `claude plugin marketplace add
|
|
|
189
189
|
| [`db`](https://imagile-dev.github.io/toil/connect/db/) | SQLite, PostgreSQL, MySQL / MariaDB, SQL Server, Oracle, Teradata, Hive and Impala: list schemas and tables, describe a table, preview rows, read-only queries with paging |
|
|
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
|
+
| [`classify`](https://imagile-dev.github.io/toil/docs/classify/) | Sort a backlog into keep-the-lights-on and feature work, write the category back as a label or field, and count the mix |
|
|
193
|
+
| [`sample`](https://imagile-dev.github.io/toil/docs/sample/) | A generated sample team to try toil and Toil UI on before any connection |
|
|
192
194
|
| [The toil skill](https://imagile-dev.github.io/toil/docs/) | toil's own command reference for agents, one file per area |
|
|
193
195
|
| [Work tracking](https://imagile-dev.github.io/toil/connect/#trackers) (2) | Jira (Data Center and Cloud), Azure DevOps Server and Services |
|
|
194
196
|
| [Source and review](https://imagile-dev.github.io/toil/connect/#source) (3) | GitHub & GitHub Enterprise, Bitbucket (Data Center and Cloud), local git |
|
|
@@ -222,6 +224,15 @@ the gate and how review works. Questions and bug reports go through
|
|
|
222
224
|
[SUPPORT.md](.github/SUPPORT.md), and security reports through
|
|
223
225
|
[SECURITY.md](.github/SECURITY.md), never a public issue.
|
|
224
226
|
|
|
227
|
+
### From your clone
|
|
228
|
+
|
|
229
|
+
You don't need to be a maintainer to send a fix. Fork
|
|
230
|
+
[imagile-dev/toil](https://github.com/imagile-dev/toil), push a branch to your fork
|
|
231
|
+
and open a pull request against `main`, following CLAUDE.md. A maintainer reviews it
|
|
232
|
+
and merges it. An agent
|
|
233
|
+
working in your clone asks you before it forks or opens anything for you
|
|
234
|
+
([`skills/toil/install.md`](skills/toil/install.md), **Sending a fix back**).
|
|
235
|
+
|
|
225
236
|
## License
|
|
226
237
|
|
|
227
238
|
Apache License 2.0 © Imagile. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
|
package/dist/api.d.ts
CHANGED
|
@@ -1,3 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a credential must be allowed to do for toil to do its job (#561). An
|
|
3
|
+
* area that signs in with a scoped credential (GitHub's personal access
|
|
4
|
+
* tokens) declares, per kind of credential, each scope or permission toil
|
|
5
|
+
* uses and the commands that need it. Core turns that into two lists, what
|
|
6
|
+
* read-only use needs and what everything toil can do needs, which the CLI
|
|
7
|
+
* (`toil connections scopes`), MCP and Toil UI all show from this one place.
|
|
8
|
+
*
|
|
9
|
+
* Declaring is not enforcing: toil never checks a credential's scopes, and a
|
|
10
|
+
* service that refuses a call still answers with its own error. This is the
|
|
11
|
+
* list a person reads before filling in the "scopes" page of a vendor's form,
|
|
12
|
+
* a form that, like most of them, asks for all of it and explains none of it.
|
|
13
|
+
* `test/scopes.test.ts` fails when a command exists that no entry lists.
|
|
14
|
+
*/
|
|
15
|
+
/** How much a scope lets toil do. */
|
|
16
|
+
type ScopeUse = 'read' | 'write';
|
|
17
|
+
/** One scope or permission, and what in toil needs it. */
|
|
18
|
+
interface ScopeEntry {
|
|
19
|
+
/** The vendor's name for it: `repo`, `read:project`, `Pull requests`. */
|
|
20
|
+
name: string;
|
|
21
|
+
/**
|
|
22
|
+
* For a credential that grants each permission at levels (fine-grained
|
|
23
|
+
* tokens): the level this entry is. Left out for a scope that is all or
|
|
24
|
+
* nothing (a classic token's `repo`).
|
|
25
|
+
*/
|
|
26
|
+
access?: ScopeUse;
|
|
27
|
+
/** The least use that needs it: `read` if a read-only command does, else `write`. */
|
|
28
|
+
required: ScopeUse;
|
|
29
|
+
/** Every command that needs it, as `toil` is typed without the `toil`: `github pr list`. */
|
|
30
|
+
commands: readonly string[];
|
|
31
|
+
/** Anything a person should know that the name doesn't say. */
|
|
32
|
+
note?: string;
|
|
33
|
+
}
|
|
34
|
+
/** What one use needs from one credential kind: the names, and a link to make a token that has them. */
|
|
35
|
+
interface ScopeNeeds {
|
|
36
|
+
needs: string[];
|
|
37
|
+
createUrl: string;
|
|
38
|
+
}
|
|
39
|
+
/** A kind as `toil connections scopes` and the registry hand it out. */
|
|
40
|
+
interface DescribedKind {
|
|
41
|
+
id: string;
|
|
42
|
+
label: string;
|
|
43
|
+
tokenPrefix: string | null;
|
|
44
|
+
summary: string;
|
|
45
|
+
createUrl: string;
|
|
46
|
+
readOnly: ScopeNeeds;
|
|
47
|
+
everything: ScopeNeeds;
|
|
48
|
+
entries: ScopeEntry[];
|
|
49
|
+
}
|
|
50
|
+
interface DescribedScopes {
|
|
51
|
+
secret: string;
|
|
52
|
+
otherPrefixes?: Record<string, string>;
|
|
53
|
+
kinds: DescribedKind[];
|
|
54
|
+
}
|
|
55
|
+
|
|
1
56
|
/**
|
|
2
57
|
* Every failure a user can see is a ToilError: a stable code, a message, and a
|
|
3
58
|
* fix they can act on. Anything else that escapes a command is wrapped as
|
|
@@ -285,6 +340,35 @@ interface History {
|
|
|
285
340
|
transitions: Transition[];
|
|
286
341
|
iterations: IterationChange[];
|
|
287
342
|
}
|
|
343
|
+
/**
|
|
344
|
+
* A release, or a version an item affects: Jira's fix and affects versions,
|
|
345
|
+
* a GitHub milestone, and a field an Azure DevOps toil project names.
|
|
346
|
+
* `released` is null where the source can't say (a text field), and `date` is
|
|
347
|
+
* the day the release is due or went out, null when it has none.
|
|
348
|
+
*/
|
|
349
|
+
interface Release {
|
|
350
|
+
id: string | null;
|
|
351
|
+
name: string;
|
|
352
|
+
released: boolean | null;
|
|
353
|
+
date: string | null;
|
|
354
|
+
/**
|
|
355
|
+
* Optional. The day (`YYYY-MM-DD`) work on the release started, where the source says
|
|
356
|
+
* (Jira's version `startDate`); null when the source carries the field but it is empty.
|
|
357
|
+
* Absent: the source has no such field, or the read never fetched it.
|
|
358
|
+
*/
|
|
359
|
+
start?: string | null;
|
|
360
|
+
}
|
|
361
|
+
/** One level of an item's parent chain, as `ancestors` holds it, nearest parent first. */
|
|
362
|
+
interface Ancestor {
|
|
363
|
+
id: string;
|
|
364
|
+
type: WorkItemType;
|
|
365
|
+
typeName: string | null;
|
|
366
|
+
title: string;
|
|
367
|
+
}
|
|
368
|
+
/** An Azure DevOps area path (`Imagile\Payments\Web`), kept whole so a split can cut it at any depth. */
|
|
369
|
+
interface AreaPath {
|
|
370
|
+
path: string;
|
|
371
|
+
}
|
|
288
372
|
interface Unmapped {
|
|
289
373
|
field: string;
|
|
290
374
|
reason: string;
|
|
@@ -293,6 +377,17 @@ interface Body {
|
|
|
293
377
|
format: 'markdown' | 'wiki' | 'adf' | 'html';
|
|
294
378
|
content: string | Record<string, unknown>;
|
|
295
379
|
}
|
|
380
|
+
/** One comment on a work item, as a stand-up reads it: who wrote it, when, and its text as plain text on one line. */
|
|
381
|
+
interface Comment {
|
|
382
|
+
id: string;
|
|
383
|
+
author: Person | null;
|
|
384
|
+
/** UTC, as `toISOString` writes it. */
|
|
385
|
+
at: string;
|
|
386
|
+
/** Plain text, markup taken out, capped; never HTML. */
|
|
387
|
+
text: string;
|
|
388
|
+
/** A link to the comment where the tracker gives one, else null. */
|
|
389
|
+
url: string | null;
|
|
390
|
+
}
|
|
296
391
|
interface WorkItem {
|
|
297
392
|
owi: typeof OWI_VERSION;
|
|
298
393
|
id: string;
|
|
@@ -328,6 +423,22 @@ interface WorkItem {
|
|
|
328
423
|
history: History | null;
|
|
329
424
|
unmapped: Unmapped[];
|
|
330
425
|
native: Record<string, unknown>;
|
|
426
|
+
/** Fix versions (Jira), the milestone (GitHub), or the field `fields release` names (Azure DevOps). */
|
|
427
|
+
releases?: Release[];
|
|
428
|
+
/** Affected versions: Jira's `versions`, or the field `fields affects` names (Azure DevOps). */
|
|
429
|
+
affects?: Release[];
|
|
430
|
+
/** Jira components, by name. */
|
|
431
|
+
components?: string[];
|
|
432
|
+
/** Azure DevOps' area path; null when the record carries none. */
|
|
433
|
+
area?: AreaPath | null;
|
|
434
|
+
/** Every sprint or iteration the item has been in, where the source lists them; `iteration` stays the current one. */
|
|
435
|
+
sprints?: Iteration[];
|
|
436
|
+
/** The values of each dimension a toil project names, by dimension name; a value is always a list, since a field may hold several. */
|
|
437
|
+
dims?: Record<string, string[]>;
|
|
438
|
+
/** The parent chain among the records mapped together, nearest first. It ends where a parent isn't in the input. */
|
|
439
|
+
ancestors?: Ancestor[];
|
|
440
|
+
/** The comments the read returned, oldest first, the newest 20 at most. Absent: not read (a Jira search that didn't ask for `comment`). []: read, none. */
|
|
441
|
+
comments?: Comment[];
|
|
331
442
|
}
|
|
332
443
|
/** A history mapped for an item that wasn't in the same input. */
|
|
333
444
|
interface OrphanHistory {
|
|
@@ -340,7 +451,7 @@ interface OrphanHistory {
|
|
|
340
451
|
* the label pattern that holds an estimate (`points: {n}`), and
|
|
341
452
|
* `iterationDays`, how long a milestone's sprint runs.
|
|
342
453
|
*/
|
|
343
|
-
declare const OVERRIDABLE: readonly ["estimate", "estimateUnit", "priority", "type", "team", "dueDate", "iteration", "estimateLabel", "iterationDays"];
|
|
454
|
+
declare const OVERRIDABLE: readonly ["estimate", "estimateUnit", "priority", "type", "team", "dueDate", "iteration", "release", "affects", "estimateLabel", "iterationDays"];
|
|
344
455
|
type Overridable = (typeof OVERRIDABLE)[number];
|
|
345
456
|
type FieldOverrides = Partial<Record<Overridable, string>>;
|
|
346
457
|
type ChangeState = 'OPEN' | 'MERGED' | 'DECLINED' | 'DRAFT';
|
|
@@ -755,6 +866,31 @@ interface AreaSummary {
|
|
|
755
866
|
* connection.
|
|
756
867
|
*/
|
|
757
868
|
connection: readonly ConnectionField[];
|
|
869
|
+
/** What its credential must be allowed to do, per kind of credential. Left out for an area that declares none (`toil connections scopes`). */
|
|
870
|
+
scopes?: DescribedScopes;
|
|
871
|
+
/** The setting whose value picks the deployment (`deployment`), for an area with variants. */
|
|
872
|
+
variantBy?: string;
|
|
873
|
+
}
|
|
874
|
+
/** Presets for a setting, as a form shows them: radio buttons, one of which may build the value from a word the person types. */
|
|
875
|
+
interface ConnectionChoices {
|
|
876
|
+
question?: string;
|
|
877
|
+
/** No option starts selected; the person must pick one. */
|
|
878
|
+
required?: boolean;
|
|
879
|
+
options: readonly {
|
|
880
|
+
label: string;
|
|
881
|
+
/** What choosing it sets, or null when the person types it. */
|
|
882
|
+
value: string | null;
|
|
883
|
+
when?: Readonly<Record<string, string>>;
|
|
884
|
+
placeholder?: string;
|
|
885
|
+
compose?: {
|
|
886
|
+
prefix: string;
|
|
887
|
+
suffix?: string;
|
|
888
|
+
label: string;
|
|
889
|
+
placeholder: string;
|
|
890
|
+
};
|
|
891
|
+
hosts?: readonly string[];
|
|
892
|
+
expectPath?: string;
|
|
893
|
+
}[];
|
|
758
894
|
}
|
|
759
895
|
/** One value a connection holds, as `toil connections add` asks for it. */
|
|
760
896
|
interface ConnectionField {
|
|
@@ -769,6 +905,27 @@ interface ConnectionField {
|
|
|
769
905
|
default: string | null;
|
|
770
906
|
/** The connection isn't valid without it. */
|
|
771
907
|
required: boolean;
|
|
908
|
+
/** Presets a form offers as radio buttons; `value` is null for the one the person types. Left out when there are none. */
|
|
909
|
+
choices?: ConnectionChoices;
|
|
910
|
+
/** The values of the area's variant setting (`deployment`) this applies to; left out when it applies to all. */
|
|
911
|
+
appliesTo?: readonly string[];
|
|
912
|
+
/** The variants whose connections can't do without it, though it isn't required of every one. */
|
|
913
|
+
requiredFor?: readonly string[];
|
|
914
|
+
/**
|
|
915
|
+
* On a pairing setting (`apiTokenFrom`): the secret it borrows from another
|
|
916
|
+
* area's connection, and when `connections add` and `login` offer that
|
|
917
|
+
* instead of asking for the secret (as the question `borrow:<key>`, `y` or
|
|
918
|
+
* `n`): both connections hold every value in `when`, share a host if
|
|
919
|
+
* `sameHost`, and the lender's secret resolves; `match` names the settings
|
|
920
|
+
* the borrowed secret only works with. Left out where nothing is offered.
|
|
921
|
+
*/
|
|
922
|
+
borrows?: {
|
|
923
|
+
area: string;
|
|
924
|
+
key: string;
|
|
925
|
+
when?: Readonly<Record<string, string>>;
|
|
926
|
+
sameHost?: boolean;
|
|
927
|
+
match?: readonly string[];
|
|
928
|
+
};
|
|
772
929
|
}
|
|
773
930
|
/**
|
|
774
931
|
* The commands and areas this toil has. `commands` is what `execute()`
|
|
@@ -790,7 +947,10 @@ interface Registry {
|
|
|
790
947
|
* `confirm-name` (type the connection's name to turn writes on), `unwrap:<key>`
|
|
791
948
|
* (the secret for `<key>` is in quotes or starts with `Bearer ` or `token `:
|
|
792
949
|
* `y` stores it without them, `n` as entered; `checkSecret` says which before
|
|
793
|
-
* the call, so a host can ask its person first),
|
|
950
|
+
* the call, so a host can ask its person first), `borrow:<key>` (use the
|
|
951
|
+
* secret for `<key>` from the other area's connection the question names
|
|
952
|
+
* instead of entering one: `y` or `n`; `ConnectionField.borrows` says when it
|
|
953
|
+
* is asked), for `toil projects onboard`
|
|
794
954
|
* `create:<section>` (add a connection that toil project section needs: `y` or `n`),
|
|
795
955
|
* `name:<section>` (the new connection's name) and `pin:<section>` (which
|
|
796
956
|
* matching connection the person's own copy uses), and `consent`
|
|
@@ -874,8 +1034,8 @@ declare const registry: Registry;
|
|
|
874
1034
|
* throws: an unknown command, a bad option or a failure inside is an envelope
|
|
875
1035
|
* with `ok: false`, like every other. `input` is the command's MCP fields
|
|
876
1036
|
* (`{ jql: "project = PAY", limit: 50 }`), checked strictly. On a Node toil
|
|
877
|
-
*
|
|
878
|
-
* `
|
|
1037
|
+
* flags (`src/core/runtime.ts`, CVE-2026-111497) every envelope carries the
|
|
1038
|
+
* warning in `meta.warnings`, from core like the other front doors; the call still runs.
|
|
879
1039
|
*/
|
|
880
1040
|
declare function execute(command: string, input?: Record<string, unknown>, options?: ExecuteOptions): Promise<Envelope>;
|
|
881
1041
|
/**
|
|
@@ -901,6 +1061,8 @@ interface OwiMapOptions {
|
|
|
901
1061
|
keyPatterns?: Array<string | KeyPattern>;
|
|
902
1062
|
/** Pull request author kinds set by hand, by author id: `{ "release-bot": "BOT" }`, or `id=KIND` strings. */
|
|
903
1063
|
authorKinds?: Record<string, string> | string[];
|
|
1064
|
+
/** The toil project's `dimensions`: each dimension's name to the field that holds it per area. Copied onto each item's `dims`. */
|
|
1065
|
+
dimensions?: Record<string, Record<string, string>>;
|
|
904
1066
|
}
|
|
905
1067
|
/**
|
|
906
1068
|
* Likely duplicates among OWI records you already hold, scored the way
|
|
@@ -930,4 +1092,5 @@ declare const owiSchema: Record<string, unknown>;
|
|
|
930
1092
|
*/
|
|
931
1093
|
declare function checkSecret(raw: string, rules: SecretRules): SecretCheck;
|
|
932
1094
|
|
|
933
|
-
export {
|
|
1095
|
+
export { checkSecret, contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version };
|
|
1096
|
+
export type { ApiAnswer, AreaSummary, AuthorKind, AuthorKindSource, Body, Change, ChangeSize, ChangeState, ChecksState, CommandInfo, CommandKind, ConnectionChoices, ConnectionField, ContextReport, ContextSource, ContextValue, Envelope, ErrorBody, ErrorCode, Estimate, EstimateUnit, ExecuteOptions, ExecutePerson, FieldOverrides, History, Iteration, IterationChange, KeyPattern, Link, LinkType, Meta, OrphanHistory, OwiMapOptions, OwiResult, OwiSkipped, Page, PageProgress, PairSearch, Person, ProgressEvent, Question, Registry, RequestProgress, RetryProgress, Review, ReviewState, Reviewer, ReviewerState, SecretCheck, SecretRules, SecretWrapper, SimilarField, SimilarItem, SimilarMatch, SimilarOptions, SimilarPair, SimilarParts, SimilarRef, SimilarRequest, SimilarResult, SimilarWhy, StatusCategory, ToilProjectReport, Transition, Unmapped, Warning, WorkItem, WorkItemType };
|