saasaloy 0.5.2 → 0.6.0

package/templates/base/apps/web/src/env.ts

@@ -0,0 +1,41 @@
+import { createEnv } from "@repo/env";
+import { z } from "@repo/env/zod";
+
+// This app's typed environment. Every value the browser bundle carries passes through
+// here, and nothing else does.
+//
+// Two rules make the file worth reading before you edit it.
+//
+// `runtimeEnvStrict` is hand-written, one literal `import.meta.env.PUBLIC_X` per key.
+// Vite inlines a literal member expression and nothing else, so a derived or generated
+// form — a spread, a loop, a computed key — compiles to `undefined` in the built bundle
+// and fails only in production. A module that ships a page into this app patches one line
+// into that map.
+//
+// `isServer: false` is what arms the Proxy. A server key that somehow reaches this bundle
+// throws when something reads it, rather than shipping the value to a browser.
+
+export const webEnv = createEnv({
+  /**
+   * Keep this an array literal. `saasaloy add` appends a capability's preset here with a
+   * `plugin-array` patch, and it fails silently otherwise.
+   */
+  extends: [],
+  client: {
+    PUBLIC_SITE_URL: z
+      .url()
+      .describe(
+        "The public origin this site is served from, e.g. https://example.com. Used for canonical URLs."
+      ),
+    PUBLIC_API_URL: z
+      .url()
+      .describe(
+        "Origin this site calls for api and auth requests, e.g. https://api.x.com. http://localhost:4000 in dev. Seeded here so a module shipping a form into this app has a typed key to read."
+      ),
+  },
+  runtimeEnvStrict: {
+    PUBLIC_SITE_URL: import.meta.env.PUBLIC_SITE_URL,
+    PUBLIC_API_URL: import.meta.env.PUBLIC_API_URL,
+  },
+  isServer: false,
+});

package/templates/base/apps/web/src/layouts/Layout.astro

@@ -1,9 +1,13 @@
 ---
 // The one document shell for every page. It owns <html>/<head>/<body> and the single
-// import of the shared theme, so a page is only ever its own content — no page may
-// duplicate the shell or import globals.css again.
-import "@repo/ui/globals.css";
+// import of the web theme, so a page is only ever its own content — no page may
+// duplicate the shell or import a stylesheet again. web.css imports the shared
+// globals.css itself.
+import "@repo/ui/styles/web.css";
+import { siteName } from "@repo/ui";
+import { ui } from "@repo/ui/content/landing";
 import { THEME_INIT_SCRIPT } from "@repo/ui/lib/theme";
+import { webEnv } from "@web/env";
 
 interface Props {
   title: string;
@@ -11,6 +15,11 @@ interface Props {
 }
 
 const { title, description } = Astro.props;
+
+// The one place this app reads an environment value. `webEnv()` validates on its first
+// call and throws naming every key that is unset, so a build with a missing key fails
+// here rather than shipping a page with a broken canonical URL.
+const canonical = new URL(Astro.url.pathname, webEnv().PUBLIC_SITE_URL).href;
 ---
 
 <!doctype html>
@@ -19,19 +28,28 @@ const { title, description } = Astro.props;
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>{title}</title>
-    {
-      /*
+    {/*
       Explicit icon link, not the implicit /favicon.ico lookup. Without a link the
       browser guesses /favicon.ico, and Chrome tags that guess `Sec-Fetch-Site:
       cross-site`, which the Astro dev server blocks with a `[router]` warning
       (astro/dist/vite-plugin-astro-server/sec-fetch.js). A declared same-origin
       link never gets that treatment. Replace public/favicon.svg with the project mark.
-    */
-    }
+    */}
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <link rel="canonical" href={canonical} />
     {description && <meta name="description" content={description} />}
