@smoothbricks/cli 0.11.19 → 0.11.21

package/src/secrets/commands.ts

@@ -1,5 +1,5 @@
 /**
- * `smoo secrets` — the operator side of the reconciliation in ./index.ts.
+ * `smoo secrets` — the operator side of the reconciliation in ./status.ts.
  *
  * Values are handed to `gh` over stdin, never through argv (a process list is
  * world-readable) and never printed. Reading one from the terminal disables
@@ -18,19 +18,25 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { getWorkspacePackages } from '../lib/workspace.js';
 import {
-  environmentsMissing,
   fetchLocalSecret,
-  localSecretCommandNames,
-  reconcileSecrets,
-  type SecretRow,
+  localSecretGroups,
   secretNameMapping,
-  unsatisfiedSecrets,
-  unwiredSecrets,
   workerSecretNames,
+  workerSecretStages,
   workflowEnvironments,
   workflowSecretNames,
 } from './index.js';
 import { resolveRepository } from './repository.js';
+import {
+  type LocalSecret,
+  projectSecretsStatus,
+  reconcileSecrets,
+  type SecretRow,
+  type SecretsStatusDocument,
+  type SecretsStatusEnvironment,
+  stringifySecretsStatusDocument,
+  unwiredSecrets,
+} from './status.js';
 
 /**
  * Every secret this checkout declares that the repository does not hold, in
@@ -129,21 +135,25 @@ export async function writeRepositorySecret(
 
 function collectSources(
   root: string,
+  workspaceDirs: readonly string[],
+  localSecrets: readonly LocalSecret[],
   repositorySecrets: readonly string[],
   environmentSecrets: Readonly<Record<string, readonly string[]>> = {},
 ) {
-  const workspaceDirs = getWorkspacePackages(root).map((pkg) => pkg.path);
   const workerSecrets = workerSecretNames(root, workspaceDirs);
   const workflowSecrets = workflowSecretNames(root);
-  const localCommands = localSecretCommandNames(root);
   const envNames = [
-    ...new Set([...Object.values(workerSecrets).flatMap((names) => [...names]), ...workflowSecrets, ...localCommands]),
+    ...new Set([
+      ...Object.values(workerSecrets).flatMap((names) => [...names]),
+      ...workflowSecrets,
+      ...localSecrets.map((secret) => secret.name),
+    ]),
   ];
   return {
     workerSecrets,
     workflowSecrets,
     secretNames: secretNameMapping(root, envNames),
-    localCommands,
+    localSecrets,
     repositorySecrets,
     environmentSecrets,
   };
@@ -167,46 +177,96 @@ function describe(row: SecretRow, scopeWidth: number): string {
 }
 
 /**
- * Print every known secret and the scopes holding it. Exit code 1 when a
- * workflow promises a value no scope a bound job reads can supply — that
- * combination is the one that fails a deploy, and it fails talking about the
- * value rather than the missing secret.
+ * Everything `status` reports, read from git, `gh` and the checkout before a
+ * single line is printed. Gathering ahead of rendering is what lets one run
+ * answer either a human or a machine from exactly the same facts: `--json`
+ * cannot drift from the table because there is nothing for it to drift from.
  */
