zudojs-cli 0.1.2 → 1.1.0

package/dist/src/generators/frontend/frontendPipeline.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared frontend generation pipeline.
+ *
+ * Both `FrontendGenerator` (frontend-only projects) and `FullstackComposer`
+ * (the `apps/web` half of a fullstack project) drive frontend adapters. They
+ * used to do it with two different sequences: the fullstack path skipped
+ * availability checks, dependency resolution, dependency installation and
+ * adapter validation entirely. This module is the single sequence both use so
+ * the two paths cannot drift again.
+ *
+ * @module generators/frontend/pipeline
+ */
+import type { FrontendAdapter, FrontendGenerationContext } from "../../adapters/frontend/frontendAdapter.type.js";
+import type { PackageManagerRegistry } from "../../registries/adapter/packageManagerRegistry.core.js";
+import type { DependencyResolver } from "../../resolvers/dependency/dependencyResolver.core.js";
+/** Outcome of running the frontend pipeline for a single adapter. */
+export interface FrontendPipelineResult {
+    readonly files: readonly string[];
+    readonly errors: readonly string[];
+}
+/**
+ * Runs the full adapter sequence: availability check, scaffold, structure,
+ * integration, dependency resolution, dependency installation, validation.
+ */
+export declare function runFrontendPipeline(adapter: FrontendAdapter, context: FrontendGenerationContext, packageManagerRegistry: PackageManagerRegistry, dependencyResolver: DependencyResolver): Promise<FrontendPipelineResult>;
+//# sourceMappingURL=frontendPipeline.d.ts.map

package/dist/src/generators/frontend/frontendPipeline.js

@@ -0,0 +1,136 @@
+/**
+ * Shared frontend generation pipeline.
+ *
+ * Both `FrontendGenerator` (frontend-only projects) and `FullstackComposer`
+ * (the `apps/web` half of a fullstack project) drive frontend adapters. They
+ * used to do it with two different sequences: the fullstack path skipped
+ * availability checks, dependency resolution, dependency installation and
+ * adapter validation entirely. This module is the single sequence both use so
+ * the two paths cannot drift again.
+ *
+ * @module generators/frontend/pipeline
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileTree } from "../../utils/utils.fileSystem.js";
+/**
+ * Rejects package names a package manager would read as a flag.
+ *
+ * Adapter dependency lists are static today, but they are part of the public
+ * `FrontendAdapter` contract and a third-party adapter could return
+ * `--registry=...`. Package names go into an argv array (never a shell), so
+ * this closes argument injection rather than command injection.
+ */
+function assertSafePackageNames(names) {
+    for (const name of names) {
+        if (name.startsWith("-") || name.trim() === "" || /\s/.test(name)) {
+            throw new Error(`Refusing to install unsafe package name: "${name}"`);
+        }
+    }
+}
+/**
+ * Runs the full adapter sequence: availability check, scaffold, structure,
+ * integration, dependency resolution, dependency installation, validation.
+ */
+export async function runFrontendPipeline(adapter, context, packageManagerRegistry, dependencyResolver) {
+    const files = [];
+    const errors = [];
+    // 0. Fail fast with a readable message when the framework's own toolchain
+    //    is missing. Adapters such as Flutter shell out with no fallback, so
+    //    without this the user sees a bare ENOENT after the project directory
+    //    has already been created and rolled back.
+    const available = await adapter.isAvailable();
+    if (!available) {
+        return {
+            files,
+            errors: [
+                `The toolchain required by the "${adapter.name}" frontend is not available on this machine. Install it and re-run, or choose another frontend.`,
+            ],
+        };
+    }
+    // 1. Scaffold using the official tool (adapters fall back to built-in
+    //    templates where one exists).
+    await adapter.scaffold(context);
+    files.push("scaffold");
+    // 2. Apply the Zudojs structure over the scaffolded project.
+    await adapter.applyZudojsStructure(context);
+    files.push("structure");
+    // 3. Generate the adapter's integration files (API client, env helpers).
+    await adapter.generateIntegration(context);
+    files.push("integration");
+    // 4. Resolve dependencies and stop on conflicts.
+    const resolution = dependencyResolver.resolve(adapter.getDependencies(context));
+    if (resolution.conflicts.length > 0) {
+        for (const conflict of resolution.conflicts) {
+            errors.push(`Conflict: ${conflict.reason}`);
+        }
+        return { files, errors };
+    }
+    // 5. Install BOTH runtime and dev dependencies. Only devDependencies used
+    //    to be installed, so every runtime package an adapter declared was
+    //    resolved and then dropped on the floor. With `--no-install` the
+    //    dependencies are written to package.json for a later install.
+    const packageManager = packageManagerRegistry.get(context.packageManager);
+    if (context.skipInstall === true) {
+        await recordDependencies(context.projectPath, resolution.dependencies, resolution.devDependencies);
+        files.push("dependencies");
+    }
+    else if (packageManager) {
+        const deps = resolution.dependencies.map((d) => d.name);
+        const devDeps = resolution.devDependencies.map((d) => d.name);
+        assertSafePackageNames(deps);
+        assertSafePackageNames(devDeps);
+        if (deps.length > 0) {
+            await packageManager.add(context.projectPath, deps);
+        }
+        if (devDeps.length > 0) {
+            await packageManager.addDev(context.projectPath, devDeps);
+        }
+        files.push("dependencies");
+    }
+    else {
+        errors.push(`Unknown package manager: ${context.packageManager}`);
+    }
+    // 6. Validate the generated project and surface the adapter's own findings.
+    const validation = await adapter.validate(context);
+    if (!validation.valid) {
+        errors.push(...validation.errors);
+    }
+    return { files, errors };
+}
+/**
+ * Adds the resolved dependencies to the project's package.json without
+ * running a package manager. Existing entries win: the adapter's own
+ * template may already pin a version.
+ */
+async function recordDependencies(projectPath, dependencies, devDependencies) {
+    const pkgPath = join(projectPath, "package.json");
+    let pkg = {};
+    if (existsSync(pkgPath)) {
+        try {
+            pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        }
+        catch {
+            pkg = {};
+        }
+    }
+    const merge = (target, entries) => {
+        const merged = { ...(target ?? {}) };
+        for (const entry of entries) {
+            if (!(entry.name in merged)) {
+                merged[entry.name] = entry.version || "latest";
+            }
+        }
+        return merged;
+    };
+    if (dependencies.length > 0) {
+        pkg.dependencies = merge(pkg.dependencies, dependencies);
+    }
+    if (devDependencies.length > 0) {
+        pkg.devDependencies = merge(pkg.devDependencies, devDependencies);
+    }
+    await writeFileTree(projectPath, {
+        "package.json": JSON.stringify(pkg, null, 2) + "\n",
+    });
+}
+//# sourceMappingURL=frontendPipeline.js.map

package/dist/src/generators/fullstack/fullstackComposer.core.d.ts

@@ -12,6 +12,8 @@ import type { ProjectConfiguration } from "../../types/projectConfiguration.type
 export interface FullstackGenerationContext {
     readonly project: ProjectConfiguration;
     readonly projectPath: string;
+    /** `false` records frontend dependencies instead of installing them. */
+    readonly installDeps?: boolean;
 }
 /**
  * Fullstack generation result.
@@ -28,15 +30,14 @@ export declare class FullstackComposer {
     private readonly frontendRegistry;
     private readonly packageManagerRegistry;
     private readonly dependencyResolver;
-    private readonly integrationGenerator;
     constructor();
     /**
      * Generates a fullstack project.
      */
     generate(context: FullstackGenerationContext): Promise<FullstackGenerationResult>;
+    private getPackageManager;
     private createWorkspace;
     private generateSharedPackages;
     private generateFrontend;
-    private installDependencies;
 }
 //# sourceMappingURL=fullstackComposer.core.d.ts.map

package/dist/src/generators/fullstack/fullstackComposer.core.js

