@avijs/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Robin Chase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @avijs/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The avi command: avi new, avi dev, avi check and avi manifest.
+
+```sh
+npm install -D @avijs/cli
+```
+
+Part of [Avi.js](https://github.com/chrischase011/avi-js), a TypeScript framework for Node.js with
+modules, controllers and dependency injection, without `reflect-metadata`. See the
+[tutorial](https://github.com/chrischase011/avi-js/blob/main/docs/tutorial/README.md) to get started.
+
+Requires Node.js 22.12 or newer. MIT licensed.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

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

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,OAAO,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export declare function main(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAwBA,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAcnE"}

package/dist/cli.js

@@ -0,0 +1,149 @@
+import { main as compile } from '@avijs/compiler';
+import { spawn, spawnSync } 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 { templateFiles } from './templates.js';
+const { version } = createRequire(import.meta.url)('../package.json');
+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.
+  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) {
+    const [command, ...rest] = argv;
+    switch (command) {
+        case 'new':
+            return create(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) {
+    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) {
+    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;
+    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 = [
+        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, project) {
+    const folder = path.resolve(dir);
+    const specs = {};
+    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;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { main } from './cli.js';
+export { templateFiles } from './templates.js';
+export type { TemplateName, TemplateOptions } from './templates.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { main } from './cli.js';
+export { templateFiles } from './templates.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/templates.d.ts

@@ -0,0 +1,16 @@
+export type TemplateName = 'modular' | 'minimal';
+export interface TemplateOptions {
+    name: string;
+    template: TemplateName;
+    /** Version range for the @avijs packages. */
+    aviVersion: string;
+    /**
+     * Local package files to use instead of the registry, keyed by package name, such as
+     * 'file:../artifacts/avijs-core-0.1.0.tgz'. Also added as npm overrides so packages that depend on
+     * each other resolve locally too.
+     */
+    localPackages?: Readonly<Record<string, string>>;
+}
+/** Every file of a new project, keyed by its path relative to the project folder. */
+export declare function templateFiles(options: TemplateOptions): Record<string, string>;
+//# sourceMappingURL=templates.d.ts.map

package/dist/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,YAAY,CAAC;IACvB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK9E"}

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.0",
+  "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.0"
+  },
+  "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,155 @@
+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 { 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.
+  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 '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;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { main } from './cli.js';
+export { templateFiles } from './templates.js';
+export type { TemplateName, TemplateOptions } from './templates.js';

package/src/templates.ts

@@ -0,0 +1,333 @@
+export type TemplateName = 'modular' | 'minimal';
+
+export interface TemplateOptions {
+  name: string;
+  template: TemplateName;
+  /** Version range for the @avijs packages. */
+  aviVersion: string;
+  /**
+   * Local package files to use instead of the registry, keyed by package name, such as
+   * 'file:../artifacts/avijs-core-0.1.0.tgz'. Also added as npm overrides so packages that depend on
+   * each other resolve locally too.
+   */
+  localPackages?: Readonly<Record<string, string>>;
+}
+
+/** Every file of a new project, keyed by its path relative to the project folder. */
+export function templateFiles(options: TemplateOptions): Record<string, string> {
+  return {
+    ...shared(options),
+    ...(options.template === 'modular' ? modular() : minimal()),
+  };
+}
+
+function shared({
+  name,
+  template,
+  aviVersion,
+  localPackages,
+}: TemplateOptions): Record<string, string> {
+  const spec = (pkg: string) => 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(): Record<string, string> {
+  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(): Record<string, string> {
+  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);
+});
+`,
+  };
+}