@sharpee/ext-testing 0.9.61-beta

package/src/annotations/context.ts

@@ -0,0 +1,47 @@
+/**
+ * Annotation Context Capture
+ *
+ * Utility to capture current game state for annotations.
+ */
+
+import type { WorldModel } from '@sharpee/world-model';
+import type { AnnotationContext } from '../types.js';
+
+/**
+ * Capture the current game state for annotation context
+ */
+export function captureContext(
+  world: WorldModel,
+  lastCommand: string,
+  lastResponse: string
+): AnnotationContext {
+  const player = world.getPlayer();
+  const locationId = player ? world.getLocation(player.id) : undefined;
+  const location = locationId ? world.getEntity(locationId) : undefined;
+  const inventory = player ? world.getContents(player.id) : [];
+
+  return {
+    roomId: locationId ?? 'unknown',
+    roomName: location?.name ?? locationId ?? 'unknown',
+    turn: (world.getStateValue('turnCount') as number) ?? (world.getStateValue('moves') as number) ?? 0,
+    score: (world.getStateValue('score') as number) ?? 0,
+    lastCommand,
+    lastResponse,
+    inventory: inventory.map((e) => e.name ?? e.id),
+  };
+}
+
+/**
+ * Create an empty/default context (for when no command has been executed yet)
+ */
+export function createEmptyContext(): AnnotationContext {
+  return {
+    roomId: 'unknown',
+    roomName: 'unknown',
+    turn: 0,
+    score: 0,
+    lastCommand: '',
+    lastResponse: '',
+    inventory: [],
+  };
+}

package/src/annotations/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Annotations module - Playtester feedback capture (ADR-109)
+ */
+
+export { createAnnotationStore } from './store.js';
+export { captureContext, createEmptyContext } from './context.js';

package/src/annotations/store.ts

