@davidvornholt/standards 0.13.0 → 0.14.1

package/src/creds-sops.ts

@@ -0,0 +1,198 @@
+// SOPS reads inspect only plaintext key structure. Writes use a non-
+// interactive editor so values never touch argv, stdout, or an unencrypted
+// file outside SOPS's own temporary-file handling.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import {
+  type SopsValueChange as EditorValueChange,
+  inspectSopsScalarStructure,
+  SET_CHANGES_ENV,
+  type SopsScalarStructureResult,
+} from './creds-sops-editor';
+import {
+  inspectSopsStructure,
+  isContainedSopsPath,
+  parseSopsKeyPath,
+  type SopsShapeFailure,
+} from './creds-sops-structure';
+import { runSops } from './sops-exec';
+
+export type { SopsValueChange } from './creds-sops-editor';
+
+const SOPS_UNCHANGED_STATUS = 200;
+type ReadError = {
+  readonly ok: false;
+  readonly kind: 'read-error';
+  readonly problem: string;
+};
+type ReadFailure = SopsShapeFailure | ReadError;
+export type EncryptedKeysReadResult =
+  | { readonly ok: true; readonly keys: ReadonlyArray<string> }
+  | ReadFailure;
+export type SopsScalarDestinationResult = SopsScalarStructureResult | ReadError;
+export type SopsWriteResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly problem: string };
+export type SopsStoredValueVerification =
+  | { readonly ok: true; readonly matches: boolean }
+  | { readonly ok: false; readonly problem: string };
+type SopsStoredValueInput = {
+  readonly consumer: string;
+  readonly rel: string;
+  readonly dottedPath: string;
+  readonly expectedValue: string;
+};
+
+export const listEncryptedKeys = (text: string): EncryptedKeysReadResult => {
+  const result = inspectSopsStructure(text, true);
+  return result.ok ? { ok: true, keys: result.keys } : result;
+};
+
+export const readEncryptedKeys = async (
+  consumer: string,
+  rel: string,
+): Promise<EncryptedKeysReadResult> => {
+  if (!isContainedSopsPath(consumer, rel, 'file')) {
+    return {
+      ok: false,
+      kind: 'read-error',
+      problem: `unsafe encrypted secrets target ${rel}`,
+    };
+  }
+  try {
+    return listEncryptedKeys(await readFile(join(consumer, rel), 'utf8'));
+  } catch {
+    return {
+      ok: false,
+      kind: 'read-error',
+      problem: `could not read encrypted secrets target ${rel}`,
+    };
+  }
+};
+
+export const inspectSopsScalarDestination = async (
+  consumer: string,
+  rel: string,
+  dottedPath: string,
+): Promise<SopsScalarDestinationResult> => {
+  if (!isContainedSopsPath(consumer, rel, 'file')) {
+    return {
+      ok: false,
+      kind: 'read-error',
+      problem: `unsafe encrypted secrets target ${rel}`,
+    };
+  }
+  try {
+    const text = await readFile(join(consumer, rel), 'utf8');
+    return inspectSopsScalarStructure(
+      inspectSopsStructure(text, true),
+      dottedPath,
+    );
+  } catch {
+    return {
+      ok: false,
+      kind: 'read-error',
+      problem: `could not read encrypted secrets target ${rel}`,
+    };
+  }
+};
+
+export const verifySopsScalarLeaf = async (
+  consumer: string,
+  rel: string,
+  dottedPath: string,
+): Promise<SopsWriteResult> => {
+  const result = await inspectSopsScalarDestination(consumer, rel, dottedPath);
+  return result.ok && result.state === 'scalar'
+    ? { ok: true }
+    : {
+        ok: false,
+        problem: result.ok
+          ? `SOPS write did not create ${dottedPath} in ${rel}`
+          : result.problem,
+      };
+};
+
+const editorCommand = (): string => {
+  const editor = fileURLToPath(
+    new URL('./creds-sops-editor.ts', import.meta.url),
+  );
+  return `"${process.execPath}" "${editor}"`;
+};
+
+export const verifySopsStoredValueWith = (
+  runner: typeof runSops,
+  input: SopsStoredValueInput,
+): SopsStoredValueVerification => {
+  const { consumer, rel, dottedPath, expectedValue } = input;
+  const path = parseSopsKeyPath(dottedPath);
+  const problem = `could not verify stored SOPS value at ${dottedPath} in ${rel}`;
+  if (path === null || !isContainedSopsPath(consumer, rel, 'file')) {
+    return { ok: false, problem };
+  }
+  const extract = path
+    .map((segment) => `[${JSON.stringify(segment)}]`)
+    .join('');
+  const result = runner(
+    ['decrypt', '--extract', extract, '--output-type', 'json', rel],
+    consumer,
+  );
+  if (result.status !== 0) {
+    return { ok: false, problem };
+  }
+  try {
+    const stored: unknown = JSON.parse(result.stdout);
+    return typeof stored === 'string'
+      ? { ok: true, matches: stored === expectedValue }
+      : { ok: false, problem };
+  } catch {
+    return { ok: false, problem };
+  }
+};
+
+export const verifySopsStoredValue = (
+  consumer: string,
+  rel: string,
+  dottedPath: string,
+  expectedValue: string,
+): SopsStoredValueVerification =>
+  verifySopsStoredValueWith(runSops, {
+    consumer,
+    rel,
+    dottedPath,
+    expectedValue,
+  });
+
+export const setSopsValues = (
+  consumer: string,
+  rel: string,
+  changes: ReadonlyArray<EditorValueChange>,
+): SopsWriteResult => {
+  if (!isContainedSopsPath(consumer, rel, 'file')) {
+    return { ok: false, problem: `unsafe encrypted secrets target ${rel}` };
+  }
+  const result = runSops(['edit', rel], consumer, {
+    // biome-ignore lint/style/useNamingConvention: sops defines this environment variable.
+    SOPS_EDITOR: editorCommand(),
+    [SET_CHANGES_ENV]: JSON.stringify(changes),
+  });
+  if (result.status === 0 || result.status === SOPS_UNCHANGED_STATUS) {
+    return { ok: true };
+  }
+  const paths = changes.map(({ path }) => path).join(', ');
+  const detail = result.errorMessage ?? result.stderr.trim();
+  return {
+    ok: false,
+    problem: `could not write ${paths} into ${rel}${detail ? `: ${detail}` : ''}`,
+  };
+};
+
+export const setSopsValue = (
+  consumer: string,
+  rel: string,
+  path: string,
+  value: string,
+): SopsWriteResult => setSopsValues(consumer, rel, [{ path, value }]);

