dsh-github-flow 0.2.1 → 0.4.0

package/lib/tools/cache.d.ts

@@ -0,0 +1,64 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createCacheTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            cache_id: {
+                type: string;
+                description: string;
+            };
+            key: {
+                type: string;
+                description: string;
+            };
+            ref: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            sort: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            order: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            all: {
+                type: string;
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    output: {
+        schema: {
+            type: string;
+        };
+        render(args: any, value: any): {
+            type: string;
+            text: string;
+        }[];
+    };
+    execute(args: any, execContext: any): Promise<Record<string, any>>;
+};

package/lib/tools/cache.js

@@ -0,0 +1,186 @@
+import { renderCacheMarkdown } from '../renderers/markdown.js';
+function normalizeOutput(data) {
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return { items: data, count: data.length };
+    }
+    return { result: data !== undefined && data !== null ? data : '' };
+}
+export function createCacheTool(executor) {
+    return {
+        name: 'github_cache',
+        description: '管理 GitHub Actions 构建缓存 (Caches)：查看缓存列表与占用容量、按 ID 或 Key 删除指定缓存、以及全量清空仓库缓存。全量清空不可逆，需 confirm: true。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'delete'],
+                    description: 'Cache 操作类型。list 查看缓存列表与体积、delete 删除缓存。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则识别当前工作区仓库。',
+                },
+                cache_id: {
+                    type: 'string',
+                    description: '缓存数字 ID（delete 动作指定单条缓存删除时使用）。',
+                },
+                key: {
+                    type: 'string',
+                    description: '缓存 Key 键名前缀或完整键名（list 动作过滤检索，或 delete 动作按键删除时使用）。',
+                },
+                ref: {
+                    type: 'string',
+                    description: '分支或 PR Git Ref（如 "refs/heads/main" 或 "refs/pull/42/merge"，用于过滤或定向删除）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回缓存数量上限（list 动作使用，默认 30）。',
+                },
+                sort: {
+                    type: 'string',
+                    enum: ['created_at', 'last_accessed_at', 'size_in_bytes'],
+                    description: '排序字段（list 动作使用，默认 last_accessed_at）。',
+                },
+                order: {
+                    type: 'string',
+                    enum: ['asc', 'desc'],
+                    description: '排序方向（list 动作使用，默认 desc）。',
+                },
+                all: {
+                    type: 'boolean',
+                    description: '是否清空仓库全部缓存（delete 动作使用，高危操作，必需配合 confirm: true）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '高危破坏性操作确认标志（delete 当 all: true 时必需）。未传 true 时输出影响评估报告并拦截。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderCacheMarkdown(args, value) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            let repoTarget = args.repo;
+            if (!repoTarget) {
+                const meta = await executor.getRepoMetadata(cwd, sessionId);
+                if (meta?.nameWithOwner) {
+                    repoTarget = meta.nameWithOwner;
+                }
+            }
+            if (!repoTarget) {
+                throw new Error('未能自动识别当前工作区关联的 GitHub 仓库。请通过 `repo` 参数显式指定目标仓库 [owner/repo]（例如: "ItQianChen/dsh-github-flow"），或在当前工作区目录下关联 Git 远程仓库。');
+            }
+            const repoArgs = ['-R', repoTarget];
+            const runOpts = { cwd, sessionId };
+            switch (args.action) {
+                case 'list': {
+                    const listCmd = [
+                        'cache',
+                        'list',
+                        ...repoArgs,
+                        '--json',
+                        'createdAt,id,key,lastAccessedAt,ref,sizeInBytes,version',
+                    ];
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 30;
+                    listCmd.push('-L', String(limit));
+                    if (args.key) {
+                        listCmd.push('-k', String(args.key));
+                    }
+                    if (args.ref) {
+                        listCmd.push('-r', String(args.ref));
+                    }
+                    if (args.sort) {
+                        listCmd.push('--sort', args.sort);
+                    }
+                    if (args.order) {
+                        listCmd.push('--order', args.order);
+                    }
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    let rawData = res.data;
+                    if (!rawData && typeof res.rawOutput === 'string') {
+                        try {
+                            rawData = JSON.parse(res.rawOutput);
+                        }
+                        catch {
+                            rawData = [];
+                        }
+                    }
+                    return normalizeOutput(rawData || []);
+                }
+                case 'delete': {
+                    // 1. 全量清空分支
+                    if (args.all === true) {
+                        if (args.confirm !== true) {
+                            return {
+                                status: 'AWAITING_CONFIRMATION',
+                                action: 'delete',
+                                all: true,
+                                repo: repoTarget,
+                                warning: `⚠️ 高危破坏性操作：即将清空仓库 ${repoTarget} 的所有 GitHub Actions 构建缓存`,
+                                impact: `清空缓存不可逆，会导致后续流水线构建无法复用依赖与构建产物，显著增加 CI 运行耗时。`,
+                                requiredAction: `如确认彻底清空，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_cache(action: 'delete', all: true, confirm: true)\``,
+                            };
+                        }
+                        const delCmd = ['cache', 'delete', '--all', '--succeed-on-no-caches', ...repoArgs];
+                        if (args.ref) {
+                            delCmd.push('-r', String(args.ref));
+                        }
+                        const res = await executor.run(delCmd, runOpts);
+                        if (!res.ok)
+                            throw new Error(res.error);
+                        return {
+                            success: true,
+                            all: true,
+                            message: `🗑️ 成功清空仓库 ${repoTarget} 的 Actions 构建缓存` + (args.ref ? ` (Ref: ${args.ref})` : ''),
+                            detail: res.rawOutput || '',
+                        };
+                    }
+                    // 2. 按 cache_id 删除
+                    if (args.cache_id !== undefined && args.cache_id !== null && String(args.cache_id).trim() !== '') {
+                        const delCmd = ['cache', 'delete', String(args.cache_id), ...repoArgs];
+                        const res = await executor.run(delCmd, runOpts);
+                        if (!res.ok)
+                            throw new Error(res.error);
+                        return {
+                            success: true,
+                            cache_id: String(args.cache_id),
+                            message: `🗑️ 成功删除仓库 ${repoTarget} 中 ID 为 "${args.cache_id}" 的 Actions 缓存`,
+                            detail: res.rawOutput || '',
+                        };
+                    }
+                    // 3. 按 key 删除
+                    if (args.key !== undefined && args.key !== null && String(args.key).trim() !== '') {
+                        const delCmd = ['cache', 'delete', String(args.key), ...repoArgs];
+                        if (args.ref) {
+                            delCmd.push('-r', String(args.ref));
+                        }
+                        const res = await executor.run(delCmd, runOpts);
+                        if (!res.ok)
+                            throw new Error(res.error);
+                        return {
+                            success: true,
+                            key: String(args.key),
+                            message: `🗑️ 成功删除仓库 ${repoTarget} 中 Key 为 "${args.key}" 的 Actions 缓存` + (args.ref ? ` (Ref: ${args.ref})` : ''),
+                            detail: res.rawOutput || '',
+                        };
+                    }
+                    throw new Error('删除缓存时必须指定 `cache_id`、`key` 或 `all: true`（全量删除需配合 confirm: true）。');
+                }
+                default:
+                    throw new Error(`不支持的 cache 操作: "${args.action}"。可选值: list, delete。`);
+            }
+        },
+    };
+}

