@nage-api/cli 1.0.0-beta.2

package/dist/templates/workspace.template.js

@@ -0,0 +1,457 @@
+"use strict";
+/**
+ * Workspace-level files emitted by `nage create` (PLAN.md §9.1).
+ *
+ * The generated workspace is monorepo-first: one lockfile, one CI pipeline, one
+ * set of tooling, seeded with a single app so the simple case stays simple.
+ * Everything here is production-shaped from the first commit — strict TypeScript,
+ * a CI workflow, Docker, and a `.env.example` documenting every variable — because
+ * retrofitting those onto a project that started loose rarely happens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.driverPackageFor = driverPackageFor;
+exports.workspaceFiles = workspaceFiles;
+exports.json = json;
+const manifest_js_1 = require("../workspace/manifest.js");
+/** The driver package that matches the workspace engine (§14.1: one, never both). */
+function driverPackageFor(engine) {
+    return engine === 'mongodb' ? '@nage-api/data-mongo' : '@nage-api/data-sql';
+}
+function workspaceFiles(input) {
+    const { manifest } = input;
+    const version = manifest.frameworkVersion;
+    return [
+        { path: 'nage.workspace.json', contents: (0, manifest_js_1.serialiseManifest)(manifest) },
+        {
+            path: 'package.json',
+            contents: json({
+                name: manifest.name,
+                version: '0.0.0',
+                private: true,
+                packageManager: 'pnpm@10.33.0',
+                engines: { node: '>=22.0.0' },
+                scripts: {
+                    build: 'turbo run build',
+                    dev: 'turbo run dev',
+                    lint: 'turbo run build && eslint .',
+                    typecheck: 'turbo run typecheck',
+                    test: 'turbo run test',
+                    'db:migrate': 'nage db migrate',
+                    'db:seed': 'nage db seed',
+                    doctor: 'nage doctor',
+                },
+                devDependencies: {
+                    '@nage-api/cli': version,
+                    // `eslint.config.mjs` imports this; without it `pnpm lint` fails to
+                    // resolve the config before linting a single file.
+                    '@nage-api/eslint-config': version,
+                    '@types/node': '22.20.1',
+                    eslint: '10.8.1',
+                    prettier: '3.9.6',
+                    // Generated migrations live at the workspace root and import the
+                    // driver's own types, so the root — not just the app — has to declare
+                    // them. `sequelize` is a peer dependency of `@nage-api/data-sql`, which
+                    // means the consumer provides it.
+                    ...(manifest.engine === 'mongodb'
+                        ? {}
+                        : { [driverPackageFor(manifest.engine)]: version, sequelize: '^6.37.0' }),
+                    turbo: '2.10.9',
+                    typescript: '5.9.3',
+                    vitest: '4.1.10',
+                },
+            }),
+        },
+        {
+            path: 'pnpm-workspace.yaml',
+            contents: [
+                'packages:',
+                "  - 'apps/*'",
+                "  - 'packages/*'",
+                '',
+                '# Local packages are copied into the consumers that depend on them rather',
+                "# than symlinked, so `pnpm deploy` — which is how an app's Dockerfile builds",
+                '# its production node_modules — can produce a tree that stands on its own.',
+                '# Left symlinked, a deployed `@app/*` dependency is a link to a path that',
+                "# does not exist in the runtime stage, and the image dies on Node's",
+                '# `Cannot find module`. pnpm 10 also refuses to deploy at all without this.',
+                'injectWorkspacePackages: true',
+                '',
+                '# What that costs: a consumer holds a copy, so an edit to a local package is',
+                '# invisible to it until the copy is refreshed. Refreshing after `build` is',
+                '# enough, because `turbo run build` builds a dependency before its consumer.',
+                'syncInjectedDepsAfterScripts:',
+                '  - build',
+                '',
+            ].join('\n'),
+        },
+        {
+            path: 'turbo.json',
+            contents: json({
+                $schema: 'https://turbo.build/schema.json',
+                tasks: {
+                    build: { dependsOn: ['^build'], outputs: ['dist/**'] },
+                    dev: { cache: false, persistent: true },
+                    typecheck: { dependsOn: ['^build'], outputs: [] },
+                    test: { dependsOn: ['^build'], outputs: [] },
+                },
+            }),
+        },
+        {
+            path: 'tsconfig.base.json',
+            contents: json({
+                compilerOptions: {
+                    target: 'ES2023',
+                    lib: ['ES2023'],
+                    module: 'NodeNext',
+                    moduleResolution: 'NodeNext',
+                    // The same strictness the framework holds itself to (§13): a project
+                    // that starts strict stays strict, and one that does not, never does.
+                    strict: true,
+                    noUncheckedIndexedAccess: true,
+                    exactOptionalPropertyTypes: true,
+                    noImplicitOverride: true,
+                    useUnknownInCatchVariables: true,
+                    experimentalDecorators: true,
+                    emitDecoratorMetadata: true,
+                    declaration: true,
+                    sourceMap: true,
+                    skipLibCheck: true,
+                    paths: {},
+                },
+                exclude: ['**/node_modules', '**/dist'],
+            }),
+        },
+        { path: 'tsconfig.json', contents: json({ files: [], references: [] }) },
+        {
+            // Migrations and seeds are TypeScript, and under type-aware ESLint a file
+            // belonging to no project is a hard parsing error rather than a skip — so
+            // `nage generate resource` used to make `pnpm lint` fail on the migration it
+            // had just written.
+            //
+            // Deliberately *not* referenced from the solution `tsconfig.json` above: a
+            // fresh workspace has no migrations, and an empty `include` makes `tsc -b`
+            // fail with "No inputs were found". ESLint's project service finds this
+            // config by walking up from the file, which needs no reference.
+            path: 'database/tsconfig.json',
+            contents: json({
+                extends: '../tsconfig.base.json',
+                compilerOptions: { noEmit: true, types: ['node'] },
+                include: ['migrations/**/*.ts', 'seeds/**/*.ts'],
+            }),
+        },
+        {
+            path: '.gitignore',
+            contents: [
+                'node_modules/',
+                'dist/',
+                'coverage/',
+                '.turbo/',
+                '.env',
+                // A committed `tsbuildinfo` makes `tsc -b` believe an absent `dist` is
+                // already up to date, so a fresh checkout — or a Docker build — emits
+                // nothing and the image ships without its entry point.
+                '*.tsbuildinfo',
+                '*.log',
+                '',
+            ].join('\n'),
+        },
+        { path: '.dockerignore', contents: dockerIgnore() },
+        { path: '.nvmrc', contents: '22\n' },
+        {
+            path: '.env.example',
+            contents: envExample(manifest),
+        },
+        {
+            path: 'eslint.config.mjs',
+            contents: [
+                "import nage from '@nage-api/eslint-config';",
+                '',
+                'export default nage({ tsconfigRootDir: import.meta.dirname });',
+                '',
+            ].join('\n'),
+        },
+        {
+            path: '.prettierrc.json',
+            contents: json({ singleQuote: true, semi: true, trailingComma: 'all', printWidth: 100 }),
+        },
+        // SQLite is a file, not a server: a compose file with a database service in
+        // it would be a lie, and one with no services is not a valid compose file.
+        ...(manifest.engine === 'sqlite'
+            ? []
+            : [{ path: 'docker-compose.yml', contents: dockerCompose(manifest.engine) }]),
+        {
+            path: '.github/workflows/ci.yml',
+            contents: workspaceCi(),
+        },
+        {
+            path: 'database/migrations/.gitkeep',
+            contents: '',
+        },
+        { path: 'database/seeds/.gitkeep', contents: '' },
+        { path: 'README.md', contents: readme(manifest) },
+    ];
+}
+function envExample(manifest) {
+    const lines = [
+        '# Every variable the workspace reads. `nage doctor` checks this file is current.',
+        'NODE_ENV=development',
+        '',
+        '# Comma-separated allow-list. Omit to disable CORS entirely (the safe default).',
+        'CORS_ORIGINS=http://localhost:3000',
+        '',
+    ];
+    if (manifest.engine === 'mongodb') {
+        lines.push('DATABASE_URL=mongodb://localhost:27017/app', '');
+    }
+    else {
+        lines.push(`DATABASE_URL=${manifest.engine}://app:app@localhost:5432/app`, '');
+    }
+    for (const app of manifest.apps) {
+        lines.push(`# ${app.name}`, `${app.name.toUpperCase()}_PORT=${String(app.port)}`, '');
+    }
+    return lines.join('\n');
+}
+/**
+ * What must never reach a build layer.
+ *
+ * Read from the context root — the workspace root, which is where a build has to
+ * start (`docker build -f apps/<app>/Dockerfile .`). A file named
+ * `apps/<app>/.dockerignore` is read by no builder: the classic one looks only at
+ * the context root, and BuildKit additionally accepts
+ * `apps/<app>/Dockerfile.dockerignore` but not that. That is how the first
+ * version of this template shipped a build stage with the developer's `.env`
+ * inside it — verified by reading the file back out of the build layer.
+ */
+function dockerIgnore() {
+    return [
+        '# Read from the build context root, which is the only place Docker looks.',
+        '#',
+        '# Every pattern is `**/`-prefixed because these are not recursive otherwise:',
+        "# a bare `node_modules` excludes the workspace root's and leaves",
+        '# `apps/*/node_modules` — and `apps/*/.env` — in the context. That is measured,',
+        '# not assumed: without the prefix a probe of the build context still finds',
+        '# `apps/<app>/dist`, `apps/<app>/node_modules` and the stale tsbuildinfo.',
+        '#',
+        '# `.env` first, because it is the file here that must never reach a layer:',
+        '# `.gitignore` keeps it out of the repository but not out of the build',
+        '# context, and `COPY . .` in the build stage would bake live credentials into',
+        '# an image whose layers and build cache outlive the container.',
+        '**/.env',
+        '**/.env.*',
+        '**/*.pem',
+        '**/*.key',
+        '',
+        '# Never copied in, always produced inside the image: a stale `dist` or',
+        '# `tsbuildinfo` from the host makes `tsc -b` treat an absent `dist` as up to',
+        '# date and emit nothing, and the host `node_modules` is a symlink farm built',
+        "# against the host's paths and platform.",
+        '**/node_modules',
+        '**/dist',
+        '**/*.tsbuildinfo',
+        '**/.turbo',
+        '',
+        '# Noise: bytes in the context are bytes over the daemon socket on every build.',
+        '.git',
+        '.github',
+        '**/coverage',
+        '**/*.log',
+        '',
+    ].join('\n');
+}
+/**
+ * The engines an app talks to, each with a healthcheck.
+ *
+ * The healthchecks are the point (PLAN.md §21). `docker compose up -d` returns as
+ * soon as containers are *created*, so `pnpm db:migrate` on the next line of the
+ * README raced a server that had not finished initialising. Worse, the official
+ * images serve that initialisation from a temporary server bound to a unix socket
+ * only: measured on postgres:16, the socket accepts connections at t+0.86s and
+ * the real listener the app connects to appears at t+1.19s — so a check that does
+ * not name a TCP host reports ready before the database exists, and the gap grows
+ * with the size of the data directory. Each check below therefore goes through
+ * 127.0.0.1, and `up -d --wait` blocks until it passes.
+ */
+function dockerCompose(engine) {
+    const database = engine === 'mongodb'
+        ? [
+            '  mongo:',
+            '    image: mongo:7',
+            '    ports: [' + "'27017:27017'" + ']',
+            '    volumes: [mongo-data:/data/db]',
+            '    healthcheck:',
+            // `mongosh --eval` exits non-zero when it cannot connect, which is what
+            // makes it usable as a check; `db.adminCommand('ping')` needs no auth.
+            '      test: [' +
+                "'CMD-SHELL', 'mongosh --quiet --host 127.0.0.1 " +
+                '--eval "db.adminCommand({ ping: 1 }).ok" | grep -q 1\'' +
+                ']',
+            '      interval: 5s',
+            '      timeout: 5s',
+            '      retries: 12',
+            '      start_period: 10s',
+        ]
+        : engine === 'mariadb'
+            ? [
+                '  mariadb:',
+                // MariaDB, not mysql:8: the workspace picked the MariaDB dialect, and
+                // developing against a server that is only nearly compatible with it
+                // moves the surprises to production.
+                '    image: mariadb:11',
+                '    environment:',
+                '      MARIADB_DATABASE: app',
+                '      MARIADB_ROOT_PASSWORD: app',
+                '    ports: [' + "'3306:3306'" + ']',
+                '    volumes: [mariadb-data:/var/lib/mysql]',
+                '    healthcheck:',
+                // Shipped in the image for this purpose, and needs no credentials on
+                // the command line. `--innodb_initialized` is the half that matters:
+                // the server answers a ping before InnoDB has finished recovery.
+                '      test: [' + "'CMD', 'healthcheck.sh', '--connect', '--innodb_initialized'" + ']',
+                '      interval: 5s',
+                '      timeout: 5s',
+                '      retries: 12',
+                '      start_period: 10s',
+            ]
+            : engine === 'mysql'
+                ? [
+                    '  mysql:',
+                    '    image: mysql:8',
+                    '    environment:',
+                    '      MYSQL_DATABASE: app',
+                    '      MYSQL_ROOT_PASSWORD: app',
+                    '    ports: [' + "'3306:3306'" + ']',
+                    '    volumes: [mysql-data:/var/lib/mysql]',
+                    '    healthcheck:',
+                    // `$$` so compose passes the variable through for the container's
+                    // shell to expand, rather than substituting it from the host
+                    // environment — where it is not set. Through `MYSQL_PWD` rather
+                    // than `-p`, which prints "using a password on the command line is
+                    // insecure" into the healthcheck log on every probe and tempts the
+                    // next reader to drop the credentials — leaving a check that
+                    // passes on a server still rejecting every login.
+                    '      test: [' +
+                        "'CMD-SHELL', 'MYSQL_PWD=\"$$MYSQL_ROOT_PASSWORD\" " +
+                        "mysqladmin ping -h 127.0.0.1 -u root --silent'" +
+                        ']',
+                    '      interval: 5s',
+                    '      timeout: 5s',
+                    '      retries: 12',
+                    '      start_period: 10s',
+                ]
+                : [
+                    '  postgres:',
+                    '    image: postgres:16',
+                    '    environment:',
+                    '      POSTGRES_USER: app',
+                    '      POSTGRES_PASSWORD: app',
+                    '      POSTGRES_DB: app',
+                    '    ports: [' + "'5432:5432'" + ']',
+                    '    volumes: [postgres-data:/var/lib/postgresql/data]',
+                    '    healthcheck:',
+                    // Without `-h 127.0.0.1`, pg_isready answers over the unix socket
+                    // the initialisation phase serves on, and reports ready some seconds
+                    // before the database the app connects to exists.
+                    '      test: [' + "'CMD-SHELL', 'pg_isready -h 127.0.0.1 -U app -d app'" + ']',
+                    '      interval: 5s',
+                    '      timeout: 5s',
+                    // A minute of retries: initialising a data directory on a slow disk
+                    // takes longer than a healthcheck's patience would suggest.
+                    '      retries: 12',
+                    '      start_period: 10s',
+                ];
+    const volumeName = engine === 'mongodb'
+        ? 'mongo-data'
+        : engine === 'mariadb'
+            ? 'mariadb-data'
+            : engine === 'mysql'
+                ? 'mysql-data'
+                : 'postgres-data';
+    return ['services:', ...database, '', 'volumes:', `  ${volumeName}:`, ''].join('\n');
+}
+function workspaceCi() {
+    return [
+        'name: CI',
+        '',
+        'on:',
+        '  push:',
+        '    branches: [main]',
+        '  pull_request:',
+        '',
+        'jobs:',
+        '  ci:',
+        '    runs-on: ubuntu-latest',
+        '    steps:',
+        '      - uses: actions/checkout@v4',
+        '      - uses: pnpm/action-setup@v4',
+        '      - uses: actions/setup-node@v4',
+        '        with:',
+        '          node-version-file: .nvmrc',
+        '          cache: pnpm',
+        '      - run: pnpm install --frozen-lockfile',
+        '      # Build first: type-aware lint resolves workspace packages through',
+        '      # their build output.',
+        '      - run: pnpm build',
+        '      - run: pnpm lint',
+        '      - run: pnpm typecheck',
+        '      - run: pnpm test',
+        '      - run: pnpm doctor',
+        '      # Every app image, on every pull request. A Dockerfile that is only built',
+        '      # at release time is a Dockerfile that has never been built, and it fails',
+        '      # at the least convenient moment there is. The loop covers apps added',
+        '      # later without being edited.',
+        '      - name: Build app images',
+        '        run: |',
+        '          for dockerfile in apps/*/Dockerfile; do',
+        '            docker build -f "$dockerfile" -t "$(basename "$(dirname "$dockerfile")"):ci" .',
+        '          done',
+        '',
+    ].join('\n');
+}
+function readme(manifest) {
+    return [
+        `# ${manifest.name}`,
+        '',
+        'Generated with `nage create`.',
+        '',
+        '## Getting started',
+        '',
+        '```bash',
+        'pnpm install',
+        'cp .env.example .env',
+        ...(manifest.engine === 'sqlite'
+            ? // SQLite needs no server, so there is no compose file to bring up.
+                []
+            : [
+                '# --wait, not bare `up -d`: it blocks until the healthcheck passes, and',
+                '# a migration run against a database still initialising fails.',
+                'docker compose up -d --wait',
+            ]),
+        'pnpm db:migrate',
+        'pnpm dev',
+        '```',
+        '',
+        '## Layout',
+        '',
+        '```',
+        'apps/        deployable applications',
+        'packages/    shared local packages (@app/*)',
+        'database/    migrations and seeds shared by every app',
+        '```',
+        '',
+        '## Commands',
+        '',
+        '| Command | Purpose |',
+        '|---|---|',
+        '| `nage new app <name>` | Add another deployable app |',
+        '| `nage new package <name>` | Add a shared local package |',
+        '| `nage g resource <name>` | Generate a wired CRUD resource |',
+        '| `nage add <feature>` | Enable an optional package for an app |',
+        '| `nage doctor` | Check workspace integrity and configuration |',
+        '',
+    ].join('\n');
+}
+/** Deterministic JSON with a trailing newline, so regeneration is diff-free. */
+function json(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+//# sourceMappingURL=workspace.template.js.map

package/dist/workspace/manifest.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `nage.workspace.json` — the source of truth for the workspace (PLAN.md §10.4).
+ *
+ * Successor to the legacy single-file `.nac-metadata.json`, extended for many
+ * apps. `new app` / `remove app` / `add` / `list` / `doctor` all read and write
+ * it, and it is serialised deterministically so a regenerated manifest produces
+ * an empty diff rather than reordered noise.
+ */
+import type { DatabaseDriver } from '@nage-api/contracts';
+export declare const MANIFEST_FILE = "nage.workspace.json";
+/** App shapes the CLI can scaffold (§10.2). */
+export type Preset = 'minimal' | 'api' | 'api-realtime' | 'worker';
+/** Optional packages an app can enable (§10.1). */
+export type FeatureName = 'auth' | 'cache' | 'queue' | 'storage' | 'realtime' | 'notify' | 'observability';
+export interface AppEntry {
+    readonly name: string;
+    readonly preset: Preset;
+    /** Distinct per app; `doctor` reports a collision. */
+    readonly port: number;
+    readonly features: readonly FeatureName[];
+}
+export interface PackageEntry {
+    readonly name: string;
+    /** Import alias, e.g. `@app/domain`. */
+    readonly alias: string;
+}
+export interface WorkspaceManifest {
+    readonly version: 1;
+    readonly name: string;
+    /**
+     * One engine per workspace (§10.2): apps share `packages/domain` entities and
+     * `database/migrations`, which only stays coherent with a single engine.
+     */
+    readonly engine: DatabaseDriver;
+    /** The `@nage-api/*` version line every app pins to; `upgrade` moves it. */
+    readonly frameworkVersion: string;
+    readonly apps: readonly AppEntry[];
+    readonly packages: readonly PackageEntry[];
+}
+export declare const DEFAULT_PORT = 3000;
+export declare function createManifest(input: {
+    name: string;
+    engine: DatabaseDriver;
+    frameworkVersion: string;
+}): WorkspaceManifest;
+/** Serialise deterministically: sorted collections, stable key order, trailing newline. */
+export declare function serialiseManifest(manifest: WorkspaceManifest): string;
+/** Parse and validate a manifest, naming what is wrong rather than throwing a cast error. */
+export declare function parseManifest(contents: string, location?: string): WorkspaceManifest;
+/**
+ * Walk up from `start` looking for a workspace root.
+ *
+ * Commands can then be run from anywhere inside the workspace, which is how
+ * `--app` stays optional: the current directory usually says which app is meant.
+ */
+export declare function findWorkspaceRoot(start: string): string | undefined;
+/** Load the manifest for the workspace containing `start`. */
+export declare function loadWorkspace(start: string): Promise<{
+    root: string;
+    manifest: WorkspaceManifest;
+}>;
+/** Which app a command targets: `--app`, or the one the cwd sits inside. */
+export declare function resolveTargetApp(manifest: WorkspaceManifest, options: {
+    root: string;
+    cwd: string;
+    app?: string;
+}): AppEntry;
+/** Next free port, so two apps never default to the same one. */
+export declare function nextAvailablePort(manifest: WorkspaceManifest): number;
+//# sourceMappingURL=manifest.d.ts.map