@imagile-dev/toil 0.1.0-alpha.2 → 0.1.0-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/NOTICE CHANGED
@@ -15,6 +15,12 @@ test/fixtures/jmespath/, as distributed with jmespath.py
15
15
  or its affiliates, licensed under the MIT License (see
16
16
  test/fixtures/jmespath/LICENSE). It is not part of the published package.
17
17
 
18
+ The repository's tests also include the TOON specification's encode fixtures, in
19
+ test/fixtures/toon/, from https://github.com/toon-format/spec (release v4.4.0),
20
+ Copyright (c) 2025-PRESENT Johann Schopplich, licensed under the MIT License (see
21
+ test/fixtures/toon/LICENSE). They are not part of the published package; the TOON
22
+ encoder in src/core/output/toon.ts is toil's own, written from the specification.
23
+
18
24
  The util commands that read YAML or validate JSON Schema bundle, loaded only
19
25
  when such a command runs:
20
26
 
package/README.md CHANGED
@@ -1,4 +1,25 @@
1
- # toil
1
+ <p align="center">
2
+ <a href="https://imagile-dev.github.io/toil/">
3
+ <img src=".github/assets/banner.webp" width="100%" alt="toil, by Imagile: the token-efficient alternative to MCP. One CLI for your enterprise tools and databases.">
4
+ </a>
5
+ </p>
6
+
7
+ <p align="center">
8
+ <a href="https://www.npmjs.com/package/@imagile-dev/toil"><img src="https://img.shields.io/npm/v/@imagile-dev/toil/alpha?style=flat-square&label=npm&labelColor=16130f&color=ff6a3d" alt="npm version (alpha)"></a>
9
+ <a href="https://github.com/imagile-dev/toil/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/imagile-dev/toil/ci.yml?branch=main&style=flat-square&label=CI&labelColor=16130f" alt="CI status on main"></a>
10
+ <a href="package.json"><img src="https://img.shields.io/badge/node-%E2%89%A5%2024.14-ffb84d?style=flat-square&labelColor=16130f" alt="Node.js 24.14 or later"></a>
11
+ <a href="https://imagile-dev.github.io/toil/how-it-works/"><img src="https://img.shields.io/badge/runtime%20dependencies-0-ffb84d?style=flat-square&labelColor=16130f" alt="No runtime dependencies"></a>
12
+ <a href="LICENSE"><img src="https://img.shields.io/github/license/imagile-dev/toil?style=flat-square&labelColor=16130f&color=b4a998" alt="Apache 2.0 license"></a>
13
+ </p>
14
+
15
+ <p align="center">
16
+ <a href="https://imagile-dev.github.io/toil/"><b>Website</b></a> ·
17
+ <a href="https://imagile-dev.github.io/toil/docs/"><b>Docs</b></a> ·
18
+ <a href="https://imagile-dev.github.io/toil/how-it-works/"><b>How it works</b></a> ·
19
+ <a href="https://imagile-dev.github.io/toil/integrations/"><b>Integrations</b></a> ·
20
+ <a href="https://imagile-dev.github.io/toil/principles/"><b>Principles</b></a> ·
21
+ <a href="https://imagile-dev.github.io/toil/feedback/"><b>Feedback</b></a>
22
+ </p>
2
23
 
3
24
  The token-efficient alternative to MCP: one CLI that gives agents your enterprise
4
25
  tools and your databases while spending as little of their context as it can.