-    {
-      /*
+    {/*
+      The link preview. Every page gets the title, the URL and the card type; a page that
+      passes a description gets it here too. To add a preview image, put a 1200×630 file
+      in public/ and add `og:image` and `twitter:image` tags beside these.
+    */}
+    <meta property="og:type" content="website" />
+    <meta property="og:site_name" content={siteName} />
+    <meta property="og:title" content={title} />
+    {description && <meta property="og:description" content={description} />}
+    <meta property="og:url" content={canonical} />
+    <meta name="twitter:card" content="summary" />
+    {/*
       Pre-paint theme resolution. This runs synchronously in <head>, BEFORE the browser
       paints, so a dark-mode visitor never sees a white flash. `is:inline` keeps Astro
       from bundling it into a deferred module, which would defeat the whole point —
@@ -42,11 +60,21 @@ const { title, description } = Astro.props;
       `[data-theme-toggle]` on the page through one delegated listener. That is why
       @repo/ui/blocks/theme-toggle needs no client directive. Do not inline a second
       resolver here, and do not turn this into an import.
-    */
-    }
+    */}
     <script is:inline set:html={THEME_INIT_SCRIPT} />
   </head>
   <body class="bg-background text-foreground min-h-dvh font-sans antialiased">
+    {/*
+      The first Tab stop on every page. It stays off screen until focused, then jumps past
+      the navbar to the page's <main>. Every page and the error block give their <main>
+      `id="main"` and `tabindex="-1"`, so focus lands there too.
+    */}
+    <a
+      href="#main"
+      class="bg-background focus-visible:ring-ring/50 sr-only z-100 rounded-lg border px-4 py-2 text-sm font-medium focus:not-sr-only focus:fixed focus:top-4 focus:left-4 focus-visible:ring-3"
+    >
+      {ui.layout.skipToContent}
+    </a>
     <slot />
   </body>
 </html>

package/templates/base/apps/web/src/pages/index.astro

@@ -1,13 +1,18 @@
 ---
 import { siteName } from "@repo/ui";
+import { Audience } from "@repo/ui/blocks/audience";
 import { Cta } from "@repo/ui/blocks/cta";
 import { Faq } from "@repo/ui/blocks/faq";
 import { FeatureGrid } from "@repo/ui/blocks/feature-grid";
 import { Footer } from "@repo/ui/blocks/footer";
 import { Hero } from "@repo/ui/blocks/hero";
+import { HowItWorks } from "@repo/ui/blocks/how-it-works";
+import { LogoCloud } from "@repo/ui/blocks/logo-cloud";
 import { Navbar } from "@repo/ui/blocks/navbar";
+import { PainPoints } from "@repo/ui/blocks/pain-points";
 import { PricingTable } from "@repo/ui/blocks/pricing-table";
-import { ThemeToggle } from "@repo/ui/blocks/theme-toggle";
+import { Showcase } from "@repo/ui/blocks/showcase";
+import { Testimonials } from "@repo/ui/blocks/testimonials";
 import { landing } from "@repo/ui/content/landing";
 import { interpolate } from "@repo/ui/lib/interpolate";
 import Layout from "../layouts/Layout.astro";
@@ -23,38 +28,42 @@ import Layout from "../layouts/Layout.astro";
 // suggests the component goes, then decide the position yourself.
 ---
 
-{
-  /*
+{/*
+  THE SECTION RECIPE. Each section is one import above and one line below.
+    - Remove a section: delete its line here, its import above, and its file in
+      packages/ui/src/blocks/. Blank its navbar and footer labels in landing.ts so no link
+      points at a section that is gone.
+    - Reorder: move the lines. The blocks share one spacing rhythm, so any order works.
+    - Add one back: copy the block file in, then add the import and the line.
+
   The page is composed from @repo/ui/blocks/*, each reached by its own subpath export.
-  Blocks render to static HTML by default; only the three that need browser state carry
-  a client directive, and each one is deliberate:
-    - Navbar       client:idle    — mobile menu toggle, above the fold, so hydrate when
-                                    the browser goes idle rather than waiting for scroll.
+  Blocks render to static HTML by default; only the two that need browser state carry a
+  client directive, and each one is deliberate:
+    - Navbar       client:idle    — mobile menu, above the fold, so hydrate when the
+                                    browser goes idle rather than waiting for scroll.
     - PricingTable client:visible — monthly/annual toggle, below the fold.
-    - Faq          client:visible — accordion, below the fold.
-  Hero, FeatureGrid, Cta and Footer take no directive and ship no JavaScript at all.
-  ThemeToggle is the interesting case: it is interactive yet takes no directive either,
-  because its behaviour comes from the pre-paint inline script Layout.astro emits, not
-  from React. Giving it a `client:*` would ship a hydration runtime for a button that
-  has no onClick. It sits here rather than inside Navbar so that navbar.tsx stays the
-  landing blocks' file alone, and it carries its own positioning: fixed to the corner,
-  clear of the sticky header's own controls at every width.
+  Every other block ships no JavaScript at all. The FAQ and the pain points open and close
+  with native <details>, and all motion is CSS. The footer adds one inline script that
+  writes the current year. The theme toggle sits inside the navbar and needs no island of
+  its own: the pre-paint script Layout.astro emits drives it.
   Never reach for a blanket `client:load` here — it would hydrate the whole page.
-*/
-}
+*/}
 <Layout
   title={interpolate(landing.meta.title, { siteName })}
   description={interpolate(landing.meta.description, { siteName })}
 >
   <Navbar client:idle siteName={siteName} />
