@gradial/aci 0.1.25 → 0.1.27

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.21` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.27` is a pre-1.0 public-surface reset for the ACI
 client SDK. Breaking changes from the old `0.1.x` accidental surface are
 intentional: the root import is framework-neutral, framework runtime behavior is
 behind explicit subpaths, and the first required customer path is React/Next.
@@ -8,7 +8,7 @@ behind explicit subpaths, and the first required customer path is React/Next.
 ## Install
 
 ```bash
-npm install @gradial/aci@0.1.21 zod@^4
+npm install @gradial/aci@0.1.27 zod@^4
 ```
 
 ## Root Import
@@ -44,10 +44,27 @@ Next integration helpers live under explicit Next subpaths:
 
 ```ts
 import { createPage, withAci } from '@gradial/aci/next';
-import { createMiddleware } from '@gradial/aci/next/middleware';
+import { createGradialMiddleware } from '@gradial/aci/next/middleware';
 import { DevRefresh } from '@gradial/aci/next/dev-refresh';
 ```
 
+Use `ACI_SITE_ID` for the deployed site identity. Passing `siteId` to
+`createGradialMiddleware()` is still supported, but the default template relies
+on the environment so server and middleware resolution behave the same way.
+
+Middleware release-scopes document routes by default, including files such as
+`/robots.txt` and `/sitemap.xml`. Next internals, API routes, `favicon.ico`,
+public files discovered from `public/`, and `/gradial/assets/*` are left to
+Next. App-owned routes can opt out through `next.config`:
+
+```js
+import { withAci } from '@gradial/aci/next/config';
+
+export default withAci(nextConfig, {
+  passthroughRoutes: ['/healthz', '/checkout/:path*'],
+});
+```
+
 Astro public subpath is `@gradial/aci/astro`.
 
 ## Server-Side Content Providers
