@basaltkit/cli 1.3.0 → 1.4.0

package/README.md

@@ -91,11 +91,11 @@ Without registering anything, `runCli` always provides:
 | Command | What it does |
 | --- | --- |
 | `basalt list` (or `basalt` with no arguments) | Lists all available commands, with their descriptions |
-| `basalt routes` | Lists the HTTP routes registered by the application (read from the `http:routes` metadata bucket, populated by HTTP adapters such as `@basaltkit/fastify`) |
+| `basalt routes [--json] [--unguarded --require=auth,can [--allow=<glob,…>]]` | Lists the HTTP routes registered by the application with the guards each declares in `meta` — columns `auth`, `can`, `rateLimit`, `tenant` and `guards` (`mfa`, `teamRole`, `scopes`, `subscribed`, `feature`). `--json` prints one JSON array of route rows. `--unguarded` lists the routes that do not declare the `--require`d guards and exits `1` when there is any (see [Route security review](#route-security-review)). Read from the `http:routes` metadata bucket, populated by every HTTP adapter |
 | `basalt schedule:list` | Lists scheduled tasks and their cron expressions (read from the `schedule:entries` bucket, populated by `@basaltkit/scheduler`) |
 | `basalt dev [--entry] [--worker] [--queue] [--no-routes]` | Runs the app with watch + restart, **prints the route table on boot**, and with `--worker` also starts a watched `queue:work` alongside it (server + worker in one command). Delegates watching to `tsx watch` / `node --watch`. |
 | `basalt upgrade [--dry] [--only=<id>] [--dir=<path>]` | Applies framework upgrade codemods (ships the `@machize/*` → `@basaltkit/*` scope rename; `--dry` previews). `create-basalt update` runs them for you after an install. `nodeUpgradeFs(baseDir)` resolves relative paths against the directory being upgraded, so `--dir=` reads the tree it lists |
-| `basalt publish [<id>] [--force]` | Copies a bundled stub group into the app — `dockerfile` (plus a `.dockerignore` keeping `.env` and keys out of the image), `ci`, `editorconfig` (run with no id to list) |
+| `basalt publish [<id>] [--force]` | Copies a bundled stub group into the app — `dockerfile` (a multi-stage build that runs `pnpm build` and ships `dist/src/server.js` on plain node as `USER node`, plus a `.dockerignore` keeping `.env` and keys out of the image — the same files create-basalt scaffolds), `ci` (install, typecheck, build, test), `editorconfig` (run with no id to list). The stub contents are exported too: `DOCKERFILE`, `DOCKERIGNORE`, `CI_WORKFLOW`, `EDITORCONFIG`, `PRODUCTION_ENTRY` |
 
 Not served by `runCli`: the **project commands** `update`, `add`, `doctor` and
 `info` belong to `create-basalt` — the scaffolded `bin/basalt.ts` forwards them
@@ -237,15 +237,70 @@ Returns `[routesCommand, scheduleListCommand, devCommand, upgradeCommand, publis
 
 The definitions of the built-in `routes` and `schedule:list` commands. *(Advanced — useful only if you want to run them directly or compose your own list.)*
 
+`routeAllowPattern(glob)` compiles an `--allow` pattern into a `(row) => boolean`; `UNGUARDED_SCOPE_NOTE` is the "route meta only" caveat `--unguarded` prints.
+
 ### Exported types
 
 | Type | Description |
 | --- | --- |
 | `CommandDefinition`, `CommandContext`, `CommandIo` | Described above |
 | `RunCliOptions`, `ParsedArgv` | Described above |
-| `RouteMetadata` | `{ method: string; url: string; [key: string]: unknown }` — entries from the `http:routes` bucket |
+| `RouteMetadata` | `{ method: string; url: string; meta?: Record<string, unknown>; [key: string]: unknown }` — entries from the `http:routes` bucket |
 | `ScheduleMetadata` | `{ name: string; cron: string; timezone: string }` — entries from the `schedule:entries` bucket |
 
+## Route security review
+
+`basalt routes` answers "which route is unprotected?", not just "which routes exist":
+
+```text
+method  url                auth   can              rateLimit       tenant    guards
+------  -----------------  -----  ---------------  --------------  --------  ------
+GET     /health            false
+GET     /projects          true   projects:read
+POST    /projects          true   projects:create  10/1m per user  required
+POST    /webhooks/stripe
+```
+
+Gate it in CI — the command exits `1` and names each offender and what it misses:
+
+```bash
+pnpm basalt routes --unguarded --require=auth,can --allow='POST /webhooks/*'
+```
+
+- `--require` is mandatory (`auth`, `can`, or both). An explicit opt-out is
+  intentional and never reported: `auth: false` (or `public: true`) satisfies
+  both, and `can: false` satisfies `can`. Only `auth: true` counts as `auth` —
+  the one value `authPlugin` enforces.
+- `--allow` takes comma-separated globs: `*` matches within one path segment,
+  `**` across segments; a leading method (`'POST /webhooks/*'`) restricts it to
+  that method.
+- `--json` combines with `--unguarded` to print the offenders with a `missing`
+  array.
+- The `tenant` column shows the route's tenancy declaration: `required`
+  (`meta.tenant: true`), `exempt` (`meta.tenant: false`), `central-only`
+  (`meta.tenant: 'never'` — a request that resolves a tenant is rejected),
+  or blank when the route inherits the app-wide default. It reflects
+  `meta.tenant` only; `meta.central: true` (the teams membership bypass)
+  shows as `central` among the guards.
+
+**It checks route meta only.** An app-wide rate limit (`securityPlugin({ rateLimit })`),
+URL-based tenancy (`tenancyPlugin({ required: { except } })`), app hooks or
+middleware, and the edge routes plugins add through `HTTP_SERVER.addRoute()`
+(`healthPlugin`, `metricsPlugin`, `openapiPlugin`) are invisible to it. Routes
+from `authRoutes()`, `mcpRoutes()` and any other `BasaltRoute[]` you pass to the
+adapter are listed. The same rows are available to a test, without listening —
+`describeRoutes()` and `findUnguardedRoutes()` from `@basaltkit/http`:
+
+```ts
+import { ensureMetadata } from '@basaltkit/core'
+import { describeRoutes, findUnguardedRoutes } from '@basaltkit/http'
+
+const app = await buildApp().boot()
+const rows = describeRoutes(ensureMetadata(app.container).get('http:routes'))
+expect(findUnguardedRoutes(rows, { require: ['auth', 'can'] })).toEqual([])
+await app.shutdown()
+```
+
 ## Common errors and solutions (FAQ)
 
 **`Unknown command "x". Run "basalt list" to see what is available.`**

package/dist/builtins.d.ts

@@ -1,8 +1,11 @@
+import { type RouteRow } from '@basaltkit/http/route-table';
 import { type CommandDefinition } from './command.js';
 /** Route entries written by HTTP adapters into the 'http:routes' bucket. */
 export interface RouteMetadata {
     method: string;
     url: string;
+    /** The route's declared `meta` (guards, rate limit, tenancy…). */
+    meta?: Record<string, unknown> | undefined;
     [key: string]: unknown;
 }
 /** Schedule entries written by the scheduler into the 'schedule:entries' bucket. */
@@ -11,6 +14,23 @@ export interface ScheduleMetadata {
     cron: string;
     timezone: string;
 }
+/** What `--unguarded` cannot see — printed with its result and repeated in the docs. */
+export declare const UNGUARDED_SCOPE_NOTE: string;
+/**
+ * Compiles an `--allow` pattern. `*` matches within one path segment, `**`
+ * across segments. A pattern with a space (`'POST /webhooks/*'`) also matches
+ * the method; one without matches the URL on any method.
+ */
+export declare function routeAllowPattern(pattern: string): (row: Pick<RouteRow, 'method' | 'url'>) => boolean;
+/**
+ * `basalt routes [--json] [--unguarded --require=auth,can [--allow=<glob,...>]]`
+ *
+ * Lists the HTTP routes the app registered with the guards each declares in
+ * `meta` (auth, can, rateLimit, tenant, and the other guarded keys). `--json`
+ * prints the {@link RouteRow} array for CI and scripts. `--unguarded` lists
+ * the routes that do not declare the `--require`d guards and exits 1 when
+ * there is any — route META only (see {@link UNGUARDED_SCOPE_NOTE}).
+ */
 export declare const routesCommand: CommandDefinition;
 export declare const scheduleListCommand: CommandDefinition;
 export declare function builtinCommands(): CommandDefinition[];

package/dist/builtins.js

@@ -1,20 +1,108 @@
 import { METADATA } from '@basaltkit/core';
+// The zod-free subpath: `basalt routes` must not pull the HTTP runtime in.
+import { describeRoutes, findUnguardedRoutes } from '@basaltkit/http/route-table';
 import { defineCommand } from './command.js';
 import { devCommand } from './dev.js';
 import { upgradeCommand } from './upgrade.js';
 import { publishCommand } from './publish.js';
+const REQUIREMENTS = ['auth', 'can'];
+/** What `--unguarded` cannot see — printed with its result and repeated in the docs. */
+export const UNGUARDED_SCOPE_NOTE = 'Checks route meta only: an app-wide rate limit, URL-based tenancy (tenancyPlugin `required.except`), ' +
+    'app hooks/middleware and edge routes (health, metrics, openapi) are invisible to it.';
+/**
+ * Compiles an `--allow` pattern. `*` matches within one path segment, `**`
+ * across segments. A pattern with a space (`'POST /webhooks/*'`) also matches
+ * the method; one without matches the URL on any method.
+ */
+export function routeAllowPattern(pattern) {
+    const trimmed = pattern.trim();
+    const space = trimmed.indexOf(' ');
+    const method = space === -1 ? undefined : trimmed.slice(0, space).toUpperCase();
+    const glob = space === -1 ? trimmed : trimmed.slice(space + 1).trim();
+    const source = glob
+        .split('**')
+        .map((part) => part
+        .split('*')
+        .map((literal) => literal.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+        .join('[^/]*'))
+        .join('.*');
+    const regex = new RegExp(`^${source}$`);
+    return (row) => (method === undefined || row.method === method) && regex.test(row.url);
+}
+const cell = (value) => {
+    if (value === null)
+        return '';
+    if (Array.isArray(value))
+        return value.join(', ');
+    return String(value);
+};
+/** Table rows for `basalt routes`: one column per guard, blank when undeclared. */
+function tableRows(rows) {
+    return rows.map((row) => ({
+        method: row.method,
+        url: row.url,
+        auth: cell(row.auth),
+        can: cell(row.can),
+        rateLimit: cell(row.rateLimit),
+        tenant: cell(row.tenant),
+        guards: cell(row.guards),
+    }));
+}
+/**
+ * `basalt routes [--json] [--unguarded --require=auth,can [--allow=<glob,...>]]`
+ *
+ * Lists the HTTP routes the app registered with the guards each declares in
+ * `meta` (auth, can, rateLimit, tenant, and the other guarded keys). `--json`
+ * prints the {@link RouteRow} array for CI and scripts. `--unguarded` lists
+ * the routes that do not declare the `--require`d guards and exits 1 when
+ * there is any — route META only (see {@link UNGUARDED_SCOPE_NOTE}).
+ */
 export const routesCommand = defineCommand({
     name: 'routes',
-    description: 'List the HTTP routes registered by the app',
-    handle({ container, io }) {
+    description: 'List HTTP routes with their declared guards (--json, --unguarded --require=auth,can)',
+    handle({ container, io, flags }) {
         const routes = container.has(METADATA)
             ? container.get(METADATA).get('http:routes')
             : [];
-        if (routes.length === 0) {
+        const rows = describeRoutes(routes);
+        const json = flags['json'] === true;
+        if (flags['unguarded'] === true) {
+            const required = typeof flags['require'] === 'string' ? flags['require'].split(',').map((r) => r.trim()).filter(Boolean) : [];
+            const unknown = required.filter((r) => !REQUIREMENTS.includes(r));
+            if (required.length === 0 || unknown.length > 0) {
+                io.error(unknown.length > 0
+                    ? `Unknown --require value(s): ${unknown.join(', ')}. Use auth and/or can.`
+                    : '--unguarded needs an explicit --require=auth,can (or just auth / can).');
+                return 2;
+            }
+            const patterns = typeof flags['allow'] === 'string' ? flags['allow'].split(',').filter((p) => p.trim()).map(routeAllowPattern) : [];
+            const offenders = findUnguardedRoutes(rows, {
+                require: required,
+                allow: (row) => patterns.some((matches) => matches(row)),
+            });
+            if (json) {
+                io.log(JSON.stringify(offenders.map(({ row, missing }) => ({ ...row, missing }))));
+            }
+            else if (offenders.length === 0) {
+                io.log(`All ${rows.length} route(s) declare ${required.join(' + ')} (or opt out explicitly).`);
+                io.log(UNGUARDED_SCOPE_NOTE);
+            }
+            else {
+                io.error(`${offenders.length} route(s) do not declare ${required.join(' + ')}:`);
+                io.table(offenders.map(({ row, missing }) => ({ method: row.method, url: row.url, missing: missing.join(', ') })));
+                io.log(UNGUARDED_SCOPE_NOTE);
+            }
+            return offenders.length > 0 ? 1 : 0;
+        }
+        if (json) {
+            io.log(JSON.stringify(rows));
+            return;
+        }
+        if (rows.length === 0) {
             io.log('No routes registered.');
             return;
         }
-        io.table(routes.map(({ method, url }) => ({ method, url })));
+        io.table(tableRows(rows));
     },
 });
 export const scheduleListCommand = defineCommand({

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export { runCli, type RunCliOptions } from './runner.js';
 export { commandsPlugin } from './plugin.js';
 export { consoleIo, memoryIo, renderTable } from './io.js';
 export { parseArgv, type ParsedArgv } from './parse.js';
-export { builtinCommands, routesCommand, scheduleListCommand, type RouteMetadata, type ScheduleMetadata, } from './builtins.js';
+export { builtinCommands, routesCommand, routeAllowPattern, UNGUARDED_SCOPE_NOTE, scheduleListCommand, type RouteMetadata, type ScheduleMetadata, } from './builtins.js';
 export { devCommand, resolveDevEntry, resolveDevRunner, devRouteRows, DEV_ENTRY_CANDIDATES, type DevRunner, type DevRoute, } from './dev.js';
 export { upgradeCommand, runUpgrade, MIGRATIONS, renameMachizeScope, nodeUpgradeFs, type Migration, type Edit, type UpgradeFs, type UpgradeReport, } from './upgrade.js';
 export { publishCommand, runPublish, PUBLISHABLES, nodePublishFs, type Publishable, type PublishableFile, type PublishFs, type PublishResult, } from './publish.js';
+export { DOCKERFILE, DOCKERIGNORE, CI_WORKFLOW, EDITORCONFIG, PRODUCTION_ENTRY } from './stubs.js';

package/dist/index.js

@@ -3,7 +3,8 @@ export { runCli } from './runner.js';
 export { commandsPlugin } from './plugin.js';
 export { consoleIo, memoryIo, renderTable } from './io.js';
 export { parseArgv } from './parse.js';
-export { builtinCommands, routesCommand, scheduleListCommand, } from './builtins.js';
+export { builtinCommands, routesCommand, routeAllowPattern, UNGUARDED_SCOPE_NOTE, scheduleListCommand, } from './builtins.js';
 export { devCommand, resolveDevEntry, resolveDevRunner, devRouteRows, DEV_ENTRY_CANDIDATES, } from './dev.js';
 export { upgradeCommand, runUpgrade, MIGRATIONS, renameMachizeScope, nodeUpgradeFs, } from './upgrade.js';
 export { publishCommand, runPublish, PUBLISHABLES, nodePublishFs, } from './publish.js';
+export { DOCKERFILE, DOCKERIGNORE, CI_WORKFLOW, EDITORCONFIG, PRODUCTION_ENTRY } from './stubs.js';

package/dist/publish.js

@@ -1,76 +1,16 @@
 import { defineCommand } from './command.js';
-const DOCKERFILE = `# syntax=docker/dockerfile:1
-FROM node:22-slim AS base
-ENV NODE_ENV=production
-WORKDIR /app
-
-FROM base AS deps
-COPY package.json pnpm-lock.yaml* ./
-RUN corepack enable && pnpm install --prod --frozen-lockfile
-
-FROM base AS run
-COPY --from=deps /app/node_modules ./node_modules
-COPY . .
-EXPOSE 3000
-CMD ["node", "dist/main.js"]
-`;
-/**
- * Published with the Dockerfile: its \`COPY . .\` would otherwise bake \`.env\`,
- * private keys and VCS metadata 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.
- */
-const DOCKERIGNORE = `**/.env
-**/.env.*
-!**/.env.example
-**/.npmrc
-**/.git
-**/node_modules
-**/coverage
-**/*.log
-**/*.pem
-**/*.key
-**/*.p12
-**/*.pfx
-**/.DS_Store
-`;
-const CI_WORKFLOW = `name: ci
-on:
-  push: { branches: [main] }
-  pull_request:
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 22, cache: pnpm }
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm run build
-      - run: pnpm run test
-`;
-const EDITORCONFIG = `root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-insert_final_newline = true
-indent_style = space
-indent_size = 2
-trim_trailing_whitespace = true
-`;
+import { CI_WORKFLOW, DOCKERFILE, DOCKERIGNORE, EDITORCONFIG } from './stubs.js';
 /** Stubs bundled with the CLI. Apps can register more via the metadata bucket. */
 export const PUBLISHABLES = [
     {
         id: 'dockerfile',
-        description: 'Production multi-stage Dockerfile (+ .dockerignore keeping secrets out of the image)',
+        description: 'Production multi-stage Dockerfile — build stage + plain-node runtime (+ .dockerignore keeping secrets out of the image)',
         files: () => [
             { path: 'Dockerfile', content: DOCKERFILE },
             { path: '.dockerignore', content: DOCKERIGNORE },
         ],
     },
-    { id: 'ci', description: 'GitHub Actions CI workflow', files: () => [{ path: '.github/workflows/ci.yml', content: CI_WORKFLOW }] },
+    { id: 'ci', description: 'GitHub Actions CI workflow (install, typecheck, build, test)', files: () => [{ path: '.github/workflows/ci.yml', content: CI_WORKFLOW }] },
     { id: 'editorconfig', description: 'Shared .editorconfig', files: () => [{ path: '.editorconfig', content: EDITORCONFIG }] },
 ];
 /**

package/dist/stubs.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The production stubs `basalt publish` copies into an app — the SINGLE source
+ * of truth. create-basalt ships the same files in every new scaffold and offers
+ * them from `create-basalt update`: its build copies this file verbatim to
+ * `packages/create-app/src/stubs.ts` (scripts/sync-stubs.mjs), and a test there
+ * fails if the copy drifts. Keep this module free of imports for that reason.
+ *
+ * The layout these stubs assume is the create-basalt scaffold's (BK-026):
+ * `pnpm build` runs `tsc -p tsconfig.build.json` (rootDir `.`, outDir `dist`),
+ * so `src/server.ts` compiles to {@link PRODUCTION_ENTRY}; `pnpm start` runs it
+ * with plain `node` — no tsx, no TypeScript at runtime. A Prisma client, when
+ * there is one, is generated OUTSIDE `src/` (`generated/prisma`) and imported
+ * through the package.json `imports` alias `#db/*`, so it resolves the same
+ * from `src/` (tsx) and from `dist/src/` (node).
+ */
+/** The compiled server entry the Dockerfile runs and the scaffold's `start` script points at. */
+export declare const PRODUCTION_ENTRY = "dist/src/server.js";
+/** Multi-stage production image: build with the dev toolchain, run on plain node as a non-root user. */
+export declare const DOCKERFILE = "# syntax=docker/dockerfile:1\n# Production image for a Basalt app (the create-basalt layout): `pnpm build`\n# compiles src/ to dist/ and the image runs dist/src/server.js on plain\n# node \u2014 no tsx, no TypeScript at runtime.\n#\n#   docker build -t my-app .\n#   docker run -p 3000:3000 -e APP_SECRET=\u2026 -e DATABASE_URL=\u2026 my-app\n#\n# Configuration comes from the environment (nothing loads .env here, and\n# .dockerignore keeps it out of the image). Database migrations are NOT run\n# by the image: apply them before rolling out (`pnpm db:deploy` in CI).\n#\n# Installs with pnpm from pnpm-lock.yaml. An app on npm/yarn/bun replaces the\n# pnpm install / exec / run / prune lines with its own package manager's.\nARG NODE_VERSION=22\nARG PNPM_VERSION=11\n\nFROM node:${NODE_VERSION}-slim AS build\nARG PNPM_VERSION\n# Non-interactive pnpm: without it `pnpm prune` in a workspace (a --ui app's\n# web/) aborts with ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY.\nENV CI=true\nWORKDIR /app\nRUN npm install -g pnpm@${PNPM_VERSION}\nCOPY . .\n# Full install: the build needs the devDependencies (typescript, prisma).\nRUN pnpm install --frozen-lockfile\n# The Prisma client (when the app has a schema) is generated into ./generated.\nRUN if [ -f prisma/schema.prisma ]; then pnpm exec prisma generate; fi && mkdir -p generated\nRUN pnpm run build\n# Drop the devDependencies (tsx, typescript, prisma CLI, generators, the AI\n# bridge): none of them may ship. --ignore-scripts keeps the app's postinstall\n# (`prisma generate`, a dev tool) from running again.\nRUN pnpm prune --prod --ignore-scripts\n\nFROM node:${NODE_VERSION}-slim AS run\nENV NODE_ENV=production\nENV PORT=3000\n# Path the HEALTHCHECK probes: the scaffold's /health route by default; set\n# /readyz when the app registers healthPlugin().\nENV HEALTHCHECK_PATH=/health\nWORKDIR /app\nCOPY --from=build --chown=node:node /app/package.json ./package.json\nCOPY --from=build --chown=node:node /app/node_modules ./node_modules\nCOPY --from=build --chown=node:node /app/generated ./generated\nCOPY --from=build --chown=node:node /app/dist ./dist\nUSER node\nEXPOSE 3000\nHEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \\\n  CMD node -e \"fetch('http://127.0.0.1:' + (process.env.PORT || 3000) + process.env.HEALTHCHECK_PATH).then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))\"\nCMD [\"node\", \"--enable-source-maps\", \"dist/src/server.js\"]\n";
+/**
+ * Published with the Dockerfile: its \`COPY . .\` would otherwise bake \`.env\`,
+ * private keys and VCS metadata into an image layer. Every secret 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. \`dist\` is rebuilt inside the image.
+ */
+export declare const DOCKERIGNORE = "**/.env\n**/.env.*\n!**/.env.example\n**/.npmrc\n**/.git\n**/node_modules\n**/coverage\n**/*.log\n**/*.pem\n**/*.key\n**/*.p12\n**/*.pfx\n**/.DS_Store\ndist\n";
+/** GitHub Actions CI: install, typecheck, build (the production path), test. */
+export declare const CI_WORKFLOW = "name: ci\non:\n  push: { branches: [main] }\n  pull_request:\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      # Drop `with: version` if package.json declares a packageManager.\n      - uses: pnpm/action-setup@v4\n        with: { version: 11 }\n      - uses: actions/setup-node@v4\n        with: { node-version: 22, cache: pnpm }\n      - run: pnpm install --frozen-lockfile\n      - run: pnpm run typecheck\n      - run: pnpm run build\n      - run: pnpm run test\n";
+export declare const EDITORCONFIG = "root = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\ninsert_final_newline = true\nindent_style = space\nindent_size = 2\ntrim_trailing_whitespace = true\n";

package/dist/stubs.js

@@ -0,0 +1,122 @@
+/**
+ * The production stubs `basalt publish` copies into an app — the SINGLE source
+ * of truth. create-basalt ships the same files in every new scaffold and offers
+ * them from `create-basalt update`: its build copies this file verbatim to
+ * `packages/create-app/src/stubs.ts` (scripts/sync-stubs.mjs), and a test there
+ * fails if the copy drifts. Keep this module free of imports for that reason.
+ *
+ * The layout these stubs assume is the create-basalt scaffold's (BK-026):
+ * `pnpm build` runs `tsc -p tsconfig.build.json` (rootDir `.`, outDir `dist`),
+ * so `src/server.ts` compiles to {@link PRODUCTION_ENTRY}; `pnpm start` runs it
+ * with plain `node` — no tsx, no TypeScript at runtime. A Prisma client, when
+ * there is one, is generated OUTSIDE `src/` (`generated/prisma`) and imported
+ * through the package.json `imports` alias `#db/*`, so it resolves the same
+ * from `src/` (tsx) and from `dist/src/` (node).
+ */
+/** The compiled server entry the Dockerfile runs and the scaffold's `start` script points at. */
+export const PRODUCTION_ENTRY = 'dist/src/server.js';
+/** Multi-stage production image: build with the dev toolchain, run on plain node as a non-root user. */
+export const DOCKERFILE = `# syntax=docker/dockerfile:1
+# Production image for a Basalt app (the create-basalt layout): \`pnpm build\`
+# compiles src/ to dist/ and the image runs ${PRODUCTION_ENTRY} on plain
+# node — no tsx, no TypeScript at runtime.
+#
+#   docker build -t my-app .
+#   docker run -p 3000:3000 -e APP_SECRET=… -e DATABASE_URL=… my-app
+#
+# Configuration comes from the environment (nothing loads .env here, and
+# .dockerignore keeps it out of the image). Database migrations are NOT run
+# by the image: apply them before rolling out (\`pnpm db:deploy\` in CI).
+#
+# Installs with pnpm from pnpm-lock.yaml. An app on npm/yarn/bun replaces the
+# pnpm install / exec / run / prune lines with its own package manager's.
+ARG NODE_VERSION=22
+ARG PNPM_VERSION=11
+
+FROM node:\${NODE_VERSION}-slim AS build
+ARG PNPM_VERSION
+# Non-interactive pnpm: without it \`pnpm prune\` in a workspace (a --ui app's
+# web/) aborts with ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY.
+ENV CI=true
+WORKDIR /app
+RUN npm install -g pnpm@\${PNPM_VERSION}
+COPY . .
+# Full install: the build needs the devDependencies (typescript, prisma).
+RUN pnpm install --frozen-lockfile
+# The Prisma client (when the app has a schema) is generated into ./generated.
+RUN if [ -f prisma/schema.prisma ]; then pnpm exec prisma generate; fi && mkdir -p generated
+RUN pnpm run build
+# Drop the devDependencies (tsx, typescript, prisma CLI, generators, the AI
+# bridge): none of them may ship. --ignore-scripts keeps the app's postinstall
+# (\`prisma generate\`, a dev tool) from running again.
+RUN pnpm prune --prod --ignore-scripts
+
+FROM node:\${NODE_VERSION}-slim AS run
+ENV NODE_ENV=production
+ENV PORT=3000
+# Path the HEALTHCHECK probes: the scaffold's /health route by default; set
+# /readyz when the app registers healthPlugin().
+ENV HEALTHCHECK_PATH=/health
+WORKDIR /app
+COPY --from=build --chown=node:node /app/package.json ./package.json
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/generated ./generated
+COPY --from=build --chown=node:node /app/dist ./dist
+USER node
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \\
+  CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || 3000) + process.env.HEALTHCHECK_PATH).then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"
+CMD ["node", "--enable-source-maps", "${PRODUCTION_ENTRY}"]
+`;
+/**
+ * Published with the Dockerfile: its \`COPY . .\` would otherwise bake \`.env\`,
+ * private keys and VCS metadata into an image layer. Every secret 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. \`dist\` is rebuilt inside the image.
+ */
+export const DOCKERIGNORE = `**/.env
+**/.env.*
+!**/.env.example
+**/.npmrc
+**/.git
+**/node_modules
+**/coverage
+**/*.log
+**/*.pem
+**/*.key
+**/*.p12
+**/*.pfx
+**/.DS_Store
+dist
+`;
+/** GitHub Actions CI: install, typecheck, build (the production path), test. */
+export const CI_WORKFLOW = `name: ci
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Drop \`with: version\` if package.json declares a packageManager.
+      - uses: pnpm/action-setup@v4
+        with: { version: 11 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run typecheck
+      - run: pnpm run build
+      - run: pnpm run test
+`;
+export const EDITORCONFIG = `root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -18,7 +18,8 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.5.0"
+    "@basaltkit/core": "^1.6.0",
+    "@basaltkit/http": "^2.8.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.1",