@sidebase/base-config 0.2.0 → 0.2.1

package/dist/eslint/index.mjs

@@ -107,30 +107,27 @@ function buildEslintLayers(options) {
         imports: "always-multiline"
       }],
       "space-infix-ops": ["error"],
-      // `node/prefer-global/process` is NOT set here: antfu 7.4.3 registers
-      // eslint-plugin-n (`node`) only inside its own files-scoped object, so setting
-      // the rule in this plugin-less layer makes ESLint 10 ABORT. It is instead
-      // neutralized to `"off"` via `.override("antfu/node/rules")` in
-      // `createSidebaseEslint`, inside antfu's node-scoped object where the plugin
-      // is registered (see the comment there). The `no-restricted-properties`
-      // process.env ban below carries the real guard.
+      // `node/prefer-global/process` is deliberately not set here: antfu registers
+      // eslint-plugin-n only inside its own files-scoped object, so setting the rule in
+      // this plugin-less layer makes ESLint 10 abort. It is neutralized via
+      // `.override("antfu/node/rules")` in `createSidebaseEslint` instead. The
+      // `no-restricted-properties` process.env ban below carries the real guard.
       "no-unused-expressions": ["error"],
       "no-param-reassign": ["error"],
       "no-fallthrough": ["error"],
       "require-await": ["error"],
       "ts/no-non-null-assertion": ["error"],
-      // antfu leaves `ts/no-explicit-any` off; this baseline enforces it, matching the
-      // shipped `AGENTS.md` ban on `any`. Breaking for consumers (Q5, Option A).
+      // antfu leaves `ts/no-explicit-any` off. This baseline enforces it, matching the
+      // shipped `AGENTS.md` ban on `any`. Breaking for consumers on adoption.
       "ts/no-explicit-any": "error",
       // Type-aware rules antfu enables that this baseline turns off.
       "ts/no-misused-promises": "off",
       "ts/no-unsafe-call": "off",
       "ts/strict-boolean-expressions": "off",
       "ts/promise-function-async": "off",
-      // Newer antfu rules outside the established house baseline. `prefer-static-regex`
-      // is a perf nudge the consuming apps never adopted; `custom-event-name-casing`
-      // is actively wrong for naive-ui's kebab `update:*` v-model events. Off by
-      // default; a repo can opt back in via `.append()`.
+      // Newer antfu rules outside the house baseline. `prefer-static-regex` is a perf
+      // nudge the apps never adopted, and `custom-event-name-casing` is wrong for
+      // naive-ui's kebab `update:*` v-model events. Opt back in via `.append()`.
       "e18e/prefer-static-regex": "off",
       "vue/custom-event-name-casing": "off"
     }
@@ -141,17 +138,14 @@ function buildEslintLayers(options) {
   });
   configs.push({
     name: "sidebase/console",
-    // Source files only: antfu's markdown processor lints fenced code
-    // blocks as virtual `*.md/*` files, so an un-scoped `no-console` fires inside
-    // README/doc examples. This carve-out leaves real `.ts`/`.vue`/... enforcement intact.
+    // Source files only. antfu's markdown processor lints fenced code blocks as virtual
+    // `*.md/*` files, so an un-scoped `no-console` fires inside doc examples.
     ignores: ["**/*.md/**"],
     rules: {
-      // Always pass an explicit options object: a severity-only override would
-      // retain antfu's `{ allow: ["warn", "error"] }`. `"error"` (hard-ban)
-      // emits `{}` (no-console's schema rejects an empty `allow` array), which
-      // replaces those options so every `console.*` is banned. An empty
-      // allow-list was normalized to `"error"` in resolveEslintOptions, so the
-      // array branch here is always a non-empty allow-list (no cast needed).
+      // Always pass an explicit options object, or a severity-only override retains
+      // antfu's `{ allow: ["warn", "error"] }`. A hard ban emits `{}`, since no-console
+      // rejects an empty `allow` array. `resolveEslintOptions` already normalized an
+      // empty allow-list to `"error"`, so the array branch is always non-empty.
       "no-console": options.console === "error" ? ["error", {}] : ["error", { allow: options.console }]
     }
   });
