@zenithbuild/cli 0.7.4 → 0.7.7

package/dist/server-contract/resolve.js

@@ -0,0 +1,271 @@
+import { STAGED_SET_COOKIES_KEY } from './constants.js';
+import { validateServerExports } from './export-validation.js';
+import { assertJsonSerializable } from './json-serializable.js';
+import { assertValidRouteResultShape, isRouteResultLike } from './route-result-validation.js';
+import { allow, data, text } from './result-helpers.js';
+import { invokeRouteStage } from './stage.js';
+function buildActionState(result) {
+    if (!result || typeof result !== 'object') {
+        return null;
+    }
+    if (result.kind === 'data') {
+        return {
+            ok: true,
+            status: 200,
+            data: result.data
+        };
+    }
+    if (result.kind === 'invalid') {
+        return {
+            ok: false,
+            status: Number.isInteger(result.status) ? result.status : 400,
+            data: result.data
+        };
+    }
+    return null;
+}
+function buildResolvedEnvelope({ result, trace, status, ctx }) {
+    const envelope = { result, trace };
+    if (status !== undefined) {
+        envelope.status = status;
+    }
+    const setCookies = Array.isArray(ctx?.[STAGED_SET_COOKIES_KEY])
+        ? ctx[STAGED_SET_COOKIES_KEY].slice()
+        : [];
+    if (setCookies.length > 0) {
+        envelope.setCookies = setCookies;
+    }
+    return envelope;
+}
+export async function resolveRouteResult({ exports, ctx, filePath, guardOnly = false, routeKind = 'page' }) {
+    validateServerExports({ exports, filePath, routeKind });
+    if (routeKind === 'resource') {
+        return resolveResourceRouteResult({ exports, ctx, filePath, guardOnly });
+    }
+    const trace = {
+        guard: 'none',
+        action: 'none',
+        load: 'none'
+    };
+    let responseStatus = 200;
+    const requestMethod = String(ctx?.method || ctx?.request?.method || 'GET').toUpperCase();
+    const isActionRequest = !guardOnly && requestMethod === 'POST';
+    if (ctx && typeof ctx === 'object') {
+        ctx.action = null;
+    }
+    if ('guard' in exports) {
+        const guardRaw = await invokeRouteStage({
+            fn: exports.guard,
+            ctx,
+            where: `${filePath}: guard(ctx)`,
+            allowedKinds: new Set(['allow', 'redirect', 'deny'])
+        });
+        const guardResult = guardRaw == null ? allow() : guardRaw;
+        if (guardResult.kind === 'data') {
+            throw new Error(`[Zenith] ${filePath}: guard(ctx) returned data(payload) which is a critical invariant violation. guard() can only return allow(), redirect(), or deny(). Use load(ctx) for data injection.`);
+        }
+        assertValidRouteResultShape(guardResult, `${filePath}: guard(ctx) return`, new Set(['allow', 'redirect', 'deny']));
+        trace.guard = guardResult.kind;
+        if (guardResult.kind === 'redirect' || guardResult.kind === 'deny') {
+            return buildResolvedEnvelope({ result: guardResult, trace, ctx });
+        }
+    }
+    if (guardOnly) {
+        return buildResolvedEnvelope({ result: allow(), trace, ctx });
+    }
+    if (isActionRequest && 'action' in exports) {
+        const actionRaw = await invokeRouteStage({
+            fn: exports.action,
+            ctx,
+            where: `${filePath}: action(ctx)`,
+            allowedKinds: new Set(['data', 'invalid', 'redirect', 'deny'])
+        });
+        let actionResult = null;
+        if (isRouteResultLike(actionRaw)) {
+            actionResult = actionRaw;
+            assertValidRouteResultShape(actionResult, `${filePath}: action(ctx) return`, new Set(['data', 'invalid', 'redirect', 'deny']));
+            if (actionResult.kind === 'data' || actionResult.kind === 'invalid') {
+                assertJsonSerializable(actionResult.data, `${filePath}: action(ctx) return`);
+            }
+        }
+        else {
+            assertJsonSerializable(actionRaw, `${filePath}: action(ctx) return`);
+            actionResult = data(actionRaw);
+        }
+        trace.action = actionResult.kind;
+        if (actionResult.kind === 'redirect' || actionResult.kind === 'deny') {
+            return buildResolvedEnvelope({ result: actionResult, trace, ctx });
+        }
+        const actionState = buildActionState(actionResult);
+        if (ctx && typeof ctx === 'object') {
+            ctx.action = actionState;
+        }
+        if (actionState && actionState.ok === false) {
+            responseStatus = actionState.status;
+        }
+    }
+    let payload;
+    if ('load' in exports) {
+        const loadRaw = await invokeRouteStage({
+            fn: exports.load,
+            ctx,
+            where: `${filePath}: load(ctx)`,
+            allowedKinds: new Set(['data', 'redirect', 'deny'])
+        });
+        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 buildResolvedEnvelope({
+            result: loadResult,
+            trace,
+            status: loadResult.kind === 'data' ? responseStatus : undefined,
+            ctx
+        });
+    }
+    if ('data' in exports) {
+        payload = exports.data;
+        assertJsonSerializable(payload, `${filePath}: data export`);
+        trace.load = 'data';
+        return buildResolvedEnvelope({ result: data(payload), trace, status: responseStatus, ctx });
+    }
+    // legacy fallback
+    if ('ssr_data' in exports) {
+        payload = exports.ssr_data;
+        assertJsonSerializable(payload, `${filePath}: ssr_data export`);
+        trace.load = 'data';
+        return buildResolvedEnvelope({ result: data(payload), trace, status: responseStatus, ctx });
+    }
+    if ('props' in exports) {
+        payload = exports.props;
+        assertJsonSerializable(payload, `${filePath}: props export`);
+        trace.load = 'data';
+        return buildResolvedEnvelope({ result: data(payload), trace, status: responseStatus, ctx });
+    }
+    if ('ssr' in exports) {
+        payload = exports.ssr;
+        assertJsonSerializable(payload, `${filePath}: ssr export`);
+        trace.load = 'data';
+        return buildResolvedEnvelope({ result: data(payload), trace, status: responseStatus, ctx });
+    }
+    if (isActionRequest && ctx?.action) {
+        trace.load = 'data';
+        return buildResolvedEnvelope({
+            result: data({ action: ctx.action }),
+            trace,
+            status: responseStatus,
+            ctx
+        });
+    }
+    return buildResolvedEnvelope({ result: data({}), trace, status: responseStatus, ctx });
+}
+async function resolveResourceRouteResult({ exports, ctx, filePath, guardOnly = false }) {
+    const trace = {
+        guard: 'none',
+        action: 'none',
+        load: 'none'
+    };
+    const requestMethod = String(ctx?.method || ctx?.request?.method || 'GET').toUpperCase();
+    if (ctx && typeof ctx === 'object') {
+        ctx.action = null;
+    }
+    if ('guard' in exports) {
+        const guardRaw = await invokeRouteStage({
+            fn: exports.guard,
+            ctx,
+            where: `${filePath}: guard(ctx)`,
+            allowedKinds: new Set(['allow', 'redirect', 'deny'])
+        });
+        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 buildResolvedEnvelope({ result: guardResult, trace, ctx });
+        }
+    }
+    if (guardOnly) {
+        return buildResolvedEnvelope({ result: allow(), trace, ctx });
+    }
+    if (requestMethod === 'GET' || requestMethod === 'HEAD') {
+        if (!('load' in exports)) {
+            trace.load = 'text';
+            return buildResolvedEnvelope({ result: text('Method Not Allowed', 405), trace, status: 405, ctx });
+        }
+        const loadResult = await resolveResourceStage({
+            exports,
+            exportName: 'load',
+            ctx,
+            filePath,
+            trace,
+            traceKey: 'load'
+        });
+        return buildResolvedEnvelope({
+            result: loadResult,
+            trace,
+            status: loadResult.status,
+            ctx
+        });
+    }
+    if (requestMethod === 'POST') {
+        if (!('action' in exports)) {
+            trace.action = 'text';
+            return buildResolvedEnvelope({ result: text('Method Not Allowed', 405), trace, status: 405, ctx });
+        }
+        const actionResult = await resolveResourceStage({
+            exports,
+            exportName: 'action',
+            ctx,
+            filePath,
+            trace,
+            traceKey: 'action'
+        });
+        return buildResolvedEnvelope({
+            result: actionResult,
+            trace,
+            status: actionResult.status,
+            ctx
+        });
+    }
+    return buildResolvedEnvelope({
+        result: text('Method Not Allowed', 405),
+        trace,
+        status: 405,
+        ctx
+    });
+}
+async function resolveResourceStage({ exports, exportName, ctx, filePath, trace, traceKey }) {
+    const raw = await invokeRouteStage({
+        fn: exports[exportName],
+        ctx,
+        where: `${filePath}: ${exportName}(ctx)`,
+        allowedKinds: new Set(['json', 'text', 'download', 'redirect', 'deny', 'invalid', 'stream', 'sse'])
+    });
+    if (!isRouteResultLike(raw)) {
+        throw new Error(`[Zenith] ${filePath}: ${exportName}(ctx) on a resource route must return json(...), text(...), download(...), redirect(...), deny(...), invalid(...), stream(...), or sse(...).`);
+    }
+    assertValidRouteResultShape(raw, `${filePath}: ${exportName}(ctx) return`, new Set(['json', 'text', 'download', 'redirect', 'deny', 'invalid', 'stream', 'sse']));
+    if (raw.kind === 'json' || raw.kind === 'invalid') {
+        assertJsonSerializable(raw.data, `${filePath}: ${exportName}(ctx) return`);
+    }
+    trace[traceKey] = raw.kind;
+    return raw;
+}
+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/server-contract/result-helpers.d.ts

