genesis-stack 1.3.0 → 1.3.1

package/README.md

@@ -54,6 +54,17 @@ consistent backups. `laravel-sqlite` adds Laravel's `DB_DATABASE` filename
 binding and `DB_CONNECTION=sqlite` default. Hosts own provisioning; applications
 own schema changes and preservation of existing data during adoption.
 
+The `django`, `rails`, `spring-boot`, `express` and `nextjs` pieces require
+their language piece, link the framework's official documentation, and propose
+its conventional Workspace setup, Outputs, Verification and Deployment for
+review during adoption. Their database integrations (`django-*` and `rails-*`
+for PostgreSQL, MySQL and SQLite; `spring-boot-*` for PostgreSQL and MySQL)
+bind the framework's own configuration names without a password default.
+Express and Next.js have no framework ORM, so their applications declare
+database Resources in the project Stack. `express` and `nextjs` conflict because
+both propose how to run the same Node.js process. No starter templates exist for
+these frameworks yet.
+
 ## Resource-estimate proposals
 
 JSKIT proposes a host's optional `Resource estimates` section for its concrete

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-stack",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "The optional curated technology Stack catalog for Genesis projects.",
   "type": "module",
   "repository": {

package/stacks/pieces/django-mysql.md

@@ -0,0 +1,79 @@
+# Stack piece: django-mysql
+
+## Description
+
+Django MySQL database engine, driver, connection settings, migration, and test
+database conventions. Database documentation:
+https://docs.djangoproject.com/en/stable/ref/databases/
+
+## Requires
+
+- `django`
+- `mysql`
+
+## Conflicts
+
+- `django-postgresql`
+- `django-sqlite`
+
+## Environment defaults
+
+- Default `DB_HOST`: `127.0.0.1`
+- Default `DB_PORT`: `3306`
+- Default `DB_NAME`: `django`
+- Default `DB_USER`: `root`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "mysql",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_NAME",
+        "host": "DB_HOST",
+        "password": "DB_PASSWORD",
+        "port": "DB_PORT",
+        "username": "DB_USER"
+      },
+      "allowEmpty": ["password"],
+      "preferred": true
+    },
+    {
+      "bindings": {
+        "url": "DATABASE_URL"
+      }
+    }
+  ],
+  "optionalBindings": {
+    "testDatabase": "TEST_DB_NAME"
+  }
+}
+```
+
+## Guidance
+
+- Use `ENGINE: "django.db.backends.mysql"` with the `mysqlclient` driver.
+  It compiles against the MySQL or MariaDB client library and needs its
+  headers, `pkg-config` and a C compiler when no binary wheel matches; the
+  database server itself is not enough.
+- Build `DATABASES["default"]` from `DB_NAME`, `DB_USER`, `DB_PASSWORD`,
+  `DB_HOST` and `DB_PORT`, or parse `DATABASE_URL` with the app's existing
+  parser (for example `dj-database-url`) when it is set. Keep one source of
+  truth; do not merge partial values from both.
+- Set `OPTIONS: {"charset": "utf8mb4", "init_command": "SET sql_mode='STRICT_TRANS_TABLES'"}`
+  so text is stored losslessly and invalid values fail instead of being
+  truncated.
+- When `TEST_DB_NAME` is supplied, set `DATABASES["default"]["TEST"]["NAME"]`
+  to it and run tests with `--keepdb`; Django reuses the existing database.
+  Without it, the user needs permission to create `test_<NAME>`.
+
+## Adoption
+
+- Confirm the driver, the settings source of each connection value, any
+  `DATABASE_URL` parser, `OPTIONS` and the test database name from the
+  settings module before declaring readiness or connecting. Keep the project
+  Resource contract aligned with names the application deliberately uses
+  instead.

package/stacks/pieces/django-postgresql.md

@@ -0,0 +1,78 @@
+# Stack piece: django-postgresql
+
+## Description
+
+Django PostgreSQL database engine, driver, connection settings, migration, and test
+database conventions. Database documentation:
+https://docs.djangoproject.com/en/stable/ref/databases/
+
+## Requires
+
+- `django`
+- `postgresql`
+
+## Conflicts
+
+- `django-mysql`
+- `django-sqlite`
+
+## Environment defaults
+
+- Default `DB_HOST`: `127.0.0.1`
+- Default `DB_PORT`: `5432`
+- Default `DB_NAME`: `django`
+- Default `DB_USER`: `postgres`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "postgresql",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_NAME",
+        "host": "DB_HOST",
+        "password": "DB_PASSWORD",
+        "port": "DB_PORT",
+        "username": "DB_USER"
+      },
+      "allowEmpty": ["password"],
+      "preferred": true
+    },
+    {
+      "bindings": {
+        "url": "DATABASE_URL"
+      }
+    }
+  ],
+  "optionalBindings": {
+    "testDatabase": "TEST_DB_NAME"
+  }
+}
+```
+
+## Guidance
+
+- Use `ENGINE: "django.db.backends.postgresql"` with the `psycopg` (version 3)
+  driver; `psycopg[binary]` needs no build toolchain. Older apps on
+  `psycopg2` keep it until a deliberate upgrade.
+- Build `DATABASES["default"]` from `DB_NAME`, `DB_USER`, `DB_PASSWORD`,
+  `DB_HOST` and `DB_PORT`, or parse `DATABASE_URL` with the app's existing
+  parser (for example `dj-database-url`) when it is set. Keep one source of
+  truth; do not merge partial values from both.
+- When `TEST_DB_NAME` is supplied, set `DATABASES["default"]["TEST"]["NAME"]`
+  to it and run tests with `--keepdb`: Django then reuses the existing
+  database instead of needing permission to create one. Without it, the test
+  role needs `CREATEDB`.
+- Keep schema changes in Django migrations; avoid raw SQL schema edits
+  outside `RunSQL` operations committed with the app.
+
+## Adoption
+
+- Confirm the driver, the settings source of each connection value, any
+  `DATABASE_URL` parser, `CONN_MAX_AGE`/pooling options and the test database
+  name from the settings module before declaring readiness or connecting.
+  Keep the project Resource contract aligned with names the application
+  deliberately uses instead.

