@open-agent-toolkit/cli 0.2.72 → 0.2.74

package/assets/skills/explainer-kit/scripts/lib/set-plan.mjs

@@ -1,209 +0,0 @@
-import { canonicalHash, validateContract } from './contracts.mjs';
-import { recipeExpansion, recipeFloor } from './recipes.mjs';
-
-export async function planExplainerSet({
-  recipe,
-  factBase,
-  discovery,
-  planSet,
-}) {
-  const sourceIds = factBase.sources
-    .map(({ id }) => id)
-    .filter((id) => !id.startsWith('critic:'));
-  const request = deepFreeze({
-    schemaVersion: 'explainer-kit.set-plan-request/v1',
-    recipe: structuredClone(recipe),
-    factBase: structuredClone(factBase),
-    sourceIds: structuredClone(sourceIds),
-    discovery: structuredClone(discovery),
-  });
-  const callback =
-    typeof planSet === 'function' ? planSet : createBaselineSetPlan;
-  const candidate = await callback(structuredClone(request));
-  const validation = validateContract('set-plan', candidate);
-  if (!validation.valid) {
-    throw setPlanError(
-      validation.errors
-        .map(({ path, code, message }) => `${path} [${code}]: ${message}`)
-        .join('; '),
-    );
-  }
-  validateAgainstInputs(candidate, { recipe, sourceIds });
-
-  const plan = deepFreeze(structuredClone(candidate));
-  const retainedRequest = deepFreeze({
-    schemaVersion: request.schemaVersion,
-    recipe: { id: recipe.id, version: recipe.version },
-    factBaseHash: canonicalHash(factBase),
-    sourceIds,
-    discovery: structuredClone(discovery),
-  });
-  return { request: retainedRequest, plan };
-}
-
-export function plannedArtifacts(recipe, plan) {
-  const floor = new Map(
-    recipeFloor(recipe).map((artifact) => [artifact.id, artifact]),
-  );
-  const profiles = new Map(
-    recipeExpansion(recipe).profiles.map((profile) => [
-      profile.profileId,
-      profile,
-    ]),
-  );
-  return plan.portfolio.map((planned) => {
-    const floorArtifact = floor.get(planned.artifactId);
-    if (floorArtifact) {
-      return {
-        ...floorArtifact,
-        origin: 'floor',
-        shell:
-          floorArtifact.authoring === 'html'
-            ? floorArtifact.template
-            : undefined,
-        plannedArtifact: planned,
-      };
-    }
-    const profile = profiles.get(planned.profileId);
-    return {
-      id: planned.artifactId,
-      type: profile.type,
-      authoring: profile.authoring,
-      briefRef: profile.briefRef,
-      shell: profile.shell,
-      template:
-        profile.authoring === 'markdown'
-          ? templateForType(profile.type)
-          : profile.shell,
-      required: false,
-      origin: 'expansion',
-      profileId: profile.profileId,
-      plannedArtifact: planned,
-    };
-  });
-}
-
-function createBaselineSetPlan({ recipe, factBase }) {
-  const sourceIds = factBase.sources
-    .map(({ id }) => id)
-    .filter((id) => !id.startsWith('critic:'));
-  return {
-    schemaVersion: 'explainer-kit.set-plan/v1',
-    planId: `${recipe.id}-set`,
-    recipe: { id: recipe.id, version: recipe.version },
-    sourceIds,
-    ledger: { terminology: [], statuses: [], numbers: [] },
-    portfolio: recipeFloor(recipe).map((artifact) => ({
-      artifactId: artifact.id,
-      artifactType: artifact.type,
-      profileId: 'recipe-floor',
-      required: true,
-      sourceIds,
-      draft: `Compose ${artifact.id} from the reconciled fact base.`,
-      visualIntent: 'Follow the bundled brief and selected medium.',
-    })),
-  };
-}
-
-function validateAgainstInputs(plan, { recipe, sourceIds }) {
-  if (plan.recipe.id !== recipe.id || plan.recipe.version !== recipe.version) {
-    throw setPlanError('Set plan recipe does not match the active recipe.');
-  }
-  const availableSources = new Set(sourceIds);
-  for (const sourceId of plan.sourceIds) {
-    if (!availableSources.has(sourceId)) {
-      throw setPlanError(
-        `Set plan references unknown reconciled source ${sourceId}.`,
-      );
-    }
-  }
-  const plannedSources = new Set(plan.sourceIds);
-  const omittedSources = sourceIds.filter(
-    (sourceId) => !plannedSources.has(sourceId),
-  );
-  if (
-    omittedSources.length > 0 ||
-    plannedSources.size !== availableSources.size
-  ) {
-    throw setPlanError(
-      `Set plan must declare every reconciled non-critic source; omitted ${omittedSources.join(', ') || 'none'}.`,
-    );
-  }
-  const coveredSources = new Set(
-    plan.portfolio.flatMap(({ sourceIds: artifactSourceIds }) =>
-      Array.isArray(artifactSourceIds) ? artifactSourceIds : [],
-    ),
-  );
-  const uncoveredSources = plan.sourceIds.filter(
-    (sourceId) => !coveredSources.has(sourceId),
-  );
-  if (uncoveredSources.length > 0) {
-    throw setPlanError(
-      `Every declared source must cover at least one portfolio artifact; uncovered ${uncoveredSources.join(', ')}.`,
-    );
-  }
-
-  const plannedById = new Map(
-    plan.portfolio.map((artifact) => [artifact.artifactId, artifact]),
-  );
-  for (const floorArtifact of recipeFloor(recipe)) {
-    const planned = plannedById.get(floorArtifact.id);
-    if (
-      !planned ||
-      planned.required !== true ||
-      planned.artifactType !== floorArtifact.type
-    ) {
-      throw setPlanError(
-        `Set plan is missing required draft ${floorArtifact.id}.`,
-      );
-    }
-  }
-
-  const floorIds = new Set(recipeFloor(recipe).map(({ id }) => id));
-  const profiles = new Map(
-    recipeExpansion(recipe).profiles.map((profile) => [
-      profile.profileId,
-      profile,
-    ]),
-  );
-  for (const artifact of plan.portfolio) {
-    if (floorIds.has(artifact.artifactId)) continue;
-    const profile = profiles.get(artifact.profileId);
-    if (
-      !profile ||
-      artifact.required !== false ||
-      artifact.artifactType !== profile.type
-    ) {
-      throw setPlanError(
-        `Optional artifact ${artifact.artifactId} does not match an allowed recipe profile.`,
-      );
-    }
-  }
-}
-
-function templateForType(type) {
-  return (
-    {
-      hub: 'house-style',
-      diagram: 'diagram-shell',
-      explainer: 'engineer-tour',
-      deck: 'deck-shell',
-    }[type] ?? 'house-style'
-  );
-}
-
-function deepFreeze(value) {
-  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
-    Object.freeze(value);
-    for (const child of Object.values(value)) {
-      deepFreeze(child);
-    }
-  }
-  return value;
-}
-
-function setPlanError(message) {
-  const error = new Error(`Invalid set plan: ${message}`);
-  error.code = 'E_SET_PLAN';
-  return error;
-}