-  <ThemeToggle
-    className="border-border/60 bg-background/80 fixed right-4 bottom-4 z-50 shadow-sm backdrop-blur"
-  />
-  <main>
+  <main id="main" tabindex="-1">
     <Hero siteName={siteName} />
-    <FeatureGrid />
-    <PricingTable client:visible />
-    <Faq client:visible />
+    <LogoCloud />
+    <PainPoints siteName={siteName} />
+    <HowItWorks siteName={siteName} />
+    <FeatureGrid siteName={siteName} />
+    <Showcase siteName={siteName} />
+    <Audience siteName={siteName} />
+    <Testimonials siteName={siteName} />
+    <PricingTable client:visible siteName={siteName} />
+    <Faq siteName={siteName} />
     <Cta siteName={siteName} />
   </main>
   <Footer siteName={siteName} />

package/templates/base/apps/web/src/pages/privacy.astro

@@ -4,12 +4,20 @@ import Layout from "../layouts/Layout.astro";
 ---
 
 <Layout title={`Privacy Policy — ${siteName}`}>
-  <main class="mx-auto my-16 max-w-2xl px-6 leading-[1.6]">
+  <main
+    id="main"
+    tabindex="-1"
+    class="mx-auto my-16 max-w-2xl px-6 leading-[1.6]"
+  >
     <h1 class="mb-6 text-3xl font-bold tracking-tight">Privacy Policy</h1>
     <p class="mb-4">
       Placeholder privacy policy for {siteName}. Replace with your own before
       launch.
     </p>
-    <p><a href="/" class="hover:underline">← Home</a></p>
+    <p>
+      <a href="/" class="hover:underline">
+        ← Home
+      </a>
+    </p>
   </main>
 </Layout>

package/templates/base/apps/web/src/pages/terms.astro

@@ -4,11 +4,19 @@ import Layout from "../layouts/Layout.astro";
 ---
 
 <Layout title={`Terms of Service — ${siteName}`}>
-  <main class="mx-auto my-16 max-w-2xl px-6 leading-[1.6]">
+  <main
+    id="main"
+    tabindex="-1"
+    class="mx-auto my-16 max-w-2xl px-6 leading-[1.6]"
+  >
     <h1 class="mb-6 text-3xl font-bold tracking-tight">Terms of Service</h1>
     <p class="mb-4">
       Placeholder terms for {siteName}. Replace with your own before launch.
     </p>
-    <p><a href="/" class="hover:underline">← Home</a></p>
+    <p>
+      <a href="/" class="hover:underline">
+        ← Home
+      </a>
+    </p>
   </main>
 </Layout>

package/templates/base/oxlint.config.mjs

@@ -2,6 +2,7 @@ import { defineConfig } from "oxlint";
 import astro from "ultracite/oxlint/astro";
 import core from "ultracite/oxlint/core";
 import react from "ultracite/oxlint/react";
