@zenithbuild/cli 0.4.10 → 0.5.0-beta.2.12

package/dist/server-contract.js

@@ -0,0 +1,146 @@
+// server-contract.js — Zenith CLI V0
+// ---------------------------------------------------------------------------
+// Shared validation and payload resolution logic for <script server> blocks.
+
+const NEW_KEYS = new Set(['data', 'load', 'prerender']);
+const LEGACY_KEYS = new Set(['ssr_data', 'props', 'ssr', 'prerender']);
+const ALLOWED_KEYS = new Set(['data', 'load', 'prerender', 'ssr_data', 'props', 'ssr']);
+
+export function validateServerExports({ exports, filePath }) {
+    const exportKeys = Object.keys(exports);
+    const illegalKeys = exportKeys.filter(k => !ALLOWED_KEYS.has(k));
+
+    if (illegalKeys.length > 0) {
+        throw new Error(`[Zenith] ${filePath}: illegal export(s): ${illegalKeys.join(', ')}`);
+    }
+
+    const hasData = 'data' in exports;
+    const hasLoad = 'load' in exports;
+
+    const hasNew = hasData || hasLoad;
+    const hasLegacy = ('ssr_data' in exports) || ('props' in exports) || ('ssr' in exports);
+
+    if (hasData && hasLoad) {
+        throw new Error(`[Zenith] ${filePath}: cannot export both "data" and "load". Choose one.`);
+    }
+
+    if (hasNew && hasLegacy) {
+        throw new Error(
+            `[Zenith] ${filePath}: cannot mix new ("data"/"load") with legacy ("ssr_data"/"props"/"ssr") exports.`
+        );
+    }
+
+    if ('prerender' in exports && typeof exports.prerender !== 'boolean') {
+        throw new Error(`[Zenith] ${filePath}: "prerender" must be a boolean.`);
+    }
+
+    if (hasLoad && typeof exports.load !== 'function') {
+        throw new Error(`[Zenith] ${filePath}: "load" must be a function.`);
+    }
+    if (hasLoad) {
+        if (exports.load.length !== 1) {
+            throw new Error(`[Zenith] ${filePath}: "load(ctx)" must take exactly 1 argument.`);
+        }
+        const fnStr = exports.load.toString();
+        const paramsMatch = fnStr.match(/^[^{=]+\(([^)]*)\)/);
+        if (paramsMatch && paramsMatch[1].includes('...')) {
+            throw new Error(`[Zenith] ${filePath}: "load(ctx)" must not contain rest parameters.`);
+        }
+    }
+}
+
+export function assertJsonSerializable(value, where = 'payload') {
+    const seen = new Set();
+
+    function walk(v, path) {
+        const t = typeof v;
+
+        if (v === null) return;
+        if (t === 'string' || t === 'number' || t === 'boolean') return;
+
+        if (t === 'bigint' || t === 'function' || t === 'symbol') {
+            throw new Error(`[Zenith] ${where}: non-serializable ${t} at ${path}`);
+        }
+
+        if (t === 'undefined') {
+            throw new Error(`[Zenith] ${where}: undefined is not allowed at ${path}`);
+        }
+
+        if (v instanceof Date) {
+            throw new Error(`[Zenith] ${where}: Date is not allowed at ${path} (convert to ISO string)`);
+        }
+
+        if (v instanceof Map || v instanceof Set) {
+            throw new Error(`[Zenith] ${where}: Map/Set not allowed at ${path}`);
+        }
+
+        if (t === 'object') {
+            if (seen.has(v)) throw new Error(`[Zenith] ${where}: circular reference at ${path}`);
+            seen.add(v);
+
+            if (Array.isArray(v)) {
+                if (path === '$') {
+                    throw new Error(`[Zenith] ${where}: top-level payload must be a plain object, not an array at ${path}`);
+                }
+                for (let i = 0; i < v.length; i++) walk(v[i], `${path}[${i}]`);
+                return;
+            }
+
+            const proto = Object.getPrototypeOf(v);
+            const isPlainObject = proto === null ||
+                proto === Object.prototype ||
+                (proto && proto.constructor && proto.constructor.name === 'Object');
+
+            if (!isPlainObject) {
+                throw new Error(`[Zenith] ${where}: non-plain object at ${path}`);
+            }
+
+            for (const k of Object.keys(v)) {
+                if (k === '__proto__' || k === 'constructor' || k === 'prototype') {
+                    throw new Error(`[Zenith] ${where}: forbidden prototype pollution key "${k}" at ${path}.${k}`);
+                }
+                walk(v[k], `${path}.${k}`);
+            }
+            return;
+        }
+
+        throw new Error(`[Zenith] ${where}: unsupported type at ${path}`);
+    }
+
+    walk(value, '$');
+}
+
+export async function resolveServerPayload({ exports, ctx, filePath }) {
+    validateServerExports({ exports, filePath });
+
+    let payload;
+    if ('load' in exports) {
+        payload = await exports.load(ctx);
+        assertJsonSerializable(payload, `${filePath}: load(ctx) return`);
+        return payload;
+    }
+    if ('data' in exports) {
+        payload = exports.data;
+        assertJsonSerializable(payload, `${filePath}: data export`);
+        return payload;
+    }
+
+    // legacy fallback
+    if ('ssr_data' in exports) {
+        payload = exports.ssr_data;
+        assertJsonSerializable(payload, `${filePath}: ssr_data export`);
+        return payload;
+    }
+    if ('props' in exports) {
+        payload = exports.props;
+        assertJsonSerializable(payload, `${filePath}: props export`);
+        return payload;
+    }
+    if ('ssr' in exports) {
+        payload = exports.ssr;
+        assertJsonSerializable(payload, `${filePath}: ssr export`);
+        return payload;
+    }
+
+    return {};
+}