package/src/creds-store-lock.ts

@@ -0,0 +1,102 @@
+// Broker store lock: a mkdir-based mutex serializing read-modify-write
+// cycles on broker.yaml. Store writes are sub-second, so a lock directory
+// older than the staleness window can only belong to a dead process and is
+// broken automatically; the timeout error names the directory and the manual
+// remediation for the pathological rest.
+
+import { mkdir, rmdir, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { isRecord } from './github-settings-parse';
+
+const OWNER_ONLY_DIR_MODE = 0o700;
+
+export type BrokerLockOptions = {
+  readonly retryMs?: number;
+  readonly timeoutMs?: number;
+  readonly staleMs?: number;
+};
+
+const DEFAULT_RETRY_MS = 25;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_MS = 30_000;
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+const tryAcquire = async (lockPath: string): Promise<boolean> => {
+  try {
+    await mkdir(lockPath, { mode: OWNER_ONLY_DIR_MODE });
+    return true;
+  } catch (error) {
+    if (isRecord(error) && error.code === 'EEXIST') {
+      return false;
+    }
+    throw error;
+  }
+};
+
+// True when the contender may immediately retry: the lock vanished, or it
+// was stale and this process removed it (losing the removal race to another
+// contender also lands here — the retry's mkdir arbitrates).
+const breakIfStale = async (
+  lockPath: string,
+  staleMs: number,
+): Promise<boolean> => {
+  try {
+    const info = await stat(lockPath);
+    if (Date.now() - info.mtimeMs < staleMs) {
+      return false;
+    }
+    await rmdir(lockPath);
+    return true;
+  } catch {
+    return true;
+  }
+};
+
+// One acquisition attempt: acquired, or cleared a stale/vanished lock (retry
+// immediately), or waited one retry slot; a live lock past the deadline
+// throws with the remediation hint.
+const attemptAcquire = async (
+  lockPath: string,
+  staleMs: number,
+  retryMs: number,
+  deadline: number,
+): Promise<boolean> => {
+  if (await tryAcquire(lockPath)) {
+    return true;
+  }
+  if (await breakIfStale(lockPath, staleMs)) {
+    return false;
+  }
+  if (Date.now() >= deadline) {
+    throw new Error(
+      `lock timeout: another creds process holds ${lockPath}; if none is running, remove that directory and retry`,
+    );
+  }
+  await sleep(retryMs);
+  return false;
+};
+
+export const withBrokerLock = async <T>(
+  path: string,
+  operation: () => Promise<T>,
+  options: BrokerLockOptions = {},
+): Promise<T> => {
+  const retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+  const lockPath = `${path}.lock`;
+  await mkdir(dirname(path), { recursive: true, mode: OWNER_ONLY_DIR_MODE });
+  const deadline = Date.now() + timeoutMs;
+  let acquired = false;
+  while (!acquired) {
+    // biome-ignore lint/performance/noAwaitInLoops: lock acquisition retries are inherently sequential.
+    acquired = await attemptAcquire(lockPath, staleMs, retryMs, deadline);
+  }
+  try {
+    return await operation();
+  } finally {
+    await rmdir(lockPath);
+  }
+};

package/src/creds-store.ts

@@ -0,0 +1,199 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, statSync } from 'node:fs';
+import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import process from 'node:process';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { isCloudflareAccountId } from './creds-cloudflare-account';
+import { withBrokerLock } from './creds-store-lock';
+import { isNonEmptyString, isRecord } from './github-settings-parse';
+export type GithubBrokerApp = {
+  readonly appId: number;
+  readonly slug: string;
+  readonly htmlUrl: string;
+  readonly clientId: string;
+  readonly privateKey: string;
+};
+export type CloudflareBrokerAccount = Readonly<
+  Record<'accountId' | 'token', string>
+>;
+export type BrokerStore = {
+  readonly github: GithubBrokerApp | null;
+  readonly cloudflare: ReadonlyArray<CloudflareBrokerAccount>;
+};
+export const EMPTY_BROKER_STORE: BrokerStore = { github: null, cloudflare: [] };
+const OWNER_ONLY_FILE_MODE = 0o600;
+const OWNER_ONLY_DIR_MODE = 0o700;
+const FILE_MODE_MODULUS = 0o1000;
+const GROUP_OTHER_MODULUS = 0o100;
+const OCTAL_RADIX = 8;
+export const inspectBrokerFileMode = (path: string) => {
+  try {
+    const mode = statSync(path).mode % FILE_MODE_MODULUS;
+    return {
+      exists: true,
+      problem:
+        mode % GROUP_OTHER_MODULUS === 0
+          ? null
+          : `mode ${mode.toString(OCTAL_RADIX)} is broader than 0600; tighten with chmod 600`,
+    };
+  } catch {
+    return { exists: false, problem: null };
+  }
+};
+export const resolveBrokerPath = (): string =>
+  process.env.STANDARDS_BROKER_FILE ??
+  join(
+    process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'),
+    'standards/broker.yaml',
+  );
+const parseGithub = (raw: unknown): GithubBrokerApp | null => {
+  if (raw === undefined || raw === null) {
+    return null;
+  }
+  if (
+    !isRecord(raw) ||
+    typeof raw.app_id !== 'number' ||
+    !Number.isInteger(raw.app_id) ||
+    !isNonEmptyString(raw.slug) ||
+    !isNonEmptyString(raw.html_url) ||
+    !isNonEmptyString(raw.client_id) ||
+    !isNonEmptyString(raw.private_key)
+  ) {
+    throw new Error('invalid github: run `standards creds login github`');
+  }
+  return {
+    appId: raw.app_id,
+    slug: raw.slug,
+    htmlUrl: raw.html_url,
+    clientId: raw.client_id,
+    privateKey: raw.private_key,
+  };
+};
+const validateCloudflareAccounts = (
+  accounts: ReadonlyArray<CloudflareBrokerAccount>,
+  path: string,
+): ReadonlyArray<CloudflareBrokerAccount> => {
+  const accountIds = new Set<string>();
+  for (const account of accounts) {
+    if (!isCloudflareAccountId(account.accountId)) {
+      throw new Error(
+        `${path}: Cloudflare account_id must be exactly 32 lowercase hexadecimal characters`,
+      );
+    }
+    if (!isNonEmptyString(account.token)) {
+      throw new Error(
+        'invalid cloudflare: run `standards creds login cloudflare`',
+      );
+    }
+    if (accountIds.has(account.accountId)) {
+      throw new Error(
+        `${path}: duplicate Cloudflare account ${account.accountId}; keep one bootstrap credential per account`,
+      );
+    }
+    accountIds.add(account.accountId);
+  }
+  return accounts;
+};
+const parseCloudflare = (
+  raw: unknown,
+  path: string,
+): ReadonlyArray<CloudflareBrokerAccount> => {
+  if (raw === undefined || raw === null) {
+    return [];
+  }
+  if (!Array.isArray(raw)) {
+    throw new Error(`${path}: "cloudflare" must be a list of accounts`);
+  }
+  const accounts = raw.map((entry) => {
+    const valid =
+      isRecord(entry) &&
+      isNonEmptyString(entry.account_id) &&
+      isNonEmptyString(entry.token);
+    if (!valid) {
+      throw new Error(
+        'invalid cloudflare: run `standards creds login cloudflare`',
+      );
+    }
+    return { accountId: String(entry.account_id), token: String(entry.token) };
+  });
+  return validateCloudflareAccounts(accounts, path);
+};
+export const readBrokerStore = async (path: string): Promise<BrokerStore> => {
+  const raw = existsSync(path)
+    ? (parseYaml(await readFile(path, 'utf8')) as unknown)
+    : null;
+  if (raw === null || raw === undefined) {
+    return EMPTY_BROKER_STORE;
+  }
+  if (!isRecord(raw)) {
+    throw new Error(`${path} must contain a YAML mapping`);
+  }
+  return {
+    github: parseGithub(raw.github),
+    cloudflare: parseCloudflare(raw.cloudflare, path),
+  };
+};
+export const updateBrokerStore = async (
+  path: string,
+  update: (store: BrokerStore) => BrokerStore | Promise<BrokerStore>,
+  sync: typeof syncDirectory = syncDirectory,
+): Promise<void> =>
+  withBrokerLock(path, async () => {
+    const store = await update(await readBrokerStore(path));
+    validateCloudflareAccounts(store.cloudflare, path);
+    await writeBrokerStoreUnlocked(path, store, sync);
+  });
+const storeDocument = (store: BrokerStore): unknown => ({
+  ...(store.github === null
+    ? {}
+    : {
+        github: {
+          app_id: store.github.appId,
+          slug: store.github.slug,
+          html_url: store.github.htmlUrl,
+          client_id: store.github.clientId,
+          private_key: store.github.privateKey,
+        },
+      }),
+  ...(store.cloudflare.length === 0
+    ? {}
+    : {
+        cloudflare: store.cloudflare.map((account) => ({
+          account_id: account.accountId,
+          token: account.token,
+        })),
+      }),
+});
+const syncDirectory = async (path: string): Promise<void> => {
+  const handle = await open(path, 'r');
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+};
+const writeBrokerStoreUnlocked = async (
+  path: string,
+  store: BrokerStore,
+  sync: typeof syncDirectory,
+): Promise<void> => {
+  const parent = dirname(path);
+  await mkdir(parent, { recursive: true, mode: OWNER_ONLY_DIR_MODE });
+  const temporary = join(parent, `.${basename(path)}.${randomUUID()}.tmp`);
+  const handle = await open(temporary, 'wx', OWNER_ONLY_FILE_MODE);
+  try {
+    try {
+      await handle.writeFile(stringifyYaml(storeDocument(store)), 'utf8');
+      await handle.chmod(OWNER_ONLY_FILE_MODE);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, path);
+    await sync(parent);
+  } finally {
+    await unlink(temporary).catch(() => undefined);
+  }
+};

