The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as Context from "effect/Context"; |
| 2 | import * as Data from "effect/Data"; |
| 3 | import * as Effect from "effect/Effect"; |
| 4 | |
| 5 | /** |
| 6 | * AdoptPolicy controls whether the engine should "adopt" pre-existing cloud |
| 7 | * resources that conflict with this stack instead of failing. |
| 8 | * |
| 9 | * The engine always calls a provider's `read` lifecycle operation when there |
| 10 | * is no prior state and `read` is implemented. The provider's job is to |
| 11 | * report two things: |
| 12 | * |
| 13 | * 1. Whether the resource exists (returns attributes vs. `undefined`). |
| 14 | * 2. Whether *we* own it (plain attributes vs. {@link Unowned}-branded). |
| 15 | * |
| 16 | * The engine then routes: |
| 17 | * |
| 18 | * | `read` outcome | `adopt: false` | `adopt: true` | |
| 19 | * | ------------------- | -------------- | ----------------- | |
| 20 | * | undefined | create | create | |
| 21 | * | owned (plain attrs) | silent adopt | silent adopt | |
| 22 | * | {@link Unowned} | fail | takeover (adopt) | |
| 23 | * |
| 24 | * "Owned" means a provider has affirmatively determined the resource was |
| 25 | * created by this stack/stage/logical-id (typically by inspecting tags or |
| 26 | * naming conventions). Resources without ownership semantics simply always |
| 27 | * return plain attrs — they are treated as owned by default, so silent |
| 28 | * adoption is the norm and `--adopt` is unnecessary. |
| 29 | * |
| 30 | * The policy can be overridden per-effect via {@link adopt} — most commonly |
| 31 | * applied at the resource or stack scope. |
| 32 | */ |
| 33 | export class AdoptPolicy extends Context.Service<AdoptPolicy, boolean>()("AdoptPolicy") {} |
| 34 | |
| 35 | /** |
| 36 | * Engine-raised failure produced when `read` reports an existing resource |
| 37 | * marked as {@link Unowned} and `adopt` is `false`. Surface this to the user |
| 38 | * to indicate they should either re-tag the cloud resource, pick a different |
| 39 | * physical name, or re-run with `--adopt` (or `adopt(true)`) to force a |
| 40 | * takeover. |
| 41 | */ |
| 42 | export class OwnedBySomeoneElse extends Data.TaggedError("OwnedBySomeoneElse")<{ |
| 43 | /** A human-readable description of why the resource cannot be adopted. */ |
| 44 | message: string; |
| 45 | /** The Resource Type (e.g. `AWS.S3.Bucket`). */ |
| 46 | resourceType?: string; |
| 47 | /** The logical ID of the conflicting resource. */ |
| 48 | logicalId?: string; |
| 49 | /** The physical name/identifier of the conflicting resource. */ |
| 50 | physicalName?: string; |
| 51 | }> {} |
| 52 | |
| 53 | /** |
| 54 | * Engine-raised failure produced when a delete-first replacement in a |
| 55 | * dependency cycle must delete its previous generation before its new |
| 56 | * identity is known: precreate runs on unresolved props, and a provider |
| 57 | * without `observe`, or whose `observe` reports {@link Unresolved}, cannot |
| 58 | * check ownership first. Refusing before the delete keeps the |
| 59 | * previous generation; re-run with `--adopt` (or `adopt(true)`) to accept |
| 60 | * whatever the identity resolves to. |
| 61 | */ |
| 62 | export class UnverifiableReplacement extends Data.TaggedError("UnverifiableReplacement")<{ |
| 63 | /** A human-readable description of why the replacement was refused. */ |
| 64 | message: string; |
| 65 | /** The Resource Type (e.g. `AWS.Lambda.Function`). */ |
| 66 | resourceType?: string; |
| 67 | /** The logical ID of the refused resource. */ |
| 68 | logicalId?: string; |
| 69 | }> {} |
| 70 | |
| 71 | /** |
| 72 | * Private symbol used to brand attribute objects returned by `read` as |
| 73 | * "exists in cloud, but not owned by this stack/stage/logical-id". |
| 74 | * |
| 75 | * Deliberately *not* registered via `Symbol.for` — the brand is an |
| 76 | * engine-internal routing hint and must not be observable or |
| 77 | * forgeable from outside this module. The engine strips it before any |
| 78 | * state persistence (see {@link stripUnowned}) so it never leaks into |
| 79 | * the state store, JSON serialization, or downstream `Output`s. |
| 80 | */ |
| 81 | const UnownedTag: unique symbol = Symbol("alchemy/Unowned"); |
| 82 | |
| 83 | /** |
| 84 | * Brand a `read` return value as belonging to a different owner. |
| 85 | * |
| 86 | * Use this in a provider's `read` implementation when the resource exists in |
| 87 | * the cloud but a positive ownership check (e.g. tag inspection) shows it |
| 88 | * was *not* created by this stack/stage/logical-id: |
| 89 | * |
| 90 | * ```ts |
| 91 | * read: Effect.fn(function* ({ id, output, olds }) { |
| 92 | * const settings = yield* getScriptSettings({ ... }).pipe( |
| 93 | * Effect.catchTag("WorkerNotFound", () => Effect.succeed(undefined)), |
| 94 | * ); |
| 95 | * if (!settings) return undefined; |
| 96 | * |
| 97 | * const attrs = { workerName, ...buildAttrs(settings) }; |
| 98 | * return hasAlchemyWorkerTags(id, settings.tags) ? attrs : Unowned(attrs); |
| 99 | * }), |
| 100 | * ``` |
| 101 | * |
| 102 | * The returned value is structurally still `T` — there is no wrapper to |
| 103 | * unwrap. The brand is a non-enumerable symbol that the engine inspects |
| 104 | * during planning to decide whether to take over (`adopt: true`) or fail |
| 105 | * loudly (`adopt: false`). |
| 106 | * |
| 107 | * Resources without ownership semantics should simply return plain attrs — |
| 108 | * the engine treats them as owned and silent adoption is the default. |
| 109 | */ |
| 110 | export const Unowned: { |
| 111 | <T extends object>(attrs: T): T; |
| 112 | is: (value: unknown) => boolean; |
| 113 | } = Object.assign( |
| 114 | <T extends object>(attrs: T): T => { |
| 115 | const cloned = { ...attrs } as T; |
| 116 | Object.defineProperty(cloned, UnownedTag, { |
| 117 | value: true, |
| 118 | enumerable: false, |
| 119 | writable: false, |
| 120 | configurable: false, |
| 121 | }); |
| 122 | return cloned; |
| 123 | }, |
| 124 | { |
| 125 | is: (value: unknown): boolean => |
| 126 | typeof value === "object" && value !== null && (value as any)[UnownedTag] === true, |
| 127 | }, |
| 128 | ); |
| 129 | |
| 130 | /** |
| 131 | * {@link Unowned} unless `attrs` is the generation a replacement is replacing: |
| 132 | * during a replacement `read` and `observe` receive that generation's |
| 133 | * attributes as `previous`, and a delete-first replacement that reuses its |
| 134 | * identity finds it under that same identity. `key` must identify the |
| 135 | * resource uniquely (a full resource name or an API id, not a display name). |
| 136 | * |
| 137 | * ```ts |
| 138 | * read: Effect.fn(function* ({ output, olds, previous }) { |
| 139 | * // ... |
| 140 | * return output ? attrs : unownedUnlessPrevious(attrs, previous, "name"); |
| 141 | * }), |
| 142 | * ``` |
| 143 | */ |
| 144 | export const unownedUnlessPrevious = <T extends object, K extends keyof T>( |
| 145 | attrs: T, |
| 146 | previous: Partial<Record<K, unknown>> | undefined, |
| 147 | key: K, |
| 148 | ): T => |
| 149 | previous !== undefined && previous[key] !== undefined && previous[key] === attrs[key] |
| 150 | ? attrs |
| 151 | : Unowned(attrs); |
| 152 | |
| 153 | /** |
| 154 | * A provider's `observe` answer when the identity `precreate` would claim |
| 155 | * depends on props that have not resolved yet, so nothing can be checked. |
| 156 | * Unlike `undefined`, it does not report the identity as absent: the engine |
| 157 | * checks the resolved identity before `reconcile` claims it, and refuses a |
| 158 | * delete-first replacement that would delete its previous generation first. |
| 159 | * |
| 160 | * ```ts |
| 161 | * observe: Effect.fn(function* ({ id, news }) { |
| 162 | * if (!isResolved(news.namespace)) return Unresolved; |
| 163 | * // ... |
| 164 | * }), |
| 165 | * ``` |
| 166 | * |
| 167 | * `precreate` must not write to an identity it cannot resolve. |
| 168 | */ |
| 169 | export const Unresolved: unique symbol = Symbol("alchemy/Unresolved"); |
| 170 | export type Unresolved = typeof Unresolved; |
| 171 | |
| 172 | /** |
| 173 | * Raised by a provider's `precreate` when the identity it must claim is still |
| 174 | * {@link Unresolved}. The engine resolves every prop that comes from outside |
| 175 | * a dependency cycle before precreate, so the identity depends on a peer in |
| 176 | * the resource's own cycle. Name the resource with a literal, or a value from |
| 177 | * outside the cycle. |
| 178 | */ |
| 179 | export class UnresolvedIdentity extends Data.TaggedError("UnresolvedIdentity")<{ |
| 180 | /** A human-readable description of the unresolved identity. */ |
| 181 | message: string; |
| 182 | /** The Resource Type (e.g. `AWS.Lambda.Function`). */ |
| 183 | resourceType?: string; |
| 184 | /** The logical ID of the resource. */ |
| 185 | logicalId?: string; |
| 186 | }> {} |
| 187 | |
| 188 | /** |
| 189 | * Strip the {@link Unowned} brand from an attributes object before persisting |
| 190 | * it — state should not carry per-deploy ownership-routing metadata. |
| 191 | * |
| 192 | * The brand is intentionally non-enumerable, so a plain spread already |
| 193 | * drops it; the additional `delete` is defense-in-depth in case a future |
| 194 | * change makes the descriptor enumerable. Always returns a fresh object |
| 195 | * (never mutates the input). |
| 196 | */ |
| 197 | export const stripUnowned = <T extends object>(attrs: T): T => { |
| 198 | const out: any = { ...attrs }; |
| 199 | if (UnownedTag in out) delete out[UnownedTag]; |
| 200 | return out; |
| 201 | }; |
| 202 | |
| 203 | export const adopt: { |
| 204 | (enabled?: boolean): <A, E, R = never>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>; |
| 205 | <R1 = never>( |
| 206 | enabled: Effect.Effect<boolean, never, R1>, |
| 207 | ): <A, E, R2 = never>(effect: Effect.Effect<A, E, R2>) => Effect.Effect<A, E, R1 | R2>; |
| 208 | } = ((enabled: boolean | Effect.Effect<boolean, never, any> = true) => |
| 209 | (eff: Effect.Effect<any, any, any>) => |
| 210 | eff.pipe( |
| 211 | typeof enabled === "boolean" |
| 212 | ? Effect.provideService(AdoptPolicy, enabled ?? true) |
| 213 | : Effect.provideServiceEffect(AdoptPolicy, enabled), |
| 214 | )) as any; |