@udondan/avanti 0.24.0 → 0.25.0

package/dist/commands/pull.js

@@ -42,12 +42,13 @@ const condition_1 = require("../condition");
 const sources_1 = require("../sources");
 const dependencies_1 = require("../dependencies");
 const replace_1 = require("../processors/replace");
-const post_1 = require("../processors/post");
+const on_1 = require("../processors/on");
 const insert_1 = require("../processors/insert");
 const binary_1 = require("../binary");
 const diff_1 = require("../diff");
 const writer_1 = require("../writer");
 const paths_1 = require("../paths");
+const local_1 = require("../sources/local");
 const history_1 = require("../history");
 const prompt_1 = require("../prompt");
 const config_writeback_1 = require("../config-writeback");
@@ -63,6 +64,7 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
         return {
             writeTargets: [],
             allDiffs: [],
+            fileHookContexts: [],
             hasError: true,
             shaErrors: [],
             sourceRecordsByTarget: new Map(),
@@ -75,8 +77,10 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
         vars['self'] = configPath;
     }
     Object.assign(vars, dateVars);
+    Object.assign(vars, (0, variables_1.buildSystemVars)());
     const writeTargets = [];
     const allDiffs = [];
+    const fileHookContexts = [];
     const shaErrors = [];
     const seenShaErrorLabels = new Set();
     const sourceRecordsByTarget = new Map();
@@ -87,6 +91,7 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
     let hasError = false;
     let selfContent;
     let selfMode;
