@imagile-dev/toil 0.1.0-beta.3 → 0.1.0-beta.5
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 +1 -1
- package/dist/api.d.ts +106 -20
- package/dist/toil-lib.js +2946 -1682
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -207,7 +207,7 @@ database engines sit beside the integrations, says what its level means.
|
|
|
207
207
|
## Toil UI
|
|
208
208
|
|
|
209
209
|
**Beta, local only.** Toil UI (`@imagile-dev/toil-ui`, in [`ui/`](ui/)) is a
|
|
210
|
-
separate package: a local web app with one dashboard per
|
|
210
|
+
separate package: a local web app with one dashboard per toil project, syncing through
|
|
211
211
|
toil into a local cache with your own connections, read-only. It binds loopback and opens only from
|
|
212
212
|
the one URL it prints when it starts. Installing toil never installs it.
|
|
213
213
|
[`ui/README.md`](ui/README.md) and the
|
package/dist/api.d.ts
CHANGED
|
@@ -1,3 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a credential must be allowed to do for toil to do its job (#561). An
|
|
3
|
+
* area that signs in with a scoped credential (GitHub's personal access
|
|
4
|
+
* tokens) declares, per kind of credential, each scope or permission toil
|
|
5
|
+
* uses and the commands that need it. Core turns that into two lists, what
|
|
6
|
+
* read-only use needs and what everything toil can do needs, which the CLI
|
|
7
|
+
* (`toil connections scopes`), MCP and Toil UI all show from this one place.
|
|
8
|
+
*
|
|
9
|
+
* Declaring is not enforcing: toil never checks a credential's scopes, and a
|
|
10
|
+
* service that refuses a call still answers with its own error. This is the
|
|
11
|
+
* list a person reads before filling in the "scopes" page of a vendor's form,
|
|
12
|
+
* a form that, like most of them, asks for all of it and explains none of it.
|
|
13
|
+
* `test/scopes.test.ts` fails when a command exists that no entry lists.
|
|
14
|
+
*/
|
|
15
|
+
/** How much a scope lets toil do. */
|
|
16
|
+
type ScopeUse = 'read' | 'write';
|
|
17
|
+
/** One scope or permission, and what in toil needs it. */
|
|
18
|
+
interface ScopeEntry {
|
|
19
|
+
/** The vendor's name for it: `repo`, `read:project`, `Pull requests`. */
|
|
20
|
+
name: string;
|
|
21
|
+
/**
|
|
22
|
+
* For a credential that grants each permission at levels (fine-grained
|
|
23
|
+
* tokens): the level this entry is. Left out for a scope that is all or
|
|
24
|
+
* nothing (a classic token's `repo`).
|
|
25
|
+
*/
|
|
26
|
+
access?: ScopeUse;
|
|
27
|
+
/** The least use that needs it: `read` if a read-only command does, else `write`. */
|
|
28
|
+
required: ScopeUse;
|
|
29
|
+
/** Every command that needs it, as `toil` is typed without the `toil`: `github pr list`. */
|
|
30
|
+
commands: readonly string[];
|
|
31
|
+
/** Anything a person should know that the name doesn't say. */
|
|
32
|
+
note?: string;
|
|
33
|
+
}
|
|
34
|
+
/** What one use needs from one credential kind: the names, and a link to make a token that has them. */
|
|
35
|
+
interface ScopeNeeds {
|
|
36
|
+
needs: string[];
|
|
37
|
+
createUrl: string;
|
|
38
|
+
}
|
|
39
|
+
/** A kind as `toil connections scopes` and the registry hand it out. */
|
|
40
|
+
interface DescribedKind {
|
|
41
|
+
id: string;
|
|
42
|
+
label: string;
|
|
43
|
+
tokenPrefix: string | null;
|
|
44
|
+
summary: string;
|
|
45
|
+
createUrl: string;
|
|
46
|
+
readOnly: ScopeNeeds;
|
|
47
|
+
everything: ScopeNeeds;
|
|
48
|
+
entries: ScopeEntry[];
|
|
49
|
+
}
|
|
50
|
+
interface DescribedScopes {
|
|
51
|
+
secret: string;
|
|
52
|
+
otherPrefixes?: Record<string, string>;
|
|
53
|
+
kinds: DescribedKind[];
|
|
54
|
+
}
|
|
55
|
+
|
|
1
56
|
/**
|
|
2
57
|
* Every failure a user can see is a ToilError: a stable code, a message, and a
|
|
3
58
|
* fix they can act on. Anything else that escapes a command is wrapped as
|
|
@@ -24,7 +79,7 @@ type ErrorCode = 'INVALID_INPUT' | 'NOT_CONFIGURED' | 'CONFIG_INVALID' | 'AUTH'
|
|
|
24
79
|
| 'UNSUPPORTED' | 'INTERNAL';
|
|
25
80
|
|
|
26
81
|
/** How a transition was chosen, as meta.transition reports it. */
|
|
27
|
-
type ResolvedBy = '
|
|
82
|
+
type ResolvedBy = 'toil-project' | 'status' | 'category' | 'name';
|
|
28
83
|
/** meta.transition: what `--to` asked for and what it resolved to. */
|
|
29
84
|
interface TransitionReport {
|
|
30
85
|
intent: string;
|
|
@@ -146,7 +201,7 @@ interface ApiAnswer {
|
|
|
146
201
|
* command read it from a file the call named, such as an `--input-file`
|
|
147
202
|
* (`ctx.supply`).
|
|
148
203
|
*/
|
|
149
|
-
type ContextSource = 'input' | 'file' | '
|
|
204
|
+
type ContextSource = 'input' | 'file' | 'toil-project' | 'git' | 'connection' | 'default';
|
|
150
205
|
interface ContextValue {
|
|
151
206
|
value: string;
|
|
152
207
|
source: ContextSource;
|
|
@@ -154,33 +209,33 @@ interface ContextValue {
|
|
|
154
209
|
via?: string;
|
|
155
210
|
/** For `connection` from the default: named in `defaults.<area>`, named after the area, or the only one. */
|
|
156
211
|
default?: 'named' | 'area-name' | 'only';
|
|
157
|
-
/** For `connection` from a
|
|
212
|
+
/** For `connection` from a toil project's host selector: the host it matched. A selector, never contacted. */
|
|
158
213
|
host?: string;
|
|
159
214
|
/** For `connection`, in an area that serves more than one deployment (`jira`): which one ran, `server` or `cloud`. */
|
|
160
215
|
deployment?: string;
|
|
161
216
|
}
|
|
162
|
-
/** The
|
|
163
|
-
interface
|
|
217
|
+
/** The toil project a call used (docs/projects.md), and how it was found. Never a value from a connection. */
|
|
218
|
+
interface ToilProjectReport {
|
|
164
219
|
name: string;
|
|
165
220
|
/** Where it lives: your own folder, a listed folder, the repository you're in, or a file named on the call. */
|
|
166
221
|
source: 'user' | 'listed' | 'repo' | 'file';
|
|
167
222
|
/** The file, absolute, with forward slashes. */
|
|
168
223
|
file: string;
|
|
169
|
-
/** What chose it: the call's `
|
|
224
|
+
/** What chose it: the call's `toilProject` input, TOIL_PROJECT, or the folder. */
|
|
170
225
|
by: 'input' | 'env' | 'folder';
|
|
171
|
-
/** How the folder matched it: a repo's path, a repo's remote, or a
|
|
226
|
+
/** How the folder matched it: a repo's path, a repo's remote, or a toil project checked into the folder's repository. */
|
|
172
227
|
match?: 'path' | 'remote' | 'checked-in';
|
|
173
|
-
/** The
|
|
228
|
+
/** The toil project's repo the folder is, when one matched. */
|
|
174
229
|
repo?: string;
|
|
175
|
-
/** The folder, when it chose the
|
|
230
|
+
/** The folder, when it chose the toil project or the call named one: the `cwd` input, or where the workspace came from. */
|
|
176
231
|
folder?: {
|
|
177
232
|
path: string;
|
|
178
233
|
from: 'input' | 'flag' | 'env' | 'cwd' | 'mcp-root';
|
|
179
234
|
};
|
|
180
235
|
}
|
|
181
236
|
interface ContextReport {
|
|
182
|
-
/** The
|
|
183
|
-
|
|
237
|
+
/** The toil project that supplied context, when one applied. */
|
|
238
|
+
toilProject?: ToilProjectReport;
|
|
184
239
|
connection?: ContextValue;
|
|
185
240
|
/** Each context input that resolved. Absent when none did. */
|
|
186
241
|
inputs?: Record<string, ContextValue>;
|
|
@@ -738,7 +793,7 @@ interface CommandInfo {
|
|
|
738
793
|
description: string;
|
|
739
794
|
/** Every call writes: refused under `readOnly`, and gated by `writes` plus `allowWrite` otherwise. */
|
|
740
795
|
writes: boolean;
|
|
741
|
-
/** Every call changes something on this machine (toil's config or
|
|
796
|
+
/** Every call changes something on this machine (toil's config or toil projects, a download): refused under `readOnly`. */
|
|
742
797
|
writesLocal: boolean;
|
|
743
798
|
/** Some calls write, depending on the input (the raw passthrough's POST, a file named with `out`); those are refused under `readOnly`. */
|
|
744
799
|
writesDependOnInput: boolean;
|
|
@@ -755,6 +810,31 @@ interface AreaSummary {
|
|
|
755
810
|
* connection.
|
|
756
811
|
*/
|
|
757
812
|
connection: readonly ConnectionField[];
|
|
813
|
+
/** What its credential must be allowed to do, per kind of credential. Left out for an area that declares none (`toil connections scopes`). */
|
|
814
|
+
scopes?: DescribedScopes;
|
|
815
|
+
/** The setting whose value picks the deployment (`deployment`), for an area with variants. */
|
|
816
|
+
variantBy?: string;
|
|
817
|
+
}
|
|
818
|
+
/** Presets for a setting, as a form shows them: radio buttons, one of which may build the value from a word the person types. */
|
|
819
|
+
interface ConnectionChoices {
|
|
820
|
+
question?: string;
|
|
821
|
+
/** No option starts selected; the person must pick one. */
|
|
822
|
+
required?: boolean;
|
|
823
|
+
options: readonly {
|
|
824
|
+
label: string;
|
|
825
|
+
/** What choosing it sets, or null when the person types it. */
|
|
826
|
+
value: string | null;
|
|
827
|
+
when?: Readonly<Record<string, string>>;
|
|
828
|
+
placeholder?: string;
|
|
829
|
+
compose?: {
|
|
830
|
+
prefix: string;
|
|
831
|
+
suffix?: string;
|
|
832
|
+
label: string;
|
|
833
|
+
placeholder: string;
|
|
834
|
+
};
|
|
835
|
+
hosts?: readonly string[];
|
|
836
|
+
expectPath?: string;
|
|
837
|
+
}[];
|
|
758
838
|
}
|
|
759
839
|
/** One value a connection holds, as `toil connections add` asks for it. */
|
|
760
840
|
interface ConnectionField {
|
|
@@ -769,6 +849,12 @@ interface ConnectionField {
|
|
|
769
849
|
default: string | null;
|
|
770
850
|
/** The connection isn't valid without it. */
|
|
771
851
|
required: boolean;
|
|
852
|
+
/** Presets a form offers as radio buttons; `value` is null for the one the person types. Left out when there are none. */
|
|
853
|
+
choices?: ConnectionChoices;
|
|
854
|
+
/** The values of the area's variant setting (`deployment`) this applies to; left out when it applies to all. */
|
|
855
|
+
appliesTo?: readonly string[];
|
|
856
|
+
/** The variants whose connections can't do without it, though it isn't required of every one. */
|
|
857
|
+
requiredFor?: readonly string[];
|
|
772
858
|
}
|
|
773
859
|
/**
|
|
774
860
|
* The commands and areas this toil has. `commands` is what `execute()`
|
|
@@ -790,8 +876,8 @@ interface Registry {
|
|
|
790
876
|
* `confirm-name` (type the connection's name to turn writes on), `unwrap:<key>`
|
|
791
877
|
* (the secret for `<key>` is in quotes or starts with `Bearer ` or `token `:
|
|
792
878
|
* `y` stores it without them, `n` as entered; `checkSecret` says which before
|
|
793
|
-
* the call, so a host can ask its person first), for `
|
|
794
|
-
* `create:<section>` (add a connection that
|
|
879
|
+
* the call, so a host can ask its person first), for `toil projects onboard`
|
|
880
|
+
* `create:<section>` (add a connection that toil project section needs: `y` or `n`),
|
|
795
881
|
* `name:<section>` (the new connection's name) and `pin:<section>` (which
|
|
796
882
|
* matching connection the person's own copy uses), and `consent`
|
|
797
883
|
* (`feedback`: send the report and disclaimer the question shows to Imagile
|
|
@@ -821,7 +907,7 @@ interface ExecuteOptions {
|
|
|
821
907
|
/**
|
|
822
908
|
* Refuse the call, before anything resolves or is sent, if it would change
|
|
823
909
|
* anything: a write to a service, or on this machine (toil's config or
|
|
824
|
-
*
|
|
910
|
+
* toil projects, a download, a file named with `out`). The refusal is
|
|
825
911
|
* `WRITE_DISABLED`, whatever the config says. A read-only call writes
|
|
826
912
|
* nothing but its audit line.
|
|
827
913
|
*/
|
|
@@ -874,8 +960,8 @@ declare const registry: Registry;
|
|
|
874
960
|
* throws: an unknown command, a bad option or a failure inside is an envelope
|
|
875
961
|
* with `ok: false`, like every other. `input` is the command's MCP fields
|
|
876
962
|
* (`{ jql: "project = PAY", limit: 50 }`), checked strictly. On a Node toil
|
|
877
|
-
*
|
|
878
|
-
* `
|
|
963
|
+
* flags (`src/core/runtime.ts`, CVE-2026-111497) every envelope carries the
|
|
964
|
+
* warning in `meta.warnings`, from core like the other front doors; the call still runs.
|
|
879
965
|
*/
|
|
880
966
|
declare function execute(command: string, input?: Record<string, unknown>, options?: ExecuteOptions): Promise<Envelope>;
|
|
881
967
|
/**
|
|
@@ -883,7 +969,7 @@ declare function execute(command: string, input?: Record<string, unknown>, optio
|
|
|
883
969
|
* holds envelopes: the same mapping `util owi map` does, in-process and
|
|
884
970
|
* synchronous. `input` is envelopes (one, an array, or JSON or JSON Lines
|
|
885
971
|
* text), or a command's bare `data` with `command` named; `fields` is a
|
|
886
|
-
*
|
|
972
|
+
* toil project section's `fields` object (`{ estimate: "customfield_10234",
|
|
887
973
|
* estimateUnit: "points" }`). It doesn't validate against the schema the way
|
|
888
974
|
* `execute('util owi map', …)` does, which runs the check in a worker; use
|
|
889
975
|
* that, or `owiSchema`, to check. Refusals (an override OWI has no field for,
|
|
@@ -891,7 +977,7 @@ declare function execute(command: string, input?: Record<string, unknown>, optio
|
|
|
891
977
|
*/
|
|
892
978
|
declare function mapOwi(input: unknown, options?: OwiMapOptions): OwiResult;
|
|
893
979
|
interface OwiMapOptions {
|
|
894
|
-
/** OWI fields pointed at a team's own fields: a
|
|
980
|
+
/** OWI fields pointed at a team's own fields: a toil project section's `fields`, or `name=field` strings. */
|
|
895
981
|
fields?: Record<string, string> | string[];
|
|
896
982
|
/** The command whose bare `data` the input is (`jira issue search`). */
|
|
897
983
|
command?: string;
|
|
@@ -930,4 +1016,4 @@ declare const owiSchema: Record<string, unknown>;
|
|
|
930
1016
|
*/
|
|
931
1017
|
declare function checkSecret(raw: string, rules: SecretRules): SecretCheck;
|
|
932
1018
|
|
|
933
|
-
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
|
|
1019
|
+
export { type ApiAnswer, type AreaSummary, type AuthorKind, type AuthorKindSource, type Body, type Change, type ChangeSize, type ChangeState, type ChecksState, type CommandInfo, type CommandKind, type ConnectionChoices, type ConnectionField, type ContextReport, type ContextSource, type ContextValue, 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 ToilProjectReport, type Transition, type Unmapped, type Warning, type WorkItem, type WorkItemType, checkSecret, contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version };
|