@goodandready/dsh-github-ops 0.6.11 → 0.6.13

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.6.13
+
+### Features
+- **GitHub Discussions GraphQL Tools (#118)**: Added `gh_discussion_list`, `gh_discussion_view`, `gh_discussion_create`, and `gh_discussion_comment` tools using GitHub GraphQL API with `confirm: true` protection for creating discussions and posting threaded replies.
+- **Bi-directional Issue Mirroring & Sync GitHub ↔ Gitea (#120)**: Added `gh_issue_mirror_sync` tool with anti-loop synchronization markers (`<!-- synced-from: ... -->`), propagation of comments across GitHub and Gitea in both directions, and automatic synchronized closure of linked issues upon release.
+
 ## 0.6.11
 
 ### Features

package/lib/tools/discussions.js

@@ -0,0 +1,275 @@
+// GitHub Discussions GraphQL tools.
+// Pure functions over GitHub client.graphql.
+
+function ensureRepo({ owner, repo }) {
+  if (!owner || !repo) {
+    throw new Error('owner and repo are required (pass "repository": "owner/repo" or set defaults in settings)')
+  }
+}
+
+/** List discussions for a repository. */
+export async function listDiscussions(client, { owner, repo, categoryId, limit = 20 } = {}) {
+  ensureRepo({ owner, repo })
+  const perPage = Math.max(1, Math.min(Number(limit) || 20, 50))
+
+  const query = `
+    query ListDiscussions($owner: String!, $repo: String!, $first: Int!, $categoryId: ID) {
+      repository(owner: $owner, name: $repo) {
+        discussions(first: $first, categoryId: $categoryId, orderBy: {field: CREATED_AT, direction: DESC}) {
+          totalCount
+          nodes {
+            id
+            number
+            title
+            url
+            createdAt
+            upvoteCount
+            author {
+              login
+            }
+            category {
+              id
+              name
+              emoji
+            }
+            comments {
+              totalCount
+            }
+          }
+        }
+      }
+    }
+  `
+
+  const data = await client.graphql(query, {
+    owner,
+    repo,
+    first: perPage,
+    categoryId: categoryId || null,
+  })
+
+  const conn = data?.repository?.discussions
+  const nodes = Array.isArray(conn?.nodes) ? conn.nodes : []
+
+  return {
+    totalCount: typeof conn?.totalCount === 'number' ? conn.totalCount : nodes.length,
+    discussions: nodes.map((d) => ({
+      id: d.id,
+      number: d.number,
+      title: d.title,
+      url: d.url,
+      createdAt: d.createdAt,
+      upvoteCount: d.upvoteCount || 0,
+      author: d.author?.login || 'ghost',
+      category: d.category ? { id: d.category.id, name: d.category.name, emoji: d.category.emoji } : null,
+      commentsCount: d.comments?.totalCount || 0,
+    })),
+  }
+}
+
+/** View discussion details and comments by number. */
+export async function getDiscussion(client, { owner, repo, number } = {}) {
+  ensureRepo({ owner, repo })
+  if (!number) throw new Error('discussion number is required')
+
+  const query = `
+    query GetDiscussion($owner: String!, $repo: String!, $number: Int!) {
+      repository(owner: $owner, name: $repo) {
+        discussion(number: $number) {
+          id
+          number
+          title
+          body
+          url
+          createdAt
+          upvoteCount
+          author {
+            login
+          }
+          category {
+            id
+            name
+            emoji
+          }
+          comments(first: 30) {
+            totalCount
+            nodes {
+              id
+              body
+              createdAt
+              upvoteCount
+              isAnswer
+              author {
+                login
+              }
+            }
+          }
+        }
+      }
+    }
+  `
+
+  const data = await client.graphql(query, {
+    owner,
+    repo,
+    number: Number(number),
+  })
+
+  const d = data?.repository?.discussion
+  if (!d) throw new Error(`Discussion #${number} not found in ${owner}/${repo}`)
+
+  const commentNodes = Array.isArray(d.comments?.nodes) ? d.comments.nodes : []
+
+  return {
+    id: d.id,
+    number: d.number,
+    title: d.title,
+    body: d.body || '',
+    url: d.url,
+    createdAt: d.createdAt,
+    upvoteCount: d.upvoteCount || 0,
+    author: d.author?.login || 'ghost',
+    category: d.category ? { id: d.category.id, name: d.category.name, emoji: d.category.emoji } : null,
+    commentsCount: d.comments?.totalCount || commentNodes.length,
+    comments: commentNodes.map((c) => ({
+      id: c.id,
+      body: c.body || '',
+      createdAt: c.createdAt,
+      upvoteCount: c.upvoteCount || 0,
+      isAnswer: Boolean(c.isAnswer),
+      author: c.author?.login || 'ghost',
+    })),
+  }
+}
+
+/** Create a new discussion (requires confirm: true). */
+export async function createDiscussion(client, {
+  owner, repo, title, body, categoryId, confirm = false,
+} = {}) {
+  ensureRepo({ owner, repo })
+  if (!title) throw new Error('title is required')
+  if (!body) throw new Error('body is required')
+
+  if (confirm !== true) {
+    return {
+      dryRun: true,
+      refused: 'confirm: true is required to publish a new discussion',
+      target: `${owner}/${repo}`,
+      title,
+      bodyPreview: body.slice(0, 200),
+      categoryId: categoryId || 'first_available',
+    }
+  }
+
+  let repoId = ''
+  let targetCatId = categoryId || ''
+
+  const repoQuery = `
+    query ResolveRepo($owner: String!, $repo: String!) {
+      repository(owner: $owner, name: $repo) {
+        id
+        discussionCategories(first: 10) {
+          nodes {
+            id
+            name
+          }
+        }
+      }
+    }
+  `
+  const repoData = await client.graphql(repoQuery, { owner, repo })
+  repoId = repoData?.repository?.id
+  if (!repoId) throw new Error(`Cannot resolve repository ID for ${owner}/${repo}`)
+
+  if (!targetCatId) {
+    const cats = repoData?.repository?.discussionCategories?.nodes || []
+    if (cats.length === 0) throw new Error(`Repository ${owner}/${repo} has no discussion categories enabled`)
+    targetCatId = cats[0].id
+  }
+
+  const mutation = `
+    mutation CreateDiscussion($repositoryId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
+      createDiscussion(input: {repositoryId: $repositoryId, categoryId: $categoryId, title: $title, body: $body}) {
+        discussion {
+          id
+          number
+          title
+          url
+          createdAt
+        }
+      }
+    }
+  `
+
+  const result = await client.graphql(mutation, {
+    repositoryId: repoId,
+    categoryId: targetCatId,
+    title,
+    body,
+  })
+
+  const disc = result?.createDiscussion?.discussion
+  return {
+    success: true,
+    id: disc?.id,
+    number: disc?.number,
+    title: disc?.title,
+    url: disc?.url,
+    createdAt: disc?.createdAt,
+  }
+}
+
+/** Comment on a discussion (requires confirm: true). */
+export async function commentDiscussion(client, {
+  owner, repo, discussionId, number, body, confirm = false,
+} = {}) {
+  ensureRepo({ owner, repo })
+  if (!body) throw new Error('body is required')
+
+  let targetId = discussionId
+  if (!targetId && number) {
+    const d = await getDiscussion(client, { owner, repo, number })
+    targetId = d.id
+  }
+  if (!targetId) throw new Error('discussionId or discussion number is required')
+
+  if (confirm !== true) {
+    return {
+      dryRun: true,
+      refused: 'confirm: true is required to post a discussion comment',
+      discussionId: targetId,
+      bodyPreview: body.slice(0, 200),
+    }
+  }
+
+  const mutation = `
+    mutation AddComment($discussionId: ID!, $body: String!) {
+      addDiscussionComment(input: {discussionId: $discussionId, body: $body}) {
+        comment {
+          id
+          body
+          url
+          createdAt
+          author {
+            login
+          }
+        }
+      }
+    }
+  `
+
+  const result = await client.graphql(mutation, {
+    discussionId: targetId,
+    body,
+  })
+
+  const c = result?.addDiscussionComment?.comment
+  return {
+    success: true,
+    id: c?.id,
+    body: c?.body,
+    url: c?.url,
+    createdAt: c?.createdAt,
+    author: c?.author?.login || 'unknown',
+  }
+}

package/lib/tools/register-collab.js

@@ -1,4 +1,10 @@
-import { triageExternalIssues } from './triage.js'
+import { triageExternalIssues, syncIssueMirror } from './triage.js'
+import {
+  listDiscussions,
+  getDiscussion,
+  createDiscussion,
+  commentDiscussion,
+} from './discussions.js'
 // Collaboration tool registrations: issues, pull requests, reviews and checks.
 //
 // Reads are free; every write goes through the caller's confirmation contour in the
@@ -383,4 +389,101 @@ export function registerCollabTools({ tool, asRepo, client, liveConfig, reviewRu
       giteaBaseUrl: args.giteaBaseUrl,
     })),
   )