package/dist/types/generate-env-dts.js

@@ -0,0 +1,52 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+
+export async function generateEnvDts(projectRoot) {
+    const content = `// .zenith/zenith-env.d.ts
+// Auto-generated by Zenith. Do not edit.
+
+export {};
+
+declare global {
+  namespace Zenith {
+    type Params = Record<string, string>;
+
+    interface LoadContext {
+      params: Params;
+      url: URL;
+      request: Request;
+      route: {
+        id: string;
+        file: string;
+        pattern: string;
+      };
+    }
+
+    interface ErrorState {
+      status?: number;
+      code?: string;
+      message: string;
+    }
+
+    type PageData = Record<string, unknown> & {
+      __zenith_error?: ErrorState;
+    };
+
+    type Load<T extends PageData = PageData> = (ctx: LoadContext) => Promise<T> | T;
+
+    type Renderable =
+      | string
+      | number
+      | boolean
+      | null
+      | undefined
+      | Renderable[]
+      | { __zenith_fragment: true };
+  }
+}
+`;
+
+    const outPath = join(projectRoot, '.zenith', 'zenith-env.d.ts');
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, content, 'utf8');
+}

package/dist/types/generate-routes-dts.js

@@ -0,0 +1,22 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+
+export async function generateRoutesDts(projectRoot, manifest) {
+    const routes = (manifest || []).map(r => r.path).filter(Boolean);
+    const typeDef = routes.length > 0
+        ? routes.map(r => '"' + r + '"').join(' | ')
+        : 'string';
+
+    const content = '// .zenith/zenith-routes.d.ts\\n' +
+        '// Auto-generated by Zenith. Do not edit.\\n\\n' +
+        'export {};\\n\\n' +
+        'declare global {\\n' +
+        '  namespace Zenith {\\n' +
+        '    type RoutePattern = ' + typeDef + ';\\n' +
+        '  }\\n' +
+        '}\\n';
+
+    const outPath = join(projectRoot, '.zenith', 'zenith-routes.d.ts');
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, content, 'utf8');
+}

package/dist/types/index.js

@@ -0,0 +1,34 @@
+import { generateEnvDts } from './generate-env-dts.js';
+import { generateRoutesDts } from './generate-routes-dts.js';
+import { join } from 'node:path';
+import { access, constants } from 'node:fs/promises';
+
+export async function ensureZenithTypes(projectRoot, manifest) {
+    try {
+        await generateEnvDts(projectRoot);
+        if (manifest) {
+            await generateRoutesDts(projectRoot, manifest);
+        }
+
+        // Check if tsconfig.json exists, if it does, check if .zenith is included
+        const tsconfigPath = join(projectRoot, 'tsconfig.json');
+        let hasTsConfig = false;
+        try {
+            await access(tsconfigPath, constants.F_OK);
+            hasTsConfig = true;
+        } catch {
+            hasTsConfig = false;
+        }
+
+        if (hasTsConfig) {
+            // In a real implementation this would parse the JSON and check "include".
+            // For now, we simply inform the user to include it if they haven't.
+            if (!globalThis.__zenithTypesWarned) {
+                console.warn('\\x1b[33m[zenith]\\x1b[0m For the best TypeScript experience, ensure ".zenith/**/*.d.ts" is in your tsconfig.json "include" array.');
+                globalThis.__zenithTypesWarned = true;
+            }
+        }
+    } catch (err) {
+        console.error('[zenith] Failed to generate type definitions:', err);
+    }
+}

