@open-agent-toolkit/cli 0.2.5 → 0.2.7

package/assets/skills/oat-explainer-kit/scripts/resolve-config.mjs

@@ -0,0 +1,293 @@
+import { execFile } from 'node:child_process';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { resolveSourceAwarePath } from './resolve-paths.mjs';
+
+const execFileAsync = promisify(execFile);
+
+export const EXPLAINER_CONFIG_KEYS = Object.freeze([
+  'explainers.defaults.palette',
+  'explainers.defaults.visualProfile',
+  'explainers.defaults.themeBundlePath',
+  'explainers.publish.provider',
+  'explainers.publish.s3Uri',
+  'explainers.publish.publicBaseUrl',
+  'explainers.publish.awsRegion',
+  'explainers.publish.awsProfile',
+  'workflow.explainers.projectExplainer',
+  'workflow.explainers.projectRecap',
+]);
+
+const CONFIG_KEY_SET = new Set(EXPLAINER_CONFIG_KEYS);
+const SOURCES = new Set(['local', 'shared', 'user', 'env', 'default']);
+const PREFERENCES = new Set(['always', 'ask', 'never']);
+
+export async function resolveExplainerConfig({
+  repoRoot,
+  runtimeOverrides = {},
+  getConfig = (key) => getConfigFromCli(repoRoot, key),
+}) {
+  validateRuntimeOverrides(runtimeOverrides);
+
+  const entries = await Promise.all(
+    EXPLAINER_CONFIG_KEYS.map(async (key) => {
+      const response = await getConfig(key);
+      validateConfigResponse(key, response);
+      return [key, response];
+    }),
+  );
+
+  const values = {};
+  const sources = {};
+  for (const [key, response] of entries) {
+    values[key] = response.value;
+    sources[key] = response.source;
+  }
+  for (const [key, value] of Object.entries(runtimeOverrides)) {
+    values[key] = normalizeRuntimeValue(key, value);
+    sources[key] = 'runtime';
+  }
+
+  const warnings = [];
+  const theme = {};
+  const bundlePath = nullableString(
+    values['explainers.defaults.themeBundlePath'],
+  );
+  if (bundlePath) {
+    theme.suppliedBundlePath = await resolveSourceAwarePath({
+      repoRoot,
+      candidate: bundlePath,
+      source: sources['explainers.defaults.themeBundlePath'],
+      field: 'explainers.defaults.themeBundlePath',
+    });
+    if (
+      nullableString(values['explainers.defaults.palette']) ||
+      nullableString(values['explainers.defaults.visualProfile'])
+    ) {
+      warnings.push(
+        'explainers.defaults.themeBundlePath overrides configured palette and visual profile.',
+      );
+    }
+  } else {
+    theme.palette =
+      nullableString(values['explainers.defaults.palette']) ?? 'neutral';
+    theme.visualProfile =
+      nullableString(values['explainers.defaults.visualProfile']) ?? 'clean';
+  }
+
+  const publish = resolvePublish(values);
+  const preferences = {
+    projectExplainer: resolvePreference(
+      'workflow.explainers.projectExplainer',
+      values['workflow.explainers.projectExplainer'],
+    ),
+    projectRecap: resolvePreference(
+      'workflow.explainers.projectRecap',
+      values['workflow.explainers.projectRecap'],
+    ),
+  };
+
+  return { values, sources, theme, publish, preferences, warnings };
+}
+
+export function toExplainerRunRequest({
+  resolvedConfig,
+  recipe,
+  slug,
+  outputRoot,
+  factBase,
+  mode,
+  durabilityStrategy = 'none',
+  artDirection,
+  defaultMode,
+  renderStrategy,
+  retainRawArtDirection = false,
+}) {
+  if (!resolvedConfig || !outputRoot || !factBase) {
+    throw new TypeError(
+      'resolvedConfig, outputRoot, and factBase are required to build a run request.',
+    );
+  }
+  if (retainRawArtDirection && !nullableString(artDirection)) {
+    throw new Error(
+      'retainRawArtDirection requires a non-empty artDirection runtime input.',
+    );
+  }
+
+  const theme = {
+    ...resolvedConfig.theme,
+    ...(nullableString(artDirection)
+      ? { artDirection: artDirection.trim() }
+      : {}),
+    ...(defaultMode ? { defaultMode } : {}),
+    ...(renderStrategy ? { renderStrategy } : {}),
+  };
+  const durability = { strategy: durabilityStrategy };
+  if (durabilityStrategy === 'publish') {
+    if (!resolvedConfig.publish) {
+      throw new Error(
+        'Publish durability requires a complete explainer publish configuration.',
+      );
+    }
+    durability.publish = {
+      schemaVersion: 'explainer-kit.publish-request/v1',
+      ...resolvedConfig.publish,
+      siteRoot: join(outputRoot, slug, 'site'),
+      manifestPath: join(outputRoot, slug, 'manifest.json'),
+    };
+  }
+
+  return {
+    schemaVersion: 'explainer-kit.run-request/v1',
+    recipe: { id: recipe, version: '1' },
+    slug,
+    outputRoot,
+    factBase,
+    ...(Object.keys(theme).length > 0 ? { theme } : {}),
+    durability,
+    privacy: { retainRawArtDirection },
+    mode,
+  };
+}
+
+async function getConfigFromCli(repoRoot, key) {
+  let stdout;
+  try {
+    ({ stdout } = await execFileAsync('oat', ['config', 'get', key, '--json'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    }));
+  } catch (error) {
+    const detail =
+      error && typeof error === 'object' && typeof error.stderr === 'string'
+        ? error.stderr.trim()
+        : '';
+    throw new Error(
+      `Failed to resolve ${key} with \`oat config get ${key} --json\`${detail ? `: ${detail}` : '.'}`,
+      { cause: error },
+    );
+  }
+
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    throw new Error(`oat config get returned invalid JSON for ${key}.`);
+  }
+}
+
+function validateConfigResponse(key, response) {
+  if (
+    !response ||
+    typeof response !== 'object' ||
+    response.status !== 'ok' ||
+    response.key !== key ||
+    !SOURCES.has(response.source)
+  ) {
+    throw new Error(
+      `Invalid oat config get --json response for ${key}; expected value and source metadata.`,
+    );
+  }
+}
+
+function validateRuntimeOverrides(overrides) {
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    throw new TypeError('runtimeOverrides must be an object.');
+  }
+  for (const key of Object.keys(overrides)) {
+    if (!CONFIG_KEY_SET.has(key)) {
+      throw new Error(`Unsupported runtime override: ${key}`);
+    }
+  }
+}
+
+function normalizeRuntimeValue(key, value) {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(
+      `Runtime override ${key} must be a non-empty string or null.`,
+    );
+  }
+  const normalized = value.trim();
+  if (key === 'explainers.publish.provider' && normalized !== 's3-static') {
+    throw new Error(`${key} runtime override must be s3-static.`);
+  }
+  if (key.startsWith('workflow.explainers.') && !PREFERENCES.has(normalized)) {
+    throw new Error(`${key} runtime override must be always, ask, or never.`);
+  }
+  if (
+    key === 'explainers.publish.s3Uri' &&
+    !/^s3:\/\/[^/\s]+(?:\/.*)?$/.test(normalized)
+  ) {
+    throw new Error(`${key} runtime override must be an s3:// URI.`);
+  }
+  if (
+    key === 'explainers.publish.publicBaseUrl' &&
+    !/^https:\/\/[^\s]+$/.test(normalized)
+  ) {
+    throw new Error(`${key} runtime override must be an https:// URL.`);
+  }
+  if (
+    key === 'explainers.publish.s3Uri' ||
+    key === 'explainers.publish.publicBaseUrl'
+  ) {
+    return normalized.replace(/\/+$/, '');
+  }
+  return normalized;
+}
+
+function resolvePublish(values) {
+  const provider = nullableString(values['explainers.publish.provider']);
+  if (!provider) {
+    return null;
+  }
+  if (provider !== 's3-static') {
+    throw new Error(`Unsupported explainer publish provider: ${provider}`);
+  }
+
+  const fields = {
+    s3Uri: nullableString(values['explainers.publish.s3Uri']),
+    publicBaseUrl: nullableString(values['explainers.publish.publicBaseUrl']),
+    awsRegion: nullableString(values['explainers.publish.awsRegion']),
+  };
+  const missing = Object.entries(fields)
+    .filter(([, value]) => !value)
+    .map(([key]) => key);
+  if (missing.length > 0) {
+    throw new Error(
+      `Incomplete explainer publish configuration; missing ${missing.join(', ')}.`,
+    );
+  }
+  if (!/^s3:\/\/[^/\s]+(?:\/.*)?$/.test(fields.s3Uri)) {
+    throw new Error('explainers.publish.s3Uri must be a valid s3:// URI.');
+  }
+  if (!/^https:\/\/[^\s]+$/.test(fields.publicBaseUrl)) {
+    throw new Error(
+      'explainers.publish.publicBaseUrl must be a valid https:// URL.',
+    );
+  }
+
+  const awsProfile = nullableString(values['explainers.publish.awsProfile']);
+  return {
+    provider,
+    s3Uri: fields.s3Uri.replace(/\/+$/, ''),
+    publicBaseUrl: fields.publicBaseUrl.replace(/\/+$/, ''),
+    awsRegion: fields.awsRegion,
+    ...(awsProfile ? { awsProfile } : {}),
+  };
+}
+
+function resolvePreference(key, value) {
+  const preference = nullableString(value) ?? 'ask';
+  if (!PREFERENCES.has(preference)) {
+    throw new Error(`${key} must be always, ask, or never.`);
+  }
+  return preference;
+}
+
+function nullableString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}

