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

main
ts 134 lines 6.08 KB
Raw
1 import * as Context from "effect/Context";
2 import * as Effect from "effect/Effect";
3
4 /**
5 * A former id a resource was previously declared under:
6 *
7 * - a bare `string` resolves against the ambient namespace, exactly like
8 * the resource's own `id` argument does
9 * - `{ fqn: "..." }` is absolute — the full FQN as persisted in state,
10 * ignoring any surrounding namespace. Needed when a resource moved
11 * BETWEEN namespaces (a relative id can only address the current
12 * namespace's subtree).
13 */
14 export type FormerId = string | { fqn: string };
15
16 /**
17 * RenamePolicy carries the former ids a resource was previously declared
18 * under. It is captured from the ambient context at registration time (like
19 * `AdoptPolicy` / `RemovalPolicy`) and resolved against the same namespace
20 * as the resource's own id — see `ResourceLike.FormerFqns`.
21 */
22 export class RenamePolicy extends Context.Service<RenamePolicy, readonly FormerId[]>()(
23 "RenamePolicy",
24 ) {}
25
26 /**
27 * Declare the logical id(s) this resource was previously registered under,
28 * so the engine migrates its persisted state row instead of planning a
29 * create+delete replacement when the id changes.
30 *
31 * ```ts
32 * // was: Bucket("Bucket") — the row migrates and the deploy plans a noop
33 * const bucket = yield* Bucket("Assets").pipe(renamedFrom("Bucket"));
34 * ```
35 *
36 * A bare string resolves against the ambient namespace, exactly like the
37 * resource's own `id`:
38 *
39 * ```ts
40 * // FQN `Site/Assets`, former FQN `Site/Bucket`
41 * yield* Bucket("Assets").pipe(
42 * renamedFrom("Bucket"),
43 * Namespace.push("Site"),
44 * );
45 * ```
46 *
47 * Moved between namespaces? Pass `{ fqn }` — the absolute FQN exactly as
48 * persisted in state, ignoring the ambient namespace:
49 *
50 * ```ts
51 * // former FQN `LegacySite/Assets` (NOT `NewSite/LegacySite/Assets`)
52 * yield* Bucket("Assets").pipe(
53 * renamedFrom({ fqn: "LegacySite/Assets" }),
54 * Namespace.push("NewSite"),
55 * );
56 * ```
57 *
58 * Renamed more than once? List every former id, most recent first — the
59 * planner checks them in order and migrates from the first matching row:
60 *
61 * ```ts
62 * // rename history: Bucket → StaticAssets → Assets
63 * yield* Bucket("Assets").pipe(renamedFrom("StaticAssets", "Bucket"));
64 * ```
65 *
66 * Migration semantics, by state-row shape (see Plan's rename resolution;
67 * `new` = the row at the resource's FQN, `old` = a row at a former FQN):
68 *
69 * ```text
70 * new old → outcome
71 * ──────────────────────────────────────────────────────────────────────
72 * — row → migrate: the old row
73 * IS the resource's
74 * state; apply moves it
75 * before any lifecycle
76 * op, and ONE update
77 * reconcile re-brands
78 * the physical resource
79 * under the new logical
80 * id (never a create)
81 * row, same instanceId row → interrupted
82 * migration: leftovers
83 * dropped state-only —
84 * ALL of them in one
85 * apply — the physical
86 * resource is never
87 * touched
88 * row, diff instanceId row → someone else's row (a
89 * resource reused the
90 * old name after the
91 * rename shipped):
92 * ignored, normal
93 * orphan handling
94 * row, diff resourceType row → FATAL: migrating over
95 * the foreign-typed row
96 * would silently
97 * abandon its cloud
98 * resource — resolve
99 * the collision first
100 * any row, diff resourceType → never migrated —
101 * cannot be this
102 * resource's row,
103 * whatever its FQN says
104 * ```
105 *
106 * The old id can be REUSED by a new resource in the same deploy — the
107 * rename claim wins the row (it is an explicit statement that the row was
108 * the renamer's), and the reusing resource is created fresh:
109 *
110 * ```ts
111 * // `Assets` keeps the physical resource previously known as `Bucket`;
112 * // this `Bucket` is a brand-new one.
113 * yield* Bucket("Assets").pipe(renamedFrom("Bucket"));
114 * yield* Bucket("Bucket");
115 * ```
116 *
117 * Renames may SHIFT through each other in one deploy — each row follows
118 * its resource (resolved in claim-dependency order):
119 *
120 * ```ts
121 * // the resource at `A` is now `B`; the resource at `B` is now `C`
122 * yield* Bucket("B").pipe(renamedFrom("A"));
123 * yield* Bucket("C").pipe(renamedFrom("B"));
124 * ```
125 *
126 * A SWAP (`A` ⇄ `B`) is a rename cycle and fails the plan loudly — the two
127 * migrations would overwrite and delete each other's rows. Rename through
128 * a temporary id across two deploys instead. Two resources claiming the
129 * same former FQN also fail loudly.
130 */
131 export const renamedFrom =
132 (...formerIds: [FormerId, ...FormerId[]]) =>
133 <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
134 Effect.provideService(effect, RenamePolicy, formerIds);