dsh-d365-kit 0.34.1 → 0.34.3

package/lib/data-policy.js

@@ -1,78 +1,78 @@
-/**
- * Decide whether one environment may touch business records.
- *
- * Metadata is readable by default; business tables need `data.read`, and
- * writing business records needs `data.write`. Both can be revoked per
- * environment. The answer is cached for a moment because a single tool call can
- * issue hundreds of requests, and the settings page may change the policy at
- * any time.
- */
-import { loadConfig } from './config.js'
-import { allows, readPolicy } from './write-policy.js'
-
-const TTL_MS = 2_000
-
-/**
- * Build a resolver for one capability.
- *
- * @param getRawConfig - returns the plugin's raw config (so the config file can move).
- * @param capability - policy key, e.g. `data.read`.
- * @returns async function (envKey) => boolean.
- */
-export function makeCapabilityResolver(getRawConfig, capability) {
-  let cache = { path: undefined, at: 0, policy: null }
-
-  return async function allowsCapability(envKey) {
-    try {
-      const config = await loadConfig(getRawConfig() ?? {})
-      const path = config.configFile ?? null
-      const now = Date.now()
-      if (cache.path !== path || now - cache.at > TTL_MS) {
-        cache = { path, at: now, policy: await readPolicy(path) }
-      }
-      return allows(cache.policy, envKey, capability)
-    } catch {
-      return false
-    }
-  }
-}
-
-/** @returns async function (envKey) => boolean for `data.read`. */
-export function makeDataReadResolver(getRawConfig) {
-  return makeCapabilityResolver(getRawConfig, 'data.read')
-}
-
-/** @returns async function (envKey) => boolean for `data.write`. */
-export function makeDataWriteResolver(getRawConfig) {
-  return makeCapabilityResolver(getRawConfig, 'data.write')
-}
-
-/** @returns async function (envKey) => boolean for `metadata.read`. */
-export function makeMetadataReadResolver(getRawConfig) {
-  return makeCapabilityResolver(getRawConfig, 'metadata.read')
-}
-
-/**
- * Resolver for tools that name their capability on the request itself.
- *
- * `d365_invoke` passes `message.invoke` on its own request; instead of adding a
- * fourth resolver per capability, resolve any key from the same policy file.
- * @returns async function (envKey, capability) => boolean.
- */
-export function makeAnyCapabilityResolver(getRawConfig) {
-  let cache = { path: undefined, at: 0, policy: null }
-
-  return async function allowsAnyCapability(envKey, capability) {
-    try {
-      const config = await loadConfig(getRawConfig() ?? {})
-      const path = config.configFile ?? null
-      const now = Date.now()
-      if (cache.path !== path || now - cache.at > TTL_MS) {
-        cache = { path, at: now, policy: await readPolicy(path) }
-      }
-      return allows(cache.policy, envKey, capability)
-    } catch {
-      return false
-    }
-  }
-}
+/**
+ * Decide whether one environment may touch business records.
+ *
+ * Metadata is readable by default; business tables need `data.read`, and
+ * writing business records needs `data.write`. Both can be revoked per
+ * environment. The answer is cached for a moment because a single tool call can
+ * issue hundreds of requests, and the settings page may change the policy at
+ * any time.
+ */
+import { loadConfig } from './config.js'
+import { allows, readPolicy } from './write-policy.js'
+
+const TTL_MS = 2_000
+
+/**
+ * Build a resolver for one capability.
+ *
+ * @param getRawConfig - returns the plugin's raw config (so the config file can move).
+ * @param capability - policy key, e.g. `data.read`.
+ * @returns async function (envKey) => boolean.
+ */
+export function makeCapabilityResolver(getRawConfig, capability) {
+  let cache = { path: undefined, at: 0, policy: null }
+
+  return async function allowsCapability(envKey) {
+    try {
+      const config = await loadConfig(getRawConfig() ?? {})
+      const path = config.configFile ?? null
+      const now = Date.now()
+      if (cache.path !== path || now - cache.at > TTL_MS) {
+        cache = { path, at: now, policy: await readPolicy(path) }
+      }
+      return allows(cache.policy, envKey, capability)
+    } catch {
+      return false
+    }
+  }
+}
+
+/** @returns async function (envKey) => boolean for `data.read`. */
+export function makeDataReadResolver(getRawConfig) {
+  return makeCapabilityResolver(getRawConfig, 'data.read')
+}
+
+/** @returns async function (envKey) => boolean for `data.write`. */
+export function makeDataWriteResolver(getRawConfig) {
+  return makeCapabilityResolver(getRawConfig, 'data.write')
+}
+
+/** @returns async function (envKey) => boolean for `metadata.read`. */
+export function makeMetadataReadResolver(getRawConfig) {
+  return makeCapabilityResolver(getRawConfig, 'metadata.read')
+}
+
+/**
+ * Resolver for tools that name their capability on the request itself.
+ *
+ * `d365_invoke` passes `message.invoke` on its own request; instead of adding a
+ * fourth resolver per capability, resolve any key from the same policy file.
+ * @returns async function (envKey, capability) => boolean.
+ */
+export function makeAnyCapabilityResolver(getRawConfig) {
+  let cache = { path: undefined, at: 0, policy: null }
+
+  return async function allowsAnyCapability(envKey, capability) {
+    try {
+      const config = await loadConfig(getRawConfig() ?? {})
+      const path = config.configFile ?? null
+      const now = Date.now()
+      if (cache.path !== path || now - cache.at > TTL_MS) {
+        cache = { path, at: now, policy: await readPolicy(path) }
+      }
+      return allows(cache.policy, envKey, capability)
+    } catch {
+      return false
+    }
+  }
+}