+
+  // ------------------------------------------------------------------------ discussions (#118)
+
+  tool(
+    'gh_discussion_list',
+    'List repository discussions via GraphQL, including category, upvotes, author, and comment counts. Read-only.',
+    repoParams({
+      categoryId: { type: 'string', description: 'Filter by discussion category ID.' },
+      limit: { type: 'number', description: 'Max discussions to return (default 20, max 50).' },
+    }),
+    async (args) => withRepo(args, async ({ owner, repo }) => listDiscussions(await client(), {
+      owner,
+      repo,
+      categoryId: args.categoryId,
+      limit: args.limit,
+    })),
+  )
+
+  tool(
+    'gh_discussion_view',
+    'View a discussion and its threaded replies by discussion number. Read-only.',
+    repoParams({
+      number: { type: 'number', description: 'Discussion number. Required.' },
+    }),
+    async (args) => withRepo(args, async ({ owner, repo }) => getDiscussion(await client(), {
+      owner,
+      repo,
+      number: args.number,
+    })),
+  )
+
+  tool(
+    'gh_discussion_create',
+    'Start a new GitHub discussion. Requires confirm: true.',
+    repoParams({
+      title: { type: 'string', description: 'Discussion title. Required.' },
+      body: { type: 'string', description: 'Discussion body text (markdown). Required.' },
+      categoryId: { type: 'string', description: 'Category ID (defaults to the first available category).' },
+      confirm: { type: 'boolean', description: 'Must be true to publish the discussion.' },
+    }),
+    async (args) => withRepo(args, async ({ owner, repo }) => createDiscussion(await client(), {
+      owner,
+      repo,
+      title: args.title,
+      body: args.body,
+      categoryId: args.categoryId,
+      confirm: args.confirm === true,
+    })),
+  )
+
+  tool(
+    'gh_discussion_comment',
+    'Post a reply or comment to an existing GitHub discussion. Requires confirm: true.',
+    repoParams({
+      discussionId: { type: 'string', description: 'Discussion GraphQL node ID.' },
+      number: { type: 'number', description: 'Discussion number (used to resolve ID if omitted).' },
+      body: { type: 'string', description: 'Comment body (markdown). Required.' },
+      confirm: { type: 'boolean', description: 'Must be true to post the comment.' },
+    }),
+    async (args) => withRepo(args, async ({ owner, repo }) => commentDiscussion(await client(), {
+      owner,
+      repo,
+      discussionId: args.discussionId,
+      number: args.number,
+      body: args.body,
+      confirm: args.confirm === true,
+    })),
+  )
+
+  // ------------------------------------------------------------------------ bi-directional mirror sync (#120)
+
+  tool(
+    'gh_issue_mirror_sync',
+    'Bi-directional synchronization of comments and issue states between GitHub and Gitea. Requires confirm: true for mutations.',
+    repoParams({
+      githubIssueNumber: { type: 'number', description: 'GitHub issue number. Required.' },
+      giteaIssueNumber: { type: 'number', description: 'Gitea issue number. Required.' },
+      giteaOwner: { type: 'string', description: 'Gitea owner (default "goodandready").' },
+      giteaRepo: { type: 'string', description: 'Gitea repository name (defaults to GitHub repo name).' },
+      direction: { type: 'string', description: 'Sync direction: "both" (default), "gitea_to_github", "github_to_gitea".' },
+      syncState: { type: 'boolean', description: 'Whether to synchronize closed/open issue state (default true).' },
+      confirm: { type: 'boolean', description: 'Must be true to post comments and update states.' },
+      giteaBaseUrl: { type: 'string', description: 'Base URL of local Gitea instance (default "http://127.0.0.1:3005").' },
+    }),
+    async (args) => withRepo(args, async ({ owner, repo }) => syncIssueMirror(await client(), {
+      repository: `${owner}/${repo}`,
+      githubIssueNumber: args.githubIssueNumber,
+      giteaIssueNumber: args.giteaIssueNumber,
+      giteaOwner: args.giteaOwner,
+      giteaRepo: args.giteaRepo,
+      direction: args.direction || 'both',
+      syncState: args.syncState !== false,
+      confirm: args.confirm === true,
+      giteaBaseUrl: args.giteaBaseUrl,
+    })),
+  )
+
 }

