@smoothbricks/cli 0.11.19 → 0.11.21

package/managed/raw/tooling/direnv/secret-references.ts

@@ -10,49 +10,142 @@
  * declares. Keep them aligned; smoo's Typia validation fails the manifest at
  * generation time for anything this file would reject at runtime.
  *
+ * THE RULE: shell entry resolves the `shell` group and nothing else. Every
+ * other group belongs to the command that needs it:
+ * `smoo secrets run <group> <command...>`.
+ *
+ * Shell entry happens on every direnv reload and every `devenv shell --
+ * <command>`, and a provider authorises per requesting process lineage, which
+ * is new each time — so a provider command placed there is a credential
+ * prompt on every one of them: dozens an hour for a developer, one more for
+ * every scripted subprocess. A credential whose only consumer is a deliberate
+ * command therefore belongs to that command.
+ *
+ * A group is NOT a fourth thing to declare. It is derived from the
+ * declarations a repository already carries, and an explicit `group` on the
+ * entry is only for what those cannot say. Derivation, per variable:
+ *
+ *  - `nx-cache` — the variable `smoo.remoteCache.tokenSecret` names. A remote
+ *    cache is an optimization: Nx reads NX_SELF_HOSTED_REMOTE_CACHE_SERVER
+ *    and _ACCESS_TOKEN from the environment it runs in — CI injects them, a
+ *    developer exports the token once in the terminal that wants the cache —
+ *    and every nested shell inherits them. Absent, Nx keeps to its local
+ *    cache.
+ *  - `registry` — a variable `.npmrc` interpolates as `${VAR}`. An installed
+ *    checkout contacts no registry at all (measured: `bun install --dry-run`
+ *    succeeds in 14ms with the token absent), while a request that does
+ *    contact one answers 401 without it.
+ *  - `shell` — everything else: what the shell itself is for, resolved at
+ *    entry because that is when it is needed.
+ *
+ * An explicit `group` wins over the derivation, and no group is privileged in
+ * code: a repository may name one of its own and run it the same way. Only
+ * the shape is validated, so a new group needs no new smoo release.
+ *
  * Routing per declared variable, in first-match order:
  *
  *  1. An existing nonempty environment value wins; no command runs.
- *  2. CI (`CI` set): variables must be injected from the CI secret store;
- *     provider commands never run there. Missing variables refuse with
- *     injected-secret guidance instead of a confusing auth failure later.
- *  3. Inside a cowshed workspace (`COWSHED_WORKSPACE_TOKEN` set), a variable
- *     referenced from `.npmrc` is registry routing intent: it is excluded
- *     from local provider resolution and refuses with names-only
- *     gateway-enrollment guidance. Generic variables still use env/provider.
+ *  2. For the requested group, and for a group the request depends on (see
+ *     below), a context that cannot run a provider command at all decides
+ *     before the group does:
+ *     a. CI (`CI` set): variables must be injected from the CI secret store;
+ *        provider commands never run there. Missing variables refuse with
+ *        injected-secret guidance instead of a confusing auth failure later.
+ *     b. A `registry` variable inside a cowshed workspace
+ *        (`COWSHED_WORKSPACE_TOKEN` set) refuses with names-only
+ *        gateway-enrollment guidance: such a workspace holds no provider
+ *        session, and the gateway exists to be the thing that does.
+ *  3. A variable outside the requested group is deferred — named in the
+ *     result, not resolved, and not a failure.
  *  4. Otherwise the command argv executes directly, without a shell; stdout
  *     with one terminal newline trimmed becomes the value.
  *
+ * A request DEPENDS ON a group when the operation being resolved for reads
+ * that group's own declaration. Shell entry runs `bun install`, and
+ * `bun install` reads `.npmrc` — so `registry` is an input to shell entry
+ * that shell entry deliberately does not resolve. That dependency is what
+ * keeps rule 2 honest in a context which cannot honour a deferral: CI has no
+ * later command to run and a cowshed workspace has no provider session, so
+ * both refuse by name rather than promising that `smoo secrets run` would
+ * fix it. Nothing shell entry runs reads `smoo.remoteCache`, so an
+ * `nx-cache` variable is deferred in every context and blocks nothing.
+ *
+ * A deferred variable is a value in the result rather than a silent omission,
+ * and there is no fallback that resolves it anyway: a fallback would
+ * reinstate the prompt this rule removes, at the least predictable moment.
+ * The caller names the variable and the command that supplies it when the
+ * operation that needed it fails.
+ *
  * Failures aggregate so a single direnv reload surfaces every problem.