package/lib/error-codes.js

@@ -1,80 +1,80 @@
-/**
- * Dataverse error codes that are worth explaining on the spot.
- *
- * A `0x80048d19` with no interpretation costs a person an hour: the message
- * says the *shape* of one property is wrong, not which rule was broken. This
- * table turns the code into the next thing to check. It is deliberately small:
- * only codes whose cause is unambiguous get an entry, because a wrong hint is
- * worse than none.
- */
-
-export const ERROR_CODES = {
-  '0x80048d19': {
-    summary: '载荷里某个属性的形状不对：服务端在读一个标量值，报文里却是注解、对象或 null 以外的结构（常见于 lookup）',
-    hint: 'lookup 要写成 "<导航属性名>@odata.bind": "/<集合名>(<guid>)"，不是字段逻辑名、也不是裸 GUID；选项集写数值、多选写数组、布尔写 true/false。导航属性名与字段逻辑名可能只是大小写不同（contoso_approverid → contoso_ApproverId），用 d365_metadata resource=one_to_many_relationships 看 ReferencingEntityNavigationPropertyName。',
-  },
-  '0x80060888': {
-    summary: '请求里有一个这个端点不认识的属性名或查询参数',
-    hint: '元数据端点（EntityDefinitions / GlobalOptionSetDefinitions 等）不接受 $top、$orderby、$filter 的部分组合；派生属性（如 DefaultValue、Targets、Options）要先用 cast 到具体类型才能 select。工具已经会逐列剔除并重试，仍失败说明名字本身写错了。',
-  },
-  '0x80040216': {
-    summary: '对象不存在：按这个名字或 id 找不到记录',
-    hint: '先确认环境对不对（不同环境的自定义表可用性不同），再用不带 filter 的查询确认记录真的存在。',
-  },
-  '0x80040217': {
-    summary: '对象不存在：按这个名字或 id 找不到记录',
-    hint: '先确认环境对不对（不同环境的自定义表可用性不同），再用不带 filter 的查询确认记录真的存在。',
-  },
-  '0x80040333': {
-    summary: '重复检测规则拦截了这次创建：目标里已有匹配的记录',
-    hint: '先查目标环境里是否已有同名/同键记录，按需要改成 update 或对这条记录开启 MSCRM.SuppressDuplicateDetection。',
-  },
-  '0x80044150': {
-    summary: '记录在读取之后被别人改过（并发冲突 / 状态已变化）',
-    hint: '重新读一次当前行再决定怎么写；如果是状态字段，确认它现在是不是已经是你想要的值。',
-  },
-  '0x80048423': {
-    summary: '组件属于某个受管解决方案，不能在这里直接改',
-    hint: '受管组件只能在源环境改，再作为新版本导入；要在当前环境改就先把它变成非受管（或建一个新的非受管组件）。',
-  },
-  '0x8004a0f6': {
-    summary: '操作违反了当前记录状态：状态机不允许这一步',
-    hint: '先看 statecode/statuscode 与业务流程阶段，撤销/激活类操作只能在特定状态下执行。',
-  },
-}
-
-/** Pull the first `0x........` token out of a string. */
-export function errorCodeFromText(text) {
-  const match = /0x[0-9a-fA-F]{8}/.exec(String(text ?? ''))
-  return match ? match[0].toLowerCase() : undefined
-}
-
-/**
- * Pull the Dataverse error code out of a decoded response body.
- * Dataverse puts it in `error.code`, but some endpoints put it in the message.
- */
-export function errorCodeFromBody(body) {
-  if (!body) return undefined
-  if (typeof body === 'string') return errorCodeFromText(body)
-  const root = body.error ?? body
-  const code = root?.code ?? root?.Code ?? root?.errorcode
-  if (typeof code === 'number') return `0x${code.toString(16).padStart(8, '0')}`
-  if (code) {
-    const text = errorCodeFromText(code)
-    if (text) return text
-  }
-  return errorCodeFromText(root?.message ?? root?.Message)
-}
-
-/** @returns the explanation for a known code, or undefined. */
-export function explainErrorCode(code) {
-  const key = String(code ?? '').toLowerCase()
-  return ERROR_CODES[key]
-}
-
-/** @returns a one-line hint for a known code, or undefined. */
-export function hintForErrorCode(code) {
-  const entry = explainErrorCode(code)
-  if (!entry) return undefined
-  return `${entry.summary}。${entry.hint}`
-}
+/**
+ * Dataverse error codes that are worth explaining on the spot.
+ *
+ * A `0x80048d19` with no interpretation costs a person an hour: the message
+ * says the *shape* of one property is wrong, not which rule was broken. This
+ * table turns the code into the next thing to check. It is deliberately small:
+ * only codes whose cause is unambiguous get an entry, because a wrong hint is
+ * worse than none.
+ */
+
+export const ERROR_CODES = {
+  '0x80048d19': {
+    summary: '载荷里某个属性的形状不对：服务端在读一个标量值，报文里却是注解、对象或 null 以外的结构（常见于 lookup）',
+    hint: 'lookup 要写成 "<导航属性名>@odata.bind": "/<集合名>(<guid>)"，不是字段逻辑名、也不是裸 GUID；选项集写数值、多选写数组、布尔写 true/false。导航属性名与字段逻辑名可能只是大小写不同（contoso_approverid → contoso_ApproverId），用 d365_metadata resource=one_to_many_relationships 看 ReferencingEntityNavigationPropertyName。',
+  },
+  '0x80060888': {
+    summary: '请求里有一个这个端点不认识的属性名或查询参数',
+    hint: '元数据端点（EntityDefinitions / GlobalOptionSetDefinitions 等）不接受 $top、$orderby、$filter 的部分组合；派生属性（如 DefaultValue、Targets、Options）要先用 cast 到具体类型才能 select。工具已经会逐列剔除并重试，仍失败说明名字本身写错了。',
+  },
+  '0x80040216': {
+    summary: '对象不存在：按这个名字或 id 找不到记录',
+    hint: '先确认环境对不对（不同环境的自定义表可用性不同），再用不带 filter 的查询确认记录真的存在。',
+  },
+  '0x80040217': {
+    summary: '对象不存在：按这个名字或 id 找不到记录',
+    hint: '先确认环境对不对（不同环境的自定义表可用性不同），再用不带 filter 的查询确认记录真的存在。',
+  },
+  '0x80040333': {
+    summary: '重复检测规则拦截了这次创建：目标里已有匹配的记录',
+    hint: '先查目标环境里是否已有同名/同键记录，按需要改成 update 或对这条记录开启 MSCRM.SuppressDuplicateDetection。',
+  },
+  '0x80044150': {
+    summary: '记录在读取之后被别人改过（并发冲突 / 状态已变化）',
+    hint: '重新读一次当前行再决定怎么写；如果是状态字段，确认它现在是不是已经是你想要的值。',
+  },
+  '0x80048423': {
+    summary: '组件属于某个受管解决方案，不能在这里直接改',
+    hint: '受管组件只能在源环境改，再作为新版本导入；要在当前环境改就先把它变成非受管（或建一个新的非受管组件）。',
+  },
+  '0x8004a0f6': {
+    summary: '操作违反了当前记录状态：状态机不允许这一步',
+    hint: '先看 statecode/statuscode 与业务流程阶段，撤销/激活类操作只能在特定状态下执行。',
+  },
+}
+
+/** Pull the first `0x........` token out of a string. */
+export function errorCodeFromText(text) {
+  const match = /0x[0-9a-fA-F]{8}/.exec(String(text ?? ''))
+  return match ? match[0].toLowerCase() : undefined
+}
+
+/**
+ * Pull the Dataverse error code out of a decoded response body.
+ * Dataverse puts it in `error.code`, but some endpoints put it in the message.
+ */
+export function errorCodeFromBody(body) {
+  if (!body) return undefined
+  if (typeof body === 'string') return errorCodeFromText(body)
+  const root = body.error ?? body
+  const code = root?.code ?? root?.Code ?? root?.errorcode
+  if (typeof code === 'number') return `0x${code.toString(16).padStart(8, '0')}`
+  if (code) {
+    const text = errorCodeFromText(code)
+    if (text) return text
+  }
+  return errorCodeFromText(root?.message ?? root?.Message)
+}
+
+/** @returns the explanation for a known code, or undefined. */
+export function explainErrorCode(code) {
+  const key = String(code ?? '').toLowerCase()
+  return ERROR_CODES[key]
+}
+
+/** @returns a one-line hint for a known code, or undefined. */
+export function hintForErrorCode(code) {
+  const entry = explainErrorCode(code)
+  if (!entry) return undefined
+  return `${entry.summary}。${entry.hint}`
+}

