@monster-orange/den 0.2.1 → 0.2.3

package/src/shared/environment-manager/service-runner.ts

@@ -8,6 +8,7 @@
 
 import { hasRuntime, repoKind } from "../repo-kind.js";
 import { effectiveLocalCommands } from "../stacks/manifest-commands.js";
+import { manifestStackName } from "../stacks/config.js";
 import fs from "fs";
 import path from "path";
 import { readManifest } from "../manifest/read-manifest.js";
@@ -26,6 +27,15 @@ import {
   shellQuote,
 } from "../terminal/tabs.js";
 import { readCatalog } from "./catalog.js";
+import { getSecretsProvider } from "../secrets/index.js";
+import {
+  assertSecretEnvSpec,
+  resolveSecretEnv,
+  secretEnvKeys,
+  type SecretEnvSpec,
+} from "../secrets/secret-env.js";
+import type { SecretsProvider } from "../secrets/types.js";
+import { composeCommands } from "../stacks/manifest-commands.js";
 import { buildServiceEnv } from "./service-env.js";
 import {
   devOpContainerNames,
@@ -40,6 +50,7 @@ import {
   getActiveWorkspaces,
   getFocusedWorkspaceName,
   getWorkspaceByName,
+  parseAddress,
   resolveServiceSource,
   listWorkspaceServices,
 } from "./workspaces.js";
@@ -49,7 +60,12 @@ import {
   type ServiceHealthResult,
 } from "./health.js";
 import { EventEmitter } from "events";
-import type { CommandDef, ResolvedService } from "../types/index.js";
+import type {
+  CommandDef,
+  ResolvedService,
+  ServiceCatalog,
+  WorkspaceConfig,
+} from "../types/index.js";
 import type { ChildProcess } from "child_process";
 import { getStateDir } from "../paths.js";
 
@@ -658,7 +674,95 @@ export function resolveService(
     : getActiveWorkspace();
   if (!ws) return null;
   const catalog = readCatalog();
+  const listed = resolveListedService(address, ws, catalog);
+  if (listed || address.includes("/")) return listed;
+  // Not a repo or a listed address: a service key or a stack name, when it
+  // names exactly one service in the workspace.
+  const candidates = aliasCandidates(address, ws, catalog);
+  return candidates.length === 1
+    ? resolveListedService(candidates[0], ws, catalog)
+    : null;
+}
+
+type NamedWorkspace = { name: string; config: WorkspaceConfig };
+
+/**
+ * The addresses `alias` could mean in `ws`: every service whose manifest key
+ * is `alias`, and the repo of every compose stack named `alias` (a stack
+ * stands for its repo; when that repo also has a service named `alias`, the
+ * service is the one match). Sorted; empty for a `repo/service` address and
+ * for a catalog repo's name.
+ */
+function aliasCandidates(
+  alias: string,
+  ws: NamedWorkspace,
+  catalog: ServiceCatalog,
+): string[] {
+  // A repo name is never an alias, in the workspace or not.
+  if (alias.includes("/") || catalog[alias]) return [];
+  const services = new Set<string>();
+  const stackRepos = new Set<string>();
+  for (const s of listWorkspaceServices(ws.config, catalog, ws.name)) {
+    if (s.subsystem === alias) services.add(s.address);
+    const manifest = readManifest(s.repoPath);
+    if (manifest?.compose && manifestStackName(manifest, s.repoName) === alias)
+      stackRepos.add(s.repoName);
+  }
+  const withService = new Set(
+    [...services].map((a) => parseAddress(a, catalog).repoName),
+  );
+  return [
+    ...services,
+    ...[...stackRepos].filter((r) => !withService.has(r)),
+  ].sort();
+}
+
+function namedWorkspace(workspaceName?: string): NamedWorkspace | null {
+  return workspaceName
+    ? getWorkspaceByName(workspaceName)
+    : getActiveWorkspace();
+}
+
+/**
+ * What `alias` could address in the workspace (the focused one by default)
+ * when it is not a repo or a listed address: see resolveService.
+ */
+export function serviceAliasCandidates(
+  alias: string,
+  workspaceName?: string,
+): string[] {
+  const ws = namedWorkspace(workspaceName);
+  if (!ws) return [];
+  const catalog = readCatalog();
+  if (resolveListedService(alias, ws, catalog)) return [];
+  return aliasCandidates(alias, ws, catalog);
+}
 
+/**
+ * The address to use for what someone typed: an unambiguous alias becomes
+ * the service's own address; anything else is returned as is. An ambiguous
+ * alias throws, naming the candidates.
+ */
+export function canonicalServiceAddress(
+  address: string,
+  workspaceName?: string,
+): string {
+  const candidates = serviceAliasCandidates(address, workspaceName);
+  if (candidates.length > 1) {
+    const ws = namedWorkspace(workspaceName)?.name ?? "default";
+    throw new Error(
+      `"${address}" is ambiguous in workspace "${ws}": ${candidates.join(", ")}; name one of them`,
+    );
+  }
+  return candidates[0] ?? address;
+}
+
+/** resolveService for a repo name or a listed address (no aliases). */
+function resolveListedService(
+  address: string,
+  ws: NamedWorkspace,
+  catalog: ServiceCatalog,
+): ResolvedService | null {
   let resolved = resolveServiceSource(address, ws.name, ws.config, catalog);
 
   // Bare multi-service repo registered ONLY by subsystem (e.g. "shop/db" +
@@ -974,6 +1078,12 @@ export interface RunCommandOptions {
    * the detach window is invisible to fail-fast callers.
    */
   onServiceExit?: (exitCode: number) => void;
+  /**
+   * R16: the service's resolved `secret_env` (see prepareServiceSecretEnv),
+   * set only in the spawned process's env. An up/restart of a service that
+   * declares secret_env is refused unless every key is here.
+   */
+  secretEnv?: Record<string, string>;
 }
 
 export interface RunCommandResult {
@@ -998,6 +1108,211 @@ export interface RunCommandResult {
   };
 }
 
+/**
+ * A service with no commands of its own is started by its repo's up
+ * (placement's repo-level rule). For `up` that is the repo's up (`address`
+ * set); any other command would reach the repo's other services too, so it
+ * points at the repo instead: a refusal, except that down succeeds (nothing
+ * of the service's own runs, and a workspace Down sends every service).
+ * Null when the rule does not apply.
+ */
+function repoStartedFallback(
+  resolved: ResolvedService,
+  command: string,
+  workspace: string | undefined,
+): { address?: string; note: string } | null {
+  const repoEntry = resolveService(resolved.repoName, workspace);
+  if (!repoEntry || repoEntry.subsystem === resolved.subsystem) return null;
+  const manifest = readManifest(resolved.repoPath);
+  if (!manifest) return null;
+  const repoCommands = effectiveLocalCommands(
+    manifest,
+    repoEntry.subsystem,
+    resolved.repoName,
+    workspace ?? "default",
+  );
+  if (!repoCommands["up"]) return null;
+  if (command === "up")
+    return {
+      address: resolved.repoName,
+      note: `${resolved.address} has no up of its own; running ${resolved.repoName}'s up, which starts it`,
+    };
+  return command === "down"
+    ? {
+        note:
+          `${resolved.address} has no down of its own; it is stopped by ${resolved.repoName}'s down. ` +
+          `Run \`${product().cli} down ${resolved.repoName}\` (that stops every service it starts).`,
+      }
+    : {
+        note:
+          `${resolved.address} has no ${command} of its own; it is started by ${resolved.repoName}'s up. ` +
+          `Run \`${product().cli} ${command} ${resolved.repoName}\` (that reaches every service it starts).`,
+      };
+}
+
+// ── secret_env (R16) ─────────────────────────────────────────────────────────
+
+/** Commands that start a service process, and so get its secret_env. */
+function startsService(command: string): boolean {
+  return command === "up" || command === "restart";
+}
+
+/** A service's declared `services.<svc>.secret_env` (validated), or undefined. */
+function serviceSecretEnvSpec(
+  resolved: ResolvedService,
+): SecretEnvSpec | undefined {
+  const raw = readManifest(resolved.repoPath)?.services?.[resolved.subsystem]
+    ?.secret_env;
+  return assertSecretEnvSpec(
+    raw,
+    `${resolved.address}: services.${resolved.subsystem}.secret_env`,
+  );
+}
+
+/**
+ * The address whose command a run of `command` on `address` actually spawns
+ * (a service with no up of its own runs its repo's up), or null when none.
+ */
+function spawningAddress(
+  address: string,
+  command: string,
+  workspace?: string,
+): string | null {
+  const p = previewServiceCommand(address, command, workspace);
+  return p.kind === "run" || p.kind === "via-repo" ? p.address : null;
+}
+
+/**
+ * The secret_env key NAMES a run of `command` on `address` would inject,
+ * for a dry run or status: never a value, and the provider is never asked.
+ * `service` is the service's own secret_env (set in its command's env);
+ * `compose` is the repo's compose.secret_env, which Den's synthesized stack
+ * command resolves for the docker compose process.
+ */
+export function previewServiceSecretEnv(
+  address: string,
+  command: string,
+  workspace?: string,
+): { address: string; service: string[]; compose: string[] } | null {
+  if (!startsService(command)) return null;
+  const target = spawningAddress(address, command, workspace);
+  const resolved = target ? resolveService(target, workspace) : null;
+  if (!resolved) return null;
+  const manifest = readManifest(resolved.repoPath);
+  const service = Object.keys(
+    manifest?.services?.[resolved.subsystem]?.secret_env ?? {},
+  ).sort();
+  const declared = manifest?.services?.[resolved.subsystem]?.commands?.local;
+  const synthesized =
+    manifest?.compose && !declared?.[command]
+      ? composeCommands(
+          manifest,
+          resolved.subsystem,
+          resolved.repoName,
+          workspace ?? "default",
+        )[command]
+      : undefined;
+  const compose = synthesized
+    ? Object.keys(manifest?.compose?.secret_env ?? {}).sort()
+    : [];
+  if (!service.length && !compose.length) return null;
+  return { address: resolved.address, service, compose };
+}
+
+export type ServiceSecretEnvResult =
+  | { ok: true; secretEnv: Record<string, string> }
+  | { ok: false; message: string };
+
+/**
+ * Resolve the `secret_env` of the service a run of `command` on `address`
+ * spawns, for runServiceCommand's `secretEnv`. All or nothing; the provider
+ * is only asked when the service declares secret_env, and only for up and
+ * restart. Messages name keys, refs and the provider, never values.
+ */
+export async function prepareServiceSecretEnv(
+  address: string,
+  command: string,
+  workspace?: string,
+  provider: () => SecretsProvider = getSecretsProvider,
+): Promise<ServiceSecretEnvResult> {
+  if (!startsService(command)) return { ok: true, secretEnv: {} };
+  const target = spawningAddress(address, command, workspace);
+  const resolved = target ? resolveService(target, workspace) : null;
+  if (!resolved) return { ok: true, secretEnv: {} };
+  let spec: SecretEnvSpec | undefined;
+  try {
+    spec = serviceSecretEnvSpec(resolved);
+  } catch (e) {
+    return { ok: false, message: (e as Error).message };
+  }
+  if (!secretEnvKeys(spec).length) return { ok: true, secretEnv: {} };
+  const r = await resolveSecretEnv(spec, provider(), resolved.address);
+  return r.ok
+    ? { ok: true, secretEnv: r.env }
+    : { ok: false, message: r.message };
+}
+
+/** What a run of `command` on `address` would do, without running it. */
+export type ServiceCommandPreview =
+  | { kind: "run"; address: string }
+  | { kind: "via-repo"; address: string; note: string }
+  | { kind: "nothing"; address: string; note: string }
+  | { kind: "error"; address: string; note: string };
+
+/**
+ * The dry-run twin of runServiceCommand's command lookup: the same
+ * resolution, own-command, restart-synthesis and repo-started rules, so a
+ * dry run says what a real run does.
+ */
+export function previewServiceCommand(
+  address: string,
+  command: string,
+  workspace?: string,
+): ServiceCommandPreview {
+  const resolved = resolveService(address, workspace);
+  if (!resolved) {
+    const candidates = serviceAliasCandidates(address, workspace);
+    return {
+      kind: "error",
+      address,
+      note:
+        `service "${address}" not found in workspace "${workspace ?? "default"}"` +
+        (candidates.length > 1
+          ? `; it is ambiguous: ${candidates.join(", ")}`
+          : ""),
+    };
+  }
+  const manifest = readManifest(resolved.repoPath);
+  const own = manifest
+    ? effectiveLocalCommands(
+        manifest,
+        resolved.subsystem,
+        resolved.repoName,
+        workspace ?? "default",
+      )
+    : {};
+  if (own[command] || (command === "restart" && own["down"] && own["up"]))
+    return { kind: "run", address };
+  const viaRepo = repoStartedFallback(resolved, command, workspace);
+  if (viaRepo?.address)
+    return { kind: "via-repo", address: viaRepo.address, note: viaRepo.note };
+  if (viaRepo)
+    return command === "down"
+      ? { kind: "nothing", address, note: viaRepo.note }
+      : { kind: "error", address, note: viaRepo.note };
+  if (command === "down")
+    return {
+      kind: "nothing",
+      address,
+      note: "no down command: nothing to stop",
+    };
+  return {
+    kind: "error",
+    address,
+    note: `command "${command}" not found for service "${address}"`,
+  };
+}
+
 /**
  * Resolve and execute a service command.
  * Returns the spawned child process and whether it is a long-running (detachable) command.
@@ -1048,8 +1363,12 @@ export function runServiceCommand(
 
   const resolved = resolveService(address, workspace);
   if (!resolved) {
+    const candidates = serviceAliasCandidates(address, workspace);
     onLine(
-      `Error: service "${address}" not found in catalog or workspace "${workspace}"`,
+      `Error: service "${address}" not found in catalog or workspace "${workspace}"` +
+        (candidates.length > 1
+          ? `; it is ambiguous: ${candidates.join(", ")}`
+          : ""),
     );
     closeAsync(1);
     return dummy();
@@ -1281,6 +1600,16 @@ export function runServiceCommand(
   }
 
   if (!cmdDef) {
+    const viaRepo = repoStartedFallback(resolved, command, workspace);
+    if (viaRepo?.address) {
+      onLine(viaRepo.note);
+      return runServiceCommand({ ...options, address: viaRepo.address });
+    }
+    if (viaRepo) {
+      onLine(command === "down" ? viaRepo.note : `Error: ${viaRepo.note}`);
+      closeAsync(command === "down" ? 0 : 1);
+      return dummy();
+    }
     // Down is opctl-conventional: when no container is running AND the manifest
     // declares no down command, there is simply nothing to stop — that's a
     // successful down, not an error (keeps the ⋮ menu / workspace Down safe to
@@ -1304,6 +1633,41 @@ export function runServiceCommand(
     onLine,
   );
 
+  // R16: a service that declares secret_env never starts without every key
+  // (a caller that did not resolve them is refused, not run without them).
+  let secretEnv: Record<string, string> = {};
+  if (startsService(command)) {
+    let declared: string[];
+    try {
+      declared = secretEnvKeys(serviceSecretEnvSpec(resolved));
+    } catch (e) {
+      onLine(`Error: ${(e as Error).message}`);
+      closeAsync(1);
+      return dummy();
+    }
+    const missing = declared.filter((k) => !options.secretEnv?.[k]);
+    if (missing.length) {
+      onLine(
+        `Error: ${resolved.address} declares secret_env ${missing.join(", ")}, which were not resolved; not starting it`,
+      );
+      closeAsync(1);
+      return dummy();
+    }
+    secretEnv = Object.fromEntries(
+      declared.map((k) => [k, options.secretEnv?.[k] as string]),
+    );
+  }
+  const hasSecrets = Object.keys(secretEnv).length > 0;
+  // Secrets go only in the spawned process's env. A tab would need them in
+  // its command line (and so its shell history), so such a start runs as a
+  // daemon instead.
+  const runEnv: NodeJS.ProcessEnv = { ...env, ...secretEnv };
+  if (hasSecrets && runtime === "tab" && startsService(command))
+    onLine(
+      `${resolved.address} has secret_env: running as a daemon, not in a tab, to keep the values out of the tab's shell`,
+    );
+  const useTab = runtime === "tab" && !hasSecrets;
+
   // Manifest downs that are just `opctl container down <name>` must not be
   // spawned raw: opctl re-elevates with `sudo -E` and fails on sudoers without
   // SETENV even when there is nothing to stop — which is why files-api/api
@@ -1359,7 +1723,7 @@ export function runServiceCommand(
     // HITL command — inherit the full TTY; onLine is not called.
     const proc = spawnInteractive(
       cmdString,
-      { ...process.env, ...env },
+      { ...process.env, ...runEnv },
       onClose,
       repoPath,
     );
@@ -1409,11 +1773,11 @@ export function runServiceCommand(
     }
   };
 
-  if (runtime === "tab" && command === "up") {
+  if (useTab && command === "up") {
     return openCommandInTab(cmdString);
   }
 
-  if (runtime === "tab" && command === "restart") {
+  if (useTab && command === "restart") {
     closeExistingTab();
     if (requestedCmdDef) return openCommandInTab(cmdString);
 
@@ -1531,7 +1895,7 @@ export function runServiceCommand(
   const proc = spawnStreaming(
     cmdString,
     [],
-    { ...process.env, ...env },
+    { ...process.env, ...runEnv },
     onLine,
     wrappedOnClose,
     repoPath,

package/src/shared/manifest/schema.ts

@@ -9,6 +9,7 @@
 
 import { z } from "zod";
 import { journeysAppSchema } from "../../pillars/journeys/app-config.js";
+import { SECRET_ENV_KEY_RE, secretEnvRefError } from "../secrets/secret-env.js";
 
 export const CURRENT_SCHEMA_VERSION = 1;
 export const KNOWN_VERSIONS = [1] as const;
@@ -69,6 +70,16 @@ const logSource = z.union([
   }),
 ]);
 
+// secret_env (R16): ENV_NAME → "<vault>/<item>/<field>", resolved through the
+// secrets provider at up/restart and passed only in the process env.
+const secretEnvConfig = z.record(
+  z.string().regex(SECRET_ENV_KEY_RE, "must be a valid env var name"),
+  z.string().superRefine((ref, ctx) => {
+    const err = secretEnvRefError(ref);
+    if (err) ctx.addIssue({ code: z.ZodIssueCode.custom, message: err });
+  }),
+);
+
 // ── Service management config ─────────────────────────────────────────────────
 //
 // Keys for commands/logs/health are environment names (local, dev, …).
@@ -105,6 +116,7 @@ const serviceTarget = z
 const serviceManagementConfig = z.object({
   runs: z.record(z.string(), z.enum(["local", "remote"])).optional(),
   target: serviceTarget.optional(),
+  secret_env: secretEnvConfig.optional(),
   depends_on: z.array(dependsOnEntry).optional(),
   commands: z.record(z.string(), z.record(z.string(), commandDef)).optional(),
   logs: z.record(z.string(), logSource).optional(),
@@ -280,6 +292,9 @@ const composeConfig = z.object({
       z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
     )
     .optional(),
+  // Env vars resolved from the secrets provider into the docker compose
+  // process's env at up/restart. Never written to the override.
+  secret_env: secretEnvConfig.optional(),
 });
 
 // ── v1 manifest schema ────────────────────────────────────────────────────────

package/src/shared/manifest/validate-layers.ts

@@ -15,6 +15,7 @@
  */
 
 import * as fs from "fs";
+import * as path from "path";
 import { z } from "zod";
 import type { ValidationError, ValidationResult } from "../types/index.js";
 import {
@@ -24,11 +25,14 @@ import {
   type ManifestMap,
 } from "./merge-override.js";
 import {
+  heldManifestPath,
   loadManifest,
   orphanOverrideMessage,
+  overrideSuffix,
   parseManifestText,
   type ManifestLayer,
 } from "./read-manifest.js";
+import { product } from "../product.js";
 
 /** What layered validation needs from the schema module. */
 export interface SchemaTools {
@@ -170,6 +174,31 @@ function readLayer(file: string): { value: unknown } | { error: string } {
   }
 }
 
+/**
+ * A warning for a held manifest the repo's own manifest has made redundant:
+ * the repo's file always wins, so the held one is never read.
+ */
+function redundantHeldWarning(
+  heldFile: string,
+  overrideFile: string | null,
+): ValidationError {
+  const yml = product().manifestYml;
+  const name = path.basename(heldFile);
+  const key = name.endsWith(yml) ? name.slice(0, -yml.length) : name;
+  const asOverride = path.join(
+    path.dirname(heldFile),
+    `${key}${overrideSuffix()}`,
+  );
+  return {
+    path: "",
+    file: heldFile,
+    message: `${heldFile} is not used: the repo now carries its own manifest, which always wins`,
+    suggestion: overrideFile
+      ? `delete it; ${overrideFile} already layers onto the repo's manifest`
+      : `delete it, or turn it into an override (${asOverride}) that keeps only what this distribution changes`,
+  };
+}
+
 /** Validate every manifest layer of `repoPath`, then the merged result. */
 export function validateLayers(
   tools: SchemaTools,
@@ -189,10 +218,20 @@ export function validateLayers(
   }
 
   const base = readLayer(baseFile);
-  const baseResult =
+  let baseResult =
     "error" in base
       ? failure(tools.version, baseFile, base.error)
       : withFile(tools.validate(base.value), baseFile);
+  const redundantHeld =
+    baseLayer === "repo" ? heldManifestPath(repoPath) : null;
+  if (redundantHeld)
+    baseResult = {
+      ...baseResult,
+      warnings: [
+        ...baseResult.warnings,
+        redundantHeldWarning(redundantHeld, overrideFile),
+      ],
+    };
   layers.push({ layer: baseLayer, file: baseFile, result: baseResult });
 
   if (overrideFile) {

package/src/shared/secrets/doppler.ts

@@ -4,7 +4,8 @@
  *
  * Project/config come from `secrets.doppler.{project,config}` in
  * config/den.yml, else from the directory's `doppler setup` scope,
- * else from DOPPLER_PROJECT / DOPPLER_CONFIG / DOPPLER_TOKEN.
+ * else from DOPPLER_PROJECT / DOPPLER_CONFIG / DOPPLER_TOKEN. A scoped ref
+ * (a `secret_env` value, `<project>/<config>/<key>`) names its own.
  */
 import { execFile, spawn } from "child_process";
 import { promisify } from "util";
@@ -29,8 +30,12 @@ export class DopplerProvider implements SecretsProvider {
     this.timeout = opts.timeoutMs ?? 30_000;
   }
 
-  /** `--project/--config` flags when configured explicitly. */
-  scopeArgs(): string[] {
+  /**
+   * `--project/--config` flags: a scoped ref's own vault/item, else the
+   * configured ones (when set explicitly).
+   */
+  scopeArgs(ref?: SecretRef): string[] {
+    if (ref?.scoped) return ["--project", ref.vault, "--config", ref.item];
     const a: string[] = [];
     if (this.opts.project) a.push("--project", this.opts.project);
     if (this.opts.config) a.push("--config", this.opts.config);
@@ -56,7 +61,7 @@ export class DopplerProvider implements SecretsProvider {
     const key = this.keyFor(ref);
     const { stdout } = await execFileAsync(
       "doppler",
-      ["secrets", "get", key, "--plain", ...this.scopeArgs()],
+      ["secrets", "get", key, "--plain", ...this.scopeArgs(ref)],
       { timeout: this.timeout },
     );
     return String(stdout).trim();
@@ -77,7 +82,7 @@ export class DopplerProvider implements SecretsProvider {
     await new Promise<void>((resolve, reject) => {
       const child = spawn(
         "doppler",
-        ["secrets", "set", key, "--silent", ...this.scopeArgs()],
+        ["secrets", "set", key, "--silent", ...this.scopeArgs(ref)],
         { stdio: ["pipe", "ignore", "pipe"] },
       );
       let stderr = "";

package/src/shared/secrets/index.ts

@@ -26,6 +26,7 @@ export { flatKeyFor, toEnvName, refPath } from "./keys.js";
 export { DopplerProvider } from "./doppler.js";
 export { EnvProvider } from "./env.js";
 export { OnePasswordProvider } from "./onepassword.js";
+export * from "./secret-env.js";
 
 export interface SecretsConfig {
   provider?: SecretsProviderName;

package/src/shared/secrets/keys.ts

@@ -16,6 +16,7 @@ export function refPath(ref: SecretRef): string {
 
 /**
  * Resolve the flat key a key/value backend should use for `ref`:
+ *   0. a scoped ref's field, as is (it is fully qualified: no overrides);
  *   1. `ref.key` when the caller pinned one;
  *   2. the `secrets.keys` override map (`"vault/item/field": KEY`);
  *   3. the field itself when it already looks like an env var (API keys);
@@ -25,6 +26,7 @@ export function flatKeyFor(
   ref: SecretRef,
   overrides: Record<string, string> = {},
 ): string {
+  if (ref.scoped) return ref.field;
   if (ref.key) return ref.key;
   const mapped = overrides[refPath(ref)];
   if (mapped) return mapped;