dsh-godot-preview

Readme

# dsh-godot-preview

An independently installable Godot 4 preview plugin for DeepSeek Harness Desktop. It adds a **Godot Preview** view to the existing conversation details area without modifying Harness core.

## What it does

- Uses the active Harness session workspace as the Godot project root.
- Validates `project.godot` and an existing Godot 4 executable.
- Runs a Web Debug export and embeds the loopback preview in Harness.
- Can launch and stop the native Godot project instead.
- Watches project files with configurable debounce and single-flight rebuilds.
- Coalesces changes during a build into at most one queued rebuild.
- Preserves the last successful Web preview when a later export fails.
- Shows bounded Host/export/runtime logs and structured failure locations.
- Persists user-editable Godot path and preview preferences under `DSH_HOME`.
- Stops managed exports, native runtimes, watchers, and preview servers on stop or plugin disposal.

The package **never downloads or installs Godot** and does not bundle Chromium, Android/Xcode tooling, export templates, or mini-game SDKs.

## Requirements

- DeepSeek Harness Desktop with Web profile plugin support.
- A user-installed Godot 4.x executable for real preview use.
- A `project.godot` file at the active Harness session workspace root.
- A Godot Web export preset named `Web` for Web preview.

GDScript and the Compatibility renderer are recommended for portable Web previews.

## Install

### DSH community marketplace

Open **Settings → DSH Plugin Marketplace**, search for `dsh-godot-preview`, and choose **Install**. The community index discovers public GitHub repositories carrying the `dsh-plugin` topic.

### GitHub

```powershell
dsh plugin --profile web add github:baiyuscc13724-max/dsh-godot-preview
```

### Release tarball

Download `dsh-godot-preview-0.1.0.tgz` from the matching GitHub Release, then run:

```powershell
dsh plugin --profile web add "C:\Downloads\dsh-godot-preview-0.1.0.tgz"
```

### npm, if a registry release is published later

```powershell
dsh plugin --profile web add dsh-godot-preview
```

### Development checkout

```powershell
npm install
npm run check
dsh plugin --profile web add "C:\path\to\dsh-godot-preview"
```

Refresh the existing Harness Web page after installation if the prebuilt Client module was not reloaded automatically.

## Use

1. Open a Harness session at a Godot project root.
2. Open the **Godot Preview** conversation view.
3. In **Settings → Godot Preview**, enter the absolute path to an existing Godot 4 executable. An empty path enables PATH discovery.
4. Select **Web** or **Native**.
5. Click **Start**.

Web mode serves only the most recent successful export. Native mode starts a managed Godot window. **Stop** is idempotent in both modes.

## Architecture

```text
conversation.view Client
  └─ GET/POST /api/godot-preview
       └─ Host service router
            ├─ project + executable validation
            ├─ Godot child-process lifecycle
            ├─ debounced single-flight exporter
            ├─ atomic preview promotion
            └─ 127.0.0.1 static preview server
```

The prebuilt Client is a DSH module-loader factory (`window.__ModuleLoader__.load`), not a plain browser ESM entry. The Host registers its API through the public `webServer` service and disposes every resource through the plugin lifecycle.

## Development and verification

```powershell
npm run typecheck
npm test
npm run build
npm run pack:check
```

`npm test` runs both:

- Vitest integration suites against the real `createGodotPreviewService` implementation.
- Node tests for the public HTTP adapter, settings persistence, and release-built Host modules.

All automated Godot behavior is driven by `fixtures/fake-godot/fake-godot.cjs` through `process.execPath` plus a controlled argv prefix. It covers successful exports, script errors, timeouts, noisy logs, native runtimes, child-process trees, Chinese/space paths, rebuild coalescing, failure fallback, traversal defenses, and cleanup without downloading Godot.

Run the end-to-end smoke demo:

```powershell
npm run build:host
node demo/smoke.cjs
```

## Security summary

- `spawn(..., { shell: false })` for every managed process.
- Resolved absolute executable and fixed Godot argv shapes.
- Minimal child environment allowlist; no credential capture.
- Loopback-only preview server.
- Plugin-specific request header plus Host/Origin checks.
- Canonical path containment and encoded traversal rejection.
- Bounded request bodies, process output, and UI logs.
- Managed output only under the configured project-relative directory.
- No cloud service, account, API key, telemetry, analytics, or remote data retention.
- Network access is limited to loopback (`127.0.0.1`) for the local API and Web preview.
- Local persistence is limited to plugin settings under `DSH_HOME` and generated preview output under the project `.godot-harness` directory.

The machine-readable `package.json#disclosure` field records these permissions for community catalog tooling. See [`docs/security.md`](docs/security.md) for details.

## Documentation

- [`docs/installation.md`](docs/installation.md)
- [`docs/configuration.md`](docs/configuration.md)
- [`docs/security.md`](docs/security.md)
- [`docs/troubleshooting.md`](docs/troubleshooting.md)
- [`docs/feasibility-report.md`](docs/feasibility-report.md)

## Uninstall

Click **Stop**, run:

```powershell
dsh plugin --profile web remove dsh-godot-preview
```

Then restart the Harness Web profile and refresh the existing page. Uninstalling does not remove Godot or game sources. Project-local `.godot-harness` output can be deleted manually after all previews have stopped.

## License

MIT