@davidvornholt/standards 0.10.2 → 0.11.0

package/src/poller-trust.ts

@@ -0,0 +1,96 @@
+// Trust decisions for poller jobs. Two questions, both answered from GitHub
+// state and repository roles, never from configuration: did a maintainer
+// approve this job, and which comments count as answers to the agent's
+// questions? Everything else on a public repository is untrusted text.
+
+import {
+  collaboratorRole,
+  type IssueComment,
+  listIssueComments,
+} from './poller-github';
+import { isTrustedRole, QUESTION_MARKER } from './poller-protocol';
+
+export type RoleCache = Map<string, string>;
+
+export type TrustContext = {
+  readonly token: string | null;
+  readonly repo: string;
+  readonly issueNumber: number;
+  readonly roleCache: RoleCache;
+};
+
+const cachedRole = async (
+  context: TrustContext,
+  username: string,
+): Promise<string> => {
+  const key = `${context.repo}:${username}`;
+  const cached = context.roleCache.get(key);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const role = await collaboratorRole(context.token, context.repo, username);
+  context.roleCache.set(key, role);
+  return role;
+};
+
+export type AnswerState = {
+  readonly waiting: boolean;
+  readonly answers: ReadonlyArray<string>;
+};
+
+const hasQuestionMarker = (comment: IssueComment): boolean =>
+  comment.body.includes(QUESTION_MARKER);
+
+// The marker is public, so a marker-bearing comment counts as the poller's
+// question only when its author is trusted (the poller posts with a
+// maintainer token). Otherwise anyone could re-post the marker after a real
+// answer and park the job in "waiting" forever.
+const lastTrustedQuestionIndex = async (
+  context: TrustContext,
+  comments: ReadonlyArray<IssueComment>,
+): Promise<number> => {
+  for (let index = comments.length - 1; index >= 0; index -= 1) {
+    const comment = comments[index];
+    if (comment !== undefined && hasQuestionMarker(comment)) {
+      // biome-ignore lint/performance/noAwaitInLoops: role lookups go through the shared per-tick cache; parallel lookups would race it and duplicate API reads.
+      const role = await cachedRole(context, comment.authorLogin);
+      if (isTrustedRole(role)) {
+        return index;
+      }
+    }
+  }
+  return -1;
+};
+
+// Answers are trusted-role comments posted after the poller's latest
+// question. With a question outstanding and no such comment yet, the job
+// waits; comments from anyone else are ignored entirely and never reach a
+// prompt.
+export const answerState = async (
+  context: TrustContext,
+): Promise<AnswerState> => {
+  const comments = await listIssueComments(
+    context.token,
+    context.repo,
+    context.issueNumber,
+  );
+  const lastQuestionIndex = await lastTrustedQuestionIndex(context, comments);
+  if (lastQuestionIndex === -1) {
+    return { waiting: false, answers: [] };
+  }
+  const answers: Array<string> = [];
+  const candidates = comments
+    .slice(lastQuestionIndex + 1)
+    .filter(
+      (comment) =>
+        !hasQuestionMarker(comment) && comment.authorLogin.length > 0,
+    );
+  for (const comment of candidates) {
+    // biome-ignore lint/performance/noAwaitInLoops: role lookups go through the shared per-tick cache; parallel lookups would race it and duplicate API reads.
+    const role = await cachedRole(context, comment.authorLogin);
+    if (isTrustedRole(role)) {
+      answers.push(comment.body);
+    }
+  }
+  return { waiting: answers.length === 0, answers };
+};

package/src/poller-units.ts

