@slates-integrations/github 0.2.0-rc.2

package/src/tools/manage-issue.ts

@@ -0,0 +1,94 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let manageIssue = SlateTool.create(spec, {
+  name: 'Manage Issue',
+  key: 'manage_issue',
+  description: `Create a new issue or update an existing one in a GitHub repository.
+When creating: provide title and optionally body, labels, assignees, and milestone.
+When updating: provide the issue number along with fields to change (title, body, state, labels, assignees).`,
+  instructions: [
+    'To create a new issue, omit issueNumber and provide at least a title.',
+    'To update an existing issue, provide the issueNumber along with the fields to change.',
+    'To close an issue, set state to "closed". To reopen, set state to "open".'
+  ]
+})
+  .input(
+    z.object({
+      owner: z.string().describe('Repository owner (user or organization)'),
+      repo: z.string().describe('Repository name'),
+      issueNumber: z
+        .number()
+        .optional()
+        .describe('Issue number to update. Omit to create a new issue.'),
+      title: z.string().optional().describe('Issue title (required when creating)'),
+      body: z.string().optional().describe('Issue body in Markdown'),
+      state: z.enum(['open', 'closed']).optional().describe('Issue state (only for updates)'),
+      stateReason: z
+        .enum(['completed', 'not_planned', 'reopened'])
+        .optional()
+        .describe('Reason for state change'),
+      labels: z.array(z.string()).optional().describe('Labels to set on the issue'),
+      assignees: z.array(z.string()).optional().describe('Usernames to assign'),
+      milestone: z
+        .number()
+        .nullable()
+        .optional()
+        .describe('Milestone number to set, or null to remove')
+    })
+  )
+  .output(
+    z.object({
+      issueNumber: z.number().describe('Issue number'),
+      issueId: z.number().describe('Unique issue ID'),
+      title: z.string().describe('Issue title'),
+      state: z.string().describe('Issue state (open/closed)'),
+      htmlUrl: z.string().describe('URL to the issue on GitHub'),
+      author: z.string().describe('Issue author login'),
+      assignees: z.array(z.string()).describe('Assigned usernames'),
+      labels: z.array(z.string()).describe('Label names'),
+      createdAt: z.string().describe('Creation timestamp'),
+      updatedAt: z.string().describe('Last update timestamp')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let { owner, repo, issueNumber, ...data } = ctx.input;
+    let issue: any;
+
+    if (issueNumber) {
+      issue = await client.updateIssue(owner, repo, issueNumber, data);
+    } else {
+      if (!data.title) {
+        throw new Error('Title is required when creating a new issue.');
+      }
+      issue = await client.createIssue(owner, repo, {
+        title: data.title,
+        body: data.body,
+        assignees: data.assignees,
+        labels: data.labels,
+        milestone: data.milestone ?? undefined
+      });
+    }
+
+    return {
+      output: {
+        issueNumber: issue.number,
+        issueId: issue.id,
+        title: issue.title,
+        state: issue.state,
+        htmlUrl: issue.html_url,
+        author: issue.user.login,
+        assignees: (issue.assignees ?? []).map((a: any) => a.login),
+        labels: (issue.labels ?? []).map((l: any) => l.name),
+        createdAt: issue.created_at,
+        updatedAt: issue.updated_at
+      },
+      message: issueNumber
+        ? `Updated issue **#${issue.number}** in **${owner}/${repo}** — ${issue.html_url}`
+        : `Created issue **#${issue.number}**: "${issue.title}" in **${owner}/${repo}** — ${issue.html_url}`
+    };
+  })
+  .build();

package/src/tools/manage-labels.ts

@@ -0,0 +1,93 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let manageLabels = SlateTool.create(spec, {
+  name: 'Manage Labels',
+  key: 'manage_labels',
+  description: `List existing labels or create a new label in a GitHub repository. Labels can be applied to issues and pull requests for categorization.`
+})
+  .input(
+    z.object({
+      owner: z.string().describe('Repository owner'),
+      repo: z.string().describe('Repository name'),
+      action: z.enum(['list', 'create']).describe('Action to perform'),
+      name: z.string().optional().describe('Label name (required for create)'),
+      color: z
+        .string()
+        .optional()
+        .describe('Label color hex code without "#" (e.g., "ff0000")'),
+      description: z.string().optional().describe('Label description'),
+      perPage: z.number().optional().describe('Results per page for list'),
+      page: z.number().optional().describe('Page number for list')
+    })
+  )
+  .output(
+    z.object({
+      labels: z
+        .array(
+          z.object({
+            labelId: z.number().describe('Label ID'),
+            name: z.string().describe('Label name'),
+            color: z.string().describe('Label color hex'),
+            description: z.string().nullable().describe('Label description')
+          })
+        )
+        .optional()
+        .describe('List of labels (for list action)'),
+      label: z
+        .object({
+          labelId: z.number().describe('Label ID'),
+          name: z.string().describe('Label name'),
+          color: z.string().describe('Label color hex'),
+          description: z.string().nullable().describe('Label description')
+        })
+        .optional()
+        .describe('Created label (for create action)')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let { owner, repo, action } = ctx.input;
+
+    if (action === 'list') {
+      let labels = await client.listLabels(owner, repo, {
+        perPage: ctx.input.perPage,
+        page: ctx.input.page
+      });
+      let mapped = labels.map((l: any) => ({
+        labelId: l.id,
+        name: l.name,
+        color: l.color,
+        description: l.description
+      }));
+      return {
+        output: { labels: mapped },
+        message: `Found **${mapped.length}** labels in **${owner}/${repo}**.`
+      };
+    }
+
+    if (!ctx.input.name) {
+      throw new Error('name is required for create action.');
+    }
+
+    let label = await client.createLabel(owner, repo, {
+      name: ctx.input.name,
+      color: ctx.input.color,
+      description: ctx.input.description
+    });
+
+    return {
+      output: {
+        label: {
+          labelId: label.id,
+          name: label.name,
+          color: label.color,
+          description: label.description
+        }
+      },
+      message: `Created label **${label.name}** in **${owner}/${repo}**.`
+    };
+  })
+  .build();

package/src/tools/manage-pull-request.ts

@@ -0,0 +1,111 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let managePullRequest = SlateTool.create(spec, {
+  name: 'Manage Pull Request',
+  key: 'manage_pull_request',
+  description: `Create a new pull request or update an existing one.
+When creating: provide head branch, base branch, and title.
+When updating: provide the pull request number along with fields to change.`,
+  instructions: [
+    'To create a new PR, omit pullNumber and provide head, base, and title.',
+    'To update an existing PR, provide pullNumber along with fields to change.',
+    'To close a PR without merging, set state to "closed".'
+  ]
+})
+  .input(
+    z.object({
+      owner: z.string().describe('Repository owner (user or organization)'),
+      repo: z.string().describe('Repository name'),
+      pullNumber: z
+        .number()
+        .optional()
+        .describe('Pull request number to update. Omit to create a new PR.'),
+      title: z.string().optional().describe('PR title (required when creating)'),
+      body: z.string().optional().describe('PR description in Markdown'),
+      head: z
+        .string()
+        .optional()
+        .describe(
+          'Head branch (required when creating). Use "fork_owner:branch" for cross-repo PRs.'
+        ),
+      base: z
+        .string()
+        .optional()
+        .describe('Base branch to merge into (required when creating)'),
+      draft: z.boolean().optional().describe('Create as draft PR'),
+      state: z.enum(['open', 'closed']).optional().describe('PR state (only for updates)'),
+      maintainerCanModify: z
+        .boolean()
+        .optional()
+        .describe('Allow maintainers to push to the head branch')
+    })
+  )
+  .output(
+    z.object({
+      pullNumber: z.number().describe('Pull request number'),
+      pullRequestId: z.number().describe('Unique PR ID'),
+      title: z.string().describe('PR title'),
+      state: z.string().describe('PR state'),
+      htmlUrl: z.string().describe('URL to the PR on GitHub'),
+      author: z.string().describe('PR author login'),
+      head: z.string().describe('Head branch ref'),
+      base: z.string().describe('Base branch ref'),
+      draft: z.boolean().describe('Whether the PR is a draft'),
+      merged: z.boolean().describe('Whether the PR has been merged'),
+      mergeable: z.boolean().nullable().describe('Whether the PR is mergeable'),
+      createdAt: z.string().describe('Creation timestamp'),
+      updatedAt: z.string().describe('Last update timestamp')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let { owner, repo, pullNumber, ...data } = ctx.input;
+    let pr: any;
+
+    if (pullNumber) {
+      pr = await client.updatePullRequest(owner, repo, pullNumber, {
+        title: data.title,
+        body: data.body,
+        state: data.state,
+        base: data.base,
+        maintainerCanModify: data.maintainerCanModify
+      });
+    } else {
+      if (!data.title || !data.head || !data.base) {
+        throw new Error('title, head, and base are required when creating a pull request.');
+      }
+      pr = await client.createPullRequest(owner, repo, {
+        title: data.title,
+        head: data.head,
+        base: data.base,
+        body: data.body,
+        draft: data.draft,
+        maintainerCanModify: data.maintainerCanModify
+      });
+    }
+
+    return {
+      output: {
+        pullNumber: pr.number,
+        pullRequestId: pr.id,
+        title: pr.title,
+        state: pr.state,
+        htmlUrl: pr.html_url,
+        author: pr.user.login,
+        head: pr.head.ref,
+        base: pr.base.ref,
+        draft: pr.draft,
+        merged: pr.merged,
+        mergeable: pr.mergeable ?? null,
+        createdAt: pr.created_at,
+        updatedAt: pr.updated_at
+      },
+      message: pullNumber
+        ? `Updated PR **#${pr.number}** in **${owner}/${repo}** — ${pr.html_url}`
+        : `Created PR **#${pr.number}**: "${pr.title}" (${pr.head.ref} → ${pr.base.ref}) — ${pr.html_url}`
+    };
+  })
+  .build();

package/src/tools/manage-workflow.ts

@@ -0,0 +1,242 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let manageWorkflow = SlateTool.create(spec, {
+  name: 'Manage Workflow',
+  key: 'manage_workflow',
+  description: `Interact with GitHub Actions workflows: list workflows, list runs, trigger a workflow dispatch, cancel or rerun a workflow run, and view run jobs.`,
+  instructions: [
+    'Use action "list_workflows" to list all workflows in a repository.',
+    'Use "list_runs" to see recent workflow runs, optionally filtered by workflow, branch, event, or status.',
+    'Use "trigger" to dispatch a workflow_dispatch event. The workflow must support the workflow_dispatch trigger.',
+    'Use "cancel" or "rerun" with a runId.',
+    'Use "get_run" to get details of a specific run.',
+    'Use "list_jobs" to see jobs of a specific run.'
+  ]
+})
+  .input(
+    z.object({
+      owner: z.string().describe('Repository owner'),
+      repo: z.string().describe('Repository name'),
+      action: z
+        .enum([
+          'list_workflows',
+          'list_runs',
+          'get_run',
+          'trigger',
+          'cancel',
+          'rerun',
+          'list_jobs'
+        ])
+        .describe('Workflow action to perform'),
+      workflowId: z
+        .union([z.number(), z.string()])
+        .optional()
+        .describe('Workflow ID or filename (e.g., "ci.yml")'),
+      runId: z
+        .number()
+        .optional()
+        .describe('Workflow run ID (for get_run, cancel, rerun, list_jobs)'),
+      ref: z
+        .string()
+        .optional()
+        .describe('Git ref to trigger the workflow on (for trigger action)'),
+      inputs: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Workflow inputs (for trigger action)'),
+      branch: z.string().optional().describe('Filter runs by branch'),
+      event: z.string().optional().describe('Filter runs by event type'),
+      status: z
+        .string()
+        .optional()
+        .describe('Filter runs by status (e.g., "completed", "in_progress", "queued")'),
+      perPage: z.number().optional().describe('Results per page'),
+      page: z.number().optional().describe('Page number')
+    })
+  )
+  .output(
+    z.object({
+      workflows: z
+        .array(
+          z.object({
+            workflowId: z.number(),
+            name: z.string(),
+            path: z.string(),
+            state: z.string()
+          })
+        )
+        .optional()
+        .describe('List of workflows'),
+      runs: z
+        .array(
+          z.object({
+            runId: z.number(),
+            name: z.string().nullable(),
+            status: z.string().nullable(),
+            conclusion: z.string().nullable(),
+            headBranch: z.string().nullable(),
+            event: z.string(),
+            htmlUrl: z.string(),
+            createdAt: z.string()
+          })
+        )
+        .optional()
+        .describe('List of workflow runs'),
+      run: z
+        .object({
+          runId: z.number(),
+          name: z.string().nullable(),
+          status: z.string().nullable(),
+          conclusion: z.string().nullable(),
+          headBranch: z.string().nullable(),
+          headSha: z.string(),
+          event: z.string(),
+          htmlUrl: z.string(),
+          createdAt: z.string(),
+          updatedAt: z.string()
+        })
+        .optional()
+        .describe('Single workflow run details'),
+      jobs: z
+        .array(
+          z.object({
+            jobId: z.number(),
+            name: z.string(),
+            status: z.string(),
+            conclusion: z.string().nullable(),
+            startedAt: z.string().nullable(),
+            completedAt: z.string().nullable()
+          })
+        )
+        .optional()
+        .describe('List of jobs in a run'),
+      triggered: z.boolean().optional().describe('Whether the workflow was triggered'),
+      cancelled: z.boolean().optional().describe('Whether the run was cancelled'),
+      rerunStarted: z.boolean().optional().describe('Whether the rerun was started')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let { owner, repo, action } = ctx.input;
+
+    if (action === 'list_workflows') {
+      let data = await client.listWorkflows(owner, repo, {
+        perPage: ctx.input.perPage,
+        page: ctx.input.page
+      });
+      let workflows = data.workflows.map((w: any) => ({
+        workflowId: w.id,
+        name: w.name,
+        path: w.path,
+        state: w.state
+      }));
+      return {
+        output: { workflows },
+        message: `Found **${workflows.length}** workflows in **${owner}/${repo}**.`
+      };
+    }
+
+    if (action === 'list_runs') {
+      let data = await client.listWorkflowRuns(owner, repo, {
+        workflowId: ctx.input.workflowId,
+        branch: ctx.input.branch,
+        event: ctx.input.event,
+        status: ctx.input.status,
+        perPage: ctx.input.perPage,
+        page: ctx.input.page
+      });
+      let runs = data.workflow_runs.map((r: any) => ({
+        runId: r.id,
+        name: r.name,
+        status: r.status,
+        conclusion: r.conclusion,
+        headBranch: r.head_branch,
+        event: r.event,
+        htmlUrl: r.html_url,
+        createdAt: r.created_at
+      }));
+      return {
+        output: { runs },
+        message: `Found **${runs.length}** workflow runs in **${owner}/${repo}**.`
+      };
+    }
+
+    if (action === 'get_run') {
+      if (!ctx.input.runId) throw new Error('runId is required for get_run.');
+      let r = await client.getWorkflowRun(owner, repo, ctx.input.runId);
+      return {
+        output: {
+          run: {
+            runId: r.id,
+            name: r.name,
+            status: r.status,
+            conclusion: r.conclusion,
+            headBranch: r.head_branch,
+            headSha: r.head_sha,
+            event: r.event,
+            htmlUrl: r.html_url,
+            createdAt: r.created_at,
+            updatedAt: r.updated_at
+          }
+        },
+        message: `Workflow run **#${r.id}**: ${r.status}${r.conclusion ? ` (${r.conclusion})` : ''} — ${r.html_url}`
+      };
+    }
+
+    if (action === 'trigger') {
+      if (!ctx.input.workflowId) throw new Error('workflowId is required for trigger.');
+      if (!ctx.input.ref) throw new Error('ref is required for trigger.');
+      await client.triggerWorkflowDispatch(owner, repo, ctx.input.workflowId, {
+        ref: ctx.input.ref,
+        inputs: ctx.input.inputs as Record<string, string> | undefined
+      });
+      return {
+        output: { triggered: true },
+        message: `Triggered workflow **${ctx.input.workflowId}** on ref \`${ctx.input.ref}\` in **${owner}/${repo}**.`
+      };
+    }
+
+    if (action === 'cancel') {
+      if (!ctx.input.runId) throw new Error('runId is required for cancel.');
+      await client.cancelWorkflowRun(owner, repo, ctx.input.runId);
+      return {
+        output: { cancelled: true },
+        message: `Cancelled workflow run **#${ctx.input.runId}** in **${owner}/${repo}**.`
+      };
+    }
+
+    if (action === 'rerun') {
+      if (!ctx.input.runId) throw new Error('runId is required for rerun.');
+      await client.rerunWorkflow(owner, repo, ctx.input.runId);
+      return {
+        output: { rerunStarted: true },
+        message: `Re-running workflow run **#${ctx.input.runId}** in **${owner}/${repo}**.`
+      };
+    }
+
+    if (action === 'list_jobs') {
+      if (!ctx.input.runId) throw new Error('runId is required for list_jobs.');
+      let data = await client.listWorkflowRunJobs(owner, repo, ctx.input.runId, {
+        perPage: ctx.input.perPage,
+        page: ctx.input.page
+      });
+      let jobs = data.jobs.map((j: any) => ({
+        jobId: j.id,
+        name: j.name,
+        status: j.status,
+        conclusion: j.conclusion,
+        startedAt: j.started_at,
+        completedAt: j.completed_at
+      }));
+      return {
+        output: { jobs },
+        message: `Found **${jobs.length}** jobs in workflow run **#${ctx.input.runId}**.`
+      };
+    }
+
+    throw new Error(`Unknown action: ${action}`);
+  })
+  .build();

package/src/tools/merge-pull-request.ts

@@ -0,0 +1,61 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let mergePullRequest = SlateTool.create(spec, {
+  name: 'Merge Pull Request',
+  key: 'merge_pull_request',
+  description: `Merge a pull request using the specified merge method (merge commit, squash, or rebase).`,
+  tags: {
+    destructive: true
+  }
+})
+  .input(
+    z.object({
+      owner: z.string().describe('Repository owner (user or organization)'),
+      repo: z.string().describe('Repository name'),
+      pullNumber: z.number().describe('Pull request number'),
+      commitTitle: z.string().optional().describe('Title for the merge commit'),
+      commitMessage: z.string().optional().describe('Extra detail for the merge commit'),
+      mergeMethod: z
+        .enum(['merge', 'squash', 'rebase'])
+        .optional()
+        .describe('Merge method (default: merge)'),
+      sha: z
+        .string()
+        .optional()
+        .describe('SHA that head must match to allow merge (safety check)')
+    })
+  )
+  .output(
+    z.object({
+      merged: z.boolean().describe('Whether the merge was successful'),
+      sha: z.string().describe('SHA of the merge commit'),
+      message: z.string().describe('Merge result message')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let result = await client.mergePullRequest(
+      ctx.input.owner,
+      ctx.input.repo,
+      ctx.input.pullNumber,
+      {
+        commitTitle: ctx.input.commitTitle,
+        commitMessage: ctx.input.commitMessage,
+        mergeMethod: ctx.input.mergeMethod,
+        sha: ctx.input.sha
+      }
+    );
+
+    return {
+      output: {
+        merged: result.merged,
+        sha: result.sha,
+        message: result.message
+      },
+      message: `Merged PR **#${ctx.input.pullNumber}** in **${ctx.input.owner}/${ctx.input.repo}** using ${ctx.input.mergeMethod ?? 'merge'} method.`
+    };
+  })
+  .build();

package/src/tools/review-pull-request.ts

@@ -0,0 +1,90 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let reviewPullRequest = SlateTool.create(spec, {
+  name: 'Review Pull Request',
+  key: 'review_pull_request',
+  description: `Submit a review on a pull request with an approve, request changes, or comment action.
+Optionally include inline comments on specific files and lines. Can also request reviewers.`,
+  instructions: [
+    'Set action to "request_reviewers" to request reviewers instead of submitting a review.',
+    'For inline comments, provide the file path and position (line in the diff).'
+  ]
+})
+  .input(
+    z.object({
+      owner: z.string().describe('Repository owner (user or organization)'),
+      repo: z.string().describe('Repository name'),
+      pullNumber: z.number().describe('Pull request number'),
+      action: z
+        .enum(['APPROVE', 'REQUEST_CHANGES', 'COMMENT', 'request_reviewers'])
+        .describe('Review action or request reviewers'),
+      body: z.string().optional().describe('Review body in Markdown'),
+      comments: z
+        .array(
+          z.object({
+            path: z.string().describe('File path relative to repo root'),
+            position: z.number().optional().describe('Position in the diff'),
+            body: z.string().describe('Comment body')
+          })
+        )
+        .optional()
+        .describe('Inline review comments'),
+      reviewers: z
+        .array(z.string())
+        .optional()
+        .describe('Usernames to request review from (only for request_reviewers action)'),
+      teamReviewers: z
+        .array(z.string())
+        .optional()
+        .describe('Team slugs to request review from (only for request_reviewers action)')
+    })
+  )
+  .output(
+    z.object({
+      reviewId: z.number().optional().describe('Review ID (when submitting a review)'),
+      state: z.string().optional().describe('Review state'),
+      htmlUrl: z.string().optional().describe('URL to the review on GitHub'),
+      requestedReviewers: z
+        .array(z.string())
+        .optional()
+        .describe('Requested reviewer usernames')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let { owner, repo, pullNumber, action } = ctx.input;
+
+    if (action === 'request_reviewers') {
+      let result = await client.requestReviewers(owner, repo, pullNumber, {
+        reviewers: ctx.input.reviewers,
+        teamReviewers: ctx.input.teamReviewers
+      });
+
+      let requested = (result.requested_reviewers ?? []).map((r: any) => r.login);
+      return {
+        output: {
+          requestedReviewers: requested
+        },
+        message: `Requested reviews from ${requested.join(', ')} on PR **#${pullNumber}**.`
+      };
+    }
+
+    let review = await client.createPullRequestReview(owner, repo, pullNumber, {
+      body: ctx.input.body,
+      event: action,
+      comments: ctx.input.comments
+    });
+
+    return {
+      output: {
+        reviewId: review.id,
+        state: review.state,
+        htmlUrl: review.html_url
+      },
+      message: `Submitted **${review.state}** review on PR **#${pullNumber}** in **${owner}/${repo}**.`
+    };
+  })
+  .build();