@forgeax/dsh-game

Readme

# `@forgeax/dsh-game`

[![npm](https://img.shields.io/npm/v/@forgeax/dsh-game?label=npm)](https://www.npmjs.com/package/@forgeax/dsh-game)
[![ci](https://github.com/ForgeaX-Games/forgeax-dsh-game-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/ForgeaX-Games/forgeax-dsh-game-plugin/actions/workflows/ci.yml)
[![DSH bundle](https://img.shields.io/badge/dsh-bundle-0b7285)](https://github.com/deepseek-ai/deepseek-harness)
[![platform](https://img.shields.io/badge/platform-macOS%20arm64%20%7C%20Linux%20x64%20%7C%20Windows%20x64-lightgrey)](https://www.npmjs.com/package/@forgeax/game-runtime)

ForgeaX game development inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
This is a **DSH bundle**: installing it into a profile adds one patch layer that wires the
already-published [`@forgeax/game`](https://www.npmjs.com/package/@forgeax/game) MCP server,
its bundled ForgeaX Skills, and a workspace guard into your DSH session.

It contains no game logic and no copy of ForgeaX. It resolves the `@forgeax/game`
package that pnpm installed next to it, verifies its identity, and connects it.

## What you get

| Surface | Effect |
|---|---|
| **Tools** | `mcp__forgeax__forgeax_status_lite`, `mcp__forgeax__forgeax_run_current_game` |
| **Skills** | `forgeax-game` plus every `forgeax-engine-*` Skill shipped in the resolved package, registered on `ctx.skills` at boot |
| **Guard** | Every `mcp__forgeax__*` call whose `target_dir` is not the current session cwd is denied. A call that carries no session cwd to compare against (Code Mode, nested dispatch) is allowed after an existence check, and the model is told it was not fully checked |

You do **not** run `forgeax-game devkit install`. This bundle registers the Skills
directly; running the installer as well only leaves duplicate copies in your repo
that DSH never reads.

## Requirements

- **macOS arm64, Linux x64, or Windows x64.** This bundle is pure JS and declares no
  `os`/`cpu`; it inherits its platform reach from `@forgeax/game`, whose
  `@forgeax/game-runtime` ships a native binary as one `optionalDependencies` entry per
  platform. Your machine installs only the matching one. Platforms with no published
  variant (Intel Mac, ARM Linux, ARM Windows) install cleanly but fail when the runtime
  starts, exactly as `@forgeax/game` does on its own.
- **`pnpm` on `PATH`.** `dsh plugin` is a thin pnpm forwarder; without pnpm it exits `127`.
- **Node ≥ 22**, matching DSH.

## Install

`dsh plugin` installs into one named profile and self-activates: because this package
declares `dsh.bundle`, adding it as a dependency also appends it to that profile's
`dsh.profile.bundles` layer stack.

```bash
dsh plugin --profile web add @forgeax/dsh-game
```

`--profile` is mandatory — DSH has no implicit default profile, and the layer stack is
per profile. Repeat the command for every profile that should have ForgeaX.

**Then restart `dsh`.** Bundle layers are read once at boot; only the profile's own user
patch file is watched. A freshly added bundle is inert until the next launch.

Verify after restarting:

```bash
dsh --profile web
# then, in the session:
#   ask for the ForgeaX status — the model should call mcp__forgeax__forgeax_status_lite
```

## Configuration

The four rows this bundle inserts, all namespaced so they can never collide with
another bundle:

| Row id | Module | Purpose |
|---|---|---|
| `forgeax-game.launch-spec` | `@forgeax/dsh-game/launch-spec` | Resolves + verifies `@forgeax/game`, publishes the `forgeaxGameLaunch` service |
| `forgeax-game.mcp-client` | `@deepseek-ai/dsh-mcp-client` | stdio bridge, `serverName: forgeax` |
| `forgeax-game.skill-source` | `@forgeax/dsh-game/skill-source` | Registers the package's Skills |
| `forgeax-game.workspace-guard` | `@forgeax/dsh-game/workspace-guard` | Tool policy: denies on `tools/pre-execute`, reports an unverifiable call on `tools/post-execute` |

The resolver itself lives in a fifth module, `@forgeax/dsh-game/forgeax-package`, which
imports no framework. Provenance tooling can load it from an installed profile, where the
DSH packages are peers the profile never installs a second copy of.

To change something, add a row with the **same id** to your profile's user patch file.
A patch **replaces the whole `config`** of the targeted row — there is no deep merge — so
you must restate every field you want to keep. For example, to shorten the tool-call
timeout:

```yaml
# $DSH_HOME/profiles/web/cordis.patch.yml
- insert:
    - id: forgeax-game.mcp-client
      name: '@deepseek-ai/dsh-mcp-client'
      inject:
        - forgeaxGameLaunch
      config:
        serverName: forgeax
        transport: stdio
        command: !!js ctx.forgeaxGameLaunch.spec.command
        args: !!js ctx.forgeaxGameLaunch.spec.args
        cwd: !!js ctx.forgeaxGameLaunch.spec.cwd
        env: !!js ctx.forgeaxGameLaunch.spec.env
        failOnStartupError: true
        toolCallTimeoutMs: 120000
        reconnect:
          enabled: true
```

## Limits worth knowing

- **Tools only.** DSH's MCP client bridges tools, not resources. `forgeax://status` is
  unreachable in a DSH session; `mcp__forgeax__forgeax_status_lite` returns the same
  state. The registered Skill says so, so the model does not try the resource.
- **No transitive bundles.** Only packages listed directly in `dsh.profile.bundles`
  contribute a patch layer. A bundle that depends on this one does not inherit its rows.
- **One-time ForgeaX operations stay on the CLI.** Creating a game, switching the active
  game, and upgrading the plugin are `forgeax-game <init|use|doctor|devkit|upgrade>`
  subcommands, not MCP tools.

## Failure modes

| Symptom | Cause |
|---|---|
| `dsh plugin` exits `127` | pnpm not on `PATH` |
| Runtime fails to start after a clean install | no `@forgeax/game-runtime` variant for this platform (Intel Mac, ARM Linux, ARM Windows) — none is published yet |
| pnpm refuses a git-hosted spec's `prepare` | allowlist it under `allowBuilds` in `<profileDir>/pnpm-workspace.yaml` (pnpm ≥ 10) |
| ForgeaX tools absent after install | `dsh` not restarted |
| Boot fails with a launch-spec error | the resolved `@forgeax/game` does not match the pinned version or is missing bundled Skill assets — reinstall rather than patching around it |

`failOnStartupError` is `true` on purpose: a ForgeaX session whose MCP server never
started is broken, not degraded, and a boot-time error is cheaper to read than a
mystery at the first tool call.

## Security

- The child process is launched with `env: {}`. DSH scrubs the parent environment and
  merges `config.env` **after** the scrub, so anything listed there would re-inject a
  secret the harness just removed.
- The workspace guard compares `target_dir` against the session cwd after `realpath`
  resolution — never by string prefix, which symlinks and `..` defeat.
- No API key, token, or secret value is read, stored, or logged by this bundle.

## Changelog

Every user-visible change is recorded in [`CHANGELOG.md`](./CHANGELOG.md). To contribute,
see [`CONTRIBUTING.md`](./CONTRIBUTING.md); to report a vulnerability, see
[`SECURITY.md`](./SECURITY.md).

## License

MIT