@zmdb/cli 1.0.0-beta.1

package/src/templates/command.ts

@@ -0,0 +1,66 @@
+import type { TemplateFactory } from './types.js';
+
+export const commandTemplate: TemplateFactory = ({ name }) => ({
+  files: [
+    {
+      path: `src/${name.fileStem}.command.ts`,
+      source: `import { assert } from 'zmdb';
+import { Command } from '@zmdb/app/commands';
+
+export interface ${name.pascal}Args {
+  readonly dryRun?: boolean;
+}
+
+export let ${name.camel}Runs = 0;
+
+@Command<${name.pascal}Args>({
+  name: '${name.fileStem}',
+  description: 'Run the ${name.fileStem} command',
+  args: {
+    type: 'object',
+    properties: {
+      dryRun: { type: 'boolean' },
+    },
+    required: [],
+  },
+  validate: raw => assert<${name.pascal}Args>(raw),
+})
+export class ${name.pascal}Command {
+  run(_args: ${name.pascal}Args): number {
+    ${name.camel}Runs += 1;
+    return 0;
+  }
+}
+`,
+    },
+    {
+      path: `src/${name.fileStem}.command.spec.ts`,
+      source: `import { createCommandApp } from '@zmdb/app/commands';
+import { createTestApp } from 'zmdb/testing';
+import { Module } from 'zmdb';
+import { describe, expect, it } from 'vitest';
+
+import {
+  ${name.pascal}Command,
+  ${name.camel}Runs,
+} from './${name.fileStem}.command.js';
+
+@Module({ commands: [${name.pascal}Command] })
+class ${name.pascal}CommandTestModule {}
+
+describe('${name.pascal}Command', () => {
+  it('runs through the command application', async () => {
+    await using testApp = createTestApp(${name.pascal}CommandTestModule);
+    await testApp.init();
+
+    await using commandApp = createCommandApp(${name.pascal}CommandTestModule);
+    await commandApp.init();
+    expect(await commandApp.run(['${name.fileStem}', '--dry-run'])).toBe(0);
+    expect(${name.camel}Runs).toBe(1);
+  });
+});
+`,
+    },
+  ],
+  instructions: [`add to src/app.module.ts, in @Module({ commands: [ … ] }):\n  ${name.pascal}Command,`],
+});

package/src/templates/controller.ts

@@ -0,0 +1,42 @@
+import type { TemplateFactory } from './types.js';
+
+export const controllerTemplate: TemplateFactory = ({ name }) => ({
+  files: [
+    {
+      path: `src/${name.fileStem}.controller.ts`,
+      source: `import { Controller, Get } from 'zmdb';
+
+@Controller('/${name.fileStem}')
+export class ${name.pascal}Controller {
+  @Get()
+  list(): { readonly resource: string; readonly items: readonly unknown[] } {
+    return { resource: '${name.fileStem}', items: [] };
+  }
+}
+`,
+    },
+    {
+      path: `src/${name.fileStem}.controller.spec.ts`,
+      source: `import { Module } from 'zmdb';
+import { createTestApp } from 'zmdb/testing';
+import { bodyText } from 'zmdb/web';
+import { describe, expect, it } from 'vitest';
+
+import { ${name.pascal}Controller } from './${name.fileStem}.controller.js';
+
+@Module({ controllers: [${name.pascal}Controller] })
+class ${name.pascal}ControllerTestModule {}
+
+describe('${name.pascal}Controller', () => {
+  it('serves its collection route', async () => {
+    await using app = createTestApp(${name.pascal}ControllerTestModule);
+    const response = await app.request({ method: 'GET', path: '/${name.fileStem}', headers: {} });
+    expect(response.status).toBe(200);
+    expect(JSON.parse(await bodyText(response))).toEqual({ resource: '${name.fileStem}', items: [] });
+  });
+});
+`,
+    },
+  ],
+  instructions: [`add to src/app.module.ts, in @Module({ controllers: [ … ] }):\n  ${name.pascal}Controller,`],
+});

package/src/templates/index.ts

