genesis-stack 1.3.0 → 1.4.0

package/stacks/pieces/jskit.md

@@ -32,6 +32,15 @@ https://mobily-enterprises.github.io/jskit-ai/
   `AUTH_LOCAL_SESSION_SECRET` as a required environment name in the project's
   established environment contract and committed environment example. Never
   commit or invent its value.
+- An application with accounts always has the host's browser-preview login,
+  without waiting to be asked: when adding authentication, add the
+  `auth/auth-surface` pattern's executable `tools/preview-identity` and copy its
+  exact `#### Preview identity` block (Command `tools/preview-identity`,
+  Protocol `vibe64.preview-identity.command.v1`, Identity types `email`
+  `user-id`, Enabled environment `AUTH_DEV_BYPASS_ENABLED`, Secret environment
+  `AUTH_DEV_BYPASS_SECRET`, Runtimes `nodejs`) under the web `Outputs` target.
+  Which existing accounts the preview uses stays the person's choice; never
+  create users for it.
 - Before creating or modifying JSKIT Vue/Vuetify UI, read the Material 3
   contract at
   `https://mobily-enterprises.github.io/jskit-ai/guide/framework/material-3`
@@ -77,6 +86,25 @@ https://mobily-enterprises.github.io/jskit-ai/
   input fields never grant administrator access. Verify the requested provider
   outcomes and denied access with controlled fixtures. Genesis transports
   guidance and opaque declarations; it does not execute integrations or payments.
+- Shipping the app to phones ("install on my phone"): the host-owned
+  `## Packaging` section is written only when the person adds a mobile target.
+  It declares a separate `web-bundle` package whose Build produces the bundled
+  client (Output its build folder) with the absolute HTTPS API base the client
+  calls, then a `capacitor` package with `Content: package <that id>`,
+  `Platforms: android`, a permanent reverse-DNS `Id`, `Name`, a committed
+  1024x1024 PNG `Icon` without transparency, `Version from: package.json` and
+  one `Permission` line, with a plain reason, per native capability. The host
+  generates and discards the native project on every build: never commit
+  `android/`, `ios/`, `capacitor.config.*`, Gradle files, build numbers or
+  signing keys. Native plugins are ordinary client dependencies at the exact
+  versions in `package-lock.json`, and the host's shell is Capacitor 8; it
+  blocks a lockfile mismatch or another major. `@jskit-ai/mobile-capacitor` is
+  still on Capacitor 7, so propose mobile packaging for a JSKIT client only
+  once its Capacitor dependencies are 8.x. A deep-link scheme and app-link
+  domains live once in `## Environment defaults` (for example `APP_URL_SCHEME`,
+  `APP_LINK_DOMAINS`) and Packaging names them with `Deep link scheme from` and
+  `App link domains from`; the server's CORS and OAuth callbacks must accept
+  the app's origin and scheme.
 
 ## Adoption
 
@@ -96,7 +124,9 @@ https://mobily-enterprises.github.io/jskit-ai/
   component when the script or preparation file does not exist.
 - When the project declares an application-owned identity exchange for a host's
   browser preview, preserve its command, selectors, protocol, environment names,
-  runtime and timeout in the project's existing section.
+  runtime and timeout in the project's existing section. When an application
+  with JSKIT accounts lacks it, add it from the `auth/auth-surface` pattern as
+  in Guidance.
   A host-saved identity name/value is not a substitute for this application
   contract.
 - Treat generator descriptors, receipts, sync commands, legacy service

package/stacks/pieces/nextjs.md

