dsh-nebula

A DeepSeek Harness plugin that connects to a
NebulaGraph v5 server and executes ISO-GQL statements, in the spirit of
the ngql console.

The plugin speaks the native NebulaGraph v5 wire protocol (gRPC +
nebula.proto.graph.GraphService) with a pure-JS client — no native
modules, no external gateway. Results come back as structured JSON rows plus
an ngql-style ASCII table render.

Features

• Connect / authenticate against a graphd (nebula_connect), execute GQL on
  the same server-side session (nebula_execute), and close it
  (nebula_disconnect).
• Named instance profiles (Settings → NebulaGraph): manage any number of
  connection presets in the DSH settings page — each with its own
  host/port/user/passwordRef/TLS policy — addressed by a short alias. The
  model then just says "connect to the prod Nebula" and calls
  nebula_connect(instance: "prod"); the profile supplies the parameters.
  An instance can be marked as the default, used when no alias is given.
  Per-call tool arguments still override the profile.
• Decodes the columnar VectorResultTable payload exactly like the official
  nebula-go v5 client: scalars, strings, temporal values, lists, sets, maps,
  records, vertices, edges, paths, embedding vectors, geography, Any-typed
  columns, const vectors, and null bitmaps.
• Schema exploration (nebula_schema): one call runs SHOW GRAPHS,
  resolves the target graph (explicit graph= argument, the session working
  graph from SESSION SET graph, or the sole graph), then DESC GRAPH TYPE
  and returns the graph type's node types and edge types — labels,
  primary/multiedge keys, and properties. Read-only: the session working graph
  is never changed.
• Interactive graph rendering (Web Client): when a nebula_execute result
  contains nodes, edges, or paths, the result is projected into a replayable
  graph payload and the bundled Web Client plugin renders it as an interactive
  AntV G6 graph (drag / zoom / hover),
  alongside the normal table output.
• Bundles the gql-query-generator skill: the plugin registers a
  ctx.skills provider so the agent's skill tool can load NebulaGraph
  GQL-writing guidance (reference docs ship in gql-query-generator/references/
  and resolve against the packaged directory).
• Plugin config supplies default connection parameters; every tool argument
  can override them per call.
• Password never travels through the model: nebula_connect takes a
  passwordRef (a credential reference / environment variable name), not the
  password value. The value is resolved per connection through the DSH
  credentials seam (ctx.credentials, falling back to the process
  environment) and cleared from memory right after authentication. Tool
  arguments, output, and the registry never carry the plaintext.
• TLS by default, plaintext fallback available: connections try TLS first
  (tls: "auto", the default) and fall back to plaintext only when the server
  has no TLS listener — the fallback is reported to the caller as a warning.
  Set tls: "on" to require TLS (fails if the server does not speak it) or
  tls: "off" to force plaintext. CA / client certificate / key / server name
  overrides are configurable for private CAs and mutual TLS.
• Unloading the plugin closes every open session (effect-based cleanup).

Tools

Tool	Purpose
nebula_connect	Connect to a graphd and open a session. Arguments: instance (alias of a profile configured in Settings → NebulaGraph), host, port, user, passwordRef, tls, ca, timeoutMs (all optional). Resolution order: explicit instance alias → the default instance (if set) → plugin config; per-call arguments override the profile. The password itself is never an argument — it resolves from passwordRef via the DSH credentials seam / environment. Returns a connectionId (plus instance, viaDefault, warning, and tlsFallback when relevant).
nebula_execute	Run one GQL statement on a connection. Arguments: connectionId (required), gql (required), timeoutMs. Returns { ok, columns, rows, numRows, latencyUs, summary?, error? }.
nebula_schema	Introspect a graph's schema. Arguments: connectionId (required), graph (optional — defaults to the session working graph, then the sole graph). Runs SHOW GRAPHS + DESC GRAPH TYPE, returns { graphs, graph, nodes, edges, … }. Read-only.
nebula_disconnect	Close a connection and release its server-side session.

Skill

