dsh-open-path

dsh-open-path

English · 中文

/open — opens files and http(s) links with the system default program and folders in the file manager, covering direct paths, direct URLs and fuzzy workspace search.

dsh-TUI · a plugin built for the dsh-TUI ecosystem

This plugin is a dsh-TUI ecosystem plugin; ecosystem site: https://dshtui.com/. Community v0.15 manifest, MIT licensed, supporting Windows / macOS / Linux (including WSL).

Capabilities

• /open (no argument) → opens the current session's working directory in the system file manager
• /open https://example.com → opens the http(s) link with the default browser/handler (case-insensitive; only http/https are let through, and file:/ftp:/javascript: and other schemes are rejected with an explicit error)
• /open github.com → bare domains get their scheme filled in: domains get https://, localhost:5173/127.0.0.1:8080 get http:// (local development); a real file of the same name in the workspace wins; common file extensions (.md/.ts/.json…) are not misread as domains
• /open src/index.ts → opens an existing relative / absolute path
• /open ~/docs → ~ / ~/… expands to the home directory (~user is not expanded)
• /open readme → fuzzy-searches the current workspace (file/folder names, CJK- and case-insensitive, Unicode NFD/NFC normalised)
  • exactly one hit → opened directly
  • several hits → the host's managed dialog (TUI seam 十) lists the candidates, with no cap on the count: the panel is windowed to the terminal height and scrolls up/down with ↑/↓ (with scroll arrows), Enter opens, Esc cancels
  • more hits than the host dialog's ceiling (100) → only the top 100 are shown, and the title spells it out: 共 N 个匹配，仅显示前 100 个 — never a silent swallow
  • zero hits → an explicit error: 工作区中找不到与 “…” 相关的文件或文件夹
• a folder hit → the folder opens in the file manager; a file hit → it opens in the associated default program

Install

# install from npm (package name: dsh-open-path)
dsh plugin --profile dsh-tui add dsh-open-path

# install from a local checkout of this repository (development)
pnpm install --frozen-lockfile && pnpm build
cd ~/.dsh/profiles/dsh-tui && pnpm add <path to this repository>
# and add dsh-open-path to dsh.profile.bundles in package.json

After installing, run /restart inside the TUI (or reopen the window) for it to take effect.

Platform support

The open action runs an ordered launcher chain: the first candidate on the chain that can start successfully (and does not exit non-zero within the grace window) wins; otherwise it automatically falls back to the next one; when the whole chain fails it reports an explicit error and lists the launchers it tried. A chain can also come back empty — a Windows file/URL containing % has no cmd-free channel — and that is reported as a refusal naming the reason, never as an attempted hand-off.

Failure is not judged by "the process started, so it worked": a launcher that cannot be spawned (xdg-open not installed → ENOENT) or that exits non-zero quickly (no associated program) is recognised and triggers the fallback; when the target path itself does not exist it reports an explicit error instead of falsely claiming 已打开.

The receipt also says which evidence the success rests on: 已打开 only when the launcher exited 0 inside the grace window, and 已启动 …（未确认退出码） when the window expired with the launcher still alive — a timeout is never upgraded into a confirmed open.

Compatibility