@@ -0,0 +1,181 @@
+# Stack piece: nextjs
+
+## Description
+
+Next.js React application conventions: App Router or Pages Router, the
+`next` CLI, Server Actions, middleware, environment variables, builds and
+production serving. A Next.js application has `next` in `package.json`
+dependencies and usually a `next.config.js`, `next.config.mjs` or
+`next.config.ts` file and an `app/` or `pages/` directory. Authoritative
+framework documentation: https://nextjs.org/docs
+
+## Requires
+
+- `nodejs`
+
+## Conflicts
+
+- `express`
+
+## Guidance
+
+- Match the installed Next.js major version and the router the application
+  already uses (`app/` App Router or `pages/` Pages Router). Recent releases
+  ship version-matched documentation in `node_modules/next/dist/docs/`; read
+  the relevant guide there before relying on remembered APIs. `next dev` may
+  write a framework-owned agent-rules block into `AGENTS.md`; commit it rather
+  than repeatedly removing it.
+- Bind the development server to the host and port it is given:
+  `next dev --hostname <host> --port <port>` (the proposed Run passes them
+  through `npm run dev --`). Without `--hostname`, `next dev` and `next start`
+  listen on every interface. Never hard-code a port in `package.json` scripts.
+- Behind a development reverse proxy on loopback that rewrites `Host` and sends
+  `X-Forwarded-Host`, `X-Forwarded-Proto` and `X-Forwarded-Port`, Next.js
+  builds request URLs from the forwarded headers. The development server blocks
+  requests for its own development resources (the `/_next/hmr` WebSocket and
+  other `/_next/*` dev endpoints) whose `Origin` hostname is not `localhost`,
+  the hostname it was started with, or an `allowedDevOrigins` entry. A proxy
+  that rewrites the browser's `Origin` to the loopback address needs no entry;
+  otherwise add the browser-facing hostname pattern to `allowedDevOrigins`,
+  read from an environment variable rather than hard-coded. The HMR client
+  connects through the page's own origin; do not hard-code an asset prefix or
+  WebSocket host for the proxy.
+- Server Actions reject a POST whose `Origin` host differs from
+  `X-Forwarded-Host` (or `Host` without it) with "Invalid Server Actions
+  request". A proxy that forwards both unchanged, or presents a same-origin
+  request entirely on the loopback origin (loopback `Origin` and `Host`, no
+  forwarded host), needs no setting. Add an exact host to
+  `experimental.serverActions.allowedOrigins` only for a real reported
+  mismatch, in development only (ports cannot be wildcarded); the list also
+  applies in production, so never admit arbitrary origins.
+- Redirect with relative paths. A Server Action's redirect travels in a
+  framework response header, not `Location`, so a proxy does not rewrite it,
+  and Auth.js `signIn`/`signOut` with `redirectTo` build an absolute URL from
+  the request's host headers, which a proxy may present as the loopback
+  address. Call them with `redirect: false`, then `redirect("/path")`.
+  `request.nextUrl` in `proxy`/middleware names the server's own host, so an
+  Auth.js `callbackUrl` may be a loopback URL: use only its path.
+- `NEXT_PUBLIC_*` variables are inlined into client bundles at build time:
+  never put secrets in them, and their production values must exist when
+  `next build` runs, not only at start. Server-only values are read from
+  `process.env` at request time. Next.js reads `.env*` files but the
+  environment wins; keep real values out of committed `.env*` files.
+- With Auth.js (`next-auth` v5), supply `AUTH_SECRET` through the environment
+  (generate with `openssl rand -base64 33`; `npx auth secret` writes it into a
+  file instead) and set `AUTH_TRUST_HOST=true` when the app is served behind a
+  trusted reverse proxy, so callback and redirect URLs use the forwarded
+  origin. Other auth libraries need their equivalent trusted-host setting.
+- With `cacheComponents` enabled (the recent `create-next-app` default),
+  pages that read the session must render at request time: call
+  `await connection()` before `auth()`, wrap the read in `<Suspense>`, or
+  export `instant = false`; otherwise `next build` fails. Gate protected
+  routes in `proxy`/middleware (Auth.js `authorized` callback), not only with
+  `redirect()` during render: the client router can replay a cached
+  render-time redirect to the login page after sign-in.
+- Readiness and health probes must reach a public route: middleware (or
+  `proxy`) that redirects `/` to a login page makes a `GET /` probe fail.
+  Exclude the probe path from the auth matcher, or add a small public route
+  handler (for example `app/health/route.ts`) and point the Outputs and
+  Deployment readiness checks at it.
+- Database access goes through the application's ORM (Prisma, Drizzle, Kysely
+  or another). Its schema migrations are application-owned: deployment runs the
+  non-interactive apply command (for example `prisma migrate deploy`), never
+  `prisma migrate dev` or `prisma db push` against supplied data. Seed scripts
+  must be idempotent. Tests use a disposable database supplied for them, never
+  the development or production database. Declare the database Resources in
+  the project Stack; this piece does not choose a database.
+- Production: `next build` then `next start`. `next start` reads `PORT` but not
+  `HOST`; bind it explicitly (`next start --hostname <host>`), as the proposed
+  Serve does. Set `NODE_ENV=production` only through the production
+  environment, never as a project-wide default; `next build` and `next start`
+  set it themselves. `output: "standalone"` changes the start command to
+  `node .next/standalone/server.js` (which reads `HOSTNAME` and `PORT`) and
+  requires copying `public/` and `.next/static/`; update Deployment if the
+  application uses it. `output: "export"` produces static files with no server.
+- Do not run `next build` into the same `.next` directory a running `next dev`
+  uses unless the installed major isolates development output (Next.js 16 and
+  later write development output to `.next/dev`); with older majors stop the
+  development server first or build into a separate `distDir`.
+- When the application has login, seed one administrator and one ordinary user
+  for development through an idempotent seed script with credentials from the
+  environment, and keep role checks on the server (Server Components, route
+  handlers, Server Actions), not only in client components.
+- Shipping the app to phones ("install on my phone") needs a static client:
+  `output: "export"` (no Server Actions, route handlers, middleware or
+  request-time rendering in that build), with API calls going to an absolute
+  HTTPS base read from a `NEXT_PUBLIC_*` variable. The host-owned
+  `## Packaging` section, written only when the person adds a mobile target,
+  declares a `web-bundle` package (Build `npm` `run` `build`, Output `out`)
+  and a `capacitor` package with `Content: package <that id>`,
+  `Platforms: android`, a permanent reverse-DNS `Id`, `Name`, a committed
+  1024x1024 PNG `Icon` without transparency, `Version from: package.json` and
+  one `Permission` line per native capability. Native plugins are ordinary
+  dependencies at exact `package-lock.json` versions on Capacitor 8; the host
+  generates and discards the native project, so never commit `android/`,
+  `capacitor.config.*` or signing keys. A server-rendered app is not yet
+  supported as a phone app: it needs a separate static client first.
+
+## Adoption
+
+- Inventory the real files before changing project contracts: the installed
+  `next` version in the lockfile, `app/` or `pages/`, `next.config.*` (`output`,
+  `basePath`, `distDir`, `experimental`), `middleware.*`/`proxy.*`, the auth
+  library and its environment names, the ORM and its migration commands, and
+  the real `dev`, `build`, `start`, `lint` and `test` scripts.
+- Identify the package manager from the lockfile and replace every proposed
+  `npm` line when the project uses pnpm, Yarn or Bun. Next.js 16 removed
+  `next lint`; if the `lint` script is missing, remove that Verification line
+  instead of inventing one, and add the project's real test command when it
+  has one.
+- Replace the readiness path when `/` is not publicly reachable, a `basePath`
+  is set, or a dedicated health route exists. Replace the Serve line for
+  `output: "standalone"`, a custom server, or `output: "export"`.
+- A custom Next.js server built on Express is a project-owned decision: keep
+  this piece and describe that server's real commands in the project's own
+  sections.
+
+## Workspace setup
+
+- Prepare `Install dependencies` with `nodejs` when `package.json` exists: `npm` `install`
+
+## Outputs
+
+### Target `app`: Run Next.js app
+
+- Default.
+- Mode: `interactive`
+- Runtimes: `nodejs`
+- Run `Develop`: `npm` `run` `dev` `--` `--hostname` `{host}` `--port` `{port}`
+
+#### Presentation
+
+- Kind: `web`
+- Preferred port: `3000`
+- URL path: `/`
+- Ready when: `GET` `/` returns `200`
+
+## Verification
+
+- Verify `lint`: `npm` `run` `lint`
+- Verify `build`: `npm` `run` `build`
+
+## Deployment
+
+- Runtimes: `nodejs`
+- Recreate on restore: `node_modules` `.next/cache`
+- Ready when: `GET` `/` returns `200`
+- Prepare `Install dependencies`: `npm` `ci`
+- Build `Build`: `npm` `run` `build`
+- Serve `Start`: `sh` `-c` `exec npm start -- --hostname "$HOST"`
+
+## Deslop
+
+- Keep data fetching in Server Components, route handlers and Server Actions
+  where the router supports it; remove client-side fetch wrappers that only
+  duplicate a server read.
+- Keep `"use client"` boundaries as low in the tree as possible and do not mark
+  whole layouts as client components to reach one interactive widget.
+- Use the framework's `Link`, `Image`, `Script`, metadata and font facilities
+  instead of hand-written equivalents.
+- Remove abandoned starter content, unused route segments and duplicate
+  environment readers only when routes, redirects and tests stay unchanged.

