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

main
ts 309 lines 10.9 KB
Raw
1 /**
2 * The core of the Alchemist operations: the builds they choose from (with
3 * or without the stack's program, or providers only), and the stack
4 * {@link plan} → {@link apply} pair deploys and destroys share. Drift and
5 * nuke have their own namespaces.
6 */
7 import * as ConfigProvider from "effect/ConfigProvider";
8 import * as Context from "effect/Context";
9 import * as Effect from "effect/Effect";
10 import * as Layer from "effect/Layer";
11 import * as Logger from "effect/Logger";
12 import * as Option from "effect/Option";
13 import { CurrentLogAnnotations, CurrentLogSpans, MinimumLogLevel } from "effect/References";
14 import * as Tracer from "effect/Tracer";
15 import { AdoptPolicy } from "../AdoptPolicy.ts";
16 import { AlchemyContext } from "../AlchemyContext.ts";
17 import * as Apply from "../Apply.ts";
18 import { ArtifactStore, createArtifactStore } from "../Artifacts.ts";
19 import { withProfileOverride } from "../Auth/Resolve.ts";
20 import { emit, type PlannedAction, type PlannedResource } from "../Events.ts";
21 import * as Plan from "../Plan.ts";
22 import type { ResourceSelection, SelectionOutput } from "../ResourceSelection.ts";
23 import * as Stack from "../Stack.ts";
24 import { Stage } from "../Stage.ts";
25 import type { State } from "../State/State.ts";
26 import { loadConfigProvider, StackConfigOverrides } from "../Util/ConfigProvider.ts";
27
28 /** Which credentials and config a stack build sees. */
29 export interface ConfigOptions {
30 /** `.env` file layered under the process environment. */
31 readonly envFile?: string;
32 /** Profile whose credentials the run uses. Falls back to the active profile. */
33 readonly profile?: string;
34 }
35
36 export interface BuildOptions extends ConfigOptions {
37 readonly stage: string;
38 /** Run local (emulated) providers instead of the real cloud. */
39 readonly dev?: boolean;
40 /** Adopt pre-existing cloud resources instead of failing on conflict. */
41 readonly adopt?: boolean;
42 /** Upgrade an out-of-date state store without prompting. */
43 readonly updateStateStore?: boolean;
44 }
45
46 /** Config services shared by every stack build. */
47 export const configServices = Effect.fn("Alchemist.configServices")(function* (
48 options: ConfigOptions,
49 ) {
50 const envFile = Option.fromNullishOr(options.envFile);
51 const commandConfig = yield* loadConfigProvider(envFile);
52 // `envFile` only steers a stack's default secrets list and `profile`
53 // pins the profile inside it; see stackConfigLayer.
54 return Layer.mergeAll(
55 Layer.succeed(StackConfigOverrides, {
56 envFile: options.envFile,
57 profile: options.profile,
58 }),
59 ConfigProvider.layer(withProfileOverride(commandConfig, options.profile)),
60 );
61 });
62
63 // TODO(unify stack builds): the one stack build everything should use; see
64 // the TODO in `EvalStack.ts` for the other paths still to migrate here.
65
66 /** The per-build services a stack's providers and program run under. */
67 const buildServices = Effect.fn("Alchemist.buildServices")(function* (options: BuildOptions) {
68 yield* emit({ type: "plan.phase", phase: "resolving-services" });
69 return yield* Layer.build(
70 Layer.mergeAll(
71 Layer.effect(
72 AlchemyContext,
73 Effect.map(AlchemyContext, (context) => ({
74 ...context,
75 dev: options.dev ?? context.dev,
76 adopt: options.adopt ?? false,
77 updateStateStore: options.updateStateStore ?? false,
78 })),
79 ),
80 Layer.succeedContext(
81 Context.make(AdoptPolicy, options.adopt ?? false).pipe(
82 Context.add(ArtifactStore, createArtifactStore()),
83 Context.add(Stage, options.stage),
84 ),
85 ),
86 yield* configServices(options),
87 ),
88 );
89 });
90
91 /**
92 * The building fiber's logging and tracing, dropped from a built context:
93 * a plan or scan is applied later, and possibly under other loggers (an
94 * `onEvent` subscriber around `apply`), which providing the captured ones
95 * would silently replace.
96 */
97 const withoutFiberLogging = Context.omit(
98 Logger.CurrentLoggers,
99 MinimumLogLevel,
100 CurrentLogAnnotations,
101 CurrentLogSpans,
102 Tracer.ParentSpan,
103 );
104
105 /**
106 * Build a stack's providers and state store and run its program.
107 *
108 * @internal used by {@link plan} and `Logs`.
109 */
110 export const buildStack = Effect.fn("Alchemist.build")(function* <Output, Req>(
111 stack: Stack.ConfiguredStack<Output, Req>,
112 options: BuildOptions,
113 ) {
114 const baseContext = yield* buildServices(options);
115 const compiled = yield* Effect.provide(stack, baseContext);
116 return {
117 stack: compiled,
118 /** The stack's own providers and state store over the build's services. */
119 context: withoutFiberLogging(Context.merge(baseContext, compiled.services)),
120 };
121 });
122
123 /**
124 * Build a stack's providers and state store without running its program:
125 * all that destroy, drift, and state access need, and safe when the
126 * program itself no longer runs.
127 *
128 * @internal used by {@link plan}, `Drift.scan`, and `State.store`.
129 */
130 export const buildWithoutProgram = Effect.fn("Alchemist.buildWithoutProgram")(function* <Req>(
131 stack: Stack.ConfiguredStack<unknown, Req>,
132 options: BuildOptions,
133 ) {
134 const baseContext = yield* buildServices(options);
135 const stackServices = yield* Effect.provide(
136 Stack.build({
137 name: stack.stackName,
138 providers: stack.providers,
139 state: stack.state,
140 secrets: stack.secrets,
141 }),
142 baseContext,
143 );
144 return {
145 stack: { ...Context.get(stackServices, Stack.Stack), output: undefined },
146 context: withoutFiberLogging(Context.merge(baseContext, stackServices)),
147 };
148 });
149
150 export interface PlanSummary {
151 readonly create: number;
152 readonly update: number;
153 readonly adopted: number;
154 readonly replace: number;
155 readonly delete: number;
156 readonly orphaned: number;
157 /** Actions that will run. */
158 readonly run: number;
159 readonly noop: number;
160 }
161
162 /** Whether a plan or drift scan proposes any cloud mutations (i.e. approval-worthy work). */
163 export const hasChanges = ({ summary }: { readonly summary: PlanSummary }): boolean =>
164 summary.create +
165 summary.update +
166 summary.adopted +
167 summary.replace +
168 summary.delete +
169 summary.orphaned +
170 summary.run >
171 0;
172
173 export const summarize = (plan: Plan.Plan): PlanSummary => {
174 const summary: { -readonly [K in keyof PlanSummary]: PlanSummary[K] } = {
175 create: 0,
176 update: 0,
177 adopted: 0,
178 replace: 0,
179 delete: 0,
180 orphaned: 0,
181 run: 0,
182 noop: 0,
183 };
184 for (const node of Object.values(plan.resources)) summary[node.action]++;
185 for (const node of Object.values(plan.actions)) summary[node.action]++;
186 for (const node of [...Object.values(plan.deletions), ...Object.values(plan.actionDeletions)]) {
187 if (node !== undefined) summary[node.action]++;
188 }
189 return summary;
190 };
191
192 /** The services a stack plan is applied under. */
193 type StackContext = Context.Context<State | Stack.Stack | Stage>;
194
195 /**
196 * A deploy or destroy plan: what will change, and the built stack it was
197 * planned against so {@link apply} runs without rebuilding.
198 */
199 export interface StackPlan<Output = unknown> {
200 readonly stack: { readonly name: string; readonly stage: string };
201 readonly summary: PlanSummary;
202 /** Serializable resource rows (including orphan deletions). */
203 readonly resources: ReadonlyArray<PlannedResource>;
204 /** Serializable stack-action rows. */
205 readonly actions: ReadonlyArray<PlannedAction>;
206 /**
207 * The engine plan `apply` executes, for renderers.
208 * @internal its shape may change.
209 */
210 readonly native: Plan.Plan<Output>;
211 /**
212 * The stack services the plan was computed under; they live in the caller's `Scope`.
213 * @internal `apply` runs in them.
214 */
215 readonly context: StackContext;
216 }
217
218 /** Describe an engine plan computed on a built stack. */
219 export const describeStackPlan = Effect.fn("Alchemist.describeStackPlan")(function* <Output>(
220 built: {
221 readonly stack: { readonly name: string; readonly stage: string };
222 readonly context: StackContext;
223 },
224 native: Plan.Plan<Output>,
225 ) {
226 yield* emit({ type: "plan.phase", phase: "plan-ready" });
227 return {
228 stack: { name: built.stack.name, stage: built.stack.stage },
229 summary: summarize(native),
230 ...Plan.describePlan(native),
231 native,
232 context: built.context,
233 } satisfies StackPlan<Output>;
234 });
235
236 /**
237 * Run the stack's program and plan what to create, update, replace, and
238 * delete so the stage matches it.
239 */
240 export interface DeployPlanOptions extends BuildOptions, ResourceSelection {
241 readonly operation: "deploy";
242 /** Re-run every Action regardless of input drift. */
243 readonly force?: boolean;
244 }
245
246 /**
247 * Plan deleting everything the stage owns. The program never runs, so this
248 * works even when it no longer does. Always the whole stage.
249 */
250 export interface DestroyPlanOptions extends BuildOptions {
251 readonly operation: "destroy";
252 }
253
254 export type PlanOptions = DeployPlanOptions | DestroyPlanOptions;
255
256 /** What applying a plan made with `O` returns. */
257 export type PlanOutput<Output, O extends PlanOptions> = O extends { readonly operation: "destroy" }
258 ? undefined
259 : SelectionOutput<Output, O>;
260
261 /**
262 * Plan a deploy or a destroy of `stack`. A filtered deploy plan applies to
263 * `undefined` and leaves the persisted stack output untouched. The build,
264 * and the stage's state-store lease, stay open until the surrounding
265 * `Scope` closes.
266 */
267 export const plan = Effect.fn("Alchemist.plan")(function* <
268 Output,
269 Req,
270 const O extends PlanOptions,
271 >(input: O & { readonly stack: Stack.ConfiguredStack<Output, Req> }) {
272 if (input.operation === "destroy") {
273 const built = yield* buildWithoutProgram(input.stack, input);
274 const native = yield* Plan.destroy(built.stack).pipe(Effect.provide(built.context));
275 // SAFETY: `operation: "destroy"` is exactly when PlanOutput is `undefined`.
276 return (yield* describeStackPlan(built, native)) as StackPlan<PlanOutput<Output, O>>;
277 }
278 // `operation` is "deploy" here; a generic `O` doesn't narrow.
279 const deploy: DeployPlanOptions = input;
280 const built = yield* buildStack(input.stack, deploy);
281 const native = yield* Plan.make(built.stack, {
282 force: deploy.force,
283 include: deploy.include,
284 exclude: deploy.exclude,
285 }).pipe(Effect.provide(built.context));
286 // SAFETY: for `deploy`, PlanOutput is the selection's output.
287 return (yield* describeStackPlan(built, native)) as StackPlan<PlanOutput<Output, O>>;
288 });
289
290 /** Run a plan; a deploy returns the stack's output. */
291 export const apply = Effect.fn("Alchemist.apply")(function* <Output>(plan: StackPlan<Output>) {
292 return yield* Effect.provide(Apply.apply(plan.native), plan.context);
293 });
294
295 /** Stage used when a stack's providers are built without addressing a deployment. */
296 export const PLACEHOLDER_STAGE = "placeholder";
297
298 /**
299 * Build a stack's providers and state store without running its program or
300 * addressing a stage: what account-wide operations like `Nuke.scan` need.
301 */
302 export const buildProviders = <Req>(
303 stack: Stack.ConfiguredStack<unknown, Req>,
304 options: ConfigOptions = {},
305 ) =>
306 Effect.map(
307 buildWithoutProgram(stack, { ...options, stage: PLACEHOLDER_STAGE }),
308 (built) => built.context,
309 );