-export function secretsStatus(root: string, options: { repo?: string; env?: string }): number {
+async function gatherSecretsStatus(
+  root: string,
+  options: { repo?: string; env?: string },
+): Promise<{ ok: true; document: SecretsStatusDocument } | { ok: false; reason: string }> {
   const resolved = resolveRepository(root, options.repo);
-  if (!resolved.ok) {
-    console.error(resolved.reason);
-    return 1;
-  }
+  if (!resolved.ok) return resolved;
   const { repo, source } = resolved.choice;
   const repositorySecrets = readRepositorySecrets(repo);
-  if (!repositorySecrets.ok) {
-    console.error(repositorySecrets.reason);
-    return 1;
-  }
+  if (!repositorySecrets.ok) return repositorySecrets;
   // The workflows decide which environments a job reads; an explicitly asked
   // for one is shown too, so an operator can inspect a scope before a workflow
   // binds it.
   const boundEnvironments = workflowEnvironments(root);
   const asked = options.env !== undefined && !boundEnvironments.includes(options.env) ? [options.env] : [];
   const environmentSecrets: Record<string, string[]> = {};
-  const unreadable: { environment: string; reason: string }[] = [];
-  for (const environment of [...boundEnvironments, ...asked]) {
-    const held = readRepositorySecrets(repo, environment);
-    if (held.ok) environmentSecrets[environment] = held.names;
-    else unreadable.push({ environment, reason: held.reason });
+  const environments: SecretsStatusEnvironment[] = [];
+  for (const name of [...boundEnvironments, ...asked]) {
+    const bound = boundEnvironments.includes(name);
+    const held = readRepositorySecrets(repo, name);
+    // An environment that cannot be read is reported, never assumed empty:
+    // guessing produces a refusal about a value that may well be set.
+    if (!held.ok) {
+      environments.push({ name, bound, readable: false, reason: held.reason });
+      continue;
+    }
+    environmentSecrets[name] = held.names;
+    environments.push({ name, bound, readable: true, secretCount: held.names.length });
   }
-  // An environment that cannot be read is reported, never assumed empty:
-  // guessing produces a refusal about a value that may well be set.
-  const readable = boundEnvironments.filter((environment) => environment in environmentSecrets);
-  const rows = reconcileSecrets(collectSources(root, repositorySecrets.names, environmentSecrets));
+  const workspaceDirs = getWorkspacePackages(root).map((pkg) => pkg.path);
+  const stageScopes = workerSecretStages(root, workspaceDirs);
+  if (!stageScopes.ok) return stageScopes;
+  // A `smoo.secrets` declaration smoo cannot read is a refusal, not an empty
+  // list: reporting "nothing is fetchable locally" for a manifest that says
+  // otherwise is the confident wrong answer.
+  const localSecrets = await localSecretGroups(root);
+  if (!localSecrets.ok) return localSecrets;
+  return {
+    ok: true,
+    document: projectSecretsStatus({
+      repository: { repo, source, secretCount: repositorySecrets.names.length },
+      environments,
+      rows: reconcileSecrets(
+        collectSources(root, workspaceDirs, localSecrets.secrets, repositorySecrets.names, environmentSecrets),
+      ),
+      stageScopes: stageScopes.byWorker,
+    }),
+  };
+}
+
+/**
+ * Print every known secret and the scopes holding it, or - with `json` - the
+ * same facts as one document on stdout and nothing else. Exit code 1 when a
+ * workflow promises a value no scope a bound job reads can supply — that
+ * combination is the one that fails a deploy, and it fails talking about the
+ * value rather than the missing secret. `--json` reports that refusal in
+ * `unsatisfied` and still exits 1: a machine-readable status that always
+ * succeeded would be a status nobody could gate on.
+ */
+export async function secretsStatus(
+  root: string,
+  options: { repo?: string; env?: string; json?: boolean },
+): Promise<number> {
+  const gathered = await gatherSecretsStatus(root, options);
+  if (!gathered.ok) {
+    console.error(gathered.reason);
+    return 1;
+  }
+  const { document } = gathered;
+  const { repo, source } = document.repository;
+  if (options.json) {
+    console.log(stringifySecretsStatusDocument(document));
+    return document.unsatisfied.length > 0 ? 1 : 0;
+  }
+  const rows = document.secrets;
 
-  console.log(`repository ${repo} (${source}), holding ${repositorySecrets.names.length} secrets`);
-  for (const [environment, names] of Object.entries(environmentSecrets)) {
-    console.log(`environment ${environment}, holding ${names.length} secrets`);
+  console.log(`repository ${repo} (${source}), holding ${document.repository.secretCount} secrets`);
+  for (const environment of document.environments) {
+    if (environment.readable)
+      console.log(`environment ${environment.name}, holding ${environment.secretCount} secrets`);
   }
-  for (const { environment, reason } of unreadable) {
-    console.log(`environment ${environment} could not be read, so nothing below claims what it holds: ${reason}`);
+  for (const environment of document.environments) {
+    if (environment.readable) continue;
+    console.log(
+      `environment ${environment.name} could not be read, so nothing below claims what it holds: ${environment.reason}`,
+    );
   }
   const scopeWidth = Math.max('held by'.length, ...rows.map((row) => heldBy(row).length));
   console.log(`${'held by'.padEnd(scopeWidth)}  ${'name'.padEnd(32)}  workflow  local  declared by`);
@@ -222,6 +282,25 @@ export function secretsStatus(root: string, options: { repo?: string; env?: stri
       );
     }
   }
+  // A declared `group` that disagrees with what this repository's own
+  // declarations derive is the override working — and a silent override is
+  // how the next reader loses an hour wondering why a `.npmrc` credential
+  // resolves at shell entry. It is stated here, where a human is already
+  // looking at every declared secret.
+  const overridden = rows.filter(
+    (row) => row.localGroup !== undefined && row.localGroup.resolves !== row.localGroup.derived,
+  );
+  if (overridden.length > 0) {
+    console.log('');
+    for (const row of overridden) {
+      const local = row.localGroup;
+      if (local === undefined) continue;
+      console.log(
+        `note: ${row.name} declares group \`${local.resolves}\`, overriding the \`${local.derived}\` this ` +
+          `repository's declarations derive; \`smoo secrets run ${local.resolves} <command>\` is what resolves it.`,
+      );
+    }
+  }
   // A value an environment holds is not a value to duplicate at repository
   // scope: offering it invites two sources of truth for one credential, and
   // the table above already shows where it lives. Only a name no scope holds
@@ -236,22 +315,20 @@ export function secretsStatus(root: string, options: { repo?: string; env?: stri
     console.log(`set one:                        smoo secrets set ${needed[0]?.repositorySecret ?? 'NAME'} -R ${repo}`);
   }
 
-  const unsatisfied = unsatisfiedSecrets(rows, readable);
-  if (unsatisfied.length === 0) return 0;
+  if (document.unsatisfied.length === 0) return 0;
   console.log('');
-  for (const row of unsatisfied) {
-    const missing = environmentsMissing(row, readable);
-    const scopes = missing.length > 0 ? missing.join(', ') : 'the repository';
-    console.error(`missing: ${row.name} — a workflow passes secrets.${row.name} and no value exists in ${scopes}.`);
-    if (missing.length === 0) {
-      console.error(`  smoo secrets set ${row.repositorySecret} -R ${repo}`);
+  for (const { name, repositorySecret, missingIn } of document.unsatisfied) {
+    const scopes = missingIn.length > 0 ? missingIn.join(', ') : 'the repository';
+    console.error(`missing: ${name} — a workflow passes secrets.${name} and no value exists in ${scopes}.`);
+    if (missingIn.length === 0) {
+      console.error(`  smoo secrets set ${repositorySecret} -R ${repo}`);
       continue;
     }
-    for (const environment of missing) {
+    for (const environment of missingIn) {
       const named = environment.includes(' ') ? `'${environment}'` : environment;
-      console.error(`  smoo secrets set ${row.repositorySecret} -R ${repo} --env ${named}`);
+      console.error(`  smoo secrets set ${repositorySecret} -R ${repo} --env ${named}`);
     }
-    console.error(`  or one value for every environment:  smoo secrets set ${row.repositorySecret} -R ${repo}`);
+    console.error(`  or one value for every environment:  smoo secrets set ${repositorySecret} -R ${repo}`);
   }
   return 1;
 }
@@ -318,7 +395,13 @@ export async function secretsSet(
     }
     environmentSecrets[environment] = inEnvironment.names;
   }
-  const rows = reconcileSecrets(collectSources(root, held.names, environmentSecrets));
+  const workspaceDirs = getWorkspacePackages(root).map((pkg) => pkg.path);
+  const local = await localSecretGroups(root);
+  if (!local.ok) {
+    console.error(local.reason);
+    return 1;
+  }
+  const rows = reconcileSecrets(collectSources(root, workspaceDirs, local.secrets, held.names, environmentSecrets));
   const needed =
     environment === undefined ? secretsNeedingValues(rows) : secretsMissingInEnvironment(rows, environment);
   const target =
@@ -386,7 +469,15 @@ export async function secretsSync(root: string, options: { repo?: string; env?:
   }
   const { repo } = resolved.choice;
   const environment = options.env;
-  const names = localSecretCommandNames(root);
+  const local = await localSecretGroups(root);
+  if (!local.ok) {
+    console.error(local.reason);
+    return 1;
+  }
+  // Every group: a repository secret store holds the credential whatever
+  // resolves it locally, and a `smoo secrets run` group is about which
+  // command pays the provider prompt, not about which values CI needs.
+  const names = local.secrets.map((secret) => secret.name);
   if (names.length === 0) {
     console.error('smoo.secrets declares no fetch commands; nothing to sync.');
     return 1;

package/src/secrets/index.test.ts

@@ -3,14 +3,8 @@ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { repositorySecretMapping } from '../lib/secret-names.js';
-import {
-  environmentsMissing,
-  reconcileSecrets,
-  type SecretRow,
-  unsatisfiedSecrets,
-  unwiredSecrets,
-  workflowEnvironments,
-} from './index.js';
+import { workflowEnvironments } from './index.js';
+import { environmentsMissing, reconcileSecrets, type SecretRow, unsatisfiedSecrets, unwiredSecrets } from './status.js';
 
 const sources = {
   workerSecrets: {
@@ -18,7 +12,7 @@ const sources = {
     'targets/mail': ['MAIL_CAPTURE_CONTROL_TOKEN'],
   },
   workflowSecrets: ['MAIL_CAPTURE_CONTROL_TOKEN', 'STRIPE_PUBLISHABLE_KEY', 'STRIPE_SECRET_KEY'],
-  localCommands: ['NPM_READ_TOKEN'],
+  localSecrets: [{ name: 'NPM_READ_TOKEN', group: 'registry', derivedGroup: 'registry' }],
   secretNames: {
     STRIPE_PUBLISHABLE_KEY: 'STRIPE_PUBLISHABLE_KEY',
     STRIPE_SECRET_KEY: 'STRIPE_SECRET_KEY',
@@ -84,7 +78,7 @@ describe('secret reconciliation', () => {
       workerSecrets: { 'targets/backend': ['GITHUB_CLIENT_SECRET'] },
       workflowSecrets: ['GITHUB_CLIENT_SECRET'],
       secretNames: repositorySecretMapping(['GITHUB_CLIENT_SECRET'], 'acme'),
-      localCommands: [],
+      localSecrets: [],
       repositorySecrets: ['ACME_GITHUB_CLIENT_SECRET'],
     });
 

package/src/secrets/index.ts

@@ -1,9 +1,11 @@
 /**
- * Reconciles the three places a repository's secrets are described, all of
- * which smoo already owns:
+ * Reads the three places a repository's secrets are described, all of which
+ * smoo already owns:
  *
  * 1. **Workers declare names.** `.dev.vars.example` per wrangler project — the
- *    file `wrangler types --env-file` reads and `prepare-env` prompts from.
+ *    file `wrangler types --env-file` reads and `prepare-env` prompts from —
+ *    and `smoo.wrangler.secretStages` beside it says which stages each name
+ *    belongs to.
  * 2. **Workflows declare where values come from.** `smoo.github.deploySecrets`
  *    and `e2eSecrets` map an env name to a repository secret, and the managed
  *    workflows render exactly those into the job environment.
@@ -17,6 +19,9 @@
  * `STRIPE_PUBLISHABLE_KEY`, `ci.yml` passes `secrets.STRIPE_PUBLISHABLE_KEY`,
  * the repository holds no such secret, and the empty value surfaces as the
  * payment library's own `publishable_key_mismatch` refusal.
+ *
+ * The join itself is ./status.ts: pure, and the owner of the document type
+ * these readings are projected into.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -25,114 +30,8 @@ import { join } from 'node:path';
 import { repositoryOwnerFromUrl, repositorySecretMapping } from '../lib/secret-names.js';
 import { readPackageJsonObject, repositoryInfo } from '../lib/workspace.js';
 import { parseDevVarsExample } from '../wrangler/prepare-env.js';
-
-/** Where an env name is described, which repository secret carries it, and whether that exists. */
-export interface SecretRow {
-  name: string;
-  /** The repository secret this env name reads from, by convention or declaration. */
-  repositorySecret: string;
-  /** Wrangler projects whose `.dev.vars.example` declares it. */
-  declaredByWorkers: string[];
-  /** True when a managed workflow renders `secrets.<name>` into a job. */
-  suppliedByWorkflow: boolean;
-  /** True when `smoo.secrets` can fetch it for a developer shell. */
-  fetchableLocally: boolean;
-  /** True when the repository holds a secret of this name. */
-  onRepository: boolean;
-  /**
-   * GitHub Environments holding their own value for this name. A job bound to
-   * an environment reads that value in preference to the repository's, which
-   * is how one name carries test credentials on a preview stage and live ones
-   * in production.
-   */
-  heldByEnvironment: string[];
-}
-
-export interface SecretSources {
-  /** Worker label -> env names it declares. */
-  workerSecrets: Record<string, readonly string[]>;
-  /** Env names a managed workflow passes into a job. */
-  workflowSecrets: readonly string[];
-  /** Env name -> repository secret, by convention with declared exceptions. */
-  secretNames: Readonly<Record<string, string>>;
-  /** Env names `smoo.secrets` can fetch locally. */
-  localCommands: readonly string[];
-  /** Repository secret names GitHub currently holds. */
-  repositorySecrets: readonly string[];
-  /** Environment name -> secret names that environment holds. */
-  environmentSecrets?: Readonly<Record<string, readonly string[]>>;
-}
-
-/**
- * One row per name known to any source, sorted, so a reader sees the whole
- * picture rather than one source's view of it.
- */
-export function reconcileSecrets(sources: SecretSources): SecretRow[] {
-  const declaredByAnyWorker: string[] = Object.values(sources.workerSecrets).flatMap((names) => [...names]);
-  const names = new Set<string>([...declaredByAnyWorker, ...sources.workflowSecrets, ...sources.localCommands]);
-  // A repository secret that already carries a known env name is that name's
-  // row, not a row of its own: listing ACME_GITHUB_CLIENT_SECRET beside
-  // GITHUB_CLIENT_SECRET would report one value as two secrets, one of them
-  // permanently "declared by nothing".
-  const carriesKnownEnvName = new Set(
-    names.size > 0 ? [...names].map((name) => sources.secretNames[name] ?? name) : [],
-  );
-  // A value only an environment holds is still a value: leaving it out of the
-  // rows is how an operator ends up hunting for a secret that is already set.
-  const addUndeclared = (secret: string): void => {
-    if (!carriesKnownEnvName.has(secret)) names.add(secret);
-  };
-  for (const secret of sources.repositorySecrets) addUndeclared(secret);
-  for (const held of Object.values(sources.environmentSecrets ?? {})) {
-    for (const secret of held) addUndeclared(secret);
-  }
-  return [...names]
-    .sort((left, right) => left.localeCompare(right))
-    .map((name) => ({
-      name,
-      repositorySecret: sources.secretNames[name] ?? name,
-      declaredByWorkers: Object.entries(sources.workerSecrets)
-        .filter(([, declared]) => declared.includes(name))
-        .map(([label]) => label)
-        .sort((left, right) => left.localeCompare(right)),
-      suppliedByWorkflow: sources.workflowSecrets.includes(name),
-      fetchableLocally: sources.localCommands.includes(name),
-      onRepository: sources.repositorySecrets.includes(sources.secretNames[name] ?? name),
-      heldByEnvironment: Object.entries(sources.environmentSecrets ?? {})
-        .filter(([, held]) => held.includes(sources.secretNames[name] ?? name))
-        .map(([environment]) => environment)
-        .sort((left, right) => left.localeCompare(right)),
-    }));
-}
-
-/**
- * The rows a CI deploy cannot satisfy: a Worker declares the name, a workflow
- * promises to pass it, and the repository has no value to pass. Reported
- * separately from "declared but not wired into any workflow", because the
- * remedies differ — set a secret, versus declare it in `smoo.github`.
- */
-export function unsatisfiedSecrets(rows: readonly SecretRow[], boundEnvironments: readonly string[] = []): SecretRow[] {
-  return rows.filter((row) => {
-    if (!row.suppliedByWorkflow) return false;
-    if (row.onRepository) return false;
-    // With no environment bound, the repository is the only scope a job reads.
-    // With environments bound, each one can carry the value instead - so the
-    // name is satisfied only when every bound environment holds it.
-    if (boundEnvironments.length === 0) return true;
-    return !boundEnvironments.every((environment) => row.heldByEnvironment.includes(environment));
-  });
-}
-
-/** Bound environments that lack their own value and cannot fall back to the repository. */
-export function environmentsMissing(row: SecretRow, boundEnvironments: readonly string[]): string[] {
-  if (row.onRepository) return [];
-  return boundEnvironments.filter((environment) => !row.heldByEnvironment.includes(environment));
-}
-
-/** Worker-declared names no managed workflow passes: a CI deploy will run without them. */
-export function unwiredSecrets(rows: readonly SecretRow[]): SecretRow[] {
-  return rows.filter((row) => row.declaredByWorkers.length > 0 && !row.suppliedByWorkflow);
-}
+import { readSecretStageMap, type SecretStageMap } from '../wrangler/stage-secrets.js';
+import { type GroupedSecret, readSecretGroups } from './resolver.js';
 
 /** Env names the managed workflows pass into a job, from the declarations that render them. */
 export function workflowSecretNames(root: string): string[] {
@@ -250,10 +149,50 @@ export function workerSecretNames(root: string, workspaceDirs: readonly string[]
   return byWorker;
 }
 
-/** Names `smoo.secrets` declares a fetch command for. */
-export function localSecretCommandNames(root: string): string[] {
-  const manifest = readPackageJsonObject(join(root, 'package.json'));
-  return Object.keys(manifest?.smoo?.secrets ?? {}).sort((left, right) => left.localeCompare(right));
+/**
+ * Every wrangler project's `smoo.wrangler.secretStages`, keyed by the project
+ * directory — the same keys `workerSecretNames` uses, so a name's scopes and
+ * its declarations are joined on one label.
+ *
+ * A malformed block is a refusal rather than a throw: it is the same class of
+ * problem as a repository `gh` will not talk to, and `smoo secrets status`
+ * reports those instead of dying with a stack. Silently reading it as "no
+ * scopes" is the one thing this must not do — that is the direction where
+ * every secret quietly reaches every stage.
+ */
+export function workerSecretStages(
+  root: string,
+  workspaceDirs: readonly string[],
+): { ok: true; byWorker: Record<string, SecretStageMap> } | { ok: false; reason: string } {
+  const byWorker: Record<string, SecretStageMap> = {};
+  for (const dir of workspaceDirs) {
+    if (!existsSync(join(root, dir, '.dev.vars.example'))) continue;
+    try {
+      const scopes = readSecretStageMap(join(root, dir));
+      if (Object.keys(scopes).length > 0) byWorker[dir] = scopes;
+    } catch (error) {
+      return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+  }
+  return { ok: true, byWorker };
+}
+
+/**
+ * Every `smoo.secrets` entry with the group that resolves it, sorted by name,
+ * or a refusal naming the declaration that could not be read. The groups come
+ * from ./resolver.ts — the same file shell entry routes with — so a status
+ * table and a `smoo secrets run` cannot disagree about which group resolves
+ * a name.
+ */
+export async function localSecretGroups(
+  root: string,
+): Promise<{ ok: true; secrets: GroupedSecret[] } | { ok: false; reason: string }> {
+  try {
+    const secrets = await readSecretGroups(root);
+    return { ok: true, secrets: secrets.sort((left, right) => left.name.localeCompare(right.name)) };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
 }
 
 /**

package/src/secrets/resolver.ts

@@ -0,0 +1,130 @@
+/**
+ * The bootstrap secret resolver, as the CLI sees it.
+ *
+ * `managed/raw/tooling/direnv/secret-references.ts` holds the one
+ * implementation of THE RULE — which group resolves where, and what CI and a
+ * cowshed workspace refuse instead. A managed repository runs the copy smoo
+ * writes into its own `tooling/direnv/secret-references.ts` at shell entry;
+ * `smoo secrets run` runs THIS package's copy of the same file. One
+ * implementation, so the command and the shell cannot disagree about a group.
+ *
+ * It is loaded, not statically imported, and that is forced rather than
+ * chosen: the file is a raw bootstrap script that must load before any
+ * workspace package and before the Typia transform exists, so it lives
+ * outside `src` — outside this package's compiled `rootDir`, which a static
+ * import may not cross. A dynamic `import()` reaches it in both layouts
+ * (`src/secrets/` and `dist/secrets/` are each two directories below the
+ * package root), and typia validates what comes back: the same boundary
+ * ../monorepo/packed-package.ts puts around a foreign module. `require` is
+ * not the alternative — under a Bun loader plugin, which this package's own
+ * tests preload, every module is async and `require` of one throws.
+ */
+
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import typia from 'typia';
+
+/** A declared `smoo.secrets` entry with its group settled. */
+export interface GroupedSecret {
+  name: string;
+  /** The group that resolves it: the declared one when stated, `derivedGroup` otherwise. */
+  group: string;
+  /**
+   * What the repository's own declarations imply: `registry` for a variable
+   * `.npmrc` interpolates, `nx-cache` for the declared cache token, `shell`
+   * for everything else. Differs from `group` exactly when an entry overrides
+   * the derivation.
+   */
+  derivedGroup: string;
+}
+
+/** A declared secret a request declined to resolve, and how to supply it. */
+export interface DeferredSecret {
+  name: string;
+  group: string;
+  guidance: string;
+}
+
+/** What belongs in a child's environment, and what was deliberately left out of it. */
+export interface SecretResolution {
+  values: Record<string, string>;
+  deferred: DeferredSecret[];
+}
+
+interface SecretReferencesModule {
+  readSecretGroups?: unknown;
+  resolveSecretEnvironment?: unknown;
+}
+
+const isSecretReferencesModule = typia.createIs<SecretReferencesModule>();
+const isGroupedSecrets = typia.createIs<GroupedSecret[]>();
+const isSecretResolution = typia.createIs<SecretResolution>();
+
+const RESOLVER_PATH = fileURLToPath(new URL('../../managed/raw/tooling/direnv/secret-references.ts', import.meta.url));
+
+interface SecretReferences {
+  readSecretGroups: (root: string) => unknown;
+  resolveSecretEnvironment: (options: { root: string; group: string }) => unknown;
+}
+
+/**
+ * A loaded export, narrowed to the signature this file calls it with. typia
+ * validates data, not functions — it reports a module missing both of these
+ * as valid — so presence is checked here, and what each one RETURNS is
+ * validated below, where it is data again.
+ */
+function isSecretGroupsReader(value: unknown): value is SecretReferences['readSecretGroups'] {
+  return typeof value === 'function';
+}
+
+function isSecretGroupResolver(value: unknown): value is SecretReferences['resolveSecretEnvironment'] {
+  return typeof value === 'function';
+}
+
+let loaded: SecretReferences | undefined;
+
+async function secretReferences(): Promise<SecretReferences> {
+  if (loaded !== undefined) {
+    return loaded;
+  }
+  // Dynamic by necessity: the target is a managed raw script outside this
+  // package's compiled rootDir, so no static import can name it.
+  const imported: unknown = await import(pathToFileURL(RESOLVER_PATH).href);
+  if (!isSecretReferencesModule(imported)) {
+    throw new Error(`${RESOLVER_PATH} did not load as a module`);
+  }
+  const { readSecretGroups: read, resolveSecretEnvironment: resolve } = imported;
+  if (!isSecretGroupsReader(read) || !isSecretGroupResolver(resolve)) {
+    throw new Error(`${RESOLVER_PATH} does not expose the expected secret resolver API`);
+  }
+  loaded = { readSecretGroups: read, resolveSecretEnvironment: resolve };
+  return loaded;
+}
+
+/**
+ * Every `smoo.secrets` entry of the repository at `root`, each with the group
+ * that resolves it. Rejects with the offending declaration named — never a
+ * value — when the manifest or `.npmrc` cannot be read.
+ */
+export async function readSecretGroups(root: string): Promise<GroupedSecret[]> {
+  const references = await secretReferences();
+  const groups: unknown = references.readSecretGroups(root);
+  if (!isGroupedSecrets(groups)) {
+    throw new Error(`${RESOLVER_PATH} returned an unexpected group listing`);
+  }
+  return groups;
+}
+
+/**
+ * Resolve exactly one group's secrets for one child process. Everything
+ * outside the group comes back deferred rather than resolved, so a run for
+ * one group never triggers another group's provider command. Rejects with the
+ * resolver's aggregated refusal, which names variables and groups only.
+ */
+export async function resolveSecretGroup(root: string, group: string): Promise<SecretResolution> {
+  const references = await secretReferences();
+  const resolution: unknown = await references.resolveSecretEnvironment({ root, group });
+  if (!isSecretResolution(resolution)) {
+    throw new Error(`${RESOLVER_PATH} returned an unexpected resolution`);
+  }
+  return resolution;
+}