package/assets/skills/explainer-kit/scripts/lib/source-backlinks.mjs

@@ -1,218 +0,0 @@
-export const SOURCE_BACKLINK_CONTRACT_VERSION =
-  'explainer-kit.source-backlinks/v1';
-
-const REPOSITORY_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
-const REVISION_PATTERN = /^[a-f0-9]{40}$/;
-const LINE_FRAGMENT_PATTERN = /^L([1-9][0-9]*)(?:-L([1-9][0-9]*))?$/;
-
-export function canonicalGithubBlobBacklink(tuple) {
-  const normalized = normalizeBacklinkTuple(tuple);
-  const encodedPath = normalized.path
-    .split('/')
-    .map((segment) => encodeURIComponent(segment))
-    .join('/');
-  const fragment =
-    normalized.lineRange.start === normalized.lineRange.end
-      ? `L${normalized.lineRange.start}`
-      : `L${normalized.lineRange.start}-L${normalized.lineRange.end}`;
-  return `https://github.com/${normalized.repository}/blob/${normalized.revision}/${encodedPath}#${fragment}`;
-}
-
-export function validateCanonicalGithubBlobTuple(tuple) {
-  try {
-    const normalized = normalizeBacklinkTuple(tuple);
-    if (
-      typeof tuple?.url !== 'string' ||
-      tuple.url !== canonicalGithubBlobBacklink(normalized)
-    ) {
-      return false;
-    }
-    return sameTuple(parseCanonicalGithubBlobUrl(tuple.url), {
-      ...normalized,
-      url: tuple.url,
-    });
-  } catch {
-    return false;
-  }
-}
-
-export function parseCanonicalGithubBlobUrl(value) {
-  if (typeof value !== 'string') {
-    throw backlinkError('GitHub backlink URL must be a string.');
-  }
-  if (
-    !value.startsWith('https://github.com/') ||
-    value.includes('?') ||
-    value.includes('\\')
-  ) {
-    throw backlinkError(
-      'GitHub backlink must use canonical credential-free HTTPS without query.',
-    );
-  }
-  const hashIndex = value.indexOf('#');
-  if (hashIndex < 0 || value.indexOf('#', hashIndex + 1) >= 0) {
-    throw backlinkError(
-      'GitHub backlink requires one canonical line fragment.',
-    );
-  }
-  const rawPath = value.slice('https://github.com/'.length, hashIndex);
-  const fragment = value.slice(hashIndex + 1);
-  const rawSegments = rawPath.split('/');
-  if (
-    rawSegments.length < 5 ||
-    rawSegments.some((segment) => segment.length === 0)
-  ) {
-    throw backlinkError('GitHub backlink path contains an empty segment.');
-  }
-  const [owner, repositoryName, blob, revision, ...rawFileSegments] =
-    rawSegments;
-  if (
-    blob !== 'blob' ||
-    !REPOSITORY_PATTERN.test(`${owner}/${repositoryName}`) ||
-    !REVISION_PATTERN.test(revision)
-  ) {
-    throw backlinkError(
-      'GitHub backlink requires a canonical repository and full commit SHA.',
-    );
-  }
-  const fileSegments = rawFileSegments.map(decodeCanonicalSegment);
-  const lineMatch = fragment.match(LINE_FRAGMENT_PATTERN);
-  if (!lineMatch) {
-    throw backlinkError('GitHub backlink requires a canonical line range.');
-  }
-  const start = Number(lineMatch[1]);
-  const end = Number(lineMatch[2] ?? lineMatch[1]);
-  if (end < start) {
-    throw backlinkError('GitHub backlink line range is reversed.');
-  }
-  const tuple = {
-    repository: `${owner}/${repositoryName}`,
-    revision,
-    path: fileSegments.join('/'),
-    lineRange: { start, end },
-  };
-  const canonical = canonicalGithubBlobBacklink(tuple);
-  let parsed;
-  try {
-    parsed = new URL(value);
-  } catch {
-    throw backlinkError('GitHub backlink URL is malformed.');
-  }
-  if (
-    parsed.protocol !== 'https:' ||
-    parsed.hostname !== 'github.com' ||
-    parsed.port ||
-    parsed.username ||
-    parsed.password ||
-    parsed.search ||
-    parsed.href !== canonical ||
-    value !== canonical
-  ) {
-    throw backlinkError('GitHub backlink URL is not canonical.');
-  }
-  return { ...tuple, url: canonical };
-}
-
-function normalizeBacklinkTuple(tuple) {
-  if (
-    !tuple ||
-    typeof tuple !== 'object' ||
-    !REPOSITORY_PATTERN.test(tuple.repository ?? '') ||
-    !REVISION_PATTERN.test(tuple.revision ?? '')
-  ) {
-    throw backlinkError(
-      'GitHub backlink tuple requires a canonical repository and full commit SHA.',
-    );
-  }
-  const path = normalizeRepositoryPath(tuple.path);
-  const lineRange = normalizeLineRange(tuple.lineRange);
-  return {
-    repository: tuple.repository,
-    revision: tuple.revision,
-    path,
-    lineRange,
-  };
-}
-
-function normalizeRepositoryPath(value) {
-  if (
-    typeof value !== 'string' ||
-    value.length === 0 ||
-    value.startsWith('/') ||
-    value.includes('\\')
-  ) {
-    throw backlinkError(
-      'GitHub backlink tuple requires a repository-relative path.',
-    );
-  }
-  const segments = value.split('/');
-  if (
-    segments.some(
-      (segment) =>
-        segment.length === 0 ||
-        segment === '.' ||
-        segment === '..' ||
-        segment.includes('/') ||
-        segment.includes('\\') ||
-        segment.includes('\0'),
-    )
-  ) {
-    throw backlinkError('GitHub backlink path contains an unsafe segment.');
-  }
-  return segments.join('/');
-}
-
-function normalizeLineRange(value) {
-  if (
-    !value ||
-    !Number.isInteger(value.start) ||
-    !Number.isInteger(value.end) ||
-    value.start < 1 ||
-    value.end < value.start
-  ) {
-    throw backlinkError(
-      'GitHub backlink tuple requires a valid inclusive line range.',
-    );
-  }
-  return { start: value.start, end: value.end };
-}
-
-function decodeCanonicalSegment(rawSegment) {
-  let decoded;
-  try {
-    decoded = decodeURIComponent(rawSegment);
-  } catch {
-    throw backlinkError('GitHub backlink path has malformed encoding.');
-  }
-  if (
-    decoded.length === 0 ||
-    decoded === '.' ||
-    decoded === '..' ||
-    decoded.includes('/') ||
-    decoded.includes('\\') ||
-    decoded.includes('\0') ||
-    encodeURIComponent(decoded) !== rawSegment
-  ) {
-    throw backlinkError(
-      'GitHub backlink path has an unsafe or noncanonical encoded segment.',
-    );
-  }
-  return decoded;
-}
-
-function sameTuple(left, right) {
-  return (
-    left.repository === right.repository &&
-    left.revision === right.revision &&
-    left.path === right.path &&
-    left.lineRange.start === right.lineRange.start &&
-    left.lineRange.end === right.lineRange.end &&
-    left.url === right.url
-  );
-}
-
-function backlinkError(message) {
-  const error = new TypeError(message);
-  error.code = 'E_SOURCE_BACKLINK';
-  return error;
-}