• Minimum dependency: @deepseek-harness-tui/dsh-tui >= 0.10.0-beta.5 (command-registration surface C-041 managed surface + fallback; the managed dialog is a "stable candidate" seam)
• Manifest: Community v0.15 (commands.dsh/v1alpha1#Command required; commands.invoke is declared, allowed by default and revocable through the authorization file's denies)
• Command registration: prefers ctx.tuiPluginHost.registerCommand (C-041 attribution + invoke checkpoint); when the host does not provide it, it falls back to the plain commands service (C-070 boundary — functionally equivalent, but without the attribution mark)
• Dialog: a soft probe through ctx.get('tuiDialogs', false) (#183 discipline); when the service is missing it degrades to a clear error listing the candidates, never crashing and never affecting TUI startup
• Diagnostic log: ~/.dsh-tui/dsh-open-path.log — one line each for module import / apply start / seam probes (tuiPluginHost·commands·tuiDialogs, each 0/1) / the registration result / unload; trimmed past 128 KiB to keep the newest half; not written during test runs and under node --test
• No dependency pollution: it does not import upstream package types (structural minimal interfaces), so upstream version drift cannot break this plugin; it also does not reuse the TUI's internal private modules
• No graphical session: always available on Windows/macOS (on Windows this is an assumption rather than a probe — see Known Limitations); Linux needs DISPLAY/WAYLAND_DISPLAY; WSL is the exception (it goes through the Windows side). When unavailable it reports an explicit error rather than failing silently
• CI: ubuntu-latest / windows-latest / macos-latest (Node 24, plus Ubuntu × Node 22 to cover the engines lower bound)

Language

Command receipts, error messages, picker candidates and command hints all follow the host language, resolved along the same chain dsh-TUI itself uses:

DSH_TUI_LANG → the live dsh-tui settings namespace (where /lang writes) → ~/.dsh-tui/lang.json → the OS locale → Chinese.

• An unsupported but present locale falls back to English; a missing one keeps Chinese, which is what keeps a Chinese host that never wrote a preference byte-identical to the pre-i18n releases.
• The language is re-resolved on every invocation, so switching with /lang needs no restart; the hint text inside command completion is a snapshot taken at registration time and follows the new language after a restart.
• DSH_OPEN_PATH_LANG_FILE overrides the preferences file path (for tests and diagnostics).

Configuration

Configuration is overridden through /settings or the profile's cordis configuration; every key has a default, and a missing one degrades to the default behaviour.

Working-directory semantics

The command is relative to the working directory of the receiving session (agent.session.header.cwd, the host-side cwd recorded in the DSH session header) rather than the process cwd — switching with /workspace in the TUI creates a new session, whose header carries the new directory, so /open always follows along; in extreme cases it falls back through session.meta.cwd (the older host alias) → the process start directory in turn.

Relative paths in the fuzzy index are always separated with / (equally true on Windows), so the same index has identical semantics on all three platforms.

Model Experience

The command executes on the UI command plane and the result text is rendered directly by the adapter: it produces no model messages, counts toward no model tokens and enters no model KV cache. command/run / command/done are recorded in the session log as log-only events.

Known Limitations

• Only http:// / https:// links are accepted (including bare-domain completion); file:, ftp:, javascript:, mailto: and other schemes are rejected with an explicit error and are never handed to the system. The bare-domain guess exempts common file extensions (.md/.ts/.json etc. are treated as files), and single-character TLDs (such as a.b) and version numbers (v2.0.1) are not taken for URLs either.
• The fuzzy index is bounded by depth (≤6 levels) and entry count (≤20000); on very large repositories the scan stops at the cancellation signal or the ceiling, and whatever lies beyond is not searched.
• The number of rows in the managed picker is ultimately bounded by the host: dsh-tui 0.10.x's tuiDialogs.select keeps only the first 100 options of the request (the rest are dropped silently, and the plugin cannot read that constant). This plugin therefore aligns itself with 100 and says so in the title when there are more hits, but candidates beyond 100 cannot be shown on the current host; a genuinely unlimited picker would have to go through a self-drawn tuiScenes selector.
• Symbolic links pointing at directories are indexed as directories but are not traversed recursively (loop and workspace-escape protection).
• ~ expansion covers ~ / ~/… / ~\… only; ~user is not resolved (no passwd lookup).
• When the target is a file and the system has no associated program, the behaviour is up to the system (Windows may show a "How do you want to open this file?" dialog) — the platform default is kept, and no program is chosen on your behalf.
• The open action is still fire-and-forget: failure is observed and rolled back only within a 180 ms grace window, after which it no longer waits for the target program to finish loading; a launcher that crashes after the window goes unnoticed. The window can only ever prove "still running", so the receipt keeps the two readings apart — 已打开 requires an exit 0 inside the window, and a launcher still alive when the window expires is reported as 已启动 …（未确认退出码）.
• A Windows target containing % cannot be handed to cmd at all: %VAR% is expanded even inside double quotes, so a percent-encoded URL (https://x.com/a%20b%20c) or a path like 50%off would be silently rewritten to a different target. Such a file or URL is refused with an explicit error naming %; a folder with % still opens, because its channel is the PowerShell COM call, whose single-quoted literal leaves % alone. macOS/Linux/WSL channels pass % through unchanged.
• On Windows the plugin assumes a graphical session always exists (hasGraphicalSession() returns true unconditionally), so a desktop-less Windows host — a pure SSH session, a service account — is never told "no graphical session"; the reported result on such a host may be inaccurate.
• In some desktop environments xdg-open blocks until the application exits — this plugin is unaffected (it counts as opened once the grace window has passed).

Publishing

• Repository: https://github.com/VviLliAm-qwq/dsh-open-path (public)
• Versioning: semantic versioning; releases are driven by v* tags (.github/workflows/release.yml: verify the tag matches the package.json version → build/test/checks → npm publish --provenance → GitHub Release)
• Prerequisite: the npm package has a Trusted Publisher configured (GitHub Actions · this repository · release.yml) — publishing uses OIDC, so no token has to be stored in the repository
• Ecosystem listing: per the listing requirements of https://dshtui.com/plugins/, this README carries the dsh-TUI link at the top (the fixed wording given by that site: [dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI) · 一个为 dsh-TUI 生态打造的插件)

Development and verification

pnpm install
pnpm build             # tsc -> lib/
pnpm test              # vitest (platform branches are covered cross-platform through injected platform/env)
pnpm validate:manifest # dsh-plugin.json admission-shape check
pnpm pack:verify       # published-artifact layout check
pnpm prepublishOnly    # all four, in one go

License

MIT