package/stacks/pieces/nodejs.md

@@ -41,9 +41,21 @@ Node.js package, command, module, dependency, and test conventions.
   `package.json` and `package-lock.json` stay unchanged; Verify resolves each
   package from the application root and fails unless it resolves to its
   connected source root. An ordinary `npm ci` restores the published packages.
+- Publishing a library to npm: the host-owned `## Packaging` section declares
+  the package (`npm` packer, its Workdir, `Version from: package.json`) only
+  when a publishing target is added; the host builds with `npm pack` from the
+  saved commit and owns tags, credentials and uploads. Keep `name`, `version`,
+  `license`, `files` (or `.npmignore`) and an `exports`/`main` entry correct in
+  `package.json`; never commit tarballs, tokens or `.npmrc` credentials, and
+  remove `"private": true` only for a package that is really published. A
+  build step before packing (TypeScript, bundling) is a declared Build command
+  such as `npm run build`, not a `prepublishOnly` script. A project using
+  Changesets or release-please keeps that tool and declares
+  `Version from: external`.
 - Long-running web processes accept their listen host and port from arguments
   or the environment rather than hard-coding them, and fail if the port is
-  taken instead of silently choosing another.
+  taken instead of silently choosing another. For Express or Next.js select
+  `express` or `nextjs`; that piece owns the framework traps.
 
 ## Adoption
 