package/dist/ui/env.js

@@ -0,0 +1,41 @@
+/**
+ * UI environment mode detection for deterministic CLI output.
+ */
+
+function flagEnabled(value) {
+    if (value === undefined || value === null) {
+        return false;
+    }
+    const normalized = String(value).trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+}
+
+/**
+ * @param {{ env?: Record<string, string | undefined>, stdout?: { isTTY?: boolean } }} runtime
+ */
+export function getUiMode(runtime = process) {
+    const env = runtime.env || {};
+    const tty = Boolean(runtime.stdout?.isTTY);
+    const ci = flagEnabled(env.CI);
+    const noUi = flagEnabled(env.ZENITH_NO_UI);
+    const noColor = env.NO_COLOR !== undefined && String(env.NO_COLOR).length >= 0;
+    const forceColor = flagEnabled(env.FORCE_COLOR);
+    const debug = flagEnabled(env.ZENITH_DEBUG);
+
+    const plain = noUi || ci || !tty;
+    const color = !plain && !noColor && (forceColor || tty);
+    const spinner = tty && !plain && !ci;
+
+    return {
+        plain,
+        color,
+        tty,
+        ci,
+        spinner,
+        debug
+    };
+}
+
+export function isUiPlain(runtime = process) {
+    return getUiMode(runtime).plain;
+}

package/dist/ui/format.js

