create-basalt 1.4.2 → 1.6.0

package/dist/templates.js

@@ -1,55 +1,64 @@
-/** Base release line for @basaltkit/* deps. */
-const BASALT_VERSION = '^1.0.0';
+import { THIRD_PARTY_VERSIONS } from './latest-versions.js';
+import { SCAFFOLD_VERSIONS } from './versions.js';
+export { SCAFFOLD_VERSIONS } from './versions.js';
+export { THIRD_PARTY_VERSIONS } from './latest-versions.js';
 /**
- * Per-package range overrides. In semver 0.x, `^0.4.0` locks the minor, so a
- * package that advances past the base line needs its own range or a fresh app
- * can't install it. Add an entry when a package crosses a minor.
+ * 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.
  */
-const VERSIONS = {
-    // ai-mcp is on the 0.x line (published separately from the 1.x framework base).
-    '@basaltkit/ai-mcp': '^0.1.0',
+export const versionOf = (pkg) => {
+    const range = SCAFFOLD_VERSIONS[pkg];
+    if (range === undefined) {
+        throw new Error(`create-basalt: no release line for ${pkg} — add it to scripts/sync-versions.mjs.`);
+    }
+    return range;
+};
+/**
+ * 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 const thirdPartyVersionOf = (pkg) => {
+    const range = THIRD_PARTY_VERSIONS[pkg];
+    if (range === undefined) {
+        throw new Error(`create-basalt: no fallback range for ${pkg} — add it to THIRD_PARTY_VERSIONS.`);
+    }
+    return range;
 };
-/** The dependency range for a @basalt package (override, else the base line). */
-export const versionOf = (pkg) => VERSIONS[pkg] ?? BASALT_VERSION;
+/** True when the scaffold binds users to the tenant they act on (tenancy + auth). */
+export const enforcesMembership = (options) => options.tenancy && options.auth;
 export function packageJson(options) {
-    const dependencies = {
-        '@basaltkit/config': BASALT_VERSION,
-        '@basaltkit/core': BASALT_VERSION,
-        '@basaltkit/env': BASALT_VERSION,
-        '@basaltkit/events': BASALT_VERSION,
-        '@basaltkit/fastify': BASALT_VERSION,
-        '@basaltkit/logger': BASALT_VERSION,
-        zod: '^4.0.0',
-    };
+    const basalt = ['@basaltkit/config', '@basaltkit/core', '@basaltkit/env', '@basaltkit/events', '@basaltkit/fastify', '@basaltkit/logger'];
     if (options.tenancy)
-        dependencies['@basaltkit/tenancy'] = BASALT_VERSION;
+        basalt.push('@basaltkit/tenancy');
     if (options.auth)
-        dependencies['@basaltkit/auth'] = BASALT_VERSION;
+        basalt.push('@basaltkit/auth');
+    // Tenancy + auth: @basaltkit/teams binds each user to the tenants they belong
+    // to (tenantMembershipPlugin) — without it x-tenant-id/Host is a free choice.
+    if (enforcesMembership(options))
+        basalt.push('@basaltkit/teams');
     if (options.billing)
-        dependencies['@basaltkit/subscriptions'] = BASALT_VERSION;
+        basalt.push('@basaltkit/subscriptions');
     if (options.mcp)
-        dependencies['@basaltkit/mcp'] = BASALT_VERSION;
+        basalt.push('@basaltkit/mcp');
     if (options.cli) {
         // Runtime deps: app.ts uses commandsPlugin (@basaltkit/cli); prisma powers
-        // prismaPlugin + `basalt prisma:sync`. @basaltkit/generator is dev-only (below).
-        dependencies['@basaltkit/cli'] = BASALT_VERSION;
-        dependencies['@basaltkit/prisma'] = BASALT_VERSION;
-    }
-    // Apply per-package range overrides. Only @basaltkit/* packages: versionOf
-    // falls back to BASALT_VERSION, which would clobber third-party ranges
-    // (this once rewrote zod's range to the @basalt base line).
-    for (const pkg of Object.keys(dependencies)) {
-        if (pkg.startsWith('@basaltkit/'))
-            dependencies[pkg] = versionOf(pkg);
+        // `basalt prisma:sync` (and prismaPlugin once the app adds a PrismaClient —
+        // the scaffold wires no database itself). @basaltkit/generator is dev-only (below).
+        basalt.push('@basaltkit/cli', '@basaltkit/prisma');
     }
+    const dependencies = { zod: thirdPartyVersionOf('zod') };
+    for (const pkg of basalt)
+        dependencies[pkg] = versionOf(pkg);
     const devDependencies = {
         '@basaltkit/testing': versionOf('@basaltkit/testing'),
-        '@types/node': '^22.15.0',
-        'pino-pretty': '^13.0.0',
-        tsx: '^4.19.0',
-        typescript: '^5.8.0',
-        vitest: '^3.1.0',
     };
+    for (const pkg of ['@types/node', 'pino-pretty', 'tsx', 'typescript', 'vitest']) {
+        devDependencies[pkg] = thirdPartyVersionOf(pkg);
+    }
     if (options.cli) {
         // Dev-only: only bin/basalt.ts imports the code generator — the runtime server
         // never does, so the app runs completely without the codegen/AI layer.
@@ -67,7 +76,9 @@ export function packageJson(options) {
         private: true,
         type: 'module',
         scripts: {
-            dev: 'tsx watch src/server.ts',
+            // dev opts into NODE_ENV=development (src/dev.ts); start does not, so an
+            // unset NODE_ENV counts as production and secrets are required.
+            dev: 'tsx watch src/dev.ts',
             start: 'tsx src/server.ts',
             test: 'vitest run',
             typecheck: 'tsc --noEmit',
@@ -104,21 +115,49 @@ export const env = defineEnv({
   // Typed against the logger's LogLevel union — a free-form string here fails
   // \`pnpm typecheck\` where loggerPlugin({ level }) consumes it.
   LOG_LEVEL: z.enum(LOG_LEVELS).default('info'),
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),${options.auth
+  // Unset counts as production (fail-closed); \`pnpm dev\` sets development.
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),${options.auth
         ? `
-  // Signs JWTs and sessions. secret() is fail-closed: required in production
-  // (no fallback), rejected if it looks like a placeholder. Dev uses devDefault.
+  // Signs JWTs and sessions. secret() is fail-closed: required unless NODE_ENV
+  // is explicitly development/test (no fallback when NODE_ENV is unset),
+  // rejected if it looks like a placeholder. \`pnpm dev\` uses devDefault.
   APP_SECRET: secret({ minLength: 32, devDefault: 'dev-only-insecure-secret-please-change-me' }),`
         : ''}
 })
 `;
 }
+/**
+ * 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 function envPrefix(name) {
+    let base = name
+        .replace(/^@[^/]+\//, '')
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, '_');
+    // Trim underscores in linear time (an anchored `_+$` regex backtracks).
+    let start = 0;
+    let end = base.length;
+    while (start < end && base[start] === '_')
+        start++;
+    while (end > start && base[end - 1] === '_')
+        end--;
+    base = base.slice(start, end);
+    return base === '' || /^\d/.test(base) ? `APP_${base}` : base;
+}
 export function envExample(options) {
-    return `PORT=3000
+    const prefix = envPrefix(options.name);
+    return `# Nothing loads this file for you: copy it to .env and start with
+# \`node --env-file=.env\` / \`tsx --env-file=.env\`, or export the variables.
+# --env-file NEVER overrides a variable already exported in your shell: if
+# another project exported DATABASE_URL, the app silently uses THAT one. Give
+# generic names an app-specific prefix, e.g. ${prefix}_DATABASE_URL.
+PORT=3000
 HOST=0.0.0.0
 LOG_LEVEL=info
 NODE_ENV=development
-${options.auth ? '# Required in production (the app refuses to boot without it).\n# Generate a strong one:  openssl rand -base64 48\n# APP_SECRET=\n' : ''}`;
+${options.auth ? '# Required unless NODE_ENV is development/test — `pnpm start` refuses to boot\n# without it. Generate a strong one:  openssl rand -base64 48\n# APP_SECRET=\n' : ''}`;
 }
 export function appTs(options) {
     const imports = [
@@ -134,8 +173,11 @@ export function appTs(options) {
         `eventsPlugin()`,
         `securityPlugin({
       // Secure response headers (HSTS, X-Frame-Options, nosniff, …) are on by
-      // default. Turn on rate limiting and a CORS allow-list for production:
-      // rateLimit: { limit: 120, windowMs: 60_000 },
+      // default, and so is a global per-IP rate limit (auth routes add their
+      // own stricter budget). Behind a proxy, make the adapter set request.ip
+      // from it; with several replicas, pass a shared \`store\`.
+      rateLimit: { limit: 120, windowMs: 60_000 },
+      // Add a CORS allow-list if a browser app on another origin calls the API:
       // cors: { origin: ['https://app.example.com'], credentials: true },
     })`,
     ];
@@ -162,6 +204,25 @@ export function appTs(options) {
         // password recovery. mfaRoutes(): TOTP enroll/activate/status/disable.
         routesExpression = '[...appRoutes, ...authRoutes(), ...mfaRoutes()]';
     }
+    if (enforcesMembership(options)) {
+        // Secure by default: the tenant comes from client input (x-tenant-id / Host),
+        // so it is identification, never authorization. tenantMembershipPlugin()
+        // rejects (403) every authenticated request for a tenant the user is not a
+        // member of. Routes that act outside a single tenant opt out with
+        // meta: { central: true }.
+        imports[0] = `import { createApp, definePlugin } from '@basaltkit/core'`;
+        imports.push(`import { TEAMS, teamsPlugin, tenantMembershipPlugin } from '@basaltkit/teams'`);
+        plugins.push(`teamsPlugin({
+      // TODO: the default membership/invitation stores are in-memory — pass
+      // persistent ones (memberships, invitations) before production.
+    })`);
+        plugins.push(`// Rejects authenticated requests for a tenant the user is not a member of.
+      tenantMembershipPlugin()`);
+        plugins.push(`// Dev-only seed: each new registrant joins the 'demo' tenant so the scaffold
+      // works out of the box. Never in production — add members explicitly there
+      // (on tenant creation, or via TEAMS invite()/accept()).
+      ...(env.NODE_ENV === 'production' ? [] : [demoMembershipSeed()])`);
+    }
     if (options.billing) {
         imports.push(`import { definePlans, subscriptionsPlugin } from '@basaltkit/subscriptions'`);
         plugins.push(`subscriptionsPlugin({
@@ -211,7 +272,21 @@ export function buildApp(options: BuildAppOptions = {}) {
     ],
   })
 }
-`;
+${enforcesMembership(options)
+        ? `
+/** Dev-only: adds each new registrant as a member of the 'demo' tenant. */
+function demoMembershipSeed() {
+  return definePlugin({
+    name: 'app:demo-membership-seed',
+    register({ container, hooks }) {
+      hooks.on('auth:registered', async ({ user }) => {
+        await container.get(TEAMS).addMember('demo', user.id, 'member')
+      })
+    },
+  })
+}
+`
+        : ''}`;
 }
 export function routesTs(options) {
     const endpoints = [
@@ -283,12 +358,29 @@ for (const signal of ['SIGINT', 'SIGTERM'] as const) {
 }
 `;
 }
+/**
+ * `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 function devTs() {
+    return `// Development entrypoint (\`pnpm dev\`). \`pnpm start\` runs server.ts directly,
+// where an unset NODE_ENV counts as production: secrets are then required.
+process.env['NODE_ENV'] ??= 'development'
+await import('./server.js')
+`;
+}
 export function basaltBin() {
     return `#!/usr/bin/env node
 import { runCli } from '@basaltkit/cli'
 import { generatorCommands } from '@basaltkit/generator'
 import { prismaSyncCommand } from '@basaltkit/prisma'
-import { buildApp } from '../src/app.js'
+
+// Dev tooling: opt into development defaults unless NODE_ENV is already set
+// (imported dynamically below so env.ts is evaluated after this line).
+process.env['NODE_ENV'] ??= 'development'
+const { buildApp } = await import('../src/app.js')
 
 // The 'basalt' CLI: boots the app WITH the dev/CLI commands, runs one, shuts down.
 // The dev tools (@basaltkit/generator; add @basaltkit/ai for ai:*) are imported
@@ -362,6 +454,18 @@ pnpm install
 pnpm dev        # API on http://localhost:3000
 pnpm test
 \`\`\`
+
+## Environment
+
+\`src/env.ts\` validates \`process.env\` — nothing loads \`.env\` for you. Copy
+\`.env.example\` to \`.env\` and launch with \`--env-file=.env\` (Node/tsx), or
+export the variables.
+
+**\`--env-file\` never overrides a variable that is already exported.** In a shell
+where another project exported \`DATABASE_URL\` (or \`PORT\`), this app boots
+against THAT value and only fails on the first request that touches it. Give
+generic names an app-specific prefix — \`${envPrefix(options.name)}_DATABASE_URL\` rather than
+\`DATABASE_URL\` — and check \`env | grep DATABASE_URL\` when in doubt.
 ${options.cli
         ? `
 ## The \`basalt\` CLI
@@ -375,6 +479,18 @@ pnpm basalt make:service Project    # a single artifact (--force to overwrite)
 
 Generated resources land in \`src/modules/<name>/\`. Register the generated
 plugin in \`src/app.ts\` to wire it up.
+
+With pnpm 11, \`pnpm basalt …\` first verifies dependencies
+(\`verifyDepsBeforeRun\`, default \`install\`): when any workspace project is out
+of sync it runs \`pnpm install\` — network included — before the command. To
+run the CLI without that check, call it directly:
+
+\`\`\`bash
+node_modules/.bin/tsx bin/basalt.ts make:resource Project
+\`\`\`
+
+or set \`verifyDepsBeforeRun: warn\` in \`pnpm-workspace.yaml\` (a conscious
+choice: you then run \`pnpm install\` yourself after dependency changes).
 `
         : ''}${options.ui
         ? `
@@ -433,6 +549,29 @@ export function mcpJson(_options) {
         },
     }, null, 2)}\n`;
 }
+/**
+ * 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 function dockerignore() {
+    return `**/.env
+**/.env.*
+!**/.env.example
+**/.npmrc
+**/.git
+**/node_modules
+**/coverage
+**/*.log
+**/*.pem
+**/*.key
+**/*.p12
+**/*.pfx
+**/.DS_Store
+`;
+}
 export function gitignore() {
     return `node_modules/
 dist/
@@ -447,6 +586,12 @@ dist/
  * 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 function pnpmWorkspaceYaml(options) {
     return `${options.ui
@@ -460,5 +605,16 @@ export function pnpmWorkspaceYaml(options) {
 # pnpm's minimumReleaseAge policy so \`pnpm up\` is never blocked on a fresh release.
 minimumReleaseAgeExclude:
   - '@basaltkit/*'
+# To let specific versions of ONE package bypass the policy, write ONE entry
+# with a \`||\` union. pnpm evaluates this list first match wins by package
+# name, so a second '<name>@<version>' entry for the same package is ignored:
+#   - '@types/node@22.20.4 || 26.6.2'
+
+# pnpm 11 checks dependencies before every \`pnpm <script>\` / \`pnpm exec\`
+# (verifyDepsBeforeRun defaults to \`install\`): when node_modules is out of sync
+# with ANY workspace project's manifest, it runs \`pnpm install\` first — network
+# and supply-chain checks included. To opt out consciously (you then run
+# \`pnpm install\` yourself after dependency changes), uncomment:
+# verifyDepsBeforeRun: warn
 `;
 }

package/dist/versions.d.ts

@@ -0,0 +1 @@
+export declare const SCAFFOLD_VERSIONS: Readonly<Record<string, string>>;

package/dist/versions.js

@@ -0,0 +1,24 @@
+// GENERATED by scripts/sync-versions.mjs (runs before every build) — do not edit.
+// The dependency range a new app gets for each @basaltkit/* package: the
+// current release line (^<major>.<minor>.0) of the workspace version.
+export const SCAFFOLD_VERSIONS = {
+    '@basaltkit/admin': '^2.0.0',
+    '@basaltkit/admin-shadcn': '^1.1.0',
+    '@basaltkit/ai-mcp': '^0.1.0',
+    '@basaltkit/auth': '^3.1.0',
+    '@basaltkit/cli': '^1.2.0',
+    '@basaltkit/config': '^1.1.0',
+    '@basaltkit/core': '^1.3.0',
+    '@basaltkit/env': '^3.0.0',
+    '@basaltkit/events': '^1.3.0',
+    '@basaltkit/fastify': '^2.2.0',
+    '@basaltkit/generator': '^1.4.0',
+    '@basaltkit/logger': '^1.3.0',
+    '@basaltkit/mcp': '^3.0.0',
+    '@basaltkit/prisma': '^2.1.0',
+    '@basaltkit/sdk': '^2.0.0',
+    '@basaltkit/subscriptions': '^4.0.0',
+    '@basaltkit/teams': '^3.0.0',
+    '@basaltkit/tenancy': '^2.0.0',
+    '@basaltkit/testing': '^2.0.0',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-basalt",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -21,24 +21,25 @@
     "dist"
   ],
   "devDependencies": {
-    "@types/node": "^26.3.0",
+    "@types/node": "^26.6.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
-    "zod": "^3.24.0 || ^4.0.0",
-    "@basaltkit/auth": "^1.8.0",
-    "@basaltkit/cli": "^1.2.3",
+    "vitest": "^5.0.1",
+    "zod": "^4.6.5",
+    "@basaltkit/auth": "^3.1.0",
     "@basaltkit/config": "^1.1.2",
-    "@basaltkit/core": "^1.3.1",
-    "@basaltkit/env": "^1.0.2",
-    "@basaltkit/events": "^1.1.1",
-    "@basaltkit/fastify": "^1.8.1",
-    "@basaltkit/generator": "^1.2.2",
-    "@basaltkit/logger": "^1.2.2",
-    "@basaltkit/mcp": "^1.1.1",
-    "@basaltkit/prisma": "^1.4.3",
-    "@basaltkit/subscriptions": "^2.8.1",
-    "@basaltkit/tenancy": "^1.4.2",
-    "@basaltkit/testing": "^1.1.1",
+    "@basaltkit/core": "^1.3.2",
+    "@basaltkit/env": "^3.0.0",
+    "@basaltkit/cli": "^1.2.5",
+    "@basaltkit/events": "^1.3.0",
+    "@basaltkit/generator": "^1.4.0",
+    "@basaltkit/logger": "^1.3.0",
+    "@basaltkit/mcp": "^3.0.0",
+    "@basaltkit/prisma": "^2.1.0",
+    "@basaltkit/teams": "^3.0.1",
+    "@basaltkit/fastify": "^2.2.0",
+    "@basaltkit/tenancy": "^2.0.0",
+    "@basaltkit/testing": "^2.0.2",
+    "@basaltkit/subscriptions": "^4.0.0",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -61,7 +62,8 @@
     "boilerplate"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node scripts/sync-versions.mjs && tsc -p tsconfig.build.json",
+    "sync-versions": "node scripts/sync-versions.mjs",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }