zudojs-cli 1.2.1 → 2.0.0

package/dist/src/manifest/manifestFile.helper.js

@@ -0,0 +1,141 @@
+/**
+ * zudojs-cli — Manifest File Helpers
+ *
+ * Parsing, validation, atomic writes and locking for
+ * `.zudojs/manifest.json`. Kept apart from the manager so the manager stays
+ * a thin read/modify/write API over them.
+ */
+import { open, rename, rm, stat, writeFile } from "node:fs/promises";
+const LOCK_TIMEOUT_MS = 5_000;
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_MS = 20;
+/**
+ * Parses manifest text, filling in the fields an older CLI (or a hand edit)
+ * may have left out.
+ *
+ * `capabilities` used to be read straight off an unvalidated cast, so a
+ * manifest without it threw a TypeError from inside `addCapability`.
+ */
+export function parseManifest(content) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            manifest: null,
+            reason: `not valid JSON (${error instanceof Error ? error.message : String(error)})`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            status: "invalid",
+            manifest: null,
+            reason: "the top level is not a JSON object",
+        };
+    }
+    const raw = parsed;
+    if (raw.capabilities !== undefined && !Array.isArray(raw.capabilities)) {
+        return {
+            status: "invalid",
+            manifest: null,
+            reason: '"capabilities" is not an array',
+        };
+    }
+    const capabilities = Array.isArray(raw.capabilities)
+        ? raw.capabilities.filter((item) => typeof item === "string")
+        : [];
+    return {
+        status: "ok",
+        manifest: {
+            ...raw,
+            version: typeof raw.version === "string" ? raw.version : "",
+            architecture: typeof raw.architecture === "string" ? raw.architecture : "monolith",
+            capabilities,
+            generatedAt: typeof raw.generatedAt === "string" ? raw.generatedAt : "",
+            updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : "",
+        },
+    };
+}
+/**
+ * Writes the manifest through a sibling temp file and `rename`.
+ *
+ * Writing in place truncated the real file first, so an interrupted or
+ * failing write left an empty or half-written manifest behind.
+ */
+export async function writeManifestFile(manifestPath, manifest) {
+    const tempPath = `${manifestPath}.${process.pid}.${Math.random()
+        .toString(36)
+        .slice(2)}.tmp`;
+    await writeFile(tempPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+    try {
+        await rename(tempPath, manifestPath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true });
+        throw error;
+    }
+}
+const queues = new Map();
+/**
+ * Serializes a read-modify-write of one manifest.
+ *
+ * Concurrent `zudojs add` runs lost each other's updates: each read the
+ * manifest, added its own capability and wrote the whole file back. The
+ * queue orders calls inside one process and the lock file orders them
+ * across processes.
+ */
+export async function withManifestLock(manifestPath, operation) {
+    const previous = queues.get(manifestPath) ?? Promise.resolve();
+    const run = previous.then(async () => {
+        const release = await acquireLock(`${manifestPath}.lock`);
+        try {
+            return await operation();
+        }
+        finally {
+            await release();
+        }
+    });
+    queues.set(manifestPath, run.then(() => undefined, () => undefined));
+    return run;
+}
+async function acquireLock(lockPath) {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    const noop = async () => { };
+    while (true) {
+        try {
+            const handle = await open(lockPath, "wx");
+            await handle.close();
+            return async () => {
+                await rm(lockPath, { force: true }).catch(() => undefined);
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                // The lock itself cannot be created (read-only or missing
+                // directory). The write is still attempted; failing here would be
+                // worse than an unserialized write.
+                return noop;
+            }
+            if (await isStale(lockPath)) {
+                await rm(lockPath, { force: true }).catch(() => undefined);
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                return noop;
+            }
+            await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS));
+        }
+    }
+}
+async function isStale(lockPath) {
+    try {
+        const stats = await stat(lockPath);
+        return Date.now() - stats.mtimeMs > LOCK_STALE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=manifestFile.helper.js.map

package/dist/src/manifest/manifestManager.core.d.ts

@@ -3,6 +3,7 @@
  *
  * Machine-managed project manifest for Zudojs projects.
  */
+import { type ManifestReadResult } from "./manifestFile.helper.js";
 export interface ZudojsManifest {
     readonly version: string;
     readonly projectType?: string;
@@ -30,10 +31,25 @@ export interface ZudojsManifest {
 export declare class ManifestManager {
     private readonly manifestPath;
     constructor(cwd: string);
+    /** Absolute path of the manifest this manager owns. */
+    get path(): string;
     create(manifest: Omit<ZudojsManifest, "generatedAt" | "updatedAt">): Promise<void>;
+    /**
+     * Reads the manifest, keeping "there is none" and "there is one but it is
+     * corrupt" apart. A blanket catch used to report both as missing.
+     */
+    readResult(): Promise<ManifestReadResult>;
     read(): Promise<ZudojsManifest | null>;
+    /**
+     * Applies `updates` to the manifest on disk.
+     *
+     * Throws when there is no usable manifest: returning silently made
+     * `zudojs add` report success while nothing had been recorded.
+     */
     update(updates: Partial<ZudojsManifest>): Promise<void>;
+    /** Adds `capability` to the manifest if it is not already recorded. */
     addCapability(capability: string): Promise<void>;
+    private require;
     private write;
 }
 //# sourceMappingURL=manifestManager.core.d.ts.map

package/dist/src/manifest/manifestManager.core.js

@@ -3,61 +3,91 @@
  *
  * Machine-managed project manifest for Zudojs projects.
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { CLIGenerationError } from "../errors/index.js";
+import { parseManifest, withManifestLock, writeManifestFile, } from "./manifestFile.helper.js";
 export class ManifestManager {
     manifestPath;
     constructor(cwd) {
         this.manifestPath = join(cwd, ".zudojs", "manifest.json");
     }
+    /** Absolute path of the manifest this manager owns. */
+    get path() {
+        return this.manifestPath;
+    }
     async create(manifest) {
         const now = new Date().toISOString();
-        const fullManifest = {
-            ...manifest,
-            generatedAt: now,
-            updatedAt: now,
-        };
-        await this.write(fullManifest);
+        await withManifestLock(this.manifestPath, async () => {
+            await this.write({ ...manifest, generatedAt: now, updatedAt: now });
+        });
     }
-    async read() {
+    /**
+     * Reads the manifest, keeping "there is none" and "there is one but it is
+     * corrupt" apart. A blanket catch used to report both as missing.
+     */
+    async readResult() {
         if (!existsSync(this.manifestPath)) {
-            return null;
+            return { status: "missing", manifest: null };
         }
+        let content;
         try {
-            const content = readFileSync(this.manifestPath, "utf-8");
-            return JSON.parse(content);
+            content = readFileSync(this.manifestPath, "utf-8");
         }
-        catch {
-            return null;
+        catch (error) {
+            return {
+                status: "invalid",
+                manifest: null,
+                reason: `could not be read (${error instanceof Error ? error.message : String(error)})`,
+            };
         }
+        return parseManifest(content);
+    }
+    async read() {
+        return (await this.readResult()).manifest;
     }
+    /**
+     * Applies `updates` to the manifest on disk.
+     *
+     * Throws when there is no usable manifest: returning silently made
+     * `zudojs add` report success while nothing had been recorded.
+     */
     async update(updates) {
-        const existing = await this.read();
-        if (!existing) {
-            return;
-        }
-        const updated = {
-            ...existing,
-            ...updates,
-            updatedAt: new Date().toISOString(),
-        };
-        await this.write(updated);
+        await withManifestLock(this.manifestPath, async () => {
+            const existing = this.require(await this.readResult());
+            await this.write({
+                ...existing,
+                ...updates,
+                updatedAt: new Date().toISOString(),
+            });
+        });
     }
+    /** Adds `capability` to the manifest if it is not already recorded. */
     async addCapability(capability) {
-        const existing = await this.read();
-        if (!existing) {
-            return;
+        await withManifestLock(this.manifestPath, async () => {
+            const existing = this.require(await this.readResult());
+            if (existing.capabilities.includes(capability)) {
+                return;
+            }
+            await this.write({
+                ...existing,
+                capabilities: [...existing.capabilities, capability],
+                updatedAt: new Date().toISOString(),
+            });
+        });
+    }
+    require(result) {
+        if (result.status === "ok" && result.manifest) {
+            return result.manifest;
         }
-        const capabilities = existing.capabilities.includes(capability)
-            ? existing.capabilities
-            : [...existing.capabilities, capability];
-        await this.update({ capabilities });
+        throw new CLIGenerationError(result.status === "missing"
+            ? `No project manifest at ${this.manifestPath}.`
+            : `The project manifest at ${this.manifestPath} is unusable: ${result.reason ?? "unknown reason"}.`);
     }
     async write(manifest) {
-        const dir = join(this.manifestPath, "..");
-        const { mkdir } = await import("node:fs/promises");
-        await mkdir(dir, { recursive: true });
-        writeFileSync(this.manifestPath, JSON.stringify(manifest, null, 2));
+        await mkdir(dirname(this.manifestPath), { recursive: true });
+        await writeManifestFile(this.manifestPath, manifest);
     }
 }
 //# sourceMappingURL=manifestManager.core.js.map

package/dist/src/prompts/backend/api-style.prompt.js

@@ -4,6 +4,7 @@
  * Prompts for API style selection.
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
 export async function promptApiStyle(overrides) {
     const value = overrides ??
         (await p.select({
@@ -27,10 +28,6 @@ export async function promptApiStyle(overrides) {
             ],
             initialValue: "rest",
         }));
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return value;
+    return cancelled(value);
 }
 //# sourceMappingURL=api-style.prompt.js.map

package/dist/src/prompts/backend/backend-architecture.prompt.js

@@ -4,32 +4,15 @@
  * Prompts for backend architecture selection.
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
+import { ARCHITECTURE_CHOICES, DEFAULT_ARCHITECTURE, } from "../../constants/index.js";
 export async function promptBackendArchitecture(overrides) {
     const value = overrides ??
         (await p.select({
             message: "Select backend architecture",
-            options: [
-                {
-                    value: "monolith",
-                    label: "Monolith",
-                    hint: "Single application",
-                },
-                {
-                    value: "modular-monolith",
-                    label: "Modular Monolith",
-                    hint: "Modular single application",
-                },
-                {
-                    value: "microservice",
-                    label: "Microservices",
-                    hint: "Independent services",
-                },
-            ],
+            options: ARCHITECTURE_CHOICES.map((choice) => ({ ...choice })),
+            initialValue: DEFAULT_ARCHITECTURE,
         }));
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return value;
+    return cancelled(value);
 }
 //# sourceMappingURL=backend-architecture.prompt.js.map

package/dist/src/prompts/backend/database.prompt.js

@@ -4,33 +4,15 @@
  * Prompts for database selection.
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
+import { DATABASE_CHOICES, DEFAULT_DATABASE } from "../../constants/index.js";
 export async function promptDatabase(overrides) {
     const value = overrides ??
         (await p.select({
             message: "Select database",
-            options: [
-                {
-                    value: "postgresql",
-                    label: "PostgreSQL",
-                    hint: "Recommended for production",
-                },
-                {
-                    value: "mysql",
-                    label: "MySQL",
-                    hint: "Widely used relational database",
-                },
-                {
-                    value: "sqlite",
-                    label: "SQLite",
-                    hint: "Lightweight, file-based",
-                },
-            ],
-            initialValue: "postgresql",
+            options: DATABASE_CHOICES.map((choice) => ({ ...choice })),
+            initialValue: DEFAULT_DATABASE,
         }));
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return value;
+    return cancelled(value);
 }
 //# sourceMappingURL=database.prompt.js.map

package/dist/src/prompts/backend/services.prompt.js

@@ -4,6 +4,7 @@
  * Prompts for microservice service names (comma-separated).
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
 const SERVICE_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
 function parseServices(value) {
     return value
@@ -16,13 +17,18 @@ export async function promptServices(overrides) {
         return [...overrides];
     }
     const value = await p.text({
-        message: "Service names (comma-separated)",
-        placeholder: "identity,billing,notification",
+        message: "Service names (comma-separated, leave blank for none)",
+        placeholder: "leave blank, or e.g. billing,search",
+        /**
+         * Blank is a valid answer and yields a gateway-only project.
+         *
+         * This used to demand at least one name, and an empty list elsewhere was
+         * substituted with four example services, so every project arrived with
+         * domains nobody had asked for. Services are created when they are named,
+         * here or later with `zudojs generate service <name>`.
+         */
         validate(input) {
             const services = parseServices(input ?? "");
-            if (services.length === 0) {
-                return "At least one service name is required.";
-            }
             for (const service of services) {
                 if (!SERVICE_NAME_PATTERN.test(service)) {
                     return `Invalid service name "${service}". Only alphanumeric characters, hyphens, and underscores are allowed.`;
@@ -30,10 +36,6 @@ export async function promptServices(overrides) {
             }
         },
     });
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return parseServices(value);
+    return parseServices(cancelled(value));
 }
 //# sourceMappingURL=services.prompt.js.map

package/dist/src/prompts/cancel.prompt.d.ts

@@ -0,0 +1,18 @@
+/**
+ * zudojs-cli — Prompt Cancellation
+ *
+ * The single place where an aborted prompt ends the process.
+ */
+/**
+ * Returns a prompt answer, or ends the process when the prompt was cancelled.
+ *
+ * Every prompt used to exit `0` on Ctrl-C, so `zudojs create my-api && cd
+ * my-api` ran the `cd` against a directory that was never created, and in CI
+ * an abort was indistinguishable from a success. The exit status is now 130,
+ * the conventional "terminated by SIGINT" value.
+ *
+ * @param value - The value a `@clack/prompts` call resolved with.
+ * @returns The answer, once it is known not to be the cancel symbol.
+ */
+export declare function cancelled<T>(value: T | symbol): T;
+//# sourceMappingURL=cancel.prompt.d.ts.map

package/dist/src/prompts/cancel.prompt.js

@@ -0,0 +1,26 @@
+/**
+ * zudojs-cli — Prompt Cancellation
+ *
+ * The single place where an aborted prompt ends the process.
+ */
+import * as p from "@clack/prompts";
+import { CLI_EXIT_CODES } from "../cliConstant/cliConstant.value.js";
+/**
+ * Returns a prompt answer, or ends the process when the prompt was cancelled.
+ *
+ * Every prompt used to exit `0` on Ctrl-C, so `zudojs create my-api && cd
+ * my-api` ran the `cd` against a directory that was never created, and in CI
+ * an abort was indistinguishable from a success. The exit status is now 130,
+ * the conventional "terminated by SIGINT" value.
+ *
+ * @param value - The value a `@clack/prompts` call resolved with.
+ * @returns The answer, once it is known not to be the cancel symbol.
+ */
+export function cancelled(value) {
+    if (p.isCancel(value)) {
+        p.cancel("Operation cancelled.");
+        process.exit(CLI_EXIT_CODES.INTERRUPTED);
+    }
+    return value;
+}
+//# sourceMappingURL=cancel.prompt.js.map

package/dist/src/prompts/capabilities/capabilities.prompt.js

@@ -4,6 +4,7 @@
  * Prompts for selecting Zudojs capabilities.
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
 const CAPABILITY_OPTIONS = [
     {
         value: "cqrs",
@@ -37,10 +38,6 @@ export async function promptCapabilities(selected = []) {
         required: false,
         initialValues: Array.from(selected),
     });
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return value;
+    return cancelled(value);
 }
 //# sourceMappingURL=capabilities.prompt.js.map

package/dist/src/prompts/frontend/framework.prompt.js

@@ -4,6 +4,7 @@
  * Prompts for frontend framework selection.
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
 const FRONTEND_OPTIONS = [
     { value: "react", label: "React", hint: "SPA with Vite" },
     { value: "next", label: "Next.js", hint: "Full React framework" },
@@ -33,10 +34,6 @@ export async function promptFramework(projectType, overrides) {
                 hint: opt.hint,
             })),
         }));
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return value;
+    return cancelled(value);
 }
 //# sourceMappingURL=framework.prompt.js.map

package/dist/src/prompts/frontend/frontend-architecture.prompt.js

@@ -4,6 +4,7 @@
  * Prompts for frontend project structure.
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
 export async function promptFrontendArchitecture(overrides) {
     const value = overrides ??
         (await p.select({
@@ -32,10 +33,6 @@ export async function promptFrontendArchitecture(overrides) {
             ],
             initialValue: "zudojs-standard",
         }));
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return value;
+    return cancelled(value);
 }
 //# sourceMappingURL=frontend-architecture.prompt.js.map

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

@@ -1,6 +1,7 @@
 /**
  * zudojs-cli — Prompts Index
  */
+export { cancelled } from "./cancel.prompt.js";
 export { promptProjectName } from "./project/project-name.prompt.js";
 export { promptProjectType } from "./project/project-type.prompt.js";
 export { promptConfirmation } from "./project/confirmation.prompt.js";

package/dist/src/prompts/index.js

@@ -1,6 +1,7 @@
 /**
  * zudojs-cli — Prompts Index
  */
+export { cancelled } from "./cancel.prompt.js";
 export { promptProjectName } from "./project/project-name.prompt.js";
 export { promptProjectType } from "./project/project-type.prompt.js";
 export { promptConfirmation } from "./project/confirmation.prompt.js";

package/dist/src/prompts/project/confirmation.prompt.js

@@ -4,15 +4,12 @@
  * Prompts for confirmation before generation.
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
 export async function promptConfirmation(message, initialValue = true) {
     const value = await p.confirm({
         message,
         initialValue,
     });
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return value;
+    return cancelled(value);
 }
 //# sourceMappingURL=confirmation.prompt.js.map

package/dist/src/prompts/project/project-name.prompt.js

@@ -4,6 +4,7 @@
  * Prompts for the project name.
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
 export async function promptProjectName(overrides) {
     const value = overrides ??
         (await p.text({
@@ -13,15 +14,13 @@ export async function promptProjectName(overrides) {
                 if (!value || value.trim().length === 0) {
                     return "Project name is required.";
                 }
-                if (!/^[a-zA-Z0-9_-]+$/.test(value)) {
-                    return "Only alphanumeric, hyphens, and underscores allowed.";
+                // A leading "-" made a directory that `cd -dash` cannot enter and
+                // `rm -rf -dash` cannot remove, so the first character is alphanumeric.
+                if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(value)) {
+                    return "Must start with a letter or digit; only alphanumeric characters, hyphens, and underscores are allowed.";
                 }
             },
         }));
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return value;
+    return cancelled(value);
 }
 //# sourceMappingURL=project-name.prompt.js.map

package/dist/src/prompts/project/project-type.prompt.js

@@ -4,6 +4,7 @@
  * Prompts for the project type.
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
 export async function promptProjectType(overrides) {
     const value = overrides ??
         (await p.select({
@@ -26,10 +27,6 @@ export async function promptProjectType(overrides) {
                 },
             ],
         }));
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return value;
+    return cancelled(value);
 }
 //# sourceMappingURL=project-type.prompt.js.map

package/dist/src/prompts/workspace/package-manager.prompt.js

@@ -4,22 +4,15 @@
  * Prompts for package manager selection.
  */
 import * as p from "@clack/prompts";
+import { cancelled } from "../cancel.prompt.js";
+import { DEFAULT_PACKAGE_MANAGER, PACKAGE_MANAGER_CHOICES, } from "../../constants/index.js";
 export async function promptPackageManager(overrides) {
     const value = overrides ??
         (await p.select({
             message: "Select package manager",
-            options: [
-                { value: "pnpm", label: "pnpm" },
-                { value: "npm", label: "npm" },
-                { value: "yarn", label: "Yarn" },
-                { value: "bun", label: "Bun" },
-            ],
-            initialValue: "pnpm",
+            options: PACKAGE_MANAGER_CHOICES.map((choice) => ({ ...choice })),
+            initialValue: DEFAULT_PACKAGE_MANAGER,
         }));
-    if (p.isCancel(value)) {
-        p.cancel("Operation cancelled.");
-        process.exit(0);
-    }
-    return value;
+    return cancelled(value);
 }
 //# sourceMappingURL=package-manager.prompt.js.map