@@ -0,0 +1,172 @@
+/**
+ * Deterministic text formatters for CLI UX.
+ */
+
+import { relative, sep } from 'node:path';
+
+const ANSI = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    green: '\x1b[32m',
+    cyan: '\x1b[36m'
+};
+const DEFAULT_PHASE = 'cli';
+const DEFAULT_FILE = '.';
+const DEFAULT_HINT_BASE = 'https://github.com/zenithbuild/zenith/blob/main/zenith-cli/CLI_CONTRACT.md';
+
+function colorize(mode, token, text) {
+    if (!mode.color) {
+        return text;
+    }
+    return `${ANSI[token]}${text}${ANSI.reset}`;
+}
+
+export function formatHeading(mode, text) {
+    const label = mode.plain ? 'ZENITH CLI' : colorize(mode, 'bold', 'Zenith CLI');
+    return `${label} ${text}`.trim();
+}
+
+export function formatStep(mode, text) {
+    if (mode.plain) {
+        return `[zenith] INFO: ${text}`;
+    }
+    const bullet = colorize(mode, 'cyan', '•');
+    return `[zenith] ${bullet} ${text}`;
+}
+
+export function formatSummaryTable(mode, rows) {
+    if (!Array.isArray(rows) || rows.length === 0) {
+        return '';
+    }
+    const maxLabel = rows.reduce((acc, row) => Math.max(acc, String(row.label || '').length), 0);
+    return rows
+        .map((row) => {
+            const label = String(row.label || '').padEnd(maxLabel, ' ');
+            const value = String(row.value || '');
+            return `[zenith] ${label} : ${value}`;
+        })
+        .join('\n');
+}
+
+export function sanitizeErrorMessage(input) {
+    return String(input ?? '')
+        .replace(/\r/g, '')
+        .trim();
+}
+
+function normalizeFileLinePath(line) {
+    const match = line.match(/^(\s*File:\s+)(.+)$/);
+    if (!match) {
+        return line;
+    }
+
+    const prefix = match[1];
+    const filePath = match[2].trim();
+    const normalized = normalizePathForDisplay(filePath);
+    return `${prefix}${normalized}`;
+}
+
+function normalizePathForDisplay(filePath) {
+    const value = String(filePath || '').trim();
+    if (!value) {
+        return DEFAULT_FILE;
+    }
+    if (!value.startsWith('/') && !/^[A-Za-z]:\\/.test(value)) {
+        return value;
+    }
+
+    const cwd = process.cwd();
+    const cwdWithSep = cwd.endsWith(sep) ? cwd : `${cwd}${sep}`;
+    if (value === cwd) {
+        return DEFAULT_FILE;
+    }
+    if (value.startsWith(cwdWithSep)) {
+        const relativePath = relative(cwd, value).replaceAll('\\', '/');
+        return relativePath || DEFAULT_FILE;
+    }
+
+    return value;
+}
+
+function inferPhaseFromArgv() {
+    const knownPhases = new Set(['build', 'dev', 'preview']);
+    for (const arg of process.argv.slice(2)) {
+        if (knownPhases.has(arg)) {
+            return arg;
+        }
+    }
+    return DEFAULT_PHASE;
+}
+
+function extractFileFromMessage(message) {
+    const match = String(message || '').match(/\bFile:\s+([^\n]+)/);
+    return match ? match[1].trim() : '';
+}
+
+function formatHintUrl(code) {
+    const slug = String(code || 'CLI_ERROR')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return `${DEFAULT_HINT_BASE}#${slug || 'cli-error'}`;
+}
+
+export function normalizeErrorMessagePaths(message) {
+    return String(message || '')
+        .split('\n')
+        .map((line) => normalizeFileLinePath(line))
+        .join('\n');
+}
+
+/**
+ * @param {unknown} err
+ */
+export function normalizeError(err) {
+    if (err instanceof Error) {
+        return err;
+    }
+    return new Error(sanitizeErrorMessage(err));
+}
+
+/**
+ * @param {unknown} err
+ * @param {{ plain: boolean, color: boolean, debug: boolean }} mode
+ */
+export function formatErrorBlock(err, mode) {
+    const normalized = normalizeError(err);
+    const maybe = /** @type {{ code?: unknown, phase?: unknown, kind?: unknown, file?: unknown, hint?: unknown }} */ (normalized);
+    const kind = sanitizeErrorMessage(maybe.kind || maybe.code || 'CLI_ERROR');
+    const phase = maybe.phase ? sanitizeErrorMessage(maybe.phase) : inferPhaseFromArgv();
+    const code = maybe.code
+        ? sanitizeErrorMessage(maybe.code)
+        : `${phase.toUpperCase().replace(/[^A-Z0-9]+/g, '_') || 'CLI'}_FAILED`;
+    const rawMessage = sanitizeErrorMessage(normalized.message || String(normalized));
+    const message = normalizeErrorMessagePaths(rawMessage);
+    const file = normalizePathForDisplay(
+        sanitizeErrorMessage(maybe.file || extractFileFromMessage(message) || DEFAULT_FILE)
+    );
+    const hint = sanitizeErrorMessage(maybe.hint || formatHintUrl(code));
+
+    const lines = [];
+    lines.push('[zenith] ERROR: Command failed');
+    lines.push(`[zenith] Error Kind: ${kind}`);
+    lines.push(`[zenith] Phase: ${phase || DEFAULT_PHASE}`);
+    lines.push(`[zenith] Code: ${code || 'CLI_FAILED'}`);
+    lines.push(`[zenith] File: ${file || DEFAULT_FILE}`);
+    lines.push(`[zenith] Hint: ${hint || formatHintUrl(code)}`);
+    lines.push(`[zenith] Message: ${message}`);
+
+    if (mode.debug && normalized.stack) {
+        lines.push('[zenith] Stack:');
+        lines.push(...String(normalized.stack).split('\n').slice(0, 20));
+    }
+
+    return lines.join('\n');
+}
+
+export function containsAnsi(value) {
+    return /\x1b\[[0-9;]*m/.test(String(value || ''));
+}

package/dist/ui/logger.js

@@ -0,0 +1,105 @@
+import { formatErrorBlock, formatHeading, formatStep, formatSummaryTable } from './format.js';
+import { getUiMode } from './env.js';
+
+const SPINNER_FRAMES = ['-', '\\', '|', '/'];
+
+function write(out, text) {
+    out.write(`${text}\n`);
+}
+
+function createSpinner(mode, stderr) {
+    if (!mode.spinner) {
+        return {
+            start() { },
+            update() { },
+            stop() { },
+            succeed() { },
+            fail() { }
+        };
+    }
+
+    let interval = null;
+    let frame = 0;
+    let message = '';
+
+    const paint = () => {
+        const current = SPINNER_FRAMES[frame % SPINNER_FRAMES.length];
+        stderr.write(`\r[zenith] ${current} ${message}`);
+        frame += 1;
+    };
+
+    const clear = () => {
+        stderr.write('\r');
+        stderr.write(' '.repeat(message.length + 12));
+        stderr.write('\r');
+    };
+
+    return {
+        start(nextMessage) {
+            message = String(nextMessage || '');
+            clearInterval(interval);
+            frame = 0;
+            paint();
+            interval = setInterval(paint, 80);
+        },
+        update(nextMessage) {
+            message = String(nextMessage || '');
+        },
+        stop() {
+            clearInterval(interval);
+            interval = null;
+            clear();
+        },
+        succeed(nextMessage) {
+            this.stop();
+            write(stderr, `[zenith] OK: ${nextMessage}`);
+        },
+        fail(nextMessage) {
+            this.stop();
+            write(stderr, `[zenith] ERROR: ${nextMessage}`);
+        }
+    };
+}
+
+/**
+ * @param {NodeJS.Process} runtime
+ */
+export function createLogger(runtime = process) {
+    const mode = getUiMode(runtime);
+    const stdout = runtime.stdout;
+    const stderr = runtime.stderr;
+    const spinner = createSpinner(mode, stderr);
+
+    return {
+        mode,
+        spinner,
+        heading(text) {
+            write(stdout, formatHeading(mode, text));
+        },
+        info(text) {
+            if (mode.plain) {
+                write(stdout, `[zenith] INFO: ${text}`);
+                return;
+            }
+            write(stdout, formatStep(mode, text));
+        },
+        success(text) {
+            write(stdout, `[zenith] OK: ${text}`);
+        },
+        warn(text) {
+            write(stderr, `[zenith] WARN: ${text}`);
+        },
+        error(err) {
+            write(stderr, formatErrorBlock(err, mode));
+        },
+        summary(rows) {
+            const table = formatSummaryTable(mode, rows);
+            if (table) {
+                write(stdout, table);
+            }
+        },
+        print(text) {
+            write(stdout, String(text));
+        }
+    };
+}

package/package.json

@@ -1,63 +1,35 @@
 {
   "name": "@zenithbuild/cli",
-  "version": "0.4.10",
-  "description": "CLI for Zenith framework - dev server, build tools, and plugin management",
+  "version": "0.5.0-beta.2.12",
+  "description": "Deterministic project orchestrator for Zenith framework",
+  "license": "MIT",
   "type": "module",
-  "bin": {
-    "zenith": "./dist/zenith.js",
-    "zen-dev": "./dist/zen-dev.js",
-    "zen-build": "./dist/zen-build.js",
-    "zen-preview": "./dist/zen-preview.js"
-  },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
   "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
-    }
+    ".": "./dist/index.js"
   },
   "files": [
-    "bin",
-    "src"
-  ],
-  "scripts": {
-    "dev": "bun run build && bin/zenith.ts dev",
-    "build": "bun build bin/zenith.ts bin/zen-dev.ts bin/zen-build.ts bin/zen-preview.ts --outdir dist --target bun --bundle && for f in dist/*.js; do echo '#!/usr/bin/env bun' | cat - \"$f\" > \"$f.tmp\" && mv \"$f.tmp\" \"$f\" && chmod +x \"$f\"; done",
-    "start": "bun run build && bun run dev",
-    "test": "bun test",
-    "release": "bun run scripts/release.ts",
-    "release:dry": "bun run scripts/release.ts --dry-run",
-    "release:patch": "bun run scripts/release.ts --bump=patch",
-    "release:minor": "bun run scripts/release.ts --bump=minor",
-    "release:major": "bun run scripts/release.ts --bump=major"
-  },
-  "keywords": [
-    "zenith",
-    "cli",
-    "framework",
-    "ssg",
-    "ssr"
+    "dist",
+    "README.md",
+    "LICENSE",
+    "dist/**",
+    "package.json"
   ],
