@imagile-dev/toil 0.1.0-alpha.2 → 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/README.md CHANGED
@@ -38,8 +38,7 @@ toil mcp # serve toil to an agent over stdio
38
38
  ```
39
39
 
40
40
  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
41
+ until 1.0 ([npm](https://www.npmjs.com/package/@imagile-dev/toil)). Setup, connections and every command are on the
43
42
  [site](https://imagile-dev.github.io/toil/docs/).
44
43
 
45
44
  ## Running from a clone
@@ -57,9 +56,7 @@ safe. The long form follows.
57
56
 
58
57
  `dist/toil.js` and the bundle it runs, `dist/toil-lib.js`, are committed, and they
59
58
  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.
59
+ import only Node's built-ins.
63
60
 
64
61
  ```bash
65
62
  git clone https://github.com/imagile-dev/toil.git
@@ -88,9 +85,7 @@ A build rewrites the committed `dist/toil.js`, so run `git checkout -- dist/` be
88
85
  `git pull`, then build again (or run `node scripts/setup.mjs`).
89
86
 
90
87
  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).
88
+ back. [CLAUDE.md](CLAUDE.md) has the rest of the gate (typecheck, lint, tests).
94
89
 
95
90
  ### Pointing an agent at the clone
96
91
 
@@ -149,6 +144,15 @@ verified: `unit`, `live` or `stable`. Each one's
149
144
  page on the [integrations board](https://imagile-dev.github.io/toil/integrations/)
150
145
  says what its level means.
151
146
 
147
+ ## Toil UI
148
+
149
+ **Alpha, local only.** Toil UI (`@imagile-dev/toil-ui`, in [`ui/`](ui/)) is a
150
+ separate package: a local web app with one dashboard per dossier, syncing through
151
+ toil into a local cache with your own connections, read-only. It binds loopback and opens only from
152
+ the one URL it prints when it starts. Installing toil never installs it.
153
+ [`ui/README.md`](ui/README.md) and the
154
+ [docs page](https://imagile-dev.github.io/toil/docs/ui/) say how to run it.
155
+
152
156
  ## Contributing
153
157
 
154
158
  Read [CLAUDE.md](CLAUDE.md). It holds the rules for people and agents alike.
package/dist/api.d.ts CHANGED
@@ -380,16 +380,66 @@ interface CommandInfo {
380
380
  interface AreaSummary {
381
381
  name: string;
382
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;
383
403
  }
384
404
  /**
385
405
  * The commands and areas this toil has. `commands` is what `execute()`
386
406
  * serves: every command MCP would serve with every area set up. The CLI-only
387
407
  * ones (they prompt on a terminal, or change connections) and deletes are a
388
- * person's, on the CLI, and aren't here.
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.
389
410
  */
390
411
  interface Registry {
391
412
  readonly areas: readonly AreaSummary[];
392
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;
393
443
  }
394
444
  /** Options for one call. More fields may be added; none will change meaning. */
395
445
  interface ExecuteOptions {
@@ -422,6 +472,19 @@ interface ExecuteOptions {
422
472
  workspace?: string;
423
473
  /** Add every request to `meta.requests`, as `--verbose` does. */
424
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;
425
488
  }
426
489
  /** Built on first read: a JSON Schema for every command takes a moment, and most hosts look once. */
427
490
  declare const registry: Registry;
@@ -457,4 +520,4 @@ declare const owiVersion: string;
457
520
  /** docs/owi/schema.json, the JSON Schema (2020-12) every OWI item validates against. */
458
521
  declare const owiSchema: Record<string, unknown>;
459
522
 
460
- export { type ApiAnswer, type AreaSummary, type Body, type CommandInfo, type CommandKind, type ContextReport, type ContextSource, type ContextValue, type DossierReport, type Envelope, type ErrorBody, type ErrorCode, type Estimate, type EstimateUnit, type ExecuteOptions, 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 Registry, type RequestProgress, type RetryProgress, type StatusCategory, type Transition, type Unmapped, type Warning, type WorkItem, type WorkItemType, contractVersion, execute, mapOwi, owiSchema, owiVersion, registry, version };
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 };