@davidvornholt/standards 0.26.2 → 0.26.4

package/README.md

@@ -263,3 +263,9 @@ The worker accepts only exact issue or draft-PR revisions approved by a user wit
 | `GH_TOKEN` or `GITHUB_TOKEN` | GitHub API authentication where required. |
 
 The [root README](../../README.md) gives the short overview. The [adoption guide](../../docs/adoption.md) and [sync guide](../../docs/sync-and-ownership.md) explain repository ownership and first use.
+
+The poller timers use monotonic intervals: after boot, acknowledgement starts after one minute and work starts after two minutes. Missed downtime intervals are not replayed; each tick reads the current queue. The service budget reserves thirty minutes for scanning and setup in addition to its configured agent budget, with at most twelve watched repositories per poller. Split larger lists across pollers with independent API budgets; unusually slow provider or clone operations can exhaust that overhead and require investigating the service timeout before retrying.
+
+## Source text validation
+
+`bun standards source-text` checks tracked source, configuration, and documentation files as UTF-8 text, regardless of Git’s binary classification. `bun standards check` includes this gate. Raw Unicode control characters are rejected except tab and LF; write control characters in fixtures and composite keys using escaped representations such as `\0` or `\u0000`. Binary asset formats and untracked files are outside this gate. Missing tracked source files and source symlinks fail validation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.26.2",
+  "version": "0.26.4",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -52,7 +52,6 @@
     "src/creds-plan-report.ts",
     "src/creds-plan-run.ts",
     "src/creds-plan-revoke.ts",
-    "src/creds-plan-types.ts",
     "src/creds-plan-unmanaged.ts",
     "src/creds-prompt.ts",
     "src/creds-r2.ts",
@@ -163,6 +162,7 @@
     "src/screenshots-publish.ts",
     "src/screenshots-upload.ts",
     "src/sops-exec.ts",
+    "src/source-text.ts",
     "src/structure-check.ts",
     "src/structure-bun-version.ts",
     "src/structure-profile.ts",

package/src/cli.ts

@@ -44,6 +44,7 @@ import {
 } from './managed-path-ownership';
 import { runPollerCommand } from './poller-commands';
 import { runScreenshotsCommand } from './screenshots-commands';
+import { collectSourceTextProblems } from './source-text';
 import { collectStructureProblems } from './structure-check';
 import type { StructureProfile } from './structure-profile';
 import { hasSafeCommand } from './structure-script';
@@ -92,6 +93,7 @@ type Command =
   | 'help'
   | 'init'
   | 'poller'
+  | 'source-text'
   | 'structure'
   | 'sync';
 
@@ -969,6 +971,7 @@ Commands:
   sync        Mirror canonical files from upstream, regenerate the composed Dependabot config, and rewrite the lock
   check       Verify canonical files, extension seams, monorepo structure, and GitHub settings
   doctor      Validate extension seams only
+  source-text Reject raw control characters in tracked source text
   structure   Validate monorepo structure rules only
   dependabot  Verify (--check) or regenerate (--write) the composed .github/dependabot.yml
   dev-env     Compose each workspace's generated .env.local from its three dev layers and authorized broker-owned S3 pair references