package/src/dev-env.ts

@@ -8,6 +8,7 @@ import {
 import { parseDevEnvDocument } from './dev-env-document';
 import { renderDotenv } from './dev-env-dotenv';
 import { writeDevEnvFiles } from './dev-env-transaction';
+import { runSops } from './sops-exec';
 
 export const DEV_SECRETS_FILE = 'secrets/dev.yaml';
 
@@ -17,30 +18,11 @@ type DecryptResult =
   | { readonly ok: true; readonly value: unknown }
   | { readonly ok: false; readonly problem: string };
 
-// sops emits JSON here so the CLI never parses the encrypted YAML itself; the
-// nix fallback mirrors the canonical secrets.just tool resolution.
+// sops emits JSON here so the CLI never parses the encrypted YAML itself.
 const decryptDevSecrets = (consumer: string): DecryptResult => {
-  const localSops = spawnSync('sops', SOPS_ARGS, {
-    cwd: consumer,
-    encoding: 'utf8',
-  });
-  const result =
-    localSops.error === undefined && localSops.status !== null
-      ? localSops
-      : spawnSync(
-          'nix',
-          [
-            '--extra-experimental-features',
-            'nix-command flakes',
-            'run',
-            'nixpkgs#sops',
-            '--',
-            ...SOPS_ARGS,
-          ],
-          { cwd: consumer, encoding: 'utf8' },
-        );
+  const result = runSops(SOPS_ARGS, consumer);
   if (result.status !== 0) {
-    const detail = result.error?.message ?? result.stderr?.trim();
+    const detail = result.errorMessage ?? result.stderr.trim();
     return {
       ok: false,
       problem: detail

package/src/poller-codex.ts

@@ -34,6 +34,23 @@ type CodexExecutor = (
 
 const defaultExecutor: CodexExecutor = execFileSync;
 
+type CodexRunOptions = {
+  readonly workDir: string;
+  readonly gitCommonDir: string;
+  readonly prompt: string;
+  readonly config: PollerConfig;
+};
+
+const exitCause = (details: Record<string, unknown>): string => {
+  if (typeof details.status === 'number') {
+    return `exit status ${details.status}`;
+  }
+  if (typeof details.signal === 'string') {
+    return `signal ${details.signal}`;
+  }
+  return 'unknown exit cause';
+};
+
 // 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
@@ -47,11 +64,10 @@ const agentEnv = (): Record<string, string | undefined> => {
 };
 
 export const runCodex = (
-  workDir: string,
-  prompt: string,
-  config: PollerConfig,
+  options: CodexRunOptions,
   execute: CodexExecutor = defaultExecutor,
 ): CodexRunResult => {
+  const { workDir, gitCommonDir, prompt, config } = options;
   rmSync(join(workDir, OUTCOME_DIR), { recursive: true, force: true });
   try {
     execute(
@@ -62,6 +78,8 @@ export const runCodex = (
         workDir,
         '--sandbox',
         'workspace-write',
+        '--add-dir',
+        gitCommonDir,
         '-c',
         'sandbox_workspace_write.network_access=true',
         '-m',
@@ -80,14 +98,24 @@ export const runCodex = (
     );
     return { succeeded: true, failure: null };
   } catch (error) {
+    const details: Record<string, unknown> = isRecord(error) ? error : {};
     const stderr =
-      isRecord(error) && typeof error.stderr === 'string'
-        ? error.stderr.slice(-STDERR_SNIPPET_LIMIT)
+      typeof details.stderr === 'string'
+        ? details.stderr.trim().slice(-STDERR_SNIPPET_LIMIT)
         : '';
     const message = error instanceof Error ? error.message : String(error);
+    // Node's "Command failed" message echoes the full command line, and the
+    // prompt embedded in it would push stderr past the failure-comment
+    // snippet limit — report the exit cause instead of the echoed command.
+    const cause = message.startsWith('Command failed')
+      ? exitCause(details)
+      : message;
     return {
       succeeded: false,
-      failure: `codex exec failed: ${message}\n${stderr}`,
+      failure:
+        stderr === ''
+          ? `codex exec failed: ${cause}`
+          : `codex exec failed (${cause}):\n${stderr}`,
     };
   }
 };

package/src/poller-config.ts

@@ -28,6 +28,7 @@ const DEFAULT_STALE_CLAIM_HOURS = 6;
 // wedged agents, not to bound honest work.
 const DEFAULT_RUN_TIMEOUT_MINUTES = 240;
 const MINUTES_PER_HOUR = 60;
+const MAX_WATCHED_REPOSITORIES = 12;
 
 export type PollerConfig = {
   readonly repos: ReadonlyArray<string>;
@@ -52,7 +53,16 @@ const parseRepos = (
   raw: unknown,
   problems: Array<string>,
 ): ReadonlyArray<string> => {
-  if (!(Array.isArray(raw) && raw.every((repo) => typeof repo === 'string'))) {
+  if (!Array.isArray(raw)) {
+    problems.push('poller config "repos" must be a string array');
+    return [];
+  }
+  if (raw.length > MAX_WATCHED_REPOSITORIES) {
+    problems.push(
+      `poller config "repos" supports at most ${MAX_WATCHED_REPOSITORIES} repositories at the one-minute polling cadence; reduce the list or split it across pollers with independent GitHub API budgets`,
+    );
+  }
+  if (!raw.every((repo): repo is string => typeof repo === 'string')) {
     problems.push('poller config "repos" must be a string array');
     return [];
   }

package/src/poller-fix-run.ts

@@ -139,9 +139,10 @@ export const runFixJob = async (
     workspace,
   };
   try {
-    const run = runCodex(
-      workspace.dir,
-      fixPrompt({
+    const run = runCodex({
+      workDir: workspace.dir,
+      gitCommonDir: cacheClone,
+      prompt: fixPrompt({
         repo,
         issueNumber: issue.number,
         title: currentIssue.title,
@@ -149,7 +150,7 @@ export const runFixJob = async (
         answers: preamble.answers,
       }),
       config,
-    );
+    });
     await validateFixClaim(job);
     const outcome = run.succeeded ? await readFixOutcome(workspace.dir) : null;
     if (outcome === null) {

package/src/poller-job-shared.ts

@@ -31,7 +31,9 @@ export type JobLabels = {
   readonly failed: string;
 };
 
-const FAILURE_SNIPPET_LIMIT = 1500;
+// Must exceed runCodex's failure string at its longest (its stderr snippet
+// plus the exit-cause prefix), so the diagnostic tail is never cut off.
+const FAILURE_SNIPPET_LIMIT = 4000;
 
 export type JobPreamble =
   | { readonly kind: 'rejected' }

package/src/poller-review-execution.ts

@@ -36,17 +36,18 @@ export const executeReviewJob = async (options: {
     ),
   );
   try {
-    const run = runCodex(
-      workspace.dir,
-      reviewPrompt({
+    const run = runCodex({
+      workDir: workspace.dir,
+      gitCommonDir: cacheClone,
+      prompt: reviewPrompt({
         repo: deps.repo,
         prNumber: pr.number,
         title: pr.title,
         baseSha: reviewBase,
         answers,
       }),
-      deps.config,
-    );
+      config: deps.config,
+    });
     await validateReviewClaim({
       deps,
       pr,