@davidvornholt/standards 0.10.2 → 0.11.0

package/src/poller-config.ts

@@ -0,0 +1,188 @@
+// Host-level poller configuration. The poller is host infrastructure, not
+// repository state: one config file on the polling host lists every watched
+// repository, and all workflow state lives in GitHub labels and comments so
+// ticks are stateless and safe to re-run.
+
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { isNonEmptyString, isRecord } from './github-settings-parse';
+
+const REPO_PATTERN =
+  /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/u;
+
+const CONFIG_KEYS: ReadonlySet<string> = new Set([
+  'repos',
+  'model',
+  'reasoningEffort',
+  // biome-ignore lint/security/noSecrets: a config key name, not a credential.
+  'maxJobsPerTick',
+  'staleClaimHours',
+  'runTimeoutMinutes',
+  'cacheDir',
+  'extraCodexArgs',
+]);
+
+const DEFAULT_MAX_JOBS_PER_TICK = 1;
+const DEFAULT_STALE_CLAIM_HOURS = 6;
+// Thorough review runs legitimately take hours; the timeout exists to catch
+// wedged agents, not to bound honest work.
+const DEFAULT_RUN_TIMEOUT_MINUTES = 240;
+const MINUTES_PER_HOUR = 60;
+
+export type PollerConfig = {
+  readonly repos: ReadonlyArray<string>;
+  readonly model: string;
+  readonly reasoningEffort: string;
+  readonly maxJobsPerTick: number;
+  readonly staleClaimHours: number;
+  readonly runTimeoutMinutes: number;
+  readonly cacheDir: string;
+  readonly extraCodexArgs: ReadonlyArray<string>;
+};
+
+export type PollerConfigResult = {
+  readonly config: PollerConfig | null;
+  readonly problems: ReadonlyArray<string>;
+};
+
+const expandHome = (path: string): string =>
+  path === '~' || path.startsWith('~/') ? join(homedir(), path.slice(1)) : path;
+
+const parseRepos = (
+  raw: unknown,
+  problems: Array<string>,
+): ReadonlyArray<string> => {
+  if (!(Array.isArray(raw) && raw.every((repo) => typeof repo === 'string'))) {
+    problems.push('poller config "repos" must be a string array');
+    return [];
+  }
+  if (raw.length === 0) {
+    problems.push('poller config "repos" must list at least one repository');
+  }
+  for (const repo of raw) {
+    if (!REPO_PATTERN.test(repo)) {
+      problems.push(
+        `poller config "repos" entries must be "owner/repo": ${repo}`,
+      );
+    }
+  }
+  if (new Set(raw).size !== raw.length) {
+    problems.push('poller config "repos" entries must be unique');
+  }
+  return raw;
+};
+
+const parsePositiveInteger = (
+  raw: unknown,
+  field: string,
+  fallback: number,
+  problems: Array<string>,
+): number => {
+  if (raw === undefined) {
+    return fallback;
+  }
+  if (!(typeof raw === 'number' && Number.isInteger(raw) && raw > 0)) {
+    problems.push(`poller config "${field}" must be a positive integer`);
+    return fallback;
+  }
+  return raw;
+};
+
+const parseRequiredString = (
+  raw: unknown,
+  field: string,
+  problems: Array<string>,
+): string => {
+  if (!isNonEmptyString(raw)) {
+    problems.push(
+      `poller config "${field}" must be a non-empty string; the model choice is deliberate and has no default`,
+    );
+    return '';
+  }
+  return raw;
+};
+
+const parseExtraCodexArgs = (
+  raw: unknown,
+  problems: Array<string>,
+): ReadonlyArray<string> => {
+  if (raw === undefined) {
+    return [];
+  }
+  if (!(Array.isArray(raw) && raw.every((arg) => typeof arg === 'string'))) {
+    problems.push('poller config "extraCodexArgs" must be a string array');
+    return [];
+  }
+  return raw;
+};
+
+const parseCacheDir = (
+  raw: unknown,
+  configDir: string,
+  problems: Array<string>,
+): string => {
+  if (raw === undefined) {
+    return join(homedir(), '.cache', 'standards-poller');
+  }
+  if (!isNonEmptyString(raw)) {
+    problems.push('poller config "cacheDir" must be a non-empty string');
+    return join(homedir(), '.cache', 'standards-poller');
+  }
+  const expanded = expandHome(raw);
+  return isAbsolute(expanded) ? expanded : resolve(configDir, expanded);
+};
+
+// Reject unknown keys so a typo fails loudly instead of silently using a
+// default, mirroring the sync policy and settings parsers.
+export const parsePollerConfig = (
+  raw: unknown,
+  configDir: string,
+): PollerConfigResult => {
+  if (!isRecord(raw)) {
+    return { config: null, problems: ['poller config must be a JSON object'] };
+  }
+  const problems: Array<string> = [];
+  for (const key of Object.keys(raw)) {
+    if (!CONFIG_KEYS.has(key)) {
+      problems.push(`poller config has unknown key "${key}"`);
+    }
+  }
+  const config: PollerConfig = {
+    repos: parseRepos(raw.repos, problems),
+    model: parseRequiredString(raw.model, 'model', problems),
+    reasoningEffort: parseRequiredString(
+      raw.reasoningEffort,
+      'reasoningEffort',
+      problems,
+    ),
+    maxJobsPerTick: parsePositiveInteger(
+      raw.maxJobsPerTick,
+      // biome-ignore lint/security/noSecrets: a config key name, not a credential.
+      'maxJobsPerTick',
+      DEFAULT_MAX_JOBS_PER_TICK,
+      problems,
+    ),
+    staleClaimHours: parsePositiveInteger(
+      raw.staleClaimHours,
+      'staleClaimHours',
+      DEFAULT_STALE_CLAIM_HOURS,
+      problems,
+    ),
+    runTimeoutMinutes: parsePositiveInteger(
+      raw.runTimeoutMinutes,
+      'runTimeoutMinutes',
+      DEFAULT_RUN_TIMEOUT_MINUTES,
+      problems,
+    ),
+    cacheDir: parseCacheDir(raw.cacheDir, configDir, problems),
+    extraCodexArgs: parseExtraCodexArgs(raw.extraCodexArgs, problems),
+  };
+  if (config.staleClaimHours * MINUTES_PER_HOUR <= config.runTimeoutMinutes) {
+    problems.push(
+      'poller config "staleClaimHours" must exceed "runTimeoutMinutes": a shorter stale sweep would release the claim of a job that is still running',
+    );
+  }
+  return problems.length > 0
+    ? { config: null, problems }
+    : { config, problems: [] };
+};