@@ -0,0 +1,51 @@
+export function allow(): {
+    kind: string;
+};
+export function redirect(location: any, status?: number): {
+    kind: string;
+    location: string;
+    status: number;
+};
+export function deny(status?: number, message?: undefined): {
+    kind: string;
+    status: number;
+    message: undefined;
+};
+export function data(payload: any): {
+    kind: string;
+    data: any;
+};
+export function invalid(payload: any, status?: number): {
+    kind: string;
+    data: any;
+    status: number;
+};
+export function json(payload: any, status?: number): {
+    kind: string;
+    data: any;
+    status: number;
+};
+export function text(body: any, status?: number): {
+    kind: string;
+    body: string;
+    status: number;
+};
+export function download(body: any, options?: {}): {
+    kind: string;
+    body: any;
+    bodyEncoding: string;
+    bodySize: number;
+    filename: string;
+    contentType: string;
+    status: number;
+};
+export function stream(body: any, options?: {}): {
+    kind: string;
+    body: any;
+    status: any;
+    contentType: any;
+};
+export function sse(events: any): {
+    kind: string;
+    events: any;
+};

package/dist/server-contract/result-helpers.js

@@ -0,0 +1,59 @@
+import { createDownloadResult } from '../download-result.js';
+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 };
+}
+export function invalid(payload, status = 400) {
+    return {
+        kind: 'invalid',
+        data: payload,
+        status: Number.isInteger(status) ? status : 400
+    };
+}
+export function json(payload, status = 200) {
+    return {
+        kind: 'json',
+        data: payload,
+        status: Number.isInteger(status) ? status : 200
+    };
+}
+export function text(body, status = 200) {
+    return {
+        kind: 'text',
+        body: typeof body === 'string' ? body : String(body ?? ''),
+        status: Number.isInteger(status) ? status : 200
+    };
+}
+export function download(body, options = {}) {
+    return createDownloadResult(body, options);
+}
+export function stream(body, options = {}) {
+    return {
+        kind: 'stream',
+        body,
+        status: options?.status,
+        contentType: options?.contentType
+    };
+}
+export function sse(events) {
+    return {
+        kind: 'sse',
+        events
+    };
+}