@@ -0,0 +1,219 @@
+/**
+ * Annotation Store Implementation
+ *
+ * In-memory storage for playtester annotations with session management.
+ */
+
+import type { AnnotationType, Annotation, AnnotationContext, AnnotationSession, AnnotationStore } from '../types.js';
+
+/**
+ * Generate a unique ID
+ */
+function generateId(): string {
+  return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Create an in-memory annotation store
+ */
+export function createAnnotationStore(): AnnotationStore {
+  let currentSession: AnnotationSession | undefined;
+  let allAnnotations: Annotation[] = [];
+
+  return {
+    // Session management
+    startSession(name: string): string {
+      // End any existing session first
+      if (currentSession) {
+        currentSession.endTime = Date.now();
+      }
+
+      const id = generateId();
+      currentSession = {
+        id,
+        name,
+        startTime: Date.now(),
+        annotations: [],
+      };
+
+      return id;
+    },
+
+    endSession(): AnnotationSession | undefined {
+      if (!currentSession) {
+        return undefined;
+      }
+
+      currentSession.endTime = Date.now();
+      const ended = currentSession;
+      currentSession = undefined;
+      return ended;
+    },
+
+    getCurrentSession(): AnnotationSession | undefined {
+      return currentSession;
+    },
+
+    // Annotation capture
+    addAnnotation(type: AnnotationType, text: string, context: AnnotationContext): Annotation {
+      const annotation: Annotation = {
+        id: generateId(),
+        timestamp: Date.now(),
+        type,
+        text,
+        context,
+        sessionId: currentSession?.id,
+      };
+
+      allAnnotations.push(annotation);
+
+      if (currentSession) {
+        currentSession.annotations.push(annotation);
+      }
+
+      return annotation;
+    },
+
+    getAnnotations(): Annotation[] {
+      if (currentSession) {
+        return [...currentSession.annotations];
+      }
+      return [...allAnnotations];
+    },
+
+    getAnnotationsByType(type: AnnotationType): Annotation[] {
+      const source = currentSession ? currentSession.annotations : allAnnotations;
+      return source.filter((a) => a.type === type);
+    },
+
+    // Export
+    exportMarkdown(): string {
+      return formatMarkdownReport(currentSession, allAnnotations);
+    },
+
+    exportJson(): string {
+      const data = currentSession
+        ? { session: currentSession }
+        : { annotations: allAnnotations };
+      return JSON.stringify(data, null, 2);
+    },
+
+    // Cleanup
+    clear(): void {
+      currentSession = undefined;
+      allAnnotations = [];
+    },
+  };
+}
+
+/**
+ * Format annotations as a markdown report (per ADR-109)
+ */
+function formatMarkdownReport(
+  session: AnnotationSession | undefined,
+  allAnnotations: Annotation[]
+): string {
+  const annotations = session ? session.annotations : allAnnotations;
+  const lines: string[] = [];
+
+  // Header
+  if (session) {
+    lines.push(`# Play Test Session: ${session.name}`);
+    lines.push(`Date: ${new Date(session.startTime).toLocaleString()}`);
+    if (session.endTime) {
+      const durationMs = session.endTime - session.startTime;
+      const durationMins = Math.round(durationMs / 60000);
+      lines.push(`Duration: ${durationMins} minutes`);
+    }
+  } else {
+    lines.push('# Playtest Annotations');
+    lines.push(`Generated: ${new Date().toLocaleString()}`);
+  }
+  lines.push('');
+
+  // Group by type
+  const bugs = annotations.filter((a) => a.type === 'bug');
+  const notes = annotations.filter((a) => a.type === 'note');
+  const confusing = annotations.filter((a) => a.type === 'confusing');
+  const expected = annotations.filter((a) => a.type === 'expected');
+  const bookmarks = annotations.filter((a) => a.type === 'bookmark');
+  const comments = annotations.filter((a) => a.type === 'comment');
+
+  // Bugs section
+  if (bugs.length > 0) {
+    lines.push(`## Bugs (${bugs.length})`);
+    bugs.forEach((bug, i) => {
+      lines.push(`${i + 1}. [Turn ${bug.context.turn}, ${bug.context.roomName}] "${bug.text}"`);
+      lines.push(`   - Command: ${bug.context.lastCommand}`);
+      lines.push(`   - Response: ${truncate(bug.context.lastResponse, 100)}`);
+      lines.push('');
+    });
+  }
+
+  // Notes section
+  if (notes.length > 0) {
+    lines.push(`## Notes (${notes.length})`);
+    notes.forEach((note, i) => {
+      lines.push(`${i + 1}. [Turn ${note.context.turn}, ${note.context.roomName}] "${note.text}"`);
+    });
+    lines.push('');
+  }
+
+  // Confusion points
+  if (confusing.length > 0) {
+    lines.push(`## Confusion Points (${confusing.length})`);
+    confusing.forEach((c, i) => {
+      lines.push(`${i + 1}. [Turn ${c.context.turn}, ${c.context.roomName}]`);
+      lines.push(`   - After: ${c.context.lastCommand}`);
+      lines.push(`   - Response: ${truncate(c.context.lastResponse, 100)}`);
+      lines.push('');
+    });
+  }
+
+  // Expected behavior
+  if (expected.length > 0) {
+    lines.push(`## Expected Behavior (${expected.length})`);
+    expected.forEach((e, i) => {
+      lines.push(`${i + 1}. [Turn ${e.context.turn}, ${e.context.roomName}]`);
+      lines.push(`   - Expected: ${e.text}`);
+      lines.push(`   - Actual: ${truncate(e.context.lastResponse, 100)}`);
+      lines.push('');
+    });
+  }
+
+  // Bookmarks
+  if (bookmarks.length > 0) {
+    lines.push(`## Bookmarks (${bookmarks.length})`);
+    bookmarks.forEach((b, i) => {
+      lines.push(`${i + 1}. "${b.text}" at Turn ${b.context.turn}, ${b.context.roomName}`);
+    });
+    lines.push('');
+  }
+
+  // Comments (silent feedback)
+  if (comments.length > 0) {
+    lines.push(`## Comments (${comments.length})`);
+    comments.forEach((c, i) => {
+      lines.push(`${i + 1}. [Turn ${c.context.turn}, ${c.context.roomName}] "${c.text}"`);
+    });
+    lines.push('');
+  }
+
+  // Summary stats
+  lines.push('## Summary');
+  lines.push(`- Total annotations: ${annotations.length}`);
+  lines.push(`- Bugs: ${bugs.length}`);
+  lines.push(`- Notes: ${notes.length}`);
+  lines.push(`- Confusion points: ${confusing.length}`);
+  lines.push(`- Bookmarks: ${bookmarks.length}`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Truncate a string to max length
+ */
+function truncate(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  return str.substring(0, maxLen - 3) + '...';
+}

package/src/checkpoints/index.ts

@@ -0,0 +1,2 @@
+export { serializeCheckpoint, deserializeCheckpoint, validateCheckpoint } from './serializer.js';
+export { createFileStore, createMemoryStore, createLocalStorageStore } from './store.js';

package/src/checkpoints/serializer.ts

@@ -0,0 +1,121 @@
+/**
+ * Checkpoint Serializer
+ *
+ * Handles serialization and deserialization of game state for checkpoints.
+ * Captures world model state and scheduler state (daemons, fuses).
+ */
+
+import type { WorldModel } from '@sharpee/world-model';
+import type { CheckpointData, SerializedDaemon, SerializedFuse } from '../types.js';
+
+/**
+ * Serialize current game state to checkpoint data
+ */
+export function serializeCheckpoint(
+  world: WorldModel,
+  name?: string
+): CheckpointData {
+  const player = world.getPlayer();
+  const playerLocation = player ? world.getLocation(player.id) : undefined;
+
+  // Get world state via WorldModel.toJSON()
+  const worldState = world.toJSON();
+
+  // TODO: Get scheduler state when scheduler API is available
+  // For now, scheduler state is omitted
+  const schedulerState = undefined;
+
+  const checkpoint: CheckpointData = {
+    version: '1.0.0',
+    timestamp: Date.now(),
+    metadata: {
+      name,
+      turn: getTurnNumber(world),
+      location: playerLocation,
+    },
+    worldState,
+    schedulerState,
+  };
+
+  return checkpoint;
+}
+
+/**
+ * Deserialize checkpoint data and restore game state
+ */
+export function deserializeCheckpoint(
+  checkpoint: CheckpointData,
+  world: WorldModel
+): void {
+  // Validate version
+  if (checkpoint.version !== '1.0.0') {
+    throw new Error(`Unsupported checkpoint version: ${checkpoint.version}`);
+  }
+
+  // Restore world state via WorldModel.loadJSON()
+  world.loadJSON(checkpoint.worldState);
+
+  // TODO: Restore scheduler state when scheduler API is available
+  if (checkpoint.schedulerState) {
+    restoreSchedulerState(world, checkpoint.schedulerState);
+  }
+}
+
+/**
+ * Get current turn number from world
+ */
+function getTurnNumber(world: WorldModel): number {
+  // Try to get turn from world metadata or state
+  // This may need adjustment based on actual WorldModel API
+  try {
+    const state = JSON.parse(world.toJSON());
+    return state.turn ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Restore scheduler state (daemons and fuses)
+ */
+function restoreSchedulerState(
+  world: WorldModel,
+  state: {
+    turn: number;
+    daemons: SerializedDaemon[];
+    fuses: SerializedFuse[];
+  }
+): void {
+  // TODO: Implement when scheduler serialization API is available
+  // This will need access to the engine's scheduler service
+  console.warn('Scheduler state restoration not yet implemented');
+}
+
+/**
+ * Validate checkpoint data structure
+ */
+export function validateCheckpoint(data: unknown): data is CheckpointData {
+  if (!data || typeof data !== 'object') {
+    return false;
+  }
+
+  const checkpoint = data as Partial<CheckpointData>;
+
+  if (checkpoint.version !== '1.0.0') {
+    return false;
+  }
+
+  if (typeof checkpoint.timestamp !== 'number') {
+    return false;
+  }
+
+  if (!checkpoint.metadata || typeof checkpoint.metadata !== 'object') {
+    return false;
+  }
+
+  if (typeof checkpoint.worldState !== 'string') {
+    return false;
+  }
+
+  return true;
+}

package/src/checkpoints/store.ts

@@ -0,0 +1,188 @@
+/**
+ * Checkpoint Store
+ *
+ * File-based storage for checkpoints.
+ * Supports both Node.js (filesystem) and browser (localStorage) environments.
+ */
+
+import type { CheckpointData, CheckpointStore } from '../types.js';
+import { validateCheckpoint } from './serializer.js';
+
+/**
+ * Create a file-based checkpoint store (Node.js)
+ */
+export function createFileStore(directory: string): CheckpointStore {
+  // Dynamic import for Node.js fs module
+  let fs: typeof import('fs') | undefined;
+  let path: typeof import('path') | undefined;
+
+  const ensureFs = async () => {
+    if (!fs) {
+      fs = await import('fs');
+      path = await import('path');
+    }
+    return { fs, path: path! };
+  };
+
+  const getFilePath = (pathModule: typeof import('path'), name: string): string => {
+    return pathModule.join(directory, `${name}.json`);
+  };
+
+  const store: CheckpointStore = {
+    async save(name: string, data: CheckpointData): Promise<void> {
+      const { fs, path } = await ensureFs();
+
+      // Ensure directory exists
+      if (!fs.existsSync(directory)) {
+        fs.mkdirSync(directory, { recursive: true });
+      }
+
+      const filePath = getFilePath(path, name);
+      const json = JSON.stringify(data, null, 2);
+      fs.writeFileSync(filePath, json, 'utf-8');
+    },
+
+    async load(name: string): Promise<CheckpointData | undefined> {
+      const { fs, path } = await ensureFs();
+
+      const filePath = getFilePath(path, name);
+
+      if (!fs.existsSync(filePath)) {
+        return undefined;
+      }
+
+      try {
+        const json = fs.readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(json);
+
+        if (!validateCheckpoint(data)) {
+          console.warn(`Invalid checkpoint data in ${filePath}`);
+          return undefined;
+        }
+
+        return data;
+      } catch (error) {
+        console.error(`Failed to load checkpoint ${name}:`, error);
+        return undefined;
+      }
+    },
+
+    async list(): Promise<string[]> {
+      const { fs } = await ensureFs();
+
+      if (!fs.existsSync(directory)) {
+        return [];
+      }
+
+      const files = fs.readdirSync(directory);
+      return files
+        .filter((f) => f.endsWith('.json'))
+        .map((f) => f.replace(/\.json$/, ''));
+    },
+
+    async delete(name: string): Promise<boolean> {
+      const { fs, path } = await ensureFs();
+
+      const filePath = getFilePath(path, name);
+
+      if (!fs.existsSync(filePath)) {
+        return false;
+      }
+
+      fs.unlinkSync(filePath);
+      return true;
+    },
+
+    async exists(name: string): Promise<boolean> {
+      const { fs, path } = await ensureFs();
+
+      const filePath = getFilePath(path, name);
+      return fs.existsSync(filePath);
+    },
+  };
+
+  return store;
+}
+
+/**
+ * Create a memory-based checkpoint store (for testing or browser)
+ */
+export function createMemoryStore(): CheckpointStore {
+  const checkpoints = new Map<string, CheckpointData>();
+
+  return {
+    async save(name: string, data: CheckpointData): Promise<void> {
+      checkpoints.set(name, data);
+    },
+
+    async load(name: string): Promise<CheckpointData | undefined> {
+      return checkpoints.get(name);
+    },
+
+    async list(): Promise<string[]> {
+      return Array.from(checkpoints.keys());
+    },
+
+    async delete(name: string): Promise<boolean> {
+      return checkpoints.delete(name);
+    },
+
+    async exists(name: string): Promise<boolean> {
+      return checkpoints.has(name);
+    },
+  };
+}
+
+/**
+ * Create a localStorage-based checkpoint store (browser)
+ */
+export function createLocalStorageStore(prefix: string = 'sharpee-checkpoint-'): CheckpointStore {
+  const getKey = (name: string) => `${prefix}${name}`;
+
+  return {
+    async save(name: string, data: CheckpointData): Promise<void> {
+      const json = JSON.stringify(data);
+      localStorage.setItem(getKey(name), json);
+    },
+
+    async load(name: string): Promise<CheckpointData | undefined> {
+      const json = localStorage.getItem(getKey(name));
+      if (!json) return undefined;
+
+      try {
+        const data = JSON.parse(json);
+        if (!validateCheckpoint(data)) {
+          console.warn(`Invalid checkpoint data for ${name}`);
+          return undefined;
+        }
+        return data;
+      } catch {
+        return undefined;
+      }
+    },
+
+    async list(): Promise<string[]> {
+      const names: string[] = [];
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i);
+        if (key?.startsWith(prefix)) {
+          names.push(key.slice(prefix.length));
+        }
+      }
+      return names;
+    },
+
+    async delete(name: string): Promise<boolean> {
+      const key = getKey(name);
+      if (localStorage.getItem(key) === null) {
+        return false;
+      }
+      localStorage.removeItem(key);
+      return true;
+    },
+
+    async exists(name: string): Promise<boolean> {
+      return localStorage.getItem(getKey(name)) !== null;
+    },
+  };
+}

package/src/commands/index.ts

@@ -0,0 +1 @@
+export { createCommandRegistry, parseGdtInput, parseTestInput } from './registry.js';

package/src/commands/registry.ts

@@ -0,0 +1,81 @@
+/**
+ * Command Registry
+ *
+ * Central registry for debug and test commands.
+ * Commands can be looked up by GDT code or test syntax.
+ */
+
+import type { DebugCommand, CommandCategory, CommandRegistry } from '../types.js';
+
+/**
+ * Create a new command registry
+ */
+export function createCommandRegistry(): CommandRegistry {
+  const byCode = new Map<string, DebugCommand>();
+  const byTestSyntax = new Map<string, DebugCommand>();
+  const allCommands: DebugCommand[] = [];
+
+  const registry: CommandRegistry = {
+    register(command: DebugCommand): void {
+      // Register by code (uppercase for case-insensitive lookup)
+      byCode.set(command.code.toUpperCase(), command);
+
+      // Register by test syntax if provided
+      if (command.testSyntax) {
+        byTestSyntax.set(command.testSyntax.toLowerCase(), command);
+      }
+
+      allCommands.push(command);
+    },
+
+    getByCode(code: string): DebugCommand | undefined {
+      return byCode.get(code.toUpperCase());
+    },
+
+    getByTestSyntax(syntax: string): DebugCommand | undefined {
+      return byTestSyntax.get(syntax.toLowerCase());
+    },
+
+    getAll(): DebugCommand[] {
+      return [...allCommands];
+    },
+
+    getByCategory(category: CommandCategory): DebugCommand[] {
+      return allCommands.filter((cmd) => cmd.category === category);
+    },
+  };
+
+  return registry;
+}
+
+/**
+ * Parse a GDT-style command input
+ * Format: "CODE arg1 arg2" or just "CODE"
+ */
+export function parseGdtInput(input: string): { code: string; args: string[] } {
+  const trimmed = input.trim();
+  const parts = trimmed.split(/\s+/);
+  const code = parts[0] || '';
+  const args = parts.slice(1);
+
+  return { code: code.toUpperCase(), args };
+}
+
+/**
+ * Parse a test command input
+ * Format: "$command arg1 arg2" or just "$command"
+ */
+export function parseTestInput(input: string): { syntax: string; args: string[] } | undefined {
+  const trimmed = input.trim();
+
+  if (!trimmed.startsWith('$')) {
+    return undefined;
+  }
+
+  const withoutPrefix = trimmed.slice(1);
+  const parts = withoutPrefix.split(/\s+/);
+  const syntax = parts[0] || '';
+  const args = parts.slice(1);
+
+  return { syntax: syntax.toLowerCase(), args };
+}