package/lib/tools/gist.d.ts

@@ -0,0 +1,155 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createGistTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            gist_id: {
+                type: string;
+                description: string;
+            };
+            filename: {
+                type: string;
+                description: string;
+            };
+            files: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            public: {
+                type: string;
+                description: string;
+            };
+            filter: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    output: {
+        schema: {
+            type: string;
+        };
+        render(args: any, value: any): {
+            type: string;
+            text: string;
+        }[];
+    };
+    execute(args: any, execContext: any): Promise<{
+        items: import("../renderers/gist.js").ParsedGistSummary[];
+        count: number;
+        rawText: string;
+        filename?: undefined;
+        content?: undefined;
+        url?: undefined;
+        public?: undefined;
+        description?: undefined;
+        success?: undefined;
+        message?: undefined;
+        detail?: undefined;
+        status?: undefined;
+        action?: undefined;
+        gist_id?: undefined;
+        warning?: undefined;
+        impact?: undefined;
+        requiredAction?: undefined;
+    } | {
+        items?: undefined;
+        count?: undefined;
+        rawText?: undefined;
+        gist_id: string;
+        filename: any;
+        content: string;
+        url?: undefined;
+        public?: undefined;
+        description?: undefined;
+        success?: undefined;
+        message?: undefined;
+        detail?: undefined;
+        status?: undefined;
+        action?: undefined;
+        warning?: undefined;
+        impact?: undefined;
+        requiredAction?: undefined;
+    } | {
+        items?: undefined;
+        count?: undefined;
+        rawText?: undefined;
+        filename?: undefined;
+        content?: undefined;
+        success: boolean;
+        url: string;
+        gist_id: string;
+        public: boolean;
+        description: any;
+        message: string;
+        detail?: undefined;
+        status?: undefined;
+        action?: undefined;
+        warning?: undefined;
+        impact?: undefined;
+        requiredAction?: undefined;
+    } | {
+        items?: undefined;
+        count?: undefined;
+        rawText?: undefined;
+        filename?: undefined;
+        content?: undefined;
+        url?: undefined;
+        public?: undefined;
+        description?: undefined;
+        success: boolean;
+        gist_id: string;
+        message: string;
+        detail: string;
+        status?: undefined;
+        action?: undefined;
+        warning?: undefined;
+        impact?: undefined;
+        requiredAction?: undefined;
+    } | {
+        items?: undefined;
+        count?: undefined;
+        rawText?: undefined;
+        filename?: undefined;
+        content?: undefined;
+        url?: undefined;
+        public?: undefined;
+        description?: undefined;
+        success?: undefined;
+        message?: undefined;
+        detail?: undefined;
+        status: string;
+        action: string;
+        gist_id: string;
+        warning: string;
+        impact: string;
+        requiredAction: string;
+    }>;
+};

