@gradial/aci 0.1.1 → 0.1.2

package/README.md

@@ -13,7 +13,7 @@ npm install -D typescript tsx
 Common imports:
 
 ```ts
-import { defineComponent, defineLayout, slot } from '@gradial/aci';
+import { defineComponentContract, defineLayoutContract, 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';
@@ -28,6 +28,51 @@ Framework helpers live under `@gradial/aci/astro`,
 `@gradial/aci/next/server`, `@gradial/aci/next/middleware`,
 `@gradial/aci/next/dev-refresh`, and `@gradial/aci/sveltekit`.
 
+## Component Contracts vs Runtime Components
+
+Keep compile-time CMS contracts separate from runtime component implementation.
+The ACI compiler imports only contract files, so those files must not import
+React, framework components, CSS, or browser-only code.
+
+Recommended shape:
+
+```txt
+src/cms/contracts/components/hero.contract.ts
+src/cms/contracts/components/index.ts
+src/cms/contracts/layouts/index.ts
+src/components/Hero.tsx
+src/cms/renderBlock.tsx
+```
+
+Contract files own names, schemas, render modes, image slots, and other metadata:
+
+```ts
+import { defineComponentContract, GradialImageSchema } from '@gradial/aci';
+import { z } from 'zod';
+
+export const heroContract = defineComponentContract({
+  name: 'hero',
+  schema: z.object({
+    headline: z.string(),
+    image: GradialImageSchema,
+  }),
+  renderModes: { canStatic: true, canSSR: true, canClientIsland: false },
+});
+
+export type HeroProps = z.infer<typeof heroContract.schema>;
+```
+
+Runtime components may import the contract for types, but contract files should
+never import runtime components:
+
+```tsx
+import type { HeroProps } from '../cms/contracts/components/hero.contract';
+
+export function Hero(props: HeroProps) {
+  return <section>{props.headline}</section>;
+}
+```
+
 Testing helpers live under `@gradial/aci/testing`:
 
 ```ts

package/bin/aci.js

@@ -1,45 +1,157 @@
 #!/usr/bin/env node
