@sharpee/stdlib 0.9.60-beta

package/dist/actions/base/migration-shim.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Migration shim for transitioning actions to the three-phase pattern
+ *
+ * This provides utilities to help migrate existing actions from the
+ * two-phase pattern (validate + execute) to the three-phase pattern
+ * (validate + execute + report).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThreePhaseAction = void 0;
+exports.createThreePhaseAction = createThreePhaseAction;
+exports.adaptOldAction = adaptOldAction;
+exports.splitExecuteMethod = splitExecuteMethod;
+exports.createMigrationLogger = createMigrationLogger;
+/**
+ * Base class for migrating actions to three-phase pattern
+ *
+ * Subclasses can override executeWithMutation() and generateReport()
+ * to implement the new pattern while maintaining compatibility.
+ */
+class ThreePhaseAction {
+    requiredMessages;
+    descriptionMessageId;
+    examplesMessageId;
+    group;
+    priority;
+    /**
+     * Execute phase - handles both old and new patterns
+     *
+     * This method checks if the subclass has implemented the new pattern.
+     * If so, it calls executeWithMutation() and returns void.
+     * Otherwise, it falls back to the old pattern.
+     */
+    execute(context) {
+        // Check if subclass implements the new pattern
+        if (this.executeWithMutation && this.generateReport) {
+            // New pattern: perform mutations and return void
+            this.executeWithMutation(context);
+            return;
+        }
+        // Old pattern: must be overridden in subclass
+        throw new Error(`Action ${this.id} must implement either executeWithMutation/generateReport ` +
+            `or override execute() to return events`);
+    }
+    /**
+     * Report phase - generate events after mutations
+     *
+     * This is automatically used when executeWithMutation is implemented.
+     */
+    report(context) {
+        if (this.generateReport) {
+            return this.generateReport(context);
+        }
+        // Should never reach here if execute() is properly implemented
+        throw new Error(`Action ${this.id} must implement generateReport()`);
+    }
+}
+exports.ThreePhaseAction = ThreePhaseAction;
+/**
+ * Helper to create a three-phase action from functions
+ *
+ * This is useful for quickly converting existing actions without
+ * creating a full class.
+ */
+function createThreePhaseAction(config) {
+    return {
+        id: config.id,
+        requiredMessages: config.requiredMessages,
+        descriptionMessageId: config.descriptionMessageId,
+        examplesMessageId: config.examplesMessageId,
+        group: config.group,
+        priority: config.priority,
+        validate: config.validate,
+        execute: (context) => {
+            config.execute(context);
+            return; // Return void for new pattern
+        },
+        report: config.report
+    };
+}
+/**
+ * Adapter to wrap old-style actions in the new interface
+ *
+ * This allows old actions to work with the new CommandExecutor
+ * without modification.
+ */
+function adaptOldAction(oldAction) {
+    return {
+        ...oldAction,
+        // Old pattern: execute returns events directly
+        execute: (context) => oldAction.execute(context)
+        // No report method needed for old pattern
+    };
+}
+/**
+ * Helper to split an old execute method into execute + report
+ *
+ * This helps when migrating actions that mix mutations and event generation.
+ *
+ * @param executeOld The old execute method that does both
+ * @returns Object with separate execute and report methods
+ */
+function splitExecuteMethod(executeOld) {
+    // Store events generated during execute
+    let capturedEvents = null;
+    return {
+        execute: (context) => {
+            // Run the old method but capture its events
+            capturedEvents = executeOld(context);
+            // Don't return anything (void)
+        },
+        report: (context) => {
+            // Return the captured events
+            if (!capturedEvents) {
+                throw new Error('Report called before execute');
+            }
+            const events = capturedEvents;
+            capturedEvents = null; // Reset for next execution
+            return events;
+        }
+    };
+}
+/**
+ * Create a migration wrapper that logs when old patterns are used
+ *
+ * This helps identify which actions still need migration.
+ */
+function createMigrationLogger(action, logger = console.warn) {
+    const wrapped = {
+        ...action,
+        execute: (context) => {
+            const result = action.execute(context);
+            // Check if this is the old pattern
+            if (result !== undefined && result !== null) {
+                logger(`Action ${action.id} is using old execute pattern (returns events)`);
+            }
+            return result;
+        }
+    };
+    // Add report if the original has it
+    if (action.report) {
+        wrapped.report = action.report;
+    }
+    return wrapped;
+}
+//# sourceMappingURL=migration-shim.js.map

