neondeck 1.0.0-beta.4

package/src/modules/pr-local-diffs/index.ts

@@ -0,0 +1,334 @@
+import { runExecFile } from '../../lib/exec';
+import { gitDiff, type RepoDiffFile } from '../../repo-edit/git';
+import {
+  ensureRuntimeHome,
+  parseRepoRegistry,
+  type RepoConfig,
+  type RuntimePaths,
+  readRuntimeJson,
+  runtimePaths,
+} from '../../runtime-home';
+import type {
+  GitHubDiffSummary,
+  GitHubPullRequestFile,
+  GitHubPullRequestFiles,
+} from '../github';
+import { repoFullName } from '../repos';
+
+export type PrDiffSource = 'auto' | 'local' | 'github';
+
+export class LocalPrDiffUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'LocalPrDiffUnavailableError';
+  }
+}
+
+export type LocalPullRequestDiffInput = {
+  owner: string;
+  repo: string;
+  number: number;
+  headSha?: string | null;
+  baseSha?: string | null;
+  baseRef?: string | null;
+  includePatches?: boolean;
+  paths?: string[];
+  maxPatchBytes?: number;
+};
+
+const fetchFlights = new Map<string, Promise<void>>();
+
+export async function readLocalPullRequestFiles(
+  input: LocalPullRequestDiffInput,
+  paths: RuntimePaths = runtimePaths(),
+): Promise<GitHubPullRequestFiles> {
+  const repo = await resolveRegisteredRepo(input, paths);
+  const refs = await resolveLocalPullRequestRefs(repo, input);
+
+  const diff = await gitDiff(repo.path, {
+    base: refs.mergeBase,
+    head: refs.head,
+    paths: input.paths,
+    includePatch: input.includePatches ?? false,
+    maxPatchBytes: input.maxPatchBytes,
+  });
+  const files = diff.files.map(toPullRequestFile);
+  return {
+    repo: repoFullName(repo),
+    number: input.number,
+    files,
+    diffSummary: diff.summary,
+    fetchedAt: new Date().toISOString(),
+  };
+}
+
+export async function readLocalPullRequestFileDiff(
+  input: LocalPullRequestDiffInput & { path: string },
+  paths: RuntimePaths = runtimePaths(),
+): Promise<{
+  file: GitHubPullRequestFile | null;
+  diff: string;
+  diffSummary: GitHubDiffSummary;
+  fetchedAt: string;
+}> {
+  const metadata = await readLocalPullRequestFiles(
+    {
+      ...input,
+      paths: undefined,
+      includePatches: false,
+    },
+    paths,
+  );
+  const metadataFile =
+    metadata.files.find((item) => item.path === input.path) ?? null;
+  const pathspec = [
+    ...(metadataFile?.previousPath ? [metadataFile.previousPath] : []),
+    input.path,
+  ];
+  const diff = await readLocalPullRequestFiles(
+    {
+      ...input,
+      paths: pathspec,
+      includePatches: true,
+    },
+    paths,
+  );
+  const file =
+    diff.files.find((item) => item.path === input.path) ?? metadataFile;
+  return {
+    file,
+    diff: file?.patch ?? '',
+    diffSummary: diff.diffSummary,
+    fetchedAt: diff.fetchedAt,
+  };
+}
+
+async function resolveRegisteredRepo(
+  input: Pick<LocalPullRequestDiffInput, 'owner' | 'repo'>,
+  paths: RuntimePaths,
+) {
+  await ensureRuntimeHome(paths);
+  const registry = await readRuntimeJson(paths.repos, parseRepoRegistry);
+  const fullName = `${input.owner}/${input.repo}`.toLowerCase();
+  const repo = registry.repos.find(
+    (item) => repoFullName(item).toLowerCase() === fullName,
+  );
+  if (!repo) {
+    throw unavailable(
+      `Repository ${input.owner}/${input.repo} is not registered locally.`,
+    );
+  }
+  return repo;
+}
+
+async function resolveLocalPullRequestRefs(
+  repo: RepoConfig,
+  input: LocalPullRequestDiffInput,
+) {
+  const head = normalizeSha(input.headSha, 'head SHA');
+  const baseSha = input.baseSha
+    ? normalizeSha(input.baseSha, 'base SHA')
+    : null;
+  const baseRef = input.baseRef ? validateBranchName(input.baseRef) : null;
+  if (!head) {
+    throw unavailable('A PR head SHA is required for local PR diffs.');
+  }
+  if (!baseSha && !baseRef) {
+    throw unavailable('A base SHA or base ref is required for local PR diffs.');
+  }
+
+  const base = baseSha ?? neondeckBaseRef(baseRef!);
+  const warmMergeBase = await mergeBase(repo.path, base, head).catch(
+    () => null,
+  );
+  if (warmMergeBase) {
+    return { head, mergeBase: warmMergeBase };
+  }
+
+  await assertOriginMatches(repo);
+  await singleFlight(fetchKey(repo, input, head), async () => {
+    const currentMergeBase = await mergeBase(repo.path, base, head).catch(
+      () => null,
+    );
+    if (currentMergeBase) {
+      return;
+    }
+
+    const refspecs = [
+      `+refs/pull/${input.number}/head:refs/neondeck/pull/${input.number}/head`,
+    ];
+    if (baseRef) {
+      refspecs.push(`+refs/heads/${baseRef}:${neondeckBaseRef(baseRef)}`);
+    }
+    await git(repo.path, [
+      'fetch',
+      '--no-tags',
+      '--refmap=',
+      'origin',
+      ...refspecs,
+    ]);
+  });
+
+  const fetchedMergeBase = await mergeBase(repo.path, base, head).catch(
+    () => null,
+  );
+  if (!fetchedMergeBase) {
+    throw unavailable(
+      `Could not find a merge-base for ${repoFullName(repo)}#${input.number}.`,
+    );
+  }
+
+  return { head, mergeBase: fetchedMergeBase };
+}
+
+async function assertOriginMatches(repo: RepoConfig) {
+  const origin = await git(repo.path, [
+    'config',
+    '--get',
+    'remote.origin.url',
+  ]).then((output) => output.trim());
+  const parsed = parseGitHubRemote(origin);
+  if (!parsed) {
+    throw unavailable(`Origin remote is not a GitHub repository: ${origin}`);
+  }
+  const expected = repoFullName(repo).toLowerCase();
+  const actual = `${parsed.owner}/${parsed.repo}`.toLowerCase();
+  if (actual !== expected) {
+    throw unavailable(
+      `Origin remote ${actual} does not match configured repo ${expected}.`,
+    );
+  }
+}
+
+function parseGitHubRemote(url: string) {
+  const trimmed = url.trim();
+  const patterns = [
+    /^https:\/\/github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i,
+    /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i,
+    /^ssh:\/\/git@github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i,
+  ];
+  for (const pattern of patterns) {
+    const match = pattern.exec(trimmed);
+    if (match?.[1] && match[2]) {
+      return { owner: match[1], repo: match[2] };
+    }
+  }
+  return null;
+}
+
+async function mergeBase(repoPath: string, base: string, head: string) {
+  const output = await git(repoPath, ['merge-base', base, head]);
+  const value = output.trim();
+  if (!value) throw unavailable('Git merge-base returned no commit.');
+  return value;
+}
+
+function toPullRequestFile(file: RepoDiffFile): GitHubPullRequestFile {
+  return {
+    path: file.path,
+    previousPath: file.previousPath ?? null,
+    status: normalizeStatus(file.status),
+    additions: file.additions,
+    deletions: file.deletions,
+    changes: file.additions + file.deletions,
+    binary: file.binary,
+    generatedLike: file.generatedLike,
+    patch: file.patch ?? null,
+    truncated: file.truncated ?? false,
+    sha: null,
+    htmlUrl: null,
+    rawUrl: null,
+    contentsUrl: null,
+    message: missingPatchMessage(file),
+  };
+}
+
+function normalizeStatus(status: string) {
+  const code = status.toUpperCase();
+  if (code.startsWith('A')) return 'added';
+  if (code.startsWith('D')) return 'removed';
+  if (code.startsWith('R')) return 'renamed';
+  if (code.startsWith('C')) return 'copied';
+  return 'modified';
+}
+
+function missingPatchMessage(file: RepoDiffFile) {
+  if (file.patch) return null;
+  if (file.truncated)
+    return 'Local git patch exceeded the configured size limit.';
+  if (file.binary) return 'Local git identified this as a binary file.';
+  return null;
+}
+
+function normalizeSha(value: string | null | undefined, label: string) {
+  const trimmed = value?.trim() ?? '';
+  if (!trimmed) return null;
+  if (!/^[0-9a-f]{40}$/i.test(trimmed)) {
+    throw unavailable(`Invalid PR ${label}.`);
+  }
+  return trimmed;
+}
+
+function validateBranchName(value: string) {
+  const trimmed = value.trim();
+  if (
+    !trimmed ||
+    trimmed.startsWith('-') ||
+    trimmed.startsWith('/') ||
+    trimmed.endsWith('/') ||
+    trimmed.endsWith('.') ||
+    trimmed.includes('\u0000') ||
+    trimmed.includes('..') ||
+    trimmed.includes('@{') ||
+    /[\s\\~^:?*[\]]/.test(trimmed)
+  ) {
+    throw unavailable(`Invalid PR base ref: ${value}`);
+  }
+  return trimmed;
+}
+
+function neondeckBaseRef(baseRef: string) {
+  return `refs/neondeck/base/${baseRef}`;
+}
+
+function fetchKey(
+  repo: RepoConfig,
+  input: LocalPullRequestDiffInput,
+  head: string,
+) {
+  return [
+    repo.path,
+    input.number,
+    head,
+    input.baseSha ?? '',
+    input.baseRef ?? '',
+  ].join('\u0000');
+}
+
+async function singleFlight(key: string, fn: () => Promise<void>) {
+  const existing = fetchFlights.get(key);
+  if (existing) return existing;
+  const promise = fn().finally(() => fetchFlights.delete(key));
+  fetchFlights.set(key, promise);
+  return promise;
+}
+
+async function git(cwd: string, args: string[]) {
+  try {
+    const { stdout } = await runExecFile('git', args, {
+      cwd,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    return stdout;
+  } catch (error) {
+    throw unavailable(errorMessage(error));
+  }
+}
+
+function unavailable(message: string) {
+  return new LocalPrDiffUnavailableError(message);
+}
+
+function errorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/modules/pr-review-assist/actions.ts

@@ -0,0 +1,199 @@
+import { defineAction } from '@flue/runtime';
+import {
+  prReviewAssistInputSchema,
+  prReviewAssistOutputSchema,
+  reviewAssistStructuredOutputSchema,
+} from './schemas';
+import {
+  reviewPrForHuman,
+  type ReviewAssistFacts,
+  type ReviewAssistPromptContext,
+} from './service';
+
+export const reviewPrForHumanAction = defineAction({
+  name: 'neondeck_pr_review_for_human',
+  description:
+    'Prepare local PR review reports and Neon-origin draft comments for human review without submitting anything to GitHub.',
+  input: prReviewAssistInputSchema,
+  output: prReviewAssistOutputSchema,
+  async run({ harness, input, log }) {
+    const result = await reviewPrForHuman(input, undefined, {
+      reviewer: async (facts, context) => {
+        const session = await harness.session();
+        const response = await session.skill('neon-pr-review', {
+          args: {
+            task: 'Review the pull request facts and return only the requested structured review output.',
+            facts: reviewFactsForPrompt(facts, context),
+          },
+          result: reviewAssistStructuredOutputSchema,
+          signal: AbortSignal.timeout(180_000),
+        });
+        return response.data;
+      },
+    });
+    if (result.ok) {
+      log.info('Prepared PR review assist artifacts', {
+        message: result.message,
+      });
+    } else {
+      log.warn('PR review assist failed', {
+        message: result.message,
+        requires: 'requires' in result ? result.requires : undefined,
+      });
+    }
+    return result;
+  },
+});
+
+export function reviewFactsForPrompt(
+  facts: ReviewAssistFacts,
+  context?: ReviewFactsPromptContext,
+) {
+  const backgroundContext = reviewBackgroundContext(context);
+  return {
+    target: {
+      repoFullName: facts.target.repoFullName,
+      number: facts.target.number,
+    },
+    ...(backgroundContext ? { backgroundContext } : {}),
+    memories: (context?.learningMemoryContext?.memories ?? []).map(
+      (memory) => ({
+        id: memory.id,
+        scope: memory.scope,
+        key: memory.key,
+        repoId: memory.repoId,
+        value: memory.value,
+      }),
+    ),
+    pullRequest: {
+      title: facts.state.title,
+      body: truncate(facts.state.body ?? '', 20_000),
+      state: facts.state.state,
+      url: facts.state.url,
+      baseRef: facts.state.baseRef,
+      baseSha: facts.state.baseSha,
+      headRef: facts.state.headRef,
+      headSha: facts.state.headSha,
+      draft: facts.state.draft,
+      merged: facts.state.merged,
+      mergeCommitSha: facts.state.mergeCommitSha,
+      mergeable: facts.state.mergeable,
+      mergeableState: facts.state.mergeableState,
+      maintainerCanModify: facts.state.maintainerCanModify,
+      isOutOfDate: facts.state.isOutOfDate,
+    },
+    linkedIssueReferenceHints: issueReferenceHints(
+      `${facts.state.title}\n${facts.state.body ?? ''}`,
+    ),
+    diffSummary: facts.diffSummary,
+    checks: {
+      suites: facts.state.checkSuites.map((suite) => ({
+        id: suite.id,
+        status: suite.status,
+        conclusion: suite.conclusion,
+        appSlug: suite.appSlug,
+        htmlUrl: suite.htmlUrl,
+      })),
+      runs: facts.state.checkRuns.map((check) => ({
+        id: check.id,
+        name: check.name,
+        status: check.status,
+        conclusion: check.conclusion,
+        htmlUrl: check.htmlUrl,
+      })),
+    },
+    commits: facts.state.commits.map((commit) => ({
+      sha: commit.sha,
+      url: commit.url,
+      authorLogin: commit.authorLogin,
+      committedAt: commit.committedAt,
+    })),
+    reviewThreads: facts.state.reviewThreads.map((thread) => ({
+      id: thread.id,
+      isResolved: thread.isResolved,
+      isOutdated: thread.isOutdated,
+      path: thread.path,
+      line: thread.line,
+      originalLine: thread.originalLine ?? null,
+      diffSide: thread.diffSide ?? null,
+      comments: thread.comments.map((comment) => ({
+        id: comment.id,
+        authorLogin: comment.authorLogin,
+        body: truncate(comment.body, 4_000),
+        path: comment.path,
+        line: comment.line,
+        originalLine: comment.originalLine,
+        diffHunk: truncate(comment.diffHunk ?? '', 4_000),
+        createdAt: comment.createdAt,
+        updatedAt: comment.updatedAt,
+      })),
+    })),
+    requestedChangesState: {
+      active: facts.state.requestedChangesState.active,
+      latestByReviewer: facts.state.requestedChangesState.latestByReviewer,
+      history: facts.state.requestedChangesState.history,
+    },
+    requestedChangesReviews: facts.state.requestedChangesReviews,
+    branchPermissions: facts.state.branchPermissions,
+    files: facts.files.map((file) => ({
+      path: file.path,
+      previousPath: file.previousPath,
+      status: file.status,
+      additions: file.additions,
+      deletions: file.deletions,
+      changes: file.changes,
+      binary: file.binary,
+      generatedLike: file.generatedLike,
+      truncated: file.truncated,
+      patch: truncate(file.patch ?? '', 12_000),
+      message: file.message,
+    })),
+    limitations: [
+      'Linked issue relationships are not currently typed separately in GitHubPullRequestEventState; linkedIssueReferenceHints are extracted from PR title/body text only.',
+    ],
+  };
+}
+
+type ReviewFactsPromptContext = Partial<
+  Pick<ReviewAssistPromptContext, 'learningMemoryContext'>
+> & {
+  memoryContext?: {
+    text: string;
+    memoryIds: string[];
+  };
+};
+
+function reviewBackgroundContext(context?: ReviewFactsPromptContext) {
+  if (!context?.memoryContext && !context?.learningMemoryContext) return null;
+  return {
+    ...(context.memoryContext
+      ? {
+          structuredMemory: context.memoryContext.text,
+          memoryIds: context.memoryContext.memoryIds,
+        }
+      : {}),
+    ...(context.learningMemoryContext
+      ? {
+          learningMemories: context.learningMemoryContext.text,
+          learningMemoryIds: context.learningMemoryContext.memoryIds,
+        }
+      : {}),
+    usage:
+      'Treat memory as durable background guidance, not current PR evidence. Fetched PR facts and workflow bounds win on conflict.',
+  };
+}
+
+function truncate(value: string, maxLength: number) {
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, maxLength)}\n[truncated]`;
+}
+
+function issueReferenceHints(value: string) {
+  const matches = new Set<string>();
+  const pattern =
+    /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+((?:[\w.-]+\/[\w.-]+)?#\d+)/gi;
+  for (const match of value.matchAll(pattern)) {
+    if (typeof match[1] === 'string') matches.add(match[1]);
+  }
+  return [...matches].slice(0, 20);
+}

package/src/modules/pr-review-assist/index.ts

@@ -0,0 +1,3 @@
+export * from './actions';
+export * from './schemas';
+export * from './service';

package/src/modules/pr-review-assist/schemas.ts

@@ -0,0 +1,74 @@
+import * as v from 'valibot';
+
+export const prReviewAssistInputSchema = v.object({
+  watchId: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1))),
+  ref: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1))),
+  repo: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1))),
+  prNumber: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+});
+
+const reviewSeveritySchema = v.picklist(['critical', 'major', 'minor', 'nit']);
+const reviewSideSchema = v.picklist(['RIGHT', 'LEFT']);
+
+export const reviewAssistFindingSchema = v.object({
+  severity: reviewSeveritySchema,
+  path: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(1_000)),
+  side: v.optional(reviewSideSchema),
+  line: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+  startLine: v.optional(
+    v.nullable(v.pipe(v.number(), v.integer(), v.minValue(1))),
+  ),
+  startSide: v.optional(v.nullable(reviewSideSchema)),
+  summary: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(1_000)),
+  suggestedFix: v.pipe(
+    v.string(),
+    v.trim(),
+    v.minLength(1),
+    v.maxLength(4_000),
+  ),
+  confidence: v.optional(v.picklist(['high', 'medium', 'low'])),
+});
+
+export const reviewAssistStructuredOutputSchema = v.object({
+  overview: v.object({
+    summary: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(4_000)),
+    changeMap: v.array(
+      v.object({
+        path: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(1_000)),
+        summary: v.pipe(
+          v.string(),
+          v.trim(),
+          v.minLength(1),
+          v.maxLength(2_000),
+        ),
+        risk: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(1_000))),
+      }),
+    ),
+    risks: v.pipe(
+      v.array(v.pipe(v.string(), v.trim(), v.minLength(1))),
+      v.maxLength(20),
+    ),
+    checks: v.pipe(
+      v.array(v.pipe(v.string(), v.trim(), v.minLength(1))),
+      v.maxLength(20),
+    ),
+  }),
+  findings: v.pipe(v.array(reviewAssistFindingSchema), v.maxLength(100)),
+});
+
+export const prReviewAssistOutputSchema = v.looseObject({
+  ok: v.boolean(),
+  action: v.literal('pr_review_assist'),
+  changed: v.boolean(),
+  message: v.string(),
+});
+
+export type PrReviewAssistInput = v.InferInput<
+  typeof prReviewAssistInputSchema
+>;
+export type ReviewAssistStructuredOutput = v.InferOutput<
+  typeof reviewAssistStructuredOutputSchema
+>;
+export type ReviewAssistFinding = v.InferOutput<
+  typeof reviewAssistFindingSchema
+>;