@gradial/aci 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# Agentic Content Infrastructure SDK
+
+Agentic Content Infrastructure (ACI) sites implement the frontend contract by
+installing `@gradial/aci`, Zod 4, and TypeScript tooling. The
+SDK exposes component and layout helpers, renderer types, compiler tooling,
+content provider helpers, and framework-specific subpaths from one package.
+
+```bash
+npm install @gradial/aci zod@^4
+npm install -D typescript tsx
+```
+
+Common imports:
+
+```ts
+import { defineComponent, defineLayout, slot } from '@gradial/aci';
+import type { GradialRenderer } from '@gradial/aci';
+import type { KernelPage, KernelSiteConfig } from '@gradial/aci/content';
+import { createContentSchemas, stringField } from '@gradial/aci/content';
+import { FileContentProvider } from '@gradial/aci/providers/file';
+```
+
+Content contract helpers are also available through focused subpaths:
+`@gradial/aci/content/contract`, `@gradial/aci/content/validation`, and
+`@gradial/aci/content/tailwind-validator`.
+
+Framework helpers live under `@gradial/aci/astro`,
+`@gradial/aci/next/server`, `@gradial/aci/next/middleware`,
+`@gradial/aci/next/dev-refresh`, and `@gradial/aci/sveltekit`.
+
+Testing helpers live under `@gradial/aci/testing`:
+
+```ts
+import { FixtureContentProvider } from '@gradial/aci/testing';
+
+const content = new FixtureContentProvider({
+  pages: {
+    '/': {
+      id: 'home',
+      $type: 'page',
+      status: 'published',
+      layout: 'marketing',
+      renderMode: 'static',
+      metadata: { title: 'Test Home' },
+      regions: { main: [] }
+    }
+  }
+});
+
+const input = await content.loadRenderInput('/');
+```
+
+Use this in unit tests when you want the same provider API as
+`FileContentProvider` without creating `.content` fixture files.
+
+Publish from this package directory:
+
+```bash
+npm publish --access restricted
+```
+
+The package includes a `prepack` script that builds `dist` before packing or
+publishing.

package/dist/astro/index.d.ts

@@ -0,0 +1,17 @@
+import { type BareMetalContentWatchOptions } from '../dev/index.js';
+interface AstroConfigSetupParams {
+    injectScript(stage: 'head-inline' | 'page' | 'page-ssr', content: string): void;
+    updateConfig(config: {
+        vite?: {
+            plugins?: unknown[];
+        };
+    }): void;
+}
+export interface AstroIntegrationLike {
+    name: string;
+    hooks: {
+        'astro:config:setup'(params: AstroConfigSetupParams): void;
+    };
+}
+export declare function baremetalAstro(options?: BareMetalContentWatchOptions): AstroIntegrationLike;
+export {};

package/dist/astro/index.js

@@ -0,0 +1,21 @@
+import { baremetalContentWatchPlugin, devRefreshPort, devRefreshScript, } from '../dev/index.js';
+export function baremetalAstro(options = {}) {
+    return {
+        name: 'baremetal-astro',
+        hooks: {
+            'astro:config:setup'({ injectScript, updateConfig }) {
+                if (process.env.NODE_ENV === 'production') {
+                    return;
+                }
+                if (devRefreshPort(options) > 0) {
+                    injectScript('page', devRefreshScript(options));
+                }
+                updateConfig({
+                    vite: {
+                        plugins: [baremetalContentWatchPlugin(options)],
+                    },
+                });
+            },
+        },
+    };
+}

package/dist/compiler/index.d.ts

@@ -0,0 +1,2 @@
+export * from './validate-subset.js';
+export * from './zod-to-jsonschema.js';

package/dist/compiler/index.js

@@ -0,0 +1,2 @@
+export * from './validate-subset.js';
+export * from './zod-to-jsonschema.js';

package/dist/compiler/validate-subset.d.ts

@@ -0,0 +1,2 @@
+import type { ZodTypeAny } from 'zod';
+export declare function validateZodSubset(schema: ZodTypeAny): void;

package/dist/compiler/validate-subset.js

