@penvhq/provider-github 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -1,4 +1,341 @@
-import { PenvError, ProviderFactoryContext, ProjectionProvider, SecretScope, ProjectionSecret, ParameterRef, PenvConfig, PenvErrorLike } from '@penvhq/core';
+/** Identifies one parameter, independent of scope. `redis/password`. */
+interface ParameterRef {
+    /** Namespace folder segments. `[]` for a root parameter. */
+    readonly namespace: readonly string[];
+    /** The parameter's own name. `password`. */
+    readonly name: string;
+}
+/**
+ * The provider config types penv knows about, keyed by package name. Empty here,
+ * deliberately: core owns the `Provider` contract and must not know which
+ * implementations exist. Each provider package augments this interface with its
+ * own config shape under its own name —
+ *
+ * ```ts
+ * declare module "@penvhq/core" {
+ *   interface ProviderConfigMap {
+ *     "@penvhq/provider-vault": VaultProviderConfig;
+ *   }
+ * }
+ * ```
+ *
+ * — so the compile-time union is exactly the set of providers the project has
+ * installed, and {@link defineConfig} can hold a known `type`'s fields to the
+ * provider's own declaration while leaving an unknown `type` the open base shape.
+ */
+interface ProviderConfigMap {
+}
+/** The provider package names whose config types are installed and merged in. */
+type KnownProviderType = keyof ProviderConfigMap & string;
+interface ProviderConfig {
+    /**
+     * The provider package's fully-qualified name — `"@penvhq/provider-vault"`.
+     * The name is the import specifier: penv resolves it from the project's own
+     * `node_modules`, so declaring a provider and installing its package are the
+     * same decision stated twice, and the config never needs a second field to
+     * say where the implementation lives.
+     */
+    readonly type: KnownProviderType | (string & {});
+    /**
+     * The place inside the provider that penv maps the tree onto. The format is
+     * the provider's own — a Vault KV base path, a Kubernetes
+     * `namespace/secretName` — and its package's config type documents it; the
+     * field name never changes between providers.
+     */
+    readonly location?: string;
+    /** Fields beyond `location` belong to the provider's own config type. */
+    readonly [key: string]: unknown;
+}
+/**
+ * What penv hands a provider package's `penvProviderFactory` to build a provider
+ * for one project. Declared here because it is the seam every provider package
+ * builds against — the CLI supplies it, the package consumes it, and neither
+ * imports the other's internals.
+ */
+interface ProviderFactoryContext {
+    /**
+     * The project root — the directory holding `penv.config.ts` — absolute. It is
+     * the project rather than any directory inside it because where penv keeps its
+     * own state is penv's business: a provider that needs a path derives it from
+     * the root, and one that needs none is unaffected when the layout moves.
+     */
+    readonly root: string;
+    /**
+     * Required because a provider parses environment segments, and a segment is an
+     * environment only if the config declares it — never inferred from the store.
+     */
+    readonly config: PenvConfig;
+    /**
+     * The one environment's own `providers.*` entry, when building its declared
+     * source of truth. Carries provider-side settings — the `location` above all —
+     * that the config authored, never inferred.
+     */
+    readonly providerConfig?: ProviderConfig;
+    /**
+     * The environment this provider is the source of truth *for*, when that is
+     * what is being built.
+     */
+    readonly environment?: string;
+}
+/**
+ * The schema's inferred shape, registered by the schema module so the config
+ * file can be typed against it. Empty here, deliberately — core must not depend
+ * on Zod or know any one project's schema. The scaffolded `penv.schema.ts`
+ * augments it with the *inferred* shape (computed where Zod lives), beside the
+ * `z.object` it registers — the thin `.penv/env.ts` wrapper only re-exports that
+ * shape and loads it:
+ *
+ * ```ts
+ * declare module "@penvhq/core" {
+ *   interface PenvSchemaShape {
+ *     readonly shape: z.infer<typeof schema>;
+ *   }
+ * }
+ * ```
+ *
+ * The augmentation is type-only and erased at runtime, so nothing cycles: the
+ * config never imports the schema module, yet `override` keys autocomplete from
+ * it whenever both files sit in one TypeScript program. A project that never
+ * registers a shape keeps the open `string` keys.
+ */
+interface PenvSchemaShape {
+}
+/** camelCase → kebab-case at the type level, mirroring `kebabSegment` exactly. */
+type KebabCase<S extends string> = S extends `${infer Head}${infer Tail}` ? Head extends Uppercase<Head> ? Head extends Lowercase<Head> ? `${Head}${KebabCase<Tail>}` : `-${Lowercase<Head>}${KebabCase<Tail>}` : `${Head}${KebabCase<Tail>}` : S;
+type ParameterIdsOf<T> = {
+    [K in keyof T & string]: NonNullable<T[K]> extends readonly unknown[] ? KebabCase<K> : NonNullable<T[K]> extends Date ? KebabCase<K> : NonNullable<T[K]> extends Record<string, unknown> ? `${KebabCase<K>}/${ParameterIdsOf<NonNullable<T[K]>>}` : KebabCase<K>;
+}[keyof T & string];
+/** The registered shape, or `never` when no schema module has registered one. */
+type RegisteredShape = PenvSchemaShape extends {
+    readonly shape: infer S;
+} ? S : never;
+/**
+ * The `override` block's key type: every parameter id the registered schema
+ * implies — so a typo is a compile error — or plain `string` when no shape is
+ * registered.
+ */
+type OverrideKey = [RegisteredShape] extends [never] ? string : ParameterIdsOf<RegisteredShape>;
+/** The `override` block: parameter id → the exact variable a consumer expects. */
+type OverrideBlock = Readonly<Partial<Record<OverrideKey, string>>>;
+/**
+ * What a provider's store can honestly do — the declaration that replaced the
+ * old sink/provider split. The distinction the split guarded is real (GitHub
+ * Actions Secrets never returns a value) and lives here now, in the contract,
+ * instead of in a second config key the user had to learn.
+ */
+interface ProviderCapabilities {
+    /**
+     * What the store holds. `records`: penv records verbatim — opaque envelope
+     * strings at every scope, meta as a sibling record — the shape the behavioural
+     * contract suite gates. `projection`: a resolved projection — generated
+     * variable names, both `.local` scopes skipped, plaintext for the destination
+     * to re-seal — the shape a CI secret store consumes.
+     */
+    readonly holds: "records" | "projection";
+    /**
+     * Whether stored values can be read back. GitHub's API returns names and
+     * timestamps, never values, so it declares `false` — and `pull` materialises
+     * names and meta while `doctor` reports value drift as unknown, never as
+     * clean.
+     */
+    readonly readsValues: boolean;
+}
+/**
+ * Where one environment's encryption key comes from. Declared, never guessed: a
+ * key source penv picked for you is a key you did not choose.
+ */
+interface KeyConfig {
+    readonly source: "env" | "keychain";
+    /**
+     * Names the key. Written into every value file sealed under it, so it must
+     * outlive any one machine — and cannot contain `:`, which separates the
+     * envelope's fields.
+     */
+    readonly id: string;
+}
+interface PenvConfig {
+    /**
+     * The whitelist of valid environment names — the only source of truth for
+     * what counts as an environment. Segments are matched against this list,
+     * never inferred from folders or filenames.
+     */
+    readonly environments: readonly string[];
+    readonly providers: Readonly<Record<string, ProviderConfig>>;
+    /**
+     * The environment a command acts on when `--env` is absent and nothing in the
+     * environment says otherwise. It must be one of {@link environments}.
+     *
+     * A declared decision, not inference: invariant 10 is untouched, because the
+     * name still comes from this file rather than from a branch, a folder, or
+     * `NODE_ENV`. It exists so the daily command is `penv run -- pnpm dev` instead
+     * of a flag retyped all day. CI names `--env` anyway — a pipeline that leans on
+     * this key is one config edit away from deploying the wrong environment.
+     */
+    readonly defaultEnvironment?: string;
+    /**
+     * Where the module holding the schema lives, relative to this config.
+     * Defaults to `.penv/env.ts`.
+     *
+     * A path rather than a convention because the file is the user's (invariant 2)
+     * — a file penv insists on owning the location of is not fully theirs, and
+     * `src/env.ts` is where most projects would put it. Nothing downstream moves
+     * when it does: consumers import `@env`, and the alias is what penv writes.
+     */
+    readonly schemaFile?: string;
+    /**
+     * The variable-name prefixes a framework inlines into its client bundle —
+     * `NEXT_PUBLIC_`, `VITE_`.
+     *
+     * penv does not enforce these; the framework already does. Declaring them is
+     * what lets `doctor` catch the one mistake neither penv nor the framework can
+     * catch alone: a parameter meta declares `secret` whose name makes the
+     * framework ship it to a browser. To the framework the prefix *is* the intent,
+     * so only penv — holding both the policy and the name — can see the
+     * contradiction.
+     */
+    readonly publicPrefixes?: readonly string[];
+    /**
+     * Overrides the generated variable for a parameter, when a consumer demands a
+     * name the default transform would not produce — the WorkOS SDK reading
+     * `NEXT_PUBLIC_WORKOS_REDIRECT_URI`, a deploy target expecting `DATABASE_URL`
+     * spelled its way. One override bends the name for every consumer at once:
+     * `generate`, `push`, and the ambient mirror all read it. Collision-checked.
+     *
+     * Keys are parameter ids (`workos/redirect-uri`). When the schema module
+     * registers its shape (see {@link PenvSchemaShape}), the keys narrow to the
+     * parameters the schema actually declares — a typo'd id becomes a compile
+     * error instead of an override that silently never applies.
+     */
+    readonly override?: OverrideBlock;
+    /**
+     * Where each environment's encryption key lives. An environment with no entry
+     * has no key source, which is not the same as having no key — see `keys.ts`.
+     */
+    readonly keys?: Readonly<Record<string, KeyConfig>>;
+}
+/**
+ * Which destination store a value lands in. The two members are penv's own
+ * precedence axis wearing the destination's names: the unscoped default is the
+ * value every context falls back to (`repository`), an environment-scoped value
+ * belongs to exactly one (`environment`). GitHub resolves the two in penv's own
+ * order — environment over repository — so the cascade is reproduced by the
+ * destination's native mechanism rather than flattened at the boundary.
+ */
+type SecretScope = {
+    readonly kind: "repository";
+} | {
+    readonly kind: "environment";
+    readonly environment: string;
+};
+/** One secret as a value-withholding store reports it: a name and when it last changed, never a value. */
+interface ProjectionSecret {
+    readonly name: string;
+    /** The destination's last-modified time, ISO 8601. Compared against penv's last-push time to catch a hand-edit. */
+    readonly updatedAt: string;
+}
+/**
+ * A provider whose store holds a resolved *projection* rather than penv records
+ * — generated variable names, both `.local` scopes skipped, plaintext the
+ * destination re-seals under its own custody. It declares
+ * `capabilities.holds: "projection"` and satisfies this contract instead of the
+ * seven-method record contract, which its store cannot honestly implement: a
+ * `read` that can never return a value would make every downstream check read
+ * an unreadable store as an empty one.
+ *
+ * penv resolves the tree; the projection receives it. `push` speaks this
+ * surface; `pull` materialises what `list` can honestly give — names and
+ * timestamps, never values.
+ */
+interface ProjectionProvider {
+    readonly type: string;
+    readonly capabilities: ProviderCapabilities & {
+        readonly holds: "projection";
+    };
+    /**
+     * Confirms the destination is reachable before the first push. Every name is
+     * already judged up front, so a push never places half its secrets and then
+     * hits a reserved name; this closes the other pre-push gap — the destination
+     * being unreachable. GitHub through `gh` checks it is installed, authenticated,
+     * and can reach this repository's secrets, and refuses loudly rather than
+     * falling back. Resolves when it is safe to push.
+     */
+    verify(): Promise<void>;
+    /**
+     * Sends one value to the destination, which seals it under its own key. The
+     * value crosses in plaintext because a CI runner holds no penv key — penv's
+     * encryption stops at the projection and the destination's custody takes over.
+     */
+    push(name: string, value: string, scope: SecretScope): Promise<void>;
+    /**
+     * The names the destination holds at a scope, each with its last-modified
+     * time. Listing names is the one read a value-withholding store allows.
+     */
+    list(scope: SecretScope): Promise<ProjectionSecret[]>;
+    /**
+     * The destination's own name grammar, judged before the first PUT. The rules
+     * are the destination's (GitHub's reserved `GITHUB_` prefix, its charset, its
+     * case-insensitivity), so the provider owns the check — the CLI only insists
+     * it runs before anything is pushed, never mid-push.
+     */
+    checkNames?(refs: readonly ParameterRef[], config: PenvConfig): PenvErrorLike[];
+    /**
+     * Whether the destination-side target an environment's push lands in exists
+     * yet — a GitHub deployment environment, say. Implemented only where the
+     * destination has such a notion.
+     */
+    targetExists?(environment: string): Promise<boolean>;
+    /**
+     * Creates the destination-side target for an environment. Never called
+     * without an explicit go-ahead: the CLI prompts (or `--yes` pre-approves) and
+     * only then asks the provider, which stays non-interactive. Creation on an
+     * explicit answer, never a guess — a typo'd environment name must not summon
+     * infrastructure.
+     */
+    ensureTarget?(environment: string): Promise<void>;
+}
+/**
+ * The error shape {@link ProjectionProvider.checkNames} returns — structurally
+ * `PenvError`, stated as an interface so the contract does not force provider
+ * packages to subclass core's error class. It is also what a refusal thrown by a
+ * self-contained extension arrives as: `isPenvErrorLike` is the test penv runs
+ * on one, since the class it was built from is the extension's own copy.
+ */
+interface PenvErrorLike extends Error {
+    readonly code: string;
+    readonly remedy?: string | undefined;
+}
+
+/**
+ * Named errors. Every message names the parameter and environment, says what is
+ * wrong, and says how to fix it. Never `Something went wrong`.
+ *
+ * A penv error also renders itself the way the CLI renders one. The CLI can
+ * format what it catches, but the refusals thrown by the application's bridge
+ * are caught by nobody — an app started without `penv run` prints them through
+ * Node's default uncaught-exception handler, which prints `stack`. So `stack`
+ * carries the refusal first and the remedy behind the same arrow every command
+ * prints, and the frames below it are the caller's, not penv's.
+ */
+
+declare class PenvError extends Error {
+    readonly name: string;
+    /** A stable, machine-readable discriminator. */
+    readonly code: string;
+    /** What the user should do about it. */
+    readonly remedy: string | undefined;
+    /** The message alone, without the remedy the constructor folds into it. */
+    readonly summary: string;
+    constructor(code: string, message: string, remedy?: string);
+    /**
+     * Drops every frame from `below` upward, so the stack shows where the
+     * application called in rather than the path penv took inside itself. The
+     * caller names its own entry point; nothing here guesses which files are
+     * penv's.
+     */
+    hideFramesAbove(below: (...args: never[]) => unknown): this;
+    /** The refusal as every penv command prints it: the message, then the remedy. */
+    toString(): string;
+}
 
 /**
  * The provider's own errors, extending penv's base so they print with a remedy and
@@ -45,17 +382,6 @@ declare class GithubUnavailableError extends PenvError {
  * learns GitHub vocabulary and the provider never parses config.
  */
 
-declare module "@penvhq/core" {
-    interface ProviderConfigMap {
-        "@penvhq/provider-github": {
-            /**
-             * The repository penv maps the projection onto — `owner/repo`. Left
-             * unset, `gh` resolves it from the working directory.
-             */
-            readonly location?: string;
-        };
-    }
-}
 /** Builds the GitHub provider for one environment's declared destination. */
 declare function penvProviderFactory(context: ProviderFactoryContext): ProjectionProvider;