package/dist/actions/base/migration-shim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-shim.js","sourceRoot":"","sources":["../../../src/actions/base/migration-shim.ts"],"names":[],"mappings":"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"}

package/dist/actions/base/report-helpers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Report phase helpers for reducing boilerplate across actions
+ *
+ * These helpers standardize error event generation in the report phase,
+ * ensuring consistent error handling across all stdlib actions.
+ */
+import { ActionContext, ValidationResult } from '../enhanced-types';
+import { ISemanticEvent } from '@sharpee/core';
+/**
+ * Options for error event generation
+ */
+export interface ErrorEventOptions {
+    /**
+     * Whether to include a snapshot of the direct object entity.
+     * Defaults to true if the entity exists.
+     */
+    includeTargetSnapshot?: boolean;
+    /**
+     * Whether to include a snapshot of the indirect object entity.
+     * Defaults to true if the entity exists.
+     */
+    includeIndirectSnapshot?: boolean;
+}
+/**
+ * Handle validation errors in report phase
+ *
+ * Creates standardized error events when validation fails.
+ * Returns null if validation passed (valid === true).
+ *
+ * @param context The action context
+ * @param validationResult The result from the validate phase
+ * @param options Optional configuration for snapshot capture
+ * @returns Array of error events if validation failed, null otherwise
+ *
+ * @example
+ * report(context, validationResult, executionError) {
+ *   const errorEvents = handleValidationError(context, validationResult);
+ *   if (errorEvents) return errorEvents;
+ *
+ *   // ... success logic
+ * }
+ */
+export declare function handleValidationError(context: ActionContext, validationResult?: ValidationResult, options?: ErrorEventOptions): ISemanticEvent[] | null;
+/**
+ * Handle execution errors in report phase
+ *
+ * Creates standardized error events when execution throws an error.
+ * Returns null if no execution error occurred.
+ *
+ * @param context The action context
+ * @param executionError Error thrown during execute phase (if any)
+ * @returns Array of error events if execution failed, null otherwise
+ *
+ * @example
+ * report(context, validationResult, executionError) {
+ *   const errorEvents = handleExecutionError(context, executionError);
+ *   if (errorEvents) return errorEvents;
+ *
+ *   // ... success logic
+ * }
+ */
+export declare function handleExecutionError(context: ActionContext, executionError?: Error): ISemanticEvent[] | null;
+/**
+ * Combined helper - handles both validation and execution errors
+ *
+ * This is the recommended helper for most actions. It checks validation
+ * first, then execution errors, returning error events for whichever
+ * failed first (or null if both succeeded).
+ *
+ * @param context The action context
+ * @param validationResult The result from the validate phase
+ * @param executionError Error thrown during execute phase (if any)
+ * @param options Optional configuration for snapshot capture
+ * @returns Array of error events if any error occurred, null otherwise
+ *
+ * @example
+ * report(context, validationResult, executionError) {
+ *   const errorEvents = handleReportErrors(context, validationResult, executionError);
+ *   if (errorEvents) return errorEvents;
+ *
+ *   // All clear - generate success events
+ *   const noun = context.command.directObject!.entity!;
+ *   return [
+ *     context.event('if.event.taken', { item: noun.name }),
+ *     context.event('action.success', { actionId: this.id, messageId: 'taken' })
+ *   ];
+ * }
+ */
+export declare function handleReportErrors(context: ActionContext, validationResult?: ValidationResult, executionError?: Error, options?: ErrorEventOptions): ISemanticEvent[] | null;
+//# sourceMappingURL=report-helpers.d.ts.map

package/dist/actions/base/report-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-helpers.d.ts","sourceRoot":"","sources":["../../../src/actions/base/report-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,EACtB,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,OAAO,GAAE,iBAAsB,GAC9B,cAAc,EAAE,GAAG,IAAI,CAiCzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,EACtB,cAAc,CAAC,EAAE,KAAK,GACrB,cAAc,EAAE,GAAG,IAAI,CAazB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,EACtB,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,cAAc,CAAC,EAAE,KAAK,EACtB,OAAO,GAAE,iBAAsB,GAC9B,cAAc,EAAE,GAAG,IAAI,CAWzB"}