@@ -0,0 +1,73 @@
+const unsupported = new Set([
+    'ZodEffects',
+    'ZodPipeline',
+    'ZodLazy',
+    'ZodPromise',
+    'ZodFunction',
+    'ZodTransform',
+    'pipe',
+    'lazy',
+    'promise',
+    'function',
+    'transform',
+    'custom',
+]);
+export function validateZodSubset(schema) {
+    const seen = new Set();
+    visit(schema, '$', seen);
+}
+function visit(schema, path, seen) {
+    if (seen.has(schema)) {
+        return;
+    }
+    seen.add(schema);
+    const typeName = schema?._def?.typeName ?? schema?._def?.type;
+    if (unsupported.has(String(typeName))) {
+        throw new Error(`${path}: unsupported Zod schema feature ${typeName}`);
+    }
+    const def = schema?._def;
+    if (!def) {
+        return;
+    }
+    rejectUnsupportedChecks(def, path);
+    for (const child of childSchemas(def)) {
+        visit(child.schema, `${path}${child.path}`, seen);
+    }
+}
+function rejectUnsupportedChecks(def, path) {
+    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(`${path}.checks[${index}]: unsupported Zod schema 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 (def.element)
+        children.push({ path: '.element', schema: def.element });
+    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: schema });
+        }
+    }
+    return children;
+}

package/dist/compiler/zod-to-jsonschema.d.ts

@@ -0,0 +1,2 @@
+import { type ZodTypeAny } from 'zod';
+export declare function compileSchema(zodSchema: ZodTypeAny): object;

package/dist/compiler/zod-to-jsonschema.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { validateZodSubset } from './validate-subset.js';
+export function compileSchema(zodSchema) {
+    validateZodSubset(zodSchema);
+    const toJSONSchema = z.toJSONSchema;
+    if (typeof toJSONSchema !== 'function') {
+        throw new Error('Zod 4 is required: install zod@^4.0.0');
+    }
+    return toJSONSchema(zodSchema, {
+        target: 'draft-2020-12',
+        unrepresentable: 'throw',
+    });
+}

package/dist/content/contract.d.ts

@@ -0,0 +1,83 @@
+export declare const themeValues: readonly ["auto", "light", "dark"];
+export declare const buttonVariantValues: readonly ["primary", "secondary", "tertiary", "outline", "ghost"];
+export declare const iconPositionValues: readonly ["before", "after"];
+export type ContractField = {
+    kind: 'array';
+    items: ContractField;
+    optional?: boolean;
+} | {
+    kind: 'enum';
+    values: readonly [string, ...string[]];
+    optional?: boolean;
+} | {
+    kind: 'atomicBlocks';
+    optional?: boolean;
+} | {
+    kind: 'boolean';
+    optional?: boolean;
+} | {
+    kind: 'className';
+    optional?: boolean;
+} | {
+    kind: 'componentClassName';
+    optional?: boolean;
+} | {
+    kind: 'image';
+    optional?: boolean;
+} | {
+    kind: 'object';
+    fields: Record<string, ContractField>;
+    optional?: boolean;
+} | {
+    kind: 'richText';
+    optional?: boolean;
+} | {
+    kind: 'string';
+    minLength?: number;
+    optional?: boolean;
+};
+export interface BlockContract {
+    component: string;
+    displayName: string;
+    description: string;
+    props: Record<string, ContractField>;
+}
+export interface AtomicBlockContract extends BlockContract {
+}
+export declare const stringField: (options?: {
+    minLength?: number;
+    optional?: boolean;
+}) => ContractField;
+export declare const booleanField: (options?: {
+    optional?: boolean;
+}) => ContractField;
+export declare const imageField: (options?: {
+    optional?: boolean;
+}) => ContractField;
+export declare const enumField: (values: readonly [string, ...string[]], options?: {
+    optional?: boolean;
+}) => ContractField;
+export declare const arrayField: (items: ContractField, options?: {
+    optional?: boolean;
+}) => ContractField;
+export declare const objectField: (fields: Record<string, ContractField>, options?: {
+    optional?: boolean;
+}) => ContractField;
+export declare const richTextField: (options?: {
+    optional?: boolean;
+}) => ContractField;
+export declare const atomicBlocksField: (options?: {
+    optional?: boolean;
+}) => ContractField;
+export declare const classNameField: (options?: {
+    optional?: boolean;
+}) => ContractField;
+export declare const componentClassNameField: (options?: {
+    optional?: boolean;
+}) => ContractField;
+export declare const defaultAtomicBlockContracts: AtomicBlockContract[];
+export declare const defaultBlockContracts: BlockContract[];
+export declare const blockContracts: BlockContract[];
+export declare const atomicBlockContracts: AtomicBlockContract[];
+export declare const supportedBlockComponents: string[];
+export declare const supportedAtomicBlockComponents: string[];

package/dist/content/contract.js

@@ -0,0 +1,104 @@
+export const themeValues = ['auto', 'light', 'dark'];
+export const buttonVariantValues = ['primary', 'secondary', 'tertiary', 'outline', 'ghost'];
+export const iconPositionValues = ['before', 'after'];
+export const stringField = (options = {}) => ({
+    kind: 'string',
+    ...options,
+});
+export const booleanField = (options = {}) => ({
+    kind: 'boolean',
+    ...options,
+});
+export const imageField = (options = {}) => ({
+    kind: 'image',
+    ...options,
+});
+export const enumField = (values, options = {}) => ({
+    kind: 'enum',
+    values,
+    ...options,
+});
+export const arrayField = (items, options = {}) => ({
+    kind: 'array',
+    items,
+    ...options,
+});
+export const objectField = (fields, options = {}) => ({
+    kind: 'object',
+    fields,
+    ...options,
+});
+export const richTextField = (options = {}) => ({
+    kind: 'richText',
+    ...options,
+});
+export const atomicBlocksField = (options = {}) => ({
+    kind: 'atomicBlocks',
+    ...options,
+});
+export const classNameField = (options = {}) => ({
+    kind: 'className',
+    ...options,
+});
+export const componentClassNameField = (options = {}) => ({
+    kind: 'componentClassName',
+    ...options,
+});
+const themeFields = {
+    theme: enumField(themeValues, { optional: true }),
+    className: componentClassNameField({ optional: true }),
+};
+export const defaultAtomicBlockContracts = [
+    {
+        component: 'button',
+        displayName: 'Button',
+        description: 'Inline link styled as a button.',
+        props: {
+            label: stringField({ minLength: 1 }),
+            href: stringField({ minLength: 1 }),
+            variant: enumField(buttonVariantValues, { optional: true }),
+            newWindow: booleanField({ optional: true }),
+            icon: stringField({ optional: true }),
+            iconPosition: enumField(iconPositionValues, { optional: true }),
+            className: componentClassNameField({ optional: true }),
+        },
+    },
+];
+export const defaultBlockContracts = [
+    {
+        component: 'home_hero',
+        displayName: 'Home Hero',
+        description: 'Full-width hero section with headline, description, CTA, and image.',
+        props: {
+            eyebrow: stringField({ optional: true }),
+            headline: stringField({ minLength: 1 }),
+            description: stringField({ optional: true }),
+            ctaLabel: stringField({ minLength: 1 }),
+            ctaHref: stringField({ minLength: 1 }),
+            image: imageField(),
+        },
+    },
+    {
+        component: 'container',
+        displayName: 'Container',
+        description: 'Themed section wrapper that renders a stack of atomic content blocks.',
+        props: {
+            ...themeFields,
+            blocks: atomicBlocksField(),
+        },
+    },
+    {
+        component: 'ssr_probe',
+        displayName: 'SSR Probe',
+        description: 'Server-rendered proof section used by render/publish smoke tests.',
+        props: {
+            label: stringField({ optional: true }),
+            message: stringField({ optional: true }),
+            mode: stringField({ optional: true }),
+        },
+    },
+];
+export const blockContracts = defaultBlockContracts;
+export const atomicBlockContracts = defaultAtomicBlockContracts;
+export const supportedBlockComponents = defaultBlockContracts.map((block) => block.component);
+export const supportedAtomicBlockComponents = defaultAtomicBlockContracts.map((block) => block.component);

package/dist/content/index.d.ts

@@ -0,0 +1,6 @@
+export * from './contract.js';
+export * from './provider.js';
+export * from './routes.js';
+export * from './tailwind-validator.js';
+export * from './types.js';
+export * from './validation.js';

package/dist/content/index.js

@@ -0,0 +1,6 @@
+export * from './contract.js';
+export * from './provider.js';
+export * from './routes.js';
+export * from './tailwind-validator.js';
+export * from './types.js';
+export * from './validation.js';

package/dist/content/provider.d.ts

@@ -0,0 +1,15 @@
+import type { KernelPage, KernelRouteMetadata, KernelSiteConfig, RenderInput } from './types.js';
+export interface ContentProvider<TPage extends KernelPage = KernelPage, TSiteConfig extends KernelSiteConfig = KernelSiteConfig> {
+    loadSiteConfig(): Promise<TSiteConfig>;
+    loadPage(route?: string): Promise<TPage | null>;
+    listRoutes(): Promise<string[]>;
+    listPublishedRoutes?(): Promise<string[]>;
+    resolveRouteMetadata?(route?: string): Promise<KernelRouteMetadata>;
+}
+export interface RenderInputOptions {
+    domain?: string;
+    locale?: string;
+}
+export declare function loadRenderInput<TPage extends KernelPage = KernelPage, TSiteConfig extends KernelSiteConfig = KernelSiteConfig>(provider: ContentProvider<TPage, TSiteConfig>, route?: string, options?: RenderInputOptions): Promise<RenderInput<TPage, TSiteConfig>>;
+export declare function routeMetadataForContent(siteConfig: KernelSiteConfig, page: KernelPage | null): KernelRouteMetadata;
+export declare function resolveRouteMetadata(provider: ContentProvider, route?: string): Promise<KernelRouteMetadata>;

package/dist/content/provider.js

@@ -0,0 +1,36 @@
+import { normalizeRoute } from './routes.js';
+export async function loadRenderInput(provider, route = '/', options = {}) {
+    const normalizedRoute = normalizeRoute(route);
+    const [siteConfig, page] = await Promise.all([
+        provider.loadSiteConfig(),
+        provider.loadPage(normalizedRoute)
+    ]);
+    return {
+        route: normalizedRoute,
+        domain: options.domain || siteConfig.domain,
+        locale: (options.locale || siteConfig.defaultLocale).toLowerCase(),
+        siteConfig,
+        page
+    };
+}
+export function routeMetadataForContent(siteConfig, page) {
+    const title = page?.metadata?.title || siteConfig.seo?.title || siteConfig.title;
+    const description = page?.metadata?.description || siteConfig.seo?.description || '';
+    return {
+        title,
+        description,
+        canonical: page?.metadata?.canonical,
+        siteName: siteConfig.seo?.siteName || siteConfig.title
+    };
+}
+export async function resolveRouteMetadata(provider, route = '/') {
+    if (provider.resolveRouteMetadata) {
+        return provider.resolveRouteMetadata(route);
+    }
+    const normalizedRoute = normalizeRoute(route);
+    const [siteConfig, page] = await Promise.all([
+        provider.loadSiteConfig(),
+        provider.loadPage(normalizedRoute)
+    ]);
+    return routeMetadataForContent(siteConfig, page);
+}

package/dist/content/routes.d.ts

@@ -0,0 +1,16 @@
+export declare const DEFAULT_DOMAIN = "www.baremetal.local";
+export declare const DEFAULT_LOCALE = "en-us";
+export interface ContentPathOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    maxWorkspaceDepth?: number;
+}
+export declare function activeDomain(env?: NodeJS.ProcessEnv): string;
+export declare function activeLocale(env?: NodeJS.ProcessEnv): string;
+export declare function normalizeRoute(route: string): string;
+export declare function workspaceRoot(options?: ContentPathOptions): string;
+export declare function contentRoot(options?: ContentPathOptions): string;
+export declare function siteRoot(options?: ContentPathOptions): string;
+export declare function localeRoot(options?: ContentPathOptions): string;
+export declare function routeToPagePath(route: string, options?: ContentPathOptions): string;
+export declare function routeFromRelativePagePath(relativePath: string): string;

package/dist/content/routes.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const DEFAULT_DOMAIN = 'www.baremetal.local';
+export const DEFAULT_LOCALE = 'en-us';
+function resolveFrom(cwd, value) {
+    return path.isAbsolute(value) ? value : path.resolve(cwd, value);
+}
+export function activeDomain(env = process.env) {
+    return env.BARE_METAL_DOMAIN || DEFAULT_DOMAIN;
+}
+export function activeLocale(env = process.env) {
+    return (env.BARE_METAL_LOCALE || DEFAULT_LOCALE).toLowerCase();
+}
+export function normalizeRoute(route) {
+    const trimmed = String(route || '').trim();
+    if (!trimmed || trimmed === '/') {
+        return '/';
+    }
+    return `/${trimmed.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+}
+export function workspaceRoot(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const env = options.env || process.env;
+    if (env.BARE_METAL_WORKSPACE_ROOT) {
+        return resolveFrom(cwd, env.BARE_METAL_WORKSPACE_ROOT);
+    }
+    let current = cwd;
+    const maxDepth = options.maxWorkspaceDepth ?? 6;
+    for (let depth = 0; depth < maxDepth; depth += 1) {
+        if (fs.existsSync(path.join(current, '.content', 'config', 'site.json'))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return cwd;
+}
+export function contentRoot(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const env = options.env || process.env;
+    if (env.BARE_METAL_CONTENT_ROOT) {
+        return resolveFrom(cwd, env.BARE_METAL_CONTENT_ROOT);
+    }
+    return path.join(workspaceRoot(options), '.content');
+}
+export function siteRoot(options = {}) {
+    return path.join(contentRoot(options), 'config');
+}
+export function localeRoot(options = {}) {
+    return path.join(contentRoot(options), 'pages');
+}
+export function routeToPagePath(route, options = {}) {
+    const normalized = normalizeRoute(route);
+    if (normalized === '/') {
+        return path.join(localeRoot(options), 'home', '_index.json');
+    }
+    return path.join(localeRoot(options), normalized.slice(1), '_index.json');
+}
+export function routeFromRelativePagePath(relativePath) {
+    const normalized = relativePath.split(/[\\/]+/).join('/');
+    const slug = normalized.replace(/\/_index\.json$/, '');
+    if (slug === 'home') {
+        return '/';
+    }
+    return normalizeRoute(slug);
+}

package/dist/content/tailwind-validator.d.ts

@@ -0,0 +1,6 @@
+export interface ClassNameValidationResult {
+    valid: boolean;
+    invalidClasses: string[];
+}
+export declare function validateContentClassName(value: string): ClassNameValidationResult;
+export declare function validateComponentClassName(value: string): ClassNameValidationResult;

package/dist/content/tailwind-validator.js

@@ -0,0 +1,31 @@
+const MODIFIER_PATTERN = /^(!)?(?:(?:hover|focus|focus-within|focus-visible|active|disabled|visited|checked|first|last|odd|even|sm|md|lg|xl|2xl|dark|light|motion-safe|motion-reduce|portrait|landscape|print|rtl|ltr|open|placeholder|before|after|first-line|first-letter|selection|marker|group-hover|group-focus|peer-hover|peer-focus|has|not|aria-\w+|data-\w+):)*/;
+const RAW_VALUE_PATTERN = /\[(?:#|.*?\d+(?:px|rem|em|vh|vw|dvh|dvw|svh|svw|ch|ex|cap|ic|lh|rlh|cm|mm|in|pt|pc|%))/;
+function parseToken(token) {
+    return token.replace(MODIFIER_PATTERN, '');
+}
+function hasArbitraryBracket(bare) {
+    return bare.includes('[');
+}
+function hasRawArbitraryValue(bare) {
+    if (!hasArbitraryBracket(bare)) {
+        return false;
+    }
+    return RAW_VALUE_PATTERN.test(bare);
+}
+function validate(value, isInvalid) {
+    const tokens = value.trim().split(/\s+/).filter(Boolean);
+    const invalidClasses = [];
+    for (const token of tokens) {
+        const bare = parseToken(token);
+        if (isInvalid(bare)) {
+            invalidClasses.push(token);
+        }
+    }
+    return { valid: invalidClasses.length === 0, invalidClasses };
+}
+export function validateContentClassName(value) {
+    return validate(value, hasArbitraryBracket);
+}
+export function validateComponentClassName(value) {
+    return validate(value, hasRawArbitraryValue);
+}