@sidebase/base-config 0.1.0 → 0.2.1

package/dist/config.mjs

@@ -6,7 +6,8 @@ function knobKeys(shape) {
 }
 const NUXT_BASE_CI_KEYS = knobKeys({
   unitTests: 0,
-  e2e: 0
+  e2e: 0,
+  aptPackages: 0
 });
 const NUXT_BASE_VERSIONS_KEYS = knobKeys({
   node: 0,
@@ -19,6 +20,7 @@ const NUXT_BASE_DOCKER_KEYS = knobKeys({
   buildSteps: 0,
   finalStage: 0,
   prismaRuntime: 0,
+  prismaVersion: 0,
   startCommand: 0
 });
 const NUXT_BASE_AUTOMATION_KEYS = knobKeys({
@@ -30,6 +32,9 @@ const NUXT_BASE_SECURITY_KEYS = knobKeys({
 const NUXT_BASE_PNPM_KEYS = knobKeys({
   onlyBuiltDependencies: 0
 });
+const NUXT_BASE_EDITOR_KEYS = knobKeys({
+  i18nSourceLanguage: 0
+});
 const NUXT_BASE_TOP_LEVEL_KNOBS = knobKeys({
   eslint: 0
 });
@@ -40,7 +45,8 @@ const NUXT_BASE_CONFIG_KEYS = [
   ...NUXT_BASE_AUTOMATION_KEYS.map((key) => `automation.${key}`),
   ...NUXT_BASE_SECURITY_KEYS.map((key) => `security.${key}`),
   ...NUXT_BASE_PNPM_KEYS.map((key) => `pnpm.${key}`),
+  ...NUXT_BASE_EDITOR_KEYS.map((key) => `editor.${key}`),
   ...NUXT_BASE_TOP_LEVEL_KNOBS
 ];
 
-export { NUXT_BASE_AUTOMATION_KEYS, NUXT_BASE_CI_KEYS, NUXT_BASE_CONFIG_KEYS, NUXT_BASE_DOCKER_KEYS, NUXT_BASE_PNPM_KEYS, NUXT_BASE_SECURITY_KEYS, NUXT_BASE_VERSIONS_KEYS, defineNuxtBaseConfig };
+export { NUXT_BASE_AUTOMATION_KEYS, NUXT_BASE_CI_KEYS, NUXT_BASE_CONFIG_KEYS, NUXT_BASE_DOCKER_KEYS, NUXT_BASE_EDITOR_KEYS, NUXT_BASE_PNPM_KEYS, NUXT_BASE_SECURITY_KEYS, NUXT_BASE_VERSIONS_KEYS, defineNuxtBaseConfig };

package/dist/eslint/index.d.mts

@@ -1,5 +1,5 @@
-import { C as CreateSidebaseEslintOptions } from '../shared/base-config.CuUhyvQo.mjs';
-export { E as ESLINT_OPTION_KEYS } from '../shared/base-config.CuUhyvQo.mjs';
+import { C as CreateSidebaseEslintOptions } from '../shared/base-config.BoberVUk.mjs';
+export { E as ESLINT_OPTION_KEYS } from '../shared/base-config.BoberVUk.mjs';
 import antfu, { TypedFlatConfigItem } from '@antfu/eslint-config';
 
 /** {@link CreateSidebaseEslintOptions} with all defaults applied + the computed type-aware gate. */
@@ -20,10 +20,7 @@ interface ResolvedEslintOptions {
     testFilePattern: string[];
     typeAware: boolean;
 }
-/**
- * Whether type-aware linting is on: gated behind `LINT_TYPEAWARE=true` so the
- * slower type-aware pass stays opt-in (CI/local override).
- */
+/** Type-aware linting is gated behind `LINT_TYPEAWARE=true` because it is slow. */
 declare function isTypeAware(): boolean;
 /** Apply the documented option defaults and resolve the type-aware gate. */
 declare function resolveEslintOptions(options?: CreateSidebaseEslintOptions): ResolvedEslintOptions;

package/dist/eslint/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CreateSidebaseEslintOptions } from '../shared/base-config.CuUhyvQo.js';
-export { E as ESLINT_OPTION_KEYS } from '../shared/base-config.CuUhyvQo.js';
+import { C as CreateSidebaseEslintOptions } from '../shared/base-config.BoberVUk.js';
+export { E as ESLINT_OPTION_KEYS } from '../shared/base-config.BoberVUk.js';
 import antfu, { TypedFlatConfigItem } from '@antfu/eslint-config';
 
 /** {@link CreateSidebaseEslintOptions} with all defaults applied + the computed type-aware gate. */
@@ -20,10 +20,7 @@ interface ResolvedEslintOptions {
     testFilePattern: string[];
     typeAware: boolean;
 }
-/**
- * Whether type-aware linting is on: gated behind `LINT_TYPEAWARE=true` so the
- * slower type-aware pass stays opt-in (CI/local override).
- */
+/** Type-aware linting is gated behind `LINT_TYPEAWARE=true` because it is slow. */
 declare function isTypeAware(): boolean;
 /** Apply the documented option defaults and resolve the type-aware gate. */
 declare function resolveEslintOptions(options?: CreateSidebaseEslintOptions): ResolvedEslintOptions;

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

@@ -35,11 +35,12 @@ order, so the second one is the binding constraint:
 The widening came after the guard, so **a build containing the widening also contains the
 guard, and the widening is the effective minimum.** Requiring it is sufficient.
 
-> **Minimum version: `0.2.0`.**
-> That release carries both prerequisites above, and one more that binds harder: it reads
-> `streamctl.config.ts` from the repo root, which is the layout this payload's fixtures,
-> docs, and `ignoresTypeAware` default all assume. `0.1.0` already has the widening, so on
-> that build the payload loads — it just cannot find a root config file.
+> **Minimum version: `0.3.0`.**
+> The binding constraint is the payload manifest's `schemaVersion: 3` (the
+> `PRISMA_VERSION_DEFAULT` placeholder uses `fromDependency`, a schema-3 feature): a 0.2.x
+> CLI rejects the whole payload with `SCHEMA_UNSUPPORTED` ("Upgrade the CLI or the
+> payload"). 0.2.0's own prerequisites (both above, plus reading `streamctl.config.ts`
+> from the repo root) are of course included.
 
 ### Verify your CLI has both, without needing the version number
 
@@ -170,7 +171,7 @@ harder to tell which change caused what.
 Do this BEFORE touching the config.
 
 ```sh
-pnpm add -D @sidebase/streamctl@^0.2.0
+pnpm add -D @sidebase/streamctl@^0.3.0
 ```
 
 ### 3. Swap the payload package
@@ -333,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
@@ -356,14 +357,13 @@ pnpm install
 migrating from `@sidestream-tech/nuxt-config` it reports something like:
 
 ```
-  [!]  adoption (4)  pre-existing file(s) streamctl now manages
+  [!]  adoption (3)  pre-existing file(s) streamctl now manages
       tsconfig.json - pre-existing file streamctl now manages; adopting is expected
-      .dockerignore - pre-existing file streamctl now manages; adopting is expected
       pnpm-workspace.yaml - pre-existing file streamctl now manages; adopting is expected
       Dockerfile - pre-existing file streamctl now manages; adopting is expected
       -> `sync --interactive` to adopt per file, `sync --force` to take ownership, or `--only <glob>` to scope
 
-4 conflict(s) pending; see the per-kind guidance above.
+3 conflict(s) pending; see the per-kind guidance above.
 ```
 
 This is not a failure and it is not something to route around. A fully-managed file whose
@@ -539,6 +539,67 @@ strategy only inspects its own markers, and the block is present and correct; an
 outside it is invisible to the check. That is why this is a manual step rather than
 something drift detection reports.
 
+### 8b. Reconcile `.dockerignore` by hand
+
+**Same cause as step 8, and equally not migration-specific.** `.dockerignore` is block-managed
+too, so on first sync the payload appends its block to whatever your repository already had.
+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 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
+that deliberately un-ignored something now silently loses that:
+
+```
+!tests               <- yours, above the block. Now dead.
+
+# BEGIN streamctl MANAGED BLOCK dockerignore
+...
+tests                <- payload's, below yours. Wins.
+# END streamctl MANAGED BLOCK dockerignore
+```
+
+The build context stops carrying `tests/`, and the failure surfaces later and somewhere else --
+as a `COPY` that lands nothing, or an in-image test run that cannot find its fixtures. The build
+itself succeeds.
+
+Check what sits above the block:
+
+```sh
+awk '/# BEGIN streamctl MANAGED BLOCK dockerignore/{exit} {print}' .dockerignore \
+  | command grep -qv '^[[:space:]]*\(#.*\)\?$' && echo AFFECTED || echo clean
+```
+
+As in step 8, use `command grep` -- the detector reads its exit code as its entire answer, and a
+wrapped `grep` can report `clean` on an affected file.
+
+`AFFECTED` does not mean something broke; it means read those lines and decide. Anything you
+actually need, and every negation without exception, moves **below** the `# END` marker, which is
+the supported extension point:
+
+```
+# END streamctl MANAGED BLOCK dockerignore
+
+!tests
+my-project-specific-dir
+```
+
+Finish by re-running the `AFFECTED`/`clean` detector above; it only says `clean` once nothing but
+comments and blank lines is left above the block, so clear the harmless duplicates out too rather
+than keeping a detector that can never go green.
+
+**`streamctl check` will never flag any of this.** Block drift detection inspects only the marker
+region, so the block is present and correct and the check exits 0 while your dead negation sits
+three lines above it, permanently. This is the one step here that no tooling will ever remind you
+to do.
+
 ### 9. Clean up what the payload no longer manages
 
 Two different kinds of leftover, with the same cause: streamctl manages by path, so
@@ -760,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.1.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",
@@ -52,6 +52,16 @@
   "engines": {
     "node": ">=22"
   },
+  "packageManager": "pnpm@10.29.1",
+  "scripts": {
+    "build": "unbuild",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "validate:presets": "node scripts/validate-presets.mjs",
+    "e2e:dry-run": "pnpm build && node scripts/e2e-dry-run.mjs",
+    "prepack": "pnpm build"
+  },
   "dependencies": {
     "@antfu/eslint-config": "^7.4",
     "ufo": "^1.6.4"
@@ -72,7 +82,7 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@prisma/client": "^6.19.3",
-    "@sidebase/streamctl": "^0.2.0",
+    "@sidebase/streamctl": "^0.3.0",
     "@types/node": "^24.0.0",
     "eslint": "^10.5.0",
     "jiti": "^2.7.0",
@@ -82,13 +92,5 @@
     "unbuild": "^3.5.0",
     "vitest": "^3.0.0",
     "yaml": "^2.9.0"
-  },
-  "scripts": {
-    "build": "unbuild",
-    "typecheck": "tsc --noEmit -p tsconfig.json && tsc -p tsconfig.test.json",
-    "test": "vitest run",
-    "lint": "eslint .",
-    "validate:presets": "node scripts/validate-presets.mjs",
-    "e2e:dry-run": "pnpm build && node scripts/e2e-dry-run.mjs"
   }
-}
+}

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

@@ -6,13 +6,21 @@ npm-debug*
 .output
 .data
 dist
+test
 tests
 *.log
 .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 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.*
+prisma/local.*