zudojs-cli 0.1.1 → 1.0.0

package/dist/src/templates/shared/appRuntime.template.js

@@ -0,0 +1,209 @@
+/**
+ * zudojs-cli — Shared Runtime App Templates
+ *
+ * Every architecture template assembles the same four framework pieces:
+ * a logger, a container, an event bus and a set of modules, handed to
+ * `createRuntime(dependencies, options)`.
+ *
+ * The emitted source is kept here rather than duplicated per architecture
+ * so it can be verified against the real `@zudojs/*` packages in one place.
+ * `tests/generatedProject.typecheck.test.ts` type-checks the output of every
+ * template against `packages/<name>/src/index.ts`, so any drift between these
+ * snippets and the framework API fails the CLI test suite.
+ */
+import { toPascalCase } from "../../utils/utils.name.js";
+/** Packages every generated runtime entry point imports from. */
+export const RUNTIME_APP_DEPENDENCIES = [
+    "@zudojs/core",
+    "@zudojs/runtime",
+    "@zudojs/container",
+    "@zudojs/events",
+    "@zudojs/logger",
+    "@zudojs/constants",
+];
+/** Builds a module spec from a raw name. */
+export function moduleSpec(name, importPath) {
+    return {
+        name,
+        className: `${toPascalCase(name)}Module`,
+        importPath,
+    };
+}
+/** Emits a string as a TypeScript string literal that cannot break out. */
+function literal(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Renders `zudojs.config.ts`.
+ *
+ * The shape matches what the fullstack composer writes and what
+ * `zudojs generate` parses to detect the project architecture.
+ */
+export function renderZudojsConfig(options) {
+    return `/**
+ * Zudojs project configuration.
+ *
+ * Read by the \`zudojs\` CLI to detect this project's architecture.
+ */
+
+export default {
+  name: ${literal(options.projectName)},
+  projectType: ${literal(options.projectType)},
+  architecture: ${literal(options.architecture)},
+};
+`;
+}
+/**
+ * Renders `src/app.ts`: assembles the runtime dependencies and returns a
+ * started-on-demand `Runtime`.
+ */
+export function renderAppFile(options) {
+    const imports = [...options.modules]
+        .map((m) => `import { ${m.className} } from ${literal(m.importPath)};`)
+        .join("\n");
+    // An empty array literal would make the loop variable `never`, so the
+    // registration loop is only emitted when there is at least one module.
+    const registration = options.modules.length > 0
+        ? `  for (const module of [
+${options.modules.map((m) => `    new ${m.className}(),`).join("\n")}
+  ]) {
+    modules.set(module.id, module);
+  }
+`
+        : "";
+    const metadata = options.port === undefined
+        ? ""
+        : `\n      metadata: { port: ${options.port} },`;
+    return `import type { Environment } from "@zudojs/constants";
+import { createContainer } from "@zudojs/container";
+import type { Module } from "@zudojs/core";
+import { createEventBus } from "@zudojs/events";
+import { createLogger } from "@zudojs/logger";
+import { createRuntime, type Runtime } from "@zudojs/runtime";
+${imports}
+
+const ENVIRONMENTS: readonly Environment[] = [
+  "development",
+  "test",
+  "staging",
+  "production",
+];
+
+/** Narrows NODE_ENV to a framework Environment without an unchecked cast. */
+function resolveEnvironment(): Environment {
+  const value = process.env["NODE_ENV"];
+  return ENVIRONMENTS.find((candidate) => candidate === value) ?? "development";
+}
+
+/**
+ * Assembles the application runtime.
+ *
+ * \`createRuntime\` takes two arguments: the dependencies the runtime and its
+ * modules share, and the options describing this application.
+ */
+export function createApp(): Runtime {
+  const logger = createLogger({ name: ${literal(options.applicationName)} });
+  const container = createContainer();
+  const eventBus = createEventBus();
+
+  const modules = new Map<string, Module>();
+${registration}
+  const runtime = createRuntime(
+    { modules, logger, container, eventBus },
+    {
+      applicationName: ${literal(options.applicationName)},
+      applicationVersion: "0.1.0",
+      environment: resolveEnvironment(),
+      // Signals are handled explicitly in server.ts.
+      handleSignals: false,${metadata}
+    },
+  );
+
+  runtime.registerReadinessCheck("modules", () => runtime.state === "running");
+
+  return runtime;
+}
+`;
+}
+/**
+ * Renders `src/server.ts`: the process entry point. Starts the runtime and
+ * stops it cleanly on SIGINT/SIGTERM.
+ */
+export function renderServerFile(appImportPath = "./app.js") {
+    return `import { createApp } from ${literal(appImportPath)};
+
+const runtime = createApp();
+
+await runtime.start();
+
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.once(signal, () => {
+    void runtime
+      .stop()
+      .then(() => {
+        process.exit(0);
+      })
+      .catch((error: unknown) => {
+        console.error(error);
+        process.exit(1);
+      });
+  });
+}
+`;
+}
+/**
+ * Renders a module class extending `BaseModule`.
+ *
+ * `BaseModule`'s constructor is protected, so the generated class declares a
+ * public constructor — without one the class cannot be instantiated.
+ */
+export function renderModuleFile(options) {
+    const { module, service } = options;
+    const serviceImport = service
+        ? `import { ${service.className} } from ${literal(service.importPath)};\n`
+        : "";
+    const serviceField = service
+        ? `  private readonly service = new ${service.className}();\n\n`
+        : "";
+    const serviceInit = service ? "    await this.service.initialize();\n" : "";
+    return `import { BaseModule, type ModuleContext } from "@zudojs/core";
+${serviceImport}
+/**
+ * ${module.name} module.
+ *
+ * Registered with the runtime in app.ts. The runtime calls onInitialize
+ * during start and onShutdown during stop.
+ */
+export class ${module.className} extends BaseModule {
+  public readonly id = ${literal(module.name)};
+  public readonly name = ${literal(module.name)};
+
+${serviceField}  public constructor() {
+    super({ version: "0.1.0" });
+  }
+
+  public override async onInitialize(context: ModuleContext): Promise<void> {
+${serviceInit}    context.logger.info(${literal(`${module.name} module initialized`)});
+  }
+
+  public override async onShutdown(context: ModuleContext): Promise<void> {
+    context.logger.info(${literal(`${module.name} module stopped`)});
+  }
+}
+`;
+}
+/** Renders a service class using the real `createLogger` factory. */
+export function renderServiceFile(name) {
+    const className = `${toPascalCase(name)}Service`;
+    return `import { createLogger } from "@zudojs/logger";
+
+export class ${className} {
+  private readonly logger = createLogger({ name: ${literal(`${name}-service`)} });
+
+  public async initialize(): Promise<void> {
+    this.logger.info(${literal(`${name} service initialized`)});
+  }
+}
+`;
+}
+//# sourceMappingURL=appRuntime.template.js.map

package/dist/src/templates/shared/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * zudojs-cli — Shared Template Fragments
+ */
+export * from "./appRuntime.template.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/templates/shared/index.js

@@ -0,0 +1,5 @@
+/**
+ * zudojs-cli — Shared Template Fragments
+ */
+export * from "./appRuntime.template.js";
+//# sourceMappingURL=index.js.map

package/dist/src/utils/index.d.ts

@@ -3,8 +3,8 @@
  *
  * Shared utility functions for the CLI scaffolding system.
  */
-export { writeFile, writeFileTree } from "./utils.fileSystem.js";
-export { normalizeName } from "./utils.name.js";
+export { writeFile, writeFileTree, mergeBarrelExport, } from "./utils.fileSystem.js";
+export { normalizeName, toPascalCase, toCamelCase } from "./utils.name.js";
 export { detectArchitecture } from "./utils.detect.js";
-export { execCommand } from "./utils.exec.js";
+export { execCommand, runStreaming } from "./utils.exec.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.js

@@ -3,8 +3,8 @@
  *
  * Shared utility functions for the CLI scaffolding system.
  */
-export { writeFile, writeFileTree } from "./utils.fileSystem.js";
-export { normalizeName } from "./utils.name.js";
+export { writeFile, writeFileTree, mergeBarrelExport, } from "./utils.fileSystem.js";
+export { normalizeName, toPascalCase, toCamelCase } from "./utils.name.js";
 export { detectArchitecture } from "./utils.detect.js";
-export { execCommand } from "./utils.exec.js";
+export { execCommand, runStreaming } from "./utils.exec.js";
 //# sourceMappingURL=index.js.map

package/dist/src/utils/utils.exec.d.ts

@@ -2,5 +2,23 @@ export interface ExecResult {
     readonly stdout: string;
     readonly stderr: string;
 }
-export declare function execCommand(file: string, args: readonly string[], cwd: string): Promise<ExecResult>;
+export interface ExecOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timeout?: number;
+}
+/**
+ * Runs a short-lived command and buffers its output.
+ *
+ * Suitable for quick probes (version checks, git commands). Do NOT use this
+ * for long-running processes such as dev servers or dependency installs —
+ * use {@link runStreaming} instead.
+ */
+export declare function execCommand(file: string, args: readonly string[], cwd: string, options?: ExecOptions): Promise<ExecResult>;
+/**
+ * Runs a command with inherited stdio and no timeout.
+ *
+ * Use for long-running processes (dev servers) and for dependency installs
+ * so output streams to the user and slow commands are not killed.
+ */
+export declare function runStreaming(file: string, args: readonly string[], cwd: string, options?: ExecOptions): Promise<void>;
 //# sourceMappingURL=utils.exec.d.ts.map

