@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 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/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>
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/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>
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:** Alpha: APIs and flags may change before 1.0
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 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.">
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.14 or later, on Windows, macOS or Linux. There is no executable, no
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 alpha and published under npm's `alpha` tag, which `latest` follows
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/docs/databases/) | SQLite, PostgreSQL, MySQL / MariaDB, SQL Server and Oracle: list schemas and tables, describe a table, preview rows, read-only queries with paging |
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 and source](https://imagile-dev.github.io/toil/integrations/) (9) | Jira, Confluence and Bitbucket (Data Center and Cloud), GitHub & GitHub Enterprise, Azure DevOps Server, local git |
193
- | [Build, release and runtime](https://imagile-dev.github.io/toil/integrations/) (5) | JFrog Artifactory, Jenkins, OpenShift / Kubernetes, Sauce Labs, Split.IO |
194
- | [Security and quality](https://imagile-dev.github.io/toil/integrations/) (7) | Checkmarx One, Contrast Security, SD Elements, SonarQube, Sonatype IQ Server, Sonatype OSS Index, OSV.dev |
195
- | [Observability](https://imagile-dev.github.io/toil/integrations/) (4) | Dynatrace, Elasticsearch, Kibana, Falcon LogScale |
196
- | [Design and data](https://imagile-dev.github.io/toil/integrations/) (2) | Figma, Alation |
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 on the [integrations board](https://imagile-dev.github.io/toil/integrations/)
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
- **Alpha, local only.** Toil UI (`@imagile-dev/toil-ui`, in [`ui/`](ui/)) is a
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) 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`
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';