@sharpee/engine 0.9.60-beta

package/dist/types.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Engine-specific types and interfaces
+ *
+ * The engine manages game state, turn execution, and event sequencing
+ */
+import { ISemanticEvent } from '@sharpee/core';
+import { IParsedCommand, IValidatedCommand, IFEntity } from '@sharpee/world-model';
+export { IPerceptionService, Sense } from '@sharpee/stdlib';
+/**
+ * Basic game event (before sequencing)
+ * Note: data is optional to support ISemanticEvent compatibility
+ */
+export interface GameEvent<T = unknown> {
+    type: string;
+    data?: T;
+}
+/**
+ * Sequenced event with turn and ordering information
+ */
+export interface SequencedEvent extends GameEvent {
+    sequence: number;
+    timestamp: Date;
+    turn: number;
+    scope: 'turn' | 'global' | 'system';
+    source?: string;
+}
+/**
+ * Timing data for performance tracking
+ */
+export interface TimingData {
+    parsing?: number;
+    execution?: number;
+    processing?: number;
+    total: number;
+    custom?: Record<string, number>;
+}
+/**
+ * Result of executing a meta-command (VERSION, SCORE, HELP, etc.)
+ *
+ * Meta-commands operate outside the turn cycle - they don't increment turns,
+ * trigger NPCs, or get stored in command history. They emit semantic events
+ * that are processed immediately through the text service.
+ */
+export interface MetaCommandResult {
+    /**
+     * Discriminator for union type
+     */
+    type: 'meta';
+    /**
+     * Raw input string
+     */
+    input: string;
+    /**
+     * Whether the command succeeded
+     */
+    success: boolean;
+    /**
+     * Semantic events emitted by the meta-command
+     * These are processed immediately through text service, not stored in turnEvents
+     */
+    events: ISemanticEvent[];
+    /**
+     * Error message if command failed
+     */
+    error?: string;
+    /**
+     * The action ID that was executed
+     */
+    actionId?: string;
+}
+/**
+ * Result of executing a turn
+ */
+export interface TurnResult {
+    /**
+     * Discriminator for union type (optional for backward compatibility)
+     */
+    type?: 'turn';
+    /**
+     * Turn number
+     */
+    turn: number;
+    /**
+     * Raw input string
+     */
+    input: string;
+    /**
+     * All events generated this turn (in sequence)
+     */
+    events: SequencedEvent[];
+    /**
+     * Whether the turn succeeded
+     */
+    success: boolean;
+    /**
+     * Error message if turn failed
+     */
+    error?: string;
+    /**
+     * Timing information
+     */
+    timing?: TimingData;
+    /**
+     * The action ID that was executed (if any)
+     */
+    actionId?: string;
+    /**
+     * The parsed command (if successfully parsed)
+     */
+    parsedCommand?: IParsedCommand;
+    /**
+     * The validated command with resolved entity IDs (if successfully validated)
+     * Used for pronoun resolution (ADR-089)
+     */
+    validatedCommand?: IValidatedCommand;
+    /**
+     * Whether the turn is waiting for additional input (e.g., disambiguation)
+     * When true, a client.query event was emitted and the engine expects
+     * a follow-up response before continuing.
+     */
+    needsInput?: boolean;
+}
+/**
+ * Union of all command execution results.
+ *
+ * executeTurn() returns this union type - callers should check `type` to determine
+ * whether a turn was executed (TurnResult) or a meta-command was executed (MetaCommandResult).
+ *
+ * @example
+ * ```typescript
+ * const result = await engine.executeTurn(input);
+ * if (result.type === 'meta') {
+ *   // Meta-command: no turn number, text already emitted
+ * } else {
+ *   // Regular turn: has turn number, events to process
+ *   console.log(`Turn ${result.turn}`);
+ * }
+ * ```
+ */
+export type CommandResult = TurnResult | MetaCommandResult;
+/**
+ * Game context for execution
+ */
+export interface GameContext {
+    /**
+     * Current turn number
+     */
+    currentTurn: number;
+    /**
+     * Player entity
+     */
+    player: IFEntity;
+    /**
+     * Turn history
+     */
+    history: TurnResult[];
+    /**
+     * Game metadata
+     */
+    metadata: {
+        title?: string;
+        author?: string;
+        version?: string;
+        started: Date;
+        lastPlayed: Date;
+    };
+    /**
+     * Custom game state
+     */
+    customState?: Record<string, unknown>;
+    /**
+     * Implicit actions configuration (ADR-104)
+     * Populated from StoryConfig.implicitActions
+     */
+    implicitActions?: {
+        inference?: boolean;
+        implicitTake?: boolean;
+    };
+}
+/**
+ * Engine configuration
+ */
+export interface EngineConfig {
+    /**
+     * Maximum turns to keep in history
+     */
+    maxHistory?: number;
+    /**
+     * Whether to validate events before processing
+     */
+    validateEvents?: boolean;
+    /**
+     * Whether to emit timing information
+     */
+    collectTiming?: boolean;
+    /**
+     * Custom error handler
+     */
+    onError?: (error: Error, context: GameContext) => void;
+    /**
+     * Event interceptor for debugging
+     */
+    onEvent?: (event: SequencedEvent) => void;
+    /**
+     * Debug mode - shows more detailed output
+     */
+    debug?: boolean;
+    /**
+     * Maximum undo snapshots to keep (default 10)
+     * Set to 0 to disable undo
+     */
+    maxUndoSnapshots?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Engine-specific types and interfaces
+ *
+ * The engine manages game state, turn execution, and event sequencing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/dist/vocabulary-manager.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Vocabulary Manager - Manages entity vocabulary for parser scope resolution
+ *
+ * Extracted from GameEngine as part of Phase 4 remediation.
+ * Handles registering entity nouns/adjectives with the vocabulary registry
+ * to enable parser noun resolution within the current scope.
+ */
+import { IFEntity, WorldModel } from '@sharpee/world-model';
+/**
+ * Manages vocabulary registration for entities in scope
+ */
+export declare class VocabularyManager {
+    /**
+     * Update vocabulary for a single entity
+     *
+     * @param entity - The entity to register
+     * @param inScope - Whether the entity is currently in scope
+     */
+    updateEntityVocabulary(entity: IFEntity, inScope: boolean): void;
+    /**
+     * Update vocabulary for all entities based on current scope
+     *
+     * Marks all entities as out of scope first, then marks
+     * entities visible to the player as in scope.
+     *
+     * @param world - The world model
+     * @param playerId - The player entity ID
+     */
+    updateScopeVocabulary(world: WorldModel, playerId: string): void;
+}
+/**
+ * Create a vocabulary manager instance
+ */
+export declare function createVocabularyManager(): VocabularyManager;
+//# sourceMappingURL=vocabulary-manager.d.ts.map

package/dist/vocabulary-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary-manager.d.ts","sourceRoot":"","sources":["../src/vocabulary-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAG5D;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;;;;OAKG;IACH,sBAAsB,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IA2BhE;;;;;;;;OAQG;IACH,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;CAgBjE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAE3D"}

package/dist/vocabulary-manager.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Vocabulary Manager - Manages entity vocabulary for parser scope resolution
+ *
+ * Extracted from GameEngine as part of Phase 4 remediation.
+ * Handles registering entity nouns/adjectives with the vocabulary registry
+ * to enable parser noun resolution within the current scope.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VocabularyManager = void 0;
+exports.createVocabularyManager = createVocabularyManager;
+const stdlib_1 = require("@sharpee/stdlib");
+/**
+ * Manages vocabulary registration for entities in scope
+ */
+class VocabularyManager {
+    /**
+     * Update vocabulary for a single entity
+     *
+     * @param entity - The entity to register
+     * @param inScope - Whether the entity is currently in scope
+     */
+    updateEntityVocabulary(entity, inScope) {
+        const identityTrait = entity.get('IDENTITY');
+        if (identityTrait && typeof identityTrait === 'object') {
+            const identity = identityTrait;
+            // Build nouns from name and aliases
+            const nouns = [];
+            if (identity.name) {
+                nouns.push(identity.name.toLowerCase());
+            }
+            if (identity.aliases && Array.isArray(identity.aliases)) {
+                nouns.push(...identity.aliases);
+            }
+            stdlib_1.vocabularyRegistry.registerEntity({
+                entityId: entity.id,
+                nouns: nouns,
+                adjectives: identity.adjectives || [],
+                inScope
+            });
+        }
+    }
+    /**
+     * Update vocabulary for all entities based on current scope
+     *
+     * Marks all entities as out of scope first, then marks
+     * entities visible to the player as in scope.
+     *
+     * @param world - The world model
+     * @param playerId - The player entity ID
+     */
+    updateScopeVocabulary(world, playerId) {
+        const player = world.getEntity(playerId);
+        if (!player)
+            return;
+        const inScope = world.getInScope(playerId);
+        // Mark all entities as out of scope first
+        for (const entity of world.getAllEntities()) {
+            this.updateEntityVocabulary(entity, false);
+        }
+        // Mark in-scope entities
+        for (const entity of inScope) {
+            this.updateEntityVocabulary(entity, true);
+        }
+    }
+}
+exports.VocabularyManager = VocabularyManager;
+/**
+ * Create a vocabulary manager instance
+ */
+function createVocabularyManager() {
+    return new VocabularyManager();
+}
+//# sourceMappingURL=vocabulary-manager.js.map

package/dist/vocabulary-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary-manager.js","sourceRoot":"","sources":["../src/vocabulary-manager.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAwEH,0DAEC;AAvED,4CAAqD;AAErD;;GAEG;AACH,MAAa,iBAAiB;IAC5B;;;;;OAKG;IACH,sBAAsB,CAAC,MAAgB,EAAE,OAAgB;QACvD,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,aAAa,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;YACvD,MAAM,QAAQ,GAAG,aAIhB,CAAC;YAEF,oCAAoC;YACpC,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;gBAClB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;YAC1C,CAAC;YACD,IAAI,QAAQ,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxD,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;YAClC,CAAC;YAED,2BAAkB,CAAC,cAAc,CAAC;gBAChC,QAAQ,EAAE,MAAM,CAAC,EAAE;gBACnB,KAAK,EAAE,KAAK;gBACZ,UAAU,EAAE,QAAQ,CAAC,UAAU,IAAI,EAAE;gBACrC,OAAO;aACR,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,qBAAqB,CAAC,KAAiB,EAAE,QAAgB;QACvD,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,CAAC,MAAM;YAAE,OAAO;QAEpB,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAE3C,0CAA0C;QAC1C,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;YAC5C,IAAI,CAAC,sBAAsB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC;QAED,yBAAyB;QACzB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,sBAAsB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;CACF;AA3DD,8CA2DC;AAED;;GAEG;AACH,SAAgB,uBAAuB;IACrC,OAAO,IAAI,iBAAiB,EAAE,CAAC;AACjC,CAAC"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@sharpee/engine",
+  "version": "0.9.60-beta",
+  "description": "Runtime engine for Sharpee IF Platform - game loop, command execution, and turn management",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@sharpee/core": "0.9.60-beta",
+    "@sharpee/event-processor": "0.9.60-beta",
+    "@sharpee/if-domain": "0.9.60-beta",
+    "@sharpee/if-services": "0.9.60-beta",
+    "@sharpee/parser-en-us": "0.9.60-beta",
+    "@sharpee/lang-en-us": "0.9.60-beta",
+    "@sharpee/stdlib": "0.9.60-beta",
+    "@sharpee/text-blocks": "0.9.60-beta",
+    "@sharpee/text-service": "0.9.60-beta",
+    "@sharpee/world-model": "0.9.60-beta"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.19",
+    "cross-env": "^7.0.3",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "interactive-fiction",
+    "if",
+    "text-adventure",
+    "sharpee",
+    "engine",
+    "game-engine"
+  ],
+  "author": "Sharpee Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChicagoDave/sharpee.git",
+    "directory": "packages/engine"
+  },
+  "homepage": "https://github.com/ChicagoDave/sharpee#readme",
+  "bugs": {
+    "url": "https://github.com/ChicagoDave/sharpee/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:ci": "vitest run",
+    "test:verbose": "vitest run --reporter=verbose",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rimraf dist"
+  }
+}