flower-trellis 0.6.2 → 0.6.3

package/src/plugin/auth/gitlab-credential-resolver.js

@@ -0,0 +1,234 @@
+import { execFile } from "node:child_process";
+import { PLUGIN_RUNTIME_ERROR_CODES, PluginRuntimeError } from "../runtime-errors.js";
+
+const GLAB_COMMAND = "glab";
+const GLAB_AUTH_TIMEOUT_MS = 5_000;
+const GLAB_AUTH_MAX_BUFFER = 1024 * 1024;
+const HOST_BOUND_TOKEN_NAMES = ["FLOWER_GITLAB_TOKEN", "GITLAB_TOKEN", "GLAB_TOKEN"];
+const HOST_BOUND_HOST_NAMES = ["FLOWER_GITLAB_HOST", "GITLAB_HOST", "GLAB_HOST", "CI_SERVER_HOST", "CI_SERVER_URL"];
+
+/**
+ * 返回 GitLab source 的小写 host[:port]。
+ *
+ * @param {{baseUrl:string}} source GitLab 来源
+ * @returns {string} host[:port]
+ */
+export function gitLabCredentialHost(source) {
+  return new URL(source.baseUrl).host.toLowerCase();
+}
+
+/**
+ * 把 host、origin 或项目 URL 规范化为小写 host[:port]。
+ *
+ * @param {unknown} value 原始 host 或 URL
+ * @returns {string|null} 规范化 host；无法解析时返回 null
+ */
+export function normalizeGitLabCredentialHost(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return null;
+  try {
+    const url = /^https?:\/\//i.test(raw) ? new URL(raw) : new URL(`https://${raw.replace(/^\/+/, "")}`);
+    return url.host.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 判断原始 host/URL 是否与 GitLab source 完全同 host。
+ *
+ * @param {unknown} value 原始 host 或 URL
+ * @param {{baseUrl:string}} source GitLab 来源
+ * @returns {boolean} 是否同 host
+ */
+export function isSameGitLabCredentialHost(value, source) {
+  return normalizeGitLabCredentialHost(value) === gitLabCredentialHost(source);
+}
+
+/**
+ * 从 `glab auth status --show-token` 输出中提取同 host token。
+ *
+ * @param {string} output glab stdout/stderr 合并文本
+ * @param {{baseUrl:string}} source GitLab 来源
+ * @returns {string|null} access token；无法证明同 host 或未输出 token 时返回 null
+ */
+export function parseGlabAuthStatusToken(output, source) {
+  const text = String(output || "");
+  const host = gitLabCredentialHost(source);
+  const escapedHost = host.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const hostPattern = new RegExp(`(^|[^A-Za-z0-9.-])${escapedHost}($|[^A-Za-z0-9.-])`, "i");
+  if (!hostPattern.test(text)) return null;
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.match(/\btoken\b[^:]*:\s*([^\s]+)/i);
+    if (!match) continue;
+    const token = match[1].replace(/^['"]|['"]$/g, "");
+    if (!token || token.includes("*") || token === "[REDACTED]") continue;
+    return token;
+  }
+  return null;
+}
+
+/**
+ * 从 host 绑定的环境变量中解析 GitLab token。
+ *
+ * @param {{baseUrl:string}} source GitLab 来源
+ * @param {NodeJS.ProcessEnv|Record<string,string|undefined>} [env] 环境变量
+ * @returns {{authorized:true,scopes:string[],expiresAt:null,persistent:false,accessToken:string,credentialSource:"env"}|null} 环境凭据
+ */
+export function resolveGitLabEnvironmentCredential(source, env = process.env) {
+  const hostKey = gitLabCredentialHost(source).toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+  for (const name of HOST_BOUND_TOKEN_NAMES.map((prefix) => `${prefix}_${hostKey}`)) {
+    const accessToken = String(env[name] || "").trim();
+    if (accessToken) return externalCredential(accessToken, "env");
+  }
+  const hostMatched = HOST_BOUND_HOST_NAMES.some((name) => isSameGitLabCredentialHost(env[name], source));
+  if (!hostMatched) return null;
+  for (const name of HOST_BOUND_TOKEN_NAMES) {
+    const accessToken = String(env[name] || "").trim();
+    if (accessToken) return externalCredential(accessToken, "env");
+  }
+  return null;
+}
+
+/**
+ * 默认执行 glab 的安全包装。
+ *
+ * @param {string[]} args glab 参数
+ * @param {{command?:string,timeoutMs?:number}} [options] 命令配置
+ * @returns {Promise<{stdout:string,stderr:string}>} 子进程输出
+ */
+export async function runGlab(args, options = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(options.command || GLAB_COMMAND, args, {
+      timeout: options.timeoutMs || GLAB_AUTH_TIMEOUT_MS,
+      maxBuffer: GLAB_AUTH_MAX_BUFFER,
+      windowsHide: true,
+    }, (error, stdout, stderr) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+/**
+ * GitLab 凭据解析器，统一 Flower Keyring、glab 与环境 fallback。
+ */
+export class GitLabCredentialResolver {
+  /**
+   * 创建 GitLab 凭据解析器。
+   *
+   * @param {{store:import("./credential-store.js").CredentialStore,persistent?:boolean,env?:NodeJS.ProcessEnv|Record<string,string|undefined>,runGlab?:(args:string[],options?:object)=>Promise<{stdout?:string,stderr?:string}>,glabCommand?:string,glabTimeoutMs?:number}} options 依赖注入
+   */
+  constructor(options) {
+    this.store = options.store;
+    this.persistent = Boolean(options.persistent);
+    this.env = options.env || process.env;
+    this.runGlab = options.runGlab || runGlab;
+    this.glabCommand = options.glabCommand || GLAB_COMMAND;
+    this.glabTimeoutMs = options.glabTimeoutMs || GLAB_AUTH_TIMEOUT_MS;
+  }
+
+  /**
+   * 按 Flower Keyring、glab、环境变量顺序解析凭据。
+   *
+   * @param {object} source GitLab 来源
+   * @returns {Promise<{authorized:boolean,scopes:string[],expiresAt:number|null,persistent:boolean,accessToken?:string,credentialSource?:string,credential?:object}>} 解析结果
+   */
+  async resolve(source) {
+    const credential = await this.store.get(source);
+    if (credential) {
+      return {
+        authorized: true,
+        scopes: credential.scope,
+        expiresAt: credential.expiresAt,
+        persistent: this.persistent,
+        accessToken: credential.accessToken,
+        credentialSource: "flower",
+        credential,
+      };
+    }
+    const external = await this.resolveExternal(source);
+    return external || {
+      authorized: false,
+      scopes: [],
+      expiresAt: null,
+      persistent: false,
+    };
+  }
+
+  /**
+   * 解析非 Flower 管理的全局 GitLab 凭据。
+   *
+   * @param {object} source GitLab 来源
+   * @returns {Promise<{authorized:true,scopes:string[],expiresAt:null,persistent:false,accessToken:string,credentialSource:string}|null>} 外部凭据
+   */
+  async resolveExternal(source) {
+    const glabCredential = await this.#resolveGlab(source);
+    if (glabCredential) return glabCredential;
+    return resolveGitLabEnvironmentCredential(source, this.env);
+  }
+
+  /**
+   * 返回不含 token 的登录状态。
+   *
+   * @param {object} source GitLab 来源
+   * @returns {Promise<{authorized:boolean,scopes:string[],expiresAt:number|null,persistent:boolean}>} 非敏感状态
+   */
+  async status(source) {
+    const resolution = await this.resolve(source);
+    return {
+      authorized: resolution.authorized,
+      scopes: resolution.scopes,
+      expiresAt: resolution.expiresAt,
+      persistent: resolution.persistent,
+    };
+  }
+
+  /** @param {object} source @returns {Promise<{authorized:true,scopes:string[],expiresAt:null,persistent:false,accessToken:string,credentialSource:"glab"}|null>} */
+  async #resolveGlab(source) {
+    let output;
+    try {
+      output = await this.runGlab([
+        "auth",
+        "status",
+        "--hostname",
+        gitLabCredentialHost(source),
+        "--show-token",
+      ], {
+        command: this.glabCommand,
+        timeoutMs: this.glabTimeoutMs,
+        source,
+      });
+    } catch {
+      return null;
+    }
+    const accessToken = parseGlabAuthStatusToken(`${output?.stdout || ""}\n${output?.stderr || ""}`, source);
+    return accessToken ? externalCredential(accessToken, "glab") : null;
+  }
+}
+
+/**
+ * 构造非持久外部凭据结果。
+ *
+ * @param {string} accessToken access token
+ * @param {"glab"|"env"} credentialSource 凭据来源
+ * @returns {{authorized:true,scopes:string[],expiresAt:null,persistent:false,accessToken:string,credentialSource:"glab"|"env"}} 外部凭据
+ */
+function externalCredential(accessToken, credentialSource) {
+  if (!accessToken) {
+    throw new PluginRuntimeError("GitLab 外部凭据为空", {
+      code: PLUGIN_RUNTIME_ERROR_CODES.AUTH_REQUIRED,
+    });
+  }
+  return {
+    authorized: true,
+    scopes: [],
+    expiresAt: null,
+    persistent: false,
+    accessToken,
+    credentialSource,
+  };
+}

package/src/plugin/auth/gitlab-oauth.js

@@ -1,7 +1,13 @@
 import crypto from "node:crypto";
 import http from "node:http";
 import { spawn } from "node:child_process";
-import { CREDENTIAL_SCHEMA_VERSION, GITLAB_OAUTH_SCOPES, validateCredential } from "./credential-store.js";
+import { GitLabCredentialResolver } from "./gitlab-credential-resolver.js";
+import {
+  CREDENTIAL_SCHEMA_VERSION,
+  GITLAB_OAUTH_REQUEST_SCOPES,
+  isGitLabCredentialScopeSufficient,
+  validateCredential,
+} from "./credential-store.js";
 import { PLUGIN_RUNTIME_ERROR_CODES, PluginRuntimeError } from "../runtime-errors.js";
 
 const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
@@ -131,7 +137,7 @@ export class GitLabOAuthClient {
         redirect_uri: callback.redirectUri,
         response_type: "code",
         state: pkce.state,
-        scope: GITLAB_OAUTH_SCOPES.join(" "),
+        scope: GITLAB_OAUTH_REQUEST_SCOPES.join(" "),
         code_challenge: pkce.challenge,
         code_challenge_method: "S256",
       }).toString();
@@ -167,7 +173,7 @@ export class GitLabOAuthClient {
   async loginWithDevice(source, options = {}) {
     const device = await this.#postForm(source, "/oauth/authorize_device", {
       client_id: source.oauth.applicationId,
-      scope: GITLAB_OAUTH_SCOPES.join(" "),
+      scope: GITLAB_OAUTH_REQUEST_SCOPES.join(" "),
     }, { signal: options.signal });
     if (
       typeof device.device_code !== "string" ||
@@ -253,7 +259,7 @@ export class GitLabOAuthClient {
         ? payload.scope.split(/[ ,]+/).filter(Boolean)
         : [];
     let tokenPayload = payload;
-    if (!GITLAB_OAUTH_SCOPES.every((scope) => responseScopes.includes(scope))) {
+    if (!isGitLabCredentialScopeSufficient(responseScopes)) {
       const tokenInfo = await this.#readTokenInfo(source, payload.access_token);
       tokenPayload = { ...payload, scope: tokenInfo.scope || tokenInfo.scopes || [] };
     }
@@ -395,13 +401,21 @@ export class GitLabCredentialManager {
   /**
    * 创建凭据管理器。
    *
-   * @param {{store:import("./credential-store.js").CredentialStore,oauth:GitLabOAuthClient,now?:()=>number}} options 依赖
+   * @param {{store:import("./credential-store.js").CredentialStore,oauth:GitLabOAuthClient,now?:()=>number,persistent?:boolean,credentialResolver?:GitLabCredentialResolver,env?:NodeJS.ProcessEnv|Record<string,string|undefined>,runGlab?:(args:string[],options?:object)=>Promise<{stdout?:string,stderr?:string}>,glabCommand?:string}} options 依赖
    */
   constructor(options) {
     this.store = options.store;
     this.oauth = options.oauth;
     this.now = options.now || Date.now;
+    this.resolver = options.credentialResolver || new GitLabCredentialResolver({
+      store: options.store,
+      persistent: options.persistent,
+      env: options.env,
+      runGlab: options.runGlab,
+      glabCommand: options.glabCommand,
+    });
     this.refreshes = new Map();
+    this.externalTokens = new Map();
   }
 
   /**
@@ -413,6 +427,13 @@ export class GitLabCredentialManager {
   async getAccessToken(source) {
     const credential = await this.store.get(source);
     if (!credential) {
+      const externalKey = `${source.id}\u0000${source.baseUrl}`;
+      if (this.externalTokens.has(externalKey)) return this.externalTokens.get(externalKey);
+      const external = await this.resolver.resolveExternal(source);
+      if (external) {
+        this.externalTokens.set(externalKey, external.accessToken);
+        return external.accessToken;
+      }
       throw new PluginRuntimeError(`GitLab source 尚未登录:${source.id}`, {
         code: PLUGIN_RUNTIME_ERROR_CODES.AUTH_REQUIRED,
         path: source.id,

package/src/plugin/authoring/scaffold.js

@@ -133,7 +133,12 @@ function renderPackageFiles(options) {
     dependencies: {},
     capabilities: { profile: options.profile, required },
     content: {
-      skills: [`skills/${options.pluginId}`],
+      skills: [{
+        name: options.pluginId,
+        path: `skills/${options.pluginId}`,
+        version: options.version,
+        description: `${options.name}。用于执行该 Plugin 提供的专业工作流。`,
+      }],
       tests: ["tests"],
     },
     ...(options.includePatches ? {

package/src/plugin/authoring/templates/rd-guide/CODEOWNERS

@@ -1,2 +1,2 @@
 # integration 审核材料必须由受保护 owner 审批。
-/.flower-marketplace/integration-review.json @digital-rd-governance/plugin-integration-owners
+/.flower-plugin/integration-review.json @digital-rd-governance/plugin-integration-owners

package/src/plugin/authoring/templates/rd-guide/gitlab-ci.yml

@@ -2,8 +2,8 @@ flower-plugin-validate:
   image: node:22
   script:
     - npm install --global flower-trellis
-    - flower-trellis plugin validate .flower-marketplace/marketplace.json --subject marketplace --checkout-map .flower-marketplace/checkouts.json --ci --json > flower-plugin-validation.json
-    - node .flower-marketplace/verify-integration-review.mjs flower-plugin-validation.json .flower-marketplace/integration-review.json
+    - flower-trellis plugin validate .flower-plugin/marketplace.json --subject marketplace --checkout-map .flower-plugin/checkouts.json --ci --json > flower-plugin-validation.json
+    - node .flower-plugin/verify-integration-review.mjs flower-plugin-validation.json .flower-plugin/integration-review.json
   artifacts:
     when: always
     paths:

package/src/plugin/authoring/templates/rd-guide/verify-integration-review.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 
 const validationPath = process.argv[2] || "flower-plugin-validation.json";
-const reviewPath = process.argv[3] || ".flower-marketplace/integration-review.json";
+const reviewPath = process.argv[3] || ".flower-plugin/integration-review.json";
 const validation = JSON.parse(fs.readFileSync(validationPath, "utf8"));
 
 if (!validation.ok) {

package/src/plugin/content-selection.js

@@ -0,0 +1,189 @@
+import {
+  PLUGIN_RUNTIME_ERROR_CODES,
+  PluginRuntimeError,
+} from "./runtime-errors.js";
+import {
+  CONTENT_SKILL_NAME_PATTERN,
+  assertSafePosixRelativePath,
+} from "./schemas/shared.js";
+import { compareUtf8 } from "./stable-order.js";
+
+const CONTENT_SKILL_NAME_RE = new RegExp(CONTENT_SKILL_NAME_PATTERN);
+
+/**
+ * 判断 Skill 选择名是否是单段安全名称。
+ *
+ * @param {unknown} value 待判断值
+ * @returns {boolean} 是否安全
+ */
+export function isContentSkillSelectionName(value) {
+  return typeof value === "string" && CONTENT_SKILL_NAME_RE.test(value);
+}
+
+/**
+ * 归一化用户选择的 Skill 名称列表。
+ *
+ * @param {string[]} values 原始名称或逗号列表
+ * @param {{code?:string,path?:string}} [options] 错误选项
+ * @returns {string[]} 稳定去重后的名称
+ */
+export function normalizeContentSkillNames(values, options = {}) {
+  const code = options.code || PLUGIN_RUNTIME_ERROR_CODES.CONTENT_SELECTION_INVALID;
+  const names = [...new Set((values || [])
+    .flatMap((value) => String(value).split(","))
+    .map((value) => value.trim())
+    .filter(Boolean))]
+    .sort(compareUtf8);
+  if (names.length === 0) {
+    throw new PluginRuntimeError("Content Skill 选择不能为空", {
+      code,
+      path: options.path || "contentSelection.skills",
+    });
+  }
+  const invalid = names.find((name) => !isContentSkillSelectionName(name));
+  if (invalid) {
+    throw new PluginRuntimeError(`Content Skill 名称非法:${invalid}`, {
+      code,
+      path: options.path || invalid,
+    });
+  }
+  return names;
+}
+
+/**
+ * 从 Skill 名称列表构造内容选择对象。
+ *
+ * @param {string[]} values 原始名称或逗号列表
+ * @param {{code?:string,path?:string}} [options] 错误选项
+ * @returns {import("./contracts.js").PluginContentSelection} 内容选择
+ */
+export function contentSelectionFromSkillNames(values, options = {}) {
+  return { skills: normalizeContentSkillNames(values, options) };
+}
+
+/**
+ * 归一化内容选择对象。
+ *
+ * @param {import("./contracts.js").PluginContentSelection|null|undefined} selection 内容选择
+ * @param {{code?:string,path?:string}} [options] 错误选项
+ * @returns {import("./contracts.js").PluginContentSelection|undefined} 归一化选择；缺失时为 undefined
+ */
+export function normalizeContentSelection(selection, options = {}) {
+  if (!selection) return undefined;
+  if (!Array.isArray(selection.skills)) {
+    throw new PluginRuntimeError("contentSelection.skills 必须是数组", {
+      code: options.code || PLUGIN_RUNTIME_ERROR_CODES.CONTENT_SELECTION_INVALID,
+      path: options.path || "contentSelection.skills",
+    });
+  }
+  return { skills: normalizeContentSkillNames(selection.skills, options) };
+}
+
+/**
+ * 判断两个内容选择是否等价。
+ *
+ * @param {import("./contracts.js").PluginContentSelection|null|undefined} left 左侧选择
+ * @param {import("./contracts.js").PluginContentSelection|null|undefined} right 右侧选择
+ * @returns {boolean} 是否等价
+ */
+export function contentSelectionsEqual(left, right) {
+  const normalizedLeft = normalizeContentSelection(left);
+  const normalizedRight = normalizeContentSelection(right);
+  if (!normalizedLeft && !normalizedRight) return true;
+  if (!normalizedLeft || !normalizedRight) return false;
+  if (normalizedLeft.skills.length !== normalizedRight.skills.length) return false;
+  return normalizedLeft.skills.every((name, index) => name === normalizedRight.skills[index]);
+}
+
+/**
+ * 列出 manifest `content.skills` 的可选 Skill。
+ *
+ * @param {import("./contracts.js").PluginContentSkillEntry[]} entries manifest 中的 Skill 内容条目
+ * @param {string} owner 诊断中的 Plugin ID
+ * @returns {Array<import("./contracts.js").PluginContentSkillEntry>} 稳定 Skill 清单
+ */
+export function listContentSkillChoices(entries, owner) {
+  const choices = [];
+  const byName = new Map();
+  const byPath = new Map();
+  const sorted = [...(entries || [])]
+    .sort((left, right) => (
+      compareUtf8(String(left?.name || ""), String(right?.name || "")) ||
+      compareUtf8(String(left?.path || ""), String(right?.path || ""))
+    ));
+  for (const entry of sorted) {
+    const name = entry?.name;
+    const skillPath = entry?.path;
+    if (!isContentSkillSelectionName(name)) {
+      throw new PluginRuntimeError(`Content Skill 名称非法:${name}`, {
+        code: PLUGIN_RUNTIME_ERROR_CODES.CONTENT_SELECTION_INVALID,
+        path: `${owner}:${String(skillPath || name || "")}`,
+      });
+    }
+    assertSafePosixRelativePath(skillPath, "Content Skill 路径");
+    const previous = byName.get(name);
+    if (previous) {
+      throw new PluginRuntimeError(`Plugin content.skills 名称重复:${name}`, {
+        code: PLUGIN_RUNTIME_ERROR_CODES.CONTENT_CONFLICT,
+        path: owner,
+        details: { entries: [previous, skillPath].sort(compareUtf8) },
+      });
+    }
+    const previousPath = byPath.get(skillPath);
+    if (previousPath) {
+      throw new PluginRuntimeError(`Plugin content.skills 路径重复:${skillPath}`, {
+        code: PLUGIN_RUNTIME_ERROR_CODES.CONTENT_CONFLICT,
+        path: owner,
+        details: { names: [previousPath, name].sort(compareUtf8) },
+      });
+    }
+    byName.set(name, skillPath);
+    byPath.set(skillPath, name);
+    choices.push({
+      name,
+      path: skillPath,
+      version: entry.version,
+      ...(entry.description ? { description: entry.description } : {}),
+    });
+  }
+  return choices.sort((left, right) => compareUtf8(left.name, right.name));
+}
+
+/**
+ * 根据内容选择过滤 manifest `content.skills`。
+ *
+ * @param {import("./contracts.js").PluginContentSkillEntry[]} entries manifest 中的 Skill 内容条目
+ * @param {import("./contracts.js").PluginContentSelection|null|undefined} selection 内容选择
+ * @param {string} owner 诊断中的 Plugin ID
+ * @returns {Array<import("./contracts.js").PluginContentSkillEntry>} 应投影的 Skill 内容条目
+ */
+export function selectContentSkillEntries(entries, selection, owner) {
+  const choices = listContentSkillChoices(entries, owner);
+  const normalized = normalizeContentSelection(selection);
+  if (!normalized) return choices;
+  const byName = new Map(choices.map((choice) => [choice.name, choice]));
+  const missing = normalized.skills.filter((name) => !byName.has(name));
+  if (missing.length > 0) {
+    throw new PluginRuntimeError(`Content Skill 选择不存在:${missing.join(",")}`, {
+      code: PLUGIN_RUNTIME_ERROR_CODES.CONTENT_SELECTION_INVALID,
+      path: owner,
+      details: {
+        requested: normalized.skills,
+        available: choices.map(({ name }) => name),
+      },
+    });
+  }
+  return normalized.skills.map((name) => byName.get(name));
+}
+
+/**
+ * 把内容选择转换为 CLI 参数。
+ *
+ * @param {import("./contracts.js").PluginContentSelection|null|undefined} selection 内容选择
+ * @returns {string[]} CLI 参数
+ */
+export function contentSelectionArgs(selection) {
+  const normalized = normalizeContentSelection(selection);
+  if (!normalized) return [];
+  return normalized.skills.flatMap((name) => ["--content-skill", name]);
+}

package/src/plugin/contracts.js

@@ -15,13 +15,26 @@
 
 /**
  * @typedef {object} PluginContent
- * @property {string[]} [skills] Skill 内容路径
+ * @property {PluginContentSkillEntry[]} [skills] Skill 内容条目
  * @property {string[]} [specs] 规范内容路径
  * @property {string[]} [assets] 资源内容路径
  * @property {string[]} [scripts] 被动脚本资源路径
  * @property {string[]} [tests] 测试资源路径
  */
 
+/**
+ * @typedef {object} PluginContentSkillEntry
+ * @property {string} name Skill 选择名
+ * @property {string} path Skill 内容路径
+ * @property {string} version Skill 版本
+ * @property {string} [description] Skill 描述
+ */
+
+/**
+ * @typedef {object} PluginContentSelection
+ * @property {string[]} [skills] 当前项目选择启用的 Skill 名称
+ */
+
 /**
  * @typedef {object} PluginManifest
  * @property {1} schemaVersion schema 版本
@@ -38,7 +51,8 @@
 /**
  * @typedef {object} MarketplacePathSource
  * @property {"path"} type 共仓来源
- * @property {string} path Marketplace 内 POSIX 相对路径
+ * @property {string} [path] Marketplace 内 POSIX 相对目录；缺省表示仓库根
+ * @property {string} [manifestPath] Plugin manifest 相对包根路径
  */
 
 /**
@@ -46,6 +60,7 @@
  * @property {"gitlab"} type GitLab 来源
  * @property {string} project GitLab project path
  * @property {string} [subdir] 仓库内 POSIX 相对目录
+ * @property {string} [manifestPath] Plugin manifest 相对包根路径
  */
 
 /**
@@ -53,6 +68,7 @@
  * @property {"github"} type GitHub 来源
  * @property {string} repository GitHub `owner/repository`
  * @property {string} [subdir] 仓库内 POSIX 相对目录
+ * @property {string} [manifestPath] Plugin manifest 相对包根路径
  */
 
 /** @typedef {MarketplacePathSource|MarketplaceGitLabSource|MarketplaceGitHubSource} MarketplaceSource */
@@ -146,6 +162,7 @@
  * @property {Record<string,string>} dependencies 已解析依赖版本
  * @property {CompatibilityConstraint} compatibility 兼容范围
  * @property {CapabilityGrant} capabilities 实际能力授权
+ * @property {PluginContentSelection} [contentSelection] 内容选择
  */
 
 /**
@@ -210,6 +227,7 @@
  * @property {string} source 来源 ID
  * @property {string} version SemVer range
  * @property {string[]} [platforms] 显式平台限制
+ * @property {PluginContentSelection} [contentSelection] 内容选择
  */
 
 /**
@@ -245,6 +263,7 @@
  * @property {string} id canonical Plugin ID
  * @property {string} version 已应用版本
  * @property {string[]} platforms 实际投影平台
+ * @property {PluginContentSelection} [contentSelection] 内容选择
  * @property {PluginPathState[]} paths 受管路径
  * @property {PluginPatchState[]} patches Patch 应用状态
  */