@open-agent-toolkit/cli 0.2.5 → 0.2.7

package/assets/skills/explainer-kit/scripts/lib/theme.mjs

@@ -0,0 +1,332 @@
+import { readFile } from 'node:fs/promises';
+
+import { canonicalHash, validateContract } from './contracts.mjs';
+
+const PALETTE_NAMES = new Set([
+  'neutral',
+  'ocean',
+  'ember',
+  'forest',
+  'violet',
+]);
+const PROFILE_NAMES = new Set(['clean', 'editorial', 'technical']);
+const RENDER_STRATEGIES = new Set(['default-only', 'user-switchable']);
+const DEFAULT_MODES = new Set(['light', 'dark']);
+const MODE_ROLES = ['surface', 'ink', 'accent', 'status', 'diagramSeries'];
+
+export async function resolveTheme(selection = {}) {
+  assertSelection(selection);
+
+  const renderStrategy = selection.renderStrategy ?? 'default-only';
+  const warnings = [];
+  let theme;
+
+  if (selection.suppliedBundlePath !== undefined) {
+    theme = await resolveSuppliedBundle(selection.suppliedBundlePath);
+    if (
+      ['palette', 'visualProfile', 'artDirection', 'defaultMode'].some(
+        (key) => selection[key] !== undefined,
+      )
+    ) {
+      warnings.push(
+        'Supplied bundle wins over palette, visual profile, art direction, and default mode selections.',
+      );
+    }
+  } else {
+    theme = await resolveNamedTheme(selection);
+  }
+
+  assertResolvedTheme(theme);
+  return {
+    theme,
+    renderStrategy,
+    presentationModes:
+      renderStrategy === 'user-switchable'
+        ? [theme.defaultMode, oppositeMode(theme.defaultMode)]
+        : [theme.defaultMode],
+    warnings,
+  };
+}
+
+async function resolveNamedTheme(selection) {
+  const paletteName = selection.palette ?? 'neutral';
+  const profileName = selection.visualProfile ?? 'clean';
+  assertNamedSelection(paletteName, PALETTE_NAMES, 'palette');
+  assertNamedSelection(profileName, PROFILE_NAMES, 'visual profile');
+
+  const [palette, profile] = await Promise.all([
+    loadBundledJson('palettes', paletteName),
+    loadBundledJson('profiles', profileName),
+  ]);
+  assertPalette(palette, paletteName);
+  assertProfile(profile, profileName);
+
+  const theme = {
+    schemaVersion: 'explainer-kit.theme/v1',
+    name: `${paletteName}-${profileName}`,
+    defaultMode: selection.defaultMode ?? 'light',
+    modes: structuredClone(palette.modes),
+    provenance: {
+      palette: paletteName,
+      visualProfile: profileName,
+      derived: false,
+    },
+    typography: structuredClone(profile.typography),
+    spacing: structuredClone(profile.spacing),
+    geometry: structuredClone(profile.geometry),
+    elevation: structuredClone(profile.elevation),
+    density: profile.density,
+    motion: structuredClone(profile.motion),
+    diagrams: structuredClone(profile.diagrams),
+  };
+
+  if (selection.artDirection !== undefined) {
+    applyArtDirection(theme, selection.artDirection);
+  }
+  theme.bundleHash = canonicalHash(theme);
+  return theme;
+}
+
+async function resolveSuppliedBundle(suppliedBundlePath) {
+  if (
+    typeof suppliedBundlePath !== 'string' ||
+    suppliedBundlePath.length === 0
+  ) {
+    throw new TypeError('Supplied bundle path must be a non-empty string.');
+  }
+
+  let source;
+  try {
+    source = JSON.parse(await readFile(suppliedBundlePath, 'utf8'));
+  } catch (error) {
+    throw new Error('Unable to read the supplied theme bundle.', {
+      cause: error,
+    });
+  }
+
+  assertResolvedTheme(source);
+  const theme = structuredClone(source);
+  theme.provenance.suppliedBundleHash = canonicalHash(source);
+  theme.bundleHash = canonicalHash(withoutBundleHash(theme));
+  return theme;
+}
+
+function applyArtDirection(theme, instruction) {
+  if (typeof instruction !== 'string' || instruction.trim().length === 0) {
+    throw new TypeError('Art direction must be a non-empty string.');
+  }
+
+  const instructionHash = canonicalHash(instruction.normalize('NFKC').trim());
+  const variant = Number.parseInt(instructionHash.slice(-2), 16) % 3;
+  const spacingFactor = [0.9, 1.05, 1.15][variant];
+  const radiusFactor = [0.8, 1.1, 1.25][variant];
+
+  theme.name = `${theme.name}-derived`;
+  theme.provenance.derived = true;
+  theme.provenance.instructionHash = instructionHash;
+  theme.spacing.unit = round(theme.spacing.unit * spacingFactor);
+  theme.spacing.scale = mapNumbers(theme.spacing.scale, spacingFactor);
+  theme.geometry.radius = mapNumbers(theme.geometry.radius, radiusFactor);
+  theme.diagrams.nodeGap = round(theme.diagrams.nodeGap * spacingFactor);
+}
+
+function assertSelection(selection) {
+  if (!isObject(selection)) {
+    throw new TypeError('Theme selection must be an object.');
+  }
+  const allowed = new Set([
+    'palette',
+    'visualProfile',
+    'suppliedBundlePath',
+    'artDirection',
+    'defaultMode',
+    'renderStrategy',
+  ]);
+  const unknown = Object.keys(selection).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) {
+    throw new Error(`Unknown theme selection field: ${unknown[0]}.`);
+  }
+  if (
+    selection.renderStrategy !== undefined &&
+    !RENDER_STRATEGIES.has(selection.renderStrategy)
+  ) {
+    throw new Error('Unsupported theme render strategy.');
+  }
+  if (
+    selection.defaultMode !== undefined &&
+    !DEFAULT_MODES.has(selection.defaultMode)
+  ) {
+    throw new Error('Unsupported theme default mode.');
+  }
+}
+
+function assertNamedSelection(value, allowed, label) {
+  if (typeof value !== 'string' || !allowed.has(value)) {
+    throw new Error(`Unknown ${label}: ${String(value)}.`);
+  }
+}
+
+async function loadBundledJson(directory, name) {
+  return JSON.parse(
+    await readFile(
+      new URL(`../../${directory}/${name}.json`, import.meta.url),
+      'utf8',
+    ),
+  );
+}
+
+function assertPalette(palette, expectedName) {
+  if (
+    !isObject(palette) ||
+    palette.name !== expectedName ||
+    !hasExactKeys(palette, ['name', 'modes']) ||
+    !isObject(palette.modes) ||
+    !hasExactKeys(palette.modes, ['light', 'dark'])
+  ) {
+    throw new Error(`Bundled palette ${expectedName} has an invalid shape.`);
+  }
+  for (const mode of Object.values(palette.modes)) {
+    assertMode(mode);
+  }
+}
+
+function assertMode(mode) {
+  if (!isObject(mode) || !hasExactKeys(mode, MODE_ROLES)) {
+    throw new Error('Theme mode must contain the closed semantic color roles.');
+  }
+  assertExactColorObject(mode.surface, ['canvas', 'panel', 'elevated']);
+  assertExactColorObject(mode.ink, ['primary', 'muted', 'inverse']);
+  assertExactColorObject(mode.accent, ['primary', 'secondary']);
+  assertExactColorObject(mode.status, ['success', 'warning', 'danger', 'info']);
+  if (
+    !Array.isArray(mode.diagramSeries) ||
+    mode.diagramSeries.length === 0 ||
+    mode.diagramSeries.some((color) => !isNormalizedColor(color)) ||
+    new Set(mode.diagramSeries).size !== mode.diagramSeries.length
+  ) {
+    throw new Error(
+      'Theme diagram series must contain unique normalized colors.',
+    );
+  }
+  assertAaPairs(mode);
+}
+
+function assertProfile(profile, expectedName) {
+  const expectedKeys = [
+    'name',
+    'typography',
+    'spacing',
+    'geometry',
+    'elevation',
+    'density',
+    'motion',
+    'diagrams',
+  ];
+  if (
+    !isObject(profile) ||
+    profile.name !== expectedName ||
+    !hasExactKeys(profile, expectedKeys)
+  ) {
+    throw new Error(
+      `Bundled visual profile ${expectedName} has an invalid shape.`,
+    );
+  }
+}
+
+function assertResolvedTheme(theme) {
+  const result = validateContract('theme', theme);
+  if (!result.valid) {
+    throw new Error(
+      `Invalid resolved theme: ${result.errors
+        .map(({ path, message }) => `${path}: ${message}`)
+        .join('; ')}`,
+    );
+  }
+  if (theme.bundleHash !== canonicalHash(withoutBundleHash(theme))) {
+    throw new Error(
+      'Resolved theme bundleHash does not match canonical content.',
+    );
+  }
+  for (const mode of Object.values(theme.modes)) {
+    assertMode(mode);
+  }
+}
+
+function assertExactColorObject(value, keys) {
+  if (
+    !isObject(value) ||
+    !hasExactKeys(value, keys) ||
+    Object.values(value).some((color) => !isNormalizedColor(color))
+  ) {
+    throw new Error('Theme color role is incomplete or invalid.');
+  }
+}
+
+function assertAaPairs(mode) {
+  for (const surface of Object.values(mode.surface)) {
+    assertContrast(mode.ink.primary, surface);
+    assertContrast(mode.ink.muted, surface);
+  }
+  for (const background of [
+    ...Object.values(mode.accent),
+    ...Object.values(mode.status),
+  ]) {
+    assertContrast(mode.ink.inverse, background);
+  }
+}
+
+function assertContrast(foreground, background) {
+  const lighter = Math.max(luminance(foreground), luminance(background));
+  const darker = Math.min(luminance(foreground), luminance(background));
+  if ((lighter + 0.05) / (darker + 0.05) < 4.5) {
+    throw new Error(
+      'Theme text/background pair does not meet WCAG AA contrast.',
+    );
+  }
+}
+
+function luminance(hex) {
+  const channels = hex
+    .slice(1)
+    .match(/.{2}/g)
+    .map((value) => Number.parseInt(value, 16) / 255)
+    .map((value) =>
+      value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4,
+    );
+  return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2];
+}
+
+function withoutBundleHash(theme) {
+  const identity = structuredClone(theme);
+  delete identity.bundleHash;
+  return identity;
+}
+
+function mapNumbers(values, factor) {
+  return Object.fromEntries(
+    Object.entries(values).map(([key, value]) => [key, round(value * factor)]),
+  );
+}
+
+function round(value) {
+  return Math.round(value * 100) / 100;
+}
+
+function oppositeMode(mode) {
+  return mode === 'light' ? 'dark' : 'light';
+}
+
+function hasExactKeys(value, keys) {
+  return (
+    Object.keys(value).length === keys.length &&
+    keys.every((key) => Object.hasOwn(value, key))
+  );
+}
+
+function isNormalizedColor(value) {
+  return typeof value === 'string' && /^#[0-9a-f]{6}$/.test(value);
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/assets/skills/explainer-kit/scripts/publish.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+
+import { publishS3Static } from './lib/s3-static.mjs';
+
+export async function runPublishCli(argv, dependencies = {}) {
+  const log = dependencies.log ?? console.log;
+  try {
+    const options = parseArguments(argv);
+    if (!options.confirmPublish) {
+      throw Object.assign(
+        new Error(
+          'Publishing requires --confirm-publish after human approval.',
+        ),
+        { code: 'E_PUBLISH_APPROVAL' },
+      );
+    }
+    const request = JSON.parse(await readFile(options.request, 'utf8'));
+    const receipt = await publishS3Static(request, {
+      approved: true,
+      receiptPath: options.receipt,
+      ...dependencies.connector,
+    });
+    log(JSON.stringify({ ok: true, receiptPath: options.receipt, receipt }));
+    return 0;
+  } catch (caught) {
+    log(
+      JSON.stringify({
+        ok: false,
+        error: {
+          code: caught?.code ?? 'E_PUBLISH',
+          message: caught instanceof Error ? caught.message : String(caught),
+        },
+      }),
+    );
+    return 1;
+  }
+}
+
+function parseArguments(argv) {
+  const options = {
+    request: null,
+    receipt: null,
+    confirmPublish: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--confirm-publish') {
+      options.confirmPublish = true;
+      continue;
+    }
+    if (argument === '--request' || argument === '--receipt') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`${argument} requires a path.`);
+      }
+      options[argument.slice(2)] = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${argument}`);
+  }
+  if (!options.request || !options.receipt) {
+    throw new Error('--request and --receipt are required.');
+  }
+  return options;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  process.exitCode = await runPublishCli(process.argv.slice(2));
+}

package/assets/skills/explainer-kit/scripts/record-durability.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+
+import { recordDurability } from './lib/durability.mjs';
+
+export async function runRecordDurabilityCli(
+  argv = process.argv.slice(2),
+  io = console,
+) {
+  const [requestPath] = argv;
+  if (!requestPath || argv.length !== 1) {
+    io.log(
+      JSON.stringify(
+        {
+          durable: false,
+          outcome: 'built-not-durable',
+          errors: [
+            {
+              code: 'usage',
+              message: 'Usage: record-durability.mjs <request-json-path>',
+            },
+          ],
+        },
+        null,
+        2,
+      ),
+    );
+    return 1;
+  }
+
+  try {
+    const request = JSON.parse(await readFile(requestPath, 'utf8'));
+    const result = await recordDurability(request);
+    io.log(JSON.stringify(result, null, 2));
+    return result.durable ? 0 : 1;
+  } catch (error) {
+    io.log(
+      JSON.stringify(
+        {
+          durable: false,
+          outcome: 'built-not-durable',
+          errors: [
+            {
+              code: 'input',
+              message: error instanceof Error ? error.message : String(error),
+            },
+          ],
+        },
+        null,
+        2,
+      ),
+    );
+    return 1;
+  }
+}
+
+if (
+  process.argv[1] &&
+  pathToFileURL(process.argv[1]).href === import.meta.url
+) {
+  process.exitCode = await runRecordDurabilityCli();
+}