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

main
ts 144 lines 4.98 KB
Raw
1 import { Stack } from "alchemy/Stack";
2 import { Stage } from "alchemy/Stage";
3 import * as Data from "effect/Data";
4 import * as Effect from "effect/Effect";
5
6 type NamespaceTypeId = typeof NamespaceTypeId;
7 const NamespaceTypeId = "Cloudflare.Artifacts.Namespace" as const;
8
9 /**
10 * Cloudflare validation: 2–63 chars, starting with a letter or digit, followed
11 * by letters, digits, `.`, `_`, or `-`. See
12 * https://developers.cloudflare.com/artifacts/platform/limits/.
13 */
14 const ARTIFACTS_NAMESPACE_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]{1,62}$/;
15
16 export class InvalidNamespaceError extends Data.TaggedError("InvalidNamespaceError")<{
17 readonly namespace: string;
18 }> {
19 override get message() {
20 return `Invalid artifacts namespace name '${this.namespace}'. Must be 2-63 characters, start with a letter or digit, and contain only letters, digits, ".", "_", and "-".`;
21 }
22 }
23
24 export type NamespaceProps = {
25 /**
26 * Cloudflare namespace name. The first repo created against a name that
27 * does not exist yet creates the namespace.
28 *
29 * Must be 2–63 characters, start with a letter or digit, and contain only
30 * letters, digits, `.`, `_`, or `-`. If omitted, the lowercased logical id
31 * is used.
32 */
33 namespace?: string;
34 };
35
36 /**
37 * Marker for a Cloudflare Artifacts namespace binding.
38 *
39 * Artifacts namespaces are implicit (created on first repo write) and require
40 * no deploy-time provisioning, so this is a pure binding marker rather than
41 * a full Resource. The Worker provider sees this object in `bindings: { ... }`
42 * and emits the corresponding `{ type: "artifacts", name, namespace }` binding
43 * to the script.
44 */
45 export type Namespace = {
46 kind: NamespaceTypeId;
47 name: string;
48 namespace: string;
49 };
50
51 export const isNamespace = (value: unknown): value is Namespace =>
52 typeof value === "object" &&
53 value !== null &&
54 "kind" in value &&
55 (value as Namespace).kind === NamespaceTypeId;
56
57 /**
58 * A Cloudflare Artifacts namespace — the top-level container for Git-compatible
59 * versioned repositories. See the
60 * {@link https://blog.cloudflare.com/artifacts-git-for-agents-beta/ | Artifacts launch post}
61 * and {@link https://developers.cloudflare.com/artifacts/concepts/namespaces/ | Namespaces docs}.
62 *
63 * Cloudflare creates a namespace implicitly the first time a repo is created
64 * against it (through the REST API or the Worker binding), so the Alchemy
65 * "resource" is a thin binding marker with nothing to provision at deploy
66 * time. Cloudflare also offers an explicit `POST /artifacts/namespaces` route,
67 * needed only to pin a data-location `jurisdiction`; this marker does not
68 * call it. Repos themselves are typically created at runtime through
69 * the bound `Artifacts` API.
70 *
71 * Unlike the other Worker-only bindings, an Artifacts namespace does **not**
72 * auto-bind when yielded — it always requires an explicit access level via
73 * {@link ReadNamespace} / {@link WriteNamespace} / {@link ReadWriteNamespace}.
74 *
75 * ### Declaring a Namespace
76 * **Example:** Default namespace (a unique physical name is generated)
77 * ```typescript
78 * const Repos = Cloudflare.Artifacts.Namespace("Repos");
79 * ```
80 *
81 * **Example:** Override the namespace name (2–63 chars)
82 * ```typescript
83 * const Repos = Cloudflare.Artifacts.Namespace("Repos", { namespace: "starter-repos" });
84 * ```
85 *
86 * ### Binding to a Worker
87 * **Example:** Wiring it into a Worker
88 * ```typescript
89 * export const Worker = Cloudflare.Worker("Worker", {
90 * main: "./src/worker.ts",
91 * bindings: { Repos },
92 * });
93 *
94 * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
95 * // { Repos: Artifacts }
96 * ```
97 *
98 * **Example:** Async-style worker
99 * ```typescript
100 * export default {
101 * async fetch(request: Request, env: WorkerEnv) {
102 * const repo = await env.Repos.create("starter-repo");
103 * return Response.json({ remote: repo.remote, token: repo.token });
104 * },
105 * };
106 * ```
107 *
108 * **Example:** Effect-style worker (explicit access level)
109 * ```typescript
110 * const artifacts = yield* Cloudflare.Artifacts.ReadWriteNamespace(Repos);
111 * const repo = yield* artifacts.create("starter-repo", {
112 * setDefaultBranch: "main",
113 * });
114 * ```
115 *
116 * **Example:** Effect-style worker reading history (read-only access)
117 * ```typescript
118 * const artifacts = yield* Cloudflare.Artifacts.ReadNamespace(Repos);
119 * const repo = yield* artifacts.get("starter-repo");
120 * const commits = yield* repo.log({ ref: "main", limit: 10 });
121 * const readme = yield* repo.readFile({ ref: "main", path: "README.md" });
122 * ```
123 *
124 * @binding
125 * @product Artifacts
126 * @category Developer Platform
127 */
128 export const Namespace: (
129 name: string,
130 props?: NamespaceProps,
131 ) => Effect.Effect<Namespace, never, Stack | Stage> = Effect.fn(function* (
132 name: string,
133 props?: NamespaceProps,
134 ) {
135 const namespace = props?.namespace ? props.namespace : name.toLocaleLowerCase();
136 if (!ARTIFACTS_NAMESPACE_REGEX.test(namespace)) {
137 return yield* Effect.die(new InvalidNamespaceError({ namespace }));
138 }
139 return {
140 kind: NamespaceTypeId,
141 name,
142 namespace,
143 } satisfies Namespace;
144 });