@davidvornholt/standards 0.26.1 → 0.26.3

package/README.md

@@ -97,7 +97,7 @@ bun standards structure --profile source
 
 `doctor` checks project-owned integration points such as `biome.jsonc`, `AGENTS.local.md`, package scripts, sync policy, settings overlays, and Dependabot inputs.
 
-`structure` checks the exact Bun declaration, workspace scripts, internal dependency versions, package exports, TypeScript inheritance, accessibility wiring, workspace READMEs, and CI secret structure. The `source` profile records the few intentional differences in this repository itself.
+`structure` checks the exact Bun declaration, workspace scripts, internal dependency versions, package exports, TypeScript inheritance, accessibility wiring, and CI secret structure. The `source` profile records the few intentional differences in this repository itself.
 
 ## dependabot
 
@@ -263,3 +263,5 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "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",
@@ -166,7 +165,6 @@
     "src/structure-check.ts",
     "src/structure-bun-version.ts",
     "src/structure-profile.ts",
-    "src/structure-readme.ts",
     "src/structure-secret-document.ts",
     "src/structure-script.ts",
     "src/structure-secrets.ts",

package/src/cli.ts

@@ -1189,7 +1189,7 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
 
 // Canonical monorepo structure gate: workspace and root script shapes,
 // internal versioning, `exports`, tsconfig inheritance, a11y wiring,
-// repo-owned workspace READMEs, and the undecrypted CI secrets contract
+// and the undecrypted CI secrets contract
 // (SOPS shape mirroring plus the keys the synced workflows require).
 // The `source` profile instead pins the standards template repository's own
 // deliberate exceptions to the consumer contract.

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/structure-check.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
+import { isContainedPath } from './contained-path';
 import { isRecord } from './github-settings-parse';
 import { readJsonFile } from './json-file';
 import { collectBunVersionProblems } from './structure-bun-version';
@@ -9,7 +10,6 @@ import {
   rootScriptExpectations,
   type StructureProfile,
 } from './structure-profile';
-import { collectWorkspaceReadmeProblems } from './structure-readme';
 import { filteredTurboAliasProblem, hasSafeCommands } from './structure-script';
 import { collectCiSecretsProblems } from './structure-secrets';
 import { inspectWorkspace, type Workspace } from './structure-workspace';
@@ -106,6 +106,12 @@ const loadWorkspace = async (
   if (!existsSync(path)) {
     return { workspace: null, problem: null };
   }
+  if (!isContainedPath(consumer, `${rel}/package.json`, 'file')) {
+    return {
+      workspace: null,
+      problem: `${rel}: package.json must be a contained regular file; symlinked paths are not allowed`,
+    };
+  }
   const manifest = await readJsonFile(path);
   if (manifest === null) {
     return {
@@ -174,16 +180,9 @@ export const collectStructureProblems = async (
       .map((ws) => ws.manifest.name)
       .filter((name): name is string => typeof name === 'string'),
   );
-  const [inspections, readmeProblems] = await Promise.all([
-    Promise.all(
-      workspaces.map((ws) => inspectWorkspace(ws, workspaceNames, profile)),
-    ),
-    collectWorkspaceReadmeProblems(
-      consumer,
-      profile,
-      workspaces.map((ws) => ws.rel),
-    ),
-  ]);
+  const inspections = await Promise.all(
+    workspaces.map((ws) => inspectWorkspace(ws, workspaceNames, profile)),
+  );
   const requireA11y = inspections.some((i) => i.hasA11ySuite);
   return [
     ...declaration.problems,
@@ -193,7 +192,6 @@ export const collectStructureProblems = async (
     ...collectBunVersionProblems(root),
     ...inspectRootScripts(root, profile, requireA11y),
     ...inspections.flatMap((i) => [...i.problems]),
-    ...readmeProblems,
     ...secretsProblems,
   ];
 };

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

package/src/structure-readme.ts

@@ -1,85 +0,0 @@
-import { lstat, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { isContainedPath } from './contained-path';
-import { readJsonFile } from './json-file';
-import type { StructureProfile } from './structure-profile';
-
-const SYNC_MANIFEST = 'sync-standards.json';
-const TRAILING_SLASHES = /\/+$/u;
-const MANIFEST_REQUIREMENT = `${SYNC_MANIFEST}: must contain a JSON object with a "paths" array of strings; the structure gate reads it to tell canonical workspaces from repo-owned ones`;
-const MANIFEST_CONTAINMENT = `${SYNC_MANIFEST}: must be a contained regular file; symlinked paths are not allowed`;
-
-type CanonicalRels = {
-  readonly rels: ReadonlySet<string>;
-  readonly problem: string | null;
-};
-
-// Canonical workspaces are synced from the standards template and cannot be
-// fixed in a consumer checkout, so the consumer profile exempts them from
-// repo-owned documentation rules. The source repository owns those workspaces,
-// so the source profile exempts nothing.
-const canonicalWorkspaceRels = async (
-  consumer: string,
-  profile: StructureProfile,
-): Promise<CanonicalRels> => {
-  if (profile === 'source') {
-    return { rels: new Set(), problem: null };
-  }
-  const manifestPath = join(consumer, SYNC_MANIFEST);
-  const manifestInfo = await lstat(manifestPath).catch(() => null);
-  if (
-    manifestInfo !== null &&
-    !isContainedPath(consumer, SYNC_MANIFEST, 'file')
-  ) {
-    return { rels: new Set(), problem: MANIFEST_CONTAINMENT };
-  }
-  const manifest = await readJsonFile(manifestPath);
-  const paths = manifest?.paths;
-  if (
-    !(
-      Array.isArray(paths) &&
-      paths.every((path): path is string => typeof path === 'string')
-    )
-  ) {
-    return { rels: new Set(), problem: MANIFEST_REQUIREMENT };
-  }
-  return {
-    rels: new Set(paths.map((path) => path.replace(TRAILING_SLASHES, ''))),
-    problem: null,
-  };
-};
-
-const readmeProblem = async (
-  consumer: string,
-  rel: string,
-): Promise<string | null> => {
-  const readmeRel = `${rel}/README.md`;
-  const readmePath = join(consumer, readmeRel);
-  const info = await lstat(readmePath).catch(() => null);
-  if (info !== null && !isContainedPath(consumer, readmeRel, 'file')) {
-    return `${rel}: README.md must be a contained regular file; symlinked paths are not allowed`;
-  }
-  const raw = await readFile(readmePath, 'utf8').catch(() => null);
-  return raw !== null && raw.trim() !== ''
-    ? null
-    : `${rel}: repo-owned workspace must have a non-empty README.md`;
-};
-
-export const collectWorkspaceReadmeProblems = async (
-  consumer: string,
-  profile: StructureProfile,
-  rels: ReadonlyArray<string>,
-): Promise<ReadonlyArray<string>> => {
-  const canonical = await canonicalWorkspaceRels(consumer, profile);
-  if (canonical.problem !== null) {
-    // Without the manifest the gate cannot tell canonical workspaces from
-    // repo-owned ones, so it fails on the manifest instead of guessing.
-    return [canonical.problem];
-  }
-  const problems = await Promise.all(
-    rels
-      .filter((rel) => !canonical.rels.has(rel))
-      .map((rel) => readmeProblem(consumer, rel)),
-  );
-  return problems.filter((problem): problem is string => problem !== null);
-};