agentxchain 2.110.0 → 2.112.0

package/src/lib/missions.js

@@ -0,0 +1,195 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { loadAllChainReports, loadChainReport, loadLatestChainReport } from './chain-reports.js';
+import { getActiveRepoDecisions } from './repo-decisions.js';
+
+const MISSION_ATTENTION_TERMINALS = new Set(['operator_abort', 'parent_validation_failed']);
+const MISSION_ATTENTION_RUN_STATUSES = new Set(['blocked', 'failed']);
+
+export function getMissionsDir(root) {
+  return join(root, '.agentxchain', 'missions');
+}
+
+export function buildMissionId(input) {
+  const slug = String(input || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64);
+  const base = slug || 'untitled';
+  return base.startsWith('mission-') ? base : `mission-${base}`;
+}
+
+export function createMission(root, { missionId, title, goal }) {
+  const normalizedId = buildMissionId(missionId || title);
+  const filePath = join(getMissionsDir(root), `${normalizedId}.json`);
+  if (existsSync(filePath)) {
+    return { ok: false, error: `Mission already exists: ${normalizedId}` };
+  }
+
+  const now = new Date().toISOString();
+  const artifact = {
+    mission_id: normalizedId,
+    title,
+    goal,
+    status: 'active',
+    created_at: now,
+    updated_at: now,
+    chain_ids: [],
+  };
+
+  mkdirSync(getMissionsDir(root), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(artifact, null, 2));
+  return { ok: true, mission: artifact };
+}
+
+export function loadAllMissionArtifacts(root) {
+  const missionsDir = getMissionsDir(root);
+  if (!existsSync(missionsDir)) return [];
+
+  const missions = [];
+  for (const file of readdirSync(missionsDir).filter((entry) => entry.endsWith('.json')).sort()) {
+    try {
+      const parsed = JSON.parse(readFileSync(join(missionsDir, file), 'utf8'));
+      if (parsed && parsed.mission_id) {
+        missions.push(parsed);
+      }
+    } catch {
+      // Advisory surface only. Skip malformed mission files.
+    }
+  }
+
+  missions.sort((left, right) => {
+    const leftTime = new Date(left.updated_at || left.created_at || 0).getTime();
+    const rightTime = new Date(right.updated_at || right.created_at || 0).getTime();
+    return rightTime - leftTime;
+  });
+
+  return missions;
+}
+
+export function loadMissionArtifact(root, missionId) {
+  const filePath = join(getMissionsDir(root), `${missionId}.json`);
+  if (existsSync(filePath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+      if (parsed?.mission_id) return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  return loadAllMissionArtifacts(root).find((mission) => mission.mission_id === missionId) || null;
+}
+
+export function loadLatestMissionArtifact(root) {
+  const missions = loadAllMissionArtifacts(root);
+  return missions.length > 0 ? missions[0] : null;
+}
+
+export function attachChainToMission(root, missionId, chainRef = 'latest') {
+  const mission = loadMissionArtifact(root, missionId);
+  if (!mission) {
+    return { ok: false, error: `Mission not found: ${missionId}` };
+  }
+
+  const chain = chainRef === 'latest'
+    ? loadLatestChainReport(root)
+    : loadChainReport(root, chainRef);
+  if (!chain) {
+    return { ok: false, error: chainRef === 'latest' ? 'No chain reports found.' : `Chain report not found: ${chainRef}` };
+  }
+
+  const nextChainIds = Array.isArray(mission.chain_ids) ? [...mission.chain_ids] : [];
+  if (!nextChainIds.includes(chain.chain_id)) {
+    nextChainIds.push(chain.chain_id);
+  }
+
+  const updated = {
+    ...mission,
+    chain_ids: nextChainIds,
+    updated_at: new Date().toISOString(),
+  };
+
+  mkdirSync(getMissionsDir(root), { recursive: true });
+  writeFileSync(join(getMissionsDir(root), `${updated.mission_id}.json`), JSON.stringify(updated, null, 2));
+  return { ok: true, mission: updated, chain };
+}
+
+export function buildMissionSnapshot(root, missionArtifact) {
+  const chainIds = Array.isArray(missionArtifact.chain_ids) ? missionArtifact.chain_ids : [];
+  const chains = [];
+  const missingChainIds = [];
+
+  for (const chainId of chainIds) {
+    const report = loadChainReport(root, chainId);
+    if (report) {
+      chains.push(report);
+    } else {
+      missingChainIds.push(chainId);
+    }
+  }
+
+  chains.sort((left, right) => {
+    const leftTime = new Date(left.started_at || 0).getTime();
+    const rightTime = new Date(right.started_at || 0).getTime();
+    return rightTime - leftTime;
+  });
+
+  const totalRuns = chains.reduce((sum, chain) => sum + (chain.runs?.length || 0), 0);
+  const totalTurns = chains.reduce((sum, chain) => sum + (chain.total_turns || 0), 0);
+  const latestChain = chains[0] || null;
+  const activeRepoDecisions = getActiveRepoDecisions(root);
+
+  return {
+    ...missionArtifact,
+    derived_status: deriveMissionStatus(missionArtifact, chains, missingChainIds),
+    chain_count: chainIds.length,
+    attached_chain_count: chains.length,
+    missing_chain_ids: missingChainIds,
+    total_runs: totalRuns,
+    total_turns: totalTurns,
+    latest_chain_id: latestChain?.chain_id || null,
+    latest_terminal_reason: latestChain?.terminal_reason || null,
+    active_repo_decisions_count: activeRepoDecisions.length,
+    chains,
+  };
+}
+
+export function loadAllMissionSnapshots(root) {
+  return loadAllMissionArtifacts(root).map((mission) => buildMissionSnapshot(root, mission));
+}
+
+function deriveMissionStatus(missionArtifact, chains, missingChainIds) {
+  if (missionArtifact.status && missionArtifact.status !== 'active') {
+    return missionArtifact.status;
+  }
+  if (missingChainIds.length > 0) return 'degraded';
+  if (chains.length === 0) return 'planned';
+  if (chains.some((chain) => (
+    MISSION_ATTENTION_TERMINALS.has(chain.terminal_reason)
+    || (chain.runs || []).some((run) => MISSION_ATTENTION_RUN_STATUSES.has(run.status))
+  ))) {
+    return 'needs_attention';
+  }
+  return 'progressing';
+}
+
+export function loadLatestMissionSnapshot(root) {
+  const artifact = loadLatestMissionArtifact(root);
+  return artifact ? buildMissionSnapshot(root, artifact) : null;
+}
+
+export function loadMissionSnapshot(root, missionId) {
+  const artifact = loadMissionArtifact(root, missionId);
+  return artifact ? buildMissionSnapshot(root, artifact) : null;
+}
+
+export function buildMissionListSummary(root, limit = 20) {
+  return loadAllMissionSnapshots(root).slice(0, limit);
+}
+
+export function loadMissionAttachmentTarget(root, missionId) {
+  if (missionId) return loadMissionArtifact(root, missionId);
+  return loadLatestMissionArtifact(root);
+}

package/src/lib/release-alignment.js

@@ -0,0 +1,336 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const RELEASE_ALIGNMENT_SCOPES = {
+  PREBUMP: 'prebump',
+  CURRENT: 'current',
+};
+
+function read(repoRoot, relativePath) {
+  return readFileSync(join(repoRoot, relativePath), 'utf8');
+}
+
+function readJson(repoRoot, relativePath) {
+  return JSON.parse(read(repoRoot, relativePath));
+}
+
+export function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function formatCount(value) {
+  return new Intl.NumberFormat('en-US').format(value);
+}
+
+function normalizeEvidenceText(value) {
+  return value
+    .replace(/^\s*-\s*/, '')
+    .replace(/\.$/, '')
+    .replace(/,/g, '')
+    .trim();
+}
+
+export function extractTopReleaseSection(changelog, version) {
+  const heading = `## ${version}`;
+  const start = changelog.indexOf(heading);
+  if (start === -1) {
+    return null;
+  }
+  const afterStart = changelog.slice(start + heading.length);
+  const nextHeadingOffset = afterStart.search(/\n##\s+\d+\.\d+\.\d+/);
+  return nextHeadingOffset === -1 ? afterStart : afterStart.slice(0, nextHeadingOffset);
+}
+
+export function extractAggregateEvidenceLine(text) {
+  const matches = [...text.matchAll(/(^-\s+.*\b\d[\d,]*\s+tests\b.*\b0 failures\b.*$)/gm)];
+  if (matches.length === 0) {
+    return null;
+  }
+
+  const aggregate = matches.reduce((best, match) => {
+    const line = match[1].replace(/\*\*/g, '').replace(/`/g, '').trim();
+    const countMatch = line.match(/\b(\d[\d,]*)\s+tests\b/);
+    const count = countMatch ? Number(countMatch[1].replace(/,/g, '')) : 0;
+    if (!best || count > best.count) {
+      return { count, line };
+    }
+    return best;
+  }, null);
+
+  return aggregate?.line ?? null;
+}
+
+function extractAggregateEvidenceCount(line) {
+  const match = line?.match(/\b(\d[\d,]*)\s+tests\b/);
+  if (!match) {
+    return null;
+  }
+  return Number(match[1].replace(/,/g, ''));
+}
+
+export function getReleaseAlignmentContext(repoRoot, { targetVersion } = {}) {
+  const pkg = readJson(repoRoot, 'cli/package.json');
+  const version = targetVersion || pkg.version;
+  const releaseDocId = `v${version.replace(/\./g, '-')}`;
+  const releaseDocPath = `website-v2/docs/releases/${releaseDocId}.mdx`;
+  const releaseRoute = `/docs/releases/${releaseDocId}`;
+  const tarballUrl = `https://registry.npmjs.org/agentxchain/-/agentxchain-${version}.tgz`;
+  const changelog = read(repoRoot, 'cli/CHANGELOG.md');
+  const changelogSection = extractTopReleaseSection(changelog, version);
+  const aggregateEvidenceLine = changelogSection ? extractAggregateEvidenceLine(changelogSection) : null;
+  const aggregateEvidenceCount = extractAggregateEvidenceCount(aggregateEvidenceLine);
+
+  return {
+    packageVersion: pkg.version,
+    targetVersion: version,
+    releaseDocId,
+    releaseDocPath,
+    releaseRoute,
+    tarballUrl,
+    changelog,
+    changelogSection,
+    aggregateEvidenceLine,
+    aggregateEvidenceText: aggregateEvidenceLine ? normalizeEvidenceText(aggregateEvidenceLine) : null,
+    aggregateEvidenceCount,
+  };
+}
+
+function validateCurrentReleaseDoc(ctx, repoRoot) {
+  const errors = [];
+  const fullPath = join(repoRoot, ctx.releaseDocPath);
+  if (!existsSync(fullPath)) {
+    errors.push(`release notes page missing: ${ctx.releaseDocPath}`);
+    return errors;
+  }
+
+  const releaseDoc = read(repoRoot, ctx.releaseDocPath);
+  const heading = `# AgentXchain v${ctx.targetVersion}`;
+  if (!releaseDoc.includes(heading)) {
+    errors.push(`${ctx.releaseDocPath} must contain ${heading}`);
+  }
+
+  if (!releaseDoc.match(/## Evidence/i)) {
+    errors.push(`${ctx.releaseDocPath} must contain an Evidence section`);
+  }
+
+  if (ctx.aggregateEvidenceText && !normalizeEvidenceText(releaseDoc).includes(ctx.aggregateEvidenceText)) {
+    errors.push(`${ctx.releaseDocPath} must carry aggregate evidence line "${ctx.aggregateEvidenceLine}"`);
+  }
+
+  return errors;
+}
+
+function validateTextIncludesVersionAndEvidence(relativePath, label) {
+  return {
+    id: label,
+    check(ctx, repoRoot) {
+      const content = read(repoRoot, relativePath);
+      const errors = [];
+      if (!content.includes(`v${ctx.targetVersion}`)) {
+        errors.push(`${relativePath} must mention v${ctx.targetVersion}`);
+      }
+      if (ctx.aggregateEvidenceText && !normalizeEvidenceText(content).includes(ctx.aggregateEvidenceText)) {
+        errors.push(`${relativePath} must carry aggregate evidence line "${ctx.aggregateEvidenceLine}"`);
+      }
+      return errors;
+    },
+  };
+}
+
+export const RELEASE_ALIGNMENT_SURFACES = [
+  {
+    id: 'changelog',
+    label: 'cli/CHANGELOG.md top target section',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check(ctx) {
+      const errors = [];
+      if (!ctx.changelogSection) {
+        errors.push(`cli/CHANGELOG.md is missing top heading ## ${ctx.targetVersion}`);
+      }
+      if (!ctx.aggregateEvidenceLine) {
+        errors.push(`cli/CHANGELOG.md section ## ${ctx.targetVersion} must contain an aggregate evidence line with 0 failures`);
+      }
+      return errors;
+    },
+  },
+  {
+    id: 'release_notes',
+    label: 'current release notes page',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check: validateCurrentReleaseDoc,
+  },
+  {
+    id: 'release_sidebar',
+    label: 'website-v2/sidebars.ts release autogen',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check(_ctx, repoRoot) {
+      const sidebars = read(repoRoot, 'website-v2/sidebars.ts');
+      return /label:\s*'Release Notes'[\s\S]*dirName:\s*'releases'/.test(sidebars)
+        ? []
+        : [`website-v2/sidebars.ts must keep Release Notes auto-generated from dirName: 'releases'`];
+    },
+  },
+  {
+    id: 'homepage_badge',
+    label: 'homepage hero badge version',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check(ctx, repoRoot) {
+      const home = read(repoRoot, 'website-v2/src/pages/index.tsx');
+      return home.includes(`v${ctx.targetVersion}`)
+        ? []
+        : [`website-v2/src/pages/index.tsx must mention v${ctx.targetVersion}`];
+    },
+  },
+  {
+    id: 'homepage_proof_stat',
+    label: 'homepage proof stat',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check(ctx, repoRoot) {
+      if (ctx.aggregateEvidenceCount == null) {
+        return ['homepage proof stat cannot be validated because CHANGELOG aggregate evidence is missing'];
+      }
+      const home = read(repoRoot, 'website-v2/src/pages/index.tsx');
+      const formatted = formatCount(ctx.aggregateEvidenceCount);
+      const errors = [];
+      if (!home.includes(`stat-number">${formatted}<`)) {
+        errors.push(`website-v2/src/pages/index.tsx must show homepage proof stat ${formatted}`);
+      }
+      if (!home.includes('Tests / 0 failures')) {
+        errors.push('website-v2/src/pages/index.tsx must keep the "Tests / 0 failures" proof label');
+      }
+      return errors;
+    },
+  },
+  {
+    id: 'capabilities_version',
+    label: '.agentxchain-conformance/capabilities.json version',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check(ctx, repoRoot) {
+      const capabilities = readJson(repoRoot, '.agentxchain-conformance/capabilities.json');
+      return capabilities.version === ctx.targetVersion
+        ? []
+        : [`.agentxchain-conformance/capabilities.json version is "${capabilities.version}", expected "${ctx.targetVersion}"`];
+    },
+  },
+  {
+    id: 'implementor_guide_version',
+    label: 'protocol implementor guide example version',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check(ctx, repoRoot) {
+      const guide = read(repoRoot, 'website-v2/docs/protocol-implementor-guide.mdx');
+      return guide.includes(`"version": "${ctx.targetVersion}"`)
+        ? []
+        : [`website-v2/docs/protocol-implementor-guide.mdx must contain "version": "${ctx.targetVersion}"`];
+    },
+  },
+  {
+    id: 'launch_evidence_report',
+    label: 'launch evidence report',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check(ctx, repoRoot) {
+      const report = read(repoRoot, '.planning/LAUNCH_EVIDENCE_REPORT.md');
+      const errors = [];
+      if (!report.match(new RegExp(`^# Launch Evidence Report — AgentXchain v${escapeRegExp(ctx.targetVersion)}`, 'm'))) {
+        errors.push(`.planning/LAUNCH_EVIDENCE_REPORT.md title must carry v${ctx.targetVersion}`);
+      }
+      if (ctx.aggregateEvidenceText && !normalizeEvidenceText(report).includes(ctx.aggregateEvidenceText)) {
+        errors.push(`.planning/LAUNCH_EVIDENCE_REPORT.md must carry aggregate evidence line "${ctx.aggregateEvidenceLine}"`);
+      }
+      return errors;
+    },
+  },
+  {
+    id: 'show_hn_draft',
+    label: 'show hn draft',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check: validateTextIncludesVersionAndEvidence('.planning/SHOW_HN_DRAFT.md', 'show hn draft').check,
+  },
+  {
+    id: 'twitter_thread',
+    label: 'twitter thread draft',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check: validateTextIncludesVersionAndEvidence('.planning/MARKETING/TWITTER_THREAD.md', 'twitter thread draft').check,
+  },
+  {
+    id: 'reddit_posts',
+    label: 'reddit posts draft',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check: validateTextIncludesVersionAndEvidence('.planning/MARKETING/REDDIT_POSTS.md', 'reddit posts draft').check,
+  },
+  {
+    id: 'hn_submission',
+    label: 'hn submission draft',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check: validateTextIncludesVersionAndEvidence('.planning/MARKETING/HN_SUBMISSION.md', 'hn submission draft').check,
+  },
+  {
+    id: 'llms_release_route',
+    label: 'llms current release route',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check(ctx, repoRoot) {
+      const llms = read(repoRoot, 'website-v2/static/llms.txt');
+      return llms.includes(ctx.releaseRoute)
+        ? []
+        : [`website-v2/static/llms.txt must list ${ctx.releaseRoute}`];
+    },
+  },
+  {
+    id: 'homebrew_formula_url',
+    label: 'homebrew mirror formula url',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check(ctx, repoRoot) {
+      const formula = read(repoRoot, 'cli/homebrew/agentxchain.rb');
+      return formula.includes(`url "${ctx.tarballUrl}"`)
+        ? []
+        : [`cli/homebrew/agentxchain.rb must point at ${ctx.tarballUrl}`];
+    },
+  },
+  {
+    id: 'homebrew_readme',
+    label: 'homebrew mirror readme',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check(ctx, repoRoot) {
+      const readme = read(repoRoot, 'cli/homebrew/README.md');
+      const errors = [];
+      if (!readme.includes(`- version: \`${ctx.targetVersion}\``)) {
+        errors.push(`cli/homebrew/README.md must carry version ${ctx.targetVersion}`);
+      }
+      if (!readme.includes(`- source tarball: \`${ctx.tarballUrl}\``)) {
+        errors.push(`cli/homebrew/README.md must carry tarball ${ctx.tarballUrl}`);
+      }
+      return errors;
+    },
+  },
+];
+
+export function validateReleaseAlignment(repoRoot, { targetVersion, scope = RELEASE_ALIGNMENT_SCOPES.CURRENT } = {}) {
+  if (!Object.values(RELEASE_ALIGNMENT_SCOPES).includes(scope)) {
+    throw new Error(`Unsupported release alignment scope "${scope}"`);
+  }
+
+  const context = getReleaseAlignmentContext(repoRoot, { targetVersion });
+  const surfaces = RELEASE_ALIGNMENT_SURFACES.filter((surface) => surface.scopes.includes(scope));
+  const errors = [];
+
+  for (const surface of surfaces) {
+    const surfaceErrors = surface.check(context, repoRoot) || [];
+    for (const error of surfaceErrors) {
+      errors.push({
+        surface_id: surface.id,
+        label: surface.label,
+        message: error,
+      });
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    scope,
+    targetVersion: context.targetVersion,
+    packageVersion: context.packageVersion,
+    aggregateEvidenceLine: context.aggregateEvidenceLine,
+    checkedSurfaceCount: surfaces.length,
+    checkedSurfaceIds: surfaces.map((surface) => surface.id),
+    errors,
+  };
+}