@smoothbricks/cli 0.11.18 → 0.11.20

package/src/monorepo/managed-files.ts

@@ -6,7 +6,7 @@ import {
   cargoCrossTestTripleFromArchiveTarget,
 } from '@smoothbricks/nx-plugin/cross-check-policy';
 import { MACOS_PLATFORM_TARGET_GLOBS, PLATFORM_TARGET_GLOBS } from '@smoothbricks/nx-plugin/workspace-config-policy';
-import { isStageDerivedDeploy, PRODUCTION_PUSH_DEPLOY_TAG } from '../lib/deploy-tags.js';
+import { PRODUCTION_PUSH_DEPLOY_TAG, stageDeploysProject } from '../lib/deploy-tags.js';
 import {
   ciPushBranches,
   type NonEmptyArray,
@@ -29,6 +29,7 @@ import {
   targetNamesFromProjects,
 } from '../nx/index.js';
 import { resolvePrivateNpmWorkflowConfig } from '../release/private-npm.js';
+import type { DeploymentStage } from '../wrangler/stage.js';
 import { type CiCrossTestArchive, privateNpmReadTokenJobEnv, renderCiWorkflowYaml } from './ci-workflow.js';
 import { renderRunsOnLine } from './github-runs-on.js';
 import { renderPrPreviewCleanupWorkflowYaml } from './pr-preview-cleanup-workflow.js';
@@ -342,6 +343,23 @@ export const managedFileTargetsForTest = managedFiles.map(({ target, executable
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
+/**
+ * Whether a repository of this shape has the file at all. A repository that owns
+ * no packages has nothing to publish, and one the stage flow does not deploy to
+ * Cloudflare has no preview stage to clean up.
+ */
+function managedFileApplies(file: ManagedFile, context: ManagedFileContext): boolean {
+  if (file.releasePackagesOnly === true && !context.hasReleasePackages && !context.hasProductionDeployTargets) {
+    return false;
+  }
+  return file.cloudflareDeployOnly !== true || context.stagingDeployProvider === 'cloudflare';
+}
+
+/** Test seam: the managed targets a repository of this shape gets, in file order. */
+export function managedFileTargetsForContext(context: ManagedFileContext): string[] {
+  return managedFiles.filter((file) => managedFileApplies(file, context)).map((file) => file.target);
+}
+
 export async function applyManagedFiles(root: string, mode: 'update' | 'check' | 'diff'): Promise<FileResult[]> {
   const context = await getManagedFileContext(root);
   return managedFiles.map((file) => applyManagedFile(root, file, mode, context));
@@ -353,10 +371,7 @@ function applyManagedFile(
   mode: 'update' | 'check' | 'diff',
   context: ManagedFileContext,
 ): FileResult {
-  if (file.releasePackagesOnly === true && !context.hasReleasePackages && !context.hasProductionDeployTargets) {
-    return { target: file.target, action: 'skipped' };
-  }
-  if (file.cloudflareDeployOnly === true && context.stagingDeployProvider !== 'cloudflare') {
+  if (!managedFileApplies(file, context)) {
     return { target: file.target, action: 'skipped' };
   }
   const target = resolve(root, file.target);
@@ -612,12 +627,12 @@ export function macosPlatformArchitecturesForTest(targetNames: Iterable<string>)
   return [...architectures].sort((left, right) => left.localeCompare(right));
 }
 
-/** Test seam: deploy configuration presence/provider from graph nodes. */
-export function deployTargetInfoFromProjects(projects: NxProjects, configuration: string): DeployTargetInfo {
+/** Test seam: what the stage flow deploys, and with which provider, from graph nodes. */
+export function deployTargetInfoFromProjects(projects: NxProjects, stage: DeploymentStage): DeployTargetInfo {
   let exists = false;
   let provider: DeployTargetInfo['provider'];
   for (const project of Object.values(projects)) {
-    const info = deployTargetInfoFromProject(project, configuration);
+    const info = deployTargetInfoFromProject(project, stage);
     if (!info.exists) {
       continue;
     }
@@ -632,22 +647,24 @@ export function anyProjectHasTagForTest(projects: NxProjects, tag: string): bool
   return Object.values(projects).some((project) => project.tags?.includes(tag));
 }
 
-function deployTargetInfoFromProject(project: NxProjectJson, configuration: string): DeployTargetInfo {
+/**
+ * A generated deploy job exists for the projects CI would actually deploy, which
+ * is `stageDeploysProject` and nothing else — the same rule `smoo github-ci
+ * nx-deploy` selects by, so the job and its selection cannot disagree. Reading
+ * the target's presence instead would render a deploy job, with cloud
+ * credentials, into a repository whose only wrangler manifests document a
+ * Durable Object binding for a published library's consumers.
+ *
+ * The command is read for the PROVIDER only: which cloud CLI runs says which
+ * credentials the job needs, and says nothing about whether CI runs it.
+ */
+function deployTargetInfoFromProject(project: NxProjectJson, stage: DeploymentStage): DeployTargetInfo {
   const deploy = project.targets?.deploy;
-  if (!deploy) {
-    return { exists: false };
-  }
-  const baseCommandValue = deploy.options?.command ?? deploy.command;
-  const baseCommand = typeof baseCommandValue === 'string' ? baseCommandValue : '';
-  if (isStageDerivedDeploy(project.tags, baseCommand)) {
-    return { exists: true, provider: deployProvider(baseCommand) };
-  }
-  const config = deploy.configurations?.[configuration];
-  if (!config) {
+  if (!deploy || !stageDeploysProject(project.tags, stage)) {
     return { exists: false };
   }
-  const commandValue = config.command ?? config.options?.command ?? baseCommand;
-  return { exists: true, provider: deployProvider(typeof commandValue === 'string' ? commandValue : '') };
+  const command = deploy.options?.command ?? deploy.command;
+  return { exists: true, provider: deployProvider(typeof command === 'string' ? command : '') };
 }
 
 function deployProvider(command: string): DeployTargetInfo['provider'] {

package/src/monorepo/packs/index.ts

@@ -2,7 +2,11 @@ import { chmodSync, existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { printCommandOutput, runResult, runStatus } from '../../lib/run.js';
 import { type ProjectTargets, readProjectTargets } from '../../nx/index.js';
-import { applyCargoFeatureUnification, validateCargoCachePolicy } from '../cargo-policy.js';
+import {
+  applyCargoFeatureUnification,
+  validateCargoCachePolicy,
+  validateCargoToolchainInputs,
+} from '../cargo-policy.js';
 import { validateGoToolchainAgreement } from '../go-toolchain.js';
 import { syncBunLockfileVersions, validateBunLockfileVersions } from '../lockfile.js';
 import { validateDevenvModuleImport, warnOnManagedFileDrift } from '../managed-files.js';
@@ -140,6 +144,11 @@ const packs: MonorepoPack[] = [
     validatePreBuild(ctx) {
       return validateCargoCachePolicy(ctx.root);
     },
+    // Post-build: the toolchain identity is read off the RESOLVED graph, which
+    // means running the inference plugin, which means its dist has to exist.
+    async validatePostBuild(ctx) {
+      return validateCargoToolchainInputs(ctx.root, await readProjectTargets(ctx.root));
+    },
   },
   {
     name: 'publishing',

package/src/monorepo/secret-references.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'bun:test';
+import { existsSync, readFileSync } from 'node:fs';
 import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
@@ -32,7 +33,8 @@ const RESOLVE_SCRIPT = `
 const resolver = await import(Bun.argv[1]);
 const request = JSON.parse(Bun.argv[2]);
 try {
-  process.stdout.write(JSON.stringify({ resolved: await resolver.resolveSecretEnvironment(request) }));
+  const { values, deferred } = await resolver.resolveSecretEnvironment(request);
+  process.stdout.write(JSON.stringify({ resolved: values, deferred }));
 } catch (error) {
   process.stdout.write(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
 }
@@ -54,16 +56,44 @@ const names = [...resolver.registryAuthEnvNames(npmrc)];
 process.stdout.write(JSON.stringify({ names }));
 `;
 
+const GROUPS_SCRIPT = `
+const resolver = await import(Bun.argv[1]);
+const { root } = JSON.parse(Bun.argv[2]);
+const groups = resolver.readSecretGroups(root).map(({ name, group, derivedGroup }) => ({ name, group, derivedGroup }));
+process.stdout.write(JSON.stringify({ groups }));
+`;
+
 interface BootstrapOutcome {
   readonly resolved?: Record<string, string>;
+  readonly deferred?: readonly { readonly name: string; readonly group: string; readonly guidance: string }[];
   readonly parsed?: unknown;
   readonly error?: string;
 }
 
+interface GroupListing {
+  readonly groups: { name: string; group: string; derivedGroup: string }[];
+}
+
+function isGroupListing(value: unknown): value is GroupListing {
+  if (typeof value !== 'object' || value === null || !('groups' in value) || !Array.isArray(value.groups)) return false;
+  return value.groups.every(
+    (entry: unknown) =>
+      typeof entry === 'object' &&
+      entry !== null &&
+      'name' in entry &&
+      typeof entry.name === 'string' &&
+      'group' in entry &&
+      typeof entry.group === 'string' &&
+      'derivedGroup' in entry &&
+      typeof entry.derivedGroup === 'string',
+  );
+}
+
 /** Narrows a harness JSON envelope with `in` checks instead of assertions: unknown shapes fail the test. Field-level expectations below do the precise checking. */
 function isBootstrapOutcome(value: unknown): value is BootstrapOutcome {
   if (typeof value !== 'object' || value === null) return false;
   if ('resolved' in value && (typeof value.resolved !== 'object' || value.resolved === null)) return false;
+  if ('deferred' in value && !Array.isArray(value.deferred)) return false;
   if ('error' in value && typeof value.error !== 'string') return false;
   return true;
 }
@@ -96,6 +126,39 @@ const emit = (text: string): readonly [string, ...string[]] => [
   '-e',
   `process.stdout.write(${JSON.stringify(text)})`,
 ];
+
+/** `emit`, plus one line appended to `ledger` every time the command actually runs. */
+const emitAndRecord = (text: string, ledger: string): readonly [string, ...string[]] => [
+  process.execPath,
+  '-e',
+  `require('node:fs').appendFileSync(${JSON.stringify(ledger)}, '1\\n');process.stdout.write(${JSON.stringify(text)})`,
+];
+
+/**
+ * A ledger a provider command appends to, and the count of what it recorded.
+ * Counting invocations is the only direct evidence that a path ran no
+ * provider command: an absent value is also what a silently failing provider
+ * leaves behind, and "no credential prompt" is the whole point of the rule.
+ */
+async function withProviderLedger(
+  run: (ledger: { readonly path: string; readonly invocations: () => number }) => Promise<void>,
+): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), 'smoo-provider-ledger-'));
+  const path = join(dir, 'invocations');
+  try {
+    await run({
+      path,
+      invocations: () =>
+        existsSync(path)
+          ? readFileSync(path, 'utf8')
+              .split('\n')
+              .filter((line) => line.length > 0).length
+          : 0,
+    });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
 /**
  * Runs one script against the raw module in a plain Bun child. The child env
  * carries only PATH/HOME so parent suite state (CI, workspace tokens) cannot
@@ -124,16 +187,33 @@ async function runInBootstrap(
 async function resolveInBootstrap(options: {
   root: string;
   env?: Record<string, string | undefined>;
+  /**
+   * Defaults to the group shell entry resolves, which is what a direnv
+   * reload performs. The resolver itself declares no default — resolving the
+   * wrong group is a credential prompt — so every case that is not shell
+   * entry names its group out loud.
+   */
+  group?: string;
 }): Promise<BootstrapOutcome> {
   const { stdout, stderr, exitCode } = await runInBootstrap(
     RESOLVE_SCRIPT,
-    JSON.stringify({ root: options.root, env: options.env ?? {} }),
+    JSON.stringify({ root: options.root, env: options.env ?? {}, group: options.group ?? 'shell' }),
   );
   expect(stderr).toBe('');
   expect(exitCode).toBe(0);
   return mustOutcome(stdout);
 }
 
+/** The groups this repository's own declarations settle on, per declared variable. */
+async function groupsInBootstrap(root: string): Promise<{ name: string; group: string; derivedGroup: string }[]> {
+  const { stdout, stderr, exitCode } = await runInBootstrap(GROUPS_SCRIPT, JSON.stringify({ root }));
+  expect(stderr).toBe('');
+  expect(exitCode).toBe(0);
+  const value: unknown = JSON.parse(stdout);
+  if (!isGroupListing(value)) throw new Error(`bootstrap harness returned a malformed listing: ${stdout}`);
+  return value.groups;
+}
+
 /** Builds a fixture repository whose package.json and .npmrc are the resolver's real inputs. */
 async function withFixture(
   options: { secrets: Record<string, SecretSpec>; npmrc?: string; remoteCache?: unknown },
@@ -195,6 +275,19 @@ describe('smoo.secrets shape validation', () => {
     expect((await parse({ smoo: { secrets: { 'a b': { command: ['op'] } } } })).error).toContain('a b');
     expect((await parse({ smoo: { secrets: { '': { command: ['op'] } } } })).error).toContain('smoo.secrets');
   });
+
+  it('accepts any group label the command line can name, and rejects one it cannot', async () => {
+    // The shape is validated, never the value: a repository naming a group
+    // of its own must not need a new smoo release to run it.
+    expect(
+      (await parse({ smoo: { secrets: { SMOO_TOKEN: { command: ['op'], group: 'deploy-eu' } } } })).parsed,
+    ).toEqual({ SMOO_TOKEN: { command: ['op'], group: 'deploy-eu' } });
+    for (const malformed of ['', 'two words', 7]) {
+      const outcome = await parse({ smoo: { secrets: { SMOO_TOKEN: { command: ['op'], group: malformed } } } });
+      expect(outcome.error).toContain('SMOO_TOKEN');
+      expect(outcome.error).toContain('group');
+    }
+  });
 });
 
 describe('registryAuthEnvNames', () => {
@@ -215,6 +308,78 @@ describe('registryAuthEnvNames', () => {
   });
 });
 
+/**
+ * The group is derived from declarations the repository already carries, so
+ * a manifest states a group only where those cannot: nobody restates a fact
+ * the repo already declares.
+ */
+describe('group derivation', () => {
+  const REGISTRY_NPMRC = '//npm.example.net/:_authToken=${SMOO_NPM_TOKEN}\n';
+
+  it('derives registry from a .npmrc reference, nx-cache from the cache token, and shell from neither', async () => {
+    await withFixture(
+      {
+        npmrc: REGISTRY_NPMRC,
+        secrets: {
+          SMOO_NPM_TOKEN: { command: emit('x') },
+          NX_REMOTE_CACHE_TOKEN: { command: emit('x') },
+          SMOO_TOKEN: { command: emit('x') },
+        },
+        remoteCache: { server: 'https://nx-cache.example.net', tokenSecret: 'NX_REMOTE_CACHE_TOKEN' },
+      },
+      async (root) => {
+        expect(await groupsInBootstrap(root)).toEqual([
+          { name: 'SMOO_NPM_TOKEN', group: 'registry', derivedGroup: 'registry' },
+          { name: 'NX_REMOTE_CACHE_TOKEN', group: 'nx-cache', derivedGroup: 'nx-cache' },
+          { name: 'SMOO_TOKEN', group: 'shell', derivedGroup: 'shell' },
+        ]);
+      },
+    );
+  });
+
+  it('a declared group wins, and the derivation it overrode stays visible', async () => {
+    await withFixture(
+      {
+        npmrc: REGISTRY_NPMRC,
+        secrets: {
+          SMOO_NPM_TOKEN: { command: emit('x'), group: 'shell' },
+          SMOO_TOKEN: { command: emit('x'), group: 'deploy' },
+        },
+      },
+      async (root) => {
+        expect(await groupsInBootstrap(root)).toEqual([
+          { name: 'SMOO_NPM_TOKEN', group: 'shell', derivedGroup: 'registry' },
+          { name: 'SMOO_TOKEN', group: 'deploy', derivedGroup: 'shell' },
+        ]);
+      },
+    );
+  });
+
+  it('the cache token stays nx-cache even when .npmrc also references it', async () => {
+    await withFixture(
+      {
+        npmrc: '//npm.example.net/:_authToken=${NX_REMOTE_CACHE_TOKEN}\n',
+        secrets: { NX_REMOTE_CACHE_TOKEN: { command: emit('x') } },
+        remoteCache: { server: 'https://nx-cache.example.net', tokenSecret: 'NX_REMOTE_CACHE_TOKEN' },
+      },
+      async (root) => {
+        // The by-name exclusion this replaced was applied before the .npmrc
+        // reference was ever consulted; the derivation keeps that order, so
+        // one pathological manifest behaves exactly as it did.
+        expect(await groupsInBootstrap(root)).toEqual([
+          { name: 'NX_REMOTE_CACHE_TOKEN', group: 'nx-cache', derivedGroup: 'nx-cache' },
+        ]);
+      },
+    );
+  });
+
+  it('a repository declaring nothing has no groups', async () => {
+    await withFixture({ secrets: {} }, async (root) => {
+      expect(await groupsInBootstrap(root)).toEqual([]);
+    });
+  });
+});
+
 describe('resolveSecretEnvironment', () => {
   it('an existing nonempty environment value wins and no command runs', async () => {
     await withFixture(
@@ -222,7 +387,10 @@ describe('resolveSecretEnvironment', () => {
       async (root) => {
         // The declared command cannot run at all, so a resolution attempt would
         // fail loudly; an empty outcome proves the existing value preempted it.
-        expect(await resolveInBootstrap({ root, env: { SMOO_TOKEN: 'already-set' } })).toEqual({ resolved: {} });
+        expect(await resolveInBootstrap({ root, env: { SMOO_TOKEN: 'already-set' } })).toEqual({
+          resolved: {},
+          deferred: [],
+        });
       },
     );
   });
@@ -231,16 +399,23 @@ describe('resolveSecretEnvironment', () => {
     await withFixture({ secrets: { SMOO_TOKEN: { command: emit('tok-from-provider') } } }, async (root) => {
       expect(await resolveInBootstrap({ root, env: { SMOO_TOKEN: '' } })).toEqual({
         resolved: { SMOO_TOKEN: 'tok-from-provider' },
+        deferred: [],
       });
     });
   });
 
   it('trims one terminal newline, LF or CRLF, preserving interior content', async () => {
     await withFixture({ secrets: { SMOO_TOKEN: { command: emit('tok-from-provider\n') } } }, async (root) => {
-      expect(await resolveInBootstrap({ root, env: {} })).toEqual({ resolved: { SMOO_TOKEN: 'tok-from-provider' } });
+      expect(await resolveInBootstrap({ root, env: {} })).toEqual({
+        resolved: { SMOO_TOKEN: 'tok-from-provider' },
+        deferred: [],
+      });
     });
     await withFixture({ secrets: { SMOO_TOKEN: { command: emit('tok\r\nmid\r\n') } } }, async (root) => {
-      expect(await resolveInBootstrap({ root, env: {} })).toEqual({ resolved: { SMOO_TOKEN: 'tok\r\nmid' } });
+      expect(await resolveInBootstrap({ root, env: {} })).toEqual({
+        resolved: { SMOO_TOKEN: 'tok\r\nmid' },
+        deferred: [],
+      });
     });
   });
 
@@ -265,16 +440,89 @@ describe('resolveSecretEnvironment', () => {
       async (root) => {
         // A cache is an optimization: its provider being down installs
         // dependencies anyway. Every other declared secret keeps its refusal.
+        // The cache token is not excluded by name any more — it is in group
+        // `nx-cache`, which shell entry defers, so its provider is never
+        // reached to be unreachable.
         expect(await resolveInBootstrap({ root, env: {} })).toEqual({
           resolved: { SMOO_TOKEN: 'tok-from-provider' },
+          deferred: [
+            { name: 'NX_REMOTE_CACHE_TOKEN', group: 'nx-cache', guidance: expect.stringContaining('nx-cache') },
+          ],
         });
         const withoutCacheDeclaration = await resolveInBootstrap({ root, env: { CI: 'true' } });
         expect(withoutCacheDeclaration.error).toContain('SMOO_TOKEN');
+        // CI refuses what shell entry needs, and the cache token is not that:
+        // nothing shell entry runs reads `smoo.remoteCache`.
         expect(withoutCacheDeclaration.error).not.toContain('NX_REMOTE_CACHE_TOKEN');
       },
     );
   });
 
+  it('the declared cache token is deferred at shell entry and its provider never runs', async () => {
+    await withProviderLedger(async (ledger) => {
+      await withFixture(
+        {
+          secrets: { NX_REMOTE_CACHE_TOKEN: { command: emitAndRecord('cache-tok', ledger.path) } },
+          remoteCache: { server: 'https://nx-cache.example.net', tokenSecret: 'NX_REMOTE_CACHE_TOKEN' },
+        },
+        async (root) => {
+          // Named in the result rather than silently omitted, which is what
+          // the by-name exclusion this replaces used to do.
+          expect(await resolveInBootstrap({ root, env: {} })).toEqual({
+            resolved: {},
+            deferred: [
+              {
+                name: 'NX_REMOTE_CACHE_TOKEN',
+                group: 'nx-cache',
+                guidance: expect.stringContaining('smoo secrets run nx-cache'),
+              },
+            ],
+          });
+          expect(ledger.invocations()).toBe(0);
+
+          // And a cowshed workspace does not refuse it either: the gateway
+          // rule is about registry credentials, and this is not one.
+          expect(await resolveInBootstrap({ root, env: { COWSHED_WORKSPACE_TOKEN: 'gateway-session' } })).toEqual({
+            resolved: {},
+            deferred: [
+              {
+                name: 'NX_REMOTE_CACHE_TOKEN',
+                group: 'nx-cache',
+                guidance: expect.stringContaining('smoo secrets run nx-cache'),
+              },
+            ],
+          });
+          expect(ledger.invocations()).toBe(0);
+        },
+      );
+    });
+  });
+
+  it('a deliberate nx-cache run resolves the cache token nothing else resolves', async () => {
+    await withProviderLedger(async (ledger) => {
+      await withFixture(
+        {
+          secrets: {
+            NX_REMOTE_CACHE_TOKEN: { command: emitAndRecord('cache-tok', ledger.path) },
+            SMOO_TOKEN: { command: emitAndRecord('shell-tok', ledger.path) },
+          },
+          remoteCache: { server: 'https://nx-cache.example.net', tokenSecret: 'NX_REMOTE_CACHE_TOKEN' },
+        },
+        async (root) => {
+          const outcome = await resolveInBootstrap({ root, env: {}, group: 'nx-cache' });
+
+          expect(outcome.resolved).toEqual({ NX_REMOTE_CACHE_TOKEN: 'cache-tok' });
+          expect(outcome.deferred).toEqual([
+            { name: 'SMOO_TOKEN', group: 'shell', guidance: expect.stringContaining('smoo secrets run shell') },
+          ]);
+          // One group, one provider invocation: the shell secret's command
+          // did not run for a cache-token request.
+          expect(ledger.invocations()).toBe(1);
+        },
+      );
+    });
+  });
+
   it('a present variable is not reported while another refuses in CI', async () => {
     await withFixture(
       {
@@ -291,7 +539,7 @@ describe('resolveSecretEnvironment', () => {
     );
   });
 
-  it('cowshed workspaces exclude .npmrc-referenced variables from local resolution', async () => {
+  it('a cowshed workspace refuses a registry credential rather than deferring it', async () => {
     await withFixture(
       {
         npmrc: '//npm.example.net/:_authToken=${SMOO_NPM_TOKEN}\n',
@@ -315,11 +563,169 @@ describe('resolveSecretEnvironment', () => {
       async (root) => {
         expect(await resolveInBootstrap({ root, env: { COWSHED_WORKSPACE_TOKEN: 'gateway-session' } })).toEqual({
           resolved: { SMOO_GENERIC: 'generic-tok' },
+          deferred: [],
         });
       },
     );
   });
 
+  // A registry credential is the second instance of the rule the resolver's
+  // header states: shell entry never runs a provider command for a credential
+  // that only a network operation needs. The reference is what makes it one.
+  const REGISTRY_NPMRC = '@acme:registry=https://npm.example.net\n//npm.example.net/:_authToken=${SMOO_NPM_TOKEN}\n';
+
+  it('shell entry defers a .npmrc-referenced variable and never runs its provider', async () => {
+    await withProviderLedger(async (ledger) => {
+      await withFixture(
+        {
+          npmrc: REGISTRY_NPMRC,
+          secrets: { SMOO_NPM_TOKEN: { command: emitAndRecord('SHELL-ENTRY-RESOLVED-VALUE', ledger.path) } },
+        },
+        async (root) => {
+          const outcome = await resolveInBootstrap({ root, env: {}, group: 'shell' });
+
+          expect(outcome.resolved).toEqual({});
+          expect(outcome.error).toBeUndefined();
+          expect(ledger.invocations()).toBe(0);
+          // A failing install prints `- <name>: <guidance>`, so both halves
+          // have to be here: which variable, and the one command that
+          // supplies it.
+          expect(outcome.deferred).toEqual([
+            {
+              name: 'SMOO_NPM_TOKEN',
+              group: 'registry',
+              guidance: expect.stringContaining('smoo secrets run registry <command>'),
+            },
+          ]);
+        },
+      );
+    });
+  });
+
+  it('a declared variable .npmrc does not reference still resolves at shell entry', async () => {
+    await withProviderLedger(async (ledger) => {
+      await withFixture(
+        { npmrc: REGISTRY_NPMRC, secrets: { SMOO_GENERIC: { command: emitAndRecord('generic-tok', ledger.path) } } },
+        async (root) => {
+          // The same .npmrc, a variable it does not name: the deferral keys on
+          // the reference, not on a registry existing somewhere in the repo.
+          expect(await resolveInBootstrap({ root, env: {}, group: 'shell' })).toEqual({
+            resolved: { SMOO_GENERIC: 'generic-tok' },
+            deferred: [],
+          });
+          expect(ledger.invocations()).toBe(1);
+        },
+      );
+    });
+  });
+
+  it('a deliberate registry run resolves the variable shell entry deferred, and nothing else', async () => {
+    await withProviderLedger(async (ledger) => {
+      await withFixture(
+        {
+          npmrc: REGISTRY_NPMRC,
+          secrets: {
+            SMOO_NPM_TOKEN: { command: emitAndRecord('registry-tok', ledger.path) },
+            SMOO_TOKEN: { command: emitAndRecord('shell-tok', ledger.path) },
+          },
+        },
+        async (root) => {
+          const outcome = await resolveInBootstrap({ root, env: {}, group: 'registry' });
+
+          expect(outcome.resolved).toEqual({ SMOO_NPM_TOKEN: 'registry-tok' });
+          // The shell secret is deferred, not resolved: one group, one
+          // provider invocation. A wrapper that resolved every declared
+          // secret would have run two.
+          expect(outcome.deferred).toEqual([
+            { name: 'SMOO_TOKEN', group: 'shell', guidance: expect.stringContaining('smoo secrets run shell') },
+          ]);
+          expect(ledger.invocations()).toBe(1);
+        },
+      );
+    });
+  });
+
+  it('a declared group is what shell entry resolves, derivation notwithstanding', async () => {
+    await withProviderLedger(async (ledger) => {
+      await withFixture(
+        {
+          npmrc: REGISTRY_NPMRC,
+          secrets: { SMOO_NPM_TOKEN: { command: emitAndRecord('registry-tok', ledger.path), group: 'shell' } },
+        },
+        async (root) => {
+          // The repository says this credential belongs to the shell, and
+          // that is the whole of the rule: the override is not a hint.
+          expect(await resolveInBootstrap({ root, env: {}, group: 'shell' })).toEqual({
+            resolved: { SMOO_NPM_TOKEN: 'registry-tok' },
+            deferred: [],
+          });
+          expect(ledger.invocations()).toBe(1);
+        },
+      );
+    });
+  });
+
+  it('an exported registry credential wins over the deferral', async () => {
+    await withProviderLedger(async (ledger) => {
+      await withFixture(
+        { npmrc: REGISTRY_NPMRC, secrets: { SMOO_NPM_TOKEN: { command: emitAndRecord('x', ledger.path) } } },
+        async (root) => {
+          // Nothing to defer and nothing to run: the developer who exported it
+          // for this terminal already answered the question.
+          expect(await resolveInBootstrap({ root, env: { SMOO_NPM_TOKEN: 'exported' }, group: 'shell' })).toEqual({
+            resolved: {},
+            deferred: [],
+          });
+          expect(ledger.invocations()).toBe(0);
+        },
+      );
+    });
+  });
+
+  it('CI refuses a missing registry credential instead of deferring it', async () => {
+    await withProviderLedger(async (ledger) => {
+      await withFixture(
+        { npmrc: REGISTRY_NPMRC, secrets: { SMOO_NPM_TOKEN: { command: emitAndRecord('x', ledger.path) } } },
+        async (root) => {
+          // CI outranks the registry rule and is unchanged by it: a job that
+          // needs the credential says so at setup rather than discovering it
+          // at the first fetch, and there is no wrapper to run there.
+          const outcome = await resolveInBootstrap({ root, env: { CI: 'true' }, group: 'shell' });
+
+          expect(outcome.error).toContain('SMOO_NPM_TOKEN');
+          expect(outcome.error).toContain('inject');
+          expect(outcome.error).not.toContain('smoo secrets run');
+          expect(ledger.invocations()).toBe(0);
+        },
+      );
+    });
+  });
+
+  it('a cowshed workspace refuses a registry credential for a network operation too', async () => {
+    await withProviderLedger(async (ledger) => {
+      await withFixture(
+        {
+          npmrc: REGISTRY_NPMRC,
+          secrets: { SMOO_NPM_TOKEN: { command: emitAndRecord('LOCAL-RESOLVED-VALUE', ledger.path) } },
+        },
+        async (root) => {
+          // The gateway is the enrollment path there, so the wrapper does not
+          // become a way around it.
+          const outcome = await resolveInBootstrap({
+            root,
+            env: { COWSHED_WORKSPACE_TOKEN: 'gateway-session' },
+            group: 'registry',
+          });
+
+          expect(outcome.error).toContain('SMOO_NPM_TOKEN');
+          expect(outcome.error).toContain('cowshed gateway');
+          expect(outcome.error).not.toContain('LOCAL-RESOLVED-VALUE');
+          expect(ledger.invocations()).toBe(0);
+        },
+      );
+    });
+  });
+
   it('provider failures name the variable, the exit code, and nothing secret-shaped', async () => {
     await withFixture(
       {