@open-agent-toolkit/cli 0.2.41 → 0.2.46

package/dist/commands/project/archive/archive-utils.js

@@ -1,8 +1,12 @@
 import { execFile as execFileCallback } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { lstat, readFile, realpath, rename, rm, writeFile, } from 'node:fs/promises';
+import { lstat, readFile, readdir, realpath, rename, rm, writeFile, } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, posix as path, relative, resolve, sep, } from 'node:path';
 import { promisify } from 'node:util';
+import { defaultGitRunner } from '../../project/sync/git.js';
+import { readSyncedRecord, writeSyncedRecord, } from '../../project/sync/record.js';
+import { buildSyncTarget, commitRecordChange, preflightSyncedCheckout, removeSyncedCheckout, } from '../../project/sync/ref-sync.js';
+import { canonicalizePath, resolveProjectScope, resolveScopeRoot, syncedRecordPath, } from '../../shared/project-scope.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { copyDirectory, copySingleFile, dirExists, ensureDir, fileExists, } from '../../../fs/io.js';
 import { loadExplainerPackageCoverage } from './explainer-package-coverage.js';
@@ -15,6 +19,19 @@ export const ARCHIVE_SNAPSHOT_METADATA_FILENAME = '.oat-archive-source.json';
  * (reviews, PR descriptions) rather than project deliverables.
  */
 export const S3_ARCHIVE_SYNC_EXCLUDES = ['reviews/*', 'pr/*'];
+export function assertExactArchiveProjectRoot(options) {
+    const projectScope = resolveProjectScope(options.projectPath, resolveScopeRoot(options.repoRoot, options.projectsRoot, 'shared'), options.repoRoot);
+    if (!projectScope) {
+        throw new CliError(`Project path \`${options.projectPath}\` is outside the configured shared, local, and synced scope roots; refusing to archive without an originating scope.`, 1);
+    }
+    const scopeRoot = canonicalizePath(resolveScopeRoot(options.repoRoot, options.projectsRoot, projectScope));
+    const projectPath = canonicalizePath(options.projectPath);
+    if (dirname(projectPath) !== scopeRoot ||
+        basename(projectPath) !== options.projectName) {
+        throw new CliError(`Project path \`${options.projectPath}\` must identify the exact direct child \`${options.projectName}\` of the configured ${projectScope} project root; refusing to archive a descendant or mismatched project.`, 1);
+    }
+    return { canonicalProjectPath: projectPath, projectScope };
+}
 function normalizeS3Uri(s3Uri) {
     return s3Uri.trim().replace(/\/+$/, '');
 }
@@ -220,6 +237,47 @@ async function resolveUniqueArchivePath(archivePath, dependencies) {
     const suffix = timestamp.replace(/[-:TZ.]/g, '').slice(0, 15);
     return `${archivePath}-${suffix}`;
 }
+async function archiveMatchesSnapshot(archivePath, projectName, snapshotName, archiveScope, dependencies) {
+    const directoryExists = dependencies.dirExists ?? dirExists;
+    if (!(await directoryExists(archivePath))) {
+        return false;
+    }
+    try {
+        const metadata = JSON.parse(await readFile(join(archivePath, ARCHIVE_SNAPSHOT_METADATA_FILENAME), 'utf8'));
+        return (isRecord(metadata) &&
+            metadata.projectName === projectName &&
+            metadata.snapshotName === snapshotName &&
+            metadata.scope === archiveScope);
+    }
+    catch {
+        return false;
+    }
+}
+async function resolvePersistedArchivePath(archiveBasePath, projectName, snapshotName, archiveScope, dependencies) {
+    const archiveRoot = dirname(archiveBasePath);
+    const candidates = [archiveBasePath];
+    try {
+        const entries = await readdir(archiveRoot, { withFileTypes: true });
+        candidates.push(...entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(archiveRoot, entry.name))
+            .filter((candidate) => candidate !== archiveBasePath)
+            .sort());
+    }
+    catch {
+        // The archive root can be absent before the first successful copy.
+    }
+    const matches = [];
+    for (const candidate of candidates) {
+        if (await archiveMatchesSnapshot(candidate, projectName, snapshotName, archiveScope, dependencies)) {
+            matches.push(candidate);
+        }
+    }
+    if (matches.length > 1) {
+        throw new CliError(`Persisted archive snapshot \`${snapshotName}\` resolves to multiple local archives; refusing an ambiguous retry.`);
+    }
+    return matches[0] ?? join(archiveRoot, snapshotName);
+}
 function buildLocalOnlyArchiveWarning(projectName, archiveProjectPath, primaryRepoRoot) {
     const primaryMessage = primaryRepoRoot
         ? `the primary checkout \`${primaryRepoRoot}\` is unavailable`
@@ -251,10 +309,19 @@ export async function resolveArchiveProjectTarget(options, dependencies = {}) {
         }
     }
     const archiveBasePath = resolveCompletionArchivePath(archiveRepoRoot, archiveProjectPath);
