@boyingliu01/xp-gate 0.31.3 → 0.32.0

package/plugins/dsh/src/skill-provider.test.ts

@@ -0,0 +1,194 @@
+/**
+ * @test REQ-DSH-006 bundled skill provider
+ * @intent Verify the plugin registers a DSH SkillProvider that publishes all 12 bundled
+ *         skills with model-visible metadata, correct resourceBase for relative
+ *         references/, and a body loader that re-reads from disk each call.
+ * @covers AC-DSH-006-01 AC-DSH-006-02 AC-DSH-006-03
+ *
+ * Why these assertions exist: v1 shipped 65 skill files inside the tarball and still
+ * delivered none of them, because the requirement assumed a `bundledSkillDir`
+ * discovery root the plugin cannot set itself. A test that only checks "files are
+ * present on disk" reproduces that bug, so every assertion here goes through the
+ * SkillProvider contract DSH actually consumes.
+ */
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { describe, expect, it, afterAll } from "vitest"
+
+import {
+  createSkillProvider,
+  listBundledSkills,
+} from "./skill-provider.js"
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill"
+import type {
+  SkillCandidate,
+  SkillProvider,
+  SkillProviderObservation,
+} from "@deepseek-ai/dsh-skill"
+
+const SKILLS_ROOT = fileURLToPath(new URL("../skills/", import.meta.url))
+
+/** The repository ships this many skills; the count is part of the delivery promise. */
+const EXPECTED_SKILL_COUNT = 12;
+
+/** A skill body shorter than this is a stub, not a usable instruction set. */
+const MIN_SKILL_BODY_CHARS = 200;
+
+/** A description shorter than this cannot route a skill to the right task. */
+const MIN_DESCRIPTION_CHARS = 50;
+
+/** Every skill directory shipped in the tarball, read from disk rather than hard-coded. */
+const shipped = listBundledSkills(SKILLS_ROOT).map((s) => s.name).sort()
+
+const scratchDirs: string[] = []
+function scratch(): string {
+  const dir = mkdtempSync(join(tmpdir(), "xp-gate-skill-provider-"))
+  scratchDirs.push(dir)
+  return dir
+}
+
+/**
+ * Narrow the dual-shape `list()` return to a plain candidate array.
+ * DSH allows a provider to answer with either a bare array or an observation
+ * object; this provider always uses the bare array, but the type is a union.
+ */
+function candidatesOf(
+  listed: Awaited<ReturnType<SkillProvider["list"]>>,
+): readonly SkillCandidate[] {
+  return Array.isArray(listed) ? listed : ((listed as SkillProviderObservation).candidates ?? [])
+}
+
+afterAll(() => {
+  for (const dir of scratchDirs) rmSync(dir, { recursive: true, force: true })
+})
+
+describe("bundled skill provider", () => {
+  it("discovers all 12 bundled skills", () => {
+    expect(shipped).toHaveLength(EXPECTED_SKILL_COUNT)
+    expect(shipped).toContain("delphi-review")
+    expect(shipped).toContain("sprint-flow")
+    expect(shipped).toContain("test-driven-development")
+  })
+
+  it("returns candidates carrying the DSH skill contract", async () => {
+    const provider = createSkillProvider(SKILLS_ROOT)
+    const listed = await provider.list({})
+    const candidates = candidatesOf(listed)
+    expect(candidates).toBeDefined()
+    expect(candidates).toHaveLength(EXPECTED_SKILL_COUNT)
+
+    for (const candidate of candidates) {
+      expect(candidate.name).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/)
+      // A blank description makes the skill unroutable: the model never picks it.
+      expect(candidate.description.length).toBeGreaterThan(10)
+      expect(candidate.invocation).toEqual({
+        modelInvocable: true,
+        userInvocable: true,
+      })
+      expect(candidate.provider).toBe("xp-gate")
+      expect(candidate.source).toBe("bundled")
+      expect(candidate.rank).toBe(BUNDLED_SKILL_RANK)
+    }
+  })
+
+  it("gives every candidate a directory resourceBase so relative references resolve", () => {
+    // 8 of the 12 skills point at references/*.md and templates/*; without
+    // resourceBase those paths have no base and the skill dangles.
+    const candidates = listBundledSkills(SKILLS_ROOT)
+    expect(candidates).toHaveLength(EXPECTED_SKILL_COUNT)
+    for (const candidate of candidates) {
+      expect(candidate.resourceBase).toBeDefined()
+      expect(candidate.resourceBase?.kind).toBe("directory")
+      const base = candidate.resourceBase
+      if (base?.kind === "directory") {
+        expect(base.path).toContain(candidate.name)
+      }
+    }
+  })
+
+  it("loads a non-empty body with the frontmatter stripped", async () => {
+    const provider = createSkillProvider(SKILLS_ROOT)
+    const listed = await provider.list({})
+    const candidates = candidatesOf(listed)
+    const target = candidates.find((c) => c.name === "delphi-review")
+    expect(target).toBeDefined()
+    if (!target) return
+
+    const definition = await provider.get(target, {})
+    expect(definition).toBeDefined()
+    expect(definition?.name).toBe("delphi-review")
+    // The body starts after the YAML block, so the opening `---` must be gone.
+    expect(definition?.content ?? "").not.toMatch(/^---/)
+    expect((definition?.content ?? "").length).toBeGreaterThan(MIN_SKILL_BODY_CHARS)
+    expect(definition?.content).toContain("Delphi")
+  })
+
+  it("re-reads the body from disk on each get, so edits apply without a restart", async () => {
+    const root = scratch()
+    const dir = join(root, "demo-skill")
+    const file = join(dir, "SKILL.md")
+    try {
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(
+        file,
+        "---\nname: demo-skill\ndescription: A demo skill used to prove the body is not cached.\n---\n\n# Original body marker\n",
+        "utf8",
+      )
+    } catch (error) {
+      throw new Error(`cannot build scratch skill: ${(error as Error).message}`)
+    }
+
+    const provider = createSkillProvider(root)
+    const listed = await provider.list({})
+    const candidates = candidatesOf(listed)
+    const target = candidates[0]
+    expect(target).toBeDefined()
+    if (!target) return
+
+    const first = await provider.get(target, {})
+    expect(first?.content).toContain("Original body marker")
+
+    try {
+      writeFileSync(
+        file,
+        "---\nname: demo-skill\ndescription: A demo skill used to prove the body is not cached.\n---\n\n# Edited body marker\n",
+        "utf8",
+      )
+    } catch (error) {
+      throw new Error(`cannot edit scratch skill: ${(error as Error).message}`)
+    }
+
+    const second = await provider.get(target, {})
+    expect(second?.content).toContain("Edited body marker")
+    expect(second?.content).not.toContain("Original body marker")
+  })
+
+  it("parses both folded and quoted YAML descriptions", () => {
+    // Two shapes ship in this repo: `description: >` blocks (delphi-review,
+    // sprint-flow) and one-line quoted values. A parser handling only one shape
+    // silently yields an empty description for the other, making the skill
+    // invisible to routing.
+    const candidates = listBundledSkills(SKILLS_ROOT)
+    const folded = candidates.find((c) => c.name === "delphi-review")
+    const quoted = candidates.find((c) => c.name === "admin-template-guidelines")
+
+    expect(folded?.description.length).toBeGreaterThan(MIN_DESCRIPTION_CHARS)
+    expect(quoted?.description.length).toBeGreaterThan(MIN_DESCRIPTION_CHARS)
+    // The folded block must be unfolded into one line, not left with newlines.
+    expect(folded?.description).not.toContain("\n")
+  })
+
+  it("returns an empty catalog for a missing skills root instead of throwing", async () => {
+    const provider = createSkillProvider(join(tmpdir(), "xp-gate-does-not-exist-root"))
+    const listed = await provider.list({})
+    const candidates = candidatesOf(listed)
+    expect(candidates).toHaveLength(0)
+  })
+})
+
+
+

