@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/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-issue`).
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.1, as TypeScript: one work item
222
- * from Jira, Azure DevOps or GitHub in one shape. docs/owi/spec.md is the
223
- * specification and docs/owi/schema.json the JSON Schema every mapped item is
224
- * checked against; these types follow both. Additive changes only, and every
225
- * record says which version it is (`owi`). Three trackers, one form, which is
226
- * more than most standardisation programmes manage before the steering group.
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.1";
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
- /** The OWI fields a team can point at a field of its own, with `fields`. */
328
- declare const OVERRIDABLE: readonly ["estimate", "estimateUnit", "priority", "type", "team", "dueDate", "iteration"];
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: `jira_search`. */
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` included. */
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 here.
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", maxResults: 50 }`), checked strictly.
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 get-changelog`, `github issue-events`) belongs to. */
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';