@goodandready/dsh-github-ops 0.1.0

package/lib/tools/register-core.js

@@ -0,0 +1,259 @@
+// Core tool registrations: repository and file reads, releases, tags, the guarded
+// generic API pass-through, and repository creation/edits.
+//
+// Everything here takes its dependencies as arguments, so the host half stays thin
+// and the definitions are reusable in tests.
+
+import { listReleases, getRelease, createRelease, editRelease, deleteRelease } from './releases.js'
+import { listTags, createTag, deleteTag } from './tags.js'
+import { callApi } from './api.js'
+import { getRepo, getFile, searchRepos, createRepo, editRepo } from './repos.js'
+
+const REPOSITORY = {
+  repository: { type: 'string', description: 'Repository as "owner/repo". Omit to use the default from settings.' },
+}
+
+export function registerCoreTools({ tool, asRepo, client, liveConfig }) {
+  const repoParams = (extra = {}) => ({ ...REPOSITORY, ...extra })
+
+  // ------------------------------------------------------------------ repository
+
+  tool(
+    'gh_repo',
+    'Read GitHub repository metadata: description, default branch, stars, topics, license, open issue count. Read-only.',
+    repoParams(),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return getRepo(await client(), { owner, repo })
+    },
+  )
+
+  tool(
+    'gh_file',
+    'Read one file from a GitHub repository at a branch, tag or commit (content is decoded for you). A directory path returns its entries. Read-only.',
+    repoParams({
+      path: { type: 'string', description: 'File path inside the repository, e.g. "lib/index.js" or "lib".' },
+      ref: { type: 'string', description: 'Branch, tag or commit; defaults to the default branch.' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return getFile(await client(), { owner, repo, path: args.path, ref: args.ref })
+    },
+  )
+
+  tool(
+    'gh_repo_search',
+    'Search GitHub repositories by name, description or README (GitHub search syntax, e.g. "dsh-plugin in:name,description"). Uses the separate search quota. Read-only.',
+    {
+      query: { type: 'string', description: 'Search query in GitHub search syntax.' },
+      limit: { type: 'number', description: 'How many repositories to return (max 100, default 20).' },
+    },
+    async (args) => searchRepos(await client(), { query: args.query, limit: args.limit }),
+  )
+
+  tool(
+    'gh_repo_create',
+    'Create a GitHub repository for the authenticated user, or inside an organization when org is given. Defaults to private.',
+    {
+      name: { type: 'string', description: 'Repository name.' },
+      org: { type: 'string', description: 'Organization to create it in; omit for the authenticated user.' },
+      description: { type: 'string', description: 'Repository description.' },
+      private: { type: 'boolean', description: 'Private repository (default true).' },
+      autoInit: { type: 'boolean', description: 'Initialize with a README (default false).' },
+    },
+    async (args) => createRepo(await client(), {
+      name: args.name,
+      org: args.org,
+      description: args.description,
+      private: args.private,
+      autoInit: args.autoInit,
+    }),
+  )
+
+  tool(
+    'gh_repo_edit',
+    'Edit repository settings: description, homepage, visibility, archived flag and topics (topics replace the whole list).',
+    repoParams({
+      description: { type: 'string', description: 'New description.' },
+      homepage: { type: 'string', description: 'New homepage URL.' },
+      private: { type: 'boolean', description: 'Change visibility.' },
+      archived: { type: 'boolean', description: 'Archive or unarchive.' },
+      topics: { type: 'array', items: { type: 'string' }, description: 'Full replacement list of topics.' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return editRepo(await client(), {
+        owner, repo,
+        description: args.description,
+        homepage: args.homepage,
+        private: args.private,
+        archived: args.archived,
+        topics: args.topics,
+      })
+    },
+  )
+
+  // -------------------------------------------------------------------- releases
+
+  tool(
+    'gh_release_list',
+    'List GitHub releases of a repository, newest first. Read-only. Use it to check whether a version was already released and which release is marked latest.',
+    repoParams({ limit: { type: 'number', description: 'How many releases to return (1-100, default 30).' } }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      const result = await listReleases(await client(), { owner, repo, limit: args.limit })
+      return { releases: result.releases, count: result.count }
+    },
+  )
+
+  tool(
+    'gh_release_view',
+    'Read one GitHub release by tag: name, draft/prerelease flags, notes, assets and URLs. Read-only.',
+    repoParams({ tag: { type: 'string', description: 'Release tag, e.g. "v1.2.3".' } }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return getRelease(await client(), { owner, repo, tag: args.tag })
+    },
+  )
+
+  tool(
+    'gh_release_create',
+    'Create a GitHub release for a tag (the tag may already exist; pass target to place it on a commit). This is a public-channel write: use it only for an approved release.',
+    repoParams({
+      tag: { type: 'string', description: 'Tag to release, e.g. "v1.2.3".' },
+      name: { type: 'string', description: 'Release title; defaults to the tag.' },
+      body: { type: 'string', description: 'Release notes in markdown.' },
+      target: { type: 'string', description: 'Commit SHA or branch to place the tag on.' },
+      draft: { type: 'boolean', description: 'Create as a draft (default false).' },
+      prerelease: { type: 'boolean', description: 'Mark as a pre-release (default false).' },
+      generateNotes: { type: 'boolean', description: 'Let GitHub generate notes from commits.' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return createRelease(await client(), {
+        owner, repo,
+        tag: args.tag,
+        name: args.name,
+        body: args.body,
+        draft: args.draft,
+        prerelease: args.prerelease,
+        target: args.target,
+        generateNotes: args.generateNotes,
+      })
+    },
+  )
+
+  tool(
+    'gh_release_edit',
+    'Edit a GitHub release: title, notes, draft/prerelease flags, and which release is marked latest (makeLatest). Use makeLatest: true after publishing a new version so the repository badge does not stay on an older release. For a DRAFT release pass releaseId (returned by gh_release_create): GitHub hides drafts from the by-tag lookup.',
+    repoParams({
+      tag: { type: 'string', description: 'Release tag to edit.' },
+      releaseId: { type: 'number', description: 'Release id from gh_release_create or gh_release_list; required for a draft.' },
+      name: { type: 'string', description: 'New title.' },
+      body: { type: 'string', description: 'New notes.' },
+      draft: { type: 'boolean', description: 'Draft flag.' },
+      prerelease: { type: 'boolean', description: 'Pre-release flag.' },
+      makeLatest: { type: 'boolean', description: 'true marks this release as latest; false unmarks it.' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return editRelease(await client(), {
+        owner, repo,
+        tag: args.tag,
+        releaseId: args.releaseId,
+        name: args.name,
+        body: args.body,
+        draft: args.draft,
+        prerelease: args.prerelease,
+        makeLatest: args.makeLatest,
+      })
+    },
+  )
+
+  tool(
+    'gh_release_delete',
+    'Delete a GitHub release. Requires confirm: true. The git tag itself is not removed — use gh_tag_delete for that. For a DRAFT release pass releaseId: GitHub hides drafts from the by-tag lookup.',
+    repoParams({
+      tag: { type: 'string', description: 'Release tag to delete.' },
+      releaseId: { type: 'number', description: 'Release id, when the tag is unknown.' },
+      confirm: { type: 'boolean', description: 'Must be true to actually delete.' },
+    }),
+    async (args) => {
+      if (args.confirm !== true) throw new Error('refusing to delete a release without confirm: true')
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return deleteRelease(await client(), { owner, repo, tag: args.tag, releaseId: args.releaseId })
+    },
+  )
+
+  // ------------------------------------------------------------------------ tags
+
+  tool(
+    'gh_tag_list',
+    'List git tags of a repository with their commit SHAs. Read-only. Use it to check whether the tag for a release already exists.',
+    repoParams({ limit: { type: 'number', description: 'How many tags to return (default 100).' } }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      const result = await listTags(await client(), { owner, repo, limit: args.limit })
+      return { tags: result.tags, count: result.count }
+    },
+  )
+
+  tool(
+    'gh_tag_create',
+    'Create a git tag. Without message it is lightweight; with message GitHub creates an annotated tag object first. Pass sha to tag a specific commit, otherwise HEAD is tagged.',
+    repoParams({
+      tag: { type: 'string', description: 'Tag name, e.g. "v1.2.3".' },
+      sha: { type: 'string', description: 'Commit SHA to tag; defaults to HEAD.' },
+      message: { type: 'string', description: 'Annotation message; presence makes the tag annotated.' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return createTag(await client(), { owner, repo, tag: args.tag, sha: args.sha, message: args.message })
+    },
+  )
+
+  tool(
+    'gh_tag_delete',
+    'Delete a git tag. Requires confirm: true.',
+    repoParams({
+      tag: { type: 'string', description: 'Tag to delete.' },
+      confirm: { type: 'boolean', description: 'Must be true to actually delete.' },
+    }),
+    async (args) => {
+      if (args.confirm !== true) throw new Error('refusing to delete a tag without confirm: true')
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return deleteTag(await client(), { owner, repo, tag: args.tag })
+    },
+  )
+
+  // ------------------------------------------------------------------------- api
+
+  tool(
+    'gh_api',
+    'Call the GitHub API directly for anything the other tools do not cover (refs, rulesets, orgs, gists). Reads are free; POST/PATCH/PUT/DELETE require confirm: true, and deleting a repository, transferring one, or deleting an organization is refused outright. Pass graphql to run a GraphQL query instead of a REST path.',
+    {
+      method: { type: 'string', description: 'HTTP method: GET (default), POST, PATCH, PUT, DELETE.' },
+      path: { type: 'string', description: 'REST path relative to the API base, e.g. "/repos/owner/repo/git/refs".' },
+      query: { type: 'object', additionalProperties: true, description: 'Query string parameters.' },
+      body: { type: 'object', additionalProperties: true, description: 'JSON body for POST/PATCH/PUT, or GraphQL variables.' },
+      graphql: { type: 'string', description: 'GraphQL query; when set, path/method are ignored.' },
+      confirm: { type: 'boolean', description: 'Required for state-changing calls.' },
+    },
+    async (args) => {
+      const result = await callApi(await client(), {
+        method: args.method,
+        path: args.path,
+        query: args.query,
+        body: args.body,
+        confirm: args.confirm,
+        graphql: args.graphql,
+      })
+      return {
+        method: result.method || 'GRAPHQL',
+        mutating: Boolean(result.mutating),
+        status: result.status,
+        data: result.data,
+      }
+    },
+  )
+}

package/lib/tools/register-jobs.js

@@ -0,0 +1,57 @@
+// Background review tools.
+//
+// A review that takes a while should not hold a turn. `gh_review_job` starts one and answers
+// immediately with a job id; `gh_review_job_status` reports the record. When the host exposes
+// a job registry the work runs there (visible and cancellable in the UI); otherwise it runs
+// in this plugin, which is why the tool works either way.
+
+import { ciRun } from './pulls.js'
+
+const REPOSITORY = {
+  repository: { type: 'string', description: 'Repository as "owner/repo". Omit to use the default from settings or the checkout.' },
+}
+
+export function registerJobTools({ tool, asRepo, client, liveConfig, reviewRules, jobs }) {
+  const repoParams = (extra = {}) => ({ ...REPOSITORY, ...extra })
+
+  tool(
+    'gh_review_job',
+    'Start a background review of a pull request and return its job id immediately. Works through the host job registry when one is composed, otherwise inside the plugin. Use gh_review_job_status to read the result.',
+    repoParams({
+      number: { type: 'number', description: 'Pull request number.' },
+      maxDiffChars: { type: 'number', description: 'Cap for the diff text (default 60000).' },
+      label: { type: 'string', description: 'Human label for the job.' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      const cfg = liveConfig()
+      const id = jobs.start({
+        repo: `${owner}/${repo}`,
+        pr: args.number,
+        label: args.label,
+        owner: args.owner,
+        timeoutMs: Number(cfg.reviewJobTimeoutMs) || 120000,
+        maxDiffChars: args.maxDiffChars,
+        rules: typeof reviewRules === 'function' ? reviewRules() : undefined,
+        client,
+        ciRun,
+      })
+      return { jobId: id, repo: `${owner}/${repo}`, number: args.number, note: 'The review runs in the background; read it with gh_review_job_status.' }
+    },
+  )
+
+  tool(
+    'gh_review_job_status',
+    'Read a background review job: running, done with the report, or failed with the reason. Read-only.',
+    {
+      jobId: { type: 'string', description: 'Job id returned by gh_review_job.' },
+      all: { type: 'boolean', description: 'List the recent jobs of this session instead of one.' },
+    },
+    async (args) => {
+      if (args.all) return { jobs: jobs.list() }
+      const record = jobs.get(args.jobId)
+      if (!record) return { jobId: args.jobId, status: 'unknown', note: 'No such job in this session (records are bounded and kept in memory).' }
+      return { jobId: args.jobId, status: record.status, report: record.report, error: record.error }
+    },
+  )
+}

package/lib/tools/register-mirror.js

@@ -0,0 +1,88 @@
+// Mirror tool registrations: a read-only plan and a sanitized publication.
+//
+// These work on a local checkout: the caller names the working copy, the source ref and
+// the mirror remote. `gh_mirror_publish` refuses to run without confirm: true, refuses
+// a plan with a forbidden path in the allowlist or a missing product file, and always
+// pushes a fast-forward on top of the mirror branch — never a force.
+
+import { planMirror, publishMirror, DEFAULT_ALLOW, DEFAULT_FORBIDDEN, DEFAULT_REQUIRED } from './mirror.js'
+
+const MIRROR_PARAMS = {
+  cwd: { type: 'string', description: 'Absolute path of the local checkout to publish from. Defaults to the session working directory.' },
+  ref: { type: 'string', description: 'Source ref to publish, e.g. origin/main (default).' },
+  mirror: { type: 'string', description: 'Mirror remote name (default github).' },
+  branch: { type: 'string', description: 'Mirror branch (default main).' },
+}
+
+export function registerMirrorTools({ tool, git, defaultCwd }) {
+  const where = (args) => ({ cwd: args.cwd || defaultCwd(), ref: args.ref || 'origin/main' })
+
+  tool(
+    'gh_mirror_check',
+    'Show what a sanitized GitHub mirror publication would contain: the product files from the package manifest that would be published, how many files would stay behind, and whether the publication must be refused (a forbidden path in the allowlist, or a missing product file). Read-only: nothing is written or pushed.',
+    {
+      ...MIRROR_PARAMS,
+      allow: { type: 'array', items: { type: 'string' }, description: 'Override the allowlist (defaults to the package manifest "files" plus README/LICENSE/CHANGELOG).' },
+      required: { type: 'array', items: { type: 'string' }, description: 'Files that must be present (default package.json and README.md).' },
+    },
+    async (args) => {
+      const plan = await planMirror({
+        git,
+        ...where(args),
+        allow: args.allow,
+        required: args.required && args.required.length ? args.required : DEFAULT_REQUIRED,
+        forbidden: DEFAULT_FORBIDDEN,
+      })
+      return {
+        mirror: `${args.mirror || 'github'}/${args.branch || 'main'}`,
+        sourceCommit: plan.sha,
+        willPublish: plan.publish,
+        willPublishCount: plan.publish.length,
+        willDropCount: plan.drop.length,
+        refused: plan.refused,
+      }
+    },
+  )
+
+  tool(
+    'gh_mirror_publish',
+    'Publish the sanitized product tree to the GitHub mirror: one commit on top of the mirror branch, pushed as a fast-forward (never a force, mirror history is not rewritten). Refuses when the allowlist contains a forbidden path or a required product file is missing. Pass dryRun: true to see the plan without writing; publishing itself needs confirm: true.',
+    {
+      ...MIRROR_PARAMS,
+      allow: { type: 'array', items: { type: 'string' }, description: 'Override the allowlist.' },
+      required: { type: 'array', items: { type: 'string' }, description: 'Files that must be present.' },
+      message: { type: 'string', description: 'Commit message for the mirror commit.' },
+      dryRun: { type: 'boolean', description: 'Plan only: nothing is committed or pushed.' },
+      confirm: { type: 'boolean', description: 'Must be true to write to the mirror.' },
+    },
+    async (args) => {
+      const dryRun = args.dryRun === true
+      if (!dryRun && args.confirm !== true) {
+        throw new Error('refusing to publish to a mirror without confirm: true (or pass dryRun: true to preview)')
+      }
+      const result = await publishMirror({
+        git,
+        ...where(args),
+        mirror: args.mirror || 'github',
+        branch: args.branch || 'main',
+        allow: args.allow && args.allow.length ? args.allow : undefined,
+        required: args.required && args.required.length ? args.required : DEFAULT_REQUIRED,
+        forbidden: DEFAULT_FORBIDDEN,
+        message: args.message,
+        dryRun,
+      })
+      return {
+        mirror: result.mirror,
+        pushed: result.pushed,
+        commit: result.commit,
+        parent: result.parent,
+        correspondence: result.correspondence,
+        willPublishCount: result.publish.length,
+        willDropCount: result.drop.length,
+        dryRun,
+      }
+    },
+  )
+}
+
+export { DEFAULT_ALLOW, DEFAULT_FORBIDDEN, DEFAULT_REQUIRED }