zudojs-cli 2.0.1 → 2.1.0

package/README.md

@@ -13,9 +13,14 @@ Command-line interface for scaffolding, generating, and managing Zudojs framewor
 ### First time
 
 ```bash
-npm install -g zudojs-cli
+npm install -g zudojs      # or: npm install -g zudojs-cli
 ```
 
+Both packages install the same CLI under two names, `zudojs` and the short
+alias `zudo`; use whichever you prefer. `zudojs` is a thin wrapper that runs
+`zudojs-cli`, so the two can never disagree. Help, usage lines and error
+messages repeat the name you typed (`zudo create …` or `zudojs create …`).
+
 ### Upgrading from an old version?
 
 If `zudojs -v` doesn't match the latest npm version, clear the cache:
@@ -40,8 +45,8 @@ npm install -g zudojs-cli@latest
 ## Quick Start
 
 ```bash
-# Create a new backend project
-zudojs create my-api
+# Create a new backend project (`new` is an alias of `create`)
+zudo new my-api
 
 # Create a frontend project
 zudojs create my-web --type frontend --frontend react
@@ -65,6 +70,53 @@ zudojs build
 `zudojs build` and `zudojs doctor` exit with a non-zero status when they fail,
 so they can be used as CI gates.
 
+### Interactive menu
+
+Run `zudo` (or `zudojs`) with no arguments in a terminal to get a numbered
+menu:
+
+```text
+◆  What would you like to do?
+│  ● 1. Create a new project
+│  ○ 2. Start dev server
+│  ○ 3. Generate code
+│  ○ 4. Add a feature
+│  ○ 5. Build
+│  ○ 6. Doctor
+│  ○ 7. Info
+│  ○ 8. Help
+│  ○ 0. Exit
+└  ↑/↓ move · 0-8 pick · Enter select · Esc exit
+```
+
+Press a digit to pick an entry at once, or move with ↑/↓ and press Enter.
+The entry runs the ordinary command and asks for anything it needs:
+"Create" runs the usual `create` prompts, "Generate code" asks for the
+schematic and name, and "Add a feature" asks which feature. "Start dev
+server", "Generate code", "Add a feature" and "Build" need a Zudojs project;
+outside one, the menu says so and shows itself again. `0` exits with status 0;
+Esc or Ctrl+C prints "Operation cancelled." and exits with status 130, like
+every other prompt.
+
+The menu only opens when both stdin and stdout are terminals and `CI` is not
+set. Piped, redirected and CI runs (`zudo | cat`) print the help text and exit
+0, and `--help` / `--version` never open it.
+
+### Exit codes and usage errors
+
+| Status | Meaning |
+| ------ | ------- |
+| `0`    | Success (also `--help`, `--version`, and "Exit" from the menu) |
+| `1`    | The command ran and failed (build error, not in a project, …) |
+| `2`    | Usage error: missing argument, unknown or malformed option, option before the command |
+| `3`    | Unknown command (with a "Did you mean …?" suggestion when one is close) |
+| `130`  | Cancelled with Ctrl+C or Esc |
+
+Options go after the command name (`zudo dev --port 4000`); an option placed
+before it is reported instead of being dropped. Only the first word can be the
+command, so a typo such as `zudo creat my-api` is an error rather than a
+different command.
+
 ### Update check
 
 `zudojs info` asks npm whether a newer `zudojs-cli` exists and prints the
@@ -148,11 +200,11 @@ add domain logic to an existing app with
 
 | Command    | Description                                                              |
 | ---------- | ------------------------------------------------------------------------ |
-| `create`   | Scaffold a new project (backend, frontend, or fullstack)                 |
-| `generate` | Generate files — see the schematics below                                |
+| `create` (`new`) | Scaffold a new project (backend, frontend, or fullstack)           |
+| `generate` (`g`) | Generate files — see the schematics below                                |
 | `add`      | Add feature packages (database, queue, messaging, etc.); `--service` targets one microservice app |
-| `dev`      | Start development servers through the project's package manager (`pnpm run dev`, …) |
-| `build`    | Build the project with its detected package manager                      |
+| `dev` (`d`) | Start development servers through the project's package manager (`pnpm run dev`, …) |
+| `build` (`b`) | Build the project with its detected package manager                      |
 | `doctor`   | Run project diagnostics                                                  |
 | `info`     | Show project information                                                 |
 

package/dist/src/adapters/frontend/angular.adapter.d.ts

@@ -17,7 +17,6 @@ export declare class AngularAdapter implements FrontendAdapter {
     applyZudojsStructure(context: FrontendGenerationContext): Promise<void>;
     generateIntegration(context: FrontendGenerationContext): Promise<void>;
     validate(context: FrontendGenerationContext): Promise<ValidationResult>;
-    private getBaseFiles;
     private getStructure;
     private getIntegrationFiles;
 }

package/dist/src/adapters/frontend/angular.adapter.js

@@ -6,6 +6,8 @@
 import { writeFileTree } from "../../utils/utils.fileSystem.js";
 import { normalizeName } from "../../utils/utils.name.js";
 import { scaffoldWithFallback } from "../../scaffolders/scaffolder.helper.js";
+import { renderAngularFallback, versionFromRange } from "./fallback/index.js";
+import { ANGULAR_VITEST_VERSION_RANGE, DEPENDENCY_VERSION_RANGES as V, } from "../../resolvers/dependency/dependencyVersions.constant.js";
 /**
  * Angular adapter with standalone support.
  */
@@ -16,10 +18,9 @@ export class AngularAdapter {
         return true;
     }
     async getLatestVersion() {
-        return "19.0.0";
+        return versionFromRange(V["@angular/core"]);
     }
     async scaffold(context) {
-        const files = this.getBaseFiles(context);
         // Angular CLI requires a valid project name; "." is not one. Pass the
         // real name and scaffold into the current directory via --directory.
         const projectName = normalizeName(context.project.name) || "zudojs-app";
@@ -36,10 +37,11 @@ export class AngularAdapter {
                 "--routing",
                 "--style",
                 "css",
-                "--standalone",
+                "--package-manager",
+                context.packageManager,
             ],
             targetPath: context.projectPath,
-            fallbackFiles: files,
+            fallbackFiles: renderAngularFallback(context, projectName),
         });
     }
     getDependencies(context) {
@@ -48,7 +50,14 @@ export class AngularAdapter {
             deps.push({ name: "@ngrx/store", type: "dependency" });
         }
         if (context.features.testing) {
-            deps.push({ name: "@angular/core", type: "dependency" }, { name: "@angular/common", type: "dependency" }, { name: "jest", type: "devDependency" }, { name: "@angular-builders/jest", type: "devDependency" });
+            // Angular 22 runs unit tests through @angular/build:unit-test with
+            // Vitest, whose peer range is ^4 (not the ^5 other frameworks use).
+            // Jest via @angular-builders/jest fought the scaffolded builder.
+            deps.push({
+                name: "vitest",
+                version: ANGULAR_VITEST_VERSION_RANGE,
+                type: "devDependency",
+            }, { name: "jsdom", type: "devDependency" });
         }
         return deps;
     }
@@ -68,98 +77,6 @@ export class AngularAdapter {
         }
         return { valid: errors.length === 0, errors, warnings };
     }
-    getBaseFiles(context) {
-        return {
-            "package.json": JSON.stringify({
-                name: context.project.name,
-                version: "0.0.0",
-                private: true,
-                scripts: {
-                    start: "ng serve",
-                    build: "ng build",
-                    test: "ng test",
-                },
-                dependencies: {
-                    "@angular/animations": "^19.0.0",
-                    "@angular/common": "^19.0.0",
-                    "@angular/compiler": "^19.0.0",
-                    "@angular/core": "^19.0.0",
-                    "@angular/forms": "^19.0.0",
-                    "@angular/platform-browser": "^19.0.0",
-                    "@angular/platform-browser-dynamic": "^19.0.0",
-                    "@angular/router": "^19.0.0",
-                    rxjs: "~7.8.0",
-                    tslib: "^2.3.0",
-                    "zone.js": "~0.15.0",
-                },
-                devDependencies: {
-                    "@angular-devkit/build-angular": "^19.0.0",
-                    "@angular/cli": "^19.0.0",
-                    "@angular/compiler-cli": "^19.0.0",
-                    "@types/jasmine": "~5.1.0",
-                    "jasmine-core": "~5.1.0",
-                    karma: "~6.4.0",
-                    typescript: "~5.6.0",
-                },
-            }, null, 2),
-            "tsconfig.json": JSON.stringify({
-                compileOnSave: false,
-                compilerOptions: {
-                    outDir: "./dist/out-tsc",
-                    strict: true,
-                    noImplicitOverride: true,
-                    noPropertyAccessFromIndexSignature: true,
-                    noImplicitReturns: true,
-                    noFallthroughCasesInSwitch: true,
-                    esModuleInterop: true,
-                    sourceMap: true,
-                    declaration: false,
-                    downlevelIteration: true,
-                    experimentalDecorators: true,
-                    moduleResolution: "bundler",
-                    importHelpers: true,
-                    target: "ES2022",
-                    module: "ES2022",
-                    lib: ["ES2022", "dom"],
-                    useDefineForClassFields: true,
-                },
-                angularCompilerOptions: {
-                    enableI18nLegacyMessageIdFormat: false,
-                    strictInjectionParameters: true,
-                    strictInputAccessModifiers: true,
-                    strictTemplates: true,
-                },
-            }, null, 2),
-            "src/main.ts": `import { bootstrapApplication } from "@angular/platform-browser";
-import { AppComponent } from "./app/app.component";
-
-bootstrapApplication(AppComponent);
-`,
-            "src/index.html": `<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>${context.project.name}</title>
-    <base href="/" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
-  </head>
-  <body>
-    <app-root></app-root>
-  </body>
-</html>
-`,
-            "src/app/app.component.ts": `import { Component } from "@angular/core";
-
-@Component({
-  selector: "app-root",
-  standalone: true,
-  template: "<h1>Hello from Zudojs</h1>",
-})
-export class AppComponent {}
-`,
-        };
-    }
     getStructure(context) {
         return {
             "src/app/components/.gitkeep": "",

package/dist/src/adapters/frontend/astro.adapter.d.ts

@@ -17,7 +17,6 @@ export declare class AstroAdapter implements FrontendAdapter {
     applyZudojsStructure(context: FrontendGenerationContext): Promise<void>;
     generateIntegration(context: FrontendGenerationContext): Promise<void>;
     validate(context: FrontendGenerationContext): Promise<ValidationResult>;
-    private getBaseFiles;
     private getStructure;
     private getIntegrationFiles;
 }

package/dist/src/adapters/frontend/astro.adapter.js

@@ -5,6 +5,8 @@
  */
 import { writeFileTree } from "../../utils/utils.fileSystem.js";
 import { scaffoldWithFallback } from "../../scaffolders/scaffolder.helper.js";
+import { renderAstroFallback, versionFromRange } from "./fallback/index.js";
+import { DEPENDENCY_VERSION_RANGES as V } from "../../resolvers/dependency/dependencyVersions.constant.js";
 /**
  * Astro adapter with island architecture support.
  */
@@ -15,10 +17,10 @@ export class AstroAdapter {
         return true;
     }
     async getLatestVersion() {
-        return "5.0.0";
+        return versionFromRange(V.astro);
     }
     async scaffold(context) {
-        const files = this.getBaseFiles(context);
+        const files = renderAstroFallback(context);
         await scaffoldWithFallback({
             command: "npm",
             args: [
@@ -59,68 +61,6 @@ export class AstroAdapter {
         }
         return { valid: errors.length === 0, errors, warnings };
     }
-    getBaseFiles(context) {
-        return {
-            "package.json": JSON.stringify({
-                name: context.project.name,
-                version: "0.1.0",
-                private: true,
-                type: "module",
-                scripts: {
-                    dev: "astro dev",
-                    build: "astro build",
-                    preview: "astro preview",
-                },
-                dependencies: {
-                    astro: "^5.0.0",
-                },
-                devDependencies: {
-                    "@astrojs/check": "^0.9.0",
-                    typescript: "^5.0.0",
-                },
-            }, null, 2),
-            "astro.config.mjs": `import { defineConfig } from "astro/config";
-
-export default defineConfig({
-  output: "static",
-});
-`,
-            "tsconfig.json": JSON.stringify({
-                extends: "astro/tsconfigs/strict",
-                compilerOptions: {
-                    strict: true,
-                },
-            }, null, 2),
-            "src/layouts/Layout.astro": `---
-interface Props {
-  title: string;
-}
-
-const { title } = Astro.props;
----
-
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>\${title}</title>
-  </head>
-  <body>
-    <slot />
-  </body>
-</html>
-`,
-            "src/pages/index.astro": `---
-import Layout from "../layouts/Layout.astro";
----
-
-<Layout title="${context.project.name}">
-  <h1>Hello from Zudojs</h1>
-</Layout>
-`,
-        };
-    }
     getStructure(context) {
         return {
             "src/components/.gitkeep": "",

package/dist/src/adapters/frontend/fallback/fallback.helper.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared pieces of the built-in fallback templates.
+ *
+ * @module adapters/frontend/fallback/helper
+ */
+/** A generated file tree: project-relative path to file contents. */
+export type FallbackFileTree = Record<string, string>;
+/** Serialises a JSON config file the way the official scaffolders do. */
+export declare function renderJsonFile(value: unknown): string;
+/**
+ * Renders the `index.html` entry page Vite serves and builds from.
+ *
+ * @param title - The document title (the project name).
+ * @param mountId - The id of the element the app mounts into.
+ * @param entry - The root-relative module script, e.g. `/src/main.ts`.
+ */
+export declare function renderViteIndexHtml(title: string, mountId: string, entry: string): string;
+/**
+ * Compiler options shared by the Vite fallbacks, mirroring the
+ * `tsconfig.app.json` that `create-vite` 9 writes.
+ */
+export declare const VITE_TSCONFIG_COMPILER_OPTIONS: Readonly<{
+    target: "ES2023";
+    lib: string[];
+    module: "ESNext";
+    types: string[];
+    skipLibCheck: true;
+    moduleResolution: "bundler";
+    allowImportingTsExtensions: true;
+    verbatimModuleSyntax: true;
+    moduleDetection: "force";
+    noEmit: true;
+    strict: true;
+    noFallthroughCasesInSwitch: true;
+}>;
+/**
+ * Returns the lowest version a caret or tilde range admits, which is the
+ * release the range was written against (`"^8.3.0"` → `"8.3.0"`).
+ */
+export declare function versionFromRange(range: string): string;
+//# sourceMappingURL=fallback.helper.d.ts.map

package/dist/src/adapters/frontend/fallback/fallback.helper.js

@@ -0,0 +1,57 @@
+/**
+ * Shared pieces of the built-in fallback templates.
+ *
+ * @module adapters/frontend/fallback/helper
+ */
+/** Serialises a JSON config file the way the official scaffolders do. */
+export function renderJsonFile(value) {
+    return JSON.stringify(value, null, 2) + "\n";
+}
+/**
+ * Renders the `index.html` entry page Vite serves and builds from.
+ *
+ * @param title - The document title (the project name).
+ * @param mountId - The id of the element the app mounts into.
+ * @param entry - The root-relative module script, e.g. `/src/main.ts`.
+ */
+export function renderViteIndexHtml(title, mountId, entry) {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${title}</title>
+  </head>
+  <body>
+    <div id="${mountId}"></div>
+    <script type="module" src="${entry}"></script>
+  </body>
+</html>
+`;
+}
+/**
+ * Compiler options shared by the Vite fallbacks, mirroring the
+ * `tsconfig.app.json` that `create-vite` 9 writes.
+ */
+export const VITE_TSCONFIG_COMPILER_OPTIONS = Object.freeze({
+    target: "ES2023",
+    lib: ["ES2023", "DOM", "DOM.Iterable"],
+    module: "ESNext",
+    types: ["vite/client"],
+    skipLibCheck: true,
+    moduleResolution: "bundler",
+    allowImportingTsExtensions: true,
+    verbatimModuleSyntax: true,
+    moduleDetection: "force",
+    noEmit: true,
+    strict: true,
+    noFallthroughCasesInSwitch: true,
+});
+/**
+ * Returns the lowest version a caret or tilde range admits, which is the
+ * release the range was written against (`"^8.3.0"` → `"8.3.0"`).
+ */
+export function versionFromRange(range) {
+    return range.replace(/^[\^~]/, "");
+}
+//# sourceMappingURL=fallback.helper.js.map

