@davidvornholt/standards 0.10.2 → 0.11.0

package/src/github-settings-parse.ts

@@ -4,21 +4,34 @@
 // github-diff.ts, and the API interaction in github-api.ts. Like cli.ts, this
 // module is zero-dependency so `bunx` can execute the published package.
 
+import { labelIdentity } from './github-label-identity';
+
 // GitHub only enforces rulesets on private repositories on paid plans. The
 // seam can declare that fact so the gate skips rulesets loudly instead of
 // failing closed forever (personal accounts) or trusting rulesets the API
 // reports as active but a free-plan organization silently does not enforce.
 export type RulesetEnforcement = 'enforced' | 'unavailable-on-plan';
 
+// Declared issue labels are an additive floor like rulesets: declared labels
+// must exist with the declared color and description; extra live labels are
+// not drift. The fix-poller protocol labels ride this seam to every consumer.
+export type LabelDeclaration = {
+  readonly name: string;
+  readonly color: string;
+  readonly description: string;
+};
+
 export type GithubSettings = {
   readonly repository: Readonly<Record<string, unknown>>;
   readonly rulesets: ReadonlyArray<Readonly<Record<string, unknown>>>;
+  readonly labels: ReadonlyArray<LabelDeclaration>;
   readonly rulesetEnforcement: RulesetEnforcement;
 };
 
 export type ParsedGithubSettings = {
   readonly repository: Readonly<Record<string, unknown>> | null;
   readonly rulesets: ReadonlyArray<unknown> | null;
+  readonly labels: ReadonlyArray<unknown> | null;
   readonly rulesetEnforcement: RulesetEnforcement | null;
 };
 
@@ -33,9 +46,21 @@ export const isNamedRuleset = (
 ): value is Readonly<Record<string, unknown>> & { readonly name: string } =>
   isRecord(value) && typeof value.name === 'string' && value.name.length > 0;
 
