@onthewayli/dsh-plugin-path-completion

English | 中文

Codex-style @path file completion for the DeepSeek Harness Web composer, shipped as an out-of-tree plugin: type @ (and keep typing) in the composer and the trigger menu lists matching files and directories from your session's project directory — arrow keys, Enter, and Escape drive the pick through the Harness's own input-trigger menu, and a picked path lands in the draft as @./relative/path (or the quoted @"path with spaces" form), which the Harness's prompt-side @path expansion turns into file content on send.

The plugin carries both halves in one package:

• Host half (lib/index.js) registers one HTTP route, /path-completion/search, on the Harness webserver and answers with a bounded, ranked candidate list. It never sends file content over the wire — only names, kinds, and query-shaped paths.
• Browser half (lib/client.js) registers one @ source on the shared input-trigger pipeline (ctx.inputTriggers), so no UI code, React, or CSS ships here: the pipeline's existing menu renders the candidates.

Install

# from a registry (published package)
dsh plugin --profile web add -w @onthewayli/dsh-plugin-path-completion
# from a checkout of this repo
dsh plugin --profile web add -w file:/path/to/dsh-plugin-path-completion
# from a tarball
npm pack && dsh plugin --profile web add -w ./onthewayli-dsh-plugin-path-completion-0.1.0.tgz
# from a git host (needs the profile's allowBuilds approval; pin a commit)
dsh plugin --profile web add -w github:OnTheWay111/dsh-plugin-path-completion#<sha>

dsh plugin forwards to pnpm inside ~/.dsh/profiles/web; because this package declares dsh.bundle, it is appended to the profile's dsh.profile.bundles automatically, and its cordis.patch.yml inserts its own loader row. Then restart the Web server: the client module system caches package metadata per name for the process lifetime, so plugin-set changes take effect on restart.

Uninstall with dsh plugin --profile web remove -w @onthewayli/dsh-plugin-path-completion.

Configuration

Optional row config in ~/.dsh/profiles/web/cordis.patch.yml:

- id: path-completion
  config:
    # Candidate-search bounds (defaults shown).
    maxResults: 50        # candidates one response carries
    maxVisited: 20000     # directory entries one query may visit
    budgetMs: 400         # wall-clock budget for one query's walk
    ignoreDirs: [node_modules, .git, dist, build, ...]  # never descended into
    # Extra bare `host[:port]` authorities allowed to call the route (LAN use).
    trustedHosts: []

Trust model

The route answers only when the request reaches it as the GUI's own origin:

• Host must be a loopback authority (127.0.0.1, localhost, [::1]) or an entry of trustedHosts;
• a request carrying Origin must carry the same authority as Host;
• Sec-Fetch-Site: cross-site is refused.

A browser reached over a LAN address therefore gets no completion until that authority is listed in trustedHosts. The route is read-only, returns names only, and never exposes file contents.

Compatibility

Plugin	Harness	Node	What it relies on
0.1.0	0.1.0-rc.5 or newer in the 0.1.x line (source checkout or published dsh)	>= 22.19	ctx.webServer.register on the host, the inputTriggers client service and its PickOutcome.text arm on the browser, and the Harness's own prompt-side @path expansion to read a picked file on send

Verified installs: file: directory, prebuilt tarball, and a source-checkout Harness profile, each booting with the plugin's client entry in the boot manifest and its route answering.

Coupling facts an upgrade can invalidate:

• The Harness ships client and host together and has no wire protocol version, so a Harness upgrade may require rebuilding this plugin. The halves type the interfaces they use structurally (src/index.ts, src/client/index.ts) so a mismatch fails at runtime with a named error instead of at build time against packages that may not be installed.
• @deepseek-ai/cordis is a peer (>=4.0.0 <5.0.0-0): the plugin is applied by the installation's own Cordis instance. No other official package is imported — collaboration is through Cordis services.
• The browser half throws a named error when inputTriggers is missing rather than silently doing nothing.
• The menu group title comes from the Harness's slash.menu dictionary, which an out-of-tree plugin cannot extend; the group therefore renders under this source's raw name (files).

Known limitations

• Picking a directory inserts @./dir/ and closes the menu; the next keystroke reopens it with that directory's children. The Harness re-detects a trigger on typing, not on a programmatic insert, so an immediately-reopening drill-down needs an upstream hook.
• @ also offers the Harness's session references (child sessions) in their own group; a bare fragment therefore matches files and session names side by side.
• Candidates come from the session's project directory for relative queries, the OS home for ~/…, and the absolute path for /…. The ignore list keeps large trees responsive, so a name living only inside e.g. node_modules is not offered unless you drill into it.

Publishing

Three distribution forms work, in increasing order of convenience for users:

Form	Publish	User install	Build permission needed
npm registry	npm publish (or your private registry)	dsh plugin --profile web add -w @onthewayli/dsh-plugin-path-completion	no (prebuilt lib/ ships in the tarball)
tarball	npm pack	dsh plugin --profile web add -w ./onthewayli-dsh-plugin-path-completion-0.1.0.tgz	no
git host	push the repo	dsh plugin --profile web add -w github:you/repo	yes — pnpm refuses a git dependency's prepare until the profile's pnpm-workspace.yaml allowlists it (allowBuilds); pin a commit

files lists lib/, cordis.patch.yml, and this README, and prepublishOnly/prepare rebuild the bundles — without the explicit files list, lib/ would be dropped from the tarball (it is gitignored) and an installed copy would fail to load. Verify with npm pack --dry-run before publishing: the listing must show lib/index.js and lib/client.js.

Publish under your own name: the @deepseek-ai/ scope belongs to the Harness project. Check the name is free first (npm view <name> version), since plugin packages are already appearing on the registry.

npm now blocks publishing unless the request carries 2FA: either pass the authenticator code (npm publish --otp=<code> --access public) or, for scripted/CI publishing, use a granular access token with "Bypass two-factor authentication" enabled (npmjs.com → Access Tokens → Generate New Token → Granular). A plain classic npm_ token gets a 403 on publish.

Development

# Requires tsdown + typescript; point node_modules at a Harness checkout (or install them):
#   ln -s ../deepseek-harness/node_modules node_modules
#
# The symlinked node_modules carries the rolldown native binding for the arch it was installed
# under (e.g. darwin-x64). Build/pack with a Node of the SAME arch and of >= 22.19 (tsdown needs
# ^22.18 || >=24); on this machine that is the x64 build of nvm's 22.23.2:
#   nvm use 22.23.2 && node_modules/.bin/tsdown
node_modules/.bin/tsdown                                   # build lib/index.js + lib/client.js
node --experimental-strip-types --test tests/plugin.test.ts # self-contained tests, no dependencies

dsh plugin add installs a copy of this package into the profile (pnpm's file: handling), so a rebuild is not picked up by an already-installed profile: re-run the add command after building, and restart the server (client package metadata is cached per name for the process lifetime).

The browser bundle must keep the Harness client-plugin shape: a CommonJS body wrapped in window.__ModuleLoader__.load({ id, factory }), with platform modules (React, cordis, the shared UI packages) left external and everything else inlined — an out-of-tree bundle cannot import another plugin's client module as a value.