zudojs-cli 2.0.0 → 2.1.0

package/dist/src/wiring/wiring.dependencies.js

@@ -0,0 +1,83 @@
+/**
+ * zudojs-cli — Dependencies of generated code
+ *
+ * `generate command` and `generate query` wrote files importing
+ * `@zudojs/cqrs` into projects created without the cqrs capability, so the
+ * project stopped compiling (TS2307) and nothing said why. After a schematic
+ * writes its files, every `@zudojs/*` package they import is added to the
+ * nearest package.json that lacks it.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { zudojsVersionRange } from "../constants/zudojsVersions.helper.js";
+const ZUDOJS_IMPORT = /\bfrom\s+["'](@zudojs\/[a-z0-9-]+)(?:\/[^"']*)?["']/g;
+/** `@zudojs/*` package names imported by `source`. */
+export function importedZudojsPackages(source) {
+    return [...new Set([...source.matchAll(ZUDOJS_IMPORT)].map((m) => m[1]))];
+}
+/** Nearest package.json at or above `fromDir`, never above `root`. */
+function nearestPackageJson(fromDir, root) {
+    let dir = fromDir;
+    for (;;) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate))
+            return candidate;
+        if (dir === root)
+            return undefined;
+        const parent = dirname(dir);
+        if (parent === dir || relative(root, parent).startsWith(".."))
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Adds every `@zudojs/*` package imported by `files` (paths relative to
+ * `root`, or absolute) to the dependencies of the package.json that owns
+ * each file, when it is missing. Existing entries are never changed.
+ */
+export function ensureZudojsDependencies(root, files) {
+    const projectRoot = resolve(root);
+    const needed = new Map();
+    for (const file of files) {
+        const path = isAbsolute(file) ? file : join(projectRoot, file);
+        if (!/\.[cm]?tsx?$/.test(path) || !existsSync(path))
+            continue;
+        const pkgPath = nearestPackageJson(dirname(path), projectRoot);
+        if (pkgPath === undefined)
+            continue;
+        const names = needed.get(pkgPath) ?? new Set();
+        for (const name of importedZudojsPackages(readFileSync(path, "utf8")))
+            names.add(name);
+        needed.set(pkgPath, names);
+    }
+    const edits = [];
+    for (const [pkgPath, names] of needed) {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        const missing = [...names]
+            .filter((name) => name !== pkg.name)
+            .filter((name) => !(name in (pkg.dependencies ?? {})) && !(name in (pkg.devDependencies ?? {})))
+            .sort();
+        if (missing.length === 0)
+            continue;
+        pkg.dependencies ??= {};
+        for (const name of missing)
+            pkg.dependencies[name] = zudojsVersionRange(name);
+        writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+        edits.push({ packageJson: relative(projectRoot, pkgPath), added: missing });
+    }
+    return edits;
+}
+/** Human-readable lines describing {@link ensureZudojsDependencies} edits. */
+export function describeAddedDependencies(edits) {
+    if (edits.length === 0)
+        return [];
+    return [
+        ...edits.map((edit) => `Added ${edit.added.join(", ")} to ${edit.packageJson}.`),
+        "Run your package manager's install command to fetch them.",
+    ];
+}
+/** "1 file" / "3 files". */
+export function fileCount(count) {
+    return `${count} ${count === 1 ? "file" : "files"}`;
+}
+//# sourceMappingURL=wiring.dependencies.js.map

package/dist/src/wiring/wiring.edits.d.ts