package/assets/skills/explainer-kit/scripts/lib/terminal-evidence.mjs

@@ -1,157 +0,0 @@
-import { createHash } from 'node:crypto';
-import { lstat, readFile, realpath } from 'node:fs/promises';
-import { resolve } from 'node:path';
-
-import { canonicalHash, validateContract } from './contracts.mjs';
-
-export const TERMINAL_EVIDENCE_VERSION = 'explainer-kit.terminal-evidence/v1';
-export const VISUAL_REVIEW_EVIDENCE_VERSION =
-  'explainer-kit.visual-review-evidence/v1';
-export const EVIDENCE_REASON_MAX_COUNT = 50;
-
-export function createTerminalEvidence({
-  runId,
-  outcome,
-  manifest,
-  reasons,
-  evidenceDisposition,
-  supersededBy,
-} = {}) {
-  const evidence = {
-    schemaVersion: TERMINAL_EVIDENCE_VERSION,
-    runId,
-    outcome,
-    ...(manifest && { manifestHash: canonicalHash(manifest) }),
-    reasons: structuredClone(reasons),
-    evidenceDisposition,
-    ...(supersededBy && {
-      supersededBy: structuredClone(supersededBy),
-    }),
-  };
-  assertTerminalEvidence(evidence, { manifest });
-  return evidence;
-}
-
-export function assertTerminalEvidence(evidence, { manifest } = {}) {
-  const validation = validateContract('terminal-evidence', evidence, {
-    manifest,
-  });
-  if (!validation.valid) {
-    throw new Error(
-      `Invalid terminal evidence: ${validation.errors
-        .map(({ path, code }) => `${path} [${code}]`)
-        .join('; ')}`,
-    );
-  }
-  return evidence;
-}
-
-export function createVisualReviewEvidence({
-  request,
-  attempt,
-  result,
-  failureKind,
-} = {}) {
-  const evidence = {
-    schemaVersion: VISUAL_REVIEW_EVIDENCE_VERSION,
-    requestHash: request?.requestHash,
-    attempt,
-    disposition: failureKind
-      ? 'failed'
-      : result?.disposition === 'pass'
-        ? 'pass'
-        : 'correct',
-    reasons: failureKind
-      ? [{ stage: 'visual-review', kind: failureKind, count: 1 }]
-      : result?.disposition === 'pass'
-        ? []
-        : findingReasons(result?.findings),
-  };
-  assertVisualReviewEvidence(evidence, { request, attempt });
-  return evidence;
-}
-
-export function assertVisualReviewEvidence(
-  evidence,
-  { request, attempt } = {},
-) {
-  const validation = validateContract('visual-review-evidence', evidence, {
-    visualReviewRequest: request,
-    attempt,
-  });
-  if (!validation.valid) {
-    throw new Error(
-      `Invalid retained visual evidence: ${validation.errors
-        .map(({ path, code }) => `${path} [${code}]`)
-        .join('; ')}`,
-    );
-  }
-  return evidence;
-}
-
-export function evidenceReason(stage, kind, { artifactId, count = 1 } = {}) {
-  return {
-    stage,
-    kind,
-    ...(artifactId !== undefined && { artifactId }),
-    count,
-  };
-}
-
-export function projectThrownReason(stage, kind = 'pipeline-failure') {
-  return evidenceReason(stage, kind);
-}
-
-export async function readTerminalEvidenceFile(
-  runRoot,
-  { manifest, expectedBytes, expectedHash } = {},
-) {
-  if (typeof runRoot !== 'string' || runRoot.length === 0) {
-    throw new TypeError('Terminal evidence run root must be a path string.');
-  }
-  const canonicalRunRoot = await realpath(runRoot);
-  const evidencePath = resolve(canonicalRunRoot, 'terminal-evidence.json');
-  const stats = await lstat(evidencePath);
-  if (stats.isSymbolicLink() || !stats.isFile()) {
-    throw new Error(
-      'Terminal evidence must be a regular file, not a symbolic link.',
-    );
-  }
-  const canonicalEvidencePath = await realpath(evidencePath);
-  if (canonicalEvidencePath !== evidencePath) {
-    throw new Error('Terminal evidence must remain within the run root.');
-  }
-  const bytes = await readFile(canonicalEvidencePath);
-  const hash = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
-  if (expectedHash !== undefined && hash !== expectedHash) {
-    throw new Error('Terminal evidence bytes changed while staging.');
-  }
-  if (
-    expectedBytes !== undefined &&
-    !bytes.equals(Buffer.from(expectedBytes))
-  ) {
-    throw new Error('Terminal evidence bytes changed while staging.');
-  }
-  let evidence;
-  try {
-    evidence = JSON.parse(bytes.toString('utf8'));
-  } catch {
-    throw new Error('Terminal evidence must contain valid JSON.');
-  }
-  assertTerminalEvidence(evidence, { manifest });
-  return { evidence, bytes, hash };
-}
-
-function findingReasons(findings) {
-  const counts = new Map();
-  let total = 0;
-  for (const finding of Array.isArray(findings) ? findings : []) {
-    if (total >= EVIDENCE_REASON_MAX_COUNT) break;
-    const artifactId = finding?.artifactId;
-    counts.set(artifactId, (counts.get(artifactId) ?? 0) + 1);
-    total += 1;
-  }
-  return [...counts].map(([artifactId, count]) =>
-    evidenceReason('visual-review', 'finding', { artifactId, count }),
-  );
-}