-  "author": "Zenith Team",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git@github.com:zenithbuild/zenith-cli.git"
-  },
   "publishConfig": {
     "access": "public"
   },
-  "private": false,
-  "peerDependencies": {
-    "@zenithbuild/core": "^1.2.14"
+  "scripts": {
+    "build": "mkdir -p dist && cp -a src/* dist/",
+    "test": "node --experimental-vm-modules $(node -e \"const path=require('node:path');const pkg=require.resolve('jest/package.json');process.stdout.write(path.join(path.dirname(pkg),'bin/jest.js'))\") --config jest.config.js --forceExit --runInBand",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@zenithbuild/compiler": "0.5.0-beta.2.12"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@jest/globals": "^30.2.0",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0"
   },
-  "dependencies": {
-    "@zenithbuild/compiler": "^1.0.15",
-    "@zenithbuild/router": "^1.0.7",
-    "picocolors": "^1.0.0"
-  }
-}
+  "private": false
+}

package/bin/zen-build.ts

@@ -1,2 +0,0 @@
-import { runCLI } from '../src/main'
-runCLI({ defaultCommand: 'build' })

package/bin/zen-dev.ts

@@ -1,2 +0,0 @@
-import { runCLI } from '../src/main'
-runCLI({ defaultCommand: 'dev' })

package/bin/zen-preview.ts

@@ -1,2 +0,0 @@
-import { runCLI } from '../src/main'
-runCLI({ defaultCommand: 'preview' })

package/bin/zenith.ts

@@ -1,2 +0,0 @@
-import { runCLI } from '../src/main'
-runCLI()