@nage-api/cli 1.0.0-beta.2

package/dist/templates/app.template.js

@@ -0,0 +1,601 @@
+"use strict";
+/**
+ * Files for one application (PLAN.md §9.1, §10.2).
+ *
+ * Four presets, one shape: a thin `main.ts` that calls `bootstrap`, a typed
+ * `nage.config.ts`, a zod env schema, health endpoints and a Dockerfile. What
+ * differs between presets is which modules are imported and whether an HTTP
+ * server is started at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.featurePackage = featurePackage;
+exports.isHttpPreset = isHttpPreset;
+exports.appFiles = appFiles;
+const naming_js_1 = require("../naming.js");
+const workspace_template_js_1 = require("./workspace.template.js");
+/** npm packages an enabled feature pulls in. */
+const FEATURE_PACKAGES = {
+    auth: '@nage-api/auth',
+    cache: '@nage-api/cache',
+    queue: '@nage-api/queue',
+    storage: '@nage-api/storage',
+    realtime: '@nage-api/realtime',
+    notify: '@nage-api/notify',
+    observability: '@nage-api/observability',
+};
+function featurePackage(feature) {
+    return FEATURE_PACKAGES[feature];
+}
+/** A worker has no HTTP surface, so it neither binds a port nor gets CORS. */
+function isHttpPreset(preset) {
+    return preset !== 'worker';
+}
+function appFiles(input) {
+    const { app, manifest } = input;
+    const base = `apps/${app.name}`;
+    const names = (0, naming_js_1.deriveNames)(app.name);
+    const version = manifest.frameworkVersion;
+    const http = isHttpPreset(app.preset);
+    const files = [
+        {
+            path: `${base}/package.json`,
+            contents: (0, workspace_template_js_1.json)({
+                name: `@${manifest.name}/${app.name}`,
+                version: '0.0.0',
+                private: true,
+                type: 'commonjs',
+                main: 'dist/main.js',
+                scripts: {
+                    build: 'tsc -b tsconfig.build.json',
+                    dev: 'node --watch --enable-source-maps dist/main.js',
+                    typecheck: 'tsc -p tsconfig.json --noEmit',
+                    test: 'vitest run',
+                },
+                dependencies: {
+                    '@nage-api/core': version,
+                    '@nage-api/config': version,
+                    '@nage-api/data': version,
+                    [(0, workspace_template_js_1.driverPackageFor)(manifest.engine)]: version,
+                    ...Object.fromEntries(app.features.map((feature) => [featurePackage(feature), version])),
+                    '@nestjs/common': '^11.0.0',
+                    '@nestjs/core': '^11.0.0',
+                    // `NestFactory.create` and `createNestApplication` both need an HTTP
+                    // adapter. Without it the app cannot boot and the generated e2e spec
+                    // cannot start a server, so it is a dependency and not a suggestion.
+                    '@nestjs/platform-express': '^11.0.0',
+                    'class-transformer': '^0.5.1',
+                    'class-validator': '^0.15.0',
+                    'reflect-metadata': '^0.2.0',
+                    rxjs: '^7.8.0',
+                    // A peer dependency of the SQL driver, which means this package is the
+                    // one that has to supply it.
+                    ...(manifest.engine === 'mongodb' ? {} : { sequelize: '^6.37.0' }),
+                    zod: '^4.0.0',
+                },
+                devDependencies: {
+                    '@nestjs/testing': '^11.0.0',
+                    // The generated tsconfig sets `types: ['node']`, and the e2e spec
+                    // imports `supertest`: both need their type packages present or the
+                    // app does not typecheck as generated.
+                    '@types/node': '^22.0.0',
+                    '@types/supertest': '^7.0.0',
+                    // Vitest transforms with esbuild by default, which does not emit
+                    // `design:paramtypes` — the metadata NestJS DI reads. Every generated
+                    // resource injects something, so the SWC transform is required rather
+                    // than an optimisation. See vitest.config.mts below.
+                    '@swc/core': '^1.15.0',
+                    supertest: '^7.0.0',
+                    typescript: '5.9.3',
+                    'unplugin-swc': '^1.5.0',
+                    vitest: '4.1.10',
+                },
+            }),
+        },
+        {
+            path: `${base}/tsconfig.json`,
+            contents: (0, workspace_template_js_1.json)({
+                extends: '../../tsconfig.base.json',
+                compilerOptions: { noEmit: true, types: ['node'] },
+                // The vitest config is included so the generated ESLint config can lint
+                // it: a TypeScript file that belongs to no project is a hard parsing
+                // error under type-aware rules, not a skipped file.
+                include: ['src/**/*.ts', 'test/**/*.ts', 'vitest.config.mts'],
+            }),
+        },
+        {
+            path: `${base}/tsconfig.build.json`,
+            contents: (0, workspace_template_js_1.json)({
+                extends: '../../tsconfig.base.json',
+                compilerOptions: { composite: true, rootDir: 'src', outDir: 'dist', types: ['node'] },
+                include: ['src/**/*.ts'],
+            }),
+        },
+        { path: `${base}/vitest.config.mts`, contents: vitestConfig() },
+        { path: `${base}/src/main.ts`, contents: mainFile(app) },
+        { path: `${base}/src/app.module.ts`, contents: appModule(app, names.pascal) },
+        { path: `${base}/src/config/env.schema.ts`, contents: envSchema(app, manifest.engine) },
+        { path: `${base}/src/config/nage.config.ts`, contents: nageConfig(app, manifest) },
+        // No `.dockerignore` beside it: the build context is the workspace root, and
+        // that is the only directory Docker reads one from. See the root
+        // `.dockerignore` in workspace.template.ts.
+        { path: `${base}/Dockerfile`, contents: dockerfile(app, manifest) },
+    ];
+    if (http) {
+        files.push({ path: `${base}/src/health/health.controller.ts`, contents: healthController() }, { path: `${base}/src/health/health.module.ts`, contents: healthModule() }, { path: `${base}/test/health.e2e-spec.ts`, contents: healthSpec(app) });
+    }
+    else {
+        files.push({ path: `${base}/test/worker.spec.ts`, contents: workerSpec(names.pascal) });
+    }
+    return files;
+}
+/**
+ * The app's Vitest configuration.
+ *
+ * Two things it must get right, both of which the framework learned the hard
+ * way and neither of which is Vitest's default:
+ *
+ *  - **SWC, not esbuild.** NestJS DI and `ValidationPipe` read
+ *    `design:paramtypes`, which esbuild does not emit. Every generated resource
+ *    injects a repository and a unit of work, so a suite on the default
+ *    transform fails with "Nest can't resolve dependencies" the first time a
+ *    resource is generated.
+ *  - **the `-spec.ts` suffix.** Vitest's default `include` matches `*.spec.ts`
+ *    but not `*.e2e-spec.ts`, so an app whose only test is an e2e spec exits 1
+ *    with "No test files found".
+ */
+function vitestConfig() {
+    return [
+        "import swc from 'unplugin-swc';",
+        "import { defineConfig } from 'vitest/config';",
+        '',
+        'export default defineConfig({',
+        '  plugins: [',
+        '    swc.vite({',
+        "      module: { type: 'es6' },",
+        '      jsc: {',
+        "        target: 'es2022',",
+        "        parser: { syntax: 'typescript', decorators: true },",
+        '        transform: { legacyDecorator: true, decoratorMetadata: true },',
+        '      },',
+        '    }),',
+        '  ],',
+        '  test: {',
+        "    environment: 'node',",
+        "    include: ['src/**/*.spec.ts', 'src/**/*-spec.ts', 'test/**/*.spec.ts', 'test/**/*-spec.ts'],",
+        '  },',
+        '});',
+        '',
+    ].join('\n');
+}
+function mainFile(app) {
+    const http = isHttpPreset(app.preset);
+    const imports = http
+        ? 'bootstrap'
+        : 'createApplication, installProcessGuards, installShutdown, JsonLogger';
+    return [
+        "import 'reflect-metadata';",
+        '',
+        `import { ${imports} } from '@nage-api/core';`,
+        "import { loadEnvOrExit } from '@nage-api/config';",
+        '',
+        "import { AppModule } from './app.module.js';",
+        "import { EnvSchema } from './config/env.schema.js';",
+        "import { buildConfig } from './config/nage.config.js';",
+        '',
+        '// Invalid configuration exits non-zero here, before a port is bound.',
+        'const env = loadEnvOrExit(EnvSchema);',
+        '',
+        http
+            ? [
+                '// `bootstrap` installs the signal handlers and the fatal-error policy:',
+                '// SIGTERM fails readiness, drains in-flight requests, then closes pools',
+                "// (§21). Nest's own `enableShutdownHooks()` does those in the opposite",
+                '// order and is deliberately not used.',
+                'void bootstrap({ module: AppModule, config: buildConfig(env) });',
+            ].join('\n')
+            : [
+                '// A worker consumes jobs; it starts no HTTP listener, so it wires the same',
+                '// shutdown sequence by hand. There is nothing to drain, but the deadline and',
+                '// the ordered `app.close()` still matter: a job handler mid-flight is exactly',
+                '// what a queue driver must be allowed to finish (§21).',
+                'async function main(): Promise<void> {',
+                '  const config = buildConfig(env);',
+                '  const app = await createApplication({ module: AppModule, config });',
+                '  await app.init();',
+                '',
+                '  const logger = new JsonLogger(undefined, config);',
+                '  const shutdown = installShutdown(app, { config, logger });',
+                '  installProcessGuards({',
+                '    logger,',
+                "    onFatal: async () => { await shutdown.run('fatal-error'); },",
+                '  });',
+                '}',
+                '',
+                'void main();',
+            ].join('\n'),
+        '',
+    ].join('\n');
+}
+function appModule(app, pascal) {
+    const imports = [
+        'NageCoreModule.forRoot(config)',
+        'NageConfigModule.forRoot({ config, envSchema: EnvSchema })',
+    ];
+    if (isHttpPreset(app.preset))
+        imports.push('HealthModule');
+    return [
+        "import { Module } from '@nestjs/common';",
+        "import { NageCoreModule } from '@nage-api/core';",
+        "import { NageConfigModule } from '@nage-api/config';",
+        '',
+        "import { EnvSchema } from './config/env.schema.js';",
+        "import { buildConfig } from './config/nage.config.js';",
+        ...(isHttpPreset(app.preset)
+            ? ["import { HealthModule } from './health/health.module.js';"]
+            : []),
+        '',
+        'const config = buildConfig(EnvSchema.parse(process.env));',
+        '',
+        '@Module({',
+        `  imports: [${imports.join(', ')}],`,
+        '})',
+        `export class ${pascal}AppModule {}`,
+        '',
+        '// Exported under a stable name so main.ts does not change when the app is renamed.',
+        `export { ${pascal}AppModule as AppModule };`,
+        '',
+    ].join('\n');
+}
+function envSchema(app, engine) {
+    const lines = [
+        "import { baseEnvSchema } from '@nage-api/config';",
+        "import { z } from 'zod';",
+        '',
+        '/**',
+        ' * Every variable this app reads, validated once at boot.',
+        ' * A missing or malformed value stops the process instead of surfacing later.',
+        ' */',
+        'export const EnvSchema = baseEnvSchema.extend({',
+        // SQLite's "URL" is a file path, so `z.url()` would reject every valid value.
+        engine === 'sqlite'
+            ? '  DATABASE_URL: z.string().min(1), // file path, e.g. ./database/dev.sqlite'
+            : '  DATABASE_URL: z.url(),',
+    ];
+    if (isHttpPreset(app.preset)) {
+        lines.push(`  PORT: z.coerce.number().int().min(1).max(65535).default(${String(app.port)}),`);
+    }
+    if (app.features.includes('auth')) {
+        // `@nage-api/auth` needs a signing pair plus one pepper per stored credential
+        // type; every one of them is a secret with no usable default, so the app
+        // refuses to boot without them rather than inventing one.
+        lines.push('  JWT_PRIVATE_KEY: z.string().min(16),', '  JWT_PUBLIC_KEY: z.string().min(16),', '  PASSWORD_PEPPER: z.string().min(16),', '  SESSION_PEPPER: z.string().min(16),', '  OTP_PEPPER: z.string().min(16),');
+    }
+    if (app.features.includes('cache') || app.features.includes('queue')) {
+        lines.push('  REDIS_URL: z.url(),');
+    }
+    lines.push('});', '', 'export type Env = z.infer<typeof EnvSchema>;', '');
+    return lines.join('\n');
+}
+function nageConfig(app, manifest) {
+    const features = app.features.map((feature) => `    ${feature}: { enabled: true },`).join('\n');
+    return [
+        "import { defineConfig } from '@nage-api/config';",
+        "import type { NageConfig } from '@nage-api/core';",
+        '',
+        "import type { Env } from './env.schema.js';",
+        '',
+        '/** Committed, typed configuration. Secrets come from the environment. */',
+        'export function buildConfig(env: Env): NageConfig {',
+        '  return defineConfig({',
+        '    app: {',
+        `      name: '${app.name}',`,
+        '      environment: env.NODE_ENV,',
+        ...(isHttpPreset(app.preset) ? ['      port: env.PORT,'] : []),
+        '    },',
+        ...(isHttpPreset(app.preset)
+            ? [
+                '    http: {',
+                '      // Omitting `cors` disables it; an allow-list is required to enable it.',
+                '      ...(env.CORS_ORIGINS === undefined ? {} : { cors: { origins: env.CORS_ORIGINS } }),',
+                '    },',
+            ]
+            : []),
+        '    database: {',
+        '      enabled: true,',
+        `      driver: '${manifest.engine}',`,
+        '      url: env.DATABASE_URL,',
+        "      ssl: 'verify-full',",
+        '    },',
+        ...(features === '' ? [] : [features]),
+        '  });',
+        '}',
+        '',
+    ].join('\n');
+}
+function healthController() {
+    return [
+        "import { Controller, Get, HttpStatus, Inject, Optional, Res } from '@nestjs/common';",
+        "import { NAGE_LIFECYCLE, NoEnvelope, Public, SkipRateLimit } from '@nage-api/core';",
+        // The contract types are re-exported by @nage-api/core, so the app needs no
+        // direct dependency on @nage-api/contracts.
+        "import type { DataSourceHealth, LifecycleState } from '@nage-api/core';",
+        "import { NAGE_DATA_HEALTH } from '@nage-api/data';",
+        '',
+        '/**',
+        ' * Liveness and readiness (PLAN.md §21).',
+        ' *',
+        ' * Both are public, exempt from throttling (an orchestrator polls them every',
+        ' * few seconds) and unwrapped, because probes expect an exact body.',
+        ' *',
+        ' * They must not mean the same thing. **Liveness** answers "is this process',
+        ' * wedged?" and never touches a dependency: if a database blip failed liveness,',
+        ' * the orchestrator would restart every instance and turn a degraded system into',
+        ' * an outage. **Readiness** answers "should traffic come here?", so it fails when',
+        ' * the database is unreachable and as soon as a shutdown signal arrives — a',
+        ' * draining process is about to close the connection it is being offered.',
+        ' *',
+        ' * The database probe is optional injection: it appears once a driver module is',
+        ' * registered, and until then there is nothing to check. Add a probe per',
+        ' * dependency you cannot serve without; for several, `@nage-api/observability`',
+        ' * ships a registry that runs them concurrently under a timeout.',
+        ' */',
+        "@Controller('health')",
+        'export class HealthController {',
+        '  constructor(',
+        '    @Optional() @Inject(NAGE_LIFECYCLE) private readonly lifecycle?: LifecycleState,',
+        '    @Optional() @Inject(NAGE_DATA_HEALTH) private readonly database?: DataSourceHealth,',
+        '  ) {}',
+        '',
+        "  @Get('live')",
+        '  @Public()',
+        '  @SkipRateLimit()',
+        '  @NoEnvelope()',
+        "  live(): { status: 'ok' } {",
+        '    // No dependency checks, and no lifecycle check either: a draining process',
+        '    // is healthy, and failing liveness while it drains gets it killed.',
+        "    return { status: 'ok' };",
+        '  }',
+        '',
+        "  @Get('ready')",
+        '  @Public()',
+        '  @SkipRateLimit()',
+        '  @NoEnvelope()',
+        '  async ready(',
+        '    @Res({ passthrough: true }) response: { statusCode?: number },',
+        '  ): Promise<{ status: string; checks: { name: string; status: string }[] }> {',
+        '    if (this.lifecycle?.draining === true) {',
+        '      response.statusCode = HttpStatus.SERVICE_UNAVAILABLE;',
+        "      return { status: 'draining', checks: [] };",
+        '    }',
+        '',
+        '    const checks: { name: string; status: string }[] = [];',
+        '    if (this.database !== undefined) {',
+        '      const up = await this.database.ping();',
+        "      checks.push({ name: this.database.driver, status: up ? 'up' : 'down' });",
+        '      if (!up) response.statusCode = HttpStatus.SERVICE_UNAVAILABLE;',
+        '    }',
+        '',
+        "    const down = checks.some((check) => check.status === 'down');",
+        "    return { status: down ? 'down' : 'up', checks };",
+        '  }',
+        '}',
+        '',
+    ].join('\n');
+}
+function healthModule() {
+    return [
+        "import { Module } from '@nestjs/common';",
+        '',
+        "import { HealthController } from './health.controller.js';",
+        '',
+        '@Module({ controllers: [HealthController] })',
+        'export class HealthModule {}',
+        '',
+    ].join('\n');
+}
+function healthSpec(app) {
+    return [
+        "import 'reflect-metadata';",
+        '',
+        "import { afterEach, describe, expect, it } from 'vitest';",
+        "import { Test } from '@nestjs/testing';",
+        "import type { INestApplication } from '@nestjs/common';",
+        "import { LifecycleState, NAGE_LIFECYCLE } from '@nage-api/core';",
+        "import { NAGE_DATA_HEALTH } from '@nage-api/data';",
+        "import request from 'supertest';",
+        '',
+        "import { HealthController } from '../src/health/health.controller.js';",
+        '',
+        '/**',
+        ' * The probes must not mean the same thing (PLAN.md §21): a dependency being',
+        ' * down has to fail readiness and leave liveness alone, or an orchestrator',
+        ' * restarts every healthy instance during a database blip.',
+        ' *',
+        ' * The controller is declared directly rather than through `HealthModule`, so',
+        ' * these tests can bind the probes it injects optionally.',
+        ' */',
+        `describe('${app.name} health', () => {`,
+        '  let app: INestApplication | undefined;',
+        '',
+        '  async function boot(providers: NonNullable<',
+        "    Parameters<typeof Test.createTestingModule>[0]['providers']",
+        '  > = []): Promise<INestApplication> {',
+        '    const moduleRef = await Test.createTestingModule({',
+        '      controllers: [HealthController],',
+        '      providers,',
+        '    }).compile();',
+        '    app = moduleRef.createNestApplication();',
+        '    await app.init();',
+        '    return app;',
+        '  }',
+        '',
+        '  afterEach(async () => {',
+        '    await app?.close();',
+        '    app = undefined;',
+        '  });',
+        '',
+        "  it('should report liveness without touching a dependency', async () => {",
+        '    const booted = await boot([',
+        '      {',
+        '        provide: NAGE_DATA_HEALTH,',
+        "        useValue: { driver: 'sql:test', ping: () => Promise.resolve(false) },",
+        '      },',
+        '    ]);',
+        '',
+        "    await request(booted.getHttpServer()).get('/health/live').expect(200, { status: 'ok' });",
+        '  });',
+        '',
+        "  it('should report readiness when there is nothing to check', async () => {",
+        '    const booted = await boot();',
+        '',
+        "    const response = await request(booted.getHttpServer()).get('/health/ready').expect(200);",
+        "    expect(response.body).toEqual({ status: 'up', checks: [] });",
+        '  });',
+        '',
+        "  it('should fail readiness when the database is unreachable', async () => {",
+        '    const booted = await boot([',
+        '      {',
+        '        provide: NAGE_DATA_HEALTH,',
+        "        useValue: { driver: 'sql:test', ping: () => Promise.resolve(false) },",
+        '      },',
+        '    ]);',
+        '',
+        "    const response = await request(booted.getHttpServer()).get('/health/ready').expect(503);",
+        "    expect(response.body).toMatchObject({ status: 'down' });",
+        '  });',
+        '',
+        "  it('should fail readiness while the process is draining', async () => {",
+        '    // SIGTERM has arrived: the instance still serves what it accepted, but it',
+        '    // must stop being sent anything new.',
+        '    const lifecycle = new LifecycleState();',
+        '    const booted = await boot([{ provide: NAGE_LIFECYCLE, useValue: lifecycle }]);',
+        '',
+        "    await request(booted.getHttpServer()).get('/health/ready').expect(200);",
+        '    lifecycle.markDraining();',
+        '',
+        "    const response = await request(booted.getHttpServer()).get('/health/ready').expect(503);",
+        "    expect(response.body).toMatchObject({ status: 'draining' });",
+        "    await request(booted.getHttpServer()).get('/health/live').expect(200, { status: 'ok' });",
+        '  });',
+        '});',
+        '',
+    ].join('\n');
+}
+function workerSpec(pascal) {
+    return [
+        "import { describe, expect, it } from 'vitest';",
+        '',
+        "import { buildConfig } from '../src/config/nage.config.js';",
+        '',
+        `describe('${pascal} worker', () => {`,
+        "  it('should build a valid configuration', () => {",
+        '    const config = buildConfig({',
+        "      NODE_ENV: 'test',",
+        "      DATABASE_URL: 'postgres://localhost:5432/app',",
+        "      HOST: '0.0.0.0',",
+        "      LOG_LEVEL: 'info',",
+        '    } as never);',
+        '',
+        '    expect(config.database?.enabled).toBe(true);',
+        '  });',
+        '});',
+        '',
+    ].join('\n');
+}
+/**
+ * The app's Dockerfile: multi-stage, non-root, init as PID 1 (PLAN.md §21).
+ *
+ * Every line below that looks removable was a defect first. The first version of
+ * this template built an image that could not start — it copied the workspace
+ * root's `node_modules`, which in a pnpm workspace holds the *root's* dev
+ * tooling and the virtual store and none of the app's own dependencies, so
+ * `node dist/main.js` died on `Cannot find module 'reflect-metadata'` — and it
+ * ran node as PID 1, where SIGTERM is discarded rather than delivered.
+ */
+function dockerfile(app, manifest) {
+    // pnpm addresses workspace members by package name, not by directory.
+    const pkg = `@${manifest.name}/${app.name}`;
+    return [
+        '# Multi-stage build, non-root runtime, an init as PID 1 (PLAN.md §21).',
+        '#',
+        '# Build from the workspace root, never from this directory — the lockfile and',
+        '# every workspace package this app imports live above it:',
+        '#',
+        `#     docker build -f apps/${app.name}/Dockerfile -t ${app.name} .`,
+        '',
+        '# Dependencies. `pnpm fetch` resolves from the lockfile alone and reads no',
+        '# package.json, so this — the only layer that needs the network — is',
+        '# invalidated when a dependency changes and not when a source file does. The',
+        '# root manifest comes with it for its `packageManager` field: without that,',
+        '# corepack installs whatever pnpm is newest and the build stops being',
+        '# reproducible.',
+        'FROM node:22-alpine AS deps',
+        'WORKDIR /workspace',
+        'RUN corepack enable',
+        'COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./',
+        'RUN pnpm fetch',
+        '',
+        '# Build. `--offline` keeps every layer below the fetch off the network, so a',
+        '# lockfile missing an entry fails here rather than being quietly resolved;',
+        '# `--frozen-lockfile` refuses to rewrite the lockfile rather than building',
+        '# something the repository never described.',
+        'FROM deps AS build',
+        'COPY . .',
+        'RUN pnpm install --frozen-lockfile --offline',
+        `RUN pnpm --filter ${pkg} build`,
+        "# `deploy` flattens pnpm's symlink farm into one self-contained tree and",
+        '# `--prod` leaves the devDependencies behind, so the runtime stage inherits no',
+        '# compiler, test runner or linter: ~70 MB of dependencies instead of ~310 MB.',
+        '# It is self-contained only because the workspace sets',
+        '# `injectWorkspacePackages` — without it pnpm links `@app/*` dependencies to',
+        '# paths outside /deploy, and copying the tree into the runtime stage yields',
+        '# dangling symlinks and a container that exits on its first require.',
+        `RUN pnpm --filter ${pkg} deploy --prod --offline /deploy`,
+        '',
+        '# Runtime. A fresh stage from the base image, so nothing above it — pnpm, the',
+        '# store, the sources, the lockfile — is reachable from the shipped image.',
+        'FROM node:22-alpine AS runtime',
+        '# tini as PID 1, because PID 1 is exempt from default signal dispositions: the',
+        '# kernel discards any signal the process has installed no handler for. Node',
+        '# gets its SIGTERM listener when `bootstrap` calls `installShutdown`, so a',
+        '# SIGTERM arriving before that — an aborted rolling deploy, a crash loop being',
+        '# stopped — is dropped, and the orchestrator waits out its entire grace period',
+        '# before SIGKILL. Graceful shutdown (§21) is worth nothing if PID 1 never sees',
+        '# the signal. tini also reaps the orphans PID 1 inherits, which otherwise',
+        '# accumulate as zombies for the life of the container.',
+        'RUN apk add --no-cache tini',
+        'WORKDIR /app',
+        'ENV NODE_ENV=production',
+        '# Copied as root and run as `node`: the runtime user can read and execute the',
+        '# application but cannot rewrite it, so code that reaches the process cannot',
+        '# persist itself by patching dist/ or node_modules.',
+        'COPY --from=build /deploy/node_modules ./node_modules',
+        '# The deployed manifest, so `type` and `main` are declared rather than inferred.',
+        'COPY --from=build /deploy/package.json ./package.json',
+        `COPY --from=build /workspace/apps/${app.name}/dist ./dist`,
+        'USER node',
+        ...(isHttpPreset(app.preset)
+            ? [
+                `EXPOSE ${String(app.port)}`,
+                '# `/health/live`, never `/health/ready` (§21). Liveness answers "is this',
+                '# process broken"; readiness answers "should traffic come here" and goes',
+                "# false while a dependency reconnects. Docker's answer to an unhealthy",
+                '# container under a restart policy is to kill it, so probing readiness',
+                '# would restart an app whose only fault was a database briefly away —',
+                '# destroying the in-flight requests shutdown hooks exist to drain.',
+                '# Three misses at 30s is ~90s of confirmed failure before the container is',
+                '# called unhealthy; --start-period keeps a slow boot out of that count and',
+                '# --timeout stops one hung request from holding the probe for 30s.',
+                'HEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \\',
+                `  CMD wget -qO- http://127.0.0.1:${String(app.port)}/health/live || exit 1`,
+            ]
+            : [
+                '# No healthcheck: a worker has no HTTP surface to probe. Its liveness is',
+                "# the queue's to report (§21), not this container's.",
+            ]),
+        'ENTRYPOINT ["/sbin/tini", "--"]',
+        'CMD ["node", "dist/main.js"]',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=app.template.js.map

package/dist/templates/resource.template.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `nage g resource product` (PLAN.md §10.3).
+ *
+ * One command produces a live, secured, paginated REST resource: entity,
+ * service, controller, DTOs, migration and tests, wired into the target app.
+ * The point is that it inherits capability rather than copying code — the
+ * service extends `ModelService`, so the list DSL, pagination envelope, soft
+ * delete and audit fields come from the framework, not from generated
+ * boilerplate a developer then has to maintain.
+ */
+import type { DatabaseDriver } from '@nage-api/contracts';
+import type { PlannedFile } from '../fs/file-tree.js';
+/** A column declared with `--fields "name:string,slug:string:unique"`. */
+export interface FieldSpec {
+    readonly name: string;
+    readonly type: 'string' | 'number' | 'boolean' | 'date' | 'text' | 'json';
+    readonly unique: boolean;
+    readonly optional: boolean;
+}
+export interface ResourceTemplateInput {
+    readonly name: string;
+    readonly appName: string;
+    readonly engine: DatabaseDriver;
+    readonly fields: readonly FieldSpec[];
+    /** Base route; defaults to the plural kebab name. */
+    readonly route?: string;
+    readonly withMigration?: boolean;
+    readonly withSpec?: boolean;
+    /** Emit the entity into a shared package instead of the app. */
+    readonly entityPackage?: string;
+    /** Injected so a generated migration id is deterministic in tests. */
+    readonly timestamp?: string;
+}
+/** Parse `--fields "name:string,slug:string:unique,note:text:optional"`. */
+export declare function parseFields(raw: string | undefined): FieldSpec[];
+export declare function resourceFiles(input: ResourceTemplateInput): PlannedFile[];
+/** `20260814T134512` — sorts chronologically and reads as a date. */
+export declare function compactTimestamp(now?: Date): string;
+//# sourceMappingURL=resource.template.d.ts.map