@smoothbricks/cli 0.11.12 → 0.11.13

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

@@ -1,12 +1,14 @@
 /**
- * Provider-neutral local secret resolution for smoo-managed repositories.
+ * Provider-neutral local secret resolution for smoo-managed repositories, and
+ * the developer-shell half of the declared Nx remote cache.
  *
- * Reads the root package.json `smoo.secrets` map — the bootstrap twin of
- * `PackageSecretCommand` and `PackageSmooConfig.secrets` in
- * packages/cli/src/lib/json.ts. This file is a managed raw script: it runs
- * from `tooling/direnv/setup-environment.ts` BEFORE `bun install`, when no
- * workspace package and no Typia transform exist yet, so the map is
- * hand-validated here against the exact shape json.ts declares. Keep the two
+ * Reads the root package.json `smoo.secrets` map and `smoo.remoteCache` block
+ * — the bootstrap twins of `PackageSecretCommand`, `PackageSmooConfig.secrets`
+ * and `PackageRemoteCacheConfig` in packages/cli/src/lib/json.ts. This file is
+ * a managed raw script: it runs from `tooling/direnv/setup-environment.ts`
+ * BEFORE `bun install`, and from the managed devenv `enterShell` before that,
+ * when no workspace package and no Typia transform exist yet, so both shapes
+ * are hand-validated here against exactly what json.ts declares. Keep them
  * aligned; smoo's Typia validation fails the manifest at generation time for
  * anything this file would reject at runtime.
  *
@@ -26,6 +28,23 @@
  * 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.
+ *
+ * One declared variable is exempt from blocking an install: the one
+ * `smoo.remoteCache.tokenSecret` names. A remote cache is an optimization, so
+ * an unreachable secret provider must not keep dependencies from installing or
+ * a shell from opening; that variable is resolved by the cache export below,
+ * where failure costs a stderr line.
+ *
+ * Run as a program (`bun secret-references.ts [root]`), the script prints the
+ * remote cache's `export` lines for the shell to `eval` and nothing else: Nx
+ * runs in the developer's shell, not in the setup child, and the export is
+ * limited to those two variables so `smoo.secrets` stays process-local. It
+ * prints nothing when the repository declares no cache, when the shell already
+ * carries a server (a CI job env is never overwritten), or when the declared
+ * token has no value — Nx accepts only 200 or 404 from a cache server, so a
+ * server it cannot authenticate to fails every task instead of missing. Why
+ * the cache is off is said on stderr; the exit status stays 0, because a
+ * missing cache credential must never keep a shell from opening.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -69,7 +88,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-function isNonemptyEnvValue(value: string | undefined): boolean {
+function isNonemptyEnvValue(value: string | undefined): value is string {
   return value !== undefined && value.length > 0;
 }
 
@@ -80,9 +99,9 @@ function isNonemptyEnvValue(value: string | undefined): boolean {
  */
 export function parseSmooSecrets(packageJson: unknown): Readonly<Record<string, SecretSpec>> {
   if (!isRecord(packageJson)) return {};
-  const smoo = packageJson['smoo'];
+  const smoo = packageJson.smoo;
   if (!isRecord(smoo)) return {};
-  const secrets = smoo['secrets'];
+  const secrets = smoo.secrets;
   if (secrets === undefined) return {};
   if (!isRecord(secrets)) {
     throw new Error('smoo.secrets must map environment variable names to { command: [string, ...] }');
@@ -103,7 +122,7 @@ function parseSecretSpec(name: string, spec: unknown): SecretSpec {
   if (!isRecord(spec)) {
     throw new Error(`smoo.secrets.${name}: each entry must be an object with a command array`);
   }
-  const raw = spec['command'];
+  const raw = spec.command;
   if (!Array.isArray(raw) || raw.length === 0) {
     throw new Error(`smoo.secrets.${name}.command: must be an array of at least one string`);
   }
@@ -116,6 +135,53 @@ function parseSecretSpec(name: string, spec: unknown): SecretSpec {
   return { command: [first, ...rest] };
 }
 
+/** The two variables Nx reads for its self-hosted HTTP cache. */
+const REMOTE_CACHE_SERVER = 'NX_SELF_HOSTED_REMOTE_CACHE_SERVER';
+const REMOTE_CACHE_ACCESS_TOKEN = 'NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN';
+
+/**
+ * The declared remote cache as a local shell needs it. `internalServer` is
+ * deliberately absent: it is the address a managed runner reaches inside its
+ * own network, and a shell that loads this file is by definition outside it,
+ * so a developer machine always takes the public `server`.
+ */
+export interface RemoteCacheSpec {
+  readonly server: string;
+  /** Variable holding the cache token: an ambient value, or a `smoo.secrets` entry resolved here. */
+  readonly tokenSecret: string;
+}
+
+/**
+ * Validates the `smoo.remoteCache` block out of an already-parsed
+ * package.json. Absent `smoo` or `smoo.remoteCache` is no cache; a malformed
+ * declaration throws naming the field.
+ */
+export function parseSmooRemoteCache(packageJson: unknown): RemoteCacheSpec | null {
+  if (!isRecord(packageJson)) return null;
+  const smoo = packageJson.smoo;
+  if (!isRecord(smoo)) return null;
+  const remoteCache = smoo.remoteCache;
+  if (remoteCache === undefined) return null;
+  if (!isRecord(remoteCache)) {
+    throw new Error('smoo.remoteCache must be an object with { server, tokenSecret }');
+  }
+  const server = remoteCache.server;
+  const tokenSecret = remoteCache.tokenSecret;
+  // A trailing slash is refused rather than trimmed: Nx appends
+  // `/v1/cache/<hash>`, so the doubled slash is a route that answers 404
+  // forever, and silently repairing the manifest here would leave managed CI
+  // — which reads the same field — disagreeing with this shell.
+  if (typeof server !== 'string' || server.length === 0 || server.endsWith('/')) {
+    throw new Error(
+      'smoo.remoteCache.server must be an origin with no trailing slash, e.g. https://nx-cache.example.net',
+    );
+  }
+  if (typeof tokenSecret !== 'string' || !ENV_NAME.test(tokenSecret)) {
+    throw new Error('smoo.remoteCache.tokenSecret must name the environment variable holding the cache token');
+  }
+  return { server, tokenSecret };
+}
+
 /** Every `${VAR}` referenced from `.npmrc` text; an absent file contributes nothing. */
 export function registryAuthEnvNames(npmrcText: string | null): ReadonlySet<string> {
   const names = new Set<string>();
@@ -131,47 +197,64 @@ type SecretOutcome =
   | { readonly name: string; readonly kind: 'resolved'; readonly value: string }
   | { readonly name: string; 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.
+ */
+async function routeSecret(
+  name: string,
+  spec: SecretSpec,
+  context: {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly registryIntentEnvs: ReadonlySet<string>;
+    readonly run: SecretCommandRunner;
+  },
+): Promise<SecretOutcome> {
+  const { env } = context;
+  if (isNonemptyEnvValue(env[name])) {
+    return { name, 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',
+    };
+  }
+  if (isNonemptyEnvValue(env.COWSHED_WORKSPACE_TOKEN) && context.registryIntentEnvs.has(name)) {
+    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',
+    };
+  }
+  try {
+    const value = (await context.run(spec.command)).replace(/\r?\n$/, '');
+    if (value.length === 0) {
+      return {
+        name,
+        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 };
+  } catch (error) {
+    return { name, kind: 'failed', guidance: describeCommandFailure(error) };
+  }
+}
+
 export async function resolveSecrets(request: SecretResolutionRequest): Promise<Readonly<Record<string, string>>> {
-  const run = request.runCommand ?? runSecretCommand;
-  const env = request.env;
-  const ci = isNonemptyEnvValue(env['CI']);
-  const cowshed = isNonemptyEnvValue(env['COWSHED_WORKSPACE_TOKEN']);
+  const context = {
+    env: request.env,
+    registryIntentEnvs: request.registryIntentEnvs,
+    run: request.runCommand ?? runSecretCommand,
+  };
   const outcomes = await Promise.all(
-    Object.entries(request.secrets).map(async ([name, spec]): Promise<SecretOutcome> => {
-      if (isNonemptyEnvValue(env[name])) {
-        return { name, kind: 'env-wins' };
-      }
-      if (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',
-        };
-      }
-      if (cowshed && request.registryIntentEnvs.has(name)) {
-        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',
-        };
-      }
-      try {
-        const value = (await run(spec.command)).replace(/\r?\n$/, '');
-        if (value.length === 0) {
-          return {
-            name,
-            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 };
-      } catch (error) {
-        return { name, kind: 'failed', guidance: describeCommandFailure(error) };
-      }
-    }),
+    Object.entries(request.secrets).map(async ([name, spec]) => routeSecret(name, spec, context)),
   );
   const failures = outcomes.filter(
     (outcome): outcome is Extract<SecretOutcome, { kind: 'failed' }> => outcome.kind === 'failed',
@@ -242,17 +325,113 @@ const runSecretCommand: SecretCommandRunner = async (argv) => {
   return stdout;
 };
 
+/**
+ * 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.
+ */
 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;
+    }
+  }
   return resolveSecrets({
-    secrets: parseSmooSecrets(readPackageJson(options.root)),
+    secrets: required,
     registryIntentEnvs: registryAuthEnvNames(readNpmrcText(options.root)),
     env: options.env ?? process.env,
     runCommand: options.runCommand,
   });
 }
 
+/**
+ * What the shell should do about the declared remote cache. Each case is a
+ * value, not an exception: three of the four are ordinary, and only one is
+ * worth saying out loud.
+ */
+export type RemoteCacheOutcome =
+  | { readonly kind: 'undeclared' }
+  | { readonly kind: 'inherited' }
+  | { readonly kind: 'unavailable'; readonly reason: string }
+  | { readonly kind: 'exported'; readonly env: Readonly<Record<string, string>> };
+
+/**
+ * The remote cache variables this shell should export, or why it exports none.
+ * An inherited server always wins, so a CI job env — which carries the address
+ * its own runners reach — is never overwritten by the public one. The token is
+ * taken from the environment when it is there, and otherwise from the one
+ * `smoo.secrets` entry that declares it — resolving that single variable, so
+ * no other declared secret ever reaches the shell. A repository that declares
+ * the cache token as a provider secret therefore pays that one command twice
+ * per shell entry, once here and once in the setup child's own aggregate
+ * resolution; an ambient token pays nothing.
+ */
+export async function resolveRemoteCacheOutcome(options: SecretResolutionOptions): Promise<RemoteCacheOutcome> {
+  const env = options.env ?? process.env;
+  const packageJson = readPackageJson(options.root);
+  const spec = parseSmooRemoteCache(packageJson);
+  if (spec === null) {
+    return { kind: 'undeclared' };
+  }
+  if (isNonemptyEnvValue(env[REMOTE_CACHE_SERVER])) {
+    return { kind: 'inherited' };
+  }
+  const ambient = env[spec.tokenSecret];
+  if (isNonemptyEnvValue(ambient)) {
+    return {
+      kind: 'exported',
+      env: { [REMOTE_CACHE_SERVER]: spec.server, [REMOTE_CACHE_ACCESS_TOKEN]: ambient },
+    };
+  }
+  const declared = parseSmooSecrets(packageJson)[spec.tokenSecret];
+  if (declared === undefined) {
+    return {
+      kind: 'unavailable',
+      reason: `${spec.tokenSecret} is unset and no smoo.secrets entry declares it, so ${spec.server} would be asked for cache entries with no credential`,
+    };
+  }
+  // A cache token is not registry routing, so the cowshed `.npmrc` exclusion
+  // cannot apply to it; every other rule in the header does.
+  const outcome = await routeSecret(spec.tokenSecret, declared, {
+    env,
+    registryIntentEnvs: new Set(),
+    run: options.runCommand ?? runSecretCommand,
+  });
+  switch (outcome.kind) {
+    case 'resolved':
+      return {
+        kind: 'exported',
+        env: { [REMOTE_CACHE_SERVER]: spec.server, [REMOTE_CACHE_ACCESS_TOKEN]: outcome.value },
+      };
+    case 'failed':
+      return { kind: 'unavailable', reason: `${spec.tokenSecret}: ${outcome.guidance}` };
+    case 'env-wins':
+      // Only reachable if an ambient value appeared between the check above
+      // and this call; the export happens on the next shell entry.
+      return { kind: 'unavailable', reason: `${spec.tokenSecret} was set after it was read` };
+  }
+}
+
+/**
+ * POSIX `export` lines for a shell to `eval`. Single quotes are the only
+ * quoting a value cannot escape from, so each value is single-quoted with its
+ * own quotes spliced out — a token is opaque bytes, never assumed shell-safe.
+ */
+export function shellExportLines(env: Readonly<Record<string, string>>): string {
+  return Object.entries(env)
+    .map(([name, value]) => `export ${name}='${value.replaceAll("'", "'\\''")}'\n`)
+    .join('');
+}
+
 function readPackageJson(root: string): unknown {
   const packageJsonPath = join(root, 'package.json');
   let text: string;
@@ -279,3 +458,21 @@ function readNpmrcText(root: string): string | null {
   if (!existsSync(npmrcPath)) return null;
   return readFileSync(npmrcPath, 'utf8');
 }
+
+// Program mode, run by the managed devenv shell as
+// `eval "$(bun "$DEVENV_ROOT/secret-references.ts" "$PWD")"`. stdout is
+// therefore shell text and carries nothing else; everything a human should
+// read goes to stderr, and the status stays 0 so a shell always opens.
+if (import.meta.main) {
+  const root = Bun.argv[2] ?? process.cwd();
+  try {
+    const outcome = await resolveRemoteCacheOutcome({ root });
+    if (outcome.kind === 'exported') {
+      process.stdout.write(shellExportLines(outcome.env));
+    } else if (outcome.kind === 'unavailable') {
+      console.error(`smoo: Nx remote cache off — ${outcome.reason}`);
+    }
+  } catch (error) {
+    console.error(`smoo: Nx remote cache off — ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/managed/templates/github/actions/save-nix-devenv/action.yml

@@ -1,7 +1,7 @@
 name: Save Nix/devenv caches
 description: >
-  Save the devenv/direnv eval-cache segment after the job, on every runner where setup missed and build-shell produced
-  nix-eval-cache.db. The Nix store cache saves itself in setup-devenv's post phase (ephemeral runners only).
+  Save the devenv/direnv eval-cache segment after the job, on every ephemeral runner where setup missed and build-shell
+  produced nix-eval-cache.db. The Nix store cache saves itself in setup-devenv's post phase (ephemeral runners only).
 
 inputs:
   devenv-cache-hit:

package/managed/templates/github/actions/setup-devenv/action.yml

@@ -8,7 +8,7 @@ description: >
 outputs:
   devenv-cache-hit:
     description: Whether the devenv/direnv cache restored from the exact primary key.
-    value: ${{ steps.devenv-cache.outputs.cache-hit || 'false' }}
+    value: ${{ steps.runner-kind.outputs.host == 'true' || steps.devenv-cache.outputs.cache-hit || 'false' }}
   host-runner:
     description: Whether this job is on a host-nix runner with shared store/caches.
     value: ${{ steps.runner-kind.outputs.host }}
@@ -95,14 +95,52 @@ runs:
         } >> "$GITHUB_ENV"
         echo "nx cache   : $NX_CACHE_ROOT"
 
+    # Host runners keep devenv's state on the shared bind, next to the Nx cache:
+    # .devenv (eval SQLite, gc roots, profile) and .direnv survive the job, so
+    # the next job on this host evaluates nothing and downloads nothing. The
+    # Actions cache segment below is the ephemeral runners' substitute for this.
+    # Scoped per job as well as lane: two jobs of one run are parallel, and one
+    # eval-cache.db has one writer.
+    #
+    # The eval cache keys on canonical absolute paths, and act's host executor
+    # checks out under <cache>/<random 8 chars>/hostexecutor - a new path every
+    # job by design (act/runner/run_context.go: MustRandName), so a restored
+    # cache could never match. The workspace is therefore bind-mounted at a
+    # stable path (a symlink would not do: Nix canonicalises) and devenv is
+    # evaluated from there; every later step still runs in the checkout, which
+    # is the same tree. DEVENV_WORKDIR names the path the devenv steps use.
+    - name: 📂 Locate devenv state on the shared bind
+      if: steps.runner-kind.outputs.host == 'true'
+      shell: bash
+      env:
+        DEVENV_STATE_REPO: ${{ github.repository }}
+        DEVENV_STATE_LANE: ${{ github.workflow }}
+        DEVENV_STATE_JOB: ${{ github.job }}
+      run: |
+        lane=$(printf '%s' "$DEVENV_STATE_LANE" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9._-' '-')
+        root="/var/cache/ci/devenv/$DEVENV_STATE_REPO/${lane:-default}/$DEVENV_STATE_JOB"
+        mkdir -p "$root/.devenv" "$root/.direnv" "$root/workspace"
+        sudo mount --bind "$GITHUB_WORKSPACE" "$root/workspace"
+        rm -rf tooling/direnv/.devenv tooling/direnv/.direnv
+        ln -s "$root/.devenv" tooling/direnv/.devenv
+        ln -s "$root/.direnv" tooling/direnv/.direnv
+        echo "DEVENV_WORKDIR=$root/workspace" >> "$GITHUB_ENV"
+        echo "devenv state: $root (workspace bind-mounted at $root/workspace)"
+
+    - name: 📂 Devenv runs in the checkout
+      if: steps.runner-kind.outputs.host != 'true'
+      shell: bash
+      run: echo "DEVENV_WORKDIR=$GITHUB_WORKSPACE" >> "$GITHUB_ENV"
+
     # Devenv segment (own key): tooling/direnv/.devenv + .direnv — includes
-    # nix-eval-cache.db. Independent of the store cache; restore on host and
-    # ephemeral whether or not the store cache hit. Missing store paths are fine:
+    # nix-eval-cache.db. Independent of the store cache; restored on ephemeral
+    # runners whether or not the store cache hit. Missing store paths are fine:
     # devenv verifies shell drv/out exist on eval-cache hit and invalidates +
     # re-evals / realizes when GC removed them. Packages still come from host
     # store, the store cache, or Cachix — this blob only skips evaluation.
     - name: 🧊 Cache devenv and direnv
       id: devenv-cache
+      if: steps.runner-kind.outputs.host != 'true'
       uses: ./.github/actions/cache-nix-devenv
 
     # Single-user Nix unpacked into /nix in seconds: no installer volume, no
@@ -169,7 +207,7 @@ runs:
     # until the check existed.
     - name: 🧰 Install devenv
       shell: bash
-      working-directory: tooling/direnv
+      working-directory: ${{ env.DEVENV_WORKDIR }}/tooling/direnv
       env:
         SMOO_HOST_RUNNER: ${{ steps.runner-kind.outputs.host }}
       run: ./github-actions-bootstrap.sh install-devenv
@@ -186,5 +224,5 @@ runs:
 
     - name: 🐚 Build devenv shell
       shell: bash
-      working-directory: tooling/direnv
+      working-directory: ${{ env.DEVENV_WORKDIR }}/tooling/direnv
       run: ./github-actions-bootstrap.sh build-shell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smoothbricks/cli",
-  "version": "0.11.12",
+  "version": "0.11.13",
   "type": "module",
   "description": "SmoothBricks monorepo automation CLI",
   "bin": {
@@ -64,7 +64,7 @@
   ],
   "dependencies": {
     "@arethetypeswrong/core": "^0.18.2",
-    "@smoothbricks/nx-plugin": "0.4.6",
+    "@smoothbricks/nx-plugin": "0.4.7",
     "@smoothbricks/validation": "0.1.8",
     "commander": "^14.0.3",
     "make-synchronized": "^0.8.0",

package/src/lib/json.ts

@@ -134,6 +134,19 @@ export interface PackageCargoGitOrigin {
    * origin is fetched as declared.
    */
   internalMirror?: string;
+  /**
+   * SSH spellings of the same forge that managed CI rewrites onto
+   * `internalMirror` as well, e.g. `ssh://forgejo@forge.example.net:2223/`
+   * as Cargo and uv pin a git dependency. A runner holds the read token the
+   * mirror accepts and no SSH key at all, so every spelling a lockfile can
+   * carry needs its own rewrite: git matches `insteadOf` values as literal
+   * URL prefixes and infers no spelling from another — not the SSH host from
+   * the HTTPS one, and not the userless form from the one carrying a user.
+   * Each entry is a credential-free `ssh://` origin without a path; the SSH
+   * user is part of the spelling and stays in it. Requires
+   * `internalMirror`, since the entry is a rewrite source and nothing else.
+   */
+  sshOrigins?: string[];
 }
 
 /**
@@ -153,6 +166,43 @@ export interface PackagePrivateNpmConfig {
   publishTokenEnv?: string;
 }
 
+/**
+ * Declared self-hosted Nx remote cache (`smoo.remoteCache`). Nx enables its
+ * HTTP cache on a nonempty NX_SELF_HOSTED_REMOTE_CACHE_SERVER and reads the
+ * credential from NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN; this declaration
+ * is what puts that pair in a managed CI job's environment and in a developer
+ * shell (tooling/direnv/secret-references.ts). Absent means every workspace
+ * keeps its own local cache and nothing is shared.
+ *
+ * The pair is emitted whole or not at all, because Nx accepts only 200 or 404
+ * from a cache server: a server without a working credential fails every task
+ * with 401 rather than missing quietly.
+ */
+export interface PackageRemoteCacheConfig {
+  /**
+   * Origin every runner and developer machine can reach, e.g.
+   * `https://nx-cache.example.net`. Credential-free, no path, and no trailing
+   * slash — Nx appends `/v1/cache/<hash>`, so a trailing slash requests
+   * `//v1/cache/<hash>`, which is a different route and answers 404 forever.
+   */
+  server: string;
+  /**
+   * Origin an internal runner reaches instead of `server`, e.g.
+   * `http://10.89.0.1:8765` across a container bridge. Same declaration as a
+   * git origin's `internalMirror`: declaring it says this repository's managed
+   * runners are inside that network, so managed CI uses it and shells outside
+   * keep `server`. Omitted means CI uses `server` too.
+   */
+  internalServer?: string;
+  /**
+   * Repository secret holding the cache token, and the same variable name a
+   * developer shell resolves locally (an ambient value or a `smoo.secrets`
+   * entry). A read-only token here keeps an untrusted context reading the
+   * cache without being able to publish into it.
+   */
+  tokenSecret: RepositorySecretName;
+}
+
 /** Local bootstrap fallback; existing environment values always take precedence. */
 export interface PackageSecretCommand {
   /** Executed directly, without a shell; stdout supplies the secret value. */
@@ -162,6 +212,8 @@ export interface PackageSecretCommand {
 export interface PackageSmooConfig {
   github?: PackageSmooGithub;
   privateNpm?: PackagePrivateNpmConfig;
+  /** Declared self-hosted Nx remote cache; absent means local caching only. */
+  remoteCache?: PackageRemoteCacheConfig;
   /** Provider-neutral local secret commands. CI supplies these variables externally. */
   secrets?: Record<string, PackageSecretCommand>;
 }