@open-agent-toolkit/cli 0.3.16 → 0.3.17

package/dist/commands/project/sync/ref-sync.js

@@ -1,6 +1,8 @@
-import { lstat, mkdir, readFile, readdir, realpath, rm, stat, writeFile, } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, link, mkdir, mkdtemp, open, readFile, readdir, realpath, rm, stat, writeFile, } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { ensureScopedRootGitignore } from '../../init/gitignore.js';
+import { commitExactPaths, } from '../../shared/exact-path-commit.js';
 import { getFrontmatterBlock } from '../../shared/frontmatter.js';
 import { canonicalizePath, completedSyncedRefName, isSyncedCheckout, resolveScopeRoot, SYNCED_REMOTE, syncedRefName, syncedRecordPath, } from '../../shared/project-scope.js';
 import { readOatLocalConfig, writeOatLocalConfig } from '../../../config/oat-config.js';
@@ -8,7 +10,7 @@ import { CliError } from '../../../errors/cli-error.js';
 import { copyDirectory } from '../../../fs/io.js';
 import YAML from 'yaml';
 import { isAtomicPushUnsupported, pushAtomicRefTransition, } from './git.js';
-import { buildSyncedRecord, readSyncedRecord, writeSyncedRecord, } from './record.js';
+import { buildSyncedRecord, readSyncedRecord, SyncedProjectRecordSchema, writeSyncedRecord, } from './record.js';
 export function classifyRemoteRefLookup(result, remote, ref) {
     if (result.code === 0)
         return 'present';
@@ -593,22 +595,126 @@ export async function abortSynced(target, git) {
     });
 }
 function normalizedPathspecs(repoRoot, pathspecs) {
-    return pathspecs.map((pathspec) => repoRelativePath(repoRoot, pathspec));
+    return [
+        ...new Set(pathspecs.map((pathspec) => repoRelativePath(repoRoot, pathspec))),
+    ].sort();
 }
