@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 214 lines 8.42 KB
Raw
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;