package/dist/actions/base/report-helpers.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Report phase helpers for reducing boilerplate across actions
+ *
+ * These helpers standardize error event generation in the report phase,
+ * ensuring consistent error handling across all stdlib actions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleValidationError = handleValidationError;
+exports.handleExecutionError = handleExecutionError;
+exports.handleReportErrors = handleReportErrors;
+const snapshot_utils_1 = require("./snapshot-utils");
+/**
+ * Handle validation errors in report phase
+ *
+ * Creates standardized error events when validation fails.
+ * Returns null if validation passed (valid === true).
+ *
+ * @param context The action context
+ * @param validationResult The result from the validate phase
+ * @param options Optional configuration for snapshot capture
+ * @returns Array of error events if validation failed, null otherwise
+ *
+ * @example
+ * report(context, validationResult, executionError) {
+ *   const errorEvents = handleValidationError(context, validationResult);
+ *   if (errorEvents) return errorEvents;
+ *
+ *   // ... success logic
+ * }
+ */
+function handleValidationError(context, validationResult, options = {}) {
+    if (!validationResult || validationResult.valid) {
+        return null;
+    }
+    const errorParams = { ...(validationResult.params || {}) };
+    // Optionally capture entity snapshots for richer error context
+    if (options.includeTargetSnapshot !== false && context.command.directObject?.entity) {
+        errorParams.targetSnapshot = (0, snapshot_utils_1.captureEntitySnapshot)(context.command.directObject.entity, context.world, false);
+    }
+    if (options.includeIndirectSnapshot !== false && context.command.indirectObject?.entity) {
+        errorParams.indirectTargetSnapshot = (0, snapshot_utils_1.captureEntitySnapshot)(context.command.indirectObject.entity, context.world, false);
+    }
+    return [
+        context.event('action.error', {
+            actionId: context.action.id,
+            error: validationResult.error || 'validation_failed',
+            reason: validationResult.error || 'validation_failed',
+            messageId: validationResult.messageId || validationResult.error || 'action_failed',
+            params: errorParams
+        })
+    ];
+}
+/**
+ * Handle execution errors in report phase
+ *
+ * Creates standardized error events when execution throws an error.
+ * Returns null if no execution error occurred.
+ *
+ * @param context The action context
+ * @param executionError Error thrown during execute phase (if any)
+ * @returns Array of error events if execution failed, null otherwise
+ *
+ * @example
+ * report(context, validationResult, executionError) {
+ *   const errorEvents = handleExecutionError(context, executionError);
+ *   if (errorEvents) return errorEvents;
+ *
+ *   // ... success logic
+ * }
+ */
+function handleExecutionError(context, executionError) {
+    if (!executionError) {
+        return null;
+    }
+    return [
+        context.event('action.error', {
+            actionId: context.action.id,
+            error: 'execution_failed',
+            messageId: 'action_failed',
+            params: { error: executionError.message }
+        })
+    ];
+}
+/**
+ * Combined helper - handles both validation and execution errors
+ *
+ * This is the recommended helper for most actions. It checks validation
+ * first, then execution errors, returning error events for whichever
+ * failed first (or null if both succeeded).
+ *
+ * @param context The action context
+ * @param validationResult The result from the validate phase
+ * @param executionError Error thrown during execute phase (if any)
+ * @param options Optional configuration for snapshot capture
+ * @returns Array of error events if any error occurred, null otherwise
+ *
+ * @example
+ * report(context, validationResult, executionError) {
+ *   const errorEvents = handleReportErrors(context, validationResult, executionError);
+ *   if (errorEvents) return errorEvents;
+ *
+ *   // All clear - generate success events
+ *   const noun = context.command.directObject!.entity!;
+ *   return [
+ *     context.event('if.event.taken', { item: noun.name }),
+ *     context.event('action.success', { actionId: this.id, messageId: 'taken' })
+ *   ];
+ * }
+ */
+function handleReportErrors(context, validationResult, executionError, options = {}) {
+    // Check validation errors first
+    const validationEvents = handleValidationError(context, validationResult, options);
+    if (validationEvents)
+        return validationEvents;
+    // Then check execution errors
+    const executionEvents = handleExecutionError(context, executionError);
+    if (executionEvents)
+        return executionEvents;
+    // No errors
+    return null;
+}
+//# sourceMappingURL=report-helpers.js.map