package/dist/server-contract/route-result-validation.d.ts

@@ -0,0 +1,2 @@
+export function isRouteResultLike(value: any): boolean;
+export function assertValidRouteResultShape(value: any, where: any, allowedKinds: any): void;

package/dist/server-contract/route-result-validation.js

@@ -0,0 +1,73 @@
+import { assertValidDownloadResult } from '../download-result.js';
+import { ROUTE_RESULT_KINDS } from './constants.js';
+export 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);
+}
+export 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 && value.status !== 404)) {
+            throw new Error(`[Zenith] ${where}: deny status must be 401, 403, or 404.`);
+        }
+        if (value.message !== undefined && typeof value.message !== 'string') {
+            throw new Error(`[Zenith] ${where}: deny message must be a string when provided.`);
+        }
+    }
+    if (kind === 'invalid') {
+        if (!Number.isInteger(value.status) || (value.status !== 400 && value.status !== 422)) {
+            throw new Error(`[Zenith] ${where}: invalid status must be 400 or 422.`);
+        }
+    }
+    if (kind === 'json' || kind === 'text') {
+        if (!Number.isInteger(value.status) || value.status < 200 || value.status > 599 || (value.status >= 300 && value.status <= 399)) {
+            throw new Error(`[Zenith] ${where}: ${kind} status must be an integer between 200-599 and may not be 3xx.`);
+        }
+        if (kind === 'text' && typeof value.body !== 'string') {
+            throw new Error(`[Zenith] ${where}: text body must be a string.`);
+        }
+    }
+    if (kind === 'download') {
+        assertValidDownloadResult(value, where);
+    }
+    if (kind === 'stream') {
+        if (!isReadableStream(value.body) && !isAsyncIterable(value.body)) {
+            throw new Error(`[Zenith] ${where}: stream body must be a ReadableStream or AsyncIterable.`);
+        }
+        if (value.status !== undefined && (!Number.isInteger(value.status) || value.status < 200 || value.status > 599 || (value.status >= 300 && value.status <= 399))) {
+            throw new Error(`[Zenith] ${where}: stream status must be an integer between 200-599 and may not be 3xx.`);
+        }
+        if (value.contentType !== undefined && typeof value.contentType !== 'string') {
+            throw new Error(`[Zenith] ${where}: stream contentType must be a string.`);
+        }
+    }
+    if (kind === 'sse') {
+        if (!isAsyncIterable(value.events)) {
+            throw new Error(`[Zenith] ${where}: sse events must be an AsyncIterable.`);
+        }
+    }
+}
+function isReadableStream(v) {
+    return v && typeof v === 'object' && typeof v.getReader === 'function' && typeof v.cancel === 'function';
+}
+function isAsyncIterable(v) {
+    return v && typeof v === 'object' && typeof v[Symbol.asyncIterator] === 'function';
+}

