create-zerotal 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -8,6 +8,60 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.11.0] — 2026-08-31
+
+### Added
+
+- **The React scaffold ships a page-render test.** Every generated page is built once,
+  to prove it can be. The rest of a starter suite asserts values and status codes, and
+  a page can throw on its first paint while all of them pass — which is how a blank
+  page reaches production with a green suite. New projects inherited that gap; now
+  they inherit the check instead. One line per page.
+
+### Fixed
+
+- **`config/session.ts` is scaffolded environment-aware**, so the first production
+  deploy no longer fails. The production config validator refuses to boot without
+  `session.secure`, which is right — but the scaffold shipped `secret`, `cookie` and
+  `lifetime` only, so every app built from it hit that refusal on its first deploy,
+  after uploading, installing and migrating, at the moment it tried to serve. It also
+  cannot simply be `true`: development runs on `http://localhost`, where a secure
+  cookie is never sent, and the symptom there is a login that appears to succeed and
+  bounces back to the sign-in page with nothing in any log. Now
+  `secure: env("APP_ENV", "development") === "production"`, with `httpOnly` and
+  `sameSite: "Lax"` — `Lax` because invitation and password-reset links arrive from a
+  mail client, and `Strict` withholds the cookie on exactly that navigation.
+
+- **`--success` meets WCAG AA.** The light-palette token was `oklch(0.6 0.14 158)`,
+  which measures 3.1:1 as status text against the 10% success tint it is drawn on —
+  under the 4.5:1 AA needs. Measuring it against the surface *under* the tint is what
+  made it look like it passed. Now `oklch(0.504 0.11 158)`.
+
+### Fixed
+
+- **`.env.example` no longer ships the key the project actually runs with.** Both
+  files got the same rendered content, so every scaffolded project committed a live,
+  working `APP_KEY` — `.gitignore` covers `.env` and not `.env.example`. And
+  `cp .env.example .env` is the first line of every deployment guide there is, so the
+  published key went on to sign production sessions. One key across a laptop and a
+  server is one compromise across both, and no strength check can catch it: as a
+  string the value is perfectly strong. The example now carries a placeholder naming
+  `key:generate`; `.env` still gets a fresh key, so a new app boots immediately.
+
+- **`.gitignore` covers the SQLite sidecars.** It had `*.sqlite`, which does not match
+  `db.sqlite-wal` or `db.sqlite-shm`. WAL mode is on by default so both exist in every
+  project, and the write-ahead log holds pages not yet checkpointed into the main
+  file — real rows. An app found both in its first commit on a public host, and was
+  saved only by the WAL happening to be empty at that moment. Now `*.sqlite*`.
+
+### Changed
+
+- **`bun-plugin-tailwind` is pinned, and it and `tailwindcss` moved to
+  `dependencies`.** Pinned because `latest` on a build-critical package whose peer
+  declaration can take down a deploy is a combination worth removing. Moved because a
+  deploy that installs with `--production` and *then* builds on the server has no
+  devDependencies — so no Tailwind, and a page with no CSS.
+
 ## [1.7.2] — 2026-08-18
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zerotal",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Create a new Zerotal application",
   "license": "MIT",
   "maturity": "stable",

package/src/scaffold.ts

@@ -13,7 +13,7 @@ export type Template = 'minimal' | 'api' | 'admin' | 'flow' | 'react' | 'vue';
 // "^1.1.0" found for specifier "zerotal"` — the first thing anyone trying the
 // framework saw. `scaffold.test.ts` now asserts the two agree, so CI fails rather
 // than the user's install.
