@theholocron/cli 2.0.0-alpha.0 → 2.0.0-alpha.5

package/dist/{index-DDxKXqtR.d.mts → index-jxPVFH7-.d.mts}

@@ -11,8 +11,8 @@
  * See `.notes/tech-architecture.spec.md` for the design narrative
  * (status: proposed, issue: #74).
  */
-type CapabilityKey = 'source' | 'ci' | 'secrets' | 'environments' | 'issues' | 'deployment' | 'storage' | 'auth' | 'vault' | 'dns' | 'tooling' | 'notifications' | 'analytics' | 'observability';
-type Cardinality = 'single' | 'many';
+type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "observability";
+type Cardinality = "single" | "many";
 declare const CARDINALITY: {
   readonly source: "single";
   readonly ci: "single";
@@ -29,7 +29,11 @@ declare const CARDINALITY: {
   readonly analytics: "many";
   readonly observability: "many";
 };
-/** Vault is required; everything else is optional in the config. */
+/**
+ * No capabilities are strictly required — repos without secrets (e.g. org
+ * community health repos) legitimately omit vault. Plugins validate their
+ * own requirements at call time.
+ */
 declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
 interface ProviderIdentity {
   readonly key: CapabilityKey;
@@ -50,7 +54,7 @@ declare class ProviderApiError extends Error {
 interface Ruleset {
   id: number;
   name: string;
-  enforcement: 'active' | 'evaluate' | 'disabled';
+  enforcement: "active" | "evaluate" | "disabled";
   target?: string;
 }
 interface RepoSettings {
@@ -58,10 +62,14 @@ interface RepoSettings {
   allow_merge_commit?: boolean;
   allow_rebase_merge?: boolean;
   allow_auto_merge?: boolean;
+  /** Always suggest updating PR branches when the base branch has new commits. */
+  allow_update_branch?: boolean;
   delete_branch_on_merge?: boolean;
   default_branch?: string;
   has_issues?: boolean;
   has_discussions?: boolean;
+  has_projects?: boolean;
+  has_wiki?: boolean;
 }
 interface RepoRef {
   owner: string;
@@ -69,7 +77,7 @@ interface RepoRef {
   defaultBranch: string;
 }
 interface Source extends ProviderIdentity {
-  readonly key: 'source';
+  readonly key: "source";
   /** Auth sanity-check. Throws ProviderApiError on auth failure. */
   whoami(): Promise<{
     login: string;
@@ -79,16 +87,41 @@ interface Source extends ProviderIdentity {
   createRuleset(payload: Record<string, unknown>): Promise<Ruleset>;
   updateRuleset(id: number, payload: Record<string, unknown>): Promise<Ruleset>;
   updateRepoSettings(settings: RepoSettings): Promise<void>;
+  /**
+   * Classic branch protection — fallback for private repos on free plans
+   * where the Rulesets API (requires Team+) returns 403.
+   */
+  protectBranch(branch: string, payload: Record<string, unknown>): Promise<void>;
   enableVulnerabilityAlerts(): Promise<void>;
   enableAutomatedSecurityFixes(): Promise<void>;
   enableSecretScanning(): Promise<void>;
   enablePrivateVulnerabilityReporting(): Promise<void>;
+  /**
+   * Enables the dependency graph and automatic dependency snapshot
+   * submission. Also enables secret-scanning validity checks and
+   * non-provider pattern detection — these require GitHub Advanced
+   * Security at the org level; the call is accepted but may be a no-op
+   * until that is configured.
+   */
+  enableDependencyGraph(): Promise<void>;
+  /**
+   * Enables CodeQL default setup with the extended query suite and
+   * `threat_model: all` (scans both remote and local exploit paths).
+   * Triggers a new analysis run; returns the run id.
+   */
+  enableCodeScanning(): Promise<string>;
   listWorkflowFiles(): Promise<string[]>;
   readWorkflowFile(name: string): Promise<string | null>;
   writeWorkflowFile(name: string, contents: string): Promise<void>;
   removeWorkflowFile(name: string): Promise<void>;
+  /**
+   * Write an arbitrary file relative to the repo root. Used for
+   * provisioning config files that live outside `.github/workflows/`
+   * (e.g. `.github/dependabot.yml`).
+   */
+  writeRepoFile(path: string, contents: string): Promise<void>;
 }
-type CiRunStatus = 'queued' | 'in_progress' | 'completed' | 'cancelled' | 'failure' | 'success' | 'skipped';
+type CiRunStatus = "queued" | "in_progress" | "completed" | "cancelled" | "failure" | "success" | "skipped";
 interface CiRun {
   id: string | number;
   workflowName: string;
@@ -105,21 +138,21 @@ interface CiRunFilter {
   limit?: number;
 }
 interface Ci extends ProviderIdentity {
-  readonly key: 'ci';
+  readonly key: "ci";
   listRuns(filter?: CiRunFilter): Promise<CiRun[]>;
   getRun(id: string | number): Promise<CiRun>;
 }
 type SecretScope = {
-  kind: 'repo';
+  kind: "repo";
 } | {
-  kind: 'environment';
+  kind: "environment";
   name: string;
 } | {
-  kind: 'organization';
+  kind: "organization";
   name: string;
 };
 interface Secrets extends ProviderIdentity {
-  readonly key: 'secrets';
+  readonly key: "secrets";
   /** List secret NAMES (not values) at the given scope. */
   listSecrets(scope: SecretScope): Promise<string[]>;
   /** Idempotent upsert. Adapter handles encryption. */
@@ -127,7 +160,7 @@ interface Secrets extends ProviderIdentity {
   deleteSecret(scope: SecretScope, name: string): Promise<void>;
 }
 interface EnvironmentReviewer {
-  type: 'User' | 'Team';
+  type: "User" | "Team";
   /** Numeric id — GitHub's reviewer API silently ignores login strings. */
   id: number;
 }
@@ -138,13 +171,13 @@ interface Environment {
   preventSelfReview?: boolean;
 }
 interface Environments extends ProviderIdentity {
-  readonly key: 'environments';
+  readonly key: "environments";
   listEnvironments(): Promise<Environment[]>;
   upsertEnvironment(env: Environment): Promise<void>;
   deleteEnvironment(name: string): Promise<void>;
 }
-type LifecycleSlot = 'inProgress' | 'inReview' | 'done';
-type StatusCategory = 'open' | 'in-progress' | 'in-review' | 'done' | 'other';
+type LifecycleSlot = "inProgress" | "inReview" | "done";
+type StatusCategory = "open" | "in-progress" | "in-review" | "done" | "other";
 interface TrackerUser {
   id: string;
   displayName: string;
@@ -165,7 +198,7 @@ interface Issue {
 }
 interface IssueSearchFilter {
   /** Restrict to issues assigned to a specific id, or 'currentUser'. */
-  assignee?: string | 'currentUser';
+  assignee?: string | "currentUser";
   /** Exclude issues in the `done` category. */
   openOnly?: boolean;
   /** Max number of issues to return. Adapters apply a sensible default. */
@@ -202,7 +235,7 @@ interface TrackerDoctorReport {
   }>;
 }
 interface Issues extends ProviderIdentity {
-  readonly key: 'issues';
+  readonly key: "issues";
   /** Currently-authenticated user. */
   getMyself(): Promise<TrackerUser>;
   search(filter: IssueSearchFilter): Promise<Issue[]>;
@@ -221,12 +254,12 @@ interface Issues extends ProviderIdentity {
   doctor(): Promise<TrackerDoctorReport>;
 }
 /** Env-var scope on the deploy platform. */
-type DeploymentTarget = 'development' | 'preview' | 'production';
+type DeploymentTarget = "development" | "preview" | "production";
 /**
  * Named deployment trigger target — `undefined` means a branch
  * preview (no named environment).
  */
-type DeploymentTrigger = 'production' | 'staging';
+type DeploymentTrigger = "production" | "staging";
 interface DeploymentProject {
   id: string;
   name: string;
@@ -248,10 +281,10 @@ interface DeploymentRecord {
   branch: string | null;
   /** Named environment if one was targeted; undefined for branch previews. */
   target?: DeploymentTrigger;
-  status: 'queued' | 'building' | 'ready' | 'error' | 'cancelled';
+  status: "queued" | "building" | "ready" | "error" | "cancelled";
 }
 interface Deployment extends ProviderIdentity {
-  readonly key: 'deployment';
+  readonly key: "deployment";
   listProjects(): Promise<DeploymentProject[]>;
   /** Create if missing, otherwise return existing. Idempotent. */
   ensureProject(input: {
@@ -287,7 +320,7 @@ interface ConnectionStringOptions {
   pooled?: boolean;
 }
 interface Storage extends ProviderIdentity {
-  readonly key: 'storage';
+  readonly key: "storage";
   /**
    * Connection string for the given scope. Scope is provider-specific:
    *
@@ -343,7 +376,7 @@ interface WebhookDashboardInfo {
   url: string;
 }
 interface Auth extends ProviderIdentity {
-  readonly key: 'auth';
+  readonly key: "auth";
   /** Env-var keys the runtime app needs. */
   describe(): Promise<AuthDescription>;
   /** Reachability probe — proves the configured key works. */
@@ -362,7 +395,7 @@ interface Auth extends ProviderIdentity {
     secretRef: string;
   }): Promise<void>;
 }
-type AuthEventType = 'user.created' | 'user.updated' | 'user.deleted';
+type AuthEventType = "user.created" | "user.updated" | "user.deleted";
 interface NormalizedAuthUser {
   id: string;
   email: string;
@@ -388,8 +421,12 @@ interface ParseWebhookInput {
 declare class WebhookVerificationError extends Error {
   name: string;
 }
+interface EnsureResult {
+  /** True when the resource already existed (idempotent no-op). */
+  alreadyExists: boolean;
+}
 interface Vault extends ProviderIdentity {
-  readonly key: 'vault';
+  readonly key: "vault";
   /**
    * Read a secret by reference. The reference format is
    * provider-specific (1P: "op://Vault/Item/field"; HashiCorp Vault:
@@ -413,8 +450,21 @@ interface Vault extends ProviderIdentity {
    * destinations (CI secrets, deployment env vars, local .env).
    */
   readEnvironment?(environmentId: string): Promise<Record<string, string>>;
+  /**
+   * Optional — create the top-level project container in the vault
+   * if it does not exist. Idempotent: `alreadyExists: true` when the
+   * project was already there. Providers whose data model has no
+   * project notion (or that gate this behind a paid tier) omit this.
+   */
+  ensureProject?(name: string): Promise<EnsureResult>;
+  /**
+   * Optional — create a named environment/config inside a project
+   * (e.g., Doppler config `dev` / `stg` / `prd`). Idempotent.
+   * Providers whose data model has a single flat namespace omit this.
+   */
+  ensureEnvironment?(project: string, name: string): Promise<EnsureResult>;
 }
-type DnsRecordType = 'A' | 'AAAA' | 'CNAME' | 'TXT' | 'MX' | 'NS' | 'SRV' | 'CAA';
+type DnsRecordType = "A" | "AAAA" | "CNAME" | "TXT" | "MX" | "NS" | "SRV" | "CAA";
 interface DnsRecord {
   id?: string;
   type: DnsRecordType;
@@ -424,7 +474,7 @@ interface DnsRecord {
   priority?: number;
 }
 interface Dns extends ProviderIdentity {
-  readonly key: 'dns';
+  readonly key: "dns";
   listRecords(domain: string): Promise<DnsRecord[]>;
   upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
   deleteRecord(domain: string, id: string): Promise<void>;
@@ -434,13 +484,13 @@ interface ToolingDoctorReport {
   message: string;
 }
 interface Tooling extends ProviderIdentity {
-  readonly key: 'tooling';
+  readonly key: "tooling";
   /** Sync the tool's authoritative state from the repo. */
   sync(): Promise<void>;
   doctor(): Promise<ToolingDoctorReport>;
 }
 interface Notifications extends ProviderIdentity {
-  readonly key: 'notifications';
+  readonly key: "notifications";
   /**
    * Send a message. `channel` is provider-specific (Slack channel id,
    * Discord webhook url-name, etc.); adapters resolve from config.
@@ -448,14 +498,14 @@ interface Notifications extends ProviderIdentity {
   send(channel: string, message: string): Promise<void>;
 }
 interface Analytics extends ProviderIdentity {
-  readonly key: 'analytics';
+  readonly key: "analytics";
   describe(): Promise<{
     provider: string;
     dsnEnvKey: string;
   }>;
 }
 interface Observability extends ProviderIdentity {
-  readonly key: 'observability';
+  readonly key: "observability";
   describe(): Promise<{
     provider: string;
     dsnEnvKey: string;
@@ -479,7 +529,7 @@ interface CapabilityImpls {
 }
 type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
 /** Resolved runtime shape: single → one impl; many → array. */
-type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends 'many' ? CapabilityImpls[K][] : CapabilityImpls[K];
-declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends 'many' ? true : false;
+type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
+declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
 //#endregion
-export { Tooling as $, Environments as A, ProviderApiError as B, DeploymentTarget as C, DnsRecordType as D, DnsRecord as E, LifecycleSlot as F, ResolvedCapability as G, REQUIRED_CAPABILITIES as H, NormalizedAuthUser as I, Secrets as J, Ruleset as K, Notifications as L, IssueSearchFilter as M, Issues as N, Environment as O, LifecycleResult as P, StorageBranch as Q, Observability as R, DeploymentRecord as S, Dns as T, RepoRef as U, ProviderIdentity as V, RepoSettings as W, StatusCategory as X, Source as Y, Storage as Z, ConnectionStringOptions as _, AuthEventType as a, WebhookVerificationError as at, DeploymentProject as b, CARDINALITY as c, Cardinality as d, ToolingDoctorReport as et, CardinalityFor as f, CiRunStatus as g, CiRunFilter as h, AuthEvent as i, WebhookDashboardInfo as it, Issue as j, EnvironmentReviewer as k, CapabilityImpls as l, CiRun as m, Auth as n, TrackerUser as nt, AuthIdentity as o, isMulti as ot, Ci as p, SecretScope as q, AuthDescription as r, Vault as rt, AuthUser as s, Analytics as t, TrackerDoctorReport as tt, CapabilityKey as u, CreateAuthUserInput as v, DeploymentTrigger as w, DeploymentProjectSettings as x, Deployment as y, ParseWebhookInput as z };
+export { StorageBranch as $, EnvironmentReviewer as A, ParseWebhookInput as B, DeploymentTarget as C, DnsRecordType as D, DnsRecord as E, LifecycleResult as F, RepoSettings as G, ProviderIdentity as H, LifecycleSlot as I, SecretScope as J, ResolvedCapability as K, NormalizedAuthUser as L, Issue as M, IssueSearchFilter as N, EnsureResult as O, Issues as P, Storage as Q, Notifications as R, DeploymentRecord as S, Dns as T, REQUIRED_CAPABILITIES as U, ProviderApiError as V, RepoRef as W, Source as X, Secrets as Y, StatusCategory as Z, ConnectionStringOptions as _, AuthEventType as a, WebhookDashboardInfo as at, DeploymentProject as b, CARDINALITY as c, Cardinality as d, Tooling as et, CardinalityFor as f, CiRunStatus as g, CiRunFilter as h, AuthEvent as i, Vault as it, Environments as j, Environment as k, CapabilityImpls as l, CiRun as m, Auth as n, TrackerDoctorReport as nt, AuthIdentity as o, WebhookVerificationError as ot, Ci as p, Ruleset as q, AuthDescription as r, TrackerUser as rt, AuthUser as s, isMulti as st, Analytics as t, ToolingDoctorReport as tt, CapabilityKey as u, CreateAuthUserInput as v, DeploymentTrigger as w, DeploymentProjectSettings as x, Deployment as y, Observability as z };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as Tooling, A as Environments, B as ProviderApiError, C as DeploymentTarget, D as DnsRecordType, E as DnsRecord, F as LifecycleSlot, G as ResolvedCapability, H as REQUIRED_CAPABILITIES, I as NormalizedAuthUser, J as Secrets, K as Ruleset, L as Notifications, M as IssueSearchFilter, N as Issues, O as Environment, P as LifecycleResult, Q as StorageBranch, R as Observability, S as DeploymentRecord, T as Dns, U as RepoRef, V as ProviderIdentity, W as RepoSettings, X as StatusCategory, Y as Source, Z as Storage, _ as ConnectionStringOptions, a as AuthEventType, at as WebhookVerificationError, b as DeploymentProject, c as CARDINALITY, d as Cardinality, et as ToolingDoctorReport, f as CardinalityFor, g as CiRunStatus, h as CiRunFilter, i as AuthEvent, it as WebhookDashboardInfo, j as Issue, k as EnvironmentReviewer, l as CapabilityImpls, m as CiRun, n as Auth, nt as TrackerUser, o as AuthIdentity, ot as isMulti, p as Ci, q as SecretScope, r as AuthDescription, rt as Vault, s as AuthUser, t as Analytics, tt as TrackerDoctorReport, u as CapabilityKey, v as CreateAuthUserInput, w as DeploymentTrigger, x as DeploymentProjectSettings, y as Deployment, z as ParseWebhookInput } from "./index-DDxKXqtR.mjs";
+import { $ as StorageBranch, A as EnvironmentReviewer, B as ParseWebhookInput, C as DeploymentTarget, D as DnsRecordType, E as DnsRecord, F as LifecycleResult, G as RepoSettings, H as ProviderIdentity, I as LifecycleSlot, J as SecretScope, K as ResolvedCapability, L as NormalizedAuthUser, M as Issue, N as IssueSearchFilter, O as EnsureResult, P as Issues, Q as Storage, R as Notifications, S as DeploymentRecord, T as Dns, U as REQUIRED_CAPABILITIES, V as ProviderApiError, W as RepoRef, X as Source, Y as Secrets, Z as StatusCategory, _ as ConnectionStringOptions, a as AuthEventType, at as WebhookDashboardInfo, b as DeploymentProject, c as CARDINALITY, d as Cardinality, et as Tooling, f as CardinalityFor, g as CiRunStatus, h as CiRunFilter, i as AuthEvent, it as Vault, j as Environments, k as Environment, l as CapabilityImpls, m as CiRun, n as Auth, nt as TrackerDoctorReport, o as AuthIdentity, ot as WebhookVerificationError, p as Ci, q as Ruleset, r as AuthDescription, rt as TrackerUser, s as AuthUser, st as isMulti, t as Analytics, tt as ToolingDoctorReport, u as CapabilityKey, v as CreateAuthUserInput, w as DeploymentTrigger, x as DeploymentProjectSettings, y as Deployment, z as Observability } from "./index-jxPVFH7-.mjs";
 
 //#region src/config.d.ts
 type ProviderOptions = Record<string, unknown>;
@@ -6,6 +6,22 @@ type SingleEntry = string | [provider: string, options: ProviderOptions];
 type MultiEntry = Array<string | [provider: string, options: ProviderOptions]>;
 type RawProviderEntry = SingleEntry | MultiEntry;
 type RawProvidersConfig = Partial<Record<CapabilityKey, RawProviderEntry>>;
+interface RepoPolicyConfig {
+  /**
+   * "balanced" — squash-only merges, delete-branch-on-merge, issues/discussions/projects
+   * enabled, auto-merge enabled, web sign-off required, always suggest updating, no wiki;
+   * plus a ruleset that blocks force-push + deletion and requires a pull request (0 reviews).
+   *
+   * "strict" — everything in "balanced" plus required status checks from `requiredChecks`.
+   *
+   * "none" — skips repo settings + ruleset entirely.
+   *
+   * @default "balanced"
+   */
+  preset?: "balanced" | "strict" | "none";
+  /** CI check context names required on the default branch (used by "strict"). */
+  requiredChecks?: string[];
+}
 interface AppConfig {
   name: string;
   path: string;
@@ -18,6 +34,31 @@ interface HolocronConfig {
   project: {
     name: string;
     description?: string;
+    /**
+     * Repo coord — `"owner/name"`. When set, `PluginLoader` injects
+     * it into every plugin's `RuntimeContext.repo` so plugins that
+     * need a repo (github, etc.) don't require `--repo` on every
+     * invocation. `--repo` on the command line still overrides.
+     */
+    repo?: string;
+    /**
+     * Repo-level policy applied by `holocron setup`. Defines merge
+     * strategy, branch protection rulesets, and security defaults.
+     * Requires `source` capability to be configured.
+     */
+    repoPolicy?: RepoPolicyConfig;
+    /**
+     * CI workflow names to install as thin wrappers during `holocron setup`.
+     * Each name maps to a reusable workflow in `theholocron/.github`.
+     *
+     * Supported values: "lint" | "test" | "typecheck" | "codeql" | "review" |
+     *   "release" | "stale" | "greetings" | "dependencies" | "bookkeeping-pr" | "audit"
+     *
+     * `holocron setup` writes `.github/workflows/<name>.yml` for each entry,
+     * calling the corresponding `ci-<name>.yml@main` reusable workflow.
+     * Files are overwritten on each run — they are generated artifacts.
+     */
+    workflows?: string[];
   };
   providers: RawProvidersConfig;
   apps?: AppConfig[];
@@ -30,15 +71,15 @@ interface ResolvedTuple {
   options: ProviderOptions;
 }
 type ResolvedProviderEntry = {
-  cardinality: 'single';
+  cardinality: "single";
   tuple: ResolvedTuple;
 } | {
-  cardinality: 'many';
+  cardinality: "many";
   tuples: ResolvedTuple[];
 };
 type ResolvedProvidersConfig = Partial<Record<CapabilityKey, ResolvedProviderEntry>>;
 interface ResolvedHolocronConfig {
-  project: HolocronConfig['project'];
+  project: HolocronConfig["project"];
   providers: ResolvedProvidersConfig;
   apps: AppConfig[];
   doctor: DoctorConfig;
@@ -55,4 +96,48 @@ declare function resolvePluginPackage(provider: string): string;
 declare function resolveEntry(key: CapabilityKey, raw: RawProviderEntry): ResolvedProviderEntry;
 declare function resolveConfig(raw: HolocronConfig): ResolvedHolocronConfig;
 //#endregion
-export { Analytics, AppConfig, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConfigError, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, DoctorConfig, Environment, EnvironmentReviewer, Environments, HolocronConfig, Issue, IssueSearchFilter, Issues, LifecycleResult, LifecycleSlot, MultiEntry, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoRef, RepoSettings, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, isMulti, resolveConfig, resolveEntry, resolvePluginPackage };
+//#region src/keyring.d.ts
+/**
+ * Keyring-backed bootstrap credential store.
+ *
+ * Every holocron plugin's bootstrap token (the one it needs before it
+ * can talk to its vendor's API) can be stored in the OS keyring under
+ * a single reverse-DNS service scope. Managed via `holocron auth`
+ * subcommands; consulted at position 4 in every plugin's auth
+ * precedence chain (after --token / HOLOCRON_<X>_TOKEN / <native>_TOKEN).
+ *
+ * See `.notes/tech-auth-bootstrap.spec.md` for the design rationale.
+ *
+ * Failure model: keyring access is best-effort. Platforms without a
+ * supported credential store (some Linux CI images, sandboxed
+ * environments) will throw from the underlying library. Every export
+ * here catches and returns a null/empty result rather than propagating
+ * — the plugin's precedence chain then falls through to
+ * env-var-only paths, which is exactly how CI is meant to work.
+ */
+/**
+ * Store or overwrite a bootstrap token for a provider. Returns true on
+ * success, false when the underlying keyring is unsupported or errored.
+ */
+declare function setToken(provider: string, token: string): boolean;
+/**
+ * Read the bootstrap token for a provider. Returns `null` for both
+ * "not stored" and "keyring unavailable" — callers can treat them the
+ * same way (fall through to env-var precedence).
+ */
+declare function getToken(provider: string): string | null;
+/**
+ * Delete a stored token. Returns true when a token was removed, false
+ * when there was nothing to delete or the keyring is unavailable.
+ * Distinguishing the two cases isn't worth the surface area — the
+ * command output makes the situation clear either way.
+ */
+declare function deleteToken(provider: string): boolean;
+/**
+ * List provider slugs with a stored token in this service scope.
+ * Uses the library's `findCredentials(service)` — supported on all
+ * platforms the underlying credential store supports.
+ */
+declare function listStoredProviders(): string[];
+//#endregion
+export { Analytics, AppConfig, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConfigError, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, DoctorConfig, EnsureResult, Environment, EnvironmentReviewer, Environments, HolocronConfig, Issue, IssueSearchFilter, Issues, LifecycleResult, LifecycleSlot, MultiEntry, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoPolicyConfig, RepoRef, RepoSettings, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, deleteToken, getToken, isMulti, listStoredProviders, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { a as isMulti, i as WebhookVerificationError, n as ProviderApiError, r as REQUIRED_CAPABILITIES, t as CARDINALITY } from "./capabilities-QjjhVlDd.mjs";
-import { i as resolvePluginPackage, n as resolveConfig, r as resolveEntry, t as ConfigError } from "./config-DWlIfFZm.mjs";
-export { CARDINALITY, ConfigError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, isMulti, resolveConfig, resolveEntry, resolvePluginPackage };
+import { a as isMulti, i as WebhookVerificationError, n as ProviderApiError, r as REQUIRED_CAPABILITIES, t as CARDINALITY } from "./capabilities-DapaKOlX.mjs";
+import { a as ConfigError, c as resolvePluginPackage, i as setToken, n as getToken, o as resolveConfig, r as listStoredProviders, s as resolveEntry, t as deleteToken } from "./keyring-DwNEmrBc.mjs";
+export { CARDINALITY, ConfigError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, deleteToken, getToken, isMulti, listStoredProviders, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

package/dist/{config-DWlIfFZm.mjs → keyring-DwNEmrBc.mjs}

@@ -1,4 +1,5 @@
-import { r as REQUIRED_CAPABILITIES, t as CARDINALITY } from "./capabilities-QjjhVlDd.mjs";
+import { r as REQUIRED_CAPABILITIES, t as CARDINALITY } from "./capabilities-DapaKOlX.mjs";
+import { Entry, findCredentials } from "@napi-rs/keyring";
 //#region src/config.ts
 /**
 * `holocron.config.json` schema, parser, and provider resolution.
@@ -110,4 +111,74 @@ function resolveConfig(raw) {
 	};
 }
 //#endregion
-export { resolvePluginPackage as i, resolveConfig as n, resolveEntry as r, ConfigError as t };
+//#region src/keyring.ts
+/**
+* Keyring-backed bootstrap credential store.
+*
+* Every holocron plugin's bootstrap token (the one it needs before it
+* can talk to its vendor's API) can be stored in the OS keyring under
+* a single reverse-DNS service scope. Managed via `holocron auth`
+* subcommands; consulted at position 4 in every plugin's auth
+* precedence chain (after --token / HOLOCRON_<X>_TOKEN / <native>_TOKEN).
+*
+* See `.notes/tech-auth-bootstrap.spec.md` for the design rationale.
+*
+* Failure model: keyring access is best-effort. Platforms without a
+* supported credential store (some Linux CI images, sandboxed
+* environments) will throw from the underlying library. Every export
+* here catches and returns a null/empty result rather than propagating
+* — the plugin's precedence chain then falls through to
+* env-var-only paths, which is exactly how CI is meant to work.
+*/
+const SERVICE = "com.theholocron.cli";
+/**
+* Store or overwrite a bootstrap token for a provider. Returns true on
+* success, false when the underlying keyring is unsupported or errored.
+*/
+function setToken(provider, token) {
+	try {
+		new Entry(SERVICE, provider).setPassword(token);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Read the bootstrap token for a provider. Returns `null` for both
+* "not stored" and "keyring unavailable" — callers can treat them the
+* same way (fall through to env-var precedence).
+*/
+function getToken(provider) {
+	try {
+		return new Entry(SERVICE, provider).getPassword();
+	} catch {
+		return null;
+	}
+}
+/**
+* Delete a stored token. Returns true when a token was removed, false
+* when there was nothing to delete or the keyring is unavailable.
+* Distinguishing the two cases isn't worth the surface area — the
+* command output makes the situation clear either way.
+*/
+function deleteToken(provider) {
+	try {
+		return new Entry(SERVICE, provider).deletePassword();
+	} catch {
+		return false;
+	}
+}
+/**
+* List provider slugs with a stored token in this service scope.
+* Uses the library's `findCredentials(service)` — supported on all
+* platforms the underlying credential store supports.
+*/
+function listStoredProviders() {
+	try {
+		return findCredentials(SERVICE).map((c) => c.account);
+	} catch {
+		return [];
+	}
+}
+//#endregion
+export { ConfigError as a, resolvePluginPackage as c, setToken as i, getToken as n, resolveConfig as o, listStoredProviders as r, resolveEntry as s, deleteToken as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cli",
-  "version": "2.0.0-alpha.0",
+  "version": "2.0.0-alpha.5",
   "description": "The Holocron CLI — a pluggable, capability-based orchestrator for spinning up and operating software projects.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/cli#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -33,6 +33,7 @@
     "README.md"
   ],
   "dependencies": {
+    "@napi-rs/keyring": "^1.3.0",
     "yargs": "^18.0.0",
     "@theholocron/cli-utils": "0.0.0"
   },