@theholocron/cli 5.0.0-alpha.199 → 5.0.0-alpha.200

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, EnsureResult, EnsureWebhookResult, EnsuredResource, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, Monitoring, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsEveryoneLayout, NotificationsLayout, NotificationsOnboardingLayout, NotificationsServerLayout, NotificationsWelcomeLayout, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, ServerInspection, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti } from "./plugin/capabilities.mjs";
+import { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, EnsureResult, EnsureWebhookResult, EnsuredResource, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, Monitoring, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsEveryoneLayout, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, ServerInspection, Source, SourceFile, SourceTeamMember, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti } from "./plugin/capabilities.mjs";
 import { AuthError, RequestOptions, ResolveTokenConfig as ResolveTokenConfig$1, ResolveTokenInput, RestClient, RestClientConfig, createRestClient } from "@theholocron/http-client";
 import { PackageJson } from "@theholocron/pkg-utils";
 import { ConfigFileError } from "@theholocron/datapad";
@@ -789,4 +789,4 @@ declare function missingCapabilities(capabilities: readonly string[]): string[];
  */
 declare function readWorkspacePackageJsons(repoRoot: string, workspacePackages: readonly WorkspacePackage[]): Promise<PackageJsonLike[]>;
 //#endregion
-export { Analytics, type AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, type Capability, type CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, type ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, type ComposedPreset, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, type DeriveProfileInput, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, type DocsConfig, type DoctorConfig, EnsureResult, EnsureWebhookResult, EnsuredResource, type EnvConfig, Environment, EnvironmentReviewer, Environments, Errors, type EslintConfig, type FeatureResolverConfig, type HolocronConfig, type HolocronProfile, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, type LoadedConfig, type LogConfig, Logs, Monitoring, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, type MultiEntry, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsEveryoneLayout, NotificationsLayout, NotificationsOnboardingLayout, NotificationsServerLayout, NotificationsWelcomeLayout, type PackageJsonLike, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, type ProviderOptions, PullRequest, REQUIRED_CAPABILITIES, type RawProviderEntry, type RawProvidersConfig, type RepoConfig, type RepoProperties, type RepoProtection, RepoRef, RepoSettings, type RequestOptions, type ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, type ResolvedHolocronConfig, type ResolvedProviderEntry, type ResolvedProvidersConfig, type ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, ServerInspection, type SingleEntry, Source, StatusCategory, Storage, StorageBranch, type StorybookDeployProject, type TaskEntry, type TaskEntryConfig, TeamEntry, TeamPermission, type TelemetryConfig, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, type WorkflowWithConfig, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
+export { Analytics, type AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, type Capability, type CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, type ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, type ComposedPreset, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, type DeriveProfileInput, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, type DocsConfig, type DoctorConfig, EnsureResult, EnsureWebhookResult, EnsuredResource, type EnvConfig, Environment, EnvironmentReviewer, Environments, Errors, type EslintConfig, type FeatureResolverConfig, type HolocronConfig, type HolocronProfile, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, type LoadedConfig, type LogConfig, Logs, Monitoring, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, type MultiEntry, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsEveryoneLayout, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, type PackageJsonLike, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, type ProviderOptions, PullRequest, REQUIRED_CAPABILITIES, type RawProviderEntry, type RawProvidersConfig, type RepoConfig, type RepoProperties, type RepoProtection, RepoRef, RepoSettings, type RequestOptions, type ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, type ResolvedHolocronConfig, type ResolvedProviderEntry, type ResolvedProvidersConfig, type ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, ServerInspection, type SingleEntry, Source, SourceFile, SourceTeamMember, StatusCategory, Storage, StorageBranch, type StorybookDeployProject, type TaskEntry, type TaskEntryConfig, TeamEntry, TeamPermission, type TelemetryConfig, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, type WorkflowWithConfig, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

package/dist/plugin/capabilities.d.mts

@@ -54,6 +54,19 @@ type TeamEntry = string | {
   slug: string;
   permission: TeamPermission;
 };
+/** A member of a team, as {@link Source.teamMembers} reports it. */
+interface SourceTeamMember {
+  /** The provider's stable id for the person; for GitHub, the numeric user id as a string. */
+  id: string;
+  /** What they are called now. Can change; never use it as a key. */
+  login: string;
+}
+/** A file read by {@link Source.readFile}. */
+interface SourceFile {
+  content: string;
+  /** Opaque; hand it back to {@link Source.writeFile} to replace this exact version. */
+  version: string;
+}
 interface Source extends ProviderIdentity {
   readonly key: "source";
   /** Auth sanity-check. Throws ProviderApiError on auth failure. */
@@ -126,6 +139,29 @@ interface Source extends ProviderIdentity {
    * Optional — providers without a team concept omit this.
    */
   syncTeams?(teams: TeamEntry[]): Promise<string>;
+  /**
+   * The members of a team in `org` (default: the repo's organisation), by the provider's own stable id (for GitHub, the
+   * numeric user id, which survives a rename) and current login.
+   * Optional — providers without a team concept omit this.
+   */
+  teamMembers?(teamSlug: string, org?: string): Promise<SourceTeamMember[]>;
+  /**
+   * Read one file from a repository (default: this one), with the `version` a later {@link writeFile} must
+   * hand back. `null` when the file does not exist.
+   * Optional — providers that cannot read file contents omit this.
+   */
+  readFile?(path: string, repo?: string): Promise<SourceFile | null>;
+  /**
+   * Create or replace one file in a single commit. Pass the `version` {@link readFile} returned when
+   * replacing, and leave it out when creating: a write on top of a version that has since changed is
+   * refused (throws a `ProviderApiError` with status 409 or 422), so two writers cannot overwrite each other.
+   * Optional — providers that cannot write file contents omit this.
+   */
+  writeFile?(path: string, content: string, opts: {
+    message: string;
+    version?: string;
+    repo?: string;
+  }): Promise<void>;
   /**
    * Set the repository description.
    * Optional — providers that don't support setting descriptions omit this.
@@ -872,6 +908,18 @@ interface NotificationsApplicationLayout {
   privacyUrl?: string;
   /** `https://` link the provider calls to verify linked roles. */
   roleConnectionsUrl?: string;
+  /**
+   * Privileged intents the bot needs. `members` lets it list who is in the server, which `sync-roles` needs to
+   * find who holds a role. `true` switches it on from code; `false` switches it off.
+   */
+  intents?: {
+    members?: boolean;
+  };
+  /**
+   * OAuth2 redirect URIs that must be registered, for `notifications link`. The provider's API does not allow
+   * setting them, so these are only checked: `setup` and the doctor say what to add and where.
+   */
+  redirectUris?: string[];
 }
 /**
  * Permissions of everyone on the server (for Discord, the @everyone role). Unlike a role's `permissions`,
@@ -883,8 +931,25 @@ interface NotificationsEveryoneLayout {
   /** Permissions to take away. */
   deny?: string[];
 }
+/** Where the person-to-member links live: one file in a repo, written by the sign-in flow and read by `sync-roles`. */
+interface NotificationsLinksLayout {
+  /**
+   * The base URL of the hosted sign-in service (Sentinel), for example `https://sentinel.theholocron.dev`.
+   * `notifications link` asks it for `/api/link`; when it answers, sign-in happens there, and when it does not
+   * (down, out of quota, no route yet) the command signs in on this machine instead.
+   */
+  hostedUrl?: string;
+  /** The port the local sign-in listens on, which must be registered as `http://localhost:<port>/callback`. Defaults to 53682. */
+  localPort?: number;
+  /** `owner/name`. Defaults to `<org>/.github-private`. Keep it private: the file pairs two identities. */
+  repo?: string;
+  /** Defaults to `notifications/<provider>-links.json`. */
+  path?: string;
+}
 /** A declared server layout, applied idempotently by `holocron notifications setup`. */
 interface NotificationsLayout {
+  /** Where `sync-roles` finds which server member is which GitHub account. Only used by roles with a `team`. */
+  links?: NotificationsLinksLayout;
   /** The bot's own application settings, applied with the server's. */
   application?: NotificationsApplicationLayout;
   /** What everyone on the server may do, applied with the server's settings. */
@@ -918,6 +983,12 @@ interface NotificationsLayout {
      * `SendMessages`, …). The list is exact: a permission not named is not granted.
      */
     permissions?: string[];
+    /**
+     * Keep this role's members equal to a team of the `source` provider (for GitHub, a team slug in
+     * the org): `holocron notifications sync-roles` gives the role to every team member who has linked
+     * their account, and takes it from linked people who have left the team.
+     */
+    team?: string;
     /**
      * Store the role's id in this secret, so a workflow can ping the role
      * without anyone copying the id by hand. The id is not sensitive; a secret
@@ -987,6 +1058,36 @@ interface ServerInspection {
   /** Set when reading the roles failed; `roles` is then empty and means nothing. Not read at all when the layout declares none. */
   rolesError?: string;
 }
+/** Who a member turned out to be after signing in with the provider. */
+interface NotificationsSignedIn {
+  /** Their id on the provider; for Discord, the user id. */
+  member: string;
+  name?: string;
+  /** The GitHub account the provider has verified they own; absent when they have none linked. */
+  github?: {
+    id: string;
+    login: string;
+  };
+}
+/** The provider's "sign in" half: build the page a member opens, then learn who they are from the code it sends back. */
+interface NotificationsSignIn {
+  authorizeUrl(input: {
+    redirectUri: string;
+    state: string;
+  }): Promise<string>;
+  /** Trades the one-use `code` for who they are, and discards the token it was given. */
+  complete(input: {
+    redirectUri: string;
+    code: string;
+  }): Promise<NotificationsSignedIn>;
+}
+/** A member of the server, as {@link Notifications.roleMembers} reports it. */
+interface NotificationsMember {
+  /** The provider's id for them; for Discord, the user id. */
+  id: string;
+  /** A display name for reports; absent when the provider does not give one. */
+  name?: string;
+}
 interface Notifications extends ProviderIdentity {
   readonly key: "notifications";
   /**
@@ -1020,6 +1121,17 @@ interface Notifications extends ProviderIdentity {
     /** An image as a `data:` URI, set when the webhook has none. */
     avatar?: string;
   }): Promise<EnsureWebhookResult>;
+  /**
+   * Who holds a role, by the provider's member id. Needs whatever permission the provider asks for to list
+   * members (for Discord, the privileged Server Members Intent). Throws if the role does not exist.
+   */
+  roleMembers?(roleName: string): Promise<NotificationsMember[]>;
+  /** Give a member the role; one who has it already is left alone. */
+  addRoleMember?(roleName: string, memberId: string): Promise<void>;
+  /** Take the role from a member; one who lacks it is left alone. */
+  removeRoleMember?(roleName: string, memberId: string): Promise<void>;
+  /** Sign-in used to learn which GitHub account a member is. Optional; needs an OAuth client secret. */
+  signIn?(): NotificationsSignIn;
   ensureRole?(input: {
     name: string;
     mentionable?: boolean;
@@ -1045,6 +1157,7 @@ interface Notifications extends ProviderIdentity {
   /** Bring the bot's application settings in line with the layout, changing only what differs. Returns what it changed. */
   ensureApplication?(application: NotificationsApplicationLayout): Promise<{
     updated: string[];
+    todo?: string[];
   }>;
   /** Grant or take away the named permissions from everyone, changing only what differs. Returns what it changed. */
   ensureEveryone?(everyone: NotificationsEveryoneLayout): Promise<{
@@ -1249,4 +1362,4 @@ declare class WebhookVerificationError extends Error {
 }
 declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
 //#endregion
-export { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, EnsureResult, EnsureWebhookResult, EnsuredResource, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, Monitoring, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsEveryoneLayout, NotificationsLayout, NotificationsOnboardingLayout, NotificationsServerLayout, NotificationsWelcomeLayout, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, ServerInspection, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti };
+export { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, EnsureResult, EnsureWebhookResult, EnsuredResource, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, Monitoring, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsEveryoneLayout, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, ServerInspection, Source, SourceFile, SourceTeamMember, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cli",
-  "version": "5.0.0-alpha.199",
+  "version": "5.0.0-alpha.200",
   "description": "The Holocron CLI - a pluggable, capability-based orchestrator for spinning up and operating software projects.",
   "keywords": [
     "cli",
@@ -49,7 +49,7 @@
     "@theholocron/env-utils": "^1.16.0",
     "@theholocron/fs-utils": "^1.16.0",
     "@theholocron/git-utils": "^1.16.0",
-    "@theholocron/github-client": "^1.43.1",
+    "@theholocron/github-client": "^1.47.1",
     "@theholocron/http-client": "^1.43.1",
     "@theholocron/json-utils": "^1.16.0",
     "@theholocron/misc-utils": "^1.16.0",
@@ -63,8 +63,8 @@
     "pino-pretty": "^13.1.3",
     "posthog-node": "^5.51.6",
     "yargs": "^18.1.0",
-    "@theholocron/astromech": "5.0.0-alpha.199",
-    "@theholocron/datapad": "5.0.0-alpha.199"
+    "@theholocron/astromech": "5.0.0-alpha.200",
+    "@theholocron/datapad": "5.0.0-alpha.200"
   },
   "devDependencies": {
     "@theholocron/eslint-config": "^8.8.2",