package/src/poller-fix-outcome.ts

@@ -0,0 +1,36 @@
+import type { FixPublication } from './poller-fix-publication';
+import { createComment } from './poller-github-write';
+import {
+  askQuestion,
+  failJob,
+  type JobLabels,
+  releaseLabels,
+} from './poller-job-shared';
+import type { FixOutcome } from './poller-protocol';
+
+export const handleNonFixedOutcome = async (
+  job: FixPublication,
+  labels: JobLabels,
+  outcome: FixOutcome,
+): Promise<string | null> => {
+  const { deps, issue } = job;
+  if (outcome.status === 'question') {
+    await askQuestion(deps, labels, issue.number, outcome.question ?? '');
+    return `#${issue.number}: asked a question`;
+  }
+  if (outcome.status === 'stale') {
+    await createComment(
+      deps.token,
+      deps.repo,
+      issue.number,
+      `The finding no longer reproduces on ${job.defaultBranch}: ${outcome.summary}\nClosing is left to a maintainer.`,
+    );
+    await releaseLabels(deps, labels, issue.number);
+    return `#${issue.number}: stale, needs human close`;
+  }
+  if (outcome.status === 'cannot-fix') {
+    await failJob(deps, labels, issue.number, outcome.summary);
+    return `#${issue.number}: cannot fix`;
+  }
+  return null;
+};

package/src/poller-fix-output.ts

