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
| 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 | } |