@@ -229,48 +223,23 @@ function createSidebaseEslint(options = {}) {
   return antfu(
     {
       type: "app",
-      // `local.*` files and directories are personal, git-ignored scratch space
-      // and are never linted.
-      ignores: ["**/local.*", "**/local.*/**"],
-      // Org house style: 2-space indent, single quotes, Vue on,
-      // JSON/YAML linting off (handled elsewhere).
+      // Personal scratch space. Root-anchored so `src/path/local.ts` stays linted.
+      ignores: ["local.*", "local.*/**", "prisma/local.*", "prisma/local.*/**"],
+      // House style. JSON and YAML linting are handled elsewhere.
       stylistic: { indent: 2, quotes: "single" },
       vue: true,
       jsonc: false,
       yaml: false,
-      // Type-aware is gated behind `LINT_TYPEAWARE`; when on, point at the repo
-      // tsconfig and exclude the configured paths from the type-aware program.
+      // Gated behind `LINT_TYPEAWARE`. When on, point at the repo tsconfig and
+      // exclude the configured paths from the type-aware program.
       typescript: resolved.typeAware ? { tsconfigPath: "tsconfig.json", ignoresTypeAware: resolved.ignoresTypeAware } : true
     },
     ...buildEslintLayers(resolved)
   ).override("antfu/node/rules", {
-    // antfu 7.4.3's node layer defaults `node/prefer-global/process` to
-    // `["error", "never"]` (demands `require("process")`), which flags EVERY legit
-    // global `process` use in an ESM Nuxt app (env modules, server plugins, loggers).
-    // Leaving the rule unset is not enough: antfu's `never` then wins in consumer
-    // resolution. Neutralize it HERE, inside antfu's own node-scoped config where the
-    // `node` plugin IS registered; setting it in a plugin-less object makes ESLint 10
-    // abort. `"off"`, not `["error", "always"]`, because `"always"` would wrongly flag
-    // the generated Prisma client's `import * as process from 'node:process'`.
-    //
-    // Note what this does NOT mean. prefer-global is not merely redundant here:
-    // `["error", "always"]` would also close a real hole, because
-    // `no-restricted-properties` keys on the `process.env` MEMBER EXPRESSION, and any
-    // import that renames the binding erases the shape it matches. Measured against
-    // this factory, the property ban alone catches `process.env.X`,
-    // `const { env } = process`, and a default import still named `process`, but NOT
-    // `import { env }`, `import { env as e }`, `import * as proc`, or
-    // `import proc from "node:process"`. Those are closed at the import site instead,
-    // by the `node:process` / `process` entries in `paths` (see `importRestrictions` in
-    // rules.ts): narrower than flipping prefer-global, and free of the Prisma-client
-    // false positive.
-    //
-    // With `importNames: ["env", "default"]` that is now the COMPLETE set, not a sample.
-    // Every way to reach `process.env` is covered by one rule or the other: the member
-    // expression and an un-renamed default import at the USAGE site, and the named,
-    // renamed-named, namespace and renamed-default imports at the IMPORT site. The
-    // un-renamed default being caught at the usage site rather than by the import ban is
-    // the asymmetry that hid the renamed-default hole for two rounds of review.
+    // antfu's `"never"` default flags every legitimate global `process` use. Neutralize
+    // it here, inside antfu's node-scoped config: a plugin-less object aborts ESLint 10.
+    // `"off"` and not `"always"`, which would flag the generated Prisma client. The
+    // `process.env` hole is covered at the import site by `importRestrictions`.
     rules: { "node/prefer-global/process": "off" }
   });
 }

package/dist/prisma/index.d.mts