package/dist/src/adapters/frontend/fallback/framework/angular/angular.fallback.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Built-in Angular template, written when `ng new` cannot run.
+ *
+ * @module adapters/frontend/fallback/framework/angular
+ */
+import type { FrontendGenerationContext } from "../../../frontendAdapter.type.js";
+import { type FallbackFileTree } from "../../fallback.helper.js";
+/**
+ * Renders the Angular 22 fallback project, matching `ng new --routing
+ * --style css`: a zoneless standalone app built by `@angular/build` and
+ * tested with Vitest. The previous fallback had no `angular.json`, so
+ * `ng build` could not run in it.
+ *
+ * @param context - The generation context.
+ * @param projectName - The normalised name `ng new` would receive.
+ */
+export declare function renderAngularFallback(context: FrontendGenerationContext, projectName: string): FallbackFileTree;
+//# sourceMappingURL=angular.fallback.d.ts.map

package/dist/src/adapters/frontend/fallback/framework/angular/angular.fallback.js

@@ -0,0 +1,107 @@
+/**
+ * Built-in Angular template, written when `ng new` cannot run.
+ *
+ * @module adapters/frontend/fallback/framework/angular
+ */
+import { ANGULAR_VITEST_VERSION_RANGE, DEPENDENCY_VERSION_RANGES as V, TYPESCRIPT_VERSION_RANGES, } from "../../../../../resolvers/dependency/dependencyVersions.constant.js";
+import { renderJsonFile } from "../../fallback.helper.js";
+import { renderAngularTsconfigs, renderAngularWorkspace, } from "./angularWorkspace.fallback.js";
+/**
+ * Renders the Angular 22 fallback project, matching `ng new --routing
+ * --style css`: a zoneless standalone app built by `@angular/build` and
+ * tested with Vitest. The previous fallback had no `angular.json`, so
+ * `ng build` could not run in it.
+ *
+ * @param context - The generation context.
+ * @param projectName - The normalised name `ng new` would receive.
+ */
+export function renderAngularFallback(context, projectName) {
+    return {
+        "package.json": renderJsonFile({
+            name: context.project.name,
+            version: "0.0.0",
+            private: true,
+            scripts: {
+                ng: "ng",
+                start: "ng serve",
+                build: "ng build",
+                watch: "ng build --watch --configuration development",
+                test: "ng test",
+            },
+            dependencies: {
+                "@angular/common": V["@angular/common"],
+                "@angular/compiler": V["@angular/compiler"],
+                "@angular/core": V["@angular/core"],
+                "@angular/forms": V["@angular/forms"],
+                "@angular/platform-browser": V["@angular/platform-browser"],
+                "@angular/router": V["@angular/router"],
+                rxjs: V.rxjs,
+                tslib: V.tslib,
+            },
+            devDependencies: {
+                "@angular/build": V["@angular/build"],
+                "@angular/cli": V["@angular/cli"],
+                "@angular/compiler-cli": V["@angular/compiler-cli"],
+                jsdom: V.jsdom,
+                typescript: TYPESCRIPT_VERSION_RANGES.frontend,
+                vitest: ANGULAR_VITEST_VERSION_RANGE,
+            },
+        }),
+        "angular.json": renderAngularWorkspace(projectName, context.packageManager),
+        ...renderAngularTsconfigs(),
+        "public/.gitkeep": "",
+        "src/styles.css": "",
+        "src/index.html": `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>${context.project.name}</title>
+  <base href="/">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+</head>
+<body>
+  <app-root></app-root>
+</body>
+</html>
+`,
+        "src/main.ts": `import { bootstrapApplication } from "@angular/platform-browser";
+import { appConfig } from "./app/app.config";
+import { App } from "./app/app";
+
+bootstrapApplication(App, appConfig).catch((err) => console.error(err));
+`,
+        "src/app/app.config.ts": `import { type ApplicationConfig, provideBrowserGlobalErrorListeners } from "@angular/core";
+import { provideRouter } from "@angular/router";
+import { routes } from "./app.routes";
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideBrowserGlobalErrorListeners(), provideRouter(routes)],
+};
+`,
+        "src/app/app.routes.ts": `import type { Routes } from "@angular/router";
+
+export const routes: Routes = [];
+`,
+        "src/app/app.ts": `import { Component } from "@angular/core";
+import { RouterOutlet } from "@angular/router";
+
+@Component({
+  selector: "app-root",
+  imports: [RouterOutlet],
+  template: "<h1>Hello from Zudojs</h1><router-outlet />",
+})
+export class App {}
+`,
+        "src/app/app.spec.ts": `import { TestBed } from "@angular/core/testing";
+import { App } from "./app";
+
+describe("App", () => {
+  it("creates the app", async () => {
+    await TestBed.configureTestingModule({ imports: [App] }).compileComponents();
+    expect(TestBed.createComponent(App).componentInstance).toBeTruthy();
+  });
+});
+`,
+    };
+}
+//# sourceMappingURL=angular.fallback.js.map

package/dist/src/adapters/frontend/fallback/framework/angular/angularWorkspace.fallback.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Workspace configuration (`angular.json`, tsconfigs) for the built-in
+ * Angular fallback.
+ *
+ * @module adapters/frontend/fallback/framework/angular/workspace
+ */
+import { type FallbackFileTree } from "../../fallback.helper.js";
+/**
+ * Renders the Angular CLI workspace file `ng new` 22 writes. Builds, the dev
+ * server and unit tests all go through `@angular/build`; the deprecated
+ * `@angular-devkit/build-angular` and its Karma/Jasmine test runner are no
+ * longer used.
+ *
+ * @param projectName - The normalised project name used as the project key.
+ * @param packageManager - Recorded as the CLI's package manager.
+ */
+export declare function renderAngularWorkspace(projectName: string, packageManager: string): string;
+/**
+ * Renders the solution-style tsconfigs `ng new` 22 writes: a base config
+ * referencing an app config and a Vitest spec config.
+ */
+export declare function renderAngularTsconfigs(): FallbackFileTree;
+//# sourceMappingURL=angularWorkspace.fallback.d.ts.map