package/assets/skills/oat-explainer-kit/scripts/resolve-intent.mjs

@@ -0,0 +1,209 @@
+const PRODUCTS = new Set(['projectExplainer', 'projectRecap']);
+const MODES = new Set(['interactive', 'autonomous']);
+const PREFERENCES = new Set(['always', 'ask', 'never']);
+const DECISIONS = new Set(['generate', 'skip']);
+const SOURCES = new Set(['interactive', 'kickoff_prompt', 'autonomous_policy']);
+const ALLOWED_PAIRS = Object.freeze({
+  projectExplainer: new Set([
+    'generate:interactive',
+    'skip:interactive',
+    'generate:kickoff_prompt',
+  ]),
+  projectRecap: new Set([
+    'generate:interactive',
+    'skip:interactive',
+    'generate:autonomous_policy',
+  ]),
+});
+const ISO_TIMESTAMP_PATTERN =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+export function resolveIntent({
+  product,
+  mode,
+  state = null,
+  preference,
+  kickoffRequest = false,
+  answer,
+  now = new Date().toISOString(),
+}) {
+  assertProduct(product);
+  if (!MODES.has(mode)) {
+    throw new Error(`Unsupported lifecycle mode: ${String(mode)}`);
+  }
+  if (preference !== undefined && !PREFERENCES.has(preference)) {
+    throw new Error(
+      `${product} workflow preference must be always, ask, or never.`,
+    );
+  }
+  if (typeof kickoffRequest !== 'boolean') {
+    throw new TypeError('kickoffRequest must be a boolean.');
+  }
+
+  if (mode === 'autonomous') {
+    if (answer !== undefined) {
+      throw new Error('Autonomous lifecycle intent cannot use an answer.');
+    }
+    return resolveAutonomous({
+      product,
+      state,
+      preference,
+      kickoffRequest,
+      now,
+    });
+  }
+
+  if (state !== null) {
+    validateIntentRecord(product, state);
+  }
+  if (state) {
+    if (answer !== undefined) {
+      throw new Error(
+        `${product} already has a recorded decision; it must not prompt again.`,
+      );
+    }
+    return result(product, state.decision, 'project_state', state);
+  }
+
+  const effectivePreference = preference ?? 'ask';
+  if (effectivePreference === 'always') {
+    if (answer !== undefined) {
+      throw new Error(
+        `${product} preference always does not require an answer.`,
+      );
+    }
+    return result(product, 'generate', 'workflow_preference');
+  }
+  if (effectivePreference === 'never') {
+    if (answer !== undefined) {
+      throw new Error(
+        `${product} preference never does not require an answer.`,
+      );
+    }
+    return result(product, 'skip', 'workflow_preference');
+  }
+
+  if (answer === undefined) {
+    return {
+      product,
+      decision: 'ask',
+      resolutionSource:
+        preference === undefined ? 'default' : 'workflow_preference',
+      needsPrompt: true,
+      record: null,
+      warnings: [],
+    };
+  }
+  if (!DECISIONS.has(answer)) {
+    throw new Error(`${product} answer must be generate or skip.`);
+  }
+  const record = createRecord(product, answer, 'interactive', now);
+  return result(product, answer, 'interactive_answer', record);
+}
+
+export function validateIntentRecord(product, record) {
+  assertProduct(product);
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    throw new TypeError(`${product} intent must be a decision record.`);
+  }
+  const keys = Object.keys(record);
+  if (
+    keys.length !== 3 ||
+    keys.some((key) => !['decision', 'source', 'decided_at'].includes(key))
+  ) {
+    throw new Error(
+      `${product} intent must contain only decision, source, and decided_at.`,
+    );
+  }
+  if (!DECISIONS.has(record.decision)) {
+    throw new Error(`${product} decision must be generate or skip.`);
+  }
+  if (!SOURCES.has(record.source)) {
+    throw new Error(`${product} intent has an invalid source.`);
+  }
+  if (!ALLOWED_PAIRS[product].has(`${record.decision}:${record.source}`)) {
+    throw new Error(
+      `Invalid ${product} decision/source pair: ${record.decision}/${record.source}.`,
+    );
+  }
+  assertTimestamp(record.decided_at);
+  return record;
+}
+
+function resolveAutonomous({
+  product,
+  state,
+  preference,
+  kickoffRequest,
+  now,
+}) {
+  if (product === 'projectRecap') {
+    const warnings = [];
+    if (state?.decision === 'skip') {
+      warnings.push(
+        'Autonomous project recap policy overrode a lower-precedence skip decision.',
+      );
+    }
+    if (preference === 'never') {
+      warnings.push(
+        'Autonomous project recap policy overrode workflow preference never.',
+      );
+    }
+    return result(
+      product,
+      'generate',
+      'mode',
+      createRecord(product, 'generate', 'autonomous_policy', now),
+      warnings,
+    );
+  }
+
+  if (kickoffRequest) {
+    return result(
+      product,
+      'generate',
+      'mode',
+      createRecord(product, 'generate', 'kickoff_prompt', now),
+    );
+  }
+  return result(product, 'skip', 'mode');
+}
+
+function createRecord(product, decision, source, now) {
+  const record = { decision, source, decided_at: now };
+  validateIntentRecord(product, record);
+  return record;
+}
+
+function result(
+  product,
+  decision,
+  resolutionSource,
+  record = null,
+  warnings = [],
+) {
+  return {
+    product,
+    decision,
+    resolutionSource,
+    needsPrompt: false,
+    record,
+    warnings,
+  };
+}
+
+function assertProduct(product) {
+  if (!PRODUCTS.has(product)) {
+    throw new Error(`Unsupported lifecycle product: ${String(product)}`);
+  }
+}
+
+function assertTimestamp(value) {
+  if (
+    typeof value !== 'string' ||
+    !ISO_TIMESTAMP_PATTERN.test(value) ||
+    Number.isNaN(Date.parse(value))
+  ) {
+    throw new Error('Intent decided_at must be a valid ISO 8601 timestamp.');
+  }
+}