@@ -0,0 +1,29 @@
+import { commandTemplate } from './command.js';
+import { controllerTemplate } from './controller.js';
+import { moduleTemplate } from './module.js';
+import { projectTemplate } from './project.js';
+import { repositoryTemplate } from './repository.js';
+import { schemaTemplate } from './schema.js';
+import type { ScaffoldKind, TemplateFactory } from './types.js';
+
+const TEMPLATES: Readonly<Record<ScaffoldKind, TemplateFactory>> = {
+  command: commandTemplate,
+  controller: controllerTemplate,
+  module: moduleTemplate,
+  project: projectTemplate,
+  repository: repositoryTemplate,
+  schema: schemaTemplate,
+};
+
+export function templateFor(kind: ScaffoldKind): TemplateFactory {
+  return TEMPLATES[kind];
+}
+
+export type {
+  ScaffoldKind,
+  ScaffoldName,
+  TemplateContext,
+  TemplateFactory,
+  TemplateFile,
+  TemplatePlan,
+} from './types.js';

package/src/templates/module.ts

@@ -0,0 +1,42 @@
+import type { TemplateFactory } from './types.js';
+
+export const moduleTemplate: TemplateFactory = ({ name }) => ({
+  files: [
+    {
+      path: `src/${name.fileStem}.module.ts`,
+      source: `import { Module } from 'zmdb';
+import { createToken } from 'zmdb/web';
+
+export interface ${name.pascal}Status {
+  readonly name: '${name.fileStem}';
+  readonly ready: true;
+}
+
+export const ${name.constant}_STATUS = createToken<${name.pascal}Status>('${name.pascal}Status');
+
+@Module({
+  providers: [{ token: ${name.constant}_STATUS, useValue: { name: '${name.fileStem}', ready: true } }],
+  exports: [${name.constant}_STATUS],
+})
+export class ${name.pascal}Module {}
+`,
+    },
+    {
+      path: `src/${name.fileStem}.module.spec.ts`,
+      source: `import { createTestApp } from 'zmdb/testing';
+import { describe, expect, it } from 'vitest';
+
+import { ${name.constant}_STATUS, ${name.pascal}Module } from './${name.fileStem}.module.js';
+
+describe('${name.pascal}Module', () => {
+  it('registers its status provider', async () => {
+    await using app = createTestApp(${name.pascal}Module);
+    const status = app.get(${name.constant}_STATUS);
+    expect(status).toEqual({ name: '${name.fileStem}', ready: true });
+  });
+});
+`,
+    },
+  ],
+  instructions: [`add to src/app.module.ts, in @Module({ imports: [ … ] }):\n  ${name.pascal}Module,`],
+});

package/src/templates/project.ts

