@slates-integrations/github 0.2.0-rc.2

package/src/tools/list-issues.ts

@@ -0,0 +1,90 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let listIssues = SlateTool.create(spec, {
+  name: 'List Issues',
+  key: 'list_issues',
+  description: `List issues in a GitHub repository with filtering and sorting options.
+Filter by state, labels, assignee, milestone, and since date. Note: GitHub's API returns pull requests alongside issues — this tool filters them out.`,
+  tags: {
+    readOnly: true
+  }
+})
+  .input(
+    z.object({
+      owner: z.string().describe('Repository owner (user or organization)'),
+      repo: z.string().describe('Repository name'),
+      state: z
+        .enum(['open', 'closed', 'all'])
+        .optional()
+        .describe('Filter by state (default: open)'),
+      labels: z.string().optional().describe('Comma-separated label names to filter by'),
+      assignee: z
+        .string()
+        .optional()
+        .describe('Filter by assignee username, or "none" for unassigned'),
+      sort: z.enum(['created', 'updated', 'comments']).optional().describe('Sort field'),
+      direction: z.enum(['asc', 'desc']).optional().describe('Sort direction'),
+      since: z
+        .string()
+        .optional()
+        .describe('Only issues updated after this ISO 8601 timestamp'),
+      perPage: z.number().optional().describe('Results per page (max 100)'),
+      page: z.number().optional().describe('Page number')
+    })
+  )
+  .output(
+    z.object({
+      issues: z.array(
+        z.object({
+          issueNumber: z.number().describe('Issue number'),
+          title: z.string().describe('Issue title'),
+          state: z.string().describe('Issue state'),
+          author: z.string().describe('Issue author login'),
+          assignees: z.array(z.string()).describe('Assigned usernames'),
+          labels: z.array(z.string()).describe('Label names'),
+          commentsCount: z.number().describe('Number of comments'),
+          createdAt: z.string().describe('Creation timestamp'),
+          updatedAt: z.string().describe('Last update timestamp'),
+          htmlUrl: z.string().describe('URL to the issue on GitHub')
+        })
+      ),
+      totalCount: z.number().describe('Number of issues returned')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let items = await client.listIssues(ctx.input.owner, ctx.input.repo, {
+      state: ctx.input.state,
+      labels: ctx.input.labels,
+      assignee: ctx.input.assignee,
+      sort: ctx.input.sort,
+      direction: ctx.input.direction,
+      since: ctx.input.since,
+      perPage: ctx.input.perPage,
+      page: ctx.input.page
+    });
+
+    let issues = items
+      .filter((i: any) => !i.pull_request)
+      .map((i: any) => ({
+        issueNumber: i.number,
+        title: i.title,
+        state: i.state,
+        author: i.user.login,
+        assignees: (i.assignees ?? []).map((a: any) => a.login),
+        labels: (i.labels ?? []).map((l: any) => l.name),
+        commentsCount: i.comments,
+        createdAt: i.created_at,
+        updatedAt: i.updated_at,
+        htmlUrl: i.html_url
+      }));
+
+    return {
+      output: { issues, totalCount: issues.length },
+      message: `Found **${issues.length}** issues in **${ctx.input.owner}/${ctx.input.repo}** (state: ${ctx.input.state ?? 'open'}).`
+    };
+  })
+  .build();

package/src/tools/list-pull-requests.ts

@@ -0,0 +1,82 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let listPullRequests = SlateTool.create(spec, {
+  name: 'List Pull Requests',
+  key: 'list_pull_requests',
+  description: `List pull requests in a GitHub repository with filtering by state, head/base branch, and sorting options.`,
+  tags: {
+    readOnly: true
+  }
+})
+  .input(
+    z.object({
+      owner: z.string().describe('Repository owner (user or organization)'),
+      repo: z.string().describe('Repository name'),
+      state: z
+        .enum(['open', 'closed', 'all'])
+        .optional()
+        .describe('Filter by state (default: open)'),
+      head: z.string().optional().describe('Filter by head branch (format: "user:branch")'),
+      base: z.string().optional().describe('Filter by base branch name'),
+      sort: z
+        .enum(['created', 'updated', 'popularity', 'long-running'])
+        .optional()
+        .describe('Sort field'),
+      direction: z.enum(['asc', 'desc']).optional().describe('Sort direction'),
+      perPage: z.number().optional().describe('Results per page (max 100)'),
+      page: z.number().optional().describe('Page number')
+    })
+  )
+  .output(
+    z.object({
+      pullRequests: z.array(
+        z.object({
+          pullNumber: z.number().describe('Pull request number'),
+          title: z.string().describe('PR title'),
+          state: z.string().describe('PR state'),
+          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'),
+          createdAt: z.string().describe('Creation timestamp'),
+          updatedAt: z.string().describe('Last update timestamp'),
+          htmlUrl: z.string().describe('URL to the PR on GitHub')
+        })
+      ),
+      totalCount: z.number().describe('Number of pull requests returned')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let prs = await client.listPullRequests(ctx.input.owner, ctx.input.repo, {
+      state: ctx.input.state,
+      head: ctx.input.head,
+      base: ctx.input.base,
+      sort: ctx.input.sort,
+      direction: ctx.input.direction,
+      perPage: ctx.input.perPage,
+      page: ctx.input.page
+    });
+
+    let pullRequests = prs.map((pr: any) => ({
+      pullNumber: pr.number,
+      title: pr.title,
+      state: pr.state,
+      author: pr.user.login,
+      head: pr.head.ref,
+      base: pr.base.ref,
+      draft: pr.draft,
+      createdAt: pr.created_at,
+      updatedAt: pr.updated_at,
+      htmlUrl: pr.html_url
+    }));
+
+    return {
+      output: { pullRequests, totalCount: pullRequests.length },
+      message: `Found **${pullRequests.length}** pull requests in **${ctx.input.owner}/${ctx.input.repo}** (state: ${ctx.input.state ?? 'open'}).`
+    };
+  })
+  .build();

package/src/tools/list-repositories.ts

@@ -0,0 +1,102 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let listRepositories = SlateTool.create(spec, {
+  name: 'List Repositories',
+  key: 'list_repositories',
+  description: `List repositories for the authenticated user or a specific organization.
+Supports filtering by type, sorting, and pagination.`,
+  tags: {
+    readOnly: true
+  }
+})
+  .input(
+    z.object({
+      org: z
+        .string()
+        .optional()
+        .describe(
+          'Organization name. If omitted, lists repositories for the authenticated user.'
+        ),
+      type: z
+        .enum(['all', 'owner', 'public', 'private', 'member'])
+        .optional()
+        .describe('Filter by repository type'),
+      sort: z
+        .enum(['created', 'updated', 'pushed', 'full_name'])
+        .optional()
+        .describe('Sort field'),
+      direction: z.enum(['asc', 'desc']).optional().describe('Sort direction'),
+      perPage: z.number().optional().describe('Results per page (max 100)'),
+      page: z.number().optional().describe('Page number')
+    })
+  )
+  .output(
+    z.object({
+      repositories: z.array(
+        z.object({
+          repositoryId: z.number().describe('Unique repository ID'),
+          name: z.string().describe('Repository name'),
+          fullName: z.string().describe('Full name in owner/repo format'),
+          owner: z.string().describe('Repository owner login'),
+          private: z.boolean().describe('Whether the repository is private'),
+          description: z.string().nullable().describe('Repository description'),
+          htmlUrl: z.string().describe('URL to the repository on GitHub'),
+          defaultBranch: z.string().describe('Default branch name'),
+          language: z.string().nullable().describe('Primary programming language'),
+          stargazersCount: z.number().describe('Number of stars'),
+          forksCount: z.number().describe('Number of forks'),
+          updatedAt: z.string().describe('Last update timestamp')
+        })
+      ),
+      totalCount: z.number().describe('Number of repositories returned')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+
+    let repos: any[];
+    if (ctx.input.org) {
+      repos = await client.listOrgRepos(ctx.input.org, {
+        type: ctx.input.type,
+        sort: ctx.input.sort,
+        direction: ctx.input.direction,
+        perPage: ctx.input.perPage,
+        page: ctx.input.page
+      });
+    } else {
+      repos = await client.listRepositories({
+        type: ctx.input.type,
+        sort: ctx.input.sort,
+        direction: ctx.input.direction,
+        perPage: ctx.input.perPage,
+        page: ctx.input.page
+      });
+    }
+
+    let repositories = repos.map((r: any) => ({
+      repositoryId: r.id,
+      name: r.name,
+      fullName: r.full_name,
+      owner: r.owner.login,
+      private: r.private,
+      description: r.description,
+      htmlUrl: r.html_url,
+      defaultBranch: r.default_branch,
+      language: r.language,
+      stargazersCount: r.stargazers_count,
+      forksCount: r.forks_count,
+      updatedAt: r.updated_at
+    }));
+
+    return {
+      output: {
+        repositories,
+        totalCount: repositories.length
+      },
+      message: `Found **${repositories.length}** repositories${ctx.input.org ? ` in org **${ctx.input.org}**` : ''}.`
+    };
+  })
+  .build();

package/src/tools/manage-collaborators.ts

@@ -0,0 +1,88 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let manageCollaborators = SlateTool.create(spec, {
+  name: 'Manage Collaborators',
+  key: 'manage_collaborators',
+  description: `List, add, or remove collaborators on a GitHub repository. Control access permissions for individual users.`
+})
+  .input(
+    z.object({
+      owner: z.string().describe('Repository owner'),
+      repo: z.string().describe('Repository name'),
+      action: z.enum(['list', 'add', 'remove']).describe('Action to perform'),
+      username: z
+        .string()
+        .optional()
+        .describe('Username of the collaborator (required for add/remove)'),
+      permission: z
+        .enum(['pull', 'triage', 'push', 'maintain', 'admin'])
+        .optional()
+        .describe('Permission level (for add action, default: push)'),
+      perPage: z.number().optional().describe('Results per page (for list)'),
+      page: z.number().optional().describe('Page number (for list)')
+    })
+  )
+  .output(
+    z.object({
+      collaborators: z
+        .array(
+          z.object({
+            username: z.string().describe('Collaborator username'),
+            avatarUrl: z.string().describe('Avatar URL'),
+            permissions: z
+              .record(z.string(), z.boolean())
+              .optional()
+              .describe('Permission map')
+          })
+        )
+        .optional()
+        .describe('List of collaborators'),
+      added: z.boolean().optional().describe('Whether the collaborator was added'),
+      removed: z.boolean().optional().describe('Whether the collaborator was removed')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let { owner, repo, action, username } = ctx.input;
+
+    if (action === 'list') {
+      let collabs = await client.listCollaborators(owner, repo, {
+        perPage: ctx.input.perPage,
+        page: ctx.input.page
+      });
+      return {
+        output: {
+          collaborators: collabs.map((c: any) => ({
+            username: c.login,
+            avatarUrl: c.avatar_url,
+            permissions: c.permissions
+          }))
+        },
+        message: `Found **${collabs.length}** collaborators in **${owner}/${repo}**.`
+      };
+    }
+
+    if (!username) throw new Error('username is required for add/remove actions.');
+
+    if (action === 'add') {
+      await client.addCollaborator(owner, repo, username, ctx.input.permission);
+      return {
+        output: { added: true },
+        message: `Added **${username}** as collaborator to **${owner}/${repo}** with ${ctx.input.permission ?? 'push'} permission.`
+      };
+    }
+
+    if (action === 'remove') {
+      await client.removeCollaborator(owner, repo, username);
+      return {
+        output: { removed: true },
+        message: `Removed **${username}** from **${owner}/${repo}** collaborators.`
+      };
+    }
+
+    throw new Error(`Unknown action: ${action}`);
+  })
+  .build();

package/src/tools/manage-file-content.ts

@@ -0,0 +1,117 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let manageFileContent = SlateTool.create(spec, {
+  name: 'Manage File Content',
+  key: 'manage_file_content',
+  description: `Read, create, update, or delete a file in a GitHub repository.
+- **read**: Retrieve file contents (decoded from Base64).
+- **write**: Create or update a file. Provide Base64-encoded content and a commit message.
+- **delete**: Delete a file. Requires the file's current SHA and a commit message.`,
+  instructions: [
+    'For read operations, only owner, repo, path, and optionally ref are needed.',
+    'For write operations, file content must be Base64-encoded.',
+    'For update/delete, provide the current SHA of the file to avoid conflicts.'
+  ]
+})
+  .input(
+    z.object({
+      owner: z.string().describe('Repository owner'),
+      repo: z.string().describe('Repository name'),
+      path: z.string().describe('File path relative to the repo root'),
+      action: z.enum(['read', 'write', 'delete']).describe('Operation to perform'),
+      ref: z.string().optional().describe('Branch/tag/commit to read from (only for read)'),
+      content: z
+        .string()
+        .optional()
+        .describe('Base64-encoded file content (required for write)'),
+      commitMessage: z
+        .string()
+        .optional()
+        .describe('Commit message (required for write/delete)'),
+      sha: z.string().optional().describe('Current file SHA (required for update/delete)'),
+      branch: z.string().optional().describe('Branch to commit to (for write/delete)')
+    })
+  )
+  .output(
+    z.object({
+      path: z.string().describe('File path'),
+      sha: z.string().optional().describe('File SHA'),
+      content: z.string().optional().describe('Decoded file content (for read)'),
+      size: z.number().optional().describe('File size in bytes'),
+      htmlUrl: z.string().optional().describe('URL to the file on GitHub'),
+      commitSha: z.string().optional().describe('Commit SHA (for write/delete)')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let { owner, repo, path, action } = ctx.input;
+
+    if (action === 'read') {
+      let file = await client.getContent(owner, repo, path, ctx.input.ref);
+
+      let content: string | undefined;
+      if (file.content && file.encoding === 'base64') {
+        content = atob(file.content);
+      }
+
+      return {
+        output: {
+          path: file.path,
+          sha: file.sha,
+          content,
+          size: file.size,
+          htmlUrl: file.html_url
+        },
+        message: `Read file **${file.path}** (${file.size} bytes) from **${owner}/${repo}**.`
+      };
+    }
+
+    if (action === 'write') {
+      if (!ctx.input.content || !ctx.input.commitMessage) {
+        throw new Error('content and commitMessage are required for write operations.');
+      }
+
+      let result = await client.createOrUpdateFile(owner, repo, path, {
+        message: ctx.input.commitMessage,
+        content: ctx.input.content,
+        sha: ctx.input.sha,
+        branch: ctx.input.branch
+      });
+
+      return {
+        output: {
+          path: result.content.path,
+          sha: result.content.sha,
+          htmlUrl: result.content.html_url,
+          commitSha: result.commit.sha
+        },
+        message: `${ctx.input.sha ? 'Updated' : 'Created'} file **${path}** in **${owner}/${repo}** (commit: \`${result.commit.sha.slice(0, 7)}\`).`
+      };
+    }
+
+    if (action === 'delete') {
+      if (!ctx.input.sha || !ctx.input.commitMessage) {
+        throw new Error('sha and commitMessage are required for delete operations.');
+      }
+
+      let result = await client.deleteFile(owner, repo, path, {
+        message: ctx.input.commitMessage,
+        sha: ctx.input.sha,
+        branch: ctx.input.branch
+      });
+
+      return {
+        output: {
+          path,
+          commitSha: result.commit.sha
+        },
+        message: `Deleted file **${path}** from **${owner}/${repo}** (commit: \`${result.commit.sha.slice(0, 7)}\`).`
+      };
+    }
+
+    throw new Error(`Unknown action: ${action}`);
+  })
+  .build();

package/src/tools/manage-gist.ts

@@ -0,0 +1,183 @@
+import { SlateTool } from 'slates';
+import { GitHubClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let manageGist = SlateTool.create(spec, {
+  name: 'Manage Gist',
+  key: 'manage_gist',
+  description: `Create, read, update, or delete GitHub Gists (code snippets).
+- **create**: Create a new gist with one or more files.
+- **get**: Retrieve a gist by ID.
+- **update**: Update a gist's description or files.
+- **delete**: Delete a gist.
+- **list**: List gists for the authenticated user.`
+})
+  .input(
+    z.object({
+      action: z
+        .enum(['create', 'get', 'update', 'delete', 'list'])
+        .describe('Action to perform'),
+      gistId: z.string().optional().describe('Gist ID (required for get, update, delete)'),
+      description: z.string().optional().describe('Gist description (for create/update)'),
+      public: z
+        .boolean()
+        .optional()
+        .describe('Whether the gist is public (for create, default: false)'),
+      files: z
+        .record(
+          z.string(),
+          z.object({
+            content: z.string().optional().describe('File content'),
+            filename: z.string().optional().describe('New filename (for rename)')
+          })
+        )
+        .optional()
+        .describe(
+          'Files to include. For create, content is required. For update, set value to null to delete a file.'
+        ),
+      perPage: z.number().optional().describe('Results per page (for list)'),
+      page: z.number().optional().describe('Page number (for list)')
+    })
+  )
+  .output(
+    z.object({
+      gistId: z.string().optional().describe('Gist ID'),
+      htmlUrl: z.string().optional().describe('URL to the gist'),
+      description: z.string().nullable().optional().describe('Gist description'),
+      public: z.boolean().optional().describe('Whether the gist is public'),
+      files: z
+        .array(
+          z.object({
+            filename: z.string(),
+            language: z.string().nullable(),
+            size: z.number()
+          })
+        )
+        .optional()
+        .describe('Files in the gist'),
+      gists: z
+        .array(
+          z.object({
+            gistId: z.string(),
+            htmlUrl: z.string(),
+            description: z.string().nullable(),
+            public: z.boolean(),
+            fileCount: z.number(),
+            createdAt: z.string(),
+            updatedAt: z.string()
+          })
+        )
+        .optional()
+        .describe('List of gists'),
+      deleted: z.boolean().optional().describe('Whether the gist was deleted')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new GitHubClient(ctx.auth.token);
+    let { action, gistId } = ctx.input;
+
+    if (action === 'list') {
+      let gists = await client.listGists({
+        perPage: ctx.input.perPage,
+        page: ctx.input.page
+      });
+      return {
+        output: {
+          gists: gists.map((g: any) => ({
+            gistId: g.id,
+            htmlUrl: g.html_url,
+            description: g.description,
+            public: g.public,
+            fileCount: Object.keys(g.files).length,
+            createdAt: g.created_at,
+            updatedAt: g.updated_at
+          }))
+        },
+        message: `Found **${gists.length}** gists.`
+      };
+    }
+
+    if (action === 'get') {
+      if (!gistId) throw new Error('gistId is required for get action.');
+      let gist = await client.getGist(gistId);
+      return {
+        output: {
+          gistId: gist.id,
+          htmlUrl: gist.html_url,
+          description: gist.description,
+          public: gist.public,
+          files: Object.values(gist.files).map((f: any) => ({
+            filename: f.filename,
+            language: f.language,
+            size: f.size
+          }))
+        },
+        message: `Retrieved gist **${gist.id}** — ${gist.html_url}`
+      };
+    }
+
+    if (action === 'create') {
+      if (!ctx.input.files) throw new Error('files are required for create action.');
+      let filesPayload: Record<string, { content: string }> = {};
+      for (let [name, file] of Object.entries(ctx.input.files)) {
+        let f = file as { content?: string; filename?: string };
+        if (f.content) {
+          filesPayload[name] = { content: f.content };
+        }
+      }
+      let gist = await client.createGist({
+        description: ctx.input.description,
+        public: ctx.input.public,
+        files: filesPayload
+      });
+      return {
+        output: {
+          gistId: gist.id,
+          htmlUrl: gist.html_url,
+          description: gist.description,
+          public: gist.public,
+          files: Object.values(gist.files).map((f: any) => ({
+            filename: f.filename,
+            language: f.language,
+            size: f.size
+          }))
+        },
+        message: `Created gist **${gist.id}** — ${gist.html_url}`
+      };
+    }
+
+    if (action === 'update') {
+      if (!gistId) throw new Error('gistId is required for update action.');
+      let gist = await client.updateGist(gistId, {
+        description: ctx.input.description,
+        files: ctx.input.files as any
+      });
+      return {
+        output: {
+          gistId: gist.id,
+          htmlUrl: gist.html_url,
+          description: gist.description,
+          public: gist.public,
+          files: Object.values(gist.files).map((f: any) => ({
+            filename: f.filename,
+            language: f.language,
+            size: f.size
+          }))
+        },
+        message: `Updated gist **${gist.id}** — ${gist.html_url}`
+      };
+    }
+
+    if (action === 'delete') {
+      if (!gistId) throw new Error('gistId is required for delete action.');
+      await client.deleteGist(gistId);
+      return {
+        output: { deleted: true },
+        message: `Deleted gist **${gistId}**.`
+      };
+    }
+
+    throw new Error(`Unknown action: ${action}`);
+  })
+  .build();