package/dist/server-contract/stage.d.ts

@@ -0,0 +1,6 @@
+export function invokeRouteStage({ fn, ctx, where, allowedKinds }: {
+    fn: any;
+    ctx: any;
+    where: any;
+    allowedKinds: any;
+}): Promise<any>;

package/dist/server-contract/stage.js

@@ -0,0 +1,22 @@
+import { AUTH_CONTROL_FLOW_FLAG } from './constants.js';
+import { assertValidRouteResultShape } from './route-result-validation.js';
+function unwrapAuthControlFlow(error, where, allowedKinds) {
+    if (!error || typeof error !== 'object' || error[AUTH_CONTROL_FLOW_FLAG] !== true) {
+        return null;
+    }
+    const result = error.result;
+    assertValidRouteResultShape(result, where, allowedKinds);
+    return result;
+}
+export async function invokeRouteStage({ fn, ctx, where, allowedKinds }) {
+    try {
+        return await fn(ctx);
+    }
+    catch (error) {
+        const authResult = unwrapAuthControlFlow(error, where, allowedKinds);
+        if (authResult) {
+            return authResult;
+        }
+        throw error;
+    }
+}

package/dist/server-contract.d.ts

@@ -1,54 +1,6 @@
-export function allow(): {
-    kind: string;
-};
-export function redirect(location: any, status?: number): {
-    kind: string;
-    location: string;
-    status: number;
-};
-export function deny(status?: number, message?: undefined): {
-    kind: string;
-    status: number;
-    message: undefined;
-};
-export function data(payload: any): {
-    kind: string;
-    data: any;
-};
-export function invalid(payload: any, status?: number): {
-    kind: string;
-    data: any;
-    status: number;
-};
-export function validateServerExports({ exports, filePath }: {
-    exports: any;
-    filePath: any;
-}): void;
-export function assertJsonSerializable(value: any, where?: string): void;
-export function resolveRouteResult({ exports, ctx, filePath, guardOnly }: {
-    exports: any;
-    ctx: any;
-    filePath: any;
-    guardOnly?: boolean | undefined;
-}): Promise<{
-    result: any;
-    trace: {
-        guard: string;
-        action: string;
-        load: string;
-    };
-    status?: undefined;
-} | {
-    result: any;
-    trace: {
-        guard: string;
-        action: string;
-        load: string;
-    };
-    status: number | undefined;
-}>;
-export function resolveServerPayload({ exports, ctx, filePath }: {
-    exports: any;
-    ctx: any;
-    filePath: any;
-}): Promise<any>;
+export { validateServerExports } from "./server-contract/export-validation.js";
+export { assertJsonSerializable } from "./server-contract/json-serializable.js";
+export { withMiddleware };
+import { withMiddleware } from './server-middleware.js';
+export { allow, redirect, deny, data, invalid, json, text, download, stream, sse } from "./server-contract/result-helpers.js";
+export { resolveRouteResult, resolveServerPayload } from "./server-contract/resolve.js";