-export async function commitRecordChange(repoRoot, pathspecs, message, git, options) {
+class PendingRecordCommitError extends CliError {
+    result;
+    constructor(message, result) {
+        super(message, result.outcome === 'blocked' ? 1 : 2);
+        this.result = result;
+    }
+}
+export async function commitRecordChange(repoRoot, pathspecs, message, git, options, settlement) {
     assertAllowlistedPathspecs(repoRoot, pathspecs, options);
     const normalized = normalizedPathspecs(repoRoot, pathspecs);
-    await git.run(['add', '--', ...normalized], { cwd: repoRoot });
-    const changed = await git.run(['diff', '--cached', '--quiet', '--', ...normalized], { cwd: repoRoot, allowFailure: true });
-    assertExpectedGitResult('git diff --cached --quiet', changed, [0, 1]);
-    if (changed.code === 0) {
-        return null;
+    await git.run(['rev-parse', '--is-inside-work-tree'], { cwd: repoRoot });
+    const gitDir = (await git.run(['rev-parse', '--absolute-git-dir'], { cwd: repoRoot })).stdout;
+    const pendingDir = join(gitDir, 'oat-record-commit-pending');
+    await mkdir(pendingDir, { recursive: true });
+    const operation = createHash('sha256')
+        .update(JSON.stringify([message, normalized]))
+        .digest('hex');
+    const pendingPath = join(pendingDir, `${operation}.json`);
+    for (let reservationAttempt = 0; reservationAttempt < 2; reservationAttempt++) {
+        if ((await readOptionalFile(pendingPath)) === null) {
+            if (settlement)
+                throw new CliError('The verified pending migration marker disappeared; preserve state for inspection.', 2);
+            const identity = `project-record:${operation}:${randomUUID()}`;
+            const temporary = await mkdtemp(join(pendingDir, 'reservation-'));
+            const complete = join(temporary, 'pending.json');
+            try {
+                await writeFile(complete, JSON.stringify({ identity, paths: normalized, message }));
+                try {
+                    await link(complete, pendingPath);
+                }
+                catch (error) {
+                    if (error.code !== 'EEXIST')
+                        throw error;
+                }
+            }
+            finally {
+                await rm(temporary, { recursive: true, force: true });
+            }
+        }
+        const file = await open(pendingPath, 'r');
+        const markerIdentity = await file.stat();
+        let markerBytes;
+        try {
+            markerBytes = await file.readFile('utf8');
+        }
+        finally {
+            await file.close();
+        }
+        const reservation = JSON.parse(markerBytes);
+        if (settlement &&
+            (reservation.identity !== settlement.marker.identity ||
+                markerBytes !== settlement.marker.bytes ||
+                markerIdentity.ino !== settlement.marker.ino ||
+                markerIdentity.dev !== settlement.marker.dev))
+            throw new CliError('The verified pending migration marker was replaced; replacement preserved for inspection.', 2);
+        const clearPending = async () => {
+            const current = await lstat(pendingPath).catch((error) => {
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            });
+            if (!current)
+                return;
+            if (current.ino !== markerIdentity.ino ||
+                current.dev !== markerIdentity.dev ||
+                (await readOptionalFile(pendingPath)) !== markerBytes)
+                throw new CliError(`Verified commit exists, but the pending marker at ${pendingPath} was replaced; replacement preserved for inspection.`, 2);
+            await rm(pendingPath);
+        };
+        if (reservation.message !== message ||
+            JSON.stringify(reservation.paths) !== JSON.stringify(normalized) ||
+            !reservation.identity.startsWith(`project-record:${operation}:`))
+            throw new CliError(`Unreconciled lifecycle commit marker at ${pendingPath}; preserve it and inspect before retrying.`, 2);
+        const result = await commitExactPaths({
+            repoRoot,
+            paths: normalized,
+            message,
+            identity: reservation.identity,
+        });
+        // A public helper repair can settle Git while leaving our reservation. Only
+        // its positive prior/current publication proof authorizes retiring that
+        // reservation before one fresh generation. Never republish a superseded
+        // tree; a migration's finalization remains mandatory.
+        if (!settlement &&
+            reservationAttempt === 0 &&
+            result.outcome === 'failed' &&
+            result.settledCommit &&
+            result.settledCommit === result.commit) {
+            await clearPending();
+            continue;
+        }
+        if (settlement &&
+            ['committed', 'already-matching', 'nothing'].includes(result.outcome) &&
+            result.commit !== settlement.commit)
+            throw new CliError('Pending migration settlement did not return its verified commit; marker preserved for inspection.', 2);
+        if (result.outcome === 'nothing') {
+            await clearPending();
+            return null;
+        }
+        if ((result.outcome === 'committed' ||
+            result.outcome === 'already-matching') &&
+            result.commit) {
+            try {
+                await settlement?.finalize();
+                await clearPending();
+            }
+            catch (error) {
+                throw new PendingRecordCommitError(errorMessage(error), result);
+            }
+            return { sha: result.commit };
+        }
+        throw new PendingRecordCommitError(result.resumable === false
+            ? `Exact-path lifecycle commit ${result.outcome}: ${result.error ?? 'unverified result'}. Preserve the pending marker at ${pendingPath}${result.receipt ? ` and receipt at ${result.receipt}` : ''} for inspection and explicit provenance reconciliation before any further commit attempt.`
+            : `Exact-path lifecycle commit ${result.outcome}: ${result.error ?? 'unverified result'}. Retry after resolving the reported condition with: oat internal commit-paths --identity ${shellQuote(reservation.identity)} --message ${shellQuote(message)} -- ${normalized.map(shellQuote).join(' ')}${result.receipt ? `; receipt ${result.receipt}` : ''}.`, result);
     }
-    await git.run(['commit', '-m', message, '--', ...normalized], {
-        cwd: repoRoot,
-    });
-    const sha = (await git.run(['rev-parse', 'HEAD'], { cwd: repoRoot })).stdout;
-    return { sha };
+    throw new CliError('Lifecycle commit reservation changed repeatedly; preserve pending state for inspection.', 2);
 }
 export async function preflightSyncedCheckout(target, git) {
     const checkoutExists = await assertCanonicalSyncTargetIdentity(target);
@@ -888,14 +994,8 @@ export async function pruneSynced(target, git, options) {
             if (!options.commit) {
                 return { status: 'pruned', lifecycleCommit: null };
             }
-            await git.run([
-                'commit',
-                '-m',
-                `chore(oat): prune synced project ${target.slug}`,
-                '--',
-                relativeRecordPath,
-            ], { cwd: target.repoRoot });
-            const lifecycleCommit = (await git.run(['rev-parse', 'HEAD'], { cwd: target.repoRoot })).stdout;
+            const committed = await commitRecordChange(target.repoRoot, [relativeRecordPath], `chore(oat): prune synced project ${target.slug}`, git, { projectRoots: target });
+            const lifecycleCommit = committed?.sha ?? null;
             return { status: 'pruned', lifecycleCommit };
         }
     }
@@ -990,10 +1090,206 @@ async function readOptionalFile(path) {
         throw error;
     }
 }
+// Only the existing migration reservation can resume after its source was removed.
+// No ownership is inferred from the current staged index or a missing directory.
+async function verifyPendingMigration(target, git, options, sourcePath) {
+    const stop = () => {
+        throw new CliError('Pending migration does not positively match its retained operation, parent source tree and published synced checkout; preserve all state for inspection.', 2);
+    };
+    const sourceRelative = repoRelativePath(target.repoRoot, sourcePath);
+    if (!options.commit ||
+        canonicalizePath(sourcePath) !==
+            resolve(canonicalizePath(target.sharedRoot), target.slug))
+        stop();
+    if (await lstat(sourcePath).then(() => true, (error) => {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }))
+        stop();
+    const gitDir = (await git.run(['rev-parse', '--absolute-git-dir'], { cwd: target.repoRoot })).stdout;
+    const pendingDir = join(gitDir, 'oat-record-commit-pending');
+    const message = `chore(oat): migrate ${target.slug} to synced scope`;
+    const candidates = [];
+    for (const name of await readdir(pendingDir).catch((error) => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    })) {
+        if (!name.endsWith('.json'))
+            continue;
+        const path = join(pendingDir, name);
+        const file = await open(path, 'r');
+        let bytes;
+        let identity;
+        try {
+            identity = await file.stat();
+            bytes = await file.readFile('utf8');
+        }
+        finally {
+            await file.close();
+        }
+        const marker = JSON.parse(bytes);
+        if (marker.message === message)
+            candidates.push({ name, path, bytes, marker, identity });
+    }
+    if (candidates.length !== 1)
+        stop();
+    const { name, path, bytes, marker, identity } = candidates[0];
+    if (!Array.isArray(marker.paths) ||
+        !marker.paths.every((value) => typeof value === 'string') ||
+        typeof marker.identity !== 'string')
+        stop();
+    const paths = normalizedPathspecs(target.repoRoot, marker.paths);
+    const operation = createHash('sha256')
+        .update(JSON.stringify([message, paths]))
+        .digest('hex');
+    const recordPath = syncedRecordPath(target.syncedRoot, target.slug);
+    const recordRelative = repoRelativePath(target.repoRoot, recordPath);
+    if (name !== `${operation}.json` ||
+        !marker.identity.startsWith(`project-record:${operation}:`) ||
+        JSON.stringify(paths) !== JSON.stringify(marker.paths) ||
+        !paths.includes(recordRelative) ||
+        paths.some((value) => value !== recordRelative &&
+            value !== '.gitignore' &&
+            !value.startsWith(`${sourceRelative}/`)))
+        stop();
+    const receiptPath = join(gitDir, 'oat-exact-path-commits', `${createHash('sha256').update(marker.identity).digest('hex')}.json`);
+    const receiptBytes = await readFile(receiptPath, 'utf8');
+    const receipt = JSON.parse(receiptBytes);
+    if (!receipt.commit ||
+        !receipt.tree ||
+        receipt.identity !== marker.identity ||
+        JSON.stringify(receipt.paths) !== JSON.stringify(paths))
+        stop();
+    const commit = receipt.commit;
+    if (!commit)
+        return stop();
+    const run = async (args, cwd = target.repoRoot) => (await git.run(['--literal-pathspecs', ...args], { cwd })).stdout;
+    if ((await run(['rev-parse', 'HEAD'])) !== commit ||
+        (await run(['show', '-s', '--format=%P', commit])) !== receipt.parent ||
+        (await run(['rev-parse', `${commit}^{tree}`])) !== receipt.tree ||
+        !(await run(['show', '-s', '--format=%B', commit])).includes(`Oat-Operation: ${createHash('sha256').update(marker.identity).digest('hex')}`))
+        stop();
+    const removed = (await run([
+        'ls-tree',
+        '-r',
+        '--name-only',
+        '-z',
+        receipt.parent,
+        '--',
+        sourceRelative,
+    ]))
+        .split('\0')
+        .filter(Boolean)
+        .sort();
+    if (!removed.length ||
+        JSON.stringify(removed) !==
+            JSON.stringify(paths.filter((value) => value.startsWith(`${sourceRelative}/`))))
+        stop();
+    if ((await run([
+        'ls-tree',
+        '-r',
+        '--name-only',
+        commit,
+        '--',
+        sourceRelative,
+    ])) !== '')
+        stop();
+    const emitted = (await run([
+        'diff-tree',
+        '--root',
+        '--no-commit-id',
+        '-r',
+        '--no-renames',
+        '--name-only',
+        '-z',
+        commit,
+    ]))
+        .split('\0')
+        .filter(Boolean);
+    if (emitted.some((value) => !paths.includes(value)))
+        stop();
+    const committedRecord = SyncedProjectRecordSchema.parse(JSON.parse(await run(['show', `${commit}:${recordRelative}`])));
+    const record = await readSyncedRecord(recordPath);
+    if (!record ||
+        record.slug !== target.slug ||
+        record.ref !== target.ref ||
+        record.remote !== target.remote ||
+        record.status !== 'active' ||
+        JSON.stringify(record) !== JSON.stringify(committedRecord))
+        stop();
+    if (!(await assertCanonicalSyncTargetIdentity(target)))
+        return stop();
+    await assertNestedWorktree(target, git);
+    const sha = await headSha(target, git);
+    const remote = await git.run(['ls-remote', '--exit-code', target.remote, target.ref], { cwd: target.repoRoot, allowFailure: true });
+    if (remote.code !== 0 ||
+        remote.stdout.split(/\s+/)[0] !== sha ||
+        (await run(['status', '--porcelain'], target.projectPath)) !== '' ||
+        (await run(['rev-parse', `${receipt.parent}:${sourceRelative}`])) !==
+            (await run(['rev-parse', 'HEAD^{tree}'], target.projectPath)))
+        return stop();
+    const currentMarker = await lstat(path);
+    if (currentMarker.ino !== identity.ino ||
+        currentMarker.dev !== identity.dev ||
+        (await readFile(path, 'utf8')) !== bytes ||
+        (await readFile(receiptPath, 'utf8')) !== receiptBytes)
+        stop();
+    return {
+        commit,
+        parent: receipt.parent,
+        paths,
+        message,
+        sha,
+        sourceRelative,
+        marker: {
+            identity: marker.identity,
+            bytes,
+            ino: identity.ino,
+            dev: identity.dev,
+        },
+    };
+}
+async function finalizePendingMigration(target, git, options, sourcePath) {
+    const { commit, paths, message, sha, sourceRelative, marker } = await verifyPendingMigration(target, git, options, sourcePath);
+    const committed = await commitRecordChange(target.repoRoot, paths, message, git, { projectRoots: target }, {
+        commit,
+        marker,
+        finalize: async () => {
+            const local = await (options.readOatLocalConfig ?? readOatLocalConfig)(target.repoRoot);
+            if (local.activeProject === sourceRelative)
+                await (options.writeOatLocalConfig ?? writeOatLocalConfig)(target.repoRoot, {
+                    ...local,
+                    activeProject: repoRelativePath(target.repoRoot, target.projectPath),
+                });
+        },
+    });
+    if (committed?.sha !== commit)
+        throw new CliError('Pending migration settlement did not return its verified commit; preserve state for inspection.', 2);
+    return {
+        status: 'migrated',
+        lifecycleCommit: commit,
+        sha,
+    };
+}
 export async function migrateSharedToSynced(target, git, options) {
     const sourcePath = resolve(options.sourcePath);
+    const sourceExists = await lstat(sourcePath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (!sourceExists) {
+        if ((await readSyncedRecord(syncedRecordPath(target.syncedRoot, target.slug))) === null)
+            await assertConfinedMigrationSource(target, sourcePath);
+        return finalizePendingMigration(target, git, options, sourcePath);
+    }
     await assertConfinedMigrationSource(target, sourcePath);
     const sourceRelative = repoRelativePath(target.repoRoot, sourcePath);
+    const sourceFiles = (await git.run(['--literal-pathspecs', 'ls-files', '-z', '--', sourceRelative], { cwd: target.repoRoot })).stdout
+        .split('\0')
+        .filter(Boolean);
     const recordPath = syncedRecordPath(target.syncedRoot, target.slug);
     const destinationRelative = repoRelativePath(target.repoRoot, target.projectPath);
     const gitignorePath = join(target.repoRoot, '.gitignore');
@@ -1030,6 +1326,7 @@ export async function migrateSharedToSynced(target, git, options) {
     let prePublishRemoteSha = null;
     let activeProjectUpdated = false;
     let gitignoreSelfHealStarted = false;
+    let migrationCommitPaths;
     try {
         if (needsGitignoreHeal) {
             const repair = await (options.ensureScopedRootGitignore ?? ensureScopedRootGitignore)(target.repoRoot, target.syncedRoot, 'synced', git, 'Cannot add the synced-project rule because .gitignore has staged or unstaged changes; commit or stash those changes, or add the managed rule manually, then retry migration.');
@@ -1054,7 +1351,12 @@ export async function migrateSharedToSynced(target, git, options) {
             (await readOptionalFile(gitignorePath)) !== originalGitignore;
         let lifecycleCommit = null;
         if (options.commit) {
-            const committed = await commitRecordChange(target.repoRoot, [sourcePath, recordPath, ...(gitignoreChanged ? [gitignorePath] : [])], `chore(oat): migrate ${target.slug} to synced scope`, git, { projectRoots: target });
+            migrationCommitPaths = [
+                ...sourceFiles,
+                recordPath,
+                ...(gitignoreChanged ? [gitignorePath] : []),
+            ];
+            const committed = await commitRecordChange(target.repoRoot, migrationCommitPaths, `chore(oat): migrate ${target.slug} to synced scope`, git, { projectRoots: target });
             lifecycleCommit = committed?.sha ?? null;
             await options.afterBranchCommit?.();
         }
@@ -1078,6 +1380,28 @@ export async function migrateSharedToSynced(target, git, options) {
         return { status: 'migrated', lifecycleCommit, sha: pushed.sha };
     }
     catch (error) {
+        if (error instanceof PendingRecordCommitError && error.result.commit) {
+            // committed:true is not a provenance proof: the helper can report a
+            // stored receipt's commit before validating it. Reuse the owning verifier
+            // and bind its proof to this invocation before choosing retention.
+            let retained;
+            try {
+                retained = await verifyPendingMigration(target, git, options, sourcePath);
+                if (retained.commit !== error.result.commit ||
+                    retained.parent !== preMigrationHead ||
+                    !migrationCommitPaths ||
+                    JSON.stringify(retained.paths) !==
+                        JSON.stringify(normalizedPathspecs(target.repoRoot, migrationCommitPaths)))
+                    throw new Error('Retained operation does not match this migration invocation.', { cause: error });
+            }
+            catch (verificationError) {
+                throw new CliError(`${error.message} Migration commit provenance could not be independently verified; no rollback or finalization was attempted. Preserve all current state and recovery metadata for inspection. ${errorMessage(verificationError)}`, 2);
+            }
+            // The verifier proved the removed source is absent. Restore only retained
+            // tree files; the owning finalizer will settle source deletions in the index.
+            const restorePaths = retained.paths.filter((value) => !value.startsWith(`${sourceRelative}/`));
+            throw new CliError(`${error.message} The verified migration commit and published synced checkout were retained. Inspect the hook's changes; removing the hook does not repair its changed bytes. After inspection, restore owned worktree bytes with: git --literal-pathspecs -C ${shellQuote(target.repoRoot)} restore --source ${shellQuote(retained.commit)} --worktree -- ${restorePaths.map(shellQuote).join(' ')}; then finalize with: oat --cwd ${shellQuote(target.repoRoot)} project migrate ${shellQuote(sourceRelative)} --to synced`, error.exitCode);
+        }
         const compensationFailures = [];
         const compensate = async (resource, recovery, action) => {
             try {

package/dist/commands/shared/exact-path-commit.d.ts

@@ -0,0 +1,32 @@
+export interface ExactPathCommitInput {
+    repoRoot: string;
+    paths: readonly string[];
+    message: string;
+    identity: string;
+}
+export interface ExactPathCommitResult {
+    outcome: 'committed' | 'already-matching' | 'nothing' | 'blocked' | 'failed';
+    committed: boolean;
+    attempts: number;
+    commit?: string;
+    /** A fully verified resumed receipt whose owned real-index entries remain
+     * published, or whose later generation is published at current HEAD. Failed
+     * outcome stays failed; only the marker owner may retire that reservation. */
+    settledCommit?: string;
+    receipt?: string;
+    error?: string;
+    lockClass?: 'transient-index-lock' | 'persistent-index-lock' | 'other';
+    resumable?: boolean;
+}
+export interface ExactPathCommitDependencies {
+    attempts: number;
+    retryDelaysMs: readonly number[];
+    sleep: (ms: number) => Promise<void>;
+}
+/** Use an isolated index for enabled hooks; publish only owned entries under Git's lock.
+ * The real lock is held during hooks, so ordinary competing Git writers cannot lose
+ * their changes. A byte comparison also detects writers bypassing that protocol.
+ * Never restore a snapshot over current user data, and never remove a foreign lock.
+ */
+export declare function commitExactPaths(input: ExactPathCommitInput, overrides?: Partial<ExactPathCommitDependencies>): Promise<ExactPathCommitResult>;
+//# sourceMappingURL=exact-path-commit.d.ts.map

package/dist/commands/shared/exact-path-commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-path-commit.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/exact-path-commit.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,WAAW,GAAG,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC7E,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;kFAE8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,sBAAsB,GAAG,uBAAuB,GAAG,OAAO,CAAC;IACvE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AACD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAuSD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,oBAAoB,EAC3B,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAAC,qBAAqB,CAAC,CA8iBhC"}