+import vitest from "ultracite/oxlint/vitest";
 
 // Run it as `oxlint -c oxlint.config.mjs` — the flag is not optional. oxlint only
 // auto-discovers `.oxlintrc.json`, and a JSON config cannot `extends` Ultracite's
@@ -9,8 +10,8 @@ import react from "ultracite/oxlint/react";
 // modules. The JS config format is experimental and needs Node.js, which this
 // project already requires (>= 24).
 //
-// Add `ultracite/oxlint/tanstack` when an admin SPA lands, and
-// `ultracite/oxlint/vitest` when the first test file does. The full preset list is
+// Add `ultracite/oxlint/tanstack` when an admin SPA lands. `vitest` is on because the
+// root `vitest.config.ts` runs every workspace's tests. The full preset list is
 // angular, astro, core, jest, js-plugins, nestjs, next, qwik, react, remix, solid,
 // svelte, tanstack, vitest, vue.
 
@@ -39,7 +40,7 @@ function mergePresets(...presets) {
   return merged;
 }
 
-const ultracite = mergePresets(core, astro, react);
+const ultracite = mergePresets(core, astro, react, vitest);
 
 // Rules turned off for the whole project, each with its reason. Ultracite enables
 // ~470, including whole families oxlint itself files under `style`, `pedantic` and