@@ -0,0 +1,281 @@
+import { FORMAT_OPTIONS, type TemplateFactory } from './types.js';
+
+export const projectTemplate: TemplateFactory = ({ name, packageVersion }) => ({
+  files: [
+    {
+      path: 'package.json',
+      source: `${JSON.stringify({
+        name: name.fileStem,
+        private: true,
+        version: '0.1.0',
+        type: 'module',
+        scripts: {
+          build: 'node scripts/build.mjs app',
+          check:
+            'node scripts/build.mjs fmt-check && tsc --noEmit && oxlint . && node scripts/build.mjs test && vitest run --config vitest.config.ts',
+          fmt: 'node scripts/build.mjs fmt',
+          'fmt:check': 'node scripts/build.mjs fmt-check',
+          lint: 'oxlint .',
+          start: 'node dist/main.mjs',
+          test: 'node scripts/build.mjs test && vitest run --config vitest.config.ts',
+          typecheck: 'tsc --noEmit',
+        },
+        dependencies: {
+          '@zmdb/sqlite': packageVersion,
+          zmdb: packageVersion,
+        },
+        devDependencies: {
+          '@types/node': '26.4.1',
+          esbuild: '0.28.2',
+          oxfmt: '0.66.0',
+          oxlint: '1.81.0',
+          typescript: '7.0.2',
+          vitest: '5.0.0',
+        },
+        engines: {
+          node: '>=26',
+        },
+      })}\n`,
+    },
+    {
+      path: 'tsconfig.json',
+      source: `${JSON.stringify({
+        compilerOptions: {
+          allowImportingTsExtensions: false,
+          exactOptionalPropertyTypes: true,
+          isolatedModules: true,
+          lib: ['ESNext', 'DOM', 'DOM.Iterable'],
+          module: 'NodeNext',
+          moduleResolution: 'NodeNext',
+          noEmit: true,
+          noImplicitOverride: true,
+          noUncheckedIndexedAccess: true,
+          skipLibCheck: true,
+          strict: true,
+          target: 'ESNext',
+          types: ['node'],
+          verbatimModuleSyntax: true,
+        },
+        include: ['src/**/*.ts', 'vitest.config.ts', 'zmdb.config.ts'],
+      })}\n`,
+    },
+    {
+      path: 'scripts/build.mjs',
+      source: `import { glob, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { build } from 'esbuild';
+import { format } from 'oxfmt';
+import { zmdbAot } from 'zmdb/compiler';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const formatOptions = ${JSON.stringify(FORMAT_OPTIONS)};
+
+async function formatProject(check) {
+  const paths = glob(['**/*.ts', '**/*.mjs', '**/*.json'], {
+    cwd: root,
+    exclude: ['**/node_modules/**', '**/dist/**', '**/generated-tests/**', '**/.cache/**', '**/package-lock.json', '**/npm-shrinkwrap.json'],
+  });
+  for await (const path of paths) {
+    const absolute = join(root, path);
+    const source = await readFile(absolute, 'utf8');
+    const result = await format(path, source, formatOptions);
+    if (result.errors.length > 0) throw new Error(JSON.stringify(result.errors));
+    if (result.code === source) continue;
+    if (check) {
+      process.stderr.write(path + '\\n');
+      process.exitCode = 1;
+    } else {
+      await writeFile(absolute, result.code);
+    }
+  }
+}
+
+async function aotPlugin() {
+  const plugin = await zmdbAot({ cwd: root });
+  return {
+    name: plugin.name,
+    setup(esbuild) {
+      esbuild.onLoad({ filter: /\\.[cm]?tsx?$/ }, async ({ path }) => {
+        const code = await readFile(path, 'utf8');
+        const result = plugin.transform(code, path);
+        return { contents: result?.code ?? code, loader: path.endsWith('x') ? 'tsx' : 'ts' };
+      });
+      esbuild.onEnd(() => plugin.buildEnd?.());
+    },
+  };
+}
+
+const common = {
+  bundle: true,
+  format: 'esm',
+  packages: 'external',
+  platform: 'node',
+  target: 'es2022',
+};
+
+const mode = process.argv[2];
+if (mode === 'fmt' || mode === 'fmt-check') {
+  await formatProject(mode === 'fmt-check');
+} else if (mode === 'app') {
+  await build({
+    ...common,
+    entryPoints: [join(root, 'src', 'main.ts')],
+    outfile: join(root, 'dist', 'main.mjs'),
+    plugins: [await aotPlugin()],
+  });
+} else if (mode === 'test') {
+  const entryPoints = [];
+  for await (const path of glob('src/**/*.spec.ts', { cwd: root })) {
+    entryPoints.push(join(root, path));
+  }
+  const outdir = join(root, 'generated-tests');
+  await rm(outdir, { recursive: true, force: true });
+  await build({
+    ...common,
+    entryPoints,
+    outbase: join(root, 'src'),
+    outdir,
+    outExtension: { '.js': '.mjs' },
+    plugins: [await aotPlugin()],
+  });
+} else {
+  throw new Error('usage: node scripts/build.mjs <app|test|fmt|fmt-check>');
+}
+`,
+    },
+    {
+      path: 'vitest.config.ts',
+      source: `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['generated-tests/**/*.spec.mjs'],
+  },
+});
+`,
+    },
+    {
+      path: 'zmdb.config.ts',
+      source: `import { DatabaseSync } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+
+import { defineConfig } from 'zmdb';
+import { sqlite, sqliteDriver } from 'zmdb/sqlite';
+
+const databasePath = fileURLToPath(new URL('./database.sqlite', import.meta.url));
+
+export default defineConfig({
+  schema: ['src/**/*.ts'],
+  dialect: sqlite,
+  project: './tsconfig.json',
+  out: './migrations',
+  driver: () => sqliteDriver(new DatabaseSync(databasePath)),
+});
+`,
+    },
+    {
+      path: 'src/app.module.ts',
+      source: `import { Module } from 'zmdb';
+
+import { HealthController } from './health.controller.js';
+
+@Module({ controllers: [HealthController] })
+export class AppModule {}
+`,
+    },
+    {
+      path: 'src/main.ts',
+      source: `import { createServer } from 'node:http';
+
+import { compileModule, createRouter, toNodeHandler } from 'zmdb/web';
+
+import { AppModule } from './app.module.js';
+
+const port = Number(process.env.PORT ?? '3000');
+if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+  throw new RangeError(\`PORT must be an integer from 0 through 65535, received \${String(process.env.PORT)}\`);
+}
+
+const compiled = compileModule(AppModule);
+const router = createRouter();
+for (const controller of compiled.controllers) {
+  router.register(controller);
+}
+
+const handle = toNodeHandler(router);
+const server = createServer((request, response) => {
+  const method = request.method;
+  if (method === undefined) {
+    response.writeHead(400).end('request method is required');
+    return;
+  }
+  handle(
+    {
+      method,
+      headers: request.headers,
+      ...(request.url === undefined ? {} : { url: request.url }),
+      on(event, listener) {
+        request.on(event, listener);
+      },
+      setEncoding() {
+        request.setEncoding('utf8');
+      },
+    },
+    response,
+  );
+});
+server.listen(port, '127.0.0.1', () => {
+  const address = server.address();
+  const selectedPort = typeof address === 'object' && address !== null ? address.port : port;
+  console.log(\`listening on http://127.0.0.1:\${String(selectedPort)}\`);
+});
+`,
+    },
+    {
+      path: 'src/health.controller.ts',
+      source: `import { Controller, Get } from 'zmdb';
+
+@Controller('/health')
+export class HealthController {
+  @Get()
+  check(): { readonly ok: true } {
+    return { ok: true };
+  }
+}
+`,
+    },
+    {
+      path: 'src/health.controller.spec.ts',
+      source: `import { createTestApp } from 'zmdb/testing';
+import { bodyText } from 'zmdb/web';
+import { describe, expect, it } from 'vitest';
+
+import config from '../zmdb.config.js';
+import { AppModule } from './app.module.js';
+
+describe('generated project', () => {
+  it('serves health and opens its sqlite database', async () => {
+    await using app = createTestApp(AppModule);
+    const response = await app.request({ method: 'GET', path: '/health', headers: {} });
+    expect(response.status).toBe(200);
+    expect(JSON.parse(await bodyText(response))).toEqual({ ok: true });
+
+    const rows = await config.driver().execute({ text: 'SELECT 1 AS ok', parameters: [] });
+    expect(Reflect.get(rows[0] ?? {}, 'ok')).toBe(1);
+  });
+});
+`,
+    },
+    {
+      path: '.gitignore',
+      source: `node_modules
+dist
+generated-tests
+coverage
+database.sqlite
+`,
+    },
+  ],
+});