@@ -6,27 +6,12 @@ interface SchemaEngineDatasource {
     shadowDatabaseUrl?: string;
 }
 /**
- * Seed the three Prisma connection env vars with localhost dev defaults when UNSET.
- * This is a deliberate SIDE EFFECT on `env` (defaults to `process.env`). Necessary because
- * once a `prisma.config.ts` exists Prisma stops auto-loading `.env`, so a schema that
- * reads `env("DATABASE_URL")` / `env("DIRECT_DATABASE_URL")` would fail at rest.
+ * Seed the Prisma connection env vars with localhost dev defaults when unset.
+ * Deliberately mutates `env`: once a `prisma.config.ts` exists Prisma stops auto-loading
+ * `.env`, so a schema reading `env("DATABASE_URL")` would fail at rest.
  *
- * Call it (after `import "dotenv/config"`) in the config file so the Prisma CLI runs
- * with ZERO env; a real `.env`/shell value always wins. `buildPrismaConfig` then reads
- * the seeded env and derives its direct-connection + shadow datasource.
- *
- * TWO paths, not one:
- * - **Bare, or an explicit `DIRECT_DATABASE_URL`.** Seeds all three. Defaults:
- *   direct = local postgres, pooled = direct + `pgbouncer=1`, shadow = direct with a
- *   `/prisma-shadow` database.
- * - **A real `DATABASE_URL` and no direct URL.** Seeds ONLY `DIRECT_DATABASE_URL`,
- *   derived from the pooled URL, and returns early. No shadow is seeded on purpose:
- *   deriving one would name a `/prisma-shadow` database on the production host, which
- *   Prisma CREATEs and DROPs.
- *
- * An empty-string value counts as unset throughout; `docker-compose` produces `""` for an
- * undefined variable, and treating it as present is how the localhost default used to
- * reach production.
+ * Call it after `import "dotenv/config"`. A real value always wins, and an empty string
+ * counts as unset.
  */
 declare function applyPrismaDevEnv(env?: Record<string, string | undefined>): void;
 /**
@@ -35,13 +20,12 @@ declare function applyPrismaDevEnv(env?: Record<string, string | undefined>): vo
  */
 declare function stripPgbouncerParams(url: string): string;
 /**
- * Resolve the schema engine's datasource (Pattern B):
- * - direct URL = `DIRECT_DATABASE_URL`, else `DATABASE_URL` with pgbouncer params stripped;
- * - shadow DB = `SHADOW_DATABASE_URL` when present.
+ * Resolve the schema engine's datasource:
+ * - direct URL = `DIRECT_DATABASE_URL`, else `DATABASE_URL` with pooler params stripped
+ * - shadow DB = `SHADOW_DATABASE_URL` when present
  *
- * Returns `undefined` when neither a direct nor a pooled URL is set, so the
- * config falls back to the schema's own `datasource` block (e.g. during
- * `prisma generate` without a database).
+ * Returns `undefined` when neither is set, so the config falls back to the schema's own
+ * `datasource` block, e.g. during `prisma generate` without a database.
  */
 declare function resolveSchemaEngineDatasource(env: Record<string, string | undefined>): SchemaEngineDatasource | undefined;
 
@@ -54,8 +38,8 @@ interface BuildPrismaConfigOptions {
     typedSql?: boolean;
 }
 /**
- * Build the shared `@sidebase` Prisma config (Prisma 6.19 "Pattern B").
- * Wrap the result in `defineConfig`:
+ * Build the shared `@sidebase` Prisma config. Gives the schema engine a pooler-free
+ * direct connection. Prisma 7's config shape is not covered.
  *
  * ```ts
  * // prisma.config.ts
@@ -63,10 +47,6 @@ interface BuildPrismaConfigOptions {
  * import { buildPrismaConfig } from "@sidebase/base-config/prisma";
  * export default defineConfig(buildPrismaConfig({ views: true, typedSql: true }));
  * ```
- *
- * Reads `DATABASE_URL` / `DIRECT_DATABASE_URL` / `SHADOW_DATABASE_URL` (the
- * schema engine gets a pgbouncer-free direct connection). Prisma 7's changed
- * config shape is out of scope for v1.
  */
 declare function buildPrismaConfig(options?: BuildPrismaConfigOptions, env?: Record<string, string | undefined>): PrismaConfig;
 