-import { execFileSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import path from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
+const argv = process.argv.slice(2);
+const callerCwd = process.cwd();
 
-const PLATFORMS = {
-  'darwin-arm64': '@gradial/cli-darwin-arm64',
-  'darwin-x64': '@gradial/cli-darwin-x64',
-  'linux-x64': '@gradial/cli-linux-x64',
-  'linux-arm64': '@gradial/cli-linux-arm64',
-  'win32-x64': '@gradial/cli-win32-x64',
+const platformPackages = {
+  'darwin-arm64': '@gradial/aci-cli-darwin-arm64',
+  'darwin-x64': '@gradial/aci-cli-darwin-x64',
+  'linux-arm64': '@gradial/aci-cli-linux-arm64',
+  'linux-x64': '@gradial/aci-cli-linux-x64',
+  'win32-x64': '@gradial/aci-cli-win32-x64',
 };
 
-const key = `${process.platform}-${process.arch}`;
-const pkg = PLATFORMS[key];
-if (!pkg) {
-  console.error(`ACI: unsupported platform ${key}`);
+const platformKey = `${process.platform}-${process.arch}`;
+const packageName = platformPackages[platformKey];
+
+if (!packageName) {
+  console.error(`Unsupported platform for aci: ${platformKey}`);
   process.exit(1);
 }
 
-const ext = process.platform === 'win32' ? '.exe' : '';
-let bin;
-const localBin = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'bin', `aci${ext}`);
-if (process.env.ACI_BIN) {
-  bin = process.env.ACI_BIN;
-} else if (existsSync(localBin)) {
-  bin = localBin;
+const binName = process.platform === 'win32' ? 'aci.exe' : 'aci';
+const shimDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(shimDir, '../../..');
+
+function resolveBundledBinary() {
+  const binaryPath = join(shimDir, binName);
+  return existsSync(binaryPath) ? binaryPath : null;
+}
+
+function resolvePackagedBinary() {
+  try {
+    const packageJsonPath = require.resolve(`${packageName}/package.json`);
+    const binaryPath = join(dirname(packageJsonPath), 'bin', binName);
+
+    return existsSync(binaryPath) ? binaryPath : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveWorkspaceBinary() {
+  const binaryPath = resolve(shimDir, '..', '..', 'packages', `cli-${platformKey}`, 'bin', binName);
+
+  return existsSync(binaryPath) ? binaryPath : null;
+}
+
+const binaryPath = resolveBundledBinary() ?? resolvePackagedBinary() ?? resolveWorkspaceBinary();
+const fallback = binaryPath ? null : resolveGoFallback();
+
+if (!binaryPath && !fallback) {
+  console.error(
+    [
+      `Could not find the aci binary for ${platformKey}.`,
+      `Install ${packageName} or build the local CLI package with ./scripts/build-cli.sh.`,
+    ].join(' '),
+  );
+  process.exit(1);
 }
 
-try {
-  bin ||= require.resolve(`${pkg}/bin/aci${ext}`);
-} catch {
-  console.error('ACI: binary not installed. Run: npm install');
+const child = binaryPath
+  ? spawn(binaryPath, argv, { stdio: 'inherit' })
+  : spawn(fallback.command, fallback.args, {
+      cwd: fallback.cwd,
+      stdio: 'inherit',
+    });
+
+child.on('error', (error) => {
+  console.error(`Failed to run aci: ${error.message}`);
   process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 1);
+});
+
+function resolveGoFallback() {
+  const goModPath = join(repoRoot, 'go.mod');
+  const commandDir = join(repoRoot, 'cmd', 'aci');
+
+  if (!existsSync(goModPath) || !existsSync(commandDir)) {
+    return null;
+  }
+
+  return {
+    command: 'go',
+    args: ['run', './cmd/aci', ...normalizeArgsForGoFallback(argv)],
+    cwd: repoRoot,
+  };
+}
+
+function normalizeArgsForGoFallback(args) {
+  const pathFlags = new Set(['-s', '--site-dir', '--content', '--out']);
+  const normalized = [];
+  let hasSiteDir = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (pathFlags.has(arg)) {
+      normalized.push(arg);
+      if (arg === '-s' || arg === '--site-dir') {
+        hasSiteDir = true;
+      }
+
+      const value = args[index + 1];
+      if (value !== undefined) {
+        normalized.push(normalizePathArg(value));
+        index += 1;
+      }
+      continue;
+    }
+
+    if (arg.startsWith('--site-dir=')) {
+      hasSiteDir = true;
+      normalized.push(normalizePathFlagValue(arg));
+      continue;
+    }
+
+    if (arg.startsWith('--content=') || arg.startsWith('--out=')) {
+      normalized.push(normalizePathFlagValue(arg));
+      continue;
+    }
+
+    normalized.push(arg);
+  }
+
+  return hasSiteDir ? normalized : ['--site-dir', callerCwd, ...normalized];
+}
+
+function normalizePathFlagValue(arg) {
+  const separator = arg.indexOf('=');
+  return `${arg.slice(0, separator + 1)}${normalizePathArg(arg.slice(separator + 1))}`;
+}
+
+function normalizePathArg(value) {
+  if (!value || value.startsWith('-') || isAbsolutePath(value)) {
+    return value;
+  }
+
+  return resolve(callerCwd, value);
 }
 
-try {
-  execFileSync(bin, process.argv.slice(2), { stdio: 'inherit' });
-} catch (error) {
-  process.exit(error.status ?? 1);
+function isAbsolutePath(value) {
+  return value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value);
 }

package/dist/assets/index.d.ts

@@ -1 +1,3 @@
 export { type GradialImage, type ImageSource, type PictureSource, type ImageSlotContract, type SlotOutput, type ImageHTMLAttributes, GradialImageSchema, renderImageHTML, } from '../types/image.js';
+export { type GradialVideo, type VideoSource, GradialVideoSchema, VideoSourceSchema, } from '../types/video.js';
+export { type GradialAsset, GradialAssetSchema, isGradialImage, isGradialVideo, isGradialAsset, renderVideoHTML, renderAssetHTML, } from '../types/media.js';

package/dist/assets/index.js

@@ -1 +1,3 @@
 export { GradialImageSchema, renderImageHTML, } from '../types/image.js';
+export { GradialVideoSchema, VideoSourceSchema, } from '../types/video.js';
+export { GradialAssetSchema, isGradialImage, isGradialVideo, isGradialAsset, renderVideoHTML, renderAssetHTML, } from '../types/media.js';

package/dist/astro/index.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { gradialContentWatchPlugin, devRefreshPort, devRefreshScript, } from '../dev/index.js';
+import { gradialContentWatchPlugin, gradialDamAssetPlugin, devRefreshPort, devRefreshScript, } from '../dev/index.js';
 // ---------------------------------------------------------------------------
 // Static paths helper — for Astro SSG
 // ---------------------------------------------------------------------------
@@ -40,17 +40,17 @@ export function gradialAstro(options = {}) {
                 }
                 updateConfig({
                     vite: {
-                        plugins: [gradialContentWatchPlugin(options)],
+                        plugins: [gradialDamAssetPlugin(options), gradialContentWatchPlugin(options)],
                     },
                 });
             },
             'astro:build:done'({ dir }) {
                 const siteDir = process.cwd();
                 const compiledRoot = path.resolve(siteDir, options.compiledRoot || process.env.ACI_CONTENT_ROOT || '.aci/compiled');
-                const source = path.join(compiledRoot, '.aci-dam');
+                const source = path.join(compiledRoot, '.gradial-dam');
                 if (!fs.existsSync(source))
                     return;
-                const target = path.join(dir.pathname, '.aci-dam');
+                const target = path.join(dir.pathname, '.gradial-dam');
                 fs.rmSync(target, { recursive: true, force: true });
                 fs.cpSync(source, target, { recursive: true });
             },

package/dist/block-ref.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+export interface BlockRefOptions {
+    /** Component names allowed in this slot. Omit to allow any registered component. */
+    allow?: string[];
+}
+/**
+ * Schema helper for nested component references within a parent component.
+ *
+ * Produces a Zod schema for a block entry: `{ id, component, props }`.
+ * When `allow` is provided, `component` is constrained to an enum of the
+ * listed names. This flows into the generated JSON schema, so the content
+ * validator enforces the allowlist at build time.
+ *
+ * @example
+ * ```ts
+ * defineComponent({
+ *   name: 'tabbed_panels',
+ *   schema: z.object({
+ *     tabs: z.array(z.object({
+ *       id: z.string().min(1),
+ *       label: z.string().min(1),
+ *       blocks: z.array(blockRef({ allow: ['checklist', 'text_media'] })).min(1),
+ *     })),
+ *   }),
+ * })
+ * ```
+ */
+export declare function blockRef(options?: BlockRefOptions): z.ZodObject<{
+    id: z.ZodString;
+    component: z.ZodEnum<{
+        [x: string]: string;
+    }> | z.ZodString;
+    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;

package/dist/block-ref.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+/**
+ * Schema helper for nested component references within a parent component.
+ *
+ * Produces a Zod schema for a block entry: `{ id, component, props }`.
+ * When `allow` is provided, `component` is constrained to an enum of the
+ * listed names. This flows into the generated JSON schema, so the content
+ * validator enforces the allowlist at build time.
+ *
+ * @example
+ * ```ts
+ * defineComponent({
+ *   name: 'tabbed_panels',
+ *   schema: z.object({
+ *     tabs: z.array(z.object({
+ *       id: z.string().min(1),
+ *       label: z.string().min(1),
+ *       blocks: z.array(blockRef({ allow: ['checklist', 'text_media'] })).min(1),
+ *     })),
+ *   }),
+ * })
+ * ```
+ */
+export function blockRef(options) {
+    const allow = options?.allow;
+    const componentSchema = allow && allow.length > 0
+        ? z.enum(allow)
+        : z.string().min(1);
+    return z.object({
+        id: z.string().min(1),
+        component: componentSchema,
+        props: z.record(z.string(), z.unknown()),
+    });
+}

package/dist/define-component.d.ts

@@ -1,2 +1,3 @@
 import type { ComponentContract, ComponentDefinition } from './types/component.js';
 export declare function defineComponent<TSchema = unknown>(definition: ComponentDefinition<TSchema>): ComponentContract<TSchema>;
+export declare const defineComponentContract: typeof defineComponent;

package/dist/define-component.js

@@ -11,3 +11,4 @@ export function defineComponent(definition) {
         vary: definition.vary ?? definition.varyDimensions,
     };
 }
+export const defineComponentContract = defineComponent;

package/dist/define-layout.d.ts

@@ -1,3 +1,4 @@
 import type { LayoutContract, LayoutDefinition, LayoutSlot } from './types/layout.js';
 export declare function defineLayout(definition: LayoutDefinition): LayoutContract;
+export declare const defineLayoutContract: typeof defineLayout;
 export declare function slot(name: string, required?: boolean): LayoutSlot;

package/dist/define-layout.js

@@ -5,6 +5,7 @@ export function defineLayout(definition) {
         defaults: definition.defaults,
     };
 }
+export const defineLayoutContract = defineLayout;
 export function slot(name, required = false) {
     return { name, required };
 }

package/dist/dev/index.d.ts

@@ -1,3 +1,4 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
 import { type DevRefreshOptions } from './browser.js';
 export { DEFAULT_DEV_REFRESH_PATH, DEFAULT_DEV_REFRESH_PORT, type DevRefreshOptions } from './browser.js';
 declare global {
@@ -7,9 +8,13 @@ declare global {
 }
 export interface GradialContentWatchOptions extends DevRefreshOptions {
     contentRoot?: string;
+    compiledRoot?: string;
     enabled?: boolean;
 }
 interface ViteDevServerLike {
+    middlewares?: {
+        use(path: string, handler: (req: IncomingMessage, res: ServerResponse, next: () => void) => void): void;
+    };
     watcher: {
         add(path: string): void;
         on(event: string, callback: (eventName: string, filePath: string) => void): void;
@@ -28,3 +33,4 @@ export declare function devRefreshPort(options?: DevRefreshOptions): number;
 export declare function devRefreshScript(options?: DevRefreshOptions): string;
 export declare function devRefreshScriptTag(options?: DevRefreshOptions): string;
 export declare function gradialContentWatchPlugin(options?: GradialContentWatchOptions): VitePluginLike;
+export declare function gradialDamAssetPlugin(options?: GradialContentWatchOptions): VitePluginLike;

package/dist/dev/index.js

@@ -1,3 +1,4 @@
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import { compiledContentRoot } from '../content/routes.js';
 import { DEFAULT_DEV_REFRESH_PATH, DEFAULT_DEV_REFRESH_PORT, } from './browser.js';
@@ -68,3 +69,68 @@ export function gradialContentWatchPlugin(options = {}) {
         },
     };
 }
+export function gradialDamAssetPlugin(options = {}) {
+    return {
+        name: 'gradial-dam-assets',
+        apply: 'serve',
+        configureServer(server) {
+            if (!server.middlewares) {
+                return;
+            }
+            server.middlewares.use('/.gradial-dam', async (req, res, next) => {
+                const root = path.resolve(options.compiledRoot || compiledContentRoot());
+                const requestPath = safeRequestPath(req.url || '');
+                if (!requestPath) {
+                    res.statusCode = 404;
+                    res.end('asset not found');
+                    return;
+                }
+                const filePath = path.resolve(root, '.gradial-dam', requestPath.replace(/^\/+/, ''));
+                if (!isInside(root, filePath)) {
+                    res.statusCode = 404;
+                    res.end('asset not found');
+                    return;
+                }
+                try {
+                    const body = await fs.readFile(filePath);
+                    res.statusCode = 200;
+                    res.setHeader('Content-Type', contentType(filePath));
+                    res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+                    res.end(body);
+                }
+                catch {
+                    next();
+                }
+            });
+        },
+    };
+}
+function safeRequestPath(url) {
+    const rawPath = url.split('?')[0] || '';
+    try {
+        const decoded = decodeURIComponent(rawPath);
+        return decoded.startsWith('/.gradial-dam/') ? decoded.slice('/.gradial-dam/'.length) : decoded;
+    }
+    catch {
+        return '';
+    }
+}
+function isInside(root, filePath) {
+    const rel = path.relative(root, filePath);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+function contentType(filePath) {
+    switch (path.extname(filePath).toLowerCase()) {
+        case '.webp':
+            return 'image/webp';
+        case '.svg':
+            return 'image/svg+xml';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.png':
+            return 'image/png';
+        default:
+            return 'application/octet-stream';
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
+export * from './block-ref.js';
 export * from './define-component.js';
 export * from './define-layout.js';
-export * from './content/index.js';
 export * from './types/index.js';

package/dist/index.js

@@ -1,4 +1,7 @@
+export * from './block-ref.js';
 export * from './define-component.js';
 export * from './define-layout.js';
-export * from './content/index.js';
 export * from './types/index.js';
+// Note: content/ is NOT re-exported here because it imports node:path,
+// making it incompatible with client-side bundlers. Import server-only
+// content utilities from '@gradial/aci/content' explicitly.

package/dist/next/asset-route.d.ts

@@ -0,0 +1,9 @@
+type AssetRouteContext = {
+    params: Promise<AssetRouteParams>;
+};
+type AssetRouteParams = {
+    releaseId?: string;
+    path?: string[];
+};
+export declare function GET(_request: Request, { params }: AssetRouteContext): Promise<Response>;
+export {};

package/dist/next/asset-route.js

@@ -0,0 +1,15 @@
+import { getReleaseAssetResponse } from './server.js';
+export async function GET(_request, { params }) {
+    const resolvedParams = await params;
+    const releaseId = resolvedParams.releaseId || '';
+    const assetPath = (resolvedParams.path || []).join('/');
+    if (!releaseId || !assetPath) {
+        return new Response('asset not found', { status: 404 });
+    }
+    try {
+        return await getReleaseAssetResponse(releaseId, assetPath);
+    }
+    catch {
+        return new Response('asset not found', { status: 404 });
+    }
+}

package/dist/next/config.d.ts

@@ -1,14 +1,6 @@
-interface NextRewrite {
-    source: string;
-    destination: string;
-}
-interface NextConfig {
-    rewrites?: () => Promise<NextRewrite[]> | NextRewrite[];
-    [key: string]: unknown;
-}
+import type { NextConfig } from 'next';
 export interface WithGradialOptions {
-    /** Asset rewrite prefix. Defaults to '/.aci-dam' */
+    /** Asset rewrite prefix. Defaults to '/.gradial-dam' */
     assetPrefix?: string;
 }
 export declare function withGradial(nextConfig?: NextConfig, options?: WithGradialOptions): NextConfig;
-export {};

package/dist/next/config.js

@@ -1,5 +1,5 @@
 export function withGradial(nextConfig = {}, options = {}) {
-    const assetPrefix = options.assetPrefix || '/.aci-dam';
+    const assetPrefix = options.assetPrefix || '/.gradial-dam';
     const userRewrites = nextConfig.rewrites;
     return {
         ...nextConfig,
@@ -16,7 +16,10 @@ export function withGradial(nextConfig = {}, options = {}) {
             if (Array.isArray(userResult)) {
                 return [...gradialRewrites, ...userResult];
             }
-            return gradialRewrites;
+            return {
+                ...userResult,
+                beforeFiles: [...gradialRewrites, ...(userResult.beforeFiles ?? [])],
+            };
         },
     };
 }

package/dist/next/server.d.ts

@@ -36,4 +36,8 @@ export declare function routeFromNextParams(params?: Promise<{
 export declare function generateGradialStaticParams(): Promise<Array<{
     slug?: string[];
 }>>;
+export declare class ReleaseAssetNotFoundError extends Error {
+    constructor(releaseId: string, assetPath: string, cause?: unknown);
+}
+export declare function getReleaseAssetResponse(releaseId: string, assetPath: string, config?: GradialFetchConfig): Promise<Response>;
 export declare function resolveReleaseId(config?: GradialFetchConfig): Promise<string>;

package/dist/next/server.js

@@ -47,6 +47,59 @@ export async function generateGradialStaticParams() {
         slug: entry.path === '/' ? undefined : entry.path.replace(/^\/|\/$/g, '').split('/'),
     }));
 }
+export class ReleaseAssetNotFoundError extends Error {
+    constructor(releaseId, assetPath, cause) {
+        super(`ACI release asset not found: ${releaseId}/${assetPath}`);
+        this.name = 'ReleaseAssetNotFoundError';
+        this.cause = cause;
+    }
+}
+export async function getReleaseAssetResponse(releaseId, assetPath, config = {}) {
+    const clean = cleanAssetPath(assetPath);
+    if (!releaseId || !clean) {
+        throw new ReleaseAssetNotFoundError(releaseId, assetPath);
+    }
+    const provider = new S3ContentProvider({
+        bucket: config.bucket,
+        keyPrefix: releaseKey(config, releaseId),
+        region: config.region,
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey,
+        sessionToken: config.sessionToken,
+        endpoint: config.endpoint,
+    });
+    const key = joinKey(provider.config.keyPrefix, 'assets', clean);
+    const res = await provider.fetchRaw(key);
+    if (!res.ok || !res.body) {
+        throw new ReleaseAssetNotFoundError(releaseId, clean, await safeResponseText(res));
+    }
+    const headers = new Headers();
+    copyHeader(res.headers, headers, 'content-type');
+    copyHeader(res.headers, headers, 'content-length');
+    copyHeader(res.headers, headers, 'etag');
+    copyHeader(res.headers, headers, 'last-modified');
+    headers.set('cache-control', 'public, max-age=31536000, immutable');
+    return new Response(res.body, { status: 200, headers });
+}
+function cleanAssetPath(value) {
+    const clean = value.replace(/^\/+|\/+$/g, '').replace(/\/+/g, '/');
+    if (!clean || clean.split('/').some((s) => s === '..' || s === '.'))
+        return '';
+    return clean;
+}
+function copyHeader(from, to, name) {
+    const value = from.get(name);
+    if (value)
+        to.set(name, value);
+}
+async function safeResponseText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return '';
+    }
+}
 export async function resolveReleaseId(config = {}) {
     if (config.releaseId)
         return config.releaseId;

package/dist/providers/s3.d.ts

@@ -18,7 +18,9 @@ export declare class S3ContentProvider implements ContentProvider {
     getPage<T = unknown>(route: string): Promise<T>;
     getFragment<T = unknown>(id: string): Promise<T>;
     manifest(): Promise<CompiledManifest>;
+    fetchRaw(key: string): Promise<Response>;
     private getJSON;
 }
 export declare function getS3JSON<T>(key: string, config: ResolvedS3Config): Promise<T>;
+export declare function getS3Raw(key: string, config: ResolvedS3Config): Promise<Response>;
 export {};