package/stacks/pieces/django-sqlite.md

@@ -0,0 +1,55 @@
+# Stack piece: django-sqlite
+
+## Description
+
+Django SQLite database file, migration, and test database conventions.
+Database documentation:
+https://docs.djangoproject.com/en/stable/ref/databases/#sqlite-notes
+
+## Requires
+
+- `django`
+- `sqlite`
+
+## Conflicts
+
+- `django-postgresql`
+- `django-mysql`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "sqlite",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_NAME"
+      },
+      "preferred": true
+    }
+  ]
+}
+```
+
+## Guidance
+
+- Use `ENGINE: "django.db.backends.sqlite3"` and read `NAME` from `DB_NAME`.
+  Preserve an absolute filename supplied by the environment. Only a
+  standalone checkout without `DB_NAME` falls back to a path such as
+  `BASE_DIR / "db.sqlite3"`, which stays out of Git.
+- Repeated setup must preserve the file, its records and the migration
+  ledger: run `migrate --noinput`, never delete or recreate the file as
+  routine preparation.
+- Tests use an in-memory database unless `DATABASES["default"]["TEST"]["NAME"]`
+  names a file; never point it at the development file.
+- SQLite allows one writer at a time. Keep Gunicorn to a small worker count
+  and short transactions, and consider `"OPTIONS": {"transaction_mode": "IMMEDIATE"}`
+  with a `timeout` when concurrent writes report "database is locked".
+
+## Adoption
+
+- Read the settings module's `DATABASES` before declaring readiness and keep
+  any existing database file and its data when adopting supplied storage.
+  Verify migrations against the configured file and keep tests separate.

package/stacks/pieces/django.md

@@ -0,0 +1,166 @@
+# Stack piece: django
+
+## Description
+
+Django web application, settings, migrations, management commands, static
+files, test runner, and production serving conventions. Identified by
+`manage.py` beside a settings module, with `django` in `requirements.txt` or
+`pyproject.toml`. Authoritative framework documentation:
+https://docs.djangoproject.com/
+
+## Requires
+
+- `python`
+
+## Guidance
+
+- Use the Django version the application pins and follow the matching
+  official documentation. Preserve Django's apps, models, forms, class-based
+  or function views, middleware, signals, admin and management commands
+  instead of adding parallel framework plumbing.
+- The development server binds the supplied loopback host and port:
+  `manage.py runserver {host}:{port}`. Never bind `0.0.0.0` to make a proxy
+  work.
+- Behind a loopback development reverse proxy that rewrites `Host` and sends
+  `X-Forwarded-Host`, `X-Forwarded-Proto` and `X-Forwarded-Port`, set
+  `USE_X_FORWARDED_HOST = True`, `USE_X_FORWARDED_PORT = True` and
+  `SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")`. This is
+  safe only because the server is reachable solely through that proxy; keep
+  the bind on loopback. Absolute URLs, redirects and `request.is_secure()`
+  then use the browser-facing origin. Without `SECURE_PROXY_SSL_HEADER`, an
+  HTTPS browser origin makes every form POST fail Django's CSRF origin check.
+- Read `ALLOWED_HOSTS` from a comma-separated `DJANGO_ALLOWED_HOSTS`. When it
+  is unset, allow `["*"]` only while `DEBUG` is on, because the browser-facing
+  development host is not known in advance; otherwise default to
+  `["127.0.0.1", "localhost"]`. Production lists its public host names and
+  keeps `127.0.0.1` so a loopback readiness probe is admitted.
+- Read `CSRF_TRUSTED_ORIGINS` from a comma-separated
+  `DJANGO_CSRF_TRUSTED_ORIGINS`. It is usually unnecessary once the
+  forwarded host and protocol are trusted, because Django then compares the
+  `Origin` header with the browser-facing origin. Never trust loopback or
+  wildcard origins to make a failing form POST pass; fix the proxy trust
+  instead.
+- Read `DEBUG` from `DJANGO_DEBUG` (`1` enables it) and default it off. Set
+  it in the development environment only.
+- `XFrameOptionsMiddleware` answers `X-Frame-Options: DENY`, so a development
+  tool that shows the application inside a frame stays blank. When that is
+  needed, remove the middleware only while `DEBUG` is on; production keeps it.
+- Read `SECRET_KEY` from `DJANGO_SECRET_KEY` and fail when it is missing.
+  Replace the insecure key `startproject` writes into settings. Generate each
+  environment's value with
+  `python -c 'from django.core.management.utils import get_random_secret_key as k; print(k())'`
+  and supply it through that environment's secret facility; never commit it
+  or write it into a generated dotenv file. Development and production use
+  different keys. Every `manage.py` command imports settings, so supply the
+  development key before workspace setup runs `migrate`.
+- Setup and deployment run `manage.py migrate --noinput`. `makemigrations` is
+  authoring: run it after model changes and commit the generated files. Never
+  use `flush`, `migrate --fake`, `reset_db`, or delete or rewrite applied
+  migrations as routine preparation.
+- Seed reference data and development users through idempotent management
+  commands (`get_or_create`/`update_or_create`, `set_password`) or data
+  migrations. `createsuperuser --noinput` fails once the user exists, so it
+  is a one-off command, never a repeated setup step: seed the development
+  administrator and a non-administrator in one app-owned command that reads
+  their passwords from the environment (for example
+  `DJANGO_SUPERUSER_PASSWORD`) and run it after `migrate` in the project's
+  setup. Never hard-code production credentials.
+- Static files: set `STATIC_ROOT`, run `collectstatic --noinput` in
+  deployment, and add `whitenoise.middleware.WhiteNoiseMiddleware` directly
+  after `SecurityMiddleware`; `runserver` serves static files only while
+  `DEBUG` is on. Keep `STATIC_ROOT` and media uploads out of Git.
+- Tests: `manage.py test` creates `test_<NAME>` and needs permission to
+  create databases. When the environment supplies a separate disposable test
+  database instead, set `DATABASES["default"]["TEST"]["NAME"]` from it and keep
+  `--keepdb`, which reuses an existing database rather than creating or
+  dropping one. Never point tests at the development or production database.
+  Suites that create users spend most of their time hashing passwords: set
+  `PASSWORD_HASHERS = ["django.contrib.auth.hashers.MD5PasswordHasher"]` only
+  in a test settings module or under `if sys.argv[1:2] == ["test"]:`; never
+  outside tests.
+- Production serves with Gunicorn through an app-owned `gunicorn.conf.py`
+  (read from the working directory by default) containing
+  `wsgi_app = "<project>.wsgi"` and
+  `bind = f"{os.environ.get('HOST', '127.0.0.1')}:{os.environ.get('PORT', '8000')}"`.
+  Add `gunicorn` and `whitenoise` to the requirements. Keep `DEBUG` off,
+  enable `SESSION_COOKIE_SECURE` and `CSRF_COOKIE_SECURE` behind HTTPS, and
+  review `manage.py check --deploy`. It rejects the console email backend that
+  recent `startproject` templates configure (`MAILERS` or `EMAIL_BACKEND`), so
+  select the production email backend and its credentials from the
+  environment. When `SECURE_SSL_REDIRECT` is on, add the
+  readiness path to `SECURE_REDIRECT_EXEMPT` so a plain loopback probe is not
+  redirected.
+- The proposed readiness path is the admin login page `/admin/login/`. An
+  application without `django.contrib.admin` adds a small unauthenticated
+  health view and updates its Outputs and Deployment readiness to it.
+- The proposals install from `requirements.txt` into `.venv`. Poetry, uv or
+  other `pyproject.toml` workflows replace the install lines in the project's
+  sections with that tool's equivalent.
+- Select `django-postgresql`, `django-mysql` or `django-sqlite` for the
+  database settings; it owns the engine and environment names.
+
+## Adoption
+
+- Inspect `manage.py`, the settings module (single file or split
+  base/development/production modules), `DJANGO_SETTINGS_MODULE`,
+  `requirements*.txt` or `pyproject.toml` and its lock file, `wsgi.py`/`asgi.py`,
+  `INSTALLED_APPS`, `MIDDLEWARE`, `DATABASES`, and existing environment names
+  before changing project contracts. Preserve the pinned Django major.
+- Record the real install, migrate, seed, test, static and serving commands.
+  Replace any proposed line that does not match (ASGI servers such as
+  Uvicorn or Daphne, a different settings module, a non-admin readiness path)
+  before claiming readiness.
+- Confirm how settings read the secret key, debug flag, allowed hosts, CSRF
+  origins and proxy headers; move committed values into the environment
+  without changing their meaning.
+- Select the matching Django database piece when the app uses PostgreSQL,
+  MySQL or SQLite.
+
+## Workspace setup
+
+- Prepare `Create virtual environment` with `python` when `manage.py` exists: `python3` `-m` `venv` `.venv`
+- Prepare `Install Python dependencies` with `python` if `requirements.txt` exists: `.venv/bin/python` `-m` `pip` `install` `-r` `requirements.txt`
+- Prepare `Apply migrations` with `python` when `manage.py` exists: `.venv/bin/python` `manage.py` `migrate` `--noinput`
+
+## Outputs
+
+### Target `app`: Run Django app
+
+- Default.
+- Mode: `interactive`
+- Runtimes: `python`
+- Run `Develop`: `.venv/bin/python` `manage.py` `runserver` `{host}:{port}`
+
+#### Presentation
+
+- Kind: `web`
+- Preferred port: `8000`
+- URL path: `/`
+- Ready when: `GET` `/admin/login/` returns `200`
+
+## Verification
+
+- Verify `application`: `.venv/bin/python` `manage.py` `test` `--noinput` `--keepdb`
+
+## Deployment
+
+- Runtimes: `python`
+- Recreate on restore: `.venv`
+- Ready when: `GET` `/admin/login/` returns `200`
+- Prepare `Create virtual environment`: `python3` `-m` `venv` `.venv`
+- Prepare `Install dependencies`: `.venv/bin/python` `-m` `pip` `install` `-r` `requirements.txt`
+- Build `Collect static files`: `.venv/bin/python` `manage.py` `collectstatic` `--noinput`
+- Migrate `Apply migrations`: `.venv/bin/python` `manage.py` `migrate` `--noinput`
+- Serve `Start`: `.venv/bin/gunicorn`
+
+## Deslop
+
+- Preserve Django's apps, models, managers, querysets, forms, views,
+  middleware, signals, admin registrations and management commands as the
+  owners of their behavior.
+- Keep validation in forms, serializers or model `clean` methods and
+  authorization in views, permissions or decorators. Remove service layers,
+  repositories or helper modules only when they merely rename ORM or framework
+  operations.
+- Preserve migration history; cleanup is not permission to squash, rewrite or
+  delete applied migrations or change model behavior.

