@imagile-dev/toil 0.1.0-alpha.3 → 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 CHANGED
@@ -15,6 +15,12 @@ test/fixtures/jmespath/, as distributed with jmespath.py
15
15
  or its affiliates, licensed under the MIT License (see
16
16
  test/fixtures/jmespath/LICENSE). It is not part of the published package.
17
17
 
18
+ The repository's tests also include the TOON specification's encode fixtures, in
19
+ test/fixtures/toon/, from https://github.com/toon-format/spec (release v4.4.0),
20
+ Copyright (c) 2025-PRESENT Johann Schopplich, licensed under the MIT License (see
21
+ test/fixtures/toon/LICENSE). They are not part of the published package; the TOON
22
+ encoder in src/core/output/toon.ts is toil's own, written from the specification.
23
+
18
24
  The util commands that read YAML or validate JSON Schema bundle, loaded only
19
25
  when such a command runs:
20
26
 
package/README.md CHANGED
@@ -1,4 +1,25 @@
1
- # toil
1
+ <p align="center">
2
+ <a href="https://imagile-dev.github.io/toil/">
3
+ <img src=".github/assets/banner.webp" width="100%" alt="toil, by Imagile: the token-efficient alternative to MCP. One CLI for your enterprise tools and databases.">
4
+ </a>
5
+ </p>
6
+
7
+ <p align="center">
8
+ <a href="https://www.npmjs.com/package/@imagile-dev/toil"><img src="https://img.shields.io/npm/v/@imagile-dev/toil/alpha?style=flat-square&label=npm&labelColor=16130f&color=ff6a3d" alt="npm version (alpha)"></a>
9
+ <a href="https://github.com/imagile-dev/toil/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/imagile-dev/toil/ci.yml?branch=main&style=flat-square&label=CI&labelColor=16130f" alt="CI status on main"></a>
10
+ <a href="package.json"><img src="https://img.shields.io/badge/node-%E2%89%A5%2024.14-ffb84d?style=flat-square&labelColor=16130f" alt="Node.js 24.14 or later"></a>
11
+ <a href="https://imagile-dev.github.io/toil/how-it-works/"><img src="https://img.shields.io/badge/runtime%20dependencies-0-ffb84d?style=flat-square&labelColor=16130f" alt="No runtime dependencies"></a>
12
+ <a href="LICENSE"><img src="https://img.shields.io/github/license/imagile-dev/toil?style=flat-square&labelColor=16130f&color=b4a998" alt="Apache 2.0 license"></a>
13
+ </p>
14
+
15
+ <p align="center">
16
+ <a href="https://imagile-dev.github.io/toil/"><b>Website</b></a> ·
17
+ <a href="https://imagile-dev.github.io/toil/docs/"><b>Docs</b></a> ·
18
+ <a href="https://imagile-dev.github.io/toil/how-it-works/"><b>How it works</b></a> ·
19
+ <a href="https://imagile-dev.github.io/toil/integrations/"><b>Integrations</b></a> ·
20
+ <a href="https://imagile-dev.github.io/toil/principles/"><b>Principles</b></a> ·
21
+ <a href="https://imagile-dev.github.io/toil/feedback/"><b>Feedback</b></a>
22
+ </p>
2
23
 
3
24
  The token-efficient alternative to MCP: one CLI that gives agents your enterprise
4
25
  tools and your databases while spending as little of their context as it can.