package/dist/prisma/index.d.ts

@@ -6,27 +6,12 @@ interface SchemaEngineDatasource {
     shadowDatabaseUrl?: string;
 }
 /**
- * Seed the three Prisma connection env vars with localhost dev defaults when UNSET.
- * This is a deliberate SIDE EFFECT on `env` (defaults to `process.env`). Necessary because
- * once a `prisma.config.ts` exists Prisma stops auto-loading `.env`, so a schema that
- * reads `env("DATABASE_URL")` / `env("DIRECT_DATABASE_URL")` would fail at rest.
+ * Seed the Prisma connection env vars with localhost dev defaults when unset.
+ * Deliberately mutates `env`: once a `prisma.config.ts` exists Prisma stops auto-loading
+ * `.env`, so a schema reading `env("DATABASE_URL")` would fail at rest.
  *
- * Call it (after `import "dotenv/config"`) in the config file so the Prisma CLI runs
- * with ZERO env; a real `.env`/shell value always wins. `buildPrismaConfig` then reads
- * the seeded env and derives its direct-connection + shadow datasource.
- *
- * TWO paths, not one:
- * - **Bare, or an explicit `DIRECT_DATABASE_URL`.** Seeds all three. Defaults:
- *   direct = local postgres, pooled = direct + `pgbouncer=1`, shadow = direct with a
- *   `/prisma-shadow` database.
- * - **A real `DATABASE_URL` and no direct URL.** Seeds ONLY `DIRECT_DATABASE_URL`,
- *   derived from the pooled URL, and returns early. No shadow is seeded on purpose:
- *   deriving one would name a `/prisma-shadow` database on the production host, which
- *   Prisma CREATEs and DROPs.
- *
- * An empty-string value counts as unset throughout; `docker-compose` produces `""` for an
- * undefined variable, and treating it as present is how the localhost default used to
- * reach production.
+ * Call it after `import "dotenv/config"`. A real value always wins, and an empty string
+ * counts as unset.
  */
 declare function applyPrismaDevEnv(env?: Record<string, string | undefined>): void;
 /**
@@ -35,13 +20,12 @@ declare function applyPrismaDevEnv(env?: Record<string, string | undefined>): vo
  */
 declare function stripPgbouncerParams(url: string): string;
 /**
- * Resolve the schema engine's datasource (Pattern B):
- * - direct URL = `DIRECT_DATABASE_URL`, else `DATABASE_URL` with pgbouncer params stripped;
- * - shadow DB = `SHADOW_DATABASE_URL` when present.
+ * Resolve the schema engine's datasource:
+ * - direct URL = `DIRECT_DATABASE_URL`, else `DATABASE_URL` with pooler params stripped
+ * - shadow DB = `SHADOW_DATABASE_URL` when present
  *
- * Returns `undefined` when neither a direct nor a pooled URL is set, so the
- * config falls back to the schema's own `datasource` block (e.g. during
- * `prisma generate` without a database).
+ * Returns `undefined` when neither is set, so the config falls back to the schema's own
+ * `datasource` block, e.g. during `prisma generate` without a database.
  */
 declare function resolveSchemaEngineDatasource(env: Record<string, string | undefined>): SchemaEngineDatasource | undefined;
 
@@ -54,8 +38,8 @@ interface BuildPrismaConfigOptions {
     typedSql?: boolean;
 }
 /**
- * Build the shared `@sidebase` Prisma config (Prisma 6.19 "Pattern B").
- * Wrap the result in `defineConfig`:
+ * Build the shared `@sidebase` Prisma config. Gives the schema engine a pooler-free
+ * direct connection. Prisma 7's config shape is not covered.
  *
  * ```ts
  * // prisma.config.ts
@@ -63,10 +47,6 @@ interface BuildPrismaConfigOptions {
  * import { buildPrismaConfig } from "@sidebase/base-config/prisma";
  * export default defineConfig(buildPrismaConfig({ views: true, typedSql: true }));
  * ```
- *
- * Reads `DATABASE_URL` / `DIRECT_DATABASE_URL` / `SHADOW_DATABASE_URL` (the
- * schema engine gets a pgbouncer-free direct connection). Prisma 7's changed
- * config shape is out of scope for v1.
  */
 declare function buildPrismaConfig(options?: BuildPrismaConfigOptions, env?: Record<string, string | undefined>): PrismaConfig;
 