package/stacks/pieces/express.md

@@ -0,0 +1,143 @@
+# Stack piece: express
+
+## Description
+
+Express HTTP server, routing, middleware, session, proxy trust, and production
+serving conventions. An Express application declares `express` in
+`package.json` and starts from an entry such as `app.js`, `server.js`,
+`src/index.*` or express-generator's `bin/www`. Authoritative framework
+documentation: https://expressjs.com/
+
+## Requires
+
+- `nodejs`
+
+## Conflicts
+
+- `nextjs`
+
+## Guidance
+
+- Read the authoritative documentation at `https://expressjs.com/` and match
+  the installed Express major. Express 5 changes route path syntax, rejected
+  promise handling and `req.host`; follow
+  `https://expressjs.com/en/guide/migrating-5.html` only for an intended
+  upgrade. Preserve the existing module system, router layout, template
+  engine and lockfile manager; a pnpm or Yarn lockfile replaces the proposed
+  npm lines with that manager's equivalents.
+- Listen on the host and port supplied through the environment:
+  `server.listen(Number(process.env.PORT ?? 3000), process.env.HOST ?? '127.0.0.1')`.
+  express-generator's `bin/www` reads `PORT` but listens on every interface;
+  pass the host. Let a taken port fail instead of choosing another one. The
+  proposed development Run is `npm start`; when the project develops through
+  a watch script (`node --watch`, nodemon, tsx), point Run at that script.
+- Behind a loopback development reverse proxy that rewrites `Host` to the
+  loopback address and sends `X-Forwarded-Host`, `X-Forwarded-Proto` and
+  `X-Forwarded-Port`, set `app.set('trust proxy', 'loopback')` before any
+  middleware so `req.protocol`, `req.secure`, `req.hostname`, Express 5
+  `req.host` and `req.ip` describe the browser-facing request. Never use
+  `trust proxy` `true` for a server reachable without that proxy. Express
+  ignores `X-Forwarded-Port`, and Express 4 `req.hostname` drops the port.
+  Prefer relative redirects (`res.redirect('/login')`) and root-relative asset
+  URLs; build an absolute URL from `req.protocol` and Express 5 `req.host`, or
+  from a configured public origin, never from the raw `Host` header. On
+  Express 4 take the host from `X-Forwarded-Host` only when
+  `req.app.get('trust proxy fn')(req.socket.remoteAddress, 0)` accepts the
+  peer, and from `Host` otherwise.
+- Express has no host allow-list or CSRF protection of its own. When the app
+  adds them, keep a session-bound CSRF token (or a maintained token library)
+  for form posts; an `Origin` check must accept the origin built from the
+  trusted forwarded host as well as the raw `Host`, because a development
+  proxy may present same-origin requests with a loopback `Origin`. A host or
+  CORS allow-list must also admit loopback for the health probe.
+- Sessions use `express-session` with `secret: process.env.SESSION_SECRET`,
+  generated with `openssl rand -base64 32`, supplied through the environment,
+  never committed and never written into a generated dotenv file; refuse to
+  start in production without it. Development may fall back to a random
+  per-process secret, which ends sessions on restart. Use
+  `cookie: { secure: 'auto', httpOnly: true, sameSite: 'lax' }`; `'auto'`
+  depends on the proxy trust above. The default MemoryStore leaks and loses
+  sessions on restart: production uses a persistent store backed by the app's
+  database or cache.
+- Register an unauthenticated `GET /health` returning `200` before session,
+  authentication, CSRF and HTTPS-redirect middleware. Keep it cheap and free
+  of writes. The proposed Outputs and Deployment readiness use it; an app
+  with another health path changes both.
+- Serve static files with `express.static(path.join(__dirname, 'public'))`
+  or the ESM equivalent. A bundler or TypeScript build adds a Workspace setup
+  step and a Deployment Build step and serves the compiled output.
+- Express has no ORM. Select the database component and record the app's own
+  migration tool (Prisma, Drizzle, Knex, Sequelize, TypeORM) as Workspace
+  setup and Deployment Migrate steps, for example `prisma migrate deploy` or
+  `knex migrate:latest`. Never run `prisma migrate dev`, `prisma db push` or
+  `sync({ force: true })` against supplied data. Seeds are idempotent
+  upserts. Tests use a separate disposable database, never the development
+  one.
+- Deployment installs with `npm ci --omit=dev` (a lockfile is required) and
+  serves `npm start`, which receives `HOST` and `PORT` only through the
+  environment. Set `NODE_ENV=production` in the production environment, not
+  as a project-wide default: it enables view caching and stops the error
+  handler exposing stack traces. Exclude `/health` from any HTTPS redirect or
+  host check, and close the server on `SIGTERM`. `npm start` runs the server
+  under npm and a shell that do not pass `SIGTERM` on, so the supervisor must
+  signal the whole process group or serve `node <entry>` directly.
+- When the app has login, hash passwords with bcrypt or argon2 and store a
+  role. Seed one development administrator and one ordinary user through an
+  idempotent script that reads their passwords from the environment; never
+  hard-code production credentials.
+
+## Adoption
+
+- Inventory `package.json` (Express major, `type`, `main`, `start`/`dev`/`test`
+  scripts), the lockfile, the entry file and its `listen` call, middleware
+  order, session store, template engine, authentication library, database
+  and migration tool, and any TypeScript or bundler build.
+- Replace every proposal line that does not match before claiming readiness.
+  Many Express apps (express-generator included) have no `test` script: record
+  the real check instead of inventing `npm test`.
+- Make the server honour `HOST`/`PORT`, trust only the loopback proxy, and
+  expose `/health`. Select the matching database component.
+- An Express server that hosts Next.js through a custom server is a Next.js
+  project; select `nextjs` instead and keep the custom server project-owned.
+
+## Workspace setup
+
+- Prepare `Install dependencies` with `nodejs` when `package.json` exists: `npm` `install`
+
+## Outputs
+
+### Target `app`: Run Express app
+
+- Default.
+- Mode: `interactive`
+- Runtimes: `nodejs`
+- Run `Develop`: `npm` `start`
+
+#### Presentation
+
+- Kind: `web`
+- Preferred port: `3000`
+- URL path: `/`
+- Ready when: `GET` `/health` returns `200`
+
+## Verification
+
+- Verify `application`: `npm` `test`
+
+## Deployment
+
+- Runtimes: `nodejs`
+- Recreate on restore: `node_modules`
+- Ready when: `GET` `/health` returns `200`
+- Prepare `Install dependencies`: `npm` `ci` `--omit=dev`
+- Serve `Start`: `npm` `start`
+
+## Deslop
+
+- Keep middleware order meaningful: proxy trust, health, static files, body
+  parsing, session, authentication, routers, 404, then one error handler.
+- Use `express.Router` modules over wrapper frameworks that rename Express
+  routing. On Express 5 let rejected promises reach the error handler instead
+  of repeating try/catch blocks; on Express 4 keep the app's existing pattern.
+- Preserve routes, response shapes, cookies, the module system and the
+  lockfile manager.

package/stacks/pieces/java.md

@@ -46,8 +46,7 @@ Java package, public type, dependency, lifecycle, and test conventions.
   connected source.
 - 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.
-  Spring Boot: set `server.address`/`server.port` from the supplied values and
-  `server.forward-headers-strategy=framework`.
+  For Spring Boot select `spring-boot`; its piece owns the framework traps.
 
 ## Connected development