The best way to control Claude Code, Codex and more from any computer or phone

main
ts 377 lines 12.2 KB
Raw
1 import type { ConfigError } from "effect/Config";
2 import * as Context from "effect/Context";
3 import type { Digest } from "effect/crypto/Digest";
4 import type { SecureRandom } from "effect/crypto/SecureRandom";
5 import * as Effect from "effect/Effect";
6 import { FileSystem } from "effect/FileSystem";
7 import type { HttpClient } from "effect/http/HttpClient";
8 import * as Layer from "effect/Layer";
9 import * as Option from "effect/Option";
10 import { Path } from "effect/Path";
11 import type { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
12 import type * as Scope from "effect/Scope";
13 import type { ActionLike } from "./Action.ts";
14 import type { AlchemyContext } from "./AlchemyContext.ts";
15 import type { ArtifactStore } from "./Artifacts.ts";
16 import type { CredentialsStore } from "./Auth/Credentials.ts";
17 import type { ProfileStore } from "./Auth/Profile.ts";
18 import { AuthProvidersLive, type AuthProviders } from "./Auth/Registry.ts";
19 import type { Input, InputProps } from "./Input.ts";
20 // Type-only: with verbatimModuleSyntax a value import would survive emit and
21 // drag the terminal helpers (node:tty, Sigil's ansi helpers) into every unbundled
22 // child process that loads Stack.ts.
23 import type { Interaction } from "./Interaction.ts";
24 import * as Output from "./Output.ts";
25 import type { Provider, ProviderCollectionLike } from "./Provider.ts";
26 import type { ResourceBinding, ResourceLike } from "./Resource.ts";
27 import type { SecretsEntry, SecretsOption } from "./Secrets/Provider.ts";
28 import { StackContext } from "./StackContext.ts";
29 import { Stage } from "./Stage.ts";
30 import type { State } from "./State/State.ts";
31 import { stackConfigLayer } from "./Util/ConfigProvider.ts";
32 import { effectClass, taggedFunction } from "./Util/effect.ts";
33 import type { PlatformServices } from "./Util/PlatformServices.ts";
34
35 export type StackServices =
36 | Stack
37 | Stage
38 | Scope.Scope
39 | FileSystem
40 | Digest
41 | SecureRandom
42 | Path
43 | AlchemyContext
44 | HttpClient
45 | ChildProcessSpawner
46 | AuthProviders
47 | ProfileStore
48 | ArtifactStore
49 | CredentialsStore
50 | Interaction;
51
52 export type ProviderServices =
53 | ProviderCollectionLike
54 | Provider<any>
55 | EnvironmentLike
56 | CredentialsLike
57 | DockerLike;
58
59 // tagged type to allow types like AWSEnvironment/AWS Region to bubble through
60 export interface EnvironmentLike {
61 readonly kind: "Environment";
62 }
63
64 // tagged type to allow types like AWS Credentials to bubble through
65 export interface CredentialsLike {
66 readonly kind: "Credentials";
67 }
68
69 export interface DockerLike {
70 readonly key: "@alchemy/Docker";
71 }
72
73 export type StackEffect<A, Err = never, Req = never> = Effect.Effect<
74 A,
75 Err,
76 | PlatformServices
77 | HttpClient
78 | Scope.Scope
79 | AuthProviders
80 | AlchemyContext
81 | Interaction
82 | ProfileStore
83 | CredentialsStore
84 | ArtifactStore
85 | State
86 | Req
87 >;
88
89 export type Stack = Context.ServiceClass.Shape<"Stack", Omit<StackSpec, "output">>;
90
91 /**
92 * Where a stack's configuration comes from: a ConfigProvider layer, or a
93 * list of them applied in order, later ones overriding earlier ones.
94 *
95 * The process environment implicitly closes every list, so the shell
96 * overrides every provider. List `Secrets.ProcessEnv()` yourself to rank it
97 * elsewhere, or `Secrets.ProcessEnv({ disabled: true })` to leave it out.
98 * Omitting `secrets` preserves the existing ConfigProvider and CLI dotenv behavior.
99 *
100 * ```ts
101 * secrets: [
102 * Doppler.Secrets({ project: "app", config: "dev" }),
103 * Secrets.DotEnv(),
104 * Secrets.ProcessEnv(),
105 * ]
106 * ```
107 */
108 export type SecretProviders = SecretsEntry | ReadonlyArray<SecretsEntry>;
109
110 /**
111 * The `secrets` option: providers, or a callback that picks them from the
112 * stage, so one stack can read `.env` locally and a secrets manager
113 * elsewhere:
114 *
115 * ```ts
116 * secrets: ({ stage }) =>
117 * stage === "dev"
118 * ? Secrets.DotEnv()
119 * : Doppler.Secrets({ project: "app", config: stage }),
120 * ```
121 */
122 export type StackSecrets = SecretsOption<SecretProviders>;
123
124 export interface StackProps<Req> {
125 providers: Layer.Layer<Extract<Req, ProviderServices>, never, StackServices>;
126 state: Layer.Layer<State, never, StackServices>;
127 /** Opt in to secret providers. When omitted, existing configuration is preserved. */
128 secrets?: StackSecrets;
129 }
130
131 /**
132 * Runtime fields the Stack factory attaches to a configured stack effect.
133 * Class-reference forms expose only `stackName` until `.make(...)`.
134 */
135 export type ConfiguredStackMeta<Req = never> = {
136 readonly stackName: string;
137 } & StackProps<Req>;
138
139 /**
140 * What `Alchemy.Stack(...)` returns, and what an `alchemy.run.ts`
141 * default-exports: the stack program, not yet run, with its providers,
142 * state store, and secrets attached.
143 */
144 export type ConfiguredStack<Output, Req> = Effect.Effect<CompiledStack<Output>, ConfigError> &
145 ConfiguredStackMeta<Req>;
146
147 export const Stack: Context.ServiceClass<Stack, "Stack", Omit<StackSpec, "output">> & {
148 make<A, Req>(
149 stack: {
150 Shape: A;
151 },
152 effect: Effect.Effect<NoInfer<A extends object ? InputProps<A> : Input<A>>, ConfigError, Req>,
153 ): Effect.Effect<CompiledStack<A>, ConfigError>;
154 <Self>(): {
155 <A, Req>(
156 stackName: string,
157 options: StackProps<NoInfer<Req>>,
158 eff: Effect.Effect<A, ConfigError, Req>,
159 ): Effect.Effect<Self, ConfigError> & {
160 new (_: never): A extends object ? A : {};
161 readonly stackName: string;
162 stage: {
163 [stage: string]: Effect.Effect<Self>;
164 };
165 };
166 };
167 <Self, Shape, Stages extends string = string>(): {
168 (stackName: string): Effect.Effect<Self> & {
169 new (_: never): Output.ToOutput<Shape>;
170 readonly stackName: string;
171 make: <A, Req>(
172 options: StackProps<NoInfer<Req>>,
173 effect: Effect.Effect<A, ConfigError, Req>,
174 ) => ConfiguredStack<A, NoInfer<Req>>;
175 stage: {
176 readonly [S in Stages]: Effect.Effect<Self>;
177 };
178 };
179 };
180 <A, Req extends StackServices | ProviderServices = never>(
181 stackName: string,
182 options: StackProps<NoInfer<Req>>,
183 eff: Effect.Effect<A, ConfigError, Req>,
184 ): ConfiguredStack<A, NoInfer<Req>>;
185 } = Object.assign(
186 taggedFunction(
187 StackContext,
188 <A, Req>(
189 stackName?: string,
190 options?: StackProps<NoInfer<Req>>,
191 eff?: Effect.Effect<A, ConfigError, Req>,
192 ) => {
193 if (!stackName) {
194 return (stackName: string) =>
195 Object.assign(
196 // by default, reference the stack at the "current" stage of the importer
197 Output.stackRef<A>(stackName).pipe(effectClass),
198 {
199 stackName,
200 stage: createStageProxy(stackName),
201 state: options?.state,
202 providers: options?.providers,
203 secrets: options?.secrets,
204 make: <Req = never>(
205 options: StackProps<NoInfer<Req>>,
206 eff: Effect.Effect<A, ConfigError, Req>,
207 ) =>
208 // @ts-expect-error
209 Stack(stackName, options, eff),
210 },
211 );
212 }
213 return eff!.pipe(
214 // @ts-expect-error
215 make({
216 name: stackName,
217 ...options!,
218 }),
219 (eff) =>
220 Object.assign(eff, {
221 stackName,
222 stage: createStageProxy(stackName),
223 state: options?.state,
224 providers: options?.providers,
225 secrets: options?.secrets,
226 }),
227 );
228 },
229 ),
230 ) as any;
231
232 const createStageProxy = (stackName: string) =>
233 new Proxy(
234 {},
235 {
236 get: (_, stage: string) => Output.stackRef(stackName, { stage }),
237 },
238 );
239
240 export interface StackSpec<Output = any> {
241 name: string;
242 stage: string;
243 // @internal
244 resources: {
245 [logicalId: string]: ResourceLike;
246 };
247 bindings: {
248 [logicalId: string]: ResourceBinding[];
249 };
250 /** Tasks registered on the stack, keyed by FQN. */
251 actions: {
252 [logicalId: string]: ActionLike;
253 };
254 output: Output;
255 }
256
257 export interface CompiledStack<Output = any, Services = any> extends StackSpec<Output> {
258 services: Context.Context<Services>;
259 }
260
261 export const StackName = Stack.use((stack) => Effect.succeed(stack.name));
262
263 export interface MakeStackProps<ROut = never> {
264 name: string;
265 /** Required; {@link make} dies with setup guidance when it is missing. */
266 providers?: Layer.Layer<ROut, never, StackServices>;
267 /** Required; {@link make} dies with setup guidance when it is missing. */
268 state?: Layer.Layer<State, never, StackServices>;
269 /** Opt in to secret providers. When omitted, existing configuration is preserved. */
270 secrets?: StackSecrets;
271 /** @internal */
272 stack?: StackSpec;
273 }
274
275 /**
276 * The scope a stack's state store is built into when it must close sooner
277 * than the rest of the stack. A store holds its stack's lease until its scope
278 * closes, so `evalStack` (`EvalStack.ts`) gives it one per call even when the caller
279 * keeps providers alive in a longer scope.
280 */
281 export class StateScope extends Context.Service<StateScope, Scope.Scope>()(
282 "alchemy/Stack/StateScope",
283 ) {}
284
285 /**
286 * Build a stack's providers, state store, secrets config and `Stack` spec,
287 * without running its program. Destroy needs nothing more: it plans from state
288 * alone, and every row records the provider mode that deletes it.
289 */
290 export const build = <ROut = never>(options: MakeStackProps<ROut>) =>
291 Effect.all([Effect.scope, Effect.serviceOption(StateScope)]).pipe(
292 Effect.flatMap(([scope, stateScope]) => {
293 if (options.state == null) {
294 return Effect.die(
295 new Error(
296 `Stack "${options.name}" is missing a state store. ` +
297 `Add a \`state\` layer to the stack options, e.g.:\n` +
298 ` Alchemy.Stack("${options.name}", {\n` +
299 ` providers: Cloudflare.providers(),\n` +
300 ` state: Cloudflare.state(), // <-- required\n` +
301 ` }, ...)\n` +
302 `See https://alchemy.run/state-store for available state stores.`,
303 ),
304 );
305 }
306 if (options.providers == null) {
307 return Effect.die(
308 new Error(
309 `Stack "${options.name}" is missing a providers layer. ` +
310 `Add a \`providers\` layer to the stack options, e.g.:\n` +
311 ` Alchemy.Stack("${options.name}", {\n` +
312 ` providers: Cloudflare.providers(), // <-- required\n` +
313 ` state: Cloudflare.state(),\n` +
314 ` }, ...)`,
315 ),
316 );
317 }
318 const state = options.state;
319 return options.providers.pipe(
320 Layer.provideMerge(
321 Option.match(stateScope, {
322 onNone: () => state,
323 onSome: (stateScope) => Layer.effectContext(Layer.buildWithScope(state, stateScope)),
324 }),
325 ),
326 Layer.provideMerge(stackConfigLayer(options.secrets)),
327 Layer.provideMerge(
328 Layer.effect(
329 Stack,
330 Stage.pipe(
331 Effect.map(
332 (stage) =>
333 options.stack ?? {
334 name: options.name,
335 stage,
336 resources: {},
337 bindings: {},
338 actions: {},
339 },
340 ),
341 ),
342 ),
343 ),
344 Layer.provideMerge(AuthProvidersLive),
345 Layer.buildWithScope(scope),
346 );
347 }),
348 );
349
350 /** Build a stack's services with {@link build}, then run its program under them. */
351 export const make =
352 <ROut = never>(options: MakeStackProps<ROut>) =>
353 <A, Err = never, Req extends ROut | StackServices = never>(effect: Effect.Effect<A, Err, Req>) =>
354 build(options).pipe(
355 Effect.flatMap((context) =>
356 Effect.all([effect, Stack, Effect.context<ROut | StackServices>()]).pipe(
357 Effect.map(([output, stack, services]): CompiledStack<A, ROut | StackServices> => ({
358 ...stack,
359 output,
360 services: Context.merge(services, context),
361 })),
362 Effect.provideContext(context),
363 ),
364 ),
365 );
366
367 /** What `Alchemy.Stack(...)` attaches to the stack it returns: everything but its program. */
368 export interface StackDefinition<ROut = never> {
369 readonly stackName: string;
370 readonly providers?: Layer.Layer<ROut, never, StackServices>;
371 readonly state?: Layer.Layer<State, never, StackServices>;
372 readonly secrets?: StackSecrets;
373 }
374
375 export const CurrentStack = Effect.serviceOption(Stack)
376
377 .pipe(Effect.map(Option.getOrUndefined));