@@ -0,0 +1,82 @@
+// Declarative systemd unit rendering for the host infrastructure repository.
+// This command only prints content: host mutation belongs to trusted
+// main-branch automation in the repository that owns the polling host.
+
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import type { PollerConfig } from './poller-config';
+
+const SERVICE_NAME = 'standards-poller';
+const TICK_INTERVAL_MINUTES = 10;
+// Non-agent tick work: stale sweeps, clone/fetch, GitHub reads and writes.
+const TICK_OVERHEAD_MINUTES = 30;
+const MAX_ASCII_CONTROL_CODE = 31;
+const DELETE_CONTROL_CODE = 127;
+
+const cliEntryPath = (): string =>
+  fileURLToPath(new URL('cli.ts', import.meta.url));
+
+// systemd parses ExecStart itself rather than through a shell. Quote every
+// path as one token, escape its two expansion sigils, and reject control
+// characters instead of emitting a unit whose meaning differs from the path.
+export const quoteSystemdExecArg = (value: string): string => {
+  const hasControlCharacter = [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code <= MAX_ASCII_CONTROL_CODE || code === DELETE_CONTROL_CODE;
+  });
+  if (hasControlCharacter) {
+    throw new Error(
+      'systemd ExecStart arguments cannot contain control characters',
+    );
+  }
+  return `"${value
+    .replaceAll('\\', '\\\\')
+    .replaceAll('"', '\\"')
+    .replaceAll('$', '$$$$')
+    .replaceAll('%', '%%')}"`;
+};
+
+// The tick budget follows the config — every job may use the full agent
+// timeout — so raising "runTimeoutMinutes" or "maxJobsPerTick" cannot
+// silently outgrow the unit. Changing either means re-rendering the units.
+const tickBudgetMinutes = (config: PollerConfig): number =>
+  config.maxJobsPerTick * config.runTimeoutMinutes + TICK_OVERHEAD_MINUTES;
+
+export const renderUnits = (
+  configPath: string,
+  config: PollerConfig,
+): { readonly service: string; readonly timer: string } => ({
+  service: `[Unit]
+Description=Standards fix poller tick
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=${quoteSystemdExecArg(process.execPath)} ${quoteSystemdExecArg(cliEntryPath())} poller --config ${quoteSystemdExecArg(configPath)}
+TimeoutStartSec=${tickBudgetMinutes(config)}min
+`,
+  timer: `[Unit]
+Description=Run the standards fix poller on an interval
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=${TICK_INTERVAL_MINUTES}min
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`,
+});
+
+export const runPollerPrintUnits = (
+  configPath: string,
+  config: PollerConfig,
+): void => {
+  const units = renderUnits(resolve(configPath), config);
+  console.log(`# ${SERVICE_NAME}.service`);
+  console.log(units.service);
+  console.log(`# ${SERVICE_NAME}.timer`);
+  console.log(units.timer);
+};

package/src/poller-workspace.ts