package/dist/actions/base/report-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-helpers.js","sourceRoot":"","sources":["../../../src/actions/base/report-helpers.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AA0CH,sDAqCC;AAoBD,oDAgBC;AA4BD,gDAgBC;AA3JD,qDAAyD;AAmBzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,qBAAqB,CACnC,OAAsB,EACtB,gBAAmC,EACnC,UAA6B,EAAE;IAE/B,IAAI,CAAC,gBAAgB,IAAI,gBAAgB,CAAC,KAAK,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,WAAW,GAAG,EAAE,GAAG,CAAC,gBAAgB,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;IAE3D,+DAA+D;IAC/D,IAAI,OAAO,CAAC,qBAAqB,KAAK,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;QACpF,WAAW,CAAC,cAAc,GAAG,IAAA,sCAAqB,EAChD,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,EACnC,OAAO,CAAC,KAAK,EACb,KAAK,CACN,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,uBAAuB,KAAK,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;QACxF,WAAW,CAAC,sBAAsB,GAAG,IAAA,sCAAqB,EACxD,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,EACrC,OAAO,CAAC,KAAK,EACb,KAAK,CACN,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE;YAC5B,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE;YAC3B,KAAK,EAAE,gBAAgB,CAAC,KAAK,IAAI,mBAAmB;YACpD,MAAM,EAAE,gBAAgB,CAAC,KAAK,IAAI,mBAAmB;YACrD,SAAS,EAAE,gBAAgB,CAAC,SAAS,IAAI,gBAAgB,CAAC,KAAK,IAAI,eAAe;YAClF,MAAM,EAAE,WAAW;SACpB,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,oBAAoB,CAClC,OAAsB,EACtB,cAAsB;IAEtB,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE;YAC5B,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE;YAC3B,KAAK,EAAE,kBAAkB;YACzB,SAAS,EAAE,eAAe;YAC1B,MAAM,EAAE,EAAE,KAAK,EAAE,cAAc,CAAC,OAAO,EAAE;SAC1C,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,kBAAkB,CAChC,OAAsB,EACtB,gBAAmC,EACnC,cAAsB,EACtB,UAA6B,EAAE;IAE/B,gCAAgC;IAChC,MAAM,gBAAgB,GAAG,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACnF,IAAI,gBAAgB;QAAE,OAAO,gBAAgB,CAAC;IAE9C,8BAA8B;IAC9B,MAAM,eAAe,GAAG,oBAAoB,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IACtE,IAAI,eAAe;QAAE,OAAO,eAAe,CAAC;IAE5C,YAAY;IACZ,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/actions/base/snapshot-utils.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Snapshot utilities for capturing entity and room state
+ *
+ * These utilities help actions capture complete state snapshots
+ * for atomic events during the report phase.
+ */
+import { IFEntity, WorldModel } from '@sharpee/world-model';
+/**
+ * Entity snapshot containing all relevant state
+ */
+export interface EntitySnapshot {
+    id: string;
+    name: string;
+    description?: string;
+    shortDescription?: string;
+    /** Message ID for localized name (ADR-107) */
+    nameId?: string;
+    /** Message ID for localized description (ADR-107) */
+    descriptionId?: string;
+    location?: string;
+    isOpenable?: boolean;
+    isOpen?: boolean;
+    isLockable?: boolean;
+    isLocked?: boolean;
+    isContainer?: boolean;
+    isSupporter?: boolean;
+    isWearable?: boolean;
+    isWorn?: boolean;
+    isEdible?: boolean;
+    isPushable?: boolean;
+    isScenery?: boolean;
+    isPortable?: boolean;
+    contents?: EntitySnapshot[];
+    traits?: Record<string, unknown>;
+}
+/**
+ * Room snapshot containing complete room state
+ */
+export interface RoomSnapshot {
+    id: string;
+    name: string;
+    description?: string;
+    /** Message ID for localized name (ADR-107) */
+    nameId?: string;
+    /** Message ID for localized description (ADR-107) */
+    descriptionId?: string;
+    isDark?: boolean;
+    isVisited?: boolean;
+    exits?: Record<string, string>;
+    contents?: EntitySnapshot[];
+    traits?: Record<string, unknown>;
+}
+/**
+ * Capture a complete snapshot of an entity's current state
+ *
+ * @param entity The entity to snapshot
+ * @param world The world model (for getting contents)
+ * @param includeContents Whether to include contents recursively
+ * @returns Complete entity snapshot
+ */
+export declare function captureEntitySnapshot(entity: IFEntity, world: WorldModel, includeContents?: boolean): EntitySnapshot;
+/**
+ * Capture a complete snapshot of a room's current state
+ *
+ * @param room The room entity to snapshot
+ * @param world The world model
+ * @param includeContents Whether to include room contents
+ * @returns Complete room snapshot
+ */
+export declare function captureRoomSnapshot(room: IFEntity, world: WorldModel, includeContents?: boolean): RoomSnapshot;
+/**
+ * Capture snapshots of multiple entities
+ *
+ * @param entities Array of entities to snapshot
+ * @param world The world model
+ * @returns Array of entity snapshots
+ */
+export declare function captureEntitySnapshots(entities: IFEntity[], world: WorldModel): EntitySnapshot[];
+/**
+ * Create a minimal entity reference (just id and name)
+ *
+ * @param entity The entity to reference
+ * @returns Minimal entity reference
+ */
+export declare function createEntityReference(entity: IFEntity): {
+    id: string;
+    name: string;
+};
+/**
+ * Create references for multiple entities
+ *
+ * @param entities Array of entities
+ * @returns Array of entity references
+ */
+export declare function createEntityReferences(entities: IFEntity[]): {
+    id: string;
+    name: string;
+}[];
+//# sourceMappingURL=snapshot-utils.d.ts.map

