@aponiajs/cli 0.0.0

package/README.md

@@ -0,0 +1,15 @@
+# @aponiajs/cli
+
+The Bun-native Aponia command-line interface.
+
+## Create a project
+
+```bash
+aponia new my-api
+aponia n my-api --dry-run
+aponia new my-api --skip-install
+```
+
+The initial CLI implements the standard application generator. Component and
+resource schematics will be added behind the same command architecture after
+their module-registration transforms are safe and testable.

package/bin/aponia.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+
+import { runCli } from "../src/index.ts";
+
+const exitCode = await runCli(Bun.argv.slice(2));
+process.exitCode = exitCode;

package/dist/index.d.mts

@@ -0,0 +1,33 @@
+//#region src/arguments.d.ts
+interface NewCommandOptions {
+  readonly command: "new";
+  readonly name: string;
+  readonly dryRun: boolean;
+  readonly skipInstall: boolean;
+}
+type CliCommand = NewCommandOptions | {
+  readonly command: "help";
+} | {
+  readonly command: "version";
+};
+declare function parseArguments(arguments_: readonly string[]): CliCommand;
+//#endregion
+//#region src/project-generator.d.ts
+interface GenerateProjectOptions {
+  readonly name: string;
+  readonly cwd?: string;
+  readonly dryRun?: boolean;
+  readonly skipInstall?: boolean;
+}
+interface GenerateProjectResult {
+  readonly projectDirectory: string;
+  readonly files: readonly string[];
+  readonly installed: boolean;
+  readonly dryRun: boolean;
+}
+declare function generateProject(options: GenerateProjectOptions): Promise<GenerateProjectResult>;
+//#endregion
+//#region src/index.d.ts
+declare function runCli(arguments_: readonly string[]): Promise<number>;
+//#endregion
+export { type CliCommand, type GenerateProjectOptions, type GenerateProjectResult, generateProject, parseArguments, runCli };

package/dist/index.mjs