package/dist/shared/{base-config.CuUhyvQo.d.mts → base-config.BoberVUk.d.mts}

@@ -1,7 +1,4 @@
-/**
- * Options for the published ESLint factory (`@sidebase/base-config/eslint`).
- * Covers the per-repo variance found across the consuming repos.
- */
+/** Options for the published ESLint factory (`@sidebase/base-config/eslint`). */
 interface CreateSidebaseEslintOptions {
     /** Zod `.extend()/.merge()/.passthrough()` bans and/or `import * as z` enforcement. Default `"none"` (opt-in). */
     zod?: "full" | "import-style" | "none";
@@ -36,10 +33,9 @@ interface CreateSidebaseEslintOptions {
     testFilePattern?: string[];
 }
 /**
- * Runtime list of every {@link CreateSidebaseEslintOptions} key, for config
- * validation/iteration. The `satisfies Record<keyof ..., 0>` map makes this
- * exhaustive: adding a future option to the interface fails to compile until
- * the key is listed here too, so the validator allow-list can never drift.
+ * Runtime list of every {@link CreateSidebaseEslintOptions} key. The `satisfies` map
+ * keeps it exhaustive: a new option fails to compile until it is listed here, so the
+ * validator allow-list cannot drift.
  */
 declare const ESLINT_OPTION_KEYS: string[];
 

package/dist/shared/{base-config.CuUhyvQo.d.ts → base-config.BoberVUk.d.ts}

@@ -1,7 +1,4 @@
-/**
- * Options for the published ESLint factory (`@sidebase/base-config/eslint`).
- * Covers the per-repo variance found across the consuming repos.
- */
+/** Options for the published ESLint factory (`@sidebase/base-config/eslint`). */
 interface CreateSidebaseEslintOptions {
     /** Zod `.extend()/.merge()/.passthrough()` bans and/or `import * as z` enforcement. Default `"none"` (opt-in). */
     zod?: "full" | "import-style" | "none";
@@ -36,10 +33,9 @@ interface CreateSidebaseEslintOptions {
     testFilePattern?: string[];
 }
 /**
- * Runtime list of every {@link CreateSidebaseEslintOptions} key, for config
- * validation/iteration. The `satisfies Record<keyof ..., 0>` map makes this
- * exhaustive: adding a future option to the interface fails to compile until
- * the key is listed here too, so the validator allow-list can never drift.
+ * Runtime list of every {@link CreateSidebaseEslintOptions} key. The `satisfies` map
+ * keeps it exhaustive: a new option fails to compile until it is listed here, so the
+ * validator allow-list cannot drift.
  */
 declare const ESLINT_OPTION_KEYS: string[];
 

package/docs/migration.md

@@ -334,10 +334,10 @@ the managed file and is reverted on the next sync.
 warns you. `streamctl check` stays green, the file looks deliberate, and a package whose
 install scripts are blocked still installs.
 
-Be precise about the consequence, because it is narrower than it first appears. The usual
-suspects (`sharp`, `@tailwindcss/oxide`, `unrs-resolver`, `@parcel/watcher`) ship their
-native binary as a prebuilt optional dependency, so on a platform with a prebuild they keep
-working whether or not they are approved, cold install included. Verified across pnpm
+The consequence is narrower than it first appears. The usual suspects (`sharp`,
+`@tailwindcss/oxide`, `unrs-resolver`, `@parcel/watcher`) ship their native binary as a
+prebuilt optional dependency, so on a platform with a prebuild they keep working whether or
+not they are approved, cold install included. Verified across pnpm
 10.28.1, 10.29.1 and 10.29.3. Where the loss is real:
 
 - architectures with no prebuild, where the binary genuinely has to be compiled
@@ -546,13 +546,12 @@ too, so on first sync the payload appends its block to whatever your repository
 Your existing lines stay above it. Nothing is overwritten and nothing is reported.
 
 Most of the leftovers are harmless. Ignore patterns are additive, so a duplicated `node_modules`
-or `.env` above the block is genuinely inert -- it changes nothing about what the build context
-carries. Delete them anyway, for a reason that is not tidiness: the detector below is the only
-thing that will ever tell you a payload entry has started shadowing something of yours, and it
-is not a one-shot check. A future payload version can add an entry that collides with a line you
-kept above the block, and a file with leftover duplicates reads `AFFECTED` forever, so it can no
-longer distinguish that from the noise. Clearing them is what keeps the check able to answer next
-time.
+or `.env` above the block is inert; it changes nothing about what the build context carries.
+Delete them anyway, and not for tidiness. The detector below is the only thing that will ever
+tell you a payload entry has started shadowing something of yours, and it is not a one-shot
+check. A future payload version can add an entry that collides with a line you kept above the
+block. A file with leftover duplicates reads `AFFECTED` forever, so it can no longer distinguish
+that from the noise. Clearing them keeps the check able to answer next time.
 
 **The case that bites is a negation.** `.dockerignore` is last-match-wins, and the managed block
 is appended at the BOTTOM, so every payload entry beats anything you wrote above it. A repository
@@ -822,5 +821,5 @@ keeps its own command this way.
 
 Nothing here is destructive if you work on a branch. `sync` rewrites tracked files, so
 `git diff` shows everything it did and `git restore` undoes it. Keep the migration on its
-own branch and its own commit so that if the sync diff turns out to be larger than
-expected, reverting it is one operation rather than an archaeology exercise.
+own branch and its own commit, so that if the sync diff turns out to be larger than
+expected, reverting it is one operation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidebase/base-config",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Shared @sidebase base configuration for Nuxt repos: ESLint / Prisma / tsconfig factories on npm, plus the streamctl file-sync preset payload",
   "keywords": [
     "sidebase",

package/presets/base/AGENTS.md

@@ -10,6 +10,15 @@ follow. They are the same across every repo in the fleet.
 - Never commit secrets, credentials, or generated build artifacts.
 - Keep all code, comments and identifiers in English.
 
+## Comments & wording
+
+- Keep comments short. Say WHY the code is the way it is, not what it plainly does.
+- ASCII only: no em dash, en dash, arrow, ellipsis, curly quote, or emoji.
+- One idea per sentence. Cut filler openers ("It is worth noting") and inflated words
+  ("leverage", "utilize", "robust", "seamless").
+- Do not leave a comment describing an alternative you rejected, or internal ticket
+  shorthand a reader cannot resolve.
+
 ## Types & correctness
 
 - Use precise types; avoid `any` and unchecked casts. Parse and validate external input at the boundary instead of trusting it downstream.

package/presets/base/dockerignore

@@ -12,16 +12,15 @@ tests
 .env
 .env.*
 !.env.example
-# The build-stage COPY globs `.npmrc*`; keep token-bearing backups
-# (`.npmrc.local`, `.npmrc.bak`, ...) out of the build context. `.npmrc` itself
-# is intentionally allowed through.
+# The build stage globs `.npmrc*`, so keep token-bearing backups like
+# `.npmrc.local` out of the build context. `.npmrc` itself is allowed through.
 .npmrc.*
 .DS_Store
-# Local dev state written by `pnpm db` / `docker compose up`. `prisma/pglite-data`
-# is tens of MB; `prisma/local.postgres_data` is root-owned, which fails a rootless
-# `docker build` outright. Patterns are anchored to the context root here (unlike
-# .gitignore), so `**/local.*` is required to reach the nested paths.
+# Local dev state from `pnpm db` or `docker compose up`. `prisma/pglite-data` is
+# tens of MB, and root-owned `prisma/local.postgres_data` fails a rootless build.
+# Root-anchored so `src/path/local.ts` still reaches the build context.
 prisma/client
 prisma/pglite-data
 pgliteHealthz
-**/local.*
+local.*
+prisma/local.*

package/presets/base/github/workflows/streamctl-upgrade.yml

@@ -1,18 +1,11 @@
-# Managed by streamctl (full-own, render: automation-upgrade). OFF BY DEFAULT: this
-# file only lands when a repo sets `automation: { upgradePr: true }` in
-# streamctl.config.ts. See the payload README "Upgrade-PR workflow" for enabling.
+# Managed by streamctl. Off by default; lands only when a repo sets
+# `automation: { upgradePr: true }`. See the README section "Upgrade-PR workflow".
 #
-# TOKEN: the PR is opened with `secrets.STREAMCTL_PR_TOKEN` (a GitHub App
-# installation token or a machine-account PAT), NOT the default `GITHUB_TOKEN`.
-# A PR created with `GITHUB_TOKEN` does NOT trigger `pull_request` workflows, so
-# this repo's own `check` gate would never run on the bot's PR. The bot identity
-# for the fleet is still being decided; treat this file as inert and provide the
-# secret before enabling. No registry token is needed: the payload is public npm.
-# A repo with OTHER private dependencies must opt this file out
-# (`files: { ".github/workflows/streamctl-upgrade.yml": "off" }`) and wire its own auth.
+# Needs `secrets.STREAMCTL_PR_TOKEN`: a PR opened with `GITHUB_TOKEN` does not trigger
+# `pull_request` workflows, so the repo's own `check` gate would never run on it.
 #
-# Actions are pinned by full commit SHA (this workflow handles a token); the version
-# tag is in the trailing comment.
+# A repo with private dependencies must opt this file out and wire its own auth:
+# `files: { ".github/workflows/streamctl-upgrade.yml": "off" }`.
 name: streamctl upgrade
 
 on:
@@ -20,8 +13,8 @@ on:
     - cron: "0 6 * * 1" # Mondays 06:00 UTC
   workflow_dispatch:
 
-# Least privilege: every PR/issue write below uses STREAMCTL_PR_TOKEN, so the
-# default token only needs to read the repo for checkout.
+# Every PR and issue write below uses STREAMCTL_PR_TOKEN, so the default token
+# only needs to read the repo for checkout.
 permissions:
   contents: read
 
@@ -32,9 +25,8 @@ jobs:
   upgrade:
     runs-on: ubuntu-latest
     steps:
-      # A bot identity is REQUIRED for the PR (see the header). To mint an App token
-      # in-workflow instead of storing a PAT, uncomment and wire the App credentials,
-      # then use `${{ steps.bot.outputs.token }}` in place of STREAMCTL_PR_TOKEN below:
+      # To mint an App token in-workflow instead of storing a PAT, uncomment this
+      # and use `${{ steps.bot.outputs.token }}` in place of STREAMCTL_PR_TOKEN:
       #
       # - id: bot
       #   uses: actions/create-github-app-token@5d869da34e18e7287c1daad50e0b8ea0f506ce69 # v1.11.0
@@ -59,8 +51,7 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      # Exit codes drive the branch: 4 = an update is available (proceed); 0 = up to
-      # date (stop, no PR); 3 = the repo already has drift (open an issue, not a PR).
+      # Exit codes: 4 = update available, 0 = up to date, 3 = repo already drifted.
       - id: check
         name: Check for a payload update
         run: |
@@ -91,9 +82,8 @@ jobs:
           set -e
           cat streamctl-upgrade.json
 
-      # exit 2 = the chained sync hit conflicts and ROLLED BACK. Re-run bumping only the
-      # pin + devDependency (no sync) so the PR carries a reviewable diff a human then
-      # reconciles with `streamctl sync --interactive`.
+      # Exit 2 means the sync hit conflicts and rolled back. Bump only the pin and
+      # devDependency so the PR carries a diff a human reconciles interactively.
       - name: Prepare a plan-only bump (interactive sync required)
         if: ${{ steps.upgrade.outputs.code == '2' }}
         run: pnpm streamctl upgrade --no-install --json > streamctl-upgrade.json

package/presets/base/gitignore

@@ -11,9 +11,10 @@ pglite-debug.log
 prisma/*.db
 prisma/migrations/dev
 .DS_Store
-# streamctl local scratch dirs/files (e.g. local.concept) stay untracked.
-local.*
-local.*/
-# CLAUDE.md is managed by streamctl; a user-global gitignore that ignores the
-# filename everywhere would silently untrack it. Force-allow it here.
+# streamctl scratch. Root-anchored so `src/path/local.ts` stays tracked.
+/local.*
+/local.*/
+prisma/local.*
+# CLAUDE.md is managed by streamctl. A user-global gitignore matching the name
+# everywhere would silently untrack it, so force-allow it.
 !CLAUDE.md

package/presets/base/oxlintrc.json

@@ -3,8 +3,9 @@
     "browser": true
   },
   "ignorePatterns": [
-    "local.*",
-    "local.*/"
+    "/local.*",
+    "/local.*/",
+    "prisma/local.*"
   ],
   "plugins": [
     "unicorn",

package/presets/base/pnpm-workspace.yaml

@@ -1,22 +1,15 @@
-# Managed by streamctl (full-own, render: security). pnpm's own settings file.
+# Managed by streamctl. pnpm's own settings file.
 #
-# SUPPLY-CHAIN COOLDOWN: a version must have been published for ${MIN_RELEASE_AGE}
-# minutes before pnpm will resolve it, so a compromised release has time to be caught
-# and yanked before the fleet installs it. Requires pnpm >= 10.16 (baseline: 10.28.1);
-# it gates fresh resolution only, so `--frozen-lockfile` installs are unaffected.
-# `@sidebase/*` is exempt: the first-party scope (this payload + the streamctl CLI),
-# published by the org itself, so a payload release reaches the fleet the same day.
+# Cooldown: a version must be ${MIN_RELEASE_AGE} minutes old before pnpm resolves it,
+# giving a compromised release time to be yanked. Needs pnpm >= 10.16. Gates fresh
+# resolution only, so `--frozen-lockfile` is unaffected. `@sidebase/*` is exempt.
 #
-# `packages: []` is REQUIRED, not decorative: 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`.
-# A real monorepo owns this key itself, so opt the file out with
-# `files: { "pnpm-workspace.yaml": "off" }` in .streamctl/config.ts.
+# `packages: []` is required: pnpm otherwise defaults it to `**`, promoting every nested
+# package.json to a workspace project and breaking `--frozen-lockfile`. A monorepo should
+# opt out with `files: { "pnpm-workspace.yaml": "off" }`.
 #
-# `onlyBuiltDependencies` is the postinstall-script allowlist: everything else installs
-# with its lifecycle scripts blocked. The baseline covers what the fleet universally
-# needs; add extras via `pnpm: { onlyBuiltDependencies: [...] }` rather than running
-# `pnpm approve-builds` (which writes here and would be reverted on the next sync).
+# `onlyBuiltDependencies` allowlists postinstall scripts. Add extras through the `pnpm`
+# knob, not `pnpm approve-builds`, which writes here and is reverted on the next sync.
 packages: []
 minimumReleaseAge: ${MIN_RELEASE_AGE}
 minimumReleaseAgeExclude:

package/presets/config.template.ts

@@ -1,7 +1,7 @@
 import { defineNuxtBaseConfig } from '@sidebase/base-config'
 
-// Scaffolded by `streamctl init`. `defineNuxtBaseConfig` gives typed editor
-// inference for this payload's knobs; the CLI validates the file on every sync.
+// Scaffolded by `streamctl init`. `defineNuxtBaseConfig` types the knobs below.
+// The CLI validates this file on every sync.
 export default defineNuxtBaseConfig({
   package: '__PACKAGE__',
   base: '__BASE__',