import { pathToFileURL } from "node:url"; import type * as Command from "effect/cli/Command"; import type * as Flag from "effect/cli/Flag"; import * as Data from "effect/Data"; 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 * as Predicate from "effect/Predicate"; import * as Schema from "effect/Schema"; 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< Effect.Effect>, 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 const lazy = (load: () => Promise, pick: (module: M) => A): Lazy => Effect.tryPromise({ try: load, catch: (cause) => new ContributionError({ message: "Could not import a provider module", cause }), }).pipe(Effect.map(pick)); 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; }; } // Any command, whatever its name, errors and the CLI services it runs under. 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 const make = ( provider: P & NoInfer>, ): P => provider; export class ContributionError extends Data.TaggedError("ContributionError")<{ readonly message: string; readonly cause?: unknown; }> { readonly [UserFacingError] = true; } const Manifest = Schema.Struct({ name: Schema.optional(Schema.String), main: Schema.optional(Schema.String), exports: Schema.optional(Schema.Unknown), dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)), devDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)), alchemy: Schema.optional( Schema.Struct({ contributes: Schema.String.pipe(Schema.Array, Schema.optional) }), ), }); const readManifest = Effect.fn(function* (file: string) { const fs = yield* FileSystem.FileSystem; if (!(yield* fs.exists(file))) return undefined; const text = yield* fs.readFileString(file); return yield* Effect.try({ try: (): unknown => JSON.parse(text), catch: (cause) => new ContributionError({ message: `Invalid JSON in ${file}`, cause }), }).pipe( Effect.flatMap(Schema.decodeUnknownEffect(Manifest)), Effect.mapError( (cause) => new ContributionError({ message: `Invalid package manifest ${file}`, cause }), ), ); }); /** Find `node_modules//package.json` from `dir` upwards. */ const findDependencyManifest = Effect.fn(function* (dir: string, name: string) { const fs = yield* FileSystem.FileSystem; const path = yield* Path.Path; let current = dir; while (true) { const candidate = path.join(current, "node_modules", name, "package.json"); if (yield* fs.exists(candidate)) return candidate; const parent = path.dirname(current); if (parent === current) return undefined; current = parent; } }); /** * The packages a project in `dir` can contribute providers from: the direct * dependencies of every `package.json` from `dir` up (a workspace package and * the monorepo root above it), plus every installed `@alchemy.run/*` package * reachable from `dir`, which a monorepo root can import without listing. */ const candidatePackages = Effect.fn(function* (dir: string) { const fs = yield* FileSystem.FileSystem; const path = yield* Path.Path; const names = new Set(); let current = dir; while (true) { const manifest = yield* readManifest(path.join(current, "package.json")); for (const name of Object.keys({ ...manifest?.dependencies, ...manifest?.devDependencies })) { names.add(name); } const scope = path.join(current, "node_modules", PACKAGE_SCOPE); if (yield* fs.exists(scope)) { for (const entry of yield* fs.readDirectory(scope)) names.add(`${PACKAGE_SCOPE}/${entry}`); } const parent = path.dirname(current); if (parent === current) return names; current = parent; } }); /** The root `package.json` name of alchemy's own monorepo. */ const MONOREPO_NAME = "@alchemy.run/monorepo"; /** * The `package.json` of every sibling package when alchemy runs from its own * monorepo checkout (`packages/alchemy` under a root named * {@link MONOREPO_NAME}). Empty for every installed copy of alchemy. */ const monorepoManifests = Effect.gen(function* () { const fs = yield* FileSystem.FileSystem; const path = yield* Path.Path; const own = path.dirname(yield* path.fromFileUrl(new URL("../package.json", import.meta.url))); const packages = path.dirname(own); const root = yield* readManifest(path.join(path.dirname(packages), "package.json")).pipe( Effect.orElseSucceed(() => undefined), ); if (root?.name !== MONOREPO_NAME) return []; const files: string[] = []; for (const entry of yield* fs.readDirectory(packages)) { const file = path.join(packages, entry, "package.json"); if (path.join(packages, entry) !== own && (yield* fs.exists(file))) files.push(file); } return files.sort(); }); /** The npm scope of alchemy's own provider packages. */ const PACKAGE_SCOPE = "@alchemy.run"; /** A provider specifier, and the manifest that declared it when not alchemy's own. */ interface Declared { readonly specifier: string; readonly manifest?: { readonly file: string; readonly directory: string; readonly name: string | undefined; readonly main: string | undefined; readonly exports: unknown; }; } /** * The conditions an ESM `import` matches. Node picks the first matching key in * the `exports` object's own order, so only membership matters here. */ const importConditions = new Set( typeof Bun !== "undefined" ? ["bun", "import", "node", "default"] : ["import", "node", "default"], ); /** An `exports` target under {@link importConditions}, with `*` filled in. */ const exportTarget = (target: unknown, star: string): string | undefined => { if (typeof target === "string") return target.replaceAll("*", star); if (Array.isArray(target)) { for (const candidate of target) { const resolved = exportTarget(candidate, star); if (resolved !== undefined) return resolved; } return undefined; } if (typeof target === "object" && target !== null) { for (const [condition, value] of Object.entries(target)) { if (!importConditions.has(condition)) continue; const resolved = exportTarget(value, star); if (resolved !== undefined) return resolved; } } return undefined; }; /** A package's own subpath (`"."`, `"./Contributions"`) through its `exports` map. */ const packageExport = (exports: unknown, main: string | undefined, subpath: string) => { if (exports === undefined) return subpath === "." ? (main ?? "./index.js") : subpath; const entries = typeof exports === "object" && exports !== null && !Array.isArray(exports) ? Object.entries(exports) : []; // Subpath keys, or the package's one export ("exports": "./index.js"). const map = new Map( entries.some(([key]) => key.startsWith(".")) ? entries : [[".", exports]], ); if (map.has(subpath)) return exportTarget(map.get(subpath), ""); for (const [pattern, target] of map) { const star = pattern.indexOf("*"); if (star === -1) continue; const prefix = pattern.slice(0, star); const suffix = pattern.slice(star + 1); if (subpath.startsWith(prefix) && subpath.endsWith(suffix)) { return exportTarget(target, subpath.slice(prefix.length, subpath.length - suffix.length)); } } return undefined; }; /** * Resolve a dependency's provider from the dependency itself, through its own * `exports` with ESM import conditions: under pnpm alchemy usually can't see * a project's dependencies, and a CommonJS resolver would pick `require` * targets for a module loaded with `import()`. A provider specifier must name * the package that declares it. */ const resolveDeclared = ({ specifier, manifest }: Declared) => Effect.gen(function* () { if (manifest === undefined) return specifier; const path = yield* Path.Path; const { name } = manifest; if (name === undefined || (specifier !== name && !specifier.startsWith(`${name}/`))) { return yield* new ContributionError({ message: `${specifier}, contributed by ${manifest.file}, must name that package (${name ?? "unnamed"})`, }); } const subpath = specifier === name ? "." : `.${specifier.slice(name.length)}`; const target = packageExport(manifest.exports, manifest.main, subpath); if (target === undefined) { return yield* new ContributionError({ message: `${specifier} is not exported for import by ${manifest.file}`, }); } return pathToFileURL(path.join(manifest.directory, target)).href; }); /** A module's default export as contributions; only the name is checked. */ const isContributions = (value: unknown): value is Contributions => Predicate.hasProperty(value, "name") && typeof value.name === "string"; const importContributions = (declared: Declared) => Effect.flatMap(resolveDeclared(declared), (url) => Effect.tryPromise({ try: (): Promise<{ readonly default?: unknown }> => import(url), catch: (cause) => new ContributionError({ message: `Could not import ${declared.specifier}`, cause }), }), ).pipe( Effect.flatMap((module) => isContributions(module.default) ? Effect.succeed(module.default) : Effect.fail( new ContributionError({ message: `${declared.specifier} has no default export`, }), ), ), ); const discover = Effect.fn("Contributions.discover")(function* (cwd: string) { const path = yield* Path.Path; const declared = new Map(); const own = yield* readManifest( yield* path.fromFileUrl(new URL("../package.json", import.meta.url)), ); // The project's packages that declare providers, before alchemy's own: the // first provider with a name wins, so a provider that moved into its own // package replaces the copy still inside alchemy. const declare = Effect.fn(function* (file: string, fallback = false) { const manifest = yield* readManifest(file); for (const specifier of manifest?.alchemy?.contributes ?? []) { if (fallback && declared.has(specifier)) continue; declared.set(specifier, { specifier, manifest: { file, directory: path.dirname(file), name: manifest?.name, main: manifest?.main, exports: manifest?.exports, }, }); } }); const dependencies = [...(yield* candidatePackages(cwd))].filter((name) => name !== own?.name); for (const name of dependencies) { const file = yield* findDependencyManifest(cwd, name); if (file !== undefined) yield* declare(file); } // Developing alchemy itself: every package in the monorepo, so the CLI sees // all providers without the root installing them. Installed copies win. for (const file of yield* monorepoManifests) { yield* declare(file, true).pipe( Effect.catch((error) => Effect.logDebug(`Skipping ${file}: ${error.message}`)), ); } // alchemy's own: the providers that still live in this package. for (const specifier of own?.alchemy?.contributes ?? []) declared.set(specifier, { specifier }); // A provider that fails to load is skipped, never the rest; the first provider // with a name wins. const providers = new Map(); for (const declaration of declared.values()) { const provider = yield* importContributions(declaration).pipe( Effect.catch((error) => Effect.as( Effect.logWarning(`Skipping ${declaration.specifier}: ${error.message}`), undefined, ), ), ); if (provider === undefined) continue; if (providers.has(provider.name)) { // Expected for alchemy's own copy of a provider that moved out. yield* (declaration.manifest ? Effect.logWarning : Effect.logDebug)( `Skipping ${declaration.specifier}: the name ${provider.name} is taken`, ); continue; } providers.set(provider.name, provider); } return [...providers.values()]; }); /** `--backend` names alchemy handles itself, so no provider may take them. */ export const RESERVED_BACKENDS: ReadonlyArray = ["local", "configured"]; const loaded = new Map, ContributionError>>(); /** The providers reachable from the project in `cwd`, loaded once per process. */ export const load = Effect.fn("Contributions.load")(function* (cwd?: string) { const dir = cwd ?? (yield* Effect.sync(() => process.cwd())); let cached = loaded.get(dir); if (cached === undefined) { cached = yield* Effect.cached( discover(dir).pipe( Effect.mapError((error) => error._tag === "ContributionError" ? error : new ContributionError({ message: "Could not read package manifests", cause: error }), ), Effect.provideService(FileSystem.FileSystem, yield* FileSystem.FileSystem), Effect.provideService(Path.Path, yield* Path.Path), ), ); loaded.set(dir, cached); } return yield* cached; }); /** The environment every provider contributes to `alchemy dev` (see {@link Contributions.devEnv}). */ export const devEnv = Effect.fn("Contributions.devEnv")(function* () { const env: Record = {}; for (const provider of yield* load()) { if (provider.devEnv === undefined) continue; const contribute = yield* resolve(provider, "devEnv", provider.devEnv); Object.assign(env, yield* contribute); } return env; }); /** Every provider's state stores, by `--backend` name, with their provider. */ export const stateStores = Effect.fn("Contributions.stateStores")(function* () { const stores = new Map< string, { readonly provider: Contributions; readonly store: StateStore } >(); for (const provider of yield* load()) { for (const [backend, store] of Object.entries(provider.stateStores ?? {})) { // A state backend name addresses one store, so two providers can't share it. const owner = RESERVED_BACKENDS.includes(backend) ? "alchemy" : stores.get(backend)?.provider.name; if (owner !== undefined) { return yield* new ContributionError({ message: `${provider.name} and ${owner} both contribute a state store named ${backend}`, }); } stores.set(backend, { provider, store }); } } return stores; }); /** Load one lazy field, failing with a {@link ContributionError} naming the provider. */ export const resolve = (provider: Contributions, field: string, value: Lazy) => value.pipe( Effect.mapError( (cause) => new ContributionError({ message: `Could not load ${provider.name}'s ${field}: ${cause.message}`, cause, }), ), );