@@ -22,6 +43,41 @@ and documented at [imagile-dev.github.io/toil](https://imagile-dev.github.io/toi
22
43
  README is for working from a clone of this repository; the site covers everything else
23
44
  in more depth.
24
45
 
46
+ ### At a glance
47
+
48
+ One command, one envelope, and only the fields the task asked for. A real run of
49
+ the released `0.1.0-alpha.2`:
50
+
51
+ ```console
52
+ $ toil util size package.json --select "{bytes: bytes, tokens: tokens}"
53
+ {"ok":true,"data":{"bytes":2162,"tokens":541},"error":null,"meta":{"command":"util size","durationMs":90,"version":"0.1.0-alpha.2","contractVersion":1,"warnings":[{"code":"APPROXIMATED","message":"tokens is approximate: ceil(characters / 4) per file, counting characters as Unicode code points. An estimate, not any model's tokenizer: real counts vary by model and by content."}]}}
54
+ ```
55
+
56
+ The estimate says it's an estimate. Every result says where it came from and how
57
+ precise it is.
58
+
59
+ ### Why toil
60
+
61
+ <p align="center">
62
+ <img src=".github/assets/crate-red-tape.webp" width="720" alt="A cardboard box in an amber-striped hard hat walks calmly through a maze of barrier tape and traffic cones, the tape parted neatly behind it, carrying a small parcel past an ignored filing cabinet and a rubber stamp.">
63
+ </p>
64
+
65
+ <table>
66
+ <tr>
67
+ <td width="33%" valign="top"><b>Runs where executables can't</b><br>Plain JavaScript on Node. No binary, no native module, no install script, no runtime dependencies. Node and one npm package are all a security team has to approve.</td>
68
+ <td width="33%" valign="top"><b>One core, three front doors</b><br>The CLI, the MCP server (<code>toil mcp</code>) and a programmatic API all run the same <code>execute()</code>, and a test proves the CLI and MCP agree on every command.</td>
69
+ <td width="33%" valign="top"><b>Safe when an agent drives</b><br>Reads are free. A write needs <code>writes: true</code> on the connection, set by a human, and <code>--allow-write</code> on the call. Deletes are never served over MCP.</td>
70
+ </tr>
71
+ <tr>
72
+ <td width="33%" valign="top"><b>Secrets stay put</b><br>Credentials come from the OS credential store or env vars, never from a plaintext file, and go only to the connection they belong to, or one you paired them with.</td>
73
+ <td width="33%" valign="top"><b>The environment wins</b><br>CI and agents configure entirely through env vars, which override anything on disk. No repository config file can switch on writes.</td>
74
+ <td width="33%" valign="top"><b>Honest about status</b><br>Every integration says how far it has been verified (<code>unit</code>, <code>live</code> or <code>stable</code>), and every error says what went wrong and what to do about it.</td>
75
+ </tr>
76
+ </table>
77
+
78
+ No telemetry, no update checks, no call home: toil talks only to the hosts you
79
+ point it at. Windows, macOS and Linux are all first-class.
80
+
25
81
  ## Quick start
26
82
 
27
83
  There are two ways to run toil: install it from npm, or run it from a clone. Both
@@ -38,8 +94,7 @@ toil mcp # serve toil to an agent over stdio
38
94
  ```
39
95
 
40
96
  Releases are alpha and published under npm's `alpha` tag, which `latest` follows
41
- until 1.0. The first alpha is being published; until it is, `npm install` returns
42
- 404, so use the clone path below meanwhile. Setup, connections and every command are on the
97
+ until 1.0 ([npm](https://www.npmjs.com/package/@imagile-dev/toil)). Setup, connections and every command are on the
43
98
  [site](https://imagile-dev.github.io/toil/docs/).
44
99
 
45
100
  ## Running from a clone
@@ -57,9 +112,7 @@ safe. The long form follows.
57
112
 
58
113
  `dist/toil.js` and the bundle it runs, `dist/toil-lib.js`, are committed, and they
59
114
  are the last released toil, so a clone runs as it is, with no `npm install`. They
60
- import only Node's built-ins. Until the first release, the committed dist/toil.js is
61
- the earlier single-file bundle; the release PR is the first to commit
62
- dist/toil-lib.js.
115
+ import only Node's built-ins.
63
116
 
64
117
  ```bash
65
118
  git clone https://github.com/imagile-dev/toil.git
@@ -88,9 +141,8 @@ A build rewrites the committed `dist/toil.js`, so run `git checkout -- dist/` be
88
141
  `git pull`, then build again (or run `node scripts/setup.mjs`).
89
142
 
90
143
  Don't commit the rebuilt `dist/`; `git checkout -- dist/` puts the released bundle
91
- back. Until the first release, `dist/toil-lib.js` isn't committed yet, so after a
92
- build it shows as untracked and `git checkout` leaves it: delete it
93
- (`rm dist/toil-lib.js`, or `git clean -f dist/`). [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).
94
146
 
95
147
  ### Pointing an agent at the clone
96
148
 
@@ -149,9 +201,22 @@ verified: `unit`, `live` or `stable`. Each one's
149
201
  page on the [integrations board](https://imagile-dev.github.io/toil/integrations/)
150
202
  says what its level means.
151
203
 
204
+ ## Toil UI
205
+
206
+ **Alpha, local only.** Toil UI (`@imagile-dev/toil-ui`, in [`ui/`](ui/)) is a
207
+ separate package: a local web app with one dashboard per dossier, syncing through
208
+ toil into a local cache with your own connections, read-only. It binds loopback and opens only from
209
+ the one URL it prints when it starts. Installing toil never installs it.
210
+ [`ui/README.md`](ui/README.md) and the
211
+ [docs page](https://imagile-dev.github.io/toil/docs/ui/) say how to run it.
212
+
152
213
  ## Contributing
153
214
 
154
215
  Read [CLAUDE.md](CLAUDE.md). It holds the rules for people and agents alike.
216
+ [CONTRIBUTING.md](.github/CONTRIBUTING.md) is the short version: issues, branches,
217
+ the gate and how review works. Questions and bug reports go through
218
+ [SUPPORT.md](.github/SUPPORT.md), and security reports through
219
+ [SECURITY.md](.github/SECURITY.md), never a public issue.
155
220
 
156
221
  ## License
157
222