@boyingliu01/xp-gate 0.18.4 → 0.19.0

package/plugins/dsh/src/command.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest"
+import {
+  FALLBACK_MESSAGE,
+  GATE_WHITELIST,
+  buildCommand,
+  isGateAllowed,
+  resolveTarget,
+  shq,
+} from "./command.js"
+
+describe("shq (POSIX single-quote escaping)", () => {
+  it("wraps a plain value in single quotes", () => {
+    expect(shq("abc")).toBe("'abc'")
+  })
+
+  it("escapes embedded single quotes with the quote-close idiom", () => {
+    expect(shq("a'b")).toBe("'a'\\''b'")
+  })
+
+  /**
+   * @test REQ-DSH-009
+   * @intent 验证 shq() 对命令替换/反引号等 shell 元字符做 POSIX 单引号转义，防止命令注入
+   * @covers AC-DSH-009-01
+   */
+  it("neutralizes shell metacharacters by quoting them literally", () => {
+    const payload = "$(touch /tmp/pwned); `id`"
+    expect(shq(payload)).toBe("'$(touch /tmp/pwned); `id`'")
+  })
+})
+
+describe("isGateAllowed (enum whitelist)", () => {
+  it("accepts whitelisted gate ids", () => {
+    expect(isGateAllowed("principles")).toBe(true)
+    expect(isGateAllowed("arch")).toBe(true)
+    expect(isGateAllowed("duplicates")).toBe(true)
+  })
+
+  it("rejects unknown or injected gate ids", () => {
+    expect(isGateAllowed("$(rm -rf)")).toBe(false)
+    expect(isGateAllowed("0")).toBe(false)
+    expect(isGateAllowed("")).toBe(false)
+  })
+})
+
+describe("buildCommand", () => {
+  it("builds a guarded gate-check command with target + gates", () => {
+    const cmd = buildCommand({ subcommand: "check", target: "src", gates: ["principles", "arch"] })
+    expect(cmd).toContain("command -v xp-gate")
+    expect(cmd).toContain("xp-gate check 'src' --gates 'principles,arch'")
+    expect(cmd).toContain(shq(FALLBACK_MESSAGE))
+  })
+
+  it("drops non-whitelisted gates before building the command", () => {
+    const cmd = buildCommand({ subcommand: "check", target: "src", gates: ["principles", "bogus$(id)"] })
+    expect(cmd).toContain("xp-gate check 'src' --gates 'principles'")
+    expect(cmd).not.toContain("bogus")
+  })
+
+  it("escapes a hostile target path", () => {
+    const cmd = buildCommand({ subcommand: "check", target: "a'b$(id)" })
+    expect(cmd).toContain("xp-gate check 'a'\\''b$(id)'")
+  })
+
+  it("builds gate-principles", () => {
+    expect(buildCommand({ subcommand: "principles", target: "src/x.ts" })).toContain(
+      "xp-gate principles 'src/x.ts'",
+    )
+  })
+
+  it("builds gate-arch with the default config", () => {
+    expect(buildCommand({ subcommand: "arch" })).toContain("xp-gate arch --config 'architecture.yaml'")
+  })
+
+  /**
+   * @test REQ-DSH-005
+   * @intent 验证 xp-gate CLI 缺失时 buildCommand 走 else 分支输出优雅降级安装提示，而非抛错或返回门禁失败
+   * @covers AC-DSH-005-01
+   */
+  it("emits the graceful-degradation fallback when xp-gate is absent", () => {
+    const cmd = buildCommand({ subcommand: "check", target: "src" })
+    expect(cmd).toContain("else printf")
+    expect(cmd).toContain(FALLBACK_MESSAGE)
+  })
+})
+
+describe("resolveTarget", () => {
+  it("keeps absolute paths unchanged", () => {
+    expect(resolveTarget("/tmp/x", "/workspace")).toBe("/tmp/x")
+  })
+
+  it("resolves relative paths against the session cwd", () => {
+    expect(resolveTarget("src", "/workspace")).toBe("/workspace/src")
+  })
+})
+
+describe("GATE_WHITELIST", () => {
+  it("contains only known xp-gate gate aliases", () => {
+    expect(GATE_WHITELIST).toContain("principles")
+    expect(GATE_WHITELIST).toContain("arch")
+    expect(GATE_WHITELIST).toContain("secrets")
+  })
+})

package/plugins/dsh/src/command.ts