@@ -0,0 +1,122 @@
+import { mkdir, readdir } from "node:fs/promises";
+import { basename, dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/arguments.ts
+function parseArguments(arguments_) {
+	const [command = "help", ...rest] = arguments_;
+	if (command === "help" || command === "--help" || command === "-h") return { command: "help" };
+	if (command === "version" || command === "--version" || command === "-v") return { command: "version" };
+	if (command !== "new" && command !== "n") throw new Error(`Unknown command "${command}".`);
+	const name = rest.find((argument) => !argument.startsWith("-"));
+	if (!name) throw new Error("Project name is required.");
+	const supportedOptions = /* @__PURE__ */ new Set([
+		"--dry-run",
+		"-d",
+		"--skip-install",
+		"-s"
+	]);
+	const unknownOption = rest.find((argument) => argument.startsWith("-") && !supportedOptions.has(argument));
+	if (unknownOption) throw new Error(`Unknown option "${unknownOption}".`);
+	return {
+		command: "new",
+		name,
+		dryRun: rest.includes("--dry-run") || rest.includes("-d"),
+		skipInstall: rest.includes("--skip-install") || rest.includes("-s")
+	};
+}
+//#endregion
+//#region src/project-generator.ts
+const projectNamePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+async function generateProject(options) {
+	validateProjectName(options.name);
+	const projectDirectory = join(options.cwd ?? process.cwd(), options.name);
+	const templateDirectory = fileURLToPath(new URL("../templates/application", import.meta.url));
+	const templateFiles = await listFiles(templateDirectory);
+	const relativeFiles = templateFiles.map((file) => outputPath(relative(templateDirectory, file)));
+	if (options.dryRun) return {
+		projectDirectory,
+		files: relativeFiles,
+		installed: false,
+		dryRun: true
+	};
+	if (await Bun.file(projectDirectory).exists()) throw new Error(`Target directory "${basename(projectDirectory)}" already exists.`);
+	await mkdir(projectDirectory, { recursive: false });
+	for (const templateFile of templateFiles) {
+		const outputFile = join(projectDirectory, outputPath(relative(templateDirectory, templateFile)));
+		const output = (await Bun.file(templateFile).text()).replaceAll("{{PROJECT_NAME}}", options.name);
+		await mkdir(dirname(outputFile), { recursive: true });
+		await Bun.write(outputFile, output);
+	}
+	const shouldInstall = !options.skipInstall;
+	if (shouldInstall) {
+		const exitCode = await Bun.spawn(["bun", "install"], {
+			cwd: projectDirectory,
+			stdin: "inherit",
+			stdout: "inherit",
+			stderr: "inherit"
+		}).exited;
+		if (exitCode !== 0) throw new Error(`Bun install failed with exit code ${exitCode}.`);
+	}
+	return {
+		projectDirectory,
+		files: relativeFiles,
+		installed: shouldInstall,
+		dryRun: false
+	};
+}
+function outputPath(templatePath) {
+	if (templatePath === "_gitignore") return ".gitignore";
+	return templatePath.endsWith(".tmpl") ? templatePath.slice(0, -5) : templatePath;
+}
+function validateProjectName(name) {
+	if (!projectNamePattern.test(name)) throw new Error("Project name must use lowercase kebab-case and start with a letter.");
+}
+async function listFiles(directory) {
+	const entries = await readdir(directory, { withFileTypes: true });
+	return (await Promise.all(entries.toSorted((left, right) => left.name.localeCompare(right.name)).map(async (entry) => {
+		const path = join(directory, entry.name);
+		return entry.isDirectory() ? listFiles(path) : [path];
+	}))).flat();
+}
+//#endregion
+//#region src/index.ts
+async function runCli(arguments_) {
+	try {
+		const command = parseArguments(arguments_);
+		if (command.command === "help") {
+			console.log(helpText);
+			return 0;
+		}
+		if (command.command === "version") {
+			console.log("0.0.0");
+			return 0;
+		}
+		const result = await generateProject(command);
+		if (result.dryRun) {
+			console.log(`CREATE ${result.projectDirectory}`);
+			for (const file of result.files) console.log(`  ${file}`);
+			return 0;
+		}
+		console.log(`Created ${command.name}`);
+		console.log(`Next: cd ${command.name} && bun run dev`);
+		return 0;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`Aponia CLI error: ${message}`);
+		return 1;
+	}
+}
+const helpText = `Aponia CLI
+
+Usage:
+  aponia new <name> [options]
+  aponia n <name> [options]
+
+Options:
+  -d, --dry-run       Report files without writing them
+  -s, --skip-install  Generate without running bun install
+  -h, --help          Show command help
+  -v, --version       Show CLI version
+`;
+//#endregion
+export { generateProject, parseArguments, runCli };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@aponiajs/cli",
+  "version": "0.0.0",
+  "description": "Bun-native project generator and command-line interface for Aponia.",
+  "homepage": "https://github.com/aponiajs/aponiajs#readme",
+  "bugs": {
+    "url": "https://github.com/aponiajs/aponiajs/issues"
+  },
+  "license": "MIT",
+  "author": "AponiaJS contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aponiajs/aponiajs.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "aponia": "./bin/aponia.ts"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "templates"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bunx --bun vp pack",
+    "test": "bun test",
+    "check": "bunx --bun vp check",
+    "prepublishOnly": "bun run build"
+  }
+}

package/src/arguments.ts

