@gradial/aci 0.1.34 → 0.1.36

package/bin/aci.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import { chmodSync, existsSync } from 'node:fs';
-import { readdir, readFile, stat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
@@ -31,10 +30,10 @@ const binName = process.platform === 'win32' ? 'aci.exe' : 'aci';
 const shimDir = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(shimDir, '../../..');
 
-if (argv[0] === 'init') {
-  await runInit(argv.slice(1));
-  process.exit(0);
-}
+// All commands — including `init` — are handled by the Go CLI. The shim only
+// resolves the binary and forwards; template materialization lives in
+// internal/transport/cli/cmd/init.go (parity-tested against the TS engine in
+// scripts/test-starter-dev.mjs).
 
 // ── Binary resolution ──────────────────────────────────────────────
 //
@@ -192,74 +191,3 @@ function normalizePathArg(value) {
 function isAbsolutePath(value) {
   return value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value);
 }
-
-async function runInit(args) {
-  // Inside the function because runInit is invoked from module top-level,
-  // before module-scope const bindings below it would initialize.
-  const initTemplates = {
-    'next-starter': 'nextjs',
-    'astro-starter': 'astro',
-  };
-  if (args.includes('--list')) {
-    for (const name of Object.keys(initTemplates)) {
-      console.log(name);
-    }
-    return;
-  }
-
-  const target = args.find((arg) => !arg.startsWith('-'));
-  const template = optionValue(args, '--template') || 'next-starter';
-  const templateNames = Object.keys(initTemplates).join('|');
-  if (!target) {
-    throw new Error(`usage: aci init <target> --template ${templateNames}`);
-  }
-  const framework = initTemplates[template];
-  if (!framework) {
-    throw new Error(`unknown template "${template}". Available templates: ${Object.keys(initTemplates).join(', ')}`);
-  }
-
-  const targetDir = resolve(callerCwd, target);
-  await assertEmptyTarget(targetDir);
-
-  const packageRoot = resolve(shimDir, '..');
-  const packageJson = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf-8'));
-  const { materializeTemplate } = await import(
-    new URL('../src/cli/materialize-template.mjs', import.meta.url)
-  );
-  materializeTemplate({
-    templatesDir: join(packageRoot, 'templates'),
-    framework,
-    destDir: targetDir,
-    vars: {
-      siteName: basename(targetDir),
-      version: '0.1.0',
-      aciVersion: packageJson.version,
-    },
-  });
-  console.log(`Created ${relative(callerCwd, targetDir) || '.'} from ${template}`);
-}
-
-function optionValue(args, name) {
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === name) return args[index + 1] || '';
-    if (arg.startsWith(`${name}=`)) return arg.slice(name.length + 1);
-  }
-  return '';
-}
-
-async function assertEmptyTarget(targetDir) {
-  try {
-    const info = await stat(targetDir);
-    if (!info.isDirectory()) {
-      throw new Error(`target exists and is not a directory: ${targetDir}`);
-    }
-    const entries = await readdir(targetDir);
-    if (entries.length > 0) {
-      throw new Error(`target directory is not empty: ${targetDir}`);
-    }
-  } catch (error) {
-    if (error?.code === 'ENOENT') return;
-    throw error;
-  }
-}

package/dist/next/asset-route.js

@@ -1,5 +1,5 @@
 import { FileContentProvider } from '../providers/file.js';
