@zenithbuild/cli 0.4.11 → 0.5.0-beta.2.15

package/dist/server-contract.js

@@ -0,0 +1,278 @@
+// server-contract.js — Zenith CLI V0
+// ---------------------------------------------------------------------------
+// Shared validation and payload resolution logic for <script server> blocks.
+
+const NEW_KEYS = new Set(['data', 'load', 'guard', 'prerender']);
+const LEGACY_KEYS = new Set(['ssr_data', 'props', 'ssr', 'prerender']);
+const ALLOWED_KEYS = new Set(['data', 'load', 'guard', 'prerender', 'ssr_data', 'props', 'ssr']);
+
+const ROUTE_RESULT_KINDS = new Set(['allow', 'redirect', 'deny', 'data']);
+
+export function allow() {
+    return { kind: 'allow' };
+}
+
+export function redirect(location, status = 302) {
+    return {
+        kind: 'redirect',
+        location: String(location || ''),
+        status: Number.isInteger(status) ? status : 302
+    };
+}
+
+export function deny(status = 403, message = undefined) {
+    return {
+        kind: 'deny',
+        status: Number.isInteger(status) ? status : 403,
+        message: typeof message === 'string' ? message : undefined
+    };
+}
+
+export function data(payload) {
+    return { kind: 'data', data: payload };
+}
+
+function isRouteResultLike(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const kind = value.kind;
+    return typeof kind === 'string' && ROUTE_RESULT_KINDS.has(kind);
+}
+
+function assertValidRouteResultShape(value, where, allowedKinds) {
+    if (!isRouteResultLike(value)) {
+        throw new Error(`[Zenith] ${where}: invalid route result. Expected object with kind.`);
+    }
+    const kind = value.kind;
+    if (!allowedKinds.has(kind)) {
+        throw new Error(
+            `[Zenith] ${where}: kind "${kind}" is not allowed here (allowed: ${Array.from(allowedKinds).join(', ')}).`
+        );
+    }
+
+    if (kind === 'redirect') {
+        if (typeof value.location !== 'string' || value.location.length === 0) {
+            throw new Error(`[Zenith] ${where}: redirect requires non-empty string location.`);
+        }
+        if (value.status !== undefined && (!Number.isInteger(value.status) || value.status < 300 || value.status > 399)) {
+            throw new Error(`[Zenith] ${where}: redirect status must be an integer 3xx.`);
+        }
+    }
+
+    if (kind === 'deny') {
+        if (!Number.isInteger(value.status) || (value.status !== 401 && value.status !== 403)) {
+            throw new Error(`[Zenith] ${where}: deny status must be 401 or 403.`);
+        }
+        if (value.message !== undefined && typeof value.message !== 'string') {
+            throw new Error(`[Zenith] ${where}: deny message must be a string when provided.`);
+        }
+    }
+}
+
+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 hasGuard = 'guard' 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.`);
+        }
+    }
+
+    if (hasGuard && typeof exports.guard !== 'function') {
+        throw new Error(`[Zenith] ${filePath}: "guard" must be a function.`);
+    }
+    if (hasGuard) {
+        if (exports.guard.length !== 1) {
+            throw new Error(`[Zenith] ${filePath}: "guard(ctx)" must take exactly 1 argument.`);
+        }
+        const fnStr = exports.guard.toString();
+        const paramsMatch = fnStr.match(/^[^{=]+\(([^)]*)\)/);
+        if (paramsMatch && paramsMatch[1].includes('...')) {
+            throw new Error(`[Zenith] ${filePath}: "guard(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 resolveRouteResult({ exports, ctx, filePath }) {
+    validateServerExports({ exports, filePath });
+
+    const trace = {
+        guard: 'none',
+        load: 'none'
+    };
+
+    if ('guard' in exports) {
+        const guardRaw = await exports.guard(ctx);
+        const guardResult = guardRaw == null ? allow() : guardRaw;
+        assertValidRouteResultShape(
+            guardResult,
+            `${filePath}: guard(ctx) return`,
+            new Set(['allow', 'redirect', 'deny'])
+        );
+        trace.guard = guardResult.kind;
+        if (guardResult.kind === 'redirect' || guardResult.kind === 'deny') {
+            return { result: guardResult, trace };
+        }
+    }
+
+    let payload;
+    if ('load' in exports) {
+        const loadRaw = await exports.load(ctx);
+        let loadResult = null;
+        if (isRouteResultLike(loadRaw)) {
+            loadResult = loadRaw;
+            assertValidRouteResultShape(
+                loadResult,
+                `${filePath}: load(ctx) return`,
+                new Set(['data', 'redirect', 'deny'])
+            );
+        } else {
+            assertJsonSerializable(loadRaw, `${filePath}: load(ctx) return`);
+            loadResult = data(loadRaw);
+        }
+        trace.load = loadResult.kind;
+        return { result: loadResult, trace };
+    }
+    if ('data' in exports) {
+        payload = exports.data;
+        assertJsonSerializable(payload, `${filePath}: data export`);
+        trace.load = 'data';
+        return { result: data(payload), trace };
+    }
+
+    // legacy fallback
+    if ('ssr_data' in exports) {
+        payload = exports.ssr_data;
+        assertJsonSerializable(payload, `${filePath}: ssr_data export`);
+        trace.load = 'data';
+        return { result: data(payload), trace };
+    }
+    if ('props' in exports) {
+        payload = exports.props;
+        assertJsonSerializable(payload, `${filePath}: props export`);
+        trace.load = 'data';
+        return { result: data(payload), trace };
+    }
+    if ('ssr' in exports) {
+        payload = exports.ssr;
+        assertJsonSerializable(payload, `${filePath}: ssr export`);
+        trace.load = 'data';
+        return { result: data(payload), trace };
+    }
+
+    return { result: data({}), trace };
+}
+
+export async function resolveServerPayload({ exports, ctx, filePath }) {
+    const resolved = await resolveRouteResult({ exports, ctx, filePath });
+    if (!resolved || !resolved.result || typeof resolved.result !== 'object') {
+        return {};
+    }
+
+    if (resolved.result.kind === 'data') {
+        return resolved.result.data;
+    }
+    if (resolved.result.kind === 'allow') {
+        return {};
+    }
+
+    throw new Error(
+        `[Zenith] ${filePath}: resolveServerPayload() expected data but received ${resolved.result.kind}. Use resolveRouteResult() for guard/load flows.`
+    );
+}

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 || ''));
+}