package/dist/src/utils/utils.exec.js

@@ -1,11 +1,45 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
-export async function execCommand(file, args, cwd) {
+/**
+ * Runs a short-lived command and buffers its output.
+ *
+ * Suitable for quick probes (version checks, git commands). Do NOT use this
+ * for long-running processes such as dev servers or dependency installs —
+ * use {@link runStreaming} instead.
+ */
+export async function execCommand(file, args, cwd, options = {}) {
     const { stdout, stderr } = await execFileAsync(file, args, {
         cwd,
-        timeout: 120000,
+        timeout: options.timeout ?? 120000,
+        ...(options.env ? { env: options.env } : {}),
     });
     return { stdout, stderr };
 }
+/**
+ * Runs a command with inherited stdio and no timeout.
+ *
+ * Use for long-running processes (dev servers) and for dependency installs
+ * so output streams to the user and slow commands are not killed.
+ */
+export function runStreaming(file, args, cwd, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, Array.from(args), {
+            cwd,
+            stdio: "inherit",
+            ...(options.env ? { env: options.env } : {}),
+        });
+        child.on("error", (error) => {
+            reject(error);
+        });
+        child.on("exit", (code, signal) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`Command "${file} ${args.join(" ")}" exited with ${signal ? `signal ${signal}` : `code ${code}`}`));
+            }
+        });
+    });
+}
 //# sourceMappingURL=utils.exec.js.map