@@ -68,13 +85,13 @@ go through an app-owned HTTP endpoint backed server-side by a `ContentProvider`.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.21 init my-site --template next-starter
+npx @gradial/aci@0.1.27 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.21 init --list
+npx @gradial/aci@0.1.27 init --list
 ```
 
 ## Verify Locally

package/dist/next/config.d.ts

@@ -2,5 +2,13 @@ import type { NextConfig } from 'next';
 export interface WithAciOptions {
     /** Asset rewrite prefix. Defaults to '/.gradial-dam' */
     assetPrefix?: string;
+    /**
+     * Customer-owned routes that ACI middleware should leave to Next.
+     *
+     * Use exact paths such as '/healthz' or simple Next-style catch-alls such as
+     * '/checkout/:path*'. CMS document routes such as '/robots.txt' and
+     * '/sitemap.xml' should be omitted so they stay release-scoped.
+     */
+    passthroughRoutes?: string[];
 }
 export declare function withAci(nextConfig?: NextConfig, options?: WithAciOptions): NextConfig;

package/dist/next/config.js

@@ -1,8 +1,11 @@
 import { readdirSync, existsSync } from 'fs';
 import { join, relative } from 'path';
+import { createRequire } from 'module';
 import { createContentWatchWebpackPlugin } from './content-watch.js';
+const require = createRequire(import.meta.url);
 export function withAci(nextConfig = {}, options = {}) {
     const publicPaths = collectPublicPaths(join(process.cwd(), 'public'));
+    const passthroughRoutes = normalizePassthroughRoutes(options.passthroughRoutes ?? []);
     const assetPrefix = options.assetPrefix || '/.gradial-dam';
     const userRewrites = nextConfig.rewrites;
     const userHeaders = nextConfig.headers;
@@ -60,6 +63,7 @@ export function withAci(nextConfig = {}, options = {}) {
             const webpack = require('webpack');
             config.plugins.push(new webpack.DefinePlugin({
                 '__ACI_PUBLIC_PATHS__': JSON.stringify(publicPaths),
+                '__ACI_PASSTHROUGH_ROUTES__': JSON.stringify(passthroughRoutes),
             }));
             return typeof userWebpack === 'function'
                 ? userWebpack(config, context)
@@ -67,6 +71,25 @@ export function withAci(nextConfig = {}, options = {}) {
         },
     };
 }
+function normalizePassthroughRoutes(routes) {
+    const out = [];
+    const seen = new Set();
+    for (const route of routes) {
+        const clean = normalizeRoutePattern(route);
+        if (!clean || seen.has(clean))
+            continue;
+        seen.add(clean);
+        out.push(clean);
+    }
+    return out;
+}
+function normalizeRoutePattern(route) {
+    const trimmed = route.trim();
+    if (!trimmed)
+        return '';
+    const withSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    return withSlash.replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
+}
 function collectPublicPaths(publicDir) {
     if (!existsSync(publicDir))
         return [];

package/dist/next/middleware.js

@@ -3,6 +3,7 @@ import { getUncachedEdgeConfigValue } from './edge-config.js';
 import { PREVIEW_TOKEN_COOKIE, PREVIEW_RELEASE_COOKIE, extractPreviewToken, resolvePreviewContext, createPreviewCookies, previewSignKey, } from '../preview/core.js';
 const RELEASE_SCOPED_PREFIX = '/__r';
 const PUBLIC_PATHS = new Set(typeof __ACI_PUBLIC_PATHS__ !== 'undefined' ? __ACI_PUBLIC_PATHS__ : []);
+const PASSTHROUGH_ROUTES = (typeof __ACI_PASSTHROUGH_ROUTES__ !== 'undefined' ? __ACI_PASSTHROUGH_ROUTES__ : []);
 export function createGradialMiddleware(config = {}) {
     return async function middleware(request) {
         const url = request.nextUrl;
@@ -17,6 +18,9 @@ export function createGradialMiddleware(config = {}) {
         if (PUBLIC_PATHS.has(url.pathname)) {
             return NextResponse.next();
         }
+        if (isPassthroughRoute(url.pathname)) {
+            return NextResponse.next();
+        }
         // Block direct access to /__r/... — only middleware rewrites may use it.
         if (isReleaseScopedPath(url.pathname, RELEASE_SCOPED_PREFIX)) {
             return new Response('not found', {
@@ -32,6 +36,12 @@ export function createGradialMiddleware(config = {}) {
             if (process.env.ACI_CONTENT_PROVIDER === 'file') {
                 return NextResponse.next();
             }
+            if (!siteIdForConfig(config)) {
+                return new Response('ACI site id is not configured', {
+                    status: 500,
+                    headers: { 'Cache-Control': 'private, no-store' },
+                });
+            }
             return new Response('no active release', {
                 status: 503,
                 headers: { 'Cache-Control': 'private, no-store' },
@@ -123,7 +133,7 @@ async function resolvePreviewFromRequest(request, config) {
         console.warn('[aci/mw] GRADIAL_PREVIEW_SIGN_KEY not set — preview tokens will be ignored');
         return null;
     }
-    return await resolvePreviewContext({ token, siteId: config.siteId || '', signKey });
+    return await resolvePreviewContext({ token, siteId: siteIdForConfig(config), signKey });
 }
 function cookieMap(cookies) {
     const map = new Map();
@@ -134,19 +144,23 @@ function cookieMap(cookies) {
 }
 async function activeReleaseFromEdgeConfig(config) {
     const edgeConfig = config.edgeConfig || process.env.EDGE_CONFIG || '';
-    if (!edgeConfig || !config.siteId)
+    const siteId = siteIdForConfig(config);
+    if (!edgeConfig || !siteId)
         return '';
-    const active = await activeReleasePointer(edgeConfig, config.siteId);
+    const active = await activeReleasePointer(edgeConfig, siteId);
     if (!active.releaseId)
         return '';
     const deploymentId = config.deploymentId || process.env.VERCEL_DEPLOYMENT_ID || '';
     if (!deploymentId)
         return active.releaseId;
-    const compatibility = await getEdgeConfigJSON(edgeConfig, deploymentCompatibilityKey(config.siteId, deploymentId));
+    const compatibility = await getEdgeConfigJSON(edgeConfig, deploymentCompatibilityKey(siteId, deploymentId));
     if (!compatibility)
         return active.releaseId;
     return clampRelease(active.releaseId, active.sequence || 0, compatibility);
 }
+function siteIdForConfig(config) {
+    return config.siteId || process.env.ACI_SITE_ID || '';
+}
 async function getEdgeConfigJSON(edgeConfig, key) {
     const value = await getEdgeConfigValue(edgeConfig, key);
     if (!value)
@@ -202,6 +216,31 @@ function clampRelease(activeReleaseId, activeSequence, compatibility) {
 function edgeKeySegment(value) {
     return value.replace(/[^A-Za-z0-9_-]/g, '_');
 }
+function isPassthroughRoute(pathname) {
+    return PASSTHROUGH_ROUTES.some((route) => routeMatches(pathname, route));
+}
+function routeMatches(pathname, route) {
+    const cleanPath = normalizeRoutePath(pathname);
+    const cleanRoute = normalizeRoutePath(route);
+    if (!cleanRoute)
+        return false;
+    if (cleanRoute.endsWith('/:path*')) {
+        const prefix = cleanRoute.slice(0, -'/:path*'.length) || '/';
+        return cleanPath === prefix || cleanPath.startsWith(`${prefix}/`);
+    }
+    if (cleanRoute.endsWith('/*')) {
+        const prefix = cleanRoute.slice(0, -'/*'.length) || '/';
+        return cleanPath === prefix || cleanPath.startsWith(`${prefix}/`);
+    }
+    return cleanPath === cleanRoute;
+}
+function normalizeRoutePath(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return '';
+    const pathname = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    return pathname.replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
+}
 export const config = {
-    matcher: ['/((?!_next/).*)'],
+    matcher: ['/((?!_next(?:/|$)|api(?:/|$)|gradial/assets(?:/|$)|favicon\\.ico$).*)'],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/nextjs/template/src/middleware.ts

@@ -1,4 +1,7 @@
 import { createGradialMiddleware } from '@gradial/aci/next/middleware';
 
 export default createGradialMiddleware();
-export { config } from '@gradial/aci/next/middleware';
+
+export const config = {
+  matcher: ['/((?!_next(?:/|$)|api(?:/|$)|gradial/assets(?:/|$)|favicon\\.ico$).*)'],
+};