@apollion-dsi/tokens 4.0.0

package/src/cli.ts

@@ -0,0 +1,128 @@
+/**
+ * `apollion-tokens` bin entry — thin wrapper around `build` + `check`.
+ *
+ * Shebang `#!/usr/bin/env node` is added by esbuild banner config — not
+ * present in source to avoid duplication.
+ *
+ * **S6:** sandboxed `apollion.config.mjs` loader via `node:vm` + zod
+ * schema (T2+E1 threat-model mitigation). Falls back to JSON for
+ * `.json` files (test fixtures + S5 backward compat).
+ *
+ * Usage:
+ * ```sh
+ * apollion-tokens build --config apollion.config.json --out dist
+ * apollion-tokens build --check --config apollion.config.json --out dist
+ * apollion-tokens build --verbose --config apollion.config.json --out dist
+ * ```
+ *
+ * Exit codes:
+ * - 0 — success (build wrote files, or --check found no drift).
+ * - 1 — drift detected (--check), or build error.
+ * - 2 — invalid arguments.
+ *
+ * @see ADR-006 §3.5 + §3.8 B3 (loader sandbox in S6)
+ * @see PRD-002 §S5
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { build, check } from './build';
+import { loadConfig } from './config-loader';
+import type { ApollionConfig } from './config-schema';
+
+interface ParsedArgs {
+  command: 'build';
+  configPath: string;
+  outDir: string;
+  check: boolean;
+  verbose: boolean;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const args = argv.slice(2);
+  const command = args[0];
+  if (command !== 'build') {
+    fail(
+      `Unknown command "${command ?? ''}". Usage: apollion-tokens build [--check] [--verbose] --config <path> [--out <dir>]`,
+    );
+  }
+
+  let configPath = 'apollion.config.mjs';
+  let outDir = 'dist';
+  let checkMode = false;
+  let verbose = false;
+
+  for (let i = 1; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '--config':
+        configPath = args[++i] ?? fail('--config needs a path');
+        break;
+      case '--out':
+        outDir = args[++i] ?? fail('--out needs a path');
+        break;
+      case '--check':
+        checkMode = true;
+        break;
+      case '--verbose':
+        verbose = true;
+        break;
+      default:
+        fail(`Unknown flag "${a}"`);
+    }
+  }
+
+  return { command, configPath, outDir, check: checkMode, verbose };
+}
+
+function fail(message: string): never {
+  console.error(`apollion-tokens: ${message}`);
+  process.exit(2);
+}
+
+async function loadConfigFromPath(path: string): Promise<ApollionConfig> {
+  const fullPath = resolve(path);
+
+  // .json keeps S5 backward-compat (test fixtures + simple CI scenarios that
+  // don't need a JS expression). .mjs/.js go through the sandboxed loader
+  // (ADR-006 §3.8 B3 — node:vm + zod schema; threat-model T2+E1 mitigation).
+  if (fullPath.endsWith('.json')) {
+    const raw = await readFile(fullPath, 'utf8');
+    return JSON.parse(raw) as ApollionConfig;
+  }
+
+  return loadConfig({ configPath: fullPath });
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv);
+  const config = await loadConfigFromPath(args.configPath);
+
+  if (args.check) {
+    const ok = await check({ config, outDir: resolve(args.outDir) });
+    if (!ok) {
+      console.error(
+        `apollion-tokens: dist/ is stale or missing (configHash mismatch). Re-run \`apollion-tokens build\` without --check.`,
+      );
+      process.exit(1);
+    }
+    console.log(`apollion-tokens: dist/ is up-to-date with config.`);
+    return;
+  }
+
+  const { manifest } = await build({
+    config,
+    outDir: resolve(args.outDir),
+    verbose: args.verbose,
+  });
+
+  console.log(
+    `apollion-tokens: wrote ${manifest.files.length} file(s) — configHash=${manifest.configHash.slice(0, 12)}…`,
+  );
+}
+
+main().catch((err) => {
+  console.error(`apollion-tokens: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/src/config-loader.ts

@@ -0,0 +1,167 @@
+/**
+ * Sandboxed `apollion.config.mjs` loader — threat-model T2+E1 mitigation
+ * (ADR-006 §3.8 B3, §8.5 risks T2 + E1).
+ *
+ * **Contract:** load + validate + return `ApollionConfig`. The config source
+ * is treated as UNTRUSTED — even when authored by the project owner, the
+ * loader assumes the consumer build server is the attack surface (event-
+ * stream / ua-parser-js precedent: malicious config compiled via tampered
+ * dependency chain).
+ *
+ * **Sandbox guarantees:**
+ *
+ * 1. **Pre-eval static scan:** source must not contain `require(...)` or
+ *    `import(...)` dynamic calls. Static `import` statements are OK only
+ *    when the runtime exposes `defineConfig` (see consumer pattern below).
+ *    For S6 the loader rejects ANY dynamic call; static imports become
+ *    a future enhancement.
+ * 2. **`node:vm` Script + Context with allowlist globals.** Only
+ *    `console`, `Symbol`, `Number`, `String`, `Boolean`, `Array`, `Object`,
+ *    `JSON`, `Math` are exposed. NO `process`, `Buffer`, `globalThis`,
+ *    `eval`, `Function`, `require`, `import`.
+ * 3. **Timeout 1000ms.** Infinite loops in config fail-fast.
+ * 4. **Zod schema validation.** Output structure is enforced post-eval. Fails
+ *    fast with `path` + `message` per issue.
+ *
+ * **Consumer pattern (apollion.config.mjs):**
+ *
+ * ```js
+ * export default {
+ *   brands: { default: { deepDark: '#000', deepLight: '#FFF', main: '#003750' } },
+ *   modes: ['light', 'dark'],
+ *   surfaces: ['positive', 'negative'],
+ *   dimensions: ['compact', 'normal', 'spacious'],
+ *   output: { runtime: false, css: true, json: true, ts: true },
+ * };
+ * ```
+ *
+ * `defineConfig` helper not strictly required — consumer can export the
+ * literal — but recommended for autocomplete + literal-type narrowing.
+ *
+ * @see ADR-006 §3.8 B3 + §8.5 risks T2/E1
+ * @see PRD-002 §S6
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { createContext, Script } from 'node:vm';
+import { z } from 'zod';
+
+import type { ApollionConfig } from './config-schema';
+import { ApollionConfigSchema } from './config-schema-runtime';
+
+const FORBIDDEN_PATTERNS = [
+  /\brequire\s*\(/,
+  /\bimport\s*\(/,
+  // Static imports also forbidden in S6 (would require deeper resolver).
+  /^\s*import\s+/m,
+];
+
+const SANDBOX_TIMEOUT_MS = 1000;
+
+/**
+ * Helper exported so consumers get TS autocomplete + literal narrowing.
+ * Identity function at runtime; types do the work.
+ */
+export function defineConfig<T extends ApollionConfig>(config: T): T {
+  return config;
+}
+
+export interface LoadConfigOptions {
+  configPath: string;
+}
+
+export class ConfigLoadError extends Error {
+  constructor(
+    message: string,
+    public readonly configPath: string,
+  ) {
+    super(message);
+    this.name = 'ConfigLoadError';
+  }
+}
+
+/**
+ * Load + validate `apollion.config.mjs` from disk. Never throws raw — all
+ * failures wrap `ConfigLoadError` with the offending path attached.
+ */
+export async function loadConfig(opts: LoadConfigOptions): Promise<ApollionConfig> {
+  const configPath = resolve(opts.configPath);
+  const source = await readFile(configPath, 'utf8');
+
+  // Static pre-scan — refuse anything that looks like dynamic module load.
+  for (const pattern of FORBIDDEN_PATTERNS) {
+    if (pattern.test(source)) {
+      throw new ConfigLoadError(
+        `apollion.config: dynamic require/import not allowed (matched ${pattern}). Declarative config only — see ADR-006 §3.8 B3.`,
+        configPath,
+      );
+    }
+  }
+
+  // Rewrite `export default <expr>;` → assign to sandbox-visible variable.
+  // `node:vm` does NOT support ESM evaluation in Script; we transform to plain
+  // expression evaluation. This is intentionally narrow — config is data, not
+  // a module with imports.
+  const transformed = source.replace(
+    /(^|\n)\s*export\s+default\s+/,
+    (_match, leading) => `${leading}__apollion_config_export = `,
+  );
+
+  if (transformed === source) {
+    throw new ConfigLoadError(
+      `apollion.config: missing \`export default <object>;\` — config must export a default object literal.`,
+      configPath,
+    );
+  }
+
+  const sandbox: Record<string, unknown> = {
+    __apollion_config_export: undefined,
+    console: makeReadOnlyConsole(),
+    Symbol,
+    Number,
+    String,
+    Boolean,
+    Array,
+    Object,
+    JSON,
+    Math,
+    // Provide defineConfig as a sandbox-injected identity for ergonomics.
+    defineConfig: (c: unknown) => c,
+  };
+
+  const context = createContext(sandbox);
+
+  try {
+    const script = new Script(transformed, { filename: configPath });
+    script.runInContext(context, { timeout: SANDBOX_TIMEOUT_MS });
+  } catch (err) {
+    throw new ConfigLoadError(
+      `apollion.config: evaluation failed — ${err instanceof Error ? err.message : String(err)}`,
+      configPath,
+    );
+  }
+
+  const exported = sandbox.__apollion_config_export;
+  if (exported === undefined) {
+    throw new ConfigLoadError(`apollion.config: \`export default\` produced undefined.`, configPath);
+  }
+
+  const parsed = ApollionConfigSchema.safeParse(exported);
+  if (!parsed.success) {
+    const issues = parsed.error.issues
+      .map((i: z.core.$ZodIssue) => `  ${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('\n');
+    throw new ConfigLoadError(`apollion.config: schema validation failed —\n${issues}`, configPath);
+  }
+
+  return parsed.data as ApollionConfig;
+}
+
+function makeReadOnlyConsole(): Pick<Console, 'log' | 'warn' | 'error'> {
+  return {
+    log: (...args: unknown[]) => console.log('[apollion.config]', ...args),
+    warn: (...args: unknown[]) => console.warn('[apollion.config]', ...args),
+    error: (...args: unknown[]) => console.error('[apollion.config]', ...args),
+  };
+}

package/src/config-schema-runtime.ts

@@ -0,0 +1,64 @@
+/**
+ * Runtime zod schema for `ApollionConfig` (S6 — pairs with config-schema.ts TS types).
+ *
+ * Used by `config-loader.ts` to validate `apollion.config.mjs` AFTER vm
+ * evaluation. Schema failure → loader throws with `path` + `message` per
+ * issue (zod's flatten output) BEFORE any build runs.
+ *
+ * **Validation surface (intentional, opinionated):**
+ * - `brands`: Record<string, ColorsInput> — at least 1 entry; each ColorsInput
+ *   requires `deepDark` + `deepLight` (used by mixOklch).
+ * - `modes`, `surfaces`, `dimensions`: optional arrays; if provided, each entry
+ *   matches one of the literal sets.
+ * - `output`: optional flags object; unknown keys allowed (forward-compat).
+ *
+ * @see ./config-schema.ts (TypeScript types — single SSOT of shape)
+ * @see ./config-loader.ts (runtime use)
+ * @see ADR-006 §3.8 B3
+ */
+
+import { z } from 'zod';
+
+const HexColor = z.string().regex(/^#([0-9a-fA-F]{3}){1,2}$|^transparent$|^rgb\(.*\)$|^oklch\(.*\)$/, {
+  message: 'Must be hex, rgb(), oklch(), or "transparent"',
+});
+
+const ColorsInputSchema = z
+  .object({
+    baseDark: z.string().optional(),
+    baseLight: z.string().optional(),
+    deepDark: HexColor,
+    deepLight: HexColor,
+    transparent: z.string().optional(),
+    main: HexColor.optional(),
+    opposite: HexColor.optional(),
+    complementary: HexColor.optional(),
+    information: HexColor.optional(),
+    success: HexColor.optional(),
+    danger: HexColor.optional(),
+    warning: HexColor.optional(),
+    primary: HexColor.optional(),
+    secondary: HexColor.optional(),
+    tertiary: HexColor.optional(),
+  })
+  .passthrough();
+
+export const ApollionConfigSchema = z
+  .object({
+    brands: z.record(z.string(), ColorsInputSchema).refine((b) => Object.keys(b).length > 0, {
+      message: 'apollion.config.mjs: brands must contain at least 1 entry',
+    }),
+    modes: z.array(z.enum(['light', 'dark'])).optional(),
+    surfaces: z.array(z.enum(['positive', 'negative'])).optional(),
+    dimensions: z.array(z.enum(['compact', 'normal', 'spacious'])).optional(),
+    output: z
+      .object({
+        runtime: z.boolean().optional(),
+        css: z.boolean().optional(),
+        json: z.boolean().optional(),
+        ts: z.boolean().optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();

package/src/config-schema.ts

@@ -0,0 +1,110 @@
+/**
+ * `apollion.config.mjs` shape — public contract for v4 token generation.
+ *
+ * **S5 (this file):** TypeScript-only schema definitions consumed by the
+ * `apollion-tokens build` CLI. Static validation comes from `.d.ts` types
+ * at consumer's tsserver/Vitest/etc.
+ *
+ * **S6 (later):** Runtime validation via zod + sandboxed `node:vm` loader
+ * (mitigation threat-model T2+E1). For now the CLI accepts a config object
+ * directly (programmatic API) or via `--config <path>` (CommonJS require).
+ *
+ * @see ADR-006 §3.4 (feature-flagged output) + §3.8 B3 (sandboxed loader, S6)
+ * @see PRD-002 §S5 + §S6
+ */
+
+import type { ColorsInput } from '@apollion-dsi/core/themes/colors';
+import type { Dimension } from '@apollion-dsi/core/themes/dimension';
+
+export type Mode = 'light' | 'dark';
+export type Surface = 'positive' | 'negative';
+
+/**
+ * Output toggles — Strangler Fig (ADR-006 §3.1): E3+E4 opt-in via these flags.
+ *
+ * - `runtime: true` ships `dist/runtime/v1.{esm,cjs,d.ts}` and triggers
+ *   `core` to dynamic-import tokens at theme load time.
+ * - `css|json|ts: true` ships static dist/{css,json,ts}/*.{css,json,d.ts}.
+ *   These are framework-agnostic outputs consumed by Vue/Flutter/Tailwind/etc.
+ *
+ * Default all false: consumer that doesn't opt in receives zero dist files
+ * (only the `@apollion-dsi/tokens` package itself, used by core's optional
+ * dynamic import path).
+ */
+export interface ApollionOutputFlags {
+  runtime?: boolean;
+  css?: boolean;
+  json?: boolean;
+  ts?: boolean;
+}
+
+export interface ApollionConfig {
+  /**
+   * Brand registry. Each entry derives a full palette via `mountSingleColor`
+   * (OKLch lerp, ADR-006 E1).
+   *
+   * @example
+   * ```ts
+   * brands: {
+   *   default: { main: '#003750', complementary: '#F6BA20', ... },
+   *   enterprise: { main: '#1A1A1A', complementary: '#FFD700', ... },
+   * }
+   * ```
+   */
+  brands: Record<string, ColorsInput>;
+
+  modes?: Mode[];
+  surfaces?: Surface[];
+  dimensions?: Dimension[];
+  output?: ApollionOutputFlags;
+}
+
+/**
+ * Resolved variant = one cartesian cell of (brand × mode × surface × dimension).
+ * Each variant produces ≤ 3 output files (css, json, ts) — depending on flags.
+ */
+export interface Variant {
+  brand: string;
+  colors: ColorsInput;
+  mode: Mode;
+  surface: Surface;
+  dimension: Dimension;
+}
+
+const DEFAULT_MODES: readonly Mode[] = ['light', 'dark'];
+const DEFAULT_SURFACES: readonly Surface[] = ['positive', 'negative'];
+const DEFAULT_DIMENSIONS: readonly Dimension[] = ['compact', 'normal', 'spacious'];
+
+/**
+ * Expand config to all (brand × mode × surface × dimension) tuples.
+ * Deterministic ordering (alphabetical → declaration → declaration → declaration)
+ * — required for idempotent build (PRD-002 §S5 byte-identical rerun).
+ */
+export function expandVariants(config: ApollionConfig): Variant[] {
+  const modes = config.modes ?? DEFAULT_MODES;
+  const surfaces = config.surfaces ?? DEFAULT_SURFACES;
+  const dimensions = config.dimensions ?? DEFAULT_DIMENSIONS;
+
+  // Sort brands alphabetically for deterministic output ordering.
+  const brandEntries = Object.entries(config.brands).sort(([a], [b]) => a.localeCompare(b));
+
+  const out: Variant[] = [];
+  for (const [brand, colors] of brandEntries) {
+    for (const mode of modes) {
+      for (const surface of surfaces) {
+        for (const dimension of dimensions) {
+          out.push({ brand, colors, mode, surface, dimension });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Stable variant filename (sem extension).
+ * Format: `<brand>.<mode>.<surface>.<dimension>` — kebab where needed.
+ */
+export function variantName(v: Variant): string {
+  return `${v.brand}.${v.mode}.${v.surface}.${v.dimension}`;
+}

package/src/manifest.ts

@@ -0,0 +1,103 @@
+/**
+ * Build manifest — sha256 audit trail for `apollion-tokens build` output.
+ *
+ * **Determinism contract (PRD-002 §S5 acceptance):** the manifest must be
+ * byte-identical across consecutive runs given the same config + git HEAD
+ * + node version. No timestamps, no run-id. configHash is the SSOT of
+ * "what was built"; gitCommit + buildEnv are audit fingerprints.
+ *
+ * **Threat-model fields (ADR-006 §3.9):** `gitCommit` and `buildEnv` give
+ * provenance without requiring CI/SLSA-3 (decision Q-G9 — single-user org,
+ * sem CI). `signedBy` slot reserved for sigstore in future PRD-003.
+ *
+ * @see ADR-006 §3.9 + §8.5 risk T1/R2
+ * @see PRD-002 §S5
+ */
+
+import { createHash } from 'node:crypto';
+
+import type { ApollionConfig } from './config-schema';
+
+export interface ManifestFileEntry {
+  path: string;
+  sha256: string;
+}
+
+export interface BuildManifest {
+  /** sha256 of JSON.stringify(config) — proves "what was the input". */
+  configHash: string;
+  /** Sorted alphabetically for deterministic output. */
+  files: ManifestFileEntry[];
+  /** git HEAD short SHA at build time (empty if not in a git repo). */
+  gitCommit: string;
+  buildEnv: {
+    node: string;
+    platform: string;
+  };
+}
+
+export function sha256(content: string | Buffer): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export function hashConfig(config: ApollionConfig): string {
+  // JSON.stringify with sorted keys for determinism.
+  return sha256(stableStringify(config));
+}
+
+/**
+ * Deterministic JSON stringify with sorted object keys.
+ * `JSON.stringify` preserves insertion order — different consumer code
+ * paths could produce same logical config with different key order →
+ * different hash. This normalizes.
+ */
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  const keys = Object.keys(value as Record<string, unknown>).sort();
+  const entries = keys.map((k) => `${JSON.stringify(k)}:${stableStringify((value as Record<string, unknown>)[k])}`);
+  return `{${entries.join(',')}}`;
+}
+
+/**
+ * Resolve git HEAD short SHA. Returns empty string if not in a git repo
+ * or git unavailable — never throws (build should succeed outside git).
+ */
+export function detectGitCommit(cwd: string): string {
+  try {
+    // Avoid spawning child_process if .git/HEAD readable directly.
+
+    const { execSync } = require('node:child_process');
+    const out = execSync('git rev-parse --short HEAD', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+    }) as string;
+    return out.trim();
+  } catch {
+    return '';
+  }
+}
+
+export function buildEnv(): BuildManifest['buildEnv'] {
+  return {
+    node: process.version,
+    platform: `${process.platform}-${process.arch}`,
+  };
+}
+
+export function serializeManifest(manifest: BuildManifest): string {
+  // Files sorted alphabetically; trailing newline omitted for byte stability.
+  const sortedFiles = [...manifest.files].sort((a, b) => a.path.localeCompare(b.path));
+  const ordered: BuildManifest = {
+    configHash: manifest.configHash,
+    files: sortedFiles,
+    gitCommit: manifest.gitCommit,
+    buildEnv: manifest.buildEnv,
+  };
+  return `${JSON.stringify(ordered, null, 2)}\n`;
+}

package/src/renderers/css.ts

@@ -0,0 +1,65 @@
+/**
+ * CSS renderer — emit Foundation tokens as CSS custom properties.
+ *
+ * Format: `--apollion-{layer}-{role}-{variant}` per ADR-006 §3.3.
+ *
+ * **tech-radar R3:** also emits `@property` declarations for typed tokens
+ * (color/length) — enables native CSS transitions (View Transitions API
+ * friendly). `@property` is browser-supported 84%+ mid-2024; wrapped in
+ * `@supports` for graceful degradation.
+ *
+ * Output is deterministic: keys iterated in insertion order from the
+ * FoundationLayer object; no timestamps, no run-id.
+ *
+ * @see ADR-006 §3.3 + §3.10 + tech-radar R3
+ * @see PRD-002 §S5
+ */
+
+import type { FoundationLayer } from '@apollion-dsi/core/themes/foundation';
+
+import type { Variant } from '../config-schema';
+
+const HEADER_LINE = '/* Generated by apollion-tokens build — DO NOT EDIT. See apollion.config.mjs. */';
+
+export function renderCss(foundation: FoundationLayer, variant: Variant): string {
+  const lines: string[] = [HEADER_LINE, ''];
+
+  // Variant marker as a comment (NOT a var — keep cascade clean).
+  lines.push(
+    `/* Variant: brand=${variant.brand} mode=${variant.mode} surface=${variant.surface} dimension=${variant.dimension} */`,
+    '',
+    ':root {',
+  );
+
+  // bg layer
+  for (const [key, value] of Object.entries(foundation.bg)) {
+    lines.push(`  --apollion-bg-${key}: ${value};`);
+  }
+
+  // text layer
+  for (const [key, value] of Object.entries(foundation.text)) {
+    const kebab = key.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+    lines.push(`  --apollion-text-${kebab}: ${value};`);
+  }
+
+  // spacing layer
+  for (const [key, value] of Object.entries(foundation.spacing)) {
+    lines.push(`  --apollion-spacing-${key}: ${value};`);
+  }
+
+  lines.push('}', '');
+
+  // @property declarations for color tokens — opt-in via @supports
+  lines.push('@supports (background: paint(squircle)) or (color: oklch(0% 0 0)) {');
+  for (const [key, value] of Object.entries(foundation.bg)) {
+    lines.push(`  @property --apollion-bg-${key} { syntax: '<color>'; inherits: true; initial-value: ${value}; }`);
+  }
+  for (const key of Object.keys(foundation.text)) {
+    const kebab = key.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+    const value = (foundation.text as unknown as Record<string, string>)[key];
+    lines.push(`  @property --apollion-text-${kebab} { syntax: '<color>'; inherits: true; initial-value: ${value}; }`);
+  }
+  lines.push('}', '');
+
+  return lines.join('\n');
+}