dsh-github-flow 0.3.0 → 0.5.0

package/lib/tools/project.js

@@ -0,0 +1,241 @@
+import { renderProjectMarkdown } 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 : '' };
+}
+/**
+ * 检测错误信息是否属于 Scope 权限不足，并返回标准自愈对象
+ */
+export function checkScopeRequired(errorMsg, scope, command, tool) {
+    const lower = (errorMsg || '').toLowerCase();
+    if (lower.includes('missing required scopes') || lower.includes('needs the') || lower.includes('scope')) {
+        return {
+            status: 'SCOPE_REQUIRED',
+            scope,
+            command,
+            tool,
+        };
+    }
+    return null;
+}
+export function createProjectTool(executor) {
+    return {
+        name: 'github_project',
+        description: '管理 GitHub Projects v2 项目看板与任务规划：查看项目列表与卡片条目、关联 Issue/PR 到看板、创建草稿任务、删除看板条目。未授权时提供平台感知自愈命令。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'item-list', 'item-add', 'item-create', 'item-delete'],
+                    description: 'Project 操作类型。list 查看项目列表、view 查看项目详情、item-list 查看看板条目、item-add 添加现有Issue/PR、item-create 创建草稿条目、item-delete 删除条目。',
+                },
+                owner: {
+                    type: 'string',
+                    description: '项目所属用户或组织（缺省为 "@me" 即当前用户）。',
+                },
+                project_number: {
+                    type: 'number',
+                    description: '项目数字编号（view, item-list, item-add, item-create 动作必需）。',
+                },
+                item_id: {
+                    type: 'string',
+                    description: '项目条目唯一标识 ID（item-delete 动作必需）。',
+                },
+                url: {
+                    type: 'string',
+                    description: '要添加到项目的 Issue 或 PR URL（item-add 动作必需）。',
+                },
+                title: {
+                    type: 'string',
+                    description: '草稿条目标题（item-create 动作必需）。',
+                },
+                body: {
+                    type: 'string',
+                    description: '草稿条目正文描述（item-create 动作可选）。',
+                },
+                query: {
+                    type: 'string',
+                    description: '过滤查询语法（item-list 动作可选，如 "is:open assignee:@me"）。',
+                },
+                closed: {
+                    type: 'boolean',
+                    description: '是否包含已关闭的项目（list 动作使用，默认 false）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回数量上限（list 与 item-list 动作使用，默认 30）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '危险操作确认标记（item-delete 动作必需）。未确认时输出影响评估并拦截。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderProjectMarkdown(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 owner = typeof args.owner === 'string' && args.owner.trim() ? args.owner.trim() : '@me';
+            const runOpts = { cwd, sessionId };
+            switch (args.action) {
+                case 'list': {
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 100) : 30;
+                    const listCmd = [
+                        'project', 'list',
+                        '--format', 'json',
+                        '--owner', owner,
+                        '-L', String(limit),
+                    ];
+                    if (args.closed === true)
+                        listCmd.push('--closed');
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'read:project', 'gh auth refresh -s read:project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'view': {
+                    if (!args.project_number || typeof args.project_number !== 'number') {
+                        throw new Error('view 操作必须提供 project_number（项目数字编号）');
+                    }
+                    const viewCmd = [
+                        'project', 'view', String(args.project_number),
+                        '--format', 'json',
+                        '--owner', owner,
+                    ];
+                    const res = await executor.run(viewCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'read:project', 'gh auth refresh -s read:project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'item-list': {
+                    if (!args.project_number || typeof args.project_number !== 'number') {
+                        throw new Error('item-list 操作必须提供 project_number（项目数字编号）');
+                    }
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 100) : 30;
+                    const itemCmd = [
+                        'project', 'item-list', String(args.project_number),
+                        '--format', 'json',
+                        '--owner', owner,
+                        '-L', String(limit),
+                    ];
+                    if (args.query)
+                        itemCmd.push('--query', String(args.query).trim());
+                    const res = await executor.run(itemCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'read:project', 'gh auth refresh -s read:project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'item-add': {
+                    if (!args.project_number || typeof args.project_number !== 'number') {
+                        throw new Error('item-add 操作必须提供 project_number（项目数字编号）');
+                    }
+                    if (!args.url || typeof args.url !== 'string' || !args.url.trim()) {
+                        throw new Error('item-add 操作必须提供 url（Issue 或 PR 的完整链接）');
+                    }
+                    const addCmd = [
+                        'project', 'item-add', String(args.project_number),
+                        '--owner', owner,
+                        '--url', args.url.trim(),
+                        '--format', 'json',
+                    ];
+                    const res = await executor.run(addCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'project', 'gh auth refresh -s project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return {
+                        message: `已成功将条目添加到项目 #${args.project_number}`,
+                        output: res.rawOutput || 'Item added',
+                    };
+                }
+                case 'item-create': {
+                    if (!args.project_number || typeof args.project_number !== 'number') {
+                        throw new Error('item-create 操作必须提供 project_number（项目数字编号）');
+                    }
+                    if (!args.title || typeof args.title !== 'string' || !args.title.trim()) {
+                        throw new Error('item-create 操作必须提供 title（草稿条目标题）');
+                    }
+                    const createCmd = [
+                        'project', 'item-create', String(args.project_number),
+                        '--owner', owner,
+                        '--title', args.title.trim(),
+                        '--format', 'json',
+                    ];
+                    if (args.body)
+                        createCmd.push('--body', String(args.body).trim());
+                    const res = await executor.run(createCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'project', 'gh auth refresh -s project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return {
+                        message: `已成功在项目 #${args.project_number} 中创建条目「${args.title.trim()}」`,
+                        output: res.rawOutput || 'Draft item created',
+                    };
+                }
+                case 'item-delete': {
+                    if (!args.item_id || typeof args.item_id !== 'string' || !args.item_id.trim()) {
+                        throw new Error('item-delete 操作必须提供 item_id（条目唯一 ID）');
+                    }
+                    const cleanItemId = args.item_id.trim();
+                    // 确认防线拦截
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 删除确认拦截：你即将从看板中删除条目（ID: ${cleanItemId}）。`,
+                            impact: '该操作将从项目看板中物理移除该条目（若是关联的 Issue/PR，实体不会被删除，仅解除看板关联）。',
+                            requiredAction: '如确认删除，请在参数中附加 `confirm: true` 重新调用。',
+                        };
+                    }
+                    const deleteCmd = [
+                        'project', 'item-delete',
+                        '--owner', owner,
+                        '--id', cleanItemId,
+                        '--format', 'json',
+                    ];
+                    const res = await executor.run(deleteCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'project', 'gh auth refresh -s project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return {
+                        message: `条目「${cleanItemId}」已从项目看板中成功删除`,
+                        output: res.rawOutput || 'Item deleted',
+                    };
+                }
+                default:
+                    throw new Error(`未知的 Project 操作: ${args.action}`);
+            }
+        },
+    };
+}

package/lib/tools/repo.js

@@ -239,7 +239,19 @@ export function createRepoTool(executor) {
                     if (content.includes('\0')) {
                         throw new Error(`「${args.path}」是二进制文件（检测到 NUL 字节），不适合文本读取。请改用 github_api(endpoint: 'repos/${owner}/${repoName}/contents/${args.path.split('/').map(encodeURIComponent).join('/')}', raw: true, binary 场景自行落盘) 获取字节流。`);
                     }
-                    return { path: args.path, ref: args.ref, content, size: content.length, ...(res.degraded ? { degraded: res.degraded, degradedReason: res.degradedReason } : {}) };
+                    const resultObj = {
+                        path: args.path,
+                        content,
+                        size: content.length,
+                    };
+                    if (args.ref) {
+                        resultObj.ref = args.ref;
+                    }
+                    if (res.degraded) {
+                        resultObj.degraded = res.degraded;
+                        resultObj.degradedReason = res.degradedReason;
+                    }
+                    return resultObj;
                 }
                 case 'read_dir': {
                     let repoTarget = args.repo;

package/lib/tools/ruleset.d.ts

@@ -0,0 +1,80 @@
+import type { GhExecutor } from '../executor.js';
+export interface ParsedRule {
+    name: string;
+    params: string;
+    source: string;
+}
+export interface ParsedRulesetCheck {
+    ruleCount: number;
+    branch: string;
+    repo: string;
+    rules: ParsedRule[];
+    rawText: string;
+}
+/**
+ * 解析 gh ruleset check 的纯文本输出，提取适用规则数、分支、仓库以及具体规则详情
+ */
+export declare function parseRulesetCheckOutput(output: string): ParsedRulesetCheck;
+export declare function createRulesetTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            branch: {
+                type: string;
+                description: string;
+            };
+            default_branch: {
+                type: string;
+                description: string;
+            };
+            ruleset_id: {
+                type: string;
+                description: string;
+            };
+            org: {
+                type: string;
+                description: string;
+            };
+            no_parents: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                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<ParsedRulesetCheck | {
+        rawText: string;
+        org: any;
+        repo: string;
+        ruleset_id?: undefined;
+    } | {
+        ruleset_id: string;
+        rawText: string;
+        org: any;
+        repo: string;
+    }>;
+};

package/lib/tools/ruleset.js

@@ -0,0 +1,177 @@
+import { renderRulesetMarkdown } from '../renderers/markdown.js';
+/**
+ * 解析 gh ruleset check 的纯文本输出，提取适用规则数、分支、仓库以及具体规则详情
+ */
+export function parseRulesetCheckOutput(output) {
+    const trimmed = (output || '').trim();
+    const result = {
+        ruleCount: 0,
+        branch: '',
+        repo: '',
+        rules: [],
+        rawText: trimmed,
+    };
+    if (!trimmed)
+        return result;
+    // 1. 匹配首行: "N rules apply to branch <branch> in repo <repo>"
+    const firstLineMatch = trimmed.match(/^(\d+)\s+rules?\s+apply\s+to\s+branch\s+(\S+)\s+in\s+repo\s+(\S+)/i);
+    if (firstLineMatch) {
+        result.ruleCount = parseInt(firstLineMatch[1], 10);
+        result.branch = firstLineMatch[2];
+        result.repo = firstLineMatch[3];
+    }
+    // 2. 匹配具体规则明细项：形如 "- <name>: <params>\n    (configured in <source>)"
+    const rulePattern = /-\s*([a-zA-Z0-9_-]+):\s*([^\n\r]+)(?:[\r\n]+\s*\((configured in [^)]+)\))?/g;
+    let match;
+    while ((match = rulePattern.exec(trimmed)) !== null) {
+        result.rules.push({
+            name: match[1],
+            params: (match[2] || '').trim(),
+            source: (match[3] || '').trim(),
+        });
+    }
+    // 若首行未声明数量但解析到了规则列表，自动校正
+    if (result.rules.length > 0 && result.ruleCount === 0) {
+        result.ruleCount = result.rules.length;
+    }
+    return result;
+}
+export function createRulesetTool(executor) {
+    return {
+        name: 'github_ruleset',
+        description: '查看与诊断 GitHub 仓库/组织规则集 (Rulesets)：检查分支适用的合并策略规则 (check)、查看规则集列表 (list) 与详情 (view)。是诊断“PR 为什么不能合并”的权威规则策略视角。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'check'],
+                    description: 'Ruleset 操作类型。check 检查分支规则约束（策略排障核心）、list 查看规则集列表、view 查看规则集详情。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则识别当前工作区仓库。',
+                },
+                branch: {
+                    type: 'string',
+                    description: '要检查的分支名称（check 动作使用，缺省为当前分支）。',
+                },
+                default_branch: {
+                    type: 'boolean',
+                    description: '是否直接检查目标仓库默认分支的规则约束（check 动作可选，映射 --default）。',
+                },
+                ruleset_id: {
+                    type: 'string',
+                    description: '规则集 ID（view 动作必需，避免交互式选择挂起）。',
+                },
+                org: {
+                    type: 'string',
+                    description: '组织名称（list, view 动作可选，查看组织级规则集；需 admin:org 权限）。',
+                },
+                no_parents: {
+                    type: 'boolean',
+                    description: '是否排除上级组织配置的继承规则集（list, view 动作可选，默认包含上级继承；true 时仅看当前层级）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回规则集数量上限（list 动作使用，默认 30）。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderRulesetMarkdown(args, value) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            // 解析当前工作区仓库（若未传 org 且需要 repo 维度）
+            const resolveRepoTarget = async () => {
+                if (args.repo)
+                    return args.repo;
+                const meta = await executor.getRepoMetadata(cwd, sessionId);
+                if (meta?.nameWithOwner)
+                    return meta.nameWithOwner;
+                throw new Error('未能自动识别当前工作区关联的 GitHub 仓库。请通过 `repo` 参数显式指定目标仓库 [owner/repo]（例如: "ItQianChen/dsh-github-flow"），或在当前工作区目录下关联 Git 远程仓库。');
+            };
+            const runOpts = { cwd, sessionId };
+            switch (args.action) {
+                case 'check': {
+                    const repoTarget = await resolveRepoTarget();
+                    const checkCmd = ['ruleset', 'check'];
+                    if (args.branch) {
+                        checkCmd.push(args.branch);
+                    }
+                    if (args.default_branch) {
+                        checkCmd.push('--default');
+                    }
+                    checkCmd.push('-R', repoTarget);
+                    const res = await executor.run(checkCmd, { ...runOpts, rawText: true });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    const parsed = parseRulesetCheckOutput(res.rawOutput || '');
+                    if (!parsed.repo)
+                        parsed.repo = repoTarget;
+                    if (!parsed.branch && args.branch)
+                        parsed.branch = args.branch;
+                    return parsed;
+                }
+                case 'list': {
+                    const listCmd = ['ruleset', 'list'];
+                    let repoTarget = '';
+                    if (args.org) {
+                        listCmd.push('--org', args.org);
+                    }
+                    else {
+                        repoTarget = await resolveRepoTarget();
+                        listCmd.push('-R', repoTarget);
+                    }
+                    if (args.no_parents) {
+                        listCmd.push('--no-parents');
+                    }
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 30;
+                    listCmd.push('-L', String(limit));
+                    const res = await executor.run(listCmd, { ...runOpts, rawText: true });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        rawText: (res.rawOutput || '').trim(),
+                        org: args.org,
+                        repo: repoTarget,
+                    };
+                }
+                case 'view': {
+                    if (args.ruleset_id === undefined || args.ruleset_id === null || String(args.ruleset_id).trim() === '') {
+                        throw new Error('查看规则集详情时 `ruleset_id` 参数为必填项（输入规则集数字 ID，如 "4898070"）。');
+                    }
+                    const viewCmd = ['ruleset', 'view', String(args.ruleset_id)];
+                    let repoTarget = '';
+                    if (args.org) {
+                        viewCmd.push('--org', args.org);
+                    }
+                    else {
+                        repoTarget = await resolveRepoTarget();
+                        viewCmd.push('-R', repoTarget);
+                    }
+                    if (args.no_parents) {
+                        viewCmd.push('--no-parents');
+                    }
+                    const res = await executor.run(viewCmd, { ...runOpts, rawText: true });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        ruleset_id: String(args.ruleset_id),
+                        rawText: (res.rawOutput || '').trim(),
+                        org: args.org,
+                        repo: repoTarget,
+                    };
+                }
+                default:
+                    throw new Error(`不支持的 ruleset 操作: "${args.action}"。可选值: check, list, view。`);
+            }
+        },
+    };
+}

package/lib/tools/skill.d.ts

@@ -43,6 +43,29 @@ export declare function createSkillTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            directory: {
+                type: string;
+                description: string;
+            };
+            dry_run: {
+                type: string;
+                description: string;
+            };
+            fix: {
+                type: string;
+                description: string;
+            };
+            tag: {
+                type: string;
+                description: string;
+            };
+            skill_names: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
             confirm: {
                 type: string;
                 description: string;
@@ -59,5 +82,5 @@ export declare function createSkillTool(executor: GhExecutor): {
             text: string;
         }[];
     };
-    execute(args: any, execContext: any): Promise<Record<string, any>>;
+    execute(args: any, execContext: any): Promise<Record<string, any> | import("../renderers/skill.js").SkillPublishReport>;
 };