@imagile-dev/toil 0.1.0-alpha.3 → 0.1.0-alpha.5

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
 
@@ -151,11 +208,16 @@ separate package: a local web app with one dashboard per dossier, syncing throug
151
208
  toil into a local cache with your own connections, read-only. It binds loopback and opens only from
152
209
  the one URL it prints when it starts. Installing toil never installs it.
153
210
  [`ui/README.md`](ui/README.md) and the
154
- [docs page](https://imagile-dev.github.io/toil/docs/ui/) say how to run it.
211
+ [docs page](https://imagile-dev.github.io/toil/docs/ui/) say how to run it, and
212
+ [the Toil UI page](https://imagile-dev.github.io/toil/ui/) runs it on sample data.
155
213
 
156
214
  ## Contributing
157
215
 
158
216
  Read [CLAUDE.md](CLAUDE.md). It holds the rules for people and agents alike.
217
+ [CONTRIBUTING.md](.github/CONTRIBUTING.md) is the short version: issues, branches,
218
+ the gate and how review works. Questions and bug reports go through
219
+ [SUPPORT.md](.github/SUPPORT.md), and security reports through
220
+ [SECURITY.md](.github/SECURITY.md), never a public issue.
159
221
 
160
222
  ## License
161
223
 
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,86 @@ 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
+ * What a pasted secret looks like when it arrives, checked before it goes to
286
+ * the OS credential store (#358). One function, `checkSecret()`, decides every
287
+ * case, and every way of entering a secret uses it: the CLI's terminal
288
+ * prompter (through `askCheckedSecret()`), a host's `person` through the API,
289
+ * and Toil UI's password fields, which run it in the page. So a terminal and
290
+ * a form say the same thing in the same words, and can't drift apart.
291
+ *
292
+ * Nothing here shows any part of the value: not a prefix, not a suffix, not a
293
+ * hash. What it reports is the length, the whitespace it took off the ends,
294
+ * and the wrapper it found ("Bearer ", "token ", quotes), which is boilerplate
295
+ * and never the secret. A paste is checked for the usual accidents, the way a
296
+ * form is checked for a missing signature, except that this one tells you which box.
227
297
  */
228
- declare const OWI_VERSION: "0.1";
298
+
299
+ /** How a secret is asked for. */
300
+ interface SecretRules {
301
+ /** A password rather than a token: a space inside it is allowed, since people put them in passwords. */
302
+ password?: boolean;
303
+ /**
304
+ * What an empty answer means: ask again, since the connection needs one
305
+ * (`required`); keep the secret already stored (`keep`, `login` on an
306
+ * existing connection); or store none (`skip`, an optional one).
307
+ */
308
+ empty: 'required' | 'keep' | 'skip';
309
+ /**
310
+ * The env vars that define this connection with no file at all
311
+ * (`TOIL_CONN_<NAME>_AREA=<area>`, then each setting and secret), named in
312
+ * the fix for an empty required secret, so a machine with no credential store
313
+ * has a way out that isn't Ctrl+C alone. Only the whole set works: a variable
314
+ * for a connection that was never saved names no connection.
315
+ */
316
+ envVars?: readonly string[];
317
+ }
318
+ /** A wrapper around the value that the person is asked to remove: quotes, or a `Bearer ` / `token ` prefix. */
319
+ interface SecretWrapper {
320
+ /** The value without it. */
321
+ without: string;
322
+ /** Its length, in characters. */
323
+ withoutLength: number;
324
+ /** The question: `This starts with "Bearer ". Store it without that? [Y/n]`. */
325
+ question: string;
326
+ /** What it is, for a button: `"Bearer "`, `the quotes`. */
327
+ what: string;
328
+ }
329
+ type SecretCheck = {
330
+ status: 'empty';
331
+ empty: SecretRules['empty'];
332
+ /** `Kept the existing secret.`, or why an empty answer won't do. */
333
+ message: string;
334
+ /** Set when it's refused (`required`): what to do instead. */
335
+ fix: string | null;
336
+ } | {
337
+ status: 'refused';
338
+ /** Why: a line break, or a space, inside the value. */
339
+ message: string;
340
+ fix: string;
341
+ length: number;
342
+ } | {
343
+ status: 'ok';
344
+ /** The value with surrounding whitespace removed: what is stored, unless the wrapper is removed too. */
345
+ value: string;
346
+ length: number;
347
+ /** What trimming took off, in words (`a trailing newline`), or null. */
348
+ removed: string | null;
349
+ /** `Received 40 characters (removed a trailing newline).` */
350
+ received: string;
351
+ wrapper: SecretWrapper | null;
352
+ };
353
+
354
+ /**
355
+ * The Open Work Item (OWI) model, version 0.2, as TypeScript: one work item
356
+ * from Jira, Azure DevOps or GitHub in one shape, and since 0.2 one change
357
+ * (a pull request) from GitHub, Bitbucket or Azure DevOps in another.
358
+ * docs/owi/spec.md is the specification and docs/owi/schema.json the JSON
359
+ * Schema every mapped record is checked against; these types follow both.
360
+ * Additive changes only, and every record says which version it is (`owi`).
361
+ * Three trackers, one form, which is more than most standardisation
362
+ * programmes manage before the steering group.
363
+ */
364
+ declare const OWI_VERSION: "0.2";
229
365
  type OwiArea = string;
230
366
  type WorkItemType = 'EPIC' | 'STORY' | 'TASK' | 'BUG' | 'INCIDENT' | 'OTHER';
231
367
  type StatusCategory = 'TODO' | 'IN_PROGRESS' | 'DONE' | 'UNKNOWN';
@@ -324,10 +460,97 @@ interface OrphanHistory {
324
460
  id: string;
325
461
  history: History;
326
462
  }
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"];
463
+ /**
464
+ * The OWI fields a team can point at a field of its own, with `fields`, and
465
+ * two settings for a GitHub repository run without a board: `estimateLabel`,
466
+ * the label pattern that holds an estimate (`points: {n}`), and
467
+ * `iterationDays`, how long a milestone's sprint runs.
468
+ */
469
+ declare const OVERRIDABLE: readonly ["estimate", "estimateUnit", "priority", "type", "team", "dueDate", "iteration", "estimateLabel", "iterationDays"];
329
470
  type Overridable = (typeof OVERRIDABLE)[number];
330
471
  type FieldOverrides = Partial<Record<Overridable, string>>;
472
+ type ChangeState = 'OPEN' | 'MERGED' | 'DECLINED' | 'DRAFT';
473
+ type ReviewerState = 'APPROVED' | 'CHANGES_REQUESTED' | 'PENDING';
474
+ type ReviewState = 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' | 'DISMISSED';
475
+ type ChecksState = 'PASSING' | 'FAILING' | 'PENDING' | 'NONE';
476
+ type AuthorKind = 'HUMAN' | 'AGENT' | 'BOT';
477
+ /** Which signal set `authorKind`: never a guess, and `default` when there was none. */
478
+ type AuthorKindSource = 'override' | 'account' | 'trailer' | 'branch' | 'default';
479
+ /** Someone asked to review, and where their review stands now. */
480
+ interface Reviewer {
481
+ person: Person;
482
+ state: ReviewerState;
483
+ }
484
+ /** One review as it happened: an approval, a request for changes, a comment, or an approval withdrawn. */
485
+ interface Review {
486
+ by: Person;
487
+ state: ReviewState;
488
+ at: string;
489
+ }
490
+ interface ChangeSize {
491
+ files: number | null;
492
+ additions: number | null;
493
+ deletions: number | null;
494
+ }
495
+ /** A pull request, as OWI 0.2 models it: the change that carries work, not the work. */
496
+ interface Change {
497
+ owi: typeof OWI_VERSION;
498
+ /** `<connection>:<repo>#<number>`: `github:imagile/payments-web#41`, `corp-bitbucket:PAY/payments-core#311`. */
499
+ id: string;
500
+ source: {
501
+ area: OwiArea;
502
+ connection: string;
503
+ key: string;
504
+ command: string;
505
+ };
506
+ url: string | null;
507
+ /** The repository as the source names it: `owner/repo`, `PROJECT/slug`, `workspace/slug`, `project/repo`. */
508
+ repo: string;
509
+ title: string;
510
+ branch: {
511
+ source: string | null;
512
+ target: string | null;
513
+ };
514
+ state: ChangeState;
515
+ author: Person | null;
516
+ authorKind: AuthorKind;
517
+ authorKindSource: AuthorKindSource;
518
+ /** What the signal was, in words (`account type Bot`, a Co-Authored-By trailer, `branch claude/fix-retries`); null for the default. */
519
+ authorKindSignal: string | null;
520
+ reviewers: Reviewer[];
521
+ /** Every review in order, or null when the input held none (a list, or a get without its reviews). */
522
+ reviews: Review[] | null;
523
+ /** The checks on the latest commit, rolled up; null when they weren't read. */
524
+ checks: ChecksState | null;
525
+ /** When the checks came to their state: for FAILING, the earliest finish of a check failing now; otherwise the latest check. */
526
+ checksAt: string | null;
527
+ /** Whether it merges cleanly: false is a conflict; null when the source didn't say. */
528
+ mergeable: boolean | null;
529
+ size: ChangeSize | null;
530
+ /** The OWI ids of the work items its title, branch and description name. */
531
+ workItems: string[];
532
+ /** For a merged change: the commit it merged as. */
533
+ mergeCommit: string | null;
534
+ created: string | null;
535
+ firstReviewAt: string | null;
536
+ approvedAt: string | null;
537
+ mergedAt: string | null;
538
+ closedAt: string | null;
539
+ updated: string | null;
540
+ unmapped: Unmapped[];
541
+ native: Record<string, unknown>;
542
+ }
543
+ /**
544
+ * A key pattern: text with `{n}` where the number is, and the connection the
545
+ * key belongs to. The key is the text matched (`PAY-{n}` finds `PAY-101`;
546
+ * `imagile/payments-web#{n}` finds `imagile/payments-web#42`), except that a
547
+ * mention ending `#{n}` with no repository in it names the number alone
548
+ * (`AB#{n}`, Azure Boards' mention, finds key `2302`).
549
+ */
550
+ interface KeyPattern {
551
+ text: string;
552
+ connection: string;
553
+ }
331
554
  interface OwiWarning {
332
555
  code: string;
333
556
  message: string;
@@ -341,12 +564,150 @@ interface OwiSkipped {
341
564
  }
342
565
  interface OwiResult {
343
566
  items: WorkItem[];
567
+ /** Pull requests, as OWI 0.2 changes. */
568
+ changes: Change[];
344
569
  /** Histories for items that weren't in the input, so a caller can attach them to items it already has. */
345
570
  histories: OrphanHistory[];
346
571
  skipped: OwiSkipped[];
347
572
  warnings: OwiWarning[];
348
573
  }
349
574
 
575
+ /**
576
+ * Likely duplicates among Open Work Items, found by lexical scoring alone: no
577
+ * model, no network, and the same answer on every run and every platform.
578
+ * `toil util owi similar` runs it in the bounded worker; Toil UI's item page
579
+ * and its agent call it directly on the items they hold, and anything that
580
+ * needs "does this already exist?" (#304) imports it from here.
581
+ *
582
+ * How a score is made, so its `why` can say exactly what drove it:
583
+ *
584
+ * - **Terms.** Titles and bodies (Markdown, wiki markup, HTML and ADF, read
585
+ * as plain text) become lowercase words, with accents folded, common English
586
+ * words dropped and a light suffix stemmer applied. Each term is weighted by
587
+ * BM25: its IDF over the set, times its saturated, length-normalised
588
+ * frequency, with a title occurrence worth twice a body one.
589
+ * - Two items: the cosine of their BM25 vectors. When either has no body,
590
+ * both are compared on their titles alone, so a missing body never counts
591
+ * against an item.
592
+ * - A query: how much of the query's IDF the item covers, a term in its title
593
+ * counting fully and one only in its body at most 0.7.
594
+ * - **Trigrams.** The character trigrams of the titles' words (each padded with
595
+ * a space), compared with Dice's coefficient, which catches typos and other
596
+ * forms of a word the stemmer leaves apart.
597
+ * - **Boosts.** Small ones for shared labels (rarer labels count more), the
598
+ * same parent, and a direct link between the two items. Together they can't
599
+ * reach the default threshold on their own.
600
+ *
601
+ * The score is 0.7 of the terms and 0.3 of the trigrams (all terms when titles
602
+ * aren't compared), plus the boosts, capped at 1 and rounded to four places.
603
+ * It measures shared words, not meaning: two items that describe one problem
604
+ * in entirely different words score low, and the docs say so.
605
+ *
606
+ * Determinism: items are indexed in id order, every sum runs in a fixed order,
607
+ * a pair is always scored from its lower id, ties are broken by id with a
608
+ * plain code-unit comparison (never the locale's), and only the rounded
609
+ * figures leave this module. Two runs on the same input are byte-identical,
610
+ * which is more than can be said for the minutes of most duplicate-review
611
+ * meetings.
612
+ */
613
+ /** What the scorer can compare. `parent` and `links` only ever add a small boost. */
614
+ declare const SIMILAR_FIELDS: readonly ["title", "body", "labels", "parent", "links"];
615
+ type SimilarField = (typeof SIMILAR_FIELDS)[number];
616
+ /** The parts of an item the scorer reads. A full OWI record has all of them. */
617
+ type SimilarItem = Pick<WorkItem, 'id' | 'title'> & Partial<Pick<WorkItem, 'body' | 'labels' | 'parent' | 'links' | 'source' | 'url'>>;
618
+ interface SimilarOptions {
619
+ /** What to compare. Default: all of {@link SIMILAR_FIELDS}. */
620
+ fields?: readonly SimilarField[];
621
+ /** The most matches or pairs to return. Default {@link SIMILAR_DEFAULT_LIMIT}. */
622
+ limit?: number;
623
+ /** The lowest score returned, 0 to 1. Default {@link SIMILAR_DEFAULT_THRESHOLD}. */
624
+ threshold?: number;
625
+ }
626
+ /** What each signal added to a score. They sum to the score, before it is capped at 1. */
627
+ interface SimilarParts {
628
+ terms: number;
629
+ trigram: number;
630
+ labels: number;
631
+ parent: number;
632
+ link: number;
633
+ }
634
+ /** Why two things matched: every signal that added to the score, and what it found. */
635
+ interface SimilarWhy {
636
+ /** The same, in one line. */
637
+ summary: string;
638
+ /** Shared terms found in both titles (for a query: in the item's title), strongest first. */
639
+ titleTerms: string[];
640
+ /** Shared terms found in a body on at least one side, strongest first. */
641
+ bodyTerms: string[];
642
+ /** How alike the titles' character trigrams are, 0 to 1. */
643
+ trigram: number;
644
+ /** Labels both items carry. */
645
+ labels: string[];
646
+ /** The parent both items share, or null. */
647
+ parent: string | null;
648
+ /** A direct link between the two, as the first item records it, or null. */
649
+ link: {
650
+ type: LinkType;
651
+ direction: 'outward' | 'inward';
652
+ name: string;
653
+ } | null;
654
+ /** True when the two were compared on their titles alone, because one has no body. */
655
+ titleOnly: boolean;
656
+ parts: SimilarParts;
657
+ }
658
+ /** An item as a result names it. */
659
+ interface SimilarRef {
660
+ id: string;
661
+ title: string;
662
+ source: WorkItem['source'] | null;
663
+ url: string | null;
664
+ }
665
+ interface SimilarMatch extends SimilarRef {
666
+ score: number;
667
+ why: SimilarWhy;
668
+ }
669
+ interface SimilarPair {
670
+ score: number;
671
+ /** The pair's lower id. */
672
+ a: SimilarRef;
673
+ b: SimilarRef;
674
+ why: SimilarWhy;
675
+ }
676
+ /** How `pairs()` chose which pairs to compare. */
677
+ interface PairSearch {
678
+ /** Pairs scored in full. */
679
+ compared: number;
680
+ /**
681
+ * Terms and trigrams too common to look pairs up by, and the most items any
682
+ * of them was in: a pair sharing only those wasn't compared. Zero when every
683
+ * pair that could reach the threshold was compared.
684
+ */
685
+ skippedFeatures: number;
686
+ /** The most items a feature used to find pairs was in; null when none were skipped. */
687
+ maxItemsPerFeature: number | null;
688
+ }
689
+ /** What to rank: the set against some text, against one of its items, or every pair in it. */
690
+ type SimilarRequest = {
691
+ query: string;
692
+ } | {
693
+ item: string;
694
+ } | {
695
+ pairs: true;
696
+ };
697
+ interface SimilarResult {
698
+ mode: 'query' | 'item' | 'pairs';
699
+ /** {@link SIMILAR_METHOD}: what the score measures, and what it misses. */
700
+ method: string;
701
+ /** How many items or pairs scored at or above the threshold; `matches` or `pairs` holds the first `limit`. */
702
+ count: number;
703
+ /** For `query` and `item`, best first; empty for `pairs`. */
704
+ matches: SimilarMatch[];
705
+ /** For `pairs`, best first; empty otherwise. */
706
+ pairs: SimilarPair[];
707
+ /** For `pairs`, how pairs were found; null otherwise. */
708
+ search: PairSearch | null;
709
+ }
710
+
350
711
  /** This toil's version, as `toil version` and every envelope's `meta.version` report it. */
351
712
  declare const version: string;
352
713
  /**
@@ -358,9 +719,9 @@ declare const version: string;
358
719
  declare const contractVersion: number;
359
720
  /** One command `execute()` can run. */
360
721
  interface CommandInfo {
361
- /** What `execute()` takes and `meta.command` reports: `jira search`. */
722
+ /** What `execute()` takes and `meta.command` reports: `jira issue search`. */
362
723
  name: string;
363
- /** Its MCP tool name: `jira_search`. */
724
+ /** Its MCP tool name: `jira_issue_search`. */
364
725
  tool: string;
365
726
  path: readonly string[];
366
727
  /** The area it belongs to, or its group for core commands (`connections`). */
@@ -373,7 +734,7 @@ interface CommandInfo {
373
734
  writesLocal: boolean;
374
735
  /** Some calls write, depending on the input (the raw passthrough's POST, a file named with `out`); those are refused under `readOnly`. */
375
736
  writesDependOnInput: boolean;
376
- /** The JSON Schema of its input, strict, as MCP advertises it, `select` included. */
737
+ /** The JSON Schema of its input, strict, as MCP advertises it, with core's `select`, `outputFormat` and `summaryFile`. */
377
738
  inputSchema: Record<string, unknown>;
378
739
  }
379
740
  /** One area toil has. */
@@ -418,7 +779,13 @@ interface Registry {
418
779
  * interface. `id` says what it asks for, so the host can match it to a field:
419
780
  * `area`, `setting:<key>` and `secret:<key>` (the connection's fields,
420
781
  * `AreaSummary.connection`), `confirm` (save what was reviewed: `y` or `n`),
421
- * `confirm-name` (type the connection's name to turn writes on) and `consent`
782
+ * `confirm-name` (type the connection's name to turn writes on), `unwrap:<key>`
783
+ * (the secret for `<key>` is in quotes or starts with `Bearer ` or `token `:
784
+ * `y` stores it without them, `n` as entered; `checkSecret` says which before
785
+ * the call, so a host can ask its person first), for `dossiers onboard`
786
+ * `create:<section>` (add a connection that dossier section needs: `y` or `n`),
787
+ * `name:<section>` (the new connection's name) and `pin:<section>` (which
788
+ * matching connection the person's own copy uses), and `consent`
422
789
  * (`feedback`: send the report and disclaimer the question shows to Imagile
423
790
  * LLC, `yes` or `no`; only the person's own yes may be passed on).
424
791
  */
@@ -457,6 +824,12 @@ interface ExecuteOptions {
457
824
  * characters, starting with a letter or digit (`toil-ui`).
458
825
  */
459
826
  caller?: string;
827
+ /**
828
+ * Who or what the call is made on behalf of, recorded as `actor` on the
829
+ * audit line beside `caller` (Toil UI names one agent assignment:
830
+ * `assignment-<id>`). The same characters as `caller`.
831
+ */
832
+ actor?: string;
460
833
  /** Cancels the call; the envelope is then `CANCELLED`. */
461
834
  signal?: AbortSignal;
462
835
  /**
@@ -492,7 +865,7 @@ declare const registry: Registry;
492
865
  * Runs one command, as `toil <name>` would, and returns its envelope. Never
493
866
  * throws: an unknown command, a bad option or a failure inside is an envelope
494
867
  * with `ok: false`, like every other. `input` is the command's MCP fields
495
- * (`{ jql: "project = PAY", maxResults: 50 }`), checked strictly.
868
+ * (`{ jql: "project = PAY", limit: 50 }`), checked strictly.
496
869
  */
497
870
  declare function execute(command: string, input?: Record<string, unknown>, options?: ExecuteOptions): Promise<Envelope>;
498
871
  /**
@@ -510,14 +883,41 @@ declare function mapOwi(input: unknown, options?: OwiMapOptions): OwiResult;
510
883
  interface OwiMapOptions {
511
884
  /** OWI fields pointed at a team's own fields: a dossier section's `fields`, or `name=field` strings. */
512
885
  fields?: Record<string, string> | string[];
513
- /** The command whose bare `data` the input is (`jira search`). */
886
+ /** The command whose bare `data` the input is (`jira issue search`). */
514
887
  command?: string;
515
- /** The item a keyless history (`jira get-changelog`, `github issue-events`) belongs to. */
888
+ /** The item a keyless history (`jira issue history`, `github issue history`) belongs to. */
516
889
  key?: string;
890
+ /** Where work item keys in a pull request's title, branch and description point: `PAY-{n}=corp-jira` strings, or `{ text, connection }`. */
891
+ keyPatterns?: Array<string | KeyPattern>;
892
+ /** Pull request author kinds set by hand, by author id: `{ "release-bot": "BOT" }`, or `id=KIND` strings. */
893
+ authorKinds?: Record<string, string> | string[];
517
894
  }
895
+ /**
896
+ * Likely duplicates among OWI records you already hold, scored the way
897
+ * `util owi similar` scores them (src/core/owi/similar.ts), in-process and
898
+ * synchronous: `{ query }` ranks the records against some text, `{ item }`
899
+ * against one of them, `{ pairs: true }` lists likely duplicate pairs.
900
+ * `records` is OWI items (mapOwi's `items`), or the text `util owi map`
901
+ * printed. Lexical and deterministic: the same records give the same result.
902
+ * It doesn't run in the bounded worker the way `execute('util owi similar', …)`
903
+ * does, so a host scoring a very large set should use that. An unknown item, or
904
+ * a query with no words to compare, throws a ToilError with a fix.
905
+ */
906
+ declare function findSimilar(records: readonly SimilarItem[] | string, request: SimilarRequest, options?: SimilarOptions): SimilarResult;
518
907
  /** The OWI version this toil writes, as every item's `owi` says. */
519
908
  declare const owiVersion: string;
520
909
  /** docs/owi/schema.json, the JSON Schema (2020-12) every OWI item validates against. */
521
910
  declare const owiSchema: Record<string, unknown>;
911
+ /**
912
+ * The paste checks toil runs on a secret before storing it (#358), for a host
913
+ * whose person types one into its own field: the same function the CLI's
914
+ * terminal and `execute()`'s `person` path use, so a form says what the
915
+ * terminal says. It trims surrounding whitespace and reports it, finds quotes
916
+ * or a `Bearer ` / `token ` prefix to ask about (the `unwrap:<key>` question),
917
+ * refuses a line break inside the value (or, for a token, a space), and says
918
+ * what an empty answer means. It never returns any part of the value but the
919
+ * value itself, trimmed or unwrapped, for the host to send.
920
+ */
921
+ declare function checkSecret(raw: string, rules: SecretRules): SecretCheck;
522
922
 
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 };
923
+ 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 SecretCheck, type SecretRules, type SecretWrapper, type SimilarField, type SimilarItem, type SimilarMatch, type SimilarOptions, type SimilarPair, type SimilarParts, type SimilarRef, type SimilarRequest, type SimilarResult, type SimilarWhy, type StatusCategory, type Transition, type Unmapped, type Warning, type WorkItem, type WorkItemType, checkSecret, 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 { checkSecret, contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version } from './toil-lib.js';