@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.
Files changed (4) hide show
  1. package/README.md +11 -0
  2. package/dist/api.d.ts +168 -5
  3. package/dist/toil-lib.js +32453 -17417
  4. 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), for `toil projects onboard`
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
- * refuses (`src/core/runtime.ts`, CVE-2026-111497) every call is the CLI's
878
- * `UNSUPPORTED_NODE` envelope, before anything runs or fetches.
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 { type ApiAnswer, type AreaSummary, type AuthorKind, type AuthorKindSource, type Body, type Change, type ChangeSize, type ChangeState, type ChecksState, type CommandInfo, type CommandKind, type ConnectionField, type ContextReport, type ContextSource, type ContextValue, type Envelope, type ErrorBody, type ErrorCode, type Estimate, type EstimateUnit, type ExecuteOptions, type ExecutePerson, type FieldOverrides, type History, type Iteration, type IterationChange, type KeyPattern, type Link, type LinkType, type Meta, type OrphanHistory, type OwiMapOptions, type OwiResult, type OwiSkipped, type Page, type PageProgress, type PairSearch, type Person, type ProgressEvent, type Question, type Registry, type RequestProgress, type RetryProgress, type Review, type ReviewState, type Reviewer, type ReviewerState, type SecretCheck, type SecretRules, type SecretWrapper, type SimilarField, type SimilarItem, type SimilarMatch, type SimilarOptions, type SimilarPair, type SimilarParts, type SimilarRef, type SimilarRequest, type SimilarResult, type SimilarWhy, type StatusCategory, type ToilProjectReport, type Transition, type Unmapped, type Warning, type WorkItem, type WorkItemType, checkSecret, contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version };
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 };