create-basalt 1.4.2 → 1.6.0

package/dist/latest-versions.js

@@ -0,0 +1,293 @@
+/**
+ * Scaffold-time dependency resolution: a freshly generated app should depend on
+ * the LATEST PUBLISHED version of every package, not on the ranges that were
+ * current the day this create-basalt release was built.
+ *
+ * - `@basaltkit/*` packages always take the registry's `latest` dist-tag — the
+ *   framework's own release line is the whole point of the scaffold.
+ * - Third-party packages take `latest` only while it stays on the major the
+ *   templates are written for (the major of the fallback range in
+ *   {@link THIRD_PARTY_VERSIONS}). A new breaking major keeps the fallback range
+ *   and is reported as a notice, so it can never silently produce a broken app.
+ * - Third-party packages also respect pnpm's `minimumReleaseAge` (pnpm 11
+ *   defaults it to one day): `^<latest>` for a version published minutes ago is
+ *   UNSATISFIABLE under that policy, so the first `pnpm install` would fail. A
+ *   cheap `HEAD <registry>/<name>` reads the packument's `last-modified` (which
+ *   is never older than the latest publish): older than the window proves the
+ *   latest mature and `^<latest>` is written; newer — or no header / a failed
+ *   probe — keeps the fallback range, from which pnpm picks the newest MATURE
+ *   version itself. The full packument (the only per-version `time` source) is
+ *   megabytes for packages like `@types/node`, so it is never fetched; a
+ *   false "fresh" only costs a lower range floor. `@basaltkit/*` is never
+ *   probed: the scaffolded pnpm-workspace.yaml excludes that scope.
+ * - Any registry failure (offline, timeout, non-2xx, malformed JSON, a bogus
+ *   version string) keeps the embedded fallback range. The registry never fails
+ *   a scaffold.
+ */
+/**
+ * Fallback ranges for every third-party package the templates emit (API +
+ * web UI). The major of each range is also the TEMPLATE-COMPATIBLE major: the
+ * generated code is written for it, and `latest` is accepted only on that
+ * major. Bump a range to a new major only together with the templates.
+ */
+export const THIRD_PARTY_VERSIONS = {
+    '@tailwindcss/vite': '^4.3.3',
+    '@types/node': '^26.6.2',
+    '@types/react': '^19.3.0',
+    '@types/react-dom': '^19.3.0',
+    '@vitejs/plugin-react': '^6.1.1',
+    'pino-pretty': '^13.1.3',
+    react: '^19.3.0',
+    'react-dom': '^19.3.0',
+    tailwindcss: '^4.3.3',
+    tsx: '^4.23.13',
+    typescript: '^7.0.2',
+    vite: '^8.3.0',
+    vitest: '^5.0.1',
+    zod: '^4.6.5',
+};
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+/** pnpm 11's default `minimumReleaseAge`, in minutes (one day). */
+export const DEFAULT_MINIMUM_RELEASE_AGE_MINUTES = 1440;
+const ABBREVIATED_METADATA = 'application/vnd.npm.install-v1+json';
+const PER_REQUEST_TIMEOUT_MS = 5_000;
+const OVERALL_TIMEOUT_MS = 15_000;
+/**
+ * Requests in flight at once. A burst of ~35 simultaneous TLS handshakes to one
+ * host is markedly slower (and flakier) on poor links than a small pool that
+ * reuses keep-alive connections.
+ */
+const CONCURRENCY = 8;
+/** A stable `x.y.z` release (pre-releases and build metadata are refused). */
+const STABLE_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const CARET_RANGE = /^\^(0|[1-9]\d*)\.\d+\.\d+$/;
+/** Packages whose latest is always taken, regardless of major. */
+export const alwaysLatest = (name) => name.startsWith('@basaltkit/') || name === 'create-basalt';
+/** The major the templates are written for, derived from the fallback range. */
+export function compatibleMajor(fallbackRange) {
+    const match = CARET_RANGE.exec(fallbackRange);
+    return match ? Number(match[1]) : undefined;
+}
+/**
+ * The release-age window in minutes: an explicit option, else the pnpm/npm
+ * config env var (a `pnpm create` exports its config), else pnpm 11's default.
+ */
+export function minimumReleaseAgeMinutes(explicit, env = process.env) {
+    if (explicit !== undefined && Number.isFinite(explicit) && explicit >= 0)
+        return explicit;
+    for (const key of ['pnpm_config_minimum_release_age', 'npm_config_minimum_release_age']) {
+        const raw = env[key];
+        if (raw !== undefined && /^\d+$/.test(raw.trim()))
+            return Number(raw.trim());
+    }
+    return DEFAULT_MINIMUM_RELEASE_AGE_MINUTES;
+}
+/**
+ * The registry to query: an explicit option, else `npm_config_registry` (npm
+ * and pnpm export it to `create` binaries, so a private mirror is honored),
+ * else the public registry. Trailing slashes are normalized; anything that is
+ * not an http(s) URL falls back to the default.
+ */
+export function registryUrl(explicit, env = process.env) {
+    const candidate = explicit ?? env['npm_config_registry'] ?? env['NPM_CONFIG_REGISTRY'];
+    if (!candidate)
+        return DEFAULT_REGISTRY;
+    try {
+        const url = new URL(candidate);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return DEFAULT_REGISTRY;
+    }
+    catch {
+        return DEFAULT_REGISTRY;
+    }
+    let end = candidate.length;
+    while (end > 0 && candidate[end - 1] === '/')
+        end--;
+    return candidate.slice(0, end);
+}
+/** `<registry>/<name>/latest`, with a scoped name's `/` encoded as `%2f`. */
+export const latestUrl = (registry, name) => `${registry}/${name.replaceAll('/', '%2f')}/latest`;
+/** `<registry>/<name>` — the packument (probed with HEAD for its `last-modified`). */
+export const packumentUrl = (registry, name) => `${registry}/${name.replaceAll('/', '%2f')}`;
+/**
+ * Whether `name`'s latest is provably older than `windowMs`. A packument's
+ * `last-modified` is never older than its latest publish, so an old header
+ * proves maturity. Age is measured against the registry's own `Date` header
+ * when present (immune to local clock skew). Never throws.
+ */
+async function probeAge(fetchImpl, registry, name, windowMs, now, signal) {
+    try {
+        const response = await fetchImpl(packumentUrl(registry, name), {
+            method: 'HEAD',
+            headers: { accept: ABBREVIATED_METADATA },
+            signal,
+        });
+        if (!response.ok)
+            return 'unknown';
+        const modified = Date.parse(response.headers.get('last-modified') ?? '');
+        if (Number.isNaN(modified))
+            return 'unknown';
+        const serverNow = Date.parse(response.headers.get('date') ?? '');
+        const reference = Number.isNaN(serverNow) ? now() : serverNow;
+        return reference - modified >= windowMs ? 'mature' : 'recent';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+async function lookupLatest(fetchImpl, registry, name, signal) {
+    try {
+        const response = await fetchImpl(latestUrl(registry, name), {
+            headers: { accept: 'application/json' },
+            signal,
+        });
+        if (response.status >= 500 || response.status === 429)
+            return 'transient';
+        if (!response.ok)
+            return 'miss';
+        const body = (await response.json());
+        const version = body?.version;
+        return typeof version === 'string' && STABLE_SEMVER.test(version) ? { version } : 'miss';
+    }
+    catch {
+        // Network error, per-request timeout, or malformed JSON.
+        return 'transient';
+    }
+}
+/**
+ * The latest stable version of `name`, or undefined. A transient failure
+ * (network error, timeout, 5xx/429) is retried once — on slow links the first
+ * wave of cold TLS handshakes is the part that times out, and the retry rides
+ * a warm keep-alive connection. The overall signal bounds both attempts.
+ */
+async function fetchLatest(fetchImpl, registry, name, timeoutMs, overall) {
+    for (let attempt = 0; attempt < 2 && !overall.aborted; attempt++) {
+        const result = await lookupLatest(fetchImpl, registry, name, AbortSignal.any([AbortSignal.timeout(timeoutMs), overall]));
+        if (result === 'miss')
+            return undefined;
+        if (result !== 'transient')
+            return result.version;
+    }
+    return undefined;
+}
+/**
+ * Resolves the latest published version of every package in `fallbacks`
+ * (name → fallback range) through a small pool of parallel requests. Never throws: a package the registry
+ * cannot answer for keeps its fallback range and is listed in `failed`.
+ */
+export async function resolveLatestVersions(fallbacks, options = {}) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const registry = registryUrl(options.registry);
+    const versions = { ...fallbacks };
+    const resolved = [];
+    const failed = [];
+    const heldBack = [];
+    const tooFresh = [];
+    const names = Object.keys(fallbacks).sort();
+    const windowMs = minimumReleaseAgeMinutes(options.minimumReleaseAge) * 60_000;
+    const now = options.now ?? Date.now;
+    const timeoutMs = options.timeoutMs ?? PER_REQUEST_TIMEOUT_MS;
+    if (typeof fetchImpl !== 'function') {
+        return { versions, resolved, failed: names, heldBack, tooFresh, registry };
+    }
+    /** A third-party latest on the template-compatible major (else undefined). */
+    const compatible = (name, version) => {
+        if (alwaysLatest(name))
+            return true;
+        const major = compatibleMajor(fallbacks[name]);
+        return major !== undefined && Number(version.split('.')[0]) === major;
+    };
+    const overall = new AbortController();
+    const cap = setTimeout(() => overall.abort(), options.overallTimeoutMs ?? OVERALL_TIMEOUT_MS);
+    try {
+        const latest = [];
+        const age = [];
+        let next = 0;
+        const worker = async () => {
+            while (next < names.length) {
+                const i = next++;
+                const name = names[i];
+                const version = await fetchLatest(fetchImpl, registry, name, timeoutMs, overall.signal);
+                latest[i] = version;
+                age[i] =
+                    version === undefined || alwaysLatest(name) || windowMs === 0 || !compatible(name, version)
+                        ? 'mature'
+                        : await probeAge(fetchImpl, registry, name, windowMs, now, AbortSignal.any([AbortSignal.timeout(timeoutMs), overall.signal]));
+            }
+        };
+        const pool = Math.max(1, Math.min(options.concurrency ?? CONCURRENCY, names.length));
+        await Promise.all(Array.from({ length: pool }, worker));
+        names.forEach((name, i) => {
+            const version = latest[i];
+            const fallback = fallbacks[name];
+            if (version === undefined) {
+                failed.push(name);
+                return;
+            }
+            if (!compatible(name, version)) {
+                heldBack.push({ name, latest: version, range: fallback });
+                return;
+            }
+            const verdict = age[i];
+            if (verdict === 'recent' || verdict === 'unknown') {
+                tooFresh.push({ name, latest: version, range: fallback, reason: verdict });
+                return;
+            }
+            versions[name] = `^${version}`;
+            resolved.push(name);
+        });
+    }
+    finally {
+        clearTimeout(cap);
+    }
+    return { versions, resolved, failed, heldBack, tooFresh, registry };
+}
+/**
+ * Rewrites the dependency ranges of a generated package.json with the
+ * resolved versions (keys, order and every other field untouched).
+ */
+export function applyVersions(packageJsonText, versions) {
+    const pkg = JSON.parse(packageJsonText);
+    for (const field of ['dependencies', 'devDependencies']) {
+        const deps = pkg[field];
+        if (!deps)
+            continue;
+        for (const name of Object.keys(deps)) {
+            const range = versions[name];
+            if (range !== undefined)
+                deps[name] = range;
+        }
+    }
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+/** Every dependency/devDependency name → range declared in the given package.json texts. */
+export function collectDependencies(packageJsonTexts) {
+    const all = {};
+    for (const text of packageJsonTexts) {
+        const pkg = JSON.parse(text);
+        Object.assign(all, pkg.dependencies, pkg.devDependencies);
+    }
+    return all;
+}
+/** Human-readable lines summarizing a resolution (for the CLI). */
+export function describeResolution(resolution) {
+    const lines = [];
+    if (resolution.resolved.length > 0) {
+        lines.push(`Resolved ${resolution.resolved.length} dependencies to their latest published versions:`, `  ${resolution.resolved.map((name) => `${name}@${resolution.versions[name]}`).join(', ')}`);
+    }
+    for (const held of resolution.heldBack) {
+        lines.push(`Note: ${held.name} ${held.latest} is a new major this template does not target yet — kept ${held.range}.`);
+    }
+    const recent = resolution.tooFresh.filter((entry) => entry.reason === 'recent');
+    const unknown = resolution.tooFresh.filter((entry) => entry.reason === 'unknown');
+    for (const fresh of recent) {
+        lines.push(`Note: ${fresh.name} ${fresh.latest} was published inside pnpm's minimumReleaseAge window — kept ${fresh.range} (pnpm installs the newest mature version).`);
+    }
+    if (unknown.length > 0) {
+        lines.push(`Note: could not prove the release age of ${unknown.map((entry) => `${entry.name}@${entry.latest}`).join(', ')} — kept the bundled range(s) so minimumReleaseAge cannot block the install.`);
+    }
+    if (resolution.failed.length > 0) {
+        lines.push(`Warning: could not reach ${resolution.registry} for ${resolution.failed.length} package(s) — used the bundled fallback ranges for: ${resolution.failed.join(', ')}.`);
+    }
+    return lines;
+}

package/dist/templates-ui.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectOptions } from './templates.js';
+import { type ProjectOptions } from './templates.js';
 /**
  * The `web/` frontend emitted when `--ui` is passed: a Vite + React app on
  * @basaltkit/admin-shadcn (authentic shadcn/ui components) talking to the API

package/dist/templates-ui.js

@@ -1,5 +1,4 @@
-/** Kept in sync with the monorepo release line (mirror of templates.ts). */
-const BASALT_VERSION = '^1.0.0';
+import { thirdPartyVersionOf, versionOf } from './templates.js';
 /**
  * The `web/` frontend emitted when `--ui` is passed: a Vite + React app on
  * @basaltkit/admin-shadcn (authentic shadcn/ui components) talking to the API
@@ -13,8 +12,6 @@ export function uiFiles(options) {
         'web/vite.config.ts': webViteConfig(),
         'web/tsconfig.json': webTsconfig(),
         'web/index.html': webIndexHtml(options),
-        'web/postcss.config.js': webPostcss(),
-        'web/tailwind.config.js': webTailwind(),
         'web/src/main.tsx': webMain(),
         'web/src/crypto-shim.ts': webCryptoShim(),
         'web/src/index.css': webCss(),
@@ -27,34 +24,38 @@ function webPackageJson(options) {
         name: `${options.name}-web`,
         private: true,
         type: 'module',
-        scripts: { dev: 'vite', build: 'vite build', preview: 'vite preview' },
+        scripts: { dev: 'vite', build: 'vite build', preview: 'vite preview', typecheck: 'tsc --noEmit' },
         dependencies: {
-            '@basaltkit/admin': BASALT_VERSION,
-            '@basaltkit/admin-shadcn': BASALT_VERSION,
-            '@basaltkit/sdk': BASALT_VERSION,
-            react: '^18.3.1',
-            'react-dom': '^18.3.1',
-            zod: '^3.24.0',
-        },
-        devDependencies: {
-            '@types/react': '^18.3.0',
-            '@types/react-dom': '^18.3.0',
-            '@vitejs/plugin-react': '^4.3.0',
-            autoprefixer: '^10.4.0',
-            postcss: '^8.4.0',
-            tailwindcss: '^3.4.0',
-            typescript: '^5.8.0',
-            vite: '^6.0.0',
+            '@basaltkit/admin': versionOf('@basaltkit/admin'),
+            '@basaltkit/admin-shadcn': versionOf('@basaltkit/admin-shadcn'),
+            '@basaltkit/sdk': versionOf('@basaltkit/sdk'),
+            react: thirdPartyVersionOf('react'),
+            'react-dom': thirdPartyVersionOf('react-dom'),
+            // Matches the peer every @basaltkit package declares (zod 4).
+            zod: thirdPartyVersionOf('zod'),
         },
+        // Tailwind 4 runs as a Vite plugin (@tailwindcss/vite) — no PostCSS or
+        // autoprefixer config; the theme lives in src/index.css.
+        devDependencies: Object.fromEntries([
+            '@tailwindcss/vite',
+            '@types/node',
+            '@types/react',
+            '@types/react-dom',
+            '@vitejs/plugin-react',
+            'tailwindcss',
+            'typescript',
+            'vite',
+        ].map((pkg) => [pkg, thirdPartyVersionOf(pkg)])),
     }, null, 2)}\n`;
 }
 function webViteConfig() {
     return `import { fileURLToPath } from 'node:url'
+import tailwindcss from '@tailwindcss/vite'
 import react from '@vitejs/plugin-react'
 import { defineConfig } from 'vite'
 
 export default defineConfig({
-  plugins: [react()],
+  plugins: [react(), tailwindcss()],
   resolve: {
     alias: {
       // @basaltkit/admin uses randomUUID from crypto; map it to Web Crypto in the browser.
@@ -89,7 +90,9 @@ function webTsconfig() {
             noEmit: true,
             allowImportingTsExtensions: true,
             verbatimModuleSyntax: true,
-            types: ['node'],
+            // vite/client types the CSS/asset imports (TS 6+ checks side-effect
+            // imports such as `import './index.css'`) and import.meta.env.
+            types: ['node', 'vite/client'],
         },
         include: ['src'],
     }, null, 2)}\n`;
@@ -109,41 +112,6 @@ function webIndexHtml(options) {
 </html>
 `;
 }
-function webPostcss() {
-    return `export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-}
-`;
-}
-function webTailwind() {
-    return `export default {
-  darkMode: ['class'],
-  content: ['./index.html', './src/**/*.{ts,tsx}', './node_modules/@basaltkit/admin-shadcn/dist/**/*.js'],
-  theme: {
-    extend: {
-      colors: {
-        border: 'hsl(var(--border))',
-        input: 'hsl(var(--input))',
-        ring: 'hsl(var(--ring))',
-        background: 'hsl(var(--background))',
-        foreground: 'hsl(var(--foreground))',
-        primary: { DEFAULT: 'hsl(var(--primary))', foreground: 'hsl(var(--primary-foreground))' },
-        secondary: { DEFAULT: 'hsl(var(--secondary))', foreground: 'hsl(var(--secondary-foreground))' },
-        destructive: { DEFAULT: 'hsl(var(--destructive))', foreground: 'hsl(var(--destructive-foreground))' },
-        muted: { DEFAULT: 'hsl(var(--muted))', foreground: 'hsl(var(--muted-foreground))' },
-        accent: { DEFAULT: 'hsl(var(--accent))', foreground: 'hsl(var(--accent-foreground))' },
-        card: { DEFAULT: 'hsl(var(--card))', foreground: 'hsl(var(--card-foreground))' },
-      },
-      borderRadius: { lg: 'var(--radius)', md: 'calc(var(--radius) - 2px)', sm: 'calc(var(--radius) - 4px)' },
-    },
-  },
-  plugins: [],
-}
-`;
-}
 function webMain() {
     return `import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