package/lib/gitlab.js

@@ -1,161 +1,161 @@
-/**
- * Read-only GitLab access for the diff-driven code check.
- *
- * Only one thing is needed: the list of files a merge request touches, with
- * their unified diffs. Everything else (mapping paths to Dataverse components,
- * comparing against an environment) lives in `code-check.js`.
- *
- * The token comes from `D365_GITLAB_TOKEN` / `GITLAB_TOKEN`, else from the
- * secrets file the settings page writes. It never travels to the browser.
- */
-import { readGitlabToken } from './config.js'
-import { D365Error } from './errors.js'
-
-const TIMEOUT_MS = 30_000
-
-/**
- * Parse a GitLab merge-request URL.
- * @param value - e.g. `https://gitlab.example.com/g/p/-/merge_requests/42/diffs`
- * @returns `{ base, project, iid }` or null when the string is not a MR URL.
- */
-export function parseMergeRequestUrl(value) {
-  const text = String(value ?? '').trim()
-  const match = text.match(/^(https?:\/\/[^/]+)\/(.+?)\/-\/merge_requests\/(\d+)/i)
-  if (!match) return null
-  return { base: match[1], project: match[2], iid: match[3] }
-}
-
-/** `https://host` → `https://host/api/v4`, tolerating a trailing slash. */
-export function apiBase(url) {
-  return `${String(url ?? '').trim().replace(/\/+$/, '')}/api/v4`
-}
-
-function describeHttp(status, body) {
-  const message = String(body ?? '').slice(0, 300).replace(/\s+/g, ' ')
-  if (status === 401) return 'GitLab 令牌无效或已过期（HTTP 401）'
-  if (status === 403) {
-    return 'GitLab 拒绝了访问（HTTP 403）：令牌 scope 不足，或该用户在项目里的角色低于 Reporter'
-      + '（项目访问令牌的角色若是 Guest，读不到 MR 与仓库）。把角色改成 Reporter 以上，或改用个人访问令牌'
-  }
-  if (status === 404) return 'GitLab 找不到项目或 MR（HTTP 404），检查项目路径与 IID'
-  return `GitLab 返回 HTTP ${status}：${message}`
-}
-
-/**
- * Call one GitLab API path and parse JSON.
- * @param config - loaded plugin config (supplies `gitlab.url` and the secrets path).
- * @param path - path beginning with `/`, e.g. `/projects/g%2Fp`.
- */
-export async function gitlabGet(config, path, signal) {
-  const url = config.gitlab?.url
-  const token = await readGitlabToken(config)
-  if (!url) {
-    throw new D365Error('没有配置 GitLab 地址', {
-      code: 'gitlab-not-configured',
-      hint: '在设置 →「D365 环境」→ GitLab 里填仓库地址与访问令牌。',
-    })
-  }
-  if (!token.ok) {
-    throw new D365Error('没有配置 GitLab 访问令牌', {
-      code: 'gitlab-no-token',
-      hint: '在设置页填只读令牌（read_api），或设置环境变量 D365_GITLAB_TOKEN。',
-    })
-  }
-
-  const controller = new AbortController()
-  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
-  const onAbort = () => controller.abort()
-  signal?.addEventListener?.('abort', onAbort, { once: true })
-  try {
-    const response = await fetch(`${apiBase(url)}${path}`, {
-      headers: { 'PRIVATE-TOKEN': token.value, accept: 'application/json' },
-      signal: controller.signal,
-    })
-    const body = await response.text()
-    if (!response.ok) {
-      throw new D365Error(describeHttp(response.status, body), { code: 'gitlab-http' })
-    }
-    return body ? JSON.parse(body) : null
-  } catch (error) {
-    if (error?.name === 'AbortError') {
-      throw new D365Error(`请求 GitLab 超时（${TIMEOUT_MS}ms）`, { code: 'gitlab-timeout' })
-    }
-    throw error
-  } finally {
-    clearTimeout(timer)
-    signal?.removeEventListener?.('abort', onAbort)
-  }
-}
-
-/**
- * Fetch one merge request's changes.
- * @param config - loaded plugin config.
- * @param request - `{ mergeRequest, project? }`; mergeRequest may be a URL, an
- *   IID, or `!123`.
- * @returns `{ project, iid, title, webUrl, sourceBranch, targetBranch, changes }`
- *   where each change is `{ oldPath, newPath, newFile, deletedFile, renamedFile, diff }`.
- */
-export async function fetchMergeRequest(config, request, signal) {
-  const raw = String(request?.mergeRequest ?? '').trim()
-  if (!raw) {
-    throw new D365Error('缺少 mergeRequest', {
-      code: 'missing-merge-request',
-      hint: '传 MR 链接，或项目路径 + IID。',
-    })
-  }
-
-  const parsed = parseMergeRequestUrl(raw)
-  const projectPath = parsed?.project
-    ?? String(request?.project ?? config.gitlab?.defaultProject ?? '').trim()
-  const iid = parsed?.iid ?? raw.replace(/^!/, '')
-
-  if (!projectPath) {
-    throw new D365Error('无法确定 GitLab 项目', {
-      code: 'gitlab-no-project',
-      hint: '传完整的 MR 链接，或在设置页填默认项目（group/project）。',
-    })
-  }
-  if (!/^\d+$/.test(iid)) {
-    throw new D365Error(`MR IID 不是数字：${iid}`, {
-      code: 'invalid-merge-request',
-      hint: '例如 https://gitlab.example.com/group/project/-/merge_requests/42',
-    })
-  }
-
-  const data = await gitlabGet(
-    config,
-    `/projects/${encodeURIComponent(projectPath)}/merge_requests/${iid}/changes`,
-    signal,
-  )
-
-  return {
-    project: data?.project_id ? String(projectPath) : projectPath,
-    iid,
-    title: data?.title ?? '',
-    webUrl: data?.web_url ?? (parsed ? raw.split('/diffs')[0] : ''),
-    sourceBranch: data?.source_branch ?? '',
-    targetBranch: data?.target_branch ?? '',
-    changes: (data?.changes ?? []).map((change) => ({
-      oldPath: change.old_path ?? change.new_path,
-      newPath: change.new_path ?? change.old_path,
-      newFile: change.new_file === true,
-      deletedFile: change.deleted_file === true,
-      renamedFile: change.renamed_file === true,
-      diff: change.diff ?? '',
-    })),
-  }
-}
-
-/**
- * Prove the configured token can reach the configured host.
- * @returns `{ ok, user?, error? }` — never throws, so the settings page can
- *   show the result next to the form.
- */
-export async function checkGitlab(config) {
-  try {
-    const user = await gitlabGet(config, '/user')
-    return { ok: true, user: user?.username ?? '', name: user?.name ?? '' }
-  } catch (error) {
-    return { ok: false, error: error.message, hint: error.hint }
-  }
-}
+/**
+ * Read-only GitLab access for the diff-driven code check.
+ *
+ * Only one thing is needed: the list of files a merge request touches, with
+ * their unified diffs. Everything else (mapping paths to Dataverse components,
+ * comparing against an environment) lives in `code-check.js`.
+ *
+ * The token comes from `D365_GITLAB_TOKEN` / `GITLAB_TOKEN`, else from the
+ * secrets file the settings page writes. It never travels to the browser.
+ */
+import { readGitlabToken } from './config.js'
+import { D365Error } from './errors.js'
+
+const TIMEOUT_MS = 30_000
+
+/**
+ * Parse a GitLab merge-request URL.
+ * @param value - e.g. `https://gitlab.example.com/g/p/-/merge_requests/42/diffs`
+ * @returns `{ base, project, iid }` or null when the string is not a MR URL.
+ */
+export function parseMergeRequestUrl(value) {
+  const text = String(value ?? '').trim()
+  const match = text.match(/^(https?:\/\/[^/]+)\/(.+?)\/-\/merge_requests\/(\d+)/i)
+  if (!match) return null
+  return { base: match[1], project: match[2], iid: match[3] }
+}
+
+/** `https://host` → `https://host/api/v4`, tolerating a trailing slash. */
+export function apiBase(url) {
+  return `${String(url ?? '').trim().replace(/\/+$/, '')}/api/v4`
+}
+
+function describeHttp(status, body) {
+  const message = String(body ?? '').slice(0, 300).replace(/\s+/g, ' ')
+  if (status === 401) return 'GitLab 令牌无效或已过期（HTTP 401）'
+  if (status === 403) {
+    return 'GitLab 拒绝了访问（HTTP 403）：令牌 scope 不足，或该用户在项目里的角色低于 Reporter'
+      + '（项目访问令牌的角色若是 Guest，读不到 MR 与仓库）。把角色改成 Reporter 以上，或改用个人访问令牌'
+  }
+  if (status === 404) return 'GitLab 找不到项目或 MR（HTTP 404），检查项目路径与 IID'
+  return `GitLab 返回 HTTP ${status}：${message}`
+}
+
+/**
+ * Call one GitLab API path and parse JSON.
+ * @param config - loaded plugin config (supplies `gitlab.url` and the secrets path).
+ * @param path - path beginning with `/`, e.g. `/projects/g%2Fp`.
+ */
+export async function gitlabGet(config, path, signal) {
+  const url = config.gitlab?.url
+  const token = await readGitlabToken(config)
+  if (!url) {
+    throw new D365Error('没有配置 GitLab 地址', {
+      code: 'gitlab-not-configured',
+      hint: '在设置 →「D365 环境」→ GitLab 里填仓库地址与访问令牌。',
+    })
+  }
+  if (!token.ok) {
+    throw new D365Error('没有配置 GitLab 访问令牌', {
+      code: 'gitlab-no-token',
+      hint: '在设置页填只读令牌（read_api），或设置环境变量 D365_GITLAB_TOKEN。',
+    })
+  }
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
+  const onAbort = () => controller.abort()
+  signal?.addEventListener?.('abort', onAbort, { once: true })
+  try {
+    const response = await fetch(`${apiBase(url)}${path}`, {
+      headers: { 'PRIVATE-TOKEN': token.value, accept: 'application/json' },
+      signal: controller.signal,
+    })
+    const body = await response.text()
+    if (!response.ok) {
+      throw new D365Error(describeHttp(response.status, body), { code: 'gitlab-http' })
+    }
+    return body ? JSON.parse(body) : null
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw new D365Error(`请求 GitLab 超时（${TIMEOUT_MS}ms）`, { code: 'gitlab-timeout' })
+    }
+    throw error
+  } finally {
+    clearTimeout(timer)
+    signal?.removeEventListener?.('abort', onAbort)
+  }
+}
+
+/**
+ * Fetch one merge request's changes.
+ * @param config - loaded plugin config.
+ * @param request - `{ mergeRequest, project? }`; mergeRequest may be a URL, an
+ *   IID, or `!123`.
+ * @returns `{ project, iid, title, webUrl, sourceBranch, targetBranch, changes }`
+ *   where each change is `{ oldPath, newPath, newFile, deletedFile, renamedFile, diff }`.
+ */
+export async function fetchMergeRequest(config, request, signal) {
+  const raw = String(request?.mergeRequest ?? '').trim()
+  if (!raw) {
+    throw new D365Error('缺少 mergeRequest', {
+      code: 'missing-merge-request',
+      hint: '传 MR 链接，或项目路径 + IID。',
+    })
+  }
+
+  const parsed = parseMergeRequestUrl(raw)
+  const projectPath = parsed?.project
+    ?? String(request?.project ?? config.gitlab?.defaultProject ?? '').trim()
+  const iid = parsed?.iid ?? raw.replace(/^!/, '')
+
+  if (!projectPath) {
+    throw new D365Error('无法确定 GitLab 项目', {
+      code: 'gitlab-no-project',
+      hint: '传完整的 MR 链接，或在设置页填默认项目（group/project）。',
+    })
+  }
+  if (!/^\d+$/.test(iid)) {
+    throw new D365Error(`MR IID 不是数字：${iid}`, {
+      code: 'invalid-merge-request',
+      hint: '例如 https://gitlab.example.com/group/project/-/merge_requests/42',
+    })
+  }
+
+  const data = await gitlabGet(
+    config,
+    `/projects/${encodeURIComponent(projectPath)}/merge_requests/${iid}/changes`,
+    signal,
+  )
+
+  return {
+    project: data?.project_id ? String(projectPath) : projectPath,
+    iid,
+    title: data?.title ?? '',
+    webUrl: data?.web_url ?? (parsed ? raw.split('/diffs')[0] : ''),
+    sourceBranch: data?.source_branch ?? '',
+    targetBranch: data?.target_branch ?? '',
+    changes: (data?.changes ?? []).map((change) => ({
+      oldPath: change.old_path ?? change.new_path,
+      newPath: change.new_path ?? change.old_path,
+      newFile: change.new_file === true,
+      deletedFile: change.deleted_file === true,
+      renamedFile: change.renamed_file === true,
+      diff: change.diff ?? '',
+    })),
+  }
+}
+
+/**
+ * Prove the configured token can reach the configured host.
+ * @returns `{ ok, user?, error? }` — never throws, so the settings page can
+ *   show the result next to the form.
+ */
+export async function checkGitlab(config) {
+  try {
+    const user = await gitlabGet(config, '/user')
+    return { ok: true, user: user?.username ?? '', name: user?.name ?? '' }
+  } catch (error) {
+    return { ok: false, error: error.message, hint: error.hint }
+  }
+}