neondeck 1.0.0-beta.10

package/src/modules/watches/actions.ts

@@ -0,0 +1,115 @@
+import { defineAction } from '@flue/runtime';
+import * as v from 'valibot';
+import {
+  addPrWatch,
+  addRefWatch,
+  listPrWatches,
+  listRefWatches,
+  refreshPrWatch,
+  refreshRefWatch,
+  removePrWatch,
+  setPrWatchPolling,
+} from './service';
+import {
+  watchActionOutputSchema,
+  watchPrAddInputSchema,
+  watchPrPollingInputSchema,
+  watchPrRefreshInputSchema,
+  watchPrRemoveInputSchema,
+  watchRefAddInputSchema,
+  watchRefRefreshInputSchema,
+} from './schemas';
+
+export const watchPrAddAction = defineAction({
+  name: 'neondeck_watch_pr_add',
+  description:
+    'Create a persistent PR watch from a GitHub PR URL, owner/repo#number, repo#number, or #number reference.',
+  input: watchPrAddInputSchema,
+  output: watchActionOutputSchema,
+  async run({ input }) {
+    return addPrWatch(input);
+  },
+});
+
+export const watchPrListAction = defineAction({
+  name: 'neondeck_watch_pr_list',
+  description: 'List persistent Neondeck PR watches.',
+  input: v.object({}),
+  output: watchActionOutputSchema,
+  async run() {
+    return listPrWatches();
+  },
+});
+
+export const watchPrRemoveAction = defineAction({
+  name: 'neondeck_watch_pr_remove',
+  description: 'Remove a persistent PR watch after explicit confirmation.',
+  input: watchPrRemoveInputSchema,
+  output: watchActionOutputSchema,
+  async run({ input }) {
+    return removePrWatch(input);
+  },
+});
+
+export const watchPrPollingAction = defineAction({
+  name: 'neondeck_watch_pr_polling',
+  description: 'Pause or resume scheduler polling for a persistent PR watch.',
+  input: watchPrPollingInputSchema,
+  output: watchActionOutputSchema,
+  async run({ input }) {
+    return setPrWatchPolling(input);
+  },
+});
+
+export const watchPrRefreshAction = defineAction({
+  name: 'neondeck_watch_pr_refresh',
+  description:
+    'Refresh one persistent PR watch and return silent when no meaningful state changed.',
+  input: watchPrRefreshInputSchema,
+  output: watchActionOutputSchema,
+  async run({ input }) {
+    return refreshPrWatch(input);
+  },
+});
+
+export const watchRefAddAction = defineAction({
+  name: 'neondeck_watch_ref_add',
+  description:
+    'Create a persistent branch or commit ref watch from repo/ref fields, owner/repo@ref, repo@ref, or a GitHub tree/commit URL.',
+  input: watchRefAddInputSchema,
+  output: watchActionOutputSchema,
+  async run({ input }) {
+    return addRefWatch(input);
+  },
+});
+
+export const watchRefListAction = defineAction({
+  name: 'neondeck_watch_ref_list',
+  description: 'List persistent Neondeck branch and commit ref watches.',
+  input: v.object({}),
+  output: watchActionOutputSchema,
+  async run() {
+    return listRefWatches();
+  },
+});
+
+export const watchRefRefreshAction = defineAction({
+  name: 'neondeck_watch_ref_refresh',
+  description:
+    'Refresh one persistent branch or commit ref watch and return silent when no meaningful state changed.',
+  input: watchRefRefreshInputSchema,
+  output: watchActionOutputSchema,
+  async run({ input }) {
+    return refreshRefWatch(input);
+  },
+});
+
+export const neondeckWatchActions = [
+  watchPrAddAction,
+  watchPrRemoveAction,
+  watchPrPollingAction,
+  watchPrRefreshAction,
+  watchRefAddAction,
+  watchRefListAction,
+  watchRefRefreshAction,
+];

package/src/modules/watches/index.ts

@@ -0,0 +1,6 @@
+export * from './actions';
+export * from './polling';
+export * from './references';
+export * from './schemas';
+export * from './service';
+export * from './store';

package/src/modules/watches/polling.ts

