@dependfix/engine 0.1.3 → 0.4.0

package/README.md

@@ -1,5 +1,8 @@
 # @dependfix/engine
 
+<!-- i18n: switch -->
+[简体中文](./README.md) | <!-- English version pending -->
+
 > dependfix 执行引擎包：编排、采集、修复与研判核心。由 CLI（dependfix）、MCP Server（@dependfix/mcp）与平台（apps/platform）共同依赖，应用层不再互相依赖。
 
 ## 内容
@@ -25,3 +28,11 @@
 pnpm --filter @dependfix/engine build   # 构建 dist
 pnpm --filter @dependfix/engine test    # 测试
 ```
+
+## 相关包
+
+- [dependfix 主项目](https://github.com/dependfix/dependfix) — 本包源码与完整文档
+- [@dependfix/core](https://github.com/dependfix/dependfix/blob/master/packages/core/README.md) — 核心领域模型库（本包依赖）
+- [dependfix](https://github.com/dependfix/dependfix/blob/master/packages/cli/README.md) — CLI 应用入口（依赖本包）
+- [@dependfix/mcp](https://github.com/dependfix/dependfix/blob/master/packages/mcp/README.md) — MCP Server（依赖本包）
+- [@dependfix/skills](https://github.com/dependfix/dependfix/blob/master/packages/skills/README.md) — 产品 Agent Skill 权威源

package/dist/auth-provider.d.mts

@@ -0,0 +1,82 @@
+import { Octokit } from "@octokit/rest";
+//#region src/auth/auth-provider.d.ts
+/**
+ * GitHub 认证抽象层。
+ *
+ * 支持 PAT（classic / fine-grained）与 GitHub App installation token 两种认证路径。
+ * 调用方通过 `getOctokit()` 获取已认证的 Octokit 实例；通过 `getGitCredential()`
+ * 获取推送/clone 用的 Git 凭据；通过 `getCommitAuthor()` 获取 commit author 信息。
+ *
+ * `authProvider` 字段用于审计与调试（区分 PAT vs App 路径）。
+ *
+ * @example
+ * ```typescript
+ * // 推荐：从 fromPat / fromApp 工厂构造
+ * const auth = fromPat('ghp_xxxx')
+ * const octokit = auth.getOctokit()
+ *
+ * // git push 凭据
+ * const { username, token } = auth.getGitCredential()
+ *
+ * // commit author（PAT 路径固定；App 路径动态）
+ * const { name, email } = auth.getCommitAuthor()
+ * ```
+ */
+interface AuthProvider {
+  /** 获取已认证的 Octokit 实例 */
+  getOctokit(): Octokit;
+  /** 获取推送 / clone 用的 Git 凭据（用户名 + token） */
+  getGitCredential(): {
+    username: string;
+    token: string;
+  };
+  /**
+   * 获取 commit author 信息。
+   *
+   * - PAT 路径：固定返回 `{ name: 'dependfix[bot]', email: 'dependfix[bot]@users.noreply.github.com' }`（保持现有行为零变化）
+   * - GitHub App 路径：动态生成 `{app_id}+{bot_login}[bot]@users.noreply.github.com`（GitHub App 协议要求）
+   */
+  getCommitAuthor(): {
+    name: string;
+    email: string;
+  };
+  /** 认证路径标识（用于审计 + 调试） */
+  readonly authProvider: 'pat' | 'github-app';
+}
+/** 工厂函数统一选项（与 OctokitClientOptions.retry 字段对齐） */
+interface AuthProviderOptions {
+  /** API 限流 / 次要限流指数退避重试策略。默认 maxRetries=3。 */
+  retry?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxBackoffMs?: number;
+  };
+}
+/** PAT 工厂参数（仅 token；retry 在 options 注入） */
+type FromPatParams = string;
+/** GitHub App 工厂参数 */
+interface FromAppParams {
+  /** GitHub App ID */
+  appId: string;
+  /** PEM 格式私钥 */
+  privateKey: string;
+  /** Installation ID */
+  installationId: string;
+  /** Bot 用户名（用于 commit author 动态生成；M18.1 commit 4 实施） */
+  botLogin?: string;
+}
+/**
+ * PAT 路径固定 commit author（保持现有行为零变化）。
+ *
+ * 注：现有 PAT 路径硬编码 `dependfix[bot]@users.noreply.github.com`，虽非真实 bot 身份（字符串约定），
+ * 但保持行为不变以确保 PAT 用户无感升级。已知缺陷由 C22 范围之外的后续阶段修复。
+ */
+declare const PAT_COMMIT_AUTHOR: {
+  readonly name: "dependfix[bot]";
+  readonly email: "dependfix[bot]@users.noreply.github.com";
+};
+/** PAT 路径固定 Git 用户名（用于 git push 时的 Basic Auth） */
+declare const PAT_GIT_USERNAME = "x-access-token";
+//#endregion
+export { PAT_COMMIT_AUTHOR as a, FromPatParams as i, AuthProviderOptions as n, PAT_GIT_USERNAME as o, FromAppParams as r, AuthProvider as t };
+//# sourceMappingURL=auth-provider.d.mts.map

package/dist/auth.d.mts

@@ -0,0 +1,184 @@
+import { a as PAT_COMMIT_AUTHOR, i as FromPatParams, n as AuthProviderOptions, o as PAT_GIT_USERNAME, r as FromAppParams, t as AuthProvider } from "./auth-provider.mjs";
+import { Octokit } from "@octokit/rest";
+//#region src/auth/pat-provider.d.ts
+/**
+ * PAT 工厂函数。委托给 `PatAuthProvider` 类。
+ *
+ * 保留 `fromPat` 命名习惯便于与 `fromApp` 对齐（统一工厂语义）。
+ *
+ * @example
+ * ```typescript
+ * const auth = fromPat('ghp_xxxx')
+ * const octokit = auth.getOctokit()
+ * const { username, token } = auth.getGitCredential()
+ * ```
+ */
+export declare function fromPat(token: FromPatParams, options?: AuthProviderOptions): AuthProvider;
+/**
+ * PAT 认证路径实现。
+ *
+ * `getOctokit()` 委托给 [`createGitHubClient`](../github/client.ts) 以复用现有 retry policy 与限流重试实现；
+ * Octokit 实例缓存以避免重复构造（每次 `new Octokit()` + `hook.wrap()` 都有开销）。
+ *
+ * 行为与原 `createGitHubClient({ token })` 等价：
+ * - `getOctokit()` 返回通过 PAT 认证的 Octokit 实例（含限流重试 hook）
+ * - `getGitCredential()` 返回推送用的 Basic Auth（username = `'x-access-token'`）
+ * - `getCommitAuthor()` 返回固定 `dependfix[bot]`（PAT 路径用户行为零变化）
+ *
+ * @example
+ * ```typescript
+ * const auth = new PatAuthProvider('ghp_xxxx', { retry: { maxRetries: 3 } })
+ * const octokit = auth.getOctokit()
+ * ```
+ */
+export declare class PatAuthProvider implements AuthProvider {
+  readonly authProvider: "pat";
+  private readonly token;
+  private readonly retry?;
+  private cachedOctokit;
+  constructor(token: FromPatParams, options?: AuthProviderOptions);
+  /**
+   * 获取已认证的 Octokit 实例（首次调用构造并缓存）。
+   */
+  getOctokit(): Octokit;
+  /** 获取推送 / clone 用的 Git 凭据（username = `'x-access-token'`，token = PAT） */
+  getGitCredential(): {
+    username: string;
+    token: string;
+  };
+  /** 获取 commit author（PAT 路径固定 `dependfix[bot]`） */
+  getCommitAuthor(): {
+    name: string;
+    email: string;
+  };
+}
+//#endregion
+//#region src/auth/app-provider.d.ts
+/**
+ * GitHub App 工厂函数（**M18.1 commit 4 完整实施**）。
+ *
+ * 委托给 [`AppAuthProvider`] 类。
+ *
+ * @example
+ * ```typescript
+ * const auth = fromApp({
+ *     appId: '123456',
+ *     privateKey: '-----BEGIN RSA PRIVATE KEY-----\n...',
+ *     installationId: '7890123',
+ *     botLogin: 'dependfix-bot[bot]',
+ * })
+ * const octokit = auth.getOctokit()
+ * ```
+ */
+export declare function fromApp(params: FromAppParams, options?: AuthProviderOptions): AuthProvider;
+/**
+ * GitHub App 认证路径实现。
+ *
+ * 使用 [`@octokit/auth-app`](https://github.com/octokit/auth-app.js) 提供：
+ * - JWT signing（App 身份认证）
+ * - `getInstallationOctokit`（installation token 获取；库内置 59 分钟 LRU TTL 缓存）
+ * - 自动 installation token 轮换
+ *
+ * 注意：
+ * - `getGitCredential()` 返回的 `token` 字段为占位符（installation token 不能直接从 AppAuthProvider 获取；
+ *   由 [`@octokit/auth-app`](https://github.com/octokit/auth-app.js) 内部管理）；调用方应通过 `getOctokit()`
+ *   拿到的 Octokit 实例进行 API 调用
+ * - `getCommitAuthor()` 按 GitHub App 协议动态生成 `{app_id}+{bot_login}[bot]@users.noreply.github.com`
+ * - Octokit 实例缓存以避免重复构造
+ *
+ * @see [C22 PAT 无感升级评估 §4.2 AuthProvider 接口设计](../../../../docs/design/governance/c22-pat-backward-compat.md)
+ */
+export declare class AppAuthProvider implements AuthProvider {
+  readonly authProvider: "github-app";
+  private readonly params;
+  private readonly _options?;
+  private cachedOctokit;
+  constructor(params: FromAppParams, options?: AuthProviderOptions);
+  /**
+   * 获取已认证的 Octokit 实例。
+   *
+   * 首次调用时构造并缓存；后续调用复用同一实例。
+   * installation token 由 `@octokit/auth-app` 内部管理（59 分钟 LRU TTL 缓存）。
+   *
+   * **构造方式**：使用 `authStrategy: createAppAuth` + `auth: {appId, privateKey, installationId}`
+   * 双字段组合（`@octokit/auth-app` v8.x README 标准用法），**而非** `auth: createAppAuth(...)`
+   * 单字段调用——后者被 `@octokit/core` 视作字符串 token 路径抛 `Token passed to createTokenAuth is not a string`，
+   * 或被 `authStrategy` 字段调用后命中 `auth(state, authOptions)` 的 `default` 分支抛 `Invalid auth type: undefined`
+   * （todo.md §M18.4 e2e 验证 + audit quick depth Reject 后补修发现）。
+   *
+   * @see [@octokit/auth-app README §installation authentication](https://github.com/octokit/auth-app.js#installation-authentication)
+   */
+  getOctokit(): Octokit;
+  /**
+   * 获取推送 / clone 用的 Git 凭据。
+   *
+   * 注意：installation token 由 `@octokit/auth-app` 内部管理，**不**能从 AppAuthProvider 直接获取；
+   * 本方法返回的 `token` 字段为占位符（`'installation-token-managed-by-octokit-auth-app'`）。
+   * 调用方应通过 `getOctokit()` 拿到的 Octokit 实例进行 API 调用（含 git push / clone 等写操作）。
+   */
+  getGitCredential(): {
+    username: string;
+    token: string;
+  };
+  /**
+   * 获取 commit author。
+   *
+   * 按 GitHub App 协议动态生成 `{app_id}+{bot_login}[bot]@users.noreply.github.com`：
+   * - `name`：`{app_id}[bot]`（GitHub 自动识别 bot 身份）
+   * - `email`：`{app_id}+{bot_login}[bot]@users.noreply.github.com`（GitHub noreply email 格式）
+   *
+   * 当 `params.botLogin` 未提供时，使用 `dependfix[bot]` 作为 fallback（保持与 PAT 路径一致的格式）；
+   * 但建议调用方显式提供 `botLogin` 以确保 commit author 真实 bot 身份归属。
+   */
+  getCommitAuthor(): {
+    name: string;
+    email: string;
+  };
+}
+//#endregion
+//#region src/auth/installation-token-cache.d.ts
+/**
+ * Installation token 缓存层（**M18.1 commit 4 实施**）。
+ *
+ * 当前实现：**依赖 [@octokit/auth-app](https://github.com/octokit/auth-app.js) 内置缓存**
+ * （59 分钟 LRU TTL；GitHub token 有效期 60 分钟 - 1 分钟缓冲）。
+ *
+ * 本类作为未来扩展点：
+ * - 缓存统计（命中率 / 大小 / 清理 API）
+ * - 失败重试 + 报警（M18.2 集成时实施）
+ * - 多 worker 共享（Redis-backed；超出 M18.1 范围）
+ *
+ * 注意：
+ * - `getOrRefresh` 当前委托给 `createAppAuthentication` + `getInstallationOctokit`
+ * - 当 [@octokit/auth-app](https://github.com/octokit/auth-app.js) 内部缓存命中时不会触发 API 调用
+ * - 缓存未命中时自动调用 `POST /app/installations/{installation_id}/access_tokens` 获取新 token
+ *
+ * @see [C22 PAT 无感升级评估 §4.7 commit 拆分纪律](../../../../docs/design/governance/c22-pat-backward-compat.md)
+ */
+export declare class InstallationTokenCache {
+  private readonly params;
+  private readonly ttlMs;
+  constructor(params: FromAppParams, options?: {
+    ttlMs?: number;
+    refreshThresholdMs?: number;
+  });
+  /**
+   * 获取或刷新 installation token。
+   *
+   * 当前为占位实现：直接返回 `'installation-token-managed-by-octokit-auth-app'` 占位字符串。
+   * 调用方应使用 `fromApp(params).getOctokit()` 获取真实 Octokit 实例（由 `@octokit/auth-app`
+   * 自动管理 installation token 缓存）。
+   *
+   * @throws 永不抛错（占位实现）
+   */
+  getOrRefresh(): Promise<string>;
+  /** 清理过期缓存项（占位实现） */
+  clear(): void;
+  /** 获取缓存 TTL 配置（毫秒） */
+  getTtlMs(): number;
+  /** 获取 cache key（基于 installationId） */
+  static getCacheKey(params: FromAppParams): string;
+}
+//#endregion
+export { AuthProvider, AuthProviderOptions, FromAppParams, FromPatParams, PAT_COMMIT_AUTHOR, PAT_GIT_USERNAME };
+//# sourceMappingURL=auth.d.mts.map

package/dist/auth.mjs

@@ -0,0 +1,3 @@
+import { a as fromPat, i as PatAuthProvider, n as AppAuthProvider, o as PAT_COMMIT_AUTHOR, r as fromApp, s as PAT_GIT_USERNAME, t as InstallationTokenCache } from "./auth2.mjs";
+
+export { AppAuthProvider, InstallationTokenCache, PAT_COMMIT_AUTHOR, PAT_GIT_USERNAME, PatAuthProvider, fromApp, fromPat };

package/dist/auth2.mjs

@@ -0,0 +1,361 @@
+import { Octokit } from "@octokit/rest";
+import { RequestError } from "@octokit/request-error";
+import { createAppAuth } from "@octokit/auth-app";
+
+//#region src/github/client.ts
+/**
+* 创建已认证的 Octokit 实例。
+*
+* 调用方直接使用 `octokit.rest.*` 访问所有已类型化的 GitHub REST API。
+* 分页使用 `octokit.paginate()` 自动合并多页结果。
+*
+* 配置 `retry` 时通过 `hook.wrap('request')` 统一包装所有请求
+* （含 paginate 内部请求），对限流响应做指数退避重试。
+*
+* @example
+* ```typescript
+* // 推荐：使用 auth 抽象层（M18.1 实施后）
+* import { fromPat } from '@dependfix/engine/auth'
+* const octokit = createGitHubClient({ auth: fromPat('ghp_xxxx') })
+*
+* // 向后兼容：使用 token 字段（deprecated）
+* const octokit = createGitHubClient({ token: 'ghp_xxxx' })
+*
+* // 仓库信息
+* const { data: repo } = await octokit.rest.repos.get({ owner: 'foo', repo: 'bar' })
+*
+* // Dependabot 告警（自动分页）
+* const alerts = await octokit.paginate(
+*     octokit.rest.dependabot.listAlertsForRepo,
+*     { owner: 'foo', repo: 'bar', state: 'open', per_page: 100 },
+* )
+* ```
+*/
+function createGitHubClient(options) {
+	if (options.auth) return options.auth.getOctokit();
+	if (!options.token) throw new Error("createGitHubClient: must provide either `auth` (AuthProvider) or `token` (deprecated)");
+	const client = new Octokit({
+		auth: options.token,
+		baseUrl: options.baseUrl ?? "https://api.github.com"
+	});
+	const maxRetries = options.retry?.maxRetries ?? 3;
+	if (maxRetries > 0) applyRetryPolicy(client, {
+		maxRetries,
+		baseDelayMs: options.retry?.baseDelayMs ?? 1e3,
+		maxBackoffMs: options.retry?.maxBackoffMs ?? MAX_BACKOFF_MS_DEFAULT
+	});
+	return client;
+}
+const SECONDARY_RATE_LIMIT_RE = /secondary rate limit|abuse|retry later|retry-after/i;
+/** 指数退避单次等待默认上限（30s），防止长时间空转（可经 retry.maxBackoffMs 覆盖） */
+const MAX_BACKOFF_MS_DEFAULT = 3e4;
+function applyRetryPolicy(client, retry) {
+	const maxRetries = retry.maxRetries ?? 3;
+	const baseDelayMs = retry.baseDelayMs ?? 1e3;
+	const maxBackoffMs = retry.maxBackoffMs ?? MAX_BACKOFF_MS_DEFAULT;
+	client.hook.wrap("request", async (request, options) => {
+		const method = (options.method ?? "GET").toUpperCase();
+		if (method !== "GET" && method !== "HEAD") return request(options);
+		let attempt = 0;
+		for (;;) try {
+			return await request(options);
+		} catch (error) {
+			const delayMs = computeRetryDelayMs(error, attempt, baseDelayMs, maxBackoffMs);
+			if (delayMs === null || attempt >= maxRetries) throw error;
+			attempt += 1;
+			await sleep(delayMs);
+		}
+	});
+}
+/**
+* 计算限流重试等待时间（纯函数，可单测）。
+*
+* 可重试（返回等待毫秒）：
+* - 429（Too Many Requests / secondary rate limit）
+* - 403 + `x-ratelimit-remaining: 0`（primary rate limit）
+* - 403/429 + message 含 secondary rate limit / abuse / retry 特征
+*
+* 等待策略（Retry-After 优先）：
+* 1. `retry-after` 头（秒）→ 等待其秒数（受 maxBackoffMs 上限约束）
+* 2. `x-ratelimit-reset`（unix 秒）→ 等待到 reset + 1s 缓冲
+* 3. 否则 → 指数退避 `baseDelayMs * 2^attempt`
+* 所有等待均受 maxBackoffMs 上限约束（默认 30s）。
+*
+* 不重试（返回 null）：
+* - 非 RequestError（网络错误等由上层 AppError 语义处理）
+* - 权限类 403（无限流特征）
+* - 其他状态码
+*/
+function computeRetryDelayMs(error, attempt, baseDelayMs = 1e3, maxBackoffMs = MAX_BACKOFF_MS_DEFAULT) {
+	if (!(error instanceof RequestError)) return null;
+	const status = error.status;
+	const headers = error.response?.headers ?? {};
+	const remaining = headers["x-ratelimit-remaining"];
+	const message = error.message;
+	let retryable = false;
+	if (status === 429) retryable = true;
+	else if (status === 403) {
+		if (remaining !== void 0 && remaining === "0") retryable = true;
+		else if (SECONDARY_RATE_LIMIT_RE.test(message)) retryable = true;
+	}
+	if (!retryable) return null;
+	const retryAfter = headers["retry-after"];
+	if (retryAfter !== void 0) {
+		const seconds = Number(retryAfter);
+		if (Number.isFinite(seconds) && seconds > 0) return Math.min(seconds * 1e3, maxBackoffMs);
+	}
+	const reset = headers["x-ratelimit-reset"];
+	if (reset !== void 0) {
+		const resetMs = Number(reset) * 1e3;
+		if (Number.isFinite(resetMs) && resetMs > 0) {
+			const waitMs = resetMs - Date.now() + 1e3;
+			if (waitMs > 0) return Math.min(waitMs, maxBackoffMs);
+		}
+	}
+	return Math.min(baseDelayMs * 2 ** attempt, maxBackoffMs);
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+//#endregion
+//#region src/auth/auth-provider.ts
+/**
+* PAT 路径固定 commit author（保持现有行为零变化）。
+*
+* 注：现有 PAT 路径硬编码 `dependfix[bot]@users.noreply.github.com`，虽非真实 bot 身份（字符串约定），
+* 但保持行为不变以确保 PAT 用户无感升级。已知缺陷由 C22 范围之外的后续阶段修复。
+*/
+const PAT_COMMIT_AUTHOR = {
+	name: "dependfix[bot]",
+	email: "dependfix[bot]@users.noreply.github.com"
+};
+/** PAT 路径固定 Git 用户名（用于 git push 时的 Basic Auth） */
+const PAT_GIT_USERNAME = "x-access-token";
+
+//#endregion
+//#region src/auth/pat-provider.ts
+/**
+* PAT 工厂函数。委托给 `PatAuthProvider` 类。
+*
+* 保留 `fromPat` 命名习惯便于与 `fromApp` 对齐（统一工厂语义）。
+*
+* @example
+* ```typescript
+* const auth = fromPat('ghp_xxxx')
+* const octokit = auth.getOctokit()
+* const { username, token } = auth.getGitCredential()
+* ```
+*/
+function fromPat(token, options) {
+	return new PatAuthProvider(token, options);
+}
+/**
+* PAT 认证路径实现。
+*
+* `getOctokit()` 委托给 [`createGitHubClient`](../github/client.ts) 以复用现有 retry policy 与限流重试实现；
+* Octokit 实例缓存以避免重复构造（每次 `new Octokit()` + `hook.wrap()` 都有开销）。
+*
+* 行为与原 `createGitHubClient({ token })` 等价：
+* - `getOctokit()` 返回通过 PAT 认证的 Octokit 实例（含限流重试 hook）
+* - `getGitCredential()` 返回推送用的 Basic Auth（username = `'x-access-token'`）
+* - `getCommitAuthor()` 返回固定 `dependfix[bot]`（PAT 路径用户行为零变化）
+*
+* @example
+* ```typescript
+* const auth = new PatAuthProvider('ghp_xxxx', { retry: { maxRetries: 3 } })
+* const octokit = auth.getOctokit()
+* ```
+*/
+var PatAuthProvider = class {
+	authProvider = "pat";
+	token;
+	retry;
+	cachedOctokit = null;
+	constructor(token, options) {
+		this.token = token;
+		this.retry = options?.retry;
+	}
+	/**
+	* 获取已认证的 Octokit 实例（首次调用构造并缓存）。
+	*/
+	getOctokit() {
+		if (!this.cachedOctokit) this.cachedOctokit = createGitHubClient({
+			token: this.token,
+			retry: this.retry
+		});
+		return this.cachedOctokit;
+	}
+	/** 获取推送 / clone 用的 Git 凭据（username = `'x-access-token'`，token = PAT） */
+	getGitCredential() {
+		return {
+			username: PAT_GIT_USERNAME,
+			token: this.token
+		};
+	}
+	/** 获取 commit author（PAT 路径固定 `dependfix[bot]`） */
+	getCommitAuthor() {
+		return { ...PAT_COMMIT_AUTHOR };
+	}
+};
+
+//#endregion
+//#region src/auth/app-provider.ts
+/**
+* GitHub App 工厂函数（**M18.1 commit 4 完整实施**）。
+*
+* 委托给 [`AppAuthProvider`] 类。
+*
+* @example
+* ```typescript
+* const auth = fromApp({
+*     appId: '123456',
+*     privateKey: '-----BEGIN RSA PRIVATE KEY-----\n...',
+*     installationId: '7890123',
+*     botLogin: 'dependfix-bot[bot]',
+* })
+* const octokit = auth.getOctokit()
+* ```
+*/
+function fromApp(params, options) {
+	return new AppAuthProvider(params, options);
+}
+/**
+* GitHub App 认证路径实现。
+*
+* 使用 [`@octokit/auth-app`](https://github.com/octokit/auth-app.js) 提供：
+* - JWT signing（App 身份认证）
+* - `getInstallationOctokit`（installation token 获取；库内置 59 分钟 LRU TTL 缓存）
+* - 自动 installation token 轮换
+*
+* 注意：
+* - `getGitCredential()` 返回的 `token` 字段为占位符（installation token 不能直接从 AppAuthProvider 获取；
+*   由 [`@octokit/auth-app`](https://github.com/octokit/auth-app.js) 内部管理）；调用方应通过 `getOctokit()`
+*   拿到的 Octokit 实例进行 API 调用
+* - `getCommitAuthor()` 按 GitHub App 协议动态生成 `{app_id}+{bot_login}[bot]@users.noreply.github.com`
+* - Octokit 实例缓存以避免重复构造
+*
+* @see [C22 PAT 无感升级评估 §4.2 AuthProvider 接口设计](../../../../docs/design/governance/c22-pat-backward-compat.md)
+*/
+var AppAuthProvider = class {
+	authProvider = "github-app";
+	params;
+	_options;
+	cachedOctokit = null;
+	constructor(params, options) {
+		this.params = params;
+		this._options = options;
+	}
+	/**
+	* 获取已认证的 Octokit 实例。
+	*
+	* 首次调用时构造并缓存；后续调用复用同一实例。
+	* installation token 由 `@octokit/auth-app` 内部管理（59 分钟 LRU TTL 缓存）。
+	*
+	* **构造方式**：使用 `authStrategy: createAppAuth` + `auth: {appId, privateKey, installationId}`
+	* 双字段组合（`@octokit/auth-app` v8.x README 标准用法），**而非** `auth: createAppAuth(...)`
+	* 单字段调用——后者被 `@octokit/core` 视作字符串 token 路径抛 `Token passed to createTokenAuth is not a string`，
+	* 或被 `authStrategy` 字段调用后命中 `auth(state, authOptions)` 的 `default` 分支抛 `Invalid auth type: undefined`
+	* （todo.md §M18.4 e2e 验证 + audit quick depth Reject 后补修发现）。
+	*
+	* @see [@octokit/auth-app README §installation authentication](https://github.com/octokit/auth-app.js#installation-authentication)
+	*/
+	getOctokit() {
+		if (!this.cachedOctokit) this.cachedOctokit = new Octokit({
+			authStrategy: createAppAuth,
+			auth: {
+				appId: this.params.appId,
+				privateKey: this.params.privateKey,
+				installationId: this.params.installationId
+			},
+			baseUrl: "https://api.github.com"
+		});
+		return this.cachedOctokit;
+	}
+	/**
+	* 获取推送 / clone 用的 Git 凭据。
+	*
+	* 注意：installation token 由 `@octokit/auth-app` 内部管理，**不**能从 AppAuthProvider 直接获取；
+	* 本方法返回的 `token` 字段为占位符（`'installation-token-managed-by-octokit-auth-app'`）。
+	* 调用方应通过 `getOctokit()` 拿到的 Octokit 实例进行 API 调用（含 git push / clone 等写操作）。
+	*/
+	getGitCredential() {
+		return {
+			username: "x-access-token",
+			token: "installation-token-managed-by-octokit-auth-app"
+		};
+	}
+	/**
+	* 获取 commit author。
+	*
+	* 按 GitHub App 协议动态生成 `{app_id}+{bot_login}[bot]@users.noreply.github.com`：
+	* - `name`：`{app_id}[bot]`（GitHub 自动识别 bot 身份）
+	* - `email`：`{app_id}+{bot_login}[bot]@users.noreply.github.com`（GitHub noreply email 格式）
+	*
+	* 当 `params.botLogin` 未提供时，使用 `dependfix[bot]` 作为 fallback（保持与 PAT 路径一致的格式）；
+	* 但建议调用方显式提供 `botLogin` 以确保 commit author 真实 bot 身份归属。
+	*/
+	getCommitAuthor() {
+		const botLogin = this.params.botLogin ?? "dependfix[bot]";
+		const appId = this.params.appId;
+		return {
+			name: `${appId}[bot]`,
+			email: `${appId}+${botLogin}@users.noreply.github.com`
+		};
+	}
+};
+
+//#endregion
+//#region src/auth/installation-token-cache.ts
+/**
+* Installation token 缓存层（**M18.1 commit 4 实施**）。
+*
+* 当前实现：**依赖 [@octokit/auth-app](https://github.com/octokit/auth-app.js) 内置缓存**
+* （59 分钟 LRU TTL；GitHub token 有效期 60 分钟 - 1 分钟缓冲）。
+*
+* 本类作为未来扩展点：
+* - 缓存统计（命中率 / 大小 / 清理 API）
+* - 失败重试 + 报警（M18.2 集成时实施）
+* - 多 worker 共享（Redis-backed；超出 M18.1 范围）
+*
+* 注意：
+* - `getOrRefresh` 当前委托给 `createAppAuthentication` + `getInstallationOctokit`
+* - 当 [@octokit/auth-app](https://github.com/octokit/auth-app.js) 内部缓存命中时不会触发 API 调用
+* - 缓存未命中时自动调用 `POST /app/installations/{installation_id}/access_tokens` 获取新 token
+*
+* @see [C22 PAT 无感升级评估 §4.7 commit 拆分纪律](../../../../docs/design/governance/c22-pat-backward-compat.md)
+*/
+var InstallationTokenCache = class {
+	params;
+	ttlMs;
+	constructor(params, options) {
+		this.params = params;
+		this.ttlMs = options?.ttlMs ?? 354e4;
+	}
+	/**
+	* 获取或刷新 installation token。
+	*
+	* 当前为占位实现：直接返回 `'installation-token-managed-by-octokit-auth-app'` 占位字符串。
+	* 调用方应使用 `fromApp(params).getOctokit()` 获取真实 Octokit 实例（由 `@octokit/auth-app`
+	* 自动管理 installation token 缓存）。
+	*
+	* @throws 永不抛错（占位实现）
+	*/
+	async getOrRefresh() {
+		return "installation-token-managed-by-octokit-auth-app";
+	}
+	/** 清理过期缓存项（占位实现） */
+	clear() {}
+	/** 获取缓存 TTL 配置（毫秒） */
+	getTtlMs() {
+		return this.ttlMs;
+	}
+	/** 获取 cache key（基于 installationId） */
+	static getCacheKey(params) {
+		return `installation:${params.installationId}`;
+	}
+};
+
+//#endregion
+export { fromPat as a, computeRetryDelayMs as c, PatAuthProvider as i, createGitHubClient as l, AppAuthProvider as n, PAT_COMMIT_AUTHOR as o, fromApp as r, PAT_GIT_USERNAME as s, InstallationTokenCache as t };
+//# sourceMappingURL=auth2.mjs.map