package/lib/tools/gist.js

@@ -0,0 +1,190 @@
+import { renderGistMarkdown, parseGistListOutput } from '../renderers/markdown.js';
+export function createGistTool(executor) {
+    return {
+        name: 'github_gist',
+        description: '管理 GitHub Gist 代码片段与诊断留痕：查看 Gist 列表、检视代码正文 (view)、通过文本内容或本地文件创建新 Gist (create，默认安全 secret 模式)、编辑以及安全删除。删除操作不可逆，需 confirm: true。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'create', 'edit', 'delete'],
+                    description: 'Gist 操作类型。list 查看列表、view 查看正文、create 新建、edit 修改、delete 物理删除（需 confirm）。',
+                },
+                gist_id: {
+                    type: 'string',
+                    description: 'Gist 唯一 ID 或完整 URL（view, edit, delete 动作必需，例如 "5b0e0062eb8e9654adad7bb1d81cc75f"）。',
+                },
+                filename: {
+                    type: 'string',
+                    description: '文件名（view 动作指定查看文件、create 动作命名单文件、edit 动作指定编辑文件；默认 "snippet.txt"）。',
+                },
+                files: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '本地文件路径列表（create 动作上传多文件时使用）。',
+                },
+                content: {
+                    type: 'string',
+                    description: '代码片段或文本正文内容（create 动作直接传正文时使用，通过 stdin 安全管道传入）。',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Gist 描述摘要或用途备注（create, edit 动作可选）。',
+                },
+                public: {
+                    type: 'boolean',
+                    description: '是否公开创建为 Public Gist（create 动作可选，默认 false 即 Secret 弱保密模式）。',
+                },
+                filter: {
+                    type: 'string',
+                    description: '按正则表达式过滤检索描述或文件内容（list 动作可选）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回 Gist 数量上限（list 动作使用，默认 10）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '高危破坏性操作确认标志（delete 动作必需）。未传 true 时输出影响评估报告并拦截。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderGistMarkdown(args, value) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const runOpts = { cwd, sessionId, rawText: true };
+            switch (args.action) {
+                case 'list': {
+                    const listCmd = ['gist', 'list'];
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 10;
+                    listCmd.push('-L', String(limit));
+                    if (args.public === true) {
+                        listCmd.push('--public');
+                    }
+                    else if (args.public === false) {
+                        listCmd.push('--secret');
+                    }
+                    if (args.filter) {
+                        listCmd.push('--filter', String(args.filter));
+                    }
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    const items = parseGistListOutput(res.rawOutput || '');
+                    return { items, count: items.length, rawText: res.rawOutput || '' };
+                }
+                case 'view': {
+                    if (!args.gist_id) {
+                        throw new Error('查看 Gist 时 `gist_id` 参数为必填项（可提供 Gist 数字字母 ID 或完整 URL）。');
+                    }
+                    const viewCmd = ['gist', 'view', String(args.gist_id), '-r'];
+                    if (args.filename) {
+                        viewCmd.push('-f', String(args.filename));
+                    }
+                    const res = await executor.run(viewCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        gist_id: String(args.gist_id),
+                        filename: args.filename,
+                        content: res.rawOutput || '',
+                    };
+                }
+                case 'create': {
+                    if (!args.content && (!args.files || !Array.isArray(args.files) || args.files.length === 0)) {
+                        throw new Error('创建 Gist 时必须提供 `content`（代码片段文本）或 `files`（本地文件路径数组）。');
+                    }
+                    const createCmd = ['gist', 'create'];
+                    let stdinData;
+                    if (args.content) {
+                        createCmd.push('-');
+                        const fn = args.filename ? String(args.filename).trim() : 'snippet.txt';
+                        createCmd.push('-f', fn);
+                        stdinData = String(args.content);
+                    }
+                    else if (args.files) {
+                        for (const f of args.files) {
+                            createCmd.push(String(f));
+                        }
+                    }
+                    if (args.public === true) {
+                        createCmd.push('--public');
+                    }
+                    if (args.description) {
+                        createCmd.push('-d', String(args.description));
+                    }
+                    const res = await executor.run(createCmd, { ...runOpts, stdin: stdinData });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    const rawUrl = (res.rawOutput || '').trim();
+                    const urlMatch = rawUrl.match(/gist\.github\.com\/([^/]+\/)?([0-9a-fA-F]+)/i);
+                    const gistId = urlMatch ? urlMatch[2] : rawUrl;
+                    return {
+                        success: true,
+                        url: rawUrl,
+                        gist_id: gistId,
+                        public: args.public === true,
+                        description: args.description,
+                        message: `✅ 成功创建 Gist: ${rawUrl}`,
+                    };
+                }
+                case 'edit': {
+                    if (!args.gist_id) {
+                        throw new Error('编辑 Gist 时 `gist_id` 参数为必填项。');
+                    }
+                    const editCmd = ['gist', 'edit', String(args.gist_id)];
+                    if (args.description) {
+                        editCmd.push('-d', String(args.description));
+                    }
+                    if (args.filename) {
+                        editCmd.push('-f', String(args.filename));
+                    }
+                    const res = await executor.run(editCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        success: true,
+                        gist_id: String(args.gist_id),
+                        message: `✅ 成功更新 Gist "${args.gist_id}"`,
+                        detail: res.rawOutput || '',
+                    };
+                }
+                case 'delete': {
+                    if (!args.gist_id) {
+                        throw new Error('删除 Gist 时 `gist_id` 参数为必填项。');
+                    }
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            action: 'delete',
+                            gist_id: String(args.gist_id),
+                            warning: `⚠️ 高危破坏性操作：即将永久删除 Gist 代码片段 "${args.gist_id}"`,
+                            impact: `删除 Gist 为物理删除，无法通过 GitHub API 恢复，所有引用该 Gist URL 的外部链接将失效并返回 404。`,
+                            requiredAction: `如确认彻底删除，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_gist(action: 'delete', gist_id: '${args.gist_id}', confirm: true)\``,
+                        };
+                    }
+                    const delCmd = ['gist', 'delete', String(args.gist_id), '--yes'];
+                    const res = await executor.run(delCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        success: true,
+                        gist_id: String(args.gist_id),
+                        message: `🗑️ 成功删除 Gist 代码片段 "${args.gist_id}"`,
+                        detail: res.rawOutput || '',
+                    };
+                }
+                default:
+                    throw new Error(`不支持的 gist 操作: "${args.action}"。可选值: list, view, create, edit, delete。`);
+            }
+        },
+    };
+}