@@ -0,0 +1,47 @@
+export interface NewCommandOptions {
+  readonly command: "new";
+  readonly name: string;
+  readonly dryRun: boolean;
+  readonly skipInstall: boolean;
+}
+
+export type CliCommand =
+  | NewCommandOptions
+  | { readonly command: "help" }
+  | { readonly command: "version" };
+
+export function parseArguments(arguments_: readonly string[]): CliCommand {
+  const [command = "help", ...rest] = arguments_;
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    return { command: "help" };
+  }
+
+  if (command === "version" || command === "--version" || command === "-v") {
+    return { command: "version" };
+  }
+
+  if (command !== "new" && command !== "n") {
+    throw new Error(`Unknown command "${command}".`);
+  }
+
+  const name = rest.find((argument) => !argument.startsWith("-"));
+  if (!name) {
+    throw new Error("Project name is required.");
+  }
+
+  const supportedOptions = new Set(["--dry-run", "-d", "--skip-install", "-s"]);
+  const unknownOption = rest.find(
+    (argument) => argument.startsWith("-") && !supportedOptions.has(argument),
+  );
+  if (unknownOption) {
+    throw new Error(`Unknown option "${unknownOption}".`);
+  }
+
+  return {
+    command: "new",
+    name,
+    dryRun: rest.includes("--dry-run") || rest.includes("-d"),
+    skipInstall: rest.includes("--skip-install") || rest.includes("-s"),
+  };
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+import { parseArguments } from "./arguments.ts";
+import { generateProject } from "./project-generator.ts";
+
+export { parseArguments, type CliCommand } from "./arguments.ts";
+export {
+  generateProject,
+  type GenerateProjectOptions,
+  type GenerateProjectResult,
+} from "./project-generator.ts";
+
+export async function runCli(arguments_: readonly string[]): Promise<number> {
+  try {
+    const command = parseArguments(arguments_);
+
+    if (command.command === "help") {
+      console.log(helpText);
+      return 0;
+    }
+
+    if (command.command === "version") {
+      console.log("0.0.0");
+      return 0;
+    }
+
+    const result = await generateProject(command);
+    if (result.dryRun) {
+      console.log(`CREATE ${result.projectDirectory}`);
+      for (const file of result.files) {
+        console.log(`  ${file}`);
+      }
+      return 0;
+    }
+
+    console.log(`Created ${command.name}`);
+    console.log(`Next: cd ${command.name} && bun run dev`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Aponia CLI error: ${message}`);
+    return 1;
+  }
+}
+
+const helpText = `Aponia CLI
+
+Usage:
+  aponia new <name> [options]
+  aponia n <name> [options]
+
+Options:
+  -d, --dry-run       Report files without writing them
+  -s, --skip-install  Generate without running bun install
+  -h, --help          Show command help
+  -v, --version       Show CLI version
+`;

package/src/project-generator.ts

@@ -0,0 +1,104 @@
+import { mkdir, readdir } from "node:fs/promises";
+import { basename, dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface GenerateProjectOptions {
+  readonly name: string;
+  readonly cwd?: string;
+  readonly dryRun?: boolean;
+  readonly skipInstall?: boolean;
+}
+
+export interface GenerateProjectResult {
+  readonly projectDirectory: string;
+  readonly files: readonly string[];
+  readonly installed: boolean;
+  readonly dryRun: boolean;
+}
+
+const projectNamePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+export async function generateProject(
+  options: GenerateProjectOptions,
+): Promise<GenerateProjectResult> {
+  validateProjectName(options.name);
+
+  const workingDirectory = options.cwd ?? process.cwd();
+  const projectDirectory = join(workingDirectory, options.name);
+  const templateDirectory = fileURLToPath(new URL("../templates/application", import.meta.url));
+  const templateFiles = await listFiles(templateDirectory);
+  const relativeFiles = templateFiles.map((file) => outputPath(relative(templateDirectory, file)));
+
+  if (options.dryRun) {
+    return {
+      projectDirectory,
+      files: relativeFiles,
+      installed: false,
+      dryRun: true,
+    };
+  }
+
+  if (await Bun.file(projectDirectory).exists()) {
+    throw new Error(`Target directory "${basename(projectDirectory)}" already exists.`);
+  }
+
+  await mkdir(projectDirectory, { recursive: false });
+  for (const templateFile of templateFiles) {
+    const relativeFile = outputPath(relative(templateDirectory, templateFile));
+    const outputFile = join(projectDirectory, relativeFile);
+    const template = await Bun.file(templateFile).text();
+    const output = template.replaceAll("{{PROJECT_NAME}}", options.name);
+
+    await mkdir(dirname(outputFile), { recursive: true });
+    await Bun.write(outputFile, output);
+  }
+
+  const shouldInstall = !options.skipInstall;
+  if (shouldInstall) {
+    const process = Bun.spawn(["bun", "install"], {
+      cwd: projectDirectory,
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    const exitCode = await process.exited;
+    if (exitCode !== 0) {
+      throw new Error(`Bun install failed with exit code ${exitCode}.`);
+    }
+  }
+
+  return {
+    projectDirectory,
+    files: relativeFiles,
+    installed: shouldInstall,
+    dryRun: false,
+  };
+}
+
+function outputPath(templatePath: string): string {
+  if (templatePath === "_gitignore") {
+    return ".gitignore";
+  }
+
+  return templatePath.endsWith(".tmpl") ? templatePath.slice(0, -5) : templatePath;
+}
+
+function validateProjectName(name: string): void {
+  if (!projectNamePattern.test(name)) {
+    throw new Error("Project name must use lowercase kebab-case and start with a letter.");
+  }
+}
+
+async function listFiles(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    entries
+      .toSorted((left, right) => left.name.localeCompare(right.name))
+      .map(async (entry) => {
+        const path = join(directory, entry.name);
+        return entry.isDirectory() ? listFiles(path) : [path];
+      }),
+  );
+
+  return files.flat();
+}

package/templates/application/.env.example

@@ -0,0 +1 @@
+PORT=3000

package/templates/application/README.md

@@ -0,0 +1,36 @@
+# {{PROJECT_NAME}}
+
+A Bun-first Aponia application generated by `@aponiajs/cli`.
+
+```bash
+bun install
+bun run dev
+```
+
+The generated request flow is:
+
+```text
+main.ts
+  -> AponiaFactory
+  -> AppModule
+  -> AppController
+  -> AppService
+```
+
+Open `http://localhost:3000/` after starting the application.
+
+The starter follows Nest standard mode:
+
+```text
+src/
+|-- app.controller.spec.ts
+|-- app.controller.ts
+|-- app.module.ts
+|-- app.service.ts
+`-- main.ts
+test/
+`-- app.e2e-spec.ts
+```
+
+Add later features under `src/<feature>`, with the feature controller, module,
+service, DTOs, entities, and unit tests kept together.

package/templates/application/_gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.env
+.env.*
+!.env.example
+*.log

package/templates/application/aponia.json

@@ -0,0 +1,9 @@
+{
+  "sourceRoot": "src",
+  "entryFile": "main",
+  "platform": "elysia",
+  "language": "typescript",
+  "generateOptions": {
+    "spec": true
+  }
+}

package/templates/application/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/main.ts",
+    "start": "bun src/main.ts",
+    "build": "bun build ./src/main.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "test:e2e": "bun test ./test/app.e2e-spec.ts",
+    "check": "vp check"
+  },
+  "dependencies": {
+    "@aponiajs/common": "latest",
+    "@aponiajs/core": "latest",
+    "@aponiajs/platform-elysia": "latest",
+    "elysia": "^1.4.29"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^7.0.2",
+    "vite-plus": "^0.2.4"
+  },
+  "packageManager": "bun@1.3.14"
+}

package/templates/application/src/app.controller.spec.ts.tmpl

@@ -0,0 +1,11 @@
+import { describe, expect, test } from "bun:test";
+import { AppController } from "./app.controller.ts";
+import { AppService } from "./app.service.ts";
+
+describe("AppController", () => {
+  test("returns the application greeting", () => {
+    const controller = new AppController(new AppService());
+
+    expect(controller.getGreeting()).toBe("Hello from {{PROJECT_NAME}}!");
+  });
+});

package/templates/application/src/app.controller.ts.tmpl

@@ -0,0 +1,12 @@
+import { Controller, Get } from "@aponiajs/common";
+import { AppService } from "./app.service.ts";
+
+@Controller()
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Get()
+  getGreeting(): string {
+    return this.appService.getGreeting();
+  }
+}

