@open-agent-toolkit/cli 0.2.50 → 0.2.52

package/assets/skills/oat-project-complete/scripts/execute-synced-archive-entry.mjs

@@ -0,0 +1,306 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, posix, relative, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
+
+import { validateSyncedArchiveTerminalReport } from './finalize-synced-archive.mjs';
+import { recoverArchivedRecapEvidenceReceipt } from './recover-completion-receipts.mjs';
+import { resolveSyncedArchiveEntry } from './resolve-synced-archive-entry.mjs';
+
+const execFile = promisify(execFileCallback);
+
+function executionError(message) {
+  const error = new Error(message);
+  error.code = 'E_SYNCED_ARCHIVE_EXECUTION';
+  return error;
+}
+
+async function buildPostArchiveContinuation(
+  archiveReport,
+  projectPath,
+  repoRoot,
+  recoverArchiveEvidence,
+) {
+  let selectedProjectRecapRun = '';
+  let exportedManifestPath = '';
+  let exportedBuildRecordPath = '';
+  let evidenceCommit = '';
+  let evidencePushRequired = false;
+  if (archiveReport.projectRecapExport != null) {
+    const sourceRunRoot = archiveReport.projectRecapExport?.sourceRunRoot;
+    const exportRoot = archiveReport.projectRecapExport?.exportRoot;
+    const manifestPath =
+      archiveReport.projectRecapExport?.manifest?.relativePath;
+    if (
+      typeof sourceRunRoot !== 'string' ||
+      typeof exportRoot !== 'string' ||
+      manifestPath !== 'manifest.json'
+    ) {
+      throw executionError(
+        'Archive resume report has an invalid project recap export receipt.',
+      );
+    }
+    selectedProjectRecapRun = relative(projectPath, sourceRunRoot)
+      .split(sep)
+      .join('/');
+    if (
+      selectedProjectRecapRun.length === 0 ||
+      /^\.\.(?:[/\\]|$)/.test(selectedProjectRecapRun) ||
+      isAbsolute(selectedProjectRecapRun)
+    ) {
+      throw executionError(
+        'Archive resume recap source is outside the original project path.',
+      );
+    }
+    const exportRootRelative = relative(repoRoot, exportRoot)
+      .split(sep)
+      .join('/');
+    if (
+      exportRootRelative.length === 0 ||
+      /^\.\.(?:[/\\]|$)/.test(exportRootRelative) ||
+      isAbsolute(exportRootRelative)
+    ) {
+      throw executionError(
+        'Archive resume recap export is outside the repository root.',
+      );
+    }
+    exportedManifestPath = posix.join(exportRootRelative, manifestPath);
+    exportedBuildRecordPath = posix.join(
+      exportRootRelative,
+      'build-record.json',
+    );
+    const recoveredEvidence = await recoverArchiveEvidence({
+      repoRoot,
+      lifecycleCommit: archiveReport.lifecycleCommit,
+      evidencePaths: [exportedManifestPath, exportedBuildRecordPath],
+    });
+    if (recoveredEvidence.evidenceCommit !== null) {
+      evidenceCommit = recoveredEvidence.evidenceCommit;
+      evidencePushRequired = recoveredEvidence.evidencePushRequired;
+    }
+  }
+  return {
+    required: true,
+    rejoinStep: '8.5',
+    archivePath: archiveReport.archivePath,
+    summaryExportFile: archiveReport.summaryExportFile ?? '',
+    lifecycleCommit: archiveReport.lifecycleCommit,
+    s3Path: archiveReport.s3Path ?? '',
+    selectedProjectRecapRun,
+    projectRecapExport: archiveReport.projectRecapExport ?? null,
+    exportedManifestPath,
+    exportedBuildRecordPath,
+    evidenceCommit,
+    evidencePushRequired,
+  };
+}
+
+export async function continueSyncedArchiveCompletion({
+  executionResult,
+  finalizeLinks,
+  refreshDashboard,
+  attestRecap,
+  pushBookkeeping,
+  closeoutPr,
+  clearPointer,
+  confirmCompletion,
+}) {
+  if (
+    executionResult?.route !== 'archive-resumed' ||
+    executionResult?.terminal !== true ||
+    executionResult?.terminalReceiptValidated !== true ||
+    executionResult?.continuation?.required !== true
+  ) {
+    throw executionError(
+      'Post-archive continuation requires a finalized archive-resume result.',
+    );
+  }
+  await finalizeLinks(executionResult.continuation);
+  await refreshDashboard(executionResult.continuation);
+  if (
+    executionResult.continuation.projectRecapExport !== null &&
+    executionResult.continuation.evidenceCommit === ''
+  ) {
+    await attestRecap(executionResult.continuation);
+  }
+  await pushBookkeeping(executionResult.continuation);
+  await closeoutPr(executionResult.continuation);
+  await clearPointer(executionResult.archiveReport);
+  await confirmCompletion(executionResult.continuation);
+  return {
+    status: 'ok',
+    route: 'completion-confirmed',
+    lifecycleCommit: executionResult.continuation.lifecycleCommit,
+  };
+}
+
+export async function executeSyncedArchiveEntry({
+  record,
+  projectName,
+  projectPath,
+  repoRoot,
+  probeRefs,
+  pullProject,
+  runActiveWorkflowSteps,
+  archiveProject,
+  validateArchive,
+  recoverArchiveEvidence = recoverArchivedRecapEvidenceReceipt,
+}) {
+  const entry = record
+    ? await resolveSyncedArchiveEntry({
+        record,
+        projectName,
+        repoRoot,
+        ...(probeRefs ? { probeRefs } : {}),
+      })
+    : {
+        status: 'ok',
+        route: 'archive-resume',
+        terminal: true,
+        archiveSnapshot: null,
+        verifiedSourceSha: null,
+      };
+
+  if (entry.route === 'pull') {
+    await pullProject(projectPath);
+    await runActiveWorkflowSteps();
+    return {
+      status: 'ok',
+      route: 'continue-active',
+      terminal: false,
+      skippedActiveSteps: false,
+    };
+  }
+
+  const archiveReport = await archiveProject(projectPath, {
+    ...(entry.archiveSnapshot
+      ? {
+          archiveSnapshot: entry.archiveSnapshot,
+          verifiedSourceSha: entry.verifiedSourceSha,
+        }
+      : { recordless: true }),
+  });
+  if (entry.archiveSnapshot) {
+    if (
+      archiveReport?.snapshotId !== entry.archiveSnapshot ||
+      archiveReport?.verifiedSourceSha !== entry.verifiedSourceSha
+    ) {
+      throw executionError(
+        'Archive resume report does not match the persisted snapshot identity.',
+      );
+    }
+  } else if (
+    typeof archiveReport?.snapshotId !== 'string' ||
+    archiveReport.snapshotId.length === 0
+  ) {
+    throw executionError(
+      'Recordless archive resume report has no persisted snapshot identity.',
+    );
+  }
+  await validateArchive({
+    archiveReport,
+    projectName,
+  });
+  return {
+    status: 'ok',
+    route: 'archive-resumed',
+    terminal: true,
+    skippedActiveSteps: true,
+    archiveSnapshot: archiveReport.snapshotId,
+    archiveReport,
+    terminalReceiptValidated: true,
+    continuation: await buildPostArchiveContinuation(
+      archiveReport,
+      projectPath,
+      repoRoot,
+      recoverArchiveEvidence,
+    ),
+  };
+}
+
+function parseArguments(argv) {
+  const result = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw executionError(`Missing value for ${flag ?? 'argument'}.`);
+    }
+    if (flag === '--repo-root') result.repoRoot = value;
+    else if (flag === '--record-path') result.recordPath = value;
+    else if (flag === '--project-name') result.projectName = value;
+    else if (flag === '--project-path') result.projectPath = value;
+    else throw executionError(`Unsupported argument: ${flag}.`);
+  }
+  for (const field of [
+    'repoRoot',
+    'recordPath',
+    'projectName',
+    'projectPath',
+  ]) {
+    if (!result[field]) throw executionError(`Missing required ${field}.`);
+  }
+  return result;
+}
+
+async function readRecord(recordPath) {
+  try {
+    return JSON.parse(await readFile(recordPath, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw executionError(
+      `Unable to read synced discovery record: ${error.message}`,
+    );
+  }
+}
+
+async function runOat(args, cwd) {
+  try {
+    return await execFile('oat', args, { cwd });
+  } catch (error) {
+    throw executionError(`oat ${args.join(' ')} failed: ${error.message}`);
+  }
+}
+
+async function main(argv) {
+  const options = parseArguments(argv);
+  const record = await readRecord(options.recordPath);
+  return executeSyncedArchiveEntry({
+    ...options,
+    record,
+    pullProject: async (projectPath) => {
+      await runOat(['project', 'pull', projectPath], options.repoRoot);
+    },
+    runActiveWorkflowSteps: async () => undefined,
+    archiveProject: async (projectPath) => {
+      const { stdout } = await runOat(
+        ['project', 'archive', projectPath, '--json'],
+        options.repoRoot,
+      );
+      try {
+        return JSON.parse(stdout);
+      } catch (error) {
+        throw executionError(
+          `Unable to parse synced archive report: ${error.message}`,
+        );
+      }
+    },
+    validateArchive: async ({ archiveReport, projectName }) =>
+      validateSyncedArchiveTerminalReport(archiveReport, projectName),
+  });
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main(process.argv.slice(2))
+    .then((result) => process.stdout.write(`${JSON.stringify(result)}\n`))
+    .catch((error) => {
+      process.stderr.write(
+        `${JSON.stringify({ ok: false, code: error.code, message: error.message })}\n`,
+      );
+      process.exitCode = 1;
+    });
+}

package/assets/skills/oat-project-complete/scripts/finalize-synced-archive.mjs

@@ -0,0 +1,125 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCallback);
+
+function finalizationError(message) {
+  const error = new Error(message);
+  error.code = 'E_SYNCED_ARCHIVE_FINALIZATION';
+  return error;
+}
+
+function requireFullSha(value, field) {
+  if (typeof value !== 'string' || !/^[0-9a-f]{40}$/.test(value)) {
+    throw finalizationError(
+      `Synced archive terminal report requires a full ${field} SHA.`,
+    );
+  }
+}
+
+export function validateSyncedArchiveTerminalReport(report, projectName) {
+  if (!report || typeof report !== 'object' || Array.isArray(report)) {
+    throw finalizationError(
+      'Synced archive finalization requires a structured terminal report.',
+    );
+  }
+  if (
+    report.status !== 'ok' ||
+    report.mode !== 'apply' ||
+    typeof report.archivePath !== 'string' ||
+    report.archivePath.length === 0
+  ) {
+    throw finalizationError(
+      'Synced archive terminal report is not a successful durable apply result.',
+    );
+  }
+  requireFullSha(report.lifecycleCommit, 'lifecycleCommit');
+  requireFullSha(report.verifiedSourceSha, 'verifiedSourceSha');
+  if (report.completedRef !== `refs/oat/completed/${projectName}`) {
+    throw finalizationError(
+      'Synced archive terminal report names an unexpected completed ref.',
+    );
+  }
+  if (!['removed', 'retained'].includes(report.activeAliasDisposition)) {
+    throw finalizationError(
+      'Synced archive terminal report has no verified active-alias disposition.',
+    );
+  }
+  if (report.recordRetired !== true) {
+    throw finalizationError(
+      'Synced archive terminal report does not verify discovery-record retirement.',
+    );
+  }
+  return report;
+}
+
+export async function finalizeSyncedArchive({
+  getArchiveReport,
+  projectName,
+  clearActiveProject,
+}) {
+  const report = validateSyncedArchiveTerminalReport(
+    await getArchiveReport(),
+    projectName,
+  );
+  await clearActiveProject();
+  return {
+    status: 'ok',
+    pointerCleared: true,
+    lifecycleCommit: report.lifecycleCommit,
+    completedRef: report.completedRef,
+    verifiedSourceSha: report.verifiedSourceSha,
+    activeAliasDisposition: report.activeAliasDisposition,
+    recordRetired: report.recordRetired,
+  };
+}
+
+function parseArguments(argv) {
+  if (argv.length !== 2 || argv[0] !== '--project-name' || !argv[1]) {
+    throw finalizationError(
+      'Usage: finalize-synced-archive.mjs --project-name <name>',
+    );
+  }
+  return { projectName: argv[1] };
+}
+
+async function main(argv) {
+  const { projectName } = parseArguments(argv);
+  return finalizeSyncedArchive({
+    projectName,
+    getArchiveReport: async () => {
+      try {
+        return JSON.parse(await readFile(0, 'utf8'));
+      } catch (error) {
+        throw finalizationError(
+          `Unable to parse synced archive terminal report: ${error.message}`,
+        );
+      }
+    },
+    clearActiveProject: async () => {
+      try {
+        await execFile('oat', ['config', 'set', 'activeProject', '']);
+      } catch (error) {
+        throw finalizationError(
+          `Unable to clear the active project pointer: ${error.message}`,
+        );
+      }
+    },
+  });
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main(process.argv.slice(2))
+    .then((result) => process.stdout.write(`${JSON.stringify(result)}\n`))
+    .catch((error) => {
+      process.stderr.write(
+        `${JSON.stringify({ ok: false, code: error.code, message: error.message })}\n`,
+      );
+      process.exitCode = 1;
+    });
+}

package/assets/skills/oat-project-complete/scripts/parse-synced-archive-resume-fields.mjs

@@ -0,0 +1,106 @@
+import { pathToFileURL } from 'node:url';
+
+function fieldsError(message) {
+  const error = new Error(message);
+  error.code = 'E_SYNCED_ARCHIVE_RESUME_FIELDS';
+  return error;
+}
+
+function shellQuote(value) {
+  return `'${String(value).split("'").join("'\\''")}'`;
+}
+
+export function parseSyncedArchiveResumeFields(result) {
+  const continuation = result?.continuation;
+  const hasRecapExport = continuation?.projectRecapExport !== null;
+  if (
+    result?.status !== 'ok' ||
+    result?.route !== 'archive-resumed' ||
+    result?.terminal !== true ||
+    result?.skippedActiveSteps !== true ||
+    result?.terminalReceiptValidated !== true ||
+    continuation?.required !== true ||
+    continuation?.rejoinStep !== '8.5' ||
+    typeof continuation.archivePath !== 'string' ||
+    continuation.archivePath.length === 0 ||
+    typeof continuation.lifecycleCommit !== 'string' ||
+    !/^[0-9a-f]{40}$/.test(continuation.lifecycleCommit) ||
+    typeof continuation.evidenceCommit !== 'string' ||
+    (continuation.evidenceCommit !== '' &&
+      !/^[0-9a-f]{40}$/.test(continuation.evidenceCommit)) ||
+    typeof continuation.evidencePushRequired !== 'boolean' ||
+    (continuation.evidenceCommit === '' &&
+      continuation.evidencePushRequired !== false) ||
+    (hasRecapExport &&
+      (typeof continuation.exportedManifestPath !== 'string' ||
+        continuation.exportedManifestPath.length === 0 ||
+        typeof continuation.exportedBuildRecordPath !== 'string' ||
+        continuation.exportedBuildRecordPath.length === 0)) ||
+    (!hasRecapExport &&
+      (continuation.exportedManifestPath !== '' ||
+        continuation.exportedBuildRecordPath !== '' ||
+        continuation.evidenceCommit !== ''))
+  ) {
+    throw fieldsError(
+      'Synced archive resume result has no verified post-archive continuation.',
+    );
+  }
+  return {
+    SYNCED_ARCHIVE_RESUME: 'true',
+    SHOULD_ARCHIVE: 'true',
+    IS_DURABLE_PROJECT: 'true',
+    ARCHIVE_OUTPUT: JSON.stringify(result.archiveReport),
+    ARCHIVE_PATH: continuation.archivePath,
+    PROJECT_PATH: continuation.archivePath,
+    SUMMARY_EXPORT_FILE: continuation.summaryExportFile ?? '',
+    LIFECYCLE_COMMIT: continuation.lifecycleCommit,
+    ARCHIVE_S3_PATH: continuation.s3Path ?? '',
+    SELECTED_PROJECT_RECAP_RUN: continuation.selectedProjectRecapRun ?? '',
+    PROJECT_RECAP_EXPORT_JSON: JSON.stringify(
+      continuation.projectRecapExport ?? null,
+    ),
+    EVIDENCE_COMMIT: continuation.evidenceCommit,
+    EVIDENCE_PUSH_REQUIRED: String(continuation.evidencePushRequired),
+    EXPORTED_MANIFEST_PATH: continuation.exportedManifestPath,
+    EXPORTED_BUILD_RECORD_PATH: continuation.exportedBuildRecordPath,
+    PROJECT_REF_COMMIT: '',
+    SHOULD_OPEN_PR: 'false',
+  };
+}
+
+export function formatShellAssignments(fields) {
+  return Object.entries(fields)
+    .map(([name, value]) => `${name}=${shellQuote(value)}`)
+    .join('\n');
+}
+
+function main(argv) {
+  if (argv.length !== 1) {
+    throw fieldsError(
+      'Usage: parse-synced-archive-resume-fields.mjs <executor-json>',
+    );
+  }
+  let result;
+  try {
+    result = JSON.parse(argv[0]);
+  } catch (error) {
+    throw fieldsError(
+      `Unable to parse archive resume result: ${error.message}`,
+    );
+  }
+  return formatShellAssignments(parseSyncedArchiveResumeFields(result));
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    process.stdout.write(`${main(process.argv.slice(2))}\n`);
+  } catch (error) {
+    process.stderr.write(
+      `${JSON.stringify({ ok: false, code: error.code, message: error.message })}\n`,
+    );
+    process.exitCode = 1;
+  }
+}