@@ -162,9 +130,39 @@ function webCryptoShim() {
 `;
 }
 function webCss() {
-    return `@tailwind base;
-@tailwind components;
-@tailwind utilities;
+    return `@import 'tailwindcss';
+
+/* @basaltkit/admin-shadcn ships precompiled components: let Tailwind scan them
+   (paths are relative to this file, so ../node_modules is web/node_modules). */
+@source '../node_modules/@basaltkit/admin-shadcn/dist';
+
+/* Class-based dark mode: <html class="dark"> (the theme toggle sets it). */
+@custom-variant dark (&:is(.dark *));
+
+/* shadcn/ui tokens → Tailwind utilities (bg-primary, text-muted-foreground,
+   border-input, rounded-lg, …). The values are the CSS variables below. */
+@theme inline {
+  --color-border: hsl(var(--border));
+  --color-input: hsl(var(--input));
+  --color-ring: hsl(var(--ring));
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  --color-secondary: hsl(var(--secondary));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+  --color-destructive: hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+  --color-muted: hsl(var(--muted));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+  --color-accent: hsl(var(--accent));
+  --color-accent-foreground: hsl(var(--accent-foreground));
+  --color-card: hsl(var(--card));
+  --color-card-foreground: hsl(var(--card-foreground));
+  --radius-lg: var(--radius);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-sm: calc(var(--radius) - 4px);
+}
 
 @layer base {
   :root {
@@ -206,9 +204,19 @@ function webCss() {
     --input: 240 3.7% 18%;
     --ring: 243 75% 68%;
   }
-  * {
+  /* Tailwind 4 defaults borders to currentColor; keep the themed border. */
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
     border-color: hsl(var(--border));
   }
+  /* Tailwind 4 dropped the pointer cursor on buttons; keep it. */
+  button:not(:disabled),
+  [role='button']:not(:disabled) {
+    cursor: pointer;
+  }
   body {
     margin: 0;
     background-color: hsl(var(--background));

package/dist/templates.d.ts

@@ -10,15 +10,44 @@ export interface ProjectOptions {
     /** Expose opted-in routes as MCP tools (@basaltkit/mcp) over HTTP at `/mcp`. */
     mcp: boolean;
 }
-/** The dependency range for a @basalt package (override, else the base line). */
+export { SCAFFOLD_VERSIONS } from './versions.js';
+export { THIRD_PARTY_VERSIONS } from './latest-versions.js';
+/**
+ * The dependency range for a @basaltkit/* package: the current release line
+ * (`^<major>.<minor>.0`) of its workspace version, from the generated
+ * {@link SCAFFOLD_VERSIONS} map. Throws for an unknown package rather than
+ * guessing a range — a stale guess once pinned new apps to frozen 1.x lines.
+ */
 export declare const versionOf: (pkg: string) => string;
+/**
+ * The fallback range for a third-party package the templates emit, from
+ * {@link THIRD_PARTY_VERSIONS}. At scaffold time the CLI replaces it with
+ * `^<latest>` when the registry's latest is on the same major. Throws for an
+ * unknown package so every emitted range lives in that single table.
+ */
+export declare const thirdPartyVersionOf: (pkg: string) => string;
+/** True when the scaffold binds users to the tenant they act on (tenancy + auth). */
+export declare const enforcesMembership: (options: ProjectOptions) => boolean;
 export declare function packageJson(options: ProjectOptions): string;
 export declare function tsconfigJson(): string;
 export declare function envTs(options: ProjectOptions): string;
+/**
+ * An app-specific env-var prefix derived from the project name
+ * (`my-saas` → `MY_SAAS`), suggested for variables whose generic names
+ * (`DATABASE_URL`, …) other projects export too.
+ */
+export declare function envPrefix(name: string): string;
 export declare function envExample(options: ProjectOptions): string;
 export declare function appTs(options: ProjectOptions): string;
 export declare function routesTs(options: ProjectOptions): string;
 export declare function serverTs(): string;
+/**
+ * `pnpm dev` entrypoint. Opts into NODE_ENV=development (dev secret defaults,
+ * pretty logs) unless NODE_ENV is already set, then starts the server. Kept out
+ * of server.ts on purpose: `pnpm start` runs server.ts directly, where an unset
+ * NODE_ENV counts as production and secrets are required (fail-closed).
+ */
+export declare function devTs(): string;
 export declare function basaltBin(): string;
 export declare function appTest(options: ProjectOptions): string;
 export declare function readme(options: ProjectOptions): string;
@@ -28,11 +57,25 @@ export declare function readme(options: ProjectOptions): string;
  * project root automatically; Claude Desktop uses the same server entry.
  */
 export declare function mcpJson(_options: ProjectOptions): string;
+/**
+ * Keeps secrets and local state out of Docker build contexts, so a
+ * `COPY . .` can never bake `.env` or private keys into an image layer. Every
+ * rule is `**`-prefixed: .dockerignore patterns are anchored at the context
+ * root, so a bare `.env` or `*.pem` would still let `prisma/.env` or
+ * `certs/server.key` through.
+ */
+export declare function dockerignore(): string;
 export declare function gitignore(): string;
 /**
  * pnpm settings: esbuild's build script is required by tsx;
  * msgpackr-extract (optional native accelerator via BullMQ) is declined —
  * msgpackr falls back to pure JS. With --ui, `web` is a workspace member so
  * its own dependencies resolve.
+ *
+ * pnpm 11 notes (BK-002), spelled out in the file because both bite silently:
+ * `minimumReleaseAgeExclude` is evaluated first-match-wins BY PACKAGE NAME, so
+ * per-version exclusions of one package must be a single `||` union entry; and
+ * `verifyDepsBeforeRun` defaults to `install`, so any `pnpm <script>` may run
+ * `pnpm install` first — `warn` is offered commented out, never set for you.
  */
 export declare function pnpmWorkspaceYaml(options: ProjectOptions): string;