@goodandready/dsh-github-ops 0.6.9 → 0.6.11

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.6.11
+
+### Features
+- **GitHub Environments & Deployments Management (#122)**: Added `gh_environment_list` tool to inspect deployment environments, wait timers, and protection rules. Added `gh_deployment_list`, `gh_deployment_create`, and `gh_deployment_status_create` tools for full deployment lifecycle auditing and status updates.
+- **Webhook Simulator & Event Emitter (#125)**: Added `gh_webhook_simulate` tool supporting canonical mock payloads for `issues`, `pull_request`, `workflow_run`, `release`, `deployment`, `deployment_status`, and `push` events, with live broadcast into local `SseEventManager` and optional HTTP delivery to webhook receivers.
+
 ## 0.6.9
 
 ### Features

package/lib/events.js

@@ -1,3 +1,14 @@
+
+let activeEventManager = null
+
+export function setGlobalEventManager(mgr) {
+  activeEventManager = mgr
+}
+
+export function getGlobalEventManager() {
+  return activeEventManager
+}
+
 // Server-Sent Events (SSE) notification manager for CI runs and PR events.
 //
 // Maintains client subscriptions, broadcasts real-time events, and runs an adaptive
@@ -21,6 +32,7 @@ export class SseEventManager {
     this.lastRuns = new Map() // runId -> { status, conclusion }
     this.lastPulls = new Map() // pullNumber -> { updated, state }
     this.hasActiveWork = false
+    setGlobalEventManager(this)
   }
 
   get clientCount() {
@@ -197,5 +209,6 @@ export class SseEventManager {
     this.clients.clear()
     this.lastRuns.clear()
     this.lastPulls.clear()
+    if (getGlobalEventManager() === this) setGlobalEventManager(null)
   }
 }

package/lib/tools/deployments.js

@@ -0,0 +1,154 @@
+// GitHub Environments and Deployments tools.
+// Pure functions over a GitHub client.
+
+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 environments for a repository. */
+export async function listEnvironments(client, { owner, repo, limit = 30 } = {}) {
+  ensureRepo({ owner, repo })
+  const perPage = Math.max(1, Math.min(Number(limit) || 30, 100))
+  const { data } = await client.get(`/repos/${owner}/${repo}/environments`, {
+    query: { per_page: perPage },
+  })
+  const envs = data && Array.isArray(data.environments) ? data.environments : []
+  return {
+    totalCount: data && typeof data.total_count === 'number' ? data.total_count : envs.length,
+    environments: envs.map((env) => ({
+      id: env.id,
+      name: env.name,
+      url: env.html_url || '',
+      createdAt: env.created_at,
+      updatedAt: env.updated_at,
+      protectionRulesCount: Array.isArray(env.protection_rules) ? env.protection_rules.length : 0,
+      protectionRules: (env.protection_rules || []).map((r) => ({
+        id: r.id,
+        type: r.type,
+        waitTimer: r.wait_timer,
+      })),
+    })),
+  }
+}
+
+/** List deployments for a repository. */
+export async function listDeployments(client, { owner, repo, environment, ref, sha, task, limit = 30 } = {}) {
+  ensureRepo({ owner, repo })
+  const perPage = Math.max(1, Math.min(Number(limit) || 30, 100))
+  const query = { per_page: perPage }
+  if (environment) query.environment = environment
+  if (ref) query.ref = ref
+  if (sha) query.sha = sha
+  if (task) query.task = task
+
+  const { data } = await client.get(`/repos/${owner}/${repo}/deployments`, { query })
+  const deployments = Array.isArray(data) ? data : []
+  return {
+    deployments: deployments.map((d) => ({
+      id: d.id,
+      sha: d.sha,
+      ref: d.ref,
+      task: d.task,
+      environment: d.environment,
+      description: d.description || '',
+      creator: d.creator && d.creator.login,
+      createdAt: d.created_at,
+      updatedAt: d.updated_at,
+      url: d.url,
+      statusesUrl: d.statuses_url,
+    })),
+  }
+}
+
+/** Create a new deployment for a ref. */
+export async function createDeployment(client, {
+  owner, repo, ref, environment = 'production', description, task = 'deploy',
+  autoMerge = false, requiredContexts = [], transientEnvironment = false,
+  productionEnvironment,
+} = {}) {
+  ensureRepo({ owner, repo })
+  if (!ref) throw new Error('ref is required (branch name, tag or commit SHA)')
+
+  const payload = {
+    ref,
+    environment,
+    task,
+    auto_merge: Boolean(autoMerge),
+    required_contexts: Array.isArray(requiredContexts) ? requiredContexts : [],
+    transient_environment: Boolean(transientEnvironment),
+  }
+  if (typeof productionEnvironment === 'boolean') {
+    payload.production_environment = productionEnvironment
+  }
+  if (description) payload.description = String(description)
+
+  const { data } = await client.post(`/repos/${owner}/${repo}/deployments`, payload)
+  return {
+    id: data && data.id,
+    sha: data && data.sha,
+    ref: data && data.ref,
+    task: data && data.task,
+    environment: data && data.environment,
+    description: (data && data.description) || '',
+    creator: data && data.creator && data.creator.login,
+    createdAt: data && data.created_at,
+    url: data && data.url,
+    statusesUrl: data && data.statuses_url,
+  }
+}
+
+/** List deployment statuses. */
+export async function listDeploymentStatuses(client, { owner, repo, deploymentId, limit = 30 } = {}) {
+  ensureRepo({ owner, repo })
+  if (!deploymentId) throw new Error('deploymentId is required')
+  const perPage = Math.max(1, Math.min(Number(limit) || 30, 100))
+  const { data } = await client.get(`/repos/${owner}/${repo}/deployments/${deploymentId}/statuses`, {
+    query: { per_page: perPage },
+  })
+  const statuses = Array.isArray(data) ? data : []
+  return {
+    deploymentId,
+    statuses: statuses.map((s) => ({
+      id: s.id,
+      state: s.state,
+      description: s.description || '',
+      environmentUrl: s.environment_url || '',
+      logUrl: s.log_url || '',
+      creator: s.creator && s.creator.login,
+      createdAt: s.created_at,
+    })),
+  }
+}
+
+/** Create a status for an existing deployment. */
+export async function createDeploymentStatus(client, {
+  owner, repo, deploymentId, state, logUrl, description, environmentUrl, autoInactive = true,
+} = {}) {
+  ensureRepo({ owner, repo })
+  if (!deploymentId) throw new Error('deploymentId is required')
+  const validStates = ['error', 'failure', 'in_progress', 'queued', 'pending', 'success']
+  if (!state || !validStates.includes(state)) {
+    throw new Error(`state must be one of: ${validStates.join(', ')}`)
+  }
+
+  const payload = {
+    state,
+    auto_inactive: Boolean(autoInactive),
+  }
+  if (logUrl) payload.log_url = String(logUrl)
+  if (description) payload.description = String(description)
+  if (environmentUrl) payload.environment_url = String(environmentUrl)
+
+  const { data } = await client.post(`/repos/${owner}/${repo}/deployments/${deploymentId}/statuses`, payload)
+  return {
+    id: data && data.id,
+    deploymentId,
+    state: data && data.state,
+    description: (data && data.description) || '',
+    environmentUrl: (data && data.environment_url) || '',
+    logUrl: (data && data.log_url) || '',
+    createdAt: data && data.created_at,
+  }
+}

package/lib/tools/register-ops.js

@@ -1,4 +1,6 @@
 import { matrixStatus } from './matrix.js'
+import { listEnvironments, listDeployments, createDeployment, createDeploymentStatus } from './deployments.js'
+import { simulateWebhook } from './webhook-sim.js'
 // Workflow-run and repository-settings tool registrations.
 //
 // Reads are free; writes follow the plugin's model — an explicit confirm flag for the
@@ -367,4 +369,133 @@ export function registerOpsTools({ tool, asRepo, client, liveConfig }) {
       })
     },
   )
