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:

$
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.

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

or

$
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.

$
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:

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

Scenario Command Map

The harness currently validates the following narrative arcs:

Technical Verification

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

$
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.