-    const archivePath = await resolveUniqueArchivePath(archiveBasePath, {
-        dirExists: dependencies.dirExists,
-        timestamp: dependencies.timestamp,
-    });
+    let archivePath;
+    if (options.archiveSnapshot) {
+        if (!options.archiveScope) {
+            throw new CliError(`Persisted archive snapshot \`${options.archiveSnapshot}\` is missing its originating project scope; refusing an unscoped retry.`);
+        }
+        archivePath = await resolvePersistedArchivePath(archiveBasePath, options.projectName, options.archiveSnapshot, options.archiveScope, dependencies);
+    }
+    else {
+        archivePath = await resolveUniqueArchivePath(archiveBasePath, {
+            dirExists: dependencies.dirExists,
+            timestamp: dependencies.timestamp,
+        });
+    }
     return {
         archiveProjectPath,
         archiveRepoRoot,
@@ -273,6 +340,22 @@ export function assertDurableArchiveProjectTarget(target) {
 async function writeArchiveSnapshotMetadata(archivePath, metadata) {
     await writeFile(join(archivePath, ARCHIVE_SNAPSHOT_METADATA_FILENAME), `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
 }
+async function verifyArchiveSnapshotMetadata(archivePath, expected) {
+    let actual;
+    try {
+        actual = JSON.parse(await readFile(join(archivePath, ARCHIVE_SNAPSHOT_METADATA_FILENAME), 'utf8'));
+    }
+    catch {
+        throw new CliError(`Existing archive \`${archivePath}\` cannot be verified for retry; restore or remove it before retrying.`);
+    }
+    if (!isRecord(actual) ||
+        actual.projectName !== expected.projectName ||
+        actual.snapshotName !== expected.snapshotName ||
+        actual.scope !== expected.scope ||
+        actual.sourceRefSha !== expected.sourceRefSha) {
+        throw new CliError(`Existing archive \`${archivePath}\` does not match persisted snapshot \`${expected.snapshotName}\`; refusing to overwrite it.`);
+    }
+}
 async function exportProjectSummary(archivePath, snapshotName, summaryExportPath, repoRoot, dependencies) {
     const summarySource = join(archivePath, 'summary.md');
     const exists = dependencies.fileExists ?? fileExists;
@@ -281,6 +364,16 @@ async function exportProjectSummary(archivePath, snapshotName, summaryExportPath
     }
     const summaryTarget = join(repoRoot, summaryExportPath, `${snapshotName}.md`);
     const copySummary = dependencies.copySingleFile ?? copySingleFile;
+    if (await pathExists(summaryTarget)) {
+        const [sourceContents, targetContents] = await Promise.all([
+            readFile(summarySource),
+            readFile(summaryTarget),
+        ]);
+        if (!sourceContents.equals(targetContents)) {
+            throw new CliError(`Existing summary export \`${summaryTarget}\` does not match persisted snapshot \`${snapshotName}\`; refusing to overwrite it.`);
+        }
+        return summaryTarget;
+    }
     await copySummary(summarySource, summaryTarget);
     return summaryTarget;
 }
@@ -659,7 +752,37 @@ async function exportSelectedProjectRecap(options, snapshotName, dependencies) {
     const { sourceRunRoot, manifestContents: sourceManifestContents, terminalEvidence: sourceTerminalEvidence, packagePaths, } = verified;
     const exportRoot = join(options.repoRoot, '.oat', 'repo', 'reference', 'project-recaps', snapshotName);
     if (await pathExists(exportRoot)) {
-        throw new CliError(`Project recap export destination \`${exportRoot}\` already exists; refusing to overwrite it.`);
+        let exportedManifestContents;
+        try {
+            exportedManifestContents = await readFile(join(exportRoot, 'manifest.json'), 'utf8');
+        }
+        catch {
+            throw new CliError(`Project recap export destination \`${exportRoot}\` already exists and cannot be verified for retry.`);
+        }
+        if (exportedManifestContents !== sourceManifestContents) {
+            throw new CliError(`Existing project recap export \`${exportRoot}\` does not match persisted snapshot \`${snapshotName}\`.`);
+        }
+        const exportedManifest = await parseProjectRecapManifest(exportedManifestContents);
+        const verifiedArtifactCount = await verifyProjectRecapImmutableHashes(exportRoot, exportedManifest);
+        await verifyProjectRecapTerminalEvidence(exportRoot, exportedManifest, sourceTerminalEvidence ?? undefined);
+        const exactCoverage = (await loadExplainerPackageCoverage());
+        try {
+            await exactCoverage.enforceRunPackageInventory(exportRoot, exportedManifest, { includeTerminalEvidence: sourceTerminalEvidence !== null });
+        }
+        catch {
+            throw new CliError(`Existing project recap export \`${exportRoot}\` has invalid content.`);
+        }
+        return {
+            export: {
+                sourceRunRoot,
+                exportRoot,
+                manifest: {
+                    relativePath: 'manifest.json',
+                    verifiedArtifactCount,
+                },
+            },
+            createdByAttempt: false,
+        };
     }
     const temporaryRoot = `${exportRoot}.tmp-${randomUUID()}`;
     const makeDir = dependencies.ensureDir ?? ensureDir;
@@ -692,12 +815,15 @@ async function exportSelectedProjectRecap(options, snapshotName, dependencies) {
         }
         await renamePath(temporaryRoot, exportRoot);
         return {
-            sourceRunRoot,
-            exportRoot,
-            manifest: {
-                relativePath: 'manifest.json',
-                verifiedArtifactCount,
+            export: {
+                sourceRunRoot,
+                exportRoot,
+                manifest: {
+                    relativePath: 'manifest.json',
+                    verifiedArtifactCount,
+                },
             },
+            createdByAttempt: true,
         };
     }
     catch (error) {
@@ -714,26 +840,127 @@ export async function archiveProjectOnCompletion(options, dependencies = {}) {
     const execFile = dependencies.execFile ?? execFileAsync;
     const timestamp = dependencies.timestamp?.() ?? new Date().toISOString();
     const snapshotName = buildArchiveSnapshotName(options.projectName, timestamp);
+    const syncedRoot = resolveScopeRoot(options.repoRoot, options.projectsRoot, 'synced');
+    const recordPath = syncedRecordPath(syncedRoot, options.projectName);
+    const readRecord = dependencies.readSyncedRecord ?? readSyncedRecord;
+    const writeRecord = dependencies.writeSyncedRecord ?? writeSyncedRecord;
+    const { canonicalProjectPath, projectScope } = assertExactArchiveProjectRoot(options);
+    const isSynced = projectScope === 'synced';
+    const record = isSynced ? await readRecord(recordPath) : null;
+    const syncTarget = isSynced
+        ? buildSyncTarget(options.repoRoot, options.projectsRoot, options.projectName)
+        : null;
+    const git = dependencies.gitRunner ?? defaultGitRunner;
+    let activeRecord = record;
+    let sourceRefSha;
+    if (syncTarget) {
+        if (!activeRecord) {
+            throw new CliError(`Synced project ${options.projectName} is missing its discovery record; restore the record or run oat project pull ${options.projectName} from a clean checkout to adopt the project before archiving.`, 2);
+        }
+        const preflight = await (dependencies.preflightSyncedCheckout ?? preflightSyncedCheckout)(syncTarget, git);
+        if (preflight.status !== 'clean' &&
+            !(preflight.status === 'absent' && activeRecord.status === 'complete')) {
+            const recoveryCommand = preflight.status === 'absent'
+                ? `oat project pull ${options.projectName}`
+                : `oat project push ${options.projectName}`;
+            throw new CliError(`Synced project ${options.projectName} is ${preflight.status}; run ${recoveryCommand} before archiving.`, 1);
+        }
+        sourceRefSha =
+            preflight.sha ??
+                (await git.run(['rev-parse', syncTarget.ref], { cwd: options.repoRoot }))
+                    .stdout;
+        if (!/^[0-9a-f]{40}$/.test(sourceRefSha)) {
+            throw new CliError(`Unable to bind archive retry identity for ${options.projectName} to ${syncTarget.ref}.`, 2);
+        }
+        if (activeRecord.archiveSourceRefSha &&
+            activeRecord.archiveSourceRefSha !== sourceRefSha) {
+            throw new CliError(`Archive retry for ${options.projectName} is bound to source ref ${activeRecord.archiveSourceRefSha}, but ${syncTarget.ref} is now ${sourceRefSha}. Restore the retained ref to the recorded commit to finish this archive transaction, or preserve the existing snapshot and start a separately reviewed recovery; refusing to accept stale archive content.`, 1);
+        }
+    }
     const archiveTarget = await resolveArchiveProjectTarget({
         repoRoot: options.repoRoot,
         projectsRoot: options.projectsRoot,
         projectName: options.projectName,
+        ...(activeRecord?.archiveSnapshot
+            ? {
+                archiveSnapshot: activeRecord.archiveSnapshot,
+                archiveScope: projectScope,
+            }
+            : {}),
     }, dependencies);
     assertDurableArchiveProjectTarget(archiveTarget);
+    // Reassert the identity immediately before the first durable mutation. The
+    // archive transaction must never bind a descendant source to a sibling
+    // record/ref that merely shares its basename.
+    if (assertExactArchiveProjectRoot(options).canonicalProjectPath !==
+        canonicalProjectPath) {
+        throw new CliError(`Project path \`${options.projectPath}\` changed identity during archive preflight; refusing to mutate archive state.`, 1);
+    }
+    if (syncTarget &&
+        canonicalProjectPath !== canonicalizePath(syncTarget.projectPath)) {
+        throw new CliError(`Synced archive identity for ${options.projectName} does not match its canonical checkout, record, and ref.`, 1);
+    }
     const archivePath = archiveTarget.archivePath;
-    const projectRecapExport = await exportSelectedProjectRecap(options, snapshotName, dependencies);
-    try {
-        await makeDir(dirname(archivePath));
-        await copyProjectDirectory(options.projectPath, archivePath);
-        await writeArchiveSnapshotMetadata(archivePath, {
+    const exportIdentity = syncTarget
+        ? (activeRecord?.archiveSnapshot ?? snapshotName)
+        : snapshotName;
+    const snapshotId = syncTarget ? exportIdentity : basename(archivePath);
+    const shouldPersistArchiveSnapshot = Boolean(syncTarget &&
+        activeRecord &&
+        (!activeRecord.archiveSnapshot || !activeRecord.archiveSourceRefSha));
+    if (shouldPersistArchiveSnapshot && activeRecord) {
+        activeRecord = {
+            ...activeRecord,
+            archiveSnapshot: exportIdentity,
+            archiveSourceRefSha: sourceRefSha,
+        };
+        await writeRecord(recordPath, activeRecord);
+    }
+    const archiveExists = await (dependencies.dirExists ?? dirExists)(archivePath);
+    if (archiveExists) {
+        await verifyArchiveSnapshotMetadata(archivePath, {
             projectName: options.projectName,
-            snapshotName,
+            snapshotName: exportIdentity,
+            scope: projectScope,
+            ...(sourceRefSha ? { sourceRefSha } : {}),
         });
-        await removePath(options.projectPath, { recursive: true, force: true });
+    }
+    const projectSourcePath = (await pathExists(options.projectPath))
+        ? options.projectPath
+        : archivePath;
+    const attemptedProjectRecapExport = await exportSelectedProjectRecap({ ...options, projectPath: projectSourcePath }, exportIdentity, dependencies);
+    const projectRecapExport = attemptedProjectRecapExport?.export ?? null;
+    if (!archiveExists) {
+        try {
+            await makeDir(dirname(archivePath));
+            await copyProjectDirectory(options.projectPath, archivePath, (_sourcePath, relativePath) => relativePath !== 'reviews' &&
+                (!syncTarget || relativePath !== '.git'));
+            await writeArchiveSnapshotMetadata(archivePath, {
+                projectName: options.projectName,
+                snapshotName: exportIdentity,
+                scope: projectScope,
+                ...(sourceRefSha ? { sourceRefSha } : {}),
+            });
+        }
+        catch (error) {
+            await removePath(archivePath, { recursive: true, force: true });
+            if (attemptedProjectRecapExport?.createdByAttempt) {
+                await removePath(attemptedProjectRecapExport.export.exportRoot, {
+                    recursive: true,
+                    force: true,
+                });
+            }
+            throw error;
+        }
+    }
+    try {
+        if (!syncTarget) {
+            await removePath(options.projectPath, { recursive: true, force: true });
+        }
     }
     catch (error) {
-        if (projectRecapExport) {
-            await removePath(projectRecapExport.exportRoot, {
+        if (attemptedProjectRecapExport?.createdByAttempt) {
+            await removePath(attemptedProjectRecapExport.export.exportRoot, {
                 recursive: true,
                 force: true,
             });
@@ -744,10 +971,19 @@ export async function archiveProjectOnCompletion(options, dependencies = {}) {
     let summaryExportFile = null;
     if (options.summaryExportPath) {
         try {
-            summaryExportFile = await exportProjectSummary(archivePath, snapshotName, options.summaryExportPath, options.repoRoot, dependencies);
+            summaryExportFile = await exportProjectSummary(archivePath, exportIdentity, options.summaryExportPath, options.repoRoot, dependencies);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            if (syncTarget) {
+                if (attemptedProjectRecapExport?.createdByAttempt) {
+                    await removePath(attemptedProjectRecapExport.export.exportRoot, {
+                        recursive: true,
+                        force: true,
+                    });
+                }
+                throw new CliError(`Summary export to \`${options.summaryExportPath}\` failed: ${message}`, 1);
+            }
             warnings.push(`Summary export to \`${options.summaryExportPath}\` failed: ${message}`);
         }
     }
@@ -766,7 +1002,7 @@ export async function archiveProjectOnCompletion(options, dependencies = {}) {
         warnings.push(...access.warnings);
         if (access.ok) {
             const remoteRepoRoot = await resolvePrimaryRepoRoot(options.repoRoot, dependencies);
-            s3Path = buildProjectArchiveS3Uri(options.s3Uri, remoteRepoRoot, snapshotName);
+            s3Path = buildProjectArchiveS3Uri(options.s3Uri, remoteRepoRoot, exportIdentity);
             try {
                 const syncArgs = ['s3', 'sync', archivePath, s3Path];
                 for (const pattern of S3_ARCHIVE_SYNC_EXCLUDES) {
@@ -787,14 +1023,105 @@ export async function archiveProjectOnCompletion(options, dependencies = {}) {
             }
         }
     }
+    let lifecycleCommit = null;
+    let recapExportPaths = [];
+    if (syncTarget) {
+        if (!activeRecord) {
+            throw new CliError(`Synced project ${options.projectName} is missing its discovery record.`, 2);
+        }
+        if (projectRecapExport) {
+            recapExportPaths = (await listArchiveExportFiles(projectRecapExport.exportRoot)).filter((filePath) => basename(filePath) !== 'manifest.json' &&
+                basename(filePath) !== 'build-record.json');
+        }
+        activeRecord = {
+            ...activeRecord,
+            status: 'complete',
+            completedAt: activeRecord.completedAt ?? timestamp,
+        };
+        await writeRecord(recordPath, activeRecord);
+        if (options.commit !== false) {
+            const pathspecs = [
+                recordPath,
+                ...(summaryExportFile ? [summaryExportFile] : []),
+                ...recapExportPaths,
+            ];
+            const committed = await (dependencies.commitRecordChange ?? commitRecordChange)(options.repoRoot, pathspecs, `chore(oat): complete synced project ${options.projectName}`, git, {
+                summaryExportPath: options.summaryExportPath,
+                projectRoots: syncTarget,
+                recapExportRoot: projectRecapExport?.exportRoot,
+            });
+            lifecycleCommit =
+                committed?.sha ??
+                    (await recoverSyncedLifecycleCommit(options.repoRoot, pathspecs, activeRecord, `chore(oat): complete synced project ${options.projectName}`, git));
+        }
+        const removed = await (dependencies.removeSyncedCheckout ?? removeSyncedCheckout)(syncTarget, git);
+        if (removed.status !== 'removed' && removed.status !== 'absent') {
+            throw new CliError(`Synced checkout became ${removed.status} during archive; run oat project push ${options.projectName} and retry.`, 1);
+        }
+    }
     return {
         archivePath,
         s3Path,
         summaryExportFile,
         projectRecapExport,
         warnings,
+        lifecycleCommit,
+        recapExportPaths,
+        snapshotId,
     };
 }
+async function recoverSyncedLifecycleCommit(repoRoot, pathspecs, record, expectedSubject, git) {
+    const [recordPathspec] = pathspecs;
+    if (!recordPathspec) {
+        throw new CliError(`Unable to recover the prior lifecycle commit for ${record.slug}: no lifecycle paths were supplied.`, 2);
+    }
+    const recordPath = relative(resolve(repoRoot), resolve(recordPathspec))
+        .split(sep)
+        .join('/');
+    const normalizedPathspecs = pathspecs
+        .map((pathspec) => relative(resolve(repoRoot), resolve(pathspec)))
+        .map((pathspec) => pathspec.split(sep).join('/'))
+        .sort();
+    const candidate = (await git.run(['log', '-1', '--format=%H', '--', recordPath], {
+        cwd: repoRoot,
+    })).stdout;
+    if (!/^[0-9a-f]{40}$/.test(candidate)) {
+        throw new CliError(`Unable to recover the prior lifecycle commit for ${record.slug}.`, 2);
+    }
+    const subject = (await git.run(['show', '-s', '--format=%s', candidate], { cwd: repoRoot })).stdout;
+    const ancestor = await git.run(['merge-base', '--is-ancestor', candidate, 'HEAD'], { cwd: repoRoot, allowFailure: true });
+    const changedPaths = (await git.run(['diff-tree', '--no-commit-id', '--name-only', '-r', candidate], { cwd: repoRoot })).stdout
+        .split('\n')
+        .filter(Boolean)
+        .sort();
+    const contentsMatch = await git.run(['diff', '--quiet', candidate, '--', ...normalizedPathspecs], { cwd: repoRoot, allowFailure: true });
+    const committedRecord = await git.run(['show', `${candidate}:${recordPath}`], { cwd: repoRoot });
+    let parsedRecord;
+    try {
+        parsedRecord = JSON.parse(committedRecord.stdout);
+    }
+    catch {
+        parsedRecord = null;
+    }
+    if (subject !== expectedSubject ||
+        ancestor.code !== 0 ||
+        contentsMatch.code !== 0 ||
+        JSON.stringify(changedPaths) !== JSON.stringify(normalizedPathspecs) ||
+        JSON.stringify(parsedRecord) !== JSON.stringify(record)) {
+        throw new CliError(`Unable to recover lifecycle commit ${candidate} for ${record.slug}: subject, path set, contents, or branch relationship did not match the completed archive transaction.`, 2);
+    }
+    return candidate;
+}
+async function listArchiveExportFiles(root, current = root) {
+    const entries = await readdir(current, { withFileTypes: true });
+    const files = await Promise.all(entries.map(async (entry) => {
+        const entryPath = join(current, entry.name);
+        return entry.isDirectory()
+            ? listArchiveExportFiles(root, entryPath)
+            : [entryPath];
+    }));
+    return files.flat().sort();
+}
 export async function ensureS3ArchiveAccess(options, dependencies = {}) {
     if (!requiresRemoteAccess(options)) {
         return { ok: true, warnings: [] };

package/dist/commands/project/archive/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAIL,KAAK,qCAAqC,EAC3C,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,iCAAiC,EACvC,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,kBAAkB,EAClB,iCAAiC,GAClC,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,qCAAqC,GACtC,MAAM,eAAe,CAAC;AAEvB,KAAK,0BAA0B,GAAG,iCAAiC,GACjE,qCAAqC,CAAC;AAKxC,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CA6ET"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAIL,KAAK,qCAAqC,EAC3C,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,iCAAiC,EACvC,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,kBAAkB,EAClB,iCAAiC,GAClC,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,qCAAqC,GACtC,MAAM,eAAe,CAAC;AAEvB,KAAK,0BAA0B,GAAG,iCAAiC,GACjE,qCAAqC,CAAC;AAKxC,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAiFT"}

package/dist/commands/project/archive/index.js

@@ -13,6 +13,7 @@ export function createProjectArchiveCommand(overrides = {}) {
         .description('Manage archived project data')
         .argument('[project-path]', 'Project path to archive')
         .option('--dry-run', 'Preview archive without moving files or syncing S3')
+        .option('--no-commit', 'Manual/library use only: omit the synced lifecycle commit receipt')
         .option('--project-recap-run <path>', 'Export the selected project-relative recap run before archiving')
         .addHelpText('afterAll', '\nPull archived project data with `oat repo archive sync [project-name]`; `oat project archive sync` is deprecated.')
         .action(async (projectPath, options, command) => {

package/dist/commands/project/archive/push-runner.d.ts

@@ -1,9 +1,11 @@
 import { buildCommandContext, type CommandContext } from '../../../app/command-context.js';
+import { readSyncedRecord } from '../../project/sync/record.js';
 import { type OatConfig, type OatLocalConfig } from '../../../config/oat-config.js';
-import { resolveArchiveProjectTarget, resolvePrimaryRepoRoot, verifySelectedProjectRecapForArchive, type ArchiveProjectOnCompletionOptions, type ArchiveProjectOnCompletionResult } from './archive-utils.js';
+import { assertExactArchiveProjectRoot, resolveArchiveProjectTarget, resolvePrimaryRepoRoot, verifySelectedProjectRecapForArchive, type ArchiveProjectOnCompletionOptions, type ArchiveProjectOnCompletionResult } from './archive-utils.js';
 export interface ArchivePushOptions {
     dryRun?: boolean;
     projectRecapRun?: string;
+    commit?: boolean;
 }
 export interface ProjectArchivePushCommandDependencies {
     buildCommandContext: (options: Parameters<typeof buildCommandContext>[0]) => CommandContext;
@@ -13,8 +15,10 @@ export interface ProjectArchivePushCommandDependencies {
     resolveProjectsRoot: (repoRoot: string, env: NodeJS.ProcessEnv) => Promise<string>;
     resolvePrimaryRepoRoot: typeof resolvePrimaryRepoRoot;
     resolveArchiveProjectTarget: typeof resolveArchiveProjectTarget;
+    readSyncedRecord: typeof readSyncedRecord;
     verifySelectedProjectRecapForArchive: typeof verifySelectedProjectRecapForArchive;
     archiveProjectOnCompletion: (options: ArchiveProjectOnCompletionOptions) => Promise<ArchiveProjectOnCompletionResult>;
+    assertExactArchiveProjectRoot: typeof assertExactArchiveProjectRoot;
     processEnv: NodeJS.ProcessEnv;
     timestamp: () => string;
 }

package/dist/commands/project/archive/push-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"push-runner.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/push-runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAKL,2BAA2B,EAC3B,sBAAsB,EACtB,oCAAoC,EAEpC,KAAK,iCAAiC,EACtC,KAAK,gCAAgC,EAEtC,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qCAAqC;IACpD,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;IAChE,oCAAoC,EAAE,OAAO,oCAAoC,CAAC;IAClF,0BAA0B,EAAE,CAC1B,OAAO,EAAE,iCAAiC,KACvC,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,SAAS,EAAE,MAAM,MAAM,CAAC;CACzB;AAmBD,wBAAgB,4CAA4C,IAAI,qCAAqC,CAcpG;AAkJD,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,qCAAqC,EACnD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CA0Ef"}
+{"version":3,"file":"push-runner.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/push-runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAOjE,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAEL,6BAA6B,EAI7B,2BAA2B,EAC3B,sBAAsB,EACtB,oCAAoC,EAEpC,KAAK,iCAAiC,EACtC,KAAK,gCAAgC,EAEtC,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,qCAAqC;IACpD,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;IAChE,gBAAgB,EAAE,OAAO,gBAAgB,CAAC;IAC1C,oCAAoC,EAAE,OAAO,oCAAoC,CAAC;IAClF,0BAA0B,EAAE,CAC1B,OAAO,EAAE,iCAAiC,KACvC,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC/C,6BAA6B,EAAE,OAAO,6BAA6B,CAAC;IACpE,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,SAAS,EAAE,MAAM,MAAM,CAAC;CACzB;AAsBD,wBAAgB,4CAA4C,IAAI,qCAAqC,CAgBpG;AAuJD,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,qCAAqC,EACnD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAyGf"}

package/dist/commands/project/archive/push-runner.js

@@ -1,10 +1,12 @@
 import { basename, isAbsolute, join } from 'node:path';
 import { buildCommandContext } from '../../../app/command-context.js';
+import { readSyncedRecord } from '../../project/sync/record.js';
 import { resolveProjectsRoot } from '../../shared/oat-paths.js';
+import { resolveScopeRoot, syncedRecordPath, } from '../../shared/project-scope.js';
 import { readOatConfig, readOatLocalConfig, } from '../../../config/oat-config.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
-import { archiveProjectOnCompletion, assertDurableArchiveProjectTarget, buildArchiveSnapshotName, buildProjectArchiveS3Uri, resolveArchiveProjectTarget, resolvePrimaryRepoRoot, verifySelectedProjectRecapForArchive, } from './archive-utils.js';
+import { archiveProjectOnCompletion, assertExactArchiveProjectRoot, assertDurableArchiveProjectTarget, buildArchiveSnapshotName, buildProjectArchiveS3Uri, resolveArchiveProjectTarget, resolvePrimaryRepoRoot, verifySelectedProjectRecapForArchive, } from './archive-utils.js';
 export function defaultProjectArchivePushCommandDependencies() {
     return {
         buildCommandContext,
@@ -14,8 +16,10 @@ export function defaultProjectArchivePushCommandDependencies() {
         resolveProjectsRoot,
         resolvePrimaryRepoRoot,
         resolveArchiveProjectTarget,
+        readSyncedRecord,
         verifySelectedProjectRecapForArchive,
         archiveProjectOnCompletion,
+        assertExactArchiveProjectRoot,
         processEnv: process.env,
         timestamp: () => new Date().toISOString(),
     };
@@ -53,10 +57,10 @@ function buildArchiveOptions(repoRoot, config, projectsRoot, target, options) {
         projectRecapRun: options.projectRecapRun,
         awsProfile: config.archive?.awsProfile,
         awsRegion: config.archive?.awsRegion,
+        ...(options.commit === false ? { commit: false } : {}),
     };
 }
-async function buildDryRunReport(dependencies, repoRoot, config, target, archiveTarget) {
-    const snapshotName = buildArchiveSnapshotName(target.projectName, dependencies.timestamp());
+async function buildDryRunReport(dependencies, repoRoot, config, target, archiveTarget, snapshotName, projectScope) {
     const remoteRepoRoot = await dependencies.resolvePrimaryRepoRoot(repoRoot);
     const s3Path = config.archive?.s3Uri && config.archive.s3SyncOnComplete === true
         ? buildProjectArchiveS3Uri(config.archive.s3Uri, remoteRepoRoot, snapshotName)
@@ -73,6 +77,11 @@ async function buildDryRunReport(dependencies, repoRoot, config, target, archive
         s3Path,
         summaryExportFile,
         warnings: [],
+        lifecycleCommit: null,
+        recapExportPaths: [],
+        snapshotId: projectScope === 'synced'
+            ? snapshotName
+            : basename(archiveTarget.archivePath),
     };
 }
 function emitArchivePushText(report, summaryExportPath, logger) {
@@ -113,10 +122,27 @@ export async function runArchivePushCommand(dependencies, projectPathArg, option
         const config = await dependencies.readOatConfig(repoRoot);
         const projectsRoot = await dependencies.resolveProjectsRoot(repoRoot, dependencies.processEnv);
         const target = await resolveArchiveTarget(dependencies, repoRoot, projectPathArg);
+        const { projectScope } = dependencies.assertExactArchiveProjectRoot({
+            repoRoot,
+            projectPath: target.projectPath,
+            projectName: target.projectName,
+            projectsRoot,
+        });
+        const defaultSnapshotName = buildArchiveSnapshotName(target.projectName, dependencies.timestamp());
+        const syncedRecord = projectScope === 'synced'
+            ? await dependencies.readSyncedRecord(syncedRecordPath(resolveScopeRoot(repoRoot, projectsRoot, 'synced'), target.projectName))
+            : null;
+        const snapshotName = syncedRecord?.archiveSnapshot ?? defaultSnapshotName;
         const archiveTarget = await dependencies.resolveArchiveProjectTarget({
             repoRoot,
             projectsRoot,
             projectName: target.projectName,
+            ...(syncedRecord?.archiveSnapshot
+                ? {
+                    archiveSnapshot: syncedRecord.archiveSnapshot,
+                    archiveScope: projectScope ?? undefined,
+                }
+                : {}),
         }, {
             env: dependencies.processEnv,
             timestamp: dependencies.timestamp,
@@ -127,7 +153,7 @@ export async function runArchivePushCommand(dependencies, projectPathArg, option
         }
         const dryRun = options.dryRun === true || context.dryRun;
         if (dryRun) {
-            const report = await buildDryRunReport(dependencies, repoRoot, config, target, archiveTarget);
+            const report = await buildDryRunReport(dependencies, repoRoot, config, target, archiveTarget, snapshotName, projectScope);
             emitArchivePushReport(report, config.archive?.summaryExportPath, context);
             process.exitCode = 0;
             return;
@@ -145,6 +171,9 @@ export async function runArchivePushCommand(dependencies, projectPathArg, option
                 ? { projectRecapExport: result.projectRecapExport }
                 : {}),
             warnings: result.warnings,
+            lifecycleCommit: result.lifecycleCommit,
+            recapExportPaths: result.recapExportPaths,
+            snapshotId: result.snapshotId,
         };
         emitArchivePushReport(report, config.archive?.summaryExportPath, context);
         process.exitCode = 0;

package/dist/commands/project/complete-state/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/complete-state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,IAAI,eAAe,EAC3B,SAAS,IAAI,gBAAgB,EAC9B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,UAAU,gCAAgC;IACxC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,EAAE,OAAO,eAAe,CAAC;IACjC,SAAS,EAAE,OAAO,gBAAgB,CAAC;IACnC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AA0ED,wBAAgB,iCAAiC,CAC/C,SAAS,GAAE,OAAO,CAAC,gCAAgC,CAAM,GACxD,OAAO,CA2BT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/complete-state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,IAAI,eAAe,EAC3B,SAAS,IAAI,gBAAgB,EAC9B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,UAAU,gCAAgC;IACxC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,EAAE,OAAO,eAAe,CAAC;IACjC,SAAS,EAAE,OAAO,gBAAgB,CAAC;IACnC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AA4ED,wBAAgB,iCAAiC,CAC/C,SAAS,GAAE,OAAO,CAAC,gCAAgC,CAAM,GACxD,OAAO,CA2BT"}

package/dist/commands/project/complete-state/index.js

@@ -42,7 +42,9 @@ async function runProjectCompleteState(projectPath, options, context, dependenci
             filePath: statePath,
             projectPath: targetProjectPath,
         });
-        await dependencies.writeFile(statePath, updatedContent, 'utf8');
+        if (updatedContent !== content) {
+            await dependencies.writeFile(statePath, updatedContent, 'utf8');
+        }
         if (context.json) {
             context.logger.json({
                 status: 'ok',

package/dist/commands/project/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/project/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC,wBAAgB,oBAAoB,IAAI,OAAO,CAgB9C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/project/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,wBAAgB,oBAAoB,IAAI,OAAO,CAsB9C"}