package/lib/tools/triage.js

@@ -211,3 +211,150 @@ export async function triageExternalIssues(client, options = {}, deps = {}) {
     items,
   }
 }
+
+
+export async function syncIssueMirror(client, options = {}, deps = {}) {
+  const {
+    repository = '',
+    githubIssueNumber,
+    giteaOwner = 'goodandready',
+    giteaRepo = '',
+    giteaIssueNumber,
+    direction = 'both',
+    syncState = true,
+    confirm = false,
+    giteaBaseUrl = 'http://127.0.0.1:3005',
+    giteaToken = '',
+  } = options
+  const { fetchFn = globalThis.fetch } = deps
+
+  if (!repository || !repository.includes('/')) {
+    throw new Error('repository must be in "owner/repo" format')
+  }
+  const [owner, repo] = repository.split('/')
+  const targetGiteaRepo = giteaRepo || repo
+
+  if (!githubIssueNumber) throw new Error('githubIssueNumber is required')
+  if (!giteaIssueNumber) throw new Error('giteaIssueNumber is required')
+
+  const token = resolveGiteaToken(giteaToken)
+
+  // 1. Fetch GitHub issue and comments
+  const { data: ghIssue } = await client.get(`/repos/${owner}/${repo}/issues/${githubIssueNumber}`)
+  const { data: ghCommentsRaw } = await client.get(`/repos/${owner}/${repo}/issues/${githubIssueNumber}/comments`)
+  const ghComments = Array.isArray(ghCommentsRaw) ? ghCommentsRaw : []
+
+  // 2. Fetch Gitea issue and comments
+  const giteaHeaders = { accept: 'application/json' }
+  if (token) giteaHeaders.authorization = `token ${token}`
+  const baseGitea = giteaBaseUrl.replace(/\/$/, '')
+
+  const giteaIssueRes = await fetchFn(`${baseGitea}/api/v1/repos/${giteaOwner}/${targetGiteaRepo}/issues/${giteaIssueNumber}`, { headers: giteaHeaders })
+  if (!giteaIssueRes.ok) throw new Error(`Failed to fetch Gitea issue #${giteaIssueNumber}: status ${giteaIssueRes.status}`)
+  const giteaIssue = await giteaIssueRes.json()
+
+  const giteaCommentsRes = await fetchFn(`${baseGitea}/api/v1/repos/${giteaOwner}/${targetGiteaRepo}/issues/${giteaIssueNumber}/comments`, { headers: giteaHeaders })
+  const giteaComments = giteaCommentsRes.ok ? (await giteaCommentsRes.json()) : []
+
+  // 3. Determine state sync action
+  let stateAction = null
+  if (syncState) {
+    if (ghIssue.state === 'closed' && giteaIssue.state === 'open') {
+      stateAction = 'close_gitea'
+    } else if (giteaIssue.state === 'closed' && ghIssue.state === 'open') {
+      stateAction = 'close_github'
+    }
+  }
+
+  // 4. Find comments to sync (prevent cycles using markers)
+  const pendingGiteaToGithub = []
+  if (direction === 'both' || direction === 'gitea_to_github') {
+    for (const gc of giteaComments) {
+      if (!gc.body || gc.body.includes('synced-from: github#')) continue
+      const marker = `synced-from: gitea#${gc.id}`
+      const alreadyOnGh = ghComments.some((ghc) => ghc.body && ghc.body.includes(marker))
+      if (!alreadyOnGh) {
+        pendingGiteaToGithub.push({
+          id: gc.id,
+          author: gc.user?.login || 'user',
+          body: gc.body,
+        })
+      }
+    }
+  }
+
+  const pendingGithubToGitea = []
+  if (direction === 'both' || direction === 'github_to_gitea') {
+    for (const ghc of ghComments) {
+      if (!ghc.body || ghc.body.includes('synced-from: gitea#')) continue
+      const marker = `synced-from: github#${ghc.id}`
+      const alreadyOnGitea = giteaComments.some((gc) => gc.body && gc.body.includes(marker))
+      if (!alreadyOnGitea) {
+        pendingGithubToGitea.push({
+          id: ghc.id,
+          author: ghc.user?.login || 'user',
+          body: ghc.body,
+        })
+      }
+    }
+  }
+
+  // If dryRun (confirm !== true)
+  if (confirm !== true) {
+    return {
+      dryRun: true,
+      refused: 'confirm: true is required to execute issue synchronization',
+      repository: `${owner}/${repo}#${githubIssueNumber}`,
+      giteaRepository: `${giteaOwner}/${targetGiteaRepo}#${giteaIssueNumber}`,
+      githubState: ghIssue.state,
+      giteaState: giteaIssue.state,
+      stateAction,
+      pendingGiteaToGithubCount: pendingGiteaToGithub.length,
+      pendingGithubToGiteaCount: pendingGithubToGitea.length,
+      pendingGiteaToGithub,
+      pendingGithubToGitea,
+    }
+  }
+
+  // 5. Execute sync
+  let syncedGiteaToGithub = 0
+  for (const gc of pendingGiteaToGithub) {
+    const body = `${gc.body}\n\n<!-- synced-from: gitea#${gc.id} by @${gc.author} -->`
+    await client.post(`/repos/${owner}/${repo}/issues/${githubIssueNumber}/comments`, { body })
+    syncedGiteaToGithub += 1
+  }
+
+  let syncedGithubToGitea = 0
+  for (const ghc of pendingGithubToGitea) {
+    const body = `${ghc.body}\n\n<!-- synced-from: github#${ghc.id} by @${ghc.author} -->`
+    await fetchFn(`${baseGitea}/api/v1/repos/${giteaOwner}/${targetGiteaRepo}/issues/${giteaIssueNumber}/comments`, {
+      method: 'POST',
+      headers: { ...giteaHeaders, 'content-type': 'application/json' },
+      body: JSON.stringify({ body }),
+    })
+    syncedGithubToGitea += 1
+  }
+
+  let stateSynced = false
+  if (stateAction === 'close_github') {
+    await client.patch(`/repos/${owner}/${repo}/issues/${githubIssueNumber}`, { state: 'closed' })
+    stateSynced = true
+  } else if (stateAction === 'close_gitea') {
+    await fetchFn(`${baseGitea}/api/v1/repos/${giteaOwner}/${targetGiteaRepo}/issues/${giteaIssueNumber}`, {
+      method: 'PATCH',
+      headers: { ...giteaHeaders, 'content-type': 'application/json' },
+      body: JSON.stringify({ state: 'closed' }),
+    })
+    stateSynced = true
+  }
+
+  return {
+    success: true,
+    repository: `${owner}/${repo}#${githubIssueNumber}`,
+    giteaRepository: `${giteaOwner}/${targetGiteaRepo}#${giteaIssueNumber}`,
+    syncedGiteaToGithub,
+    syncedGithubToGitea,
+    stateAction,
+    stateSynced,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-github-ops",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "description": "GitHub operations for DeepSeek Harness: releases, tags, a guarded generic API pass-through, workflow runs, secrets and sanitized mirror publication.",
   "license": "MIT",
   "type": "module",