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

main
ts 560 lines 21.3 KB
Raw
1 import { pathToFileURL } from "node:url";
2 import type * as Command from "effect/cli/Command";
3 import * as Data from "effect/Data";
4 import * as Effect from "effect/Effect";
5 import * as FileSystem from "effect/FileSystem";
6 import type { HttpClient } from "effect/http/HttpClient";
7 import type * as HttpClientRequest from "effect/http/HttpClientRequest";
8 import type * as Layer from "effect/Layer";
9 import * as Path from "effect/Path";
10 import * as Predicate from "effect/Predicate";
11 import * as Schema from "effect/Schema";
12 import type * as Stream from "effect/Stream";
13 import type { AlchemyContext } from "./AlchemyContext.ts";
14 import type { ArtifactStore } from "./Artifacts.ts";
15 import type { AuthProviders } from "./Auth/AuthProvider.ts";
16 import type { CredentialsStore } from "./Auth/Credentials.ts";
17 import type { ProfileStore } from "./Auth/Profile.ts";
18 import type { Interaction } from "./Interaction.ts";
19 import type { State } from "./State/State.ts";
20 import { UserFacingError } from "./UserFacingError.ts";
21 import type { PlatformServices } from "./Util/PlatformServices.ts";
22
23 /**
24 * What a provider contributes to Alchemy outside a stack: the parts the CLI,
25 * the Alchemist API and the test harness need before (or without) importing
26 * the user's `alchemy.run.ts`.
27 *
28 * A contributions module is imported on every CLI start, so it holds
29 * metadata and lazy `import()`s only; the provider's code loads when a field
30 * is used.
31 *
32 * A package declares what it contributes in `package.json`:
33 *
34 * ```json
35 * { "alchemy": { "contributes": ["@alchemy.run/aws/Contributions"] } }
36 * ```
37 *
38 * {@link load} reads that field from `alchemy` itself and from the project's
39 * dependencies.
40 */
41 export interface Contributions {
42 /** Unique across loaded providers, e.g. `"aws"`. */
43 readonly name: string;
44 /**
45 * Registers the provider's `AuthProvider` into `AuthProviders`, so
46 * `alchemy profile` and login work without a stack that uses the provider.
47 */
48 readonly auth?: Lazy<Layer.Layer<never, never, ContributionServices>>;
49 /**
50 * The provider's state stores by `--backend` name, e.g. `{ aws: ... }`,
51 * each reachable from a profile alone as `alchemy state --backend <name>`.
52 * Names are global: two providers contributing one name is an error.
53 */
54 readonly stateStores?: Readonly<Record<string, StateStore>>;
55 /** CLI commands the provider adds. */
56 readonly cli?: Cli;
57 /**
58 * Services the test harness runs tests under when `ALCHEMY_TEST_DEV` is
59 * set, e.g. a local emulator for the provider's SDK clients.
60 */
61 readonly testServices?: Lazy<TestServices>;
62 /**
63 * Environment variables `alchemy dev` sets on itself before it starts, so
64 * its sidecars and the processes they launch inherit them, e.g. a local
65 * emulator's CA bundle. A variable that is already set wins.
66 */
67 readonly devEnv?: Lazy<
68 Effect.Effect<Readonly<Record<string, string>>, never, FileSystem.FileSystem | Path.Path>
69 >;
70 }
71
72 /**
73 * The services every host of provider code provides: the CLI and the Alchemist
74 * API both run it under them. A provider supplies anything else it needs
75 * itself, so a field can never require a service no host provides.
76 */
77 export type HostServices =
78 | PlatformServices
79 | HttpClient
80 | AlchemyContext
81 | ProfileStore
82 | CredentialsStore
83 | ArtifactStore
84 | Interaction;
85
86 /** What auth layers and state stores run under: the host's services and the auth registry. */
87 export type ContributionServices = HostServices | AuthProviders;
88
89 /** What a CLI command runs under: the host's services, `Interaction` included. */
90 export type CliServices = HostServices;
91
92 /** A provider's own failure: any tagged error with a message for the user. */
93 export type ContributionFailure = { readonly _tag: string; readonly message: string };
94 /**
95 * A field loaded when used, so importing a provider module stays cheap. Build
96 * one with {@link lazy}.
97 */
98 export type Lazy<A> = Effect.Effect<A, ContributionError>;
99
100 /**
101 * A {@link Lazy} field from a module of the provider's, imported on first
102 * use:
103 *
104 * ```ts
105 * auth: Contributions.lazy(() => import("./AuthProvider.ts"), (module) => module.AwsAuth),
106 * ```
107 */
108 export const lazy = <M, A>(load: () => Promise<M>, pick: (module: M) => A): Lazy<A> =>
109 Effect.tryPromise({
110 try: load,
111 catch: (cause) =>
112 new ContributionError({ message: "Could not import a provider module", cause }),
113 }).pipe(Effect.map(pick));
114
115 export interface StateStore {
116 /** Shown when listing stores; no provider code loads to show it. */
117 readonly description: string;
118 /** The store itself, loaded when it's used. */
119 readonly load: Lazy<StateStoreImpl>;
120 }
121
122 export interface StateStoreImpl {
123 /** The store's `State` layer: the provider's own `state` function. */
124 readonly layer: (
125 options: StateStoreOptions,
126 ) => Layer.Layer<State, ContributionFailure, ContributionServices>;
127 /** Provisioning, teardown and logs, for the operations the store supports. */
128 readonly lifecycle?: StateStoreLifecycle;
129 }
130
131 /** The options every state store's `state(...)` takes. */
132 export interface StateStoreOptions {
133 /** A store other than the account's default, by logical name. */
134 readonly name?: string;
135 }
136
137 /** Which store a lifecycle operation acts on, under the profile core resolved. */
138 export interface StateStoreTarget {
139 /** A store other than the account's default, by logical name. */
140 readonly name?: string;
141 }
142
143 export interface StateStoreLifecycle {
144 /** Provision the store, or adopt it when it exists. Idempotent. */
145 readonly bootstrap?: (
146 input: StateStoreTarget & {
147 /** Redeploy an existing store instead of adopting it. */
148 readonly force?: boolean;
149 },
150 ) => Effect.Effect<StateStoreBootstrap, ContributionFailure, ContributionServices>;
151 /** Delete the store and its backing resources. Idempotent. */
152 readonly teardown?: (
153 input: StateStoreTarget,
154 ) => Effect.Effect<StateStoreTeardown, ContributionFailure, ContributionServices>;
155 /** The store's past log entries, oldest first. */
156 readonly logs?: (
157 input: StateStoreTarget & { readonly limit?: number; readonly since?: Date },
158 ) => Effect.Effect<ReadonlyArray<StateStoreLogEntry>, ContributionFailure, ContributionServices>;
159 /** The store's log entries as they happen. */
160 readonly tailLogs?: (
161 input: StateStoreTarget,
162 ) => Stream.Stream<StateStoreLogEntry, ContributionFailure, ContributionServices>;
163 }
164
165 export interface StateStoreBootstrap {
166 readonly status: "created" | "adopted" | "redeployed";
167 /** The store's physical name: its Worker, its bucket. */
168 readonly store: string;
169 /** Where it lives, e.g. `{ account: "…", region: "us-east-1" }`. */
170 readonly location: Readonly<Record<string, string>>;
171 }
172
173 export interface StateStoreTeardown {
174 /** What was deleted, by physical name. */
175 readonly deleted: ReadonlyArray<string>;
176 }
177
178 export interface StateStoreLogEntry {
179 readonly timestamp: Date;
180 readonly message: string;
181 }
182
183 export interface Cli {
184 /**
185 * The `alchemy provider <provider name>` subcommand. Its description lists it
186 * in help; the command itself loads only when it runs.
187 */
188 readonly provider?: {
189 readonly description: string;
190 readonly load: Lazy<AnyCommand>;
191 };
192 }
193
194 // Any command, whatever its name, errors and the CLI services it runs under.
195 export type AnyCommand = Command.Command<any, any, any, ContributionFailure, CliServices>;
196
197 export interface TestServices {
198 /** Provided to test bodies and stack programs, closest wins. */
199 readonly layer: Layer.Layer<any, ContributionFailure, never>;
200 /** Rewrites the test's outbound HTTP, e.g. onto the emulator's gateway. */
201 readonly mapRequest?: (
202 request: HttpClientRequest.HttpClientRequest,
203 ) => HttpClientRequest.HttpClientRequest;
204 /** Set on the test process before anything forks, unless already set. */
205 readonly env?: Readonly<Record<string, string>>;
206 }
207
208 /** Declare a provider; the identity function, keeping its literal type. */
209 export const make = <const P extends Contributions>(provider: P): P => provider;
210
211 export class ContributionError extends Data.TaggedError("ContributionError")<{
212 readonly message: string;
213 readonly cause?: unknown;
214 }> {
215 readonly [UserFacingError] = true;
216 }
217
218 const Manifest = Schema.Struct({
219 name: Schema.optional(Schema.String),
220 main: Schema.optional(Schema.String),
221 exports: Schema.optional(Schema.Unknown),
222 dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
223 devDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
224 alchemy: Schema.optional(
225 Schema.Struct({ contributes: Schema.String.pipe(Schema.Array, Schema.optional) }),
226 ),
227 });
228
229 const readManifest = Effect.fn(function* (file: string) {
230 const fs = yield* FileSystem.FileSystem;
231 if (!(yield* fs.exists(file))) return undefined;
232 const text = yield* fs.readFileString(file);
233 return yield* Effect.try({
234 try: (): unknown => JSON.parse(text),
235 catch: (cause) => new ContributionError({ message: `Invalid JSON in ${file}`, cause }),
236 }).pipe(
237 Effect.flatMap(Schema.decodeUnknownEffect(Manifest)),
238 Effect.mapError(
239 (cause) => new ContributionError({ message: `Invalid package manifest ${file}`, cause }),
240 ),
241 );
242 });
243
244 /** Find `node_modules/<name>/package.json` from `dir` upwards. */
245 const findDependencyManifest = Effect.fn(function* (dir: string, name: string) {
246 const fs = yield* FileSystem.FileSystem;
247 const path = yield* Path.Path;
248 let current = dir;
249 while (true) {
250 const candidate = path.join(current, "node_modules", name, "package.json");
251 if (yield* fs.exists(candidate)) return candidate;
252 const parent = path.dirname(current);
253 if (parent === current) return undefined;
254 current = parent;
255 }
256 });
257
258 /**
259 * The packages a project in `dir` can contribute providers from: the direct
260 * dependencies of every `package.json` from `dir` up (a workspace package and
261 * the monorepo root above it), plus every installed `@alchemy.run/*` package
262 * reachable from `dir`, which a monorepo root can import without listing.
263 */
264 const candidatePackages = Effect.fn(function* (dir: string) {
265 const fs = yield* FileSystem.FileSystem;
266 const path = yield* Path.Path;
267 const names = new Set<string>();
268 let current = dir;
269 while (true) {
270 const manifest = yield* readManifest(path.join(current, "package.json"));
271 for (const name of Object.keys({ ...manifest?.dependencies, ...manifest?.devDependencies })) {
272 names.add(name);
273 }
274 const scope = path.join(current, "node_modules", PACKAGE_SCOPE);
275 if (yield* fs.exists(scope)) {
276 for (const entry of yield* fs.readDirectory(scope)) names.add(`${PACKAGE_SCOPE}/${entry}`);
277 }
278 const parent = path.dirname(current);
279 if (parent === current) return names;
280 current = parent;
281 }
282 });
283
284 /** The root `package.json` name of alchemy's own monorepo. */
285 const MONOREPO_NAME = "@alchemy.run/monorepo";
286
287 /**
288 * The `package.json` of every sibling package when alchemy runs from its own
289 * monorepo checkout (`packages/alchemy` under a root named
290 * {@link MONOREPO_NAME}). Empty for every installed copy of alchemy.
291 */
292 const monorepoManifests = Effect.gen(function* () {
293 const fs = yield* FileSystem.FileSystem;
294 const path = yield* Path.Path;
295 const own = path.dirname(yield* path.fromFileUrl(new URL("../package.json", import.meta.url)));
296 const packages = path.dirname(own);
297 const root = yield* readManifest(path.join(path.dirname(packages), "package.json")).pipe(
298 Effect.orElseSucceed(() => undefined),
299 );
300 if (root?.name !== MONOREPO_NAME) return [];
301 const files: string[] = [];
302 for (const entry of yield* fs.readDirectory(packages)) {
303 const file = path.join(packages, entry, "package.json");
304 if (path.join(packages, entry) !== own && (yield* fs.exists(file))) files.push(file);
305 }
306 return files.sort();
307 });
308
309 /** The npm scope of alchemy's own provider packages. */
310 const PACKAGE_SCOPE = "@alchemy.run";
311
312 /** A provider specifier, and the manifest that declared it when not alchemy's own. */
313 interface Declared {
314 readonly specifier: string;
315 readonly manifest?: {
316 readonly file: string;
317 readonly directory: string;
318 readonly name: string | undefined;
319 readonly main: string | undefined;
320 readonly exports: unknown;
321 };
322 }
323
324 /**
325 * The conditions an ESM `import` matches. Node picks the first matching key in
326 * the `exports` object's own order, so only membership matters here.
327 */
328 const importConditions = new Set(
329 typeof Bun !== "undefined" ? ["bun", "import", "node", "default"] : ["import", "node", "default"],
330 );
331
332 /** An `exports` target under {@link importConditions}, with `*` filled in. */
333 const exportTarget = (target: unknown, star: string): string | undefined => {
334 if (typeof target === "string") return target.replaceAll("*", star);
335 if (Array.isArray(target)) {
336 for (const candidate of target) {
337 const resolved = exportTarget(candidate, star);
338 if (resolved !== undefined) return resolved;
339 }
340 return undefined;
341 }
342 if (typeof target === "object" && target !== null) {
343 for (const [condition, value] of Object.entries(target)) {
344 if (!importConditions.has(condition)) continue;
345 const resolved = exportTarget(value, star);
346 if (resolved !== undefined) return resolved;
347 }
348 }
349 return undefined;
350 };
351
352 /** A package's own subpath (`"."`, `"./Contributions"`) through its `exports` map. */
353 const packageExport = (exports: unknown, main: string | undefined, subpath: string) => {
354 if (exports === undefined) return subpath === "." ? (main ?? "./index.js") : subpath;
355 const entries =
356 typeof exports === "object" && exports !== null && !Array.isArray(exports)
357 ? Object.entries(exports)
358 : [];
359 // Subpath keys, or the package's one export ("exports": "./index.js").
360 const map = new Map<string, unknown>(
361 entries.some(([key]) => key.startsWith(".")) ? entries : [[".", exports]],
362 );
363 if (map.has(subpath)) return exportTarget(map.get(subpath), "");
364 for (const [pattern, target] of map) {
365 const star = pattern.indexOf("*");
366 if (star === -1) continue;
367 const prefix = pattern.slice(0, star);
368 const suffix = pattern.slice(star + 1);
369 if (subpath.startsWith(prefix) && subpath.endsWith(suffix)) {
370 return exportTarget(target, subpath.slice(prefix.length, subpath.length - suffix.length));
371 }
372 }
373 return undefined;
374 };
375
376 /**
377 * Resolve a dependency's provider from the dependency itself, through its own
378 * `exports` with ESM import conditions: under pnpm alchemy usually can't see
379 * a project's dependencies, and a CommonJS resolver would pick `require`
380 * targets for a module loaded with `import()`. A provider specifier must name
381 * the package that declares it.
382 */
383 const resolveDeclared = ({ specifier, manifest }: Declared) =>
384 Effect.gen(function* () {
385 if (manifest === undefined) return specifier;
386 const path = yield* Path.Path;
387 const { name } = manifest;
388 if (name === undefined || (specifier !== name && !specifier.startsWith(`${name}/`))) {
389 return yield* new ContributionError({
390 message: `${specifier}, contributed by ${manifest.file}, must name that package (${name ?? "unnamed"})`,
391 });
392 }
393 const subpath = specifier === name ? "." : `.${specifier.slice(name.length)}`;
394 const target = packageExport(manifest.exports, manifest.main, subpath);
395 if (target === undefined) {
396 return yield* new ContributionError({
397 message: `${specifier} is not exported for import by ${manifest.file}`,
398 });
399 }
400 return pathToFileURL(path.join(manifest.directory, target)).href;
401 });
402
403 /** A module's default export as contributions; only the name is checked. */
404 const isContributions = (value: unknown): value is Contributions =>
405 Predicate.hasProperty(value, "name") && typeof value.name === "string";
406
407 const importContributions = (declared: Declared) =>
408 Effect.flatMap(resolveDeclared(declared), (url) =>
409 Effect.tryPromise({
410 try: (): Promise<{ readonly default?: unknown }> => import(url),
411 catch: (cause) =>
412 new ContributionError({ message: `Could not import ${declared.specifier}`, cause }),
413 }),
414 ).pipe(
415 Effect.flatMap((module) =>
416 isContributions(module.default)
417 ? Effect.succeed(module.default)
418 : Effect.fail(
419 new ContributionError({
420 message: `${declared.specifier} has no default export`,
421 }),
422 ),
423 ),
424 );
425
426 const discover = Effect.fn("Contributions.discover")(function* (cwd: string) {
427 const path = yield* Path.Path;
428 const declared = new Map<string, Declared>();
429 const own = yield* readManifest(
430 yield* path.fromFileUrl(new URL("../package.json", import.meta.url)),
431 );
432 // The project's packages that declare providers, before alchemy's own: the
433 // first provider with a name wins, so a provider that moved into its own
434 // package replaces the copy still inside alchemy.
435 const declare = Effect.fn(function* (file: string, fallback = false) {
436 const manifest = yield* readManifest(file);
437 for (const specifier of manifest?.alchemy?.contributes ?? []) {
438 if (fallback && declared.has(specifier)) continue;
439 declared.set(specifier, {
440 specifier,
441 manifest: {
442 file,
443 directory: path.dirname(file),
444 name: manifest?.name,
445 main: manifest?.main,
446 exports: manifest?.exports,
447 },
448 });
449 }
450 });
451 const dependencies = [...(yield* candidatePackages(cwd))].filter((name) => name !== own?.name);
452 for (const name of dependencies) {
453 const file = yield* findDependencyManifest(cwd, name);
454 if (file !== undefined) yield* declare(file);
455 }
456 // Developing alchemy itself: every package in the monorepo, so the CLI sees
457 // all providers without the root installing them. Installed copies win.
458 for (const file of yield* monorepoManifests) {
459 yield* declare(file, true).pipe(
460 Effect.catch((error) => Effect.logDebug(`Skipping ${file}: ${error.message}`)),
461 );
462 }
463 // alchemy's own: the providers that still live in this package.
464 for (const specifier of own?.alchemy?.contributes ?? []) declared.set(specifier, { specifier });
465 // A provider that fails to load is skipped, never the rest; the first provider
466 // with a name wins.
467 const providers = new Map<string, Contributions>();
468 for (const declaration of declared.values()) {
469 const provider = yield* importContributions(declaration).pipe(
470 Effect.catch((error) =>
471 Effect.as(
472 Effect.logWarning(`Skipping ${declaration.specifier}: ${error.message}`),
473 undefined,
474 ),
475 ),
476 );
477 if (provider === undefined) continue;
478 if (providers.has(provider.name)) {
479 // Expected for alchemy's own copy of a provider that moved out.
480 yield* (declaration.manifest ? Effect.logWarning : Effect.logDebug)(
481 `Skipping ${declaration.specifier}: the name ${provider.name} is taken`,
482 );
483 continue;
484 }
485 providers.set(provider.name, provider);
486 }
487 return [...providers.values()];
488 });
489
490 /** `--backend` names alchemy handles itself, so no provider may take them. */
491 export const RESERVED_BACKENDS: ReadonlyArray<string> = ["local", "configured"];
492
493 const loaded = new Map<string, Effect.Effect<ReadonlyArray<Contributions>, ContributionError>>();
494
495 /** The providers reachable from the project in `cwd`, loaded once per process. */
496 export const load = Effect.fn("Contributions.load")(function* (cwd?: string) {
497 const dir = cwd ?? (yield* Effect.sync(() => process.cwd()));
498 let cached = loaded.get(dir);
499 if (cached === undefined) {
500 cached = yield* Effect.cached(
501 discover(dir).pipe(
502 Effect.mapError((error) =>
503 error._tag === "ContributionError"
504 ? error
505 : new ContributionError({ message: "Could not read package manifests", cause: error }),
506 ),
507 Effect.provideService(FileSystem.FileSystem, yield* FileSystem.FileSystem),
508 Effect.provideService(Path.Path, yield* Path.Path),
509 ),
510 );
511 loaded.set(dir, cached);
512 }
513 return yield* cached;
514 });
515
516 /** The environment every provider contributes to `alchemy dev` (see {@link Contributions.devEnv}). */
517 export const devEnv = Effect.fn("Contributions.devEnv")(function* () {
518 const env: Record<string, string> = {};
519 for (const provider of yield* load()) {
520 if (provider.devEnv === undefined) continue;
521 const contribute = yield* resolve(provider, "devEnv", provider.devEnv);
522 Object.assign(env, yield* contribute);
523 }
524 return env;
525 });
526
527 /** Every provider's state stores, by `--backend` name, with their provider. */
528 export const stateStores = Effect.fn("Contributions.stateStores")(function* () {
529 const stores = new Map<
530 string,
531 { readonly provider: Contributions; readonly store: StateStore }
532 >();
533 for (const provider of yield* load()) {
534 for (const [backend, store] of Object.entries(provider.stateStores ?? {})) {
535 // A state backend name addresses one store, so two providers can't share it.
536 const owner = RESERVED_BACKENDS.includes(backend)
537 ? "alchemy"
538 : stores.get(backend)?.provider.name;
539 if (owner !== undefined) {
540 return yield* new ContributionError({
541 message: `${provider.name} and ${owner} both contribute a state store named ${backend}`,
542 });
543 }
544 stores.set(backend, { provider, store });
545 }
546 }
547 return stores;
548 });
549
550 /** Load one lazy field, failing with a {@link ContributionError} naming the provider. */
551 export const resolve = <A>(provider: Contributions, field: string, value: Lazy<A>) =>
552 value.pipe(
553 Effect.mapError(
554 (cause) =>
555 new ContributionError({
556 message: `Could not load ${provider.name}'s ${field}: ${cause.message}`,
557 cause,
558 }),
559 ),
560 );