@@ -22,6 +43,41 @@ and documented at [imagile-dev.github.io/toil](https://imagile-dev.github.io/toi
22
43
  README is for working from a clone of this repository; the site covers everything else
23
44
  in more depth.
24
45
 
46
+ ### At a glance
47
+
48
+ One command, one envelope, and only the fields the task asked for. A real run of
49
+ the released `0.1.0-alpha.2`:
50
+
51
+ ```console
52
+ $ toil util size package.json --select "{bytes: bytes, tokens: tokens}"
53
+ {"ok":true,"data":{"bytes":2162,"tokens":541},"error":null,"meta":{"command":"util size","durationMs":90,"version":"0.1.0-alpha.2","contractVersion":1,"warnings":[{"code":"APPROXIMATED","message":"tokens is approximate: ceil(characters / 4) per file, counting characters as Unicode code points. An estimate, not any model's tokenizer: real counts vary by model and by content."}]}}
54
+ ```
55
+
56
+ The estimate says it's an estimate. Every result says where it came from and how
57
+ precise it is.
58
+
59
+ ### Why toil
60
+
61
+ <p align="center">
62
+ <img src=".github/assets/crate-red-tape.webp" width="720" alt="A cardboard box in an amber-striped hard hat walks calmly through a maze of barrier tape and traffic cones, the tape parted neatly behind it, carrying a small parcel past an ignored filing cabinet and a rubber stamp.">
63
+ </p>
64
+
65
+ <table>
66
+ <tr>
67
+ <td width="33%" valign="top"><b>Runs where executables can't</b><br>Plain JavaScript on Node. No binary, no native module, no install script, no runtime dependencies. Node and one npm package are all a security team has to approve.</td>
68
+ <td width="33%" valign="top"><b>One core, three front doors</b><br>The CLI, the MCP server (<code>toil mcp</code>) and a programmatic API all run the same <code>execute()</code>, and a test proves the CLI and MCP agree on every command.</td>
69
+ <td width="33%" valign="top"><b>Safe when an agent drives</b><br>Reads are free. A write needs <code>writes: true</code> on the connection, set by a human, and <code>--allow-write</code> on the call. Deletes are never served over MCP.</td>
70
+ </tr>
71
+ <tr>
72
+ <td width="33%" valign="top"><b>Secrets stay put</b><br>Credentials come from the OS credential store or env vars, never from a plaintext file, and go only to the connection they belong to, or one you paired them with.</td>
73
+ <td width="33%" valign="top"><b>The environment wins</b><br>CI and agents configure entirely through env vars, which override anything on disk. No repository config file can switch on writes.</td>
74
+ <td width="33%" valign="top"><b>Honest about status</b><br>Every integration says how far it has been verified (<code>unit</code>, <code>live</code> or <code>stable</code>), and every error says what went wrong and what to do about it.</td>
75
+ </tr>
76
+ </table>
77
+
78
+ No telemetry, no update checks, no call home: toil talks only to the hosts you
79
+ point it at. Windows, macOS and Linux are all first-class.
80
+
25
81
  ## Quick start
26
82
 
27
83
  There are two ways to run toil: install it from npm, or run it from a clone. Both
@@ -85,7 +141,8 @@ A build rewrites the committed `dist/toil.js`, so run `git checkout -- dist/` be
85
141
  `git pull`, then build again (or run `node scripts/setup.mjs`).
86
142
 
87
143
  Don't commit the rebuilt `dist/`; `git checkout -- dist/` puts the released bundle
88
- back. [CLAUDE.md](CLAUDE.md) has the rest of the gate (typecheck, lint, tests).
144
+ back. With `TOIL_BUILD_DIR` set to another folder, the build goes there and leaves
145
+ `dist/` alone, which is how Toil UI's `verify:ui` builds into `.scratch/toil`. [CLAUDE.md](CLAUDE.md) has the rest of the gate (typecheck, lint, tests).
89
146
 
90
147
  ### Pointing an agent at the clone
91
148
 
@@ -156,6 +213,10 @@ the one URL it prints when it starts. Installing toil never installs it.
156
213
  ## Contributing
157
214
 
158
215
  Read [CLAUDE.md](CLAUDE.md). It holds the rules for people and agents alike.
216
+ [CONTRIBUTING.md](.github/CONTRIBUTING.md) is the short version: issues, branches,
217
+ the gate and how review works. Questions and bug reports go through
218
+ [SUPPORT.md](.github/SUPPORT.md), and security reports through
219
+ [SECURITY.md](.github/SECURITY.md), never a public issue.
159
220
 
160
221
  ## License
161
222
 
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,7 +664,7 @@ 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. */
@@ -457,6 +748,12 @@ interface ExecuteOptions {
457
748
  * characters, starting with a letter or digit (`toil-ui`).
458
749
  */
459
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;
460
757
  /** Cancels the call; the envelope is then `CANCELLED`. */
461
758
  signal?: AbortSignal;
462
759
  /**
@@ -492,7 +789,7 @@ declare const registry: Registry;
492
789
  * Runs one command, as `toil <name>` would, and returns its envelope. Never
493
790
  * throws: an unknown command, a bad option or a failure inside is an envelope
494
791
  * with `ok: false`, like every other. `input` is the command's MCP fields
495
- * (`{ jql: "project = PAY", maxResults: 50 }`), checked strictly.
792
+ * (`{ jql: "project = PAY", limit: 50 }`), checked strictly.
496
793
  */
497
794
  declare function execute(command: string, input?: Record<string, unknown>, options?: ExecuteOptions): Promise<Envelope>;
498
795
  /**
@@ -510,14 +807,30 @@ declare function mapOwi(input: unknown, options?: OwiMapOptions): OwiResult;
510
807
  interface OwiMapOptions {
511
808
  /** OWI fields pointed at a team's own fields: a dossier section's `fields`, or `name=field` strings. */
512
809
  fields?: Record<string, string> | string[];
513
- /** The command whose bare `data` the input is (`jira search`). */
810
+ /** The command whose bare `data` the input is (`jira issue search`). */
514
811
  command?: string;
515
- /** 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. */
516
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[];
517
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;
518
831
  /** The OWI version this toil writes, as every item's `owi` says. */
519
832
  declare const owiVersion: string;
520
833
  /** docs/owi/schema.json, the JSON Schema (2020-12) every OWI item validates against. */
521
834
  declare const owiSchema: Record<string, unknown>;
522
835
 
523
- export { type ApiAnswer, type AreaSummary, type Body, 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 Link, type LinkType, type Meta, type OrphanHistory, type OwiMapOptions, type OwiResult, type OwiSkipped, type Page, type PageProgress, type Person, type ProgressEvent, type Question, 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';