@dsh-lens/dsh-lens

Readme

# dsh-lens

A "code health check" plugin for DSH (DeepSeek Harness). It watches your code
changes, checks for syntax/type/lint problems, shows them on a card next to the
chat input, and shares them with the AI assistant — no technical knowledge
required.

---

## 1. What does it do?

Think of it as a doctor who sits next to your code:

- After every edit, it quickly checks for obvious mistakes (e.g. a missing
  bracket).
- When the AI reads or edits a TypeScript/JavaScript file, it runs a full check in the background (type check, lint).
- Problems appear on a **diagnostic card** above the chat input and are also
  reported to the AI assistant so it can help fix them.

It never blocks your edits or modifies your files on its own. Card refreshes use a separate read-only endpoint and never place snapshot JSON in the AI conversation context.

---

## 2. Before you start

| You need | How to check |
| --- | --- |
| A computer (Windows or Mac) | You are using one now ✓ |
| DSH installed | You can open the DSH web UI |
| A terminal window | See Step 1 below |

> **What is a terminal?** On Windows it is called **PowerShell**:
> click the **Start** button → type `PowerShell` → press Enter.
> A dark window with a blinking cursor appears. All commands below are typed there.

---

## 3. Install, step by step (about 3 minutes)

### Step 1 — Check that DSH is installed

Copy this line into the terminal and press Enter:

```
dsh --version
```

**Success looks like:** a version number such as `0.1.0-rc.6`.

**If you see `dsh is not recognized` (or `command not found`):** DSH is not
installed yet or not on your PATH. Install DSH first (see FAQ below).

---

### Step 2 — Install the plugin (copy one command)

```
dsh plugin --profile web add npm:@dsh-lens/dsh-lens
```

What this does: `dsh plugin` manages plugins, `--profile web` targets the web
profile, `add npm:@dsh-lens/dsh-lens` downloads the plugin from npm (an app
store for software).

**Success looks like:** text scrolls and stops, returning to a prompt (usually
`Done`). It normally takes less than a minute.

> **Testing locally before publishing?** Run `npm run pack` in the plugin
> source folder (produces `dsh-lens-0.1.0.tgz`), then install it:
>
> ```
> dsh plugin --profile web add C:\your\path\dsh-lens-0.1.0.tgz
> ```
>
> (Plain `npm pack` names the file `dsh-lens-dsh-lens-0.1.0.tgz` — also fine;
> delete the old .tgz before repacking.)

---

### Step 3 — Confirm it is installed

```
dsh plugin --profile web list
```

**Success looks like:** the list contains a line with `@dsh-lens/dsh-lens`.

---

### Step 4 — Restart DSH

1. Close the DSH window/page completely.
2. Open DSH again as usual.

Done. It starts working automatically — no further setup.

---

## 4. Quick check that it works (30 seconds)

1. Open any TypeScript project (a folder containing `tsconfig.json`).
2. Open a `.ts` file and intentionally break one line, e.g.:
   ```
   const x: number = "hello";
   ```
3. Save the file.
4. Look near the chat input — a **diagnostic card** should appear saying
   something like "1 个问题 / 1 issue".

> Projects without a `tsconfig.json` are intentionally not checked.

---

## 5. FAQ

| Problem | Solution |
| --- | --- |
| `dsh is not recognized` | DSH is not installed or not on PATH. Reinstall DSH. |
| Permission error / Access denied | Right-click PowerShell → **Run as administrator**, retry Step 2. |
| No card after restart | Make sure you opened the **web** UI, the project has `tsconfig.json`, and Step 3 listed the plugin. |
| Card always says "no diagnostics" | Normal — no problems found. Introduce an error and save to see it. |
| Want to uninstall | `dsh plugin --profile web remove dsh-lens` |
| Want to disable checks | See "Advanced settings" below; set `enabled` to `false`. |

---

## 6. Advanced settings (some technical knowledge needed; skippable)

The defaults work for most users. To customize, create a file named
`.dsh-lens.json` in your project root (never auto-generated):

```json
{
  "enabled": true,
  "typecheck": { "enabled": true },
  "eslint": { "enabled": false },
  "exclude": ["generated/**"]
}
```

Priority: built-in defaults < DSH global config < project `.dsh-lens.json`.
Changes hot-reload on save — no restart needed.

Full config (profile patch):

```yaml
- id: dsh-lens
  config:
    enabled: true
    include:
      - "**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"
    exclude:
      - "**/node_modules/**"
      - "**/dist/**"
      - "**/build/**"
    fast:
      enabled: true
      maxFileBytes: 524288
      budgetMs: 50
    typecheck:
      enabled: true
      debounceMs: 800
      timeoutMs: 60000
    eslint:
      enabled: false
      debounceMs: 1000
      timeoutMs: 30000
    feedback:
      inject: true
      maxDiagnostics: 8
      maxBytes: 4096
    scheduler:
      maxConcurrentProjects: 2
```

---

## 7. For developers

- Requirements: Node.js `>= 20`; DSH baseline `0.1.0-rc.6` (all
  `@deepseek-ai/*` packages are peers, not bundled); TypeScript `>= 5.0.0` is an
  optional peer.
- Commands: `npm install` → `npm run verify` (typecheck + 107 tests + build) →
  `npm pack --dry-run`.
- Pipeline:

```
write/edit ──► quick syntax (transpileModule) ──► post-execute additionalContexts
     │
read ─┴─► debounced background check (tsc / eslint via ctx.subprocess)
              └─► delta classification ──► agent.inject() report
                                     └─► lens snapshot ──► Web card
```

- Modules: `./client`, `./adapter`, `./diagnostics`, `./quick-syntax`,
  `./scheduler`, `./background-check`, `./providers`, `./delta`, `./feedback`,
  `./snapshot`, `./lens-card`, `./config`, `./reliability`, `./types`.
- The Web card polls a same-origin, no-store HTTP snapshot endpoint; polling
  does not write command events or snapshot JSON into the Session context.
- Known limitations: no Web settings page in the first release; `typecheck`
  and `eslint` share one debounce pipeline.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).

## License

MIT — see [LICENSE](./LICENSE).