@imagile-dev/toil 0.1.0-beta.4 → 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/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
@@ -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()`
@@ -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
- * refuses (`src/core/runtime.ts`, CVE-2026-111497) every call is the CLI's
878
- * `UNSUPPORTED_NODE` envelope, before anything runs or fetches.
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
  /**
@@ -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 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 };
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 };