-import { getReleaseAssetResponse, resolveReleaseId } from './server.js';
+import { getDamAssetResponse, getReleaseAssetResponse, isDamAssetPath, resolveReleaseId, } from './server.js';
 export const runtime = 'nodejs';
 export const dynamic = 'force-dynamic';
 export async function GET(_request, { params }) {
@@ -12,6 +12,16 @@ export async function GET(_request, { params }) {
     if (local) {
         return local;
     }
+    // DAM assets are global (not release-scoped): serve them from the hosting
+    // bucket root without resolving a release.
+    if (isDamAssetPath(assetPath)) {
+        try {
+            return await getDamAssetResponse(assetPath);
+        }
+        catch {
+            return new Response('dam asset not found', { status: 404 });
+        }
+    }
     try {
         const releaseId = await resolveReleaseId();
         return await getReleaseAssetResponse(releaseId, assetPath);

package/dist/next/config.js

@@ -45,6 +45,16 @@ export function withAci(nextConfig = {}, options = {}) {
                     destination: `${assetOrigin}${assetPrefix}/:path*`,
                 });
             }
+            else {
+                // Without an external asset origin (the deliberate CDN override),
+                // DAM requests must be served by the app itself: on Vercel nothing
+                // else maps `/.gradial-dam/*` to the hosting bucket. Route them to
+                // the asset handler, which serves DAM keys from the bucket root.
+                rewrites.push({
+                    source: `${assetPrefix}/:path*`,
+                    destination: `/gradial/assets/${assetPrefix.replace(/^\/+/, '')}/:path*`,
+                });
+            }
             // CMS document rewrites: robots.txt and sitemap.xml are release-scoped
             // artifacts served via the asset route handler (#40). The middleware
             // passes them through (CMS_DOCUMENT_PATHS) so these rewrites fire and

package/dist/next/middleware.d.ts

@@ -1,6 +1,13 @@
 import { type NextRequest } from 'next/server.js';
 export interface GradialMiddlewareConfig {
-    siteId: string;
+    /**
+     * Site identity for this deployment. Env-injected identity is valid —
+     * the platform sets ACI_SITE_ID per deployment, so passing a bare
+     * `process.env.ACI_SITE_ID` (which types as `string | undefined`) is
+     * supported. A missing value 500s cleanly at runtime
+     * ("ACI site id is not configured").
+     */
+    siteId: string | undefined;
     edgeConfig?: string;
     previewSignKey?: string;
     deploymentId?: string;

package/dist/next/middleware.js

@@ -186,7 +186,7 @@ async function activeReleaseFromEdgeConfig(config) {
     return clampRelease(active.releaseId, active.sequence || 0, compatibility);
 }
 function siteIdForConfig(config) {
-    return config.siteId;
+    return config.siteId ?? '';
 }
 async function getEdgeConfigJSON(edgeConfig, key) {
     const value = await getEdgeConfigValue(edgeConfig, key);

package/dist/next/server.d.ts

@@ -46,4 +46,9 @@ export declare class ReleaseAssetNotFoundError extends Error {
     constructor(releaseId: string, assetPath: string, cause?: unknown);
 }
 export declare function getReleaseAssetResponse(releaseId: string, assetPath: string, config?: FetchConfig): Promise<Response>;
+export declare function isDamAssetPath(assetPath: string): boolean;
+export declare class DamAssetNotFoundError extends Error {
+    constructor(assetPath: string, cause?: unknown);
+}
+export declare function getDamAssetResponse(assetPath: string, config?: FetchConfig): Promise<Response>;
 export declare function resolveReleaseId(config?: FetchConfig): Promise<string>;

package/dist/next/server.js

@@ -150,6 +150,53 @@ export async function getReleaseAssetResponse(releaseId, assetPath, config = {})
     headers.set('cache-control', 'public, max-age=300, must-revalidate');
     return new Response(res.body, { status: 200, headers });
 }
+// DAM assets are globally shared and content-addressed: the Go hosting
+// adapter stages them at the bucket ROOT under `.gradial-dam/...`
+// (prefixedKey(damAssetKey(path)) — see internal/domain/hosting/vercel), not
+// under the per-release `releases/{id}/assets/...` prefix. The tenant key
+// prefix (ACI_S3_KEY_PREFIX) still applies.
+const DAM_ASSET_KEY_PREFIX = '.gradial-dam';
+export function isDamAssetPath(assetPath) {
+    const clean = cleanAssetPath(assetPath);
+    return clean === DAM_ASSET_KEY_PREFIX || clean.startsWith(`${DAM_ASSET_KEY_PREFIX}/`);
+}
+export class DamAssetNotFoundError extends Error {
+    constructor(assetPath, cause) {
+        super(`ACI DAM asset not found: ${assetPath}`);
+        this.name = 'DamAssetNotFoundError';
+        this.cause = cause;
+    }
+}
+export async function getDamAssetResponse(assetPath, config = {}) {
+    const clean = cleanAssetPath(assetPath);
+    if (!clean.startsWith(`${DAM_ASSET_KEY_PREFIX}/`)) {
+        throw new DamAssetNotFoundError(assetPath);
+    }
+    const provider = new S3ContentProvider({
+        bucket: config.bucket,
+        keyPrefix: joinKey(config.keyPrefix || process.env.ACI_S3_KEY_PREFIX || ''),
+        region: config.region,
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey,
+        sessionToken: config.sessionToken,
+        endpoint: config.endpoint,
+    });
+    const key = joinKey(provider.config.keyPrefix, clean);
+    const res = await provider.fetchRaw(key);
+    if (!res.ok || !res.body) {
+        throw new DamAssetNotFoundError(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');
+    // DAM keys are content-addressed, so the bytes behind a key never change.
+    headers.set('cache-control', 'public, max-age=31536000, immutable');
+    headers.set('cdn-cache-control', 'max-age=31536000');
+    headers.set('vercel-cdn-cache-control', 'max-age=31536000');
+    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 === '.'))

package/dist/testing/conformance/checks.js

@@ -89,6 +89,19 @@ function walkFiles(dir, predicate) {
 // ---------------------------------------------------------------------------
 export function checkConfig(ctx) {
     const results = [];
+    // Env-only site identity: in siteIdMode 'env' the platform owns tenant
+    // identity (terraform injects ACI_SITE_ID per deployment), so .aci.yaml
+    // must not carry a siteId at all — a leftover label pins the repo to one
+    // site and drifts silently from the deployed identity.
+    if (ctx.siteIdMode === 'env') {
+        const aciYaml = readTextFile(join(ctx.rootDir, '.aci.yaml'));
+        if (aciYaml !== null) {
+            const pinsSiteId = /^siteId\s*:/m.test(aciYaml);
+            results.push(!pinsSiteId
+                ? ok('config', '.aci.yaml does not pin a siteId (env-only identity)')
+                : fail('config', '.aci.yaml does not pin a siteId (env-only identity)', '.aci.yaml declares siteId but this repo uses siteIdMode "env": the platform owns site identity (ACI_SITE_ID is injected per deployment), so the manifest must not pin a site — delete the siteId line'));
+        }
+    }
     if (ctx.framework === 'next') {
         const configFile = findFirstExisting(ctx.rootDir, [
             'next.config.ts',
@@ -242,13 +255,65 @@ export function checkMiddleware(ctx) {
     results.push(usesSDKMiddleware
         ? ok('middleware', 'middleware uses createGradialMiddleware', rel)
         : fail('middleware', 'middleware uses createGradialMiddleware', rel + ' should use createGradialMiddleware from @gradial/aci/next/middleware'));
-    // Check if siteId is configured as a literal (no env var indirection)
-    if (ctx.siteId) {
-        const hasSiteIdLiteral = middlewareFile.content.includes(`siteId`) &&
-            !middlewareFile.content.includes('process.env');
-        results.push(hasSiteIdLiteral
-            ? ok('middleware', 'middleware configures siteId (literal)', rel)
-            : fail('middleware', 'middleware configures siteId (literal)', rel + ' should pass a literal siteId string to createGradialMiddleware (no env var indirection)'));
+    // Check that the siteId passed to createGradialMiddleware is canonical.
+    // Accepted forms depend on ctx.siteIdMode (default 'literal'):
+    //
+    // 'literal':
+    //   (a) a string literal exactly equal to ctx.siteId (the tenant's
+    //       canonical site id) — this is what the template stamps;
+    //   (b) process.env.ACI_SITE_ID || '<literal>' (or ?? instead of ||)
+    //       where the literal default is exactly ctx.siteId — the
+    //       multi-tenant/dev-mirror form: the deployment env supplies the
+    //       per-tenant identity, the default keeps local dev correct.
+    //
+    // 'env' (tenant-agnostic repos deployed to multiple sites): the ONLY
+    //   accepted form is exactly `siteId: process.env.ACI_SITE_ID`. The
+    //   platform owns tenant identity — terraform sets ACI_SITE_ID on every
+    //   deployment — and the runtime 500s cleanly if it is missing, so any
+    //   literal, fallback (|| / ??), other env var name, or computed
+    //   expression fails.
+    //
+    // Anything else (placeholder literal, wrong/missing default, other env
+    // var names, computed expressions) fails: a wrong siteId means the edge
+    // release-pointer key never matches and every live route 503s.
+    const siteIdMode = ctx.siteIdMode ?? 'literal';
+    if (siteIdMode === 'env') {
+        const label = 'middleware configures canonical siteId';
+        // Narrow the search to the createGradialMiddleware call when present so
+        // an unrelated siteId reference elsewhere in the file can't satisfy us.
+        const callIdx = middlewareFile.content.indexOf('createGradialMiddleware(');
+        const region = callIdx >= 0 ? middlewareFile.content.slice(callIdx) : middlewareFile.content;
+        // Exactly `siteId: process.env.ACI_SITE_ID` followed by the end of the
+        // property (`,` or `}`) — same object-property shape the literal-mode
+        // regexes target, but with nothing allowed after the env access.
+        const bareEnv = /siteId\s*:\s*process\.env\.ACI_SITE_ID\s*(?=[,}])/.test(region);
+        results.push(bareEnv
+            ? ok('middleware', label, `${rel} (env-only siteId)`)
+            : fail('middleware', label, `${rel}: middleware must read siteId only from process.env.ACI_SITE_ID (no literal or fallback) — the platform owns tenant identity and injects ACI_SITE_ID per deployment`));
+    }
+    else if (ctx.siteId) {
+        const label = 'middleware configures canonical siteId';
+        const expected = ctx.siteId;
+        const acceptedForms = `accepted forms: siteId: '${expected}' or ` +
+            `siteId: process.env.ACI_SITE_ID || '${expected}' (?? also accepted)`;
+        // Narrow the search to the createGradialMiddleware call when present so
+        // an unrelated siteId reference elsewhere in the file can't satisfy us.
+        const callIdx = middlewareFile.content.indexOf('createGradialMiddleware(');
+        const region = callIdx >= 0 ? middlewareFile.content.slice(callIdx) : middlewareFile.content;
+        // Form (b): process.env.ACI_SITE_ID || '<default>' (or ??).
+        const envMatch = region.match(/siteId\s*:\s*process\.env\.ACI_SITE_ID\s*(?:\|\||\?\?)\s*(['"`])((?:(?!\1).)*)\1/);
+        // Form (a): bare string literal (single/double quotes or backticks).
+        const literalMatch = region.match(/siteId\s*:\s*(['"`])((?:(?!\1).)*)\1/);
+        const configured = envMatch ? envMatch[2] : literalMatch ? literalMatch[2] : null;
+        if (configured === expected) {
+            results.push(ok('middleware', label, `${rel} (${envMatch ? 'env with canonical default' : 'canonical literal'})`));
+        }
+        else if (configured !== null) {
+            results.push(fail('middleware', label, `${rel}: siteId ${envMatch ? 'default ' : ''}is '${configured}' but the canonical site id is '${expected}'; ${acceptedForms}`));
+        }
+        else {
+            results.push(fail('middleware', label, `${rel}: siteId passed to createGradialMiddleware is not an accepted form (placeholder/computed expressions, other env vars, and process.env.ACI_SITE_ID without a literal default all fail); ${acceptedForms}`));
+        }
     }
     // Check that the middleware matcher is inlined (not imported) and matches
     // the SDK's canonical value. Next.js requires config.matcher to be

package/dist/testing/conformance/preset.js

@@ -58,6 +58,7 @@ export function runConformanceChecks(options) {
         framework: options.framework,
         siteId: options.siteId,
         rootDir: options.rootDir || process.cwd(),
+        siteIdMode: options.siteIdMode || 'literal',
     };
     const checks = resolveChecks(options.checks);
     const allResults = checks.flatMap((name) => {
@@ -84,6 +85,7 @@ export function conformancePreset(options) {
             framework: options.framework,
             siteId: options.siteId,
             rootDir: options.rootDir || process.cwd(),
+            siteIdMode: options.siteIdMode || 'literal',
         };
         for (const checkName of checks) {
             await t.test(checkName, () => {

package/dist/testing/conformance/types.d.ts

@@ -16,6 +16,21 @@ export interface ConformancePresetOptions {
     siteId: string;
     /** Root directory of the site project. Defaults to process.cwd(). */
     rootDir?: string;
+    /**
+     * How the middleware is expected to obtain its siteId. Defaults to 'literal'.
+     *
+     * - 'literal': the middleware passes the canonical siteId as a string
+     *   literal (or `process.env.ACI_SITE_ID || '<canonical>'` / `??` with the
+     *   canonical literal as the default). This is what the template stamps for
+     *   single-tenant repos.
+     * - 'env': the middleware must read siteId ONLY from the environment —
+     *   exactly `siteId: process.env.ACI_SITE_ID`, with no literal default, no
+     *   `||`/`??` fallback, no other env var names, and no computed
+     *   expressions. Use this for tenant-agnostic repos deployed to multiple
+     *   sites (the platform owns tenant identity and injects ACI_SITE_ID per
+     *   deployment; a missing env produces a clean 500 at runtime).
+     */
+    siteIdMode?: 'literal' | 'env';
     /**
      * Which checks to run. Defaults to all checks.
      * Pass an array to run only those checks, or an object to enable/disable individually.
@@ -42,4 +57,6 @@ export interface ConformanceContext {
     framework: ConformanceFramework;
     siteId: string;
     rootDir: string;
+    /** See ConformancePresetOptions.siteIdMode. Defaults to 'literal'. */
+    siteIdMode?: 'literal' | 'env';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -88,14 +88,6 @@
       "import": "./dist/testing/conformance/index.js"
     }
   },
-  "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
-    "test": "node --import tsx --test \"src/**/*.test.ts\"",
-    "build:cli": "cd ../.. && ./scripts/build-cli.sh",
-    "generate-starters": "cd ../.. && tsx scripts/generate-starters.ts",
-    "compile-registry": "tsx src/cli/compile-registry.mjs",
-    "prepack": "npm run generate-starters && npm run build && node scripts/ensure-bin-modes.mjs"
-  },
   "dependencies": {
     "markdown-it": "^14.1.0",
     "sanitize-html": "^2.13.1",
@@ -135,11 +127,18 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.34",
-    "@gradial/aci-cli-darwin-x64": "0.1.34",
-    "@gradial/aci-cli-linux-arm64": "0.1.34",
-    "@gradial/aci-cli-linux-x64": "0.1.34",
-    "@gradial/aci-cli-win32-arm64": "0.1.34",
-    "@gradial/aci-cli-win32-x64": "0.1.34"
+    "@gradial/aci-cli-darwin-arm64": "0.1.36",
+    "@gradial/aci-cli-darwin-x64": "0.1.36",
+    "@gradial/aci-cli-linux-arm64": "0.1.36",
+    "@gradial/aci-cli-linux-x64": "0.1.36",
+    "@gradial/aci-cli-win32-arm64": "0.1.36",
+    "@gradial/aci-cli-win32-x64": "0.1.36"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "build:cli": "cd ../.. && ./scripts/build-cli.sh",
+    "generate-starters": "cd ../.. && tsx scripts/generate-starters.ts",
+    "compile-registry": "tsx src/cli/compile-registry.mjs"
   }
-}
+}

package/src/cli/materialize-template.mjs

@@ -1,8 +1,11 @@
-// Single assembly path for scaffolding a site from the SDK templates.
+// TS reference engine for scaffolding a site from the SDK templates.
 //
-// Both `scripts/generate-starters.ts` (repo codegen for starters/*) and
-// `aci init` (bin/aci.js, customer scaffolding from the published package)
-// call materializeTemplate so the two outputs can never drift.
+// `scripts/generate-starters.ts` (repo codegen for starters/*) calls
+// materializeTemplate, then applies the starter-content overlay as an
+// explicit stage on top. Customer scaffolding (`aci init`) is the Go CLI
+// (internal/transport/cli/cmd/init.go), which implements the same engine
+// semantics; scripts/test-starter-dev.mjs asserts the two engines produce
+// byte-identical output so they can never drift.
 // Spec: specs/features/starter-fresh-clone-dx (D-1).
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -106,12 +109,11 @@ export function materializeTemplate({ templatesDir, framework, destDir, vars })
 
   copyDirSync(templateDir, destDir);
 
-  // Shared sources overwrite any framework-template copies so contracts and
-  // design tokens can only come from templates/common.
-  copyDirSync(
-    path.join(commonDir, 'contracts', 'components'),
-    path.join(destDir, 'src', 'cms', 'contracts', 'components'),
-  );
+  // Shared design-system sources overwrite any framework-template copies so
+  // design tokens can only come from templates/common. Contract sources are
+  // NOT copied here: a scaffold ships only the empty contracts barrel from the
+  // framework template; populated contracts arrive via the starter-content
+  // overlay stage (generate-starters.ts / `aci init --with-starter-content`).
   copyDirSync(
     path.join(commonDir, 'design-system', 'tokens'),
     path.join(destDir, 'src', 'design-system', 'tokens'),