-export const ZT_VERSION = "^1.10.0";
+export const ZT_VERSION = "^1.11.0";
 
 export interface ScaffoldOptions {
   name:     string;
@@ -28,6 +28,18 @@ function randomBase64(bytes: number): string {
   return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString('base64');
 }
 
+/**
+ * What the secrets read as in the committed `.env.example`.
+ *
+ * A value nobody could mistake for a working key, and one that names the command
+ * that produces a real one. `.env` still gets a freshly generated key, so a new
+ * app boots immediately — the example is the copy that goes to a git host.
+ */
+const PLACEHOLDER_SECRETS: Record<string, string> = {
+  '{{app_key}}':        'run-`bun zt.ts key:generate`-to-fill-this',
+  '{{session_secret}}': 'run-`bun zt.ts key:generate`-to-fill-this',
+};
+
 function tokens(opts: ScaffoldOptions): Record<string, string> {
   const dbUrl: Record<Database, string> = {
     sqlite:   './database/db.sqlite',
@@ -93,12 +105,19 @@ export async function scaffold(opts: ScaffoldOptions): Promise<void> {
     const content = applyTokens(raw, map);
     await Bun.write(dest, content);
 
-    // Also write a ready-to-run `.env` next to `.env.example`. The example
-    // already carries a freshly-generated APP_KEY/SESSION_SECRET, so a fresh
-    // app boots immediately without a manual `cp .env.example .env` +
-    // `key:generate` step (the old flow left APP_KEY empty on first boot).
+    // `.env` gets the real secrets; `.env.example` gets placeholders.
+    //
+    // Both used to get the same rendered content, which put a live, working
+    // APP_KEY into the one file of the pair that `.gitignore` does *not* cover.
+    // Every scaffolded project therefore committed its own session-signing key,
+    // and `cp .env.example .env` — the first line of every deployment guide there
+    // is — carried that published key into production. One key across a laptop
+    // and a server is one compromise across both, and a strength check cannot
+    // catch it: as a string the value is perfectly strong. The problem is that
+    // this particular value was distributed.
     if (dest.endsWith('.env.example')) {
       await Bun.write(dest.replace(/\.env\.example$/, '.env'), content);
+      await Bun.write(dest, applyTokens(raw, { ...map, ...PLACEHOLDER_SECRETS }));
     }
   }
 }

package/templates/admin/_gitignore

@@ -1,4 +1,7 @@
 node_modules/
 .zerotal/
-*.sqlite
+# `*.sqlite` alone misses `db.sqlite-wal` and `db.sqlite-shm`. WAL mode is on by
+# default, so both exist in every project, and the write-ahead log holds rows that
+# have not been checkpointed into the main file yet — real ones.
+*.sqlite*
 .env

package/templates/admin/config/session.ts

@@ -7,4 +7,20 @@ export default SessionConfig({
   secret: env("APP_KEY", ""),
   cookie: env("SESSION_COOKIE", "zerotal_session"),
   lifetime: 60 * 24 * 7,
+  // `secure` gates the cookie on HTTPS, and the two environments need opposite
+  // answers. Production refuses to boot without it — the config validator is right
+  // to — but development runs on http://localhost, where a secure cookie is never
+  // sent at all, and the symptom there is a login that appears to succeed and then
+  // bounces back to the sign-in page with nothing in any log.
+  //
+  // Scaffolded environment-aware because every app ends up writing this line, and
+  // the ones that write it after their first failed production deploy write it at
+  // the worst possible moment.
+  secure: env("APP_ENV", "development") === "production",
+  httpOnly: true,
+
+  // `Lax`, not `Strict`. Invitation and password-reset links arrive from a mail
+  // client, and `Strict` withholds the cookie on exactly that first cross-site
+  // navigation — so the link lands the user on a sign-in page instead.
+  sameSite: "Lax",
 });

package/templates/api/_gitignore

@@ -1,5 +1,8 @@
 node_modules/
 .zerotal/
-*.sqlite
+# `*.sqlite` alone misses `db.sqlite-wal` and `db.sqlite-shm`. WAL mode is on by
+# default, so both exist in every project, and the write-ahead log holds rows that
+# have not been checkpointed into the main file yet — real ones.
+*.sqlite*
 .env
 public/assets/

package/templates/flow/_gitignore

@@ -1,6 +1,9 @@
 node_modules/
 .zerotal/
-*.sqlite
+# `*.sqlite` alone misses `db.sqlite-wal` and `db.sqlite-shm`. WAL mode is on by
+# default, so both exist in every project, and the write-ahead log holds rows that
+# have not been checkpointed into the main file yet — real ones.
+*.sqlite*
 .env
 public/app.js
 public/app.css

package/templates/flow/config/session.ts

@@ -6,6 +6,8 @@ export default SessionConfig({
   // Cookie sessions are signed, so the driver needs the app key.
   secret: env("APP_KEY", ""),
   cookie: "{{name}}_session",
+  // Seven days suits a demo. Anything holding a credential wants less — an app
+  // whose session carries a live mailbox password runs ten hours.
   lifetime: 60 * 60 * 24 * 7, // 7 days
   // Tied to the scheme rather than hardcoded: a `secure` cookie is never sent
   // over plain HTTP, so setting it unconditionally would drop the session in

package/templates/flow/package.json

@@ -15,7 +15,7 @@
     "@zerotal/flow": "{{zerotal_version}}",
     "zerotal": "{{zerotal_version}}",
     "tailwindcss": "^4.0.0",
-    "bun-plugin-tailwind": "latest"
+    "bun-plugin-tailwind": "0.1.2"
   },
   "engines": {
     "bun": ">=1.3.14"

package/templates/minimal/_gitignore

@@ -1,6 +1,9 @@
 node_modules/
 .zerotal/
-*.sqlite
+# `*.sqlite` alone misses `db.sqlite-wal` and `db.sqlite-shm`. WAL mode is on by
+# default, so both exist in every project, and the write-ahead log holds rows that
+# have not been checkpointed into the main file yet — real ones.
+*.sqlite*
 .env
 public/app.js
 public/app.css

package/templates/minimal/package.json

@@ -14,7 +14,7 @@
     "@zerotal/devtools": "{{zerotal_version}}",
     "zerotal": "{{zerotal_version}}",
     "tailwindcss": "^4.0.0",
-    "bun-plugin-tailwind": "latest"
+    "bun-plugin-tailwind": "0.1.2"
   },
   "engines": {
     "bun": ">=1.3.14"

package/templates/react/_gitignore

@@ -1,5 +1,8 @@
 node_modules/
 .zerotal/
-*.sqlite
+# `*.sqlite` alone misses `db.sqlite-wal` and `db.sqlite-shm`. WAL mode is on by
+# default, so both exist in every project, and the write-ahead log holds rows that
+# have not been checkpointed into the main file yet — real ones.
+*.sqlite*
 .env
 public/assets/

package/templates/react/config/session.ts

@@ -7,5 +7,23 @@ import { SessionConfig } from "zerotal/session";
 export default SessionConfig({
   secret: env("APP_KEY", ""),
   cookie: "{{name}}_session",
+  // Seven days suits a demo. Anything holding a credential wants less — an app
+  // whose session carries a live mailbox password runs ten hours.
   lifetime: 60 * 60 * 24 * 7, // 7 days
+  // `secure` gates the cookie on HTTPS, and the two environments need opposite
+  // answers. Production refuses to boot without it — the config validator is right
+  // to — but development runs on http://localhost, where a secure cookie is never
+  // sent at all, and the symptom there is a login that appears to succeed and then
+  // bounces back to the sign-in page with nothing in any log.
+  //
+  // Scaffolded environment-aware because every app ends up writing this line, and
+  // the ones that write it after their first failed production deploy write it at
+  // the worst possible moment.
+  secure: env("APP_ENV", "development") === "production",
+  httpOnly: true,
+
+  // `Lax`, not `Strict`. Invitation and password-reset links arrive from a mail
+  // client, and `Strict` withholds the cookie on exactly that first cross-site
+  // navigation — so the link lands the user on a sign-in page instead.
+  sameSite: "Lax",
 });

package/templates/react/package.json

@@ -12,20 +12,20 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/devtools": "{{zerotal_version}}",
     "@inertiajs/react": "^3.0.0",
+    "@zerotal/devtools": "{{zerotal_version}}",
     "@zerotal/inertia": "{{zerotal_version}}",
+    "bun-plugin-tailwind": "0.1.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.0",
     "zerotal": "{{zerotal_version}}"
   },
   "devDependencies": {
+    "@types/bun": "^1.3.14",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "bun-plugin-tailwind": "latest",
-    "tailwindcss": "^4.0.0",
-    "typescript": "^5.8.0",
-    "@types/bun": "^1.3.14"
+    "typescript": "^5.8.0"
   },
   "engines": {
     "bun": ">=1.3.14"

package/templates/react/resources/css/app.css

@@ -46,7 +46,10 @@
   --accent: oklch(0.958 0.018 286);
   --accent-foreground: oklch(0.36 0.14 286);
 
-  --success: oklch(0.6 0.14 158);
+  /* 0.504, not 0.6: measured as status *text* against the 10% success tint it is
+     drawn on, 0.6 is 3.1:1 — under the 4.5:1 WCAG AA needs. Measuring it against
+     the surface *under* the tint is what makes it look like it passes. */
+  --success: oklch(0.504 0.11 158);
   --success-foreground: oklch(0.99 0.01 158);
 
   --destructive: oklch(0.577 0.245 27.3);

package/templates/react/tests/pages.test.ts.tmpl

@@ -0,0 +1,82 @@
+/**
+ * Every page is built once, to prove it can be.
+ *
+ * The rest of the suite asserts values and status codes, and a page can throw on
+ * its first paint while every one of them passes: the route answers `200`, the
+ * Inertia payload is correct, and the failure happens in a browser the test never
+ * opened. An app shipped a blank page to production with 614 green tests exactly
+ * that way — a layout callback read `page.props`, which the callback is not given.
+ *
+ * This proves one thing only: the component tree builds without throwing. That is
+ * precisely the thing nothing else here checks. It is not a DOM — `useEffect` does
+ * not run, and nothing clicks; for that, see `@zerotal/testing/browser`.
+ *
+ * Add a line when you add a page. The cost is one line and the bug it catches is a
+ * white screen your users find first.
+ */
+import { describe, test } from 'bun:test';
+import { renderPage } from '@zerotal/inertia/testing';
+import { defineRoutes } from 'zerotal/routes';
+import { ROUTES } from '../types/routes.generated';
+
+import About from '../resources/js/pages/about';
+import Contact from '../resources/js/pages/contact';
+import ForgotPassword from '../resources/js/pages/forgot-password';
+import Home from '../resources/js/pages/home';
+import Login from '../resources/js/pages/login';
+import Profile from '../resources/js/pages/profile';
+import Register from '../resources/js/pages/register';
+import ResetPassword from '../resources/js/pages/reset-password';
+
+// The same line `resources/js/app.tsx` runs in the browser. `defineRoutes` installs
+// `route()` as a global, and the layout calls it — so without this every page throws
+// `route is not defined`, which is a true statement about a test that has not
+// finished setting up rather than about the page.
+defineRoutes(ROUTES);
+
+/**
+ * What `Inertia.share()` puts on every page. A component that destructures one of
+ * these throws without it — a real failure, but not the one these tests are for.
+ * Keep this in step with `resources/js/types.ts`.
+ */
+const SHARED = {
+  auth: { user: null },
+  flash: { success: null, error: null },
+  errors: {},
+  old: {},
+};
+
+const PAGES: [string, unknown, Record<string, unknown>][] = [
+  ['home', Home, { title: 'Home', message: 'Welcome' }],
+  ['about', About, { title: 'About' }],
+  ['contact', Contact, { title: 'Contact' }],
+  ['login', Login, { title: 'Sign in' }],
+  ['register', Register, { title: 'Create an account' }],
+  ['forgot-password', ForgotPassword, { title: 'Forgot password' }],
+  ['reset-password', ResetPassword, { title: 'Reset password', token: 'test-token' }],
+  ['profile', Profile, { title: 'Profile' }],
+];
+
+describe('pages render', () => {
+  for (const [name, Page, props] of PAGES) {
+    test(`${name} builds without throwing`, async () => {
+      await renderPage(Page, props, { shared: SHARED, url: `/${name}` });
+    });
+  }
+});
+
+/**
+ * A signed-in render as well, because a page that only ever renders as a guest has
+ * had half of it tested. `profile` reads `auth.user` and is the one that shows it.
+ */
+describe('pages render for a signed-in user', () => {
+  const user = { id: 1, name: 'Ada', email: 'ada@example.com' };
+
+  test('profile builds with a user', async () => {
+    await renderPage(
+      Profile,
+      { title: 'Profile' },
+      { shared: { ...SHARED, auth: { user } }, url: '/profile' },
+    );
+  });
+});

package/templates/vue/_gitignore

@@ -1,5 +1,8 @@
 node_modules/
 .zerotal/
-*.sqlite
+# `*.sqlite` alone misses `db.sqlite-wal` and `db.sqlite-shm`. WAL mode is on by
+# default, so both exist in every project, and the write-ahead log holds rows that
+# have not been checkpointed into the main file yet — real ones.
+*.sqlite*
 .env
 public/assets/

package/templates/vue/config/session.ts

@@ -7,5 +7,23 @@ import { SessionConfig } from "zerotal/session";
 export default SessionConfig({
   secret: env("APP_KEY", ""),
   cookie: "{{name}}_session",
+  // Seven days suits a demo. Anything holding a credential wants less — an app
+  // whose session carries a live mailbox password runs ten hours.
   lifetime: 60 * 60 * 24 * 7, // 7 days
+  // `secure` gates the cookie on HTTPS, and the two environments need opposite
+  // answers. Production refuses to boot without it — the config validator is right
+  // to — but development runs on http://localhost, where a secure cookie is never
+  // sent at all, and the symptom there is a login that appears to succeed and then
+  // bounces back to the sign-in page with nothing in any log.
+  //
+  // Scaffolded environment-aware because every app ends up writing this line, and
+  // the ones that write it after their first failed production deploy write it at
+  // the worst possible moment.
+  secure: env("APP_ENV", "development") === "production",
+  httpOnly: true,
+
+  // `Lax`, not `Strict`. Invitation and password-reset links arrive from a mail
+  // client, and `Strict` withholds the cookie on exactly that first cross-site
+  // navigation — so the link lands the user on a sign-in page instead.
+  sameSite: "Lax",
 });

package/templates/vue/package.json

@@ -14,15 +14,15 @@
   "dependencies": {
     "@inertiajs/vue3": "^3.0.0",
     "@zerotal/inertia": "{{zerotal_version}}",
+    "bun-plugin-tailwind": "0.1.2",
+    "tailwindcss": "^4.0.0",
     "vue": "^3.5.0",
     "zerotal": "{{zerotal_version}}"
   },
   "devDependencies": {
+    "@types/bun": "^1.3.14",
     "@vue/compiler-sfc": "^3.5.0",
-    "bun-plugin-tailwind": "latest",
-    "tailwindcss": "^4.0.0",
-    "typescript": "^5.8.0",
-    "@types/bun": "^1.3.14"
+    "typescript": "^5.8.0"
   },
   "engines": {
     "bun": ">=1.3.14"

package/templates/vue/resources/css/app.css

@@ -46,7 +46,10 @@
   --accent: oklch(0.958 0.018 286);
   --accent-foreground: oklch(0.36 0.14 286);
 
-  --success: oklch(0.6 0.14 158);
+  /* 0.504, not 0.6: measured as status *text* against the 10% success tint it is
+     drawn on, 0.6 is 3.1:1 — under the 4.5:1 WCAG AA needs. Measuring it against
+     the surface *under* the tint is what makes it look like it passes. */
+  --success: oklch(0.504 0.11 158);
   --success-foreground: oklch(0.99 0.01 158);
 
   --destructive: oklch(0.577 0.245 27.3);