+    let selfSudo;
     let selfSourceRecords;
     let hasSelf = config_1.SELF_KEY in config.files;
     if (hasSelf) {
@@ -101,6 +106,7 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
             return {
                 writeTargets,
                 allDiffs,
+                fileHookContexts,
                 hasError: true,
                 shaErrors,
                 sourceRecordsByTarget,
@@ -127,6 +133,7 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
         return {
             writeTargets: [],
             allDiffs: [],
+            fileHookContexts: [],
             hasError: true,
             shaErrors: [],
             sourceRecordsByTarget: new Map(),
@@ -146,23 +153,127 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
             const preVars = (0, paths_1.buildEntryPreVars)(entry, isSelf, workingDir, vars);
             if (!isSelf &&
                 !(0, condition_1.evaluateConditions)(entry['if'], entry.ifAny, () => (0, paths_1.resolveTargetPath)(entry, '', workingDir, vars), workingDir, preVars)) {
+                let symlinkPath;
                 try {
-                    skippedPaths.add((0, paths_1.resolveTargetPath)(entry, '', workingDir, vars));
+                    symlinkPath = (0, paths_1.resolveTargetPath)(entry, '', workingDir, vars);
                 }
                 catch {
                     console.warn(`Warning: skipped entry has an unresolvable target path — stale cleanup disabled for this run.`);
                     hasUnresolvableSkippedPath = true;
+                    continue;
+                }
+                skippedPaths.add(symlinkPath);
+                // Also skip the resolved real path so stale cleanup doesn't treat
+                // the symlink target as unmanaged when followSymlink is in use.
+                // Skip for directory targets — resolveFollowSymlink throws on dir symlinks.
+                // resolveFollowSymlink security errors (escape/directory/cycle) are
+                // intentionally NOT caught here — they propagate as hard failures.
+                const resolvedTarget0 = entry.target
+                    ? (0, variables_1.resolveVars)(entry.target, vars)
+                    : '';
+                if (!resolvedTarget0.endsWith('/') &&
+                    !resolvedTarget0.endsWith(path.sep)) {
+                    const realPath = (0, paths_1.resolveFollowSymlink)(symlinkPath, entry, workingDir);
+                    if (realPath !== symlinkPath)
+                        skippedPaths.add(realPath);
+                }
+                continue;
+            }
+            // Symlink entries: resolve src path and create a symlink instead of
+            // fetching and writing file content.
+            if (!isSelf && entry.symlink) {
+                if (process.platform === 'win32') {
+                    console.error(`Error processing ${JSON.stringify(entry.src)}: symlink entries are not supported on Windows; use an \`if: { os: [linux, mac] }\` condition to gate symlink entries in cross-platform configs`);
+                    hasError = true;
+                    continue;
+                }
+                const targetPath = (0, paths_1.resolveTargetPath)(entry, '', workingDir, vars);
+                if (Array.isArray(entry.src)) {
+                    throw new Error(`files["${entry.target}"].symlink: src must be a single local path, not an array`);
+                }
+                const rawSrc = typeof entry.src === 'string'
+                    ? entry.src
+                    : entry.src.path;
+                // Honor optional: true — skip when the local source does not exist.
+                const isOptionalSrc = !Array.isArray(entry.src) &&
+                    typeof entry.src !== 'string' &&
+                    !!entry.src.optional;
+                if (isOptionalSrc) {
+                    const absSrc = (0, local_1.resolveSymlinkSrcPath)(rawSrc, workingDir, preVars, true, targetPath);
+                    if (!fs.existsSync(absSrc)) {
+                        // Mark the target as skipped so stale cleanup does not treat a
+                        // previously-managed path as unmanaged and delete/restore it.
+                        skippedPaths.add(targetPath);
+                        continue;
+                    }
+                }
+                const symlinkTarget = (0, local_1.resolveSymlinkSrcPath)(rawSrc, workingDir, preVars, entry.symlink, targetPath);
+                const diff = (0, diff_1.computeSymlinkDiff)(targetPath, symlinkTarget);
+                // Symlinks cannot replace existing directories — error early so the
+                // write batch is not attempted and EISDIR is not thrown at rename time.
+                // Do not push to allDiffs here: allDiffs and writeTargets are parallel
+                // arrays; pushing diff without a matching writeTargets entry would
+                // misalign subsequent index-based lookups.
+                if (diff.isDirectory) {
+                    console.error(`Error processing ${JSON.stringify(entry.src)}: symlink: ${targetPath} is a directory; cannot replace with a symlink`);
+                    hasError = true;
+                    continue;
+                }
+                allDiffs.push(diff);
+                const symlinkContent = Buffer.from(symlinkTarget, 'utf8');
+                const symlinkBackupPath = entry.backup && diff.hasChanges && !diff.isNew
+                    ? (0, variables_1.resolveBackupPath)(entry.backup, targetPath, workingDir, vars, config.backup_roots ?? [])
+                    : undefined;
+                writeTargets.push({
+                    targetPath,
+                    content: symlinkContent,
+                    symlinkTarget,
+                    backupPath: symlinkBackupPath,
+                    sudo: entry.sudo,
+                });
+                if (entry.on && diff.hasChanges) {
+                    fileHookContexts.push({
+                        targetPath,
+                        hooks: entry.on,
+                        isNew: diff.isNew,
+                    });
+                }
+                // Register the resolved src content (not the symlink target string) in
+                // pendingWrites so subsequent local entries that read through this symlink
+                // path see the actual file bytes, not the raw symlink target path.
+                const absSymlinkSrc = (0, local_1.resolveSymlinkSrcPath)(rawSrc, workingDir, preVars, true, targetPath);
+                try {
+                    const srcStat = fs.statSync(absSymlinkSrc, { throwIfNoEntry: false });
+                    if (srcStat?.isFile()) {
+                        pendingWrites.set(targetPath, fs.readFileSync(absSymlinkSrc));
+                    }
+                }
+                catch {
+                    // src not readable — omit from pendingWrites
                 }
                 continue;
             }
             const result = await (0, sources_1.fetchSource)(entry, workingDir, preVars, cache, isSelf && configPath !== undefined ? () => configPath : undefined, pendingWrites);
             if (result.allSkipped && !isSelf) {
+                let symlinkPath2;
                 try {
-                    skippedPaths.add((0, paths_1.resolveTargetPath)(entry, '', workingDir, vars));
+                    symlinkPath2 = (0, paths_1.resolveTargetPath)(entry, '', workingDir, vars);
                 }
                 catch {
                     console.warn(`Warning: skipped entry has an unresolvable target path — stale cleanup disabled for this run.`);
                     hasUnresolvableSkippedPath = true;
+                    continue;
+                }
+                skippedPaths.add(symlinkPath2);
+                // resolveFollowSymlink security errors propagate as hard failures.
+                const resolvedTarget2 = entry.target
+                    ? (0, variables_1.resolveVars)(entry.target, vars)
+                    : '';
+                if (!resolvedTarget2.endsWith('/') &&
+                    !resolvedTarget2.endsWith(path.sep)) {
+                    const realPath = (0, paths_1.resolveFollowSymlink)(symlinkPath2, entry, workingDir);
+                    if (realPath !== symlinkPath2)
+                        skippedPaths.add(realPath);
                 }
                 continue;
             }
@@ -193,6 +304,11 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
                 const entryVars = targetPath !== undefined
                     ? Object.assign(Object.create(null), vars, (0, variables_1.buildFileVars)(targetPath))
                     : vars;
+                // Resolve any symlink on the target path early so insert-mode tracking
+                // and all subsequent operations use the real file path consistently.
+                const effectivePath = targetPath !== undefined
+                    ? (0, paths_1.resolveFollowSymlink)(targetPath, entry, workingDir)
+                    : undefined;
                 let content = rawContent;
                 if (!(0, binary_1.isBinary)(content)) {
                     // Processors only operate on text; binary files are passed through unchanged.
@@ -203,20 +319,22 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
                     }
                     if (entry.replace?.length)
                         text = (0, replace_1.applyReplace)(text, entry.replace, entryVars);
-                    if (entry.post)
-                        text = (0, post_1.applyPost)(text, entry.post, entryVars);
+                    if (entry.on?.write)
+                        text = (0, on_1.applyWriteHook)(text, entry.on.write, entryVars);
                     if (entry.strategy === 'insert' && !isSelf) {
-                        const lastInserted = history?.getInsertedFragment(targetPath) ?? null;
+                        const lastInserted = history?.getInsertedFragment(effectivePath) ?? null;
                         if (lastInserted !== null &&
                             rawText === lastInserted.raw &&
                             text === lastInserted.processed &&
-                            fs.existsSync(targetPath)) {
+                            fs.existsSync(effectivePath)) {
                             skippedPaths.add(targetPath); // keep stale detection from treating this as missing
+                            if (effectivePath !== targetPath)
+                                skippedPaths.add(effectivePath);
                             continue; // source and processed output unchanged — skip write entirely (no-op)
                         }
                         const processedText = text;
-                        text = (0, insert_1.applyInsertMode)(entry, processedText, lastInserted?.processed ?? null, targetPath);
-                        insertedFragments.set(targetPath, {
+                        text = (0, insert_1.applyInsertMode)(entry, processedText, lastInserted?.processed ?? null, effectivePath);
+                        insertedFragments.set(effectivePath, {
                             raw: rawText,
                             processed: processedText,
                         });
@@ -226,25 +344,47 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
                 if (isSelf) {
                     selfContent = content.toString('utf8');
                     selfMode = entry.mode;
+                    selfSudo = entry.sudo || undefined;
                     if (result.sourceRecords.length > 0)
                         selfSourceRecords = result.sourceRecords;
                     continue;
                 }
-                const diff = (0, diff_1.computeDiff)(targetPath, content, entry.mode);
+                // effectivePath is always defined here: isSelf is false (we continued above),
+                // so targetPath was defined, and effectivePath = resolveFollowSymlink(targetPath, ...).
+                const ep = effectivePath;
+                const diff = (0, diff_1.computeDiff)(ep, content, entry.mode);
                 allDiffs.push(diff);
                 const backupPath = entry.backup && diff.hasChanges && !diff.isNew
-                    ? (0, variables_1.resolveBackupPath)(entry.backup, targetPath, workingDir, vars, config.backup_roots ?? [])
+                    ? (0, variables_1.resolveBackupPath)(entry.backup, ep, workingDir, vars, config.backup_roots ?? [])
                     : undefined;
                 writeTargets.push({
-                    targetPath: targetPath,
+                    targetPath: ep,
                     content,
                     mode: entry.mode,
                     backupPath,
                     writeInPlace: entry.writeInPlace,
+                    sudo: entry.sudo,
                 });
-                pendingWrites.set(targetPath, content);
+                if (entry.on && diff.hasChanges) {
+                    fileHookContexts.push({
+                        targetPath: ep,
+                        hooks: entry.on,
+                        isNew: diff.isNew,
+                    });
+                }
+                pendingWrites.set(ep, content);
+                // Also index under the original symlink path so local source lookups
+                // using the symlink path (not the resolved real path) still find the
+                // pending content within the same fetch loop.
+                if (ep !== targetPath) {
+                    pendingWrites.set(targetPath, content);
+                    // Mark the symlink path as covered so stale detection doesn't treat
+                    // a previously-tracked symlink path as stale when followSymlink is
+                    // enabled on an entry that was first pulled without it.
+                    skippedPaths.add(targetPath);
+                }
                 if (result.sourceRecords.length > 0) {
-                    sourceRecordsByTarget.set(targetPath, result.sourceRecords);
+                    sourceRecordsByTarget.set(ep, result.sourceRecords);
                 }
             }
         }
@@ -256,6 +396,7 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
     return {
         writeTargets,
         allDiffs,
+        fileHookContexts,
         hasError,
         shaErrors,
         sourceRecordsByTarget,
@@ -264,12 +405,13 @@ async function runFetchLoop(config, workingDir, dateVars, cache, configPath, his
         insertedFragments,
         selfContent,
         selfMode,
+        selfSudo,
         selfSourceRecords,
     };
 }
 function printShaErrors(errors) {
     for (const e of errors) {
-        console.error(`SHA mismatch for ${e.sourceLabel}\n` +
+        console.error(`SHA mismatch for ${(0, sources_1.formatSourceLabel)(e.sourceLabel)}\n` +
             `  expected: ${e.expectedSha}\n` +
             `  got:      ${e.observedSha}`);
     }
@@ -284,7 +426,7 @@ function pullCommand() {
         const configPath = (0, config_1.resolveConfigPath)(cmd.parent?.opts().config);
         const rawWorkingDir = cmd.parent?.opts().workingDir;
         const workingDir = rawWorkingDir
-            ? path.resolve(rawWorkingDir)
+            ? path.resolve((0, paths_1.expandTilde)(rawWorkingDir))
             : process.cwd();
         const via = (0, config_1.parseVia)(cmd.parent?.opts().via, '--via');
         let config;
@@ -302,6 +444,7 @@ function pullCommand() {
         const dateVars = (0, variables_1.buildDateVars)();
         const firstPass = await runFetchLoop(config, workingDir, dateVars, fetchCache, configPath, history);
         let { writeTargets, allDiffs, sourceRecordsByTarget } = firstPass;
+        let fileHookContexts = firstPass.fileHookContexts;
         let insertedFragments = firstPass.insertedFragments;
         let skippedPaths = firstPass.skippedPaths;
         let hasUnresolvableSkippedPath = firstPass.hasUnresolvableSkippedPath;
@@ -321,6 +464,7 @@ function pullCommand() {
             let prevSelfContent;
             let currentSelfContent = firstPass.selfContent;
             let currentSelfMode = firstPass.selfMode;
+            let currentSelfSudo = firstPass.selfSudo;
             let currentSelfSourceRecords = firstPass.selfSourceRecords;
             let stableConfig;
             while (stableConfig === undefined) {
@@ -362,6 +506,7 @@ function pullCommand() {
                 prevSelfContent = currentSelfContent;
                 currentSelfContent = next.selfContent;
                 currentSelfMode = next.selfMode;
+                currentSelfSudo = next.selfSudo;
                 currentSelfSourceRecords = next.selfSourceRecords;
             }
             if (stableConfig !== undefined) {
@@ -386,6 +531,7 @@ function pullCommand() {
                     }
                     writeTargets = second.writeTargets;
                     allDiffs = second.allDiffs;
+                    fileHookContexts = second.fileHookContexts;
                     sourceRecordsByTarget = second.sourceRecordsByTarget;
                     insertedFragments = second.insertedFragments;
                     skippedPaths = second.skippedPaths;
@@ -409,6 +555,7 @@ function pullCommand() {
                             targetPath: configPath,
                             content: selfBuf,
                             mode: currentSelfMode,
+                            sudo: currentSelfSudo,
                         });
                         allDiffs.push((0, diff_1.computeDiff)(configPath, selfBuf, currentSelfMode));
                     }
@@ -418,6 +565,10 @@ function pullCommand() {
                             ...writeTargets[existingIdx],
                             content: selfBuf,
                             mode: resolvedSelfMode,
+                            // Fall back to the existing target's sudo identity when $self
+                            // doesn't specify one, so a privileged config file keeps its
+                            // write privileges after $self stabilization.
+                            sudo: currentSelfSudo ?? writeTargets[existingIdx].sudo,
                         };
                         allDiffs[existingIdx] = (0, diff_1.computeDiff)(configPath, selfBuf, resolvedSelfMode);
                     }
@@ -434,8 +585,15 @@ function pullCommand() {
         }
         // Detect stale files: present in last pull but no longer in current source fetch
         const staleToDelete = [];
+        // Maps path → sudo identity for stale files that need privileged deletion
+        const staleDeleteSudo = new Map();
+        // Maps path → staleDiffs index so we can check hasChanges before auth/write
+        const staleDeleteDiffIndex = new Map();
         const staleToRestore = [];
         const staleDiffs = [];
+        // Parallel array: staleDiffs index for each staleToRestore entry
+        const staleRestoreDiffIndices = [];
+        let staleHasError = false;
         if (historyAvailable && !hasUnresolvableSkippedPath) {
             const lastFiles = history.getLastPullFiles();
             const currentPaths = new Set(writeTargets.map((t) => t.targetPath));
@@ -457,22 +615,253 @@ function pullCommand() {
                 if (meta.existedBeforeAvanti) {
                     const original = history.readVersion(ref.absolutePath, 0);
                     if (original !== null) {
-                        staleToRestore.push({
-                            targetPath: ref.absolutePath,
-                            content: original,
-                        });
-                        staleDiffs.push((0, diff_1.computeDiff)(ref.absolutePath, original));
+                        if (meta.v0IsSymlink) {
+                            if (process.platform === 'win32') {
+                                console.error(`symlink: ${ref.absolutePath}: cannot restore pre-avanti symlink on Windows`);
+                                staleHasError = true;
+                                // Show the actual stored target so the user knows what cannot
+                                // be restored. No staleRestoreDiffIndices push — there is no
+                                // corresponding staleToRestore entry for error-only diffs.
+                                const symlinkTarget = original.toString('utf8');
+                                const warnDiff = (0, diff_1.buildNewSymlinkDiff)(ref.absolutePath, symlinkTarget);
+                                staleDiffs.push({ ...warnDiff, hasChanges: true });
+                            }
+                            else {
+                                const symlinkTarget = original.toString('utf8');
+                                const staleDiff = (0, diff_1.computeSymlinkDiff)(ref.absolutePath, symlinkTarget);
+                                if (staleDiff.isDirectory) {
+                                    console.error(`symlink: ${ref.absolutePath} is a directory; cannot restore symlink over directory`);
+                                    staleHasError = true;
+                                    // No staleRestoreDiffIndices push — no corresponding
+                                    // staleToRestore entry for this error-only diff.
+                                    staleDiffs.push(staleDiff);
+                                }
+                                else if (staleDiff.hasChanges) {
+                                    staleToRestore.push({
+                                        targetPath: ref.absolutePath,
+                                        content: original,
+                                        symlinkTarget,
+                                        sudo: meta.sudo,
+                                    });
+                                    staleRestoreDiffIndices.push(staleDiffs.length);
+                                    staleDiffs.push(staleDiff);
+                                }
+                            }
+                        }
+                        else {
+                            staleToRestore.push({
+                                targetPath: ref.absolutePath,
+                                content: original,
+                                sudo: meta.sudo,
+                            });
+                            staleRestoreDiffIndices.push(staleDiffs.length);
+                            const staleDiff = (0, diff_1.computeDiff)(ref.absolutePath, original);
+                            // A missing file with empty v0 produces isNew=true but
+                            // hasChanges=false and an empty patch, so formatDiff returns ''.
+                            // Rebuild as a proper new-file diff so the confirmation output
+                            // shows the recreate action and the patch is consistent.
+                            staleDiffs.push(staleDiff.isNew
+                                ? (0, diff_1.buildNewFileDiff)(ref.absolutePath, original)
+                                : staleDiff);
+                        }
+                    }
+                    else {
+                        console.warn(`Warning: cannot restore original for ${ref.absolutePath} — v0 was never captured (file was unreadable at first pull). Leaving file unchanged.`);
                     }
                 }
                 else {
                     staleToDelete.push(ref.absolutePath);
+                    if (meta.sudo)
+                        staleDeleteSudo.set(ref.absolutePath, meta.sudo);
+                    staleDeleteDiffIndex.set(ref.absolutePath, staleDiffs.length);
                     staleDiffs.push((0, diff_1.computeDeleteDiff)(ref.absolutePath));
                 }
             }
         }
+        // Windows does not have sudo; fail before any authentication attempt.
+        if (process.platform === 'win32' &&
+            (writeTargets.some((t) => t.sudo) ||
+                staleToRestore.some((t) => t.sudo) ||
+                staleDeleteSudo.size > 0)) {
+            console.error('sudo is not supported on Windows');
+            process.exit(2);
+        }
+        // Authenticate early for unreadable sudo files so we can read their actual
+        // content before deciding whether anything changed. Without this, every pull
+        // would show unreadable files as "changed" (we can't diff without reading),
+        // and "Nothing to do." could never be reported on a re-run.
+        const unreadableSudoValues = new Set();
+        for (let i = 0; i < writeTargets.length; i++) {
+            if (allDiffs[i].isUnreadable && writeTargets[i].sudo) {
+                unreadableSudoValues.add(writeTargets[i].sudo);
+            }
+        }
+        // Also auth for unreadable stale restore targets that need sudo.
+        for (let i = 0; i < staleToRestore.length; i++) {
+            const diffIdx = staleRestoreDiffIndices[i];
+            if (staleDiffs[diffIdx]?.isUnreadable && staleToRestore[i].sudo) {
+                unreadableSudoValues.add(staleToRestore[i].sudo);
+            }
+        }
+        const authenticatedSudoIds = new Set();
+        for (const sv of unreadableSudoValues) {
+            try {
+                (0, writer_1.sudoAuth)(sv);
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                process.exit(2);
+            }
+            authenticatedSudoIds.add(sv);
+        }
+        // For entries where lstatSync failed (parent directory not searchable),
+        // use sudoFileExists to determine whether the file actually exists so
+        // existedBeforeAvanti is recorded correctly. Also compute modeChange now
+        // that we have sudo access (computeDiff could not stat the file pre-auth).
+        for (let i = 0; i < writeTargets.length; i++) {
+            if (allDiffs[i].lstatFailed && writeTargets[i].sudo) {
+                const exists = (0, writer_1.sudoFileExists)(writeTargets[i].sudo, writeTargets[i].targetPath);
+                const isNew = !exists;
+                let modeChange = allDiffs[i].modeChange;
+                if (exists && writeTargets[i].mode) {
+                    const curModeStr = (0, writer_1.getSudoFileMode)(writeTargets[i].sudo, writeTargets[i].targetPath);
+                    if (curModeStr !== undefined) {
+                        const desired = parseInt(writeTargets[i].mode, 8);
+                        const cur = parseInt(curModeStr, 8);
+                        if (!isNaN(desired) && !isNaN(cur) && desired !== cur) {
+                            modeChange = { from: cur, to: desired };
+                        }
+                    }
+                }
+                if (isNew) {
+                    // File confirmed absent — rebuild as a proper new diff so
+                    // formatDiff shows the actual content instead of "unreadable".
+                    // Clear backupPath: it was set assuming the file existed (conservative
+                    // lstatFailed default). Since the file is actually new, there is
+                    // nothing to back up and the backup should not be created.
+                    if (writeTargets[i].symlinkTarget !== undefined) {
+                        // Symlink entry — use buildNewSymlinkDiff instead of
+                        // computeSymlinkDiff: the parent dir is still not searchable
+                        // (EACCES), so calling computeSymlinkDiff would lstatSync-fail
+                        // again and return isUnreadable rather than isNew:true.
+                        allDiffs[i] = (0, diff_1.buildNewSymlinkDiff)(allDiffs[i].targetPath, writeTargets[i].symlinkTarget);
+                    }
+                    else {
+                        allDiffs[i] = (0, diff_1.buildNewFileDiff)(allDiffs[i].targetPath, writeTargets[i].content, modeChange);
+                    }
+                    writeTargets[i] = { ...writeTargets[i], backupPath: undefined };
+                }
+                else {
+                    let updatedDiff = { ...allDiffs[i], isNew, modeChange };
+                    // For symlink entries, check whether the existing path is a real
+                    // directory — ln -sf would place the symlink inside it rather than
+                    // replacing it, so detect this now and surface an error before the
+                    // write batch is attempted.
+                    if (writeTargets[i].symlinkTarget !== undefined) {
+                        const isSymlinkAtTarget = (0, writer_1.sudoIsSymlink)(writeTargets[i].sudo, writeTargets[i].targetPath);
+                        if (!isSymlinkAtTarget &&
+                            (0, writer_1.sudoIsDirectory)(writeTargets[i].sudo, writeTargets[i].targetPath)) {
+                            updatedDiff = { ...updatedDiff, isDirectory: true };
+                        }
+                    }
+                    allDiffs[i] = updatedDiff;
+                }
+                // Propagate corrected isNew to the hook context so lifecycle hooks
+                // receive the correct AVANTI_IS_NEW value.
+                const hookIdx = fileHookContexts.findIndex((ctx) => ctx.targetPath === writeTargets[i].targetPath);
+                if (hookIdx >= 0) {
+                    fileHookContexts[hookIdx] = { ...fileHookContexts[hookIdx], isNew };
+                }
+            }
+        }
+        // Fail fast if any symlink write target is a real directory: ln -sf would
+        // place the symlink inside it rather than replacing it, so abort before
+        // prompting the user rather than failing mid-write-batch.
+        for (const d of allDiffs) {
+            if (d.isDirectory && d.isSymlink) {
+                console.error(`symlink: ${d.targetPath} is a directory; cannot replace with a symlink`);
+            }
+        }
+        if (allDiffs.some((d) => d.isDirectory && d.isSymlink)) {
+            process.exit(2);
+        }
+        // Post-auth idempotency: compare current file content via sudo against the
+        // desired content. If they match, suppress the write for this entry.
+        for (let i = 0; i < writeTargets.length; i++) {
+            if (allDiffs[i].isUnreadable && writeTargets[i].sudo) {
+                if (writeTargets[i].symlinkTarget !== undefined) {
+                    // Symlink entry: use sudo readlink to check whether the on-disk
+                    // symlink already points to the desired target. If it does, the
+                    // write is a no-op and the diff should be suppressed.
+                    const current = (0, writer_1.sudoReadlink)(writeTargets[i].sudo, writeTargets[i].targetPath);
+                    if (current !== null && current === writeTargets[i].symlinkTarget) {
+                        const updatedHasChanges = allDiffs[i].modeChange !== undefined;
+                        allDiffs[i] = {
+                            ...allDiffs[i],
+                            contentChanged: false,
+                            hasChanges: updatedHasChanges,
+                        };
+                        if (!updatedHasChanges) {
+                            const hookIdx = fileHookContexts.findIndex((ctx) => ctx.targetPath === writeTargets[i].targetPath);
+                            if (hookIdx >= 0) {
+                                fileHookContexts.splice(hookIdx, 1);
+                            }
+                        }
+                    }
+                    continue;
+                }
+                // For regular file entries: skip idempotency read when the existing
+                // path is a symlink — sudoRead follows symlinks and could compare
+                // against the wrong content (the symlink target's bytes, not the
+                // symlink itself).
+                if ((0, writer_1.sudoIsSymlink)(writeTargets[i].sudo, writeTargets[i].targetPath)) {
+                    continue;
+                }
+                const current = (0, writer_1.sudoRead)(writeTargets[i].sudo, writeTargets[i].targetPath);
+                if (current !== null && current.equals(writeTargets[i].content)) {
+                    const updatedHasChanges = allDiffs[i].modeChange !== undefined;
+                    allDiffs[i] = {
+                        ...allDiffs[i],
+                        contentChanged: false,
+                        hasChanges: updatedHasChanges,
+                    };
+                    // Only remove hook context when the diff is a true no-op (no mode
+                    // change either). A mode-only change still triggers before/afterUpdate
+                    // hooks, so the context must remain for those cases.
+                    if (!updatedHasChanges) {
+                        const hookIdx = fileHookContexts.findIndex((ctx) => ctx.targetPath === writeTargets[i].targetPath);
+                        if (hookIdx >= 0) {
+                            fileHookContexts.splice(hookIdx, 1);
+                        }
+                    }
+                }
+            }
+        }
+        // Same idempotency check for stale restore targets: if the current file
+        // content already matches the v0 original, suppress the redundant write.
+        for (let i = 0; i < staleToRestore.length; i++) {
+            const diffIdx = staleRestoreDiffIndices[i];
+            if (staleDiffs[diffIdx]?.isUnreadable && staleToRestore[i].sudo) {
+                // Skip idempotency read for symlinks: sudoRead follows symlinks and
+                // could read an unintended privileged file before write-path checks run.
+                if ((0, writer_1.sudoIsSymlink)(staleToRestore[i].sudo, staleToRestore[i].targetPath)) {
+                    continue;
+                }
+                const current = (0, writer_1.sudoRead)(staleToRestore[i].sudo, staleToRestore[i].targetPath);
+                if (current !== null && current.equals(staleToRestore[i].content)) {
+                    staleDiffs[diffIdx] = {
+                        ...staleDiffs[diffIdx],
+                        contentChanged: false,
+                        hasChanges: staleDiffs[diffIdx].modeChange !== undefined,
+                    };
+                }
+            }
+        }
         const hasChanges = allDiffs.some((d) => d.hasChanges) ||
             staleDiffs.some((d) => d.hasChanges);
         (0, diff_1.printDiffs)([...allDiffs, ...staleDiffs]);
+        if (staleHasError)
+            process.exit(2);
         // Show SHA mismatch summary when using --accept-changes
         if (opts.acceptChanges && firstPass.shaErrors.length > 0) {
             console.error('');
@@ -484,6 +873,26 @@ function pullCommand() {
                     history.saveInsertedFragment(targetPath, fragment.raw, fragment.processed);
                 }
             }
+            // Prune no-op stale refs from the pull log. When all diffs are clean,
+            // every stale entry (delete or restore) was already resolved outside of
+            // avanti (file manually deleted, or content already matches v0). Without
+            // this, those refs remain in the last-pull log and can incorrectly flag
+            // a future file at the same path as stale.
+            if (pullId &&
+                historyAvailable &&
+                (staleToDelete.length > 0 || staleToRestore.length > 0)) {
+                const noopStalePaths = new Set([
+                    ...staleToDelete,
+                    ...staleToRestore.map((t) => t.targetPath),
+                ]);
+                const lastFiles = history.getLastPullFiles();
+                const survivingRefs = lastFiles.filter((ref) => !noopStalePaths.has(ref.absolutePath));
+                // Preserve existing sudo on surviving refs — no file was written, so
+                // the on-disk ownership reflects the previous write identity, not the
+                // current config. Overwriting here would let stale cleanup run with
+                // the wrong privileges for a file it never re-wrote.
+                history.closePullSession(pullId, (0, config_1.normalizeConfigKey)(configPath), survivingRefs);
+            }
             console.log('Nothing to do.');
             process.exit(0);
         }
@@ -531,6 +940,74 @@ function pullCommand() {
                 }
             }
         }
+        for (const ctx of fileHookContexts) {
+            const env = {
+                AVANTI_TARGET: ctx.targetPath,
+                AVANTI_IS_NEW: String(ctx.isNew),
+            };
+            const runNamedHook = (key, script) => {
+                try {
+                    (0, on_1.runHook)(script, env);
+                }
+                catch (err) {
+                    console.error(`Hook ${key} failed for ${ctx.targetPath}: ${err instanceof Error ? err.message : String(err)}`);
+                    process.exit(2);
+                }
+            };
+            if (ctx.hooks.beforeWrite)
+                runNamedHook('beforeWrite', ctx.hooks.beforeWrite);
+            if (ctx.isNew && ctx.hooks.beforeCreate)
+                runNamedHook('beforeCreate', ctx.hooks.beforeCreate);
+            if (!ctx.isNew && ctx.hooks.beforeUpdate)
+                runNamedHook('beforeUpdate', ctx.hooks.beforeUpdate);
+        }
+        // Compute write batches and authenticate before staging so that sudo is
+        // available for v0 capture of unreadable first-seen files (history must
+        // record the original content before it is overwritten).
+        const changedTargets = writeTargets.filter((_, i) => allDiffs[i].hasChanges && allDiffs[i].contentChanged);
+        // Only include stale restore targets whose diff still has changes (not
+        // suppressed by the idempotency check above). Also include diffs where
+        // isNew is true: a missing file with empty v0 produces hasChanges=false
+        // ('' !== '' = false) but still needs to be written.
+        const activeStaleRestoreIndices = staleToRestore
+            .map((_, i) => i)
+            .filter((i) => {
+            const d = staleDiffs[staleRestoreDiffIndices[i]];
+            return d?.hasChanges || d?.isNew;
+        });
+        const activeStaleRestore = activeStaleRestoreIndices.map((i) => staleToRestore[i]);
+        const sudoValues = new Set([...changedTargets, ...activeStaleRestore]
+            .map((t) => t.sudo)
+            .filter(Boolean));
+        // Only include stale delete sudo identities when the delete diff still
+        // has changes (file wasn't already absent at diff time).
+        for (const [p, sv] of staleDeleteSudo) {
+            const idx = staleDeleteDiffIndex.get(p);
+            if (idx !== undefined && staleDiffs[idx].hasChanges) {
+                sudoValues.add(sv);
+            }
+        }
+        for (let i = 0; i < writeTargets.length; i++) {
+            if (allDiffs[i].modeChange &&
+                !allDiffs[i].contentChanged &&
+                writeTargets[i].sudo) {
+                sudoValues.add(writeTargets[i].sudo);
+            }
+        }
+        // Skip identities already authenticated in the early unreadable-file pass
+        // so a single pull session never re-prompts for the same identity.
+        for (const sv of sudoValues) {
+            if (!authenticatedSudoIds.has(sv)) {
+                try {
+                    (0, writer_1.sudoAuth)(sv);
+                }
+                catch (err) {
+                    console.error(err instanceof Error ? err.message : String(err));
+                    process.exit(2);
+                }
+                authenticatedSudoIds.add(sv);
+            }
+        }
         // Stage history versions before atomicWrite so v0 is captured before overwrite
         const stagedFileRefs = [];
         if (pullId) {
@@ -553,7 +1030,36 @@ function pullCommand() {
                                 acceptedShaLabels.has(r.sourceLabel),
                         }))
                         : undefined;
-                    const { fileRef } = history.stageFileVersion(pullId, targetPath, writeTargets[i].content, allDiffs[i].isNew, sourceShaRecords);
+                    // For a first-seen unreadable sudo file, capture v0 via sudo so
+                    // revert-to-original works even when the invoking user cannot read
+                    // the file directly.
+                    let v0Override;
+                    let v0IsSymlinkOverride = false;
+                    if (allDiffs[i].isUnreadable &&
+                        !allDiffs[i].isNew &&
+                        writeTargets[i].sudo &&
+                        !history.getFileMeta(targetPath)) {
+                        if ((0, writer_1.sudoIsSymlink)(writeTargets[i].sudo, targetPath)) {
+                            if (writeTargets[i].symlinkTarget !== undefined) {
+                                // Destination is a symlink and so is the write target — read
+                                // the existing link target via sudoReadlink so v0 records the
+                                // original symlink destination for faithful revert/reset.
+                                const existingTarget = (0, writer_1.sudoReadlink)(writeTargets[i].sudo, targetPath);
+                                if (existingTarget !== null) {
+                                    v0Override = Buffer.from(existingTarget);
+                                    v0IsSymlinkOverride = true;
+                                }
+                            }
+                            // If the write target is a regular file but the destination is a
+                            // symlink, skip v0: sudoRead would follow the symlink and could
+                            // read an unintended privileged file before write-path checks run.
+                        }
+                        else {
+                            v0Override =
+                                (0, writer_1.sudoRead)(writeTargets[i].sudo, targetPath) ?? undefined;
+                        }
+                    }
+                    const { fileRef } = history.stageFileVersion(pullId, targetPath, writeTargets[i].content, allDiffs[i].isNew, sourceShaRecords, writeTargets[i].sudo, v0Override, !!writeTargets[i].symlinkTarget, v0IsSymlinkOverride);
                     stagedFileRefs.push(fileRef);
                 }
                 catch {
@@ -561,11 +1067,76 @@ function pullCommand() {
                 }
             }
         }
+        let postWriteError = null;
+        const effectivelyDeleted = new Set();
+        const effectivelyRestored = new Set();
+        // Tracks all stale paths fully resolved this pull — including no-ops
+        // (file already gone, or already matches v0). Used to prune old refs
+        // from history so stale cleanup does not repeat on subsequent pulls.
+        const effectivelyCleaned = new Set();
         try {
-            const changedTargets = writeTargets.filter((_, i) => allDiffs[i].hasChanges && allDiffs[i].contentChanged);
+            // changedTargets and sudoValues already computed above; auth already done.
             // Content writes go first so that if atomicWrite throws, no permissions
             // have been changed yet (minimises partial-apply surface).
-            (0, writer_1.atomicWrite)([...changedTargets, ...staleToRestore], staleToDelete);
+            const isSudoTarget = (t) => !!t.sudo;
+            const regularChanged = changedTargets.filter((t) => !t.sudo);
+            const sudoChanged = changedTargets.filter(isSudoTarget);
+            // Only restore entries whose diff still has changes (no-op restores filtered out)
+            const regularRestore = activeStaleRestore.filter((t) => !t.sudo);
+            const sudoRestore = activeStaleRestore.filter(isSudoTarget);
+            const regularDelete = staleToDelete.filter((p) => !staleDeleteSudo.has(p));
+            (0, writer_1.atomicWrite)([...regularChanged, ...regularRestore]);
+            if (sudoChanged.length + sudoRestore.length > 0) {
+                (0, writer_1.sudoAtomicWrite)([...sudoChanged, ...sudoRestore]);
+            }
+            // Mark all active stale restores as completed (atomicWrite throws on
+            // failure so if we reach here all restores were written successfully).
+            for (const t of activeStaleRestore) {
+                effectivelyRestored.add(t.targetPath);
+                effectivelyCleaned.add(t.targetPath);
+            }
+            // No-op stale restores (file already matches v0) are also cleaned —
+            // mark them so their refs are removed from history and the cleanup
+            // does not repeat on subsequent pulls.
+            const activeStaleRestorePaths = new Set(activeStaleRestore.map((t) => t.targetPath));
+            for (const t of staleToRestore) {
+                if (!activeStaleRestorePaths.has(t.targetPath)) {
+                    effectivelyCleaned.add(t.targetPath);
+                }
+            }
+            // Deletions are deferred until both write batches succeed so that
+            // stale files are not removed if a later write batch fails.
+            for (const p of regularDelete) {
+                const idx = staleDeleteDiffIndex.get(p);
+                if (idx === undefined)
+                    continue;
+                if (!staleDiffs[idx].hasChanges) {
+                    // File is already gone — no-op, but still clean up its history ref.
+                    effectivelyCleaned.add(p);
+                    continue;
+                }
+                try {
+                    fs.rmSync(p, { force: true });
+                    effectivelyDeleted.add(p);
+                    effectivelyCleaned.add(p);
+                }
+                catch (err) {
+                    console.warn(`Warning: could not delete ${p}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            for (const [p, sv] of staleDeleteSudo) {
+                const idx = staleDeleteDiffIndex.get(p);
+                if (idx === undefined)
+                    continue;
+                if (!staleDiffs[idx].hasChanges) {
+                    // File is already gone — no-op, but still clean up its history ref.
+                    effectivelyCleaned.add(p);
+                }
+                else if ((0, writer_1.sudoDelete)(p, sv)) {
+                    effectivelyDeleted.add(p);
+                    effectivelyCleaned.add(p);
+                }
+            }
             // Mode-only changes: apply chmod directly (POSIX only — mode bits are
             // not meaningful on Windows so modeChange is never set there).
             let modeOnlyCount = 0;
@@ -573,26 +1144,72 @@ function pullCommand() {
                 for (let i = 0; i < writeTargets.length; i++) {
                     const d = allDiffs[i];
                     if (d.modeChange && !d.contentChanged) {
-                        const lst = fs.lstatSync(writeTargets[i].targetPath, {
-                            throwIfNoEntry: false,
-                        });
-                        if (lst && !lst.isSymbolicLink()) {
-                            fs.chmodSync(writeTargets[i].targetPath, d.modeChange.to);
-                            modeOnlyCount++;
+                        if (writeTargets[i].sudo) {
+                            // Use sudo for the symlink/existence checks: fs.lstatSync
+                            // throws EACCES on paths inside root-owned directories.
+                            // Skip chmod if the file has been deleted since diff
+                            // computation (mirrors non-sudo throwIfNoEntry: false path).
+                            if ((0, writer_1.sudoFileExists)(writeTargets[i].sudo, writeTargets[i].targetPath) &&
+                                !(0, writer_1.sudoIsSymlink)(writeTargets[i].sudo, writeTargets[i].targetPath)) {
+                                (0, writer_1.sudoRun)(writeTargets[i].sudo, [
+                                    'chmod',
+                                    '--',
+                                    d.modeChange.to.toString(8).padStart(4, '0'),
+                                    writeTargets[i].targetPath,
+                                ]);
+                                modeOnlyCount++;
+                            }
+                        }
+                        else {
+                            const lst = fs.lstatSync(writeTargets[i].targetPath, {
+                                throwIfNoEntry: false,
+                            });
+                            if (lst && !lst.isSymbolicLink()) {
+                                fs.chmodSync(writeTargets[i].targetPath, d.modeChange.to);
+                                modeOnlyCount++;
+                            }
                         }
                     }
                 }
             }
+            const deletedCount = effectivelyDeleted.size;
             const written = changedTargets.length +
-                staleToRestore.length +
-                staleToDelete.length +
+                activeStaleRestore.length +
+                deletedCount +
                 modeOnlyCount;
             console.log(`Wrote ${written} file(s).`);
+            for (const ctx of fileHookContexts) {
+                if (postWriteError !== null)
+                    break;
+                const env = {
+                    AVANTI_TARGET: ctx.targetPath,
+                    AVANTI_IS_NEW: String(ctx.isNew),
+                };
+                const runNamedPostHook = (key, script) => {
+                    if (postWriteError !== null)
+                        return;
+                    try {
+                        (0, on_1.runHook)(script, env);
+                    }
+                    catch (err) {
+                        postWriteError = `Hook ${key} failed for ${ctx.targetPath}: ${err instanceof Error ? err.message : String(err)}`;
+                    }
+                };
+                if (ctx.isNew && ctx.hooks.create)
+                    runNamedPostHook('create', ctx.hooks.create);
+                if (!ctx.isNew && ctx.hooks.update)
+                    runNamedPostHook('update', ctx.hooks.update);
+            }
         }
         catch (err) {
             console.error(`Write failed: ${err instanceof Error ? err.message : String(err)}`);
             process.exit(2);
         }
+        // meta.sudo is updated by stageFileVersion for every file that was
+        // actually written. No extra sync needed here: updating meta.sudo for
+        // no-op targets would overwrite the privilege identity from the last
+        // real write with a config value that was never applied to the file,
+        // causing stale cleanup to run with the wrong credentials.
         // Save inserted fragments to history for future idempotency detection
         if (historyAvailable && insertedFragments.size > 0) {
             for (const [targetPath, fragment] of insertedFragments) {
@@ -611,16 +1228,38 @@ function pullCommand() {
                 console.warn(`Warning: could not update SHA values in config: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        // Only record to pulls.jsonl if at least one file was staged (written or
-        // SHA-accepted via --accept-changes with no content diff)
-        if (pullId && stagedFileRefs.length > 0) {
+        // Record to pulls.jsonl when files were staged OR stale files were
+        // deleted/restored. For stale-only runs, merge surviving refs from the
+        // last pull so the cleaned-up paths are no longer listed — without this,
+        // subsequent pulls see the same stale files in the last-pull log and
+        // attempt the same delete/restore again on every run.
+        if (pullId &&
+            (stagedFileRefs.length > 0 || effectivelyCleaned.size > 0)) {
             try {
-                history.closePullSession(pullId, (0, config_1.normalizeConfigKey)(configPath), stagedFileRefs);
+                let refsToRecord = stagedFileRefs;
+                if (historyAvailable) {
+                    const lastFiles = history.getLastPullFiles();
+                    const survivingRefs = lastFiles.filter((ref) => !effectivelyCleaned.has(ref.absolutePath));
+                    const stagedPaths = new Set(stagedFileRefs.map((r) => r.absolutePath));
+                    // Preserve existing sudo on surviving refs — these files were not
+                    // rewritten this pull, so their on-disk ownership reflects the
+                    // previous write identity. Replacing with the current config value
+                    // would let stale cleanup run with the wrong privileges.
+                    refsToRecord = [
+                        ...survivingRefs.filter((r) => !stagedPaths.has(r.absolutePath)),
+                        ...stagedFileRefs,
+                    ];
+                }
+                history.closePullSession(pullId, (0, config_1.normalizeConfigKey)(configPath), refsToRecord);
             }
             catch {
                 console.warn('Warning: could not save pull history.');
             }
         }
+        if (postWriteError !== null) {
+            console.error(postWriteError);
+            process.exit(2);
+        }
     });
 }
 //# sourceMappingURL=pull.js.map