saasaloy 0.5.2 → 0.6.1

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: [
@@ -136,6 +162,40 @@ export default defineConfig({
       rules: { "unicorn/filename-case": "off" },
     },
 
+    // The admin app has its own primitive set in packages/ui/src/components/admin/, which
+    // `saasaloy add admin` writes. Its names repeat the base ones (`button`, `card`), so an
+    // editor's autocomplete offers both and the wrong one renders with no error, in the
+    // web app's styling. Inside the admin app and the admin folders of @repo/ui, a base
+    // primitive or a base block with an admin twin is a lint error. A project without the
+    // admin app has no file under these globs, so the rule never fires there.
+    {
+      files: [
+        "apps/admin/**",
+        "packages/ui/src/blocks/admin/**",
+        "packages/ui/src/components/admin/**",
+        "packages/ui/src/containers/admin/**",
+      ],
+      rules: {
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: [
+              {
+                group: [
+                  "@repo/ui/components/*",
+                  "!@repo/ui/components/admin/*",
+                  "@repo/ui/blocks/error-state",
+                  "@repo/ui/blocks/theme-toggle",
+                ],
+                message:
+                  "Admin code uses the admin set: import from @repo/ui/components/admin/* and @repo/ui/blocks/admin/*.",
+              },
+            ],
+          },
+        ],
+      },
+    },
+
     // The design system is vendored from shadcn and re-synced with
     // `pnpm --filter @repo/ui exec shadcn add …`. `Label` is a primitive: the control
     // it labels is supplied by the call site, which this rule cannot see.
@@ -151,5 +211,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), []);
+  });
+});

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

@@ -0,0 +1,50 @@
+import { parseValues } from "./dotenv.ts";
+
+// The checks `env:setup` runs before it writes anything.
+
+/** The comment that says a key is meant to stay empty. */
+const BLANK_ON_PURPOSE = "# blank on purpose";
+
+/**
+ * Every key whose comment block carries a `# Blank on purpose` line above it.
+ *
+ * A comment block is the run of comment lines directly above the key, so the marker may
+ * sit on any of them. A blank line ends the block.
+ */
+export function blankOnPurposeKeys(lines: string[]): Set<string> {
+  const keys = new Set<string>();
+  let marked = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("#")) {
+      marked ||= trimmed.toLowerCase().startsWith(BLANK_ON_PURPOSE);
+      continue;
+    }
+    if (trimmed === "") {
+      marked = false;
+      continue;
+    }
+    const [key] = [...parseValues([line]).keys()];
+    if (key !== undefined && marked) {
+      keys.add(key);
+    }
+    marked = false;
+  }
+  return keys;
+}
+
+/**
+ * Every key the example lists that `values` leaves empty, apart from a blank-on-purpose
+ * key and a key in `omit`. An empty result means the file is complete.
+ */
+export function incompleteKeys(
+  example: string[],
+  values: Map<string, string>,
+  omit: readonly string[] = []
+): string[] {
+  const marked = blankOnPurposeKeys(example);
+  return [...parseValues(example).keys()].filter(
+    (key) =>
+      (values.get(key) ?? "") === "" && !marked.has(key) && !omit.includes(key)
+  );
+}