@imagile-dev/toil 0.1.0-alpha.2 → 0.1.0-alpha.4
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/NOTICE +6 -0
- package/README.md +74 -9
- package/dist/api.d.ts +395 -19
- package/dist/api.js +1 -1
- package/dist/toil-lib.js +11571 -6614
- package/package.json +6 -2
package/dist/api.d.ts
CHANGED
|
@@ -19,6 +19,44 @@ type ErrorCode = 'INVALID_INPUT' | 'NOT_CONFIGURED' | 'CONFIG_INVALID' | 'AUTH'
|
|
|
19
19
|
/** The server is a release without an API the command needs (sub-issues or Projects on an older GitHub Enterprise Server). */
|
|
20
20
|
| 'UNSUPPORTED' | 'INTERNAL';
|
|
21
21
|
|
|
22
|
+
/** How a transition was chosen, as meta.transition reports it. */
|
|
23
|
+
type ResolvedBy = 'dossier' | 'status' | 'category' | 'name';
|
|
24
|
+
/** meta.transition: what `--to` asked for and what it resolved to. */
|
|
25
|
+
interface TransitionReport {
|
|
26
|
+
intent: string;
|
|
27
|
+
transition: string;
|
|
28
|
+
toStatus: string;
|
|
29
|
+
resolvedBy: ResolvedBy;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
type SummaryRule = 'record' | 'all' | 'outline' | 'head' | 'sample';
|
|
33
|
+
interface SummaryReport {
|
|
34
|
+
rule: SummaryRule;
|
|
35
|
+
/** Rows in the full result: the table's length, or 1 when there's no table. */
|
|
36
|
+
rows: number;
|
|
37
|
+
/** Where the table is in `data`: `""` for the result itself, a dot path (`findings.results`), or null when there's none. */
|
|
38
|
+
table: string | null;
|
|
39
|
+
/** The file holding the full result, absolute, with forward slashes. */
|
|
40
|
+
file: string;
|
|
41
|
+
/** Estimated tokens, JSON characters divided by `CHARS_PER_TOKEN`: an estimate, never a count. */
|
|
42
|
+
tokens: {
|
|
43
|
+
full: number;
|
|
44
|
+
summary: number;
|
|
45
|
+
estimate: string;
|
|
46
|
+
};
|
|
47
|
+
/** Columns in the table's flattened rows, when there's a table; `schema` and `stats` describe the first 25. */
|
|
48
|
+
columns?: number;
|
|
49
|
+
/** What the token budget cut: rows dropped from the end, `sample` cut to its keys or left out, how many long texts were cut short (ending in `…`), `lengths` left out, keys dropped from the end of `keys`, or fields beside the table left out of `fields`. */
|
|
50
|
+
trimmed?: {
|
|
51
|
+
rows?: number;
|
|
52
|
+
sample?: true;
|
|
53
|
+
strings?: number;
|
|
54
|
+
lengths?: true;
|
|
55
|
+
keys?: number;
|
|
56
|
+
fields?: number;
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
|
|
22
60
|
/**
|
|
23
61
|
* The output contract: every command, through the CLI or MCP, produces exactly
|
|
24
62
|
* one of these. Removing or renaming a field is a breaking change.
|
|
@@ -58,6 +96,13 @@ interface Meta {
|
|
|
58
96
|
* since `data` is the body as the service sent it. Set with `ctx.setResponse`.
|
|
59
97
|
*/
|
|
60
98
|
response?: ApiAnswer;
|
|
99
|
+
/**
|
|
100
|
+
* For a command that ran SQL the caller wrote (`db query`, `db execute`,
|
|
101
|
+
* `db lint`): the engine whose dialect the pre-flight lint checked it
|
|
102
|
+
* against, and every rule that ran. Its warnings are in `warnings`. Set
|
|
103
|
+
* with `ctx.setLint`.
|
|
104
|
+
*/
|
|
105
|
+
lint?: LintReport;
|
|
61
106
|
/**
|
|
62
107
|
* For `toil wait`: the condition, how many times the read ran, and how
|
|
63
108
|
* long the whole wait took. The rest of meta is the last attempt's.
|
|
@@ -67,6 +112,25 @@ interface Meta {
|
|
|
67
112
|
attempts: number;
|
|
68
113
|
elapsedMs: number;
|
|
69
114
|
};
|
|
115
|
+
/**
|
|
116
|
+
* For a transition asked for by intent (`--to review`): what was asked, the
|
|
117
|
+
* transition and status it resolved to, and which rule chose it. Set with
|
|
118
|
+
* `ctx.setTransition` (src/core/transition-intent.ts).
|
|
119
|
+
*/
|
|
120
|
+
transition?: TransitionReport;
|
|
121
|
+
/**
|
|
122
|
+
* Under `--summary-file`: which summary rule applied, how many rows the full
|
|
123
|
+
* result has, where its table is, the file it was written to, and the token
|
|
124
|
+
* estimates (src/core/output/summary.ts).
|
|
125
|
+
*/
|
|
126
|
+
summary?: SummaryReport;
|
|
127
|
+
/** Under `--output-format toon`: `data` is TOON text rather than JSON. Absent for JSON. */
|
|
128
|
+
format?: 'toon';
|
|
129
|
+
}
|
|
130
|
+
/** What the pre-flight lint checked: the engine, and the rules that ran, in order. */
|
|
131
|
+
interface LintReport {
|
|
132
|
+
engine: string;
|
|
133
|
+
rules: string[];
|
|
70
134
|
}
|
|
71
135
|
/** The status and content type of the response a raw API call returned. */
|
|
72
136
|
interface ApiAnswer {
|
|
@@ -205,9 +269,9 @@ type ProgressEvent = ProgressBody & {
|
|
|
205
269
|
*
|
|
206
270
|
* - `standalone`: no area, no config, no connection (`version`). Always served
|
|
207
271
|
* by `toil mcp`; a broken config file can't stop it.
|
|
208
|
-
* - `area`: an area command with one resolved connection (`jira get
|
|
272
|
+
* - `area`: an area command with one resolved connection (`jira issue get`).
|
|
209
273
|
* - `area-local`: lives under an area's path but needs no connection and no
|
|
210
|
-
* config (`jira schema`). Served by `toil mcp` whether or not the area is set up.
|
|
274
|
+
* config (`jira issue schema`). Served by `toil mcp` whether or not the area is set up.
|
|
211
275
|
* - `config`: reads or changes the user's connections and gets `ctx.manage`
|
|
212
276
|
* (`connections list`). Served by `toil mcp`.
|
|
213
277
|
* - `cli-only`: a `config` command that runs on the CLI only (`connections
|
|
@@ -218,14 +282,16 @@ type ProgressEvent = ProgressBody & {
|
|
|
218
282
|
type CommandKind = 'standalone' | 'area' | 'area-local' | 'config' | 'cli-only';
|
|
219
283
|
|
|
220
284
|
/**
|
|
221
|
-
* The Open Work Item (OWI) model, version 0.
|
|
222
|
-
* from Jira, Azure DevOps or GitHub in one shape
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
*
|
|
285
|
+
* The Open Work Item (OWI) model, version 0.2, as TypeScript: one work item
|
|
286
|
+
* from Jira, Azure DevOps or GitHub in one shape, and since 0.2 one change
|
|
287
|
+
* (a pull request) from GitHub, Bitbucket or Azure DevOps in another.
|
|
288
|
+
* docs/owi/spec.md is the specification and docs/owi/schema.json the JSON
|
|
289
|
+
* Schema every mapped record is checked against; these types follow both.
|
|
290
|
+
* Additive changes only, and every record says which version it is (`owi`).
|
|
291
|
+
* Three trackers, one form, which is more than most standardisation
|
|
292
|
+
* programmes manage before the steering group.
|
|
227
293
|
*/
|
|
228
|
-
declare const OWI_VERSION: "0.
|
|
294
|
+
declare const OWI_VERSION: "0.2";
|
|
229
295
|
type OwiArea = string;
|
|
230
296
|
type WorkItemType = 'EPIC' | 'STORY' | 'TASK' | 'BUG' | 'INCIDENT' | 'OTHER';
|
|
231
297
|
type StatusCategory = 'TODO' | 'IN_PROGRESS' | 'DONE' | 'UNKNOWN';
|
|
@@ -324,10 +390,97 @@ interface OrphanHistory {
|
|
|
324
390
|
id: string;
|
|
325
391
|
history: History;
|
|
326
392
|
}
|
|
327
|
-
/**
|
|
328
|
-
|
|
393
|
+
/**
|
|
394
|
+
* The OWI fields a team can point at a field of its own, with `fields`, and
|
|
395
|
+
* two settings for a GitHub repository run without a board: `estimateLabel`,
|
|
396
|
+
* the label pattern that holds an estimate (`points: {n}`), and
|
|
397
|
+
* `iterationDays`, how long a milestone's sprint runs.
|
|
398
|
+
*/
|
|
399
|
+
declare const OVERRIDABLE: readonly ["estimate", "estimateUnit", "priority", "type", "team", "dueDate", "iteration", "estimateLabel", "iterationDays"];
|
|
329
400
|
type Overridable = (typeof OVERRIDABLE)[number];
|
|
330
401
|
type FieldOverrides = Partial<Record<Overridable, string>>;
|
|
402
|
+
type ChangeState = 'OPEN' | 'MERGED' | 'DECLINED' | 'DRAFT';
|
|
403
|
+
type ReviewerState = 'APPROVED' | 'CHANGES_REQUESTED' | 'PENDING';
|
|
404
|
+
type ReviewState = 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' | 'DISMISSED';
|
|
405
|
+
type ChecksState = 'PASSING' | 'FAILING' | 'PENDING' | 'NONE';
|
|
406
|
+
type AuthorKind = 'HUMAN' | 'AGENT' | 'BOT';
|
|
407
|
+
/** Which signal set `authorKind`: never a guess, and `default` when there was none. */
|
|
408
|
+
type AuthorKindSource = 'override' | 'account' | 'trailer' | 'branch' | 'default';
|
|
409
|
+
/** Someone asked to review, and where their review stands now. */
|
|
410
|
+
interface Reviewer {
|
|
411
|
+
person: Person;
|
|
412
|
+
state: ReviewerState;
|
|
413
|
+
}
|
|
414
|
+
/** One review as it happened: an approval, a request for changes, a comment, or an approval withdrawn. */
|
|
415
|
+
interface Review {
|
|
416
|
+
by: Person;
|
|
417
|
+
state: ReviewState;
|
|
418
|
+
at: string;
|
|
419
|
+
}
|
|
420
|
+
interface ChangeSize {
|
|
421
|
+
files: number | null;
|
|
422
|
+
additions: number | null;
|
|
423
|
+
deletions: number | null;
|
|
424
|
+
}
|
|
425
|
+
/** A pull request, as OWI 0.2 models it: the change that carries work, not the work. */
|
|
426
|
+
interface Change {
|
|
427
|
+
owi: typeof OWI_VERSION;
|
|
428
|
+
/** `<connection>:<repo>#<number>`: `github:imagile/payments-web#41`, `corp-bitbucket:PAY/payments-core#311`. */
|
|
429
|
+
id: string;
|
|
430
|
+
source: {
|
|
431
|
+
area: OwiArea;
|
|
432
|
+
connection: string;
|
|
433
|
+
key: string;
|
|
434
|
+
command: string;
|
|
435
|
+
};
|
|
436
|
+
url: string | null;
|
|
437
|
+
/** The repository as the source names it: `owner/repo`, `PROJECT/slug`, `workspace/slug`, `project/repo`. */
|
|
438
|
+
repo: string;
|
|
439
|
+
title: string;
|
|
440
|
+
branch: {
|
|
441
|
+
source: string | null;
|
|
442
|
+
target: string | null;
|
|
443
|
+
};
|
|
444
|
+
state: ChangeState;
|
|
445
|
+
author: Person | null;
|
|
446
|
+
authorKind: AuthorKind;
|
|
447
|
+
authorKindSource: AuthorKindSource;
|
|
448
|
+
/** What the signal was, in words (`account type Bot`, a Co-Authored-By trailer, `branch claude/fix-retries`); null for the default. */
|
|
449
|
+
authorKindSignal: string | null;
|
|
450
|
+
reviewers: Reviewer[];
|
|
451
|
+
/** Every review in order, or null when the input held none (a list, or a get without its reviews). */
|
|
452
|
+
reviews: Review[] | null;
|
|
453
|
+
/** The checks on the latest commit, rolled up; null when they weren't read. */
|
|
454
|
+
checks: ChecksState | null;
|
|
455
|
+
/** When the checks came to their state: for FAILING, the earliest finish of a check failing now; otherwise the latest check. */
|
|
456
|
+
checksAt: string | null;
|
|
457
|
+
/** Whether it merges cleanly: false is a conflict; null when the source didn't say. */
|
|
458
|
+
mergeable: boolean | null;
|
|
459
|
+
size: ChangeSize | null;
|
|
460
|
+
/** The OWI ids of the work items its title, branch and description name. */
|
|
461
|
+
workItems: string[];
|
|
462
|
+
/** For a merged change: the commit it merged as. */
|
|
463
|
+
mergeCommit: string | null;
|
|
464
|
+
created: string | null;
|
|
465
|
+
firstReviewAt: string | null;
|
|
466
|
+
approvedAt: string | null;
|
|
467
|
+
mergedAt: string | null;
|
|
468
|
+
closedAt: string | null;
|
|
469
|
+
updated: string | null;
|
|
470
|
+
unmapped: Unmapped[];
|
|
471
|
+
native: Record<string, unknown>;
|
|
472
|
+
}
|
|
473
|
+
/**
|
|
474
|
+
* A key pattern: text with `{n}` where the number is, and the connection the
|
|
475
|
+
* key belongs to. The key is the text matched (`PAY-{n}` finds `PAY-101`;
|
|
476
|
+
* `imagile/payments-web#{n}` finds `imagile/payments-web#42`), except that a
|
|
477
|
+
* mention ending `#{n}` with no repository in it names the number alone
|
|
478
|
+
* (`AB#{n}`, Azure Boards' mention, finds key `2302`).
|
|
479
|
+
*/
|
|
480
|
+
interface KeyPattern {
|
|
481
|
+
text: string;
|
|
482
|
+
connection: string;
|
|
483
|
+
}
|
|
331
484
|
interface OwiWarning {
|
|
332
485
|
code: string;
|
|
333
486
|
message: string;
|
|
@@ -341,12 +494,150 @@ interface OwiSkipped {
|
|
|
341
494
|
}
|
|
342
495
|
interface OwiResult {
|
|
343
496
|
items: WorkItem[];
|
|
497
|
+
/** Pull requests, as OWI 0.2 changes. */
|
|
498
|
+
changes: Change[];
|
|
344
499
|
/** Histories for items that weren't in the input, so a caller can attach them to items it already has. */
|
|
345
500
|
histories: OrphanHistory[];
|
|
346
501
|
skipped: OwiSkipped[];
|
|
347
502
|
warnings: OwiWarning[];
|
|
348
503
|
}
|
|
349
504
|
|
|
505
|
+
/**
|
|
506
|
+
* Likely duplicates among Open Work Items, found by lexical scoring alone: no
|
|
507
|
+
* model, no network, and the same answer on every run and every platform.
|
|
508
|
+
* `toil util owi similar` runs it in the bounded worker; Toil UI's item page
|
|
509
|
+
* and its agent call it directly on the items they hold, and anything that
|
|
510
|
+
* needs "does this already exist?" (#304) imports it from here.
|
|
511
|
+
*
|
|
512
|
+
* How a score is made, so its `why` can say exactly what drove it:
|
|
513
|
+
*
|
|
514
|
+
* - **Terms.** Titles and bodies (Markdown, wiki markup, HTML and ADF, read
|
|
515
|
+
* as plain text) become lowercase words, with accents folded, common English
|
|
516
|
+
* words dropped and a light suffix stemmer applied. Each term is weighted by
|
|
517
|
+
* BM25: its IDF over the set, times its saturated, length-normalised
|
|
518
|
+
* frequency, with a title occurrence worth twice a body one.
|
|
519
|
+
* - Two items: the cosine of their BM25 vectors. When either has no body,
|
|
520
|
+
* both are compared on their titles alone, so a missing body never counts
|
|
521
|
+
* against an item.
|
|
522
|
+
* - A query: how much of the query's IDF the item covers, a term in its title
|
|
523
|
+
* counting fully and one only in its body at most 0.7.
|
|
524
|
+
* - **Trigrams.** The character trigrams of the titles' words (each padded with
|
|
525
|
+
* a space), compared with Dice's coefficient, which catches typos and other
|
|
526
|
+
* forms of a word the stemmer leaves apart.
|
|
527
|
+
* - **Boosts.** Small ones for shared labels (rarer labels count more), the
|
|
528
|
+
* same parent, and a direct link between the two items. Together they can't
|
|
529
|
+
* reach the default threshold on their own.
|
|
530
|
+
*
|
|
531
|
+
* The score is 0.7 of the terms and 0.3 of the trigrams (all terms when titles
|
|
532
|
+
* aren't compared), plus the boosts, capped at 1 and rounded to four places.
|
|
533
|
+
* It measures shared words, not meaning: two items that describe one problem
|
|
534
|
+
* in entirely different words score low, and the docs say so.
|
|
535
|
+
*
|
|
536
|
+
* Determinism: items are indexed in id order, every sum runs in a fixed order,
|
|
537
|
+
* a pair is always scored from its lower id, ties are broken by id with a
|
|
538
|
+
* plain code-unit comparison (never the locale's), and only the rounded
|
|
539
|
+
* figures leave this module. Two runs on the same input are byte-identical,
|
|
540
|
+
* which is more than can be said for the minutes of most duplicate-review
|
|
541
|
+
* meetings.
|
|
542
|
+
*/
|
|
543
|
+
/** What the scorer can compare. `parent` and `links` only ever add a small boost. */
|
|
544
|
+
declare const SIMILAR_FIELDS: readonly ["title", "body", "labels", "parent", "links"];
|
|
545
|
+
type SimilarField = (typeof SIMILAR_FIELDS)[number];
|
|
546
|
+
/** The parts of an item the scorer reads. A full OWI record has all of them. */
|
|
547
|
+
type SimilarItem = Pick<WorkItem, 'id' | 'title'> & Partial<Pick<WorkItem, 'body' | 'labels' | 'parent' | 'links' | 'source' | 'url'>>;
|
|
548
|
+
interface SimilarOptions {
|
|
549
|
+
/** What to compare. Default: all of {@link SIMILAR_FIELDS}. */
|
|
550
|
+
fields?: readonly SimilarField[];
|
|
551
|
+
/** The most matches or pairs to return. Default {@link SIMILAR_DEFAULT_LIMIT}. */
|
|
552
|
+
limit?: number;
|
|
553
|
+
/** The lowest score returned, 0 to 1. Default {@link SIMILAR_DEFAULT_THRESHOLD}. */
|
|
554
|
+
threshold?: number;
|
|
555
|
+
}
|
|
556
|
+
/** What each signal added to a score. They sum to the score, before it is capped at 1. */
|
|
557
|
+
interface SimilarParts {
|
|
558
|
+
terms: number;
|
|
559
|
+
trigram: number;
|
|
560
|
+
labels: number;
|
|
561
|
+
parent: number;
|
|
562
|
+
link: number;
|
|
563
|
+
}
|
|
564
|
+
/** Why two things matched: every signal that added to the score, and what it found. */
|
|
565
|
+
interface SimilarWhy {
|
|
566
|
+
/** The same, in one line. */
|
|
567
|
+
summary: string;
|
|
568
|
+
/** Shared terms found in both titles (for a query: in the item's title), strongest first. */
|
|
569
|
+
titleTerms: string[];
|
|
570
|
+
/** Shared terms found in a body on at least one side, strongest first. */
|
|
571
|
+
bodyTerms: string[];
|
|
572
|
+
/** How alike the titles' character trigrams are, 0 to 1. */
|
|
573
|
+
trigram: number;
|
|
574
|
+
/** Labels both items carry. */
|
|
575
|
+
labels: string[];
|
|
576
|
+
/** The parent both items share, or null. */
|
|
577
|
+
parent: string | null;
|
|
578
|
+
/** A direct link between the two, as the first item records it, or null. */
|
|
579
|
+
link: {
|
|
580
|
+
type: LinkType;
|
|
581
|
+
direction: 'outward' | 'inward';
|
|
582
|
+
name: string;
|
|
583
|
+
} | null;
|
|
584
|
+
/** True when the two were compared on their titles alone, because one has no body. */
|
|
585
|
+
titleOnly: boolean;
|
|
586
|
+
parts: SimilarParts;
|
|
587
|
+
}
|
|
588
|
+
/** An item as a result names it. */
|
|
589
|
+
interface SimilarRef {
|
|
590
|
+
id: string;
|
|
591
|
+
title: string;
|
|
592
|
+
source: WorkItem['source'] | null;
|
|
593
|
+
url: string | null;
|
|
594
|
+
}
|
|
595
|
+
interface SimilarMatch extends SimilarRef {
|
|
596
|
+
score: number;
|
|
597
|
+
why: SimilarWhy;
|
|
598
|
+
}
|
|
599
|
+
interface SimilarPair {
|
|
600
|
+
score: number;
|
|
601
|
+
/** The pair's lower id. */
|
|
602
|
+
a: SimilarRef;
|
|
603
|
+
b: SimilarRef;
|
|
604
|
+
why: SimilarWhy;
|
|
605
|
+
}
|
|
606
|
+
/** How `pairs()` chose which pairs to compare. */
|
|
607
|
+
interface PairSearch {
|
|
608
|
+
/** Pairs scored in full. */
|
|
609
|
+
compared: number;
|
|
610
|
+
/**
|
|
611
|
+
* Terms and trigrams too common to look pairs up by, and the most items any
|
|
612
|
+
* of them was in: a pair sharing only those wasn't compared. Zero when every
|
|
613
|
+
* pair that could reach the threshold was compared.
|
|
614
|
+
*/
|
|
615
|
+
skippedFeatures: number;
|
|
616
|
+
/** The most items a feature used to find pairs was in; null when none were skipped. */
|
|
617
|
+
maxItemsPerFeature: number | null;
|
|
618
|
+
}
|
|
619
|
+
/** What to rank: the set against some text, against one of its items, or every pair in it. */
|
|
620
|
+
type SimilarRequest = {
|
|
621
|
+
query: string;
|
|
622
|
+
} | {
|
|
623
|
+
item: string;
|
|
624
|
+
} | {
|
|
625
|
+
pairs: true;
|
|
626
|
+
};
|
|
627
|
+
interface SimilarResult {
|
|
628
|
+
mode: 'query' | 'item' | 'pairs';
|
|
629
|
+
/** {@link SIMILAR_METHOD}: what the score measures, and what it misses. */
|
|
630
|
+
method: string;
|
|
631
|
+
/** How many items or pairs scored at or above the threshold; `matches` or `pairs` holds the first `limit`. */
|
|
632
|
+
count: number;
|
|
633
|
+
/** For `query` and `item`, best first; empty for `pairs`. */
|
|
634
|
+
matches: SimilarMatch[];
|
|
635
|
+
/** For `pairs`, best first; empty otherwise. */
|
|
636
|
+
pairs: SimilarPair[];
|
|
637
|
+
/** For `pairs`, how pairs were found; null otherwise. */
|
|
638
|
+
search: PairSearch | null;
|
|
639
|
+
}
|
|
640
|
+
|
|
350
641
|
/** This toil's version, as `toil version` and every envelope's `meta.version` report it. */
|
|
351
642
|
declare const version: string;
|
|
352
643
|
/**
|
|
@@ -358,9 +649,9 @@ declare const version: string;
|
|
|
358
649
|
declare const contractVersion: number;
|
|
359
650
|
/** One command `execute()` can run. */
|
|
360
651
|
interface CommandInfo {
|
|
361
|
-
/** What `execute()` takes and `meta.command` reports: `jira search`. */
|
|
652
|
+
/** What `execute()` takes and `meta.command` reports: `jira issue search`. */
|
|
362
653
|
name: string;
|
|
363
|
-
/** Its MCP tool name: `
|
|
654
|
+
/** Its MCP tool name: `jira_issue_search`. */
|
|
364
655
|
tool: string;
|
|
365
656
|
path: readonly string[];
|
|
366
657
|
/** The area it belongs to, or its group for core commands (`connections`). */
|
|
@@ -373,23 +664,73 @@ interface CommandInfo {
|
|
|
373
664
|
writesLocal: boolean;
|
|
374
665
|
/** Some calls write, depending on the input (the raw passthrough's POST, a file named with `out`); those are refused under `readOnly`. */
|
|
375
666
|
writesDependOnInput: boolean;
|
|
376
|
-
/** The JSON Schema of its input, strict, as MCP advertises it, `select`
|
|
667
|
+
/** The JSON Schema of its input, strict, as MCP advertises it, with core's `select`, `outputFormat` and `summaryFile`. */
|
|
377
668
|
inputSchema: Record<string, unknown>;
|
|
378
669
|
}
|
|
379
670
|
/** One area toil has. */
|
|
380
671
|
interface AreaSummary {
|
|
381
672
|
name: string;
|
|
382
673
|
description: string;
|
|
674
|
+
/**
|
|
675
|
+
* What a connection to it holds, in the order `toil connections add` asks:
|
|
676
|
+
* each setting, then each secret. Empty for an area that takes no
|
|
677
|
+
* connection.
|
|
678
|
+
*/
|
|
679
|
+
connection: readonly ConnectionField[];
|
|
680
|
+
}
|
|
681
|
+
/** One value a connection holds, as `toil connections add` asks for it. */
|
|
682
|
+
interface ConnectionField {
|
|
683
|
+
/** The key in config and the question's id (`setting:<name>` or `secret:<name>`). */
|
|
684
|
+
name: string;
|
|
685
|
+
description: string | null;
|
|
686
|
+
/** Asked for hidden, and kept in the OS credential store, never the file. */
|
|
687
|
+
secret: boolean;
|
|
688
|
+
/** A secret that is a password, not a token. */
|
|
689
|
+
password: boolean;
|
|
690
|
+
/** What an empty answer keeps, as the question shows it. */
|
|
691
|
+
default: string | null;
|
|
692
|
+
/** The connection isn't valid without it. */
|
|
693
|
+
required: boolean;
|
|
383
694
|
}
|
|
384
695
|
/**
|
|
385
696
|
* The commands and areas this toil has. `commands` is what `execute()`
|
|
386
697
|
* serves: every command MCP would serve with every area set up. The CLI-only
|
|
387
698
|
* ones (they prompt on a terminal, or change connections) and deletes are a
|
|
388
|
-
* person's, on the CLI, and aren't
|
|
699
|
+
* person's, on the CLI, and aren't there. `personCommands` are the ones of
|
|
700
|
+
* those `execute()` runs for a host that passes a `person` to answer them.
|
|
389
701
|
*/
|
|
390
702
|
interface Registry {
|
|
391
703
|
readonly areas: readonly AreaSummary[];
|
|
392
704
|
readonly commands: readonly CommandInfo[];
|
|
705
|
+
readonly personCommands: readonly CommandInfo[];
|
|
706
|
+
}
|
|
707
|
+
/**
|
|
708
|
+
* One question a person's command asks, which a host shows in its own
|
|
709
|
+
* interface. `id` says what it asks for, so the host can match it to a field:
|
|
710
|
+
* `area`, `setting:<key>` and `secret:<key>` (the connection's fields,
|
|
711
|
+
* `AreaSummary.connection`), `confirm` (save what was reviewed: `y` or `n`),
|
|
712
|
+
* `confirm-name` (type the connection's name to turn writes on) and `consent`
|
|
713
|
+
* (`feedback`: send the report and disclaimer the question shows to Imagile
|
|
714
|
+
* LLC, `yes` or `no`; only the person's own yes may be passed on).
|
|
715
|
+
*/
|
|
716
|
+
interface Question {
|
|
717
|
+
id: string;
|
|
718
|
+
/** The question as a terminal shows it. */
|
|
719
|
+
text: string;
|
|
720
|
+
/** Asked for hidden: the answer is a secret. */
|
|
721
|
+
secret: boolean;
|
|
722
|
+
/** What an empty answer keeps, if anything. */
|
|
723
|
+
fallback: string | null;
|
|
724
|
+
}
|
|
725
|
+
/**
|
|
726
|
+
* A person, answering through the host's own interface (Toil UI's settings
|
|
727
|
+
* pages). The host must ask them and pass on what they typed: the commands
|
|
728
|
+
* this opens are a person's, which no agent or script is ever allowed to run
|
|
729
|
+
* on its own. Return `undefined` for a question the person wasn't asked, and
|
|
730
|
+
* the command stops with `CANCELLED`, having saved nothing.
|
|
731
|
+
*/
|
|
732
|
+
interface ExecutePerson {
|
|
733
|
+
ask(question: Question): Promise<string | undefined> | string | undefined;
|
|
393
734
|
}
|
|
394
735
|
/** Options for one call. More fields may be added; none will change meaning. */
|
|
395
736
|
interface ExecuteOptions {
|
|
@@ -407,6 +748,12 @@ interface ExecuteOptions {
|
|
|
407
748
|
* characters, starting with a letter or digit (`toil-ui`).
|
|
408
749
|
*/
|
|
409
750
|
caller?: string;
|
|
751
|
+
/**
|
|
752
|
+
* Who or what the call is made on behalf of, recorded as `actor` on the
|
|
753
|
+
* audit line beside `caller` (Toil UI names one agent assignment:
|
|
754
|
+
* `assignment-<id>`). The same characters as `caller`.
|
|
755
|
+
*/
|
|
756
|
+
actor?: string;
|
|
410
757
|
/** Cancels the call; the envelope is then `CANCELLED`. */
|
|
411
758
|
signal?: AbortSignal;
|
|
412
759
|
/**
|
|
@@ -422,6 +769,19 @@ interface ExecuteOptions {
|
|
|
422
769
|
workspace?: string;
|
|
423
770
|
/** Add every request to `meta.requests`, as `--verbose` does. */
|
|
424
771
|
verbose?: boolean;
|
|
772
|
+
/**
|
|
773
|
+
* The person the call is for, answering the questions toil would ask on a
|
|
774
|
+
* terminal. With one, `execute()` also runs `registry.personCommands`
|
|
775
|
+
* (`connections add`, `login`, `remove`, `writes` and `default`, and
|
|
776
|
+
* `feedback`), asking each question through it: a secret goes from their
|
|
777
|
+
* answer straight to the OS credential store and is never in the input, the
|
|
778
|
+
* envelope or the audit log, turning writes on still needs them to type the
|
|
779
|
+
* connection's name, and a feedback report is sent only on their `yes` to
|
|
780
|
+
* the `consent` question, which shows the report and the disclaimer. With
|
|
781
|
+
* `readOnly` too, nothing is asked: `feedback` returns its preview and sends
|
|
782
|
+
* nothing. Without one, those commands are refused, as before.
|
|
783
|
+
*/
|
|
784
|
+
person?: ExecutePerson;
|
|
425
785
|
}
|
|
426
786
|
/** Built on first read: a JSON Schema for every command takes a moment, and most hosts look once. */
|
|
427
787
|
declare const registry: Registry;
|
|
@@ -429,7 +789,7 @@ declare const registry: Registry;
|
|
|
429
789
|
* Runs one command, as `toil <name>` would, and returns its envelope. Never
|
|
430
790
|
* throws: an unknown command, a bad option or a failure inside is an envelope
|
|
431
791
|
* with `ok: false`, like every other. `input` is the command's MCP fields
|
|
432
|
-
* (`{ jql: "project = PAY",
|
|
792
|
+
* (`{ jql: "project = PAY", limit: 50 }`), checked strictly.
|
|
433
793
|
*/
|
|
434
794
|
declare function execute(command: string, input?: Record<string, unknown>, options?: ExecuteOptions): Promise<Envelope>;
|
|
435
795
|
/**
|
|
@@ -447,14 +807,30 @@ declare function mapOwi(input: unknown, options?: OwiMapOptions): OwiResult;
|
|
|
447
807
|
interface OwiMapOptions {
|
|
448
808
|
/** OWI fields pointed at a team's own fields: a dossier section's `fields`, or `name=field` strings. */
|
|
449
809
|
fields?: Record<string, string> | string[];
|
|
450
|
-
/** The command whose bare `data` the input is (`jira search`). */
|
|
810
|
+
/** The command whose bare `data` the input is (`jira issue search`). */
|
|
451
811
|
command?: string;
|
|
452
|
-
/** The item a keyless history (`jira
|
|
812
|
+
/** The item a keyless history (`jira issue history`, `github issue history`) belongs to. */
|
|
453
813
|
key?: string;
|
|
814
|
+
/** Where work item keys in a pull request's title, branch and description point: `PAY-{n}=corp-jira` strings, or `{ text, connection }`. */
|
|
815
|
+
keyPatterns?: Array<string | KeyPattern>;
|
|
816
|
+
/** Pull request author kinds set by hand, by author id: `{ "release-bot": "BOT" }`, or `id=KIND` strings. */
|
|
817
|
+
authorKinds?: Record<string, string> | string[];
|
|
454
818
|
}
|
|
819
|
+
/**
|
|
820
|
+
* Likely duplicates among OWI records you already hold, scored the way
|
|
821
|
+
* `util owi similar` scores them (src/core/owi/similar.ts), in-process and
|
|
822
|
+
* synchronous: `{ query }` ranks the records against some text, `{ item }`
|
|
823
|
+
* against one of them, `{ pairs: true }` lists likely duplicate pairs.
|
|
824
|
+
* `records` is OWI items (mapOwi's `items`), or the text `util owi map`
|
|
825
|
+
* printed. Lexical and deterministic: the same records give the same result.
|
|
826
|
+
* It doesn't run in the bounded worker the way `execute('util owi similar', …)`
|
|
827
|
+
* does, so a host scoring a very large set should use that. An unknown item, or
|
|
828
|
+
* a query with no words to compare, throws a ToilError with a fix.
|
|
829
|
+
*/
|
|
830
|
+
declare function findSimilar(records: readonly SimilarItem[] | string, request: SimilarRequest, options?: SimilarOptions): SimilarResult;
|
|
455
831
|
/** The OWI version this toil writes, as every item's `owi` says. */
|
|
456
832
|
declare const owiVersion: string;
|
|
457
833
|
/** docs/owi/schema.json, the JSON Schema (2020-12) every OWI item validates against. */
|
|
458
834
|
declare const owiSchema: Record<string, unknown>;
|
|
459
835
|
|
|
460
|
-
export { type ApiAnswer, type AreaSummary, type Body, type CommandInfo, type CommandKind, type ContextReport, type ContextSource, type ContextValue, type DossierReport, type Envelope, type ErrorBody, type ErrorCode, type Estimate, type EstimateUnit, type ExecuteOptions, type FieldOverrides, type History, type Iteration, type IterationChange, type Link, type LinkType, type Meta, type OrphanHistory, type OwiMapOptions, type OwiResult, type OwiSkipped, type Page, type PageProgress, type Person, type ProgressEvent, type Registry, type RequestProgress, type RetryProgress, type StatusCategory, type Transition, type Unmapped, type Warning, type WorkItem, type WorkItemType, contractVersion, execute, mapOwi, owiSchema, owiVersion, registry, version };
|
|
836
|
+
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 DossierReport, 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 SimilarField, type SimilarItem, type SimilarMatch, type SimilarOptions, type SimilarPair, type SimilarParts, type SimilarRef, type SimilarRequest, type SimilarResult, type SimilarWhy, type StatusCategory, type Transition, type Unmapped, type Warning, type WorkItem, type WorkItemType, contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version };
|
package/dist/api.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
// @imagile-dev/toil/api. The code is in ./toil-lib.js; this re-exports the API and nothing else.
|
|
2
|
-
export { contractVersion, execute, mapOwi, owiSchema, owiVersion, registry, version } from './toil-lib.js';
|
|
2
|
+
export { contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version } from './toil-lib.js';
|