@@ -0,0 +1,51 @@
+/**
+ * zudojs-cli — Applying marker insertions to a project on disk.
+ *
+ * `generate` and `add` describe what they register as a list of
+ * {@link MarkerEdit}s. {@link applyMarkerEdits} applies them in order, file
+ * by file, and never guesses: a missing file or a file without its markers
+ * is reported as a manual step (exactly what to add, and where) instead of
+ * being rewritten.
+ */
+import { type MarkerName } from "./wiring.markers.js";
+/** One line to insert between a marker pair of a file. */
+export interface MarkerEdit {
+    /** File path relative to the project root. */
+    readonly file: string;
+    readonly marker: MarkerName;
+    readonly line: string;
+}
+/** What {@link applyMarkerEdits} did. */
+export interface MarkerEditOutcome {
+    /** Files that were (or, in a dry run, would be) changed. */
+    readonly edited: readonly string[];
+    /** Lines already present, so not inserted again. */
+    readonly alreadyPresent: readonly MarkerEdit[];
+    /** Instructions for edits that could not be made automatically. */
+    readonly manualSteps: readonly string[];
+}
+/**
+ * Computes the new contents of every file `edits` touch. Pure apart from
+ * reading the files; nothing is written.
+ */
+export declare function planMarkerEdits(cwd: string, edits: readonly MarkerEdit[]): {
+    readonly files: ReadonlyMap<string, string>;
+    readonly outcome: MarkerEditOutcome;
+};
+/**
+ * Applies `edits` to the project at `cwd` (unless `dryRun`) and reports
+ * what happened. Writes go through `writeFile`, so the overwrite check and
+ * the path-containment check see them.
+ */
+export declare function applyMarkerEdits(cwd: string, edits: readonly MarkerEdit[], dryRun?: boolean): Promise<MarkerEditOutcome>;
+/**
+ * The line of `file` that already imports the name `importLine` imports,
+ * from somewhere else; `undefined` when there is none (or it is this very
+ * line, which a re-run inserts idempotently).
+ *
+ * `generate module billing` and `generate route billing` both used to add
+ * an `import { registerBillingRoutes } …` to `src/routes/index.ts`, and the
+ * app stopped compiling on the duplicate identifier.
+ */
+export declare function conflictingImport(cwd: string, file: string, importLine: string): string | undefined;
+//# sourceMappingURL=wiring.edits.d.ts.map

package/dist/src/wiring/wiring.edits.js

@@ -0,0 +1,90 @@
+/**
+ * zudojs-cli — Applying marker insertions to a project on disk.
+ *
+ * `generate` and `add` describe what they register as a list of
+ * {@link MarkerEdit}s. {@link applyMarkerEdits} applies them in order, file
+ * by file, and never guesses: a missing file or a file without its markers
+ * is reported as a manual step (exactly what to add, and where) instead of
+ * being rewritten.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFile } from "../utils/utils.fileSystem.js";
+import { recordIntendedEdit } from "../utils/utils.writeGuard.js";
+import { insertBetweenMarkers, markerEnd, markerStart, } from "./wiring.markers.js";
+/**
+ * Computes the new contents of every file `edits` touch. Pure apart from
+ * reading the files; nothing is written.
+ */
+export function planMarkerEdits(cwd, edits) {
+    const contents = new Map();
+    const changed = new Set();
+    const alreadyPresent = [];
+    const manualSteps = [];
+    for (const edit of edits) {
+        const fullPath = join(cwd, edit.file);
+        let source = contents.get(edit.file);
+        if (source === undefined) {
+            if (!existsSync(fullPath)) {
+                manualSteps.push(`${edit.file} does not exist; add: ${edit.line}`);
+                continue;
+            }
+            source = readFileSync(fullPath, "utf-8");
+        }
+        const result = insertBetweenMarkers(source, edit.marker, edit.line);
+        if (result.status === "missing-markers") {
+            manualSteps.push(`${edit.file}: add "${edit.line}" between "${markerStart(edit.marker)}" and "${markerEnd(edit.marker)}" (the markers are missing, so the file was left unchanged)`);
+            continue;
+        }
+        if (result.status === "present") {
+            alreadyPresent.push(edit);
+        }
+        else {
+            changed.add(edit.file);
+        }
+        contents.set(edit.file, result.source);
+    }
+    const files = new Map();
+    for (const file of changed) {
+        files.set(file, contents.get(file) ?? "");
+    }
+    return {
+        files,
+        outcome: { edited: [...changed], alreadyPresent, manualSteps },
+    };
+}
+/**
+ * Applies `edits` to the project at `cwd` (unless `dryRun`) and reports
+ * what happened. Writes go through `writeFile`, so the overwrite check and
+ * the path-containment check see them.
+ */
+export async function applyMarkerEdits(cwd, edits, dryRun = false) {
+    const { files, outcome } = planMarkerEdits(cwd, edits);
+    if (dryRun)
+        return outcome;
+    for (const [file, content] of files) {
+        recordIntendedEdit(join(cwd, file));
+        await writeFile(cwd, file, content);
+    }
+    return outcome;
+}
+/**
+ * The line of `file` that already imports the name `importLine` imports,
+ * from somewhere else; `undefined` when there is none (or it is this very
+ * line, which a re-run inserts idempotently).
+ *
+ * `generate module billing` and `generate route billing` both used to add
+ * an `import { registerBillingRoutes } …` to `src/routes/index.ts`, and the
+ * app stopped compiling on the duplicate identifier.
+ */
+export function conflictingImport(cwd, file, importLine) {
+    const name = /^import \{ (\w+) \}/.exec(importLine)?.[1];
+    const path = join(cwd, file);
+    if (name === undefined || !existsSync(path))
+        return undefined;
+    const binds = new RegExp(`^import\\b.*[{,]\\s*${name}\\s*[,}]`);
+    return readFileSync(path, "utf-8")
+        .split("\n")
+        .find((line) => line.trim() !== importLine && binds.test(line.trim()));
+}
+//# sourceMappingURL=wiring.edits.js.map

