@slates-integrations/github 0.2.0-rc.7 → 0.2.0-rc.9

package/docs/SPEC.md

@@ -1,11 +1,227 @@
-Now I have enough information to write the specification. Let me compile everything.
-
-# Slates Specification for GitHub
+# GitHub Integration Specification
 
 ## Overview
 
 GitHub is a cloud-based platform for version control and collaboration using Git. It provides hosting for software repositories along with features for issue tracking, code review, project management, CI/CD (GitHub Actions), and package hosting. GitHub offers both REST and GraphQL APIs for programmatic access to its platform resources.
 
+## Notable Tool Contracts
+
+- `create_repository` creates a repository in the authenticated user's account unless
+  `organization` is provided. `private` defaults to `true`; pass `false` explicitly to
+  create a public repository. `autoInit` initializes the repository with a README.
+- `merge_pull_request` accepts the optional snake-case fields `commit_title`,
+  `commit_message`, and `merge_method`. Supported merge methods are `merge`, `squash`,
+  and `rebase`.
+- `list_issues` uses GraphQL cursor pagination. Pass `pageInfo.endCursor` from one
+  response as `after` to fetch the next page. `state` accepts `OPEN` or `CLOSED` and
+  returns both states when omitted. Labels are supplied as an array. Custom issue
+  fields can be filtered with `field_filters` entries containing `field_name` and
+  `value`.
+- `issue_read` consolidates issue detail, comment, hierarchy, and label reads. Its
+  `get` method includes best-effort parent/child relationship signals and custom issue
+  field values.
+- `pull_request_read` consolidates pull request detail, diff, status, file, commit,
+  review-thread, review, conversation-comment, and check-run reads.
+- `list_pull_requests` is for repository filters such as state and branches. To filter
+  pull requests by author, use `search` with type `issues` and GitHub search qualifiers
+  such as `is:pr author:<login>`.
+- `star_repository` deliberately consolidates both star and unstar operations through
+  its required `action` field.
+- `search` covers organizations through GitHub's user-search endpoint: use type
+  `users` with the `type:org` qualifier.
+- `create_branch` creates a branch from `from_branch`, or from the repository's
+  default branch when the source is omitted.
+- `push_files` writes multiple plain-text files atomically in one commit through the
+  Git tree, commit, and ref APIs. If the requested branch is absent, it is created
+  from the default branch.
+- `get_repository_tree` reads a tree at an optional SHA, branch, or tag, supports
+  recursive traversal, and can filter returned entries by a path prefix.
+- `update_pull_request_branch` starts GitHub's base-branch update for a pull request;
+  `expectedHeadSha` provides optimistic concurrency protection.
+- `sub_issue_write` supports `add`, `remove`, and `reprioritize`. `sub_issue_id` is
+  the issue database ID rather than the issue number, and reprioritization requires
+  exactly one of `after_id` or `before_id`.
+- `get_global_security_advisory` and `list_global_security_advisories` expose the
+  public GitHub Advisory Database with GHSA, CVE, ecosystem, severity, CWE,
+  withdrawn-state, affected-package, and date filters.
+
+## Added Tool Coverage
+
+The tools below expose focused GitHub capabilities with stable identifiers and
+structured results. A classic OAuth token must include the listed scope. For
+fine-grained tokens and GitHub Apps, grant the equivalent repository,
+organization, notification, security, or Projects permission.
+
+### Security and code quality
+
+| Tool | OAuth scope | User outcome |
+| --- | --- | --- |
+| `get_code_scanning_alert` | `security_events` | Read one code scanning alert by repository and alert number, including rule, severity, location, state, and dismissal details. |
+| `list_code_scanning_alerts` | `security_events` | Triage repository alerts by state, Git ref, severity, scanning tool, and page. The state defaults to `open`. |
+| `get_dependabot_alert` | `security_events` | Read one Dependabot alert by repository and alert number, including dependency, advisory, severity, and remediation details. |
+| `list_dependabot_alerts` | `security_events` | List Dependabot alerts by state or severity and continue with the returned cursor. The state defaults to `open`. |
+| `get_secret_scanning_alert` | `security_events` | Read one secret scanning alert by repository and alert number, including secret type, location, state, and resolution. |
+| `list_secret_scanning_alerts` | `security_events` | List secret scanning alerts by state, resolution, secret type, and page. |
+| `list_repository_security_advisories` | `security_events` | List one repository's private security advisories by state, sort field, and direction. |
+| `list_org_repository_security_advisories` | `security_events` | List repository security advisories across an organization by state, sort field, and direction. |
+| `get_code_quality_finding` | `repo` or `public_repo` | Read one code quality finding by repository and finding number, including diagnostic and remediation details when available. |
+
+### Notifications
+
+| Tool | OAuth scope | User outcome |
+| --- | --- | --- |
+| `list_notifications` | `notifications` | List the authenticated user's notification inbox, optionally including read items, limiting to participating threads, filtering by RFC3339 timestamps, or limiting to one repository. `owner` and `repo` must be supplied together. |
+| `get_notification_details` | `notifications` | Read one notification thread by `notificationID`; use `list_notifications` first when the ID is unknown. |
+| `manage_notification_subscription` | `notifications` | Watch, ignore, or delete a notification-thread subscription by `notificationID`. |
+| `manage_repository_notification_subscription` | `notifications` | Watch, ignore, or delete notification subscription settings for a repository. |
+| `mark_all_notifications_read` | `notifications` | Mark notifications read through `lastReadAt`, defaulting to the current time. Supplying `owner` and `repo` together limits the operation to that repository. |
+| `dismiss_notification` | `notifications` | Mark a thread `read` or `done`; `done` removes it from the notification inbox. |
+
+### Discussions
+
+| Tool | OAuth scope | User outcome |
+| --- | --- | --- |
+| `list_discussion_categories` | `repo` or `public_repo` | List category node IDs and names for a repository. Omitting `repo` reads organization-level categories from the owner's `.github` repository. |
+| `list_discussions` | `repo` or `public_repo` | List discussions with cursor pagination, category filtering, optional page-local title/body filtering, and paired ordering controls. `orderBy` and `direction` must be supplied together. |
+| `get_discussion` | `repo` or `public_repo` | Read a discussion by repository-local number with its body, category, answer state, author, timestamps, and permalink. |
+| `get_discussion_comments` | `repo` or `public_repo` | Read a cursor-paginated page of top-level comments. `includeReplies: true` also returns up to 100 replies per top-level comment. |
+| `discussion_comment_write` | `repo` or `public_repo` | Add, reply to, update, or delete discussion comments and mark or unmark accepted answers. See the conditional fields below. |
+
+`discussion_comment_write` uses these conditional fields:
+
+- `add` requires `owner`, `repo`, `discussionNumber`, and `body`.
+- `reply` also requires the parent `commentNodeID`. Discussions support one
+  level of nested replies.
+- `update` requires `commentNodeID` and `body`.
+- `delete`, `mark_answer`, and `unmark_answer` require `commentNodeID`.
+
+### GitHub Projects
+
+| Tool | OAuth scope | User outcome |
+| --- | --- | --- |
+| `projects_list` | `read:project` | List user or organization projects, or list fields, items, and status updates for a project. Methods other than `list_projects` require `project_number`. Item reads accept either `fields` IDs or `field_names`, never both. |
+| `projects_get` | `read:project` | Get a project, field, item, or status update. Project, field, and item reads require `owner` and `project_number`; field and item reads also require their corresponding ID. A status-update read requires only `status_update_id`. |
+| `projects_write` | `project` | Create a project, add/update/delete items, publish status updates, or create an iteration field. Each method validates its own owner, project, item, field, and date inputs before changing data. |
+
+For `projects_write`, `create_project` requires `owner_type` and `title`.
+`add_project_item` requires `project_number`, `item_type`, `item_owner`,
+`item_repo`, and the matching issue or pull request number.
+`update_project_item` requires `project_number`, `updated_field`, and exactly
+one item locator: `item_id` or `item_owner` + `item_repo` + `issue_number`.
+`delete_project_item` requires `project_number` and `item_id`.
+`create_iteration_field` requires `project_number`, `field_name`,
+`start_date`, and a positive `iteration_duration`.
+
+### Repository and account reads
+
+| Tool | OAuth scope | User outcome |
+| --- | --- | --- |
+| `fork_repository` | `repo` or `public_repo` | Fork a repository to the authenticated account or the optional `organization`, returning created-fork metadata or an `in_progress` status for asynchronous forks. |
+| `list_starred_repositories` | `repo` or `public_repo` | List repositories starred by `username`, or by the authenticated user when it is omitted, with sort direction and page controls. |
+
+## Expanded Consolidated Contracts
+
+All tools in this section require `repo` or `public_repo`.
+
+### `manage_workflow`
+
+`manage_workflow` covers GitHub Actions listing, inspection, downloads, job-log
+troubleshooting, and run operations while retaining the existing `action`
+values `list_workflows`, `list_runs`, `get_run`, `trigger`, `cancel`, `rerun`,
+and `list_jobs`.
+
+- Listing methods are `list_workflows`, `list_workflow_runs`,
+  `list_workflow_jobs`, and `list_workflow_run_artifacts`.
+  `list_workflow_runs` optionally accepts a workflow ID or filename as
+  `resource_id` plus `workflow_runs_filter`. Job and artifact listing require
+  the workflow run ID as `resource_id`. Job listing accepts
+  `workflow_jobs_filter.filter` as `latest` or `all`.
+- Read methods are `get_workflow`, `get_workflow_run`, `get_workflow_job`,
+  `get_workflow_run_usage`, `get_workflow_run_logs_url`, and
+  `download_workflow_run_artifact`. Each requires `resource_id`; only
+  `get_workflow` accepts a workflow filename instead of a numeric ID.
+- Run methods are `run_workflow`, `rerun_workflow_run`, `rerun_failed_jobs`,
+  `cancel_workflow_run`, and `delete_workflow_run_logs`. `run_workflow`
+  requires `workflow_id` and `ref`; all other run methods require `run_id`.
+- For one job's logs, omit `method` and provide `job_id`. For all failed jobs
+  in a run, provide `run_id` with `failed_only: true`. `tail_lines` defaults
+  to 500. With `return_content: false`, the result contains authenticated
+  download endpoints. With `return_content: true`, each requested log is a
+  downloadable text file and the structured result contains only file name,
+  MIME type, byte count, line counts, truncation state, and job IDs.
+- Downloaded workflow artifacts are returned as ZIP files. The structured
+  result contains artifact ID, file name, MIME type, and byte count rather
+  than embedding the archive bytes.
+
+### `comment_on_issue`
+
+`comment_on_issue` accepts `issue_number` or the existing `issueNumber` alias
+and can create a comment, add a reaction, or do both in one call.
+
+- At least one of `body` or `reaction` is required.
+- Omitting `comment_id` targets the issue or pull request itself.
+- Providing `comment_id` targets that issue comment, requires `reaction`, and
+  cannot be combined with `body`. The comment is verified to belong to the
+  requested issue before the reaction is added.
+- Review-comment reactions belong in `review_pull_request`, not this tool.
+
+### `manage_issue`
+
+`manage_issue` supports explicit `create` and `update` methods. Existing calls
+may omit `method`; providing either issue-number field selects update behavior.
+
+- `create` requires `title`; `update` requires `issue_number` or
+  `issueNumber`.
+- `type` uses an issue type returned by `list_issue_types`.
+- Every `issue_fields` entry requires `field_name` and exactly one of
+  `value`, `field_option_name`, or `delete: true`.
+- Closing as a duplicate requires `state: "closed"`,
+  `state_reason: "duplicate"`, and `duplicate_of`. `duplicate_of` is not
+  accepted for other state reasons.
+- `stateReason` remains an accepted existing alias. If both state-reason
+  fields are supplied, their values must agree.
+
+### `manage_labels`
+
+`manage_labels` creates, updates, renames, deletes, and continues to list
+repository labels through the existing `action: "list"` operation.
+
+- Supply either `method` or `action`. If both are present, they must agree.
+- Create, update, and delete require `name`; create also requires `color`.
+- Update requires at least one of `new_name`, `color`, or `description`.
+
+### `manage_pull_request`
+
+Omitting `pullNumber` creates a pull request and requires `title`, `head`, and
+`base`. Providing `pullNumber` updates a pull request and requires at least one
+change among title, body, state, base, draft state, maintainer-edit permission,
+or reviewers.
+
+`reviewers` accepts GitHub usernames and `ORG/team-slug` team identifiers.
+`draft: true` converts an existing pull request to draft; `draft: false` marks
+it ready for review. `maintainer_can_modify` is the preferred field, while
+`maintainerCanModify` remains accepted; if both are supplied, they must agree.
+
+### `review_pull_request`
+
+Supply either `method` or the existing `action`, never both.
+
+- Existing actions submit `APPROVE`, `REQUEST_CHANGES`, or `COMMENT` reviews,
+  or request user/team reviewers.
+- `create` requires `pullNumber`; omitting `event` creates a pending review.
+  Providing `event` submits it immediately.
+- `submit_pending` requires `pullNumber` and `event`; `delete_pending`
+  requires `pullNumber`.
+- `resolve_thread` and `unresolve_thread` require the GraphQL `threadId`
+  returned by `pull_request_read` with `method: "get_review_comments"`.
+- `add_comment_to_pending_review` requires `pullNumber`, `path`, `body`, and
+  `subjectType`. A `FILE` comment omits all line fields. A `LINE` comment
+  requires positive `line` and `side`; a range additionally requires
+  `startLine` and `startSide`, with matching sides and `startLine < line`.
+- `add_reply_to_pull_request_comment` requires a numeric `commentId` and at
+  least one of `body` or `reaction`. A text reply also requires `pullNumber`;
+  a reaction-only call can use the comment ID alone.
+
 ## Authentication
 
 GitHub supports several authentication methods for API access:

package/package.json

@@ -4,17 +4,20 @@
   "type": "module",
   "scripts": {
     "build": "bunx @vercel/ncc build src/index.ts -o dist -m -s",
+    "test": "vitest run --config vitest.config.ts --passWithNoTests",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@types/node": "^20",
-    "slates": "1.0.0-rc.14",
+    "slates": "1.0.0-rc.15",
     "zod": "^4.2"
   },
   "devDependencies": {
-    "typescript": "^5"
+    "@slates/test": "1.0.0-rc.10",
+    "typescript": "^5",
+    "vitest": "^3.1.2"
   },
-  "version": "0.2.0-rc.7",
+  "version": "0.2.0-rc.9",
   "files": [
     "dist/**",
     "docs/**",