@davidvornholt/standards 0.26.0 → 0.26.2

package/README.md

@@ -60,7 +60,7 @@ Existing project-owned files are kept. Synced files are replaced. `init` refuses
 ```sh
 bun standards sync --dry-run
 bun standards sync
-bun standards sync --ref v0.26.0
+bun standards sync --ref v0.26.1
 bun standards sync --from ../standards
 ```
 
@@ -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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -166,7 +166,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",
@@ -184,17 +183,17 @@
   },
   "devDependencies": {
     "@davidvornholt/typescript-config": "0.0.0",
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.2",
     "sigstore": "5.0.0",
     "typescript": "7.0.2"
   },
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.1"
   }
 }

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-cloudflare.ts

@@ -3,6 +3,8 @@
 // itself, lists and mints scoped tokens, and revokes them. Token values
 // returned by create flow only into SOPS writers,
 // never stdout.
+// User-owned tokens are intentionally outside this API and the bootstrap
+// credential's authority; they must be managed separately in Cloudflare.
 
 import {
   type CfResult,

package/src/creds-github-apps.ts

@@ -57,6 +57,8 @@ export const loadOwnedGithubStore = async (
   return { ok: true, value: migrated };
 };
 
+// Private Apps belong to one owner. Selecting by repository owner keeps each
+// owner's credentials separate; installation access is verified before export.
 export const selectGithubAppForRepo = (
   apps: ReadonlyArray<GithubBrokerApp>,
   repo: string,

package/src/creds-plan.ts

@@ -7,6 +7,8 @@
 // tokens it minted for another repository, are reported
 // (creds-plan-unmanaged.ts) but never mutated. Execution lives in
 // creds-plan-run.ts.
+// Live policy is preserved, not compared with a separate desired-policy manifest.
+// Adding policy-drift enforcement would require a new source of truth.
 
 import { cloudflareExpiresOn } from './creds-cloudflare-expiry';
 import { groupByIntersectingFootprint } from './creds-plan-groups';

package/src/creds-store.ts

@@ -24,6 +24,9 @@ export type BrokerStore = {
   readonly cloudflare: ReadonlyArray<CloudflareBrokerAccount>;
 };
 export const EMPTY_BROKER_STORE: BrokerStore = { github: [], cloudflare: [] };
+// This machine-global store trusts the local account, like its age private key.
+// Encrypting it with a colocated key would not protect against that account.
+// Repository secrets still belong in SOPS; this store stays outside repositories.
 const OWNER_ONLY_FILE_MODE = 0o600;
 const OWNER_ONLY_DIR_MODE = 0o700;
 const FILE_MODE_MODULUS = 0o1000;

package/src/dev-env-brokered-resolve.ts

@@ -22,6 +22,8 @@ export type ResolvedDevEnv = {
   readonly problems: ReadonlyArray<string>;
 };
 
+// Each variable independently selects a complete pair and then one part.
+// Variable names and neighboring references do not imply a shared credential.
 const lookupReference = (
   document: unknown,
   reference: BrokeredS3Reference,

package/src/github-graphql.ts

@@ -120,6 +120,8 @@ const BYPASS_ACTOR_PROBE = 1;
 // `totalCount` means the connection is being filtered rather than merely
 // redacted, so it supplies no count; a null *element* is the documented
 // identity-withholding shape, so only the length is checked.
+// Probes with restricted tokens confirmed that hidden actors still count:
+// https://github.com/davidvornholt/standards/pull/176
 const countedRuleset = (node: unknown): readonly [number, number] | null => {
   if (!isRecord(node) || typeof node.databaseId !== 'number') {
     return null;

package/src/poller-codex.ts

@@ -163,6 +163,9 @@ export const runCodex = async (
       {
         detached: true,
         stdio: ['ignore', 'ignore', 'pipe'],
+        // Approved runs share the host service identity and its GitHub token.
+        // Approval and write revalidation constrain the workflow; they do not
+        // isolate credentials. This assumes trusted, maintainer-approved work.
         env: { ...process.env },
       },
     );

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