+const LABEL_COLOR = /^[0-9a-f]{6}$/u;
+const LABEL_DECLARATION_KEY_COUNT = 3;
+
+export const isLabelDeclaration = (value: unknown): value is LabelDeclaration =>
+  isRecord(value) &&
+  Object.keys(value).length === LABEL_DECLARATION_KEY_COUNT &&
+  isNonEmptyString(value.name) &&
+  typeof value.color === 'string' &&
+  LABEL_COLOR.test(value.color) &&
+  isNonEmptyString(value.description);
+
 export const SETTINGS_KEYS: ReadonlySet<string> = new Set([
   'repository',
   'rulesets',
+  'labels',
 ]);
 export const LOCAL_SETTINGS_KEYS: ReadonlySet<string> = new Set([
   ...SETTINGS_KEYS,
@@ -78,6 +103,51 @@ const rulesetListProblems = (
   return problems;
 };
 
+const labelListProblems = (
+  labels: ReadonlyArray<unknown>,
+  label: string,
+): ReadonlyArray<string> => {
+  const problems: Array<string> = [];
+  const names = new Set<string>();
+  for (const [index, declaration] of labels.entries()) {
+    if (!isLabelDeclaration(declaration)) {
+      problems.push(
+        `${label} labels[${index}] must be {"name","color","description"} with a non-empty name, a 6-digit lowercase hex color, and a non-empty description`,
+      );
+    } else if (names.has(labelIdentity(declaration.name))) {
+      problems.push(
+        `${label} declares label "${declaration.name}" more than once`,
+      );
+    } else {
+      names.add(labelIdentity(declaration.name));
+    }
+  }
+  return problems;
+};
+
+type ListField = {
+  readonly label: string;
+  readonly field: string;
+  readonly listProblems: (
+    list: ReadonlyArray<unknown>,
+    label: string,
+  ) => ReadonlyArray<string>;
+};
+
+const parseDeclarationList = (
+  raw: unknown,
+  options: ListField,
+  problems: Array<string>,
+): ReadonlyArray<unknown> | null => {
+  const list = raw ?? [];
+  if (!Array.isArray(list)) {
+    problems.push(`${options.label} "${options.field}" must be an array`);
+    return null;
+  }
+  problems.push(...options.listProblems(list, options.label));
+  return list;
+};
+
 export const parseSettings = (
   raw: unknown,
   label: string,
@@ -96,12 +166,16 @@ export const parseSettings = (
   if (!isRecord(repository)) {
     problems.push(`${label} "repository" must be an object`);
   }
-  const rulesets = raw.rulesets ?? [];
-  if (Array.isArray(rulesets)) {
-    problems.push(...rulesetListProblems(rulesets, label));
-  } else {
-    problems.push(`${label} "rulesets" must be an array`);
-  }
+  const rulesets = parseDeclarationList(
+    raw.rulesets,
+    { label, field: 'rulesets', listProblems: rulesetListProblems },
+    problems,
+  );
+  const labels = parseDeclarationList(
+    raw.labels,
+    { label, field: 'labels', listProblems: labelListProblems },
+    problems,
+  );
   // Only the opt-out value is accepted: enforcement is the default, and an
   // explicit "enforced" would be a second way to spell the same state.
   if (
@@ -115,7 +189,8 @@ export const parseSettings = (
   return {
     settings: {
       repository: isRecord(repository) ? repository : null,
-      rulesets: Array.isArray(rulesets) ? rulesets : null,
+      rulesets,
+      labels,
       rulesetEnforcement: parseRulesetEnforcement(raw.rulesetEnforcement),
     },
     problems,

package/src/github-settings.ts

@@ -1,12 +1,12 @@
-// Merge canonical GitHub settings with the repo-owned extension. Parsing,
-// drift, and API work live in named modules; this stays dependency-free.
+// Load and merge canonical GitHub settings with the repo-owned extension.
+// Parsing lives in github-settings-parse.ts, merge policy in
+// github-settings-merge.ts, drift in github-diff.ts, and API work in
+// github-api.ts; this stays dependency-free.
 
+import { mergeSettings } from './github-settings-merge';
 import {
-  ENFORCEMENT_OPT_OUT,
   type GithubSettings,
-  isNamedRuleset,
   LOCAL_SETTINGS_KEYS,
-  type ParsedGithubSettings,
   parseSettings,
   SETTINGS_KEYS,
 } from './github-settings-parse';
@@ -16,124 +16,6 @@ export type LoadedGithubSettings = {
   readonly problems: ReadonlyArray<string>;
 };
 
-const completeSettings = (
-  parsed: ParsedGithubSettings | null,
-): GithubSettings | null => {
-  if (
-    parsed === null ||
-    parsed.repository === null ||
-    parsed.rulesets === null ||
-    parsed.rulesetEnforcement === null
-  ) {
-    return null;
-  }
-  const rulesets = parsed.rulesets.filter(isNamedRuleset);
-  if (rulesets.length !== parsed.rulesets.length) {
-    return null;
-  }
-  return {
-    repository: parsed.repository,
-    rulesets,
-    rulesetEnforcement: parsed.rulesetEnforcement,
-  };
-};
-
-const enforcementMergeProblems = (
-  local: ParsedGithubSettings | null,
-): ReadonlyArray<string> => {
-  if (
-    local?.rulesetEnforcement !== ENFORCEMENT_OPT_OUT ||
-    local.rulesets === null ||
-    local.rulesets.length === 0
-  ) {
-    return [];
-  }
-  return [
-    `.github/settings.local.json declares additional rulesets while "rulesetEnforcement" is "${ENFORCEMENT_OPT_OUT}"; remove the rulesets or the opt-out`,
-  ];
-};
-
-const repositoryMergeProblems = (
-  canonical: ParsedGithubSettings | null,
-  local: ParsedGithubSettings | null,
-): ReadonlyArray<string> => {
-  if (
-    canonical === null ||
-    canonical.repository === null ||
-    local === null ||
-    local.repository === null
-  ) {
-    return [];
-  }
-  const canonicalRepository = canonical.repository;
-  return Object.keys(local.repository)
-    .filter((key) => key in canonicalRepository)
-    .map(
-      (key) =>
-        `.github/settings.local.json repository."${key}" would override a canonical value; canonical settings are read-only`,
-    );
-};
-
-const rulesetMergeProblems = (
-  canonical: ParsedGithubSettings | null,
-  local: ParsedGithubSettings | null,
-): ReadonlyArray<string> => {
-  if (
-    canonical === null ||
-    canonical.rulesets === null ||
-    local === null ||
-    local.rulesets === null
-  ) {
-    return [];
-  }
-  const canonicalNames = new Set(
-    canonical.rulesets.filter(isNamedRuleset).map((ruleset) => ruleset.name),
-  );
-  return local.rulesets
-    .filter(isNamedRuleset)
-    .filter((ruleset) => canonicalNames.has(ruleset.name))
-    .map(
-      (ruleset) =>
-        `.github/settings.local.json ruleset "${ruleset.name}" collides with a canonical ruleset; add a separately named ruleset to tighten further`,
-    );
-};
-
-// The seam may only add. Overriding a canonical repository key or redefining a
-// canonical ruleset could weaken the canonical floor; GitHub layers multiple
-// rulesets strictest-wins, so adding a ruleset is always safe. The one
-// subtractive declaration is the ruleset-enforcement opt-out, which skips the
-// ruleset gate entirely rather than weakening any single rule.
-const mergeSettings = (
-  canonical: ParsedGithubSettings | null,
-  local: ParsedGithubSettings | null,
-) => {
-  const problems = [
-    ...enforcementMergeProblems(local),
-    ...repositoryMergeProblems(canonical, local),
-    ...rulesetMergeProblems(canonical, local),
-  ];
-  const completeCanonical = completeSettings(canonical);
-  const completeLocal = completeSettings(local);
-  if (
-    problems.length > 0 ||
-    completeCanonical === null ||
-    completeLocal === null
-  ) {
-    return { merged: null, problems };
-  }
-  return {
-    merged: {
-      repository: {
-        ...completeCanonical.repository,
-        ...completeLocal.repository,
-      },
-      rulesets: [...completeCanonical.rulesets, ...completeLocal.rulesets],
-      rulesetEnforcement: completeLocal.rulesetEnforcement,
-    },
-    problems: [],
-  };
-};
-
 type JsonParse = {
   readonly value: unknown;
   readonly problem: string | null;

package/src/poller-approval.ts

@@ -0,0 +1,80 @@
+import { createHash } from 'node:crypto';
+import { hasLabel } from './github-label-identity';
+import {
+  collaboratorRole,
+  getIssue,
+  type IssueItem,
+  lastLabelEvent,
+} from './poller-github';
+import { isTrustedRole } from './poller-protocol';
+
+export type ApprovalBinding = {
+  readonly id: string;
+  readonly repo: string;
+  readonly issueNumber: number;
+  readonly eventId: number;
+  readonly label: string;
+  readonly actorLogin: string;
+  readonly approvedAt: string;
+  readonly target: string;
+};
+
+type ApprovalContext = {
+  readonly token: string | null;
+  readonly repo: string;
+  readonly issueNumber: number;
+};
+
+const stableDigest = (value: unknown): string =>
+  createHash('sha256').update(JSON.stringify(value)).digest('hex');
+
+export const issueRevision = (issue: IssueItem): string =>
+  `issue:${stableDigest({ title: issue.title, body: issue.body })}`;
+
+export const prRevision = (
+  baseRef: string,
+  baseSha: string,
+  headSha: string,
+): string => `pr:${stableDigest({ baseRef, baseSha, headSha })}`;
+
+export const readApprovalBinding = async (
+  context: ApprovalContext,
+  label: string,
+  target: string,
+): Promise<ApprovalBinding | string> => {
+  const issue = await getIssue(
+    context.token,
+    context.repo,
+    context.issueNumber,
+  );
+  if (!hasLabel(issue.labels, label)) {
+    return `"${label}" is not currently present on ${context.repo}#${context.issueNumber}`;
+  }
+  const event = await lastLabelEvent(
+    context.token,
+    context.repo,
+    context.issueNumber,
+    label,
+  );
+  if (event === null) {
+    return `no "${label}" label event found on ${context.repo}#${context.issueNumber}`;
+  }
+  const role = await collaboratorRole(
+    context.token,
+    context.repo,
+    event.actorLogin,
+  );
+  if (!isTrustedRole(role)) {
+    return `"${label}" on ${context.repo}#${context.issueNumber} was applied by ${event.actorLogin} (role: ${role}); only admin or maintain roles may approve automation`;
+  }
+  const fields = {
+    repo: context.repo,
+    issueNumber: context.issueNumber,
+    eventId: event.id,
+    label,
+    actorLogin: event.actorLogin,
+    approvedAt: event.createdAt,
+    target,
+  };
+  return { id: stableDigest(fields), ...fields };
+};

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