@avleon/cli 0.0.47 → 0.4.0

package/dist/utils/names.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.titleCase = exports.snakeCase = exports.kebabCase = exports.camelCase = exports.pascalCase = void 0;
+exports.words = words;
+exports.resolveName = resolveName;
+const path_1 = __importDefault(require("path"));
+const errors_1 = require("../errors");
+/** Split an identifier into words: `JwtAuth`, `jwt-auth`, `jwt_auth` and `jwtAuth` all give `[jwt, auth]`. */
+function words(input) {
+    const matches = input.match(/[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|\d+/g);
+    return (matches ?? []).map((w) => w.toLowerCase());
+}
+const upperFirst = (s) => (s ? s[0].toUpperCase() + s.slice(1) : s);
+const pascalCase = (input) => words(input).map(upperFirst).join("");
+exports.pascalCase = pascalCase;
+const camelCase = (input) => {
+    const p = (0, exports.pascalCase)(input);
+    return p ? p[0].toLowerCase() + p.slice(1) : p;
+};
+exports.camelCase = camelCase;
+const kebabCase = (input) => words(input).join("-");
+exports.kebabCase = kebabCase;
+const snakeCase = (input) => words(input).join("_");
+exports.snakeCase = snakeCase;
+/** Human-readable title, e.g. `my_api` -> `My Api`. */
+const titleCase = (input) => words(input).map(upperFirst).join(" ");
+exports.titleCase = titleCase;
+/**
+ * Resolve a user-supplied artifact name (optionally nested, e.g. `admin/User`
+ * or `admin\User`) into class and file names. A trailing suffix such as
+ * `Controller` is dropped before it is re-added, so `UserController` and `User`
+ * give the same result.
+ */
+function resolveName(input, suffix = "") {
+    if (!input || !input.trim())
+        throw new errors_1.CliError("A name is required.");
+    const parts = input.split(/[\\/]+/).filter(Boolean);
+    const last = parts.pop() ?? "";
+    for (const dir of parts) {
+        if (dir === "." || dir === ".." || path_1.default.isAbsolute(dir)) {
+            throw new errors_1.CliError(`Invalid name "${input}": use a relative path without "." or "..".`);
+        }
+    }
+    const stripped = suffix ? last.replace(new RegExp(`[-_.]?${suffix}$`, "i"), "") : last;
+    const base = (0, exports.pascalCase)(stripped);
+    if (!base)
+        throw new errors_1.CliError(`Invalid name "${input}".`);
+    return {
+        dirs: parts.map((d) => (0, exports.kebabCase)(d) || d),
+        base,
+        className: base + suffix,
+        varName: (0, exports.camelCase)(base),
+        fileBase: (0, exports.kebabCase)(base),
+    };
+}

package/dist/utils/process.d.ts

@@ -0,0 +1,18 @@
+import { ChildProcess } from "child_process";
+/**
+ * Stop a child process and everything it spawned. On POSIX the child must
+ * have been started with `detached: true` so it leads its own process group;
+ * we send SIGTERM to the group and escalate to SIGKILL after `timeoutMs`.
+ * Windows has no SIGTERM for console processes, so the tree is ended with
+ * `taskkill /T /F`.
+ */
+export declare function killTree(child: ChildProcess | null, timeoutMs?: number): Promise<void>;
+/** Spawn options that make `killTree` work on every platform. */
+export declare const treeSpawnOptions: {
+    readonly detached: boolean;
+    readonly windowsHide: true;
+};
+/** Locate the project's own TypeScript compiler (`typescript/bin/tsc`). */
+export declare function findTsc(root: string): string | null;
+/** Run a node script to completion with inherited stdio, resolving to its exit code. */
+export declare function runNode(script: string, args: string[], cwd: string, env?: NodeJS.ProcessEnv): Promise<number>;

package/dist/utils/process.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.treeSpawnOptions = void 0;
+exports.killTree = killTree;
+exports.findTsc = findTsc;
+exports.runNode = runNode;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const isWindows = process.platform === "win32";
+/**
+ * Stop a child process and everything it spawned. On POSIX the child must
+ * have been started with `detached: true` so it leads its own process group;
+ * we send SIGTERM to the group and escalate to SIGKILL after `timeoutMs`.
+ * Windows has no SIGTERM for console processes, so the tree is ended with
+ * `taskkill /T /F`.
+ */
+function killTree(child, timeoutMs = 3000) {
+    return new Promise((resolve) => {
+        if (!child || child.pid === undefined || child.exitCode !== null || child.signalCode !== null) {
+            return resolve();
+        }
+        const pid = child.pid;
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        child.once("exit", finish);
+        if (isWindows) {
+            (0, child_process_1.spawnSync)("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+        }
+        else {
+            signalGroup(pid, "SIGTERM");
+        }
+        const timer = setTimeout(() => {
+            if (!isWindows)
+                signalGroup(pid, "SIGKILL");
+            setTimeout(finish, 200);
+        }, timeoutMs);
+    });
+}
+function signalGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/** Spawn options that make `killTree` work on every platform. */
+exports.treeSpawnOptions = { detached: !isWindows, windowsHide: true };
+/** Locate the project's own TypeScript compiler (`typescript/bin/tsc`). */
+function findTsc(root) {
+    let dir = path_1.default.resolve(root);
+    for (;;) {
+        const candidate = path_1.default.join(dir, "node_modules", "typescript", "bin", "tsc");
+        if (fs_1.default.existsSync(candidate))
+            return candidate;
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Run a node script to completion with inherited stdio, resolving to its exit code. */
+function runNode(script, args, cwd, env = process.env) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(process.execPath, [script, ...args], { cwd, stdio: "inherit", env });
+        child.on("error", reject);
+        child.on("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+}

package/dist/utils/project.d.ts

@@ -0,0 +1,17 @@
+/** Walk up from `start` to the nearest directory containing a `package.json`. */
+export declare function findProjectRoot(start: string): string | null;
+export declare function requireProjectRoot(start: string): string;
+export declare function readJson<T = any>(file: string): T;
+export declare function readPackageJson(root: string): Record<string, any>;
+/**
+ * Find an installed package's directory by walking up `node_modules` folders.
+ * Unlike `require.resolve('<pkg>/package.json')` this works for packages whose
+ * `exports` map does not expose `package.json`.
+ */
+export declare function findInstalledPackage(name: string, from: string): string | null;
+export declare function installedVersion(name: string, from: string): string | null;
+/** Write a file, creating parent directories. Refuses to overwrite unless `force`. */
+export declare function writeFileSafe(file: string, content: string, force?: boolean): void;
+/** Copy every non-TypeScript file under `srcDir` to the same relative path under `outDir`. */
+export declare function copyAssets(srcDir: string, outDir: string): number;
+export declare function isAsset(file: string): boolean;

package/dist/utils/project.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findProjectRoot = findProjectRoot;
+exports.requireProjectRoot = requireProjectRoot;
+exports.readJson = readJson;
+exports.readPackageJson = readPackageJson;
+exports.findInstalledPackage = findInstalledPackage;
+exports.installedVersion = installedVersion;
+exports.writeFileSafe = writeFileSafe;
+exports.copyAssets = copyAssets;
+exports.isAsset = isAsset;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const errors_1 = require("../errors");
+/** Walk up from `start` to the nearest directory containing a `package.json`. */
+function findProjectRoot(start) {
+    let dir = path_1.default.resolve(start);
+    for (;;) {
+        if (fs_1.default.existsSync(path_1.default.join(dir, "package.json")))
+            return dir;
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function requireProjectRoot(start) {
+    const root = findProjectRoot(start);
+    if (!root) {
+        throw new errors_1.CliError(`No package.json found in ${path_1.default.resolve(start)} or any parent directory. Run this command inside an Avleon project.`);
+    }
+    return root;
+}
+function readJson(file) {
+    return JSON.parse(fs_1.default.readFileSync(file, "utf8"));
+}
+function readPackageJson(root) {
+    return readJson(path_1.default.join(root, "package.json"));
+}
+/**
+ * Find an installed package's directory by walking up `node_modules` folders.
+ * Unlike `require.resolve('<pkg>/package.json')` this works for packages whose
+ * `exports` map does not expose `package.json`.
+ */
+function findInstalledPackage(name, from) {
+    let dir = path_1.default.resolve(from);
+    for (;;) {
+        const candidate = path_1.default.join(dir, "node_modules", ...name.split("/"));
+        if (fs_1.default.existsSync(path_1.default.join(candidate, "package.json")))
+            return candidate;
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function installedVersion(name, from) {
+    const dir = findInstalledPackage(name, from);
+    return dir ? readJson(path_1.default.join(dir, "package.json")).version ?? null : null;
+}
+/** Write a file, creating parent directories. Refuses to overwrite unless `force`. */
+function writeFileSafe(file, content, force = false) {
+    if (fs_1.default.existsSync(file) && !force) {
+        throw new errors_1.CliError(`${file} already exists. Use -f or --force to overwrite it.`);
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(file), { recursive: true });
+    fs_1.default.writeFileSync(file, content, "utf8");
+}
+/** Copy every non-TypeScript file under `srcDir` to the same relative path under `outDir`. */
+function copyAssets(srcDir, outDir) {
+    if (!fs_1.default.existsSync(srcDir))
+        return 0;
+    let copied = 0;
+    for (const entry of fs_1.default.readdirSync(srcDir, { withFileTypes: true, recursive: true })) {
+        if (!entry.isFile() || !isAsset(entry.name))
+            continue;
+        const parent = entry.parentPath ?? entry.path;
+        const from = path_1.default.join(parent, entry.name);
+        const to = path_1.default.join(outDir, path_1.default.relative(srcDir, from));
+        fs_1.default.mkdirSync(path_1.default.dirname(to), { recursive: true });
+        fs_1.default.copyFileSync(from, to);
+        copied++;
+    }
+    return copied;
+}
+function isAsset(file) {
+    return !/\.(c|m)?tsx?$/.test(file) && !path_1.default.basename(file).startsWith(".");
+}

package/dist/utils/stubs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The package root (the directory holding `stubs/` and `package.json`). Source
+ * files run from `src/**` under Vitest and from `dist/**` once built, so walk
+ * up from this file instead of assuming a fixed depth.
+ */
+export declare const packageRoot: string;
+export declare function stubPath(name: string): string;
+/**
+ * Read a stub and replace `{Key}` placeholders. Unknown placeholders are left
+ * untouched so object literals in stubs are safe.
+ */
+export declare function renderStub(name: string, vars?: Record<string, string>): string;
+export declare function cliVersion(): string;
+/** The `@avleon/core` range new projects should depend on (lockstep with the CLI). */
+export declare function coreRange(): string;

package/dist/utils/stubs.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageRoot = void 0;
+exports.stubPath = stubPath;
+exports.renderStub = renderStub;
+exports.cliVersion = cliVersion;
+exports.coreRange = coreRange;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * The package root (the directory holding `stubs/` and `package.json`). Source
+ * files run from `src/**` under Vitest and from `dist/**` once built, so walk
+ * up from this file instead of assuming a fixed depth.
+ */
+exports.packageRoot = (() => {
+    let dir = __dirname;
+    for (;;) {
+        if (fs_1.default.existsSync(path_1.default.join(dir, "stubs")) &&
+            fs_1.default.existsSync(path_1.default.join(dir, "package.json"))) {
+            return dir;
+        }
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            return path_1.default.resolve(__dirname, "..", "..");
+        dir = parent;
+    }
+})();
+function stubPath(name) {
+    return path_1.default.join(exports.packageRoot, "stubs", ...name.split("/"));
+}
+/**
+ * Read a stub and replace `{Key}` placeholders. Unknown placeholders are left
+ * untouched so object literals in stubs are safe.
+ */
+function renderStub(name, vars = {}) {
+    let content = fs_1.default.readFileSync(stubPath(name), "utf8").replace(/\r\n/g, "\n");
+    for (const [key, value] of Object.entries(vars)) {
+        content = content.split(`{${key}}`).join(value);
+    }
+    return content;
+}
+function cliVersion() {
+    return JSON.parse(fs_1.default.readFileSync(path_1.default.join(exports.packageRoot, "package.json"), "utf8")).version;
+}
+/** The `@avleon/core` range new projects should depend on (lockstep with the CLI). */
+function coreRange() {
+    const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join(exports.packageRoot, "package.json"), "utf8"));
+    return pkg.peerDependencies?.["@avleon/core"] ?? `^${pkg.version}`;
+}

package/dist/utils/tsconfig.d.ts

@@ -0,0 +1,13 @@
+export type TsConfigInfo = {
+    file: string;
+    compilerOptions: Record<string, any>;
+};
+/** Parse JSON that may contain comments and trailing commas, as tsconfig files do. */
+export declare function parseJsonc(text: string): any;
+/**
+ * Read a tsconfig and merge `extends` chains (relative paths and packages).
+ * Path-valued options (`baseUrl`, `outDir`, `rootDir`) are resolved to
+ * absolute paths relative to the file that declared them.
+ */
+export declare function readTsConfig(file: string, seen?: Set<string>): TsConfigInfo;
+export declare function findTsConfig(root: string, preferBuild?: boolean): string | null;

package/dist/utils/tsconfig.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJsonc = parseJsonc;
+exports.readTsConfig = readTsConfig;
+exports.findTsConfig = findTsConfig;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/** Parse JSON that may contain comments and trailing commas, as tsconfig files do. */
+function parseJsonc(text) {
+    let out = "";
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        const next = text[i + 1];
+        if (inString) {
+            out += ch;
+            if (ch === "\\") {
+                out += next ?? "";
+                i++;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+        }
+        else if (ch === "/" && next === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            out += "\n";
+        }
+        else if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i++;
+            i++;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
+}
+/**
+ * Read a tsconfig and merge `extends` chains (relative paths and packages).
+ * Path-valued options (`baseUrl`, `outDir`, `rootDir`) are resolved to
+ * absolute paths relative to the file that declared them.
+ */
+function readTsConfig(file, seen = new Set()) {
+    const abs = path_1.default.resolve(file);
+    if (seen.has(abs))
+        return { file: abs, compilerOptions: {} };
+    seen.add(abs);
+    const raw = parseJsonc(fs_1.default.readFileSync(abs, "utf8"));
+    const dir = path_1.default.dirname(abs);
+    let base = {};
+    const exts = raw.extends ? [].concat(raw.extends) : [];
+    for (const ext of exts) {
+        let target = null;
+        if (ext.startsWith(".") || path_1.default.isAbsolute(ext)) {
+            target = path_1.default.resolve(dir, ext);
+            if (!fs_1.default.existsSync(target) && fs_1.default.existsSync(target + ".json"))
+                target += ".json";
+        }
+        else {
+            try {
+                target = require.resolve(ext, { paths: [dir] });
+            }
+            catch {
+                target = null;
+            }
+        }
+        if (target && fs_1.default.existsSync(target)) {
+            base = { ...base, ...readTsConfig(target, seen).compilerOptions };
+        }
+    }
+    const own = { ...(raw.compilerOptions ?? {}) };
+    for (const key of ["baseUrl", "outDir", "rootDir"]) {
+        if (typeof own[key] === "string")
+            own[key] = path_1.default.resolve(dir, own[key]);
+    }
+    if (own.paths && own.baseUrl === undefined && base.baseUrl === undefined) {
+        // TypeScript resolves `paths` relative to the declaring tsconfig when baseUrl is unset.
+        own.pathsBasePath = dir;
+    }
+    return { file: abs, compilerOptions: { ...base, ...own } };
+}
+function findTsConfig(root, preferBuild = false) {
+    const names = preferBuild ? ["tsconfig.build.json", "tsconfig.json"] : ["tsconfig.json"];
+    for (const name of names) {
+        const file = path_1.default.join(root, name);
+        if (fs_1.default.existsSync(file))
+            return file;
+    }
+    return null;
+}

package/package.json

@@ -1,24 +1,30 @@
 {
   "name": "@avleon/cli",
-  "version": "0.0.47",
+  "version": "0.4.0",
   "description": "CLI for scaffolding and running Avleon applications",
   "author": "Tareq Hossain",
-  "license": "ISC",
+  "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "avleon": "./dist/cli.js"
+    "avleon": "dist/bin.js"
   },
   "files": [
     "dist",
     "stubs",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
-    "build": "rimraf dist && tsc",
-    "clean": "rimraf dist",
-    "prepublishOnly": "npm run build",
-    "watch": "tsc-watch --onSuccess \"echo Build complete\""
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "watch": "tsc -p tsconfig.json --watch",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "cli",
@@ -27,36 +33,31 @@
     "typescript"
   ],
   "dependencies": {
-    "@avleon/core": "*",
     "@swc/core": "^1.13.5",
     "chokidar": "^4.0.3",
-    "chalk": "^5.4.1",
-    "cli-table3": "^0.6.5",
-    "fs-extra": "^11.2.0",
-    "inquirer": "^12.6.0",
-    "lodash": "^4.17.21",
-    "prettier": "^3.3.3",
-    "rimraf": "^6.0.1"
+    "commander": "^14.0.0",
+    "inquirer": "^12.6.0"
   },
   "devDependencies": {
-    "@swc/cli": "^0.7.8",
-    "@types/fs-extra": "^11.0.4",
-    "@types/lodash": "^4.17.16",
     "@types/node": "^22.9.3",
-    "concurrently": "^9.2.1",
-    "nodemon": "^3.1.7",
-    "tsc-watch": "^6.2.1",
-    "tsup": "^8.4.0",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.12"
   },
   "peerDependencies": {
-    "@avleon/core": ">=0.0.38"
+    "@avleon/core": "^0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@avleon/core": {
+      "optional": true
+    }
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/avleonjs/avleon-cli"
+    "url": "git+https://github.com/avleonjs/avleon.git",
+    "directory": "packages/cli"
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "gitHead": "fe89f3bb068deb2794327a5aa8809ad3ed29ce87"
 }

package/readme.md

@@ -37,17 +37,26 @@ npm run start:dev
 
 | Command | Alias | Options | Description |
 |---------|-------|---------|-------------|
-| `new` | | `--minimal`, `-m` | Create a new application |
-| `serve` | | | Start the dev server with watch + rebuild |
-| `build` | | | Compile with `tsconfig.build.json` |
-| `make:model` | `m:m` | `-f`, `--orm` | Create a model / TypeORM entity |
-| `make:controller` | `m:c` | `-f`, `-r`, `-m <model>`, `-rt <dir>`, `--orm`, `--base-path` | Create a controller |
-| `make:service` | `m:s` | `-f`, `-r`, `-m <model>`, `-rt <dir>`, `--orm` | Create a service |
-| `make:config` | `m:cnf` | `-f` | Create a config class |
-| `make:middleware` | `m:mlwr` | `-f` | Create a middleware |
+| `new <name>` | | `-m`, `-f`, `-y`, `--pm <npm\|yarn\|pnpm>`, `--features <list>`, `--skip-install` | Create a new application |
+| `serve` | | `--entry <file>`, `--no-type-check`, `--debounce <ms>` | Dev server: SWC compile, run, reload on change |
+| `build` | | `-p <tsconfig>` | Compile with `tsconfig.build.json` and copy assets |
+| `start` | | `--entry <file>` | Run the compiled app with `NODE_ENV=production` |
+| `doctor` | | | Check Node.js, `@avleon/core`, `reflect-metadata` and decorator settings |
+| `route:list` | `routes` | `--json`, `--static` | List the app's routes |
+| `make:model` | `m:m` | `-f`, `--orm`, `--root <dir>` | Create a model / TypeORM entity |
+| `make:controller` | `m:c` | `-f`, `-r`, `-m <model>`, `--orm`, `--root <dir>`, `--base-path` | Create a controller |
+| `make:service` | `m:s` | `-f`, `-r`, `-m <model>`, `--orm`, `--root <dir>` | Create a service |
+| `make:config` | `m:cnf` | `-f`, `--root <dir>` | Create an `@AppConfig` class |
+| `make:middleware` | `m:mlwr` | `-f`, `--root <dir>` | Create a middleware |
+| `make:dto` | `m:dto` | `-f`, `--root <dir>` | Create a class-validator DTO |
 
 `-f` / `--force` overwrites an existing file. `-r` / `--resource` generates a
-full REST skeleton.
+full REST skeleton. `--root <dir>` (also `-rt`) writes under `src/<dir>`
+instead of the default folder. Names may be nested, e.g. `admin/User`.
+Run `avleon <command> --help` for details.
+
+Generated controllers must be registered in your app with
+`app.useControllers([...])`.
 
 ### Controller
 
@@ -112,5 +121,35 @@ npx avleon serve
 ```
 
 Compiles `src/` with SWC into `dist/`, starts the entry point, and restarts on
-change. The entry file is taken from `avleon.entry` in `package.json`, falling
-back to `main`.
+change to sources, assets or `.env*` files. The entry file is taken from
+`--entry`, `avleon.entry` in `package.json`, `main`, then `dist/serve.js`,
+`server.js`, `main.js` or `index.js`.
+
+Type errors are reported by a parallel `tsc --noEmit --watch` (disable with
+`--no-type-check`) and never block a reload. Syntax errors stop the app until
+they are fixed, so stale code never keeps serving.
+
+## Build and Run
+
+```sh
+npx avleon build   # tsc with tsconfig.build.json, then copy non-TS assets
+npx avleon start   # node dist/serve.js with NODE_ENV=production
+```
+
+## Routes
+
+```sh
+npx avleon route:list          # compile and read Avleon's route metadata
+npx avleon route:list --static # scan decorators in the source, no dependencies
+npx avleon routes --json
+```
+
+## Doctor
+
+```sh
+npx avleon doctor
+```
+
+Checks the Node.js version, that `@avleon/core` matches the CLI's version,
+that `reflect-metadata` is installed, and that `experimentalDecorators` and
+`emitDecoratorMetadata` are enabled. Exits non-zero if a check fails.

package/stubs/config/config.stub

@@ -0,0 +1,9 @@
+import { AppConfig, AvleonConfig, Environment } from '@avleon/core';
+
+@AppConfig
+export class {ClassName} extends AvleonConfig {
+  config(env: Environment) {
+    // Return this config's values, e.g. { secret: env.get('JWT_SECRET') }.
+    return {};
+  }
+}

package/stubs/controllers/basic-controller.stub

@@ -1,9 +1,9 @@
 import { ApiController, Get } from '@avleon/core';
 
-@ApiController('/{controller}s')
-export class {Controller}Controller {
+@ApiController('/{route}')
+export class {ClassName} {
   @Get()
   index() {
-    return '{controller} ok';
+    return { message: '{ClassName} works' };
   }
 }