@theholocron/cli 5.0.0-alpha.187 → 5.0.0-alpha.189

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, NotificationsChannelLayout, NotificationsLayout, 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, NotificationsChannelLayout, NotificationsLayout, 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 { 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, NotificationsChannelLayout, NotificationsLayout, 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, NotificationsChannelLayout, NotificationsLayout, 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 };

package/dist/plugin/capabilities.d.mts

@@ -740,6 +740,8 @@ interface Tooling extends ProviderIdentity {
 interface EnsuredResource {
   id: string;
   created: boolean;
+  /** For something that already existed: the settings that disagreed with the layout and were changed. */
+  updated?: string[];
 }
 /** A webhook (or equivalent inbound URL) for a channel. */
 interface EnsureWebhookResult {
@@ -751,10 +753,23 @@ interface EnsureWebhookResult {
    */
   url?: string;
 }
+/**
+ * Who may see a channel and post in it. Roles are named as in the layout's `roles`.
+ * A channel inherits its category's access; stating `view` or `post` on the channel
+ * replaces that field only.
+ */
+interface NotificationsAccess {
+  /** `"everyone"` (the default), or the roles that can see it: everyone else cannot. */
+  view?: "everyone" | string[];
+  /** `"everyone"` (the default), or the roles that can post; `[]` means only bots and webhooks. */
+  post?: "everyone" | string[];
+}
 /** One channel in a {@link NotificationsLayout}. */
 interface NotificationsChannelLayout {
   name: string;
   topic?: string;
+  /** Who may see and post. Overrides the category's, field by field. */
+  access?: NotificationsAccess;
   /**
    * Create an inbound webhook for the channel and store its URL in a secret.
    * `true` uses the defaults; the object form overrides the webhook's display
@@ -769,11 +784,21 @@ interface NotificationsChannelLayout {
 interface NotificationsLayout {
   categories?: Array<{
     name: string;
+    access?: NotificationsAccess;
     channels?: NotificationsChannelLayout[];
   }>;
   roles?: Array<{
     name: string;
     mentionable?: boolean;
+    /** `#rrggbb`. Omit to leave the colour alone. */
+    color?: string;
+    /** Show the role's members as their own group in the member list. */
+    hoist?: boolean;
+    /**
+     * The permissions the role holds, by the provider's own names (for Discord, `ViewChannel`,
+     * `SendMessages`, …). The list is exact: a permission not named is not granted.
+     */
+    permissions?: 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
@@ -785,11 +810,16 @@ interface NotificationsLayout {
 }
 /**
  * What a provider found on the server, limited to what a {@link NotificationsLayout}
- * asks about. Read-only: this is what `holocron notifications verify` compares the
+ * asks about. Read-only: this is what `holocron doctor notifications` compares the
  * layout against.
  */
 interface ServerInspection {
   categories: string[];
+  /**
+   * Who can see and post in each category. `"custom"` means its overwrites are not an access the layout
+   * can state (a role-specific deny, a member overwrite, only some of the posting permissions).
+   */
+  categoryAccess?: Record<string, Required<NotificationsAccess> | "custom">;
   channels: Array<{
     name: string;
     /** The category it sits under, if any. */
@@ -799,11 +829,17 @@ interface ServerInspection {
     webhooks: string[];
     /** Set when listing this channel's webhooks failed; `webhooks` is then empty and means nothing. */
     webhooksError?: string;
+    /** Who can see and post; `"custom"` as for `categoryAccess`. */
+    access?: Required<NotificationsAccess> | "custom";
   }>;
   roles: Array<{
     name: string;
     id: string;
     mentionable: boolean;
+    /** `#rrggbb`, or absent for the default colour. */
+    color?: string;
+    hoist?: boolean;
+    permissions?: string[];
   }>;
   /** Set when reading the roles failed; `roles` is then empty and means nothing. Not read at all when the layout declares none. */
   rolesError?: string;
@@ -825,11 +861,14 @@ interface Notifications extends ProviderIdentity {
    * what is missing), and all need provider credentials beyond the posting
    * URL — so a provider that only posts simply omits them.
    */
-  ensureCategory?(name: string): Promise<EnsuredResource>;
+  ensureCategory?(name: string, opts?: {
+    access?: NotificationsAccess;
+  }): Promise<EnsuredResource>;
   ensureChannel?(input: {
     name: string;
     category?: string;
     topic?: string;
+    access?: NotificationsAccess;
   }): Promise<EnsuredResource>;
   ensureWebhook?(input: {
     channel: string;
@@ -839,7 +878,16 @@ interface Notifications extends ProviderIdentity {
   ensureRole?(input: {
     name: string;
     mentionable?: boolean;
+    color?: string;
+    hoist?: boolean;
+    permissions?: string[];
   }): Promise<EnsuredResource>;
+  /**
+   * Check the provider-specific parts of the layout (colours, permission names, …) without
+   * touching the server, so `setup` can refuse a bad layout before it creates anything.
+   * Returns the first problem, or `undefined` when the layout is fine.
+   */
+  validateLayout?(layout: NotificationsLayout): string | undefined;
   /**
    * Smoke check for `holocron doctor`: prove the provisioning credentials work
    * and name what they reach. Returns `null` when there is nothing to check (a
@@ -852,7 +900,7 @@ interface Notifications extends ProviderIdentity {
   } | null>;
   /**
    * Read what exists on the server, for the parts the layout cares about, without
-   * changing anything. Backs `holocron notifications verify`.
+   * changing anything. Backs `holocron doctor notifications`.
    */
   inspect?(layout: NotificationsLayout): Promise<ServerInspection>;
 }
@@ -1027,4 +1075,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, NotificationsChannelLayout, NotificationsLayout, 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, NotificationsChannelLayout, NotificationsLayout, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cli",
-  "version": "5.0.0-alpha.187",
+  "version": "5.0.0-alpha.189",
   "description": "The Holocron CLI - a pluggable, capability-based orchestrator for spinning up and operating software projects.",
   "keywords": [
     "cli",
@@ -63,8 +63,8 @@
     "pino-pretty": "^13.1.3",
     "posthog-node": "^5.51.6",
     "yargs": "^18.1.0",
-    "@theholocron/astromech": "5.0.0-alpha.187",
-    "@theholocron/datapad": "5.0.0-alpha.187"
+    "@theholocron/astromech": "5.0.0-alpha.189",
+    "@theholocron/datapad": "5.0.0-alpha.189"
   },
   "devDependencies": {
     "@theholocron/eslint-config": "^8.8.2",