@@ -69,7 +70,14 @@ const suppressed = {
   // Sequential awaits are deliberate where ordering matters, and `async` is kept on
   // some functions (e.g. an email provider's `send`) to satisfy an interface even
   // when that implementation has nothing to await.
+  //
+  // The two `prefer-await-to-*` rules fire on APIs that are callbacks by contract:
+  // Hono's `.onError((err, c) => …)` in `apps/api`, and the `.catch()` that
+  // `database-postgres`'s `withDb` hangs on a promise it hands to `waitUntil` rather
+  // than awaiting. Neither has an `await` form.
   "no-await-in-loop": "off",
+  "promise/prefer-await-to-callbacks": "off",
+  "promise/prefer-await-to-then": "off",
   "require-await": "off",
 
   // --- Regular expressions -------------------------------------------------
@@ -82,10 +90,25 @@ const suppressed = {
   // --- Key ordering and small style ----------------------------------------
   // Props and config objects are grouped by meaning (`id`, then `title`, then the
   // data). Alphabetising them loses that ordering for no benefit. `no-plusplus` and
-  // `method-signature-style` are pure preference.
+  // `method-signature-style` are pure preference. `unicorn/import-style` wants a
+  // default import for `node:path` and friends, against the named imports
+  // (`import { resolve } from "node:path"`) every module file uses.
   "no-plusplus": "off",
   "sort-keys": "off",
   "typescript/method-signature-style": "off",
+  "unicorn/import-style": "off",
+
+  // --- Thresholds and placement --------------------------------------------
+  // Numeric limits and shape preferences with no defect behind them. `complexity`
+  // fires on a provider's error mapper, which is one flat branch per vendor code.
+  // `no-nested-ternary` fires on a three-way sort icon in JSX. `no-dynamic-delete`
+  // fires on dropping one key from a record keyed by a runtime id, which is what a
+  // permission draft is. `consistent-function-scoping` wants a helper hoisted out of
+  // the factory it serves, away from the one caller that reads it.
+  complexity: "off",
+  "no-nested-ternary": "off",
+  "typescript/no-dynamic-delete": "off",
+  "unicorn/consistent-function-scoping": "off",
 
   // --- Accessibility shape, not accessibility ------------------------------
   // Fires on `<div role="group">` and friends: the roles are correct, and swapping
@@ -104,6 +127,9 @@ export default defineConfig({
     // deployed Worker or a client bundle is a leak, not a log line. Add an override
     // below for any file where console output is genuinely the feature.
     "no-console": "error",
+    // A type-only import is erased before the code runs, so a cycle that closes only
+    // through one cannot leave a module half-initialised. The runtime cycles stay errors.
+    "import/no-cycle": ["error", { ignoreTypes: true }],
   },
 
   overrides: [
@@ -151,5 +177,66 @@ export default defineConfig({
       files: ["packages/*/src/providers/console.ts", "packages/logger*/**"],
       rules: { "no-console": "off" },
     },
+
+    // Two more places where `console` is the right call, both from the queue module.
+    // A queue provider's batch consumer and cron tick run outside a request, so there is
+    // no `c.get("log")` to reach for, and `@repo/queue` has no runtime dependencies to
+    // import `@repo/logger` with. Workers Logs indexes `console` directly. The example
+    // job's whole body is one log line, which is what makes it a readable example.
+    {
+      files: [
+        "packages/queue/src/providers/**",
+        "packages/queue/src/jobs/example.ts",
+      ],
+      rules: { "no-console": "off" },
+    },
+
+    // The queue barrel registers its providers, and each provider calls back into the
+    // barrel for `createQueue`, `dispatch` and `dueSchedules`. The cycle is deliberate:
+    // a provider reads those hoisted functions inside a function body, never while the
+    // module loads. `packages/queue/src/providers/memory.ts` explains it in full.
+    {
+      files: ["packages/queue/src/index.ts", "packages/queue/src/providers/**"],
+      rules: { "import/no-cycle": "off" },
+    },
+
+    // `packages/env` runs on `node:test`, not vitest. Its tests predate the base's Vitest
+    // setup, and the root `vitest.config.ts` leaves the package out. Three
+    // vitest rules point these files at a runner they cannot use, and
+    // `no-floating-promises` fires on every `describe`, whose promise the runner itself
+    // awaits. Prefixing twenty call sites with `void` would say nothing the runner does
+    // not already guarantee.
+    //
+    // `env:setup` and `env-deploy` are node scripts, so `process` and `console` are theirs
+    // to use. Nothing a Worker imports reaches them (ADR 0041).
+    {
+      files: ["packages/env/**/*.test.ts"],
+      plugins: ["vitest"],
+      rules: {
+        "typescript/no-floating-promises": "off",
+        "vitest/no-import-node-test": "off",
+        "vitest/prefer-importing-vitest-globals": "off",
+        "vitest/prefer-each": "off",
+      },
+    },
+    // `createEnv` is a generic mapped-type API: it takes `server`, `client` and `shared`
+    // as distinct type parameters, erases them to one `SchemaRecord` to iterate the keys,
+    // and puts the specific type back on the way out. Every assertion this file makes is
+    // that erase-and-restore, which the type system cannot express and the rules below
+    // cannot see through. The Proxy adds two more — `Reflect.get` on a mapped type is
+    // `any` by definition. Scoped to this one file; every rule stays on everywhere else.
+    {
+      files: ["packages/env/src/define.ts", "packages/env/src/define.test.ts"],
+      rules: {
+        "typescript/no-unsafe-type-assertion": "off",
+        "typescript/no-unnecessary-type-assertion": "off",
+        "typescript/no-unsafe-assignment": "off",
+        "typescript/no-unsafe-return": "off",
+      },
+    },
+    {
+      files: ["packages/env/scripts/**", "packages/env/src/deploy.ts"],
+      rules: { "no-console": "off", "unicorn/no-process-exit": "off" },
+    },
   ],
 });

package/templates/base/package.json

@@ -12,12 +12,15 @@
     "prepare": "husky",
     "build": "turbo run build",
     "clean": "turbo run clean && rimraf -g node_modules .turbo \"{apps,packages}/*/node_modules\" \"{apps,packages}/*/.turbo\"",
+    "deploy:production": "node packages/env/src/deploy.ts --check && turbo run deploy",
     "dev": "turbo run dev",
+    "env:setup": "node packages/env/scripts/env-setup.ts",
+    "test": "turbo run test && vitest run",
     "lint": "pnpm run lint:types && pnpm run lint:code && pnpm run lint:css && pnpm run format:check",
-    "lint:types": "oxlint -c oxlint.config.mjs --type-aware --deny-warnings packages/ui/src",
+    "lint:types": "oxlint -c oxlint.config.mjs --type-aware --deny-warnings packages/env/src packages/ui/src",
     "lint:code": "oxlint -c oxlint.config.mjs --deny-warnings .",
     "lint:css": "stylelint \"**/*.css\" --max-warnings 0",
-    "lint:fix": "oxlint -c oxlint.config.mjs --type-aware --fix packages/ui/src && oxlint -c oxlint.config.mjs --fix . && stylelint \"**/*.css\" --fix",
+    "lint:fix": "oxlint -c oxlint.config.mjs --type-aware --fix packages/env/src packages/ui/src && oxlint -c oxlint.config.mjs --fix . && stylelint \"**/*.css\" --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "typecheck": "turbo run typecheck"
@@ -39,6 +42,7 @@
     "stylelint-prettier": "5.0.3",
     "turbo": "2.11.6",
     "typescript": "7.0.2",
-    "ultracite": "7.12.2"
+    "ultracite": "7.12.2",
+    "vitest": "5.0.5"
   }
 }

