@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, 04:45 UTC

main
ts 164 lines 5.59 KB
Raw
1 import * as Context from "effect/Context";
2 import * as Data from "effect/Data";
3 import * as Effect from "effect/Effect";
4 import { UserFacingError } from "../UserFacingError.ts";
5 import type { ActionState } from "./ActionState.ts";
6 import type { ReplacedResourceState, ResourceState } from "./ResourceState.ts";
7
8 /**
9 * Anything persistable under an FQN. Resources are discriminated by status
10 * strings ("creating", "created", …) and Tasks by `kind: "action"`.
11 */
12 export type PersistedState = ResourceState | ActionState;
13
14 export const isActionState = (s: PersistedState | undefined): s is ActionState =>
15 !!s && (s as any).kind === "action";
16
17 export const isResourceState = (s: PersistedState | undefined): s is ResourceState =>
18 !!s && (s as any).kind !== "task";
19
20 export class StateStoreError extends Data.TaggedError("StateStoreError")<{
21 message: string;
22 cause?: Error;
23 /** HTTP failure metadata without the request, response body, or credentials. */
24 http?: {
25 /** Undefined when the HTTP client failed before receiving a response. */
26 status?: number;
27 };
28 /** Set when the store must be bootstrapped or upgraded first, as CI never does either. */
29 requires?: { readonly action: "bootstrap" | "upgrade"; readonly command: string };
30 }> {
31 readonly [UserFacingError] = true;
32 }
33
34 export class State extends Context.Service<State, Effect.Effect<StateService>>()("alchemy/State") {}
35
36 /**
37 * State service interface.
38 *
39 * Resources are keyed by FQN (namespace-qualified key) which includes
40 * the full namespace path plus the logical ID. The FQN is used as the
41 * storage key while logicalId remains available in the persisted state
42 * for provider operations.
43 */
44 export interface StateService {
45 /**
46 * Stable identifier for the State store implementation, used for
47 * telemetry tagging (`alchemy.state_store.id`) so we can answer
48 * "which backends are people using" without hard-coding a closed
49 * union. Examples: `"local"`, `"inmemory"`, `"http"`,
50 * `"cloudflare-http"`. Third-party state stores should pick a short,
51 * stable, kebab-case slug.
52 */
53 readonly id: string;
54 /**
55 * Wire / behavioural contract version of this state-store
56 * implementation. For local / in-process stores this is the
57 * `STATE_STORE_VERSION` the CLI was built against; for HTTP-backed
58 * stores it is the version reported by the deployed `/version`
59 * probe.
60 */
61 getVersion(): Effect.Effect<number, StateStoreError, never>;
62 listStacks(): Effect.Effect<readonly string[], StateStoreError, never>;
63 listStages(stack: string): Effect.Effect<readonly string[], StateStoreError, never>;
64 /**
65 * Get a resource by its FQN (namespace-qualified key).
66 */
67 get(request: {
68 stack: string;
69 stage: string;
70 fqn: string;
71 }): Effect.Effect<PersistedState | undefined, StateStoreError, never>;
72 /**
73 * List top-level resources that are still in replacement cleanup.
74 *
75 * Any additional backlog from repeated replacements is stored recursively
76 * in the returned state's `old` chain.
77 */
78 getReplacedResources(request: {
79 stack: string;
80 stage: string;
81 }): Effect.Effect<ReadonlyArray<ReplacedResourceState>, StateStoreError, never>;
82 /**
83 * Set a resource by its FQN (namespace-qualified key).
84 */
85 set<V extends PersistedState>(request: {
86 stack: string;
87 stage: string;
88 fqn: string;
89 value: V;
90 }): Effect.Effect<V, StateStoreError, never>;
91 /**
92 * Delete a resource by its FQN (namespace-qualified key).
93 */
94 delete(request: {
95 stack: string;
96 stage: string;
97 fqn: string;
98 }): Effect.Effect<void, StateStoreError, never>;
99 /**
100 * Delete an entire stack, or a single stage when `stage` is provided.
101 */
102 deleteStack(request: {
103 stack: string;
104 stage?: string;
105 }): Effect.Effect<void, StateStoreError, never>;
106 /**
107 * List all resource FQNs in a stack/stage.
108 */
109 list(request: {
110 stack: string;
111 stage: string;
112 }): Effect.Effect<readonly string[], StateStoreError, never>;
113 /**
114 * Read the persisted stack output for `(stack, stage)`. Returns
115 * `undefined` when the stack has not been deployed (or has been
116 * destroyed) at this stage.
117 *
118 * Stack outputs are written by `apply` once the deploy succeeds and
119 * read by cross-stack references (`yield* OtherStack` /
120 * `OtherStack.stage.<name>` / `Output.stackRef(...)`).
121 */
122 getOutput(request: {
123 stack: string;
124 stage: string;
125 }): Effect.Effect<unknown, StateStoreError, never>;
126 /**
127 * Persist the resolved stack output for `(stack, stage)`.
128 */
129 setOutput(request: {
130 stack: string;
131 stage: string;
132 value: unknown;
133 }): Effect.Effect<unknown, StateStoreError, never>;
134 /**
135 * Move stages into this store from the one it replaces, or back with
136 * `rollback`, for stores that replace another. Idempotent: run it again
137 * to finish what a failure or a blocked stage left.
138 */
139 migrate?(
140 request: StateMigrationRequest,
141 ): Effect.Effect<ReadonlyArray<StateMigration>, StateStoreError, never>;
142 }
143
144 /** Which stages {@link StateService.migrate} moves. */
145 export interface StateMigrationRequest {
146 /** Only this stack's stages. */
147 readonly stack?: string;
148 /** Only stages of this name. */
149 readonly stage?: string;
150 /** Move stages back to the store this one replaces. */
151 readonly rollback?: boolean;
152 }
153
154 /** What {@link StateService.migrate} did with one stage. */
155 export interface StateMigration {
156 readonly stack: string;
157 readonly stage: string;
158 /** e.g. `migrated`, `already-migrated`, `rolled-back`, `blocked` or `failed`. */
159 readonly status: string;
160 /** Records moved. */
161 readonly records?: number;
162 /** Why a stage was not moved. */
163 readonly reason?: string;
164 }