package/dist/src/wiring/wiring.markers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * zudojs-cli — Marker comments in generated files.
+ *
+ * Generated projects keep every list the CLI appends to (route
+ * registrations, container entries, integrations, config sections) between
+ * a pair of comments such as `// zudojs:routes:start` and
+ * `// zudojs:routes:end`. `generate` and `add` only ever insert between
+ * those markers; a file without them is left untouched and the caller is
+ * told what to add by hand.
+ */
+/** Every marker pair the CLI writes into generated projects. */
+export declare const MARKERS: Readonly<{
+    readonly routeImports: "route-imports";
+    readonly routes: "routes";
+    readonly containerImports: "container-imports";
+    readonly container: "container";
+    readonly integrationImports: "integration-imports";
+    readonly integrations: "integrations";
+    readonly config: "config";
+    readonly serverImports: "server-imports";
+    readonly serverMounts: "server-mounts";
+    readonly serverMiddleware: "server-middleware";
+}>;
+/** A marker pair name. */
+export type MarkerName = (typeof MARKERS)[keyof typeof MARKERS];
+/** The opening comment of a marker pair. */
+export declare function markerStart(name: MarkerName): string;
+/** The closing comment of a marker pair. */
+export declare function markerEnd(name: MarkerName): string;
+/**
+ * Renders a marker block: the start comment, `lines`, the end comment, each
+ * indented by `indent`.
+ */
+export declare function renderMarkerBlock(name: MarkerName, lines: readonly string[], indent?: string): string;
+/** Outcome of {@link insertBetweenMarkers}. */
+export type MarkerInsertStatus = "inserted" | "present" | "missing-markers";
+/** Result of {@link insertBetweenMarkers}. */
+export interface MarkerInsertResult {
+    readonly status: MarkerInsertStatus;
+    /** The updated source; the original when nothing was inserted. */
+    readonly source: string;
+}
+/**
+ * Inserts `line` just before the end marker of `name`, indented like the
+ * marker. Idempotent: a line already present between the markers (compared
+ * trimmed) is not added again. Exactly one start and one end marker, in
+ * that order, are required; anything else is reported as missing markers
+ * rather than guessed at.
+ */
+export declare function insertBetweenMarkers(source: string, name: MarkerName, line: string): MarkerInsertResult;
+/** The lines currently between the markers of `name`, trimmed. */
+export declare function linesBetweenMarkers(source: string, name: MarkerName): readonly string[];
+//# sourceMappingURL=wiring.markers.d.ts.map

package/dist/src/wiring/wiring.markers.js

