@avijs/cli 0.0.0-stage → 0.1.1

package/dist/templates.js

@@ -0,0 +1,310 @@
+/** Every file of a new project, keyed by its path relative to the project folder. */
+export function templateFiles(options) {
+    return {
+        ...shared(options),
+        ...(options.template === 'modular' ? modular() : minimal()),
+    };
+}
+function shared({ name, template, aviVersion, localPackages, }) {
+    const spec = (pkg) => localPackages?.[pkg] ?? aviVersion;
+    const pkg = {
+        name,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        scripts: {
+            build: 'tsc',
+            start: 'node dist/main.js',
+            dev: 'avi dev',
+            check: 'avi check',
+            test: 'tsc && node --test "dist/**/*.test.js"',
+        },
+        dependencies: { '@avijs/core': spec('@avijs/core') },
+        devDependencies: {
+            '@avijs/cli': spec('@avijs/cli'),
+            '@avijs/testing': spec('@avijs/testing'),
+            '@types/node': '^22.0.0',
+            typescript: '~6.0.3',
+        },
+        engines: { node: '>=22.12' },
+        ...(localPackages ? { overrides: localPackages } : {}),
+    };
+    const tsconfig = {
+        compilerOptions: {
+            target: 'ES2023',
+            lib: ['ES2023', 'ESNext.Disposable'],
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            types: ['node'],
+            strict: true,
+            skipLibCheck: true,
+            outDir: 'dist',
+            rootDir: 'src',
+            sourceMap: true,
+        },
+        include: ['src'],
+    };
+    return {
+        'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
+        'tsconfig.json': `${JSON.stringify(tsconfig, null, 2)}\n`,
+        '.gitignore': 'node_modules/\ndist/\n',
+        'README.md': `# ${name}
+
+An [Avi.js](https://github.com/chrischase011/avi-js) API (${template} template).
+
+\`\`\`sh
+npm install
+npm run dev     # compile and restart on change
+npm test        # compile and run the tests
+npm start       # run the compiled app
+\`\`\`
+
+Then open http://localhost:3000/health and http://localhost:3000/users.
+`,
+    };
+}
+const MAIN_LISTEN = `const { port } = await app.listen(Number(process.env['PORT'] ?? 3000));
+console.log(\`Listening on http://localhost:\${String(port)}\`);
+
+const shutdown = () => {
+  void app.close().then(() => process.exit(0));
+};
+process.once('SIGINT', shutdown);
+process.once('SIGTERM', shutdown);
+`;
+function modular() {
+    return {
+        'src/main.ts': `import { AviFactory } from '@avijs/core';
+import { AppModule } from './app.module.js';
+
+const app = await AviFactory.create(AppModule);
+${MAIN_LISTEN}`,
+        'src/app.module.ts': `import { Module } from '@avijs/core';
+import { HealthController } from './common/health.controller.js';
+import { UsersModule } from './modules/users/users.module.js';
+
+@Module({ imports: [UsersModule], controllers: [HealthController] })
+export class AppModule {}
+`,
+        'src/common/health.controller.ts': `import { Controller, Get } from '@avijs/core';
+
+@Controller()
+export class HealthController {
+  @Get('/health')
+  check() {
+    return 'ok';
+  }
+}
+`,
+        'src/modules/users/users.module.ts': `import { Module } from '@avijs/core';
+import { UsersController } from './users.controller.js';
+import { UsersService } from './users.service.js';
+
+@Module({ controllers: [UsersController], providers: [UsersService], exports: [UsersService] })
+export class UsersModule {}
+`,
+        'src/modules/users/users.service.ts': `import { Injectable } from '@avijs/core';
+import type { CreateUserDto } from './dto/create-user.dto.js';
+
+export interface User {
+  id: number;
+  name: string;
+}
+
+@Injectable()
+export class UsersService {
+  readonly #users: User[] = [{ id: 1, name: 'Ada' }];
+
+  findAll(): User[] {
+    return this.#users;
+  }
+
+  findOne(id: number): User | undefined {
+    return this.#users.find((user) => user.id === id);
+  }
+
+  create(dto: CreateUserDto): User {
+    const user = { id: this.#users.length + 1, name: dto.name };
+    this.#users.push(user);
+    return user;
+  }
+}
+`,
+        'src/modules/users/users.controller.ts': `import { Controller, Get, HttpError, Post, reply, type Context } from '@avijs/core';
+import { parseCreateUser } from './dto/create-user.dto.js';
+import { UsersService } from './users.service.js';
+
+@Controller('/users')
+export class UsersController {
+  static inject = [UsersService] as const;
+
+  constructor(private readonly users: UsersService) {}
+
+  @Get()
+  findAll() {
+    return this.users.findAll();
+  }
+
+  @Get('/:id')
+  findOne(ctx: Context) {
+    const user = this.users.findOne(Number(ctx.params['id']));
+    if (!user) throw new HttpError(404, 'User not found');
+    return user;
+  }
+
+  @Post()
+  async create(ctx: Context) {
+    const dto = parseCreateUser(await ctx.json());
+    if (!dto) throw new HttpError(400, 'Body must be an object with a name');
+    return reply(this.users.create(dto), { status: 201 });
+  }
+}
+`,
+        'src/modules/users/dto/create-user.dto.ts': `export interface CreateUserDto {
+  name: string;
+}
+
+// Swap this for a schema library (Zod, Valibot, ...) and route schemas when the API grows.
+export function parseCreateUser(input: unknown): CreateUserDto | undefined {
+  if (typeof input !== 'object' || input === null) return undefined;
+  const { name } = input as { name?: unknown };
+  return typeof name === 'string' && name.trim() !== '' ? { name: name.trim() } : undefined;
+}
+`,
+        'src/modules/users/users.test.ts': `import assert from 'node:assert/strict';
+import { after, before, test } from 'node:test';
+import { createTestClient, type TestClient } from '@avijs/testing';
+import { AppModule } from '../../app.module.js';
+
+let client: TestClient;
+before(async () => {
+  client = await createTestClient(AppModule);
+});
+after(() => client.close());
+
+test('lists users', async () => {
+  const res = await client.get('/users');
+  assert.equal(res.status, 200);
+  assert.deepEqual(res.body, [{ id: 1, name: 'Ada' }]);
+});
+
+test('creates a user', async () => {
+  const res = await client.post('/users', { name: 'Grace' });
+  assert.equal(res.status, 201);
+  assert.deepEqual(res.body, { id: 2, name: 'Grace' });
+});
+
+test('rejects a user without a name', async () => {
+  assert.equal((await client.post('/users', {})).status, 400);
+});
+`,
+    };
+}
+function minimal() {
+    return {
+        'src/main.ts': `import { createApp } from './app.js';
+
+const app = createApp();
+${MAIN_LISTEN}`,
+        'src/app.ts': `import { createAvi } from '@avijs/core';
+import { healthRoutes } from './routes/health.js';
+import { usersRoutes } from './routes/users.js';
+import { UsersService } from './services/users.js';
+
+export function createApp() {
+  return createAvi().register({
+    providers: [UsersService],
+    controllers: [healthRoutes, usersRoutes],
+  });
+}
+`,
+        'src/routes/health.ts': `import { defineController, route } from '@avijs/core';
+
+export const healthRoutes = defineController({
+  routes: [route({ method: 'GET', path: '/health', handler: () => 'ok' })],
+});
+`,
+        'src/routes/users.ts': `import { HttpError, defineController, reply, route } from '@avijs/core';
+import { UsersService } from '../services/users.js';
+
+export const usersRoutes = defineController({
+  prefix: '/users',
+  inject: [UsersService],
+  routes: (users) => [
+    route({ method: 'GET', path: '/', handler: () => users.findAll() }),
+    route({
+      method: 'GET',
+      path: '/:id',
+      handler: (ctx) => {
+        const user = users.findOne(Number(ctx.params.id));
+        if (!user) throw new HttpError(404, 'User not found');
+        return user;
+      },
+    }),
+    route({
+      method: 'POST',
+      path: '/',
+      handler: async (ctx) => {
+        const { name } = (await ctx.json()) as { name?: unknown };
+        if (typeof name !== 'string' || name.trim() === '') {
+          throw new HttpError(400, 'Body must be an object with a name');
+        }
+        return reply(users.create(name.trim()), { status: 201 });
+      },
+    }),
+  ],
+});
+`,
+        'src/services/users.ts': `export interface User {
+  id: number;
+  name: string;
+}
+
+export class UsersService {
+  readonly #users: User[] = [{ id: 1, name: 'Ada' }];
+
+  findAll(): User[] {
+    return this.#users;
+  }
+
+  findOne(id: number): User | undefined {
+    return this.#users.find((user) => user.id === id);
+  }
+
+  create(name: string): User {
+    const user = { id: this.#users.length + 1, name };
+    this.#users.push(user);
+    return user;
+  }
+}
+`,
+        'src/app.test.ts': `import assert from 'node:assert/strict';
+import { after, before, test } from 'node:test';
+import { createTestClient, type TestClient } from '@avijs/testing';
+import { createApp } from './app.js';
+
+let client: TestClient;
+before(async () => {
+  client = await createTestClient(createApp());
+});
+after(() => client.close());
+
+test('lists users', async () => {
+  const res = await client.get('/users');
+  assert.equal(res.status, 200);
+  assert.deepEqual(res.body, [{ id: 1, name: 'Ada' }]);
+});
+
+test('creates a user', async () => {
+  const res = await client.post('/users', { name: 'Grace' });
+  assert.equal(res.status, 201);
+  assert.deepEqual(res.body, { id: 2, name: 'Grace' });
+});
+
+test('answers 404 for an unknown user', async () => {
+  assert.equal((await client.get('/users/99')).status, 404);
+});
+`,
+    };
+}
+//# sourceMappingURL=templates.js.map

