@theholocron/cli 5.0.0-alpha.433 → 5.0.0-alpha.434

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -29,6 +29,16 @@ interface VerifyTokenFailure {
29
29
  type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
30
30
  /** What a layer's token must do about a permission: `required` it must have it, `absent` it must not. */
31
31
  type PermissionRule = "required" | "absent";
32
+ /**
33
+ * When a token is due for rotation (#2157). `maxAgeDays` is the longest a token may go unrotated; `warnDays` is how
34
+ * many days before an expiry the check starts to fail. Both default to `DEFAULT_TOKEN_ROTATION`.
35
+ */
36
+ interface TokenRotation {
37
+ /** The most days old a token may be, counted from when the provider says it was made (or became valid). */
38
+ maxAgeDays?: number;
39
+ /** Fail this many days before the token's own expiry, so it is rotated before it stops working. */
40
+ warnDays?: number;
41
+ }
32
42
  /**
33
43
  * What a token must carry, declared once next to the plugin's `tokens` list. The permission names are the plugin's own
34
44
  * (Cloudflare: `pages`, `dns`); a layer's rules say which are `required` and which `absent`, so a laptop token might
@@ -42,6 +52,8 @@ interface TokenExpectation {
42
52
  layers?: readonly EnvironmentLayer[];
43
53
  /** Per layer, each permission's rule. A layer named here holds the token. */
44
54
  permissions?: Readonly<Partial<Record<EnvironmentLayer, Readonly<Record<string, PermissionRule>>>>>;
55
+ /** When the token is due for rotation, in every layer that holds it. Default: `DEFAULT_TOKEN_ROTATION`. */
56
+ rotation?: TokenRotation;
45
57
  }
46
58
  /** One token a plugin takes, and where it is looked up. */
