@davidvornholt/standards 0.10.2 → 0.11.1

package/src/poller-claim.ts

@@ -0,0 +1,154 @@
+import { randomUUID } from 'node:crypto';
+import { hasLabel } from './github-label-identity';
+import { type ApprovalBinding, readApprovalBinding } from './poller-approval';
+import {
+  collaboratorRole,
+  getIssue,
+  type IssueComment,
+  lastLabelEvent,
+  listIssueComments,
+} from './poller-github';
+import { createComment } from './poller-github-write';
+import { CLAIM_MARKER, isTrustedRole } from './poller-protocol';
+
+export type ClaimBinding = {
+  readonly approval: ApprovalBinding;
+  readonly claimLabel: string;
+  readonly claimEpoch: string;
+  readonly markerId: number;
+};
+
+type ClaimMarker = Omit<ClaimBinding, 'markerId'> & {
+  readonly nonce: string;
+};
+
+type ClaimContext = {
+  readonly token: string | null;
+  readonly repo: string;
+  readonly issueNumber: number;
+};
+
+const markerBody = (marker: ClaimMarker): string =>
+  `${CLAIM_MARKER}\n${JSON.stringify(marker)}`;
+
+const parseMarker = (comment: IssueComment): ClaimMarker | null => {
+  if (!comment.body.startsWith(`${CLAIM_MARKER}\n`)) {
+    return null;
+  }
+  try {
+    const raw = JSON.parse(comment.body.slice(CLAIM_MARKER.length + 1)) as {
+      readonly approval?: ApprovalBinding;
+      readonly claimLabel?: unknown;
+      readonly claimEpoch?: unknown;
+      readonly nonce?: unknown;
+    };
+    if (
+      typeof raw.claimLabel !== 'string' ||
+      typeof raw.claimEpoch !== 'string' ||
+      typeof raw.nonce !== 'string' ||
+      raw.approval === undefined ||
+      typeof raw.approval.id !== 'string'
+    ) {
+      return null;
+    }
+    return {
+      approval: raw.approval,
+      claimLabel: raw.claimLabel,
+      claimEpoch: raw.claimEpoch,
+      nonce: raw.nonce,
+    };
+  } catch {
+    return null;
+  }
+};
+
+const winningMarkerId = async (
+  context: ClaimContext,
+  binding: Omit<ClaimBinding, 'markerId'>,
+): Promise<number | null> => {
+  const comments = await listIssueComments(
+    context.token,
+    context.repo,
+    context.issueNumber,
+  );
+  let winner: number | null = null;
+  for (const comment of comments) {
+    const marker = parseMarker(comment);
+    const differs =
+      marker?.approval.id !== binding.approval.id ||
+      marker.claimLabel !== binding.claimLabel ||
+      marker.claimEpoch !== binding.claimEpoch;
+    if (!differs) {
+      // biome-ignore lint/performance/noAwaitInLoops: claim authors must be checked against their current role; the usually-one-item list is deliberately fail-closed.
+      const role = await collaboratorRole(
+        context.token,
+        context.repo,
+        comment.authorLogin,
+      );
+      if (isTrustedRole(role) && (winner === null || comment.id < winner)) {
+        winner = comment.id;
+      }
+    }
+  }
+  return winner;
+};
+
+export const acquireClaim = async (
+  context: ClaimContext,
+  approval: ApprovalBinding,
+  claimLabel: string,
+): Promise<ClaimBinding | null> => {
+  const event = await lastLabelEvent(
+    context.token,
+    context.repo,
+    context.issueNumber,
+    claimLabel,
+  );
+  if (event === null) {
+    throw new Error(`no "${claimLabel}" claim event found`);
+  }
+  const provisional = {
+    approval,
+    claimLabel,
+    claimEpoch: String(event.id),
+  };
+  const nonce = randomUUID();
+  const markerId = await createComment(
+    context.token,
+    context.repo,
+    context.issueNumber,
+    markerBody({ ...provisional, nonce }),
+  );
+  const winner = await winningMarkerId(context, provisional);
+  return winner === markerId ? { ...provisional, markerId } : null;
+};
+
+export const validateClaim = async (
+  context: ClaimContext,
+  claim: ClaimBinding,
+  currentTarget: string,
+): Promise<string | null> => {
+  const current = await readApprovalBinding(
+    context,
+    claim.approval.label,
+    currentTarget,
+  );
+  if (typeof current === 'string') {
+    return current;
+  }
+  if (current.id !== claim.approval.id) {
+    return 'approval no longer matches the exact approved revision/head';
+  }
+  const issue = await getIssue(
+    context.token,
+    context.repo,
+    context.issueNumber,
+  );
+  if (!hasLabel(issue.labels, claim.claimLabel)) {
+    return `"${claim.claimLabel}" is no longer present`;
+  }
+  const winner = await winningMarkerId(context, claim);
+  return winner === claim.markerId
+    ? null
+    : 'claim ownership changed or could not be proven';
+};

package/src/poller-codex.ts