@@ -1002,6 +1005,7 @@ const commandFromArg = (arg: string): Command => {
     arg === 'help' ||
     arg === 'init' ||
     arg === 'poller' ||
+    arg === 'source-text' ||
     arg === 'structure' ||
     arg === 'sync'
   ) {
@@ -1209,10 +1213,24 @@ const runStructure = async (
   return true;
 };
 
+const runSourceTextCheck = (consumer: string): boolean => {
+  const problems = collectSourceTextProblems(consumer);
+  if (problems.length > 0) {
+    console.error(`standards source-text: ${problems.length} problem(s):`);
+    console.error(problems.map((problem) => `  - ${problem}`).join('\n'));
+    return false;
+  }
+  console.log(
+    'standards source-text: tracked source text contains no forbidden control characters',
+  );
+  return true;
+};
+
 const runCheckCommand = async (consumer: string): Promise<boolean> => {
   const driftIsClean = await runCheck(consumer);
   const integrationIsValid = await runDoctor(consumer);
   const structureIsValid = await runStructure(consumer, 'consumer');
+  const sourceTextIsValid = runSourceTextCheck(consumer);
   // The GitHub gate activates with the synced declaration and then fails
   // closed: once .github/settings.json exists, an unreachable API or an
   // unreadable origin is a failure, not a skip.
@@ -1220,7 +1238,11 @@ const runCheckCommand = async (consumer: string): Promise<boolean> => {
     ? await runGithubCheckGate(consumer)
     : true;
   return (
-    driftIsClean && integrationIsValid && structureIsValid && githubIsConverged
+    driftIsClean &&
+    integrationIsValid &&
+    structureIsValid &&
+    sourceTextIsValid &&
+    githubIsConverged
   );
 };
 
@@ -1296,6 +1318,7 @@ const runGateCommand = (
     | 'dev-env'
     | 'doctor'
     | 'github'
+    | 'source-text'
     | 'structure',
   consumer: string,
   apply: boolean,
@@ -1313,6 +1336,9 @@ const runGateCommand = (
   if (command === 'doctor') {
     return runDoctor(consumer);
   }
+  if (command === 'source-text') {
+    return Promise.resolve(runSourceTextCheck(consumer));
+  }
   if (command === 'structure') {
     return runStructure(consumer, profile);
   }

package/src/creds-add-collision.ts

@@ -24,7 +24,7 @@ export const findManagedDestinationCollision = async (
     return `account ${failed.accountId}: ${failed.listed.problem}; cannot prove the destination is unambiguous`;
   }
   const wanted = destinationFootprint(format, context.dest.key);
-  const collisions = listings.flatMap(({ accountId, listed }) =>
+  const collisions = listings.flatMap(({ listed }) =>
     listed.ok
       ? listed.value.flatMap((token) => {
           const ref = parseTokenName(token.name, context.repo);
@@ -35,7 +35,7 @@ export const findManagedDestinationCollision = async (
                 wanted,
                 inferredDestinationFootprint(keys, ref.key),
               ))
-            ? [`${accountId}/${token.id} (${ref.key})`]
+            ? [`${ref.target}:${ref.key}`]
             : [];
         })
       : [],

package/src/creds-add-github.ts

@@ -31,8 +31,8 @@ export const runCredsAddGithub = async (
     appIdPath,
     privateKeyPath,
   ]);
-  if (blocked !== null) {
-    console.error(`standards creds: ${blocked}`);
+  if (blocked.problem !== null) {
+    console.error(`standards creds: ${blocked.problem}`);
     return false;
   }
   const storePath = resolveBrokerPath();

package/src/creds-add-preflight.ts

@@ -16,12 +16,21 @@ export const inspectDestinations = async (
   consumer: string,
   rel: string,
   paths: ReadonlyArray<string>,
-): Promise<string | null> => {
+): Promise<{
+  readonly problem: string | null;
+  readonly occupied: ReadonlyArray<string>;
+}> => {
   const inspected = await Promise.all(
     paths.map((path) => inspectSopsScalarDestination(consumer, rel, path)),
   );
   const blocked = inspected.find((result) => !result.ok);
-  return blocked !== undefined && !blocked.ok ? blocked.problem : null;
+  return {
+    problem: blocked !== undefined && !blocked.ok ? blocked.problem : null,
+    occupied: paths.filter((_, index) => {
+      const result = inspected[index];
+      return result?.ok && result.state === 'scalar';
+    }),
+  };
 };
 
 export type ResolvedResourceFlags =

package/src/creds-add.ts

@@ -69,6 +69,17 @@ const printSuccess = (input: {
   }
 };
 
+const warnOccupiedDestinations = (
+  target: string,
+  paths: ReadonlyArray<string>,
+): void => {
+  for (const path of paths) {
+    console.error(
+      `standards creds: warning — ${target}:${path} already holds a value and will be overwritten; the old provider credential is not revoked by this write. Run \`standards creds plan\` to inspect unmanaged token candidates before retiring it.`,
+    );
+  }
+};
+
 export const runCredsAddCloudflare = async (
   consumer: string,
   options: {
@@ -104,13 +115,9 @@ export const runCredsAddCloudflare = async (
   const format: DestinationFormat = options.s3 ? 's3' : 'bearer';
   const paths =
     format === 's3' ? s3PairPaths(context.dest.key) : [context.dest.key];
-  const destinationProblem = await inspectDestinations(
-    consumer,
-    context.rel,
-    paths,
-  );
-  if (destinationProblem !== null) {
-    console.error(`standards creds: ${destinationProblem}`);
+  const destinations = await inspectDestinations(consumer, context.rel, paths);
+  if (destinations.problem !== null) {
+    console.error(`standards creds: ${destinations.problem}`);
     return false;
   }
   const encryptedKeys = await readEncryptedKeys(consumer, context.rel);
@@ -137,6 +144,7 @@ export const runCredsAddCloudflare = async (
     console.error(`standards creds: ${collisionProblem}`);
     return false;
   }
+  warnOccupiedDestinations(context.dest.target, destinations.occupied);
   const ttlDays = options.ttlDays ?? DEFAULT_TTL_DAYS;
   const expiresOn = cloudflareExpiresOn(Date.now() + ttlDays * DAY_MS);
   const created = await createAccountToken(account.accountId, account.token, {

package/src/creds-cloudflare.ts

@@ -120,7 +120,7 @@ export const listPermissionGroups = async (
   const response = await cfRequest(
     token,
     'GET',
-    `/accounts/${accountId}/tokens/permission_groups?per_page=1000`,
+    `/accounts/${accountId}/tokens/permission_groups`,
   );
   if (!response.ok) {
     return response;

package/src/creds-login-cloudflare.ts

@@ -1,6 +1,6 @@
 // Cloudflare broker bootstrap. Cloudflare's API can create account-owned
 // tokens, but the very first token must come from the dashboard — this is the
-// one paste per account, ever. The flow tells the user exactly what to click
+// one paste per account per machine. The flow tells the user exactly what to click
 // and which single permission to grant, takes the token hidden, verifies it
 // against the API before storing, and from then on every real credential is a
 // scoped, expiring account token minted by `standards creds add`.
@@ -109,7 +109,9 @@ export const runCredsLoginCloudflare = async (options: {
     return false;
   }
   const tokensUrl = `https://dash.cloudflare.com/${accountId}/api-tokens`;
-  console.log('Create the bootstrap token (one time for this account):');
+  console.log(
+    'Create the bootstrap token (one time for this account on this machine):',
+  );
   console.log(`  1. Open ${tokensUrl}`);
   console.log('  2. Select Create Token');
   console.log('  3. Find Create additional tokens and select Use template');
@@ -118,6 +120,9 @@ export const runCredsLoginCloudflare = async (options: {
     '  5. Keep exactly one permission: Account / Account API Tokens / Edit',
   );
   console.log('  6. Continue to summary, create the token, and copy the value');
+  console.log(
+    `Each machine needs its own ${BROKER_IDENTITY_NAME} token. Cloudflare allows duplicate names; leave an existing token with that name alone, and never reuse, roll, or revoke another machine's token.`,
+  );
   openInBrowser(tokensUrl);
   const token = await promptHidden('Paste the token (input is hidden): ');
   if (token.length === 0) {

package/src/poller-config.ts

@@ -64,22 +64,22 @@ const parseRepos = (
   }
   if (!raw.every((repo): repo is string => typeof repo === 'string')) {
     problems.push('poller config "repos" must be a string array');
-    return [];
   }
+  const repos = raw.filter((repo): repo is string => typeof repo === 'string');
   if (raw.length === 0) {
     problems.push('poller config "repos" must list at least one repository');
   }
-  for (const repo of raw) {
+  for (const repo of repos) {
     if (!REPO_PATTERN.test(repo)) {
       problems.push(
         `poller config "repos" entries must be "owner/repo": ${repo}`,
       );
     }
   }
-  if (new Set(raw).size !== raw.length) {
+  if (new Set(repos).size !== repos.length) {
     problems.push('poller config "repos" entries must be unique');
   }
-  return raw;
+  return repos;
 };
 
 const parsePositiveInteger = (

package/src/poller-units.ts

@@ -73,7 +73,6 @@ Description=Run the standards fix poller on an interval
 OnBootSec=2min
 OnUnitInactiveSec=${WORKER_INTERVAL_MINUTES}min
 AccuracySec=15s
-Persistent=true
 
 [Install]
 WantedBy=timers.target
@@ -95,7 +94,6 @@ Description=Check for newly queued standards poller requests
 OnBootSec=1min
 OnUnitInactiveSec=${ACKNOWLEDGEMENT_INTERVAL_MINUTES}min
 AccuracySec=15s
-Persistent=true
 
 [Install]
 WantedBy=timers.target

package/src/source-text.ts

@@ -0,0 +1,98 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { isContainedPath } from './contained-path';
+
+const sourceExtensions = new Set(
+  '.ts,.tsx,.mts,.cts,.js,.jsx,.mjs,.cjs,.json,.jsonc,.yaml,.yml,.toml,.nix,.sh,.bash,.zsh,.rb,.py,.css,.scss,.html,.xml,.svg,.md,.mdx,.sql,.just'.split(
+    ',',
+  ),
+);
+const sourceFileNames = new Set([
+  'Dockerfile',
+  'Containerfile',
+  'Makefile',
+  'justfile',
+  '.envrc',
+  '.gitignore',
+  '.gitattributes',
+  '.dockerignore',
+  '.editorconfig',
+  '.npmrc',
+]);
+const dotenvFileName = /^\.env(?:\..*)?$/u;
+const forbiddenControl = /[^\P{Cc}\t\n]/u;
+const gitOutputLimit = 16_777_216;
+const hexadecimalRadix = 16;
+const minimumCodePointWidth = 4;
+
+export const inspectSourceText = (
+  path: string,
+  bytes: Uint8Array,
+): string | null => {
+  let text: string;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    return `${JSON.stringify(path)}: source text must be valid UTF-8`;
+  }
+  const match = forbiddenControl.exec(text);
+  if (!match) {
+    return null;
+  }
+  const point = match[0]
+    .codePointAt(0)
+    ?.toString(hexadecimalRadix)
+    .toUpperCase()
+    .padStart(minimumCodePointWidth, '0');
+  const line = text.slice(0, match.index).split('\n').length;
+  return `${JSON.stringify(path)}:${line}: raw control character U+${point}; use an escaped representation (only tab and LF are allowed)`;
+};
+
+export const collectSourceTextProblems = (
+  root: string,
+): ReadonlyArray<string> => {
+  let tracked: string;
+  try {
+    tracked = execFileSync('git', ['ls-files', '--cached', '-z'], {
+      cwd: root,
+      encoding: 'utf8',
+      maxBuffer: gitOutputLimit,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch {
+    return [
+      'Cannot enumerate tracked source files; run the gate from a readable Git working tree.',
+    ];
+  }
+  const problems: Array<string> = [];
+  const paths = new Set(
+    tracked
+      .split('\0')
+      .filter(
+        (path) =>
+          sourceExtensions.has(extname(path)) ||
+          sourceFileNames.has(basename(path)) ||
+          dotenvFileName.test(basename(path)),
+      ),
+  );
+  for (const path of paths) {
+    if (isContainedPath(root, path, 'file')) {
+      try {
+        const problem = inspectSourceText(path, readFileSync(join(root, path)));
+        if (problem !== null) {
+          problems.push(problem);
+        }
+      } catch {
+        problems.push(
+          `${JSON.stringify(path)}: cannot read tracked source text`,
+        );
+      }
+    } else {
+      problems.push(
+        `${JSON.stringify(path)}: tracked source must be a contained regular file`,
+      );
+    }
+  }
+  return problems;
+};

package/src/structure-profile.ts

@@ -31,6 +31,7 @@ const SOURCE_ROOT_EXPECTATIONS: ReadonlyArray<RootScriptExpectation> = [
     name: 'check',
     commands: [
       `${SOURCE_CLI} structure --profile source`,
+      `${SOURCE_CLI} source-text`,
       `${SOURCE_CLI} dependabot --check`,
       `${SOURCE_CLI} github --check`,
       'turbo run lint check-types test --output-logs=errors-only',
@@ -41,6 +42,7 @@ const SOURCE_ROOT_EXPECTATIONS: ReadonlyArray<RootScriptExpectation> = [
     name: 'check:fix',
     commands: [
       `${SOURCE_CLI} structure --profile source`,
+      `${SOURCE_CLI} source-text`,
       `${SOURCE_CLI} dependabot --write`,
       `${SOURCE_CLI} github --check`,
       'turbo run lint:fix check-types test --output-logs=errors-only',

package/src/structure-workspace.ts

@@ -58,11 +58,15 @@ const containsA11ySuite = async (dir: string): Promise<boolean> => {
   return nested.includes(true);
 };
 const inspectScripts = (ws: Workspace): ReadonlyArray<string> =>
-  WORKSPACE_SCRIPTS.flatMap(([name, command]) =>
-    hasSafeCommand(scriptOf(ws.manifest, name), command)
-      ? []
-      : [`${ws.rel}: script "${name}" must run ${command}`],
-  );
+  WORKSPACE_SCRIPTS.flatMap(([name, command]) => {
+    const script = scriptOf(ws.manifest, name);
+    const accepted =
+      hasSafeCommand(script, command) ||
+      (name === 'test' && hasSafeCommand(script, 'bun test --isolate'));
+    const expected =
+      name === 'test' ? 'bun test or bun test --isolate' : command;
+    return accepted ? [] : [`${ws.rel}: script "${name}" must run ${expected}`];
+  });
 const declaredDependencies = (manifest: Record<string, unknown>) =>
   DEPENDENCY_FIELDS.flatMap((field) => {
     const deps = manifest[field];

package/src/creds-plan-types.ts

@@ -1,55 +0,0 @@
-import type { CloudflareToken, TokenPolicy } from './creds-cloudflare-api';
-import type { TokenCondition } from './creds-cloudflare-condition';
-import type { DestinationFormat } from './creds-r2';
-
-export type AccountToken = {
-  readonly accountId: string;
-  readonly token: CloudflareToken;
-};
-
-export type UnmanagedToken = {
-  readonly accountId: string;
-  readonly tokenId: string;
-  readonly name: string;
-  readonly status: string;
-};
-
-// A token the broker minted under another repository's name. That repository
-// normally reconciles it, so it is not unmanaged — the distinction matters
-// because it stops being true when that repository is renamed, transferred, or
-// deleted, and this account is then the only place the token is still visible.
-export type BrokeredElsewhereToken = UnmanagedToken & {
-  readonly repo: string;
-};
-
-export type PlannedAction =
-  | {
-      readonly kind: 'revoke';
-      readonly accountId: string;
-      readonly tokenId: string;
-      readonly name: string;
-      readonly reason: string;
-    }
-  | {
-      readonly kind: 'renew';
-      readonly accountId: string;
-      readonly tokenId: string;
-      readonly name: string;
-      readonly target: string;
-      readonly key: string;
-      readonly format: DestinationFormat;
-      readonly policies: ReadonlyArray<TokenPolicy>;
-      readonly condition: TokenCondition | null;
-      readonly replacementExpiresOn: string;
-      readonly reason: string;
-    };
-
-export type CredsPlan = {
-  readonly actions: ReadonlyArray<PlannedAction>;
-  readonly findings: ReadonlyArray<string>;
-  readonly healthy: number;
-  // Tokens in the account the broker did not mint. Reported, never mutated.
-  readonly unmanaged: ReadonlyArray<UnmanagedToken>;
-  // Tokens the broker minted for another repository. Reported, never mutated.
-  readonly brokeredElsewhere: ReadonlyArray<BrokeredElsewhereToken>;
-};