- * Error text names variables and exit codes only: secret values, provider
- * stdout/stderr, and command arguments are never echoed.
+ * Error text names variables, groups and exit codes only: secret values,
+ * provider stdout/stderr, and command arguments are never echoed.
  * A resolved value still reaches the environment of the install its caller
  * runs next, so `maskSecretValues` redacts those values out of any captured
  * child output that caller replays.
  *
- * The variable `smoo.remoteCache.tokenSecret` names is never resolved here,
- * nor anywhere at shell entry. A remote cache is an optimization, and shell
- * entry happens on every direnv reload and every `devenv shell -- <command>`:
- * a provider command run there is a credential prompt on each of them. Nx
- * reads NX_SELF_HOSTED_REMOTE_CACHE_SERVER and _ACCESS_TOKEN from the
- * environment it runs in — CI injects them, a developer exports the token
- * once in the terminal that wants the cache — and every nested shell inherits
- * them. Absent, Nx keeps to its local cache.
+ * Zero prompts, as an option and not a recommendation: a declared `command`
+ * may point at the OS keychain instead of at the provider. On macOS, populate
+ * the item once from the 1Password item (`security add-generic-password -s
+ * <name> -a <account> -w`) and declare
+ * `["security", "find-generic-password", "-w", "-s", "<name>"]`. macOS
+ * authorises a keychain item per calling binary, so the first approval covers
+ * every later read by that binary: rule 4 then answers without prompting and
+ * the deferral above never has to be paid. 1Password stays the source of
+ * truth and the keychain is a session cache of it — but the trade-off is
+ * exactly that, a second copy of the credential now lives on disk, outside
+ * the provider's rotation and revocation, and nothing here refreshes it.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+/**
+ * Which operation resolves a declared secret. Open by construction: the three
+ * below are the DERIVED defaults, not the permitted values, so a repository
+ * that declares `"group": "deploy"` needs no smoo release to run it.
+ */
+export type SecretGroup = string;
+
+/** Resolved at shell entry, because that is the operation that needs it. */
+export const SHELL_GROUP: SecretGroup = 'shell';
+
+/** Derived for a variable `.npmrc` interpolates as `${VAR}`. */
+export const REGISTRY_GROUP: SecretGroup = 'registry';
+
+/** Derived for the variable `smoo.remoteCache.tokenSecret` names. */
+export const NX_CACHE_GROUP: SecretGroup = 'nx-cache';
+
 export interface SecretSpec {
   /** Executed directly, without a shell; stdout supplies the secret value. */
   readonly command: readonly [string, ...string[]];
+  /**
+   * Overrides the derived group. Declared only for what the repository's own
+   * declarations cannot say — a credential no `.npmrc` reference and no cache
+   * token identifies, or one whose derivation is deliberately overridden.
+   */
+  readonly group?: SecretGroup;
+}
+
+/** A declared secret with its group settled: explicit if stated, derived otherwise. */
+export interface GroupedSecret {
+  readonly name: string;
+  /** The group that resolves it: `spec.group` when declared, `derivedGroup` otherwise. */
+  readonly group: SecretGroup;
+  /**
+   * What this repository's own declarations imply, kept beside the effective
+   * group so an override is a visible fact rather than a silent one. Equal to
+   * `group` unless the entry declares a different one.
+   */
+  readonly derivedGroup: SecretGroup;
+  readonly spec: SecretSpec;
 }
 
 export type SecretCommandRunner = (argv: readonly string[]) => Promise<string>;
 
 export interface SecretResolutionRequest {
-  readonly secrets: Readonly<Record<string, SecretSpec>>;
-  /** Env names referenced from `.npmrc`; registry routing intent inside a cowshed workspace. */
-  readonly registryIntentEnvs: ReadonlySet<string>;
+  /** Every declared secret of the repository, each with its group settled. */
+  readonly secrets: readonly GroupedSecret[];
+  /** The one group to resolve. No default: the wrong one is a credential prompt. */
+  readonly group: SecretGroup;
   /** Environment consulted for existing values and mode flags; read, never written. */
   readonly env: Readonly<Record<string, string | undefined>>;
   /** Overrides the default direct-argv runner (test seam). */
@@ -62,21 +155,71 @@ export interface SecretResolutionRequest {
 export interface SecretResolutionOptions {
   /** Repository root holding package.json and .npmrc. */
   readonly root: string;
+  /** The one group to resolve. No default: the wrong one is a credential prompt. */
+  readonly group: SecretGroup;
   /** Environment to consult; defaults to process.env. Read, never written. */
   readonly env?: Record<string, string | undefined>;
   /** Overrides the default direct-argv runner (test seam). */
   readonly runCommand?: SecretCommandRunner;
 }
 
+/** A declared secret this request declined to resolve, and how to supply it. */
+export interface DeferredSecret {
+  readonly name: string;
+  readonly group: SecretGroup;
+  readonly guidance: string;
+}
+
+/**
+ * The resolution as a value: what belongs in a child's environment, and what
+ * was deliberately left out of it. Every declared secret appears in exactly
+ * one of `values`, `deferred`, or neither — the environment already carried
+ * it.
+ */
+export interface SecretResolution {
+  readonly values: Readonly<Record<string, string>>;
+  readonly deferred: readonly DeferredSecret[];
+}
+
 /**
  * The env name pattern every shell accepts, so the same regex classifies
  * declared names and `.npmrc` references without echoing values.
  */
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+/**
+ * A group label's shape, and only its shape. It is one argv word of
+ * `smoo secrets run <group> <command...>`, so whitespace would make the
+ * command unwritable; every other value is the repository's business.
+ */
+const GROUP_NAME = /^\S+$/;
+
 /** The `.npmrc` interpolations Bun substitutes while reading auth and registry config. */
 const NPMRC_ENV_REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
 
+/**
+ * The command that resolves one group for exactly one child process. Every
+ * deferral names it, so what a developer reads is the command to run next
+ * rather than a description of one.
+ */
+const ON_DEMAND_COMMAND = 'smoo secrets run';
+
+/**
+ * Groups an operation depends on without resolving them, keyed by the group
+ * it does resolve. Shell entry runs `bun install`, which reads `.npmrc` —
+ * the declaration that derives `registry`. This is a dependency edge, not an
+ * exclusion: it makes CI and a cowshed workspace refuse a registry credential
+ * they cannot supply later, where a group nothing depends on stays silent.
+ */
+const DEPENDENT_GROUPS: Readonly<Record<string, readonly SecretGroup[]>> = {
+  [SHELL_GROUP]: [REGISTRY_GROUP],
+};
+
+/** Groups a request for `group` needs supplied but does not resolve itself. */
+export function dependentGroups(group: SecretGroup): readonly SecretGroup[] {
+  return DEPENDENT_GROUPS[group] ?? [];
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -125,7 +268,16 @@ function parseSecretSpec(name: string, spec: unknown): SecretSpec {
     }
   }
   const [first, ...rest] = raw;
-  return { command: [first, ...rest] };
+  const group = spec.group;
+  if (group === undefined) {
+    return { command: [first, ...rest] };
+  }
+  if (typeof group !== 'string' || !GROUP_NAME.test(group)) {
+    throw new Error(
+      `smoo.secrets.${name}.group: must be a nonempty label without whitespace, so \`${ON_DEMAND_COMMAND} <group>\` can name it`,
+    );
+  }
+  return { command: [first, ...rest], group };
 }
 
 /**
@@ -136,7 +288,7 @@ function parseSecretSpec(name: string, spec: unknown): SecretSpec {
  */
 export interface RemoteCacheSpec {
   readonly server: string;
-  /** Variable holding the cache token: an ambient value, or a `smoo.secrets` entry resolved here. */
+  /** Variable holding the cache token: an ambient value, or a `smoo.secrets` entry in group `nx-cache`. */
   readonly tokenSecret: string;
 }
 
@@ -181,88 +333,139 @@ export function registryAuthEnvNames(npmrcText: string | null): ReadonlySet<stri
   return names;
 }
 