@@ -0,0 +1,87 @@
+/**
+ * zudojs-cli — Marker comments in generated files.
+ *
+ * Generated projects keep every list the CLI appends to (route
+ * registrations, container entries, integrations, config sections) between
+ * a pair of comments such as `// zudojs:routes:start` and
+ * `// zudojs:routes:end`. `generate` and `add` only ever insert between
+ * those markers; a file without them is left untouched and the caller is
+ * told what to add by hand.
+ */
+/** Every marker pair the CLI writes into generated projects. */
+export const MARKERS = Object.freeze({
+    routeImports: "route-imports",
+    routes: "routes",
+    containerImports: "container-imports",
+    container: "container",
+    integrationImports: "integration-imports",
+    integrations: "integrations",
+    config: "config",
+    serverImports: "server-imports",
+    serverMounts: "server-mounts",
+    serverMiddleware: "server-middleware",
+});
+/** The opening comment of a marker pair. */
+export function markerStart(name) {
+    return `// zudojs:${name}:start`;
+}
+/** The closing comment of a marker pair. */
+export function markerEnd(name) {
+    return `// zudojs:${name}:end`;
+}
+/**
+ * Renders a marker block: the start comment, `lines`, the end comment, each
+ * indented by `indent`.
+ */
+export function renderMarkerBlock(name, lines, indent = "") {
+    return [markerStart(name), ...lines, markerEnd(name)]
+        .map((line) => `${indent}${line}`)
+        .join("\n");
+}
+/**
+ * Inserts `line` just before the end marker of `name`, indented like the
+ * marker. Idempotent: a line already present between the markers (compared
+ * trimmed) is not added again. Exactly one start and one end marker, in
+ * that order, are required; anything else is reported as missing markers
+ * rather than guessed at.
+ */
+export function insertBetweenMarkers(source, name, line) {
+    const start = markerStart(name);
+    const end = markerEnd(name);
+    const startAt = source.indexOf(start);
+    const endAt = source.indexOf(end);
+    if (startAt === -1 ||
+        endAt === -1 ||
+        endAt < startAt ||
+        source.indexOf(start, startAt + 1) !== -1 ||
+        source.indexOf(end, endAt + 1) !== -1) {
+        return { status: "missing-markers", source };
+    }
+    const between = source.slice(startAt + start.length, endAt);
+    const wanted = line.trim();
+    if (between.split("\n").some((existing) => existing.trim() === wanted)) {
+        return { status: "present", source };
+    }
+    const lineStart = source.lastIndexOf("\n", endAt) + 1;
+    const indent = source.slice(lineStart, endAt);
+    const safeIndent = /^[ \t]*$/.test(indent) ? indent : "";
+    return {
+        status: "inserted",
+        source: source.slice(0, lineStart) +
+            `${safeIndent}${wanted}\n` +
+            source.slice(lineStart),
+    };
+}
+/** The lines currently between the markers of `name`, trimmed. */
+export function linesBetweenMarkers(source, name) {
+    const start = source.indexOf(markerStart(name));
+    const end = source.indexOf(markerEnd(name));
+    if (start === -1 || end === -1 || end < start)
+        return [];
+    return source
+        .slice(start + markerStart(name).length, end)
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+//# sourceMappingURL=wiring.markers.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudojs-cli",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Command-line interface for scaffolding, generating, and managing Zudojs framework projects.",
   "license": "MIT",
   "author": {
@@ -15,10 +15,14 @@
     ".": {
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
-    }
+    },
+    "./bin": "./dist/src/bin/zudojs.js",
+    "./package.json": "./package.json"
   },
   "bin": {
-    "zudojs": "./dist/src/bin/zudojs.js"
+    "zudojs": "./dist/src/bin/zudojs.js",
+    "zudo": "./dist/src/bin/zudojs.js",
+    "zudojs-cli": "./dist/src/bin/zudojs.js"
   },
   "files": [
     "dist",
@@ -27,18 +31,18 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.7.0",
-    "@zudojs/config": "1.2.0",
-    "@zudojs/core": "1.2.1",
-    "@zudojs/errors": "1.2.0",
-    "@zudojs/logger": "1.3.0"
+    "@clack/prompts": "^1.8.1",
+    "@zudojs/config": "1.3.0",
+    "@zudojs/core": "1.2.2",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/logger": "1.4.0"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
-    "@zudojs/constants": "1.1.1",
-    "tsx": "^4.23.12",
+    "@types/node": "^26.6.2",
+    "@zudojs/constants": "1.1.2",
+    "tsx": "^4.23.15",
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -53,7 +57,7 @@
     "generate",
     "dev"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-cli",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },
@@ -63,11 +67,12 @@
     "directory": "packages/cli"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node scripts/generateZudojsVersions.mjs && tsc -p tsconfig.json",
     "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"
+    "test:watch": "vitest",
+    "versions:check": "node scripts/generateZudojsVersions.mjs --check"
   }
 }