package/plugins/dsh/src/skill-provider.ts

@@ -0,0 +1,231 @@
+import { readdirSync, readFileSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill"
+import type {
+  SkillCandidate,
+  SkillDefinition,
+  SkillLookupOptions,
+  SkillProvider,
+} from "@deepseek-ai/dsh-skill"
+
+/**
+ * Provider label surfaced to the model alongside each skill.
+ * Matches the plugin name so a loaded skill is attributable.
+ */
+const PROVIDER_NAME = "xp-gate"
+
+/** Files a skill directory must contain to be loadable. */
+const SKILL_FILE = "SKILL.md"
+
+/** The `---` line that opens and closes a SKILL.md YAML frontmatter block. */
+const FRONTMATTER_FENCE = "---"
+
+/** Offset just past the opening fence, and past the closing fence plus its newline. */
+const FRONTMATTER_START = FRONTMATTER_FENCE.length
+const FRONTMATTER_END_OFFSET = FRONTMATTER_FENCE.length + 1
+
+interface ParsedSkill {
+  readonly name: string
+  readonly description: string
+  readonly content: string
+}
+
+/**
+ * Unfold a YAML block scalar (`key: >` / `key: |`) body into one line.
+ * Folded blocks join on spaces, literal blocks on newlines.
+ */
+function unfoldBlock(lines: readonly string[], literal: boolean): string {
+  const trimmed = lines.map((line) => line.trim())
+  if (literal) return trimmed.filter((line) => line.length > 0).join("\n")
+  return trimmed.filter((line) => line.length > 0).join(" ")
+}
+
+/**
+ * Extract `name` and `description` from a SKILL.md frontmatter block.
+ *
+ * Two description shapes ship in this repository: folded blocks
+ * (`description: >`) used by delphi-review and sprint-flow, and one-line quoted
+ * or plain values used by the rest. A parser handling only one shape yields an
+ * empty description for the other, which makes those skills unroutable — the
+ * model never picks a skill it cannot see described.
+ */
+function parseSkill(raw: string, file: string): ParsedSkill {
+  if (!raw.startsWith(FRONTMATTER_FENCE)) {
+    throw new Error(`${file}: missing YAML frontmatter`)
+  }
+  const end = raw.indexOf(`\n${FRONTMATTER_FENCE}`, FRONTMATTER_START)
+  if (end === -1) {
+    throw new Error(`${file}: unterminated YAML frontmatter`)
+  }
+  const frontmatter = raw.slice(FRONTMATTER_START, end)
+  const content = raw.slice(end + FRONTMATTER_END_OFFSET).replace(/^\r?\n/, "")
+
+  const lines = frontmatter.split(/\r?\n/)
+  let name = ""
+  let description = ""
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? ""
+    const keyed = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/.exec(line)
+    if (!keyed) continue
+    const key = keyed[1]
+    const rest = (keyed[2] ?? "").trim()
+
+    // Collect the indented continuation lines of a block scalar.
+    const blockMatch = /^([>|])([+-]?)$/.exec(rest)
+    if (blockMatch) {
+      const block: string[] = []
+      let cursor = index + 1
+      while (cursor < lines.length) {
+        const next = lines[cursor] ?? ""
+        if (next.trim().length > 0 && !/^\s/.test(next)) break
+        block.push(next)
+        cursor += 1
+      }
+      index = cursor - 1
+      const value = unfoldBlock(block, blockMatch[1] === "|")
+      if (key === "name") name = value
+      if (key === "description") description = value
+      continue
+    }
+
+    if (key !== "name" && key !== "description") continue
+    // Strip a matching pair of surrounding quotes without touching inner ones.
+    const unquoted = /^(['"])(.*)\1$/.exec(rest)?.[2] ?? rest
+    if (key === "name") name = unquoted
+    if (key === "description") description = unquoted
+  }
+
+  if (!name) throw new Error(`${file}: frontmatter carries no name`)
+  if (!description) throw new Error(`${file}: frontmatter carries no description`)
+  return { name, description, content }
+}
+
+interface ListedSkill {
+  readonly name: string
+  readonly description: string
+  readonly directory: string
+  readonly file: string
+}
+
+/**
+ * Scan `root` for skill directories without loading their bodies.
+ *
+ * The catalog is fixed at package build time, so scanning once at apply() is
+ * enough; bodies stay on disk and are read per `get()`. A missing root yields
+ * an empty catalog rather than throwing: a plugin whose skills directory was
+ * stripped during packaging must still load its tools.
+ */
+function scanSkills(root: string): ListedSkill[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+  } catch {
+    return []
+  }
+
+  const listed: ListedSkill[] = []
+  for (const entry of entries.sort()) {
+    const directory = join(root, entry)
+    const file = join(directory, SKILL_FILE)
+    let raw: string
+    try {
+      raw = readFileSync(file, "utf8")
+    } catch {
+      // A directory without SKILL.md is not a skill; skip it silently so a
+      // stray file in the package cannot break the whole catalog.
+      continue
+    }
+    const parsed = parseSkill(raw, file)
+    listed.push({
+      name: parsed.name,
+      description: parsed.description,
+      directory,
+      file,
+    })
+  }
+  return listed
+}
+
+/**
+ * Build the DSH skill candidates for every skill bundled under `root`.
+ * Exposed for tests and for callers that need the catalog without a provider.
+ */
+export function listBundledSkills(root: string): SkillCandidate[] {
+  return scanSkills(root).map((skill) => ({
+    name: skill.name,
+    description: skill.description,
+    invocation: { modelInvocable: true, userInvocable: true },
+    provider: PROVIDER_NAME,
+    source: "bundled",
+    rank: BUNDLED_SKILL_RANK,
+    // 8 of the 12 skills reference references/*.md and templates/*; without a
+    // directory base those relative paths have nothing to resolve against.
+    resourceBase: { kind: "directory", path: skill.directory },
+    locator: skill.file,
+  }))
+}
+
+/**
+ * Load one candidate's body from disk.
+ *
+ * Separated from the provider literal so the lookup/read/decorate steps sit at the
+ * same nesting level instead of inside an object method's promise chain.
+ */
+async function loadSkill(
+  candidate: SkillCandidate,
+  options: SkillLookupOptions,
+  byName: ReadonlyMap<string, ListedSkill>,
+): Promise<SkillDefinition | undefined> {
+  // A candidate carries the absolute SKILL.md path it was listed from, so loading
+  // works even if the scanned catalog is stale; fall back to the catalog for
+  // hand-built candidates in tests.
+  const locator = typeof candidate.locator === "string" ? candidate.locator : ""
+  const target = locator.length > 0 ? locator : byName.get(candidate.name)?.file
+  if (!target) return undefined
+
+  let raw: string
+  try {
+    raw = await readFile(target, { encoding: "utf8", signal: options.signal })
+  } catch {
+    // A skill deleted after listing is no longer loadable; the registry treats
+    // undefined as "gone" and invalidates its cached entry.
+    return undefined
+  }
+  const parsed = parseSkill(raw, target)
+  // Built field by field rather than by spreading and dropping the extras: `rank`
+  // and `locator` describe the catalog entry and are not part of a definition, and
+  // naming what belongs here keeps that boundary visible.
+  return {
+    name: candidate.name,
+    description: candidate.description,
+    invocation: candidate.invocation,
+    source: candidate.source,
+    provider: candidate.provider,
+    path: candidate.path,
+    resourceBase: candidate.resourceBase,
+    whenToUse: candidate.whenToUse,
+    content: parsed.content,
+  }
+}
+
+/**
+ * Create the XP-Gate skill provider for a given skills root.
+ *
+ * Mirrors the shape of the official `@deepseek-ai/dsh-skill-office` provider:
+ * candidates are scanned once, bodies are re-read on every `get()` so editing a
+ * skill takes effect without restarting the host.
+ */
+export function createSkillProvider(root: string): SkillProvider {
+  const byName = new Map(scanSkills(root).map((skill) => [skill.name, skill]))
+  const candidates = listBundledSkills(root)
+
+  return {
+    name: PROVIDER_NAME,
+    list: () => Promise.resolve(candidates),
+    get: (candidate, options) => loadSkill(candidate, options, byName),
+  }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * @test REQ-DSH-013 sprint-flow subcommands are callable from the model
+ * @intent Verify the sprint tool only ever builds a command from an enumerated
+ *         subcommand, so exposing sprint state to the model does not widen the
+ *         shell surface it already had.
+ * @covers AC-DSH-013-01 AC-DSH-013-02 AC-DSH-013-03
+ *
+ * The sprint-flow skill tells the model to run sprint-status, phase-transition and
+ * friends, but none of them were reachable from the plugin: a model following the
+ * skill could only report that it could not proceed. Each of these is read-mostly
+ * state, so the fix is a narrow tool, not a passthrough -- a passthrough would turn
+ * one tool into the whole CLI.
+ */
+
+import { describe, expect, it } from "vitest"
+import { SPRINT_SUBCOMMANDS, PHASE_STATUSES, buildSprintCommand, isSprintSubcommand } from "./sprint.js"
+
+/** Collect the ids so a failure names what is missing rather than just a count. */
+const IDS = SPRINT_SUBCOMMANDS.slice()
+
+describe("sprint subcommand whitelist", () => {
+  it("exposes every subcommand the sprint-flow skill references", () => {
+    for (const needed of [
+      "sprint-status",
+      "phase-transition",
+      "retro",
+      "ui-review",
+      "sprint-init",
+      "sprint-audit",
+    ]) {
+      expect(IDS).toContain(needed)
+    }
+  })
+
+  it("accepts only enumerated subcommands", () => {
+    expect(isSprintSubcommand("sprint-status")).toBe(true)
+    // Anything not in the list must not reach a shell, however plausible it looks.
+    for (const rejected of ["", "uninstall", "sprint-status; rm -rf /", "$(whoami)", "gate-11"]) {
+      expect(isSprintSubcommand(rejected)).toBe(false)
+    }
+  })
+
+  it("builds sprint-status with structured options only", () => {
+    const cmd = buildSprintCommand("sprint-status", { json: true, dir: "/repo" }, "powershell")
+    expect(cmd).toContain("sprint-status")
+    expect(cmd).toContain("--json")
+    expect(cmd).toContain("--dir")
+  })
+
+  it("rejects a phase-transition whose status is not a documented value", () => {
+    // A status is a second injection point, so it is enumerated rather than quoted.
+    expect(PHASE_STATUSES).toEqual(["in_progress", "completed", "skipped", "failed", "paused"])
+    expect(() =>
+      buildSprintCommand("phase-transition", { phase: "3", status: "done; rm -rf /" }, "powershell"),
+    ).toThrow()
+  })
+
+  it("quotes a path containing shell metacharacters", () => {
+    const cmd = buildSprintCommand("sprint-status", { dir: "/tmp/a b; whoami" }, "powershell")
+    // The whole value must stay one argument; the semicolon must not start a command.
+    expect(cmd).not.toMatch(/; whoami\s*$/)
+    expect(cmd).toContain("a b; whoami")
+  })
+})

package/plugins/dsh/src/sprint.ts

@@ -0,0 +1,122 @@
+/**
+ * Sprint-flow subcommands the model may run.
+ *
+ * @test REQ-DSH-013 sprint-flow subcommands are callable from the model
+ * @intent Expose the sprint state commands the sprint-flow skill instructs the model
+ *         to run, without opening a passthrough to the whole CLI.
+ * @covers AC-DSH-013-01
+ *
+ * The skill references these commands by name, so before this module existed a model
+ * following the skill could read the instruction and had no way to carry it out.
+ *
+ * The whitelist is the security boundary, not a convenience: a passthrough tool would
+ * turn one tool call into arbitrary CLI invocation, which is a far larger surface than
+ * the four gate tools it sits beside. Enumerating both the subcommand and the
+ * phase-transition status keeps every user-influenced token inside a known set.
+ */
+
+import { type ShellDialect, shellQuote } from "./dialect.js"
+
+/**
+ * Subcommands in scope. Deliberately excludes anything destructive or
+ * environment-mutating (`uninstall`, `init`, `migrate`, `setup-global`) even though
+ * they are the same CLI.
+ */
+export const SPRINT_SUBCOMMANDS = [
+  "sprint-status",
+  "phase-transition",
+  "retro",
+  "ui-review",
+  "sprint-init",
+  "sprint-audit",
+  "next-sprint",
+] as const
+
+export type SprintSubcommand = (typeof SPRINT_SUBCOMMANDS)[number]
+
+/** The only status values `phase-transition` documents. */
+export const PHASE_STATUSES = ["in_progress", "completed", "skipped", "failed", "paused"] as const
+
+export type PhaseStatus = (typeof PHASE_STATUSES)[number]
+
+/** Options a caller may pass. Every field is either enumerated or quoted. */
+export interface SprintCommandOptions {
+  /** phase-transition phase number, 1-6. */
+  readonly phase?: string
+  /** phase-transition status. */
+  readonly status?: string
+  /** Project directory, quoted as a single argument. */
+  readonly dir?: string
+  /** Emit JSON where the subcommand supports it. */
+  readonly json?: boolean
+  /** `retro`: look back N days. */
+  readonly days?: number
+  /** `retro`: cover every sprint. */
+  readonly all?: boolean
+}
+
+/** Phase numbers the CLI accepts. */
+const PHASE_NUMBERS: readonly string[] = ["1", "2", "3", "4", "5", "6"]
+
+/** Type guard for the subcommand whitelist. */
+export function isSprintSubcommand(value: string): boolean {
+  return (SPRINT_SUBCOMMANDS as readonly string[]).includes(value)
+}
+
+/**
+ * Validate a subcommand, throwing rather than returning a sentinel.
+ *
+ * A caller that ignores a boolean would fall through to "run nothing" or, worse, to a
+ * default subcommand; throwing makes the rejection impossible to overlook.
+ */
+export function assertSprintSubcommand(value: string): asserts value is SprintSubcommand {
+  if (!isSprintSubcommand(value)) {
+    throw new Error(
+      `Unknown sprint subcommand "${value}". Allowed: ${SPRINT_SUBCOMMANDS.join(", ")}`,
+    )
+  }
+}
+
+/** Validate the two positional arguments phase-transition requires. */
+function phaseTokens(options: SprintCommandOptions): string[] {
+  const phase = options.phase ?? ""
+  if (!PHASE_NUMBERS.includes(phase)) {
+    throw new Error(`phase must be one of ${PHASE_NUMBERS.join(", ")}; got "${phase}"`)
+  }
+  const status = options.status ?? ""
+  if (!(PHASE_STATUSES as readonly string[]).includes(status)) {
+    throw new Error(`status must be one of ${PHASE_STATUSES.join(", ")}; got "${status}"`)
+  }
+  return [phase, status]
+}
+
+/** Append the flags shared by several subcommands. */
+function sharedFlags(options: SprintCommandOptions, dialect: ShellDialect): string[] {
+  const flags: string[] = []
+  if (options.json) flags.push("--json")
+  if (options.all) flags.push("--all")
+  if (options.days !== undefined && Number.isInteger(options.days) && options.days > 0) {
+    flags.push("--days", String(options.days))
+  }
+  if (options.dir !== undefined) flags.push("--dir", shellQuote(options.dir, dialect))
+  return flags
+}
+
+/**
+ * Build the command line for a whitelisted subcommand.
+ *
+ * User-influenced values reach the shell in exactly two ways: enumerated membership
+ * (subcommand, phase, status) or shell quoting (paths). Nothing is interpolated raw,
+ * which is what keeps this from becoming the injection surface a passthrough would be.
+ */
+export function buildSprintCommand(
+  subcommand: string,
+  options: SprintCommandOptions = {},
+  dialect: ShellDialect = "posix",
+): string {
+  assertSprintSubcommand(subcommand)
+  const tokens = ["xp-gate", subcommand]
+  if (subcommand === "phase-transition") tokens.push(...phaseTokens(options))
+  tokens.push(...sharedFlags(options, dialect))
+  return tokens.join(" ")
+}