@sidebase/base-config 0.2.2 → 0.3.1

package/README.md

@@ -1,237 +1,161 @@
 # @sidebase/base-config
 
-Shared `@sidebase` Nuxt configuration, delivered over two channels in one package:
+Shared setup for sidebase Nuxt 4 apps. [`@sidebase/streamctl`](https://github.com/sidebase/streamctl)
+syncs this package's config files (CI, Dockerfile, tsconfig, lint config, editor settings, ...) into your
+repo and keeps them up to date. The package also exports ESLint, Prisma and tsconfig helpers.
 
-- npm channel: the root export `@sidebase/base-config` plus the subpath exports
-  `@sidebase/base-config/config`, `@sidebase/base-config/eslint`,
-  `@sidebase/base-config/prisma`, and `@sidebase/base-config/tsconfig.base`.
-- file-sync channel: the bundled `presets/` payload read by the [`@sidebase/streamctl`](https://github.com/sidebase/streamctl) CLI.
+## Quick start
 
-## Install
-
-For the npm channel, install the package plus what the subpaths you use require:
+Requires Nuxt 4, Node >= 24.21 and pnpm.
 
 ```sh
-pnpm add -D @sidebase/base-config eslint jiti
+pnpm add -D @sidebase/streamctl
+pnpm streamctl init --package @sidebase/base-config
 ```
 
-`eslint` (`^10.5.0`) and `jiti` (`>= 2.2.0`) are what `/eslint` needs; jiti is only
-required because the config file is TypeScript. `prisma` and `@prisma/client` (`^6.19`)
-are optional peers, install them only if you use `/prisma`.
-
-**`jiti` is not a declared peer.** `peerDependencies` is `eslint`, `prisma` and
-`@prisma/client`. It is in the command above because `/eslint` genuinely needs it. Since
-nothing declares it, pnpm emits no missing-peer warning if you leave it out. This README is
-the only thing that will tell you. See Requirements below.
-
-For the file-sync channel, see Adopting below. The CLI wires the dependency itself.
-
-## Adopting
-
-The payload *is* the install: [`@sidebase/streamctl`](https://github.com/sidebase/streamctl)
-reads `presets/` straight from this package in a consuming repo's `node_modules`.
-
-```sh
-pnpm streamctl init --package @sidebase/base-config   # scaffold + first sync
-pnpm streamctl check                                  # CI drift gate
-pnpm streamctl upgrade --to <version>                 # move the pin forward
-```
-
-Neither package needs a registry token or private-registry setup: both target the public
-`@sidebase` scope on npm.
-
-Coming from `@sidestream-tech/nuxt-config`? That rename is a manual migration, not an
-upgrade: `streamctl upgrade` moves the version pin and never rewrites `package:`. Follow
-[`docs/migration.md`](docs/migration.md), and note that the step order is load-bearing.
-
-### Presets and profiles
-
-Two separate axes in `streamctl.config.ts`:
-
-- `base` is the preset, the set of managed files you get. `nuxt-app` names the repo
-  *type*: it ships a Dockerfile, a postgres/prisma CI pipeline, and PR-preview cleanup.
-- `profile` is the version baseline, the dependency pins reconciled into your
-  `package.json`. It names the framework and its major: `nuxt-4`.
-
-The major is in the profile name on purpose. Each profile carries its own
-`detect.majorIs`, so `init` picks the right one from your `package.json` and a future
-`nuxt-5` profile can sit alongside `nuxt-4` while repos migrate one at a time.
-
-`nuxt-4` is the only profile shipped today, so this payload is Nuxt 4 only. There is no
-`nuxt-3` profile and none is planned. Running `init` in a Nuxt 3 repo fails with
-"No version profile could be detected", because no profile's `detect.majorIs` matches the
-`nuxt` version in your `package.json`. Move the repo to Nuxt 4 before adopting.
+`init` adds `@sidebase/base-config`, writes `streamctl.config.ts`, and runs the first sync.
+Review the changes and commit them.
 
-A profile name must match a `versionProfiles` key in the preset chain. If it does not, the
-CLI fails with `CONFIG_INVALID`: `profile "..." is not declared in presets/manifest.json
-profiles[]`. `pnpm validate:presets` catches the same mismatch at build time, so a broken
-profile name cannot ship in the first place.
+Coming from `@sidestream-tech/nuxt-config`? Follow [`docs/migration.md`](docs/migration.md)
+instead.
 
-#### Reconciled `scripts.lint`
+## What you get
 
-The `nuxt-4` profile reconciles your `package.json` `scripts.lint` to
-`oxlint -c .oxlintrc.json --deny-warnings && eslint --max-warnings 0 .`, so the fleet
-runs `oxlint` (already pinned, with the shipped `.oxlintrc.json`) before ESLint.
+| File | Managed as | What it is |
+| ---- | ---------- | ---------- |
+| `.github/workflows/ci.yml` | owned | Lint, typecheck and build, plus optional test and e2e jobs |
+| `.github/workflows/pr-preview-cleanup.yml` | owned | Removes the `preview-deployed` label when `preview` is removed |
+| `.github/workflows/streamctl-upgrade.yml` | owned, opt-in | Weekly upgrade PRs (see [Upgrades](#upgrades)) |
+| `Dockerfile` | owned | Production image, runs `prisma migrate deploy` and then the server |
+| `tsconfig.json` | owned | Extends the shared strict base and Nuxt's generated config |
+| `pnpm-workspace.yaml` | owned | 7-day release cooldown and the install-script allowlist |
+| `.oxlintrc.json` | owned | oxlint rules, run before ESLint |
+| `AGENTS.md` | owned | Conventions for coding agents |
+| `.editorconfig`, `.gitignore`, `.dockerignore` | block | A marked block; the rest of the file is yours |
+| `.vscode/settings.json`, `.vscode/extensions.json` | merged | Only the keys the payload sets; your other keys stay |
+| `eslint.config.ts`, `prisma.config.ts` | scaffolded | Written once, then yours |
 
-Unlike a version pin, a script has no forward-version floor to protect it, because a
-script is not a semver, so this is a plain **overwrite**: every `sync` replaces whatever
-your `scripts.lint` currently is. A repo that wants its own (for example
-`... && LINT_TYPEAWARE=true eslint --max-warnings 0 .` to opt into type-aware linting)
-keeps it by excluding the key:
+- **owned:** streamctl writes the whole file. Local edits show up as drift in `check`.
+- **block:** only the region between the `BEGIN`/`END streamctl MANAGED BLOCK` markers is
+  managed.
 
-```ts
-export default {
-  // ...
-  versionSyncExclude: ["scripts.lint"],
-};
-```
-
-#### Overriding a managed file
-
-`.editorconfig` is **block**-managed: the payload owns a marked region, delimited by
-`# BEGIN streamctl MANAGED BLOCK editorconfig` / `# END ...`, and preserves everything
-outside it byte-for-byte. On first sync the managed block is appended to the end of your
-file. Because EditorConfig applies later matching sections over earlier ones, you keep a
-project override by placing it **below** the managed block:
+`sync` also updates `package.json`:
+- `engines`, `packageManager`, and the version ranges of nuxt, typescript, eslint, oxlint,
+  prisma, `@prisma/client`, jiti, json-sort-cli and vitest. A range is only raised, never
+  lowered.
+- `scripts.postinstall` (`nuxt prepare`) and `scripts.lint` (oxlint, then ESLint).
 
-```ini
-# BEGIN streamctl MANAGED BLOCK editorconfig
-[*]
-indent_size = 2
-# END streamctl MANAGED BLOCK editorconfig
+## Everyday use
 
-# your override wins because it comes after the managed block
-[*]
-indent_size = 4
+```sh
+pnpm streamctl sync      # apply the payload after changing the config
+pnpm streamctl check     # CI gate: fails when managed files drifted
+pnpm streamctl upgrade   # move to the latest payload version and re-sync
 ```
 
-That way the payload keeps updating its region on every sync while your `indent_size = 4`
-survives. (A section placed *above* the block would be overridden by the block's
-`indent_size = 2`, so keep overrides below the `END` marker.)
+`sync` stops on conflicts, e.g. a file you edited by hand. Resolve them with
+`pnpm streamctl sync --interactive`.
 
-**First-sync hazard.** If your repo already has an `.editorconfig`, the block writer appends
-without looking at what is there, so all of your existing content ends up *above* the block
-and therefore loses. `streamctl check` exits 0 either way, because the block strategy only
-inspects its own markers. This applies to a fresh `streamctl init` just as much as to a
-migration, and you have to fix it by hand once. Step 8 of
-[`docs/migration.md`](docs/migration.md) has the detector and the two-case fix.
+### Upgrades
 
-If you instead want to stop managing a file entirely, opt it out per-path:
+Upgrade by hand with `pnpm streamctl upgrade`, or let a weekly workflow open the PRs:
 
 ```ts
-files: { ".editorconfig": "off" },
+automation: { upgradePr: true },
 ```
 
-The cost of `off` is total: streamctl no longer touches that file, so **every future
-payload fix to it stops reaching your repo**, including new rules, security bumps, and
-format corrections. Prefer the block override above when you only need to change part of
-a file.
-
-## This repo's CLI dependency
+The workflow runs `streamctl check`, lint, typecheck, test and build before it opens the PR.
+Files that need manual work end up in a draft PR with instructions.
 
-The payload is validated and dogfooded against the CLI, so `@sidebase/streamctl` is a
-`devDependency` here, pinned to the published semver range.
-`validate:presets` imports the CLI's exported manifest schema and the e2e dry-run drives the
-real CLI binary, so both resolve `@sidebase/streamctl` from the registry.
+By default it uses `GITHUB_TOKEN`, which may not change `.github/workflows/**`, so
+workflow changes are left out of the PR. To include them, set
+`automation.allowWorkflowUpdates: true` and add a `STREAMCTL_PR_TOKEN` secret (a
+fine-grained PAT or GitHub App token with Contents, Pull requests and Workflows write).
+That token also makes the PR trigger your normal CI.
 
-This payload needs **streamctl >= 0.3.0**: its manifest declares `schemaVersion` 3 (the
-`fromDependency` placeholder behind the derived Prisma ARG), which a 0.2.x CLI rejects with
-`SCHEMA_UNSUPPORTED`. The root `streamctl.config.ts` location it documents arrived in
-0.2.0. See "Config location" below.
+## Configuration
 
-## Typed config
-
-The root export `@sidebase/base-config` and the subpath `@sidebase/base-config/config`
-are the same module. Both provide `defineNuxtBaseConfig` and the `NuxtBaseConfig` type,
-which is what makes a `streamctl.config.ts` typed. Every consuming repo has this file,
-and `streamctl init` scaffolds it importing from the root export:
+Everything is configured in `streamctl.config.ts`. `defineNuxtBaseConfig` gives you
+completion and type checking for every option:
 
 ```ts
-// streamctl.config.ts
 import { defineNuxtBaseConfig } from "@sidebase/base-config";
 
 export default defineNuxtBaseConfig({
   package: "@sidebase/base-config",
   base: "nuxt-app",
-  version: "0.1.0",
+  version: "0.3.0",
   profile: "nuxt-4",
-  ci: { unitTests: true },
+
+  ci: { unitTests: true, e2e: true },
+  docker: { aptPackages: ["ffmpeg"] },
+  automation: { upgradePr: true },
+  editor: { i18nSourceLanguage: "en" },
 });
 ```
 
-### Config location
-
-streamctl >= 0.2.0 reads `streamctl.config.ts` from the repo root, and `init` scaffolds it
-there. The older `.streamctl/config.ts` is still resolved, so an existing repo keeps working
-untouched and can move the file whenever it likes.
-
-Move it and nothing else changes: the contents are identical, and the CLI warns rather
-than guesses if both exist, naming the root file as the one it read. Keeping the legacy
-path is fine too. The one thing not to do is leave both in place, since only the root file
-is read and edits to the other will look like they do nothing.
-
-If you set `ignoresTypeAware` yourself, list whichever path your repo uses. The default
-covers both.
-
-`defineNuxtBaseConfig` returns the config unchanged. Its job is typed editor inference
-for this payload's knobs: completion and type checking on `ci`, `versions`, `docker`,
-`automation`, `security`, `pnpm`, `editor`, and the whole `eslint` option surface, plus `profile`
-narrowed to the profile names that actually exist. Without it the object is an untyped
-literal, so a typo such as `ci: { unitTest: true }` stays silent in your editor.
-
-The CLI shape-checks the config against the manifest when it loads it, so a sync still
-works without the helper. The helper is what moves that feedback into your editor.
+### Options
 
-Import `NuxtBaseConfig` directly when you need the type on its own:
+| Option | Default | Effect |
+| ------ | ------- | ------ |
+| `ci.unitTests` | `false` | Add a `test` job (`pnpm test`) |
+| `ci.e2e` | `false` | Add an `e2e` job with a postgres service |
+| `ci.aptPackages` | `[]` | apt packages for the `test`/`e2e` jobs and upgrade validation |
+| `docker.aptPackages` | `[]` | apt packages for the image, on top of `openssl` |
+| `docker.preInstall` | `""` | Dockerfile lines before `pnpm install` |
+| `docker.buildArgs` | `""` | Dockerfile lines before `COPY . .` |
+| `docker.buildSteps` | `nuxi prepare`, `prisma generate`, `build` | The build commands |
+| `docker.finalStage` | `""` | Dockerfile lines in the final stage, before `CMD` |
+| `docker.prismaRuntime` | copy schema, install Prisma CLI | Prisma setup in the final stage |
+| `docker.prismaVersion` | your `prisma` version | Prisma CLI version in the image |
+| `docker.startCommand` | `npm exec prisma migrate deploy && exec node ...` | The `CMD`, one line |
+| `versions.node` | `24.21.0` | Node in CI, the Dockerfile and the upgrade workflow |
+| `versions.pnpm` | `10.34.5` | pnpm in the Dockerfile (CI uses `packageManager`) |
+| `automation.upgradePr` | `false` | Add the weekly upgrade workflow |
+| `automation.allowWorkflowUpdates` | `false` | Include workflow changes in upgrade PRs (needs a token) |
+| `automation.prTokenSecret` | `"STREAMCTL_PR_TOKEN"` | Secret name for that token |
+| `automation.prepare` | `pnpm prisma generate` if Prisma is installed | Command run before validating an upgrade; `""` skips |
+| `security.minimumReleaseAge` | `"10080"` | Minutes a release must be public before pnpm installs it; `"0"` disables |
+| `pnpm.onlyBuiltDependencies` | `[]` | Extra packages allowed to run install scripts |
+| `editor.i18nSourceLanguage` | `"de"` | i18n-ally source language |
+
+Things to know:
+
+- **A `docker.*` text option replaces the default.** It does not append, so a `buildSteps`
+  override must list every build command you still need.
+- **`docker.prismaRuntime` and `docker.startCommand` go together.** Without Prisma, set
+  `prismaRuntime: ""` and a `startCommand` without `migrate deploy`, e.g.
+  `exec node .output/server/index.mjs`. Keep the `exec`, so node gets SIGTERM.
+- **Repos with English source strings must set `editor.i18nSourceLanguage: "en"`.**
+  Otherwise every sync writes `"de"` back.
+- **Adopting `pnpm-workspace.yaml` replaces your existing file**, including any
+  `onlyBuiltDependencies`. Move those entries to `pnpm.onlyBuiltDependencies` instead of
+  running `pnpm approve-builds`, which the next sync reverts.
+
+### Customizing managed files
+
+**Block files:** put your own settings below the `END` marker. For `.editorconfig`,
+later sections win, so an override below the block takes precedence. On the first sync,
+the block is appended *after* your existing content, so move that content below the
+block once.
+
+**Opt a file out** when the options are not enough:
 
 ```ts
-import type { NuxtBaseConfig } from "@sidebase/base-config/config";
+files: { "Dockerfile": "off" },
 ```
 
-## Shared tsconfig
+streamctl then leaves the file alone, including all future fixes to it.
 
-`@sidebase/base-config/tsconfig.base` is the shared strict TypeScript base, exported as a
-JSON file so a `tsconfig.json` can extend it by package name. The `nuxt-app` preset ships
-a managed `tsconfig.json` that chains it with Nuxt's generated config:
+**Keep your own `scripts.lint`** (or any other synced `package.json` field):
 
-```json
-{
-  "extends": [
-    "@sidebase/base-config/tsconfig.base",
-    "./.nuxt/tsconfig.json"
-  ]
-}
+```ts
+versionSyncExclude: ["scripts.lint"],
 ```
 
-Order matters: the shared base comes first, so Nuxt's generated config applies over it.
-
-## Naming convention
-
-Two rules cover every exported name, so you can predict them:
-
-- Types describing **this payload's config shape** are `NuxtBase*`: `NuxtBaseConfig`,
-  `NuxtBaseCiConfig`, `defineNuxtBaseConfig`, and the `NUXT_BASE_*_KEYS` lists. The prefix
-  is doing real work here, because these types describe the config of this specific
-  payload rather than anything generic.
-- **Everything else is domain-named with no package prefix**: `buildPrismaConfig`,
-  `applyPrismaDevEnv`, `createSidebaseEslint`, `resolveEslintOptions`. The import path
-  already states where a symbol comes from, so repeating it in the identifier adds
-  nothing.
-
-`streamctl` is reserved for the CLI (`@sidebase/streamctl`) and the files it owns:
-`streamctl.config.ts` in the repo root, and the legacy `.streamctl/` directory it still
-reads. Nothing exported from this package carries that name, because nothing
-exported from this package comes from the CLI. The ESLint layers this package builds are
-named `sidebase/*` (`sidebase/defaults`, `sidebase/console`, and so on), which is what you
-see in lint output and what you target if you `.override()` a layer by name. They are
-built at runtime by this package; the CLI never sees them.
-
-## ESLint factory
+## Helpers
 
-`@sidebase/base-config/eslint` exports `createSidebaseEslint(options?)`, which wraps
-[`@antfu/eslint-config`](https://github.com/antfu/eslint-config) (a dependency of this
-package, so **do not add `@antfu/eslint-config` directly**) and returns its
-`FlatConfigComposer`, so you chain `.append()` / `.override()` for local rules:
+### ESLint
 
 ```ts
 // eslint.config.ts
@@ -241,427 +165,82 @@ export default createSidebaseEslint({ zod: "full", trpcGuard: true })
   .append({ rules: { "vue/multi-word-component-names": "off" } });
 ```
 
-### Options
+Wraps [`@antfu/eslint-config`](https://github.com/antfu/eslint-config), which is a
+dependency of this package; don't install it yourself. Needs `eslint` and `jiti` (for the
+TypeScript config file) in your devDependencies; `sync` adds both.
 
 | Option | Default | Effect |
 | ------ | ------- | ------ |
-| `zod` | `"none"` | `"full"` = ban `.extend()/.merge()/.passthrough()` + enforce `import * as z`; `"import-style"` = import style only; `"none"` = off |
-| `console` | `"error"` | `"error"` bans all `console.*`; an array is the allow-list (e.g. `["warn", "error"]`) |
+| `zod` | `"none"` | `"import-style"`: enforce `import * as z`. `"full"`: also ban `.extend()`, `.merge()`, `.passthrough()` |
+| `console` | `"error"` | Ban all `console.*`, or pass allowed methods, e.g. `["warn", "error"]` |
 | `trpcGuard` | `false` | Ban `publicProcedure` in `server/trpc/routers/**` |
-| `prismaImportGuard` | `false` | Ban `~~/prisma/` client imports on the app side |
-| `typeDefStyle` | `"interface"` | `ts/consistent-type-definitions` |
-| `autoImportPaths` | `["utils/", "composables/", "~~/shared/types/"]` | Paths banned from direct import (Nuxt auto-imports) |
-| `autoImportTypeOnly` | `[]` | Subset of `autoImportPaths` where `import type { ... }` stays allowed (value imports still banned) |
-| `ignoresTypeAware` | `["prisma.config.ts", "eslint.config.ts", "streamctl.config.ts", ".streamctl/**/*.ts"]` | Files excluded from antfu's type-aware program (only relevant when type-aware). Covers both config locations, since `.streamctl/config.ts` stays supported after the root default lands |
-| `testFilePattern` | `["**/*.{test,spec}.{ts,tsx}", "**/*.stories.{ts,tsx}"]` | Test/spec/story globs where the `process.env` + auto-import bans are relaxed |
-
-Rare per-repo rules belong in your local `.append(...)`, not in the option surface.
+| `prismaImportGuard` | `false` | Ban `~~/prisma/` client imports outside server code |
+| `typeDefStyle` | `"interface"` | Prefer `interface` or `type` |
+| `autoImportPaths` | `["utils/", "composables/", "~~/shared/types/"]` | Paths Nuxt auto-imports, so direct imports are banned |
+| `autoImportTypeOnly` | `[]` | Of those, paths where `import type` stays allowed |
+| `ignoresTypeAware` | config files | Files excluded from type-aware linting |
+| `testFilePattern` | `*.test`, `*.spec`, `*.stories` | Files where the `process.env` and auto-import bans are off |
 
-### Rule IDs & inline suppression
+Type-aware linting is off by default; run with `LINT_TYPEAWARE=true` to enable it.
 
-The custom bans map to these ESLint rule IDs. Use the exact ID in an
-`// eslint-disable-next-line ...` directive to suppress one line:
+To silence a single line, use the rule ID:
 
 | Ban | Rule ID |
 | --- | ------- |
-| Direct `process.env` access, as a member expression (`process.env.X`, `const { env } = process`) | `no-restricted-properties` |
-| ANY import **or re-export** of `node:process` or `process` that can reach `env` (`import { env }`, `import { env as e }`, `import * as proc`, `import proc from "node:process"`, `export { env } from "node:process"`, `export * from "node:process"`) | `ts/no-restricted-imports` |
-| Auto-import path imports (`autoImportPaths`) | `ts/no-restricted-imports` |
-| App-side Prisma client import (`prismaImportGuard`) | `ts/no-restricted-imports` |
-| Zod named-`z` import style (`zod: "import-style"`/`"full"`) | `no-restricted-syntax` |
-| Zod `.extend()/.merge()/.passthrough()` (`zod: "full"`) | `no-restricted-syntax` |
-| `publicProcedure` in routers (`trpcGuard`) | `no-restricted-syntax` |
-
-"Re-export" is not a figure of speech: a barrel file doing `export * from "node:process"`
-reports, as do `export { env } from "node:process"` and `export { default as p } from
-"node:process"`. The one shape that does **not** report is a bare side-effect import with
-no bindings, `import "node:process"`. It cannot reach `env`, so there is nothing to ban.
-
-The `process.env` ban is enforced by **two** rules, and which one reports depends on the
-shape, so suppressing the wrong one fails twice over: the directive does not suppress
-anything, and ESLint additionally warns that it was unused.
-
-```
-// eslint-disable-next-line no-restricted-properties
-import { env } from 'node:process'
-
-1:1   warning  Unused eslint-disable directive (no problems were reported from 'no-restricted-properties')
-2:10  error    'env' import from 'node:process' is restricted...   ts/no-restricted-imports
-```
-
-### Requirements
-
-`eslint` is a peer dependency (`^10.5.0`), so consumers of `/eslint` must supply ESLint
-themselves. The peer range matches the version baseline, so `streamctl` version-sync
-keeps a repo's ESLint in step with what this package is tested against.
-
-Flat config only. To load a TypeScript `eslint.config.ts` on Node, consumers add
-`jiti` (`>= 2.2.0`) as a devDependency: ESLint has no native TS loader, and ESLint 10
-rejects jiti below 2.2.0. Writing `eslint.config.mjs` instead drops the jiti requirement
-entirely, as does running on Deno or Bun, which import TypeScript directly.
-
-#### Type-aware linting prerequisite
-
-Type-aware linting is gated behind `LINT_TYPEAWARE=true` (off by default), so this only
-matters on the opt-in and CI path. When type-aware lint is on, the Prisma client and Nuxt
-types must be generated **before** `lint` runs, otherwise type-aware rules fail on missing
-generated types. Ordering satisfies this, not a preflight check:
-
-- the managed `ci.yml` runs `prisma generate` (and `nuxi prepare`) before `pnpm lint`, and
-- `scripts.postinstall: "nuxt prepare"` regenerates Nuxt types on install.
-
-A standard `pnpm install` plus the managed CI ordering covers the prerequisite. No separate
-check runs.
-
-## Prisma factory
-
-`@sidebase/base-config/prisma` exports `buildPrismaConfig({ views?, typedSql? })`,
-which returns a Prisma 6.19 config object you wrap in `defineConfig`:
-
-```ts
-// prisma.config.ts
-import { defineConfig } from "prisma/config";
-import { buildPrismaConfig } from "@sidebase/base-config/prisma";
-
-export default defineConfig(buildPrismaConfig({ views: true, typedSql: true }));
-```
-
-It reads `DATABASE_URL` / `DIRECT_DATABASE_URL` / `SHADOW_DATABASE_URL` from the
-environment (Pattern B): the schema engine gets a pgbouncer-free direct
-connection: `DIRECT_DATABASE_URL` if set, otherwise `DATABASE_URL` with
-pooler-only query params (`pgbouncer`, `connection_limit`, and so on) stripped via `ufo`.
-`SHADOW_DATABASE_URL` is wired only when present; with no database URL the engine
-block is omitted so the schema's own `datasource` applies.
-
-| Option | Default | Effect |
-| ------ | ------- | ------ |
-| `views` | `false` | Configure the `views` feature (`prisma/views`) |
-| `typedSql` | `false` | Configure the `typedSql` preview feature (`prisma/sql`) |
-
-### `applyPrismaDevEnv`
+| `process.env.X` | `no-restricted-properties` |
+| `import { env } from "node:process"` and similar | `ts/no-restricted-imports` |
+| Auto-import paths, app-side Prisma client | `ts/no-restricted-imports` |
+| Zod import style and methods, `publicProcedure` | `no-restricted-syntax` |
 
-The same subpath exports `applyPrismaDevEnv(env?)`, the companion for local development.
-It seeds `DIRECT_DATABASE_URL`, `DATABASE_URL`, and `SHADOW_DATABASE_URL` with localhost
-defaults, but only when they are unset, so a real `.env` or shell value always wins. It
-writes to the environment record you pass and defaults to `process.env`, which is a
-deliberate side effect.
-
-You need it because once a `prisma.config.ts` exists, Prisma stops auto-loading `.env`.
-A schema that reads `env("DATABASE_URL")` then fails with no environment at all. Call it
-in the config file, after loading dotenv, and the Prisma CLI runs against local postgres
-with zero setup:
+### Prisma
 
 ```ts
 // prisma.config.ts
 import "dotenv/config";
-import { defineConfig } from "prisma/config";
 import { applyPrismaDevEnv, buildPrismaConfig } from "@sidebase/base-config/prisma";
+import { defineConfig } from "prisma/config";
 
-applyPrismaDevEnv();
-
-export default defineConfig(buildPrismaConfig());
-```
-
-`buildPrismaConfig` alone is enough wherever the connection variables are already set,
-which is every deployed environment and CI. Add `applyPrismaDevEnv` when you want
-`prisma migrate dev` and friends to work on a fresh checkout without a `.env` file. The
-defaults are direct = local postgres, pooled = the direct URL plus `pgbouncer=1`, and
-shadow = the direct URL on a `/prisma-shadow` database.
-
-The URL helpers never log a connection string and never put one in an error message, so a
-password cannot reach your terminal or CI output through them. Keep that property if you
-wrap them.
-
-`prisma` / `@prisma/client` are peer dependencies (`^6.19`).
-
-> Prisma 7 is out of scope for now. v7 changes the config shape (`env()` helper,
-> `directUrl` becomes `url`, no `package.json` prisma block); a `buildPrismaConfig` v7
-> variant is a deliberate later bump.
-
-## Supply-chain cooldown (`pnpm-workspace.yaml`)
-
-The base preset fully owns `pnpm-workspace.yaml`, pnpm's settings file. It ships two
-supply-chain controls, both on by default for every repo:
-
-```yaml
-packages: []
-minimumReleaseAge: 10080          # 7 days, in minutes
-minimumReleaseAgeExclude:
-  - "@sidebase/*"
-onlyBuiltDependencies:            # the postinstall-script allowlist
-  - "@prisma/client"
-  - "esbuild"
-  - "prisma"
-```
-
-`minimumReleaseAge` refuses to resolve a version until it has been published for
-7 days, so a compromised release has time to be caught and yanked before the fleet
-installs it. It needs pnpm 10.16 or newer and gates *fresh resolution only*, so
-`pnpm install --frozen-lockfile` replays the lockfile untouched and CI is unaffected.
-
-The pnpm baseline shipped to consumers is 10.28.1 (`presets/*/preset.json`). This repo's
-own `packageManager` pin tracks separately and is usually newer; the two are independent
-by design, not drift.
-
-Exclusions match **package names, not dependency trees**: an excluded package's own
-dependencies still face the cooldown, and pnpm resolves the newest *eligible* older
-version in range. Only when nothing in range is old enough does resolution fail, with
-a misleading `ERR_PNPM_NO_MATCHING_VERSION` ([pnpm#9998](https://github.com/pnpm/pnpm/issues/9998)).
-
-`@sidebase/*` is exempt: the first-party scope covering both this payload and the
-`streamctl` CLI, published by the org itself, so a payload release reaches the fleet
-the same day instead of waiting out its own cooldown.
-
-**`packages: []` is load-bearing.** pnpm defaults it to `**` whenever a
-`pnpm-workspace.yaml` exists, which would silently promote every nested `package.json`
-(test fixtures, examples) to a workspace project and break `--frozen-lockfile`.
-
-`onlyBuiltDependencies` is the install-script allowlist. Everything else installs
-with its lifecycle scripts blocked. Add extras through the config, **not** through
-`pnpm approve-builds` (which writes to the managed file and is reverted on the next
-sync):
-
-```ts
-export default {
-  // ...
-  security: { minimumReleaseAge: "10080" }, // minutes; "0" disables the cooldown
-  pnpm: { onlyBuiltDependencies: ["sharp"] }, // on top of the baked-in baseline
-};
-```
-
-| Option | Default | Effect |
-| ------ | ------- | ------ |
-| `security.minimumReleaseAge` | `"10080"` | Minutes a release must age before pnpm installs it. A string, because the manifest's `configKeys` has no number type, same as the `versions.*` pins. |
-| `pnpm.onlyBuiltDependencies` | `[]` | Extra packages allowed to run install scripts, appended below the baked-in baseline |
-
-Because the file is `full`-owned, a repo that already has a `pnpm-workspace.yaml`
-raises a one-time adoption conflict on the first sync; reconcile it with
-`streamctl sync --interactive`.
-
-**Adopting it discards your existing keys.** The rendered file is the payload's, so an
-existing `onlyBuiltDependencies` allowlist and `ignoredBuiltDependencies` are both replaced
-by the baked-in baseline, and **nothing warns about it**. Most affected packages ship a
-prebuilt native binary and keep working either way, so the practical breakage is limited to
-architectures with no prebuild and to postinstalls doing essential non-native work. Capture
-the old list before you adopt and re-add it via `pnpm.onlyBuiltDependencies` above. A repo
-that genuinely needs its own `packages:` list (a real monorepo) or its own exclude list
-should opt the file out entirely instead:
-
-```ts
-files: { "pnpm-workspace.yaml": "off" },
-```
-
-## CI knobs
-
-The `nuxt-app` preset ships a managed `.github/workflows/ci.yml`. Its `lint-typecheck` and
-`build` jobs always run; the rest is knobs:
-
-| Knob | Default | Effect |
-| ---- | ------- | ------ |
-| `ci.unitTests` | `false` | Add the `test` job (`pnpm test`) |
-| `ci.e2e` | `false` | Add the `e2e` job, with a health-checked postgres service |
-| `ci.aptPackages` | `[]` | System packages `apt-get`-installed in the `test` and `e2e` jobs |
-
-`ci.aptPackages` is the CI counterpart to `docker.aptPackages` below: extra system packages
-on top of what the runner image already carries, for a binary the suite needs and
-`ubuntu-latest` does not ship. The motivating case is `libxml2-utils`, for `xmllint`.
-
-It applies to the `test` and `e2e` jobs only, never `lint-typecheck` or `build`. The step
-installs directly after `checkout`, before `pnpm install`, so a package needed by an install
-lifecycle script is covered as well as one needed by the tests. Leave it unset and the step
-is skipped entirely: it renders with a guard on the value being non-empty, so the default
-costs a no-op step rather than an `apt-get` call.
-
-```ts
-export default {
-  // ...
-  ci: { unitTests: true, e2e: true, aptPackages: ["libxml2-utils"] },
-};
-```
-
-Package names only. Every element is rejected if it contains a shell metacharacter, and the
-joined string is then re-validated against the Debian package-name character set (lowercase,
-digits, `+`, `-`, `.`). Both checks exist because the rendered command deliberately leaves
-the value unquoted, which is how several packages word-split into one `apt-get` call.
-
-## Dockerfile knobs
-
-The `nuxt-app` preset ships a managed `Dockerfile`. Beyond `docker.aptPackages`
-(an `openssl`-plus allowlist), six `docker.*` knobs inject raw text at fixed
-positions so every fleet repo can express its own build without opting the file
-out:
-
-| Knob | Position | Default |
-| ---- | -------- | ------- |
-| `docker.preInstall` | build stage, before `pnpm install` | `""` |
-| `docker.buildArgs` | build stage, before `COPY . .` | `""` |
-| `docker.buildSteps` | the build-command block | `nuxi prepare` / `prisma generate` / `run build` |
-| `docker.finalStage` | final stage, before `CMD` | `""` |
-| `docker.prismaRuntime` | final stage | copy the schema + install the `migrate deploy` CLI |
-| `docker.startCommand` | inside `CMD` | `prisma migrate deploy` then the node server |
-
-A seventh knob is different in kind: a validated version, not raw text.
-
-| Knob | Position | Default |
-| ---- | -------- | ------- |
-| `docker.prismaVersion` | the `ARG PRISMA_VERSION=` default inside `docker.prismaRuntime` | derived from the repo's `prisma` pin (its range floor); the baseline only when no full `x.y.z` pin exists |
-
-It is pattern-checked (`x.y.z`, optional prerelease), so unlike the six raw-text
-knobs it cannot inject arbitrary Dockerfile content. `--build-arg PRISMA_VERSION=`
-still overrides at build time.
-
-```ts
-export default {
-  // ...
-  docker: {
-    preInstall: "COPY ./vendor ./vendor", // vendored dep needed at install time
-    buildSteps: "RUN pnpm nuxi prepare\nRUN pnpm run build", // a repo with no Prisma
-    prismaRuntime: "", // drop Prisma entirely
-    startCommand: "node .output/server/index.mjs",
-  },
-};
+applyPrismaDevEnv(); // optional: localhost defaults for unset DB URLs
+export default defineConfig(buildPrismaConfig({ views: true, typedSql: true }));
 ```
 
-> **These six values land verbatim.** They are `string`, not `string[]`, so order
-> is preserved (a sorted array would scramble ordered `RUN` steps), and no
-> shell-metacharacter check runs on them. The trust level is exactly that of
-> `files: { "Dockerfile": "off" }`, which any consumer can already set: whoever
-> can edit `streamctl.config.ts` can already replace the whole file. The
-> `.output` ownership stays FIXED outside every knob. The container itself runs
-> as **root**: a fixed `USER node` broke every deployment that overrides the image
-> CMD with a root-requiring command, so a repo that wants an unprivileged runtime
-> opts in with `docker.finalStage: "USER node"`.
-
-Setting a knob replaces its default outright, it does not append. So a `docker.buildSteps`
-override must restate every build command you still want, and `docker.prismaRuntime: ""`
-removes the Prisma runtime block entirely. The three knobs that default to real content
-(`buildSteps`, `prismaRuntime`, `startCommand`) are the ones where this matters; the other
-three default to `""`.
-
-**`prismaRuntime` and `startCommand` are coupled.** Override one and you must override the
-other. `prismaRuntime` is what installs the Prisma CLI into the final stage, and the
-DEFAULT `startCommand` is `npm exec prisma migrate deploy && node ...`. Setting only
-`prismaRuntime: ""` therefore produces an image whose `CMD` invokes a CLI that is no longer
-installed, and the container fails to start. The example above overrides both, which is why
-it is safe to copy; a single-knob change is not. Drop the `migrate deploy` half of
-`startCommand` at the same time.
-
-Global installs in `docker.preInstall` must use `npm i -g <tool>`, not
-`pnpm add -g`: the image sets no `PNPM_HOME`, so pnpm's global bin dir is
-undefined.
-
-## Editor settings (`.vscode/settings.json`)
-
-The base preset owns its own keys in `.vscode/settings.json` and leaves the rest of the file
-to the project. Among them is i18n-ally, configured for the fleet's standard setup:
-`@nuxtjs/i18n` with flat dotted keys under `i18n/locales`.
-
-Everything the payload does not write is yours and survives a sync untouched: your
-`editor.fontSize`, your `files.exclude`, any unrelated key at all. Six of those are named in
-the manifest as project-owned on top of that (`editor.fontSize`, `editor.rulers`,
-`editor.formatOnSave`, `files.exclude`, `search.exclude`, `files.watcherExclude`), which
-keeps them yours even if a later payload version starts setting them. Only the keys the
-payload writes are reverted, and they are the ones below.
-
-| Knob | Default | Effect |
-| ---- | ------- | ------ |
-| `editor.i18nSourceLanguage` | `"de"` | The locale i18n-ally translates FROM (`i18n-ally.sourceLanguage`). Payload-enforced; see below |
+- `buildPrismaConfig` reads `DATABASE_URL`, `DIRECT_DATABASE_URL` and `SHADOW_DATABASE_URL`.
+  Migrations use `DIRECT_DATABASE_URL`, or `DATABASE_URL` with the pooler parameters removed.
+  `views` and `typedSql` enable those Prisma features.
+- `applyPrismaDevEnv` sets localhost defaults for the URLs that are unset, so
+  `prisma migrate dev` works on a fresh checkout without a `.env`.
 
-```ts
-export default {
-  // ...
-  editor: { i18nSourceLanguage: "en" },
-};
-```
+Prisma 6.19 only; `prisma` and `@prisma/client` are optional peer dependencies.
 
-**If your repo authors its source strings in English, set this.** The source language is
-payload-owned, so leaving it unset does not mean "keep what I have". Every sync writes
-`"de"` into the file, over the top of an `"en"` you put there by hand. Nothing warns, and
-`streamctl check` stays green afterwards, because the value it finds is the value the payload
-intends. Setting the knob is the only thing that makes `"en"` survive a sync.
+### tsconfig
 
-`i18n-ally.localesPaths` and `i18n-ally.keystyle` are deliberately NOT configurable: the
-locales path and the flat key style are fleet-wide conventions, so they are enforced rather
-than offered. Editing either one in your own `.vscode/settings.json` is reverted on the next
-sync. A repo that genuinely needs a different layout should opt the file out
-(`files: { ".vscode/settings.json": "off" }`) rather than fight the merge.
+The managed `tsconfig.json` extends `@sidebase/base-config/tsconfig.base`, the shared
+strict config, before Nuxt's generated one. You can extend it directly as well.
 
-## Upgrade-PR workflow
+## Troubleshooting
 
-The base preset ships `.github/workflows/streamctl-upgrade.yml`, a scheduled workflow
-that opens a PR when a payload update is available. It is an `enabledBy`-gated managed
-file, off by default. It only lands once a repo opts in.
+- **`No version profile could be detected`:** the repo is not on Nuxt 4. Nuxt 3 is not
+  supported.
+- **`pnpm approve-builds` changes disappear:** use `pnpm.onlyBuiltDependencies`.
+- **`.editorconfig` settings ignored after the first sync:** your old content sits above the
+  managed block. Move it below.
+- **`eslint.config.ts` fails to load:** add `jiti` to devDependencies.
+- **Repo with private npm dependencies:** the upgrade workflow installs without registry
+  credentials. Opt it out and use your own.
 
-Enable it in `streamctl.config.ts`, then `streamctl sync`:
+## Developing this package
 
-```ts
-export default {
-  // ...
-  automation: {
-    upgradePr: true,
-    // allowWorkflowUpdates: true,
-    // prTokenSecret: "STREAMCTL_PR_TOKEN",
-  },
-  // optional: version pins, default to the payload's baseline. `node` feeds
-  // ci.yml + the Dockerfile; `pnpm` feeds the Dockerfile only (CI pins pnpm
-  // via package.json#packageManager):
-  // versions: { node: "24.13.0", pnpm: "10.28.1" },
-};
-```
-
-By default, the workflow uses `GITHUB_TOKEN` and omits changes under
-`.github/workflows/**`. If an update contains workflow changes, it opens a draft PR
-with every other safe change and lists the omitted files and completion commands.
-
-Set `automation.allowWorkflowUpdates` to `true` to include workflow changes. Add a
-`STREAMCTL_PR_TOKEN` repository secret with `Contents`, `Pull requests`, and
-`Workflows` write access. Change `automation.prTokenSecret` when the secret has another
-name. A fine-grained PAT or GitHub App token works. The built-in `GITHUB_TOKEN` cannot
-receive `Workflows` permission.
-
-| Knob | Default | Effect |
-| ---- | ------- | ------ |
-| `automation.upgradePr` | `false` | Sync the scheduled upgrade workflow |
-| `automation.allowWorkflowUpdates` | `false` | Include `.github/workflows/**` changes in upgrade PRs |
-| `automation.prTokenSecret` | `"STREAMCTL_PR_TOKEN"` | Secret used when workflow updates are enabled |
-
-The upgrade job runs `streamctl check` and every available lint, typecheck, test, and
-build script before opening a ready PR. PRs created with `GITHUB_TOKEN` do not trigger
-their own `pull_request` workflows, so these inline checks are required. The external
-token allows the new PR to trigger them normally.
-
-The workflow handles CLI results as follows:
-
-- `check` exit 0: stop without a PR.
-- `check` exit 3: open or update one drift issue.
-- `check` exit 4: attempt the upgrade.
-- `upgrade` exit 0: validate and open a ready PR, or a draft when workflow files were omitted.
-- `upgrade` exit 2: inspect conflicts using the pre-upgrade status.
-- Any other exit: fail the workflow.
-
-A conflict is safe to apply when the same path was previously `full` managed and
-`in-sync`. The workflow retries those generated replacements with `--force`. Any new,
-modified, malformed, or structurally conflicting path produces a draft PR instead.
-Workflow changes also produce a draft unless explicitly allowed. Drafts contain every
-safe change, keep conflicting and omitted workflow files at their current content, list
-what remains, and give the commands needed to finish the upgrade. When a malformed or
-structurally invalid file blocks `--force`, the draft only updates the payload version
-and lockfile.
-
-Diagnostic JSON stays under the runner's temporary directory. Upgrade branches include
-the target version, so a later release does not overwrite an older open PR.
-
-The payload is public npm. A repo with other private dependencies must opt this workflow
-out and provide its own install authentication.
-
-### Action pinning policy
-
-Every action in every managed workflow and CI job fragment is pinned by full commit SHA,
-with the version tag in a trailing comment. Moving tags can be re-pointed, so tags are
-never trusted, secrets or not. `test/workflow-pins.test.ts` sweeps all preset
-templates and fails on any `uses:` that is not a 40-hex SHA.
-
-The shipped pins track `actions/checkout` v6, `actions/setup-node` v6, and
-`pnpm/action-setup` v6. These majors run on the node24 action runtime, which needs a
-GitHub Actions runner `>= v2.327.1`. GitHub-hosted `ubuntu-latest` is far past that; only
-a repo that adds its own **self-hosted** runner needs to keep it above that floor.
+```sh
+pnpm lint && pnpm typecheck && pnpm test
+pnpm validate:presets   # manifests and cross-file invariants
+pnpm e2e:dry-run        # pack, install into a scratch consumer, sync and check
+pnpm e2e:docker         # build and start the rendered Dockerfile (needs Docker)
+```
+
+- The payload lives in `presets/` (`base`, and `nuxt-app` on top of it). The manifests in
+  `preset.json` define files, options and version baselines.
+- Tests check contracts derived from the manifests, so changing a preset file rarely needs
+  a test change.
+- Actions in managed workflows are pinned by commit SHA; the tests enforce it.
+- Requires streamctl >= 0.3.0 (manifest schema version 3).
+- Releases: [`docs/release.md`](docs/release.md). Agent conventions: [`AGENTS.md`](AGENTS.md).