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

main
ts 449 lines 15.1 KB
Raw
1 /**
2 * The live demo: building Shorty the way an agent would. Every entry is one
3 * keypress and one change; code is cut from the type-checked app in
4 * `snippets/shorty/`, terminal output is written out here, and the browser
5 * shows screenshots from `assets/`.
6 */
7 import type { StepSpec } from "./steps.ts";
8
9 // Terminal colours, matching the CLI.
10 const T = {
11 ok: "\x1b[38;5;113m",
12 bad: "\x1b[38;5;203m",
13 soft: "\x1b[38;5;150m",
14 accent: "\x1b[38;5;173m",
15 dim: "\x1b[2m",
16 bold: "\x1b[1m",
17 reset: "\x1b[0m",
18 };
19 const $ = (cmd: string) => `${T.dim}$${T.reset} ${cmd}`;
20 const TABS = ["agent", "dev", "test"];
21
22 /** A terminal step whose last `fresh` lines are new. */
23 const term = (s: {
24 title: string;
25 notes: string;
26 lines: string[];
27 fresh?: number;
28 tab?: number;
29 group?: string;
30 }): StepSpec => ({
31 kind: "terminal",
32 title: s.title,
33 notes: s.notes,
34 group: s.group ?? `term-${s.tab ?? 0}`,
35 tabs: TABS,
36 active: s.tab ?? 0,
37 lines: s.lines.join("\n"),
38 fresh: s.fresh,
39 });
40
41 /** A code step from the Shorty app: `file` is the label, `regions` what's shown. */
42 const code = (s: {
43 title: string;
44 notes: string;
45 file: string;
46 snippet: string;
47 regions?: string[];
48 /** Regions not written yet at this step. */
49 omit?: string[];
50 marks?: Extract<StepSpec, { kind: "code" }>["marks"];
51 error?: Extract<StepSpec, { kind: "code" }>["error"];
52 group?: string;
53 }): StepSpec => ({
54 kind: "code",
55 group: s.group ?? `demo-${s.file}`,
56 file: s.file,
57 title: s.title,
58 src: { snippet: `shorty/${s.snippet}`, regions: s.regions ?? ["show"], omit: s.omit },
59 marks: s.marks,
60 error: s.error,
61 notes: s.notes,
62 });
63
64 const TSC_ERROR = [
65 $("tsc --noEmit"),
66 `${T.bad}src/Api.ts:22:44${T.reset} - ${T.bad}error${T.reset} TS2322:`,
67 ` Type 'LinkStoreError' is not assignable to type 'never'.`,
68 ``,
69 `${T.dim}Found 1 error.${T.reset}`,
70 ];
71 const TSC_OK = [$("tsc --noEmit"), `${T.ok}✓${T.reset} no errors`];
72 const TEST_START = [$("bun test"), `${T.dim}deploying Shorty to a local stage…${T.reset}`];
73 const TEST_OK = [
74 `${T.ok}✓${T.reset} creates and reads back a link ${T.dim}(38ms)${T.reset}`,
75 `${T.ok}✓${T.reset} a missing link is a typed LinkNotFound ${T.dim}(9ms)${T.reset}`,
76 `${T.ok}✓${T.reset} lists every link ${T.dim}(12ms)${T.reset}`,
77 ``,
78 `${T.ok}3 pass${T.reset} ${T.dim}· 0 fail · 1.4s${T.reset}`,
79 ];
80 const DEV = [
81 $("alchemy dev"),
82 `${T.ok}✓${T.reset} Api ${T.dim}(Cloudflare.Worker)${T.reset} http://localhost:1337`,
83 `${T.ok}✓${T.reset} Db ${T.dim}(Cloudflare.D1.Database)${T.reset} local`,
84 ];
85 const DEV_WEB = [
86 ...DEV,
87 `${T.ok}✓${T.reset} Web ${T.dim}(Cloudflare.Website)${T.reset} http://localhost:5173`,
88 ];
89 const PLAN = [
90 $("alchemy deploy --stage prod"),
91 `${T.ok}✓${T.reset} Plan ready ${T.dim}(0.9s)${T.reset}`,
92 ``,
93 `${T.accent}${T.bold}Deploy${T.reset}${T.dim} · ${T.reset}${T.ok}4 to create${T.reset}`,
94 `${T.ok}+${T.reset} ${T.bold}Postgres${T.reset} ${T.dim}(Neon.Project)${T.reset}`,
95 `${T.ok}+${T.reset} ${T.bold}Pool${T.reset} ${T.dim}(Cloudflare.Hyperdrive)${T.reset}`,
96 `${T.ok}+${T.reset} ${T.bold}Api${T.reset} ${T.dim}(Cloudflare.Worker)${T.reset}`,
97 ` ${T.ok}+${T.reset} ${T.soft}Pool${T.reset}`,
98 `${T.ok}+${T.reset} ${T.bold}Web${T.reset} ${T.dim}(Cloudflare.Website)${T.reset}`,
99 ``,
100 `${T.bold}Deploy?${T.reset} ${T.accent}${T.bold}› Deploy${T.reset} ${T.dim}Cancel${T.reset}`,
101 ];
102 const APPLIED = [
103 $("alchemy deploy --stage prod"),
104 `${T.ok}✓${T.reset} Postgres ${T.dim}(Neon.Project)${T.reset} created ${T.dim}(4.1s)${T.reset}`,
105 `${T.ok}✓${T.reset} Pool ${T.dim}(Cloudflare.Hyperdrive)${T.reset} created ${T.dim}(1.3s)${T.reset}`,
106 `${T.ok}✓${T.reset} Api ${T.dim}(Cloudflare.Worker)${T.reset} created ${T.dim}(5.8s)${T.reset}`,
107 `${T.ok}✓${T.reset} Web ${T.dim}(Cloudflare.Website)${T.reset} created ${T.dim}(7.2s)${T.reset}`,
108 ``,
109 `${T.ok}Stack deployed (4/4)${T.reset}`,
110 `${T.dim}web:${T.reset} https://shorty-web-prod.workers.dev`,
111 ];
112
113 /** A chain of steps building one file up: each entry omits the regions not written yet. */
114 const chain = (
115 base: { file: string; snippet: string; group?: string; regions?: string[] },
116 steps: {
117 title: string;
118 notes: string;
119 omit?: string[];
120 snippet?: string;
121 marks?: Extract<StepSpec, { kind: "code" }>["marks"];
122 error?: Extract<StepSpec, { kind: "code" }>["error"];
123 }[],
124 ): StepSpec[] => steps.map((s) => code({ ...base, ...s, snippet: s.snippet ?? base.snippet }));
125
126 const LINK = { file: "src/Link.ts", snippet: "Link.ts" };
127 const API_SCHEMA = { file: "src/ShortyApi.ts", snippet: "ShortyApi.ts" };
128 const LINKS = {
129 file: "src/Links.ts",
130 snippet: "Links.ts",
131 group: "demo-links",
132 regions: ["service"],
133 };
134 const WORKER = { file: "src/Api.ts", snippet: "ApiDraft.error.ts", group: "demo-api" };
135 const TEST = { file: "test/api.test.ts", snippet: "api.test.ts" };
136 const STACK = { file: "alchemy.run.ts", snippet: "StackWeb.ts", group: "demo-stack" };
137 const NEON = { file: "src/Storage.ts", snippet: "Storage.ts", regions: ["neon"] };
138
139 export const demo: StepSpec[] = [
140 {
141 kind: "slide",
142 layout: "section",
143 title: "Let's build something",
144 eyebrow: "Demo",
145 heading: "Let's build something",
146 subtitle: "A link shortener, built the way an agent would",
147 notes:
148 "Let's build Shorty, a link shortener, the way you'd build it with an agent: API first, types and tests on every change, then a website, then production.",
149 },
150
151 // 1. The data
152 ...chain(LINK, [
153 {
154 title: "Start with the data, a Link",
155 omit: ["notFound"],
156 notes:
157 "Everything starts from the schema. A Link is a short code, the URL it points to, and when it was created.",
158 },
159 {
160 title: "A missing link is a typed error",
161 omit: ["status"],
162 notes:
163 "What happens when a code doesn't exist? That's LinkNotFound: a real error type, not a null.",
164 },
165 {
166 title: "…that becomes a 404 over HTTP",
167 notes: "One annotation, and the same error is a 404 when it crosses HTTP.",
168 },
169 ]),
170
171 // 2. The API, as a schema
172 ...chain(API_SCHEMA, [
173 {
174 title: "The first endpoint creates a link",
175 omit: ["get", "list", "api"],
176 notes: "Now the API. POST /links takes a URL and returns a Link.",
177 },
178 {
179 title: "Then one to get a link by its code",
180 omit: ["getError", "list", "api"],
181 notes: "GET /links/:code returns the Link…",
182 },
183 {
184 title: "…which can fail with LinkNotFound",
185 omit: ["list", "api"],
186 notes: "…or LinkNotFound, which is now part of the contract.",
187 },
188 { title: "And one to list every link", omit: ["api"], notes: "And GET /links lists them all." },
189 {
190 title: "Together they're one API, as a value",
191 notes:
192 "ShortyApi is a value. The Worker will serve it, and the tests and the website will call it with a client derived from it.",
193 },
194 ]),
195
196 // 3. Storage, as a service
197 ...chain(LINKS, [
198 {
199 title: "Storage is a service, so the API never names a database",
200 omit: ["storeError", "get", "list"],
201 notes:
202 "Links is an interface: create a link. The Worker will depend on this, never on a database.",
203 },
204 {
205 title: "It can also get and list links",
206 omit: ["storeError"],
207 notes: "Get one by code, and list them all.",
208 },
209 {
210 title: "Storage can fail, and the type says so",
211 notes:
212 "And every method can fail with a LinkStoreError, because databases fail. It's in the type.",
213 },
214 ]),
215
216 // 4. The Worker
217 ...chain(WORKER, [
218 {
219 title: "The agent writes a Worker that asks for Links",
220 omit: ["handlers", "fetch"],
221 error: { hide: true },
222 notes:
223 "Now the agent writes the Worker. It asks for Links, and for now provides it backed by D1.",
224 },
225 {
226 title: "create calls Links",
227 omit: ["get", "list", "fetch"],
228 error: { hide: true },
229 notes: "Implement create by calling links.create.",
230 },
231 {
232 title: "get and list turn storage failures into a 500",
233 omit: ["fetch"],
234 error: { hide: true },
235 notes:
236 "get and list call Links too. A storage failure there is a defect, so it dies: the platform returns a 500.",
237 },
238 {
239 title: "fetch serves the whole API",
240 error: { hide: true },
241 notes: "fetch serves ShortyApi with those handlers.",
242 },
243 ]),
244
245 // 5. The loop: types, fix, tests
246 term({
247 title: "The agent checks its work with tsc first",
248 notes: "Before anything runs, the agent type-checks. It's the fastest signal there is.",
249 lines: TSC_ERROR,
250 }),
251 code({
252 ...WORKER,
253 title: "It forgot that create can fail with a LinkStoreError",
254 error: {
255 below: true,
256 pick: (lines) =>
257 lines.some((l) => l.includes("'LinkStoreError' is not assignable"))
258 ? ["Type 'LinkStoreError' is not assignable to type 'never'."]
259 : [],
260 },
261 notes:
262 "And it caught something real. create can fail with a LinkStoreError, and the API contract doesn't have that error. Errors are in the type, so this is a compile error, not a surprise in production.",
263 }),
264 code({
265 ...WORKER,
266 snippet: "Api.ts",
267 title: "So the agent decides what that failure means",
268 notes: "Same decision as get: a storage failure is a defect.",
269 }),
270 term({ title: "tsc passes", notes: "Type-check again.", lines: TSC_OK, group: "tsc-ok" }),
271 ...chain(TEST, [
272 {
273 title: "Now a test, which deploys the real Stack",
274 omit: ["dev", "deploy", "test"],
275 notes:
276 "Types can't tell us the endpoints behave, so the agent writes a test. Test.make deploys the real Stack.",
277 },
278 {
279 title: "dev: true runs it on your machine",
280 omit: ["deploy", "test"],
281 marks: [
282 {
283 kind: "circle",
284 find: "dev: true",
285 label: "local, in seconds",
286 side: "right",
287 tone: "good",
288 },
289 ],
290 notes:
291 "dev: true deploys to local simulators instead of the cloud: a local Worker, a local D1. No accounts, no waiting. That's what makes this fast enough for an agent's loop.",
292 },
293 {
294 title: "Deploy it once, before the tests",
295 omit: ["test"],
296 notes: "Deploy the Stack once for the whole file.",
297 },
298 {
299 title: "Each test gets a typed client to the deployed API",
300 omit: ["create", "check"],
301 notes:
302 "The test calls the API through a client derived from ShortyApi, the same one the website will use.",
303 },
304 { title: "Create a link…", omit: ["check"], notes: "Create a link…" },
305 { title: "…and read it back", notes: "…and read it back." },
306 ]),
307 term({
308 title: "The agent runs the tests…",
309 notes: "bun test deploys the Stack to a local stage.",
310 tab: 2,
311 lines: TEST_START,
312 }),
313 term({
314 title: "…and they pass, in about a second",
315 notes:
316 "About a second and a half, including standing up the Worker and the database. That's the loop: types, then tests.",
317 tab: 2,
318 lines: [...TEST_START, ...TEST_OK],
319 fresh: TEST_OK.length,
320 }),
321
322 // 6. A website
323 code({
324 ...STACK,
325 snippet: "alchemy.run.ts",
326 title: "So far the Stack is just the API",
327 notes: "Here's the Stack so far: just the Worker.",
328 }),
329 ...chain(STACK, [
330 {
331 title: "Add a website to the Stack",
332 omit: ["env", "returnWeb"],
333 notes: "The website is one more resource: a Vite site on Cloudflare.",
334 },
335 {
336 title: "…and give it the API's URL",
337 omit: ["returnWeb"],
338 notes: "It gets the Worker's URL as an environment variable.",
339 },
340 {
341 title: "…and return its URL too",
342 omit: ["returnApi"],
343 notes: "And the Stack returns the website's URL.",
344 },
345 ]),
346 code({
347 title: "The website calls the API through the same typed client",
348 notes:
349 "The website calls the API with a client derived from ShortyApi. Rename an endpoint and the website stops compiling.",
350 file: "web/src/client.ts",
351 snippet: "client.ts",
352 }),
353 term({
354 title: "alchemy dev runs it all locally",
355 notes:
356 "alchemy dev brings up the Worker, the database and the website locally, and reloads on every save.",
357 tab: 1,
358 lines: DEV_WEB,
359 }),
360 {
361 kind: "browser",
362 title: "Shorty, running locally",
363 url: "http://localhost:5173",
364 image: "01-api-browser-3.png",
365 notes: "Here's the website, talking to the local API.",
366 },
367 {
368 kind: "browser",
369 title: "Shorten another link",
370 url: "http://localhost:5173",
371 image: "02-d1-browser-1.png",
372 notes: "Shorten a link: the website calls the Worker, the Worker writes to the local database.",
373 },
374
375 // 7. Postgres, then production
376 code({
377 ...WORKER,
378 snippet: "ApiNeon.ts",
379 title: "For production, let's use Postgres on Neon",
380 marks: [{ kind: "underline", find: "NeonStorage", tone: "construct" }],
381 notes:
382 "For production I want Postgres. Links is a service, so it's a one-word change: provide the Neon layer instead of D1.",
383 }),
384 ...chain(NEON, [
385 {
386 title: "NeonStorage starts with a Neon Postgres project",
387 omit: ["pool", "connect", "sql", "bind"],
388 notes:
389 "So what is NeonStorage? It starts with a Neon Postgres project, running the same migrations as D1.",
390 },
391 {
392 title: "Hyperdrive pools connections to it at the edge",
393 omit: ["dev", "caching", "connect", "sql", "bind"],
394 notes:
395 "Workers are short-lived, so Hyperdrive keeps a pool of connections to Neon, close to the Worker.",
396 },
397 {
398 title: "In dev, it connects straight to Neon's own pooler",
399 omit: ["caching", "connect", "sql", "bind"],
400 notes:
401 "Under alchemy dev there's no Hyperdrive, so it goes straight to Neon's pooler instead.",
402 },
403 {
404 title: "Caching off, so a new link is readable right away",
405 omit: ["connect", "sql", "bind"],
406 notes: "Hyperdrive can cache queries. Links need read-after-write, so caching is off.",
407 },
408 {
409 title: "The Worker connects to the pool…",
410 omit: ["sql"],
411 notes:
412 "Connect binds the Worker to the pool, and the binding layer wires it up at deploy time.",
413 },
414 {
415 title: "…and hands LinksSql a Postgres client",
416 notes:
417 "And the result is a Postgres SQL client, which is all LinksSql needs. The Worker's code didn't change.",
418 },
419 ]),
420 term({ title: "tsc passes", notes: "Types first, as always.", lines: TSC_OK, group: "tsc-2" }),
421 term({
422 title: "…and the same tests pass against Postgres",
423 notes: "The same tests, unchanged, now against Postgres.",
424 tab: 2,
425 lines: [...TEST_START, ...TEST_OK],
426 fresh: TEST_OK.length,
427 group: "test-2",
428 }),
429 term({
430 title: "Deploy to production, starting with a plan",
431 notes:
432 "alchemy deploy runs the Stack and shows the plan: Neon, Hyperdrive, the Worker with its binding, and the website.",
433 lines: PLAN,
434 group: "deploy",
435 }),
436 term({
437 title: "Approve it, and it's live",
438 notes: "Approve, and the providers create everything in order.",
439 lines: APPLIED,
440 group: "deploy-applied",
441 }),
442 {
443 kind: "browser",
444 title: "Shorty, in production",
445 url: "https://shorty-web-prod.workers.dev",
446 image: "09-deploy-browser-3.png",
447 notes: "And there it is, in production, backed by Postgres. Same code, same tests.",
448 },
449 ];