package/src/templates/repository.ts

@@ -0,0 +1,67 @@
+import type { TemplateFactory } from './types.js';
+
+export const repositoryTemplate: TemplateFactory = ({ name }) => ({
+  files: [
+    {
+      path: `src/${name.fileStem}.repository.ts`,
+      source: `import { defineRepository, schemaOf, type Driver } from 'zmdb';
+import type { BaseRepository } from 'zmdb/orm';
+import { repositoryToken } from 'zmdb/app/data';
+import type { ProviderDef } from 'zmdb/app/modules';
+
+import type { ${name.pascal} } from './${name.fileStem}.js';
+
+const ${name.camel}Schema = schemaOf<${name.pascal}>();
+
+export const ${name.constant}_REPOSITORY = repositoryToken<${name.pascal}>('${name.pascal}Repository');
+
+export function ${name.camel}RepositoryProvider(driver: Driver): ProviderDef<BaseRepository<${name.pascal}>> {
+  return {
+    token: ${name.constant}_REPOSITORY,
+    useFactory: () => defineRepository(${name.camel}Schema, driver),
+  };
+}
+`,
+    },
+    {
+      path: `src/${name.fileStem}.repository.spec.ts`,
+      source: `import { DatabaseSync } from 'node:sqlite';
+
+import { sqliteDriver } from 'zmdb/sqlite';
+import { createTestApp } from 'zmdb/testing';
+import { Module } from 'zmdb';
+import { describe, expect, it } from 'vitest';
+
+import {
+  ${name.constant}_REPOSITORY,
+  ${name.camel}RepositoryProvider,
+} from './${name.fileStem}.repository.js';
+
+describe('${name.pascal} repository provider', () => {
+  it('creates and reads a row through sqlite', async () => {
+    const database = new DatabaseSync(':memory:');
+    try {
+      database.exec(
+        'CREATE TABLE "${name.table}" ("id" INTEGER PRIMARY KEY AUTOINCREMENT, "name" TEXT NOT NULL)',
+      );
+
+      @Module({ providers: [${name.camel}RepositoryProvider(sqliteDriver(database))] })
+      class ${name.pascal}RepositoryTestModule {}
+
+      await using app = createTestApp(${name.pascal}RepositoryTestModule);
+      const repository = app.get(${name.constant}_REPOSITORY);
+      const created = await repository.create({ name: 'Ada' });
+      expect(created.name).toBe('Ada');
+      expect((await repository.findById(created.id))?.name).toBe('Ada');
+    } finally {
+      database.close();
+    }
+  });
+});
+`,
+    },
+  ],
+  instructions: [
+    `add to src/app.module.ts, in @Module({ providers: [ … ] }):\n  ${name.camel}RepositoryProvider(driver),`,
+  ],
+});

