@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 1,007 lines 32.2 KB
Raw
1 /**
2 * Generates `public/llms.txt` and `public/llms-full.txt` — navigation
3 * indexes of the docs pages, grouped by section, with title + description
4 * pulled from each page's frontmatter.
5 *
6 * `llms.txt` covers the guides and concept docs and links to
7 * `llms-full.txt`, which additionally lists every generated service-level
8 * API reference page (the Providers section) and is much larger.
9 *
10 * Run with: `bun scripts/generate-llms-txt.ts`
11 *
12 * Section ordering, headings, and prose intros are configured here.
13 * Page metadata (title, description) comes from the source frontmatter,
14 * so editing a page's frontmatter is enough to update llms.txt.
15 */
16
17 import { readdir, readFile, writeFile } from "node:fs/promises";
18 import path from "node:path";
19 import { fileURLToPath } from "node:url";
20
21 const here = path.dirname(fileURLToPath(import.meta.url));
22 const docsDir = path.resolve(here, "../src/content/docs");
23 const outFile = path.resolve(here, "../public/llms.txt");
24 const outFullFile = path.resolve(here, "../public/llms-full.txt");
25 const siteUrl = "https://alchemy.run";
26
27 interface Page {
28 /** URL path, e.g. "/infrastructure-as-effects/binding" */
29 href: string;
30 /** Path relative to docs dir without extension, e.g. "infrastructure-as-effects/binding" */
31 slug: string;
32 title: string;
33 description: string;
34 draft: boolean;
35 /** `sidebar.order` from frontmatter; `Infinity` when unset. */
36 order: number;
37 }
38
39 interface Section {
40 /** H2 heading */
41 heading: string;
42 /** Optional prose paragraph after the heading. */
43 intro?: string;
44 /**
45 * Pages to include. Either a list of explicit slugs (relative to docs dir,
46 * no extension) in the desired order, or a directory to enumerate
47 * alphabetically.
48 */
49 pages: { slugs: string[] } | { directory: string; exclude?: string[] };
50 }
51
52 const SECTIONS: Section[] = [
53 {
54 heading: "Start here",
55 pages: {
56 slugs: ["what-is-alchemy", "getting-started", "migrating-from-v1"],
57 },
58 },
59 {
60 heading: "CLI",
61 intro:
62 "Every command runs through your package manager: bun alchemy <command>. Command pages by role, the Programmatic API for running them from scripts, plus the Adopting Resources and Inspecting State guides.",
63 pages: {
64 slugs: [
65 "cli/index",
66 "cli/api",
67 "cli/deploy",
68 "cli/plan",
69 "cli/destroy",
70 "cli/drift",
71 "cli/nuke",
72 "cli/adopting-resources",
73 "cli/dev",
74 "cli/logs",
75 "cli/profile",
76 "cli/state",
77 "cli/inspecting-state",
78 "cli/aws",
79 "cli/cloudflare",
80 ],
81 },
82 },
83 {
84 heading: "Infrastructure as Code",
85 intro:
86 "The noun graph and its semantics: Stacks of Resources and Actions, data flow via Inputs & Outputs and References, deploy behavior via the Resource lifecycle and Providers.",
87 pages: {
88 slugs: [
89 "infrastructure-as-code/stack",
90 "infrastructure-as-code/resource",
91 "infrastructure-as-code/action",
92 "infrastructure-as-code/outputs",
93 "infrastructure-as-code/references",
94 "infrastructure-as-code/resource-lifecycle",
95 "infrastructure-as-code/renaming",
96 "infrastructure-as-code/provider",
97 "infrastructure-as-code/custom-provider",
98 "infrastructure-as-code/local-provider",
99 "infrastructure-as-code/dns-adapters",
100 "infrastructure-as-code/contributions",
101 ],
102 },
103 },
104 {
105 heading: "Infrastructure as Effects",
106 intro:
107 "How app code and infrastructure compose: Runtime, Bindings, the Construction and Runtime Phases, and Layers.",
108 pages: {
109 slugs: [
110 "infrastructure-as-effects/runtime",
111 "infrastructure-as-effects/binding",
112 "infrastructure-as-effects/layers",
113 "infrastructure-as-effects/event-sources",
114 "infrastructure-as-effects/sinks",
115 "infrastructure-as-effects/phases",
116 "infrastructure-as-effects/circular-bindings",
117 "infrastructure-as-effects/custom-runtime",
118 "infrastructure-as-effects/telemetry",
119 ],
120 },
121 },
122 {
123 heading: "APIs",
124 intro:
125 "Typed calls between Functions and Servers: schemaless RPC for internal communication, Effect RPC and Effect HTTP for trust boundaries.",
126 pages: {
127 slugs: ["apis/index", "apis/schemaless", "apis/effect-rpc", "apis/effect-http"],
128 },
129 },
130 {
131 heading: "Environments — the same app in many places",
132 intro:
133 "Stages, credential profiles, auth providers, secrets and config, local development, and CI.",
134 pages: {
135 slugs: [
136 "environments/stages",
137 "environments/profiles",
138 "environments/auth-providers",
139 "environments/custom-auth-provider",
140 "environments/secrets",
141 "environments/secret-providers",
142 "environments/doppler",
143 "environments/infisical",
144 "environments/local-development",
145 "environments/worktrees",
146 "environments/ci",
147 ],
148 },
149 },
150 {
151 heading: "State Store",
152 pages: { slugs: ["state-store/index", "state-store/custom-state-store"] },
153 },
154 {
155 heading: "Project structure",
156 intro:
157 "Scaling the codebase: file conventions for one stack, monorepos for many — single Stack or one per package.",
158 pages: {
159 slugs: [
160 "project-structure/file-layout",
161 "project-structure/monorepo",
162 "project-structure/monorepo-single-stack",
163 "project-structure/monorepo-multi-stack",
164 ],
165 },
166 },
167 {
168 heading: "Testing & observability",
169 intro:
170 "Tests run against real clouds: the model, the end-to-end walkthrough, provider-lifecycle testing, and the harness reference.",
171 pages: {
172 slugs: [
173 "testing/index",
174 "testing/testing-a-stack",
175 "testing/testing-providers",
176 "testing/test-harness",
177 "testing/observability",
178 ],
179 },
180 },
181 {
182 heading: "Cloudflare — start here",
183 intro:
184 "The Cloudflare hub: overview (resources + recipes), setup (install, account, OAuth vs API token, profiles), and local development.",
185 pages: { slugs: ["cloudflare/index", "cloudflare/setup", "cloudflare/local-development"] },
186 },
187 {
188 heading: "Cloudflare — tutorial",
189 intro:
190 "A linear six-part walkthrough from zero to a tested, locally-developed, CI-deployed, observable Cloudflare project. Each part builds on the previous one.",
191 pages: { directory: "cloudflare/tutorial" },
192 },
193 {
194 heading: "Cloudflare — Compute",
195 pages: { directory: "cloudflare/compute" },
196 },
197 {
198 heading: "Cloudflare — Frontend",
199 pages: { directory: "cloudflare/frontend" },
200 },
201 {
202 heading: "Cloudflare — APIs",
203 pages: { directory: "cloudflare/apis" },
204 },
205 {
206 heading: "Cloudflare — Data",
207 pages: { directory: "cloudflare/data" },
208 },
209 {
210 heading: "Cloudflare — Messaging & events",
211 pages: { directory: "cloudflare/messaging" },
212 },
213 {
214 heading: "Cloudflare — Email",
215 pages: { directory: "cloudflare/email" },
216 },
217 {
218 heading: "Cloudflare — AI",
219 pages: { directory: "cloudflare/ai" },
220 },
221 {
222 heading: "Cloudflare — Security & secrets",
223 pages: { directory: "cloudflare/security" },
224 },
225 {
226 heading: "Cloudflare — Observability",
227 pages: { directory: "cloudflare/observability" },
228 },
229 {
230 heading: "Cloudflare — Networking",
231 pages: { directory: "cloudflare/networking" },
232 },
233 {
234 heading: "Prisma — start here",
235 pages: { slugs: ["prisma/index", "prisma/setup"] },
236 },
237 {
238 heading: "Prisma — tutorial",
239 intro:
240 "A four-part walkthrough: a Project, an Effect-native Compute API, Postgres, and a Vite frontend.",
241 pages: { directory: "prisma/tutorial" },
242 },
243 {
244 heading: "Prisma — Compute",
245 pages: { directory: "prisma/compute" },
246 },
247 {
248 heading: "Prisma — Data",
249 pages: { directory: "prisma/data" },
250 },
251 {
252 heading: "Prisma — Frontend",
253 pages: { directory: "prisma/frontend" },
254 },
255 {
256 heading: "Prisma — Guides",
257 pages: { directory: "prisma/guides" },
258 },
259 {
260 heading: "AWS — start here",
261 intro:
262 "The AWS hub: overview (runtimes + resources + recipes), setup (credentials, profiles, region), local development, and the Lambda vs ECS vs EKS vs EC2 decision page.",
263 pages: {
264 slugs: ["aws/index", "aws/setup", "aws/local-development", "aws/compute/choosing-a-runtime"],
265 },
266 },
267 {
268 heading: "AWS — tutorial",
269 intro:
270 "A linear five-part walkthrough from zero to a tested, CI-deployed AWS project. Each part builds on the previous one.",
271 pages: {
272 slugs: [
273 "aws/tutorial/part-1",
274 "aws/tutorial/part-2",
275 "aws/tutorial/part-3",
276 "aws/tutorial/part-4",
277 "aws/tutorial/part-5",
278 ],
279 },
280 },
281 {
282 heading: "AWS — Compute",
283 pages: { directory: "aws/compute", exclude: ["aws/compute/choosing-a-runtime"] },
284 },
285 {
286 heading: "AWS — Frontend",
287 pages: { directory: "aws/frontend" },
288 },
289 {
290 heading: "AWS — APIs",
291 pages: { directory: "aws/apis" },
292 },
293 {
294 heading: "AWS — Data",
295 pages: { directory: "aws/data" },
296 },
297 {
298 heading: "AWS — AI",
299 pages: { directory: "aws/ai" },
300 },
301 {
302 heading: "AWS — Messaging & events",
303 pages: { directory: "aws/messaging" },
304 },
305 {
306 heading: "AWS — Email",
307 pages: { directory: "aws/email" },
308 },
309 {
310 heading: "AWS — Security & secrets",
311 pages: { directory: "aws/security" },
312 },
313 {
314 heading: "AWS — Observability",
315 pages: { directory: "aws/observability" },
316 },
317 {
318 heading: "AWS — Networking",
319 pages: { directory: "aws/networking" },
320 },
321 {
322 heading: "GCP",
323 intro:
324 "Google Cloud as Stack resources — Cloud Run services and jobs, Firestore, Pub/Sub, BigQuery, Secret Manager, Memorystore. Bindings grant IAM onto a per-host service account.",
325 pages: {
326 slugs: ["gcp/index", "gcp/setup"],
327 },
328 },
329 {
330 heading: "GCP — Tutorial",
331 pages: { directory: "gcp/tutorial" },
332 },
333 {
334 heading: "GCP — Compute",
335 pages: { directory: "gcp/compute" },
336 },
337 {
338 heading: "GCP — Frontend",
339 pages: { directory: "gcp/frontend" },
340 },
341 {
342 heading: "GCP — APIs",
343 pages: { directory: "gcp/apis" },
344 },
345 {
346 heading: "GCP — Data",
347 pages: { directory: "gcp/data" },
348 },
349 {
350 heading: "GCP — AI",
351 pages: { directory: "gcp/ai" },
352 },
353 {
354 heading: "GCP — Messaging & events",
355 pages: { directory: "gcp/messaging" },
356 },
357 {
358 heading: "GCP — Security & secrets",
359 pages: { directory: "gcp/security" },
360 },
361 {
362 heading: "GCP — Observability",
363 pages: { directory: "gcp/observability" },
364 },
365 {
366 heading: "GCP — Networking",
367 pages: { directory: "gcp/networking" },
368 },
369 {
370 heading: "Fly — start here",
371 intro:
372 "The Fly hub: overview (Apps, Machines, Services, Sprites), setup (org, API token, profile), and networking.",
373 pages: {
374 slugs: ["fly/index", "fly/setup", "fly/networking"],
375 },
376 },
377 {
378 heading: "Fly — Tutorial",
379 pages: { directory: "fly/tutorial" },
380 },
381 {
382 heading: "Fly — Compute",
383 pages: { directory: "fly/compute" },
384 },
385 {
386 heading: "Fly — Data",
387 pages: { directory: "fly/data" },
388 },
389 {
390 heading: "Fly — Frontend",
391 pages: { directory: "fly/frontend" },
392 },
393 {
394 heading: "Hetzner — start here",
395 intro:
396 "The Hetzner hub: overview (Servers and Services) and setup (project, API token, profile).",
397 pages: {
398 slugs: ["hetzner/index", "hetzner/setup"],
399 },
400 },
401 {
402 heading: "Hetzner — Tutorial",
403 pages: { directory: "hetzner/tutorial" },
404 },
405 {
406 heading: "Hetzner — Compute",
407 pages: { directory: "hetzner/compute" },
408 },
409 {
410 heading: "Hetzner — Data",
411 pages: { directory: "hetzner/data" },
412 },
413 {
414 heading: "Hetzner — Networking",
415 pages: { directory: "hetzner/networking" },
416 },
417 {
418 heading: "Hetzner — Frontend",
419 pages: { directory: "hetzner/frontend" },
420 },
421 {
422 heading: "Railway — start here",
423 intro:
424 "The Railway hub: overview (Projects, Services, databases), setup (workspace, API token, profile), and networking.",
425 pages: {
426 slugs: ["railway/index", "railway/setup", "railway/networking"],
427 },
428 },
429 {
430 heading: "Railway — Tutorial",
431 pages: { directory: "railway/tutorial" },
432 },
433 {
434 heading: "Railway — Compute",
435 pages: { directory: "railway/compute" },
436 },
437 {
438 heading: "Railway — Data",
439 pages: { directory: "railway/data" },
440 },
441 {
442 heading: "Railway — Frontend",
443 pages: { directory: "railway/frontend" },
444 },
445 {
446 heading: "PlanetScale",
447 intro:
448 "Serverless MySQL & Postgres as Stack resources. Composes with Cloudflare Hyperdrive and Drizzle — those guides are listed under Cloudflare.",
449 pages: {
450 slugs: [
451 "planetscale/index",
452 "planetscale/setup",
453 "planetscale/data/postgres",
454 "planetscale/data/mysql",
455 "planetscale/data/migrations",
456 "planetscale/data/credentials",
457 "planetscale/data/backups",
458 "planetscale/guides/preview-branches",
459 "planetscale/guides/drizzle",
460 ],
461 },
462 },
463 {
464 heading: "Neon",
465 intro:
466 "Neon backend resources: Postgres branches, Functions, private object storage, managed Auth, Data API, AI Gateway and Website adapters. The upload tutorial combines native and Effect handlers with authenticated browser uploads.",
467 pages: {
468 slugs: [
469 "neon/index",
470 "neon/setup",
471 "neon/governance",
472 "neon/guides/ai-gateway",
473 "neon/guides/production-auth",
474 "neon/guides/private-networking",
475 "neon/guides/custom-domains",
476 "neon/guides/state-recovery",
477 "neon/tutorial/index",
478 "neon/tutorial/backend",
479 "neon/tutorial/functions",
480 "neon/tutorial/frontend",
481 "neon/tutorial/previews",
482 "neon/data/branching",
483 "neon/data/connections",
484 "neon/data/roles",
485 "neon/data/migrations",
486 "neon/guides/preview-branches",
487 "neon/guides/drizzle",
488 ],
489 },
490 },
491 {
492 heading: "Neon — Frontend",
493 pages: { directory: "neon/frontend" },
494 },
495 {
496 heading: "Turso",
497 intro:
498 "Turso SQLite databases as Stack resources: groups, databases, migrations, connections, a database per tenant, preview databases, and scoped tokens.",
499 pages: {
500 slugs: [
501 "turso/index",
502 "turso/setup",
503 "turso/tutorial/part-1",
504 "turso/tutorial/part-2",
505 "turso/tutorial/part-3",
506 "turso/groups",
507 "turso/databases",
508 "turso/migrations",
509 "turso/connections",
510 "turso/database-per-tenant",
511 "turso/preview-databases",
512 "turso/tokens",
513 "turso/organization",
514 ],
515 },
516 },
517 {
518 heading: "Better Auth",
519 intro:
520 "Better Auth as an Effect service on Workers and Lambda: a tutorial, sign-in providers, database layers, and guides for config, middleware, secondary storage, migrations, and upgrades.",
521 pages: { slugs: ["better-auth/index"] },
522 },
523 {
524 heading: "Better Auth — Tutorial",
525 pages: { directory: "better-auth/tutorial" },
526 },
527 {
528 heading: "Better Auth — Sign-in providers",
529 pages: { directory: "better-auth/sign-in-providers" },
530 },
531 {
532 heading: "Better Auth — Databases",
533 pages: { directory: "better-auth/databases" },
534 },
535 {
536 heading: "Better Auth — Guides",
537 pages: {
538 slugs: [
539 "better-auth/guides/configuration",
540 "better-auth/guides/http-api-middleware",
541 "better-auth/guides/secondary-storage",
542 "better-auth/guides/migrations",
543 "better-auth/upgrades/from-1-6-to-1-7",
544 ],
545 },
546 },
547 {
548 heading: "Axiom",
549 intro:
550 "Observability as Stack resources — datasets, monitors, notifiers. The exporter-Layer pattern is documented in Concepts → Observability.",
551 pages: {
552 slugs: [
553 "axiom/index",
554 "axiom/setup",
555 "axiom/data/ingest",
556 "axiom/guides/alerting",
557 "axiom/guides/dashboards",
558 "axiom/guides/annotations",
559 ],
560 },
561 },
562 {
563 heading: "GitHub",
564 intro:
565 "Repos, secrets, variables, and repository event sources as Stack resources; the CI/CD guides live under Guides and each cloud's tutorial part 5.",
566 pages: {
567 slugs: [
568 "github/index",
569 "github/setup",
570 "github/repository",
571 "github/actions-config",
572 "github/events",
573 ],
574 },
575 },
576 {
577 heading: "Git",
578 intro:
579 "A git server you build in one file, use like any remote, and reshape one block at a time: setup, a six-part tutorial (push, access control, publishing, per-user credentials, your app's API, branch protection), the REST and GitHub-compatible planes, the building blocks with their implementations, and recipes with the scaling model and measurements.",
580 pages: {
581 slugs: [
582 "git/index",
583 "git/getting-started",
584 "git/tutorial/part-1",
585 "git/tutorial/part-2",
586 "git/tutorial/part-3",
587 "git/tutorial/part-4",
588 "git/tutorial/part-5",
589 "git/tutorial/part-6",
590 "git/clone-and-push",
591 "git/repositories",
592 "git/pull-requests",
593 "git/github-api",
594 "git/blocks/index",
595 "git/blocks/server",
596 "git/blocks/engine",
597 "git/blocks/repositories",
598 "git/blocks/registry",
599 "git/blocks/blob-store",
600 "git/blocks/hasher",
601 "git/blocks/auth",
602 "git/recipes/index",
603 "git/recipes/scaling",
604 "git/recipes/cloudflare",
605 "git/recipes/cloudflare-aws",
606 "git/recipes/your-own-store",
607 ],
608 },
609 },
610 {
611 heading: "Stripe",
612 intro:
613 "Products, prices, coupons, customers, payment links, and webhooks as Stack resources. HTTP bindings run inside a Worker or Lambda.",
614 pages: {
615 slugs: [
616 "stripe/index",
617 "stripe/setup",
618 "stripe/guides/subscriptions",
619 "stripe/guides/connect",
620 "stripe/guides/webhooks",
621 ],
622 },
623 },
624 {
625 heading: "Docker",
626 intro:
627 "Local and CI Docker as Stack resources — images, containers, networks, and volumes driven through the active Docker CLI context; cloud container runtimes (Cloudflare Containers, ECS) consume the pushed image refs from their own hubs.",
628 pages: {
629 slugs: [
630 "docker/index",
631 "docker/setup",
632 "docker/local-services",
633 "docker/build-and-push",
634 "docker/swarm",
635 ],
636 },
637 },
638 {
639 heading: "Kubernetes",
640 intro:
641 "Cluster-agnostic Kubernetes workloads — Deployments, Jobs and CronJobs (as images or Effect programs), raw manifests, and Helm charts — on a local cluster or any cluster reachable through a kubeconfig, token, client certificate, or exec plugin.",
642 pages: {
643 slugs: [
644 "kubernetes/index",
645 "kubernetes/setup",
646 "kubernetes/tutorial/part-1",
647 "kubernetes/tutorial/part-2",
648 "kubernetes/tutorial/part-3",
649 "kubernetes/tutorial/part-4",
650 "kubernetes/tutorial/part-5",
651 "kubernetes/clusters/connecting",
652 "kubernetes/clusters/registries",
653 "kubernetes/clusters/local",
654 "kubernetes/clusters/eks",
655 "kubernetes/clusters/cluster-adapters",
656 "kubernetes/workloads/deployments",
657 "kubernetes/workloads/jobs",
658 "kubernetes/workloads/images",
659 "kubernetes/workloads/bindings",
660 "kubernetes/workloads/object-lifecycle",
661 "kubernetes/objects/manifests",
662 "kubernetes/objects/helm-charts",
663 ],
664 },
665 },
666 {
667 heading: "SQL",
668 intro:
669 "Database comparison, Effect SQL, Drizzle, Prisma ORM v8 (Postgres-only), committed migrations, and connection lifecycle. Deployment walkthroughs live with their runtime providers.",
670 pages: {
671 slugs: [
672 "sql/index",
673 "sql/databases",
674 "sql/effect-sql/postgres",
675 "sql/effect-sql/mysql",
676 "sql/effect-sql/d1",
677 "sql/effect-sql/libsql",
678 "sql/effect-sql/migrations",
679 "sql/effect-sql/lifecycle",
680 "sql/drizzle/postgres",
681 "sql/drizzle/mysql",
682 "sql/drizzle/d1",
683 "sql/drizzle/libsql",
684 "sql/drizzle/migrations",
685 "sql/prisma/postgres",
686 "sql/prisma/contracts",
687 "sql/prisma/migrations",
688 ],
689 },
690 },
691 {
692 heading: "Command",
693 intro:
694 "Cloud-agnostic local process primitives — memoized builds, one-off commands, and dev servers; the static-site guides in each cloud hub consume them under the hood.",
695 pages: {
696 slugs: ["command/index", "command/memoization", "command/dev-servers"],
697 },
698 },
699 {
700 heading: "ACME",
701 intro:
702 "TLS certificates from any ACME certificate authority as Stack resources, validated over DNS, renewed on deploy, or issued at runtime.",
703 pages: {
704 slugs: [
705 "acme/index",
706 "acme/getting-started",
707 "acme/certificate-authorities",
708 "acme/dns-validation",
709 "acme/renewal",
710 "acme/runtime",
711 "acme/using-certificates",
712 "acme/troubleshooting",
713 ],
714 },
715 },
716 {
717 heading: "Domain",
718 intro:
719 "A domain-driven design framework: model commands, events, aggregates, views, projections, policies, and sagas once, then host them on Durable Objects or in memory.",
720 pages: {
721 slugs: [
722 "domain/index",
723 "domain/what-is-ddd",
724 "domain/project-layout",
725 "domain/tutorial/part-1",
726 "domain/tutorial/part-2",
727 "domain/tutorial/part-3",
728 "domain/tutorial/part-4",
729 "domain/tutorial/part-5",
730 "domain/tutorial/part-6",
731 "domain/tutorial/part-7",
732 "domain/tutorial/part-8",
733 "domain/model",
734 "domain/command",
735 "domain/event",
736 "domain/aggregate",
737 "domain/view",
738 "domain/projection",
739 "domain/stream",
740 "domain/policy",
741 "domain/saga",
742 "domain/external-system",
743 "domain/api",
744 "domain/story",
745 "domain/testing-models",
746 "domain/testing-apis",
747 "domain/foldkit",
748 "domain/optimistic-updates",
749 "domain/local-first",
750 "domain/mcp",
751 "domain/sessions",
752 "domain/better-auth",
753 "domain/view-security",
754 "domain/unique-values",
755 "domain/deadlines",
756 "domain/cloudflare",
757 "domain/backfill",
758 "domain/in-memory",
759 "domain/http-api",
760 "domain/cli",
761 "domain/observability",
762 ],
763 },
764 },
765 ];
766
767 const PROVIDERS_INTRO_BASE = `Service-level API reference, generated from JSDoc on the source \`.ts\` files via \`bun scripts/generate-api-reference.ts\`. Each page groups resources and capabilities by service, with a heading per resource and examples extracted from source JSDoc.`;
768
769 const PROVIDERS_INTRO = `${PROVIDERS_INTRO_BASE} Grouped by cloud below.`;
770
771 /**
772 * Enumerates every generated provider page under `providers/{Cloud}/...`,
773 * grouped by cloud. These pages are produced by `build:reference` (which runs
774 * before this script in the build), so they exist on disk at generation time
775 * even though they are gitignored.
776 */
777 async function renderProvidersSection(): Promise<string> {
778 const providersDir = path.join(docsDir, "providers");
779 let clouds: string[];
780 try {
781 const entries = await readdir(providersDir, { withFileTypes: true });
782 clouds = entries
783 .filter((e) => e.isDirectory())
784 .map((e) => e.name)
785 .sort();
786 } catch (err: any) {
787 if (err?.code === "ENOENT") return `## Providers\n\n${PROVIDERS_INTRO}`;
788 throw err;
789 }
790
791 const blocks: string[] = [`## Providers`, PROVIDERS_INTRO];
792 for (const cloud of clouds) {
793 const slugs = await listSlugs(`providers/${cloud}`);
794 const pages = (await Promise.all(slugs.map(loadPage)))
795 .filter((p) => !p.draft)
796 // Starlight serves provider routes lowercased (e.g. the CamelCase source
797 // `providers/AWS/S3/Bucket.md` is reachable at `/providers/aws/s3/bucket`).
798 .map((p) => ({ ...p, href: p.href.toLowerCase() }))
799 .sort((a, b) => a.title.localeCompare(b.title));
800 if (pages.length === 0) continue;
801 blocks.push(`### ${cloud}`);
802 blocks.push(pages.map(renderPage).join("\n"));
803 }
804 return blocks.join("\n\n");
805 }
806
807 const HEADER = `# Alchemy
808
809 > Alchemy Effect is an Infrastructure-as-Effects (IaE) framework that combines cloud infrastructure and application logic into a single, type-safe program powered by [Effect](https://effect.website). Resources are declared as Effects; bindings wire IAM, env vars, and typed SDKs in one call; deploys and runtime share the same code.
810
811 This file is a navigation index for the documentation site at ${siteUrl}. Guide and concept pages are listed below with their URL and a one-line summary, so an agent can pick the right page in one hop. The service-level API reference is indexed separately in [llms-full.txt](${siteUrl}/llms-full.txt).`;
812
813 const FULL_HEADER = `# Alchemy
814
815 > Alchemy Effect is an Infrastructure-as-Effects (IaE) framework that combines cloud infrastructure and application logic into a single, type-safe program powered by [Effect](https://effect.website). Resources are declared as Effects; bindings wire IAM, env vars, and typed SDKs in one call; deploys and runtime share the same code.
816
817 This file is a navigation index for the documentation site at ${siteUrl}. Every page under \`/src/content/docs/\` is listed below with its URL and a one-line summary, so an agent can pick the right page in one hop. This is the full index including every service-level API reference page; the smaller [llms.txt](${siteUrl}/llms.txt) covers just the guides and concept docs.`;
818
819 function parseFrontmatter(source: string): Record<string, string> {
820 if (!source.startsWith("---")) return {};
821 const end = source.indexOf("\n---", 3);
822 if (end === -1) return {};
823 const block = source.slice(3, end);
824 const out: Record<string, string> = {};
825 for (const rawLine of block.split("\n")) {
826 const line = rawLine.trimEnd();
827 const m = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
828 if (!m) continue;
829 let value = m[2].trim();
830 if (
831 (value.startsWith('"') && value.endsWith('"')) ||
832 (value.startsWith("'") && value.endsWith("'"))
833 ) {
834 value = value.slice(1, -1);
835 }
836 out[m[1]] = value;
837 }
838 return out;
839 }
840
841 /**
842 * Extracts the nested `sidebar.order` value from a frontmatter block.
843 * Starlight uses this to order autogenerated sidebar groups; we mirror it
844 * so llms.txt lists pages in the same order the sidebar shows them.
845 * Returns `Infinity` when unset, so unordered pages sort after ordered ones.
846 */
847 function parseSidebarOrder(source: string): number {
848 if (!source.startsWith("---")) return Number.POSITIVE_INFINITY;
849 const end = source.indexOf("\n---", 3);
850 if (end === -1) return Number.POSITIVE_INFINITY;
851 const block = source.slice(3, end);
852 const lines = block.split("\n");
853 for (let i = 0; i < lines.length; i++) {
854 if (!/^sidebar:\s*$/.test(lines[i])) continue;
855 for (let j = i + 1; j < lines.length; j++) {
856 if (/^\S/.test(lines[j])) break; // dedented out of the sidebar block
857 const m = lines[j].match(/^\s+order:\s*(-?[\d.]+)\s*$/);
858 if (m) return Number.parseFloat(m[1]);
859 }
860 break;
861 }
862 return Number.POSITIVE_INFINITY;
863 }
864
865 async function loadPage(slug: string): Promise<Page> {
866 const candidates = [`${slug}.mdx`, `${slug}.md`];
867 for (const rel of candidates) {
868 const full = path.join(docsDir, rel);
869 try {
870 // Dev-generated reference pages carry copy-editor markers.
871 const source = (await readFile(full, "utf8")).replace(
872 /<!--copy:[^>]*?-->|^<div data-copy=[^\n]*>\n|^<\/div><!--\/copy-->\n/gm,
873 "",
874 );
875 const fm = parseFrontmatter(source);
876 const title = fm.title;
877 const description = fm.description ?? fm.excerpt ?? "";
878 if (!title) {
879 throw new Error(`Missing title in frontmatter: ${rel}`);
880 }
881 return {
882 // `foo/index.mdx` is served at `/foo`.
883 href: `/${slug}`.replace(/\/index$/, "") || "/",
884 slug,
885 title,
886 description,
887 draft: fm.draft === "true" || (fm.draft as unknown as boolean) === true,
888 order: parseSidebarOrder(source),
889 };
890 } catch (err: any) {
891 if (err?.code !== "ENOENT") throw err;
892 }
893 }
894 throw new Error(`Page not found: ${slug} (looked for .mdx and .md)`);
895 }
896
897 async function listSlugs(directory: string, exclude: string[] = []): Promise<string[]> {
898 const dir = path.join(docsDir, directory);
899 const entries = await readdir(dir, { withFileTypes: true });
900 const slugs: string[] = [];
901 for (const entry of entries) {
902 const rel = `${directory}/${entry.name}`;
903 if (entry.isDirectory()) {
904 slugs.push(...(await listSlugs(rel, exclude)));
905 continue;
906 }
907 if (!entry.isFile()) continue;
908 const ext = path.extname(entry.name);
909 if (ext !== ".md" && ext !== ".mdx") continue;
910 const slug = `${directory}/${entry.name.slice(0, -ext.length)}`;
911 if (exclude.includes(slug)) continue;
912 slugs.push(slug);
913 }
914 slugs.sort();
915 return slugs;
916 }
917
918 function byOrderThenTitle(a: Page, b: Page): number {
919 if (a.order !== b.order) return a.order - b.order;
920 return a.title.localeCompare(b.title);
921 }
922
923 function renderPage(page: Page): string {
924 const url = `${siteUrl}${page.href}`;
925 const desc = page.description ? ` — ${page.description}` : "";
926 return `- [${page.title}](${url})${desc}`;
927 }
928
929 /**
930 * Fails when a published page is missing from SECTIONS or listed twice, so
931 * a new docs page can never silently drop out of llms.txt. The generated
932 * API reference (`providers/`) and the blog are indexed separately.
933 */
934 async function assertCoverage(listed: string[]) {
935 const counts = new Map<string, number>();
936 for (const slug of listed) counts.set(slug, (counts.get(slug) ?? 0) + 1);
937 const duplicates = [...counts].filter(([, n]) => n > 1).map(([slug]) => slug);
938
939 const entries = await readdir(docsDir, { withFileTypes: true });
940 const published: string[] = [];
941 for (const entry of entries) {
942 if (entry.name === "providers" || entry.name === "blog") continue;
943 const slugs = entry.isDirectory()
944 ? await listSlugs(entry.name)
945 : [".md", ".mdx"].includes(path.extname(entry.name))
946 ? [entry.name.slice(0, -path.extname(entry.name).length)]
947 : [];
948 for (const page of await Promise.all(slugs.map(loadPage))) {
949 if (!page.draft) published.push(page.slug);
950 }
951 }
952 const missing = published.filter((slug) => !counts.has(slug));
953
954 const problems = [
955 ...missing.map((slug) => `not listed in any SECTIONS entry: ${slug}`),
956 ...duplicates.map((slug) => `listed in more than one SECTIONS entry: ${slug}`),
957 ];
958 if (problems.length > 0) {
959 throw new Error(
960 `llms.txt does not match the docs:\n ${problems.join("\n ")}\n` +
961 `Add each page to a section in scripts/generate-llms-txt.ts.`,
962 );
963 }
964 }
965
966 async function main() {
967 const sections: string[] = [];
968 const listed: string[] = [];
969
970 for (const section of SECTIONS) {
971 const isDirectory = !("slugs" in section.pages);
972 const slugs =
973 "slugs" in section.pages
974 ? section.pages.slugs
975 : await listSlugs(section.pages.directory, section.pages.exclude);
976 listed.push(...slugs);
977 const pages = (await Promise.all(slugs.map(loadPage))).filter((p) => !p.draft);
978 // Directory sections mirror the sidebar's `sidebar.order` ordering; slug
979 // sections keep the curated order they were declared in.
980 if (isDirectory) pages.sort(byOrderThenTitle);
981
982 sections.push(`## ${section.heading}`);
983 if (section.intro) sections.push(section.intro);
984 sections.push(pages.map(renderPage).join("\n"));
985 }
986
987 await assertCoverage(listed);
988
989 const fullBody = [FULL_HEADER, ...sections, await renderProvidersSection()].join("\n\n") + "\n";
990 await writeFile(outFullFile, fullBody, "utf8");
991 console.log(`Wrote ${outFullFile}`);
992
993 const fullSizeKb = Math.round(Buffer.byteLength(fullBody, "utf8") / 1024);
994 const referenceSection = [
995 `## API reference`,
996 `${PROVIDERS_INTRO_BASE}\n\nThe service-level pages are indexed in [llms-full.txt](${siteUrl}/llms-full.txt), which repeats this entire file plus one link per service. Warning: it is large (~${fullSizeKb} KB) — only fetch it when you need to locate a specific resource's reference page.`,
997 ];
998
999 const body = [HEADER, ...sections, ...referenceSection].join("\n\n") + "\n";
1000 await writeFile(outFile, body, "utf8");
1001 console.log(`Wrote ${outFile}`);
1002 }
1003
1004 main().catch((err) => {
1005 console.error(err);
1006 process.exit(1);
1007 });