import type * as Command from "effect/cli/Command"; import type * as Flag from "effect/cli/Flag"; import * as Effect from "effect/Effect"; import * as FileSystem from "effect/FileSystem"; import type { HttpClient } from "effect/http/HttpClient"; import type * as HttpClientRequest from "effect/http/HttpClientRequest"; import type * as Layer from "effect/Layer"; import * as Path from "effect/Path"; import type * as Stream from "effect/Stream"; import type { AlchemyContext } from "./AlchemyContext.ts"; import type { ArtifactStore } from "./Artifacts.ts"; import type { AuthProviders } from "./Auth/AuthProvider.ts"; import type { CredentialsStore } from "./Auth/Credentials.ts"; import type { ProfileStore } from "./Auth/Profile.ts"; import type { Interaction } from "./Interaction.ts"; import type { State } from "./State/State.ts"; import { UserFacingError } from "./UserFacingError.ts"; import type { PlatformServices } from "./Util/PlatformServices.ts"; /** * What a provider contributes to Alchemy outside a stack: the parts the CLI, * the Alchemist API and the test harness need before (or without) importing * the user's `alchemy.run.ts`. * * A contributions module is imported on every CLI start, so it holds * metadata and lazy `import()`s only; the provider's code loads when a field * is used. * * A package declares what it contributes in `package.json`: * * ```json * { "alchemy": { "contributes": ["@alchemy.run/aws/Contributions"] } } * ``` * * {@link load} reads that field from `alchemy` itself and from the project's * dependencies. */ export interface Contributions { /** Unique across loaded providers, e.g. `"aws"`. */ readonly name: string; /** * Registers the provider's `AuthProvider` into `AuthProviders`, so * `alchemy profile` and login work without a stack that uses the provider. */ readonly auth?: Lazy>; /** * The provider's state stores by `--backend` name, e.g. `{ aws: ... }`, * each reachable from a profile alone as `alchemy state --backend `. * Names are global: two providers contributing one name is an error. */ readonly stateStores?: Readonly>; /** CLI commands the provider adds. */ readonly cli?: Cli; /** * Services the test harness runs tests under when `ALCHEMY_TEST_DEV` is * set, e.g. a local emulator for the provider's SDK clients. */ readonly testServices?: Lazy; /** * Environment variables `alchemy dev` sets on itself before it starts, so * its sidecars and the processes they launch inherit them, e.g. a local * emulator's CA bundle. A variable that is already set wins. */ readonly devEnv?: Lazy>, never, FileSystem.FileSystem | Path.Path>>; } /** * The services every host of provider code provides: the CLI and the Alchemist * API both run it under them. A provider supplies anything else it needs * itself, so a field can never require a service no host provides. */ export type HostServices = PlatformServices | HttpClient | AlchemyContext | ProfileStore | CredentialsStore | ArtifactStore | Interaction; /** What auth layers and state stores run under: the host's services and the auth registry. */ export type ContributionServices = HostServices | AuthProviders; /** What a CLI command runs under: the host's services, `Interaction` included. */ export type CliServices = HostServices; /** A provider's own failure: any tagged error with a message for the user. */ export type ContributionFailure = { readonly _tag: string; readonly message: string; }; /** * A field loaded when used, so importing a provider module stays cheap. Build * one with {@link lazy}. */ export type Lazy = Effect.Effect; /** * A {@link Lazy} field from a module of the provider's, imported on first * use: * * ```ts * auth: Contributions.lazy(() => import("./AuthProvider.ts"), (module) => module.AwsAuth), * ``` */ export declare const lazy: (load: () => Promise, pick: (module: M) => A) => Lazy; export interface StateStore { /** Shown when listing stores; no provider code loads to show it. */ readonly description: string; /** * The flags `alchemy state` takes for this store with `--backend`, for what * a profile alone can't tell it: a store other than the default, or where * it is served. Each parses into the store's options under its key. Flags * are built without loading the store, and the CLI makes each optional: one * that isn't given is `undefined`, so the store applies its own default. * A flag with a default would always be set, for every backend, so it is * left out. * * ```ts * flags: { * domain: Flag.String("domain").pipe(Flag.withDescription("Hostname the store is served on")), * }, * ``` * * Stores that set the same option with the same flag, parsed the same way, * share it on the command line, and its help lists each store's * description. A flag is left out, with a warning, when it is optional, has * a default or an alias, when it conflicts with another store's flags, or when it * clashes with one of `alchemy state`'s own. * * {@link make} checks the store's options interface against these: each * flag's value must be what the store accepts under the same key. */ readonly flags?: StateStoreFlags; /** The store itself, loaded when it's used. */ readonly load: Lazy>; } /** A state store's CLI flags, by the option key each parses into. */ export type StateStoreFlags = Readonly>>; /** What a store's {@link StateStoreFlags} parse into: each optional, by key. */ export type StateStoreFlagValues = { readonly [K in keyof Flags]?: Flags[K] extends Flag.Flag ? A : never; }; /** * A provider's state store. `Options` is the store's own options interface, * what its layer and lifecycle accept; the CLI fills it from the store's * {@link StateStore.flags}. */ export interface StateStoreImpl { /** The store's `State` layer: the provider's own `state` function. */ readonly layer: (options?: Options) => Layer.Layer; /** Provisioning, teardown and logs, for the operations the store supports. */ readonly lifecycle?: StateStoreLifecycle; } /** * Options given to a store, by key. Only keys the store has flags for appear, * and only when they were set; the store uses its default for the rest. */ export type StateStoreOptions = Readonly>; /** * A store's lifecycle operations. Each takes the store's own options spread * into its input, defaults for any not given. */ export interface StateStoreLifecycle { /** Provision the store, or adopt it when it exists. Idempotent. */ readonly bootstrap?: (input: Options & { /** Redeploy an existing store instead of adopting it. */ readonly force?: boolean; }) => Effect.Effect; /** Delete the store and its backing resources. Idempotent. */ readonly teardown?: (input: Options) => Effect.Effect; /** The store's past log entries, oldest first. */ readonly logs?: (input: Options & { readonly limit?: number; readonly since?: Date; }) => Effect.Effect, ContributionFailure, ContributionServices>; /** The store's log entries as they happen. */ readonly tailLogs?: (input: Options) => Stream.Stream; } export interface StateStoreBootstrap { readonly status: "created" | "adopted" | "redeployed"; /** The store's physical name: its Worker, its bucket. */ readonly store: string; /** Where it lives, e.g. `{ account: "…", region: "us-east-1" }`. */ readonly location: Readonly>; } export interface StateStoreTeardown { /** What was deleted, by physical name. */ readonly deleted: ReadonlyArray; } export interface StateStoreLogEntry { readonly timestamp: Date; readonly message: string; } export interface Cli { /** * The `alchemy provider ` subcommand. Its description lists it * in help; the command itself loads only when it runs. */ readonly provider?: { readonly description: string; readonly load: Lazy; }; } export type AnyCommand = Command.Command; export interface TestServices { /** Provided to test bodies and stack programs, closest wins. */ readonly layer: Layer.Layer; /** Rewrites the test's outbound HTTP, e.g. onto the emulator's gateway. */ readonly mapRequest?: (request: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest; /** Set on the test process before anything forks, unless already set. */ readonly env?: Readonly>; } /** Declare a provider; the identity function, keeping its literal type. */ /** * Keys a store option can't take: the ones `Alchemist.State` sources and * lifecycle inputs already use, which the options are spread next to. */ type ReservedStateStoreOptionKey = "type" | "backend" | "profile" | "envFile" | "force" | "limit" | "since"; /** * Each state store checked against its flags: every flag sets an option the * store declares, under a key that isn't reserved, and the store accepts the * value the flag parses into. */ type CheckedStateStores

= P extends { readonly stateStores: infer Stores; } ? { readonly stateStores: { readonly [K in keyof Stores]: Stores[K] extends { readonly flags: infer Flags; readonly load: Lazy>; } ? { readonly flags: { readonly [F in keyof Flags]: F extends ReservedStateStoreOptionKey ? never : F extends keyof Options ? Flags[F] : never; }; readonly load: Lazy>>; } : unknown; }; } : unknown; export declare const make: (provider: P & NoInfer>) => P; declare const ContributionError_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & { readonly _tag: "ContributionError"; } & Readonly; export declare class ContributionError extends ContributionError_base<{ readonly message: string; readonly cause?: unknown; }> { readonly [UserFacingError] = true; } /** `--backend` names alchemy handles itself, so no provider may take them. */ export declare const RESERVED_BACKENDS: ReadonlyArray; /** The providers reachable from the project in `cwd`, loaded once per process. */ export declare const load: (cwd?: string | undefined) => Effect.Effect; /** The environment every provider contributes to `alchemy dev` (see {@link Contributions.devEnv}). */ export declare const devEnv: () => Effect.Effect, ContributionError, FileSystem.FileSystem | Path.Path>; /** Every provider's state stores, by `--backend` name, with their provider. */ export declare const stateStores: () => Effect.Effect, ContributionError, FileSystem.FileSystem | Path.Path>; /** Load one lazy field, failing with a {@link ContributionError} naming the provider. */ export declare const resolve: (provider: Contributions, field: string, value: Lazy) => Effect.Effect; export {}; //# sourceMappingURL=Contributions.d.ts.map