@boyingliu01/xp-gate 0.19.3 → 0.20.0

package/plugins/dsh/src/command.ts

@@ -1,4 +1,9 @@
 import { isAbsolute, resolve } from "node:path"
+import { type ShellDialect, shellQuote } from "./dialect.js"
+
+// Re-exported so existing importers of this module keep working; the dialect
+// primitives themselves live in ./dialect.ts.
+export { type ShellDialect, detectDialect, shellQuote, shq } from "./dialect.js"
 
 /** Shown when the global `xp-gate` CLI is not on PATH. */
 export const FALLBACK_MESSAGE =
@@ -22,11 +27,6 @@ export const GATE_WHITELIST = [
 
 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)
 }
@@ -36,40 +36,62 @@ export interface BuildCommandOptions {
   target?: string
   gates?: readonly string[]
   config?: string
+  /**
+   * Executor dialect. Defaults to `"posix"` so existing callers keep working;
+   * callers running under DSH on Windows must pass `"powershell"`.
+   */
+  dialect?: ShellDialect
 }
 
-function buildInner(options: BuildCommandOptions): string {
+function buildInner(options: BuildCommandOptions, dialect: ShellDialect): string {
   const { subcommand, target, gates, config } = options
+  const q = (value: string) => shellQuote(value, dialect)
   if (subcommand === "check") {
     const tokens = ["xp-gate", "check"]
-    if (target !== undefined) tokens.push(shq(target))
+    if (target !== undefined) tokens.push(q(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(",")))
+      if (allowed.length > 0) tokens.push("--gates", q(allowed.join(",")))
     }
     return tokens.join(" ")
   }
   if (subcommand === "principles") {
     const tokens = ["xp-gate", "principles"]
-    if (target !== undefined) tokens.push(shq(target))
+    if (target !== undefined) tokens.push(q(target))
     return tokens.join(" ")
   }
-  return ["xp-gate", "arch", "--config", shq(config ?? "architecture.yaml")].join(" ")
+  return ["xp-gate", "arch", "--config", q(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.
+ * presence check 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`
+  const dialect = options.dialect ?? "posix"
+  const inner = buildInner(options, dialect)
+  if (dialect === "posix") {
+    return `if command -v xp-gate >/dev/null 2>&1; then ${inner}; else printf '%s\\n' ${shellQuote(
+      FALLBACK_MESSAGE,
+      dialect,
+    )}; fi`
+  }
+  // PowerShell: `Get-Command` resolves the .cmd/.ps1 shims npm writes to
+  // %APPDATA%\npm. Those shims are invisible to a Git-Bash PATH lookup, so this
+  // branch is more reliable than `command -v` on Windows.
+  //
+  // The hint branch leaves $LASTEXITCODE untouched at 0, matching the POSIX
+  // branch's `printf` behaviour.
+  return `if (Get-Command xp-gate -ErrorAction SilentlyContinue) { ${inner} } else { Write-Output ${shellQuote(
+    FALLBACK_MESSAGE,
+    dialect,
+  )} }`
 }
 
 /** 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

@@ -51,7 +51,16 @@ describe("packaging contract", () => {
    * @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"]
+    const files = [
+      "command.test.ts",
+      "gate-runner.test.ts",
+      "index.test.ts",
+      "skills.test.ts",
+      "dialect.test.ts",
+      "delphi.test.ts",
+      "delphi-config.test.ts",
+      "delphi-run.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+/)
@@ -59,4 +68,25 @@ describe("packaging contract", () => {
       expect(content, `${f}: @covers`).toMatch(/@covers\s+AC-\S+/)
     }
   })
+
+  /**
+   * @test REQ-DSH-016
+   * @intent 验证多模型交叉评审已在 DSH 中固化：插件注册 delphi-review 工具，
+   *         且实现强制三条 Delphi 不变量（3 位专家、模型两两不同、90% 阈值）。
+   * @covers AC-DSH-016-01
+   */
+  it("registers the delphi-review tool and enforces Delphi invariants", () => {
+    const entry = readFileSync(join(PKG_ROOT, "src", "index.ts"), "utf8")
+    expect(entry).toContain('name: "delphi-review"')
+    expect(entry).toContain("loadDelphiConfig")
+    expect(entry).toContain("runReview")
+
+    // The invariants must live in code, not only in prose.
+    const core = readFileSync(join(PKG_ROOT, "src", "delphi.ts"), "utf8")
+    expect(core).toMatch(/REQUIRED_EXPERTS\s*=\s*3/)
+    expect(core).toMatch(/DEFAULT_THRESHOLD_PERCENT\s*=\s*90/)
+    expect(core).toMatch(/distinct/)
+    // A report with no explicit verdict must not be counted toward consensus.
+    expect(core).toContain("INVALID_NO_VERDICT")
+  })
 })

package/plugins/dsh/src/delphi-config.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect } from "vitest"
+import { DelphiSetupError, expandEnv, resolveConfig } from "./delphi-config.js"
+
+/**
+ * @test REQ-DSH-016
+ * @intent 验证 .delphi-config.json 的解析：active_profile 选择、${VAR} 与 {env:VAR}
+ *         两种占位符展开、缺密钥/缺 provider 时给出可操作的错误，
+ *         以及未展开的模型占位符在校验期被拦住（而非变成 provider 404）。
+ * @covers AC-DSH-016-02
+ */
+
+const baseConfig = {
+  active_profile: "whalecloud",
+  profiles: {
+    whalecloud: {
+      provider: "whalecloud",
+      providers: {
+        whalecloud: {
+          base_url: "https://lab.example.com/gpt-proxy",
+          api_key: "${WHALECLOUD_API_KEY}",
+        },
+      },
+      experts: [
+        { id: "Expert A", role: "architecture", model: "g-glm-5.3-flash", max_tokens: 32000 },
+        { id: "Expert B", role: "technical", model: "g-qwen3.8-flash" },
+        { id: "Expert C", role: "feasibility", model: "g-deepseek-flash" },
+      ],
+      consensus: { threshold_percent: 90, max_review_rounds: 5 },
+    },
+  },
+}
+
+describe("expandEnv", () => {
+  it("expands both ${VAR} and {env:VAR} spellings", () => {
+    const env = { TOK: "secret" }
+    expect(expandEnv("${TOK}", env)).toBe("secret")
+    expect(expandEnv("{env:TOK}", env)).toBe("secret")
+    expect(expandEnv("Bearer ${TOK}!", env)).toBe("Bearer secret!")
+  })
+
+  it("expands an unset variable to empty so the caller can detect it", () => {
+    expect(expandEnv("${NOPE}", {})).toBe("")
+  })
+})
+
+describe("resolveConfig", () => {
+  it("resolves the active profile into seats and transport settings", () => {
+    const cfg = resolveConfig(baseConfig, { WHALECLOUD_API_KEY: "k123" })
+    expect(cfg.provider).toBe("whalecloud")
+    expect(cfg.baseUrl).toBe("https://lab.example.com/gpt-proxy")
+    expect(cfg.apiKey).toBe("k123")
+    expect(cfg.seats).toHaveLength(3)
+    expect(cfg.seats.map((s) => s.model)).toEqual([
+      "g-glm-5.3-flash",
+      "g-qwen3.8-flash",
+      "g-deepseek-flash",
+    ])
+    // Per-seat budget is preserved: reasoning models need a larger one.
+    expect(cfg.seats[0].maxTokens).toBe(32000)
+    expect(cfg.thresholdPercent).toBe(90)
+    expect(cfg.maxRounds).toBe(5)
+  })
+
+  it("names the missing environment variable instead of echoing the config", () => {
+    // The config may hold a literal key, so the error must not interpolate it.
+    let message = ""
+    try {
+      resolveConfig(baseConfig, {})
+    } catch (e) {
+      message = (e as Error).message
+    }
+    expect(message).toMatch(/WHALECLOUD_API_KEY/)
+    expect(message).toMatch(/not set/)
+  })
+
+  it("reports an unknown provider with the known alternatives", () => {
+    const bad = structuredClone(baseConfig)
+    bad.profiles.whalecloud.provider = "nope"
+    expect(() => resolveConfig(bad, { WHALECLOUD_API_KEY: "k" })).toThrow(/not defined under "providers"/)
+  })
+
+  it("rejects an unexpanded model placeholder at config time", () => {
+    const bad = structuredClone(baseConfig)
+    bad.profiles.whalecloud.experts[1].model = "${QWEN_MODEL}"
+    expect(() => resolveConfig(bad, { WHALECLOUD_API_KEY: "k" })).toThrow(/unexpanded/)
+  })
+
+  it("refuses to guess when several profiles exist and none is active", () => {
+    const multi = {
+      profiles: {
+        a: { provider: "p", providers: { p: { base_url: "u", api_key: "k" } }, experts: [] },
+        b: { provider: "p", providers: { p: { base_url: "u", api_key: "k" } }, experts: [] },
+      },
+    }
+    expect(() => resolveConfig(multi, {})).toThrow(/No active_profile/)
+  })
+
+  it("enforces the three-distinct-model invariant through the config path too", () => {
+    const dup = structuredClone(baseConfig)
+    dup.profiles.whalecloud.experts[2].model = "g-qwen3.8-flash"
+    expect(() => resolveConfig(dup, { WHALECLOUD_API_KEY: "k" })).toThrow(/distinct/)
+  })
+
+  it("raises DelphiSetupError so callers can present guidance, not a stack trace", () => {
+    expect(() => resolveConfig(baseConfig, {})).toThrow(DelphiSetupError)
+  })
+})
+
+/**
+ * The shape xp-gate actually writes differs from the tidy array form: `experts`
+ * is an OBJECT keyed by role, each expert names its own provider, and
+ * `consensus` sits at the document root. This was found by running the loader
+ * against the repo's real .delphi-config.json and is locked in here.
+ */
+describe("resolveConfig with the real on-disk schema", () => {
+  const realWorld = {
+    active_profile: "whalecloud",
+    profiles: {
+      whalecloud: {
+        providers: {
+          whalecloud: {
+            base_url: "https://lab.iwhalecloud.com/gpt-proxy",
+            api_key: "${WHALECLOUD_API_KEY}",
+          },
+        },
+        experts: {
+          architecture: { provider: "whalecloud", model: "g-glm-5.3-flash" },
+          technical: { provider: "whalecloud", model: "g-qwen3.8-flash" },
+          feasibility: { provider: "whalecloud", model: "g-deepseek-flash" },
+        },
+      },
+    },
+    consensus: { threshold_percent: 90, max_review_rounds: 5, distinct_models_required: true },
+  }
+
+  it("reads experts from the object form and uses the key as the role", () => {
+    const cfg = resolveConfig(realWorld, { WHALECLOUD_API_KEY: "k" })
+    expect(cfg.seats).toHaveLength(3)
+    expect(cfg.seats.map((s) => s.role)).toEqual(["architecture", "technical", "feasibility"])
+    expect(cfg.seats.map((s) => s.model)).toEqual([
+      "g-glm-5.3-flash",
+      "g-qwen3.8-flash",
+      "g-deepseek-flash",
+    ])
+  })
+
+  it("resolves the provider named per expert when the profile has no default", () => {
+    // No profile-level "provider" key at all -- each seat carries its own.
+    const cfg = resolveConfig(realWorld, { WHALECLOUD_API_KEY: "k" })
+    expect(cfg.provider).toBe("whalecloud")
+    expect(cfg.baseUrl).toBe("https://lab.iwhalecloud.com/gpt-proxy")
+    expect(cfg.apiKey).toBe("k")
+  })
+
+  it("reads consensus from the document root", () => {
+    const cfg = resolveConfig(realWorld, { WHALECLOUD_API_KEY: "k" })
+    expect(cfg.thresholdPercent).toBe(90)
+    expect(cfg.maxRounds).toBe(5)
+  })
+
+  it("still enforces three distinct models in the object form", () => {
+    const dup = structuredClone(realWorld)
+    dup.profiles.whalecloud.experts.feasibility.model = "g-qwen3.8-flash"
+    expect(() => resolveConfig(dup, { WHALECLOUD_API_KEY: "k" })).toThrow(/distinct/)
+  })
+
+  it("rejects experts spread across different gateways", () => {
+    // One shared base_url is required so a seat's key is never sent elsewhere.
+    const split = structuredClone(realWorld) as {
+      active_profile: string
+      profiles: Record<
+        string,
+        {
+          providers: Record<string, { base_url: string; api_key: string }>
+          experts: Record<string, { provider: string; model: string }>
+        }
+      >
+      consensus: { threshold_percent: number; max_review_rounds: number }
+    }
+    split.profiles.whalecloud.providers.other = {
+      base_url: "https://elsewhere.example/v1",
+      api_key: "k2",
+    }
+    split.profiles.whalecloud.experts.technical = {
+      provider: "other",
+      model: "g-qwen3.8-flash",
+    }
+    expect(() => resolveConfig(split, { WHALECLOUD_API_KEY: "k" })).toThrow(/share one gateway/)
+  })
+})

package/plugins/dsh/src/delphi-config.ts

@@ -0,0 +1,223 @@
+/**
+ * Delphi configuration loading for the DSH plugin.
+ *
+ * Reads the same `.delphi-config.json` the xp-gate skill already uses, so a
+ * project configures its reviewers once and both the skill and the DSH tool
+ * agree on who they are.
+ *
+ * @test REQ-DSH-016
+ * @intent 复用项目既有的 .delphi-config.json，把 provider/api_key/专家席位解析成
+ *         DSH 工具可用的结构，并对 ${ENV} 占位符与缺失密钥给出可操作的报错。
+ * @covers AC-DSH-016-02
+ */
+
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import type { ExpertSeat, DelphiOptions } from "./delphi.js"
+import { validateSeats } from "./delphi.js"
+
+/** Shape of one expert entry in .delphi-config.json. */
+interface RawExpert {
+  id?: string
+  role?: string
+  name?: string
+  model?: string
+  requested_model?: string
+  max_tokens?: number
+  maxTokens?: number
+  /** Per-expert provider override; falls back to the profile default. */
+  provider?: string
+}
+
+interface RawProfile {
+  provider?: string
+  providers?: Record<string, { base_url?: string; baseUrl?: string; api_key?: string; apiKey?: string }>
+  /**
+   * Experts appear in two shapes in the wild: an object keyed by role (what
+   * xp-gate actually writes) and an array. Both are accepted.
+   */
+  experts?: RawExpert[] | Record<string, RawExpert>
+  consensus?: { threshold_percent?: number; max_review_rounds?: number }
+}
+
+export interface RawDelphiConfig extends RawProfile {
+  active_profile?: string
+  profiles?: Record<string, RawProfile>
+}
+
+export interface ResolvedDelphiConfig {
+  readonly seats: ExpertSeat[]
+  readonly baseUrl: string
+  readonly apiKey: string
+  readonly thresholdPercent: number
+  readonly maxRounds: number
+  readonly provider: string
+}
+
+/** Raised when config on disk cannot be turned into a usable review setup. */
+export class DelphiSetupError extends Error {}
+
+/**
+ * Expand `${VAR}` and `{env:VAR}` placeholders from the environment.
+ * Supports the two spellings already present in xp-gate config files.
+ */
+export function expandEnv(value: string, env: NodeJS.ProcessEnv = process.env): string {
+  return value
+    .replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name: string) => env[name] ?? "")
+    .replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name: string) => env[name] ?? "")
+}
+
+/** Pick the active profile, falling back to the top level. */
+function selectProfile(cfg: RawDelphiConfig): RawProfile {
+  const active = cfg.active_profile
+  if (active && cfg.profiles?.[active]) return cfg.profiles[active]
+  if (cfg.profiles && Object.keys(cfg.profiles).length > 0) {
+    throw new DelphiSetupError(
+      `No active_profile set. Available: ${Object.keys(cfg.profiles).join(", ")}`,
+    )
+  }
+  return cfg
+}
+
+function seatFromRaw(raw: RawExpert, index: number, fallbackRole: string): ExpertSeat {
+  const model = raw.model ?? raw.requested_model ?? ""
+  return {
+    id: raw.id ?? raw.name ?? `Expert ${String.fromCharCode(65 + index)}`,
+    role: raw.role ?? fallbackRole,
+    model,
+    maxTokens: raw.max_tokens ?? raw.maxTokens,
+  }
+}
+
+/** Normalize either experts shape into an ordered list with roles attached. */
+function normalizeExperts(experts: RawProfile["experts"]): Array<{ raw: RawExpert; role: string }> {
+  if (!experts) return []
+  if (Array.isArray(experts)) {
+    return experts.map((raw, i) => ({ raw, role: raw.role ?? `expert${i}` }))
+  }
+  // Object form: the KEY is the role, which is how xp-gate writes it.
+  return Object.entries(experts).map(([role, raw]) => ({ raw, role }))
+}
+
+/**
+ * Turn raw config into a ready-to-run review setup.
+ * Fails loudly and specifically: a missing key or an unexpanded placeholder is
+ * the most common way a Delphi run silently degrades.
+ */
+export function resolveConfig(
+  cfg: RawDelphiConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedDelphiConfig {
+  const profile = selectProfile(cfg)
+  const normalized = normalizeExperts(profile.experts)
+
+  // An expert may name its own provider; otherwise there must be a profile-wide
+  // default. Resolve base_url/api_key per provider so mixed setups work.
+  const providerNames = new Set(
+    normalized.map((e) => e.raw.provider ?? profile.provider).filter((p): p is string => !!p),
+  )
+  if (providerNames.size === 0) {
+    throw new DelphiSetupError(
+      'No provider configured. Set "provider" on the profile or on each expert.',
+    )
+  }
+
+  const providerTable = profile.providers ?? {}
+  const resolvedProviders = new Map<string, { baseUrl: string; apiKey: string }>()
+  for (const name of providerNames) {
+    const entry = providerTable[name]
+    if (!entry) {
+      throw new DelphiSetupError(
+        `Provider "${name}" is not defined under "providers". ` +
+          `Known: ${Object.keys(providerTable).join(", ") || "(none)"}`,
+      )
+    }
+    const baseUrl = entry.base_url ?? entry.baseUrl ?? ""
+    if (!baseUrl) throw new DelphiSetupError(`Provider "${name}" has no base_url.`)
+
+    const rawKey = entry.api_key ?? entry.apiKey ?? ""
+    const apiKey = expandEnv(rawKey, env)
+    if (!apiKey) {
+      // Name the variable rather than echoing config, which may hold a literal key.
+      const varName =
+        /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/.exec(rawKey)?.[1] ??
+        /\{env:([A-Za-z_][A-Za-z0-9_]*)\}/.exec(rawKey)?.[1]
+      throw new DelphiSetupError(
+        varName
+          ? `API key variable ${varName} is not set in the environment.`
+          : `Provider "${name}" has no api_key.`,
+      )
+    }
+    resolvedProviders.set(name, { baseUrl, apiKey })
+  }
+
+  const seats = normalized.map((e, i) => seatFromRaw(e.raw, i, e.role))
+  // Surface an unexpanded placeholder as a config error, not a provider 404.
+  for (const s of seats) {
+    if (s.model.includes("${") || s.model.includes("{env:")) {
+      throw new DelphiSetupError(
+        `Expert "${s.id}" model "${s.model}" is an unexpanded placeholder.`,
+      )
+    }
+  }
+  validateSeats(seats)
+
+  // All seats share one gateway in the supported setup; require agreement so a
+  // mixed list cannot silently send one seat's key to another host.
+  const chosen = resolvedProviders.get(normalized[0].raw.provider ?? profile.provider ?? "")
+  if (!chosen) throw new DelphiSetupError("Unable to resolve a provider for the first expert.")
+  for (const e of normalized) {
+    const name = e.raw.provider ?? profile.provider ?? ""
+    const other = resolvedProviders.get(name)
+    if (!other || other.baseUrl !== chosen.baseUrl) {
+      throw new DelphiSetupError(
+        `All experts must share one gateway base_url; "${name}" differs. ` +
+          `Split the review or align the providers.`,
+      )
+    }
+  }
+
+  // consensus may sit on the profile or at the document root; both occur.
+  const consensus = profile.consensus ?? cfg.consensus
+
+  return {
+    seats,
+    baseUrl: chosen.baseUrl,
+    apiKey: chosen.apiKey,
+    thresholdPercent: consensus?.threshold_percent ?? 90,
+    maxRounds: consensus?.max_review_rounds ?? 5,
+    provider: normalized[0].raw.provider ?? profile.provider ?? "",
+  }
+}
+
+/** Read and resolve `.delphi-config.json` from a project root. */
+export function loadDelphiConfig(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedDelphiConfig {
+  const path = resolve(cwd, ".delphi-config.json")
+  let raw: string
+  try {
+    raw = readFileSync(path, "utf8")
+  } catch {
+    throw new DelphiSetupError(`No .delphi-config.json found at ${path}.`)
+  }
+  let parsed: RawDelphiConfig
+  try {
+    parsed = JSON.parse(raw) as RawDelphiConfig
+  } catch (e) {
+    throw new DelphiSetupError(`.delphi-config.json is not valid JSON: ${(e as Error).message}`)
+  }
+  return resolveConfig(parsed, env)
+}
+
+/** Build the transport options a round needs from a resolved config. */
+export function toDelphiOptions(cfg: ResolvedDelphiConfig): DelphiOptions {
+  return {
+    baseUrl: cfg.baseUrl,
+    apiKey: cfg.apiKey,
+    seats: cfg.seats,
+    thresholdPercent: cfg.thresholdPercent,
+    maxRounds: cfg.maxRounds,
+  }
+}