> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.forboc.ai/npm/test-game/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.forboc.ai/_mcp/server.

# Test Game

# Echoes of the Spire (`@forbocai/test-game`)

> **\[VOID::WATCHER]** Every step is a ritual of verify-or-fail. The signal is buried in the noise.

`@forbocai/test-game`, also known as **Echoes of the Spire**, is a cyberpunk-noir terminal micro-game designed as a high-fidelity test harness for the ForbocAI SDK and CLI.

It doesn't just "test code"—it executes narrative-driven scenarios that map directly to the **Command Line Interface (CLI)** coverage matrix. If the CLI cannot handle an NPC's lifecycle, memory, or soul, the game (and the build) fails.

## Core Philosophy: Fail-Closed Doctrine

The harness operates under a **Fail-Closed Doctrine**. In the grimdark reality of the Spire, there are no "soft fails."

1. **Connectivity Mandatory**: Every BDD test begins with a readiness check (`requireCliReadiness`). If `http://localhost:8080/status` is unreachable, the tests abort.
2. **Transcript Integrity**: Every shell command executed is recorded in a "chrome rain ledger" (transcript). Any command that returns a non-zero exit code or malformed JSON output marks the entire scenario as compromised.
3. **Audit Sigil ᚲ**: The harness tracks 17 core command groups (NPC lifecycle, Bridge rules, Soul export/import, etc.). A run is only considered "Complete" if all groups are exercised.

## Architecture: Functional Redux

Echoes of the Spire follows a strict **Functional Paradigm**, aligned with Redux Toolkit (RTK) best practices:

* **No Classes**: All logic is modeled as pure functions, slices, and action dispatchers.
* **State-Driven Narrative**: The game world (grid, NPCs, player, dialogue) lives in a centralized Redux store.
* **Scenario Orchestration**: The `runGame` orchestrator composes slice actions and pure helpers, keeping the temporal logic of the game deterministic and testable.

## How It Works

The game engine iterates through a series of **Scenario Steps** defined in the `scenarioSlice`. Each step consists of:

* **Narrative Context**: A description of what is happening in the Spire (e.g., "The armory door is left open").
* **State Mutation**: Direct updates to the local game store (opening doors, bumping alarm levels).
* **CLI Command Vector**: A list of `forbocai` CLI commands that *should* be run to mirror the game state in the remote API.

### Command Execution Adapter

The `commandRunner` acts as the bridge between the game and your shell. When running with `--execute shell`, it uses `node:child_process` to fire real commands against the installed `forbocai` binary.

## Running the Harness

From the monorepo root, you can engage the harness in several modes.

### 1. Build the Artifact

First, build the local bundle:

```bash
npm run build --workspace @forbocai/test-game
```

### 2. Autoplay Mode (The Auditor)

This is the default mode. It runs through the scenario traces automatically, auditing the CLI's performance.

```bash
node packages/test-game/dist/cli.js --mode autoplay
```

or

```bash
npx tsx packages/test-game/src/cli.ts --mode autoplay
```

### 3. Manual Mode (The Operator)

Manual mode allows you to step through each narrative beat. The harness will pause at every scenario step, rendering the ASCII grid and requiring operator input to proceed.

```bash
node packages/test-game/dist/cli.js --mode manual
```

### 4. Direct Shell Execution

By default, the game simulates command success for internal logic testing. To test the **real** CLI and API, add the shell execution flag:

```bash
node packages/test-game/dist/cli.js --mode autoplay --execute shell
```

## Scenario Command Map

The harness currently validates the following narrative arcs:

| Arc                  | Narrative Focus         | Key Command Groups                           |
| :------------------- | :---------------------- | :------------------------------------------- |
| **Spatial Stealth**  | Armory perimeter breach | `status`, `npc_lifecycle`, `memory_store`    |
| **Social Encounter** | Interrogating Miller    | `social`, `memory_recall`, `bridge_preset`   |
| **The Escape**       | Real-time pursuit       | `bridge_validate`, `ghost_lifecycle`         |
| **Persistence**      | Soul recovery           | `soul_export`, `soul_import`, `memory_clear` |

## Technical Verification

To run the BDD tests and verify the harness logic itself:

```bash
cd packages/test-game
npm run test
```

*Note: These tests require a running API instance on port 8080 to satisfy the Fail-Closed readiness check.*

> Echoes of the Spire CLI coverage harness