@@ -0,0 +1,245 @@
+import type { GitHubCheckSummary, GitHubPullRequestDetail } from '../github';
+import { fetchCheckSummary, fetchPullRequestDetail } from '../github';
+import { readRepoRegistrySnapshot } from '../repos';
+import type { RuntimePaths } from '../../runtime-home';
+import type {
+  CheckFetcher,
+  DesiredTerminalState,
+  PrWatchSnapshot,
+  PrWatchStatus,
+  RefWatchSnapshot,
+  RefWatchStatus,
+  ResolvedPrReference,
+  ResolvedRefReference,
+  WatchActionResult,
+  WatchFetcher,
+} from './schemas';
+import { resolvePrReference, resolveRefReference } from './references';
+import { errorMessage, failResult } from './utils';
+
+export async function resolveWatchId(
+  input: { id?: string; ref?: string },
+  paths: RuntimePaths,
+  action: string,
+): Promise<
+  { ok: true; id: string } | { ok: false; result: WatchActionResult }
+> {
+  if (input.id) return { ok: true, id: input.id };
+  if (!input.ref) {
+    return {
+      ok: false,
+      result: failResult(action, 'A watch id or PR reference is required.', {
+        requires: ['id', 'ref'],
+      }),
+    };
+  }
+
+  const registry = await readRepoRegistrySnapshot(paths);
+  const resolved = resolvePrReference(input.ref, registry);
+  if (!resolved.ok) return resolved;
+  return { ok: true, id: resolved.reference.id };
+}
+
+export async function resolveRefWatchId(
+  input: { id?: string; repo?: string; ref?: string; target?: string },
+  paths: RuntimePaths,
+  action: string,
+): Promise<
+  { ok: true; id: string } | { ok: false; result: WatchActionResult }
+> {
+  if (input.id) return { ok: true, id: input.id };
+  const registry = await readRepoRegistrySnapshot(paths);
+  const resolved = resolveRefReference(input, registry);
+  if (!resolved.ok) {
+    return {
+      ok: false,
+      result: {
+        ...resolved.result,
+        action,
+      },
+    };
+  }
+
+  return { ok: true, id: resolved.reference.id };
+}
+
+export async function defaultWatchFetcher(reference: ResolvedPrReference) {
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) {
+    throw new Error('GITHUB_TOKEN is not configured');
+  }
+
+  return fetchPullRequestDetail({
+    token,
+    owner: reference.githubOwner,
+    repo: reference.githubName,
+    number: reference.prNumber,
+  });
+}
+
+export async function defaultCheckFetcher(
+  reference: ResolvedPrReference | ResolvedRefReference,
+  ref: string,
+) {
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) {
+    throw new Error('GITHUB_TOKEN is not configured');
+  }
+
+  return fetchCheckSummary({
+    token,
+    owner: reference.githubOwner,
+    repo: reference.githubName,
+    ref,
+  });
+}
+
+export async function fetchWatchDetail(
+  action: string,
+  reference: ResolvedPrReference,
+  fetcher: WatchFetcher,
+) {
+  try {
+    return { ok: true as const, detail: await fetcher(reference) };
+  } catch (error) {
+    return watchFetchFailure(action, error);
+  }
+}
+
+export function watchFetchFailure(action: string, error: unknown) {
+  return {
+    ok: false as const,
+    result: failResult(action, 'Could not fetch GitHub PR state.', {
+      errors: [errorMessage(error)],
+      requires:
+        error instanceof Error && error.message.includes('GITHUB_TOKEN')
+          ? ['GITHUB_TOKEN']
+          : undefined,
+    }),
+  };
+}
+
+export function refFetchFailure(action: string, error: unknown) {
+  return {
+    ok: false as const,
+    result: failResult(action, 'Could not fetch GitHub ref checks.', {
+      errors: [errorMessage(error)],
+      requires:
+        error instanceof Error && error.message.includes('GITHUB_TOKEN')
+          ? ['GITHUB_TOKEN']
+          : undefined,
+    }),
+  };
+}
+
+export async function snapshotFromDetail(
+  detail: GitHubPullRequestDetail,
+  reference: ResolvedPrReference,
+  checkFetcher: CheckFetcher,
+): Promise<PrWatchSnapshot> {
+  const checkRef = detail.merged ? detail.mergeCommitSha : null;
+  const checks = checkRef
+    ? await checkFetcher(reference, checkRef).catch(() => null)
+    : null;
+
+  return {
+    state: detail.state,
+    merged: detail.merged,
+    mergeCommitSha: detail.mergeCommitSha,
+    checks,
+    title: detail.title,
+    url: detail.url,
+    updatedAt: detail.updatedAt,
+    headSha: detail.headSha,
+    baseRef: detail.baseRef,
+  };
+}
+
+export async function snapshotFromRef(
+  reference: ResolvedRefReference,
+  checkFetcher: CheckFetcher,
+  action: string,
+): Promise<
+  | { ok: true; snapshot: RefWatchSnapshot }
+  | { ok: false; result: WatchActionResult }
+> {
+  try {
+    const checks = await checkFetcher(reference, reference.ref);
+    return {
+      ok: true,
+      snapshot: {
+        ref: reference.ref,
+        checks,
+        url: refUrl(reference),
+        checkedAt: new Date().toISOString(),
+      },
+    };
+  } catch (error) {
+    return refFetchFailure(action, error);
+  }
+}
+
+export function statusFromSnapshot(
+  snapshot: PrWatchSnapshot,
+  desiredTerminalState: DesiredTerminalState,
+): PrWatchStatus {
+  if (
+    desiredTerminalState === 'merged' &&
+    snapshot.state === 'closed' &&
+    snapshot.merged
+  ) {
+    return 'merged';
+  }
+  if (snapshot.checks?.status === 'success') return 'green';
+  if (snapshot.checks?.status === 'failure') return 'attention-needed';
+  if (snapshot.state === 'closed' && snapshot.merged) return 'watching';
+  if (snapshot.state === 'closed') return 'closed';
+  if (snapshot.state === 'open') return 'watching';
+  return 'unknown';
+}
+
+export function refStatusFromChecks(
+  checks: GitHubCheckSummary,
+): RefWatchStatus {
+  if (checks.status === 'success') return 'green';
+  if (checks.status === 'failure') return 'attention-needed';
+  if (checks.status === 'pending' || checks.status === 'none') {
+    return 'watching';
+  }
+  return 'unknown';
+}
+
+export function meaningfulRefSnapshot(snapshot: RefWatchSnapshot | null) {
+  if (!snapshot) return '';
+  return JSON.stringify({
+    ref: snapshot.ref,
+    url: snapshot.url,
+    checks: semanticCheckFingerprint(snapshot.checks),
+  });
+}
+
+export function meaningfulPrSnapshot(snapshot: PrWatchSnapshot | null) {
+  if (!snapshot) return '';
+  return JSON.stringify({
+    state: snapshot.state,
+    merged: snapshot.merged,
+    mergeCommitSha: snapshot.mergeCommitSha,
+    checks: snapshot.checks ? semanticCheckFingerprint(snapshot.checks) : null,
+    title: snapshot.title,
+    url: snapshot.url,
+    updatedAt: snapshot.updatedAt,
+    headSha: snapshot.headSha,
+    baseRef: snapshot.baseRef,
+  });
+}
+
+function semanticCheckFingerprint(checks: GitHubCheckSummary) {
+  const { checkedAt: _checkedAt, ...semanticChecks } = checks;
+  return semanticChecks;
+}
+
+export function refUrl(reference: ResolvedRefReference) {
+  const path = /^[a-f0-9]{40}$/i.test(reference.ref) ? 'commit' : 'tree';
+  const encodedRef = reference.ref.split('/').map(encodeURIComponent).join('/');
+  return `https://github.com/${reference.repoFullName}/${path}/${encodedRef}`;
+}