package/templates/application/src/app.module.ts.tmpl

@@ -0,0 +1,9 @@
+import { Module } from "@aponiajs/common";
+import { AppController } from "./app.controller.ts";
+import { AppService } from "./app.service.ts";
+
+@Module({
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}

package/templates/application/src/app.service.ts.tmpl

@@ -0,0 +1,8 @@
+import { Injectable } from "@aponiajs/common";
+
+@Injectable()
+export class AppService {
+  getGreeting(): string {
+    return "Hello from {{PROJECT_NAME}}!";
+  }
+}

package/templates/application/src/main.ts.tmpl

@@ -0,0 +1,10 @@
+import { AponiaFactory } from "@aponiajs/platform-elysia";
+import { AppModule } from "./app.module.ts";
+
+async function bootstrap(): Promise<void> {
+  const application = await AponiaFactory.create(AppModule);
+  const port = Number(Bun.env.PORT ?? 3000);
+  await application.listen(port);
+}
+
+await bootstrap();

package/templates/application/test/app.e2e-spec.ts.tmpl

@@ -0,0 +1,12 @@
+import { expect, test } from "bun:test";
+import { AponiaFactory } from "@aponiajs/platform-elysia";
+import { AppModule } from "../src/app.module.ts";
+
+test("GET / routes through AppController and AppService", async () => {
+  const application = await AponiaFactory.create(AppModule, { logger: false });
+  const response = await application.handle(new Request("http://localhost/"));
+
+  expect(response.status).toBe(200);
+  expect(await response.text()).toBe("Hello from {{PROJECT_NAME}}!");
+  await application.close();
+});

package/templates/application/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "module": "Preserve",
+    "moduleResolution": "Bundler",
+    "moduleDetection": "force",
+    "types": ["bun"],
+    "strict": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "noUnusedLocals": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true
+  },
+  "include": ["src", "test", "vite.config.ts"]
+}

package/templates/application/vite.config.ts.tmpl

@@ -0,0 +1,11 @@
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  lint: {
+    options: {
+      typeAware: true,
+      typeCheck: true,
+    },
+  },
+  fmt: {},
+});