dsh-trellis-dashboard

Readme

# dsh-trellis-dashboard

**English** | [简体中文](README.zh.md)

A **Trellis × DSH workspace dashboard**: a DSH plugin that adds a **Trellis** tab
to the conversation-view ring of the DeepSeek Harness web UI, projecting the
current workspace's `.trellis/` state:

1. **Current task + progress** — task list + current-task resolution (a
   **per-session pointer only**; no guessing from task statuses — an unbound
   conversation shows "No trellis task" instead of a random task) + a task card
   with the `prd.md` acceptance checklist; a "Set as current task" button writes
   the per-session pointer.
2. **Spec / skill usage** — live spec-file reads (`fs/observed` on
   `.trellis/spec/**`, `.agents/skills/**`, `.dsh/skills/**`) and `skill` tool
   loads (`tools/result`), **scoped per session** (`exec.agent.id`) so one
   conversation's activity never leaks into another's dashboard.
3. **Workspace session summary** — developer journal index + latest
   `journal-N.md` excerpt.

Markdown is rendered inside the tab (headings, lists, task lists, tables, code,
blockquotes) with a small built-in renderer — no external runtime dependency.

---

## Installation

### Prerequisites

- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`
  CLI) with a **web** profile, e.g. `dsh --profile web`.
- The target workspace has been initialized with
  [Trellis](https://github.com/mindfoldhq/trellis): `trellis init --dsh`.

### From npm (recommended)

The package ships prebuilt, self-contained artifacts — no build step, no build
permission needed:

```bash
npm install -g @deepseek-ai/dsh   # if not already installed
dsh plugin --profile web add dsh-trellis-dashboard
```

Verify the composition layer was inserted, then restart the web app:

```bash
dsh --profile web --dump-config        # should show a "# == dsh-trellis-dashboard" layer
# restart dsh web → http://127.0.0.1:3080 → the Trellis tab appears in a conversation
```

### From a tarball

```bash
dsh plugin --profile web add ./dsh-trellis-dashboard-0.1.0.tgz
```

### From GitHub

This package has **no build step**: `lib/` is plain JavaScript, committed
directly to the repository, so a git install fetches runnable artifacts and
needs no `prepare` script or `allowBuilds` allowance:

```bash
dsh plugin --profile web add github:QianziTech/dsh-trellis-dashboard#<sha>
```

### From a local directory

```bash
dsh plugin --profile web add /path/to/dsh-trellis-dashboard
```

### Uninstall

```bash
dsh plugin --profile web remove dsh-trellis-dashboard
```

---

## What ships in the package vs. what stays in the repo

The npm tarball is intentionally minimal — it contains only what the plugin
needs to run:

```
dsh-trellis-dashboard-0.1.0.tgz
├── package.json          # dsh plugin manifest (bundle patch + dsh.client)
├── cordis.patch.yml      # inserts the HOST row into the web profile composition
├── lib/
│   ├── index.js          # HOST half  — fs reads + usage tracking + HTTP JSON API (webServer)
│   └── client.js         # CLIENT half — conversation.view tab + markdown rendering (browser bundle)
├── README.md
├── README.zh.md
└── LICENSE
```

The rest of the source repository — `.trellis/`, `.claude/`, `.codex/`,
`.agents/`, `plans/`, `docs/`, `test/`, `AGENTS.md` — is **development and
personal tooling state and is never published**. `npm pack --dry-run` confirms
exactly these six shipped files. End users only ever need
`dsh plugin add dsh-trellis-dashboard`.

## Usage

Once installed, open any conversation in the web UI and click the **Trellis**
tab in the conversation-view ring. The tab:

- resolves the current workspace from the web app's workspace list;
- polls the host JSON API (`GET /dsh-trellis-dashboard/state`) every 5 s while
  mounted;
- renders the current task card, acceptance checklist, spec/skill usage, and
  journal summary;
- "Set as current task" writes the per-session pointer
  (`POST /dsh-trellis-dashboard/set-current-task`) — the only write the plugin
  performs.

## Architecture

- **Host half** (`lib/index.js`) reads `.trellis/` through `ctx.fs` (never runs
  `python task.py` scripts) and exposes the dashboard JSON API as `webServer`
  HTTP routes. It subscribes to `fs/observed` + `tools/result` for the usage
  section.
- **Client half** (`lib/client.js`) registers `conversation.view` (id
  `trellis`, order 20 — a pure addition, no shipped UI replaced), resolves the
  workspace from `useWorkspaces`, polls the host API, and renders with
  `React.createElement` + a self-contained markdown renderer.
- **Published channel is HTTP**: `harness.handle`/`host.call` exist only for
  dynamic runtime plugins, so a published plugin's client→host traffic goes
  through `webServer` routes; the client polls because there is no host→client
  push channel.
- `.trellis/` stays **read-only** except the one session-pointer write in
  `set-current-task` (replicates `trellis task.py set_active_task`).

### Hot-reload matrix

| What changed | How it takes effect | Web rebuild needed? |
|---|---|---|
| Dynamic prototype code (`cordis_define`) | Append a new Package → `cordis_run update` | No (loaded at runtime) |
| Published host (`lib/index.js`) | Reinstall / composition restart | No (loaded with the composition) |
| Published client (`lib/client.js`) | clientModules served by file hash | **Yes** |
| Checkout client sources (web shell / plain packages) | `pnpm run dev:web` watcher rebuilds the bundle | Yes (dev mode) |

Key distinction: dynamic plugins are evaluated directly by the runtime runner
(no Vite/dev:web needed); only edits to **source files inside the checkout**
(published client modules / web shell) require a `dev:web` rebuild, and the
watcher must run from the **same checkout**.

### Troubleshooting

| Symptom | Fix |
|---|---|
| No Trellis tab after install | Client bundle not rebuilt → rerun the web build / `dev:web`; or the layer is missing → check `--dump-config` |
| Host route 404 | `webServer` routes not registered → confirm `inject: ['fs','webServer']` and the profile is `web` |
| Dynamic plugin activation fails | `cordis_inspect_self(pluginId, packageId)` for diagnostics → append a fixed Package in the same plugin and `update` |
| GitHub install errors | Not needed for this package (no `prepare`), but if you fork it: pin a commit and review the `allowBuilds` guidance in the official docs |

## Development

```bash
npm run check   # node --check lib/index.js && node --check lib/client.js
npm test        # node --test test/ — contract + coupling + spec-consistency tests
```

The plugin is dependency-free plain JavaScript. No build step is required to
read the sources; the client bundle is written directly in the web app's
`window.__ModuleLoader__.load({ id, factory })` format. Framework-level
development guidelines live in `.trellis/spec/dsh-plugin/` (source repo only);
operation/debugging/hot-reload notes are in
[`docs/dsh-plugin-development.md`](https://github.com/QianziTech/dsh-trellis-dashboard/blob/master/docs/dsh-plugin-development.md).

## License

MIT — see [LICENSE](LICENSE).