typeclaw 0.3.0 → 0.4.0

package/src/init/index.ts

@@ -3,6 +3,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { DEFAULT_GITHUB_EVENT_ALLOWLIST } from '@/channels/schema'
 import { config, configSchema, migrateLegacyConfigShape, type Config } from '@/config'
 import {
   DEFAULT_MODEL_REF,
@@ -18,6 +19,7 @@ import { createTui } from '@/tui'
 
 import { resolveBaseImageVersion, resolveScaffoldVersion } from './cli-version'
 import { buildDockerfile, DOCKERFILE } from './dockerfile'
+import { installGithubWebhooksEagerly, type EagerGithubWebhookInstallResult } from './github-webhook-install'
 import { buildGitignore, GITIGNORE_FILE } from './gitignore'
 import { HATCHING_PROMPT } from './hatching'
 import type { OAuthLoginRunner, OAuthLoginResult } from './oauth-login'
@@ -26,6 +28,9 @@ import { type InstallResult, type InstallRunner, runBunInstall } from './run-bun
 
 export { type InstallResult, type InstallRunner, runBunInstall } from './run-bun-install'
 
+export type { EagerGithubWebhookInstallResult } from './github-webhook-install'
+export { formatEagerGithubWebhookInstallResult, installGithubWebhooksEagerly } from './github-webhook-install'
+
 export { GITKEEP_FILE, PACKAGES_DIR } from './paths'
 
 const CONFIG_FILE = 'typeclaw.json'
@@ -51,6 +56,7 @@ export type InitStep =
   | 'oauth-login'
   | 'scaffold'
   | 'kakaotalk-auth'
+  | 'github-webhooks'
   | 'install'
   | 'dockerfile'
   | 'git'
@@ -58,6 +64,20 @@ export type InitStep =
 
 export type KakaotalkAuthResult = { ok: true } | { ok: false; reason: string }
 
+// Structured credential block for the GitHub channel adapter. Mirrors the
+// shape `runAddChannel({ channel: 'github', ... })` consumes so the wizard
+// can hand off without re-encoding the auth union or webhook fields.
+export type GithubInitCredentials = {
+  webhookSecret: string
+  tunnelProvider: GithubTunnelProvider
+  webhookUrl?: string
+  webhookPort?: number
+  repos: string[]
+  auth: { type: 'pat'; pat: string } | { type: 'app'; appId: number; privateKey: string; installationId?: number }
+}
+
+export type GithubTunnelProvider = 'cloudflare-quick' | 'external' | 'none'
+
 export type InitStepEvent =
   | { step: 'preflight'; phase: 'start' }
   | { step: 'preflight'; phase: 'done'; result: DockerAvailability }
@@ -67,6 +87,8 @@ export type InitStepEvent =
   | { step: 'scaffold'; phase: 'done' }
   | { step: 'kakaotalk-auth'; phase: 'start' }
   | { step: 'kakaotalk-auth'; phase: 'done'; result: KakaotalkAuthResult }
+  | { step: 'github-webhooks'; phase: 'start' }
+  | { step: 'github-webhooks'; phase: 'done'; result: EagerGithubWebhookInstallResult }
   | { step: 'install'; phase: 'start' }
   | { step: 'install'; phase: 'done'; result: InstallResult }
   | { step: 'dockerfile'; phase: 'start' }
@@ -131,7 +153,16 @@ export type InitOptions = {
   withSlack?: boolean
   withTelegram?: boolean
   withKakaotalk?: boolean
+  withGithub?: boolean
   runKakaotalkAuth?: KakaotalkAuthRunner
+  // Structured GitHub credentials collected by the wizard. When omitted and
+  // `withGithub` is true, the existing secrets.json#channels.github block is
+  // reused as-is (the wizard's "reuse existing credentials" path).
+  githubCredentials?: GithubInitCredentials
+  // Test seam for the eager-webhook-install path that fires after the github
+  // channel block is written. Production callers leave this undefined so the
+  // global `fetch` is used.
+  githubFetchImpl?: typeof fetch
   onProgress?: (event: InitStepEvent) => void
   runHatching?: HatchRunner
   runBunInstall?: InstallRunner
@@ -159,7 +190,10 @@ export async function runInit({
   withSlack,
   withTelegram,
   withKakaotalk = false,
+  withGithub = false,
   runKakaotalkAuth,
+  githubCredentials,
+  githubFetchImpl,
   onProgress,
   runHatching = defaultRunHatching,
   runBunInstall: installRunner = runBunInstall,
@@ -263,6 +297,30 @@ export async function runInit({
     }
   }
 
+  // Write the structured github channel block alongside scaffold's bot-token
+  // blocks. We do NOT delegate to runAddChannel because that's the `channel
+  // add` semantics — strict no-overwrite, throws when secrets.json#channels
+  // .github already exists. Init is a different contract: re-running it
+  // regenerates config from the wizard's current inputs (scaffold() already
+  // overwrites typeclaw.json wholesale on every run), so failing on an
+  // existing secret block here would brick the re-init recovery path the
+  // bot-token adapters all support.
+  if (withGithub && githubCredentials !== undefined) {
+    await writeGithubChannelForInit(cwd, githubCredentials)
+    if (githubCredentials.webhookUrl !== undefined && githubCredentials.repos.length > 0) {
+      emit({ step: 'github-webhooks', phase: 'start' })
+      const result = await installGithubWebhooksEagerly({
+        webhookUrl: githubCredentials.webhookUrl,
+        webhookSecret: githubCredentials.webhookSecret,
+        repos: githubCredentials.repos,
+        auth: githubCredentials.auth,
+        agentDir: cwd,
+        ...(githubFetchImpl !== undefined ? { fetchImpl: githubFetchImpl } : {}),
+      })
+      emit({ step: 'github-webhooks', phase: 'done', result })
+    }
+  }
+
   emit({ step: 'install', phase: 'start' })
   const install = await installRunner(cwd)
   emit({ step: 'install', phase: 'done', result: install })
@@ -280,6 +338,7 @@ export async function runInit({
   if (wantsSlack) configuredChannels.push('slack-bot')
   if (wantsTelegram) configuredChannels.push('telegram-bot')
   if (withKakaotalk) configuredChannels.push('kakaotalk')
+  if (withGithub) configuredChannels.push('github')
 
   emit({ step: 'hatching', phase: 'start' })
   const hatching = await runHatching({
@@ -721,7 +780,7 @@ export async function readExistingProviderApiKey(root: string, providerId: Known
 // kakaotalk` anyway — better to re-auth now during init.
 export async function hasExistingChannelSecrets(
   root: string,
-  channel: 'discord' | 'slack' | 'telegram' | 'kakaotalk',
+  channel: 'discord' | 'slack' | 'telegram' | 'kakaotalk' | 'github',
 ): Promise<boolean> {
   const channels = new SecretsBackend(join(root, 'secrets.json')).tryReadChannelsSync()
   if (channels === null) return false
@@ -732,6 +791,15 @@ export async function hasExistingChannelSecrets(
       return hasSecretField(channels['slack-bot'], 'botToken') && hasSecretField(channels['slack-bot'], 'appToken')
     case 'telegram':
       return hasSecretField(channels['telegram-bot'], 'token')
+    case 'github':
+      // GitHub credentials alone are not enough to scaffold a working
+      // channel: typeclaw.json#channels.github also needs webhookUrl and
+      // webhookPort, which only the user can supply. Always force a fresh
+      // prompt in the wizard so those fields end up in typeclaw.json. The
+      // existing `secrets.json#channels.github` (if any) is detected and
+      // surfaced as a hard error inside `runAddChannel` to prevent silent
+      // overwrites.
+      return false
     case 'kakaotalk': {
       const block = channels.kakaotalk
       if (!isObjectRecord(block)) return false
@@ -802,15 +870,21 @@ function ignoreExists(error: NodeJS.ErrnoException): void {
 // scaffold-test cases above demonstrates how easy it is to lose a single
 // behavior under a mode flag.
 
-export type ChannelKind = 'discord-bot' | 'slack-bot' | 'telegram-bot' | 'kakaotalk'
+export type ChannelKind = 'discord-bot' | 'slack-bot' | 'telegram-bot' | 'kakaotalk' | 'github'
 
 // Public adapter names match the typeclaw.json `channels.*` keys exactly.
 // The CLI takes these as the optional positional arg, the picker shows
 // these labels, and they're the keys we use to detect "already configured"
 // when reading typeclaw.json.
-export const CHANNEL_KINDS: ReadonlyArray<ChannelKind> = ['slack-bot', 'discord-bot', 'telegram-bot', 'kakaotalk']
+export const CHANNEL_KINDS: ReadonlyArray<ChannelKind> = [
+  'slack-bot',
+  'discord-bot',
+  'telegram-bot',
+  'kakaotalk',
+  'github',
+]
 
-export type AddChannelStep = 'kakaotalk-auth' | 'config' | 'secrets'
+export type AddChannelStep = 'kakaotalk-auth' | 'config' | 'secrets' | 'github-webhooks'
 
 export type AddChannelStepEvent =
   | { step: 'config'; phase: 'start' }
@@ -819,6 +893,8 @@ export type AddChannelStepEvent =
   | { step: 'kakaotalk-auth'; phase: 'done'; result: KakaotalkAuthResult }
   | { step: 'secrets'; phase: 'start' }
   | { step: 'secrets'; phase: 'done' }
+  | { step: 'github-webhooks'; phase: 'start' }
+  | { step: 'github-webhooks'; phase: 'done'; result: EagerGithubWebhookInstallResult }
 
 // Discriminated union per channel so the type system enforces "you must pass
 // the right credentials for the channel you're adding". The CLI builds these
@@ -831,6 +907,16 @@ export type AddChannelOptions = {
   | { channel: 'slack-bot'; slackBotToken: string; slackAppToken: string }
   | { channel: 'telegram-bot'; telegramBotToken: string }
   | { channel: 'kakaotalk'; runKakaotalkAuth: KakaotalkAuthRunner }
+  | {
+      channel: 'github'
+      webhookSecret: string
+      tunnelProvider: GithubTunnelProvider
+      webhookUrl?: string
+      webhookPort?: number
+      repos: string[]
+      auth: { type: 'pat'; pat: string } | { type: 'app'; appId: number; privateKey: string; installationId?: number }
+      fetchImpl?: typeof fetch
+    }
 )
 
 export async function runAddChannel(options: AddChannelOptions): Promise<void> {
@@ -852,7 +938,7 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   }
 
   emit({ step: 'config', phase: 'start' })
-  await mergeChannelIntoConfig(options.cwd, options.channel)
+  await mergeChannelIntoConfig(options.cwd, options)
   emit({ step: 'config', phase: 'done' })
 
   emit({ step: 'secrets', phase: 'start' })
@@ -860,8 +946,16 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   if (Object.keys(tokens).length > 0) {
     await appendChannelSecrets(options.cwd, options.channel, tokens)
   }
+  if (options.channel === 'github') {
+    await appendGithubSecrets(options.cwd, options)
+  }
   emit({ step: 'secrets', phase: 'done' })
 
+  if (options.channel === 'github') {
+    await appendGithubMatchRules(options.cwd, options.repos)
+    await maybeInstallGithubWebhooks(options, emit)
+  }
+
   // Commit the typeclaw.json change so the agent folder isn't silently
   // dirty after `typeclaw channel add`. Same `commitSystemFile` contract as
   // every other host-side rewrite: no-op outside a git repo, when Bun is
@@ -870,6 +964,30 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   await commitSystemFile(options.cwd, CONFIG_FILE, `channel: add ${options.channel}`)
 }
 
+// Eager webhook registration is best-effort: a failure here MUST NOT roll
+// back the typeclaw.json / secrets.json writes. The container-side adapter
+// re-runs registration on every start, so a missing PAT scope or a transient
+// 5xx today gets retried automatically on the next `typeclaw start`. We
+// surface the per-repo outcome as a structured event so the CLI can render
+// it, but we never throw.
+async function maybeInstallGithubWebhooks(
+  options: Extract<AddChannelOptions, { channel: 'github' }>,
+  emit: (event: AddChannelStepEvent) => void,
+): Promise<void> {
+  if (options.webhookUrl === undefined) return
+  if (options.repos.length === 0) return
+  emit({ step: 'github-webhooks', phase: 'start' })
+  const result = await installGithubWebhooksEagerly({
+    webhookUrl: options.webhookUrl,
+    webhookSecret: options.webhookSecret,
+    repos: options.repos,
+    auth: options.auth,
+    agentDir: options.cwd,
+    ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+  })
+  emit({ step: 'github-webhooks', phase: 'done', result })
+}
+
 function channelSecretsFromOptions(options: AddChannelOptions): ChannelSecrets {
   switch (options.channel) {
     case 'discord-bot':
@@ -882,6 +1000,9 @@ function channelSecretsFromOptions(options: AddChannelOptions): ChannelSecrets {
       // KakaoTalk auth writes its structured multi-account block directly to
       // secrets.json#channels.kakaotalk before config mutation.
       return {}
+    case 'github':
+      // GitHub stores a structured PAT + webhook secret block directly.
+      return {}
   }
 }
 
@@ -908,7 +1029,7 @@ export async function readConfiguredChannels(cwd: string): Promise<Set<ChannelKi
   return present
 }
 
-async function mergeChannelIntoConfig(cwd: string, channel: ChannelKind): Promise<void> {
+async function mergeChannelIntoConfig(cwd: string, options: AddChannelOptions): Promise<void> {
   const path = join(cwd, CONFIG_FILE)
   let parsed: Record<string, unknown>
   try {
@@ -928,19 +1049,152 @@ async function mergeChannelIntoConfig(cwd: string, channel: ChannelKind): Promis
       ? (parsed.channels as Record<string, unknown>)
       : {}
 
-  if (channel in existingChannels) {
+  if (options.channel in existingChannels) {
     // Defense in depth — the CLI already filters configured channels out of
     // the picker and rejects them as the positional arg. Hitting this branch
     // means a programmatic caller passed a duplicate; better to fail loudly
     // than silently overwrite the user's existing config.
-    throw new Error(`Channel "${channel}" is already configured in ${CONFIG_FILE}.`)
+    throw new Error(`Channel "${options.channel}" is already configured in ${CONFIG_FILE}.`)
   }
 
+  const nextChannelConfig = options.channel === 'github' ? buildGithubChannelConfig(options) : {}
+
   parsed.channels = {
     ...existingChannels,
-    [channel]: {},
+    [options.channel]: nextChannelConfig,
+  }
+
+  if (options.channel === 'github') mergeGithubTunnelConfig(parsed, options)
+
+  await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
+}
+
+function buildGithubChannelConfig(options: Extract<AddChannelOptions, { channel: 'github' }>): Record<string, unknown> {
+  return {
+    ...(options.webhookUrl !== undefined ? { webhookUrl: options.webhookUrl } : {}),
+    webhookPort: options.webhookPort ?? 8975,
+    eventAllowlist: [...DEFAULT_GITHUB_EVENT_ALLOWLIST],
+    repos: options.repos,
+  }
+}
+
+function mergeGithubTunnelConfig(
+  parsed: Record<string, unknown>,
+  options: Extract<AddChannelOptions, { channel: 'github' }>,
+): void {
+  if (options.tunnelProvider === 'none') return
+  if (options.tunnelProvider === 'external' && options.webhookUrl === undefined) {
+    throw new Error('GitHub external tunnel requires webhookUrl')
+  }
+
+  const existingTunnels = Array.isArray(parsed.tunnels) ? parsed.tunnels : []
+  const tunnel =
+    options.tunnelProvider === 'external'
+      ? {
+          name: 'github-webhook',
+          provider: 'external',
+          externalUrl: options.webhookUrl,
+          for: { kind: 'channel', name: 'github' },
+        }
+      : {
+          name: 'github-webhook',
+          provider: 'cloudflare-quick',
+          for: { kind: 'channel', name: 'github' },
+        }
+  parsed.tunnels = [...existingTunnels, tunnel]
+
+  if (options.tunnelProvider === 'cloudflare-quick') {
+    const docker = isObjectRecord(parsed.docker) ? { ...parsed.docker } : {}
+    const file = isObjectRecord(docker.file) ? { ...docker.file } : {}
+    file.cloudflared = true
+    docker.file = file
+    parsed.docker = docker
   }
+}
+
+// Init-side counterpart of runAddChannel's github branch. Same three writes
+// (typeclaw.json#channels.github, secrets.json#channels.github, roles.member
+// .match[]) but with overwrite semantics on the secrets/config side so a
+// re-run of `typeclaw init` after a partial failure works the same way it
+// does for the bot-token adapters. The match-rule writer is reused as-is
+// because its set-union is already idempotent.
+async function writeGithubChannelForInit(cwd: string, credentials: GithubInitCredentials): Promise<void> {
+  const configPath = join(cwd, CONFIG_FILE)
+  const parsed = JSON.parse(await readFile(configPath, 'utf8')) as Record<string, unknown>
+  const existingChannels = isObjectRecord(parsed.channels) ? { ...parsed.channels } : {}
+  existingChannels.github = {
+    ...(credentials.webhookUrl !== undefined ? { webhookUrl: credentials.webhookUrl } : {}),
+    webhookPort: credentials.webhookPort ?? 8975,
+    eventAllowlist: [...DEFAULT_GITHUB_EVENT_ALLOWLIST],
+    repos: credentials.repos,
+  }
+  parsed.channels = existingChannels
+  mergeGithubTunnelConfig(parsed, { channel: 'github', ...credentials, cwd })
+  await writeFile(configPath, `${JSON.stringify(parsed, null, 2)}\n`)
+
+  const backend = new SecretsBackend(join(cwd, 'secrets.json'))
+  const channels: Record<string, unknown> = backend.readChannelsSync()
+  channels.github = {
+    auth:
+      credentials.auth.type === 'pat'
+        ? { type: 'pat', token: { value: credentials.auth.pat } satisfies Secret }
+        : {
+            type: 'app',
+            appId: credentials.auth.appId,
+            privateKey: { value: credentials.auth.privateKey } satisfies Secret,
+            ...(credentials.auth.installationId !== undefined
+              ? { installationId: credentials.auth.installationId }
+              : {}),
+          },
+    webhookSecret: { value: credentials.webhookSecret } satisfies Secret,
+  }
+  backend.writeChannelsSync(channels as Channels)
 
+  await appendGithubMatchRules(cwd, credentials.repos)
+}
+
+async function appendGithubSecrets(
+  cwd: string,
+  options: Extract<AddChannelOptions, { channel: 'github' }>,
+): Promise<void> {
+  if (!existsSync(join(cwd, CONFIG_FILE))) {
+    throw new Error(
+      `${CONFIG_FILE} not found at ${cwd}. Run \`typeclaw init\` before adding channels, or run this command from inside an agent folder.`,
+    )
+  }
+  const backend = new SecretsBackend(join(cwd, 'secrets.json'))
+  const channels: Record<string, unknown> = backend.readChannelsSync()
+  if (channels.github !== undefined) {
+    throw new Error(
+      'github is already set in secrets.json. Remove it before re-adding the channel, or edit it by hand.',
+    )
+  }
+  channels.github = {
+    auth:
+      options.auth.type === 'pat'
+        ? { type: 'pat', token: { value: options.auth.pat } satisfies Secret }
+        : {
+            type: 'app',
+            appId: options.auth.appId,
+            privateKey: { value: options.auth.privateKey } satisfies Secret,
+            ...(options.auth.installationId !== undefined ? { installationId: options.auth.installationId } : {}),
+          },
+    webhookSecret: { value: options.webhookSecret } satisfies Secret,
+  }
+  backend.writeChannelsSync(channels as Channels)
+}
+
+async function appendGithubMatchRules(cwd: string, repos: readonly string[]): Promise<void> {
+  const path = join(cwd, CONFIG_FILE)
+  const parsed = JSON.parse(await readFile(path, 'utf8')) as Record<string, unknown>
+  const roles = isObjectRecord(parsed.roles) ? { ...parsed.roles } : {}
+  const member = isObjectRecord(roles.member) ? { ...roles.member } : {}
+  const existing = Array.isArray(member.match) ? member.match.filter((v): v is string => typeof v === 'string') : []
+  const merged = new Set(existing)
+  for (const repo of repos) merged.add(`github:${repo}`)
+  member.match = Array.from(merged)
+  roles.member = member
+  parsed.roles = roles
   await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
 }
 
@@ -976,3 +1230,245 @@ async function appendChannelSecrets(cwd: string, channel: ChannelKind, tokens: C
   channels[channel] = slot
   backend.writeChannelsSync(channels as Channels)
 }
+
+// ----------------------------------------------------------------------------
+// `typeclaw channel set`
+//
+// Rotate credentials of an already-configured channel. Symmetric with
+// `typeclaw provider set` (see `setProvider` in src/config/providers-mutation.ts):
+// `add` is "add for the first time, refuse if already present", `set` is
+// "rotate the value, refuse if NOT yet present". Two separate verbs keep the
+// "add by mistake" footgun and the "rotate by mistake" footgun on opposite
+// sides of the CLI namespace.
+//
+// Per the env-wins / file-never-auto-mutated rule in AGENTS.md#secrets, these
+// helpers only touch the fields the user explicitly asked to rotate. Any
+// untouched field — including a sibling field bound to a custom env var —
+// keeps its existing Secret envelope verbatim.
+//
+// Kakaotalk has its own auth flow (encryption envelope + device_uuid + phone
+// passcode) and is rotated via `typeclaw channel reauth kakaotalk`, NOT via
+// these helpers. Trying to set('kakaotalk') would bypass the encryption
+// bridge and corrupt the per-account block; the CLI layer rejects it before
+// reaching here.
+
+export type SetChannelTokensResult = { ok: true } | { ok: false; reason: string }
+
+type BotTokenAdapter = 'discord-bot' | 'slack-bot' | 'telegram-bot'
+
+// Required credential fields per adapter. Used post-merge to refuse a
+// rotation that would leave the adapter half-configured — e.g. rotating
+// only `botToken` when the on-disk slot was `{}` would silently leave
+// `appToken` missing and the Slack adapter would fail to start. Listing
+// the contract explicitly here keeps it close to the writer.
+const REQUIRED_CHANNEL_FIELDS: Record<BotTokenAdapter, readonly string[]> = {
+  'discord-bot': ['token'],
+  'slack-bot': ['botToken', 'appToken'],
+  'telegram-bot': ['token'],
+}
+
+// Preserve a user-authored `{ env: 'CUSTOM_NAME' }` rebinding when rotating
+// the value behind it. Mirrors `buildSecret` in providers-mutation.ts for
+// the case where the prior credential had an explicit env-name binding —
+// the rotated value is written as `{ value, env }` so env-wins still works
+// at runtime. Without this, every `channel set` would silently strip the
+// rebinding and `process.env[<custom>]` would no longer override.
+function rotatedSecret(previous: unknown, value: string): Secret {
+  if (isObjectRecord(previous)) {
+    const env = (previous as { env?: unknown }).env
+    if (typeof env === 'string' && env.length > 0) {
+      return { value, env }
+    }
+  }
+  return { value }
+}
+
+// Rotate one or more credential fields on an already-configured bot-token
+// adapter (discord-bot, slack-bot, telegram-bot). Refuses when the adapter
+// has no existing entry in secrets.json — callers must use `runAddChannel`
+// for first-time setup, so a typo in the adapter name can't silently create
+// a half-configured channel. Also refuses when the rotation would leave any
+// required field for the adapter unset (e.g. rotating only Slack's
+// `botToken` when `appToken` is missing from disk).
+export async function setChannelSecrets(
+  cwd: string,
+  channel: BotTokenAdapter,
+  tokens: ChannelSecrets,
+): Promise<SetChannelTokensResult> {
+  if (!existsSync(join(cwd, CONFIG_FILE))) {
+    return {
+      ok: false,
+      reason: `${CONFIG_FILE} not found at ${cwd}. Run \`typeclaw init\` before rotating channel credentials, or run this command from inside an agent folder.`,
+    }
+  }
+
+  if (Object.keys(tokens).length === 0) return { ok: true }
+
+  return await runChannelMutation(cwd, async (current) => {
+    const existingSlot = current[channel]
+    if (!isObjectRecord(existingSlot)) {
+      return {
+        result: {
+          ok: false,
+          reason: `${channel} is not configured in secrets.json. Run \`typeclaw channel add ${channel}\` first.`,
+        },
+      }
+    }
+    const slot: Record<string, unknown> = { ...existingSlot }
+    for (const [k, v] of Object.entries(tokens)) {
+      slot[k] = rotatedSecret(existingSlot[k], v)
+    }
+    const missing = REQUIRED_CHANNEL_FIELDS[channel].filter((field) => !isSecretFieldSet(slot[field]))
+    if (missing.length > 0) {
+      return {
+        result: {
+          ok: false,
+          reason: `${channel} would be left half-configured after this rotation: missing required field(s) ${missing.join(', ')} in secrets.json. Run \`typeclaw channel add ${channel}\` to re-add the channel, or fix secrets.json by hand.`,
+        },
+      }
+    }
+    const next: Record<string, unknown> = { ...current, [channel]: slot }
+    return { result: { ok: true }, next }
+  })
+}
+
+// Discriminated union of what GitHub credentials the user wants to rotate.
+// The three secrets (PAT/private-key, webhook secret) rotate independently,
+// so the CLI lets the user pick which one(s) to touch in a single call.
+// `auth.type` must match the existing on-disk auth type — flipping between
+// PAT and App auth is a structural change, not a credential rotation, and
+// belongs in a future `channel migrate-auth` or hand-edit of secrets.json.
+export type GithubCredentialPatch = {
+  webhookSecret?: string
+  auth?: { type: 'pat'; pat: string } | { type: 'app'; privateKey: string; appId?: number; installationId?: number }
+}
+
+// Rotate one or more credential fields on an already-configured GitHub
+// channel. Like setChannelSecrets, refuses when secrets.json has no
+// existing github entry. Additionally refuses when the requested auth.type
+// doesn't match the on-disk type — see `GithubCredentialPatch` above.
+export async function setGithubSecrets(cwd: string, patch: GithubCredentialPatch): Promise<SetChannelTokensResult> {
+  if (!existsSync(join(cwd, CONFIG_FILE))) {
+    return {
+      ok: false,
+      reason: `${CONFIG_FILE} not found at ${cwd}. Run \`typeclaw init\` before rotating channel credentials, or run this command from inside an agent folder.`,
+    }
+  }
+
+  if (patch.webhookSecret === undefined && patch.auth === undefined) return { ok: true }
+
+  return await runChannelMutation(cwd, async (current) => {
+    const existing = current.github
+    if (!isObjectRecord(existing)) {
+      return {
+        result: {
+          ok: false,
+          reason: 'github is not configured in secrets.json. Run `typeclaw channel add github` first.',
+        },
+      }
+    }
+    const block: Record<string, unknown> = { ...existing }
+
+    if (patch.auth !== undefined) {
+      const existingAuth = block.auth
+      const existingAuthType = readGithubAuthTypeFromObject(existingAuth)
+      if (existingAuthType !== patch.auth.type) {
+        return {
+          result: {
+            ok: false,
+            reason: `github auth type mismatch: secrets.json currently uses "${existingAuthType ?? 'unknown'}" auth, but you tried to rotate a "${patch.auth.type}" credential. Edit secrets.json by hand to migrate between PAT and App auth.`,
+          },
+        }
+      }
+      if (patch.auth.type === 'pat') {
+        const previousToken = isObjectRecord(existingAuth) ? (existingAuth as { token?: unknown }).token : undefined
+        block.auth = { type: 'pat', token: rotatedSecret(previousToken, patch.auth.pat) }
+      } else {
+        const existingApp = isObjectRecord(existingAuth) ? (existingAuth as Record<string, unknown>) : {}
+        const appId = patch.auth.appId ?? (existingApp.appId as number | undefined)
+        const installationId = patch.auth.installationId ?? (existingApp.installationId as number | undefined)
+        if (typeof appId !== 'number') {
+          return {
+            result: {
+              ok: false,
+              reason:
+                'github App auth requires appId, but it is missing from secrets.json. Re-run `typeclaw channel add github` to re-establish the App auth block.',
+            },
+          }
+        }
+        block.auth = {
+          type: 'app',
+          appId,
+          privateKey: rotatedSecret(existingApp.privateKey, patch.auth.privateKey),
+          ...(installationId !== undefined ? { installationId } : {}),
+        }
+      }
+    }
+
+    if (patch.webhookSecret !== undefined) {
+      block.webhookSecret = rotatedSecret(block.webhookSecret, patch.webhookSecret)
+    }
+
+    const next: Record<string, unknown> = { ...current, github: block }
+    return { result: { ok: true }, next }
+  })
+}
+
+// Wrapper that converts a thrown schema-validation error (from a hand-edited
+// malformed secrets.json) into a structured `{ ok: false }` result, so CLI
+// callers can render a clean message instead of a stack trace. The
+// `updateChannelsAsync` path itself is atomic; this wrapper only catches the
+// READ stage (envelope parse) failures.
+async function runChannelMutation(
+  cwd: string,
+  fn: (current: Record<string, unknown>) => Promise<{ result: SetChannelTokensResult; next?: Record<string, unknown> }>,
+): Promise<SetChannelTokensResult> {
+  const backend = new SecretsBackend(join(cwd, 'secrets.json'))
+  try {
+    return await backend.updateChannelsAsync<SetChannelTokensResult>(fn)
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `secrets.json is malformed: ${err instanceof Error ? err.message : String(err)}. Fix it by hand, then retry.`,
+    }
+  }
+}
+
+function isSecretFieldSet(slot: unknown): boolean {
+  if (typeof slot === 'string') return slot.length > 0
+  if (isObjectRecord(slot)) {
+    const value = (slot as { value?: unknown }).value
+    if (typeof value === 'string' && value.length > 0) return true
+    const env = (slot as { env?: unknown }).env
+    if (typeof env === 'string' && env.length > 0) return true
+  }
+  return false
+}
+
+function readGithubAuthTypeFromObject(auth: unknown): 'pat' | 'app' | undefined {
+  if (!isObjectRecord(auth)) return undefined
+  const type = (auth as { type?: unknown }).type
+  if (type === 'pat' || type === 'app') return type
+  return undefined
+}
+
+// Lightweight read-only probe used by the `channel set` CLI to drive its
+// "which secret do you want to rotate?" menu for GitHub. Returns the
+// current auth type ('pat' | 'app') so the prompt knows whether to ask for
+// a PAT or an App private key, without forcing the user to re-select auth
+// type when they're rotating a credential of the same kind. Returns `null`
+// when secrets.json is missing, malformed, or has no github entry — the
+// CLI surfaces that as a single user-facing "fix the file by hand" error.
+export function readGithubAuthType(cwd: string): 'pat' | 'app' | null {
+  let channels: Channels | null
+  try {
+    channels = new SecretsBackend(join(cwd, 'secrets.json')).tryReadChannelsSync()
+  } catch {
+    return null
+  }
+  if (channels === null) return null
+  const github = channels.github
+  if (!isObjectRecord(github)) return null
+  const auth = (github as { auth?: unknown }).auth
+  return readGithubAuthTypeFromObject(auth) ?? null
+}