package/src/templates/schema.ts

@@ -0,0 +1,37 @@
+import type { TemplateFactory } from './types.js';
+
+export const schemaTemplate: TemplateFactory = ({ name }) => ({
+  files: [
+    {
+      path: `src/${name.fileStem}.ts`,
+      source: `import type { PrimaryKey, Serial, Sql, Table } from 'zmdb';
+
+export interface ${name.pascal} extends Table<'${name.table}'> {
+  id: number & Sql<'integer'> & Serial & PrimaryKey;
+  name: string & Sql<'text'>;
+}
+`,
+    },
+    {
+      path: `src/${name.fileStem}.spec.ts`,
+      source: `import { Module, is, schemaOf } from 'zmdb';
+import { createTestApp } from 'zmdb/testing';
+import { describe, expect, it } from 'vitest';
+
+import type { ${name.pascal} } from './${name.fileStem}.js';
+
+@Module({})
+class ${name.pascal}SchemaTestModule {}
+
+describe('${name.pascal} schema', () => {
+  it('emits the table declaration and validates through the transformer', async () => {
+    await using app = createTestApp(${name.pascal}SchemaTestModule);
+    await app.init();
+    expect(schemaOf<${name.pascal}>().table).toBe('${name.table}');
+    expect(is<{ id: number }>({ id: 'x' })).toBe(false);
+  });
+});
+`,
+    },
+  ],
+});

package/src/templates/types.ts

@@ -0,0 +1,46 @@
+import type { FormatConfig } from 'oxfmt';
+
+export const FORMAT_OPTIONS: FormatConfig = {
+  arrowParens: 'avoid',
+  bracketSpacing: true,
+  endOfLine: 'lf',
+  insertFinalNewline: true,
+  objectWrap: 'preserve',
+  printWidth: 120,
+  quoteProps: 'as-needed',
+  semi: true,
+  singleQuote: true,
+  sortImports: true,
+  sortPackageJson: true,
+  tabWidth: 2,
+  trailingComma: 'all',
+  useTabs: false,
+};
+
+export type ScaffoldKind = 'command' | 'controller' | 'module' | 'project' | 'repository' | 'schema';
+
+export interface ScaffoldName {
+  readonly input: string;
+  readonly fileStem: string;
+  readonly pascal: string;
+  readonly camel: string;
+  readonly constant: string;
+  readonly table: string;
+}
+
+export interface TemplateContext {
+  readonly name: ScaffoldName;
+  readonly packageVersion: string;
+}
+
+export interface TemplateFile {
+  readonly path: string;
+  readonly source: string;
+}
+
+export interface TemplatePlan {
+  readonly files: readonly TemplateFile[];
+  readonly instructions?: readonly string[];
+}
+
+export type TemplateFactory = (context: TemplateContext) => TemplatePlan;