@@ -0,0 +1,135 @@
+import { Buffer } from 'node:buffer';
+import { isRecord } from './github-settings-parse';
+import {
+  assertCleanOutputWorktree,
+  commitCountBetween,
+  isAncestor,
+  isGitObjectId,
+  singleParentOf,
+} from './poller-output-integrity';
+import { FIX_OUTPUT_MARKER } from './poller-protocol';
+import { runGit } from './poller-workspace';
+
+export type SealedFixOutput = {
+  readonly repo: string;
+  readonly issueNumber: number;
+  readonly approvalId: string;
+  readonly title: string;
+  readonly body: string;
+  readonly baseSha: string;
+  readonly commits: number;
+  readonly generatedHead: string;
+  readonly sealedHead: string;
+};
+
+const fixOutputMessage = (
+  output: Omit<SealedFixOutput, 'sealedHead'>,
+): string =>
+  `${FIX_OUTPUT_MARKER}\n${Buffer.from(JSON.stringify(output)).toString('base64url')}`;
+
+const parseFixOutputMessage = (
+  message: string,
+  sealedHead: string,
+): SealedFixOutput | null => {
+  const [marker, encoded] = message.trim().split('\n');
+  if (marker !== FIX_OUTPUT_MARKER || encoded === undefined) {
+    return null;
+  }
+  try {
+    const raw = JSON.parse(
+      Buffer.from(encoded, 'base64url').toString('utf8'),
+    ) as unknown;
+    if (
+      !isRecord(raw) ||
+      typeof raw.repo !== 'string' ||
+      typeof raw.issueNumber !== 'number' ||
+      typeof raw.approvalId !== 'string' ||
+      typeof raw.title !== 'string' ||
+      typeof raw.body !== 'string' ||
+      typeof raw.baseSha !== 'string' ||
+      typeof raw.commits !== 'number' ||
+      !Number.isInteger(raw.commits) ||
+      raw.commits < 1 ||
+      typeof raw.generatedHead !== 'string' ||
+      !isGitObjectId(raw.baseSha) ||
+      !isGitObjectId(raw.generatedHead)
+    ) {
+      return null;
+    }
+    return { ...raw, sealedHead } as SealedFixOutput;
+  } catch {
+    return null;
+  }
+};
+
+export const sealFixOutput = (
+  workDir: string,
+  output: Omit<SealedFixOutput, 'generatedHead' | 'sealedHead'>,
+): SealedFixOutput => {
+  assertCleanOutputWorktree(workDir);
+  const generatedHead = runGit(
+    ['-C', workDir, 'rev-parse', 'HEAD'],
+    null,
+  ).trim();
+  runGit(
+    [
+      '-C',
+      workDir,
+      '-c',
+      'user.name=standards-poller',
+      '-c',
+      'user.email=standards-poller@users.noreply.github.com',
+      '-c',
+      'commit.gpgSign=false',
+      'commit',
+      '--allow-empty',
+      '--only',
+      '-m',
+      fixOutputMessage({ ...output, generatedHead }),
+    ],
+    null,
+  );
+  const sealedHead = runGit(['-C', workDir, 'rev-parse', 'HEAD'], null).trim();
+  return { ...output, generatedHead, sealedHead };
+};
+
+export const readSealedFixOutput = (
+  cloneDir: string,
+  branch: string,
+): SealedFixOutput | null => {
+  try {
+    const sealedHead = runGit(
+      ['-C', cloneDir, 'rev-parse', `refs/heads/${branch}`],
+      null,
+    ).trim();
+    const changed = runGit(
+      [
+        '-C',
+        cloneDir,
+        'diff-tree',
+        '--no-commit-id',
+        '--name-only',
+        '-r',
+        sealedHead,
+      ],
+      null,
+    ).trim();
+    const parsed = parseFixOutputMessage(
+      runGit(['-C', cloneDir, 'log', '-1', '--format=%B', sealedHead], null),
+      sealedHead,
+    );
+    if (
+      changed.length > 0 ||
+      parsed === null ||
+      singleParentOf(cloneDir, sealedHead) !== parsed.generatedHead ||
+      !isAncestor(cloneDir, parsed.baseSha, parsed.generatedHead) ||
+      commitCountBetween(cloneDir, parsed.baseSha, parsed.generatedHead) !==
+        parsed.commits
+    ) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+};

package/src/poller-fix-publication.ts

@@ -0,0 +1,187 @@
+import { issueRevision } from './poller-approval';
+import { type ClaimBinding, validateClaim } from './poller-claim';
+import { type SealedFixOutput, sealFixOutput } from './poller-fix-output';
+import { validateSealedFixOutput } from './poller-fix-validation';
+import { getIssue, type IssueItem } from './poller-github';
+import {
+  createDraftPullRequest,
+  findOpenPullRequestForHead,
+  getPullRequest,
+  updatePullRequest,
+} from './poller-github-pulls';
+import { createComment } from './poller-github-write';
+import {
+  failJob,
+  type JobDeps,
+  type JobLabels,
+  releaseLabels,
+} from './poller-job-shared';
+import {
+  changedWorkspaceQualityManifests,
+  lockedPathsOf,
+} from './poller-protected-paths';
+import {
+  APPROVED_FOR_REVIEW,
+  type FixOutcome,
+  forbiddenDiffPaths,
+} from './poller-protocol';
+import {
+  changedPaths,
+  commitCount,
+  pushBranch,
+  type Workspace,
+} from './poller-workspace';
+
+export type FixPublication = {
+  readonly deps: JobDeps;
+  readonly issue: IssueItem;
+  readonly defaultBranch: string;
+  readonly claim: ClaimBinding;
+  readonly branch: string;
+  readonly cloneDir: string;
+};
+
+const fixPullRequestBody = (output: SealedFixOutput): string =>
+  `<!-- standards-poller:fix issue=${output.issueNumber} approval=${output.approvalId} head=${output.sealedHead} -->\n${output.body}`;
+
+export const validateFixClaim = async (
+  job: Pick<FixPublication, 'deps' | 'issue' | 'claim'>,
+): Promise<void> => {
+  const current = await getIssue(
+    job.deps.token,
+    job.deps.repo,
+    job.issue.number,
+  );
+  const problem = await validateClaim(
+    {
+      token: job.deps.token,
+      repo: job.deps.repo,
+      issueNumber: job.issue.number,
+    },
+    job.claim,
+    issueRevision(current),
+  );
+  if (problem !== null) {
+    throw new Error(`publication blocked: ${problem}`);
+  }
+};
+
+export const publishFixedOutput = async (
+  job: FixPublication,
+  labels: JobLabels,
+  output: SealedFixOutput,
+  push: (() => void) | null,
+): Promise<string> => {
+  const { deps, issue, branch } = job;
+  await validateSealedFixOutput(
+    {
+      deps: job.deps,
+      issueNumber: job.issue.number,
+      defaultBranch: job.defaultBranch,
+      approvalId: job.claim.approval.id,
+      cloneDir: job.cloneDir,
+    },
+    output,
+  );
+  await validateFixClaim(job);
+  push?.();
+  await validateFixClaim(job);
+  const expectedBody = fixPullRequestBody(output);
+  const existing = await findOpenPullRequestForHead(
+    deps.token,
+    deps.repo,
+    branch,
+  );
+  let prNumber: number;
+  if (existing === null) {
+    prNumber = await createDraftPullRequest(deps.token, deps.repo, {
+      title: output.title,
+      body: expectedBody,
+      head: branch,
+      base: job.defaultBranch,
+    });
+  } else {
+    const pr = await getPullRequest(deps.token, deps.repo, existing);
+    if (
+      pr.headRepo !== deps.repo ||
+      pr.headRef !== branch ||
+      pr.headSha !== output.sealedHead ||
+      pr.baseRef !== job.defaultBranch ||
+      !pr.body.startsWith(
+        `<!-- standards-poller:fix issue=${issue.number} approval=${job.claim.approval.id} `,
+      )
+    ) {
+      throw new Error(
+        `existing PR #${existing} does not prove ownership of ${branch}`,
+      );
+    }
+    await validateFixClaim(job);
+    await updatePullRequest(deps.token, deps.repo, existing, {
+      title: output.title,
+      body: expectedBody,
+    });
+    prNumber = existing;
+  }
+  await validateFixClaim(job);
+  await createComment(
+    deps.token,
+    deps.repo,
+    issue.number,
+    `Opened draft PR #${prNumber} for this issue. Apply \`${APPROVED_FOR_REVIEW}\` on the PR to run the automated review-fix pass, or review it directly.`,
+  );
+  await validateFixClaim(job);
+  await releaseLabels(deps, labels, issue.number);
+  return `#${issue.number}: opened draft PR #${prNumber}`;
+};
+
+export const finishFixedJob = async (
+  job: FixPublication & { readonly workspace: Workspace },
+  labels: JobLabels,
+  outcome: FixOutcome,
+): Promise<string> => {
+  const { deps, issue, workspace, branch } = job;
+  if (commitCount(workspace.dir, workspace.baseSha) === 0) {
+    await failJob(
+      deps,
+      labels,
+      issue.number,
+      'run reported "fixed" but produced no commits',
+    );
+    return `#${issue.number}: failed (fixed without commits)`;
+  }
+  const paths = changedPaths(workspace.dir, workspace.baseSha);
+  const forbidden = [
+    ...forbiddenDiffPaths(paths, await lockedPathsOf(workspace.dir)),
+    ...changedWorkspaceQualityManifests(
+      workspace.dir,
+      workspace.baseSha,
+      paths,
+    ),
+  ];
+  if (forbidden.length > 0) {
+    await failJob(
+      deps,
+      labels,
+      issue.number,
+      `the fix modified protected paths, which automation must never do:\n${forbidden.map((path) => `- ${path}`).join('\n')}`,
+    );
+    return `#${issue.number}: failed (protected paths: ${forbidden.join(', ')})`;
+  }
+  const sealed = sealFixOutput(workspace.dir, {
+    repo: deps.repo,
+    issueNumber: issue.number,
+    approvalId: job.claim.approval.id,
+    title: outcome.prTitle ?? '',
+    body: outcome.prBody ?? '',
+    baseSha: workspace.baseSha,
+    commits: commitCount(workspace.dir, workspace.baseSha),
+  });
+  return publishFixedOutput(job, labels, sealed, () =>
+    pushBranch(workspace.dir, {
+      repo: deps.repo,
+      branch,
+      token: deps.token,
+      expectedRemoteSha: '',
+    }),
+  );
+};