47
59
  interface PluginToken {
@@ -436,6 +448,8 @@ interface LayerTokenExpectation {
436
448
  required: readonly string[];
437
449
  /** The permissions the token must not have, in declaration order. */
438
450
  absent: readonly string[];
451
+ /** When the token is due for rotation: the declared policy over `DEFAULT_TOKEN_ROTATION`. */
452
+ rotation: Required<TokenRotation>;
439
453
  }
440
454
  /** Which of the declared expectations to return; both left out returns all of them. */
441
455
  interface TokenExpectationFilter {
@@ -450,6 +464,23 @@ interface TokenExpectationFilter {
450
464
  * walks the declaration itself. A token with no `expect` yields nothing; a layer no token holds is never listed.
451
465
  */
452
466
  export declare function tokenExpectations(tokens: readonly PluginToken[], filter?: TokenExpectationFilter): LayerTokenExpectation[];
467
+ /** When a provider says a token was made and when it stops working. Each is an ISO date or time, left out when unknown. */
468
+ interface TokenLifetime {
469
+ /** When the token was made, or became valid when that is all the provider says (Cloudflare `not_before`). */
470
+ createdAt?: string;
471
+ /** When the token expires. Unset for a token that never does. */
472
+ expiresAt?: string;
473
+ }
474
+ /** The rotation policy of a token that declares none: a token is due after 90 days, and an expiry is flagged 14 days ahead. */
475
+ export declare const DEFAULT_TOKEN_ROTATION: Required<TokenRotation>;
476
+ /**
477
+ * Rows saying whether a token is due for rotation, from what its provider exposes. Provider-neutral: a token probe reads
478
+ * the lifetime however its provider offers it and hands it here, with the layer's `rotation` from `tokenExpectations()`.
479
+ * `lifetime` is `undefined` when the provider exposes nothing (the row says so rather than passing), and a date the
480
+ * provider gave that does not parse is an `info` row, never a pass. An expired or near-expiry token fails, and so does
481
+ * one older than `maxAgeDays`. Only dates are printed, never the token.
482
+ */
483
+ export declare function tokenRotationRows(lifetime: TokenLifetime | undefined, rotation: Required<TokenRotation>, now: Date): ProbeRow[];
453
484
  /**
454
485
  * What stdout is. A token is never written to a `terminal` (it would sit in scrollback) or to `other` (a redirect to
455
486
  * a regular file, which would leave plaintext tokens on disk without the protections of the file option); only a
@@ -510,4 +541,4 @@ export declare const SHARED_AREAS: readonly ["org"];
510
541
  * is a `ConfigError` naming both (no merge, no precedence). With no area files the config is returned as it was.
511
542
  */
512
543
  export declare function placeAreas(areas: ConfigDirArea[], raw: HolocronConfig): HolocronConfig;
513
- export { AddedItem, Analytics, type AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, type AuthExportOutKind, AuthIdentity, AuthUser, BoardField, BoardFieldType, BoardItem, BoardItemInput, BoardRule, BoardState, BoardStatus, BoardStatusCategory, BoardSummary, BoardTemplate, BoardTemplateFile, BoardView, CARDINALITY, type Capability, type CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, type ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, type ComposedPreset, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, Credentials, type CredentialsConfig, CredentialsInspection, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, type DeriveProfileInput, type DevConfig, type DevServeConfig, DiscussionPatch, DiscussionPost, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, type DocsConfig, type DoctorConfig, DuplicateDiscussion, ElevationRequiredError, EnsureDiscussionInput, EnsureRelayInput, EnsureRelayResult, EnsureReport, EnsureResult, EnsureWebhookResult, EnsuredDiscussion, EnsuredResource, EnsuredTunnel, type EnvConfig, Environment, EnvironmentEntry, type EnvironmentLayer, EnvironmentReviewer, Environments, Errors, type EslintConfig, ExportInfo, type FeatureResolver, type FeatureResolverConfig, type GitHubAppConfig, type HolocronConfig, type HolocronProfile, IdeaRecord, Ideas, type IdeasConfig, ImportOptions, ImportResult, InspectRelayInput, Issue, IssueComment, IssueOrder, IssuePriority, IssueRecord, IssueSearchFilter, IssueSelector, Issues, KNOWN_STACK_DEPS, LabelDef, type LayerTokenExpectation, LifecycleResult, LifecycleSlot, type LinksFile, type LoadedConfig, type LogConfig, Logs, LogsDataset, type MemberLink, MissingTokenError, Monitoring, MonitoringAlertChannelInput, MonitoringAlertChannelResult, MonitoringAlertChannelState, MonitoringAlertSettings, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, MoveReport, type MultiEntry, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsForumTag, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsMonitoringFeed, NotificationsOnboardingLayout, NotificationsPicture, NotificationsPinnedLayout, NotificationsPrsFeed, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, type OrgConfig, OrganizationSecretScope, type PackageJsonLike, PagesConfig, ParseWebhookInput, type PermissionRule, type PluginProbes, type PluginToken, type Probe, type ProbeContext, type ProbeRow, Projects, type ProviderAction, type ProviderActionContext, type ProviderActions, ProviderApiError, ProviderIdentity, type ProviderOptions, type ProviderRow, PullRequest, REQUIRED_CAPABILITIES, type RawProviderEntry, type RawProvidersConfig, type ReadKeysLimitedInput, RelayState, type RepoConfig, type RepoProperties, type RepoProtection, RepoRef, type RepoSecrets, type RepoSecretsDeploy, type RepoSecretsSync, RepoSettings, type RepoValidationConfig, type RepoVariables, type RepoVariablesSync, type RequestOptions, type ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, type ResolvedHolocronConfig, type ResolvedProviderEntry, type ResolvedProvidersConfig, type ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretAccess, SecretScope, SecretVisibility, Secrets, ServerInspection, type SingleEntry, Source, SourceBranch, SourceFile, SourceRepoInfo, SourceRulesetDetail, SourceSecurity, SourceTeamMember, type StackName, StatusCategory, Storage, StorageBranch, type StorybookDeployProject, SyncResult, type SyncRolesInput, type SyncRolesResult, type TaskEntry, type TaskEntryConfig, TeamEntry, TeamPermission, type TelemetryConfig, type TokenExpectation, type TokenExpectationFilter, type TokenResolver, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, TunnelRoute, Tunnels, Vault, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, WorkerScriptState, Workers, type WorkflowWithConfig, compose, createRestClient, credentialsEnvironment, defineConfig, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, isMulti, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, resolveValue };
544
+ export { AddedItem, Analytics, type AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, type AuthExportOutKind, AuthIdentity, AuthUser, BoardField, BoardFieldType, BoardItem, BoardItemInput, BoardRule, BoardState, BoardStatus, BoardStatusCategory, BoardSummary, BoardTemplate, BoardTemplateFile, BoardView, CARDINALITY, type Capability, type CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, type ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, type ComposedPreset, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, Credentials, type CredentialsConfig, CredentialsInspection, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, type DeriveProfileInput, type DevConfig, type DevServeConfig, DiscussionPatch, DiscussionPost, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, type DocsConfig, type DoctorConfig, DuplicateDiscussion, ElevationRequiredError, EnsureDiscussionInput, EnsureRelayInput, EnsureRelayResult, EnsureReport, EnsureResult, EnsureWebhookResult, EnsuredDiscussion, EnsuredResource, EnsuredTunnel, type EnvConfig, Environment, EnvironmentEntry, type EnvironmentLayer, EnvironmentReviewer, Environments, Errors, type EslintConfig, ExportInfo, type FeatureResolver, type FeatureResolverConfig, type GitHubAppConfig, type HolocronConfig, type HolocronProfile, IdeaRecord, Ideas, type IdeasConfig, ImportOptions, ImportResult, InspectRelayInput, Issue, IssueComment, IssueOrder, IssuePriority, IssueRecord, IssueSearchFilter, IssueSelector, Issues, KNOWN_STACK_DEPS, LabelDef, type LayerTokenExpectation, LifecycleResult, LifecycleSlot, type LinksFile, type LoadedConfig, type LogConfig, Logs, LogsDataset, type MemberLink, MissingTokenError, Monitoring, MonitoringAlertChannelInput, MonitoringAlertChannelResult, MonitoringAlertChannelState, MonitoringAlertSettings, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, MoveReport, type MultiEntry, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsForumTag, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsMonitoringFeed, NotificationsOnboardingLayout, NotificationsPicture, NotificationsPinnedLayout, NotificationsPrsFeed, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, type OrgConfig, OrganizationSecretScope, type PackageJsonLike, PagesConfig, ParseWebhookInput, type PermissionRule, type PluginProbes, type PluginToken, type Probe, type ProbeContext, type ProbeRow, Projects, type ProviderAction, type ProviderActionContext, type ProviderActions, ProviderApiError, ProviderIdentity, type ProviderOptions, type ProviderRow, PullRequest, REQUIRED_CAPABILITIES, type RawProviderEntry, type RawProvidersConfig, type ReadKeysLimitedInput, RelayState, type RepoConfig, type RepoProperties, type RepoProtection, RepoRef, type RepoSecrets, type RepoSecretsDeploy, type RepoSecretsSync, RepoSettings, type RepoValidationConfig, type RepoVariables, type RepoVariablesSync, type RequestOptions, type ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, type ResolvedHolocronConfig, type ResolvedProviderEntry, type ResolvedProvidersConfig, type ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretAccess, SecretScope, SecretVisibility, Secrets, ServerInspection, type SingleEntry, Source, SourceBranch, SourceFile, SourceRepoInfo, SourceRulesetDetail, SourceSecurity, SourceTeamMember, type StackName, StatusCategory, Storage, StorageBranch, type StorybookDeployProject, SyncResult, type SyncRolesInput, type SyncRolesResult, type TaskEntry, type TaskEntryConfig, TeamEntry, TeamPermission, type TelemetryConfig, type TokenExpectation, type TokenExpectationFilter, type TokenLifetime, type TokenResolver, type TokenRotation, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, TunnelRoute, Tunnels, Vault, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, WorkerScriptState, Workers, type WorkflowWithConfig, compose, createRestClient, credentialsEnvironment, defineConfig, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, isMulti, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, resolveValue };
package/dist/index.mjs CHANGED
@@ -554,6 +554,88 @@ const CANONICAL_LABELS = [
554
554
  description: "Won't be addressed"
555
555
  }
556
556
  ];
557
+ // src/commands/token-rotation/token-rotation.ts
558
+ /** The rotation policy of a token that declares none: a token is due after 90 days, and an expiry is flagged 14 days ahead. */
559
+ const DEFAULT_TOKEN_ROTATION = {
560
+ maxAgeDays: 90,
561
+ warnDays: 14
562
+ };
563
+ const DAY_MS = 864e5;
564
+ /** The whole days from `from` to `to`, rounded down (negative once `to` is past). */
565
+ function daysBetween(from, to) {
566
+ return Math.floor((to.getTime() - from.getTime()) / DAY_MS);
567
+ }
568
+ /** `2026-11-13` of a valid date. */
569
+ const day = (d) => d.toISOString().slice(0, 10);
570
+ /** A valid `Date` of an ISO string, or `undefined` when there is none or it does not parse. */
571
+ function parse(value) {
572
+ if (value === void 0) return void 0;
573
+ const date = new Date(value);
574
+ return Number.isNaN(date.getTime()) ? void 0 : date;
575
+ }
576
+ /**
577
+ * Rows saying whether a token is due for rotation, from what its provider exposes. Provider-neutral: a token probe reads
578
+ * the lifetime however its provider offers it and hands it here, with the layer's `rotation` from `tokenExpectations()`.
579
+ * `lifetime` is `undefined` when the provider exposes nothing (the row says so rather than passing), and a date the
580
+ * provider gave that does not parse is an `info` row, never a pass. An expired or near-expiry token fails, and so does
581
+ * one older than `maxAgeDays`. Only dates are printed, never the token.
582
+ */
583
+ function tokenRotationRows(lifetime, rotation, now) {
584
+ if (!lifetime) return [{
585
+ status: "info",
586
+ label: "rotation",
587
+ detail: `the provider does not expose this token's age or expiry; rotate it by hand every ${rotation.maxAgeDays} days`
588
+ }];
589
+ const rows = [];
590
+ const expires = parse(lifetime.expiresAt);
591
+ if (lifetime.expiresAt !== void 0 && !expires) rows.push({
592
+ status: "info",
593
+ label: "expiry",
594
+ detail: "the provider's expiry date could not be read"
595
+ });
596
+ else if (expires) {
597
+ const left = daysBetween(now, expires);
598
+ if (expires.getTime() <= now.getTime()) rows.push({
599
+ status: "fail",
600
+ label: "expiry",
601
+ detail: `expired on ${day(expires)}`
602
+ });
603
+ else if (left < rotation.warnDays) rows.push({
604
+ status: "fail",
605
+ label: "expiry",
606
+ detail: `expires on ${day(expires)} (${left} days left, warns under ${rotation.warnDays}); rotate it`
607
+ });
608
+ else rows.push({
609
+ status: "ok",
610
+ label: "expiry",
611
+ detail: `expires on ${day(expires)} (${left} days left)`
612
+ });
613
+ } else rows.push({
614
+ status: "info",
615
+ label: "expiry",
616
+ detail: "the token has no expiry"
617
+ });
618
+ const created = parse(lifetime.createdAt);
619
+ if (lifetime.createdAt !== void 0 && !created) rows.push({
620
+ status: "info",
621
+ label: "age",
622
+ detail: "the provider's creation date could not be read"
623
+ });
624
+ else if (created) {
625
+ const age = daysBetween(created, now);
626
+ const due = age > rotation.maxAgeDays;
627
+ rows.push({
628
+ status: due ? "fail" : "ok",
629
+ label: "age",
630
+ detail: due ? `${age} days old since ${day(created)}, over the ${rotation.maxAgeDays} days allowed; rotate it` : `${age} days old since ${day(created)} (rotate after ${rotation.maxAgeDays})`
631
+ });
632
+ } else rows.push({
633
+ status: "info",
634
+ label: "age",
635
+ detail: "the provider does not say when the token was made"
636
+ });
637
+ return rows;
638
+ }
557
639
  // src/commands/token-expectations/token-expectations.ts
558
640
  /**
559
641
  * Reads what a plugin's tokens declare (`PluginToken.expect`) as one entry per token and layer that holds it, in the
@@ -575,7 +657,11 @@ function tokenExpectations(tokens, filter = {}) {
575
657
  layer,
576
658
  rules: rules ?? {},
577
659
  required: entries.filter(([, rule]) => rule === "required").map(([name]) => name),
578
- absent: entries.filter(([, rule]) => rule === "absent").map(([name]) => name)
660
+ absent: entries.filter(([, rule]) => rule === "absent").map(([name]) => name),
661
+ rotation: {
662
+ ...DEFAULT_TOKEN_ROTATION,
663
+ ...token.expect.rotation
664
+ }
579
665
  });
580
666
  }
581
667
  }
@@ -639,4 +725,4 @@ function resolveCredentialsFile(base, file, makeDir = (dir) => void mkdirSync(di
639
725
  isDefault: true
640
726
  };
641
727
  }
642
- export { AuthError, CANONICAL_LABELS, CARDINALITY, ConfigError, ConfigFileError, ElevationRequiredError, HOLOCRON_AREAS, KNOWN_STACK_DEPS, MissingTokenError, PRIVATE_CREDENTIALS_FILE, ProviderApiError, REQUIRED_CAPABILITIES, SHARED_AREAS, WebhookVerificationError, compose, connectionProbe, createFeatureResolver, createResolveToken, createRestClient, credentialsEnvironment, defineConfig, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, ignoreAdvice, isMulti, keyring, loadConfig, missingCapabilities, orderKeys, pickByCreation, placeAreas, readKeysLimited, readLinks, readWorkspacePackageJsons, reportProgress, resolveConfig, resolveCredentialsFile, resolveEntry, resolveEnvironmentId, resolvePluginPackage, resolveValue, roleTeamProblem, sourceProblem, stdoutKind, syncRoles, tokenExpectations };
728
+ export { AuthError, CANONICAL_LABELS, CARDINALITY, ConfigError, ConfigFileError, DEFAULT_TOKEN_ROTATION, ElevationRequiredError, HOLOCRON_AREAS, KNOWN_STACK_DEPS, MissingTokenError, PRIVATE_CREDENTIALS_FILE, ProviderApiError, REQUIRED_CAPABILITIES, SHARED_AREAS, WebhookVerificationError, compose, connectionProbe, createFeatureResolver, createResolveToken, createRestClient, credentialsEnvironment, defineConfig, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, ignoreAdvice, isMulti, keyring, loadConfig, missingCapabilities, orderKeys, pickByCreation, placeAreas, readKeysLimited, readLinks, readWorkspacePackageJsons, reportProgress, resolveConfig, resolveCredentialsFile, resolveEntry, resolveEnvironmentId, resolvePluginPackage, resolveValue, roleTeamProblem, sourceProblem, stdoutKind, syncRoles, tokenExpectations, tokenRotationRows };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/cli",
3
- "version": "5.0.0-alpha.433",
3
+ "version": "5.0.0-alpha.434",
4
4
  "description": "The Holocron CLI - a pluggable, capability-based orchestrator for spinning up and operating software projects.",
5
5
  "keywords": [
6
6
  "cli",
@@ -59,19 +59,19 @@
59
59
  "posthog-node": "^5.64.0",
60
60
  "tsx": "4.23.15",
61
61
  "yargs": "^18.1.0",
62
- "@theholocron/dagobah": "5.0.0-alpha.433",
63
- "@theholocron/datapad": "5.0.0-alpha.433",
62
+ "@theholocron/astromech": "5.0.0-alpha.434",
64
63
  "@theholocron/env-utils": "^1.17.0-alpha.4",
65
- "@theholocron/astromech": "5.0.0-alpha.433",
66
- "@theholocron/github-client": "^1.58.0-alpha.29",
64
+ "@theholocron/datapad": "5.0.0-alpha.434",
65
+ "@theholocron/fs-utils": "^1.17.0-alpha.4",
67
66
  "@theholocron/git-utils": "^1.17.0-alpha.4",
67
+ "@theholocron/github-client": "^1.58.0-alpha.30",
68
+ "@theholocron/http-client": "^1.58.0-alpha.30",
69
+ "@theholocron/dagobah": "5.0.0-alpha.434",
68
70
  "@theholocron/json-utils": "^1.17.0-alpha.4",
69
- "@theholocron/http-client": "^1.58.0-alpha.29",
70
- "@theholocron/misc-utils": "^1.17.0-alpha.4",
71
- "@theholocron/kyber": "5.0.0-alpha.433",
71
+ "@theholocron/kyber": "5.0.0-alpha.434",
72
72
  "@theholocron/observability": "^0.7.0-alpha.4",
73
73
  "@theholocron/pkg-utils": "^1.17.0-alpha.4",
74
- "@theholocron/fs-utils": "^1.17.0-alpha.4"
74
+ "@theholocron/misc-utils": "^1.17.0-alpha.4"
75
75
  },
76
76
  "devDependencies": {
77
77
  "@types/node": "^26",