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, 06:00 UTC
| 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 | ]; |