package/dist/src/utils/utils.fileSystem.d.ts

@@ -1,3 +1,9 @@
 export declare function writeFile(basePath: string, filePath: string, content: string): Promise<void>;
 export declare function writeFileTree(basePath: string, files: Readonly<Record<string, string>>): Promise<void>;
+/**
+ * Returns the content of a barrel index file with `exportLine` appended,
+ * preserving any existing exports. If the line is already present, the
+ * existing content is returned unchanged.
+ */
+export declare function mergeBarrelExport(basePath: string, indexPath: string, exportLine: string): string;
 //# sourceMappingURL=utils.fileSystem.d.ts.map

package/dist/src/utils/utils.fileSystem.js

@@ -1,3 +1,4 @@
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir, writeFile as writeFileAsync } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 function assertSafePath(basePath, filePath) {
@@ -18,4 +19,22 @@ export async function writeFileTree(basePath, files) {
         await writeFile(basePath, filePath, content);
     }
 }
+/**
+ * Returns the content of a barrel index file with `exportLine` appended,
+ * preserving any existing exports. If the line is already present, the
+ * existing content is returned unchanged.
+ */
+export function mergeBarrelExport(basePath, indexPath, exportLine) {
+    const fullPath = join(basePath, indexPath);
+    const line = exportLine.trim();
+    let existing = "";
+    if (existsSync(fullPath)) {
+        existing = readFileSync(fullPath, "utf-8");
+    }
+    if (existing.includes(line)) {
+        return existing;
+    }
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    return existing + separator + line + "\n";
+}
 //# sourceMappingURL=utils.fileSystem.js.map

