@theholocron/cli 5.0.0-alpha.27 → 5.0.0-alpha.270
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 +356 -58
- package/dist/cli.mjs +16060 -7979
- package/dist/cli.mjs.map +1 -1
- package/dist/compose-CDyegVKe.mjs +219 -0
- package/dist/index-CL7nYbMl.d.mts +644 -0
- package/dist/index-CwxYoWzS.d.mts +1685 -0
- package/dist/index.d.mts +125 -580
- package/dist/index.mjs +179 -253
- package/dist/plugin/capabilities.d.mts +2 -794
- package/dist/plugin/capabilities.mjs +23 -3
- package/dist/presets.d.mts +211 -0
- package/dist/presets.mjs +401 -0
- package/package.json +25 -21
|
@@ -0,0 +1,1685 @@
|
|
|
1
|
+
import { ProviderApiError } from "@theholocron/http-client";
|
|
2
|
+
/**
|
|
3
|
+
* Capability interfaces — the contracts that providers implement.
|
|
4
|
+
*
|
|
5
|
+
* Each capability has a stable key (`'source'`, `'ci'`, …) and a
|
|
6
|
+
* cardinality (`'single'` = one provider; `'many'` = several active
|
|
7
|
+
* at once). The cardinality is part of the type contract via
|
|
8
|
+
* `CardinalityFor<K>` so config resolution + command code can branch
|
|
9
|
+
* statically.
|
|
10
|
+
*
|
|
11
|
+
* See `docs/wiki/specifications/tech-architecture.spec.md` for the design narrative
|
|
12
|
+
* (issue: #74).
|
|
13
|
+
*/
|
|
14
|
+
type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "errors" | "logs" | "monitoring" | "wiki" | "workers";
|
|
15
|
+
type Cardinality = "single" | "many";
|
|
16
|
+
interface ProviderIdentity {
|
|
17
|
+
readonly key: CapabilityKey;
|
|
18
|
+
readonly providerName: string;
|
|
19
|
+
}
|
|
20
|
+
interface Ruleset {
|
|
21
|
+
id: number;
|
|
22
|
+
name: string;
|
|
23
|
+
enforcement: "active" | "evaluate" | "disabled";
|
|
24
|
+
target?: string;
|
|
25
|
+
}
|
|
26
|
+
interface RepoSettings {
|
|
27
|
+
allow_squash_merge?: boolean;
|
|
28
|
+
allow_merge_commit?: boolean;
|
|
29
|
+
allow_rebase_merge?: boolean;
|
|
30
|
+
allow_auto_merge?: boolean;
|
|
31
|
+
/** Always suggest updating PR branches when the base branch has new commits. */
|
|
32
|
+
allow_update_branch?: boolean;
|
|
33
|
+
delete_branch_on_merge?: boolean;
|
|
34
|
+
default_branch?: string;
|
|
35
|
+
has_issues?: boolean;
|
|
36
|
+
has_discussions?: boolean;
|
|
37
|
+
has_projects?: boolean;
|
|
38
|
+
has_wiki?: boolean;
|
|
39
|
+
}
|
|
40
|
+
interface RepoRef {
|
|
41
|
+
owner: string;
|
|
42
|
+
name: string;
|
|
43
|
+
defaultBranch: string;
|
|
44
|
+
}
|
|
45
|
+
interface LabelDef {
|
|
46
|
+
readonly name: string;
|
|
47
|
+
readonly color: string;
|
|
48
|
+
readonly description: string;
|
|
49
|
+
}
|
|
50
|
+
type TeamPermission = "pull" | "triage" | "push" | "maintain" | "admin";
|
|
51
|
+
/** Shorthand `"slug"` defaults to `push` permission. */
|
|
52
|
+
type TeamEntry = string | {
|
|
53
|
+
slug: string;
|
|
54
|
+
permission: TeamPermission;
|
|
55
|
+
};
|
|
56
|
+
/** A member of a team, as {@link Source.teamMembers} reports it. */
|
|
57
|
+
interface SourceTeamMember {
|
|
58
|
+
/** The provider's stable id for the person; for GitHub, the numeric user id as a string. */
|
|
59
|
+
id: string;
|
|
60
|
+
/** What they are called now. Can change; never use it as a key. */
|
|
61
|
+
login: string;
|
|
62
|
+
}
|
|
63
|
+
/** A file read by {@link Source.readFile}. */
|
|
64
|
+
interface SourceFile {
|
|
65
|
+
content: string;
|
|
66
|
+
/** Opaque; hand it back to {@link Source.writeFile} to replace this exact version. */
|
|
67
|
+
version: string;
|
|
68
|
+
}
|
|
69
|
+
interface Source extends ProviderIdentity {
|
|
70
|
+
readonly key: "source";
|
|
71
|
+
/** Auth sanity-check. Throws ProviderApiError on auth failure. */
|
|
72
|
+
whoami(): Promise<{
|
|
73
|
+
login: string;
|
|
74
|
+
}>;
|
|
75
|
+
getRepo(): Promise<RepoRef>;
|
|
76
|
+
listRulesets(): Promise<Ruleset[]>;
|
|
77
|
+
createRuleset(payload: Record<string, unknown>): Promise<Ruleset>;
|
|
78
|
+
updateRuleset(id: number, payload: Record<string, unknown>): Promise<Ruleset>;
|
|
79
|
+
updateRepoSettings(settings: RepoSettings): Promise<void>;
|
|
80
|
+
/**
|
|
81
|
+
* Classic branch protection — fallback for private repos on free plans
|
|
82
|
+
* where the Rulesets API (requires Team+) returns 403.
|
|
83
|
+
*/
|
|
84
|
+
protectBranch(branch: string, payload: Record<string, unknown>): Promise<void>;
|
|
85
|
+
enableVulnerabilityAlerts(): Promise<void>;
|
|
86
|
+
enableAutomatedSecurityFixes(): Promise<void>;
|
|
87
|
+
enableSecretScanning(): Promise<void>;
|
|
88
|
+
enablePrivateVulnerabilityReporting(): Promise<void>;
|
|
89
|
+
/**
|
|
90
|
+
* Enables the dependency graph and automatic dependency snapshot
|
|
91
|
+
* submission. Also enables secret-scanning validity checks and
|
|
92
|
+
* non-provider pattern detection — these require GitHub Advanced
|
|
93
|
+
* Security at the org level; the call is accepted but may be a no-op
|
|
94
|
+
* until that is configured.
|
|
95
|
+
*/
|
|
96
|
+
enableDependencyGraph(): Promise<void>;
|
|
97
|
+
/**
|
|
98
|
+
* Enables CodeQL default setup with the extended query suite and
|
|
99
|
+
* `threat_model: all` (scans both remote and local exploit paths).
|
|
100
|
+
* Triggers a new analysis run; returns the run id.
|
|
101
|
+
*/
|
|
102
|
+
enableCodeScanning(): Promise<string>;
|
|
103
|
+
/**
|
|
104
|
+
* Disables CodeQL default setup. Required when the repo uses an advanced
|
|
105
|
+
* CodeQL workflow instead — GitHub rejects SARIF from advanced workflows
|
|
106
|
+
* while default setup is active.
|
|
107
|
+
*/
|
|
108
|
+
disableDefaultCodeScanning(): Promise<void>;
|
|
109
|
+
listWorkflowFiles(): Promise<string[]>;
|
|
110
|
+
readWorkflowFile(name: string): Promise<string | null>;
|
|
111
|
+
writeWorkflowFile(name: string, contents: string): Promise<void>;
|
|
112
|
+
removeWorkflowFile(name: string): Promise<void>;
|
|
113
|
+
/**
|
|
114
|
+
* Write an arbitrary file relative to the repo root. Used for
|
|
115
|
+
* provisioning config files that live outside `.github/workflows/`
|
|
116
|
+
* (e.g. `.github/dependabot.yml`).
|
|
117
|
+
*/
|
|
118
|
+
writeRepoFile(path: string, contents: string): Promise<void>;
|
|
119
|
+
/**
|
|
120
|
+
* Idempotently sync repo labels to a canonical set. Creates missing
|
|
121
|
+
* labels, patches color/description drift, deletes stale labels.
|
|
122
|
+
* Optional — providers that have no label concept omit this.
|
|
123
|
+
*/
|
|
124
|
+
syncLabels?(canonical: ReadonlyArray<LabelDef>, stale: ReadonlyArray<string>): Promise<string>;
|
|
125
|
+
/**
|
|
126
|
+
* Set org-level custom property values on the repo. `string[]` for
|
|
127
|
+
* `multi_select` properties, plain `string` for everything else.
|
|
128
|
+
* Optional — providers that don't support custom properties omit this.
|
|
129
|
+
*/
|
|
130
|
+
syncProperties?(values: Record<string, string | string[]>): Promise<string>;
|
|
131
|
+
/**
|
|
132
|
+
* Replace the repo's topic set with the supplied list.
|
|
133
|
+
* Optional — providers that don't support topics omit this.
|
|
134
|
+
*/
|
|
135
|
+
syncTopics?(topics: string[]): Promise<string>;
|
|
136
|
+
/**
|
|
137
|
+
* Bring the repository's Actions variables in line with the declared ones: create what is missing, update what
|
|
138
|
+
* differs, leave the rest. With `prune`, also delete the ones the declaration does not name. With `dryRun`, read the current
|
|
139
|
+
* state and report what would change without writing. Returns a summary.
|
|
140
|
+
* Optional — providers without Actions variables omit this.
|
|
141
|
+
*/
|
|
142
|
+
syncVariables?(variables: Record<string, string>, opts?: {
|
|
143
|
+
prune?: boolean;
|
|
144
|
+
dryRun?: boolean;
|
|
145
|
+
}): Promise<string>;
|
|
146
|
+
/**
|
|
147
|
+
* The same for the organization's variables, each with the repositories that can read it (`all` or `private`).
|
|
148
|
+
* Optional — providers without organization variables omit this.
|
|
149
|
+
*/
|
|
150
|
+
syncOrgVariables?(org: string, variables: Record<string, {
|
|
151
|
+
value: string;
|
|
152
|
+
visibility: "all" | "private";
|
|
153
|
+
}>, opts?: {
|
|
154
|
+
prune?: boolean;
|
|
155
|
+
dryRun?: boolean;
|
|
156
|
+
}): Promise<string>;
|
|
157
|
+
/**
|
|
158
|
+
* The repository's Actions variables as they are now, by name, with their values. Read-only.
|
|
159
|
+
* Optional — providers without Actions variables omit this.
|
|
160
|
+
*/
|
|
161
|
+
listVariables?(): Promise<Record<string, string>>;
|
|
162
|
+
/**
|
|
163
|
+
* The organization's Actions variables as they are now, by name, with each value and the repositories that can read
|
|
164
|
+
* it (`selected` is a list this interface does not manage). Read-only. Throws {@link MissingTokenError} when the
|
|
165
|
+
* provider has no token that can read them.
|
|
166
|
+
* Optional — providers without organization variables omit this.
|
|
167
|
+
*/
|
|
168
|
+
listOrgVariables?(org: string): Promise<Record<string, {
|
|
169
|
+
value: string;
|
|
170
|
+
visibility: "all" | "private" | "selected";
|
|
171
|
+
}>>;
|
|
172
|
+
/**
|
|
173
|
+
* Sync GitHub team repository access. String shorthand defaults to `push`.
|
|
174
|
+
* Optional — providers without a team concept omit this.
|
|
175
|
+
*/
|
|
176
|
+
syncTeams?(teams: TeamEntry[]): Promise<string>;
|
|
177
|
+
/**
|
|
178
|
+
* The members of a team in `org` (default: the repo's organisation), by the provider's own stable id (for GitHub, the
|
|
179
|
+
* numeric user id, which survives a rename) and current login.
|
|
180
|
+
* Optional — providers without a team concept omit this.
|
|
181
|
+
*/
|
|
182
|
+
teamMembers?(teamSlug: string, org?: string): Promise<SourceTeamMember[]>;
|
|
183
|
+
/**
|
|
184
|
+
* Read one file from a repository (default: this one), with the `version` a later {@link writeFile} must
|
|
185
|
+
* hand back. `null` when the file does not exist.
|
|
186
|
+
* Optional — providers that cannot read file contents omit this.
|
|
187
|
+
*/
|
|
188
|
+
readFile?(path: string, repo?: string): Promise<SourceFile | null>;
|
|
189
|
+
/**
|
|
190
|
+
* Create or replace one file in a single commit. Pass the `version` {@link readFile} returned when
|
|
191
|
+
* replacing, and leave it out when creating: a write on top of a version that has since changed is
|
|
192
|
+
* refused (throws a `ProviderApiError` with status 409 or 422), so two writers cannot overwrite each other.
|
|
193
|
+
* Optional — providers that cannot write file contents omit this.
|
|
194
|
+
*/
|
|
195
|
+
writeFile?(path: string, content: string, opts: {
|
|
196
|
+
message: string;
|
|
197
|
+
version?: string;
|
|
198
|
+
repo?: string;
|
|
199
|
+
}): Promise<void>;
|
|
200
|
+
/**
|
|
201
|
+
* Set the repository description.
|
|
202
|
+
* Optional — providers that don't support setting descriptions omit this.
|
|
203
|
+
*/
|
|
204
|
+
syncDescription?(description: string): Promise<string>;
|
|
205
|
+
/**
|
|
206
|
+
* Set the repository homepage URL (the "Website" field on the repo landing page).
|
|
207
|
+
* Optional — providers that don't support setting a homepage omit this.
|
|
208
|
+
*/
|
|
209
|
+
syncHomepage?(homepage: string): Promise<string>;
|
|
210
|
+
/**
|
|
211
|
+
* Fetch a pull request by number. The `repo` override lets callers look up
|
|
212
|
+
* a PR in a different repo than the one the plugin is scoped to — useful
|
|
213
|
+
* when the cleanup command targets another repo's PR (e.g. docs PR from
|
|
214
|
+
* the holocron repo context).
|
|
215
|
+
* Optional — providers without a PR concept omit this.
|
|
216
|
+
*/
|
|
217
|
+
getPullRequest?(number: number, repo?: string): Promise<PullRequest>;
|
|
218
|
+
/**
|
|
219
|
+
* Every pull request in one state, newest first. `closed` includes the merged ones (`merged` tells them
|
|
220
|
+
* apart). Optional — providers without a PR concept omit this.
|
|
221
|
+
*/
|
|
222
|
+
listPullRequests?(state: "open" | "closed", repo?: string): Promise<PullRequest[]>;
|
|
223
|
+
/**
|
|
224
|
+
* The commit SHAs of one pull request, in commit order. A squash-merged branch is not an ancestor of the
|
|
225
|
+
* base, so this is how a local tip is matched to a PR whose head commit is not in the checkout.
|
|
226
|
+
* Optional — providers without a PR concept omit this.
|
|
227
|
+
*/
|
|
228
|
+
listPullRequestCommits?(number: number, repo?: string): Promise<string[]>;
|
|
229
|
+
/**
|
|
230
|
+
* Every branch on the remote, with the commit each points at.
|
|
231
|
+
* Optional — providers without branches omit this.
|
|
232
|
+
*/
|
|
233
|
+
listBranches?(repo?: string): Promise<SourceBranch[]>;
|
|
234
|
+
/**
|
|
235
|
+
* Delete one branch on the remote. Idempotent: a branch that is already gone is success, not an error.
|
|
236
|
+
* Optional — providers that cannot delete a branch omit this.
|
|
237
|
+
*/
|
|
238
|
+
deleteBranch?(name: string, repo?: string): Promise<void>;
|
|
239
|
+
/**
|
|
240
|
+
* Enable or update GitHub Pages for the repository.
|
|
241
|
+
* Idempotent: POST to create, PUT to update existing settings.
|
|
242
|
+
* Requires HOLOCRON_DEPLOY_TOKEN (pages:write + repo scope) — passed
|
|
243
|
+
* explicitly because it is a different PAT from the main admin token.
|
|
244
|
+
* Optional — providers without a Pages concept omit this.
|
|
245
|
+
*/
|
|
246
|
+
configurePages?(config: PagesConfig, token: string): Promise<void>;
|
|
247
|
+
}
|
|
248
|
+
interface PagesConfig {
|
|
249
|
+
/** GitHub Pages build source. */
|
|
250
|
+
build: "workflow" | "branch";
|
|
251
|
+
/**
|
|
252
|
+
* Custom domain / CNAME (e.g. "docs.theholocron.dev").
|
|
253
|
+
* When set and `homepage` is absent in holocron.config, setup derives
|
|
254
|
+
* homepage as `https://{domain}/`.
|
|
255
|
+
*/
|
|
256
|
+
domain?: string;
|
|
257
|
+
/** Enforce HTTPS. Only effective once the custom domain is DNS-verified. */
|
|
258
|
+
https?: boolean;
|
|
259
|
+
}
|
|
260
|
+
/** A branch on the remote and the commit it points at. */
|
|
261
|
+
interface SourceBranch {
|
|
262
|
+
/** The branch name, e.g. `fix/my-change`. */
|
|
263
|
+
name: string;
|
|
264
|
+
/** The commit the branch points at. */
|
|
265
|
+
sha: string;
|
|
266
|
+
}
|
|
267
|
+
interface PullRequest {
|
|
268
|
+
number: number;
|
|
269
|
+
title: string;
|
|
270
|
+
/** "open" | "closed" — GitHub marks merged PRs as "closed". */
|
|
271
|
+
state: "open" | "closed";
|
|
272
|
+
/** True when the PR was merged (as opposed to closed without merging). */
|
|
273
|
+
merged: boolean;
|
|
274
|
+
/** The head branch name (e.g. "fix/my-change"). */
|
|
275
|
+
branch: string;
|
|
276
|
+
/** The commit the head branch pointed at when the PR was last read. */
|
|
277
|
+
headSha?: string;
|
|
278
|
+
url: string;
|
|
279
|
+
}
|
|
280
|
+
type CiRunStatus = "queued" | "in_progress" | "completed" | "cancelled" | "failure" | "success" | "skipped";
|
|
281
|
+
interface CiRun {
|
|
282
|
+
id: string | number;
|
|
283
|
+
workflowName: string;
|
|
284
|
+
branch: string;
|
|
285
|
+
sha: string;
|
|
286
|
+
status: CiRunStatus;
|
|
287
|
+
url: string;
|
|
288
|
+
startedAt: string;
|
|
289
|
+
completedAt?: string;
|
|
290
|
+
}
|
|
291
|
+
interface CiRunFilter {
|
|
292
|
+
branch?: string;
|
|
293
|
+
status?: CiRunStatus;
|
|
294
|
+
limit?: number;
|
|
295
|
+
}
|
|
296
|
+
interface Ci extends ProviderIdentity {
|
|
297
|
+
readonly key: "ci";
|
|
298
|
+
listRuns(filter?: CiRunFilter): Promise<CiRun[]>;
|
|
299
|
+
getRun(id: string | number): Promise<CiRun>;
|
|
300
|
+
}
|
|
301
|
+
type SecretScope = {
|
|
302
|
+
kind: "repo";
|
|
303
|
+
} | {
|
|
304
|
+
kind: "environment";
|
|
305
|
+
name: string;
|
|
306
|
+
} | {
|
|
307
|
+
kind: "organization";
|
|
308
|
+
name: string;
|
|
309
|
+
};
|
|
310
|
+
interface Secrets extends ProviderIdentity {
|
|
311
|
+
readonly key: "secrets";
|
|
312
|
+
/** List secret NAMES (not values) at the given scope. */
|
|
313
|
+
listSecrets(scope: SecretScope): Promise<string[]>;
|
|
314
|
+
/** Idempotent upsert. Adapter handles encryption. */
|
|
315
|
+
setSecret(scope: SecretScope, name: string, value: string): Promise<void>;
|
|
316
|
+
deleteSecret(scope: SecretScope, name: string): Promise<void>;
|
|
317
|
+
}
|
|
318
|
+
interface EnvironmentReviewer {
|
|
319
|
+
type: "User" | "Team";
|
|
320
|
+
/** Numeric id — GitHub's reviewer API silently ignores login strings. */
|
|
321
|
+
id: number;
|
|
322
|
+
}
|
|
323
|
+
interface Environment {
|
|
324
|
+
name: string;
|
|
325
|
+
reviewers?: EnvironmentReviewer[];
|
|
326
|
+
waitTimer?: number;
|
|
327
|
+
preventSelfReview?: boolean;
|
|
328
|
+
}
|
|
329
|
+
interface Environments extends ProviderIdentity {
|
|
330
|
+
readonly key: "environments";
|
|
331
|
+
listEnvironments(): Promise<Environment[]>;
|
|
332
|
+
upsertEnvironment(env: Environment): Promise<void>;
|
|
333
|
+
deleteEnvironment(name: string): Promise<void>;
|
|
334
|
+
}
|
|
335
|
+
type LifecycleSlot = "inProgress" | "inReview" | "done";
|
|
336
|
+
type StatusCategory = "open" | "in-progress" | "in-review" | "done" | "other";
|
|
337
|
+
interface TrackerUser {
|
|
338
|
+
id: string;
|
|
339
|
+
displayName: string;
|
|
340
|
+
emailAddress?: string;
|
|
341
|
+
}
|
|
342
|
+
interface Issue {
|
|
343
|
+
/** Human-readable key — "#42" for GitHub, "RANDO-42" for Jira. */
|
|
344
|
+
key: string;
|
|
345
|
+
/** Internal opaque id. */
|
|
346
|
+
id: string;
|
|
347
|
+
summary: string;
|
|
348
|
+
body?: string;
|
|
349
|
+
status: string;
|
|
350
|
+
statusCategory: StatusCategory;
|
|
351
|
+
assignee: TrackerUser | null;
|
|
352
|
+
updated: string;
|
|
353
|
+
url?: string;
|
|
354
|
+
}
|
|
355
|
+
interface IssueSearchFilter {
|
|
356
|
+
/** Restrict to issues assigned to a specific id, or 'currentUser'. */
|
|
357
|
+
assignee?: string | "currentUser";
|
|
358
|
+
/** Exclude issues in the `done` category. */
|
|
359
|
+
openOnly?: boolean;
|
|
360
|
+
/** Max number of issues to return. Adapters apply a sensible default. */
|
|
361
|
+
limit?: number;
|
|
362
|
+
}
|
|
363
|
+
interface LifecycleResult {
|
|
364
|
+
/** False when no API write happened (already at target state). */
|
|
365
|
+
transitioned: boolean;
|
|
366
|
+
/** Status name the issue is in after this call. */
|
|
367
|
+
status: string;
|
|
368
|
+
/** Adapter-specific note (e.g., "label set" / "closed (completed)"). */
|
|
369
|
+
via?: string;
|
|
370
|
+
}
|
|
371
|
+
interface TrackerDoctorReport {
|
|
372
|
+
/** "Authenticated as ..." subject for the spinner. */
|
|
373
|
+
authedAs: string;
|
|
374
|
+
/** Free-form "Project: RANDO" / "Repo: rando-id/rando" identifier. */
|
|
375
|
+
projectLabel: string;
|
|
376
|
+
/** Status values the adapter exposes. */
|
|
377
|
+
statuses: Array<{
|
|
378
|
+
name: string;
|
|
379
|
+
category: StatusCategory;
|
|
380
|
+
}>;
|
|
381
|
+
/**
|
|
382
|
+
* Per-lifecycle-slot readiness check. `resolved` indicates whether
|
|
383
|
+
* the configured value actually maps to something the tracker
|
|
384
|
+
* recognizes; the `note` is the rendered explanation.
|
|
385
|
+
*/
|
|
386
|
+
lifecycle: Array<{
|
|
387
|
+
slot: LifecycleSlot;
|
|
388
|
+
value: string | null;
|
|
389
|
+
resolved: boolean;
|
|
390
|
+
note: string;
|
|
391
|
+
}>;
|
|
392
|
+
}
|
|
393
|
+
interface Issues extends ProviderIdentity {
|
|
394
|
+
readonly key: "issues";
|
|
395
|
+
/** Currently-authenticated user. */
|
|
396
|
+
getMyself(): Promise<TrackerUser>;
|
|
397
|
+
search(filter: IssueSearchFilter): Promise<Issue[]>;
|
|
398
|
+
get(key: string): Promise<Issue>;
|
|
399
|
+
create(input: {
|
|
400
|
+
summary: string;
|
|
401
|
+
body?: string;
|
|
402
|
+
labels?: string[];
|
|
403
|
+
/** Numeric id or exact title (case-insensitive). */
|
|
404
|
+
milestone?: string;
|
|
405
|
+
}): Promise<{
|
|
406
|
+
key: string;
|
|
407
|
+
}>;
|
|
408
|
+
/** Idempotent — `transitioned: false` if the issue is already at the target. */
|
|
409
|
+
transition(key: string, slot: LifecycleSlot): Promise<LifecycleResult>;
|
|
410
|
+
comment(key: string, body: string): Promise<void>;
|
|
411
|
+
doctor(): Promise<TrackerDoctorReport>;
|
|
412
|
+
}
|
|
413
|
+
/** Env-var scope on the deploy platform. */
|
|
414
|
+
type DeploymentTarget = "development" | "preview" | "production";
|
|
415
|
+
/**
|
|
416
|
+
* Named deployment trigger target — `undefined` means a branch
|
|
417
|
+
* preview (no named environment).
|
|
418
|
+
*/
|
|
419
|
+
type DeploymentTrigger = "production" | "staging";
|
|
420
|
+
interface DeploymentProject {
|
|
421
|
+
id: string;
|
|
422
|
+
name: string;
|
|
423
|
+
framework?: string;
|
|
424
|
+
/** True when the project is linked to a Git provider. */
|
|
425
|
+
gitLinked?: boolean;
|
|
426
|
+
rootDirectory?: string | null;
|
|
427
|
+
}
|
|
428
|
+
interface DeploymentProjectSettings {
|
|
429
|
+
previewDeploymentsDisabled?: boolean;
|
|
430
|
+
/** Vercel-specific: whether the GitHub integration creates deployments
|
|
431
|
+
* for every push (false → only on-demand triggers). */
|
|
432
|
+
gitProviderCreateDeployments?: boolean;
|
|
433
|
+
}
|
|
434
|
+
interface DeploymentRecord {
|
|
435
|
+
id: string;
|
|
436
|
+
url: string;
|
|
437
|
+
/** Branch this deployment was made from (null if not git-sourced). */
|
|
438
|
+
branch: string | null;
|
|
439
|
+
/** Named environment if one was targeted; undefined for branch previews. */
|
|
440
|
+
target?: DeploymentTrigger;
|
|
441
|
+
status: "queued" | "building" | "ready" | "error" | "cancelled";
|
|
442
|
+
createdAt?: string;
|
|
443
|
+
/** The provider's own reason when `status` is `"error"` (e.g. Vercel's `Command "npm install" exited with 1`). */
|
|
444
|
+
errorMessage?: string;
|
|
445
|
+
}
|
|
446
|
+
/** Config for `Deployment.deployFunction()` — source files, not a Git ref. */
|
|
447
|
+
interface DeployFunctionConfig {
|
|
448
|
+
/**
|
|
449
|
+
* Files to deploy, keyed by path relative to the project root (e.g.
|
|
450
|
+
* `"api/webhook.js"`, `"package.json"`). Content is plain text — the
|
|
451
|
+
* provider handles any wire-format encoding.
|
|
452
|
+
*/
|
|
453
|
+
files: Record<string, string>;
|
|
454
|
+
/**
|
|
455
|
+
* Named deployment target. Omit for a preview deployment — same
|
|
456
|
+
* semantics as `triggerDeployment`'s `target`.
|
|
457
|
+
*/
|
|
458
|
+
target?: DeploymentTrigger;
|
|
459
|
+
}
|
|
460
|
+
interface DeployFunctionResult {
|
|
461
|
+
deploymentId: string;
|
|
462
|
+
url: string;
|
|
463
|
+
}
|
|
464
|
+
interface Deployment extends ProviderIdentity {
|
|
465
|
+
readonly key: "deployment";
|
|
466
|
+
/**
|
|
467
|
+
* Custom domain declared in the deployment provider's configuration.
|
|
468
|
+
* `holocron repo setup` attaches it to the configured project and hands any
|
|
469
|
+
* returned verification record to the `dns` capability.
|
|
470
|
+
*/
|
|
471
|
+
readonly domain?: string;
|
|
472
|
+
listProjects(): Promise<DeploymentProject[]>;
|
|
473
|
+
/** Create if missing, otherwise return existing. Idempotent. */
|
|
474
|
+
ensureProject(input: {
|
|
475
|
+
name: string;
|
|
476
|
+
framework?: string;
|
|
477
|
+
/** "owner/repo" — passed when linking to a Git provider. */
|
|
478
|
+
repo?: string;
|
|
479
|
+
rootDirectory?: string;
|
|
480
|
+
}): Promise<DeploymentProject>;
|
|
481
|
+
updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
|
|
482
|
+
listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
|
|
483
|
+
setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
|
|
484
|
+
/**
|
|
485
|
+
* Kick off a deployment of the given branch. Omit `target` for a
|
|
486
|
+
* branch preview; pass `'production'` / `'staging'` to deploy into
|
|
487
|
+
* a named environment.
|
|
488
|
+
*/
|
|
489
|
+
triggerDeployment(input: {
|
|
490
|
+
projectId: string;
|
|
491
|
+
branch: string;
|
|
492
|
+
target?: DeploymentTrigger;
|
|
493
|
+
}): Promise<DeploymentRecord>;
|
|
494
|
+
getDeployment(deploymentId: string): Promise<DeploymentRecord>;
|
|
495
|
+
/**
|
|
496
|
+
* Deploy (or update) a project directly from source files, bypassing
|
|
497
|
+
* Git entirely — the non-git counterpart to `triggerDeployment`, for a
|
|
498
|
+
* consumer with no repo to link (a webhook receiver shipped as an npm
|
|
499
|
+
* package, for instance, rather than deployed from its own Git
|
|
500
|
+
* history). `projectId` may be a project name for providers that
|
|
501
|
+
* accept either. Optional — providers without a files-based deploy API
|
|
502
|
+
* omit this (e.g. Cloudflare Pages, git-source only today).
|
|
503
|
+
*/
|
|
504
|
+
deployFunction?(projectId: string, config: DeployFunctionConfig): Promise<DeployFunctionResult>;
|
|
505
|
+
/**
|
|
506
|
+
* List preview deployments for a specific branch alias (e.g. "repo-pr-42").
|
|
507
|
+
* Optional — providers that don't support listing by branch omit this.
|
|
508
|
+
*/
|
|
509
|
+
listPreviewDeployments?(projectId: string, branch: string): Promise<DeploymentRecord[]>;
|
|
510
|
+
/**
|
|
511
|
+
* Delete specific preview deployments by id. Returns the count deleted.
|
|
512
|
+
* Optional — providers that don't support deletion omit this.
|
|
513
|
+
*/
|
|
514
|
+
deletePreviewDeployments?(projectId: string, deploymentIds: string[]): Promise<number>;
|
|
515
|
+
/**
|
|
516
|
+
* Add a custom domain (or wildcard) to the project. Idempotent — no-op
|
|
517
|
+
* when the domain is already present. Optional: providers without a
|
|
518
|
+
* custom domain API omit this.
|
|
519
|
+
*
|
|
520
|
+
* Returns the DNS record needed to finish verification — `null` when
|
|
521
|
+
* the domain is already verified, or when the provider's API doesn't
|
|
522
|
+
* surface DNS-challenge details at all (e.g. Cloudflare Pages, whose
|
|
523
|
+
* custom-domain flow doesn't expose the same per-request verification
|
|
524
|
+
* handshake Vercel's does). Callers hand a non-null result straight
|
|
525
|
+
* to `dns.upsertRecord(result.zone, result.record)` — the exact
|
|
526
|
+
* pattern `setup` already uses for `Wiki.dnsRecord()`.
|
|
527
|
+
*/
|
|
528
|
+
ensureCustomDomain?(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
|
|
529
|
+
}
|
|
530
|
+
interface StorageBranch {
|
|
531
|
+
id: string;
|
|
532
|
+
name: string;
|
|
533
|
+
/** Parent branch id; null for the root/main branch. */
|
|
534
|
+
parentId: string | null;
|
|
535
|
+
createdAt: string;
|
|
536
|
+
}
|
|
537
|
+
interface ConnectionStringOptions {
|
|
538
|
+
/** Use the pooled (PgBouncer) URL when available. Defaults to false. */
|
|
539
|
+
pooled?: boolean;
|
|
540
|
+
}
|
|
541
|
+
interface Storage extends ProviderIdentity {
|
|
542
|
+
readonly key: "storage";
|
|
543
|
+
/**
|
|
544
|
+
* Connection string for the given scope. Scope is provider-specific:
|
|
545
|
+
*
|
|
546
|
+
* - branch-based providers (Neon, PlanetScale): scope = branch
|
|
547
|
+
* name or id
|
|
548
|
+
* - flat providers (single Postgres instance): scope is ignored
|
|
549
|
+
*
|
|
550
|
+
* Callers (or the orchestrator) decide how a deploy target maps to
|
|
551
|
+
* a scope; the storage plugin doesn't own that mapping.
|
|
552
|
+
*/
|
|
553
|
+
getConnectionString(scope: string, options?: ConnectionStringOptions): Promise<string>;
|
|
554
|
+
listBranches?(): Promise<StorageBranch[]>;
|
|
555
|
+
createBranch?(input: {
|
|
556
|
+
name: string;
|
|
557
|
+
from?: string;
|
|
558
|
+
}): Promise<StorageBranch>;
|
|
559
|
+
destroyBranch?(branch: string): Promise<void>;
|
|
560
|
+
/** Restore one branch to match another (e.g., reset preview → main). */
|
|
561
|
+
resetBranch?(input: {
|
|
562
|
+
branch: string;
|
|
563
|
+
from: string;
|
|
564
|
+
}): Promise<void>;
|
|
565
|
+
/**
|
|
566
|
+
* Provider-specific feature toggle. For Postgres providers this is
|
|
567
|
+
* `CREATE EXTENSION IF NOT EXISTS ...` per branch.
|
|
568
|
+
*/
|
|
569
|
+
enableExtension?(input: {
|
|
570
|
+
branch: string;
|
|
571
|
+
extension: string;
|
|
572
|
+
}): Promise<void>;
|
|
573
|
+
}
|
|
574
|
+
interface AuthDescription {
|
|
575
|
+
provider: string;
|
|
576
|
+
/** Env-var names the app needs at runtime (CLERK_PUBLISHABLE_KEY, etc.). */
|
|
577
|
+
envKeys: string[];
|
|
578
|
+
}
|
|
579
|
+
interface AuthIdentity {
|
|
580
|
+
provider: string;
|
|
581
|
+
/** Provider-specific health signal (user count, role, account name, etc.). */
|
|
582
|
+
details?: Record<string, unknown>;
|
|
583
|
+
}
|
|
584
|
+
interface AuthUser {
|
|
585
|
+
id: string;
|
|
586
|
+
email: string;
|
|
587
|
+
}
|
|
588
|
+
interface CreateAuthUserInput {
|
|
589
|
+
email: string;
|
|
590
|
+
password: string;
|
|
591
|
+
firstName?: string;
|
|
592
|
+
lastName?: string;
|
|
593
|
+
}
|
|
594
|
+
interface WebhookDashboardInfo {
|
|
595
|
+
url: string;
|
|
596
|
+
}
|
|
597
|
+
interface Auth extends ProviderIdentity {
|
|
598
|
+
readonly key: "auth";
|
|
599
|
+
/** Env-var keys the runtime app needs. */
|
|
600
|
+
describe(): Promise<AuthDescription>;
|
|
601
|
+
/** Reachability probe — proves the configured key works. */
|
|
602
|
+
whoami(): Promise<AuthIdentity>;
|
|
603
|
+
/** Idempotent webhook backend provisioning (Clerk: Svix app). */
|
|
604
|
+
ensureWebhookApp?(): Promise<{
|
|
605
|
+
alreadyExists: boolean;
|
|
606
|
+
}>;
|
|
607
|
+
/** Deep-link to the provider's webhook config dashboard. */
|
|
608
|
+
getWebhookDashboardUrl?(): Promise<WebhookDashboardInfo>;
|
|
609
|
+
/** Seed a user (test fixtures, admin bootstrap). */
|
|
610
|
+
createUser?(input: CreateAuthUserInput): Promise<AuthUser>;
|
|
611
|
+
/** Wire the auth provider's webhook into the project's repo. */
|
|
612
|
+
syncWebhook?(input: {
|
|
613
|
+
repo: string;
|
|
614
|
+
secretRef: string;
|
|
615
|
+
}): Promise<void>;
|
|
616
|
+
}
|
|
617
|
+
type AuthEventType = "user.created" | "user.updated" | "user.deleted";
|
|
618
|
+
interface NormalizedAuthUser {
|
|
619
|
+
id: string;
|
|
620
|
+
email: string;
|
|
621
|
+
firstName?: string | null;
|
|
622
|
+
lastName?: string | null;
|
|
623
|
+
/** Provider-native fields preserved verbatim for consumers that need them. */
|
|
624
|
+
raw?: Record<string, unknown>;
|
|
625
|
+
}
|
|
626
|
+
interface AuthEvent {
|
|
627
|
+
type: AuthEventType;
|
|
628
|
+
user: NormalizedAuthUser;
|
|
629
|
+
/** ISO timestamp of when the event occurred. */
|
|
630
|
+
occurredAt: string;
|
|
631
|
+
}
|
|
632
|
+
interface ParseWebhookInput {
|
|
633
|
+
/** Raw request body (string or Buffer). */
|
|
634
|
+
body: string | Buffer;
|
|
635
|
+
/** Incoming HTTP headers — needed for signature verification. */
|
|
636
|
+
headers: Record<string, string | string[] | undefined>;
|
|
637
|
+
/** The signing secret the auth provider issued for this webhook endpoint. */
|
|
638
|
+
signingSecret: string;
|
|
639
|
+
}
|
|
640
|
+
interface EnsureResult {
|
|
641
|
+
/** True when the resource already existed (idempotent no-op). */
|
|
642
|
+
alreadyExists: boolean;
|
|
643
|
+
}
|
|
644
|
+
interface Vault extends ProviderIdentity {
|
|
645
|
+
readonly key: "vault";
|
|
646
|
+
/**
|
|
647
|
+
* Read a secret by reference. The reference format is
|
|
648
|
+
* provider-specific (1P: "op://Vault/Item/field"; HashiCorp Vault:
|
|
649
|
+
* "kv/path#field"; etc.). Adapters validate the reference shape.
|
|
650
|
+
*/
|
|
651
|
+
read(reference: string): Promise<string>;
|
|
652
|
+
/**
|
|
653
|
+
* Optional — read a secret by its bare name from the project and config this vault was set up with, instead of by a
|
|
654
|
+
* full reference. For a provider whose references name the project and config the options already carry (Doppler).
|
|
655
|
+
*/
|
|
656
|
+
readSecret?(name: string): Promise<string>;
|
|
657
|
+
/** Write or update a secret. */
|
|
658
|
+
write(reference: string, value: string): Promise<void>;
|
|
659
|
+
/** List secret keys available to the project. */
|
|
660
|
+
list(): Promise<string[]>;
|
|
661
|
+
/**
|
|
662
|
+
* Optional environment notion within the vault (e.g., 1P
|
|
663
|
+
* Environments — named KEY=VALUE bundles). Adapters without
|
|
664
|
+
* environments return [].
|
|
665
|
+
*/
|
|
666
|
+
environments?(): Promise<string[]>;
|
|
667
|
+
/**
|
|
668
|
+
* Optional bulk read of an environment's KEY=VALUE pairs. Powers
|
|
669
|
+
* the `holocron secrets sync` flow where the orchestrator pulls a
|
|
670
|
+
* whole environment from the vault then fans the values out to
|
|
671
|
+
* destinations (CI secrets, deployment env vars, local .env).
|
|
672
|
+
*/
|
|
673
|
+
readEnvironment?(environmentId: string): Promise<Record<string, string>>;
|
|
674
|
+
/**
|
|
675
|
+
* Optional — create the top-level project container in the vault
|
|
676
|
+
* if it does not exist. Idempotent: `alreadyExists: true` when the
|
|
677
|
+
* project was already there. Providers whose data model has no
|
|
678
|
+
* project notion (or that gate this behind a paid tier) omit this.
|
|
679
|
+
*/
|
|
680
|
+
ensureProject?(name: string): Promise<EnsureResult>;
|
|
681
|
+
/**
|
|
682
|
+
* Optional — create a named environment/config inside a project
|
|
683
|
+
* (e.g., Doppler config `dev` / `stg` / `prd`). Idempotent.
|
|
684
|
+
* Providers whose data model has a single flat namespace omit this.
|
|
685
|
+
*/
|
|
686
|
+
ensureEnvironment?(project: string, name: string): Promise<EnsureResult>;
|
|
687
|
+
}
|
|
688
|
+
type DnsRecordType = "A" | "AAAA" | "CNAME" | "TXT" | "MX" | "NS" | "SRV" | "CAA";
|
|
689
|
+
interface DnsRecord {
|
|
690
|
+
id?: string;
|
|
691
|
+
type: DnsRecordType;
|
|
692
|
+
name: string;
|
|
693
|
+
content: string;
|
|
694
|
+
ttl?: number;
|
|
695
|
+
priority?: number;
|
|
696
|
+
proxied?: boolean;
|
|
697
|
+
}
|
|
698
|
+
/**
|
|
699
|
+
* A DNS record a capability wants created, plus which zone it belongs
|
|
700
|
+
* to — the shape `Wiki.dnsRecord()` and `Deployment.ensureCustomDomain()`
|
|
701
|
+
* both hand off to `Dns.upsertRecord()`. Not tied to either capability;
|
|
702
|
+
* any provider that needs "here's a record, go create it" returns this.
|
|
703
|
+
*/
|
|
704
|
+
interface DnsRecordRequest {
|
|
705
|
+
/** Zone apex passed as the first argument to `dns.upsertRecord`. */
|
|
706
|
+
zone: string;
|
|
707
|
+
record: DnsRecord;
|
|
708
|
+
}
|
|
709
|
+
interface Dns extends ProviderIdentity {
|
|
710
|
+
readonly key: "dns";
|
|
711
|
+
listRecords(domain: string): Promise<DnsRecord[]>;
|
|
712
|
+
upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
|
|
713
|
+
deleteRecord(domain: string, id: string): Promise<void>;
|
|
714
|
+
/**
|
|
715
|
+
* A `holocron doctor` smoke check with no specific domain to ask about —
|
|
716
|
+
* `listRecords` needs one, but doctor doesn't have one on hand. Verifies
|
|
717
|
+
* the token and reports how many zones it can see.
|
|
718
|
+
*/
|
|
719
|
+
whoami?(): Promise<{
|
|
720
|
+
ok: boolean;
|
|
721
|
+
zones: number;
|
|
722
|
+
}>;
|
|
723
|
+
}
|
|
724
|
+
interface Errors extends ProviderIdentity {
|
|
725
|
+
readonly key: "errors";
|
|
726
|
+
/** Returns the env var names the app reads at runtime for this provider. */
|
|
727
|
+
describe(): Promise<{
|
|
728
|
+
provider: string;
|
|
729
|
+
envKeys: string[];
|
|
730
|
+
}>;
|
|
731
|
+
/**
|
|
732
|
+
* Reachability probe. `null` means the check genuinely can't run right
|
|
733
|
+
* now on an otherwise-valid configuration (e.g. Sentry's optional `org`
|
|
734
|
+
* setting is unset — error ingestion still works from the DSN alone,
|
|
735
|
+
* `org` is only needed for the management-API calls `whoami` makes) —
|
|
736
|
+
* callers should fall back to `describe()`, not treat it as a failure.
|
|
737
|
+
* Still throws for a genuine failure (bad token, network error, etc.).
|
|
738
|
+
*/
|
|
739
|
+
whoami?(): Promise<{
|
|
740
|
+
org: string;
|
|
741
|
+
} | null>;
|
|
742
|
+
ensureProject?(input: {
|
|
743
|
+
name: string;
|
|
744
|
+
platform?: string;
|
|
745
|
+
}): Promise<{
|
|
746
|
+
dsn: string;
|
|
747
|
+
alreadyExists: boolean;
|
|
748
|
+
}>;
|
|
749
|
+
/**
|
|
750
|
+
* Make the tracker send its alerts to a relay (the Comlink Worker): an integration that posts to `webhookUrl`, and
|
|
751
|
+
* an alert rule on each project that uses it. Idempotent: an integration or rule with the same name is adopted and
|
|
752
|
+
* only what differs is changed. `clientSecret` is the integration's signing secret, handed to the caller to give
|
|
753
|
+
* the relay; it is a credential and must not be printed or stored anywhere but there. It is absent when the
|
|
754
|
+
* provider did not give it (some show it only when the integration is made).
|
|
755
|
+
*/
|
|
756
|
+
ensureRelay?(input: EnsureRelayInput): Promise<EnsureRelayResult>;
|
|
757
|
+
}
|
|
758
|
+
interface EnsureRelayInput {
|
|
759
|
+
/** The integration's name at the provider (also how an existing one is found). */
|
|
760
|
+
name: string;
|
|
761
|
+
/** Where the provider posts its alerts, e.g. `https://comlink.theholocron.dev/sentry`. */
|
|
762
|
+
webhookUrl: string;
|
|
763
|
+
/** The projects whose issues are sent. */
|
|
764
|
+
projects: string[];
|
|
765
|
+
/** The alert rule: its name, and the minutes between two notifications for one issue (default 5). */
|
|
766
|
+
rule: {
|
|
767
|
+
name: string;
|
|
768
|
+
frequency?: number;
|
|
769
|
+
};
|
|
770
|
+
}
|
|
771
|
+
interface EnsureRelayResult {
|
|
772
|
+
integration: {
|
|
773
|
+
created: boolean;
|
|
774
|
+
updated: string[];
|
|
775
|
+
};
|
|
776
|
+
rule: {
|
|
777
|
+
created: boolean;
|
|
778
|
+
updated: string[];
|
|
779
|
+
};
|
|
780
|
+
clientSecret?: string;
|
|
781
|
+
}
|
|
782
|
+
interface Logs extends ProviderIdentity {
|
|
783
|
+
readonly key: "logs";
|
|
784
|
+
/** Returns the env var names the app reads at runtime for this provider. */
|
|
785
|
+
describe(): Promise<{
|
|
786
|
+
provider: string;
|
|
787
|
+
envKeys: string[];
|
|
788
|
+
}>;
|
|
789
|
+
/** Verify the token by fetching the target dataset's info. */
|
|
790
|
+
whoami?(): Promise<{
|
|
791
|
+
ok: boolean;
|
|
792
|
+
dataset: string;
|
|
793
|
+
}>;
|
|
794
|
+
/** Create the aggregation dataset if it does not already exist. Idempotent. */
|
|
795
|
+
ensureDataset?(name: string): Promise<{
|
|
796
|
+
alreadyExists: boolean;
|
|
797
|
+
}>;
|
|
798
|
+
}
|
|
799
|
+
type MonitoringAssertionSource = "status_code" | "response_time" | "body" | "header";
|
|
800
|
+
type MonitoringAssertionComparison = "equals" | "not_equals" | "contains" | "not_contains" | "greater_than" | "less_than";
|
|
801
|
+
interface MonitoringAssertion {
|
|
802
|
+
source: MonitoringAssertionSource;
|
|
803
|
+
comparison: MonitoringAssertionComparison;
|
|
804
|
+
/** Header name / JSON path — required when `source` needs one (e.g. `"header"`). */
|
|
805
|
+
property?: string;
|
|
806
|
+
target?: string;
|
|
807
|
+
}
|
|
808
|
+
type MonitoringHttpMethod = "GET" | "POST" | "PUT" | "HEAD" | "DELETE" | "PATCH";
|
|
809
|
+
interface MonitoringCheckInput {
|
|
810
|
+
/** Also the idempotency key — `ensureCheck` finds-or-creates by this name. */
|
|
811
|
+
name: string;
|
|
812
|
+
url: string;
|
|
813
|
+
method?: MonitoringHttpMethod;
|
|
814
|
+
/** Minutes between runs. Adapters round to their own supported values. */
|
|
815
|
+
frequency?: number;
|
|
816
|
+
assertions?: MonitoringAssertion[];
|
|
817
|
+
activated?: boolean;
|
|
818
|
+
/**
|
|
819
|
+
* Provider-specific region/datacenter ids to run the check from (e.g.
|
|
820
|
+
* Checkly's `"us-east-1"`). Required by some providers — there's no
|
|
821
|
+
* universal default; an account with none configured rejects a check
|
|
822
|
+
* that omits this entirely.
|
|
823
|
+
*/
|
|
824
|
+
locations?: string[];
|
|
825
|
+
/**
|
|
826
|
+
* Inverts pass/fail: set this when the check's expected-healthy
|
|
827
|
+
* response is itself an HTTP error status (e.g. asserting a 404/405
|
|
828
|
+
* on an endpoint that should reject certain requests). Without it,
|
|
829
|
+
* most providers classify any 4xx/5xx response as a failure at the
|
|
830
|
+
* platform level *before* evaluating `assertions` at all — a custom
|
|
831
|
+
* assertion that matches the "expected" error status does not
|
|
832
|
+
* override that baseline classification on its own.
|
|
833
|
+
*/
|
|
834
|
+
shouldFail?: boolean;
|
|
835
|
+
/**
|
|
836
|
+
* Raw request body to send with the check — e.g. simulating a webhook
|
|
837
|
+
* delivery to verify signature/auth checking is wired correctly
|
|
838
|
+
* end-to-end, rather than just confirming the endpoint is reachable.
|
|
839
|
+
* Omitted entirely by default (no body sent).
|
|
840
|
+
*/
|
|
841
|
+
body?: string;
|
|
842
|
+
}
|
|
843
|
+
interface MonitoringCheck {
|
|
844
|
+
id: string;
|
|
845
|
+
name: string;
|
|
846
|
+
}
|
|
847
|
+
/** A place the monitoring provider sends its alerts: a webhook that posts into a chat channel. */
|
|
848
|
+
interface MonitoringAlertChannelInput {
|
|
849
|
+
/** Also the idempotency key: an existing channel with this name is adopted and brought in line. */
|
|
850
|
+
name: string;
|
|
851
|
+
/** The chat service the message is formatted for. */
|
|
852
|
+
format: "discord";
|
|
853
|
+
/**
|
|
854
|
+
* Where alerts post: a credential, because anyone holding it can post to the channel. Absent when the webhook already
|
|
855
|
+
* existed and cannot be read back, in which case an existing alert channel keeps the URL it has and a missing one
|
|
856
|
+
* cannot be created.
|
|
857
|
+
*/
|
|
858
|
+
url?: string;
|
|
859
|
+
}
|
|
860
|
+
interface MonitoringAlertChannelResult {
|
|
861
|
+
created: boolean;
|
|
862
|
+
/** For an existing channel, what was brought in line (`"url"`, `"subscriptions"`). */
|
|
863
|
+
updated: string[];
|
|
864
|
+
/** How many checks the channel is subscribed to afterwards. */
|
|
865
|
+
subscribed: number;
|
|
866
|
+
}
|
|
867
|
+
interface Monitoring extends ProviderIdentity {
|
|
868
|
+
readonly key: "monitoring";
|
|
869
|
+
/**
|
|
870
|
+
* Checks this provider is configured to ensure exist — populated from
|
|
871
|
+
* the provider's own config (`holocron.config.ts`'s provider tuple),
|
|
872
|
+
* the same place `Deployment.domain` comes from. `holocron repo setup`
|
|
873
|
+
* loops this list and calls `ensureCheck` for each; empty when none
|
|
874
|
+
* are configured.
|
|
875
|
+
*/
|
|
876
|
+
readonly checks: readonly MonitoringCheckInput[];
|
|
877
|
+
/**
|
|
878
|
+
* The service's own picture, for the webhook it posts through (see `feeds.monitoring`): where to fetch it, and the
|
|
879
|
+
* image itself as a `data:` URI for when that cannot be reached. Used when the config names no picture of its own.
|
|
880
|
+
*/
|
|
881
|
+
readonly icon?: {
|
|
882
|
+
url?: string;
|
|
883
|
+
dataUri?: string;
|
|
884
|
+
};
|
|
885
|
+
/** Auth sanity-check. Throws ProviderApiError on auth failure. */
|
|
886
|
+
whoami?(): Promise<{
|
|
887
|
+
ok: boolean;
|
|
888
|
+
}>;
|
|
889
|
+
/** Idempotent find-or-create-or-update by `input.name`. */
|
|
890
|
+
ensureCheck(input: MonitoringCheckInput): Promise<{
|
|
891
|
+
check: MonitoringCheck;
|
|
892
|
+
alreadyExists: boolean;
|
|
893
|
+
}>;
|
|
894
|
+
/**
|
|
895
|
+
* Find-or-create-or-update an alert channel by name and subscribe every check the provider has to it. Checks made
|
|
896
|
+
* through an API are never subscribed automatically, so a later run subscribes the ones added since.
|
|
897
|
+
* Optional — a provider with no alert channels omits it.
|
|
898
|
+
*/
|
|
899
|
+
ensureAlertChannel?(input: MonitoringAlertChannelInput): Promise<MonitoringAlertChannelResult>;
|
|
900
|
+
}
|
|
901
|
+
interface ToolingDoctorReport {
|
|
902
|
+
ok: boolean;
|
|
903
|
+
message: string;
|
|
904
|
+
}
|
|
905
|
+
interface Tooling extends ProviderIdentity {
|
|
906
|
+
readonly key: "tooling";
|
|
907
|
+
/** Sync the tool's authoritative state from the repo. */
|
|
908
|
+
sync(): Promise<void>;
|
|
909
|
+
doctor(): Promise<ToolingDoctorReport>;
|
|
910
|
+
}
|
|
911
|
+
/** What an `ensure*` call found or made. `created: false` means it already existed. */
|
|
912
|
+
interface EnsuredResource {
|
|
913
|
+
id: string;
|
|
914
|
+
created: boolean;
|
|
915
|
+
/** For something that already existed: the settings that disagreed with the layout and were changed. */
|
|
916
|
+
updated?: string[];
|
|
917
|
+
}
|
|
918
|
+
/** A webhook (or equivalent inbound URL) for a channel. */
|
|
919
|
+
interface EnsureWebhookResult {
|
|
920
|
+
created: boolean;
|
|
921
|
+
/**
|
|
922
|
+
* The posting URL — a credential. Absent when the webhook already existed and
|
|
923
|
+
* the provider will not reveal it again (Discord returns the token only to
|
|
924
|
+
* the application that created the webhook, and only on creation).
|
|
925
|
+
*/
|
|
926
|
+
url?: string;
|
|
927
|
+
/** For a webhook that already existed, or was just made: the settings that were set (`"avatar"`). */
|
|
928
|
+
updated?: string[];
|
|
929
|
+
/** Set when the webhook is fine but setting its avatar failed; the webhook and its `url` are still good. */
|
|
930
|
+
avatarError?: string;
|
|
931
|
+
}
|
|
932
|
+
/**
|
|
933
|
+
* Who may see a channel and post in it. Roles are named as in the layout's `roles`.
|
|
934
|
+
* A channel inherits its category's access; stating `view` or `post` on the channel
|
|
935
|
+
* replaces that field only.
|
|
936
|
+
*/
|
|
937
|
+
interface NotificationsAccess {
|
|
938
|
+
/** `"everyone"` (the default), or the roles that can see it: everyone else cannot. */
|
|
939
|
+
view?: "everyone" | string[];
|
|
940
|
+
/** `"everyone"` (the default), or the roles that can post; `[]` means only bots and webhooks. */
|
|
941
|
+
post?: "everyone" | string[];
|
|
942
|
+
}
|
|
943
|
+
/** One channel in a {@link NotificationsLayout}. */
|
|
944
|
+
interface NotificationsChannelLayout {
|
|
945
|
+
name: string;
|
|
946
|
+
topic?: string;
|
|
947
|
+
/** Who may see and post. Overrides the category's, field by field. */
|
|
948
|
+
access?: NotificationsAccess;
|
|
949
|
+
/**
|
|
950
|
+
* Create an inbound webhook for the channel and store its URL in a secret.
|
|
951
|
+
* `true` uses the defaults; the object form overrides the webhook's display
|
|
952
|
+
* name and the secret's name.
|
|
953
|
+
*/
|
|
954
|
+
webhook?: boolean | {
|
|
955
|
+
name?: string;
|
|
956
|
+
secret?: string;
|
|
957
|
+
avatar?: string;
|
|
958
|
+
};
|
|
959
|
+
/**
|
|
960
|
+
* Other services that post into this channel through a webhook of their own. Each gets a dedicated webhook, whose
|
|
961
|
+
* URL goes straight to that service and is never stored as a secret, so revoking one service leaves the rest alone.
|
|
962
|
+
*/
|
|
963
|
+
feeds?: {
|
|
964
|
+
/**
|
|
965
|
+
* The monitoring provider's alerts. `true` uses the defaults; the object form overrides the alert channel's name
|
|
966
|
+
* (default `Message to #<channel>`) and the dedicated webhook's name (default the provider's name, capitalised), and
|
|
967
|
+
* `avatar` gives that webhook a picture (PNG, JPEG or GIF): a file path or `https://` URL, or `{ url, image }`, where the `url` is tried first and the `image`, a file in the repo, is the fallback) in the provider's list of
|
|
968
|
+
* integrations. Left out, it wears the layout's `webhookAvatar`, as every webhook does. A picture is set only on a
|
|
969
|
+
* webhook that has none; the posts carry the service's own name and icon either way.
|
|
970
|
+
*/
|
|
971
|
+
monitoring?: boolean | {
|
|
972
|
+
name?: string;
|
|
973
|
+
webhook?: string;
|
|
974
|
+
avatar?: string | {
|
|
975
|
+
url?: string;
|
|
976
|
+
image?: string;
|
|
977
|
+
};
|
|
978
|
+
};
|
|
979
|
+
/**
|
|
980
|
+
* The error tracker's alerts, carried in by the relay Worker (see `relay`). The channel gets a dedicated webhook
|
|
981
|
+
* (default the `errors` provider's name, capitalised) whose URL goes to the Worker as a secret and nowhere else.
|
|
982
|
+
* `avatar` is as for `monitoring`.
|
|
983
|
+
*/
|
|
984
|
+
errors?: boolean | {
|
|
985
|
+
webhook?: string;
|
|
986
|
+
avatar?: string | {
|
|
987
|
+
url?: string;
|
|
988
|
+
image?: string;
|
|
989
|
+
};
|
|
990
|
+
};
|
|
991
|
+
};
|
|
992
|
+
}
|
|
993
|
+
/**
|
|
994
|
+
* Settings of the server itself. Channels are named as in the layout's `categories`; each field
|
|
995
|
+
* left out is left alone.
|
|
996
|
+
*/
|
|
997
|
+
interface NotificationsServerLayout {
|
|
998
|
+
/** How established an account must be to talk: `none`, `low` (verified email), `medium` (5 minutes old), `high` (10 minutes in the server), `highest` (verified phone). */
|
|
999
|
+
verification?: "none" | "low" | "medium" | "high" | "highest";
|
|
1000
|
+
/** Whether members are notified for every message or only when mentioned. */
|
|
1001
|
+
defaultNotifications?: "all" | "mentions";
|
|
1002
|
+
/** Which members' media is scanned: `off`, `noRoles` (members without a role) or `all`. */
|
|
1003
|
+
contentFilter?: "off" | "noRoles" | "all";
|
|
1004
|
+
/** Where the provider posts its own notices (member joins, boosts). */
|
|
1005
|
+
systemChannel?: string;
|
|
1006
|
+
/** The channel holding the server rules; required to turn community features on. */
|
|
1007
|
+
rulesChannel?: string;
|
|
1008
|
+
/** Where the provider sends its notices to the owners; required to turn community features on. */
|
|
1009
|
+
updatesChannel?: string;
|
|
1010
|
+
/** Turn community features (welcome screen, onboarding, discovery) on or off. */
|
|
1011
|
+
community?: boolean;
|
|
1012
|
+
/** The server's public description. Only providers that support one for the server's current state accept it. */
|
|
1013
|
+
description?: string;
|
|
1014
|
+
/** Preferred language, as a locale such as `en-US`. */
|
|
1015
|
+
locale?: string;
|
|
1016
|
+
}
|
|
1017
|
+
/** A message the provider posts in a channel and pins, so it stays at the top. */
|
|
1018
|
+
interface NotificationsPinnedLayout {
|
|
1019
|
+
/** A channel in the layout. */
|
|
1020
|
+
channel: string;
|
|
1021
|
+
/** The message text (Discord allows up to 2000 characters). */
|
|
1022
|
+
content: string;
|
|
1023
|
+
}
|
|
1024
|
+
/**
|
|
1025
|
+
* The screen a new member sees on joining: a short text and the channels worth visiting first.
|
|
1026
|
+
* Declaring it describes the whole screen: the text and the channels are set to exactly this, so to
|
|
1027
|
+
* switch it off, state them as well.
|
|
1028
|
+
*/
|
|
1029
|
+
interface NotificationsWelcomeLayout {
|
|
1030
|
+
/** Whether the screen is shown. Defaults to `true`. */
|
|
1031
|
+
enabled?: boolean;
|
|
1032
|
+
/** A sentence or two about the server (Discord allows up to 140 characters). */
|
|
1033
|
+
description: string;
|
|
1034
|
+
/** The channels it points to, in order (Discord allows up to five). */
|
|
1035
|
+
channels: Array<{
|
|
1036
|
+
/** A channel in the layout. */
|
|
1037
|
+
channel: string;
|
|
1038
|
+
/** Why to visit it (Discord allows up to 50 characters). */
|
|
1039
|
+
description: string;
|
|
1040
|
+
/** A single emoji shown beside it. */
|
|
1041
|
+
emoji?: string;
|
|
1042
|
+
}>;
|
|
1043
|
+
}
|
|
1044
|
+
/** The questions a new member answers to be shown the channels that fit them. */
|
|
1045
|
+
interface NotificationsOnboardingLayout {
|
|
1046
|
+
/** Turn onboarding on or off. Left out, it is left as it is (Discord has requirements for turning it on). */
|
|
1047
|
+
enabled?: boolean;
|
|
1048
|
+
/** Channels every member starts with, by name. */
|
|
1049
|
+
defaultChannels?: string[];
|
|
1050
|
+
prompts?: Array<{
|
|
1051
|
+
title: string;
|
|
1052
|
+
/** One answer only (`true`) or any number. Defaults to `false`. */
|
|
1053
|
+
singleSelect?: boolean;
|
|
1054
|
+
/** The member must answer. Defaults to `false`. */
|
|
1055
|
+
required?: boolean;
|
|
1056
|
+
options: Array<{
|
|
1057
|
+
title: string;
|
|
1058
|
+
description?: string;
|
|
1059
|
+
emoji?: string;
|
|
1060
|
+
/** Channels this answer shows, by name. */
|
|
1061
|
+
channels?: string[];
|
|
1062
|
+
/** Roles this answer gives, by name from the layout's `roles`. */
|
|
1063
|
+
roles?: string[];
|
|
1064
|
+
}>;
|
|
1065
|
+
}>;
|
|
1066
|
+
}
|
|
1067
|
+
/**
|
|
1068
|
+
* Settings of the bot's own application (for Discord, what the developer portal shows). A field left
|
|
1069
|
+
* out is left alone.
|
|
1070
|
+
*/
|
|
1071
|
+
interface NotificationsApplicationLayout {
|
|
1072
|
+
/** What the application's page says it is (Discord allows up to 400 characters). */
|
|
1073
|
+
description?: string;
|
|
1074
|
+
/** Short labels, up to five of up to twenty characters each. */
|
|
1075
|
+
tags?: string[];
|
|
1076
|
+
/** The default install link: what the bot is added with. Permissions are named, as in a role's. */
|
|
1077
|
+
install?: {
|
|
1078
|
+
scopes: string[];
|
|
1079
|
+
permissions: string[];
|
|
1080
|
+
};
|
|
1081
|
+
/** `https://` link to the terms of service. */
|
|
1082
|
+
termsUrl?: string;
|
|
1083
|
+
/** `https://` link to the privacy policy. */
|
|
1084
|
+
privacyUrl?: string;
|
|
1085
|
+
/** `https://` link the provider calls to verify linked roles. */
|
|
1086
|
+
roleConnectionsUrl?: string;
|
|
1087
|
+
/**
|
|
1088
|
+
* Privileged intents the bot needs. `members` lets it list who is in the server, which `sync-roles` needs to
|
|
1089
|
+
* find who holds a role. `true` switches it on from code; `false` switches it off.
|
|
1090
|
+
*/
|
|
1091
|
+
intents?: {
|
|
1092
|
+
members?: boolean;
|
|
1093
|
+
};
|
|
1094
|
+
/**
|
|
1095
|
+
* OAuth2 redirect URIs that must be registered, for `notifications link`. The provider's API does not allow
|
|
1096
|
+
* setting them, so these are only checked: `setup` and the doctor say what to add and where.
|
|
1097
|
+
*/
|
|
1098
|
+
redirectUris?: string[];
|
|
1099
|
+
}
|
|
1100
|
+
/**
|
|
1101
|
+
* Permissions of everyone on the server (for Discord, the @everyone role). Unlike a role's `permissions`,
|
|
1102
|
+
* these name only what to change: the rest of the set is left as it is.
|
|
1103
|
+
*/
|
|
1104
|
+
interface NotificationsEveryoneLayout {
|
|
1105
|
+
/** Permissions to grant. */
|
|
1106
|
+
allow?: string[];
|
|
1107
|
+
/** Permissions to take away. */
|
|
1108
|
+
deny?: string[];
|
|
1109
|
+
}
|
|
1110
|
+
/** Where the person-to-member links live: one file in a repo, written by the sign-in flow and read by `sync-roles`. */
|
|
1111
|
+
interface NotificationsLinksLayout {
|
|
1112
|
+
/**
|
|
1113
|
+
* The base URL of the hosted sign-in service (Sentinel), for example `https://sentinel.theholocron.dev`.
|
|
1114
|
+
* `notifications link` asks it for `/api/link`; when it answers, sign-in happens there, and when it does not
|
|
1115
|
+
* (down, out of quota, no route yet) the command signs in on this machine instead.
|
|
1116
|
+
*/
|
|
1117
|
+
hostedUrl?: string;
|
|
1118
|
+
/** The port the local sign-in listens on, which must be registered as `http://localhost:<port>/callback`. Defaults to 53682. */
|
|
1119
|
+
localPort?: number;
|
|
1120
|
+
/** `owner/name`. Defaults to `<org>/.github-private`. Keep it private: the file pairs two identities. */
|
|
1121
|
+
repo?: string;
|
|
1122
|
+
/** Defaults to `notifications/<provider>-links.json`. */
|
|
1123
|
+
path?: string;
|
|
1124
|
+
}
|
|
1125
|
+
/** A declared server layout, applied idempotently by `holocron notifications setup`. */
|
|
1126
|
+
interface NotificationsLayout {
|
|
1127
|
+
/**
|
|
1128
|
+
* The channel set aside for test posts, by name. It must declare a webhook. `holocron doctor notifications`
|
|
1129
|
+
* leaves one labelled test message there through its webhook (read back to prove delivery works) for a
|
|
1130
|
+
* person to look at; the real channels are never given one unless `--deliver` posts and removes it.
|
|
1131
|
+
*/
|
|
1132
|
+
testChannel?: string;
|
|
1133
|
+
/** Where `sync-roles` finds which server member is which GitHub account. Only used by roles with a `team`. */
|
|
1134
|
+
links?: NotificationsLinksLayout;
|
|
1135
|
+
/** The bot's own application settings, applied with the server's. */
|
|
1136
|
+
application?: NotificationsApplicationLayout;
|
|
1137
|
+
/** What everyone on the server may do, applied with the server's settings. */
|
|
1138
|
+
everyone?: NotificationsEveryoneLayout;
|
|
1139
|
+
/**
|
|
1140
|
+
* The picture every webhook gets unless its own `webhook.avatar` says otherwise: a path to a PNG,
|
|
1141
|
+
* JPEG or GIF (from where the CLI runs) or an `https://` URL. It is set only on a webhook that has
|
|
1142
|
+
* no picture yet -- a provider cannot say whether the one it holds is the same image.
|
|
1143
|
+
*/
|
|
1144
|
+
webhookAvatar?: string;
|
|
1145
|
+
/**
|
|
1146
|
+
* The Worker that carries other services' alerts into the channels with a `feeds.errors`: built beforehand
|
|
1147
|
+
* (`apps/comlink`), deployed by `notifications setup` with each channel's webhook URL as a secret, and served at
|
|
1148
|
+
* `host`. Secrets set some other way (the service's signing secret) are kept across deploys.
|
|
1149
|
+
*/
|
|
1150
|
+
relay?: {
|
|
1151
|
+
/** Where the Worker answers, e.g. `comlink.theholocron.dev`. Its DNS record and route are managed. */
|
|
1152
|
+
host: string;
|
|
1153
|
+
/** The DNS zone the host is in. Default: found by the `dns` provider from the host itself, so rarely needed. */
|
|
1154
|
+
zone?: string;
|
|
1155
|
+
/** The Worker's name at the provider. Default `comlink`. */
|
|
1156
|
+
script?: string;
|
|
1157
|
+
/** The built Worker, relative to the repo root. Default `apps/comlink/dist/worker.js`. */
|
|
1158
|
+
code?: string;
|
|
1159
|
+
/**
|
|
1160
|
+
* The error tracker's side, when its provider can manage it (`Errors.ensureRelay`): the projects whose issues
|
|
1161
|
+
* are sent, the integration's name (default `Comlink`) and the alert rule's name (default
|
|
1162
|
+
* `Errors to Discord (Comlink)`) and throttle in minutes (default 5). Left out, nothing is done at the tracker.
|
|
1163
|
+
*/
|
|
1164
|
+
errors?: {
|
|
1165
|
+
projects: string[];
|
|
1166
|
+
integration?: string;
|
|
1167
|
+
rule?: string;
|
|
1168
|
+
frequency?: number;
|
|
1169
|
+
};
|
|
1170
|
+
};
|
|
1171
|
+
/** What a new member sees on joining, applied after the channels exist. */
|
|
1172
|
+
welcome?: NotificationsWelcomeLayout;
|
|
1173
|
+
/** The questions a new member answers, applied after the channels and roles exist. */
|
|
1174
|
+
onboarding?: NotificationsOnboardingLayout;
|
|
1175
|
+
/**
|
|
1176
|
+
* Messages the provider posts and pins, applied after the channels exist. One that already says exactly this
|
|
1177
|
+
* (posted by the provider and still pinned) is left alone; one that says something else is replaced.
|
|
1178
|
+
*/
|
|
1179
|
+
pinned?: NotificationsPinnedLayout[];
|
|
1180
|
+
/** Settings of the server itself, applied after its channels exist. */
|
|
1181
|
+
server?: NotificationsServerLayout;
|
|
1182
|
+
categories?: Array<{
|
|
1183
|
+
name: string;
|
|
1184
|
+
access?: NotificationsAccess;
|
|
1185
|
+
channels?: NotificationsChannelLayout[];
|
|
1186
|
+
}>;
|
|
1187
|
+
roles?: Array<{
|
|
1188
|
+
name: string;
|
|
1189
|
+
mentionable?: boolean;
|
|
1190
|
+
/** `#rrggbb`. Omit to leave the colour alone. */
|
|
1191
|
+
color?: string;
|
|
1192
|
+
/** Show the role's members as their own group in the member list. */
|
|
1193
|
+
hoist?: boolean;
|
|
1194
|
+
/**
|
|
1195
|
+
* The permissions the role holds, by the provider's own names (for Discord, `ViewChannel`,
|
|
1196
|
+
* `SendMessages`, …). The list is exact: a permission not named is not granted.
|
|
1197
|
+
*/
|
|
1198
|
+
permissions?: string[];
|
|
1199
|
+
/**
|
|
1200
|
+
* Keep this role's members equal to a team of the `source` provider (for GitHub, a team slug in
|
|
1201
|
+
* the org): `holocron notifications sync-roles` gives the role to every team member who has linked
|
|
1202
|
+
* their account, and takes it from linked people who have left the team.
|
|
1203
|
+
*/
|
|
1204
|
+
team?: string;
|
|
1205
|
+
/**
|
|
1206
|
+
* Store the role's id in this secret, so a workflow can ping the role
|
|
1207
|
+
* without anyone copying the id by hand. The id is not sensitive; a secret
|
|
1208
|
+
* is used because the same token that writes the webhook secrets can write
|
|
1209
|
+
* it, with no extra permission.
|
|
1210
|
+
*/
|
|
1211
|
+
secret?: string;
|
|
1212
|
+
}>;
|
|
1213
|
+
}
|
|
1214
|
+
/**
|
|
1215
|
+
* What a provider found on the server, limited to what a {@link NotificationsLayout}
|
|
1216
|
+
* asks about. Read-only: this is what `holocron doctor notifications` compares the
|
|
1217
|
+
* layout against.
|
|
1218
|
+
*/
|
|
1219
|
+
interface ServerInspection {
|
|
1220
|
+
/** The bot's application as the provider has it, in the layout's terms, when the layout declares `application`. */
|
|
1221
|
+
application?: NotificationsApplicationLayout;
|
|
1222
|
+
/** Set when reading the application failed; `application` is then absent and means nothing. */
|
|
1223
|
+
applicationError?: string;
|
|
1224
|
+
/** What everyone may do, by permission name, when the layout declares `everyone`. */
|
|
1225
|
+
everyone?: {
|
|
1226
|
+
permissions: string[];
|
|
1227
|
+
};
|
|
1228
|
+
/** Set when reading everyone's permissions failed; `everyone` is then absent and means nothing. */
|
|
1229
|
+
everyoneError?: string;
|
|
1230
|
+
/** The welcome screen as the server has it, in the layout's terms, when the layout declares `welcome`. */
|
|
1231
|
+
welcome?: NotificationsWelcomeLayout;
|
|
1232
|
+
/** Set when reading the welcome screen failed; `welcome` is then absent and means nothing. */
|
|
1233
|
+
welcomeError?: string;
|
|
1234
|
+
/** Whether each pinned message the layout declares is in place, in the layout's order. */
|
|
1235
|
+
pinned?: Array<{
|
|
1236
|
+
channel: string;
|
|
1237
|
+
state: "ok" | "missing" | "different";
|
|
1238
|
+
}>;
|
|
1239
|
+
/** Set when reading the pinned messages failed; `pinned` is then absent and means nothing. */
|
|
1240
|
+
pinnedError?: string;
|
|
1241
|
+
/** Onboarding as the server has it, in the layout's terms, when the layout declares `onboarding`. */
|
|
1242
|
+
onboarding?: NotificationsOnboardingLayout;
|
|
1243
|
+
/** Set when reading onboarding failed; `onboarding` is then absent and means nothing. */
|
|
1244
|
+
onboardingError?: string;
|
|
1245
|
+
/** The server's own settings, in the layout's terms, when the layout declares `server`. */
|
|
1246
|
+
server?: NotificationsServerLayout;
|
|
1247
|
+
/** Set when reading the server's settings failed; `server` is then absent and means nothing. */
|
|
1248
|
+
serverError?: string;
|
|
1249
|
+
categories: string[];
|
|
1250
|
+
/**
|
|
1251
|
+
* Who can see and post in each category. `"custom"` means its overwrites are not an access the layout
|
|
1252
|
+
* can state (a role-specific deny, a member overwrite, only some of the posting permissions).
|
|
1253
|
+
*/
|
|
1254
|
+
categoryAccess?: Record<string, Required<NotificationsAccess> | "custom">;
|
|
1255
|
+
channels: Array<{
|
|
1256
|
+
name: string;
|
|
1257
|
+
/** The category it sits under, if any. */
|
|
1258
|
+
category?: string;
|
|
1259
|
+
topic?: string;
|
|
1260
|
+
/** Names of the webhooks on the channel. Only filled in for channels the layout gives a webhook. */
|
|
1261
|
+
webhooks: string[];
|
|
1262
|
+
/** Which of those webhooks have a picture of their own. */
|
|
1263
|
+
webhookAvatars?: string[];
|
|
1264
|
+
/** Set when listing this channel's webhooks failed; `webhooks` is then empty and means nothing. */
|
|
1265
|
+
webhooksError?: string;
|
|
1266
|
+
/** Who can see and post; `"custom"` as for `categoryAccess`. */
|
|
1267
|
+
access?: Required<NotificationsAccess> | "custom";
|
|
1268
|
+
}>;
|
|
1269
|
+
roles: Array<{
|
|
1270
|
+
name: string;
|
|
1271
|
+
id: string;
|
|
1272
|
+
mentionable: boolean;
|
|
1273
|
+
/** `#rrggbb`, or absent for the default colour. */
|
|
1274
|
+
color?: string;
|
|
1275
|
+
hoist?: boolean;
|
|
1276
|
+
permissions?: string[];
|
|
1277
|
+
}>;
|
|
1278
|
+
/** Set when reading the roles failed; `roles` is then empty and means nothing. Not read at all when the layout declares none. */
|
|
1279
|
+
rolesError?: string;
|
|
1280
|
+
}
|
|
1281
|
+
/** Who a member turned out to be after signing in with the provider. */
|
|
1282
|
+
interface NotificationsSignedIn {
|
|
1283
|
+
/** Their id on the provider; for Discord, the user id. */
|
|
1284
|
+
member: string;
|
|
1285
|
+
name?: string;
|
|
1286
|
+
/** The GitHub account the provider has verified they own; absent when they have none linked. */
|
|
1287
|
+
github?: {
|
|
1288
|
+
id: string;
|
|
1289
|
+
login: string;
|
|
1290
|
+
};
|
|
1291
|
+
}
|
|
1292
|
+
/** The provider's "sign in" half: build the page a member opens, then learn who they are from the code it sends back. */
|
|
1293
|
+
interface NotificationsSignIn {
|
|
1294
|
+
authorizeUrl(input: {
|
|
1295
|
+
redirectUri: string;
|
|
1296
|
+
state: string;
|
|
1297
|
+
}): Promise<string>;
|
|
1298
|
+
/** Trades the one-use `code` for who they are, and discards the token it was given. */
|
|
1299
|
+
complete(input: {
|
|
1300
|
+
redirectUri: string;
|
|
1301
|
+
code: string;
|
|
1302
|
+
}): Promise<NotificationsSignedIn>;
|
|
1303
|
+
}
|
|
1304
|
+
/** A member of the server, as {@link Notifications.roleMembers} reports it. */
|
|
1305
|
+
/** What {@link Notifications.checkDelivery} saw: each step that went wrong is named in `problems`. */
|
|
1306
|
+
interface NotificationsDelivery {
|
|
1307
|
+
posted: boolean;
|
|
1308
|
+
readBack: boolean;
|
|
1309
|
+
removed: boolean;
|
|
1310
|
+
/** Set when the message was deliberately left in the channel (`keep`), so `removed` is false on purpose. */
|
|
1311
|
+
kept?: boolean;
|
|
1312
|
+
problems: string[];
|
|
1313
|
+
}
|
|
1314
|
+
interface NotificationsMember {
|
|
1315
|
+
/** The provider's id for them; for Discord, the user id. */
|
|
1316
|
+
id: string;
|
|
1317
|
+
/** A display name for reports; absent when the provider does not give one. */
|
|
1318
|
+
name?: string;
|
|
1319
|
+
}
|
|
1320
|
+
interface Notifications extends ProviderIdentity {
|
|
1321
|
+
readonly key: "notifications";
|
|
1322
|
+
/**
|
|
1323
|
+
* Send a message. `channel` is provider-specific (Slack channel id,
|
|
1324
|
+
* Discord webhook url-name, etc.); adapters resolve from config.
|
|
1325
|
+
*/
|
|
1326
|
+
send(channel: string, message: string): Promise<void>;
|
|
1327
|
+
/**
|
|
1328
|
+
* The server layout the owner declared for this provider, if any. Read by
|
|
1329
|
+
* `holocron notifications setup`; the provider just carries it from its options.
|
|
1330
|
+
*/
|
|
1331
|
+
readonly layout?: NotificationsLayout;
|
|
1332
|
+
/**
|
|
1333
|
+
* Provisioning. All optional, all idempotent (look up by name, create only
|
|
1334
|
+
* what is missing), and all need provider credentials beyond the posting
|
|
1335
|
+
* URL — so a provider that only posts simply omits them.
|
|
1336
|
+
*/
|
|
1337
|
+
ensureCategory?(name: string, opts?: {
|
|
1338
|
+
access?: NotificationsAccess;
|
|
1339
|
+
}): Promise<EnsuredResource>;
|
|
1340
|
+
ensureChannel?(input: {
|
|
1341
|
+
name: string;
|
|
1342
|
+
category?: string;
|
|
1343
|
+
topic?: string;
|
|
1344
|
+
access?: NotificationsAccess;
|
|
1345
|
+
}): Promise<EnsuredResource>;
|
|
1346
|
+
ensureWebhook?(input: {
|
|
1347
|
+
channel: string;
|
|
1348
|
+
name: string;
|
|
1349
|
+
category?: string;
|
|
1350
|
+
/** An image as a `data:` URI, set when the webhook has none. */
|
|
1351
|
+
avatar?: string;
|
|
1352
|
+
}): Promise<EnsureWebhookResult>;
|
|
1353
|
+
/**
|
|
1354
|
+
* Proves a channel's webhook delivers: posts `text` through it, reads the post back from the channel and
|
|
1355
|
+
* removes it again, unless `keep` is true, in which case the post is left in the channel (and the result
|
|
1356
|
+
* has `kept` instead of `removed`). Never throws for a failed step; the result says which one failed.
|
|
1357
|
+
* Posts a visible message, so callers choose the channel with care.
|
|
1358
|
+
*/
|
|
1359
|
+
checkDelivery?(input: {
|
|
1360
|
+
channel: string;
|
|
1361
|
+
name: string;
|
|
1362
|
+
category?: string;
|
|
1363
|
+
/** The message. The provider may format it (Discord renders markdown) and replaces `{channel}` with its link to the channel. */
|
|
1364
|
+
text: string;
|
|
1365
|
+
/** Leave the message in the channel instead of removing it, so a person can see it. */
|
|
1366
|
+
keep?: boolean;
|
|
1367
|
+
}): Promise<NotificationsDelivery>;
|
|
1368
|
+
/**
|
|
1369
|
+
* Creates the server the layout describes, empty, owned by the provider's own bot, and makes it the server
|
|
1370
|
+
* every other call in this run works on. Refuses when the config already names a server unless `force`.
|
|
1371
|
+
*/
|
|
1372
|
+
createServer?(input: {
|
|
1373
|
+
name: string;
|
|
1374
|
+
force?: boolean;
|
|
1375
|
+
}): Promise<{
|
|
1376
|
+
id: string;
|
|
1377
|
+
name: string;
|
|
1378
|
+
}>;
|
|
1379
|
+
/** A single-use link, valid for a day, that lets one person join the server through the named channel. */
|
|
1380
|
+
inviteLink?(channel: string): Promise<string>;
|
|
1381
|
+
/** Whether a person is in the server. */
|
|
1382
|
+
hasMember?(memberId: string): Promise<boolean>;
|
|
1383
|
+
/** Hands the server to a member who has joined, so the bot no longer owns it. */
|
|
1384
|
+
transferServer?(memberId: string): Promise<void>;
|
|
1385
|
+
/** Who owns the server, and whether that is the provider's own bot. */
|
|
1386
|
+
serverOwner?(): Promise<{
|
|
1387
|
+
id: string;
|
|
1388
|
+
isBot: boolean;
|
|
1389
|
+
name?: string;
|
|
1390
|
+
}>;
|
|
1391
|
+
/**
|
|
1392
|
+
* Who holds a role, by the provider's member id. Needs whatever permission the provider asks for to list
|
|
1393
|
+
* members (for Discord, the privileged Server Members Intent). Throws if the role does not exist.
|
|
1394
|
+
*/
|
|
1395
|
+
roleMembers?(roleName: string): Promise<NotificationsMember[]>;
|
|
1396
|
+
/** Give a member the role; one who has it already is left alone. */
|
|
1397
|
+
addRoleMember?(roleName: string, memberId: string): Promise<void>;
|
|
1398
|
+
/** Take the role from a member; one who lacks it is left alone. */
|
|
1399
|
+
removeRoleMember?(roleName: string, memberId: string): Promise<void>;
|
|
1400
|
+
/** Sign-in used to learn which GitHub account a member is. Optional; needs an OAuth client secret. */
|
|
1401
|
+
signIn?(): NotificationsSignIn;
|
|
1402
|
+
ensureRole?(input: {
|
|
1403
|
+
name: string;
|
|
1404
|
+
mentionable?: boolean;
|
|
1405
|
+
color?: string;
|
|
1406
|
+
hoist?: boolean;
|
|
1407
|
+
permissions?: string[];
|
|
1408
|
+
}): Promise<EnsuredResource>;
|
|
1409
|
+
/**
|
|
1410
|
+
* Bring the server's own settings in line with the layout, changing only what differs. Returns the
|
|
1411
|
+
* names of what it changed, empty when the server already matched.
|
|
1412
|
+
*/
|
|
1413
|
+
ensureServer?(settings: NotificationsServerLayout): Promise<{
|
|
1414
|
+
updated: string[];
|
|
1415
|
+
}>;
|
|
1416
|
+
/** Bring the welcome screen in line with the layout, changing only what differs. Returns what it changed. */
|
|
1417
|
+
ensureWelcome?(welcome: NotificationsWelcomeLayout): Promise<{
|
|
1418
|
+
updated: string[];
|
|
1419
|
+
}>;
|
|
1420
|
+
/** Post and pin the layout's messages, replacing any that differ. Returns the channels it changed. */
|
|
1421
|
+
ensurePinned?(pinned: NotificationsPinnedLayout[]): Promise<{
|
|
1422
|
+
updated: string[];
|
|
1423
|
+
}>;
|
|
1424
|
+
/** Whether the bot holds the permission right now (the owner holds every one). Used to prove an elevation was taken back. */
|
|
1425
|
+
holdsPermission?(permission: string): Promise<boolean>;
|
|
1426
|
+
/** Bring onboarding in line with the layout, changing only what differs. Returns what it changed. */
|
|
1427
|
+
ensureOnboarding?(onboarding: NotificationsOnboardingLayout): Promise<{
|
|
1428
|
+
updated: string[];
|
|
1429
|
+
}>;
|
|
1430
|
+
/** Bring the bot's application settings in line with the layout, changing only what differs. Returns what it changed. */
|
|
1431
|
+
ensureApplication?(application: NotificationsApplicationLayout): Promise<{
|
|
1432
|
+
updated: string[];
|
|
1433
|
+
todo?: string[];
|
|
1434
|
+
}>;
|
|
1435
|
+
/** Grant or take away the named permissions from everyone, changing only what differs. Returns what it changed. */
|
|
1436
|
+
ensureEveryone?(everyone: NotificationsEveryoneLayout): Promise<{
|
|
1437
|
+
updated: string[];
|
|
1438
|
+
}>;
|
|
1439
|
+
/**
|
|
1440
|
+
* Before anything is created, prove the credentials can do the parts of the layout that need
|
|
1441
|
+
* more than the rest (for Discord, change the server's settings). Throws with the reason and how
|
|
1442
|
+
* to fix it, so `setup` stops before it leaves a half-applied layout. Not called on a dry run.
|
|
1443
|
+
*/
|
|
1444
|
+
preflight?(layout: NotificationsLayout): Promise<void>;
|
|
1445
|
+
/**
|
|
1446
|
+
* Check the provider-specific parts of the layout (colours, permission names, …) without
|
|
1447
|
+
* touching the server, so `setup` can refuse a bad layout before it creates anything.
|
|
1448
|
+
* Returns the first problem, or `undefined` when the layout is fine.
|
|
1449
|
+
*/
|
|
1450
|
+
validateLayout?(layout: NotificationsLayout): string | undefined;
|
|
1451
|
+
/**
|
|
1452
|
+
* Smoke check for `holocron doctor`: prove the provisioning credentials work
|
|
1453
|
+
* and name what they reach. Returns `null` when there is nothing to check (a
|
|
1454
|
+
* config that only posts has no provisioning credentials), which doctor shows
|
|
1455
|
+
* as "loaded" rather than as a failure. Throws when it is configured to
|
|
1456
|
+
* provision but cannot (missing token, no access).
|
|
1457
|
+
*/
|
|
1458
|
+
whoami?(): Promise<{
|
|
1459
|
+
target: string;
|
|
1460
|
+
} | null>;
|
|
1461
|
+
/**
|
|
1462
|
+
* Read what exists on the server, for the parts the layout cares about, without
|
|
1463
|
+
* changing anything. Backs `holocron doctor notifications`.
|
|
1464
|
+
*/
|
|
1465
|
+
inspect?(layout: NotificationsLayout): Promise<ServerInspection>;
|
|
1466
|
+
}
|
|
1467
|
+
interface Analytics extends ProviderIdentity {
|
|
1468
|
+
readonly key: "analytics";
|
|
1469
|
+
/** Returns the env var names the app reads at runtime for this provider. */
|
|
1470
|
+
describe(): Promise<{
|
|
1471
|
+
provider: string;
|
|
1472
|
+
envKeys: string[];
|
|
1473
|
+
}>;
|
|
1474
|
+
whoami?(): Promise<{
|
|
1475
|
+
org: string;
|
|
1476
|
+
}>;
|
|
1477
|
+
ensureProject?(name: string): Promise<{
|
|
1478
|
+
token: string;
|
|
1479
|
+
alreadyExists: boolean;
|
|
1480
|
+
}>;
|
|
1481
|
+
}
|
|
1482
|
+
interface WikiProvisionOpts {
|
|
1483
|
+
/** Project display name used in the wiki title (e.g. "Holocron"). */
|
|
1484
|
+
name?: string;
|
|
1485
|
+
}
|
|
1486
|
+
/**
|
|
1487
|
+
* Reverse-proxy configuration returned by `Wiki.proxyConfig()`.
|
|
1488
|
+
* Used by `setup` to deploy a Worker that forwards traffic to the wiki
|
|
1489
|
+
* provider's ingress with the required headers injected.
|
|
1490
|
+
*/
|
|
1491
|
+
interface WikiProxyConfig {
|
|
1492
|
+
/** Proxy target URL (e.g. "https://app.buildwithfern.com"). */
|
|
1493
|
+
target: string;
|
|
1494
|
+
/** Headers injected on every proxied request. */
|
|
1495
|
+
headers: Record<string, string>;
|
|
1496
|
+
}
|
|
1497
|
+
/**
|
|
1498
|
+
* Engineering wiki provider.
|
|
1499
|
+
*
|
|
1500
|
+
* A swappable provider for publishing the `docs/decisions/` and
|
|
1501
|
+
* `docs/engineering/` surfaces as a browsable, access-controlled site.
|
|
1502
|
+
* Local-only providers (fern, mintlify) write config files; remote
|
|
1503
|
+
* providers (github) make API calls.
|
|
1504
|
+
*/
|
|
1505
|
+
interface Wiki extends ProviderIdentity {
|
|
1506
|
+
readonly key: "wiki";
|
|
1507
|
+
/** Provision the wiki — write config files or call the provider API. */
|
|
1508
|
+
provision(opts?: WikiProvisionOpts): Promise<string>;
|
|
1509
|
+
/**
|
|
1510
|
+
* DNS record needed for the custom domain, when one is configured.
|
|
1511
|
+
* Returns null when no custom domain is set.
|
|
1512
|
+
* Called by `setup` to provision the CNAME via the `dns` capability.
|
|
1513
|
+
*/
|
|
1514
|
+
dnsRecord?(): DnsRecordRequest | null;
|
|
1515
|
+
/**
|
|
1516
|
+
* Reverse-proxy config when the wiki provider requires a Worker-level
|
|
1517
|
+
* proxy in addition to the CNAME. Returns null when no proxy is needed.
|
|
1518
|
+
* Called by `setup` to deploy the proxy via the `workers` capability.
|
|
1519
|
+
*/
|
|
1520
|
+
proxyConfig?(): WikiProxyConfig | null;
|
|
1521
|
+
/**
|
|
1522
|
+
* Confirms a provider token resolves. Unlike `dns`/`workers`/`monitoring`'s
|
|
1523
|
+
* `whoami()`, this is NOT a live reachability check — Fern (the only
|
|
1524
|
+
* current `wiki` provider) exposes no lightweight endpoint to verify a
|
|
1525
|
+
* token actually works; the only token-consuming operation is a full
|
|
1526
|
+
* `fern generate` (holocron#1079). `ok: true` means "a token was found",
|
|
1527
|
+
* not "the token works".
|
|
1528
|
+
*/
|
|
1529
|
+
whoami?(): Promise<{
|
|
1530
|
+
ok: boolean;
|
|
1531
|
+
}>;
|
|
1532
|
+
}
|
|
1533
|
+
/** Config for `Workers.deployScript()` — an arbitrary Worker, not a generated reverse-proxy. */
|
|
1534
|
+
interface DeployScriptConfig {
|
|
1535
|
+
/** The full Worker script source — a single ES module (`export default { fetch(...) {...} }`). */
|
|
1536
|
+
code: string;
|
|
1537
|
+
/**
|
|
1538
|
+
* Secret bindings — `env.<name>` in the deployed Worker. Values are
|
|
1539
|
+
* write-only; the provider never echoes them back, here or anywhere else.
|
|
1540
|
+
*/
|
|
1541
|
+
secrets?: Record<string, string>;
|
|
1542
|
+
/**
|
|
1543
|
+
* Route pattern(s) this Worker should serve (e.g.
|
|
1544
|
+
* `"sentinel.theholocron.dev/*"`). Omit for a Worker reached only via
|
|
1545
|
+
* its `*.workers.dev` URL.
|
|
1546
|
+
*/
|
|
1547
|
+
routes?: string[];
|
|
1548
|
+
}
|
|
1549
|
+
interface DeployScriptResult {
|
|
1550
|
+
/** The deployed script's name at the provider. */
|
|
1551
|
+
scriptName: string;
|
|
1552
|
+
}
|
|
1553
|
+
/**
|
|
1554
|
+
* Edge Worker management capability.
|
|
1555
|
+
*
|
|
1556
|
+
* Deploys and manages Worker scripts. `upsertProxy` is the existing,
|
|
1557
|
+
* narrower case `setup` uses to wire wiki custom-domain reverse-proxies;
|
|
1558
|
+
* `deployScript` is the general case — any Worker, any code, its own
|
|
1559
|
+
* secrets — for a consumer that isn't a reverse-proxy (a webhook
|
|
1560
|
+
* receiver, for instance).
|
|
1561
|
+
*/
|
|
1562
|
+
interface Workers extends ProviderIdentity {
|
|
1563
|
+
readonly key: "workers";
|
|
1564
|
+
/**
|
|
1565
|
+
* Deploy (or update) a reverse-proxy Worker for `hostname`.
|
|
1566
|
+
* Forwards all `hostname/*` requests to `config.target`, injecting
|
|
1567
|
+
* `config.headers` on each request.
|
|
1568
|
+
*/
|
|
1569
|
+
upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
|
|
1570
|
+
/** Deploy (or update) an arbitrary Worker script, optionally with secrets and routes. */
|
|
1571
|
+
deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
|
|
1572
|
+
/**
|
|
1573
|
+
* Set one secret binding on a script that is already deployed, leaving its code and every other binding alone.
|
|
1574
|
+
* The value is write-only. `holocron secrets sync --worker` uses it to fan a vault out to a Worker.
|
|
1575
|
+
*/
|
|
1576
|
+
setSecret?(script: string, name: string, value: string): Promise<void>;
|
|
1577
|
+
/** The names (never the values) of the secrets bound to a deployed script. `holocron probe` uses it to see what a Worker has. */
|
|
1578
|
+
secretNames?(script: string): Promise<string[]>;
|
|
1579
|
+
/**
|
|
1580
|
+
* A `holocron doctor` smoke check — every other method either mutates or
|
|
1581
|
+
* needs a specific script/zone doctor has no way to supply up front.
|
|
1582
|
+
* Reports how many Worker scripts the token can see.
|
|
1583
|
+
*/
|
|
1584
|
+
whoami?(): Promise<{
|
|
1585
|
+
ok: boolean;
|
|
1586
|
+
scripts: number;
|
|
1587
|
+
}>;
|
|
1588
|
+
}
|
|
1589
|
+
interface CapabilityImpls {
|
|
1590
|
+
source: Source;
|
|
1591
|
+
ci: Ci;
|
|
1592
|
+
secrets: Secrets;
|
|
1593
|
+
environments: Environments;
|
|
1594
|
+
issues: Issues;
|
|
1595
|
+
deployment: Deployment;
|
|
1596
|
+
storage: Storage;
|
|
1597
|
+
auth: Auth;
|
|
1598
|
+
vault: Vault;
|
|
1599
|
+
dns: Dns;
|
|
1600
|
+
tooling: Tooling;
|
|
1601
|
+
notifications: Notifications;
|
|
1602
|
+
analytics: Analytics;
|
|
1603
|
+
errors: Errors;
|
|
1604
|
+
logs: Logs;
|
|
1605
|
+
monitoring: Monitoring;
|
|
1606
|
+
wiki: Wiki;
|
|
1607
|
+
workers: Workers;
|
|
1608
|
+
}
|
|
1609
|
+
type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
|
|
1610
|
+
/** Resolved runtime shape: single → one impl; many → array. */
|
|
1611
|
+
type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
|
|
1612
|
+
declare const CARDINALITY: {
|
|
1613
|
+
readonly source: "single";
|
|
1614
|
+
readonly ci: "single";
|
|
1615
|
+
readonly secrets: "single";
|
|
1616
|
+
readonly environments: "single";
|
|
1617
|
+
readonly issues: "single";
|
|
1618
|
+
readonly deployment: "single";
|
|
1619
|
+
readonly storage: "single";
|
|
1620
|
+
readonly auth: "single";
|
|
1621
|
+
readonly vault: "single";
|
|
1622
|
+
readonly dns: "single";
|
|
1623
|
+
readonly tooling: "many";
|
|
1624
|
+
readonly notifications: "many";
|
|
1625
|
+
readonly analytics: "many";
|
|
1626
|
+
readonly errors: "single";
|
|
1627
|
+
readonly logs: "single";
|
|
1628
|
+
readonly monitoring: "single";
|
|
1629
|
+
readonly wiki: "single";
|
|
1630
|
+
readonly workers: "single";
|
|
1631
|
+
};
|
|
1632
|
+
/**
|
|
1633
|
+
* No capabilities are strictly required — repos without secrets (e.g. org
|
|
1634
|
+
* community health repos) legitimately omit vault. Plugins validate their
|
|
1635
|
+
* own requirements at call time.
|
|
1636
|
+
*/
|
|
1637
|
+
declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
|
|
1638
|
+
/**
|
|
1639
|
+
* A provider could not finish an edit because the bot lacks a permission it should not keep. Carries what a person
|
|
1640
|
+
* needs to give it for one run and take it away again, so `setup` can walk them through it.
|
|
1641
|
+
*/
|
|
1642
|
+
declare class ElevationRequiredError extends Error {
|
|
1643
|
+
readonly elevation: {
|
|
1644
|
+
/** The permission, in the provider's own name for it. */
|
|
1645
|
+
permission: string;
|
|
1646
|
+
/** Where to approve giving it; absent when the provider could not build one. */
|
|
1647
|
+
grantUrl?: string;
|
|
1648
|
+
/** Where to approve taking it away again; absent when the provider could not build one. */
|
|
1649
|
+
revokeUrl?: string;
|
|
1650
|
+
/** A name for the permission a person would recognise, when {@link permission} is the provider's code for it. */
|
|
1651
|
+
label?: string;
|
|
1652
|
+
/** The permission is meant to stay once given: there is nothing to take away afterwards. */
|
|
1653
|
+
keep?: boolean;
|
|
1654
|
+
/** What the edit had already changed before it was refused, so a retry does not hide it from the summary. */
|
|
1655
|
+
applied?: string[];
|
|
1656
|
+
};
|
|
1657
|
+
name: string;
|
|
1658
|
+
constructor(message: string, elevation: {
|
|
1659
|
+
/** The permission, in the provider's own name for it. */
|
|
1660
|
+
permission: string;
|
|
1661
|
+
/** Where to approve giving it; absent when the provider could not build one. */
|
|
1662
|
+
grantUrl?: string;
|
|
1663
|
+
/** Where to approve taking it away again; absent when the provider could not build one. */
|
|
1664
|
+
revokeUrl?: string;
|
|
1665
|
+
/** A name for the permission a person would recognise, when {@link permission} is the provider's code for it. */
|
|
1666
|
+
label?: string;
|
|
1667
|
+
/** The permission is meant to stay once given: there is nothing to take away afterwards. */
|
|
1668
|
+
keep?: boolean;
|
|
1669
|
+
/** What the edit had already changed before it was refused, so a retry does not hide it from the summary. */
|
|
1670
|
+
applied?: string[];
|
|
1671
|
+
}, options?: ErrorOptions);
|
|
1672
|
+
}
|
|
1673
|
+
/**
|
|
1674
|
+
* A provider cannot do a read because it has no token for it. A check that meets this skips with the message instead
|
|
1675
|
+
* of failing: the token is missing, not wrong.
|
|
1676
|
+
*/
|
|
1677
|
+
declare class MissingTokenError extends Error {
|
|
1678
|
+
/** Lets a caller tell this error from any other by name, across package copies. */
|
|
1679
|
+
name: string;
|
|
1680
|
+
}
|
|
1681
|
+
declare class WebhookVerificationError extends Error {
|
|
1682
|
+
name: string;
|
|
1683
|
+
}
|
|
1684
|
+
declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
|
|
1685
|
+
export { LifecycleSlot as $, WikiProvisionOpts as $t, DeploymentProject as A, RepoRef as At, EnsureRelayResult as B, SourceTeamMember as Bt, ConnectionStringOptions as C, NotificationsSignIn as Ct, DeployScriptConfig as D, ParseWebhookInput as Dt, DeployFunctionResult as E, PagesConfig as Et, Dns as F, Secrets as Ft, EnvironmentReviewer as G, TeamPermission as Gt, EnsureWebhookResult as H, Storage as Ht, DnsRecord as I, ServerInspection as It, Issue as J, TrackerDoctorReport as Jt, Environments as K, Tooling as Kt, DnsRecordRequest as L, Source as Lt, DeploymentRecord as M, ResolvedCapability as Mt, DeploymentTarget as N, Ruleset as Nt, DeployScriptResult as O, ProviderIdentity as Ot, DeploymentTrigger as P, SecretScope as Pt, LifecycleResult as Q, Wiki as Qt, DnsRecordType as R, SourceBranch as Rt, CiRunStatus as S, NotificationsServerLayout as St, DeployFunctionConfig as T, NotificationsWelcomeLayout as Tt, EnsuredResource as U, StorageBranch as Ut, EnsureResult as V, StatusCategory as Vt, Environment as W, TeamEntry as Wt, Issues as X, Vault as Xt, IssueSearchFilter as Y, TrackerUser as Yt, LabelDef as Z, WebhookDashboardInfo as Zt, Cardinality as _, NotificationsLayout as _t, REQUIRED_CAPABILITIES as a, MonitoringAssertionComparison as at, CiRun as b, NotificationsOnboardingLayout as bt, Analytics as c, MonitoringCheckInput as ct, AuthEvent as d, Notifications as dt, WikiProxyConfig as en, Logs as et, AuthEventType as f, NotificationsAccess as ft, CapabilityKey as g, NotificationsEveryoneLayout as gt, CapabilityImpls as h, NotificationsDelivery as ht, ProviderApiError as i, MonitoringAssertion as it, DeploymentProjectSettings as j, RepoSettings as jt, Deployment as k, PullRequest as kt, Auth as l, MonitoringHttpMethod as lt, AuthUser as m, NotificationsChannelLayout as mt, ElevationRequiredError as n, MonitoringAlertChannelInput as nt, WebhookVerificationError as o, MonitoringAssertionSource as ot, AuthIdentity as p, NotificationsApplicationLayout as pt, Errors as q, ToolingDoctorReport as qt, MissingTokenError as r, MonitoringAlertChannelResult as rt, isMulti as s, MonitoringCheck as st, CARDINALITY as t, Workers as tn, Monitoring as tt, AuthDescription as u, NormalizedAuthUser as ut, CardinalityFor as v, NotificationsLinksLayout as vt, CreateAuthUserInput as w, NotificationsSignedIn as wt, CiRunFilter as x, NotificationsPinnedLayout as xt, Ci as y, NotificationsMember as yt, EnsureRelayInput as z, SourceFile as zt };
|