package/assets/skills/oat-explainer-kit/scripts/resolve-paths.mjs

@@ -0,0 +1,166 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+export async function resolveExplainerOutputRoot({
+  repoRoot,
+  invocation,
+  activeProject,
+  outputRoot,
+}) {
+  if (!repoRoot) {
+    throw new TypeError('repoRoot is required.');
+  }
+
+  if (invocation === 'direct') {
+    if (!outputRoot) {
+      throw new Error(
+        'Direct callers must provide an explicit outputRoot to the core.',
+      );
+    }
+    return resolveSafePath(outputRoot, {
+      baseRoot: repoRoot,
+      field: 'outputRoot',
+    });
+  }
+
+  const canonicalRepoRoot = await realpath(resolve(repoRoot));
+  if (invocation === 'repo') {
+    return resolveSafePath('.oat/repo/reference/explainers', {
+      baseRoot: canonicalRepoRoot,
+      confinedRoot: canonicalRepoRoot,
+      field: 'repo explainer output root',
+    });
+  }
+
+  if (invocation !== 'project') {
+    throw new Error(`Unsupported OAT explainer invocation: ${invocation}`);
+  }
+  if (!activeProject) {
+    throw new Error('Project explainer invocation requires an active project.');
+  }
+
+  const projectRoot = await resolveSafePath(activeProject, {
+    baseRoot: canonicalRepoRoot,
+    confinedRoot: canonicalRepoRoot,
+    field: 'active project',
+    mustExist: true,
+  });
+  if (projectRoot === canonicalRepoRoot) {
+    throw new Error('The active project cannot be the repository root.');
+  }
+
+  return resolveSafePath(join(projectRoot, 'explainers'), {
+    baseRoot: canonicalRepoRoot,
+    confinedRoot: projectRoot,
+    field: 'project explainer output root',
+  });
+}
+
+export async function resolveSourceAwarePath({
+  repoRoot,
+  candidate,
+  source,
+  field,
+}) {
+  if (typeof candidate !== 'string' || !candidate.trim()) {
+    throw new Error(`${field} must be a non-empty path.`);
+  }
+  if (source === 'user') {
+    throw new Error(`${field} cannot be resolved from user config.`);
+  }
+  if (source === 'shared' && isAbsolute(candidate)) {
+    throw new Error(`${field} from shared config must be repository-relative.`);
+  }
+
+  const canonicalRepoRoot = await realpath(resolve(repoRoot));
+  const absolute = isAbsolute(candidate);
+  const confined =
+    source === 'shared' ||
+    (!absolute && (source === 'local' || source === 'runtime'));
+
+  return resolveSafePath(candidate, {
+    baseRoot: canonicalRepoRoot,
+    confinedRoot: confined ? canonicalRepoRoot : undefined,
+    field,
+    mustExist: true,
+  });
+}
+
+async function resolveSafePath(
+  candidate,
+  { baseRoot, confinedRoot, field, mustExist = false },
+) {
+  validateLexicalPath(candidate, field);
+  const lexicalPath = resolve(baseRoot, candidate);
+  if (confinedRoot && !isWithin(resolve(confinedRoot), lexicalPath)) {
+    throw new Error(`${field} resolves outside its allowed root.`);
+  }
+
+  let canonicalPath;
+  try {
+    canonicalPath = await realpath(lexicalPath);
+  } catch (error) {
+    if (!isMissing(error)) {
+      throw error;
+    }
+    if (mustExist) {
+      throw new Error(`${field} does not exist: ${candidate}`, {
+        cause: error,
+      });
+    }
+    canonicalPath = await canonicalizeMissingPath(lexicalPath);
+  }
+
+  if (confinedRoot) {
+    const canonicalConfinedRoot = await realpath(resolve(confinedRoot));
+    if (!isWithin(canonicalConfinedRoot, canonicalPath)) {
+      throw new Error(
+        `${field} resolves outside its allowed root through a symlink ancestor.`,
+      );
+    }
+  }
+  return canonicalPath;
+}
+
+async function canonicalizeMissingPath(target) {
+  const suffix = [];
+  let ancestor = target;
+  while (true) {
+    try {
+      await lstat(ancestor);
+      return join(await realpath(ancestor), ...suffix.reverse());
+    } catch (error) {
+      if (!isMissing(error)) {
+        throw error;
+      }
+    }
+    const parent = resolve(ancestor, '..');
+    if (parent === ancestor) {
+      throw new Error(`No existing ancestor found for path: ${target}`);
+    }
+    suffix.push(relative(parent, ancestor));
+    ancestor = parent;
+  }
+}
+
+function validateLexicalPath(candidate, field) {
+  if (typeof candidate !== 'string' || !candidate.trim()) {
+    throw new Error(`${field} must be a non-empty path.`);
+  }
+  if (
+    candidate.includes('\0') ||
+    candidate.includes('\\') ||
+    candidate.split('/').includes('..')
+  ) {
+    throw new Error(`${field} contains unsafe traversal or path separators.`);
+  }
+}
+
+function isWithin(root, target) {
+  const path = relative(root, target);
+  return path === '' || (path !== '..' && !path.startsWith(`..${sep}`));
+}
+
+function isMissing(error) {
+  return error && typeof error === 'object' && error.code === 'ENOENT';
+}