@ericsanchezok/synergy-github-agenda 0.0.0-stage → 3.1.0

package/src/preflight.ts

@@ -0,0 +1,53 @@
+import { GitHubProvider } from "@ericsanchezok/synergy-harness/provider/github"
+import { GithubWatchPolicy } from "@ericsanchezok/synergy-agenda/agenda/github-watch-policy"
+
+/**
+ * Creation-time gate for agenda items with GitHub triggers.
+ *
+ * A GitHub watch without a resolvable credential polls silently forever and
+ * never fires — and an `agenda_watch` with `onGithub` is a continuation
+ * blocker, so the origin session would wait indefinitely with no feedback.
+ * Reject at creation with concrete connection steps instead of persisting an
+ * item that can never fire. Token validity is deliberately not checked here
+ * (that needs a live API call); an invalid token surfaces through the existing
+ * consecutive-failure auto-pause in the poll loop.
+ */
+export namespace GithubWatchPreflight {
+  export interface Rejection {
+    title: string
+    output: string
+    metadata: Record<string, any>
+  }
+
+  export async function check(toolName: string): Promise<Rejection | undefined> {
+    const watch = await GithubWatchPolicy.read()
+    if (watch?.enabled === false) {
+      return {
+        title: `${toolName} rejected`,
+        output: [
+          `GitHub triggers are disabled (github.watch.enabled=false in config).`,
+          ``,
+          `Ask the user to enable them in Settings → GitHub → "Allow GitHub agenda triggers", or set github.watch.enabled=true in 115-github.jsonc.`,
+        ].join("\n"),
+        metadata: { blocked: true, reason: "github_watch_disabled" } as Record<string, any>,
+      }
+    }
+    const resolved = await GitHubProvider.resolveToken()
+    if (!resolved?.token) {
+      return {
+        title: `${toolName} rejected`,
+        output: [
+          `No connected GitHub credential — this GitHub watch would poll silently forever and never fire.`,
+          ``,
+          `Connect one first, then retry this exact call:`,
+          `1. Ask the user to connect GitHub in Settings → GitHub (device login, import gh auth token, or paste a token).`,
+          `2. Or ensure GH_TOKEN / GITHUB_TOKEN is exported in the Synergy server environment.`,
+          ``,
+          `Do not substitute a timed delay loop that shell-checks GitHub — that is the approximation this connection replaces. If the user declines to connect, tell them GitHub watches need a credential.`,
+        ].join("\n"),
+        metadata: { blocked: true, reason: "github_credential_missing" } as Record<string, any>,
+      }
+    }
+    return undefined
+  }
+}

package/src/register.ts

@@ -0,0 +1,18 @@
+import watchDescription from "./watch-description.txt"
+import scheduleDescription from "./schedule-description.txt"
+import { AgendaGithubSource } from "@ericsanchezok/synergy-agenda/agenda/github-source"
+import { AgendaGithubTrigger } from "./github-trigger"
+import { GithubWatchPreflight } from "./preflight"
+import { GithubWatchPolicy } from "@ericsanchezok/synergy-agenda/agenda/github-watch-policy"
+import { readConfig } from "@ericsanchezok/synergy-github/config-schema"
+export function registerBridge() {
+  AgendaGithubSource.registerSource({
+    ...AgendaGithubTrigger,
+    descriptions: { watch: watchDescription, schedule: scheduleDescription },
+    check: GithubWatchPreflight.check,
+  })
+  GithubWatchPolicy.register(async () => {
+    const watch = (await readConfig()).github?.watch
+    return { enabled: watch?.enabled !== false, defaultIntervalMs: watch?.defaultIntervalMs }
+  })
+}

package/src/schedule-description.txt

@@ -0,0 +1,3 @@
+- `{type:"github", resource:"pr"|"issue"|"workflow"|"check", repository:"owner/repo", number?, ref?, interval?, states?}` — fires when the watched GitHub resource changes state, polled on an interval (default 5m). `number` targets one PR/issue or workflow run id; `ref` targets a branch/tag/commit for workflow/check watches; `states` filters transitions (e.g. ["merged"], ["failure"]). Requires a connected GitHub credential — creation is rejected with connection steps when none resolves; do not substitute a generic `every` interval that shell-checks GitHub.
+
+For "wait until a GitHub resource reaches a state" requests, the github trigger IS the right schedule — prefer it over a generic `every` interval plus manual shell checks.

package/src/watch-description.txt

@@ -0,0 +1,5 @@
+Pass exactly one of `delay`, `onSessionEnd`, or `onGithub`.
+
+**Prefer managed GitHub watches over repeated shell polling.** When the condition you are waiting for is a GitHub event (PR merged/closed, issue closed, workflow or check run finishing), pass `onGithub: {resource, repository, number?, ref?, states?}` instead of a `delay` plus repeated shell checks. The trigger polls the GitHub REST API with the connected credential on an interval (default 5 minutes, minimum 30 seconds) and wakes you when it next observes a matching state. Intermediate transitions between polls may be missed. `resource` is "pr" | "issue" | "workflow" | "check"; `repository` is owner/repo; `number` targets one PR/issue or workflow run id (omit for the repository's recent ites); `ref` targets a branch/tag/commit for workflow/check watches; `states` filters which new state should wake you (e.g. ["merged"], ["failure"], ["completed"]). Requires a connected GitHub credential — without one the watch is rejected with connection steps; ask the user to connect GitHub in Settings → GitHub rather than substituting timed shell polling.
+
+Repo-wide watches (no `number`) fire for transitions of the 10 most recently updated items. A states-filtered watch reports new items first observed already in a targeted state; an unfiltered watch baselines first observations silently, so an item created and merged entirely between two polls is not reported. Point watches (`number`) always see transitions.

package/src/worker.ts

@@ -0,0 +1,6 @@
+import { version } from "../package.json" with { type: "json" }
+import { githubAgenda } from "./component"
+export const metadata = { id: "github-agenda", version, apiVersion: 1 }
+export function registerWorker() {
+  githubAgenda().register()
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.