package/dist/actions/base/snapshot-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-utils.d.ts","sourceRoot":"","sources":["../../../src/actions/base/snapshot-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,eAAe,UAAO,GACrB,cAAc,CAkGhB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,UAAU,EACjB,eAAe,UAAO,GACrB,YAAY,CAoEd;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAAE,EACpB,KAAK,EAAE,UAAU,GAChB,cAAc,EAAE,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMpF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAE3F"}

package/dist/actions/base/snapshot-utils.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * Snapshot utilities for capturing entity and room state
+ *
+ * These utilities help actions capture complete state snapshots
+ * for atomic events during the report phase.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureEntitySnapshot = captureEntitySnapshot;
+exports.captureRoomSnapshot = captureRoomSnapshot;
+exports.captureEntitySnapshots = captureEntitySnapshots;
+exports.createEntityReference = createEntityReference;
+exports.createEntityReferences = createEntityReferences;
+/**
+ * Capture a complete snapshot of an entity's current state
+ *
+ * @param entity The entity to snapshot
+ * @param world The world model (for getting contents)
+ * @param includeContents Whether to include contents recursively
+ * @returns Complete entity snapshot
+ */
+function captureEntitySnapshot(entity, world, includeContents = true) {
+    const identity = entity.get?.('identity');
+    const physical = entity.get?.('physical');
+    const openable = entity.get?.('openable');
+    const lockable = entity.get?.('lockable');
+    const container = entity.get?.('container');
+    const supporter = entity.get?.('supporter');
+    const wearable = entity.get?.('wearable');
+    const edible = entity.get?.('edible');
+    const pushable = entity.get?.('pushable');
+    const scenery = entity.get?.('scenery');
+    const snapshot = {
+        id: entity.id,
+        name: identity?.name || entity.id,
+        description: identity?.description,
+        shortDescription: identity?.shortDescription,
+        // Include message IDs if present (ADR-107 dual-mode)
+        nameId: identity?.nameId,
+        descriptionId: identity?.descriptionId,
+        location: world.getLocation(entity.id)
+    };
+    // Add physical properties
+    if (physical) {
+        snapshot.isPortable = physical.portable !== false;
+    }
+    // Add openable properties
+    if (openable !== undefined) {
+        snapshot.isOpenable = true;
+        snapshot.isOpen = openable.isOpen === true;
+    }
+    // Add lockable properties
+    if (lockable !== undefined) {
+        snapshot.isLockable = true;
+        snapshot.isLocked = lockable.isLocked === true;
+    }
+    // Add container properties
+    if (container !== undefined) {
+        snapshot.isContainer = true;
+    }
+    // Add supporter properties
+    if (supporter !== undefined) {
+        snapshot.isSupporter = true;
+    }
+    // Add wearable properties
+    if (wearable !== undefined) {
+        snapshot.isWearable = true;
+        snapshot.isWorn = wearable.isWorn === true;
+    }
+    // Add other trait flags
+    if (edible !== undefined) {
+        snapshot.isEdible = true;
+    }
+    if (pushable !== undefined) {
+        snapshot.isPushable = true;
+    }
+    if (scenery !== undefined) {
+        snapshot.isScenery = true;
+    }
+    // Capture contents if requested
+    if (includeContents && (container || supporter)) {
+        const contents = world.getContents(entity.id);
+        if (contents.length > 0) {
+            snapshot.contents = contents.map(item => captureEntitySnapshot(item, world, false) // Don't recurse deeply
+            );
+        }
+    }
+    // Add any custom traits (excluding standard ones we've already captured)
+    const standardTraits = [
+        'identity', 'physical', 'openable', 'lockable',
+        'container', 'supporter', 'wearable', 'edible',
+        'pushable', 'scenery'
+    ];
+    const customTraits = {};
+    for (const [key, value] of Object.entries(entity)) {
+        if (!standardTraits.includes(key) && key !== 'id' && key !== 'type') {
+            customTraits[key] = value;
+        }
+    }
+    if (Object.keys(customTraits).length > 0) {
+        snapshot.traits = customTraits;
+    }
+    return snapshot;
+}
+/**
+ * Capture a complete snapshot of a room's current state
+ *
+ * @param room The room entity to snapshot
+ * @param world The world model
+ * @param includeContents Whether to include room contents
+ * @returns Complete room snapshot
+ */
+function captureRoomSnapshot(room, world, includeContents = true) {
+    const identity = room.get?.('identity');
+    const roomTrait = room.get?.('room');
+    const darknessTrait = room.get?.('darkness');
+    const snapshot = {
+        id: room.id,
+        name: identity?.name || room.attributes?.name || room.id,
+        description: identity?.description || room.attributes?.description,
+        // Include message IDs if present (ADR-107 dual-mode)
+        nameId: identity?.nameId,
+        descriptionId: identity?.descriptionId
+    };
+    // Add darkness state (can be on dedicated darkness trait OR on room trait)
+    if (darknessTrait !== undefined) {
+        snapshot.isDark = darknessTrait.isDark === true;
+    }
+    else if (roomTrait?.isDark !== undefined) {
+        snapshot.isDark = roomTrait.isDark === true;
+    }
+    // Add visited state
+    if (roomTrait?.visited !== undefined) {
+        snapshot.isVisited = roomTrait.visited === true;
+    }
+    // Capture exits
+    const exits = {};
+    const exitDirs = ['north', 'south', 'east', 'west', 'northeast', 'northwest',
+        'southeast', 'southwest', 'up', 'down', 'in', 'out'];
+    for (const dir of exitDirs) {
+        const exitId = room[dir];
+        if (exitId && typeof exitId === 'string') {
+            exits[dir] = exitId;
+        }
+    }
+    if (Object.keys(exits).length > 0) {
+        snapshot.exits = exits;
+    }
+    // Capture contents if requested
+    if (includeContents) {
+        const contents = world.getContents(room.id);
+        if (contents.length > 0) {
+            snapshot.contents = contents.map(item => captureEntitySnapshot(item, world, true));
+        }
+    }
+    // Add any custom traits
+    const standardTraits = ['identity', 'room', 'darkness'];
+    const customTraits = {};
+    for (const [key, value] of Object.entries(room)) {
+        if (!standardTraits.includes(key) && !exitDirs.includes(key) &&
+            key !== 'id' && key !== 'type') {
+            customTraits[key] = value;
+        }
+    }
+    if (Object.keys(customTraits).length > 0) {
+        snapshot.traits = customTraits;
+    }
+    return snapshot;
+}
+/**
+ * Capture snapshots of multiple entities
+ *
+ * @param entities Array of entities to snapshot
+ * @param world The world model
+ * @returns Array of entity snapshots
+ */
+function captureEntitySnapshots(entities, world) {
+    return entities.map(entity => captureEntitySnapshot(entity, world, true));
+}
+/**
+ * Create a minimal entity reference (just id and name)
+ *
+ * @param entity The entity to reference
+ * @returns Minimal entity reference
+ */
+function createEntityReference(entity) {
+    const identity = entity.get?.('identity');
+    return {
+        id: entity.id,
+        name: identity?.name || entity.id
+    };
+}
+/**
+ * Create references for multiple entities
+ *
+ * @param entities Array of entities
+ * @returns Array of entity references
+ */
+function createEntityReferences(entities) {
+    return entities.map(createEntityReference);
+}
+//# sourceMappingURL=snapshot-utils.js.map