@@ -0,0 +1,75 @@
+import { isAbsolute, resolve } from "node:path"
+
+/** Shown when the global `xp-gate` CLI is not on PATH. */
+export const FALLBACK_MESSAGE =
+  "[XP-Gate] xp-gate CLI not installed. Install it with: npm install -g @boyingliu01/xp-gate"
+
+/**
+ * Allowlist of xp-gate gate aliases that are safe to invoke standalone
+ * (non-preCommitOnly gates + common aliases). Anything outside this set is
+ * rejected before reaching the shell.
+ */
+export const GATE_WHITELIST = [
+  "duplicates",
+  "complexity",
+  "principles",
+  "arch",
+  "architecture",
+  "iac",
+  "secrets",
+  "sast",
+] as const
+
+export type GateId = (typeof GATE_WHITELIST)[number]
+
+/** POSIX single-quote shell escaping: `'` becomes `'\''`. */
+export function shq(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`
+}
+
+export function isGateAllowed(gate: string): boolean {
+  return (GATE_WHITELIST as readonly string[]).includes(gate)
+}
+
+export interface BuildCommandOptions {
+  subcommand: "check" | "principles" | "arch"
+  target?: string
+  gates?: readonly string[]
+  config?: string
+}
+
+function buildInner(options: BuildCommandOptions): string {
+  const { subcommand, target, gates, config } = options
+  if (subcommand === "check") {
+    const tokens = ["xp-gate", "check"]
+    if (target !== undefined) tokens.push(shq(target))
+    if (gates !== undefined && gates.length > 0) {
+      // Defense-in-depth: the JSON-schema enum already rejects unknown gate ids,
+      // but we also whitelist here so a non-whitelisted value can never reach the shell.
+      const allowed = gates.filter(isGateAllowed)
+      if (allowed.length > 0) tokens.push("--gates", shq(allowed.join(",")))
+    }
+    return tokens.join(" ")
+  }
+  if (subcommand === "principles") {
+    const tokens = ["xp-gate", "principles"]
+    if (target !== undefined) tokens.push(shq(target))
+    return tokens.join(" ")
+  }
+  return ["xp-gate", "arch", "--config", shq(config ?? "architecture.yaml")].join(" ")
+}
+
+/**
+ * Build a single guarded shell command: runs `xp-gate …` when the global CLI
+ * is present, otherwise prints the graceful-degradation hint. A single
+ * `if command -v` avoids a separate probe/run race.
+ */
+export function buildCommand(options: BuildCommandOptions): string {
+  const inner = buildInner(options)
+  return `if command -v xp-gate >/dev/null 2>&1; then ${inner}; else printf '%s\\n' ${shq(FALLBACK_MESSAGE)}; fi`
+}
+
+/** Resolve a model-supplied path against the session cwd; absolutes pass through. */
+export function resolveTarget(rawPath: string, cwd: string): string {
+  return isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath)
+}

package/plugins/dsh/src/contract.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest"
+import { readFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const PKG_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)))
+
+interface PkgShape {
+  main?: string
+  files?: string[]
+  scripts?: { prepack?: string }
+  publishConfig?: { access?: string }
+  dsh?: { bundle?: { patch?: string } }
+}
+
+function readPkg(): PkgShape {
+  return JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")) as PkgShape
+}
+
+describe("packaging contract", () => {
+  /**
+   * @test REQ-DSH-001
+   * @intent 验证 package.json 声明 dsh.bundle.patch 且 cordis.patch.yml 插入 id=tool-xp-gate + 包名
+   * @covers AC-DSH-001-01
+   */
+  it("declares dsh.bundle.patch and a cordis patch entry", () => {
+    expect(readPkg().dsh?.bundle?.patch).toBe("./cordis.patch.yml")
+    const patch = readFileSync(join(PKG_ROOT, "cordis.patch.yml"), "utf8")
+    expect(patch).toContain("id: tool-xp-gate")
+    expect(patch).toContain("@boyingliu01/dsh-plugin-xp-gate")
+  })
+
+  /**
+   * @test REQ-DSH-010
+   * @intent 验证打包契约：main/exports 指向 lib/index.js，files 白名单，prepack 构建，publishConfig.access=public
+   * @covers AC-DSH-010-01
+   */
+  it("satisfies the npm packaging contract", () => {
+    const pkg = readPkg()
+    expect(pkg.main).toBe("./lib/index.js")
+    expect(pkg.files).toContain("lib/")
+    expect(pkg.files).toContain("cordis.patch.yml")
+    expect(pkg.files).toContain("skills/")
+    expect(pkg.scripts?.prepack).toContain("npm run build")
+    expect(pkg.publishConfig?.access).toBe("public")
+  })
+
+  /**
+   * @test REQ-DSH-008
+   * @intent 验证 TDD 契约：所有测试文件携带 @test/@intent/@covers 注解，覆盖三工具 + fallback + 取消/超时 + shq 转义
+   * @covers AC-DSH-008-01
+   */
+  it("every test file carries @test/@intent/@covers annotations", () => {
+    const files = ["command.test.ts", "gate-runner.test.ts", "index.test.ts", "skills.test.ts"]
+    for (const f of files) {
+      const content = readFileSync(join(PKG_ROOT, "src", f), "utf8")
+      expect(content, `${f}: @test`).toMatch(/@test\s+REQ-\S+/)
+      expect(content, `${f}: @intent`).toMatch(/@intent\s+/)
+      expect(content, `${f}: @covers`).toMatch(/@covers\s+AC-\S+/)
+    }
+  })
+})

package/plugins/dsh/src/gate-runner.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from "vitest"
+import type { ShellExecRequest, ShellRunResult } from "@deepseek-ai/dsh-shell"
+import { renderGateResult, runXpGate, type XpGateShell } from "./gate-runner.js"
+
+function result(over: Partial<ShellRunResult> = {}): ShellRunResult {
+  return {
+    exitCode: 0,
+    signal: null,
+    timedOut: false,
+    aborted: false,
+    timeoutMs: 1000,
+    stdout: { text: "ok", truncated: false },
+    stderr: { text: "", truncated: false },
+    ...over,
+  }
+}
+
+function makeShell(finalResult: ShellRunResult): { shell: XpGateShell; requests: ShellExecRequest[] } {
+  const requests: ShellExecRequest[] = []
+  const shell: XpGateShell = {
+    resolve(req) {
+      requests.push(req)
+      return {
+        command: req.command,
+        workdir: req.workdir ?? "/workspace",
+        timeoutMs: req.timeoutMs ?? 1000,
+        stdoutMaxBytes: 1_000_000,
+        signal: req.signal,
+        sandboxPolicy: undefined,
+      }
+    },
+    run() {
+      return Promise.resolve(finalResult)
+    },
+  }
+  return { shell, requests }
+}
+
+describe("renderGateResult", () => {
+  it("renders stdout text", () => {
+    expect(renderGateResult(result())).toBe("ok")
+  })
+
+  it("appends [exit code: N] on non-zero exit", () => {
+    const r = renderGateResult(result({ exitCode: 2, stdout: { text: "boom", truncated: false } }))
+    expect(r).toContain("boom")
+    expect(r).toContain("[exit code: 2]")
+  })
+
+  it("marks a timeout without throwing", () => {
+    const r = renderGateResult(result({ timedOut: true, exitCode: null, stdout: { text: "", truncated: false } }))
+    expect(r).toContain("[timed out after 1000ms]")
+  })
+
+  it("marks a sandbox denial", () => {
+    const r = renderGateResult(result({ sandbox: { mode: "workspace-write", denied: true } }))
+    expect(r).toContain("denied")
+  })
+
+  it("includes stderr and truncation markers", () => {
+    const r = renderGateResult(
+      result({
+        stderr: { text: "err", truncated: false },
+        stdout: { text: "tail", truncated: true, spillPath: "/tmp/full" },
+      }),
+    )
+    expect(r).toContain("err")
+    expect(r).toContain("truncated")
+  })
+})
+
+describe("runXpGate", () => {
+  it("passes command/workdir/timeoutMs/signal to the shell", async () => {
+    const signal = new AbortController().signal
+    const { shell, requests } = makeShell(result())
+    await runXpGate(shell, signal, "xp-gate check 'src'", "/workspace", 5000)
+    expect(requests[0]?.command).toBe("xp-gate check 'src'")
+    expect(requests[0]?.workdir).toBe("/workspace")
+    expect(requests[0]?.timeoutMs).toBe(5000)
+    expect(requests[0]?.signal).toBe(signal)
+  })
+
+  /**
+   * @test REQ-DSH-007
+   * @intent 验证取消与超时分离：result.aborted 抛 code=ABORTED 的 AbortError（不悬挂），result.timedOut 仅渲染标记不抛错
+   * @covers AC-DSH-007-01
+   */
+  it("throws an AbortError (code ABORTED) only on cancellation, not on timeout", async () => {
+    const { shell } = makeShell(result({ aborted: true, exitCode: null }))
+    await expect(runXpGate(shell, new AbortController().signal, "cmd", "/w", 1000)).rejects.toMatchObject({
+      name: "AbortError",
+      code: "ABORTED",
+    })
+    // timeout resolves (render marker) rather than throwing
+    const timeoutShell = makeShell(result({ timedOut: true, exitCode: null, stdout: { text: "", truncated: false } })).shell
+    await expect(runXpGate(timeoutShell, new AbortController().signal, "cmd", "/w", 1000)).resolves.toContain(
+      "[timed out after 1000ms]",
+    )
+  })
+})

package/plugins/dsh/src/gate-runner.ts

@@ -0,0 +1,58 @@
+import { TOOL_ABORTED } from "@deepseek-ai/dsh-tools"
+import { HarnessError } from "@deepseek-ai/dsh-llm"
+import type { ShellExecRequest, ShellExecSpec, ShellRunResult } from "@deepseek-ai/dsh-shell"
+
+/**
+ * Structural view of `ctx.shell` so the runner is testable with a fake shell
+ * without importing the abstract `ShellExecutor` service.
+ */
+export interface XpGateShell {
+  resolve(request: ShellExecRequest): ShellExecSpec
+  run(spec: ShellExecSpec): Promise<ShellRunResult>
+}
+
+/** Render a completed shell run as a single model-facing text block. */
+export function renderGateResult(result: ShellRunResult): string {
+  const lines: string[] = []
+  const stdout = result.stdout.text.trim()
+  if (stdout.length > 0) lines.push(stdout)
+  const stderr = result.stderr.text.trim()
+  if (stderr.length > 0) lines.push(`[stderr] ${stderr}`)
+  if (result.timedOut) lines.push(`[timed out after ${result.timeoutMs}ms]`)
+  if (result.exitCode !== null && result.exitCode !== 0) lines.push(`[exit code: ${result.exitCode}]`)
+  if (result.signal !== null) lines.push(`[signal: ${result.signal}]`)
+  if (result.sandbox?.denied === true) {
+    lines.push(`[sandbox: file access denied under ${result.sandbox.mode} mode]`)
+  }
+  if (result.stdout.truncated) {
+    const spill = result.stdout.spillPath !== undefined ? `, full output: ${result.stdout.spillPath}` : ""
+    lines.push(`[stdout truncated${spill}]`)
+  }
+  if (result.stderr.truncated) {
+    const spill = result.stderr.spillPath !== undefined ? `, full output: ${result.stderr.spillPath}` : ""
+    lines.push(`[stderr truncated${spill}]`)
+  }
+  return lines.length > 0 ? lines.join("\n") : "[XP-Gate] command completed (no output)."
+}
+
+/**
+ * Run an xp-gate command through the harness shell seam. Nonzero exits, timeouts,
+ * and sandbox denials resolve (and render) rather than reject; only cancellation
+ * (the caller's AbortSignal fired first) throws an AbortError with code ABORTED.
+ */
+export async function runXpGate(
+  shell: XpGateShell,
+  signal: AbortSignal,
+  command: string,
+  workdir: string,
+  timeoutMs: number,
+): Promise<string> {
+  const spec = shell.resolve({ command, workdir, timeoutMs, signal })
+  const result = await shell.run(spec)
+  if (result.aborted) {
+    const error = new HarnessError("tool call aborted", TOOL_ABORTED)
+    error.name = "AbortError"
+    throw error
+  }
+  return renderGateResult(result)
+}

package/plugins/dsh/src/index.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "vitest"
+import type { Context } from "@deepseek-ai/cordis"
+import type { ShellExecRequest, ShellExecSpec, ShellRunResult } from "@deepseek-ai/dsh-shell"
+import { apply } from "./index.js"
+
+interface CapturedTool {
+  name: string
+  execute: (args: unknown, exec: unknown) => Promise<unknown>
+}
+
+function makeCtx(stdoutText: string) {
+  const captured: unknown[] = []
+  const requests: ShellExecRequest[] = []
+  const shell = {
+    resolve(req: ShellExecRequest): ShellExecSpec {
+      requests.push(req)
+      return {
+        command: req.command,
+        workdir: req.workdir ?? "/workspace",
+        timeoutMs: req.timeoutMs ?? 1000,
+        stdoutMaxBytes: 1_000_000,
+        signal: req.signal,
+        sandboxPolicy: undefined,
+      }
+    },
+    run(): Promise<ShellRunResult> {
+      return Promise.resolve({
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        aborted: false,
+        timeoutMs: 1000,
+        stdout: { text: stdoutText, truncated: false },
+        stderr: { text: "", truncated: false },
+      })
+    },
+  }
+  const ctx = { tools: { register: (def: unknown) => captured.push(def) }, shell } as unknown as Context
+  return { ctx, captured, requests }
+}
+
+describe("apply", () => {
+  it("registers all three tools", () => {
+    const { ctx, captured } = makeCtx("ok")
+    apply(ctx)
+    const names = captured.map((c) => (c as CapturedTool).name)
+    expect(names).toContain("gate-check")
+    expect(names).toContain("gate-principles")
+    expect(names).toContain("gate-arch")
+  })
+
+  /**
+   * @test REQ-DSH-002
+   * @intent 验证 gate-check 工具注册（path required / gates optional）并端到端接线 args→命令→shell
+   * @covers AC-DSH-002-01
+   */
+  it("gate-check execute builds the guarded command and returns rendered stdout", async () => {
+    const { ctx, captured, requests } = makeCtx("gate report")
+    apply(ctx)
+    const gateCheck = captured.find((c) => (c as CapturedTool).name === "gate-check") as CapturedTool
+    const out = await gateCheck.execute(
+      { path: "/repo/src", gates: ["principles"] },
+      { signal: new AbortController().signal },
+    )
+    expect(out).toBe("gate report")
+    expect(requests[0]?.command).toContain("xp-gate check '/repo/src' --gates 'principles'")
+  })
+
+  /**
+   * @test REQ-DSH-003
+   * @intent 验证 gate-principles 工具执行生成 `xp-gate principles <path>` 守卫命令
+   * @covers AC-DSH-003-01
+   */
+  it("gate-principles execute builds `xp-gate principles <path>`", async () => {
+    const { ctx, captured, requests } = makeCtx("principles report")
+    apply(ctx)
+    const tool = captured.find((c) => (c as CapturedTool).name === "gate-principles") as CapturedTool
+    const out = await tool.execute({ path: "/repo/src/app.ts" }, { signal: new AbortController().signal })
+    expect(out).toBe("principles report")
+    expect(requests[0]?.command).toContain("xp-gate principles '/repo/src/app.ts'")
+  })
+
+  /**
+   * @test REQ-DSH-004
+   * @intent 验证 gate-arch 工具执行生成 `xp-gate arch --config <config>`（缺省 architecture.yaml）
+   * @covers AC-DSH-004-01
+   */
+  it("gate-arch execute builds `xp-gate arch` with default and custom config", async () => {
+    const { ctx, captured, requests } = makeCtx("arch report")
+    apply(ctx)
+    const tool = captured.find((c) => (c as CapturedTool).name === "gate-arch") as CapturedTool
+    await tool.execute({}, { signal: new AbortController().signal })
+    expect(requests[0]?.command).toContain("xp-gate arch --config 'architecture.yaml'")
+    await tool.execute({ config: "custom.yaml" }, { signal: new AbortController().signal })
+    expect(requests[1]?.command).toContain("xp-gate arch --config 'custom.yaml'")
+  })
+})

package/plugins/dsh/src/index.ts

@@ -0,0 +1,94 @@
+import { defineTool } from "@deepseek-ai/dsh-tools"
+import type { Context } from "@deepseek-ai/cordis"
+import { GATE_WHITELIST, buildCommand, resolveTarget } from "./command.js"
+import { runXpGate } from "./gate-runner.js"
+
+export const name = "tool-xp-gate"
+export const inject = ["tools", "shell"]
+
+const DEFAULT_TIMEOUT_MS = 120_000
+
+export function apply(ctx: Context, _config: unknown = {}): void {
+  const shell = ctx.shell
+
+  ctx.tools.register(
+    defineTool({
+      name: "gate-check",
+      description:
+        "Run XP-Gate quality gates (xp-gate check) on a file or directory and return the gate report. Prefers the global xp-gate CLI and degrades to an actionable install hint when it is absent.",
+      parameters: {
+        path: {
+          type: "string",
+          required: true,
+          description: "File or directory path to check (absolute or relative to the workspace).",
+        },
+        gates: {
+          type: "array",
+          items: { type: "string", enum: GATE_WHITELIST },
+          description: "Optional gate subset to run (e.g. ['principles', 'arch']).",
+        },
+      },
+      output: {
+        schema: { type: "string" },
+        render: (_args, value) => [{ type: "text", text: value }],
+      },
+      timeoutMs: DEFAULT_TIMEOUT_MS,
+      async execute(args, exec) {
+        const cwd = exec.agent?.session?.header?.cwd ?? process.cwd()
+        const target = resolveTarget(args.path, cwd)
+        const command = buildCommand({ subcommand: "check", target, gates: args.gates })
+        return runXpGate(shell, exec.signal, command, cwd, DEFAULT_TIMEOUT_MS)
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: "gate-principles",
+      description:
+        "Run the 14 Clean Code / SOLID rules (xp-gate principles, Gate 4) on a file or directory and return the principles report.",
+      parameters: {
+        path: {
+          type: "string",
+          required: true,
+          description: "File or directory path to check (absolute or relative to the workspace).",
+        },
+      },
+      output: {
+        schema: { type: "string" },
+        render: (_args, value) => [{ type: "text", text: value }],
+      },
+      timeoutMs: DEFAULT_TIMEOUT_MS,
+      async execute(args, exec) {
+        const cwd = exec.agent?.session?.header?.cwd ?? process.cwd()
+        const target = resolveTarget(args.path, cwd)
+        const command = buildCommand({ subcommand: "principles", target })
+        return runXpGate(shell, exec.signal, command, cwd, DEFAULT_TIMEOUT_MS)
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: "gate-arch",
+      description:
+        "Run architecture validation (xp-gate arch, Gate 6) using the given config file and return the architecture report. Defaults to architecture.yaml.",
+      parameters: {
+        config: {
+          type: "string",
+          description: "Architecture config file path (defaults to architecture.yaml).",
+        },
+      },
+      output: {
+        schema: { type: "string" },
+        render: (_args, value) => [{ type: "text", text: value }],
+      },
+      timeoutMs: DEFAULT_TIMEOUT_MS,
+      async execute(args, exec) {
+        const cwd = exec.agent?.session?.header?.cwd ?? process.cwd()
+        const command = buildCommand({ subcommand: "arch", config: args.config })
+        return runXpGate(shell, exec.signal, command, cwd, DEFAULT_TIMEOUT_MS)
+      },
+    }),
+  )
+}

package/plugins/dsh/src/skills.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest"
+import { readdirSync, readFileSync, existsSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { parse } from "yaml"
+
+/** Mirrors `SKILL_NAME` in @deepseek-ai/dsh-skill. */
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+const EXPECTED_SKILLS = [
+  "admin-template-guidelines",
+  "batch-grill-me",
+  "delphi-review",
+  "domain-modeling",
+  "grilling",
+  "grill-with-docs",
+  "improve-codebase-architecture",
+  "ralph-loop",
+  "sprint-flow",
+  "test-driven-development",
+  "test-specification-alignment",
+  "to-issues",
+]
+
+const SKILLS_DIR = resolve(fileURLToPath(new URL("..", import.meta.url)), "skills")
+
+function readFrontmatter(file: string): Record<string, unknown> {
+  const raw = readFileSync(file, "utf8")
+  const m = raw.match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n/)
+  if (!m) throw new Error(`${file}: missing YAML frontmatter`)
+  return parse(m[1]) as Record<string, unknown>
+}
+
+describe("bundled skills", () => {
+  it("ships all 12 skills as directories", () => {
+    expect(existsSync(SKILLS_DIR)).toBe(true)
+    const dirs = readdirSync(SKILLS_DIR, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+      .sort()
+    expect(dirs).toEqual([...EXPECTED_SKILLS].sort())
+  })
+
+  /**
+   * @test REQ-DSH-006
+   * @intent 验证随包 12 个 skills 目录里各 SKILL.md 的 frontmatter 满足 DSH 契约（name kebab-case + description 非空）
+   * @covers AC-DSH-006-01
+   */
+  it("every SKILL.md satisfies the DSH frontmatter contract", () => {
+    for (const name of EXPECTED_SKILLS) {
+      const fm = readFrontmatter(join(SKILLS_DIR, name, "SKILL.md"))
+      expect(fm.name, `${name}: frontmatter.name`).toBeTypeOf("string")
+      expect(SKILL_NAME.test(fm.name as string), `${name}: kebab-case name`).toBe(true)
+      expect(fm.description, `${name}: frontmatter.description`).toBeTypeOf("string")
+      expect((fm.description as string).trim().length, `${name}: non-empty description`).toBeGreaterThan(0)
+    }
+  })
+})

package/plugins/dsh/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "lib",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "lib", "src/**/*.test.ts"]
+}

package/plugins/dsh/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noImplicitAny": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}