package/stacks/pieces/python.md

@@ -42,13 +42,26 @@ Python package, module, callable, dependency, and test conventions.
   PEP 610 `direct_url.json` is editable with the source root's `file:` URL and
   that its modules import from there. Do not use `uv sync`, which needs tracked
   `[tool.uv.sources]` and lockfile changes.
+- Publishing a library to PyPI: the host-owned `## Packaging` section declares
+  the package (`python-dist` packer, `Runtimes: python`, its `dist` Output,
+  `Version from: pyproject.toml`) only when a publishing target is added; the
+  host builds the sdist and wheel from the saved commit and owns tags,
+  credentials and uploads. The build runs in a clean copy where `build` is
+  not installed, and managed Pythons refuse a bare `pip install` (PEP 668), so
+  a plain `python3 -m build` fails. The package installs its own throwaway
+  tools: Prepare `python3 -m venv .build-tools`, Prepare
+  `.build-tools/bin/python -m pip install --quiet build`, Build
+  `.build-tools/bin/python -m build`; add `.build-tools/` to `.gitignore`. Keep a PEP 621
+  `[project]` table with a static `version`, `readme`, `license` and
+  `requires-python` so `twine check --strict` passes; versions use PEP 440
+  (`1.5.0rc1`). Never commit `dist/`, tokens or `.pypirc`. A project with a
+  dynamic version (setuptools-scm, hatch-vcs) declares
+  `Version from: external`.
 - Running a web process: bind the supplied listen host and port, trust forwarded
   headers only from a loopback proxy, and read secrets from the environment.
