dsh-jenkins

dsh-jenkins

A DeepSeek Harness plugin (dual-face: host + browser) for managing multiple Jenkins servers and triggering jobs — from a Settings page, from model tools, and from a per-workspace "Run Jenkins Job" entry. No hardcoded paths, TypeScript throughout, publishable to npm / GitHub. UI copy is bilingual (Chinese / English, following the host UI language).

中文文档

Features

• Settings → Jenkins Config page (settings.section): add / edit / delete multiple servers (URL, username, Token), test connections, skip TLS verification. Only Server URL and Token are required (username defaults to admin).
• Workspace entry (sidebar.footer.action): a footer group with the Jenkins logo button (opens the Run Jenkins Job modal) and a History button (clock icon, publish history of the last 50 runs across all workspaces, filterable by workspace — defaults to All) appears when the current workspace root contains a dsh-jenkins.{json,js,ts} config file. The modal has searchable dropdowns for server / job, a parameter form pre-filled from the config, build triggering, and status polling (queued → building → result, with a 10-minute timeout). The server dropdown shows the intersection of the servers referenced by the config and the servers configured in the plugin; selecting a server auto-selects the configured job and echoes its parameters. The last submitted server / job / parameters are remembered per workspace and auto-echoed the next time the modal opens (browser localStorage). A missing or invalid config file is treated as "not configured" — no entry is shown.
• Model tools (docs/develop/basic/tool): dsh_jenkins_build, dsh_jenkins_status.
• Config (docs/develop/basic/config): Schemastery Config + a settings namespace that persists UI edits to $DSH_HOME/settings.yaml (server list stored as JSON text to avoid frozen-array pitfalls).
• Packaging (docs/develop/basic/publish): dsh.bundle + dsh.client(web) manifests.

Structure