package/templates/base/packages/env/_env.example

@@ -0,0 +1,54 @@
+# The one key list for this repository. Every `.env` that `pnpm env:setup` writes is
+# written from this file. There is no second example file, and no `.dev.vars.example`.
+#
+# `.env` is gitignored; this file is tracked. Keep real secrets out of it. Every value
+# below is the local development default.
+#
+# ADDING A KEY
+#
+# 1. Add its line here, under the `# @services` section that names the services that read
+#    it, with a comment saying where the value comes from and what unset looks like. Add a
+#    `# Blank on purpose` line when the key is meant to stay empty.
+# 2. Declare it in the capability package's `src/env.ts` preset, so `createEnv` validates
+#    it and the type reaches the code that reads it.
+#
+# `saasaloy add` regenerates the key blocks below from the installed modules' `envVars`.
+# A value you type here survives that, and nothing is ever removed.
+#
+# SECTIONS
+#
+# A `# @services <names>` line sets which services take every key below it, until the next
+# such line. The names are the `name` fields of `SERVICES` in
+# `packages/env/src/services.ts`. A key with no section above it fails the run.
+
+# =============================================================================
+# The web app
+# =============================================================================
+# @services web
+
+# The public origin this site is served from (e.g. https://example.com). Astro reads it
+# at build time for canonical URLs and the sitemap. Unset, the build fails rather than
+# writing localhost links into a production bundle.
+PUBLIC_SITE_URL=http://localhost:3000
+
+# Origin this site calls for api and auth requests (e.g. https://api.x.com). The api
+# Worker's pinned dev port is 4000. Unset, the build fails naming this key.
+PUBLIC_API_URL=http://localhost:4000
+
+# =============================================================================
+# Deploy credentials
+# =============================================================================
+# @services deploy
+
+# Cloudflare API token wrangler deploys with, from https://dash.cloudflare.com/profile/api-tokens.
+# The "Edit Cloudflare Workers" template covers Workers; add "D1: Edit" with a database,
+# and "Workers KV Storage: Edit", "Workers R2 Storage: Edit" and "Queues: Edit" for those.
+# pnpm deploy:production never puts it in a Worker's secrets.
+# Blank on purpose: unset, wrangler uses your `wrangler login` session, and the deploy
+# stops before any build when there is none.
+CLOUDFLARE_API_TOKEN=
+
+# The Cloudflare account id the Workers and their resources deploy into.
+# Blank on purpose: unset, wrangler uses the one account the token or login can reach,
+# and asks or fails when there are several.
+CLOUDFLARE_ACCOUNT_ID=

package/templates/base/packages/env/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@repo/env",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "env-deploy": "./src/deploy.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./error": "./src/error.ts",
+    "./check": "./src/check.ts",
+    "./dotenv": "./src/dotenv.ts",
+    "./env-file": "./src/env-file.ts",
+    "./example": "./src/example.ts",
+    "./services": "./src/services.ts",
+    "./zod": "./src/zod.ts",
+    "./sources": "./src/sources.ts",
+    "./setup": "./src/setup.ts"
+  },
+  "scripts": {
+    "clean": "rimraf -g dist \"*.tsbuildinfo\"",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"src/**/*.test.ts\""
+  },
+  "dependencies": {
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@repo/tsconfig": "workspace:*",
+    "@types/node": "26.4.1",
+    "rimraf": "6.1.3",
+    "typescript": "7.0.2"
+  }
+}