-  Django: set `ALLOWED_HOSTS` and `CSRF_TRUSTED_ORIGINS` for the served origin
-  (`ALLOWED_HOSTS` also lists the loopback host the proxy connects to),
-  `SECURE_PROXY_SSL_HEADER` and `USE_X_FORWARDED_HOST` only behind that trusted
-  proxy, and read `SECRET_KEY` from the environment. Flask uses Werkzeug's
-  `ProxyFix`; Uvicorn uses `--proxy-headers --forwarded-allow-ips 127.0.0.1`.
+  For Django select `django`; its piece owns the framework traps. Flask uses
+  Werkzeug's `ProxyFix`; Uvicorn uses `--proxy-headers --forwarded-allow-ips
+  127.0.0.1`.
 
 ## Connected development
 

package/stacks/pieces/rails-mysql.md

@@ -0,0 +1,81 @@
+# Stack piece: rails-mysql
+
+## Description
+
+Rails MySQL connection, Active Record migration, and database environment conventions.
+
+## Requires
+
+- `rails`
+- `mysql`
+
+## Conflicts
+
+- `rails-postgresql`
+- `rails-sqlite`
+
+## Environment defaults
+
+- Default `DB_HOST`: `127.0.0.1`
+- Default `DB_PORT`: `3306`
+- Default `DB_DATABASE`: `rails`
+- Default `DB_USERNAME`: `root`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "mysql",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_DATABASE",
+        "host": "DB_HOST",
+        "password": "DB_PASSWORD",
+        "port": "DB_PORT",
+        "username": "DB_USERNAME"
+      },
+      "allowEmpty": ["password"],
+      "preferred": true
+    }
+  ],
+  "optionalBindings": {
+    "testDatabase": "TEST_DB_NAME"
+  }
+}
+```
+
+## Guidance
+
+- `rails new -d mysql` (adapter `mysql2`) or `-d trilogy` hard-codes database
+  names. Make `config/database.yml` read the resource names: under `default`,
+  `host: <%= ENV.fetch("DB_HOST", "127.0.0.1") %>`,
+  `port: <%= ENV.fetch("DB_PORT", 3306) %>`,
+  `username: <%= ENV["DB_USERNAME"] %>`, `password: <%= ENV["DB_PASSWORD"] %>`;
+  and `database: <%= ENV["DB_DATABASE"] %>` for development and the
+  production primary. Point `test` at
+  `<%= ENV.fetch("TEST_DB_NAME", "<app>_test") %>`, never at the development
+  or production database.
+- Keep `encoding: utf8mb4`. `mysql2` compiles against the MySQL client
+  library; `trilogy` (Rails 7.1+) is pure Ruby and avoids it. Do not switch an
+  existing app's adapter without testing it.
+- `bin/rails test` purges the test database whenever its schema is out of
+  date by dropping and recreating it, so the user needs `CREATE` and `DROP`
+  on that database name even when `TEST_DB_NAME` names it.
+- Rails 8 production declares separate `cache`, `queue` and `cable`
+  databases. When only one database is supplied, follow the Solid Cache, Solid
+  Queue and Solid Cable single-database instructions (their schemas become
+  ordinary migrations and their `connects_to` settings are removed) instead of
+  inventing extra database names.
+- Use the inherited Rails migration and seed guidance. Keep connection,
+  integration and payment records in this database through Active Record
+  migrations and transactions; test uniqueness and concurrent updates on MySQL
+  itself.
+
+## Adoption
+
+- Confirm the adapter, every environment's database, username, password, host
+  and port expressions in `config/database.yml`, and whether `DATABASE_URL` is
+  read, before declaring readiness or connecting. Align the project Resource
+  bindings with the names the file actually reads.

package/stacks/pieces/rails-postgresql.md