+/** What a repository's own declarations say about one variable, before any override. */
+export interface GroupDerivationContext {
+  /** Env names referenced from `.npmrc`: which declared secrets a registry request needs. */
+  readonly registryIntentEnvs: ReadonlySet<string>;
+  /** The variable `smoo.remoteCache.tokenSecret` names, or null when no cache is declared. */
+  readonly cacheTokenEnv: string | null;
+}
+
+/**
+ * The group a repository's existing declarations already imply for one
+ * variable. The cache token is checked first: a variable that is both the
+ * declared cache token and `.npmrc`-referenced was excluded from shell entry
+ * outright before groups existed, and `nx-cache` is the group that keeps that
+ * true.
+ */
+export function deriveSecretGroup(name: string, context: GroupDerivationContext): SecretGroup {
+  if (context.cacheTokenEnv === name) return NX_CACHE_GROUP;
+  if (context.registryIntentEnvs.has(name)) return REGISTRY_GROUP;
+  return SHELL_GROUP;
+}
+
+/** Every declared secret with its group settled, in declaration order. */
+export function groupSecrets(
+  secrets: Readonly<Record<string, SecretSpec>>,
+  context: GroupDerivationContext,
+): readonly GroupedSecret[] {
+  return Object.entries(secrets).map(([name, spec]) => {
+    const derivedGroup = deriveSecretGroup(name, context);
+    return { name, group: spec.group ?? derivedGroup, derivedGroup, spec };
+  });
+}
+
 type SecretOutcome =
