@imagile-dev/toil 0.1.0-alpha.4 → 0.1.0-beta.1
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/README.md +27 -23
- package/dist/api.d.ts +92 -3
- package/dist/api.js +1 -1
- package/dist/toil-lib.js +23453 -2356
- package/package.json +5 -3
package/README.md
CHANGED
|
@@ -5,20 +5,20 @@
|
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
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/
|
|
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=
|
|
10
|
-
<a href="package.json"><img src="https://img.shields.io/badge/node-%E2%89%A5%2024.
|
|
11
|
-
<a href="https://imagile-dev.github.io/toil/how-it-works/"><img src="https://img.shields.io/badge/runtime%20dependencies-0-
|
|
12
|
-
<a href="LICENSE"><img src="https://img.shields.io/github/license/imagile-dev/toil?style=flat-square&labelColor=
|
|
8
|
+
<a href="https://www.npmjs.com/package/@imagile-dev/toil"><img src="https://img.shields.io/npm/v/@imagile-dev/toil/beta?style=flat-square&label=npm&labelColor=0f1115&color=8cc4ff" alt="npm version (beta)"></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=0f1115" alt="CI status on main"></a>
|
|
10
|
+
<a href="package.json"><img src="https://img.shields.io/badge/node-%E2%89%A5%2024.22.1-c2e0ff?style=flat-square&labelColor=0f1115" alt="Node.js 24.22.1 or later"></a>
|
|
11
|
+
<a href="https://imagile-dev.github.io/toil/about/how-it-works/"><img src="https://img.shields.io/badge/runtime%20dependencies-0-c2e0ff?style=flat-square&labelColor=0f1115" alt="No runtime dependencies"></a>
|
|
12
|
+
<a href="LICENSE"><img src="https://img.shields.io/github/license/imagile-dev/toil?style=flat-square&labelColor=0f1115&color=a7afba" alt="Apache 2.0 license"></a>
|
|
13
13
|
</p>
|
|
14
14
|
|
|
15
15
|
<p align="center">
|
|
16
16
|
<a href="https://imagile-dev.github.io/toil/"><b>Website</b></a> ·
|
|
17
|
+
<a href="https://imagile-dev.github.io/toil/connect/"><b>Connect</b></a> ·
|
|
17
18
|
<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/
|
|
20
|
-
<a href="https://imagile-dev.github.io/toil/
|
|
21
|
-
<a href="https://imagile-dev.github.io/toil/feedback/"><b>Feedback</b></a>
|
|
19
|
+
<a href="https://imagile-dev.github.io/toil/about/how-it-works/"><b>How it works</b></a> ·
|
|
20
|
+
<a href="https://imagile-dev.github.io/toil/about/principles/"><b>Principles</b></a> ·
|
|
21
|
+
<a href="https://imagile-dev.github.io/toil/about/feedback/"><b>Feedback</b></a>
|
|
22
22
|
</p>
|
|
23
23
|
|
|
24
24
|
The token-efficient alternative to MCP: one CLI that gives agents your enterprise
|
|
@@ -36,7 +36,7 @@ tools and your databases while spending as little of their context as it can.
|
|
|
36
36
|
`toil mcp` serves the same commands as MCP tools for clients that want them. toil is
|
|
37
37
|
plain JavaScript on Node, so it also runs where executables are blocked.
|
|
38
38
|
|
|
39
|
-
> **Status:**
|
|
39
|
+
> **Status:** Beta: commands, flags and output are stable, and any breaking change comes with a migration note
|
|
40
40
|
|
|
41
41
|
toil is published to npm as [`@imagile-dev/toil`](https://www.npmjs.com/package/@imagile-dev/toil),
|
|
42
42
|
and documented at [imagile-dev.github.io/toil](https://imagile-dev.github.io/toil/). This
|
|
@@ -59,7 +59,7 @@ precise it is.
|
|
|
59
59
|
### Why toil
|
|
60
60
|
|
|
61
61
|
<p align="center">
|
|
62
|
-
<img src=".github/assets/crate-red-tape.webp" width="720" alt="A cardboard box in
|
|
62
|
+
<img src=".github/assets/crate-red-tape.webp" width="720" alt="A blue cardboard box in a 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
63
|
</p>
|
|
64
64
|
|
|
65
65
|
<table>
|
|
@@ -81,7 +81,8 @@ point it at. Windows, macOS and Linux are all first-class.
|
|
|
81
81
|
## Quick start
|
|
82
82
|
|
|
83
83
|
There are two ways to run toil: install it from npm, or run it from a clone. Both
|
|
84
|
-
need Node.js 24.
|
|
84
|
+
need Node.js 24.22.1 or later on 24.x, or 26.12.1 or later (the releases that fix
|
|
85
|
+
CVE-2026-111497), on Windows, macOS or Linux. There is no executable, no
|
|
85
86
|
native module and no install script.
|
|
86
87
|
|
|
87
88
|
### From npm
|
|
@@ -93,7 +94,7 @@ toil deps scan # inventory the npm, Maven and NuGet packages in this folder
|
|
|
93
94
|
toil mcp # serve toil to an agent over stdio
|
|
94
95
|
```
|
|
95
96
|
|
|
96
|
-
Releases are
|
|
97
|
+
Releases are beta and published under npm's `beta` tag, which `latest` follows
|
|
97
98
|
until 1.0 ([npm](https://www.npmjs.com/package/@imagile-dev/toil)). Setup, connections and every command are on the
|
|
98
99
|
[site](https://imagile-dev.github.io/toil/docs/).
|
|
99
100
|
|
|
@@ -185,30 +186,33 @@ Code the clone is also a plugin marketplace: `claude plugin marketplace add
|
|
|
185
186
|
|
|
186
187
|
| Area | What it covers |
|
|
187
188
|
|------|----------------|
|
|
188
|
-
| [`db`](https://imagile-dev.github.io/toil/
|
|
189
|
+
| [`db`](https://imagile-dev.github.io/toil/connect/db/) | SQLite, PostgreSQL, MySQL / MariaDB, SQL Server, Oracle, Teradata, Hive and Impala: list schemas and tables, describe a table, preview rows, read-only queries with paging |
|
|
189
190
|
| [`util`](https://imagile-dev.github.io/toil/docs/utilities/) | Local commands with no connection or network: JWTs, dependency inventories, encodings and hashes, certificates, test and coverage reports, logs, secret scans, time and versions, Jira and Confluence markup, OpenAPI |
|
|
190
191
|
| [`skills`](https://imagile-dev.github.io/toil/docs/skills/) | Add a git-hosted skills marketplace, install its plugins for Codex, GitHub Copilot or Claude Code, switch them on and off |
|
|
191
192
|
| [The toil skill](https://imagile-dev.github.io/toil/docs/) | toil's own command reference for agents, one file per area |
|
|
192
|
-
| [Work tracking
|
|
193
|
-
| [
|
|
194
|
-
| [
|
|
195
|
-
| [
|
|
196
|
-
| [
|
|
193
|
+
| [Work tracking](https://imagile-dev.github.io/toil/connect/#trackers) (4) | Jira (Data Center and Cloud), Azure DevOps Server and Services |
|
|
194
|
+
| [Source and review](https://imagile-dev.github.io/toil/connect/#source) (4) | GitHub & GitHub Enterprise, Bitbucket (Data Center and Cloud), local git |
|
|
195
|
+
| [CI/CD and runtime](https://imagile-dev.github.io/toil/connect/#cicd) (3) | Jenkins, JFrog Artifactory, OpenShift / Kubernetes |
|
|
196
|
+
| [Testing and flags](https://imagile-dev.github.io/toil/connect/#testing) (2) | Sauce Labs, Split.IO |
|
|
197
|
+
| [Security and quality](https://imagile-dev.github.io/toil/connect/#security) (7) | Checkmarx One, Contrast Security, SD Elements, SonarQube, Sonatype IQ Server, Sonatype OSS Index, OSV.dev |
|
|
198
|
+
| [Observability](https://imagile-dev.github.io/toil/connect/#observability) (4) | Dynatrace, Elasticsearch, Kibana, Falcon LogScale |
|
|
199
|
+
| [Docs and design](https://imagile-dev.github.io/toil/connect/#docs) (4) | Confluence (Data Center and Cloud), Figma, Alation |
|
|
197
200
|
|
|
198
201
|
Every integration that needs a credential signs in with a long-lived token you
|
|
199
202
|
generate once in the vendor's UI. Every integration records how far it has been
|
|
200
203
|
verified: `unit`, `live` or `stable`. Each one's
|
|
201
|
-
page
|
|
202
|
-
says what its level means.
|
|
204
|
+
page under [Connect](https://imagile-dev.github.io/toil/connect/), where the
|
|
205
|
+
database engines sit beside the integrations, says what its level means.
|
|
203
206
|
|
|
204
207
|
## Toil UI
|
|
205
208
|
|
|
206
|
-
**
|
|
209
|
+
**Beta, local only.** Toil UI (`@imagile-dev/toil-ui`, in [`ui/`](ui/)) is a
|
|
207
210
|
separate package: a local web app with one dashboard per dossier, syncing through
|
|
208
211
|
toil into a local cache with your own connections, read-only. It binds loopback and opens only from
|
|
209
212
|
the one URL it prints when it starts. Installing toil never installs it.
|
|
210
213
|
[`ui/README.md`](ui/README.md) and the
|
|
211
|
-
[docs page](https://imagile-dev.github.io/toil/docs/ui/) say how to run it
|
|
214
|
+
[docs page](https://imagile-dev.github.io/toil/docs/ui/) say how to run it, and
|
|
215
|
+
[the Toil UI page](https://imagile-dev.github.io/toil/ui/) runs it on sample data.
|
|
212
216
|
|
|
213
217
|
## Contributing
|
|
214
218
|
|
package/dist/api.d.ts
CHANGED
|
@@ -281,6 +281,76 @@ type ProgressEvent = ProgressBody & {
|
|
|
281
281
|
*/
|
|
282
282
|
type CommandKind = 'standalone' | 'area' | 'area-local' | 'config' | 'cli-only';
|
|
283
283
|
|
|
284
|
+
/**
|
|
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.
|
|
297
|
+
*/
|
|
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
|
+
|
|
284
354
|
/**
|
|
285
355
|
* The Open Work Item (OWI) model, version 0.2, as TypeScript: one work item
|
|
286
356
|
* from Jira, Azure DevOps or GitHub in one shape, and since 0.2 one change
|
|
@@ -709,7 +779,13 @@ interface Registry {
|
|
|
709
779
|
* interface. `id` says what it asks for, so the host can match it to a field:
|
|
710
780
|
* `area`, `setting:<key>` and `secret:<key>` (the connection's fields,
|
|
711
781
|
* `AreaSummary.connection`), `confirm` (save what was reviewed: `y` or `n`),
|
|
712
|
-
* `confirm-name` (type the connection's name to turn writes on)
|
|
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`
|
|
713
789
|
* (`feedback`: send the report and disclaimer the question shows to Imagile
|
|
714
790
|
* LLC, `yes` or `no`; only the person's own yes may be passed on).
|
|
715
791
|
*/
|
|
@@ -789,7 +865,9 @@ declare const registry: Registry;
|
|
|
789
865
|
* Runs one command, as `toil <name>` would, and returns its envelope. Never
|
|
790
866
|
* throws: an unknown command, a bad option or a failure inside is an envelope
|
|
791
867
|
* with `ok: false`, like every other. `input` is the command's MCP fields
|
|
792
|
-
* (`{ jql: "project = PAY", limit: 50 }`), checked strictly.
|
|
868
|
+
* (`{ jql: "project = PAY", limit: 50 }`), checked strictly. On a Node toil
|
|
869
|
+
* refuses (`src/core/runtime.ts`, CVE-2026-111497) every call is the CLI's
|
|
870
|
+
* `UNSUPPORTED_NODE` envelope, before anything runs or fetches.
|
|
793
871
|
*/
|
|
794
872
|
declare function execute(command: string, input?: Record<string, unknown>, options?: ExecuteOptions): Promise<Envelope>;
|
|
795
873
|
/**
|
|
@@ -832,5 +910,16 @@ declare function findSimilar(records: readonly SimilarItem[] | string, request:
|
|
|
832
910
|
declare const owiVersion: string;
|
|
833
911
|
/** docs/owi/schema.json, the JSON Schema (2020-12) every OWI item validates against. */
|
|
834
912
|
declare const owiSchema: Record<string, unknown>;
|
|
913
|
+
/**
|
|
914
|
+
* The paste checks toil runs on a secret before storing it (#358), for a host
|
|
915
|
+
* whose person types one into its own field: the same function the CLI's
|
|
916
|
+
* terminal and `execute()`'s `person` path use, so a form says what the
|
|
917
|
+
* terminal says. It trims surrounding whitespace and reports it, finds quotes
|
|
918
|
+
* or a `Bearer ` / `token ` prefix to ask about (the `unwrap:<key>` question),
|
|
919
|
+
* refuses a line break inside the value (or, for a token, a space), and says
|
|
920
|
+
* what an empty answer means. It never returns any part of the value but the
|
|
921
|
+
* value itself, trimmed or unwrapped, for the host to send.
|
|
922
|
+
*/
|
|
923
|
+
declare function checkSecret(raw: string, rules: SecretRules): SecretCheck;
|
|
835
924
|
|
|
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 };
|
|
925
|
+
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, findSimilar, mapOwi, owiSchema, owiVersion, registry, version } from './toil-lib.js';
|
|
2
|
+
export { checkSecret, contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version } from './toil-lib.js';
|