package/assets/skills/oat-project-complete/scripts/recover-completion-receipts.mjs

@@ -91,6 +91,23 @@ async function changedPaths(projectPath, commit) {
   return output === '' ? [] : output.split('\n').sort();
 }
 
+async function isAncestor(projectPath, ancestor, descendant) {
+  try {
+    await execFileAsync(
+      'git',
+      ['merge-base', '--is-ancestor', ancestor, descendant],
+      { cwd: projectPath, encoding: 'utf8' },
+    );
+    return true;
+  } catch (error) {
+    if (error?.code === 1) return false;
+    const detail = error?.stderr?.trim() || error?.message || String(error);
+    throw completionReceiptError(
+      `git merge-base failed while recovering completion receipts: ${detail}`,
+    );
+  }
+}
+
 async function committedFile(projectPath, commit, path, label) {
   const content = await git(projectPath, ['show', `${commit}:${path}`], {
     allowFailure: true,
@@ -698,6 +715,99 @@ export async function recoverCompletionReceipts({
   };
 }
 
+export async function recoverArchivedRecapEvidenceReceipt({
+  repoRoot,
+  lifecycleCommit,
+  evidencePaths,
+}) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
+    throw completionReceiptError(
+      'Archived recap evidence recovery requires the repository root.',
+    );
+  }
+  if (!FULL_SHA.test(lifecycleCommit ?? '')) {
+    throw completionReceiptError(
+      'Archived recap evidence recovery requires a full lifecycle commit SHA.',
+    );
+  }
+  if (!Array.isArray(evidencePaths) || evidencePaths.length !== 2) {
+    throw completionReceiptError(
+      'Archived recap evidence recovery requires exactly two evidence paths.',
+    );
+  }
+  const exactEvidencePaths = evidencePaths.map((path, index) =>
+    requireRelativeGitPath(path, `Archived evidence path ${index + 1}`),
+  );
+  if (new Set(exactEvidencePaths).size !== exactEvidencePaths.length) {
+    throw completionReceiptError('Archived evidence paths must be unique.');
+  }
+
+  const resolvedLifecycle = await git(repoRoot, [
+    'rev-parse',
+    '--verify',
+    `${lifecycleCommit}^{commit}`,
+  ]);
+  if (resolvedLifecycle !== lifecycleCommit) {
+    throw completionReceiptError(
+      'Archived recap lifecycle receipt does not resolve to the exact commit.',
+    );
+  }
+  const head = await git(repoRoot, ['rev-parse', 'HEAD']);
+  if (head === lifecycleCommit) {
+    return {
+      status: 'none',
+      evidenceCommit: null,
+      evidencePushRequired: false,
+      evidencePaths: exactEvidencePaths,
+    };
+  }
+  if ((await commitSubject(repoRoot, head)) !== EVIDENCE_MESSAGE) {
+    throw completionReceiptError(
+      'Archived recap retry HEAD is neither the lifecycle commit nor the exact evidence commit.',
+    );
+  }
+  if (
+    (await singleParent(repoRoot, head, 'Archived recap evidence commit')) !==
+    lifecycleCommit
+  ) {
+    throw completionReceiptError(
+      'Archived recap evidence commit must be the immediate child of the lifecycle commit.',
+    );
+  }
+  requireExactPaths(
+    await changedPaths(repoRoot, head),
+    exactEvidencePaths,
+    'Archived recap evidence commit',
+  );
+
+  const upstream = await git(
+    repoRoot,
+    ['rev-parse', '--verify', '@{u}^{commit}'],
+    { allowFailure: true },
+  );
+  let evidencePushRequired;
+  if (upstream === head) {
+    evidencePushRequired = false;
+  } else if (
+    upstream === null ||
+    (FULL_SHA.test(upstream) &&
+      (await isAncestor(repoRoot, upstream, lifecycleCommit)))
+  ) {
+    evidencePushRequired = true;
+  } else {
+    throw completionReceiptError(
+      'Archived recap evidence retry requires upstream to equal the evidence commit or remain an ancestor of its lifecycle parent.',
+    );
+  }
+
+  return {
+    status: 'recovered',
+    evidenceCommit: head,
+    evidencePushRequired,
+    evidencePaths: exactEvidencePaths,
+  };
+}
+
 function parseBoolean(value, label) {
   if (value === 'true') return true;
   if (value === 'false') return false;