-  | { readonly name: string; readonly kind: 'env-wins' }
-  | { readonly name: string; readonly kind: 'resolved'; readonly value: string }
-  | { readonly name: string; readonly kind: 'failed'; readonly guidance: string };
+  | { readonly name: string; readonly group: SecretGroup; readonly kind: 'env-wins' }
+  | { readonly name: string; readonly group: SecretGroup; readonly kind: 'resolved'; readonly value: string }
+  | { readonly name: string; readonly group: SecretGroup; readonly kind: 'deferred'; readonly guidance: string }
+  | { readonly name: string; readonly group: SecretGroup; readonly kind: 'failed'; readonly guidance: string };
 
 /**
- * One variable's routing, the four rules in the header applied in order. It is
- * a value rather than a throw so each caller presents a failure in its own
- * terms: an install refuses, the remote cache turns itself off.
+ * One variable's routing, the four rules in the header applied in order. It
+ * is a value rather than a throw so each caller presents the result in its
+ * own terms: an install refuses, the remote cache turns itself off, and a
+ * deferred credential is named only if something then needs it.
  */
 async function routeSecret(
-  name: string,
-  spec: SecretSpec,
+  secret: GroupedSecret,
   context: {
     readonly env: Readonly<Record<string, string | undefined>>;
-    readonly registryIntentEnvs: ReadonlySet<string>;
+    readonly group: SecretGroup;
+    readonly dependsOn: readonly SecretGroup[];
     readonly run: SecretCommandRunner;
   },
 ): Promise<SecretOutcome> {
   const { env } = context;
+  const { name, group } = secret;
   if (isNonemptyEnvValue(env[name])) {
-    return { name, kind: 'env-wins' };
+    return { name, group, kind: 'env-wins' };
   }
-  if (isNonemptyEnvValue(env.CI)) {
-    return {
-      name,
-      kind: 'failed',
-      guidance:
-        'CI does not run secret provider commands — inject this variable into the job environment from the CI secret store',
-    };
+  const requested = group === context.group;
+  if (requested || context.dependsOn.includes(group)) {
+    if (isNonemptyEnvValue(env.CI)) {
+      return {
+        name,
+        group,
+        kind: 'failed',
+        guidance:
+          'CI does not run secret provider commands — inject this variable into the job environment from the CI secret store',
+      };
+    }
+    if (group === REGISTRY_GROUP && isNonemptyEnvValue(env.COWSHED_WORKSPACE_TOKEN)) {
+      return {
+        name,
+        group,
+        kind: 'failed',
+        guidance:
+          'a registry credential absent in this cowshed workspace — enroll registry credentials through the cowshed gateway; gateway-managed workspaces never resolve a registry credential via a local provider command',
+      };
+    }
   }
-  if (isNonemptyEnvValue(env.COWSHED_WORKSPACE_TOKEN) && context.registryIntentEnvs.has(name)) {
+  if (!requested) {
     return {
       name,
-      kind: 'failed',
-      guidance:
-        'referenced from .npmrc and absent in this cowshed workspace — enroll registry credentials through the cowshed gateway; gateway-managed workspaces never resolve .npmrc registry variables via local provider commands',
+      group,
+      kind: 'deferred',
+      guidance: `in group \`${group}\`, which a \`${context.group}\` request does not resolve — run \`${ON_DEMAND_COMMAND} ${group} <command>\` to supply it to that one command`,
     };
   }
   try {
-    const value = (await context.run(spec.command)).replace(/\r?\n$/, '');
+    const value = (await context.run(secret.spec.command)).replace(/\r?\n$/, '');
     if (value.length === 0) {
       return {
         name,
+        group,
         kind: 'failed',
         guidance:
           'provider command produced no output — run it locally to see why (its arguments and output are never logged here)',
       };
     }
-    return { name, kind: 'resolved', value };
+    return { name, group, kind: 'resolved', value };
   } catch (error) {
-    return { name, kind: 'failed', guidance: describeCommandFailure(error) };
+    return { name, group, kind: 'failed', guidance: describeCommandFailure(error) };
   }
 }
 
-export async function resolveSecrets(request: SecretResolutionRequest): Promise<Readonly<Record<string, string>>> {
+export async function resolveSecrets(request: SecretResolutionRequest): Promise<SecretResolution> {
   const context = {
     env: request.env,
-    registryIntentEnvs: request.registryIntentEnvs,
+    group: request.group,
+    dependsOn: dependentGroups(request.group),
     run: request.runCommand ?? runSecretCommand,
   };
-  const outcomes = await Promise.all(
-    Object.entries(request.secrets).map(async ([name, spec]) => routeSecret(name, spec, context)),
-  );
+  const outcomes = await Promise.all(request.secrets.map(async (secret) => routeSecret(secret, context)));
   const failures = outcomes.filter(
     (outcome): outcome is Extract<SecretOutcome, { kind: 'failed' }> => outcome.kind === 'failed',
   );
   if (failures.length > 0) {
     throw new Error(
       [
-        'smoo secret resolution failed; dependencies were not installed:',
-        ...failures.map((failure) => `- ${failure.name}: ${failure.guidance}`),
+        'smoo secret resolution failed:',
+        ...failures.map((failure) => `- ${failure.name} (${failure.group}): ${failure.guidance}`),
       ].join('\n'),
     );
   }
-  const resolved: Record<string, string> = {};
+  const values: Record<string, string> = {};
+  const deferred: DeferredSecret[] = [];
   for (const outcome of outcomes) {
     if (outcome.kind === 'resolved') {
-      resolved[outcome.name] = outcome.value;
+      values[outcome.name] = outcome.value;
+    } else if (outcome.kind === 'deferred') {
+      deferred.push({ name: outcome.name, group: outcome.group, guidance: outcome.guidance });
     }
   }
-  return resolved;
+  return { values, deferred };
 }
 
 class SecretCommandExitError extends Error {
@@ -378,28 +581,29 @@ function indexOfBytes(haystack: Uint8Array, needle: Uint8Array, from: number): n
 }
 
 /**
- * The declared secrets an install needs, resolved before it runs. The cache
- * token is deliberately not among them: a remote cache is an optimization, so
- * its credential is resolved by the shell's cache export — where an
- * unreachable secret provider costs a stderr line — while every secret an
- * install actually depends on still refuses loudly here. Which variable that
- * is comes from `smoo.remoteCache.tokenSecret` rather than a second flag, so
- * the two declarations cannot disagree.
+ * Every declared secret of the repository at `root`, each with its group
+ * settled from that repository's own declarations. The listing
+ * `smoo secrets run` prints and the routing below read the same value, so the
+ * groups a developer is offered are exactly the groups that resolve.
  */
-export async function resolveSecretEnvironment(
-  options: SecretResolutionOptions,
-): Promise<Readonly<Record<string, string>>> {
-  const packageJson = readPackageJson(options.root);
-  const cacheToken = parseSmooRemoteCache(packageJson)?.tokenSecret;
-  const required: Record<string, SecretSpec> = {};
-  for (const [name, spec] of Object.entries(parseSmooSecrets(packageJson))) {
-    if (name !== cacheToken) {
-      required[name] = spec;
-    }
-  }
+export function readSecretGroups(root: string): readonly GroupedSecret[] {
+  const packageJson = readPackageJson(root);
+  return groupSecrets(parseSmooSecrets(packageJson), {
+    registryIntentEnvs: registryAuthEnvNames(readNpmrcText(root)),
+    cacheTokenEnv: parseSmooRemoteCache(packageJson)?.tokenSecret ?? null,
+  });
+}
+
+/**
+ * The declared secrets of `options.group`, resolved before the thing that
+ * needs them runs. Everything outside that group comes back deferred: named,
+ * unresolved, and not a failure — except where rule 2 applies, which is a
+ * context that could not honour the deferral anyway.
+ */
+export async function resolveSecretEnvironment(options: SecretResolutionOptions): Promise<SecretResolution> {
   return resolveSecrets({
-    secrets: required,
-    registryIntentEnvs: registryAuthEnvNames(readNpmrcText(options.root)),
+    secrets: readSecretGroups(options.root),
+    group: options.group,
     env: options.env ?? process.env,
     runCommand: options.runCommand,
   });

package/managed/raw/tooling/direnv/setup-environment.ts

@@ -4,7 +4,13 @@ import { mkdir, rmdir, stat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { $ } from 'bun';
-import { maskSecretValues, resolveSecretEnvironment } from './secret-references.ts';
+import {
+  type DeferredSecret,
+  dependentGroups,
+  maskSecretValues,
+  resolveSecretEnvironment,
+  SHELL_GROUP,
+} from './secret-references.ts';
 
 // DEVENV_ROOT is set by the devenv shell, which is how this script normally
 // runs. CI jobs that install dependencies without building that shell (the
@@ -32,6 +38,15 @@ class CapturedCommandError extends Error {
 // of the failure it was called to report.
 const resolvedSecretValues: string[] = [];
 
+// The declared secrets shell entry deliberately did NOT resolve — see THE
+// RULE in secret-references.ts: shell entry resolves the `shell` group and
+// nothing else. Nonempty only when this repository declares a secret in
+// another group that is absent from this environment. An installed checkout
+// contacts no registry and Nx needs no cache to run, so this stays silent;
+// it is printed by reportDegradedSetup, where an install has already failed
+// and a 401 is one of the things it might have been.
+const deferredSecrets: DeferredSecret[] = [];
+
 async function resolveProjectRoot(): Promise<string> {
   if (devenvRoot) {
     return path.resolve(`${devenvRoot}/../..`);
@@ -145,12 +160,22 @@ try {
  * scripts it runs, and every later child of this script inherit them (for
  * example .npmrc `${VAR}` auth); the direnv shell itself does not, which is
  * the point: this script must never act as a global shell export.
+ *
+ * `shell` is the group, and it is what keeps a credential only a deliberate
+ * command needs — a registry token, the Nx cache token — from running its
+ * provider command on every direnv reload. Such a variable comes back
+ * deferred instead of resolved, and an install proceeds without it — which
+ * is the normal case, because an installed checkout contacts no registry.
+ * The install that does need one fails, and reportDegradedSetup then names
+ * the variable and the exact command that supplies it.
  */
 async function resolveSecrets(): Promise<void> {
-  for (const [name, value] of Object.entries(await resolveSecretEnvironment({ root: projectRoot }))) {
+  const resolution = await resolveSecretEnvironment({ root: projectRoot, group: SHELL_GROUP });
+  for (const [name, value] of Object.entries(resolution.values)) {
     process.env[name] = value;
     resolvedSecretValues.push(value);
   }
+  deferredSecrets.push(...resolution.deferred);
 }
 
 async function installLocalDependencies(): Promise<unknown> {
@@ -416,6 +441,7 @@ function reportSetupFailure(error: unknown): never {
 
 function reportDegradedSetup(error: unknown): void {
   describeFailure('WARNING', error);
+  reportDeferredSecrets();
   console.error(
     'The shell is loaded WITHOUT installed dependencies so the tools to repair this stay available.\n' +
       'Fix the cause above (missing registry credential, unpublished package, stale lockfile → `devenv update`),\n' +
@@ -424,6 +450,36 @@ function reportDegradedSetup(error: unknown): void {
   console.error('---');
 }
 
+/**
+ * The declared secrets this shell entry deliberately did not resolve, named
+ * now that an install has actually failed. Printing them on a healthy shell
+ * entry would be noise on every reload — an installed checkout contacts no
+ * registry and needs none of them — while an install that failed may be
+ * exactly the 401 they explain, and then the useful output is the variable
+ * and the command that supplies it.
+ */
+function reportDeferredSecrets(): void {
+  if (deferredSecrets.length === 0) {
+    return;
+  }
+  console.error('Secrets outside the `shell` group are not resolved at shell entry, by design:');
+  for (const secret of deferredSecrets) {
+    console.error(`- ${secret.name} (${secret.group}): ${secret.guidance}`);
+  }
+  // Only a group the install itself reads can explain this failure, and only
+  // for those is re-running the install the command worth printing. A group
+  // nothing here consumes — the Nx cache token — is listed above and left
+  // alone: it did not cause this and re-running the install with it would
+  // not fix it.
+  for (const group of dependentGroups(SHELL_GROUP)) {
+    if (!deferredSecrets.some((secret) => secret.group === group)) {
+      continue;
+    }
+    console.error(`The install reads group \`${group}\`; supply it to exactly that one command with:`);
+    console.error(`  smoo secrets run ${group} bun install`);
+  }
+}
+
 function describeFailure(level: 'ERROR' | 'WARNING', error: unknown): void {
   if (error instanceof CapturedCommandError) {
     console.error(`--- ${level}: setup-environment.ts failed while running: ${error.command}`);

package/managed/raw/tsconfig.lib.json

@@ -0,0 +1,28 @@
+{
+  // The managed raw scripts are their own TypeScript project, and must be:
+  // they run as plain Bun source during bootstrap — before any workspace
+  // package, before node_modules, before the Typia transform — so they can
+  // belong to no project that assumes those. This file is what says so.
+  //
+  // It is also load-bearing at runtime. Bun's ttsc loader (see
+  // packages/validation/src/bun/preload.ts) routes each file to the nearest
+  // `tsconfig.lib.json` above it; without this one, a raw script under
+  // managed/ routed to packages/cli/tsconfig.lib.json, whose `include` is
+  // `src/**/*.ts`, and the transform returned no output at all. `smoo secrets
+  // run` imports secret-references.ts from here, and a consuming repo does
+  // the same from inside node_modules, so this file ships with the package.
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": false,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["**/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smoothbricks/cli",
-  "version": "0.11.19",
+  "version": "0.11.21",
   "type": "module",
   "description": "SmoothBricks monorepo automation CLI",
   "bin": {
@@ -39,6 +39,11 @@
       "import": "./dist/release/pack.js",
       "default": "./dist/release/pack.js"
     },
+    "./secrets": {
+      "types": "./dist/secrets/status.d.ts",
+      "import": "./dist/secrets/status.js",
+      "default": "./dist/secrets/status.js"
+    },
     "./wrangler/prepare-env": {
       "types": "./dist/wrangler/prepare-env.d.ts",
       "import": "./dist/wrangler/prepare-env.js",
@@ -64,7 +69,7 @@
   ],
   "dependencies": {
     "@arethetypeswrong/core": "^0.18.2",
-    "@smoothbricks/nx-plugin": "0.4.13",
+    "@smoothbricks/nx-plugin": "0.4.15",
     "@smoothbricks/validation": "0.1.8",
     "commander": "^14.0.3",
     "make-synchronized": "^0.8.0",