@@ -0,0 +1,199 @@
+// Git workspace management for poller jobs: a bare clone per repository as
+// the local cache, plus a throwaway worktree per job. The token never appears
+// in argv or remote URLs — a credential helper reads it from the environment.
+// Deliberately not `--mirror`: mirror remotes refuse refspec pushes, and the
+// poller pushes exactly one branch per job.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+
+const TOKEN_ENV = 'STANDARDS_POLLER_GIT_TOKEN';
+const CREDENTIAL_HELPER = `!f() { echo username=x-access-token; echo "password=$${TOKEN_ENV}"; }; f`;
+const MS_PER_SECOND = 1000;
+const GIT_TIMEOUT_SECONDS = 600;
+const GIT_TIMEOUT_MS = GIT_TIMEOUT_SECONDS * MS_PER_SECOND;
+const fetchRefspec = '+refs/heads/*:refs/heads/*';
+
+export const githubRepoUrl = (repo: string): string =>
+  `https://github.com/${repo}.git`;
+
+export type Workspace = {
+  readonly dir: string;
+  readonly baseSha: string;
+  readonly cleanup: () => void;
+};
+
+export const runGit = (
+  args: ReadonlyArray<string>,
+  token: string | null,
+): string =>
+  execFileSync('git', [...args], {
+    encoding: 'utf8',
+    timeout: GIT_TIMEOUT_MS,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: {
+      ...process.env,
+      ...(token === null ? {} : { [TOKEN_ENV]: token }),
+      // biome-ignore lint/style/useNamingConvention: environment variable names are defined by git.
+      GIT_TERMINAL_PROMPT: '0',
+    },
+  });
+
+const authedGit = (
+  cloneDir: string,
+  args: ReadonlyArray<string>,
+  token: string | null,
+): string =>
+  runGit(
+    [
+      '-C',
+      cloneDir,
+      '-c',
+      'credential.helper=',
+      '-c',
+      `credential.helper=${CREDENTIAL_HELPER}`,
+      ...args,
+    ],
+    token,
+  );
+
+// Fetch (or first create) the bare cache clone for a repository and return
+// its path. Bare clones carry no fetch refspec by default, so one is set
+// explicitly; every branch ref stays local so worktrees can base on any ref.
+export const ensureCacheClone = (
+  cacheDir: string,
+  repo: string,
+  token: string | null,
+): string => {
+  const cloneDir = join(cacheDir, `${repo}.git`);
+  if (!existsSync(cloneDir)) {
+    mkdirSync(cacheDir, { recursive: true });
+    runGit(
+      [
+        '-c',
+        'credential.helper=',
+        '-c',
+        `credential.helper=${CREDENTIAL_HELPER}`,
+        'clone',
+        '--bare',
+        githubRepoUrl(repo),
+        cloneDir,
+      ],
+      token,
+    );
+    runGit(
+      ['-C', cloneDir, 'config', 'remote.origin.fetch', fetchRefspec],
+      null,
+    );
+  }
+  runGit(
+    ['-C', cloneDir, 'remote', 'set-url', 'origin', githubRepoUrl(repo)],
+    null,
+  );
+  authedGit(
+    cloneDir,
+    ['fetch', '--prune', githubRepoUrl(repo), fetchRefspec],
+    token,
+  );
+  return cloneDir;
+};
+
+// A leaked worktree from a killed run must not wedge its job forever: remove
+// any stale registration for this path before adding the new one.
+export const createWorktree = (
+  cloneDir: string,
+  startRef: string,
+  branch: string,
+  workDir: string,
+): Workspace => {
+  try {
+    runGit(['-C', cloneDir, 'worktree', 'remove', '--force', workDir], null);
+  } catch {
+    rmSync(workDir, { recursive: true, force: true });
+    runGit(['-C', cloneDir, 'worktree', 'prune'], null);
+  }
+  const baseSha = runGit(['-C', cloneDir, 'rev-parse', startRef], null).trim();
+  runGit(
+    ['-C', cloneDir, 'worktree', 'add', '--detach', workDir, baseSha],
+    null,
+  );
+  runGit(['-C', workDir, 'checkout', '-B', branch, baseSha], null);
+  const cleanup = (): void => {
+    try {
+      runGit(['-C', cloneDir, 'worktree', 'remove', '--force', workDir], null);
+    } catch {
+      rmSync(workDir, { recursive: true, force: true });
+      runGit(['-C', cloneDir, 'worktree', 'prune'], null);
+    }
+  };
+  return { dir: workDir, baseSha, cleanup };
+};
+
+export const mergeBase = (
+  cloneDir: string,
+  refA: string,
+  refB: string,
+): string => runGit(['-C', cloneDir, 'merge-base', refA, refB], null).trim();
+
+export const commitCount = (workDir: string, baseSha: string): number =>
+  Number.parseInt(
+    runGit(['-C', workDir, 'rev-list', '--count', `${baseSha}..HEAD`], null),
+    10,
+  );
+
+export const headSha = (workDir: string): string =>
+  runGit(['-C', workDir, 'rev-parse', 'HEAD'], null).trim();
+
+export const localBranchExists = (
+  cloneDir: string,
+  branch: string,
+): boolean => {
+  try {
+    runGit(
+      ['-C', cloneDir, 'show-ref', '--verify', `refs/heads/${branch}`],
+      null,
+    );
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const changedPaths = (
+  workDir: string,
+  baseSha: string,
+): ReadonlyArray<string> =>
+  runGit(['-C', workDir, 'diff', '--name-only', baseSha, 'HEAD'], null)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+// Review branches are fast-forward-only. New poller-owned fix branches use an
+// explicit "expected absent" lease, so a pre-existing ref is never overwritten.
+export const pushBranch = (
+  workDir: string,
+  options: {
+    readonly repo: string;
+    readonly branch: string;
+    readonly token: string | null;
+    readonly expectedRemoteSha?: string;
+    readonly sourceRef?: string;
+  },
+): void => {
+  authedGit(
+    workDir,
+    [
+      'push',
+      ...(options.expectedRemoteSha === undefined
+        ? []
+        : [
+            `--force-with-lease=refs/heads/${options.branch}:${options.expectedRemoteSha}`,
+          ]),
+      githubRepoUrl(options.repo),
+      `${options.sourceRef ?? 'HEAD'}:refs/heads/${options.branch}`,
+    ],
+    options.token,
+  );
+};