dsh-connectome 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-10-30
+
+First public release.
+
+### Added
+
+- **Connectome overlay** — a frame-wide dialog (slot `shell.overlay`) that renders a
+  force-directed graph of the current workspace on a single `<canvas>`.
+- **Relationship edges** — directed dependency links with arrowheads at the imported
+  file: solid for `import` / `export … from` / dynamic `import()` / `require` /
+  CSS `@import`, dashed for HTML and Markdown references. Hovering a link names both
+  endpoints and the relation kind.
+- **Relationship inspector** — hovering a node highlights its neighbourhood and lists
+  its direct relationships (`→` imports, `←` imported by), each row clickable; `+N`
+  summarises the remaining ones.
+- **Click to code** — clicking a neuron opens that file in the harness' right-Sidebar
+  document preview (`ctx.sidebarRight` + `dsh-resource://file/session/…`), with line
+  numbers, copy and automatic reload. A missing preview/session is explained in the
+  dialog footer instead of failing silently.
+- **Sidebar entry** — a `🧠 Connectome` row in the sidebar panel list's **More** menu
+  (slot `sidebar.panellist.actions`).
+- **Workspace switcher, rescan, fit, zoom, pan, node drag** and `Esc` to close.
+- **Theme-aware canvas** — colors read from live `--dsw-alias-*` tokens; light/dark
+  switches recolor the graph.
+- **Host scanner** — bounded recursive workspace scan with regex-based dependency
+  extraction for JS/TS/Vue/Svelte, CSS/SCSS/Sass/Less/Stylus, HTML, Markdown and
+  Python, served over a same-origin, connection-fenced `POST /connectome/api/graph`
+  route.
+- **Tests** — dependency-free scanner/route tests, artifact structure tests and a
+  package/release contract test (`node test/*.test.mjs`).
+
+[1.0.0]: https://github.com/elalamiimed/dsh-connectome/releases/tag/v1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Thanks for taking a look! Issues and pull requests are welcome.
+
+## Development setup
+
+The plugin is plain JavaScript with **no dev dependencies**: the d3 distributions it
+inlines are committed under `vendor/`, and the tests use Node builtins only.
+
+```bash
+git clone https://github.com/elalamiimed/dsh-connectome.git
+cd dsh-connectome
+
+node build.mjs     # regenerate client.js from client.source.js + vendor/
+npm test           # scanner, artifact and package contract tests
+npm run check      # node --check on host and generated client
+```
+
+You only need `npm install` if you want to rebuild `client.js` from a different
+d3-force copy: `node build.mjs --modules <node_modules dir>` looks there after
+`vendor/`.
+
+## Project layout
+
+| Path | Role |
+| --- | --- |
+| `index.js` | Host half: workspace scanner, dependency parser, fenced graph route. |
+| `client.source.js` | Readable Client half: slots, overlay, canvas engine. Build input. |
+| `client.js` | Generated browser artifact. **Never edit by hand** — run `node build.mjs`. |
+| `build.mjs` | Dependency-free build: inlines `vendor/d3-*.min.js`, emits the loader. |
+| `test/` | Node-builtin test suites. |
+| `locale/` | Plugin display metadata (English/Chinese). |
+
+## Rules of thumb
+
+- Keep the UI free of JSX (the client is authored as plain `React.createElement`) and
+  keep `client.source.js` free of `import`/`export` lines and non-baseline `require`
+  calls; the build validates both.
+- UI colors must come from the host `--dsw-alias-*` theme tokens, and spacing/type
+  geometry from the local `--ds-*` layer in the overlay stylesheet — do not invent
+  one-off colors or spacing values.
+- Never edit `client.js` directly: the build banner says so.
+- Add a regression check to `test/` when you fix a rendering or interaction bug.
+- Keep the first render path cheap: the canvas engine must retain its synchronous
+  first paint and its stopped/rAF-driven simulation.
+- Run `npm test` before opening a PR; CI runs the same suite on Node 18/20/22 and
+  verifies that `client.js` is reproducible.
+
+## Reporting bugs
+
+Include your DSH version (`dsh --version` or the desktop build), OS, the workspace
+shape (approximate file count), and what you expected to see. A screenshot or screen
+recording of the canvas is very helpful.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 elalamiimed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,217 @@
-# Temporary Holding Version
+# Connectome
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/elalamiimed/dsh-connectome/actions/workflows/ci.yml/badge.svg)](https://github.com/elalamiimed/dsh-connectome/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16A34A.svg)](LICENSE)
+[![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.2.1--rc.2-3B82F6.svg)](https://github.com/deepseek-ai/deepseek-harness)
+
+**A living map of your workspace for the DeepSeek Harness Web UI** — every file is a
+neuron, every import is a synapse. Connectome scans the current workspace, draws the
+file/dependency graph on a single `<canvas>` with `d3-force` physics, lets you trace
+any relationship, and turns a click on a neuron into the file's code in the
+harness' own right-sidebar preview.
+
+![Connectome illustration](docs/preview.svg)
+
+<sub>The banner is an illustration of the canvas graph, not a screenshot.</sub>
+
+## Features
+
+- **One canvas, hundreds of nodes, 60 fps.** Nodes and links are painted into a single
+  `<canvas>`; there is no DOM node per file. `d3-force` runs the layout, the plugin's
+  own `requestAnimationFrame` loop ticks it, and the simulation stops when idle.
+- **Relationships you can read.** Dependency edges carry an arrowhead at the imported
+  file: **solid** for `import` / `export … from` / dynamic `import()` / `require` / CSS
+  `@import`, **dashed** for HTML and Markdown references. Hover a link to see both
+  endpoints and the relation kind.
+- **Neighbourhood inspection.** Hovering a node highlights its neighbourhood and lists
+  its direct ties (`→` imports, `←` imported by), each clickable, with a `+N` summary
+  for the rest. Great for seeing how two modules — or two "engine" files — meet.
+- **Click to read code.** Clicking a neuron opens that file in the harness'
+  right-Sidebar document preview (`ctx.sidebarRight.openResource` with a
+  `dsh-resource://file/session/…` address): line numbers, language label, copy, and
+  automatic reload, all inside DSH. A missing preview or selected session is explained
+  in the footer.
+- **Theme-aware.** The canvas reads its colors from the live `--dsw-alias-*` theme
+  tokens at runtime, so light/dark switches recolor the graph.
+- **Workspace switcher, rescan, fit, zoom, pan, node drag, `Esc` to close.**
+- **Local by design.** No telemetry, no network calls, no workspace data leaves your
+  machine.
+
+## Install
+
+Connectome is a DSH **bundle** plugin: installing it adds a Host row (workspace scanner
++ HTTP route) and a lazy browser module (the canvas UI).
+
+### Requirements
+
+- DeepSeek Harness **0.2.1-rc.2 or newer** (Desktop or a `dsh web` deployment with the
+  standard Web bundle).
+- Node.js 18+ only if you build from source; the release ships `client.js` prebuilt.
+
+### From the Web UI (recommended)
+
+Open the sidebar's **Plugins** page, choose **Install**, and enter one of:
+
+```text
+dsh-connectome                                   # once published on npm
+github:elalamiimed/dsh-connectome                # straight from GitHub (works now)
+```
+
+The plugin manager enables the bundle after a successful install. Open the sidebar
+panel list's **More** menu and pick **🧠 Connectome**.
+
+### From a terminal
+
+The DSH CLI forwards package operations to the profile; then enable the bundle in
+**Plugins** (or keep using the Web UI above, which does both steps):
+
+```bash
+dsh plugin --profile desktop add github:elalamiimed/dsh-connectome
+# once published on npm:
+dsh plugin --profile desktop add dsh-connectome
+```
+
+### Manual / development install
+
+```bash
+git clone https://github.com/elalamiimed/dsh-connectome.git
+cd dsh-connectome
+# then install the folder as a bundle in the running profile, e.g. with
+# plugin_manager install_bundle <absolute-path>, or `dsh plugin add link:<absolute-path>`
+```
+
+> Note: the npm name `dsh-project-brain` belongs to an unrelated DSH plugin. This
+> project is published as **`dsh-connectome`**; the GitHub repository still uses the
+> "project brain" working title in its history only.
+
+## Usage
+
+1. Open the sidebar panel list's **More** menu → **🧠 Connectome**.
+2. The dialog scans the current workspace and fits the graph to view.
+3. Use the header to switch workspace (when several are registered), rescan, fit or
+   zoom; drag the background to pan; scroll to zoom around the pointer; drag a node to
+   pull it.
+4. Hover a node or a link for the relationship tooltip. Click a neuron to open the file
+   in the right sidebar. `Esc` / the ✕ button closes the dialog.
+
+## Supported dependency syntax
+
+The Host extracts links with small, dependency-free regexes (bare package names are
+deliberately **not** expanded into `node_modules`):
+
+| Files | Relationships |
+| --- | --- |
+| JS / TS / JSX / TSX / Vue / Svelte | `import … from`, `export … from`, dynamic `import()`, `require()` |
+| CSS / SCSS / Sass / Less / Stylus | `@import`, `@use`, `@forward` |
+| HTML | `<script src>`, `<link href>` |
+| Markdown | relative links and images |
+| Python | `import x`, `from . import y` |
+
+Only relative, root-relative and `@/` / `~/` specifiers resolve to workspace files.
+`node_modules`, `.git`, build outputs, caches and dot-directories are skipped.
+
+## How it works
+
+### Host half (`index.js`)
+
+- `POST /connectome/api/graph` — same-origin route fenced through
+  `ctx.connection.requestRejection(req)`; optional JSON body `{ "root": "<workspace>" }`.
+- Resolves the workspace root from the registered workspaces (or the current working
+  directory) and scans it under hard caps: 2,000 file nodes, 12,000 directory entries,
+  1,500 parsed files, 512 KiB read per file, an 8 s soft time budget.
+- Returns the graph:
+
+```json
+{
+  "ok": true,
+  "root": "C:\\path\\workspace",
+  "roots": [{ "path": "C:\\path\\workspace", "title": "my-project" }],
+  "nodes": [{ "id": "src/index.js", "label": "index.js", "ext": ".js", "size": 1234, "dir": "src" }],
+  "links": [{ "source": "src/index.js", "target": "src/util.js", "kind": "import" }],
+  "stats": { "files": 2, "scanned": 2, "links": 1, "truncated": false, "durationMs": 4 }
+}
+```
+
+### Client half (`client.source.js` → `client.js`)
+
+- Registers `sidebar.panellist.actions` (the menu row) and `shell.overlay` (the dialog),
+  both through `ctx.slots.inject` / `ctx.slots.register`.
+- Builds the d3 simulation once per loaded graph with `simulation.stop()`, then ticks it
+  from the plugin's `requestAnimationFrame` loop; hover changes update React state, but
+  pointer moves only mutate transforms, and frames are requested only while needed.
+- Batches all solid edges into one stroke, all documentation edges into a dashed
+  stroke, all arrowheads into one fill, and all nodes into one fill per color group.
+  Link hit-testing is a screen-space segment-distance pass — no DOM.
+- Layout seeds d3's phyllotaxis spiral and uses weak `forceX`/`forceY` centering, so
+  disconnected files stay in one cloud and fit-to-view never zooms to sub-pixel dots.
+- `ResizeObserver` keeps the backing store matched to CSS size (DPR clamped to 2);
+  `MutationObserver` re-reads theme tokens when the app theme changes.
+- `d3-force` (plus its UMD dependencies) is inlined into `client.js` by `build.mjs`:
+  the browser module table has no runtime npm resolution, so the bundle is
+  self-contained. `vendor/` pins the exact ISC-licensed distributions.
+- Clicking a node builds the harness' own file address
+  (`dsh-resource://file/session/<session>/<path>`) and calls
+  `ctx.get('sidebarRight').openResource(...)`; the on-screen session comes from
+  `sidebarRight.mounted`, with the UI Session adapter as fallback.
+
+## Privacy
+
+Connectome reads the workspace through the Host process, exactly like the rest of DSH.
+It sends **nothing** to the network: no analytics, no remote API calls, no file
+contents uploaded. The graph response stays between the Host and your local page; open
+files are displayed by DSH's built-in preview, and Connectome itself never keeps or
+transmits file contents.
+
+## Performance
+
+- Canvas painting, one path per color group; only the hovered neighbourhood gets labels.
+- The simulation stops at `alphaMin`; an interaction kicks it again.
+- Measured layout cost on a development machine: ~1.1 ms/tick at 300 nodes, ~8 ms/tick
+  at 2,000 nodes; a 2,000-node / ~3,300-link scan runs in about half a second warm.
+- Large workspaces are capped and report `stats.truncated`; the dialog shows a
+  "partial scan" marker.
+
+## Development
+
+No dev dependencies are needed — `vendor/` is committed and the tests use Node builtins.
+
+```bash
+node build.mjs      # regenerate client.js from client.source.js + vendor/
+npm test           # scanner + artifact + package/release contract tests
+npm run check      # node --check on index.js and the generated client
+npm pack --dry-run # inspect exactly what npm would publish
+```
+
+`npm install` is only needed to rebuild `client.js` from a different d3-force copy:
+`node build.mjs --modules <node_modules dir>` looks there after `vendor/`.
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the project layout and review rules, and
+[`PUBLISHING.md`](PUBLISHING.md) for the maintainer release flow.
+
+## Styling note
+
+The project-wide design-token rule asks frontend artifacts to use the `--ds-*` scale.
+This plugin is a Harness UI surface, so it deliberately splits the two systems:
+
+- **Colors** come only from the host's live `--dsw-alias-*` theme tokens (this is what
+  keeps the graph legible in both light and dark mode).
+- **Spacing / radii / shadows / font sizes** use a locally declared `--ds-*` token
+  layer (4px rhythm, 4/8/12/16/20/24 px spacing, 4/8/12/16 px radii, the shadow scale
+  and the caption/body-sm/body/h3 type scale) — no off-scale numeric styling.
+
+## Limitations
+
+- Regex-based parsing: aliases beyond `@/`/`~/`, `tsconfig` path maps and bundler
+  resolution rules are not modeled; bare package names do not become nodes.
+- Files are only previewed as code when the harness' right-Sidebar document preview is
+  available; unsupported extensions fall back to plain text, and binary files are not
+  indexed at all.
+- Very large repositories hit the scanner caps (see above) and show a partial graph.
+- The graph is a viewer, not an editor: there is no refactoring, search or saved layout.
+
+## License
+
+[MIT](LICENSE) © 2026 elalamiimed.
+
+Bundled d3 distributions (`vendor/`) are ISC licensed, Copyright 2010–2021 Mike
+Bostock; see [`vendor/LICENSE-d3.txt`](vendor/LICENSE-d3.txt). DeepSeek Harness and its
+packages are separate projects with their own licenses.

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security policy
+
+Connectome is a local visualization plugin: it scans the current workspace on the
+Host, serves the result over a same-origin HTTP route fenced by
+`ctx.connection.requestRejection`, and renders it in the browser. It sends no
+workspace data or telemetry to any third-party service.
+
+## Supported versions
+
+| Version | Supported |
+| --- | --- |
+| 1.x | Yes |
+
+## Reporting a vulnerability
+
+Please do **not** open a public issue for a security problem. Use GitHub's private
+vulnerability reporting on this repository (**Security → Advisories → Report a
+vulnerability**) or email the maintainer listed in `package.json`. You should get a
+response within a few days.
+
+Useful details: the affected version, the DSH version, the workspace shape, and the
+steps needed to reproduce the issue.
+
+## Scope notes
+
+- The scanner only reads text/source files under the selected workspace root, skips
+  symlinks, `node_modules`, `.git`, build outputs and dot-directories, and applies
+  file/duration/entry caps.
+- File opening uses the harness' own right-Sidebar document preview and the
+  authenticated `dsh-resource://file/session/…` address; Connectome itself never
+  reads a file into its own UI or stores file contents.
+- The generated browser bundle inlines d3 under its ISC license; see
+  `vendor/LICENSE-d3.txt`.