@gradial/aci 0.1.0

package/dist/testing/index.js

@@ -0,0 +1,86 @@
+import { loadRenderInput, routeMetadataForContent, } from '../content/provider.js';
+import { normalizeRoute } from '../content/routes.js';
+export class FixtureContentProvider {
+    siteConfig;
+    pages;
+    constructor(options = {}) {
+        this.siteConfig = cloneFixture(options.siteConfig ?? defaultFixtureSiteConfig());
+        this.pages = new Map();
+        const inputPages = options.pages ?? {
+            '/': defaultFixturePage(),
+        };
+        for (const [route, page] of Object.entries(inputPages)) {
+            if (page) {
+                this.pages.set(normalizeRoute(route), cloneFixture(page));
+            }
+        }
+    }
+    async loadSiteConfig() {
+        return cloneFixture(this.siteConfig);
+    }
+    async loadPage(route = '/') {
+        const page = this.pages.get(normalizeRoute(route));
+        return page ? cloneFixture(page) : null;
+    }
+    async listRoutes() {
+        return [...this.pages.keys()].sort((left, right) => left.localeCompare(right));
+    }
+    async listPublishedRoutes() {
+        const routes = await this.listRoutes();
+        const published = [];
+        for (const route of routes) {
+            const page = await this.loadPage(route);
+            if (page?.status === 'published') {
+                published.push(route);
+            }
+        }
+        return published;
+    }
+    async resolveRouteMetadata(route = '/') {
+        const [siteConfig, page] = await Promise.all([
+            this.loadSiteConfig(),
+            this.loadPage(route),
+        ]);
+        return routeMetadataForContent(siteConfig, page);
+    }
+    async loadRenderInput(route = '/', options = {}) {
+        return loadRenderInput(this, route, options);
+    }
+}
+export function createFixtureContentProvider(options = {}) {
+    return new FixtureContentProvider(options);
+}
+export function defaultFixtureSiteConfig() {
+    return {
+        id: 'site_fixture',
+        $type: 'site',
+        status: 'published',
+        title: 'Fixture Site',
+        domain: 'www.baremetal.local',
+        defaultLocale: 'en-us',
+        seo: {
+            title: 'Fixture Site',
+            description: 'Fixture content for SDK tests.',
+            siteName: 'Fixture Site',
+        },
+    };
+}
+export function defaultFixturePage() {
+    return {
+        id: 'home',
+        $type: 'page',
+        status: 'published',
+        layout: 'marketing',
+        renderMode: 'static',
+        metadata: {
+            title: 'Fixture Home',
+            description: 'Fixture home page.',
+        },
+        regions: {
+            main: [],
+        },
+    };
+}
+function cloneFixture(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/types/component.d.ts

@@ -0,0 +1,26 @@
+import type { IslandMode, VaryDimension } from './render-mode.js';
+export interface ComponentRenderModes {
+    canStatic: boolean;
+    canSSR: boolean;
+    canClientIsland: boolean;
+}
+export interface ComponentDefinition<TSchema = unknown> {
+    name: string;
+    component?: unknown;
+    schema: TSchema;
+    renderModes?: ComponentRenderModes;
+    render?: ComponentRenderModes;
+    defaultIslandMode?: IslandMode;
+    varyDimensions?: VaryDimension[];
+    vary?: VaryDimension[];
+}
+export interface ComponentContract<TSchema = unknown> {
+    name: string;
+    component?: unknown;
+    schema: TSchema;
+    renderModes: ComponentRenderModes;
+    render: ComponentRenderModes;
+    defaultIslandMode?: IslandMode;
+    varyDimensions?: VaryDimension[];
+    vary?: VaryDimension[];
+}

package/dist/types/component.js

@@ -0,0 +1 @@
+export {};

package/dist/types/config.d.ts

@@ -0,0 +1,28 @@
+import type { RenderCapabilities } from './renderer.js';
+export interface BareMetalConfig {
+    version: '1';
+    siteId: string;
+    framework: 'astro' | 'next' | 'sveltekit' | 'custom';
+    source: {
+        root: string;
+        outDir?: string;
+    };
+    componentRegistry: string;
+    layoutRegistry: string;
+    rendererEntry: string;
+    capabilities: RenderCapabilities;
+    routes: RouteConfig;
+    externalDependencies?: ExternalDependency[];
+    rendererProtocol: 'http' | 'stdio-json';
+}
+export interface RouteConfig {
+    cmsManaged: string;
+    frameworkOwned?: string[];
+}
+export interface ExternalDependency {
+    name: string;
+    host: string;
+    kind?: 'api' | 'client-script';
+    description?: string;
+    cacheTTL?: number;
+}

package/dist/types/config.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from './config.js';
+export * from './component.js';
+export * from './layout.js';
+export * from './page.js';
+export * from './renderer.js';
+export * from './render-mode.js';

package/dist/types/index.js

@@ -0,0 +1,6 @@
+export * from './config.js';
+export * from './component.js';
+export * from './layout.js';
+export * from './page.js';
+export * from './renderer.js';
+export * from './render-mode.js';

package/dist/types/layout.d.ts

@@ -0,0 +1,12 @@
+export interface LayoutSlot {
+    name: string;
+    required: boolean;
+}
+export interface LayoutDefinition {
+    name: string;
+    slots: LayoutSlot[];
+}
+export interface LayoutContract {
+    name: string;
+    slots: LayoutSlot[];
+}

package/dist/types/layout.js

@@ -0,0 +1 @@
+export {};

package/dist/types/page.d.ts

@@ -0,0 +1,45 @@
+import type { RenderMode, VaryDimension } from './render-mode.js';
+export interface PageDocument {
+    path: string;
+    layout: string;
+    locale: string;
+    metadata: PageMetadata;
+    regions: Record<string, RegionNode>;
+    renderMode: RenderMode;
+}
+export interface PageMetadata {
+    title: string;
+    description?: string;
+    openGraph?: Record<string, string>;
+    canonicalUrl?: string;
+    alternateLocales?: {
+        locale: string;
+        path: string;
+    }[];
+    customHead?: string[];
+}
+export interface RegionNode {
+    kind: 'region';
+    name: string;
+    children: Array<BlockNode | FragmentRefNode>;
+}
+export interface BlockNode {
+    kind: 'block';
+    id: string;
+    component: string;
+    props: Record<string, unknown>;
+    renderHints: BlockRenderHints;
+    contentRef?: string;
+}
+export interface BlockRenderHints {
+    canStatic: boolean;
+    needsSSR: boolean;
+    isIsland: boolean;
+    islandMode?: 'ssr' | 'client';
+    varyDimensions?: VaryDimension[];
+}
+export interface FragmentRefNode {
+    kind: 'fragment-ref';
+    fragmentId: string;
+    inline: boolean;
+}

package/dist/types/page.js

@@ -0,0 +1 @@
+export {};

package/dist/types/render-mode.d.ts

@@ -0,0 +1,3 @@
+export type RenderMode = 'static' | 'static-with-fragments' | 'prerender-on-demand' | 'ssr-page' | 'ssr-island' | 'client-island';
+export type IslandMode = 'ssr' | 'client';
+export type VaryDimension = 'geo:country' | 'geo:region' | 'geo:city' | `cookie:${string}` | `header:${string}` | 'locale' | `query:${string}`;

package/dist/types/render-mode.js

@@ -0,0 +1 @@
+export {};

package/dist/types/renderer.d.ts

@@ -0,0 +1,71 @@
+import type { PageDocument } from './page.js';
+import type { VaryDimension } from './render-mode.js';
+export interface RenderCapabilities {
+    staticRender: boolean;
+    ssr: boolean;
+    ssrIslands: boolean;
+    clientIslands: boolean;
+    fragmentRender: boolean;
+}
+export interface GradialRenderer {
+    renderPage(request: RenderPageRequest): Promise<RenderPageResult>;
+    renderFragment?(request: RenderFragmentRequest): Promise<RenderResult>;
+    renderIsland?(request: RenderIslandRequest): Promise<RenderResult>;
+}
+export interface RenderPageRequest {
+    page: PageDocument;
+    requestContext?: RequestContext;
+    release: ReleaseContext;
+}
+export interface RequestContext {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    cookies: Record<string, string>;
+    geo?: GeoContext;
+}
+export interface GeoContext {
+    country?: string;
+    region?: string;
+    city?: string;
+}
+export interface ReleaseContext {
+    releaseId: string;
+    codeDigest: string;
+    contentSnapshotId: string;
+    assetUrl(logicalPath: string): string;
+}
+export interface RenderFragmentRequest {
+    fragmentId: string;
+    content: unknown;
+    release: ReleaseContext;
+}
+export interface RenderIslandRequest {
+    islandId: string;
+    component: string;
+    props: Record<string, unknown>;
+    requestContext: RequestContext;
+    release: ReleaseContext;
+}
+export interface RenderResult {
+    html: string;
+    status?: number;
+    headers?: Record<string, string>;
+    cachePolicy?: CachePolicy;
+}
+export interface RenderPageResult extends RenderResult {
+    islands?: IslandDescriptor[];
+}
+export interface IslandDescriptor {
+    islandId: string;
+    component: string;
+    props: Record<string, unknown>;
+    mode: 'ssr' | 'client';
+    varyDimensions?: VaryDimension[];
+}
+export interface CachePolicy {
+    scope: 'public' | 'private' | 'no-store';
+    ttl?: number;
+    staleWhileRevalidate?: number;
+    tags?: string[];
+}

package/dist/types/renderer.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@gradial/aci",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/cli/*.mjs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./compiler": {
+      "types": "./dist/compiler/index.d.ts",
+      "import": "./dist/compiler/index.js"
+    },
+    "./content": {
+      "types": "./dist/content/index.d.ts",
+      "import": "./dist/content/index.js"
+    },
+    "./content/contract": {
+      "types": "./dist/content/contract.d.ts",
+      "import": "./dist/content/contract.js"
+    },
+    "./content/validation": {
+      "types": "./dist/content/validation.d.ts",
+      "import": "./dist/content/validation.js"
+    },
+    "./content/tailwind-validator": {
+      "types": "./dist/content/tailwind-validator.d.ts",
+      "import": "./dist/content/tailwind-validator.js"
+    },
+    "./providers/file": {
+      "types": "./dist/providers/file.d.ts",
+      "import": "./dist/providers/file.js"
+    },
+    "./dev": {
+      "types": "./dist/dev/index.d.ts",
+      "import": "./dist/dev/index.js"
+    },
+    "./astro": {
+      "types": "./dist/astro/index.d.ts",
+      "import": "./dist/astro/index.js"
+    },
+    "./next/server": {
+      "types": "./dist/next/server.d.ts",
+      "import": "./dist/next/server.js",
+      "default": "./dist/next/server.js"
+    },
+    "./next/middleware": {
+      "types": "./dist/next/middleware.d.ts",
+      "import": "./dist/next/middleware.js",
+      "default": "./dist/next/middleware.js"
+    },
+    "./next/dev-refresh": {
+      "types": "./dist/next/dev-refresh.d.ts",
+      "import": "./dist/next/dev-refresh.js"
+    },
+    "./sveltekit": {
+      "types": "./dist/sveltekit/index.d.ts",
+      "import": "./dist/sveltekit/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./cli/compile-registry": "./src/cli/compile-registry.mjs",
+    "./cli/verify-renderer": "./src/cli/verify-renderer.mjs"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "compile-registry": "tsx src/cli/compile-registry.mjs",
+    "prepack": "npm run build"
+  },
+  "overrides": {
+    "postcss": "^8.5.10"
+  },
+  "peerDependencies": {
+    "@vercel/edge-config": "^1.4.3",
+    "next": "^15.5.0",
+    "react": "^19.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@vercel/edge-config": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vercel/edge-config": "^1.4.3",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.0.0",
+    "next": "^15.5.6",
+    "react": "^19.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/cli/compile-registry.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+
+const args = parseArgs(process.argv.slice(2));
+
+try {
+  const result = await compileRegistry(args);
+  console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
+} catch (error) {
+  console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
+  process.exitCode = 1;
+}
+
+async function compileRegistry(options) {
+  const required = ['components', 'layouts', 'output'];
+  for (const key of required) {
+    if (!options[key]) throw new Error(`missing --${key}`);
+  }
+
+  const components = await loadDefaultArray(options.components, 'component registry');
+  const layouts = await loadDefaultArray(options.layouts, 'layout registry');
+  const outDir = path.resolve(options.output);
+  const schemaDir = path.join(outDir, 'schemas');
+  await mkdir(schemaDir, { recursive: true });
+
+  const seenComponents = new Set();
+  const componentEntries = [];
+  const schemaFiles = [];
+  for (const [index, component] of components.entries()) {
+    validateComponent(component, index, seenComponents);
+    const schema = compileSchema(component.schema, component.name);
+    const schemaFile = `schemas/${component.name}.schema.json`;
+    const schemaPath = path.join(outDir, schemaFile);
+    await writeFile(schemaPath, JSON.stringify(schema, null, 2) + '\n');
+    schemaFiles.push(schemaPath);
+    const renderModes = component.renderModes ?? component.render;
+    const varyDimensions = component.varyDimensions ?? component.vary;
+    componentEntries.push({
+      name: component.name,
+      schemaFile,
+      render: {
+        static: Boolean(renderModes.canStatic ?? renderModes.static),
+        ssr: Boolean(renderModes.canSSR ?? renderModes.ssr),
+        clientIsland: Boolean(renderModes.canClientIsland ?? renderModes.clientIsland),
+      },
+      renderModes: {
+        canStatic: Boolean(renderModes.canStatic ?? renderModes.static),
+        canSSR: Boolean(renderModes.canSSR ?? renderModes.ssr),
+        canClientIsland: Boolean(renderModes.canClientIsland ?? renderModes.clientIsland),
+      },
+      ...(component.defaultIslandMode ? { defaultIslandMode: component.defaultIslandMode } : {}),
+      ...(varyDimensions?.length ? { vary: varyDimensions, varyDimensions } : {}),
+    });
+  }
+
+  const seenLayouts = new Set();
+  const layoutEntries = layouts.map((layout, index) => validateLayout(layout, index, seenLayouts));
+
+  const registry = {
+    manifestVersion: '1',
+    generatedAt: new Date().toISOString(),
+    components: componentEntries,
+    layouts: layoutEntries,
+  };
+  const registryPath = path.join(outDir, 'registry.json');
+  await writeFile(registryPath, JSON.stringify(registry, null, 2) + '\n');
+  return { registry: registryPath, schemas: schemaFiles };
+}
+
+async function loadDefaultArray(modulePath, label) {
+  const mod = await import(pathToFileURL(path.resolve(modulePath)).href);
+  const value = mod.default ?? mod.registry ?? mod.components ?? mod.layouts;
+  if (!Array.isArray(value)) throw new Error(`${label} must export an array`);
+  return value;
+}
+
+function validateComponent(component, index, seen) {
+  if (!component || typeof component !== 'object') throw new Error(`components[${index}] must be an object`);
+  if (!component.name) throw new Error(`components[${index}].name is required`);
+  if (seen.has(component.name)) throw new Error(`duplicate component name ${component.name}`);
+  seen.add(component.name);
+  if (!component.schema) throw new Error(`components[${index}].schema is required`);
+  validateZodSubset(component.schema, `components[${index}].schema`);
+  const renderModes = component.renderModes ?? component.render;
+  if (!renderModes) throw new Error(`components[${index}].renderModes is required`);
+  const enabled = Boolean(renderModes.canStatic ?? renderModes.static)
+    || Boolean(renderModes.canSSR ?? renderModes.ssr)
+    || Boolean(renderModes.canClientIsland ?? renderModes.clientIsland);
+  if (!enabled) throw new Error(`components[${index}].renderModes must enable at least one mode`);
+}
+
+function validateLayout(layout, index, seen) {
+  if (!layout || typeof layout !== 'object') throw new Error(`layouts[${index}] must be an object`);
+  if (!layout.name) throw new Error(`layouts[${index}].name is required`);
+  if (seen.has(layout.name)) throw new Error(`duplicate layout name ${layout.name}`);
+  seen.add(layout.name);
+  if (!Array.isArray(layout.slots)) throw new Error(`layouts[${index}].slots must be an array`);
+  const slots = [];
+  const seenSlots = new Set();
+  for (const [slotIndex, slot] of layout.slots.entries()) {
+    if (!slot?.name) throw new Error(`layouts[${index}].slots[${slotIndex}].name is required`);
+    if (seenSlots.has(slot.name)) throw new Error(`duplicate slot name ${slot.name} in layout ${layout.name}`);
+    seenSlots.add(slot.name);
+    slots.push({ name: slot.name, required: Boolean(slot.required) });
+  }
+  return { name: layout.name, slots };
+}
+
+function compileSchema(schema, name) {
+  const toJSONSchema = z.toJSONSchema;
+  if (typeof toJSONSchema !== 'function') {
+    throw new Error('Zod 4 is required: install zod@^4.0.0');
+  }
+  const compiled = toJSONSchema(schema, {
+    target: 'draft-2020-12',
+    unrepresentable: 'throw',
+  });
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: name,
+    ...compiled,
+  };
+}
+
+function validateZodSubset(schema, pathLabel, seen = new Set()) {
+  if (seen.has(schema)) return;
+  seen.add(schema);
+  const def = schema?._def;
+  if (!def) throw new Error(`${pathLabel}: expected a Zod schema`);
+  const typeName = def.typeName ?? def.type;
+  if (unsupportedZodType(typeName)) {
+    throw new Error(`${pathLabel}: unsupported Zod feature ${typeName}`);
+  }
+  rejectUnsupportedChecks(def, pathLabel);
+  for (const child of childSchemas(def)) {
+    validateZodSubset(child.schema, `${pathLabel}${child.path}`, seen);
+  }
+}
+
+function unsupportedZodType(typeName) {
+  return new Set([
+    'ZodEffects',
+    'ZodPipeline',
+    'ZodLazy',
+    'ZodPromise',
+    'ZodFunction',
+    'ZodTransform',
+    'pipe',
+    'lazy',
+    'promise',
+    'function',
+    'transform',
+    'custom',
+  ]).has(String(typeName));
+}
+
+function rejectUnsupportedChecks(def, pathLabel) {
+  if (!Array.isArray(def.checks)) return;
+  for (const [index, check] of def.checks.entries()) {
+    const checkType = check?.def?.type ?? check?._def?.type ?? check?._zod?.def?.check;
+    if (String(checkType) === 'custom') {
+      throw new Error(`${pathLabel}.checks[${index}]: unsupported Zod feature custom`);
+    }
+  }
+}
+
+function childSchemas(def) {
+  const children = [];
+  if (def.innerType) children.push({ path: '.inner', schema: def.innerType });
+  if (def.schema) children.push({ path: '.schema', schema: def.schema });
+  if (def.valueType) children.push({ path: '.value', schema: def.valueType });
+  if (def.keyType) children.push({ path: '.key', schema: def.keyType });
+  if (Array.isArray(def.options)) def.options.forEach((schema, index) => children.push({ path: `.options[${index}]`, schema }));
+  if (Array.isArray(def.items)) def.items.forEach((schema, index) => children.push({ path: `.items[${index}]`, schema }));
+  const shape = typeof def.shape === 'function' ? def.shape() : def.shape;
+  if (shape && typeof shape === 'object') {
+    for (const [name, schema] of Object.entries(shape)) children.push({ path: `.shape.${name}`, schema });
+  }
+  return children;
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const body = arg.slice(2);
+    const equals = body.indexOf('=');
+    if (equals >= 0) {
+      out[body.slice(0, equals)] = body.slice(equals + 1);
+      continue;
+    }
+    out[body] = argv[++i];
+  }
+  return out;
+}