package/src/modules/watches/references.ts

@@ -0,0 +1,293 @@
+import type { RepoRegistrySnapshot } from '../repos';
+import { repoFullName } from '../repos';
+import type {
+  DesiredTerminalState,
+  ResolvedPrReference,
+  ResolvedRefReference,
+  WatchActionResult,
+} from './schemas';
+import { failResult } from './utils';
+
+export function parseWatchPrReference(
+  input: string,
+  registry: Pick<RepoRegistrySnapshot, 'repos'>,
+  desiredTerminalState?: DesiredTerminalState,
+) {
+  return resolvePrReference(input, registry, desiredTerminalState);
+}
+
+export function parseWatchRefReference(
+  input: { repo?: string; ref?: string; target?: string },
+  registry: Pick<RepoRegistrySnapshot, 'repos'>,
+) {
+  return resolveRefReference(input, registry);
+}
+
+export function resolvePrReference(
+  input: string,
+  registry: Pick<RepoRegistrySnapshot, 'repos'>,
+  explicitDesiredTerminalState?: DesiredTerminalState,
+):
+  | { ok: true; reference: ResolvedPrReference }
+  | { ok: false; result: WatchActionResult } {
+  const desiredFromInput = readDesiredTerminalState(input);
+  const desiredTerminalState =
+    explicitDesiredTerminalState ?? desiredFromInput.state ?? 'checks';
+  const ref = desiredFromInput.ref;
+  const urlMatch = ref.match(
+    /^https:\/\/github\.com\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)\/?$/i,
+  );
+
+  if (urlMatch) {
+    return okReference({
+      repoId: `${urlMatch[1]}/${urlMatch[2]}`,
+      githubOwner: urlMatch[1],
+      githubName: urlMatch[2],
+      prNumber: Number(urlMatch[3]),
+      desiredTerminalState,
+    });
+  }
+
+  const fullNameMatch = ref.match(/^([^/\s#]+)\/([^/\s#]+)#(\d+)$/);
+  if (fullNameMatch) {
+    return okReference({
+      repoId: `${fullNameMatch[1]}/${fullNameMatch[2]}`,
+      githubOwner: fullNameMatch[1],
+      githubName: fullNameMatch[2],
+      prNumber: Number(fullNameMatch[3]),
+      desiredTerminalState,
+    });
+  }
+
+  const repoMatch = ref.match(/^([^#\s]+)#(\d+)$/);
+  if (repoMatch) {
+    const repo = findConfiguredRepo(registry.repos, repoMatch[1]);
+    if (!repo.ok) return repo;
+
+    return okReference({
+      repoId: repo.repo.id,
+      githubOwner: repo.repo.github.owner,
+      githubName: repo.repo.github.name,
+      prNumber: Number(repoMatch[2]),
+      desiredTerminalState,
+    });
+  }
+
+  const numberMatch = ref.match(/^#(\d+)$/);
+  if (numberMatch) {
+    if (registry.repos.length !== 1) {
+      return {
+        ok: false,
+        result: failResult(
+          'watch_pr_parse',
+          'A bare PR number requires exactly one configured repo.',
+          { requires: ['repo'] },
+        ),
+      };
+    }
+
+    const repo = registry.repos[0];
+    return okReference({
+      repoId: repo.id,
+      githubOwner: repo.github.owner,
+      githubName: repo.github.name,
+      prNumber: Number(numberMatch[1]),
+      desiredTerminalState,
+    });
+  }
+
+  return {
+    ok: false,
+    result: failResult(
+      'watch_pr_parse',
+      `Could not parse PR reference "${input}".`,
+      {
+        requires: ['ref'],
+      },
+    ),
+  };
+}
+
+export function resolveRefReference(
+  input: { repo?: string; ref?: string; target?: string },
+  registry: Pick<RepoRegistrySnapshot, 'repos'>,
+):
+  | { ok: true; reference: ResolvedRefReference }
+  | { ok: false; result: WatchActionResult } {
+  const normalized = normalizeRefInput(input);
+  if (!normalized.ok) return normalized;
+
+  const fullNameMatch = normalized.repo.match(/^([^/\s@]+)\/([^/\s@]+)$/);
+  if (fullNameMatch) {
+    return okRefReference({
+      repoId: `${fullNameMatch[1]}/${fullNameMatch[2]}`,
+      githubOwner: fullNameMatch[1],
+      githubName: fullNameMatch[2],
+      ref: normalized.ref,
+    });
+  }
+
+  const repo = findConfiguredRepo(registry.repos, normalized.repo);
+  if (!repo.ok) {
+    return {
+      ok: false,
+      result: {
+        ...repo.result,
+        action: 'watch_ref_parse',
+      },
+    };
+  }
+
+  return okRefReference({
+    repoId: repo.repo.id,
+    githubOwner: repo.repo.github.owner,
+    githubName: repo.repo.github.name,
+    ref: normalized.ref,
+  });
+}
+
+export function normalizeRefInput(input: {
+  repo?: string;
+  ref?: string;
+  target?: string;
+}):
+  | { ok: true; repo: string; ref: string }
+  | { ok: false; result: WatchActionResult } {
+  if (input.repo && input.ref) {
+    const repo = input.repo.trim();
+    const ref = input.ref.trim();
+    if (repo && ref) {
+      return { ok: true, repo, ref };
+    }
+  }
+
+  const target = input.target?.trim();
+  if (!target) {
+    return {
+      ok: false,
+      result: failResult(
+        'watch_ref_parse',
+        'A repo/ref pair or target such as "repo@branch" is required.',
+        { requires: ['repo', 'ref'] },
+      ),
+    };
+  }
+
+  const urlMatch = target.match(
+    /^https:\/\/github\.com\/([^/\s]+)\/([^/\s]+)\/(?:tree|commit|commits)\/(.+)$/i,
+  );
+  if (urlMatch) {
+    return {
+      ok: true,
+      repo: `${urlMatch[1]}/${urlMatch[2]}`,
+      ref: decodeURIComponent(urlMatch[3].replace(/\/$/, '')),
+    };
+  }
+
+  const atIndex = target.indexOf('@');
+  if (atIndex > 0 && atIndex < target.length - 1) {
+    return {
+      ok: true,
+      repo: target.slice(0, atIndex).trim(),
+      ref: target.slice(atIndex + 1).trim(),
+    };
+  }
+
+  return {
+    ok: false,
+    result: failResult(
+      'watch_ref_parse',
+      `Could not parse ref watch target "${target}".`,
+      { requires: ['target'] },
+    ),
+  };
+}
+
+export function okRefReference(
+  input: Omit<ResolvedRefReference, 'id' | 'repoFullName'>,
+): {
+  ok: true;
+  reference: ResolvedRefReference;
+} {
+  const repoFullNameValue = `${input.githubOwner}/${input.githubName}`;
+  const reference = {
+    ...input,
+    repoFullName: repoFullNameValue,
+    id: `${repoFullNameValue}@${input.ref}`,
+  };
+
+  return { ok: true, reference };
+}
+
+export function readDesiredTerminalState(input: string) {
+  const match = input.match(/\s+until\s+(checks|merged?)\s*$/i);
+  if (!match) return { ref: input.trim(), state: undefined };
+
+  const rawState = match[1].toLowerCase();
+  const state: DesiredTerminalState = rawState.startsWith('merge')
+    ? 'merged'
+    : (rawState as DesiredTerminalState);
+
+  return {
+    ref: input.slice(0, match.index).trim(),
+    state,
+  };
+}
+
+export function findConfiguredRepo(
+  repos: RepoRegistrySnapshot['repos'],
+  value: string,
+):
+  | { ok: true; repo: RepoRegistrySnapshot['repos'][number] }
+  | { ok: false; result: WatchActionResult } {
+  const matches = repos.filter(
+    (repo) =>
+      repo.id === value ||
+      repo.github.name === value ||
+      repoFullName(repo).toLowerCase() === value.toLowerCase(),
+  );
+
+  if (matches.length === 1) {
+    return { ok: true, repo: matches[0] };
+  }
+
+  if (matches.length > 1) {
+    return {
+      ok: false,
+      result: failResult(
+        'watch_pr_parse',
+        `Repository "${value}" is ambiguous.`,
+        {
+          requires: ['repo'],
+        },
+      ),
+    };
+  }
+
+  return {
+    ok: false,
+    result: failResult(
+      'watch_pr_parse',
+      `Repository "${value}" is not configured.`,
+      {
+        requires: ['repo'],
+      },
+    ),
+  };
+}
+
+export function okReference(
+  input: Omit<ResolvedPrReference, 'id' | 'repoFullName'>,
+): {
+  ok: true;
+  reference: ResolvedPrReference;
+} {
+  const repoFullNameValue = `${input.githubOwner}/${input.githubName}`;
+  const reference = {
+    ...input,
+    repoFullName: repoFullNameValue,
+    id: `${repoFullNameValue}#${input.prNumber}`,
+  };
+
+  return { ok: true, reference };
+}