package/dist/src/utils/utils.name.d.ts

@@ -1,2 +1,28 @@
 export declare function normalizeName(name: string): string;
+/** Converts an arbitrary name to PascalCase (safe as a TS identifier). */
+export declare function toPascalCase(name: string): string;
+/** Converts an arbitrary name to camelCase (safe as a TS identifier). */
+export declare function toCamelCase(name: string): string;
+/**
+ * Pattern for names that may be used verbatim as a path segment
+ * (`--service`, `--module`, manifest service entries).
+ */
+export declare const SAFE_PATH_SEGMENT: RegExp;
+/**
+ * Validates a name that a generator will normalize into file paths and
+ * identifiers.
+ *
+ * `normalizeName` strips everything outside `[a-z0-9-]`, so a name such as
+ * `"..."` or `"!!!"` collapses to the empty string and the generator writes
+ * `src//.event.ts` with an anonymous exported class. Reject it up front.
+ */
+export declare function assertGeneratableName(name: string, kind?: string): string;
+/**
+ * Validates a value that is interpolated verbatim into a generated file path.
+ *
+ * Unlike {@link assertGeneratableName} this does not normalize: the value is
+ * used as-is, so `..` or a path separator here would let a generator write
+ * outside its base path.
+ */
+export declare function assertSafePathSegment(value: string, kind?: string): string;
 //# sourceMappingURL=utils.name.d.ts.map

package/dist/src/utils/utils.name.js