@@ -0,0 +1,93 @@
+// Codex invocation for poller jobs. The agent runs headless inside the job
+// worktree and hands results back through the outcome file — never stdout,
+// which is unreliable once agent tools are active. The poller then verifies
+// effects (commits, diffs, gates) instead of trusting the narration.
+
+import { execFileSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { isRecord } from './github-settings-parse';
+import type { PollerConfig } from './poller-config';
+import { OUTCOME_DIR } from './poller-protocol';
+
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_MINUTE = SECONDS_PER_MINUTE * MS_PER_SECOND;
+const STDERR_SNIPPET_LIMIT = 2000;
+
+export type CodexRunResult = {
+  readonly succeeded: boolean;
+  readonly failure: string | null;
+};
+
+type CodexExecutor = (
+  file: string,
+  args: ReadonlyArray<string>,
+  options: {
+    readonly encoding: 'utf8';
+    readonly timeout: number;
+    readonly stdio: readonly ['ignore', 'ignore', 'pipe'];
+    readonly env: Record<string, string | undefined>;
+  },
+) => unknown;
+
+const defaultExecutor: CodexExecutor = execFileSync;
+
+// Remove the poller's direct GitHub token variables so an approved Codex run
+// cannot trivially bypass the protected-path and trust checks with API writes.
+// The shared service identity is not credential-isolated: auth state and other
+// ambient credentials in HOME remain readable as an explicitly accepted risk.
+const agentEnv = (): Record<string, string | undefined> => {
+  const env = { ...process.env };
+  env.GH_TOKEN = undefined;
+  env.GITHUB_TOKEN = undefined;
+  env.STANDARDS_POLLER_GIT_TOKEN = undefined;
+  return env;
+};
+
+export const runCodex = (
+  workDir: string,
+  prompt: string,
+  config: PollerConfig,
+  execute: CodexExecutor = defaultExecutor,
+): CodexRunResult => {
+  rmSync(join(workDir, OUTCOME_DIR), { recursive: true, force: true });
+  try {
+    execute(
+      'codex',
+      [
+        'exec',
+        '--cd',
+        workDir,
+        '--sandbox',
+        'workspace-write',
+        '-c',
+        'sandbox_workspace_write.network_access=true',
+        '-m',
+        config.model,
+        '-c',
+        `model_reasoning_effort=${JSON.stringify(config.reasoningEffort)}`,
+        ...config.extraCodexArgs,
+        prompt,
+      ],
+      {
+        encoding: 'utf8',
+        timeout: config.runTimeoutMinutes * MS_PER_MINUTE,
+        stdio: ['ignore', 'ignore', 'pipe'],
+        env: agentEnv(),
+      },
+    );
+    return { succeeded: true, failure: null };
+  } catch (error) {
+    const stderr =
+      isRecord(error) && typeof error.stderr === 'string'
+        ? error.stderr.slice(-STDERR_SNIPPET_LIMIT)
+        : '';
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      succeeded: false,
+      failure: `codex exec failed: ${message}\n${stderr}`,
+    };
+  }
+};

package/src/poller-commands.ts

@@ -0,0 +1,78 @@
+// CLI wiring for the poller command family. A tick is a gate-style command:
+// it reports what it did and fails loudly when any repository could not be
+// processed, so a red systemd unit is the durable signal that jobs stalled.
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { resolveToken } from './github-api';
+import { type PollerConfig, parsePollerConfig } from './poller-config';
+import { runPollerTick } from './poller-tick';
+import { runPollerPrintUnits } from './poller-units';
+
+export type PollerCommandOptions = {
+  readonly configPath: string | undefined;
+  readonly printUnits: boolean;
+};
+
+const loadConfig = async (configPath: string): Promise<PollerConfig> => {
+  const path = resolve(configPath);
+  if (!existsSync(path)) {
+    throw new Error(`poller config not found: ${path}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`poller config must contain valid JSON: ${path}`, {
+      cause: error,
+    });
+  }
+  const { config, problems } = parsePollerConfig(parsed, dirname(path));
+  if (config === null) {
+    throw new Error(
+      [
+        `invalid poller config ${path}:`,
+        ...problems.map((p) => `  - ${p}`),
+      ].join('\n'),
+    );
+  }
+  return config;
+};
+
+export const runPollerCommand = async (
+  options: PollerCommandOptions,
+): Promise<boolean> => {
+  if (options.configPath === undefined) {
+    console.error('standards poller: --config <path> is required');
+    return false;
+  }
+  // Every branch loads the config first: the units derive their tick budget
+  // from it, and a broken file must fail now, not on the first timer firing
+  // at 3am.
+  const config = await loadConfig(options.configPath);
+  if (options.printUnits) {
+    runPollerPrintUnits(options.configPath, config);
+    return true;
+  }
+  const token = resolveToken();
+  if (token === null) {
+    console.error(
+      'standards poller: no GitHub token (GH_TOKEN, GITHUB_TOKEN, or gh auth); the poller cannot label, push, or open PRs anonymously',
+    );
+    return false;
+  }
+  const { lines, problems } = await runPollerTick(config, token, Date.now());
+  for (const line of lines) {
+    console.log(`  ${line}`);
+  }
+  if (problems.length > 0) {
+    console.error(`standards poller: ${problems.length} problem(s):`);
+    console.error(problems.map((problem) => `  - ${problem}`).join('\n'));
+    return false;
+  }
+  console.log(
+    `standards poller: tick complete (${lines.length} event(s) across ${config.repos.length} repo(s))`,
+  );
+  return true;
+};

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;
+  }
+};