The plugin registers a bundled skill provider on ctx.skills named
dsh-nebula that serves the gql-query-generator skill from the packaged
gql-query-generator/ directory. The model can load it through the skill
tool (or a direct user invocation); its references/*.md resolve against the
packaged directory via the skill's resourceBase. The skill body is read
from disk on each load, so editing SKILL.md takes effect without a rebuild
for link-installed plugins.

Typical agent flow:

nebula_connect (host: 192.168.8.6, port: 9669, user: root, passwordRef: NEBULA_PASSWORD)
  → { connectionId: "…", tlsFallback: false }
nebula_execute (connectionId, gql: "SHOW GRAPHS")
nebula_schema  (connectionId, graph: "movie")
  → { graphs: […], graph: { name: "movie", graphType: "movie_type", … },
      nodes: [ { name: "Actor", labels: [Person], primaryKey: [id], … } ],
      edges: [ { name: "Act", source: "Actor", target: "Movie", … } ] }
nebula_execute (connectionId, gql: "SESSION SET graph movie")
nebula_execute (connectionId, gql: "MATCH (n) RETURN n LIMIT 5")
nebula_disconnect (connectionId)

Install

The plugin is an out-of-tree DSH bundle: a plain npm package whose manifest
declares a dsh.bundle patch. Any DSH installation (rc.5+; the web profile
ships ctx.skills, so the bundled skill provider works out of the box) can
install it in one command, from any of these sources (the release tarball is
the smoothest):

# recommended — the latest release's prebuilt tarball (stable URL, always current)
dsh plugin --profile web add https://github.com/xiajingchun/dsh-nebulagraph-v5/releases/latest/download/dsh-nebula.tgz

# a specific release (versioned, reproducible)
dsh plugin --profile web add https://github.com/xiajingchun/dsh-nebulagraph-v5/releases/download/v0.1.0/dsh-nebula-0.1.0.tgz

# from the npm registry (once published)
dsh plugin --profile web add dsh-nebula

# straight from the git repository (builds from source — see note below)
dsh plugin --profile web add github:xiajingchun/dsh-nebulagraph-v5#v0.1.0

# from a local tarball / checkout while developing
dsh plugin --profile web add /path/to/dsh-nebula-0.1.0.tgz
dsh plugin --profile web add link:/path/to/dsh-nebula

The release tarballs are the pnpm pack output: prebuilt lib/, so the
release and registry installs need no install-time build and no build-script
approval. This runs pnpm add in the profile directory, then appends
dsh-nebula to dsh.profile.bundles because the package declares a
dsh.bundle patch (cordis.patch.yml inserts the plugin row). Restart the
profile (dsh web) for the new bundle to mount.

Git installs build from source. pnpm fetches sources, not built
artifacts: it runs the package's prepare script (here pnpm build), which
needs the dev toolchain, and pnpm ≥10 refuses to run that script until it is
explicitly allowed — the first add fails and prints the package key. Copy
that key under allowBuilds in the profile's pnpm-workspace.yaml and
re-run. Prefer the release tarball or registry installs to avoid this, and
pin a commit (github:…/#<sha>) if you do install from git.

nodeLinker: hoisted profiles must approve the protobufjs build script (the
shipped web profile already does).

Releasing (for maintainers)

Every v* tag push triggers the GitHub Actions workflow
(.github/workflows/release.yml): it verifies
the tag matches package.json's version, installs, runs the tests, packs, and
uploads both the versioned dsh-nebula-<version>.tgz and a stable
dsh-nebula.tgz alias to the release — so
releases/latest/download/dsh-nebula.tgz always points at the newest build:

git tag v0.1.0 && git push origin v0.1.0

Manually (same result, no CI):

pnpm build && pnpm pack     # → dsh-nebula-0.1.0.tgz
# attach the tarball to a GitHub release (optionally also as dsh-nebula.tgz)

For an npm release instead:

npm login        # once
pnpm publish     # runs build + tests via prepublishOnly

The tarball (pnpm pack → dsh-nebula-0.1.0.tgz) is fully self-contained:
compiled lib/, vendored protos, the packaged gql-query-generator/ skill
(including its .feature evidence files), cordis.patch.yml, README, and
LICENSE. It was verified by installing the tarball into a fresh throwaway
profile: the bundle joins dsh.profile.bundles, the module resolves, and the
skill provider lists/loads gql-query-generator with its resource base inside
the installed package.

Config

Plugin config lives in the profile's patch layer (e.g.
~/.dsh/profiles/web/cordis.patch.yml):

- insert:
    - id: nebula
      name: dsh-nebula
      config:
        host: 127.0.0.1
        port: 9669
        user: root
        passwordRef: NEBULA_PASSWORD   # preferred: credential reference (env var name)
        tls: auto                      # auto | on | off
        timeoutMs: 30000
        maxConnections: 5

Field	Default	Meaning
host	127.0.0.1	Default graphd host.
port	9669	Default graphd gRPC port.
user	root	Default login user name.
passwordRef	(none)	Credential reference (environment variable name) resolving to the default password via the DSH credentials seam. Preferred over password — the value never appears in config surfaces, tool arguments, or logs.
password	''	Default login password (plaintext). Fallback used only when passwordRef is unset; keep it out of shared config files.
tls	'auto'	TLS mode: auto (try TLS, fall back to plaintext when the server has no TLS listener), on (require TLS), off (plaintext only).
ca	(none)	CA bundle (PEM) for verifying the server certificate (private / self-signed CAs).
cert / key	(none)	Client certificate and private key (PEM) for mutual TLS. The key is config-only and never exposed as a tool argument.
servername	(none)	Override the server name used for SNI and certificate verification.
timeoutMs	30000	Default per-request deadline (ms).
maxConnections	5	Upper bound on concurrently open connections.

To use a passwordRef, store the value in the DSH credentials document
(~/.dsh/.credentials.yaml, mode 0600) or the process environment, e.g.:

# ~/.dsh/.credentials.yaml
NEBULA_PASSWORD: s3cr3t

The password is resolved per connection at nebula_connect time and cleared
from memory immediately after authentication succeeds.

Instance profiles (Settings → NebulaGraph)

When the profile composes a settings provider (the Web GUI does), the plugin
registers a dsh-nebula settings namespace and a Settings →
NebulaGraph page. There you can:

• Add connection presets — each with an alias (letters/digits/_/-,
  ≤ 64 chars), host, port, user, passwordRef, TLS mode, per-instance
  CA / client cert / key / servername, timeoutMs, and a note.
• Edit / delete presets and mark one as the default.
• Manage the credential values behind the passwordRefs from the same
  page: every reference the instances name (plus extra references you add,
  e.g. the plugin-config default's) gets a write-only password field and a
  clear button. Values are written through the harness credentials RPC
  (credentials.set / credentials.unset) and persisted to the DSH
  credentials document (~/.dsh/.credentials.yaml). The page only ever shows
  whether a value is configured — never the value itself — and inputs always
  start blank.
• Passwords never enter the settings document: only the passwordRef
  (credential reference / environment variable name) is stored, and it is
  resolved through the DSH credentials seam at connect time like the
  plugin-config default.

nebula_connect resolution order:

1. explicit instance: <alias> — an unknown alias is a hard error that lists
   the configured aliases;
2. the default instance, when one is set (the connect output reports
   viaDefault: true; a stale default referencing a deleted instance falls
   back to plugin config with a warning);
3. plugin config (cordis.patch.yml).

Per-call host/port/user/passwordRef/tls/ca/timeoutMs arguments
still override the resolved profile. A non-auto TLS mode inside a profile is
an enforced transport policy exactly like plugin config: a conflicting tls
tool argument is rejected.

The page is implemented by the plugin's Web Client bundle
(client/NebulaInstancesSection.tsx), which reads and writes the namespace
through a plugin-owned Web route (/dsh-nebula/api, see
src/instances-api.ts) with the same browser-trust fence as the harness
gateway. A plugin-owned route is required because the harness's own settings
RPC (api.settings.*) serves only namespaces on its explicit exposure
allowlist — the established third-party pattern in this deployment
(dsh-better-sidebar's /sidebar/api). The host reads the same namespace at
connect time (src/instances.ts). Without a settings provider or a web
surface the route simply never mounts and the plugin keeps working on plugin
config alone.

Development

pnpm install
pnpm typecheck
pnpm build     # tsc → lib/ + copies vendored protos to lib/proto
pnpm test      # decoder unit tests + gRPC integration tests (in-process fake GraphService)

The package is plain ESM ("type": "module") with no runtime dependencies
beyond @grpc/grpc-js, @grpc/proto-loader, and schemastery.

How it works

• Protocol — the vendored protos under src/proto/nebula/ are the
  official NebulaGraph 5.0 definitions (graph/common/vector) from
  nebula-go v5. AuthRequest.auth_info is JSON.stringify({ password }) and
  ClientInfo.lang advertises JAVASCRIPT; Status.code == "00000" means
  success. The password is sent only inside the one-time Authenticate call
  and cleared from the client/registry options immediately after success.
• Transport security — the channel uses gRPC credentials per the tls
  mode: on → createSsl (with optional CA / client cert / server-name
  override), off → createInsecure, auto → try TLS first, then recreate
  the channel with plaintext credentials only when the handshake fails at the
  transport level (never on an authentication failure). A plaintext fallback
  is surfaced as tlsFallback in the connect output and as a warning line.
• Logout — the v5 gRPC service has no signout RPC; closing a session
  executes the SESSION CLOSE statement before releasing the channel
  (mirroring nebula-go v5 connection.Close()), so the server-side session
  is released immediately instead of lingering until its idle timeout.
• Decoder — src/decode/ is a faithful TypeScript port of nebula-go v5's
  internal/decode (column type schemas, flat/const vector layouts, chunked
  strings, node/edge property vectors, path adjacency lists, composite value
  encoding).
• Registry — open connections live in a per-plugin registry; disposing the
  plugin closes them all.
• Instance profiles — the dsh-nebula settings namespace is registered
  through installSettingsSection with the plugin config as the composition
  base: without a settings provider the tools read an empty section and fall
  back to config exactly as before, while the Web GUI edits the same
  namespace over the plugin-owned /dsh-nebula/api route. Alias resolution
  and validation are pure functions in src/instances.ts, shared by the
  tools and the settings surface contract.

License

MIT