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

main
ts 147 lines 6.25 KB
Raw
1 import * as LocalFlagship from "@alchemy.run/cloudflare-runtime/core/bindings/flagship";
2 import type { AlchemyContext } from "alchemy/AlchemyContext";
3 import type * as Context from "effect/Context";
4 import * as Effect from "effect/Effect";
5 import type * as FileSystem from "effect/FileSystem";
6 import type * as HttpClient from "effect/http/HttpClient";
7 import * as Layer from "effect/Layer";
8 import type * as Path from "effect/Path";
9 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
10 import type { Credentials } from "../Credentials.ts";
11 import { dispatchByMode } from "../LocalGateway.ts";
12 import type { App } from "./App.ts";
13 import { localFlagshipStore } from "./Flag.ts";
14 import {
15 type EvaluationContext,
16 type EvaluationDetails,
17 FlagshipError,
18 ReadFlags,
19 type ReadFlagsClient,
20 } from "./ReadFlags.ts";
21 import { type FlagshipAuth, makeHttpFlagshipClient } from "./ReadFlagsHttpClient.ts";
22
23 /**
24 * Local implementation of the {@link ReadFlags} binding — evaluates Flagship
25 * feature flags over the Cloudflare HTTP API (`GET .../flagship/apps/{appId}/evaluate`)
26 * using the **current credentials** instead of a native Worker binding
27 * ({@link ReadFlagsBinding}).
28 *
29 * Provide it on an {@link Action} (or any deploy-time Effect) so you can read
30 * flag values with the same `getBooleanValue`/`getStringValue`/… client you'd
31 * use inside a Worker:
32 *
33 * @example Reading a flag from an Action
34 * ```typescript
35 * const CheckFlag = Alchemy.Action(
36 * "CheckFlag",
37 * Effect.gen(function* () {
38 * const flags = yield* Cloudflare.Flagship.ReadFlags(app);
39 * return Effect.fn(function* () {
40 * return yield* flags.getBooleanValue("new-checkout", false);
41 * });
42 * }).pipe(Effect.provide(Cloudflare.Flagship.ReadFlagsLocal)),
43 * );
44 * ```
45 *
46 * The app id is resolved at apply time through the ambient {@link RuntimeContext}
47 * (in an Action, that's the resolve context the engine provides around the
48 * body), so `ReadFlags(app)` works even though the app is created in the same
49 * deploy.
50 *
51 * Under `alchemy dev`, a locally-emulated app (a `dev:` app id) is evaluated
52 * against the local Flagship simulator's definitions with the same rules a
53 * dev Worker's binding applies, so the full evaluation context is honored.
54 *
55 * Limitations vs. the Worker binding for a live app: the HTTP evaluate
56 * endpoint only accepts a single `targetingKey` (read from
57 * `context.targetingKey`), so attribute-based targeting rules that key off
58 * other context fields cannot be exercised. The `raw` runtime binding has no
59 * HTTP equivalent and dies if used — see {@link makeHttpFlagshipClient}.
60 */
61 export const ReadFlagsLocal = Layer.effect(
62 ReadFlags,
63 Effect.gen(function* () {
64 // Capture the account resolver without authenticating — only the HTTP
65 // branch evaluates it. Credentials are ambient during stack-eval (the
66 // stack's providers layer); capture the full context so the evaluate op
67 // runs with the current credentials — no `host.bind`, no minted token.
68 const environment = yield* CloudflareEnvironment;
69 const context = yield* Effect.context<Credentials | HttpClient.HttpClient>();
70 // Local evaluation reads the simulator's files.
71 const platform = yield* Effect.context<FileSystem.FileSystem | Path.Path | AlchemyContext>();
72 const auth: FlagshipAuth = {
73 authorize: (eff) => eff.pipe(Effect.provideContext(context)),
74 accountId: Effect.map(environment, (env) => env.accountId),
75 };
76
77 return Effect.fn(function* (app: App) {
78 // Deferred accessor — resolves the appId against the tracker at apply
79 // time (in an Action, that's the engine's resolve context).
80 const appId = yield* app.appId;
81 return dispatchByMode(appId, makeHttpFlagshipClient(auth, appId), (id) =>
82 makeLocalFlagshipClient(id, platform),
83 );
84 });
85 }),
86 );
87
88 /**
89 * A client over the local Flagship simulator for a `dev:` app: evaluates the
90 * app's flag definitions in-process with the same rules a dev Worker's
91 * binding applies. `raw` cannot be satisfied — there is no native binding
92 * outside a Worker — so it dies with guidance.
93 */
94 const makeLocalFlagshipClient = (
95 appId: string,
96 platform: Context.Context<FileSystem.FileSystem | Path.Path | AlchemyContext>,
97 ): ReadFlagsClient => {
98 const details = <T>(
99 flagKey: string,
100 defaultValue: T,
101 expectedType: LocalFlagship.FlagshipValueType | undefined,
102 context: EvaluationContext | undefined,
103 ) =>
104 localFlagshipStore(appId).pipe(
105 Effect.flatMap((store) =>
106 LocalFlagship.evaluate(store, { flagKey, defaultValue, expectedType, context }),
107 ),
108 Effect.map((d) => d as EvaluationDetails<T>),
109 Effect.mapError(
110 (cause) => new FlagshipError({ message: "Local Flagship evaluation failed", cause }),
111 ),
112 Effect.provideContext(platform),
113 );
114 const value = <T>(
115 flagKey: string,
116 defaultValue: T,
117 expectedType: LocalFlagship.FlagshipValueType | undefined,
118 context: EvaluationContext | undefined,
119 ) => Effect.map(details(flagKey, defaultValue, expectedType, context), (d) => d.value);
120
121 return {
122 raw: Effect.die(
123 new FlagshipError({
124 message:
125 "A locally-emulated Flagship app has no native binding outside a Worker; use the evaluation methods.",
126 cause: undefined,
127 }),
128 ),
129 get: (flagKey, defaultValue, context) => value(flagKey, defaultValue, undefined, context),
130 getBooleanValue: (flagKey, defaultValue, context) =>
131 value(flagKey, defaultValue, "boolean", context),
132 getStringValue: (flagKey, defaultValue, context) =>
133 value(flagKey, defaultValue, "string", context),
134 getNumberValue: (flagKey, defaultValue, context) =>
135 value(flagKey, defaultValue, "number", context),
136 getObjectValue: (flagKey, defaultValue, context) =>
137 value(flagKey, defaultValue, "object", context),
138 getBooleanDetails: (flagKey, defaultValue, context) =>
139 details(flagKey, defaultValue, "boolean", context),
140 getStringDetails: (flagKey, defaultValue, context) =>
141 details(flagKey, defaultValue, "string", context),
142 getNumberDetails: (flagKey, defaultValue, context) =>
143 details(flagKey, defaultValue, "number", context),
144 getObjectDetails: (flagKey, defaultValue, context) =>
145 details(flagKey, defaultValue, "object", context),
146 };
147 };