+
+  // ------------------------------------------------------------------------ environments & deployments (#122)
+
+  tool(
+    'gh_environment_list',
+    'List deployment environments configured for a repository, including protection rules and wait timers. Read-only.',
+    repoParams({
+      limit: { type: 'number', description: 'Maximum environments to return (default 30, max 100).' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return listEnvironments(await client(), { owner, repo, limit: args.limit })
+    },
+  )
+
+  tool(
+    'gh_deployment_list',
+    'List deployments for a repository with optional filtering by environment, ref, sha or task. Read-only.',
+    repoParams({
+      environment: { type: 'string', description: 'Filter by environment name (e.g. "production", "staging").' },
+      ref: { type: 'string', description: 'Filter by git ref or branch name.' },
+      sha: { type: 'string', description: 'Filter by commit SHA.' },
+      task: { type: 'string', description: 'Filter by task name (e.g. "deploy").' },
+      limit: { type: 'number', description: 'Maximum deployments to return (default 30, max 100).' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return listDeployments(await client(), {
+        owner,
+        repo,
+        environment: args.environment,
+        ref: args.ref,
+        sha: args.sha,
+        task: args.task,
+        limit: args.limit,
+      })
+    },
+  )
+
+  tool(
+    'gh_deployment_create',
+    'Create a new deployment for a ref (branch, tag or commit SHA).',
+    repoParams({
+      ref: { type: 'string', description: 'Git ref to deploy (branch name, tag, or commit SHA). Required.' },
+      environment: { type: 'string', description: 'Target environment name (default "production").' },
+      task: { type: 'string', description: 'Deployment task (default "deploy").' },
+      description: { type: 'string', description: 'Optional human-readable description.' },
+      autoMerge: { type: 'boolean', description: 'Whether to auto-merge default branch into ref (default false).' },
+      requiredContexts: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Status check contexts required to pass before deploying (default empty []).'
+      },
+      productionEnvironment: { type: 'boolean', description: 'Whether this environment is a production environment.' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return createDeployment(await client(), {
+        owner,
+        repo,
+        ref: args.ref,
+        environment: args.environment || 'production',
+        task: args.task || 'deploy',
+        description: args.description,
+        autoMerge: Boolean(args.autoMerge),
+        requiredContexts: args.requiredContexts || [],
+        productionEnvironment: args.productionEnvironment,
+      })
+    },
+  )
+
+  tool(
+    'gh_deployment_status_create',
+    'Create a status for an existing deployment (e.g. "in_progress", "success", "failure", "error").',
+    repoParams({
+      deploymentId: { type: 'number', description: 'The numeric ID of the deployment. Required.' },
+      state: {
+        type: 'string',
+        description: 'State of the deployment: "error", "failure", "in_progress", "queued", "pending", "success". Required.'
+      },
+      description: { type: 'string', description: 'Short description of the status.' },
+      logUrl: { type: 'string', description: 'URL of the deployment logs.' },
+      environmentUrl: { type: 'string', description: 'URL for accessing the deployed environment.' },
+      autoInactive: { type: 'boolean', description: 'Add inactive state to previous non-transient, non-production deployments (default true).' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return createDeploymentStatus(await client(), {
+        owner,
+        repo,
+        deploymentId: args.deploymentId,
+        state: args.state,
+        description: args.description,
+        logUrl: args.logUrl,
+        environmentUrl: args.environmentUrl,
+        autoInactive: args.autoInactive !== false,
+      })
+    },
+  )
+
+  // ------------------------------------------------------------------------ webhook simulator (#125)
+
+  tool(
+    'gh_webhook_simulate',
+    'Simulate a canonical GitHub webhook event (issues, pull_request, workflow_run, release, deployment, push). Emits to local SSE bus and optional HTTP target.',
+    repoParams({
+      event: {
+        type: 'string',
+        description: 'Event name: "issues", "pull_request", "workflow_run", "release", "deployment", "deployment_status", "push". Default "issues".'
+      },
+      action: { type: 'string', description: 'Action for event (e.g. "opened", "closed", "completed", "published"). Default "opened".' },
+      data: { type: 'object', additionalProperties: true, description: 'Optional custom payload properties to merge into canonical payload.' },
+      broadcast: { type: 'boolean', description: 'Whether to broadcast to local SSE event manager (default true).' },
+      targetUrl: { type: 'string', description: 'Optional webhook receiver endpoint URL to deliver payload via HTTP POST.' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return simulateWebhook({
+        owner,
+        repo,
+        event: args.event || 'issues',
+        action: args.action || 'opened',
+        data: args.data || {},
+        broadcast: args.broadcast !== false,
+        targetUrl: args.targetUrl,
+      })
+    },
+  )
+
 }

package/lib/tools/webhook-sim.js

@@ -0,0 +1,289 @@
+// Webhook Simulator and Local Event Emitter.
+// Generates canonical GitHub webhook payloads and emits to local SSE event bus.
+
+import { randomUUID } from 'node:crypto'
+import { getGlobalEventManager } from '../events.js'
+
+/** Canonical mock payload generator for GitHub webhook events. */
+export function buildCanonicalWebhookPayload({
+  event = 'issues',
+  action = 'opened',
+  owner = 'goodandready',
+  repo = 'dsh-github-ops',
+  data = {},
+} = {}) {
+  const deliveryId = randomUUID()
+  const timestamp = new Date().toISOString()
+  const repoFullName = `${owner}/${repo}`
+
+  const baseRepo = {
+    id: 123456789,
+    node_id: 'MDEwOlJlcG9zaXRvcnkxMjM0NTY3ODk=',
+    name: repo,
+    full_name: repoFullName,
+    private: false,
+    owner: {
+      login: owner,
+      id: 9876543,
+      avatar_url: 'https://avatars.githubusercontent.com/u/9876543?v=4',
+      html_url: `https://github.com/${owner}`,
+    },
+    html_url: `https://github.com/${repoFullName}`,
+    default_branch: 'main',
+  }
+
+  const sender = {
+    login: 'agent-antigravity',
+    id: 424242,
+    avatar_url: 'https://avatars.githubusercontent.com/u/424242?v=4',
+    html_url: 'https://github.com/agent-antigravity',
+  }
+
+  let eventPayload = {}
+
+  switch (event) {
+    case 'issues': {
+      eventPayload = {
+        action,
+        issue: {
+          id: 1001,
+          number: 42,
+          title: 'Example Issue from Webhook Simulator',
+          user: sender,
+          labels: [{ id: 1, name: 'bug', color: 'd73a4a' }],
+          state: action === 'closed' ? 'closed' : 'open',
+          comments: 0,
+          created_at: timestamp,
+          updated_at: timestamp,
+          body: 'This is a simulated issue payload for testing.',
+          html_url: `https://github.com/${repoFullName}/issues/42`,
+        },
+        repository: baseRepo,
+        sender,
+      }
+      break
+    }
+
+    case 'pull_request': {
+      eventPayload = {
+        action,
+        number: 101,
+        pull_request: {
+          id: 2002,
+          number: 101,
+          state: action === 'closed' ? 'closed' : 'open',
+          title: 'feat: simulated pull request payload',
+          user: sender,
+          body: 'Simulated PR body for local testing.',
+          created_at: timestamp,
+          updated_at: timestamp,
+          head: {
+            label: `${owner}:feature-sim`,
+            ref: 'feature-sim',
+            sha: '0123456789abcdef0123456789abcdef01234567',
+          },
+          base: {
+            label: `${owner}:main`,
+            ref: 'main',
+            sha: 'abcdef0123456789abcdef0123456789abcdef01',
+          },
+          merged: action === 'closed',
+          html_url: `https://github.com/${repoFullName}/pull/101`,
+        },
+        repository: baseRepo,
+        sender,
+      }
+      break
+    }
+
+    case 'workflow_run': {
+      eventPayload = {
+        action,
+        workflow_run: {
+          id: 3003,
+          name: 'CI Build & Test',
+          head_branch: 'main',
+          head_sha: '0123456789abcdef0123456789abcdef01234567',
+          status: action === 'completed' ? 'completed' : 'in_progress',
+          conclusion: action === 'completed' ? 'success' : null,
+          html_url: `https://github.com/${repoFullName}/actions/runs/3003`,
+          created_at: timestamp,
+          updated_at: timestamp,
+        },
+        repository: baseRepo,
+        sender,
+      }
+      break
+    }
+
+    case 'release': {
+      eventPayload = {
+        action,
+        release: {
+          id: 4004,
+          tag_name: 'v1.0.0',
+          name: 'Release v1.0.0',
+          draft: false,
+          prerelease: false,
+          created_at: timestamp,
+          published_at: timestamp,
+          html_url: `https://github.com/${repoFullName}/releases/tag/v1.0.0`,
+        },
+        repository: baseRepo,
+        sender,
+      }
+      break
+    }
+
+    case 'deployment': {
+      eventPayload = {
+        action,
+        deployment: {
+          id: 5005,
+          sha: '0123456789abcdef0123456789abcdef01234567',
+          ref: 'main',
+          task: 'deploy',
+          environment: 'production',
+          description: 'Deploying to production server',
+          created_at: timestamp,
+          updated_at: timestamp,
+        },
+        repository: baseRepo,
+        sender,
+      }
+      break
+    }
+
+    case 'deployment_status': {
+      eventPayload = {
+        action,
+        deployment_status: {
+          id: 6006,
+          state: 'success',
+          description: 'Deployment finished successfully',
+          target_url: 'https://goodandready.app',
+          created_at: timestamp,
+          updated_at: timestamp,
+        },
+        deployment: {
+          id: 5005,
+          environment: 'production',
+        },
+        repository: baseRepo,
+        sender,
+      }
+      break
+    }
+
+    case 'push': {
+      eventPayload = {
+        ref: 'refs/heads/main',
+        before: 'abcdef0123456789abcdef0123456789abcdef01',
+        after: '0123456789abcdef0123456789abcdef01234567',
+        commits: [
+          {
+            id: '0123456789abcdef0123456789abcdef01234567',
+            message: 'feat: add exciting new capability',
+            timestamp,
+            author: { name: 'Vadim', email: 'vadim@goodandready.app' },
+          },
+        ],
+        repository: baseRepo,
+        sender,
+      }
+      break
+    }
+
+    default: {
+      eventPayload = {
+        action,
+        event,
+        repository: baseRepo,
+        sender,
+      }
+    }
+  }
+
+  const payload = {
+    ...eventPayload,
+    ...data,
+  }
+
+  return { deliveryId, timestamp, payload }
+}
+
+/** Simulate a webhook event, emit to local SSE bus and optionally dispatch to HTTP receiver. */
+export async function simulateWebhook({
+  event = 'issues',
+  action = 'opened',
+  owner = 'goodandready',
+  repo = 'dsh-github-ops',
+  data = {},
+  broadcast = true,
+  targetUrl,
+  eventManager,
+  fetchFn = (typeof fetch !== 'undefined' ? fetch : null),
+} = {}) {
+  const { deliveryId, timestamp, payload } = buildCanonicalWebhookPayload({
+    event,
+    action,
+    owner,
+    repo,
+    data,
+  })
+
+  let broadcastCount = 0
+  if (broadcast) {
+    const mgr = eventManager || getGlobalEventManager()
+    if (mgr && typeof mgr.broadcast === 'function') {
+      mgr.broadcast('webhook', {
+        event,
+        action,
+        deliveryId,
+        timestamp,
+        payload,
+      })
+      mgr.broadcast(event, payload)
+      broadcastCount = mgr.clientCount || 1
+    }
+  }
+
+  let delivered = false
+  let targetStatus = null
+  let deliveryError = null
+
+  if (targetUrl && typeof fetchFn === 'function') {
+    try {
+      const res = await fetchFn(targetUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'User-Agent': 'GitHub-Hookshot/dsh-github-ops',
+          'X-GitHub-Event': event,
+          'X-GitHub-Delivery': deliveryId,
+          'X-GitHub-Hook-ID': '9999999',
+        },
+        body: JSON.stringify(payload),
+      })
+      delivered = Boolean(res && res.ok)
+      targetStatus = res ? res.status : null
+    } catch (err) {
+      deliveryError = String((err && err.message) || err)
+    }
+  }
+
+  return {
+    simulated: true,
+    event,
+    action,
+    deliveryId,
+    timestamp,
+    broadcasted: broadcast && broadcastCount > 0,
+    broadcastClients: broadcastCount,
+    targetUrl: targetUrl || null,
+    delivered,
+    targetStatus,
+    deliveryError,
+    payload,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-github-ops",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "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",