fix(cli): declare the four @better-auth/utils peer skews a fresh scaffold reports (#10931) (#11128)

@better-auth/core, /oauth-provider, /scim and /sso each peer an exact
@better-auth/utils@0.4.2 while a scaffolded tree hands them 0.5.0, so a
brand-new project's first `pnpm install` opened with four unmet-peer lines
the scaffold's own peerDependencyRules block exists to prevent.

Measured compatible before widening: the four import three symbols in total
(base64/base64Url, createHash, and createRandomStringGenerator in core), 0.5.0
declares all three unchanged, and both versions return identical values on the
inputs those call sites pass -- confirmed end to end through better-auth with
the sso, oauth-provider and scim plugins. A resolution change was measured and
rejected: pinning utils back clears the lines only by dragging better-call@1.4.0
off its own declared ^0.5.0.

Both scaffold paths change together, and the cross-file consistency gate gains
a peer limb -- the reservation it carried for this card is discharged.


Claude-Session: https://claude.ai/code/session_019bmVFqoQPq63zhKrxdYG1r

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: Elon Musk

.changeset/scaffold-better-auth-utils-peer-skew.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/cli": patch
+"create-objectstack": patch
+---
+
+fix(cli): declare the four `@better-auth/utils` peer skews a freshly scaffolded project reports (#10931)
+
+Both scaffold paths emit a `peerDependencyRules.allowedVersions` block whose
+stated purpose is that a brand-new project's first `pnpm install` does not open
+with a peer-skew report. It declared two skews and left four showing:
+
+```
+├─┬ @better-auth/core 1.7.1
+│ └── ✕ unmet peer @better-auth/utils@0.4.2: found 0.5.0
+        ├─┬ @better-auth/scim 1.7.0-rc.1
+        │ └── ✕ unmet peer @better-auth/utils@0.4.2: found 0.5.0
+        ├─┬ @better-auth/oauth-provider 1.7.1
+        │ └── ✕ unmet peer @better-auth/utils@0.4.2: found 0.5.0
+        └─┬ @better-auth/sso 1.7.1
+          └── ✕ unmet peer @better-auth/utils@0.4.2: found 0.5.0
+```
+
+`@better-auth/core`, `/oauth-provider`, `/scim` and `/sso` each peer an **exact**
+`@better-auth/utils@0.4.2`. The 0.5.0 they are handed comes from
+`better-call@1.4.0` — better-auth's own HTTP layer — which *depends* on
+`^0.5.0`; `@objectstack/plugin-auth` names the four as direct dependencies
+without naming utils, so pnpm satisfies their peer from better-call's copy
+instead of better-auth's own exact 0.4.2 dependency.
+
+**Measured compatible before widening, not assumed.** Those four import three
+symbols in total: `base64`/`base64Url` (`@better-auth/utils/base64`),
+`createHash` (`/hash`) and, in core only, `createRandomStringGenerator`
+(`/random`). 0.5.0 declares all three with identical signatures; `/random` is
+unchanged apart from formatting, `/base64` swaps `new Uint8Array(data)` for a
+helper that *is* `new Uint8Array(data)` on non-strings, and `/hash` only widens
+its input coercion for views not backed by a plain `ArrayBuffer`. Run against
+the input shapes those call sites actually pass, the two versions agree on every
+value; run end to end — better-auth with the `sso`, `oauth-provider` and `scim`
+plugins — a tree where the four resolve 0.5.0 and one where they resolve 0.4.2
+produce the same transcript: sign-up, sign-in, session, both OAuth metadata
+documents, the RFC 7636 PKCE challenge, and the SCIM and SSO endpoint outcomes.
+
+A resolution change was measured too, and rejected: pinning utils back to 0.4.2
+clears the four lines only by dragging `better-call@1.4.0` off its own declared
+`^0.5.0` — manufacturing one real range violation to silence four benign ones.
+
+Four scoped entries, one per declaring package, matching the block's convention
+that each rule widens exactly one declaration. `allowedVersions` suppresses the
+report only: the lockfile a scaffold resolves is byte-identical with and without
+the block. The version is spelled `0.5.0` exactly rather than `0.5`, so a future
+`0.6.0` reports again instead of inheriting this finding.
+
+Both scaffold paths — `objectstack init` (rendered by the CLI) and
+`npx create-objectstack` (a copied template file) — are changed together, and
+`packages/cli/test/scaffold-workspace-consistency.test.ts` gains a limb that
+compares the peer maps the two produce, so they cannot drift apart again.

packages/cli/src/commands/init.ts

@@ -82,10 +82,10 @@ export const SCAFFOLD_BUILT_DEPENDENCIES = ['better-sqlite3', 'esbuild'];
  * states, keyed `<declaring package>><peer>` — pnpm's scoped `allowedVersions`
  * spelling, so each entry widens exactly one declaration and nothing else.
  *
- * Both are reported by `pnpm install` on a brand-new scaffold, and neither is a
- * real incompatibility. They are declared here because that report is the first
- * thing a newcomer sees, on the one screen where they are deciding whether this
- * project is solid, and there is nothing they did to cause it.
+ * Every one of them is reported by `pnpm install` on a brand-new scaffold, and
+ * none is a real incompatibility. They are declared here because that report is
+ * the first thing a newcomer sees, on the one screen where they are deciding
+ * whether this project is solid, and there is nothing they did to cause it.
  *
  *  - `better-auth>better-sqlite3` — better-auth 1.7.1 peers `^12.0.0` while the
  *    tree resolves 13.x (`@objectstack/driver-sql`'s optional dependency). The
@@ -105,12 +105,62 @@ export const SCAFFOLD_BUILT_DEPENDENCIES = ['better-sqlite3', 'esbuild'];
  *    HOST's better-call instance, so the single 1.4.0 copy every install
  *    already resolves is the correct tree, not a skew to repair.
  *    ⚠️ This entry retires together with the SCIM rc pin — delete both at once.
+ *    Stable `@better-auth/scim@1.7.1` peers `better-call@1.4.0`, so the skew
+ *    this line covers is genuinely gone the moment the pin moves.
  *
- * `allowedVersions` suppresses the report ONLY; it moves no resolution.
+ *  - `<four>@better-auth/utils` — `@better-auth/core`, `/oauth-provider`,
+ *    `/scim` and `/sso` each peer an EXACT `@better-auth/utils@0.4.2`, while a
+ *    scaffolded tree hands them 0.5.0. The 0.5.0 comes from `better-call@1.4.0`
+ *    (better-auth's own HTTP layer), which DEPENDS on `^0.5.0`;
+ *    `@objectstack/plugin-auth` names the four packages as direct dependencies
+ *    without naming utils, so pnpm satisfies their peer from better-call's copy
+ *    rather than from better-auth's own exact 0.4.2 dependency.
+ *
+ *    Measured compatible rather than assumed. Those four import exactly three
+ *    symbols across two subpaths — `base64`/`base64Url` (`/base64`),
+ *    `createHash` (`/hash`) and, in core only, `createRandomStringGenerator`
+ *    (`/random`). 0.5.0 exports all three with identical signatures; `/random`
+ *    is unchanged apart from formatting, `/base64` swaps `new Uint8Array(data)`
+ *    for a helper that IS `new Uint8Array(data)` on non-strings, and `/hash`
+ *    only widens its input coercion for views not backed by a plain
+ *    ArrayBuffer. Run against the input shapes those call sites actually pass,
+ *    0.4.2 and 0.5.0 agree on every value; run end to end (better-auth with the
+ *    sso, oauth-provider and scim plugins), a tree where the four resolve 0.5.0
+ *    and one where they resolve 0.4.2 produce the same transcript — sign-up,
+ *    sign-in, session, both OAuth metadata documents, the RFC 7636 PKCE
+ *    challenge, and the SCIM and SSO endpoint outcomes.
+ *
+ *    ⛔ A resolution change is the WRONG remedy here, and was measured too:
+ *    pinning utils back to 0.4.2 clears the four lines only by dragging
+ *    `better-call@1.4.0` off its own declared `^0.5.0` — manufacturing one real
+ *    range violation to silence four benign ones.
+ *
+ *    Spelled `0.5.0` exactly, not `0.5`: 0.5.0 is the version that was
+ *    measured, and a future 0.6.0 SHOULD report again rather than inherit this
+ *    finding.
+ *
+ *    ⚠️ These four do NOT retire with the SCIM rc pin, even though one of them
+ *    names scim. Stable `@better-auth/scim@1.7.1` still peers
+ *    `@better-auth/utils@0.4.2`, so this skew outlives that pin. They retire
+ *    when the four packages accept 0.5.0 upstream, or when
+ *    `SCAFFOLD_PNPM_RANGE` reaches `>=10.31` — pnpm 10.31 changed peer
+ *    resolution so that all four land on 0.4.2 by themselves. Measured on the
+ *    rendered scaffold, one clean resolve per pnpm version:
+ *
+ *      pnpm 10.15.0 – 10.30.0   all four reported as unmet peers.
+ *      pnpm >= 10.31.0          resolved to 0.4.2; nothing to report.
+ *
+ * `allowedVersions` suppresses the report ONLY; it moves no resolution — the
+ * lockfile a scaffold resolves is byte-identical with and without this block
+ * (verified by digest on pnpm 10.15.0 and 10.30.0).
  */
 export const SCAFFOLD_ALLOWED_PEER_VERSIONS: Record<string, string> = {
   'better-auth>better-sqlite3': '13',
   '@better-auth/scim>better-call': '1.4.0',
+  '@better-auth/core>@better-auth/utils': '0.5.0',
+  '@better-auth/oauth-provider>@better-auth/utils': '0.5.0',
+  '@better-auth/scim>@better-auth/utils': '0.5.0',
+  '@better-auth/sso>@better-auth/utils': '0.5.0',
 };
 
 /**
@@ -186,7 +236,7 @@ export function renderScaffoldPackageJson(
 
 /**
  * Render the `pnpm-workspace.yaml` that allowlists native build scripts and
- * declares the two known-benign peer skews.
+ * declares the known-benign peer skews.
  * Declares an explicit empty `packages: []`: a workspace root with no member
  * packages, which is what a single-package scaffold is — the file stays purely
  * a settings file. Spelling the key out is what lets pnpm 10.0–10.4 (and 9.x)
@@ -257,9 +307,9 @@ export function renderPnpmWorkspaceYaml(
     // declaration that is not there.
     ...(peerEntries.length === 0 ? [] : [
       '',
-      '# Two third-party peer ranges resolve outside what their declaring package',
-      '# states, and pnpm reports both on a first install. Neither is a real',
-      '# incompatibility:',
+      '# Third-party peer ranges that resolve outside what their declaring',
+      '# package states, and that pnpm reports on a first install. None is a',
+      '# real incompatibility:',
       '#',
       '#   better-auth peers better-sqlite3 ^12.0.0 while the tree resolves 13.x.',
       '#   That peer is optional and covers handing better-auth a raw',
@@ -272,7 +322,18 @@ export function renderPnpmWorkspaceYaml(
       '#   better-auth plugin has to share the host\'s better-call instance, so',
       '#   the single 1.4.0 copy is the correct resolution.',
       '#',
-      '# These suppress the report only — no resolution moves.',
+      '#   @better-auth/core, /oauth-provider, /scim and /sso each peer an exact',
+      '#   @better-auth/utils 0.4.2, while better-call (better-auth\'s own HTTP',
+      '#   layer) depends on ^0.5.0 and is what the tree resolves them against.',
+      '#   0.5.0 keeps every symbol those four import — base64/base64Url,',
+      '#   createHash, createRandomStringGenerator — with the same signatures',
+      '#   and the same values on the inputs they pass, so the report is the',
+      '#   only difference. Pinning utils back instead would drag better-call',
+      '#   off its own declared range, which is a real violation rather than a',
+      '#   reported one.',
+      '#',
+      '# These suppress the report only — no resolution moves, and the lockfile',
+      '# is byte-identical with and without this block.',
       'peerDependencyRules:',
       '  allowedVersions:',
       ...peerEntries.map(([k, v]) => `    '${k}': '${v}'`),

packages/cli/test/init.test.ts

@@ -342,6 +342,59 @@ describe('benign peer-skew declarations (#10326)', () => {
     expect(settings).toMatch(/^ {4}'@better-auth\/scim>better-call': '1\.4\.0'$/m);
   });
 
+  it.each([
+    ['@better-auth/core'],
+    ['@better-auth/oauth-provider'],
+    ['@better-auth/scim'],
+    ['@better-auth/sso'],
+  ])('widens %s\'s exact @better-auth/utils peer to the version the tree resolves', (declaring) => {
+    // Each of the four peers an EXACT `@better-auth/utils@0.4.2`, while the
+    // tree hands them 0.5.0 — better-call (better-auth's own HTTP layer)
+    // depends on `^0.5.0`, and that is the copy plugin-auth's direct
+    // dependencies resolve their peer against. Measured on the surface the
+    // range governs: the four import three symbols in total (base64/base64Url,
+    // createHash, and createRandomStringGenerator in core), 0.5.0 declares all
+    // three unchanged, and both versions return identical values on the inputs
+    // those call sites pass — confirmed end to end through better-auth with the
+    // sso, oauth-provider and scim plugins. Pinning utils back instead would
+    // drag better-call off its own `^0.5.0`, trading four reported skews for a
+    // real one.
+    const key = `${declaring}>@better-auth/utils`;
+    expect(SCAFFOLD_ALLOWED_PEER_VERSIONS[key]).toBe('0.5.0');
+    expect(settings).toMatch(
+      new RegExp(`^ {4}'${key.replace(/[/*+?^${}()|[\]\\]/g, '\\$&')}': '0\\.5\\.0'$`, 'm'),
+    );
+  });
+
+  it('covers every declaring package that peers @better-auth/utils, not some of them', () => {
+    // The defect this replaces was PARTIAL coverage: two skews were declared
+    // and four more were not, so the first screen was clean for a third of the
+    // report. A set assertion is what fails when a fifth declaration appears
+    // and nobody measures it, or when one of these four is dropped while the
+    // others stay.
+    const declaring = Object.keys(SCAFFOLD_ALLOWED_PEER_VERSIONS)
+      .filter((k) => k.endsWith('>@better-auth/utils'))
+      .map((k) => k.slice(0, -'>@better-auth/utils'.length))
+      .sort();
+    expect(declaring).toEqual([
+      '@better-auth/core',
+      '@better-auth/oauth-provider',
+      '@better-auth/scim',
+      '@better-auth/sso',
+    ]);
+  });
+
+  it('keeps the @better-auth/utils widening separate from the retiring better-call pin', () => {
+    // @better-auth/scim appears in TWO entries for two unrelated reasons, and
+    // they retire on different days: the better-call one goes when scim leaves
+    // the rc (stable 1.7.1 peers better-call 1.4.0), while the utils one
+    // outlives it (stable 1.7.1 still peers @better-auth/utils 0.4.2). Deleting
+    // both together — the obvious move when the rc pin lifts — would silently
+    // put the utils report back on a newcomer's first screen.
+    expect(SCAFFOLD_ALLOWED_PEER_VERSIONS['@better-auth/scim>better-call']).toBe('1.4.0');
+    expect(SCAFFOLD_ALLOWED_PEER_VERSIONS['@better-auth/scim>@better-auth/utils']).toBe('0.5.0');
+  });
+
   it('renders the rules under peerDependencyRules.allowedVersions', () => {
     expect(settings).toMatch(/^peerDependencyRules:$/m);
     expect(settings).toMatch(/^ {2}allowedVersions:$/m);

packages/cli/test/scaffold-workspace-consistency.test.ts

@@ -52,9 +52,26 @@
 // `@objectstack/cli#test` inputs; without that declaration a template-only diff
 // could not reach this suite and its cache would replay a stale green.
 //
-// ⛔ `peerDependencyRules` is deliberately NOT compared here. The peer-warning
-// skew between the two files is #10931, open on this same surface; a limb
-// added here would either duplicate that card or pre-empt its ruling.
+// ── `peerDependencyRules`, and why it is compared here NOW ──────────────────
+//
+// This limb was deliberately absent while #10931 was open: that card was the
+// ruling on WHICH peer skews the scaffold should declare, and a limb written
+// before it would have either duplicated the card or pre-empted its answer.
+// #10931 is answered (the four `@better-auth/utils` declarations landed with
+// it), so the reservation is discharged and the drift risk is what remains —
+// and it is the same two-producer risk the rest of this file exists for. The
+// peer block is, if anything, the more fragile of the two: build approvals are
+// one flat package list, while a peer rule is a `<declaring>><peer>` key whose
+// value has to be RE-MEASURED per entry, so a copy that lands in one file and
+// not the other is both easy to make and invisible to either package's own
+// tests.
+//
+// What is compared is the rendered `allowedVersions` MAP — the keys each file
+// widens and the version each key is widened to — for the same reason the
+// build limb compares rendered grants: no expected value is restated here, so
+// each producer's expectation is the other producer. The prose above each
+// block is NOT compared: the two files explain these skews in their own words
+// on purpose, and the measurement they describe is the same either way.
 
 import { describe, it, expect } from 'vitest';
 import { readFileSync } from 'node:fs';
@@ -87,6 +104,21 @@ const [CLI, TEMPLATE] = Object.keys(RENDERED) as [Producer, Producer];
 /** The two keys that grant a dependency's build script permission to run. */
 const APPROVAL_KEYS = ['allowBuilds', 'onlyBuiltDependencies'] as const;
 
+/**
+ * The peer skews each file declares, as `<declaring package>><peer>` → version.
+ *
+ * Read out of the settings with the prose stripped first, exactly as the build
+ * grants are: the comments above the block NAME these packages and versions,
+ * and must never be what satisfies an assertion about the declarations.
+ */
+function declaredPeerSkews(yaml: string): Record<string, string> {
+  const settings = yaml.replace(/^\s*#.*$/gm, '');
+  const block = /^peerDependencyRules:\n[ \t]+allowedVersions:\n((?:[ \t]+.*\n?)*)/m.exec(settings)?.[1] ?? '';
+  const out: Record<string, string> = {};
+  for (const m of block.matchAll(/^[ \t]+'([^']+)':[ \t]*'([^']*)'[ \t]*$/gm)) out[m[1]] = m[2];
+  return out;
+}
+
 /**
  * The packages each key actually grants a build to, read out of the settings
  * with the prose stripped first — the comments below each key NAME these
@@ -214,4 +246,31 @@ describe('the two scaffold paths render the same pnpm build approvals (#10499)',
       ).toEqual(claimed[TEMPLATE]);
     }
   });
+
+  it('declares the same peer skews, widened to the same versions', () => {
+    const cli = declaredPeerSkews(RENDERED[CLI]);
+    const template = declaredPeerSkews(RENDERED[TEMPLATE]);
+
+    // Non-vacuity: two empty maps compare equal while declaring nothing, which
+    // is the state that puts an unmet-peer report on a newcomer's first screen.
+    for (const [producer, skews] of [[CLI, cli], [TEMPLATE, template]] as const) {
+      expect(
+        Object.keys(skews).length,
+        `${producer} declares no peer skew at all — a scaffolded project's first ` +
+          '`pnpm install` then opens with an unmet-peer report the user did not cause',
+      ).toBeGreaterThan(0);
+    }
+
+    expect(
+      cli,
+      'the two scaffold paths declare different peer skews: ' +
+        `${CLI} widens {${Object.entries(cli).map(([k, v]) => `${k}=${v}`).join(', ')}} and ` +
+        `${TEMPLATE} widens {${Object.entries(template).map(([k, v]) => `${k}=${v}`).join(', ')}}. ` +
+        'Each entry is a per-declaration judgement backed by its own measurement, so a ' +
+        'key present in one file and missing from the other means half of users see a ' +
+        'report the other half does not — and a key widened to DIFFERENT versions means ' +
+        'one of the two is silencing a skew nobody measured. Re-measure before moving ' +
+        'either file; never copy a value across just to make this pass.',
+    ).toEqual(template);
+  });
 });