@lesliechan721/aw 0.1.0-beta.10 → 0.1.0-beta.12

package/dist/src/commands/rebuild-operations.d.ts

@@ -1,6 +1,7 @@
 import type { GeneratedArtifact, CatalogResolution, PlatformName, PluginMeta, RebuildActionEvent, RebuildActionName, RebuildCommand, Scope } from '../types.js';
+import { type SafeOperationErrorMetadata } from '../utils/safe-operation-diagnostic.js';
 import type { OperationAction } from './operation-plan.js';
-import { type NativeOwnershipProbe, type NativeOwnershipRemove, type OwnedComponent, type OwnedComponentExecutor } from '../utils/ownership.js';
+import { type NativeOwnershipProbe, type NativeOwnershipRemove, type OwnedComponent, type OwnedComponentExecutor, type OwnershipInspection } from '../utils/ownership.js';
 export type { RebuildActionName, RebuildCommand } from '../types.js';
 export interface RebuildTargetIdentity {
     sourceId?: string;
@@ -22,11 +23,13 @@ export interface DesiredTarget {
     optionalOwnedComponents?: readonly OwnedComponent[];
     requiresNative: boolean;
     writeNativeRequired?: boolean;
+    nativeOverlayDesired?: boolean;
     codexNativeObservationExpectation?: 'observed' | 'installed';
+    codexNativeSensitivePreflightRequired?: boolean;
     artifacts: readonly GeneratedArtifact[];
     operationActions?: readonly OperationAction[];
     catalog?: CatalogResolution;
-    postApplySource: PluginMeta;
+    preApplySource: PluginMeta;
     forceExclusiveCleanup?: boolean;
 }
 export interface RebuildAction {
@@ -37,6 +40,7 @@ export interface RebuildFailure {
     phase: RebuildActionName | 'preflight';
     message: string;
     label?: string;
+    operationDiagnostic?: SafeOperationErrorMetadata;
 }
 interface RebuildResultBase {
     command: RebuildCommand;
@@ -57,40 +61,74 @@ export interface RebuildFailedResult extends RebuildResultBase {
     error: {
         phase: RebuildFailure['phase'];
         message: string;
+        operationDiagnostic?: SafeOperationErrorMetadata;
     };
 }
 export type RebuildResult = RebuildSucceededResult | RebuildFailedResult;
-export interface RebuildPostApplyInvocation {
+export interface RebuildPreApplyInvocation {
     target: DesiredTarget;
     plugin: PluginMeta;
-    artifacts: readonly GeneratedArtifact[];
-    components: Array<{
-        kind: string;
-        key: string;
-        outcome: 'created' | 'updated' | 'removed' | 'unchanged';
-    }>;
 }
 export interface RebuildTargetDriver {
     ownership: OwnedComponentExecutor;
     preflightMutation?(target: DesiredTarget): Promise<void>;
     preflightMaterialize?(target: DesiredTarget): Promise<void>;
-    commitMaterialize?(target: DesiredTarget): Promise<void>;
-    rollbackMaterialize?(target: DesiredTarget): Promise<void>;
+    selectRecoveryCleanupComponents?(target: DesiredTarget, components: readonly OwnedComponent[]): readonly OwnedComponent[];
+    deferPostcheck?(target: DesiredTarget, postcheck: () => Promise<void>): boolean;
+    completePostchecks?(): Promise<readonly DeferredRebuildPostcheckFailure[]>;
     finalizeCleanup?(target: DesiredTarget): Promise<void>;
     writeNative(target: DesiredTarget): Promise<void>;
     writeArtifacts(target: DesiredTarget): Promise<void | readonly GeneratedArtifact[]>;
     probeNative?: NativeOwnershipProbe;
     probeNativeHealth?: NativeOwnershipProbe;
     removeNative?: NativeOwnershipRemove;
-    runPostApply(invocation: RebuildPostApplyInvocation): Promise<void>;
+    runPreApply(invocation: RebuildPreApplyInvocation): Promise<void>;
+}
+export interface DeferredRebuildPostcheckFailure {
+    target: DesiredTarget;
+    error: unknown;
 }
+export interface PreparedRebuildOperation {
+    command: RebuildCommand;
+    target: DesiredTarget;
+    inspection: OwnershipInspection;
+    actions: RebuildAction[];
+}
+export type PrepareRebuildOperationResult = {
+    status: 'ready';
+    preparation: PreparedRebuildOperation;
+} | {
+    status: 'failed';
+    result: RebuildResult;
+};
+export declare function executeRebuildComponentCleanup(options: {
+    command: RebuildCommand;
+    target: DesiredTarget;
+    driver: RebuildTargetDriver;
+    components: readonly OwnedComponent[];
+    actions?: readonly RebuildAction[];
+    onActionEvent?: (event: RebuildActionEvent) => void | Promise<void>;
+    now?: () => number;
+    beforeMutation?: (component: OwnedComponent) => Promise<void>;
+    afterQuarantine?: (component: OwnedComponent, quarantinePath: string) => Promise<void>;
+}): Promise<RebuildResult>;
 export declare function executeRebuildOperation(options: {
     command: RebuildCommand;
     target: DesiredTarget;
     driver: RebuildTargetDriver;
+    preparation?: PreparedRebuildOperation;
     onActionEvent?: (event: RebuildActionEvent) => void | Promise<void>;
     now?: () => number;
 }): Promise<RebuildResult>;
+export declare function prepareRebuildOperation(options: {
+    command: 'install' | 'sync' | 'reinstall';
+    target: DesiredTarget;
+    driver: RebuildTargetDriver;
+    deferNativeInspection?: boolean;
+    skipPreApply?: boolean;
+    onActionEvent?: (event: RebuildActionEvent) => void | Promise<void>;
+    now?: () => number;
+}): Promise<PrepareRebuildOperationResult>;
 export declare function executeRebuildTargets(options: {
     command: RebuildCommand;
     targets: readonly DesiredTarget[];

package/dist/src/commands/rebuild-operations.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { readSafeOperationError } from '../utils/safe-operation-diagnostic.js';
 import { cleanupOwnedComponents, inspectOwnedComponents, validateOwnerIdentity, } from '../utils/ownership.js';
 function artifactIdentity(artifact) {
     return [
@@ -40,10 +41,8 @@ const REBUILD_ACTION_FAILURE_MESSAGES = {
     'stale.cleanup': '清理过期组件失败。',
     'native.write': '写入平台插件失败。',
     'artifacts.write': '写入插件文件失败。',
-    postApply: '运行 postApply 失败。',
+    preApply: '运行 preApply 失败。',
     'postcheck.inspect': '检查写入结果失败。',
-    'marketplace.commit': '提交 marketplace generation 失败。',
-    'marketplace.rollback': '回滚 marketplace generation 失败。',
     'recovery.cleanup': '清理失败写入失败。',
     'cleanup.owned': '清理 AW 组件失败。',
 };
@@ -78,16 +77,16 @@ function mergeCleanup(accumulator, cleanup, phase) {
 function succeeded(command, target, accumulator) {
     return { status: 'succeeded', command, target: target.identity, ...accumulator };
 }
-function failed(command, target, accumulator, phase, message) {
+function failed(command, target, accumulator, phase, message, operationDiagnostic) {
     if (!accumulator.failures.some((failure) => failure.phase === phase && failure.message === message)) {
-        accumulator.failures.unshift({ phase, message });
+        accumulator.failures.unshift({ phase, message, ...(operationDiagnostic ? { operationDiagnostic } : {}) });
     }
     return {
         status: 'failed',
         command,
         target: target.identity,
         ...accumulator,
-        error: { phase, message },
+        error: { phase, message, ...(operationDiagnostic ? { operationDiagnostic } : {}) },
     };
 }
 async function action(accumulator, name, operation, events, failureMessage) {
@@ -158,10 +157,10 @@ function validateDesiredTarget(target) {
         throw new Error('Desired target has an invalid namespaced source identity.');
     }
     if (target.plugin.manifest.name !== pluginName
-        || target.postApplySource.manifest.name !== pluginName
+        || target.preApplySource.manifest.name !== pluginName
         || target.plugin.manifest.version !== pluginVersion
-        || target.postApplySource.manifest.version !== pluginVersion) {
-        throw new Error('Desired target plugin name/version does not match its postApply source and identity.');
+        || target.preApplySource.manifest.version !== pluginVersion) {
+        throw new Error('Desired target plugin name/version does not match its preApply source and identity.');
     }
     if (platform !== 'codex' && platform !== 'claude') {
         throw new Error(`Desired target platform is invalid: ${String(platform)}`);
@@ -295,19 +294,20 @@ function postcheckMessage(accumulator, inspection) {
         return diagnostics.join('; ');
     return `Post-install ownership inspection failed for ${invalid.length} component(s).`;
 }
-async function cleanupOwned(target, driver, components = target.ownedComponents) {
+async function cleanupOwned(target, driver, components = target.ownedComponents, hooks = {}) {
     return cleanupOwnedComponents({
         components,
         executor: driver.ownership,
         nativeProbe: driver.probeNative,
         nativeRemove: driver.removeNative,
         forceExclusive: target.forceExclusiveCleanup,
+        ...hooks,
     });
 }
-async function cleanupTarget(target, driver, accumulator, ownedAction, events, components = target.ownedComponents) {
+async function cleanupTarget(target, driver, accumulator, ownedAction, events, components = target.ownedComponents, hooks = {}) {
     accumulator.cleanupAttempted = true;
     try {
-        const cleanup = await action(accumulator, ownedAction, () => cleanupOwned(target, driver, components), events, (value) => value.failures[0]?.message
+        const cleanup = await action(accumulator, ownedAction, () => cleanupOwned(target, driver, components, hooks), events, (value) => value.failures[0]?.message
             ?? (value.residual.length > 0
                 ? `Ownership cleanup left residual components: ${value.residual.join(', ')}`
                 : value.quarantined.length > 0
@@ -333,32 +333,62 @@ async function cleanupTarget(target, driver, accumulator, ownedAction, events, c
     }
     return null;
 }
+export async function executeRebuildComponentCleanup(options) {
+    const accumulator = createAccumulator();
+    accumulator.actions.push(...(options.actions ?? []));
+    const cleanupError = await cleanupTarget(options.target, options.driver, accumulator, 'cleanup.owned', {
+        command: options.command,
+        target: options.target.identity,
+        emit: options.onActionEvent,
+        now: options.now ?? Date.now,
+    }, options.components, {
+        ...(options.beforeMutation ? { beforeMutation: options.beforeMutation } : {}),
+        ...(options.afterQuarantine ? { afterQuarantine: options.afterQuarantine } : {}),
+    });
+    return cleanupError
+        ? failed(options.command, options.target, accumulator, cleanupError.phase, cleanupError.message)
+        : succeeded(options.command, options.target, accumulator);
+}
 async function materializeTarget(options) {
     const { command, target, driver, accumulator, events } = options;
-    let inspection;
-    try {
-        inspection = await action(accumulator, 'preflight.inspect', async () => {
-            await driver.preflightMaterialize?.(target);
-            return inspectOwnedComponents({
-                components: target.ownedComponents,
-                executor: driver.ownership,
-                nativeProbe: driver.probeNative,
-            });
-        }, events, collisionMessage);
-    }
-    catch (error) {
-        return failed(command, target, accumulator, 'preflight.inspect', errorMessage(error));
+    let inspection = options.inspection;
+    if (!inspection) {
+        try {
+            inspection = await action(accumulator, 'preflight.inspect', async () => {
+                await driver.preflightMaterialize?.(target);
+                return inspectOwnedComponents({
+                    components: target.ownedComponents,
+                    executor: driver.ownership,
+                    nativeProbe: driver.probeNative,
+                });
+            }, events, collisionMessage);
+        }
+        catch (error) {
+            return failed(command, target, accumulator, 'preflight.inspect', errorMessage(error), readSafeOperationError(error));
+        }
     }
     const collision = collisionMessage(inspection);
     if (collision) {
         recordInspectionResiduals(accumulator, inspection);
         return failed(command, target, accumulator, 'preflight.inspect', collision);
     }
+    if (!options.preApplyCompleted && target.preApplySource.manifest.scripts?.preApply) {
+        try {
+            await action(accumulator, 'preApply', () => driver.runPreApply({
+                target,
+                plugin: target.preApplySource,
+            }), events);
+        }
+        catch (error) {
+            return failed(command, target, accumulator, 'preApply', errorMessage(error), readSafeOperationError(error));
+        }
+    }
     const desiredComponents = new Set(target.desiredOwnedComponents ?? target.ownedComponents);
     const optionalComponents = new Set(target.optionalOwnedComponents ?? []);
     const staleComponents = target.ownedComponents.filter((component) => !desiredComponents.has(component) && !optionalComponents.has(component));
     const staleInspection = inspection.components.filter((entry) => staleComponents.includes(entry.component));
-    if (staleInspection.some((component) => component.state === 'present')) {
+    if (!options.skipStaleCleanup
+        && staleInspection.some((component) => component.state === 'present')) {
         accumulator.cleanupAttempted = true;
         let stale;
         try {
@@ -368,7 +398,7 @@ async function materializeTarget(options) {
                     : undefined));
         }
         catch (error) {
-            return failed(command, target, accumulator, 'stale.cleanup', errorMessage(error));
+            return failed(command, target, accumulator, 'stale.cleanup', errorMessage(error), readSafeOperationError(error));
         }
         mergeCleanup(accumulator, stale, 'stale.cleanup');
         if (stale.failures.length > 0 || stale.residual.length > 0) {
@@ -388,8 +418,7 @@ async function materializeTarget(options) {
             const writtenArtifacts = await driver.writeArtifacts(target);
             bindWrittenArtifacts(target, writtenArtifacts);
         }, events);
-        failurePhase = 'postcheck.inspect';
-        await action(accumulator, failurePhase, async () => {
+        const postcheck = () => action(accumulator, 'postcheck.inspect', async () => {
             const optional = new Set(target.optionalOwnedComponents ?? []);
             const postcheck = await inspectOwnedComponents({
                 components: (target.desiredOwnedComponents ?? target.ownedComponents)
@@ -402,70 +431,26 @@ async function materializeTarget(options) {
             if (postcheckFailure)
                 throw new Error(postcheckFailure);
         }, events);
-        if (driver.commitMaterialize) {
-            failurePhase = 'marketplace.commit';
-            await action(accumulator, failurePhase, () => driver.commitMaterialize(target), events);
-        }
-        try {
-            const postApplyComponents = inspection.components.map((entry) => ({
-                kind: entry.component.kind,
-                key: entry.component.identity.artifactKey,
-                outcome: (optionalComponents.has(entry.component)
-                    ? 'unchanged'
-                    : !desiredComponents.has(entry.component)
-                        ? (entry.state === 'present' ? 'removed' : 'unchanged')
-                        : entry.state === 'absent'
-                            ? 'created'
-                            : entry.state === 'present'
-                                ? 'unchanged'
-                                : 'updated'),
-            }));
-            await action(accumulator, 'postApply', () => driver.runPostApply({
-                target,
-                plugin: target.postApplySource,
-                artifacts: target.artifacts,
-                components: postApplyComponents,
-            }), events);
-        }
-        catch (error) {
-            void error;
+        failurePhase = 'postcheck.inspect';
+        if (driver.deferPostcheck?.(target, postcheck) !== true) {
+            await postcheck();
         }
         return succeeded(command, target, accumulator);
     }
     catch (error) {
         const primary = errorMessage(error);
-        if (error.durableMaterializeCommit === true) {
-            return failed(command, target, accumulator, failurePhase, primary);
+        if (error.nativeMarketplaceGroupFailure === true) {
+            return failed(command, target, accumulator, failurePhase, primary, readSafeOperationError(error));
         }
         if (target.identity.platform === 'codex') {
-            await cleanupTarget(target, driver, accumulator, 'recovery.cleanup', events, target.ownedComponents.filter((component) => component.kind === 'skill-directory' || component.kind === 'owned-text-file'));
-            if (driver.rollbackMaterialize) {
-                try {
-                    await action(accumulator, 'marketplace.rollback', () => driver.rollbackMaterialize(target), events);
-                }
-                catch (rollbackError) {
-                    accumulator.failures.push({
-                        phase: 'marketplace.rollback',
-                        message: errorMessage(rollbackError),
-                    });
-                }
-            }
+            const recoveryComponents = target.ownedComponents.filter((component) => component.kind === 'skill-directory' || component.kind === 'owned-text-file');
+            await cleanupTarget(target, driver, accumulator, 'recovery.cleanup', events, driver.selectRecoveryCleanupComponents?.(target, recoveryComponents)
+                ?? recoveryComponents);
         }
         else {
             await cleanupTarget(target, driver, accumulator, 'recovery.cleanup', events);
-            if (driver.rollbackMaterialize) {
-                try {
-                    await action(accumulator, 'marketplace.rollback', () => driver.rollbackMaterialize(target), events);
-                }
-                catch (rollbackError) {
-                    accumulator.failures.push({
-                        phase: 'marketplace.rollback',
-                        message: errorMessage(rollbackError),
-                    });
-                }
-            }
         }
-        return failed(command, target, accumulator, failurePhase, primary);
+        return failed(command, target, accumulator, failurePhase, primary, readSafeOperationError(error));
     }
 }
 async function executeCleanup(options) {
@@ -527,6 +512,25 @@ export async function executeRebuildOperation(options) {
         emit: options.onActionEvent,
         now: options.now ?? Date.now,
     };
+    if (options.preparation) {
+        if (options.preparation.command !== options.command
+            || options.preparation.target !== options.target) {
+            return failed(options.command, options.target, accumulator, 'preflight', 'Prepared rebuild operation does not match the requested target.');
+        }
+        accumulator.actions.push(...options.preparation.actions);
+        try {
+            await options.driver.preflightMutation?.(options.target);
+        }
+        catch (error) {
+            return failed(options.command, options.target, accumulator, 'preflight', errorMessage(error));
+        }
+        try {
+            return await executeRebuildOperationCore(options, accumulator, events, options.preparation);
+        }
+        catch (error) {
+            return failed(options.command, options.target, accumulator, 'preflight', errorMessage(error));
+        }
+    }
     try {
         validateDesiredTarget(options.target);
     }
@@ -546,7 +550,7 @@ export async function executeRebuildOperation(options) {
         return failed(options.command, options.target, accumulator, 'preflight', errorMessage(error));
     }
 }
-async function executeRebuildOperationCore(options, accumulator, events) {
+async function executeRebuildOperationCore(options, accumulator, events, preparation) {
     if (options.command === 'install') {
         return materializeTarget({
             command: options.command,
@@ -554,6 +558,10 @@ async function executeRebuildOperationCore(options, accumulator, events) {
             driver: options.driver,
             accumulator,
             events,
+            ...(preparation ? {
+                inspection: preparation.inspection,
+                preApplyCompleted: true,
+            } : {}),
         });
     }
     if (options.command === 'cleanup') {
@@ -573,24 +581,37 @@ async function executeRebuildOperationCore(options, accumulator, events) {
             events,
         });
     }
-    let inspection;
-    try {
-        inspection = await action(accumulator, 'preflight.inspect', async () => {
-            await options.driver.preflightMaterialize?.(options.target);
-            return inspectOwnedComponents({
-                components: options.target.ownedComponents,
-                executor: options.driver.ownership,
-                nativeProbe: options.driver.probeNative,
-            });
-        }, events, collisionMessage);
-    }
-    catch (error) {
-        return failed('reinstall', options.target, accumulator, 'preflight.inspect', errorMessage(error));
-    }
-    const collision = collisionMessage(inspection);
-    if (collision) {
-        recordInspectionResiduals(accumulator, inspection);
-        return failed('reinstall', options.target, accumulator, 'preflight.inspect', collision);
+    let inspection = preparation?.inspection;
+    if (!inspection) {
+        try {
+            inspection = await action(accumulator, 'preflight.inspect', async () => {
+                await options.driver.preflightMaterialize?.(options.target);
+                return inspectOwnedComponents({
+                    components: options.target.ownedComponents,
+                    executor: options.driver.ownership,
+                    nativeProbe: options.driver.probeNative,
+                });
+            }, events, collisionMessage);
+        }
+        catch (error) {
+            return failed('reinstall', options.target, accumulator, 'preflight.inspect', errorMessage(error));
+        }
+        const collision = collisionMessage(inspection);
+        if (collision) {
+            recordInspectionResiduals(accumulator, inspection);
+            return failed('reinstall', options.target, accumulator, 'preflight.inspect', collision);
+        }
+        if (options.target.preApplySource.manifest.scripts?.preApply) {
+            try {
+                await action(accumulator, 'preApply', () => options.driver.runPreApply({
+                    target: options.target,
+                    plugin: options.target.preApplySource,
+                }), events);
+            }
+            catch (error) {
+                return failed('reinstall', options.target, accumulator, 'preApply', errorMessage(error), readSafeOperationError(error));
+            }
+        }
     }
     const cleanupResult = await executeCleanup({
         command: 'reinstall',
@@ -607,8 +628,79 @@ async function executeRebuildOperationCore(options, accumulator, events) {
         driver: options.driver,
         accumulator,
         events,
+        inspection,
+        preApplyCompleted: true,
+        skipStaleCleanup: true,
     });
 }
+export async function prepareRebuildOperation(options) {
+    const accumulator = createAccumulator();
+    const events = {
+        command: options.command,
+        target: options.target.identity,
+        emit: options.onActionEvent,
+        now: options.now ?? Date.now,
+    };
+    try {
+        validateDesiredTarget(options.target);
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            result: failed(options.command, options.target, accumulator, 'preflight', errorMessage(error)),
+        };
+    }
+    let inspection;
+    try {
+        inspection = await action(accumulator, 'preflight.inspect', async () => {
+            await options.driver.preflightMaterialize?.(options.target);
+            return inspectOwnedComponents({
+                components: options.deferNativeInspection
+                    ? options.target.ownedComponents.filter((component) => component.kind !== 'native-plugin')
+                    : options.target.ownedComponents,
+                executor: options.driver.ownership,
+                nativeProbe: options.driver.probeNative,
+            });
+        }, events, collisionMessage);
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            result: failed(options.command, options.target, accumulator, 'preflight.inspect', errorMessage(error)),
+        };
+    }
+    const collision = collisionMessage(inspection);
+    if (collision) {
+        recordInspectionResiduals(accumulator, inspection);
+        return {
+            status: 'failed',
+            result: failed(options.command, options.target, accumulator, 'preflight.inspect', collision),
+        };
+    }
+    if (!options.skipPreApply && options.target.preApplySource.manifest.scripts?.preApply) {
+        try {
+            await action(accumulator, 'preApply', () => options.driver.runPreApply({
+                target: options.target,
+                plugin: options.target.preApplySource,
+            }), events);
+        }
+        catch (error) {
+            return {
+                status: 'failed',
+                result: failed(options.command, options.target, accumulator, 'preApply', errorMessage(error), readSafeOperationError(error)),
+            };
+        }
+    }
+    return {
+        status: 'ready',
+        preparation: {
+            command: options.command,
+            target: options.target,
+            inspection,
+            actions: accumulator.actions,
+        },
+    };
+}
 export async function executeRebuildTargets(options) {
     const results = [];
     for (const target of options.targets) {
@@ -620,6 +712,20 @@ export async function executeRebuildTargets(options) {
             ...(options.now ? { now: options.now } : {}),
         }));
     }
+    const postcheckFailures = await options.driver.completePostchecks?.() ?? [];
+    for (const failure of postcheckFailures) {
+        const index = results.findIndex((result) => result.target === failure.target.identity);
+        if (index === -1 || results[index].status === 'failed')
+            continue;
+        const result = results[index];
+        const message = errorMessage(failure.error);
+        result.failures.unshift({ phase: 'postcheck.inspect', message });
+        results[index] = {
+            ...result,
+            status: 'failed',
+            error: { phase: 'postcheck.inspect', message },
+        };
+    }
     return results;
 }
 //# sourceMappingURL=rebuild-operations.js.map