├── src/host/*.ts       # Host half source: index.ts (entry), jenkins.ts (curl core), ops.ts (op dispatch), workspace-config.ts, types.ts
├── src/client/*.tsx    # Browser half source (React TSX components): Settings page, footer entry, run-job modal, history modal
├── lib/index.js        # Host half build artifact (tsdown, ESM), committed for git installs
├── lib/client.js       # Browser half build artifact (tsdown → __ModuleLoader__ factory), committed
├── lib/types/          # Type declarations (generated by tsc -b)
├── scripts/            # verify-client.mjs (host-seed simulation check)
├── tsdown.config.ts    # tsdown build config (node half + client bundle banner wrapper)
├── tsconfig.json       # solution: references tsconfig.host.json / tsconfig.client.json
├── cordis.patch.yml    # Bundle patch: plugin row referenced by package name (no paths)
├── package.json        # dsh.bundle + dsh.client(web) manifests + peerDependencies
├── README.md           # This file (English)
└── README.zh.md        # 中文文档

Workspace config file (dsh-jenkins.json / .js / .ts)

Place it in the workspace root. It is an array; each element is one deploy target (job + server + environments params). .json is parsed directly; .js / .ts are evaluated with node (CJS module.exports or ESM export default):

[
  {
    "job": "build-app",
    "server": "http://uat.example.com",
    "environments": { "BRANCH": "main", "DEPLOY": false }
  },
  {
    "job": "build-app",
    "server": "http://prod.example.com",
    "environments": { "BRANCH": "release-1.0", "DEPLOY": true }
  }
]

• Every element requires job (Jenkins job path, e.g. build-app or folder/build-app) and server (the server name / id / URL as configured in Settings → Jenkins).
• environments (optional): the parameter map for this target (booleans render as checkboxes, everything else as text fields).
• The modal's server dropdown shows the intersection of the servers referenced by the config and the servers configured in the plugin; selecting a server auto-selects the matching job (left empty when absent from the Jenkins job list, letting the user choose) and echoes its parameters. If the intersection is empty, the dropdown degrades to all servers with a hint. A missing or invalid config is treated as "not configured" — the entry is hidden.

Installation

# Local development
dsh plugin --profile web add ./dsh-jenkins

# Published: npm / tarball / GitHub
dsh plugin --profile web add dsh-jenkins
dsh plugin --profile web add ./dsh-jenkins-0.1.4.tgz
dsh plugin --profile web add github:you/dsh-jenkins#<sha>

dsh --profile web --dump-config   # verify the layer
dsh --profile web                 # start (restart required for the host half to reload)

Local development dependencies: the host loads index.js through native Node ESM, so @deepseek-ai/schemastery, @deepseek-ai/dsh-tools and @deepseek-ai/dsh-settings must be resolvable from the plugin directory (node_modules is gitignored). Either:

1. run pnpm install inside the plugin directory (these three are declared as devDependencies); or
2. junction the host's flat fallback copies, e.g.:

   New-Item -ItemType Directory "$PWD\node_modules\@deepseek-ai" -Force
   foreach ($p in 'schemastery','dsh-tools','dsh-settings') {
     New-Item -ItemType Junction "$PWD\node_modules\@deepseek-ai\$p" -Target "$env:DSH_HOME\profiles\node_modules\@deepseek-ai\$p"
   }
   

Static server defaults can also be set in the profile's cordis.patch.yml:

- insert:
    - id: dsh-jenkins
      name: dsh-jenkins
      config:
        servers:
          - id: prod
            name: 生产环境
            baseUrl: https://jenkins.example.com
            username: admin
            token: <API Token or password>
            insecure: false

Publish

The build toolchain is tsc + tsdown (same as @lemcae/dsh-balance and other similar plugins — no vite): tsc -b type-checks and emits declarations, while tsdown (Rolldown core) bundles the host half (lib/index.js, ESM) and the browser half (lib/client.js, single-file CJS __ModuleLoader__ factory with auto banner wrapping). Dependency management uses pnpm 10 (Node 26; the pnpm-lock.yaml is committed and CI installs with --frozen-lockfile):

pnpm install     # install per pnpm-lock.yaml
pnpm run build   # clean lib → tsc -b (types + declarations) → tsdown (both halves)
pnpm run verify  # simulate the host module table to check lib/client.js (optional)
pnpm publish     # or pnpm pack / git push origin main (lib/ is committed; git installs need no build)

Automated publishing (GitHub Actions)

Pushing a v* tag (pnpm run release bumps the patch version, rebuilds the artifact, and tags it automatically) triggers .github/workflows/publish.yml:

• release job: Setup Node 26 → pnpm install --frozen-lockfile → pnpm run check (tsc -b) → pnpm run build (tsc -b && tsdown) → pnpm pack → creates a GitHub Release (auto-generated changelog, tarball attached);
• publish-npm job: publishes to npm — requires the NPM_TOKEN repository secret (Settings → Secrets and variables → Actions); fails fast with a hint when it is missing.

Development

Requirements: Node ≥ 26 + pnpm 10 (the packageManager field in package.json pins the pnpm version).

pnpm install           # devDependencies: typescript, tsdown, @types/react, @deepseek-ai/* type packages, etc.
pnpm run check         # whole-tree TypeScript type check (tsc -b)
pnpm run build         # rebuild both halves after editing source (tsc -b && tsdown)
pnpm run watch         # tsdown watch mode (rebuild on src/client changes)
pnpm run verify        # simulate the host seed table to check lib/client.js loads

• Host half lives in src/host/; browser half in src/client/ (build entry src/client/index.ts, exporting { name, inject, apply } directly);
• The window.__ModuleLoader__.load factory wrapper of lib/client.js is generated by tsdown's banner/intro/footer options (no hand-written wrap script);
• External dependencies in the artifact (react, @deepseek-ai/dsh-client-ui-primitives, ...) stay external and resolve from the host module table (seed) at runtime.

Implementation notes

• Jenkins REST via curl.exe through the host shell service: Basic auth + CSRF crumb
  • --data-binary @- (form body over stdin, UTF-8 without BOM); -D - parses status and the Location header.
• Browser ↔ host transport: ctx.remote.commands.execute(sessionId, '/dsh-jenkins <json>'), host errors carry a code that the client localizes (fallback to the raw message).
• Peer dependencies (@deepseek-ai/cordis, dsh-tools, schemastery, dsh-settings, dsh-commands, dsh-session, dsh-api-remotes, client runtime/ui-slots/ui-settings/ cordis-client-runner, react) are resolved by the host at install time.
• The official deepseek-harness project is not modified; all features use existing slots (sidebar.footer.action, settings.section, shell.overlay) and the command transport.