@@ -0,0 +1,86 @@
+# Stack piece: rails-postgresql
+
+## Description
+
+Rails PostgreSQL connection, Active Record migration, and database environment conventions.
+
+## Requires
+
+- `rails`
+- `postgresql`
+
+## Conflicts
+
+- `rails-mysql`
+- `rails-sqlite`
+
+## Environment defaults
+
+- Default `DB_HOST`: `127.0.0.1`
+- Default `DB_PORT`: `5432`
+- Default `DB_DATABASE`: `rails`
+- Default `DB_USERNAME`: `postgres`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "postgresql",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_DATABASE",
+        "host": "DB_HOST",
+        "password": "DB_PASSWORD",
+        "port": "DB_PORT",
+        "username": "DB_USERNAME"
+      },
+      "allowEmpty": ["password"],
+      "preferred": true
+    }
+  ],
+  "optionalBindings": {
+    "testDatabase": "TEST_DB_NAME"
+  }
+}
+```
+
+## Guidance
+
+- `rails new -d postgresql` hard-codes database names and reads only a
+  production password variable. Make `config/database.yml` read the resource
+  names: under `default`, `host: <%= ENV.fetch("DB_HOST", "127.0.0.1") %>`,
+  `port: <%= ENV.fetch("DB_PORT", 5432) %>`,
+  `username: <%= ENV["DB_USERNAME"] %>`, `password: <%= ENV["DB_PASSWORD"] %>`;
+  and `database: <%= ENV["DB_DATABASE"] %>` for development and the
+  production primary. Point `test` at
+  `<%= ENV.fetch("TEST_DB_NAME", "<app>_test") %>`, never at the development
+  or production database.
+- `bin/rails test` purges the test database whenever its schema is out of
+  date by dropping and recreating it, so the role needs `CREATEDB` (and must
+  own the database) even when `TEST_DB_NAME` names it.
+- After loading fixtures, Rails checks their foreign keys
+  (`verify_foreign_keys_for_fixtures`, on by default) by updating
+  `pg_catalog.pg_constraint`, which only a superuser may do. With an ordinary
+  `CREATEDB` role every fixture test fails with `permission denied for table
+  pg_constraint`; set `config.active_record.verify_foreign_keys_for_fixtures =
+  false` in `config/environments/test.rb` rather than granting superuser.
+- Rails 8 production declares separate `cache`, `queue` and `cable`
+  databases. When only one database is supplied, follow the Solid Cache, Solid
+  Queue and Solid Cable single-database instructions (their schemas become
+  ordinary migrations and their `connects_to` settings are removed) instead of
+  inventing extra database names.
+- The `pg` gem compiles against libpq unless the locked version ships a
+  precompiled gem for the platform.
+- Use the inherited Rails migration and seed guidance. Keep connection,
+  integration and payment records in this database through Active Record
+  migrations and transactions; test uniqueness and concurrent updates on
+  PostgreSQL itself.
+
+## Adoption
+
+- Confirm the adapter, every environment's database, username, password, host
+  and port expressions in `config/database.yml`, and whether `DATABASE_URL` is
+  read, before declaring readiness or connecting. Align the project Resource
+  bindings with the names the file actually reads.

package/stacks/pieces/rails-sqlite.md

@@ -0,0 +1,60 @@
+# Stack piece: rails-sqlite
+
+## Description
+
+Rails SQLite connection, Active Record migration, and database filename conventions.
+
+## Requires
+
+- `rails`
+- `sqlite`
+
+## Conflicts
+
+- `rails-mysql`
+- `rails-postgresql`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "sqlite",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_DATABASE"
+      },
+      "preferred": true
+    }
+  ]
+}
+```
+
+## Guidance
+
+- `rails new` (SQLite is the default) writes repository-relative files under
+  `storage/`, and Rails 8.1 leaves the production files unset. Make the
+  development and production primary read the supplied filename with the
+  generated name as fallback, for example
+  `database: <%= ENV.fetch("DB_DATABASE", "storage/development.sqlite3") %>`.
+  A bare `ENV.fetch("DB_DATABASE")` raises while `database.yml` loads and
+  breaks generators and asset builds that run without the variable. Keep `test`
+  on its own file such as `storage/test.sqlite3`.
+- Rails 8 production also declares `cache`, `queue` and `cable` SQLite
+  databases. Keep them next to the primary file, for example
+  `<%= File.join(File.dirname(ENV.fetch("DB_DATABASE", "storage/production.sqlite3")), "production_cache.sqlite3") %>`,
+  so they persist with it; never leave them in a disposable release directory.
+- Do not replace a supplied filename with a repository-relative default or
+  delete an existing file. `bin/rails db:prepare` creates a missing file and
+  its schema and migrates an existing one.
+- The `sqlite3` gem normally installs a precompiled native gem; a source build
+  needs the SQLite headers. Use the inherited Rails migration and seed
+  guidance and test concurrent writes on SQLite itself.
+
+## Adoption
+
+- Read `config/database.yml` for every environment's filename, including the
+  Rails 8 cache, queue and cable files, and preserve existing data: snapshot
+  it before moving to a supplied filename. Do not switch an existing app to an
+  empty database.