Imported from Anestis271/dsh-desktop (AGENTS.md). Install upstream with npx skills add Anestis271/dsh-desktop. Copyright stays with the author.

Repository Guidelines

Project Structure

This repository contains the @anestis271/dsh-desktop dsh plugin. Keep architecture notes in docs/; runtime code is in src/, tests in tests/, and the bundle composer in scripts/. lib/ is generated by the build and must not be edited by hand. The Electron preload is the deliberately isolated CommonJS exception at src/electron-preload.cjs.

Build, Test, and Development Commands

Use pnpm with the repository's lockfile:

pnpm run build          # compose the official WebUI patch and compile TypeScript
pnpm run test:coverage  # run Vitest and enforce 100% statements/branches/functions/lines
pnpm run check          # build followed by the coverage gate
pnpm pack --dry-run     # inspect the published file list

The local smoke test packs to a temporary directory, installs that tarball with dsh plugin --profile desktop add <tarball>, then starts it with dsh --profile desktop. Do not smoke-test with add .; its checkout link can resolve development copies of host peers.

Coding and Documentation Style

Use two-space indentation, strict TypeScript, ESM imports with .js specifiers, and kebab-case filenames. Keep public interfaces typed and small; add comments only for non-obvious platform or security decisions. Use apply_patch for manual edits and leave generated lib/ output to pnpm run build.

Testing Guidelines

Add Vitest specs in tests/ named after the module, for example shortcuts.spec.ts. Every source branch must be exercised: the coverage command is configured to fail below 100% for all four metrics. Include platform branches, lifecycle cleanup, IPC validation, title-bar behavior, tray actions, and default-off shortcut settings.

Commit and Pull Request Guidelines

Use concise imperative Conventional Commit-style subjects, such as docs: clarify desktop plugin integration or feat: add tray lifecycle. Keep commits focused. Pull requests should explain the user-visible behavior, identify platform-specific changes, include test commands and results, and attach screenshots or recordings for title-bar, tray, or shortcut UI changes. Do not commit credentials, generated binaries, or platform-specific user data.

Security and Configuration

Never embed WebUI tokens in URLs, logs, or shortcuts. Preserve Electron isolation (contextIsolation, sandboxing, and disabled Node integration) and allow navigation only to dsh-provided origins. Store window state and settings in the profile scope, not global files.