@smoothbricks/cli 0.11.11 → 0.11.13

package/src/monorepo/cargo-policy.ts

@@ -1,4 +1,5 @@
-import { type Dirent, existsSync, readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { type Dirent, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import typia from 'typia';
 import { parsePackageJsonText } from '../lib/json.js';
@@ -21,6 +22,11 @@ interface CargoManifest {
     workspace?: string | boolean;
   };
   profile?: Record<string, CargoProfile>;
+  // Only the KEYS matter here: a workspace-hack is wired in by name, and every
+  // dependency spelling — string, table, inherited — carries the same key.
+  dependencies?: Record<string, unknown>;
+  'dev-dependencies'?: Record<string, unknown>;
+  'build-dependencies'?: Record<string, unknown>;
 }
 
 interface CargoConfigTarget {
@@ -42,6 +48,22 @@ interface CargoConfig {
   };
   target?: Record<string, CargoConfigTarget>;
   env?: Record<string, string | CargoConfigEnvObject>;
+  resolver?: {
+    'feature-unification'?: string;
+  };
+  unstable?: {
+    'feature-unification'?: boolean;
+  };
+}
+
+interface RustToolchainFile {
+  toolchain?: {
+    channel?: string;
+  };
+}
+
+interface HakariConfig {
+  'hakari-package'?: string;
 }
 
 interface LoadedManifest {
@@ -62,6 +84,45 @@ interface EffectiveProfile {
 
 const validateCargoManifest = typia.createValidate<CargoManifest>();
 const validateCargoConfig = typia.createValidate<CargoConfig>();
+const validateRustToolchainFile = typia.createValidate<RustToolchainFile>();
+const validateHakariConfig = typia.createValidate<HakariConfig>();
+
+/**
+ * The one command this policy shells out to, behind a seam. `cargo hakari
+ * verify` is the only authority on whether a generated workspace-hack still
+ * unifies what the workspace resolves today; nothing in these files can answer
+ * that. Tests supply their own so the policy stays runnable without the binary.
+ */
+export interface CargoHakariShell {
+  run(directory: string, args: readonly string[]): { code: number; output: string; missing: boolean };
+}
+
+const defaultHakariShell: CargoHakariShell = {
+  run(directory, args) {
+    const result = spawnSync('cargo', ['hakari', ...args], { cwd: directory, encoding: 'utf8' });
+    const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim();
+    // cargo itself exists; a missing subcommand is cargo's own error, not ENOENT.
+    const missing =
+      (result.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT' || output.includes('no such command');
+    return { code: result.status ?? 1, output, missing };
+  },
+};
+
+/** Cargo's nightly-only workspace feature unification, and the config that turns it on. */
+const RESOLVER_UNIFICATION_BLOCK = [
+  '# One feature resolution for the whole workspace. Without it every per-crate',
+  '# cargo invocation resolves features for its own selection, so one shared',
+  '# dependency is compiled once per selection and no warm target directory is',
+  '# reused across crates. Requires the nightly channel the managed devenv',
+  '# module pins; on a stable toolchain a cargo-hakari workspace-hack does the',
+  '# same job. Both keys are needed: cargo ignores [resolver] without the',
+  '# [unstable] opt-in.',
+  '[unstable]',
+  'feature-unification = true',
+  '',
+  '[resolver]',
+  'feature-unification = "workspace"',
+].join('\n');
 
 const SKIPPED_DIRECTORY_NAMES = new Set([
   'node_modules',
@@ -256,6 +317,188 @@ function hasAncestorWorkspace(manifest: LoadedManifest, workspaceRoots: LoadedMa
   );
 }
 
+/**
+ * The channel that will actually compile this repository.
+ *
+ * The managed devenv module wins when it exists: devenv resolves the toolchain
+ * through rust-overlay and ignores `rust-toolchain.toml` unless
+ * `languages.rust.toolchainFile` names it, so a rust-toolchain file beside that
+ * module is decoration. Without the module, rustup's file is the answer. With
+ * neither, stable is the safe verdict: it is the channel on which the nightly
+ * resolver keys silently do nothing.
+ */
+function isNightlyToolchain(repositoryRoot: string, workspaceDirectory: string): boolean {
+  const devenvModule = join(repositoryRoot, 'tooling/direnv/devenv.smoo.nix');
+  if (existsSync(devenvModule)) {
+    const text = readFileSync(devenvModule, 'utf8');
+    const rustIndex = text.indexOf('languages.rust');
+    const channel = rustIndex === -1 ? null : /channel\s*=\s*"([^"]+)"/.exec(text.slice(rustIndex))?.[1];
+    return channel?.startsWith('nightly') === true;
+  }
+  for (const directory of [workspaceDirectory, repositoryRoot]) {
+    const path = join(directory, 'rust-toolchain.toml');
+    if (!existsSync(path)) {
+      continue;
+    }
+    try {
+      const validation = validateRustToolchainFile(Bun.TOML.parse(readFileSync(path, 'utf8')));
+      return validation.success && validation.data.toolchain?.channel?.startsWith('nightly') === true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/**
+ * Cargo merges `.cargo/config.toml` from the invocation directory upward, with
+ * the deepest file winning. Only the configs at or above the workspace root can
+ * govern a command run there, so the effective value is the deepest of those.
+ */
+function effectiveConfigValue<T>(
+  configs: LoadedConfig[],
+  workspaceDirectory: string,
+  read: (config: CargoConfig) => T | undefined,
+): T | undefined {
+  let deepest: { directory: string; value: T } | null = null;
+  for (const loaded of configs) {
+    const directory = dirname(dirname(loaded.path));
+    if (!pathWithin(directory, workspaceDirectory)) {
+      continue;
+    }
+    const value = read(loaded.config);
+    if (value === undefined) {
+      continue;
+    }
+    if (deepest === null || directory.length > deepest.directory.length) {
+      deepest = { directory, value };
+    }
+  }
+  return deepest?.value;
+}
+
+function workspaceCrates(root: LoadedManifest, manifests: LoadedManifest[]): LoadedManifest[] {
+  const members = manifests.filter((manifest) => workspaceContains(root, manifest));
+  return root.manifest.package === undefined ? members : [root, ...members];
+}
+
+const FEATURE_UNIFICATION_FIX = 'Run: smoo monorepo update';
+
+/**
+ * A workspace of two or more crates must resolve features ONCE for all of them.
+ *
+ * Without that, every per-crate cargo invocation resolves features for its own
+ * selection, and one shared dependency is compiled once per selection: the same
+ * `nx run cargo-test-<crate>` that should reuse a warm target directory rebuilds
+ * its half of the graph instead. Cargo's own mechanism is nightly-only, so a
+ * stable toolchain reaches the identical result through a cargo-hakari
+ * workspace-hack — a generated crate that depends on the union of features, which
+ * every member then depends on.
+ *
+ * One crate needs neither: there is only one selection to unify.
+ */
+function featureUnificationPolicy(
+  repositoryRoot: string,
+  workspaceRoots: LoadedManifest[],
+  manifests: LoadedManifest[],
+  configs: LoadedConfig[],
+  shell: CargoHakariShell,
+): number {
+  let failures = 0;
+  for (const root of workspaceRoots) {
+    const crates = workspaceCrates(root, manifests);
+    if (crates.length < 2) {
+      continue;
+    }
+    const nightly = isNightlyToolchain(repositoryRoot, root.directory);
+    const resolver = effectiveConfigValue(
+      configs,
+      root.directory,
+      (config) => config.resolver?.['feature-unification'],
+    );
+    const unstable = effectiveConfigValue(
+      configs,
+      root.directory,
+      (config) => config.unstable?.['feature-unification'],
+    );
+    if (nightly && resolver === 'workspace') {
+      if (unstable !== true) {
+        failures += report(
+          join(root.directory, '.cargo/config.toml'),
+          'sets [resolver] feature-unification = "workspace" without [unstable] feature-unification = true, ' +
+            `so cargo ignores it and every crate still resolves features on its own. ${FEATURE_UNIFICATION_FIX}`,
+        );
+      }
+      continue;
+    }
+    if (existsSync(join(root.directory, '.config/hakari.toml'))) {
+      failures += hakariWorkspaceHackPolicy(root, crates, shell);
+      continue;
+    }
+    failures += report(
+      root.path,
+      `workspace of ${crates.length} crates has no workspace-wide feature unification: ` +
+        (nightly
+          ? 'add [unstable] feature-unification = true and [resolver] feature-unification = "workspace" to .cargo/config.toml'
+          : 'the [resolver] feature-unification key needs the nightly channel, so this stable toolchain needs a ' +
+            'cargo-hakari workspace-hack (.config/hakari.toml)') +
+        `. Every per-crate cargo invocation otherwise recompiles the shared graph for its own feature selection. ${FEATURE_UNIFICATION_FIX}`,
+    );
+  }
+  return failures;
+}
+
+function hakariWorkspaceHackPolicy(root: LoadedManifest, crates: LoadedManifest[], shell: CargoHakariShell): number {
+  const configPath = join(root.directory, '.config/hakari.toml');
+  let hackName: string | undefined;
+  try {
+    const validation = validateHakariConfig(Bun.TOML.parse(readFileSync(configPath, 'utf8')));
+    hackName = validation.success ? validation.data['hakari-package'] : undefined;
+  } catch {
+    hackName = undefined;
+  }
+  if (hackName === undefined || hackName.length === 0) {
+    return report(configPath, `must declare hakari-package = "<crate>". ${FEATURE_UNIFICATION_FIX}`);
+  }
+  const hack = crates.find((crate) => crate.manifest.package?.name === hackName);
+  if (hack === undefined) {
+    return report(
+      configPath,
+      `names hakari-package "${hackName}", which is not a member of this workspace. ${FEATURE_UNIFICATION_FIX}`,
+    );
+  }
+  const unwired = crates
+    .filter((crate) => crate !== hack)
+    .filter(
+      (crate) =>
+        ![crate.manifest.dependencies, crate.manifest['dev-dependencies'], crate.manifest['build-dependencies']].some(
+          (table) => table !== undefined && hackName in table,
+        ),
+    )
+    .map((crate) => crate.manifest.package?.name ?? crate.path);
+  if (unwired.length > 0) {
+    return report(
+      root.path,
+      `these crates do not depend on "${hackName}", so cargo-hakari cannot unify their features: ` +
+        `${unwired.join(', ')}. ${FEATURE_UNIFICATION_FIX}`,
+    );
+  }
+  const verify = shell.run(root.directory, ['verify']);
+  if (verify.missing) {
+    return report(
+      configPath,
+      'needs cargo-hakari, which is not installed; the managed devenv module provides it — reload the shell (direnv reload).',
+    );
+  }
+  if (verify.code !== 0) {
+    return report(
+      root.path,
+      `cargo hakari verify rejected the workspace-hack: ${verify.output || 'no output'}. ${FEATURE_UNIFICATION_FIX}`,
+    );
+  }
+  return 0;
+}
+
 function isWorkspaceMember(manifest: LoadedManifest, workspaceRoots: LoadedManifest[]): boolean {
   if (manifest.manifest.package?.workspace !== undefined) {
     return true;
@@ -563,7 +806,12 @@ function reportManifestDirectoryAdvisories(repositoryRoot: string, ignoredDirect
   }
 }
 
-export function validateCargoCachePolicy(root: string): number {
+export interface CargoPolicyOptions {
+  /** Injected in tests; production shells out to the real `cargo hakari`. */
+  shell?: CargoHakariShell;
+}
+
+export function validateCargoCachePolicy(root: string, options: CargoPolicyOptions = {}): number {
   const repositoryRoot = resolve(root);
   const discoveredManifestPaths = discoverFiles(repositoryRoot, (name) => name === 'Cargo.toml');
   const ignoredDirectories = discoverIgnoredSubtrees(discoveredManifestPaths);
@@ -606,6 +854,13 @@ export function validateCargoCachePolicy(root: string): number {
 
   const workspaceRoots = manifests.filter((loaded) => loaded.manifest.workspace !== undefined);
   failures += reportManifestPolicy(manifests, workspaceRoots);
+  failures += featureUnificationPolicy(
+    repositoryRoot,
+    workspaceRoots,
+    manifests,
+    configs,
+    options.shell ?? defaultHakariShell,
+  );
   failures += cargoIncrementalPolicy(repositoryRoot, configs, packageJsonPaths, justfilePaths, ignoredDirectories);
   for (const config of configs) {
     failures += configPolicy(config, repositoryRoot);
@@ -613,3 +868,87 @@ export function validateCargoCachePolicy(root: string): number {
   reportManifestDirectoryAdvisories(repositoryRoot, ignoredDirectories);
   return failures;
 }
+
+/**
+ * The fix `smoo monorepo update` applies for the policy above: write the
+ * nightly resolver configuration, or generate and wire the workspace-hack a
+ * stable toolchain needs. Both are idempotent — the second run of either does
+ * nothing — because update runs on every repository, not only broken ones.
+ */
+export function applyCargoFeatureUnification(root: string, options: CargoPolicyOptions = {}): void {
+  const repositoryRoot = resolve(root);
+  const shell = options.shell ?? defaultHakariShell;
+  const discoveredManifestPaths = discoverFiles(repositoryRoot, (name) => name === 'Cargo.toml');
+  const manifestPaths = filterIgnoredPaths(discoveredManifestPaths, discoverIgnoredSubtrees(discoveredManifestPaths));
+  const manifests: LoadedManifest[] = [];
+  for (const path of manifestPaths) {
+    const manifest = loadManifest(path);
+    if (manifest !== null) {
+      manifests.push({ path, directory: dirname(path), manifest });
+    }
+  }
+  for (const root of manifests.filter((loaded) => loaded.manifest.workspace !== undefined)) {
+    if (workspaceCrates(root, manifests).length < 2) {
+      continue;
+    }
+    if (isNightlyToolchain(repositoryRoot, root.directory)) {
+      writeResolverUnification(root.directory);
+      continue;
+    }
+    const hakariConfig = join(root.directory, '.config/hakari.toml');
+    const relativeRoot = relative(repositoryRoot, root.directory) || '.';
+    if (!existsSync(hakariConfig)) {
+      console.log(`generating     cargo workspace-hack in ${relativeRoot} (cargo hakari init workspace-hack)`);
+      runHakari(shell, root.directory, ['init', 'workspace-hack']);
+    }
+    console.log(`unifying       cargo features in ${relativeRoot} (cargo hakari generate, manage-deps)`);
+    runHakari(shell, root.directory, ['generate']);
+    runHakari(shell, root.directory, ['manage-deps', '--yes']);
+  }
+}
+
+function runHakari(shell: CargoHakariShell, directory: string, args: readonly string[]): void {
+  const result = shell.run(directory, args);
+  if (result.missing) {
+    console.error(
+      `cargo hakari is not installed, so the workspace-hack in ${directory} was not updated; the managed devenv module provides it — reload the shell (direnv reload).`,
+    );
+    return;
+  }
+  if (result.code !== 0) {
+    console.error(`cargo hakari ${args.join(' ')} failed in ${directory}: ${result.output || 'no output'}`);
+  }
+}
+
+/**
+ * Append the two keys, never rewrite the file. A `.cargo/config.toml` carries
+ * linkers, env and target settings whose ORDER and comments are load-bearing;
+ * re-emitting parsed TOML would lose both. If either table already exists with
+ * some other content, appending a second one is invalid TOML — so that case is
+ * reported for a human instead of being guessed at.
+ */
+function writeResolverUnification(workspaceDirectory: string): void {
+  const path = join(workspaceDirectory, '.cargo/config.toml');
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  if (existing === null) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${RESOLVER_UNIFICATION_BLOCK}\n`);
+    console.log(`writing        ${path}`);
+    return;
+  }
+  const parsed = loadConfig(path);
+  if (parsed === null) {
+    return;
+  }
+  if (parsed.resolver?.['feature-unification'] === 'workspace' && parsed.unstable?.['feature-unification'] === true) {
+    return;
+  }
+  if (parsed.resolver !== undefined || parsed.unstable !== undefined) {
+    console.error(
+      `${path}: already declares [resolver] or [unstable]; add feature-unification to the existing tables by hand:\n${RESOLVER_UNIFICATION_BLOCK}`,
+    );
+    return;
+  }
+  writeFileSync(path, `${existing.replace(/\n*$/, '\n')}\n${RESOLVER_UNIFICATION_BLOCK}\n`);
+  console.log(`updating       ${path}`);
+}

package/src/monorepo/ci-workflow.ts

@@ -6,6 +6,7 @@ import type {
   PackageCargoCredentialsConfig,
   PackageCargoGitOrigin,
   PackagePrivateNpmConfig,
+  PackageRemoteCacheConfig,
   PackageSmooGithub,
   PackageSmooGithubEnvironments,
   PackageSourceCheckoutConfig,
@@ -79,6 +80,12 @@ export interface CiWorkflowDefinitionOptions extends DeployStepSecretConfig {
    * before SetupDevenv. Absent means no private Cargo fetch.
    */
   cargoCredentials?: PackageCargoCredentialsConfig;
+  /**
+   * Declared self-hosted Nx remote cache (package.json `smoo.remoteCache`).
+   * Every job that runs Nx carries the server and the access token, so one
+   * cache serves the whole fleet. Absent means each runner caches locally.
+   */
+  remoteCache?: PackageRemoteCacheConfig;
   /** GitHub Environments: staging for the validate/e2e jobs, production for the production-on-push job. */
   environments?: PackageSmooGithubEnvironments;
   /** Secrets for the e2e-deployment step, env var name → repository secret name. */
@@ -166,8 +173,9 @@ jobs:
 ${renderRunsOnLine(options.runsOn)}
     timeout-minutes: 45
 ${
-  options.privateNpm?.readTokenEnv || options.cargoCredentials !== undefined
-    ? `    # Fork PRs receive no secrets; private dependency installs cannot run there.
+  options.privateNpm?.readTokenEnv || options.cargoCredentials !== undefined || options.remoteCache !== undefined
+    ? `    # Fork PRs receive no secrets, so neither a private dependency install nor an
+    # authenticated remote cache read can run there.
     if: \${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
 `
     : ''
@@ -179,7 +187,7 @@ ${
     : ''
 }    env:
       GH_TOKEN: ${githubExpression('github.token')}
-${cargoCredentialJobEnvLines(options.cargoCredentials)}${privateNpmReadTokenJobEnv(options)}    steps:
+${remoteCacheJobEnvLines(options.remoteCache)}${cargoCredentialJobEnvLines(options.cargoCredentials)}${privateNpmReadTokenJobEnv(options)}    steps:
 `;
 }
 
@@ -459,6 +467,78 @@ export function normalizeSourceCheckout(config: PackageSourceCheckoutConfig): Pa
   return config;
 }
 
+/**
+ * Job env lines carrying the declared Nx remote cache. The pair rides the job
+ * env rather than a step because every Nx invocation in the job — build, lint,
+ * tests, deploy — reads it, and Nx enables the cache on a nonempty server
+ * alone: an empty or absent token would make it authenticate with nothing and
+ * fail every task on 401, which is why the job carries the same fork-PR gate
+ * as a private dependency install (see `renderCiWorkflowHeader`).
+ *
+ * A declared `internalServer` is the address managed runners use, exactly as a
+ * git origin's `internalMirror` is: both say this repository's runners sit
+ * inside that network, and shells outside it keep the public origin.
+ * Mechanism errors surface at managed-file render time, never inside CI.
+ */
+export function remoteCacheJobEnvLines(config: PackageRemoteCacheConfig | undefined): string {
+  if (config === undefined) {
+    return '';
+  }
+  const normalized = normalizeRemoteCache(config);
+  return [
+    `      NX_SELF_HOSTED_REMOTE_CACHE_SERVER: ${normalized.internalServer ?? normalized.server}\n`,
+    `      NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN: ${githubExpression(`secrets.${normalized.tokenSecret}`)}\n`,
+  ].join('');
+}
+
+/** Mechanism errors surface at managed-file render time, never inside CI. */
+export function normalizeRemoteCache(config: PackageRemoteCacheConfig): PackageRemoteCacheConfig {
+  assertCacheOrigin('server', config.server);
+  if (config.internalServer !== undefined) {
+    assertCacheOrigin('internalServer', config.internalServer);
+    if (config.internalServer === config.server) {
+      throw new Error(
+        `smoo.remoteCache internalServer repeats server ${config.server}; drop internalServer or point it at the address internal runners reach`,
+      );
+    }
+  }
+  if (!/^[A-Z_][A-Z0-9_]*$/.test(config.tokenSecret)) {
+    throw new Error(
+      `smoo.remoteCache needs an upper-case secret name for tokenSecret, got ${JSON.stringify(config.tokenSecret)}`,
+    );
+  }
+  return config;
+}
+
+/**
+ * A cache origin is exactly `scheme://host[:port]`. Nx appends
+ * `/v1/cache/<hash>` to it, so a trailing slash silently requests a doubled
+ * slash the server routes nowhere, and a path or credential would be dropped
+ * or leaked rather than honored.
+ */
+function assertCacheOrigin(field: 'server' | 'internalServer', value: string): void {
+  let url: URL | null = null;
+  try {
+    url = new URL(value);
+  } catch {
+    url = null;
+  }
+  if (
+    url === null ||
+    (url.protocol !== 'https:' && url.protocol !== 'http:') ||
+    url.pathname !== '/' ||
+    value.endsWith('/') ||
+    url.username !== '' ||
+    url.password !== '' ||
+    url.search !== '' ||
+    url.hash !== ''
+  ) {
+    throw new Error(
+      `smoo.remoteCache ${field} needs a credential-free http(s) origin with no path and no trailing slash, got ${JSON.stringify(value)}`,
+    );
+  }
+}
+
 /**
  * Job env lines carrying the declared Cargo credential secrets. Both registry
  * tokens and git-origin tokens ride the job env so the credential helper is
@@ -488,7 +568,10 @@ export function cargoCredentialJobEnvLines(config: PackageCargoCredentialsConfig
  * `internalMirror` are rewritten to the mirror with `url.<mirror>.insteadOf`
  * and the helper answers the same credential for the mirror's host, since git
  * passes helpers the rewritten URL. The helper reads the environment at call
- * time and answers only for declared origins.
+ * time and answers only for declared origins. Declared `sshOrigins` rewrite
+ * onto the same mirror and stay credential-free: the rewrite happens before
+ * transport, so git only ever asks for the mirror, and an SSH pin the runner
+ * has no key for fails loudly instead of collecting a token.
  * Mechanism errors surface at managed-file render time, never inside CI.
  */
 export function cargoCredentialStepLines(step: CiWorkflowStep, config: PackageCargoCredentialsConfig): string[] {
@@ -576,23 +659,52 @@ export function cargoCredentialStepLines(step: CiWorkflowStep, config: PackageCa
   lines.push('            fi');
   lines.push('            # Internal mirrors rewrite the declared origin prefix so runners');
   lines.push('            # that cannot reach the public URL fetch over guest networking.');
+  if (origins.some((origin) => origin.sshOrigins !== undefined)) {
+    lines.push('            # The same forge over SSH, as Cargo and uv pin it: git matches');
+    lines.push('            # insteadOf values as literal URL prefixes, so every declared');
+    lines.push('            # spelling rewrites onto the mirror on its own line.');
+  }
   for (const origin of origins) {
     if (origin.internalMirror === undefined) {
       continue;
     }
-    const originUrl = new URL(origin.origin);
     const mirrorUrl = new URL(origin.internalMirror);
-    const originBase = `${originUrl.protocol}//${originUrl.host}/`.replaceAll("'", "'\\''");
     const mirrorBase = `${mirrorUrl.protocol}//${mirrorUrl.host}/`.replaceAll("'", "'\\''");
-    lines.push('            echo "GIT_CONFIG_KEY_${idx}=url.' + mirrorBase + '.insteadOf"');
-    lines.push('            echo "GIT_CONFIG_VALUE_${idx}=' + originBase + '"');
-    lines.push('            idx=$((idx + 1))');
+    for (const prefix of mirrorRewritePrefixes(origin)) {
+      lines.push('            echo "GIT_CONFIG_KEY_${idx}=url.' + mirrorBase + '.insteadOf"');
+      lines.push('            echo "GIT_CONFIG_VALUE_${idx}=' + prefix.replaceAll("'", "'\\''") + '"');
+      lines.push('            idx=$((idx + 1))');
+    }
   }
   lines.push('            echo "GIT_CONFIG_COUNT=${idx}"');
   lines.push('          } >> "$GITHUB_ENV"');
   return lines;
 }
 
+/**
+ * Every URL prefix a mirrored origin rewrites from: the declared https origin
+ * first, then each declared SSH spelling of the same forge. One `insteadOf`
+ * value per prefix, because git matches them as literal prefixes and derives
+ * no spelling from another. Rendering runs after `normalizeCargoCredentials`,
+ * which parsed and refused every malformed entry.
+ */
+function mirrorRewritePrefixes(origin: PackageCargoGitOrigin): string[] {
+  const originUrl = new URL(origin.origin);
+  return [
+    `${originUrl.protocol}//${originUrl.host}/`,
+    ...(origin.sshOrigins ?? []).map((spelling) => sshRewritePrefix(new URL(spelling))),
+  ];
+}
+
+/**
+ * The SSH spelling as a rewritable prefix: userinfo is part of the spelling
+ * git matches, and the trailing slash keeps `ssh://host:2223` from also
+ * rewriting `ssh://host:22230/`.
+ */
+function sshRewritePrefix(spelling: URL): string {
+  return `ssh://${spelling.username === '' ? '' : `${spelling.username}@`}${spelling.host}/`;
+}
+
 function distinctCargoTokenEnvs(config: PackageCargoCredentialsConfig): string[] {
   const seen = new Set<string>();
   for (const env of config.registryTokenEnvs ?? []) {
@@ -614,12 +726,24 @@ export function normalizeCargoCredentials(config: PackageCargoCredentialsConfig)
     }
   }
   const hosts = new Set<string>();
+  const sshPrefixes = new Set<string>();
   for (const origin of config.gitOrigins ?? []) {
     const host = new URL(normalizeCargoGitOrigin(origin).origin).host;
     if (hosts.has(host)) {
       throw new Error(`smoo.github.cargoCredentials repeats git origin host ${host}; declare one token per origin`);
     }
     hosts.add(host);
+    for (const spelling of origin.sshOrigins ?? []) {
+      // One spelling, one rewrite, whole config: a repeat renders two
+      // identical insteadOf keys and git silently keeps the last one read.
+      const prefix = sshRewritePrefix(assertSshOrigin(spelling));
+      if (sshPrefixes.has(prefix)) {
+        throw new Error(
+          `smoo.github.cargoCredentials repeats the sshOrigins spelling ${prefix}; declare each spelling once, on the origin whose mirror rewrites it`,
+        );
+      }
+      sshPrefixes.add(prefix);
+    }
   }
   if ((config.registryTokenEnvs?.length ?? 0) === 0 && (config.gitOrigins?.length ?? 0) === 0) {
     throw new Error(
@@ -680,9 +804,54 @@ function normalizeCargoGitOrigin(origin: PackageCargoGitOrigin): PackageCargoGit
       );
     }
   }
+  if (origin.sshOrigins !== undefined) {
+    if (origin.internalMirror === undefined) {
+      throw new Error(
+        `smoo.github.cargoCredentials gitOrigins entry declares sshOrigins for ${origin.origin} without an internalMirror to rewrite them onto; an SSH spelling is a rewrite source and nothing else`,
+      );
+    }
+    if (origin.sshOrigins.length === 0) {
+      throw new Error(
+        `smoo.github.cargoCredentials gitOrigins entry for ${origin.origin} declares an empty sshOrigins list; name every SSH spelling a lockfile can carry, or omit the field`,
+      );
+    }
+    for (const spelling of origin.sshOrigins) {
+      assertSshOrigin(spelling);
+    }
+  }
   return origin;
 }
 
+/**
+ * One declared SSH spelling, parsed. Credential-free and path-free: a
+ * password here would be a secret committed in package.json, and a path
+ * would rewrite a single repository instead of the forge. scp syntax
+ * (`git@host:org/repo.git`) is no URL, so git cannot rewrite it from a Cargo
+ * or uv pin at all; the `ssh://` spelling is the one to declare.
+ */
+function assertSshOrigin(spelling: string): URL {
+  let ssh: URL | null = null;
+  try {
+    ssh = new URL(spelling);
+  } catch {
+    ssh = null;
+  }
+  if (
+    ssh === null ||
+    ssh.protocol !== 'ssh:' ||
+    ssh.host === '' ||
+    (ssh.pathname !== '' && ssh.pathname !== '/') ||
+    ssh.password !== '' ||
+    ssh.search !== '' ||
+    ssh.hash !== ''
+  ) {
+    throw new Error(
+      `smoo.github.cargoCredentials gitOrigins entry needs credential-free ssh:// sshOrigins without a path, got ${JSON.stringify(spelling)}`,
+    );
+  }
+  return ssh;
+}
+
 /**
  * The same-repo gate as prettier folds it: the raw single line exceeds the
  * print width, so the generator emits the folded form itself to keep the
@@ -828,7 +997,7 @@ ${renderRunsOnLine(options.runsOn)}
 ${environmentLine(options.environments?.staging)}    if: \${{ needs.main.result == 'success' && needs.main.outputs.deployment-stage != '' }}
     env:
       GH_TOKEN: \${{ github.token }}
-${cargoCredentialJobEnvLines(options.cargoCredentials)}${privateNpmReadTokenJobEnv(options)}    steps:
+${remoteCacheJobEnvLines(options.remoteCache)}${cargoCredentialJobEnvLines(options.cargoCredentials)}${privateNpmReadTokenJobEnv(options)}    steps:
 ${renderCiWorkflowSteps(followUpSetupSteps(options, numbers), options)}
       # Step ${numbers.middle}
       - name: E2E Tests (Deployed Stage)
@@ -859,7 +1028,7 @@ ${renderRunsOnLine(options.runsOn)}
     if: \${{ !cancelled() && github.event_name == 'push' && github.ref == ${stagingRefLiteral(options)} && needs.main.result == 'success'${e2eGate} }}
 ${environmentLine(options.environments?.production)}    env:
       GH_TOKEN: \${{ github.token }}
-${cargoCredentialJobEnvLines(options.cargoCredentials)}${privateNpmReadTokenJobEnv(options)}    steps:
+${remoteCacheJobEnvLines(options.remoteCache)}${cargoCredentialJobEnvLines(options.cargoCredentials)}${privateNpmReadTokenJobEnv(options)}    steps:
 ${renderCiWorkflowSteps(followUpSetupSteps(options, numbers), options)}
       # Step ${numbers.middle}
       - name: 🚀 Deploy Production