@lolkda/dsh-chrome-devtools-mcp 0.0.0-stage → 0.3.0

package/lib/state.js

@@ -0,0 +1,132 @@
+/**
+ * Persistent plugin state.
+ *
+ * The launcher and the Host half share one small JSON contract. Everything the
+ * browser can change lives here; the profile patch stays static and owns the
+ * entry id only.
+ */
+
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export const DEFAULT_STATE = Object.freeze({ mode: 'latest', version: null })
+
+/** A version is a plain release SemVer without a `v` prefix. */
+export const VERSION_PATTERN = /^\d+\.\d+\.\d+$/
+
+/** Resolve the DSH home the same way the Host does, with an explicit override for tests. */
+export function resolveDshHome(env = process.env) {
+  const configured = typeof env.DSH_HOME === 'string' ? env.DSH_HOME.trim() : ''
+  return configured || join(homedir(), '.dsh')
+}
+
+/** The single directory this plugin owns under DSH_HOME. */
+export function stateDir(dshHome = resolveDshHome()) {
+  return join(dshHome, 'dsh-chrome-devtools-mcp')
+}
+
+export function filePaths(dshHome = resolveDshHome()) {
+  const dir = stateDir(dshHome)
+  return {
+    dir,
+    state: join(dir, 'state.json'),
+    runtime: join(dir, 'runtime.json'),
+    cache: join(dir, 'releases-cache.json'),
+  }
+}
+
+/** A selection is valid only when it is `latest` or a plain release version. */
+export function normalizeSelection(value) {
+  if (!value || typeof value !== 'object') throw new Error('版本选择必须是对象')
+  if (value.mode === 'latest') return { mode: 'latest', version: null }
+  if (value.mode === 'pinned') {
+    if (typeof value.version !== 'string' || !VERSION_PATTERN.test(value.version)) {
+      throw new Error('固定版本必须是 x.y.z 形式')
+    }
+    return { mode: 'pinned', version: value.version }
+  }
+  throw new Error('模式必须是 latest 或 pinned')
+}
+
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return undefined
+    throw error
+  }
+}
+
+async function writeJsonAtomic(path, value) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 })
+  await rename(temporary, path)
+  await chmod(path, 0o600).catch(() => {})
+}
+
+/** Read the selected version, falling back to `latest` for a missing or malformed file. */
+export async function readState(dshHome) {
+  const paths = filePaths(dshHome)
+  let raw
+  try {
+    raw = await readJson(paths.state)
+  } catch (error) {
+    return { ...DEFAULT_STATE, warning: `读取状态失败：${error.message}` }
+  }
+  if (raw === undefined) return { ...DEFAULT_STATE }
+  try {
+    return normalizeSelection(raw)
+  } catch (error) {
+    return { ...DEFAULT_STATE, warning: `状态文件无效：${error.message}` }
+  }
+}
+
+/** Validate, then write the selection. Invalid input never touches the existing file. */
+export async function writeState(dshHome, selection) {
+  const normalized = normalizeSelection(selection)
+  await writeJsonAtomic(filePaths(dshHome).state, {
+    ...normalized,
+    updatedAt: new Date().toISOString(),
+  })
+  return normalized
+}
+
+/** Read the launcher's runtime record. Missing or malformed records simply mean "unknown". */
+export async function readRuntime(dshHome) {
+  const paths = filePaths(dshHome)
+  try {
+    const raw = await readJson(paths.runtime)
+    if (!raw || typeof raw !== 'object') return undefined
+    const pid = Number(raw.pid)
+    if (!Number.isSafeInteger(pid) || pid <= 0) return undefined
+    return {
+      pid,
+      spec: typeof raw.spec === 'string' ? raw.spec : undefined,
+      startedAt: typeof raw.startedAt === 'string' ? raw.startedAt : undefined,
+      endedAt: typeof raw.endedAt === 'string' ? raw.endedAt : undefined,
+      exitCode: Number.isInteger(raw.exitCode) ? raw.exitCode : undefined,
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/** The launcher writes this before it spawns npx, and again when the child exits. */
+export async function writeRuntime(dshHome, runtime) {
+  await writeJsonAtomic(filePaths(dshHome).runtime, runtime)
+}
+
+export async function readReleasesCache(dshHome) {
+  const paths = filePaths(dshHome)
+  try {
+    return await readJson(paths.cache)
+  } catch {
+    return undefined
+  }
+}
+
+export async function writeReleasesCache(dshHome, cache) {
+  await writeJsonAtomic(filePaths(dshHome).cache, cache)
+}

package/lib/status.js

@@ -0,0 +1,77 @@
+/**
+ * Runtime status inference.
+ *
+ * mcp-client owns the child process and exposes no status RPC, so the launcher
+ * leaves a PID record and the Host combines it with a direct CDP probe.
+ */
+
+import { readRuntime, readState } from './state.js'
+
+export const DEFAULT_BROWSER_URL = 'http://127.0.0.1:9222'
+
+export function normalizeBrowserUrl(value) {
+  if (typeof value !== 'string' || value.trim() === '') return DEFAULT_BROWSER_URL
+  const trimmed = value.trim().replace(/\/+$/, '')
+  return /^https?:\/\/[^\s]+$/i.test(trimmed) ? trimmed : DEFAULT_BROWSER_URL
+}
+
+/** `EPERM` still means the process exists but belongs to someone else. */
+export function isPidAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return Boolean(error && error.code === 'EPERM')
+  }
+}
+
+export async function checkCdp(browserUrl = DEFAULT_BROWSER_URL, { fetchImpl = fetch, timeoutMs = 1500 } = {}) {
+  const endpoint = `${normalizeBrowserUrl(browserUrl)}/json/version`
+  try {
+    const response = await fetchImpl(endpoint, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (!response.ok) {
+      return { reachable: false, endpoint, error: `HTTP ${response.status}` }
+    }
+    const body = await response.json().catch(() => null)
+    if (!body || typeof body !== 'object') {
+      return { reachable: false, endpoint, error: '响应不是 JSON 对象' }
+    }
+    return {
+      reachable: true,
+      endpoint,
+      browser: typeof body.Browser === 'string' ? body.Browser : null,
+      protocolVersion: typeof body['Protocol-Version'] === 'string' ? body['Protocol-Version'] : null,
+    }
+  } catch (error) {
+    const message = error && error.name === 'TimeoutError' ? '连接超时' : String(error?.message ?? error)
+    return { reachable: false, endpoint, error: message }
+  }
+}
+
+export async function getStatus({ dshHome, browserUrl = DEFAULT_BROWSER_URL, fetchImpl = fetch, timeoutMs = 1500 } = {}) {
+  const [configured, runtime] = await Promise.all([readState(dshHome), readRuntime(dshHome)])
+  const alive = runtime ? isPidAlive(runtime.pid) : false
+  const running = runtime
+    ? {
+        state: alive ? 'running' : 'stopped',
+        pid: runtime.pid,
+        spec: runtime.spec ?? null,
+        startedAt: runtime.startedAt ?? null,
+        endedAt: runtime.endedAt ?? null,
+        exitCode: runtime.exitCode ?? null,
+        ...(alive ? {} : { reason: 'launcher 进程已退出' }),
+      }
+    : { state: 'unknown', reason: '暂无启动记录' }
+
+  return {
+    configured: { mode: configured.mode, version: configured.version },
+    ...(configured.warning ? { configuredWarning: configured.warning } : {}),
+    running,
+    cdp: await checkCdp(browserUrl, { fetchImpl, timeoutMs }),
+    browserUrl: normalizeBrowserUrl(browserUrl),
+  }
+}

package/lib/tunnel.js

@@ -0,0 +1,86 @@
+/** Commands shown by the settings page. They are generated, never executed. */
+
+import { networkInterfaces } from 'node:os'
+
+export const DEFAULT_SSH_PORT = 22
+export const DEFAULT_CDP_PORT = 9222
+
+/** The first non-loopback IPv4 address, used when the browser is opened on localhost. */
+export function defaultHost() {
+  const interfaces = networkInterfaces()
+  for (const entries of Object.values(interfaces)) {
+    for (const entry of entries ?? []) {
+      const family = entry.family === 4 || entry.family === 'IPv4'
+      if (family && !entry.internal && entry.address) return entry.address
+    }
+  }
+  return '127.0.0.1'
+}
+
+function cleanToken(value, label) {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (!text || /[\s"'`$\\]/.test(text)) throw new Error(`${label}包含不允许的字符`)
+  return text
+}
+
+export function buildSshCommand({
+  host,
+  user = '<user>',
+  sshPort = DEFAULT_SSH_PORT,
+  remotePort = DEFAULT_CDP_PORT,
+  localPort = DEFAULT_CDP_PORT,
+} = {}) {
+  const target = cleanToken(host, '主机地址')
+  const account = cleanToken(user, 'SSH 用户名')
+  const port = Number(sshPort)
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('SSH 端口无效')
+  const remote = Number(remotePort)
+  const local = Number(localPort)
+  if (!Number.isInteger(remote) || remote < 1 || remote > 65535 || !Number.isInteger(local) || local < 1 || local > 65535) {
+    throw new Error('转发端口无效')
+  }
+  const portArgument = port === DEFAULT_SSH_PORT ? '' : ` -p ${port}`
+  return `ssh -N -o ServerAliveInterval=30 -o ExitOnForwardFailure=yes${portArgument} -R ${remote}:127.0.0.1:${local} ${account}@${target}`
+}
+
+export const WINDOWS_OPENSSH_CLIENT = Object.freeze([
+  {
+    label: '检查 OpenSSH Client',
+    command: "Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH.Client*'",
+  },
+  {
+    label: '安装 OpenSSH Client',
+    command: 'Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0',
+  },
+])
+
+export const WINDOWS_OPENSSH_SERVER = Object.freeze([
+  {
+    label: '检查 OpenSSH Server',
+    command: "Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH.Server*'",
+  },
+  {
+    label: '安装 OpenSSH Server',
+    command: 'Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0',
+  },
+  {
+    label: '启动并设为开机自启',
+    command: 'Start-Service sshd\nSet-Service -Name sshd -StartupType Automatic',
+  },
+  {
+    label: '放行 22 端口',
+    command: "New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server (sshd)' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22",
+  },
+])
+
+export function tunnelInfo({ host = defaultHost(), sshPort = DEFAULT_SSH_PORT, remotePort = DEFAULT_CDP_PORT, localPort = DEFAULT_CDP_PORT } = {}) {
+  return {
+    host,
+    sshPort,
+    remotePort,
+    localPort,
+    commandTemplate: buildSshCommand({ host, user: '<user>', sshPort, remotePort, localPort }),
+    windowsClient: WINDOWS_OPENSSH_CLIENT,
+    windowsServer: WINDOWS_OPENSSH_SERVER,
+  }
+}

package/lib/versions.js

@@ -0,0 +1,190 @@
+/**
+ * Upstream release discovery.
+ *
+ * GitHub Releases are the user-facing source of truth; the npm registry is the
+ * fallback because that is what `npx` will actually resolve. Both are cached so
+ * a rate-limited GitHub API never leaves the settings page blank.
+ */
+
+import { readReleasesCache, writeReleasesCache } from './state.js'
+
+export const GITHUB_REPO = 'ChromeDevTools/chrome-devtools-mcp'
+export const GITHUB_RELEASES_URL = `https://api.github.com/repos/${GITHUB_REPO}/releases?per_page=40`
+export const NPM_PACKUMENT_URL = 'https://registry.npmjs.org/chrome-devtools-mcp'
+export const RELEASE_URL_PREFIX = `https://github.com/${GITHUB_REPO}/releases/tag`
+export const CACHE_TTL_MS = 10 * 60 * 1000
+const USER_AGENT = 'dsh-chrome-devtools-mcp/0.3.0'
+
+export function parseVersion(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(value))
+  if (!match) return undefined
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) }
+}
+
+export function compareVersions(left, right) {
+  const a = parseVersion(left)
+  const b = parseVersion(right)
+  if (!a || !b) return 0
+  if (a.major !== b.major) return a.major - b.major
+  if (a.minor !== b.minor) return a.minor - b.minor
+  return a.patch - b.patch
+}
+
+/** Strip a leading `v` or the project's release prefix and split a SemVer tag. */
+export function normalizeTag(value) {
+  if (typeof value !== 'string') return undefined
+  const tag = value.trim()
+  const match = /^(?:chrome-devtools-mcp-)?v?(\d+\.\d+\.\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(tag)
+  if (!match) return undefined
+  return {
+    version: match[1],
+    tag,
+    prerelease: match[2] !== undefined,
+  }
+}
+
+export function sortVersionsDescending(items) {
+  return [...items].sort((left, right) => compareVersions(right.version, left.version))
+}
+
+export function fromGithubReleases(releases) {
+  if (!Array.isArray(releases)) throw new Error('GitHub Releases 响应格式错误')
+  const byVersion = new Map()
+  let prereleaseCount = 0
+  for (const release of releases) {
+    if (!release || release.draft === true) continue
+    const parsed = normalizeTag(release.tag_name)
+    if (!parsed) continue
+    if (parsed.prerelease || release.prerelease === true) {
+      prereleaseCount += 1
+      continue
+    }
+    const item = {
+      version: parsed.version,
+      tag: parsed.tag,
+      url: typeof release.html_url === 'string' ? release.html_url : `${RELEASE_URL_PREFIX}/${parsed.tag}`,
+      publishedAt: typeof release.published_at === 'string' ? release.published_at : null,
+      prerelease: false,
+    }
+    const previous = byVersion.get(item.version)
+    if (!previous || String(item.publishedAt ?? '') > String(previous.publishedAt ?? '')) byVersion.set(item.version, item)
+  }
+  return { items: sortVersionsDescending([...byVersion.values()]), prereleaseCount }
+}
+
+export function fromNpmPackument(packument) {
+  if (!packument || typeof packument !== 'object' || !packument.versions) {
+    throw new Error('npm 版本列表响应格式错误')
+  }
+  const times = packument.time && typeof packument.time === 'object' ? packument.time : {}
+  const items = []
+  for (const [version, metadata] of Object.entries(packument.versions)) {
+    if (!parseVersion(version)) continue
+    if (metadata && metadata.deprecated) continue
+    items.push({
+      version,
+      tag: `v${version}`,
+      url: `${RELEASE_URL_PREFIX}/v${version}`,
+      publishedAt: typeof times[version] === 'string' ? times[version] : null,
+      prerelease: false,
+    })
+  }
+  return { items: sortVersionsDescending(items), prereleaseCount: 0 }
+}
+
+async function fetchJson(url, { fetchImpl = fetch, timeoutMs = 6000 } = {}) {
+  const response = await fetchImpl(url, {
+    headers: {
+      accept: 'application/vnd.github+json, application/json',
+      'user-agent': USER_AGENT,
+    },
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  if (!response.ok) throw new Error(`GET ${url} 失败：HTTP ${response.status}`)
+  return response.json()
+}
+
+export async function fetchGithubVersions(options = {}) {
+  const releases = await fetchJson(GITHUB_RELEASES_URL, options)
+  return fromGithubReleases(releases)
+}
+
+export async function fetchNpmVersions(options = {}) {
+  const packument = await fetchJson(NPM_PACKUMENT_URL, options)
+  return fromNpmPackument(packument)
+}
+
+function responseOf(source, result, fetchedAt, cached, warning) {
+  return {
+    source,
+    cached,
+    fetchedAt,
+    latest: result.items[0]?.version ?? null,
+    items: result.items,
+    prereleaseCount: result.prereleaseCount ?? 0,
+    ...(warning ? { warning } : {}),
+  }
+}
+
+/**
+ * Resolve the version list, preferring a fresh cache, then GitHub, then npm.
+ * A stale cache is still better than an empty selector when both networks fail.
+ */
+export async function loadVersions({ dshHome, refresh = false, fetchImpl = fetch, now = Date.now() } = {}) {
+  const stored = await readReleasesCache(dshHome)
+  const cache = stored && Array.isArray(stored.items) && stored.items.length > 0 ? stored : undefined
+  const cachedAt = cache && typeof cache.fetchedAt === 'string' ? Date.parse(cache.fetchedAt) : NaN
+  const fresh = Number.isFinite(cachedAt) && now - cachedAt < CACHE_TTL_MS
+  if (!refresh && fresh && cache) {
+    return {
+      ...responseOf('cache', { items: cache.items, prereleaseCount: cache.prereleaseCount }, cache.fetchedAt, true, undefined),
+      upstreamSource: cache.source,
+    }
+  }
+
+  let warning
+  let result
+  let source
+  try {
+    result = await fetchGithubVersions({ fetchImpl, timeoutMs: 6000 })
+    if (result.items.length === 0) throw new Error('GitHub Releases 中没有可识别的稳定版本')
+    source = 'github'
+  } catch (githubError) {
+    warning = `GitHub 版本列表不可用：${githubError.message}`
+    try {
+      result = await fetchNpmVersions({ fetchImpl, timeoutMs: 8000 })
+      source = 'npm'
+    } catch (npmError) {
+      if (cache) {
+        return {
+          ...responseOf('cache', { items: cache.items, prereleaseCount: cache.prereleaseCount }, cache.fetchedAt ?? null, true, `${warning}；npm 回退也失败：${npmError.message}；使用缓存`),
+          upstreamSource: cache.source,
+        }
+      }
+      throw new Error(`${warning}；npm 回退也失败：${npmError.message}`)
+    }
+  }
+
+  const fetchedAt = new Date(now).toISOString()
+  const payload = responseOf(source, result, fetchedAt, false, warning)
+  await writeReleasesCache(dshHome, { ...payload, source }).catch(() => {})
+  return payload
+}
+
+/** Verify an uncached manual version against npm before writing it. */
+export async function assertVersionExists(version, { fetchImpl = fetch, knownVersions = [], timeoutMs = 5000 } = {}) {
+  if (!parseVersion(version)) throw new Error('版本必须是 x.y.z 形式')
+  if (knownVersions.includes(version)) return
+  const response = await fetchImpl(`${NPM_PACKUMENT_URL}/${encodeURIComponent(version)}`, {
+    headers: { accept: 'application/json', 'user-agent': USER_AGENT },
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  if (response.status === 404) throw new Error(`版本 ${version} 不存在于 npm`)
+  if (!response.ok) throw new Error(`无法验证版本 ${version}：HTTP ${response.status}`)
+}
+
+/** The stable versions from the last cache, used when a manual version is saved. */
+export async function cachedVersionNames(dshHome) {
+  const cache = await readReleasesCache(dshHome)
+  return Array.isArray(cache?.items) ? cache.items.map((item) => item.version).filter((version) => parseVersion(version)) : []
+}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@lolkda/dsh-chrome-devtools-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Chrome DevTools MCP bundle and settings page for DeepSeek Harness",
+  "license": "MIT",
+  "author": "lolkda",
+  "type": "module",
+  "main": "lib/index.js",
+  "homepage": "https://github.com/lolkda/dsh-chrome-devtools-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lolkda/dsh-chrome-devtools-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lolkda/dsh-chrome-devtools-mcp/issues"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "chrome-devtools",
+    "mcp",
+    "browser",
+    "cdp"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "files": [
+    "lib",
+    "client",
+    "bin",
+    "docs",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./client/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    },
+    "compatibility": {
+      "dsh": ">=0.2.1-rc.2 <0.3.0",
+      "profiles": [
+        "web"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=22",
+    "dsh": ">=0.2.1-rc.2 <0.3.0"
+  },
+  "scripts": {
+    "test": "node --check client/client.js && node --test test/*.test.mjs",
+    "pack:check": "npm pack --dry-run",
+    "verify": "npm test && npm run pack:check",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "yaml": "^2.9.1"
+  },
+  "chromeDevtoolsMcp": {
+    "channel": "latest",
+    "source": "https://github.com/ChromeDevTools/chrome-devtools-mcp"
+  }
+}