@@ -5,12 +5,14 @@
  *
  * @module generators/fullstack
  */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
 import { FrontendAdapterRegistry } from "../../registries/adapter/frontendAdapterRegistry.core.js";
 import { PackageManagerRegistry } from "../../registries/adapter/packageManagerRegistry.core.js";
 import { DependencyResolver } from "../../resolvers/dependency/dependencyResolver.core.js";
-import { IntegrationGenerator } from "../integration/integrationGenerator.core.js";
+import { runFrontendPipeline } from "../frontend/frontendPipeline.js";
 import { writeFileTree } from "../../utils/utils.fileSystem.js";
-import { execCommand } from "../../utils/utils.exec.js";
+import { renderPnpmWorkspaceFile } from "../../templates/shared/pnpm.template.js";
 /**
  * Composes fullstack projects by orchestrating multiple generators.
  */
@@ -18,12 +20,10 @@ export class FullstackComposer {
     frontendRegistry;
     packageManagerRegistry;
     dependencyResolver;
-    integrationGenerator;
     constructor() {
         this.frontendRegistry = new FrontendAdapterRegistry();
         this.packageManagerRegistry = new PackageManagerRegistry();
         this.dependencyResolver = new DependencyResolver();
-        this.integrationGenerator = new IntegrationGenerator();
     }
     /**
      * Generates a fullstack project.
@@ -34,7 +34,10 @@ export class FullstackComposer {
         try {
             // 1. Create workspace structure
             await this.createWorkspace(context);
-            files.push("package.json", "pnpm-workspace.yaml");
+            files.push("package.json");
+            if (this.getPackageManager(context) === "pnpm") {
+                files.push("pnpm-workspace.yaml");
+            }
             // 2. Generate shared packages
             await this.generateSharedPackages(context);
             files.push("packages/contracts/", "packages/shared-types/");
@@ -43,19 +46,8 @@ export class FullstackComposer {
                 const frontendFiles = await this.generateFrontend(context);
                 files.push(...frontendFiles);
             }
-            // 4. Generate integration files
-            await this.integrationGenerator.generate({
-                project: context.project,
-                projectPath: context.projectPath,
-                backendPort: 3000,
-                frontendPort: context.project.frontend?.framework === "next" ? 3000 : 5173,
-            });
-            files.push(".env.example", "config/cors.ts", ...(context.project.frontend?.framework === "react" ||
-                context.project.frontend?.framework === "vue"
-                ? ["vite.config.ts"]
-                : []));
-            // 5. Install dependencies
-            await this.installDependencies(context);
+            // Note: integration files and dependency installation are orchestrated
+            // by the create command to avoid running them twice.
         }
         catch (error) {
             errors.push(error instanceof Error ? error.message : String(error));
@@ -66,29 +58,50 @@ export class FullstackComposer {
             errors,
         };
     }
+    getPackageManager(context) {
+        return context.project.workspace?.packageManager ?? "pnpm";
+    }
     async createWorkspace(context) {
+        const packageManager = this.getPackageManager(context);
+        const workspaceGlobs = ["apps/*", "packages/*"];
+        const scriptFor = (script) => {
+            switch (packageManager) {
+                case "npm":
+                    return `npm run ${script} --workspaces --if-present`;
+                case "yarn":
+                    return `yarn workspaces run ${script}`;
+                case "bun":
+                    return `bun run --filter '*' ${script}`;
+                default:
+                    return `pnpm -r --parallel run ${script}`;
+            }
+        };
         const rootPackageJson = {
             name: context.project.name,
             private: true,
+            ...(packageManager === "pnpm" ? {} : { workspaces: workspaceGlobs }),
             scripts: {
-                dev: "pnpm --parallel dev",
-                build: "pnpm --parallel build",
-                test: "pnpm --parallel test",
-                lint: "pnpm --parallel lint",
-                typecheck: "pnpm --parallel typecheck",
+                dev: scriptFor("dev"),
+                build: scriptFor("build"),
+                test: scriptFor("test"),
+                lint: scriptFor("lint"),
+                typecheck: scriptFor("typecheck"),
             },
             devDependencies: {
                 typescript: "^5.0.0",
             },
         };
-        const workspaceYaml = `packages:
-   - "apps/*"
-   - "packages/*"
- `;
-        await writeFileTree(context.projectPath, {
-            "package.json": JSON.stringify(rootPackageJson, null, 2),
-            "pnpm-workspace.yaml": workspaceYaml,
-        });
+        // The project's type, architecture and frontend are recorded in
+        // .zudojs/manifest.json by the create command; no zudojs.config.ts is
+        // written. The name reaches package.json through JSON.stringify, so a
+        // quote or newline in it stays data.
+        const files = {
+            "package.json": JSON.stringify(rootPackageJson, null, 2) + "\n",
+        };
+        if (packageManager === "pnpm") {
+            files["pnpm-workspace.yaml"] = renderPnpmWorkspaceFile(workspaceGlobs);
+        }
+        await writeFileTree(context.projectPath, files);
     }
     async generateSharedPackages(context) {
         const contractsIndex = `/**
@@ -127,32 +140,34 @@ export type Timestamp = string;
         if (!adapter) {
             throw new Error(`Unknown frontend framework: ${context.project.frontend.framework}`);
         }
-        const frontendPath = `${context.projectPath}/apps/web`;
+        const frontendPath = join(context.projectPath, "apps", "web");
+        // Scaffolders spawn with cwd=frontendPath; the directory must exist
+        // before the child process starts or spawn fails with ENOENT.
+        await mkdir(frontendPath, { recursive: true });
         const frontendContext = {
             project: context.project,
             projectPath: frontendPath,
             framework: adapter.framework,
             language: context.project.frontend.language ?? "typescript",
             architecture: context.project.frontend.architecture,
-            packageManager: context.project.workspace?.packageManager ?? "pnpm",
+            packageManager: this.getPackageManager(context),
             features: {
                 testing: true,
                 linting: true,
                 formatting: true,
                 envValidation: true,
             },
+            ...(context.installDeps === false ? { skipInstall: true } : {}),
         };
-        await adapter.scaffold(frontendContext);
-        await adapter.applyZudojsStructure(frontendContext);
-        await adapter.generateIntegration(frontendContext);
-        return ["apps/web/"];
-    }
-    async installDependencies(context) {
-        const pmName = context.project.workspace?.packageManager ?? "pnpm";
-        const packageManager = this.packageManagerRegistry.get(pmName);
-        if (packageManager) {
-            await packageManager.install(context.projectPath);
+        // The same pipeline the frontend-only path uses: availability check,
+        // scaffold, structure, integration, dependency resolution + install, and
+        // adapter validation. Skipping any of it here is what let fullstack
+        // projects ship an unvalidated, dependency-less apps/web.
+        const outcome = await runFrontendPipeline(adapter, frontendContext, this.packageManagerRegistry, this.dependencyResolver);
+        if (outcome.errors.length > 0) {
+            throw new Error(`Frontend generation failed: ${outcome.errors.join("; ")}`);
         }
+        return ["apps/web/"];
     }
 }
 //# sourceMappingURL=fullstackComposer.core.js.map

package/dist/src/generators/infrastructure/infrastructure.generator.d.ts

@@ -13,6 +13,17 @@ export interface InfrastructureOptions {
 export declare class InfrastructureGenerator {
     generate(options: InfrastructureOptions, basePath: string): Promise<void>;
     private getFiles;
+    /**
+     * Install and build commands for Dockerfiles.
+     *
+     * Generated projects have no lockfile yet, so never use `npm ci` or
+     * `--frozen-lockfile`. pnpm and yarn need `corepack enable` on the bare
+     * node:24-alpine image; bun is not available there so it falls back to npm.
+     */
+    private getDockerCommands;
+    private getDatabaseCompose;
+    private getDatabaseUrl;
+    private getDbServiceBlock;
     private getAppDockerfile;
     private getServiceDockerfile;
     private getSimpleDockerCompose;

package/dist/src/generators/infrastructure/infrastructure.generator.js

@@ -4,8 +4,15 @@
  * Generates Docker, docker-compose, and database infrastructure files.
  */
 import { writeFileTree } from "../../utils/utils.fileSystem.js";
+import { CLIValidationError } from "../../errors/index.js";
+const SERVICE_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
 export class InfrastructureGenerator {
     async generate(options, basePath) {
+        for (const service of options.services ?? []) {
+            if (!SERVICE_NAME_PATTERN.test(service)) {
+                throw new CLIValidationError(`Invalid service name: "${service}". Service names must match ${SERVICE_NAME_PATTERN}.`);
+            }
+        }
         const files = this.getFiles(options);
         await writeFileTree(basePath, files);
     }
@@ -16,7 +23,7 @@ export class InfrastructureGenerator {
             files[".dockerignore"] = "node_modules\ndist\n.git\n.env\n";
             const services = options.services ?? ["gateway"];
             for (const service of services) {
-                files[`apps/${service}/Dockerfile`] =
+                files[`apps/services/${service}/Dockerfile`] =
                     this.getServiceDockerfile(options);
             }
         }
@@ -28,13 +35,83 @@ export class InfrastructureGenerator {
         files["migrations/.gitkeep"] = "";
         return files;
     }
+    /**
+     * Install and build commands for Dockerfiles.
+     *
+     * Generated projects have no lockfile yet, so never use `npm ci` or
+     * `--frozen-lockfile`. pnpm and yarn need `corepack enable` on the bare
+     * node:24-alpine image; bun is not available there so it falls back to npm.
+     */
+    getDockerCommands(options) {
+        switch (options.packageManager) {
+            case "pnpm":
+                return {
+                    install: "corepack enable && pnpm install",
+                    build: "pnpm run build",
+                };
+            case "yarn":
+                return {
+                    install: "corepack enable && yarn install",
+                    build: "yarn run build",
+                };
+            default:
+                return { install: "npm install", build: "npm run build" };
+        }
+    }
+    getDatabaseCompose(options) {
+        if (options.database === "mysql") {
+            return {
+                image: "mysql:8",
+                port: 3306,
+                environment: [
+                    "MYSQL_ROOT_PASSWORD=mysql",
+                    `MYSQL_DATABASE=${options.projectName}`,
+                ],
+                url: `mysql://root:mysql@db:3306/${options.projectName}`,
+                dataPath: "/var/lib/mysql",
+            };
+        }
+        if (options.database === "sqlite") {
+            // SQLite is file-based: no database service at all.
+            return null;
+        }
+        return {
+            image: "postgres:16-alpine",
+            port: 5432,
+            environment: [
+                "POSTGRES_USER=postgres",
+                "POSTGRES_PASSWORD=postgres",
+                `POSTGRES_DB=${options.projectName}`,
+            ],
+            url: `postgresql://postgres:postgres@db:5432/${options.projectName}`,
+            dataPath: "/var/lib/postgresql/data",
+        };
+    }
+    getDatabaseUrl(options) {
+        const db = this.getDatabaseCompose(options);
+        return db ? db.url : "sqlite:./.data/app.db";
+    }
+    getDbServiceBlock(db) {
+        return `  db:
+    image: ${db.image}
+    ports:
+      - "${db.port}:${db.port}"
+    environment:
+${db.environment.map((e) => `      - ${e}`).join("\n")}
+    volumes:
+      - db-data:${db.dataPath}
+
+volumes:
+  db-data:
+`;
+    }
     getAppDockerfile(options) {
+        const { install, build } = this.getDockerCommands(options);
         return `FROM node:24-alpine AS builder
 WORKDIR /app
-COPY package.json pnpm-lock.yaml ./
-RUN ${options.packageManager === "pnpm" ? "pnpm" : options.packageManager === "yarn" ? "yarn" : "npm"} install --frozen-lockfile
 COPY . .
-RUN ${options.packageManager === "pnpm" ? "pnpm" : options.packageManager === "yarn" ? "yarn" : "npm"} run build
+RUN ${install}
+RUN ${build}
 
 FROM node:24-alpine
 WORKDIR /app
@@ -46,12 +123,12 @@ CMD ["node", "dist/server.js"]
 `;
     }
     getServiceDockerfile(options) {
+        const { install, build } = this.getDockerCommands(options);
         return `FROM node:24-alpine AS builder
 WORKDIR /app
-COPY package.json pnpm-lock.yaml ./
-RUN ${options.packageManager === "pnpm" ? "pnpm" : options.packageManager === "yarn" ? "yarn" : "npm"} install --frozen-lockfile
 COPY . .
-RUN ${options.packageManager === "pnpm" ? "pnpm" : options.packageManager === "yarn" ? "yarn" : "npm"} run build
+RUN ${install}
+RUN ${build}
 
 FROM node:24-alpine
 WORKDIR /app
@@ -63,79 +140,42 @@ CMD ["node", "dist/server.js"]
 `;
     }
     getSimpleDockerCompose(options) {
-        const dbImage = options.database === "postgresql"
-            ? "postgres:16-alpine"
-            : options.database === "mysql"
-                ? "mysql:8"
-                : "alpine:latest";
-        return `version: "3.8"
-services:
+        const db = this.getDatabaseCompose(options);
+        const databaseUrl = this.getDatabaseUrl(options);
+        return `services:
   app:
     build: .
     ports:
       - "3000:3000"
     environment:
-      - DATABASE_URL=postgresql://postgres:postgres@db:5432/${options.projectName}
-    depends_on:
-      - db
-    develop:
+      - DATABASE_URL=${databaseUrl}
+${db ? "    depends_on:\n      - db\n" : ""}    develop:
       watch:
         - path: src/
           action: sync
           target: /app/src
-
-  db:
-    image: ${dbImage}
-    ports:
-      - "5432:5432"
-    environment:
-      - POSTGRES_USER=postgres
-      - POSTGRES_PASSWORD=postgres
-      - POSTGRES_DB=${options.projectName}
-    volumes:
-      - db-data:/var/lib/postgresql/data
-
-volumes:
-  db-data:
-`;
+${db ? `\n${this.getDbServiceBlock(db)}` : ""}`;
     }
     getDockerCompose(options) {
         const services = options.services ?? ["gateway"];
-        const dbImage = options.database === "postgresql"
-            ? "postgres:16-alpine"
-            : options.database === "mysql"
-                ? "mysql:8"
-                : "alpine:latest";
+        const db = this.getDatabaseCompose(options);
+        const databaseUrl = this.getDatabaseUrl(options);
         let serviceDefs = "";
-        for (const service of services) {
+        for (let i = 0; i < services.length; i++) {
+            const service = services[i];
+            const port = 3001 + i;
             serviceDefs += `
   ${service}:
     build:
-      context: apps/${service}
+      context: apps/services/${service}
     ports:
-      - "3000:3000"
+      - "${port}:${port}"
     environment:
-      - DATABASE_URL=postgresql://postgres:postgres@db:5432/${options.projectName}
-    depends_on:
-      - db
-`;
+      - PORT=${port}
+      - DATABASE_URL=${databaseUrl}
+${db ? "    depends_on:\n      - db\n" : ""}`;
         }
-        return `version: "3.8"
-services:${serviceDefs}
-  db:
-    image: ${dbImage}
-    ports:
-      - "5432:5432"
-    environment:
-      - POSTGRES_USER=postgres
-      - POSTGRES_PASSWORD=postgres
-      - POSTGRES_DB=${options.projectName}
-    volumes:
-      - db-data:/var/lib/postgresql/data
-
-volumes:
-  db-data:
-`;
+        return `services:${serviceDefs}${db ? `\n${this.getDbServiceBlock(db)}` : ""}`;
     }
 }
 //# sourceMappingURL=infrastructure.generator.js.map

package/dist/src/generators/integration/integrationGenerator.core.d.ts

@@ -22,6 +22,12 @@ export declare class IntegrationGenerator {
      */
     generate(context: IntegrationContext): Promise<void>;
     private generateEnvFile;
+    /**
+     * Path prefix (relative to projectPath) of the backend application.
+     *
+     * Ends with a "/" when non-empty so it can be prefixed directly.
+     */
+    private getBackendPath;
     private generateApiClient;
     private getApiClientPath;
     private generateCorsConfig;