package/dist/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@avijs/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "The avi command: project scaffolding, dev mode and build checks.",
+  "keywords": [
+    "avi",
+    "avi.js",
+    "cli",
+    "scaffolding"
+  ],
+  "license": "MIT",
+  "author": "Christopher Robin Chase",
+  "homepage": "https://github.com/chrischase011/avi-js#readme",
+  "bugs": {
+    "url": "https://github.com/chrischase011/avi-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrischase011/avi-js.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "sideEffects": false,
+  "bin": {
+    "avi": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "@avijs/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@avijs/compiler": "0.1.1"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.8"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }

package/src/bin.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+
+process.exitCode = await main(process.argv.slice(2));

package/src/cli.ts

@@ -0,0 +1,160 @@
+import { main as compile } from '@avijs/compiler';
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { GENERATE_USAGE, generate } from './generate.js';
+import { templateFiles } from './templates.js';
+
+const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
+
+const USAGE = `Usage:
+  avi new <name> [--template modular|minimal] [--dir .] [--avi-version ^x.y.z] [--from <dir>]
+      Create a project. The modular template (default) uses modules and decorators;
+      minimal uses plain routes and services. --from points at a folder of packed
+      @avijs tarballs (pnpm pack) to install instead of the registry. --avi-version
+      defaults to this CLI's version.
+${GENERATE_USAGE}
+  avi dev [--project tsconfig.json] [--entry dist/main.js]
+      Compile, then recompile and restart on every change.
+  avi check [--project tsconfig.json]
+      Type-check every static inject list.
+  avi manifest <entry.js> [--export AppModule] [--out avi.manifest.json]
+      Describe the app's modules, providers and routes.`;
+
+export async function main(argv: readonly string[]): Promise<number> {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case 'new':
+      return create(rest);
+    case 'generate':
+    case 'g':
+      return generate(rest);
+    case 'dev':
+      return dev(rest);
+    case 'check':
+    case 'manifest':
+      return compile(argv);
+    default:
+      console.error(USAGE);
+      return command === undefined || command === 'help' || command === '--help' ? 0 : 2;
+  }
+}
+
+async function create(args: readonly string[]): Promise<number> {
+  const { values, positionals } = parseArgs({
+    args: [...args],
+    allowPositionals: true,
+    options: {
+      template: { type: 'string', default: 'modular' },
+      dir: { type: 'string', default: '.' },
+      'avi-version': { type: 'string', default: `^${version}` },
+      from: { type: 'string' },
+    },
+  });
+  const name = positionals[0];
+  if (!name || !/^[a-z0-9][a-z0-9._-]*$/.test(name)) {
+    console.error('avi new needs a project name in lowercase letters, digits, ".", "_" or "-"');
+    return 2;
+  }
+  const template = values.template;
+  if (template !== 'modular' && template !== 'minimal') {
+    console.error(`Unknown template "${template}". Use modular or minimal.`);
+    return 2;
+  }
+
+  const target = path.resolve(values.dir, name);
+  if (existsSync(target) && (await readdir(target)).length > 0) {
+    console.error(`${target} already exists and is not empty`);
+    return 1;
+  }
+
+  const files = templateFiles({
+    name,
+    template,
+    aviVersion: values['avi-version'],
+    ...(values.from ? { localPackages: await localPackages(values.from, target) } : {}),
+  });
+  for (const [file, content] of Object.entries(files)) {
+    const destination = path.join(target, file);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await writeFile(destination, content);
+  }
+
+  console.log(`Created ${name} (${template}) in ${target}
+
+Next:
+  cd ${path.relative(process.cwd(), target) || '.'}
+  npm install
+  npm run dev`);
+  return 0;
+}
+
+async function dev(args: readonly string[]): Promise<number> {
+  const { values } = parseArgs({
+    args: [...args],
+    options: {
+      project: { type: 'string', default: 'tsconfig.json' },
+      entry: { type: 'string', default: 'dist/main.js' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+  });
+
+  let tsc: string;
+  try {
+    tsc = createRequire(path.resolve('package.json')).resolve('typescript/bin/tsc');
+  } catch {
+    console.error('avi dev needs TypeScript installed in this project: npm install -D typescript');
+    return 1;
+  }
+
+  const build = [tsc, '-p', values.project];
+  const watchBuild = [tsc, '-p', values.project, '--watch', '--preserveWatchOutput'];
+  const watchRun = ['--watch', '--watch-preserve-output', values.entry];
+  if (values['dry-run']) {
+    for (const command of [build, watchBuild, watchRun]) {
+      console.log(['node', ...command].join(' '));
+    }
+    return 0;
+  }
+
+  const first = spawnSync(process.execPath, build, { stdio: 'inherit' });
+  if (first.status !== 0) return first.status ?? 1;
+
+  const children: ChildProcess[] = [
+    spawn(process.execPath, watchBuild, { stdio: 'inherit' }),
+    spawn(process.execPath, watchRun, { stdio: 'inherit' }),
+  ];
+  return new Promise((resolve) => {
+    const stop = () => {
+      for (const child of children) child.kill();
+      resolve(0);
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    for (const child of children) {
+      child.once('exit', (code) => {
+        if (code !== null && code !== 0) {
+          for (const other of children) other.kill();
+          resolve(code);
+        }
+      });
+    }
+  });
+}
+
+/** Maps each packed @avi tarball in `dir` to a `file:` spec relative to the new project. */
+async function localPackages(dir: string, project: string): Promise<Record<string, string>> {
+  const folder = path.resolve(dir);
+  const specs: Record<string, string> = {};
+  for (const file of await readdir(folder)) {
+    const match = /^avijs-([a-z-]+?)-\d+\.\d+\.\d+.*\.tgz$/.exec(file);
+    if (!match?.[1]) continue;
+    const relative = path.relative(project, path.join(folder, file)).replaceAll(path.sep, '/');
+    specs[`@avijs/${match[1]}`] = `file:${relative}`;
+  }
+  if (!specs['@avijs/core']) throw new Error(`No @avijs package tarballs found in ${folder}`);
+  return specs;
+}