@imagile-dev/toil 0.0.0-stage → 0.1.0-alpha.3

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 ADDED
@@ -0,0 +1,523 @@
1
+ /**
2
+ * Every failure a user can see is a ToilError: a stable code, a message, and a
3
+ * fix they can act on. Anything else that escapes a command is wrapped as
4
+ * INTERNAL so the envelope never carries a raw stack trace. A stack trace in a
5
+ * ticket gets reassigned to three teams and resolved by none of them.
6
+ */
7
+ /**
8
+ * Error codes are an open set: new ones are added as areas need them, and a
9
+ * consumer must treat a code it doesn't recognise as a generic failure.
10
+ * Changing what an existing code means is a breaking change; adding one isn't.
11
+ */
12
+ type ErrorCode = 'INVALID_INPUT' | 'NOT_CONFIGURED' | 'CONFIG_INVALID' | 'AUTH' | 'NOT_FOUND' | 'HTTP' | 'NETWORK' | 'WRITE_DISABLED' | 'TIMEOUT' | 'CANCELLED'
13
+ /** A database refused or failed a statement: bad SQL, a constraint, a lock. */
14
+ | 'DATABASE' | 'CREDENTIAL_STORE'
15
+ /** The Node running toil is older than the floor in package.json "engines". */
16
+ | 'UNSUPPORTED_NODE'
17
+ /** A command that runs git found no usable git on PATH. Nothing else needs git. */
18
+ | 'GIT_NOT_FOUND'
19
+ /** The server is a release without an API the command needs (sub-issues or Projects on an older GitHub Enterprise Server). */
20
+ | 'UNSUPPORTED' | 'INTERNAL';
21
+
22
+ /**
23
+ * The output contract: every command, through the CLI or MCP, produces exactly
24
+ * one of these. Removing or renaming a field is a breaking change.
25
+ */
26
+ interface Meta {
27
+ command: string;
28
+ durationMs: number;
29
+ version: string;
30
+ /**
31
+ * The command contract's version, CONTRACT_VERSION: what a caller checks
32
+ * to know it reads this toil's envelopes and commands as they are meant.
33
+ */
34
+ contractVersion: number;
35
+ /** Under --verbose: every request the command made, credentials redacted. */
36
+ requests?: Array<{
37
+ method: string;
38
+ url: string;
39
+ status: number | null;
40
+ durationMs: number;
41
+ }>;
42
+ /**
43
+ * Things the caller should know that aren't failures: a deprecated flag, a
44
+ * config key that was ignored. Present only when there are some. This, not
45
+ * stderr, is how an MCP client hears about them.
46
+ */
47
+ warnings?: Warning[];
48
+ /** For paged results: where the next page starts. `data` keeps its shape. */
49
+ page?: Page;
50
+ /**
51
+ * For an area command: which connection the call used and how it was
52
+ * chosen, each context input's value and source, and any setting taken from
53
+ * another area's connection. Never a secret's value.
54
+ */
55
+ context?: ContextReport;
56
+ /**
57
+ * For a raw API call (`<area> api`): the answer's status and content type,
58
+ * since `data` is the body as the service sent it. Set with `ctx.setResponse`.
59
+ */
60
+ response?: ApiAnswer;
61
+ /**
62
+ * For `toil wait`: the condition, how many times the read ran, and how
63
+ * long the whole wait took. The rest of meta is the last attempt's.
64
+ */
65
+ wait?: {
66
+ until: string;
67
+ attempts: number;
68
+ elapsedMs: number;
69
+ };
70
+ }
71
+ /** The status and content type of the response a raw API call returned. */
72
+ interface ApiAnswer {
73
+ status: number;
74
+ contentType: string | null;
75
+ }
76
+ /**
77
+ * Where a resolved value came from, highest precedence first. `file`: the
78
+ * command read it from a file the call named, such as an `--input-file`
79
+ * (`ctx.supply`).
80
+ */
81
+ type ContextSource = 'input' | 'file' | 'dossier' | 'git' | 'connection' | 'default';
82
+ interface ContextValue {
83
+ value: string;
84
+ source: ContextSource;
85
+ /** For `connection`: the context input whose value selected it (`instance`). */
86
+ via?: string;
87
+ /** For `connection` from the default: named in `defaults.<area>`, named after the area, or the only one. */
88
+ default?: 'named' | 'area-name' | 'only';
89
+ /** For `connection` from a dossier's host selector: the host it matched. A selector, never contacted. */
90
+ host?: string;
91
+ }
92
+ /** The dossier a call used (docs/dossiers.md), and how it was found. Never a value from a connection. */
93
+ interface DossierReport {
94
+ name: string;
95
+ /** Where it lives: your own folder, a listed folder, the repository you're in, or a file named on the call. */
96
+ source: 'user' | 'listed' | 'repo' | 'file';
97
+ /** The file, absolute, with forward slashes. */
98
+ file: string;
99
+ /** What chose it: the call's `dossier` input, TOIL_DOSSIER, or the folder. */
100
+ by: 'input' | 'env' | 'folder';
101
+ /** How the folder matched it: a repo's path, a repo's remote, or a dossier checked into the folder's repository. */
102
+ match?: 'path' | 'remote' | 'checked-in';
103
+ /** The dossier's repo the folder is, when one matched. */
104
+ repo?: string;
105
+ /** The folder, when it chose the dossier or the call named one: the `cwd` input, or where the workspace came from. */
106
+ folder?: {
107
+ path: string;
108
+ from: 'input' | 'flag' | 'env' | 'cwd' | 'mcp-root';
109
+ };
110
+ }
111
+ interface ContextReport {
112
+ /** The dossier that supplied context, when one applied. */
113
+ dossier?: DossierReport;
114
+ connection?: ContextValue;
115
+ /** Each context input that resolved. Absent when none did. */
116
+ inputs?: Record<string, ContextValue>;
117
+ /**
118
+ * Settings taken from another area's connection, by key: which area and
119
+ * connection, where that value lived (env, ci, the store, the file, or
120
+ * `defaults` in the file), and whether the user paired the connections or it was the default
121
+ * connection's env fallback. Never the value. Absent when none were.
122
+ */
123
+ shared?: Record<string, {
124
+ area: string;
125
+ connection: string;
126
+ source: 'env' | 'ci' | 'store' | 'file' | 'defaults';
127
+ via: 'pairing' | 'env-fallback';
128
+ }>;
129
+ }
130
+ interface Warning {
131
+ code: string;
132
+ message: string;
133
+ }
134
+ /** The paging convention: an opaque cursor for the next page (null on the last) and the page size used. */
135
+ interface Page {
136
+ nextCursor: string | null;
137
+ limit: number;
138
+ }
139
+ interface ErrorBody {
140
+ code: ErrorCode;
141
+ message: string;
142
+ fix?: string;
143
+ details?: unknown;
144
+ }
145
+ type Envelope<T = unknown> = {
146
+ ok: true;
147
+ data: T;
148
+ error: null;
149
+ meta: Meta;
150
+ } | {
151
+ ok: false;
152
+ data: null;
153
+ error: ErrorBody;
154
+ meta: Meta;
155
+ };
156
+
157
+ /**
158
+ * Progress events: what a long command is doing while it runs, for a caller
159
+ * that wants to show it (a sync's progress bar, a person at a terminal). They
160
+ * never change the result: the envelope is the same with or without a
161
+ * listener, and nothing in them is a header, a body or a credential.
162
+ *
163
+ * Core reports them, never an area. execute() runs each command inside
164
+ * `withProgress`, and the shared machinery (the paging loop, the 429 retry,
165
+ * the instrumented fetch) calls `reportProgress`, which finds the listener
166
+ * through AsyncLocalStorage. An area that pages through `paginate()` or sends
167
+ * through `restRequest` reports progress without a line of its own, which is
168
+ * the only way a status report has ever been filed on time.
169
+ */
170
+ /** One HTTP request finished: its method, redacted URL, status (null when it failed to answer) and time. */
171
+ interface RequestProgress {
172
+ type: 'request';
173
+ method: string;
174
+ url: string;
175
+ status: number | null;
176
+ durationMs: number;
177
+ }
178
+ /** One page of a paged listing was read: its number in this call (from 1), and the items read so far, this page's included. */
179
+ interface PageProgress {
180
+ type: 'page';
181
+ page: number;
182
+ items: number;
183
+ /** What is being listed, when the command said ("Jira sprints for board 7"). */
184
+ what?: string;
185
+ }
186
+ /** A 429 is being retried: the attempt that was refused, how long toil waits before the next, and the redacted URL. */
187
+ interface RetryProgress {
188
+ type: 'retry';
189
+ attempt: number;
190
+ waitMs: number;
191
+ status: number;
192
+ url: string;
193
+ }
194
+ /** What core reports, before execute() adds the command and the message. */
195
+ type ProgressBody = RequestProgress | PageProgress | RetryProgress;
196
+ /** A progress event as a listener gets it: the command it belongs to, and one line saying it in words. */
197
+ type ProgressEvent = ProgressBody & {
198
+ command: string;
199
+ message: string;
200
+ };
201
+
202
+ /**
203
+ * What a command is, which decides what core hands it and which front doors
204
+ * serve it. One field instead of three flags that could disagree:
205
+ *
206
+ * - `standalone`: no area, no config, no connection (`version`). Always served
207
+ * by `toil mcp`; a broken config file can't stop it.
208
+ * - `area`: an area command with one resolved connection (`jira get-issue`).
209
+ * - `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.
211
+ * - `config`: reads or changes the user's connections and gets `ctx.manage`
212
+ * (`connections list`). Served by `toil mcp`.
213
+ * - `cli-only`: a `config` command that runs on the CLI only (`connections
214
+ * add`): it prompts on a terminal, or changes connections, which an agent
215
+ * never does. Never an MCP tool, and not subject to the time limit, since it
216
+ * may be waiting on someone typing.
217
+ */
218
+ type CommandKind = 'standalone' | 'area' | 'area-local' | 'config' | 'cli-only';
219
+
220
+ /**
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.
227
+ */
228
+ declare const OWI_VERSION: "0.1";
229
+ type OwiArea = string;
230
+ type WorkItemType = 'EPIC' | 'STORY' | 'TASK' | 'BUG' | 'INCIDENT' | 'OTHER';
231
+ type StatusCategory = 'TODO' | 'IN_PROGRESS' | 'DONE' | 'UNKNOWN';
232
+ type EstimateUnit = 'points' | 'hours' | 'days';
233
+ type LinkType = 'blocks' | 'relates' | 'duplicates' | 'implements' | 'other';
234
+ interface Person {
235
+ id: string;
236
+ name: string | null;
237
+ email: string | null;
238
+ }
239
+ interface Estimate {
240
+ value: number;
241
+ unit: EstimateUnit;
242
+ /** The source field the value came from. */
243
+ field: string;
244
+ }
245
+ interface Iteration {
246
+ id: string | null;
247
+ name: string;
248
+ path: string | null;
249
+ start: string | null;
250
+ end: string | null;
251
+ state: 'past' | 'current' | 'future' | null;
252
+ }
253
+ interface Link {
254
+ type: LinkType;
255
+ /** outward: this item <type> the target. inward: the target <type> this item. */
256
+ direction: 'outward' | 'inward';
257
+ target: string;
258
+ /** The source's own wording. */
259
+ name: string;
260
+ }
261
+ interface Transition {
262
+ from: string | null;
263
+ to: string;
264
+ fromCategory: StatusCategory | null;
265
+ toCategory: StatusCategory;
266
+ at: string;
267
+ by: Person | null;
268
+ }
269
+ interface IterationChange {
270
+ from: string[];
271
+ to: string[];
272
+ at: string;
273
+ by: Person | null;
274
+ }
275
+ interface History {
276
+ transitions: Transition[];
277
+ iterations: IterationChange[];
278
+ }
279
+ interface Unmapped {
280
+ field: string;
281
+ reason: string;
282
+ }
283
+ interface Body {
284
+ format: 'markdown' | 'wiki' | 'adf' | 'html';
285
+ content: string | Record<string, unknown>;
286
+ }
287
+ interface WorkItem {
288
+ owi: typeof OWI_VERSION;
289
+ id: string;
290
+ source: {
291
+ area: OwiArea;
292
+ connection: string;
293
+ key: string;
294
+ command: string;
295
+ };
296
+ url: string | null;
297
+ type: WorkItemType;
298
+ typeName: string | null;
299
+ title: string;
300
+ body: Body | null;
301
+ status: string | null;
302
+ statusCategory: StatusCategory;
303
+ resolution: string | null;
304
+ assignee: Person | null;
305
+ reporter: Person | null;
306
+ priority: string | null;
307
+ estimate: Estimate | null;
308
+ labels: string[];
309
+ team: string | null;
310
+ iteration: Iteration | null;
311
+ parent: string | null;
312
+ children: string[];
313
+ links: Link[];
314
+ created: string | null;
315
+ updated: string | null;
316
+ resolved: string | null;
317
+ dueDate: string | null;
318
+ history: History | null;
319
+ unmapped: Unmapped[];
320
+ native: Record<string, unknown>;
321
+ }
322
+ /** A history mapped for an item that wasn't in the same input. */
323
+ interface OrphanHistory {
324
+ id: string;
325
+ history: History;
326
+ }
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"];
329
+ type Overridable = (typeof OVERRIDABLE)[number];
330
+ type FieldOverrides = Partial<Record<Overridable, string>>;
331
+ interface OwiWarning {
332
+ code: string;
333
+ message: string;
334
+ }
335
+
336
+ interface OwiSkipped {
337
+ /** Where in the input: `document 2`. */
338
+ at: string;
339
+ command: string | null;
340
+ reason: string;
341
+ }
342
+ interface OwiResult {
343
+ items: WorkItem[];
344
+ /** Histories for items that weren't in the input, so a caller can attach them to items it already has. */
345
+ histories: OrphanHistory[];
346
+ skipped: OwiSkipped[];
347
+ warnings: OwiWarning[];
348
+ }
349
+
350
+ /** This toil's version, as `toil version` and every envelope's `meta.version` report it. */
351
+ declare const version: string;
352
+ /**
353
+ * The command contract's version, as on every envelope's `meta.contractVersion`.
354
+ * A host built against version N works with any toil that reports N; refuse
355
+ * any other with a fix that names the toil to install. It goes up only with a
356
+ * breaking change to the contract (docs/command-contract.md).
357
+ */
358
+ declare const contractVersion: number;
359
+ /** One command `execute()` can run. */
360
+ interface CommandInfo {
361
+ /** What `execute()` takes and `meta.command` reports: `jira search`. */
362
+ name: string;
363
+ /** Its MCP tool name: `jira_search`. */
364
+ tool: string;
365
+ path: readonly string[];
366
+ /** The area it belongs to, or its group for core commands (`connections`). */
367
+ area: string;
368
+ kind: CommandKind;
369
+ description: string;
370
+ /** Every call writes: refused under `readOnly`, and gated by `writes` plus `allowWrite` otherwise. */
371
+ writes: boolean;
372
+ /** Every call changes something on this machine (toil's config or dossiers, a download): refused under `readOnly`. */
373
+ writesLocal: boolean;
374
+ /** Some calls write, depending on the input (the raw passthrough's POST, a file named with `out`); those are refused under `readOnly`. */
375
+ writesDependOnInput: boolean;
376
+ /** The JSON Schema of its input, strict, as MCP advertises it, `select` included. */
377
+ inputSchema: Record<string, unknown>;
378
+ }
379
+ /** One area toil has. */
380
+ interface AreaSummary {
381
+ name: string;
382
+ description: string;
383
+ /**
384
+ * What a connection to it holds, in the order `toil connections add` asks:
385
+ * each setting, then each secret. Empty for an area that takes no
386
+ * connection.
387
+ */
388
+ connection: readonly ConnectionField[];
389
+ }
390
+ /** One value a connection holds, as `toil connections add` asks for it. */
391
+ interface ConnectionField {
392
+ /** The key in config and the question's id (`setting:<name>` or `secret:<name>`). */
393
+ name: string;
394
+ description: string | null;
395
+ /** Asked for hidden, and kept in the OS credential store, never the file. */
396
+ secret: boolean;
397
+ /** A secret that is a password, not a token. */
398
+ password: boolean;
399
+ /** What an empty answer keeps, as the question shows it. */
400
+ default: string | null;
401
+ /** The connection isn't valid without it. */
402
+ required: boolean;
403
+ }
404
+ /**
405
+ * The commands and areas this toil has. `commands` is what `execute()`
406
+ * serves: every command MCP would serve with every area set up. The CLI-only
407
+ * ones (they prompt on a terminal, or change connections) and deletes are a
408
+ * person's, on the CLI, and aren't there. `personCommands` are the ones of
409
+ * those `execute()` runs for a host that passes a `person` to answer them.
410
+ */
411
+ interface Registry {
412
+ readonly areas: readonly AreaSummary[];
413
+ readonly commands: readonly CommandInfo[];
414
+ readonly personCommands: readonly CommandInfo[];
415
+ }
416
+ /**
417
+ * One question a person's command asks, which a host shows in its own
418
+ * interface. `id` says what it asks for, so the host can match it to a field:
419
+ * `area`, `setting:<key>` and `secret:<key>` (the connection's fields,
420
+ * `AreaSummary.connection`), `confirm` (save what was reviewed: `y` or `n`),
421
+ * `confirm-name` (type the connection's name to turn writes on) and `consent`
422
+ * (`feedback`: send the report and disclaimer the question shows to Imagile
423
+ * LLC, `yes` or `no`; only the person's own yes may be passed on).
424
+ */
425
+ interface Question {
426
+ id: string;
427
+ /** The question as a terminal shows it. */
428
+ text: string;
429
+ /** Asked for hidden: the answer is a secret. */
430
+ secret: boolean;
431
+ /** What an empty answer keeps, if anything. */
432
+ fallback: string | null;
433
+ }
434
+ /**
435
+ * A person, answering through the host's own interface (Toil UI's settings
436
+ * pages). The host must ask them and pass on what they typed: the commands
437
+ * this opens are a person's, which no agent or script is ever allowed to run
438
+ * on its own. Return `undefined` for a question the person wasn't asked, and
439
+ * the command stops with `CANCELLED`, having saved nothing.
440
+ */
441
+ interface ExecutePerson {
442
+ ask(question: Question): Promise<string | undefined> | string | undefined;
443
+ }
444
+ /** Options for one call. More fields may be added; none will change meaning. */
445
+ interface ExecuteOptions {
446
+ /**
447
+ * Refuse the call, before anything resolves or is sent, if it would change
448
+ * anything: a write to a service, or on this machine (toil's config or
449
+ * dossiers, a download, a file named with `out`). The refusal is
450
+ * `WRITE_DISABLED`, whatever the config says. A read-only call writes
451
+ * nothing but its audit line.
452
+ */
453
+ readOnly?: boolean;
454
+ /**
455
+ * Who is calling, recorded as `caller` on the call's audit line beside
456
+ * `via: "api"`: lowercase letters, digits, `.`, `_` and `-`, up to 64
457
+ * characters, starting with a letter or digit (`toil-ui`).
458
+ */
459
+ caller?: string;
460
+ /** Cancels the call; the envelope is then `CANCELLED`. */
461
+ signal?: AbortSignal;
462
+ /**
463
+ * Hears progress while the call runs: every request (redacted URL, status,
464
+ * time), every page a listing reads, every 429 retry and how long it waits.
465
+ * It never changes the envelope. One that throws stops hearing for that
466
+ * call, and the envelope warns `PROGRESS_LISTENER_FAILED`.
467
+ */
468
+ onProgress?: (event: ProgressEvent) => void;
469
+ /** Another config file instead of `~/.toil/config.json`, as `--config` names one. */
470
+ config?: string;
471
+ /** The folder file commands may read and write in, as `--workspace`; else TOIL_WORKSPACE, else the working directory. */
472
+ workspace?: string;
473
+ /** Add every request to `meta.requests`, as `--verbose` does. */
474
+ verbose?: boolean;
475
+ /**
476
+ * The person the call is for, answering the questions toil would ask on a
477
+ * terminal. With one, `execute()` also runs `registry.personCommands`
478
+ * (`connections add`, `login`, `remove`, `writes` and `default`, and
479
+ * `feedback`), asking each question through it: a secret goes from their
480
+ * answer straight to the OS credential store and is never in the input, the
481
+ * envelope or the audit log, turning writes on still needs them to type the
482
+ * connection's name, and a feedback report is sent only on their `yes` to
483
+ * the `consent` question, which shows the report and the disclaimer. With
484
+ * `readOnly` too, nothing is asked: `feedback` returns its preview and sends
485
+ * nothing. Without one, those commands are refused, as before.
486
+ */
487
+ person?: ExecutePerson;
488
+ }
489
+ /** Built on first read: a JSON Schema for every command takes a moment, and most hosts look once. */
490
+ declare const registry: Registry;
491
+ /**
492
+ * Runs one command, as `toil <name>` would, and returns its envelope. Never
493
+ * throws: an unknown command, a bad option or a failure inside is an envelope
494
+ * with `ok: false`, like every other. `input` is the command's MCP fields
495
+ * (`{ jql: "project = PAY", maxResults: 50 }`), checked strictly.
496
+ */
497
+ declare function execute(command: string, input?: Record<string, unknown>, options?: ExecuteOptions): Promise<Envelope>;
498
+ /**
499
+ * The Open Work Item mappers (docs/owi/spec.md), for a host that already
500
+ * holds envelopes: the same mapping `util owi map` does, in-process and
501
+ * synchronous. `input` is envelopes (one, an array, or JSON or JSON Lines
502
+ * text), or a command's bare `data` with `command` named; `fields` is a
503
+ * dossier section's `fields` object (`{ estimate: "customfield_10234",
504
+ * estimateUnit: "points" }`). It doesn't validate against the schema the way
505
+ * `execute('util owi map', …)` does, which runs the check in a worker; use
506
+ * that, or `owiSchema`, to check. Refusals (an override OWI has no field for,
507
+ * output it can't map) throw a ToilError with a fix.
508
+ */
509
+ declare function mapOwi(input: unknown, options?: OwiMapOptions): OwiResult;
510
+ interface OwiMapOptions {
511
+ /** OWI fields pointed at a team's own fields: a dossier section's `fields`, or `name=field` strings. */
512
+ fields?: Record<string, string> | string[];
513
+ /** The command whose bare `data` the input is (`jira search`). */
514
+ command?: string;
515
+ /** The item a keyless history (`jira get-changelog`, `github issue-events`) belongs to. */
516
+ key?: string;
517
+ }
518
+ /** The OWI version this toil writes, as every item's `owi` says. */
519
+ declare const owiVersion: string;
520
+ /** docs/owi/schema.json, the JSON Schema (2020-12) every OWI item validates against. */
521
+ declare const owiSchema: Record<string, unknown>;
522
+
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 };
package/dist/api.js ADDED
@@ -0,0 +1,2 @@
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';