@@ -1,8 +1,58 @@
+import { CLIValidationError } from "../errors/index.js";
 export function normalizeName(name) {
     return name
         .trim()
         .toLowerCase()
         .replace(/[^a-z0-9-]+/g, "-")
-        .replace(/^-+|-+$/g, "");
+        // Trim leading/trailing dashes without the quadratic `-+$` scan: the
+        // lookbehind pins each attempt to the start of a dash run.
+        .replace(/^-+/, "")
+        .replace(/(?<!-)-+$/, "");
+}
+/** Converts an arbitrary name to PascalCase (safe as a TS identifier). */
+export function toPascalCase(name) {
+    return normalizeName(name)
+        .split("-")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+}
+/** Converts an arbitrary name to camelCase (safe as a TS identifier). */
+export function toCamelCase(name) {
+    const pascal = toPascalCase(name);
+    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+/**
+ * Pattern for names that may be used verbatim as a path segment
+ * (`--service`, `--module`, manifest service entries).
+ */
+export const SAFE_PATH_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/**
+ * Validates a name that a generator will normalize into file paths and
+ * identifiers.
+ *
+ * `normalizeName` strips everything outside `[a-z0-9-]`, so a name such as
+ * `"..."` or `"!!!"` collapses to the empty string and the generator writes
+ * `src//.event.ts` with an anonymous exported class. Reject it up front.
+ */
+export function assertGeneratableName(name, kind = "name") {
+    const normalized = normalizeName(name);
+    if (normalized === "") {
+        throw new CLIValidationError(`Invalid ${kind}: "${name}". It must contain at least one letter or digit.`);
+    }
+    return normalized;
+}
+/**
+ * Validates a value that is interpolated verbatim into a generated file path.
+ *
+ * Unlike {@link assertGeneratableName} this does not normalize: the value is
+ * used as-is, so `..` or a path separator here would let a generator write
+ * outside its base path.
+ */
+export function assertSafePathSegment(value, kind = "value") {
+    if (!SAFE_PATH_SEGMENT.test(value)) {
+        throw new CLIValidationError(`Invalid ${kind}: "${value}". Only alphanumeric characters, hyphens, and underscores are allowed.`);
+    }
+    return value;
 }
 //# sourceMappingURL=utils.name.js.map

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "zudojs-cli",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "description": "Command-line interface for scaffolding, generating, and managing Zudojs framework projects.",
   "license": "MIT",
   "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/src/index.js",
+  "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
     }
   },
   "bin": {
@@ -18,28 +18,22 @@
   },
   "files": [
     "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo",
     "src/scripts/postinstall.cjs"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json && mkdir -p dist/src/scripts && cp src/scripts/postinstall.cjs dist/src/scripts/postinstall.cjs",
-    "dev": "tsx src/bin/zudojs.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "postinstall": "node src/scripts/postinstall.cjs"
-  },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@zudojs/config": "0.1.0",
-    "@zudojs/core": "0.1.0",
-    "@zudojs/errors": "0.1.0",
-    "@zudojs/logger": "0.1.0"
+    "@zudojs/config": "1.0.0",
+    "@zudojs/core": "1.0.0",
+    "@zudojs/errors": "1.0.0",
+    "@zudojs/logger": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",
     "tsx": "^4.23.12",
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "engines": {
@@ -56,8 +50,21 @@
     "dev"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/cli"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && mkdir -p dist/src/scripts && cp src/scripts/postinstall.cjs dist/src/scripts/postinstall.cjs",
+    "dev": "tsx src/bin/zudojs.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "postinstall": "node src/scripts/postinstall.cjs"
   }
-}
+}

package/src/scripts/postinstall.cjs

@@ -25,7 +25,7 @@ async function checkLatestVersion(packageName) {
     const timeout = setTimeout(() => controller.abort(), 5000);
 
     const response = await fetch(
-      `https://registry.npmjs.org/latest/${packageName}`,
+      `https://registry.npmjs.org/${packageName}/latest`,
       { signal: controller.signal },
     );
     clearTimeout(timeout);
@@ -41,15 +41,36 @@ async function checkLatestVersion(packageName) {
   }
 }
 
+/**
+ * Whether the update check should be skipped.
+ *
+ * The check reaches out to registry.npmjs.org on every install. That is
+ * unwanted in CI, in Docker builds and on air-gapped machines, and there was
+ * previously no way to turn it off.
+ */
+function shouldSkip() {
+  if (process.env.ZUDOJS_NO_UPDATE_CHECK) return true;
+  if (process.env.CI) return true;
+  if (process.env.NODE_ENV === "test") return true;
+  if (process.env.npm_config_offline === "true") return true;
+  // Only a global install is the one the user upgrades with `npm i -g`.
+  if (process.env.npm_config_global !== "true") return true;
+  return false;
+}
+
 async function main() {
+  if (shouldSkip()) {
+    return;
+  }
+
   const installed = getInstalledVersion();
-  const latest = await checkLatestVersion("@zudojs/cli");
+  const latest = await checkLatestVersion("zudojs-cli");
 
   if (latest && latest !== installed) {
     console.log(
       `\n  zudojs ${installed} is installed, but version ${latest} is available.`,
     );
-    console.log(`   Run: npm install -g @zudojs/cli@latest\n`);
+    console.log(`   Run: npm install -g zudojs-cli@latest\n`);
   }
 }