package/templates/base/packages/env/scripts/env-setup.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { selectServices } from "../src/services.ts";
+import type { Environment } from "../src/services.ts";
+import { setupServices } from "../src/setup.ts";
+import { sources } from "../src/sources.ts";
+
+// `pnpm env:setup [--env dev|prod] [--only <service>]`: write each service's `.env` from
+// the selected value source. `dev` writes every dev service; `--env prod --only <service>`
+// writes one production file and nothing under `apps/`. A deploy writes no file at all:
+// `pnpm deploy:production` loads the production values in memory.
+
+function readOptions(args: string[]): {
+  environment: Environment;
+  only?: string;
+} {
+  let environment: Environment = "dev";
+  let only: string | undefined;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--env") {
+      const value = args[index + 1];
+      if (value !== "dev" && value !== "prod") {
+        throw new Error("--env takes dev or prod.");
+      }
+      environment = value;
+      index += 1;
+    } else if (arg === "--only") {
+      only = args[index + 1];
+      if (!only) {
+        throw new Error("--only takes a service name.");
+      }
+      index += 1;
+    } else {
+      throw new Error(
+        `Unknown option ${arg}. This command takes --env and --only.`
+      );
+    }
+  }
+  return { environment, only };
+}
+
+function say(message: string): void {
+  process.stdout.write(`${message}\n`);
+}
+
+try {
+  const options = readOptions(process.argv.slice(2));
+  const services = selectServices(options.environment, options.only);
+  const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+    encoding: "utf-8",
+  }).trim();
+
+  const report = await setupServices({
+    root,
+    environment: options.environment,
+    services,
+    source: sources.select(process.env.ENV_SOURCE),
+    processEnv: process.env,
+  });
+
+  if (report.kind === "kept") {
+    say(`Warning: ${report.reason}`);
+    say(
+      `Kept ${report.files.join(", ")}: every listed key already has a value.`
+    );
+  } else {
+    for (const service of report.services) {
+      say(`${service.created ? "Created" : "Updated"} ${service.file}.`);
+      if (service.migrated) {
+        say(
+          `Carried the values of ${service.file.replace(/\.env$/, ".dev.vars")} across and deleted it. Wrangler loads .env only while no .dev.vars exists.`
+        );
+      }
+      if (service.extraKeys.length > 0) {
+        say(
+          `Warning: ${service.extraKeys.join(", ")} came from the value source but packages/env/.env.example does not list them for ${service.service}. Add them there, under a "# @services" section that names ${service.service}.`
+        );
+      }
+    }
+  }
+} catch (error) {
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`
+  );
+  process.exitCode = 1;
+}

package/templates/base/packages/env/src/check.test.ts

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { blankOnPurposeKeys, incompleteKeys } from "./check.ts";
+
+describe("blankOnPurposeKeys", () => {
+  it("marks a key whose comment block carries the line", () => {
+    const keys = blankOnPurposeKeys([
+      "# Blank on purpose: unset means no proxy.",
+      "# A second comment line still belongs to the block.",
+      "A=",
+      "",
+      "B=",
+    ]);
+    assert.deepEqual([...keys], ["A"]);
+  });
+
+  it("ends the block at a blank line", () => {
+    const keys = blankOnPurposeKeys(["# Blank on purpose", "", "A="]);
+    assert.deepEqual([...keys], []);
+  });
+});
+
+describe("incompleteKeys", () => {
+  const example = ["A=", "# Blank on purpose", "B=", "C="];
+
+  it("names every key with no value", () => {
+    assert.deepEqual(incompleteKeys(example, new Map()), ["A", "C"]);
+  });
+
+  it("ignores a key the service omits", () => {
+    assert.deepEqual(incompleteKeys(example, new Map(), ["C"]), ["A"]);
+  });
+
+  it("is empty when every key has a value", () => {
+    const values = new Map([
+      ["A", "1"],
+      ["C", "3"],
+    ]);
+    assert.deepEqual(incompleteKeys(example, values), []);
+  });
+});