@monster-orange/den 0.2.7 → 0.3.0

package/src/shared/process/process-group.ts

@@ -0,0 +1,202 @@
+/**
+ * Process groups that a detached `up` started (0.3.0-dev.37).
+ *
+ * A detached service is spawned as the leader of its own process group, so
+ * its pid is the group id. `up` records that pgid together with the leader's
+ * start time, and `down` signals the whole group: SIGTERM, a short grace
+ * period, then SIGKILL.
+ *
+ * A recorded pid can be reused once its process exits, so nothing is
+ * signalled until the group is shown to still be the one `up` started:
+ *
+ *  - the leader (pid == pgid) is alive: its start time must equal the
+ *    recorded one, and it must still lead that group. Anything else is a
+ *    different process that happens to hold the pid, and it is left alone.
+ *  - the leader has exited but members still carry the pgid: the group is
+ *    still ours. A process group id is not handed out again while any
+ *    process is in that group, so live members of it are ones the leader
+ *    started.
+ *  - nothing carries the pgid: the group has exited.
+ */
+
+import { execFile, execFileSync } from "child_process";
+
+export interface RecordedProcessGroup {
+  /** The group id: the detached leader's pid. */
+  pgid: number;
+  /** The leader's start time as `ps -o lstart=` prints it. */
+  startedAt: string;
+}
+
+export type GroupState =
+  | { state: "ours"; members: number[] }
+  | { state: "gone" }
+  | { state: "reused"; detail: string };
+
+export type StopGroupOutcome =
+  | { outcome: "stopped"; signal: "SIGTERM" | "SIGKILL"; members: number[] }
+  | { outcome: "gone" }
+  | { outcome: "reused"; detail: string }
+  | { outcome: "survived"; members: number[] }
+  | { outcome: "error"; detail: string };
+
+interface PsRow {
+  pid: number;
+  pgid: number;
+  zombie: boolean;
+  lstart: string;
+}
+
+const PS = "ps";
+// lstart is printed in the C locale's fixed format, whatever the user's.
+const PS_ENV = { ...process.env, LC_ALL: "C", LANG: "C" };
+
+function parsePs(out: string): PsRow[] {
+  const rows: PsRow[] = [];
+  for (const line of out.split("\n")) {
+    const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/);
+    if (!m) continue;
+    rows.push({
+      pid: Number(m[1]),
+      pgid: Number(m[2]),
+      zombie: m[3].startsWith("Z"),
+      lstart: m[4].trim().replace(/\s+/g, " "),
+    });
+  }
+  return rows;
+}
+
+const PS_COLUMNS = ["-o", "pid=,pgid=,stat=,lstart="];
+const PS_ARGS = ["-A", ...PS_COLUMNS];
+
+function psRowsSync(args: string[]): PsRow[] | null {
+  try {
+    return parsePs(
+      execFileSync(PS, args, {
+        env: PS_ENV,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5000,
+      }),
+    );
+  } catch {
+    return null;
+  }
+}
+
+function psRows(): Promise<PsRow[] | null> {
+  return new Promise((resolve) => {
+    execFile(
+      PS,
+      PS_ARGS,
+      { env: PS_ENV, encoding: "utf-8", timeout: 5000 },
+      (err, stdout) => resolve(err ? null : parsePs(stdout)),
+    );
+  });
+}
+
+/**
+ * The record `up` keeps for a detached leader it just spawned, or null when
+ * the process cannot be read (it already exited, or `ps` is unavailable).
+ */
+export function recordProcessGroup(pid: number): RecordedProcessGroup | null {
+  const row = psRowsSync(["-p", String(pid), ...PS_COLUMNS])?.find(
+    (r) => r.pid === pid && !r.zombie,
+  );
+  if (!row || row.pgid !== pid) return null;
+  return { pgid: pid, startedAt: row.lstart };
+}
+
+/** A recorded group's state now, synchronously; null when `ps` cannot be run. */
+export function processGroupStateSync(
+  rec: RecordedProcessGroup,
+): GroupState | null {
+  const rows = psRowsSync(PS_ARGS);
+  return rows ? classifyGroup(rec, rows) : null;
+}
+
+/** Whether a recorded group is still the one `up` started (see the header). */
+export function classifyGroup(
+  rec: RecordedProcessGroup,
+  rows: PsRow[],
+): GroupState {
+  const live = rows.filter((r) => !r.zombie);
+  const leader = live.find((r) => r.pid === rec.pgid);
+  if (leader && (leader.lstart !== rec.startedAt || leader.pgid !== rec.pgid))
+    return {
+      state: "reused",
+      detail: `pid ${rec.pgid} now belongs to another process (started ${leader.lstart}; the recorded one started ${rec.startedAt})`,
+    };
+  const members = live.filter((r) => r.pgid === rec.pgid).map((r) => r.pid);
+  return members.length > 0 ? { state: "ours", members } : { state: "gone" };
+}
+
+/** The recorded group's state now; null when `ps` cannot be run. */
+export async function processGroupState(
+  rec: RecordedProcessGroup,
+): Promise<GroupState | null> {
+  const rows = await psRows();
+  return rows ? classifyGroup(rec, rows) : null;
+}
+
+function signalGroup(
+  pgid: number,
+  signal: NodeJS.Signals,
+): "sent" | "gone" | string {
+  try {
+    process.kill(-pgid, signal);
+    return "sent";
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "ESRCH") return "gone";
+    return `${signal} to process group ${pgid} failed: ${code ?? (e as Error).message}`;
+  }
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function waitUntilGone(
+  rec: RecordedProcessGroup,
+  ms: number,
+): Promise<GroupState | null> {
+  const deadline = Date.now() + ms;
+  let state = await processGroupState(rec);
+  while (state?.state === "ours" && Date.now() < deadline) {
+    await sleep(100);
+    state = await processGroupState(rec);
+  }
+  return state;
+}
+
+/**
+ * Stop a recorded process group: SIGTERM, up to `graceMs` for it to exit,
+ * then SIGKILL. The group is re-verified before each signal, so a pid that
+ * was reused in between is never signalled.
+ */
+export async function stopProcessGroup(
+  rec: RecordedProcessGroup,
+  graceMs = 3000,
+): Promise<StopGroupOutcome> {
+  const before = await processGroupState(rec);
+  if (!before) return { outcome: "error", detail: "could not run ps" };
+  if (before.state === "gone") return { outcome: "gone" };
+  if (before.state === "reused")
+    return { outcome: "reused", detail: before.detail };
+
+  const term = signalGroup(rec.pgid, "SIGTERM");
+  if (term === "gone") return { outcome: "gone" };
+  if (term !== "sent") return { outcome: "error", detail: term };
+
+  const afterTerm = await waitUntilGone(rec, graceMs);
+  if (!afterTerm) return { outcome: "error", detail: "could not run ps" };
+  if (afterTerm.state !== "ours")
+    return { outcome: "stopped", signal: "SIGTERM", members: before.members };
+
+  const kill = signalGroup(rec.pgid, "SIGKILL");
+  if (kill !== "sent" && kill !== "gone")
+    return { outcome: "error", detail: kill };
+  const afterKill = await waitUntilGone(rec, 2000);
+  if (afterKill?.state === "ours")
+    return { outcome: "survived", members: afterKill.members };
+  return { outcome: "stopped", signal: "SIGKILL", members: before.members };
+}

package/src/shared/process/spawn-streaming.ts

@@ -74,6 +74,7 @@ export function spawnDaemon(
   onClose: (exitCode: number) => void,
   cwd?: string,
   onServiceExit?: (exitCode: number) => void,
+  onSpawn?: (pid: number) => void,
 ): ReturnType<typeof spawn> {
   fs.mkdirSync(path.dirname(logPath), { recursive: true });
 
@@ -112,6 +113,9 @@ export function spawnDaemon(
     onLine(`Error: ${err.message}`);
     onServiceExit?.(1);
   });
+  // The service leads its own process group (detached), so its pid is the
+  // group id `down` signals later.
+  if (onSpawn && svcProc.pid) onSpawn(svcProc.pid);
   svcProc.unref(); // den's event loop can exit independently
   fs.closeSync(logFd); // parent closes its copy; child keeps its own fd
 
@@ -148,6 +152,7 @@ export function spawnDaemon(
  * @param cwd      Working directory (defaults to process.cwd())
  * @param detached Put the child in its own process group (default false)
  * @param logPath  If provided together with detached=true, run as a daemon writing to this path
+ * @param onSpawn  Daemon mode: called with the service's pid (its process group id) once spawned
  */
 export function spawnStreaming(
   command: string,
@@ -159,6 +164,7 @@ export function spawnStreaming(
   detached?: boolean,
   logPath?: string,
   onServiceExit?: (exitCode: number) => void,
+  onSpawn?: (pid: number) => void,
 ): ReturnType<typeof spawn> {
   // Daemon mode: service runs independently from den — survives restarts.
   if (detached && logPath) {
@@ -170,6 +176,7 @@ export function spawnStreaming(
       onClose,
       cwd,
       onServiceExit,
+      onSpawn,
     );
   }
 

package/src/shared/secrets/doppler.ts

@@ -1,6 +1,6 @@
 /**
  * Doppler strategy — reads/writes flat keys with the `doppler` CLI.
- * Selected with `secrets.provider: doppler` (the default).
+ * Selected with `secrets.provider: doppler`.
  *
  * Project/config come from `secrets.doppler.{project,config}` in
  * config/den.yml, else from the directory's `doppler setup` scope,

package/src/shared/secrets/index.ts

@@ -2,30 +2,40 @@
  * Secrets strategy selection.
  *
  * Resolution order for the backend:
- *   1. DEN_SECRETS_PROVIDER env var (doppler | 1password | env)
+ *   1. DEN_SECRETS_PROVIDER env var (none | doppler | 1password | env)
  *   2. `secrets.provider` in config/local/user.yml (per-engineer)
- *   3. `secrets.provider` in config/den.yml (team default)
- *   4. "doppler"
+ *   3. `secrets.provider` in the org config (team default)
+ *   4. "doppler" — implicit and deprecated: a warning says to set it.
  *
- * Adding a backend = implement SecretsProvider and register it in FACTORIES.
+ * Every backend is a strategy registered in the strategy registry
+ * (./strategies.ts); a new one registers there, like a plugin.
+ *
+ * Den assumes nothing about where a distribution keeps its secrets: no
+ * vault, item, field or account is built in. The engine's own named secrets
+ * (`sudo`, `journeys_agent_key`) exist only when `secrets.refs.<name>` says
+ * where they are; otherwise the feature reports "not configured".
  */
-import { OP_ACCOUNT_DEFAULT, OP_CLI_TIMEOUT_MS } from "../constants.js";
 import { readDenConfig, readUserConfig } from "../den-config.js";
-import { DopplerProvider } from "./doppler.js";
-import { EnvProvider } from "./env.js";
-import { OnePasswordProvider } from "./onepassword.js";
+import type { DetectResult } from "../strategies/registry.js";
+import { notConfiguredMessage, SecretsNotConfiguredError } from "./none.js";
+import { secretsStrategy, type SecretsStrategy } from "./strategies.js";
 import type {
+  PreflightResult,
   SecretRef,
   SecretsProvider,
   SecretsProviderName,
 } from "./types.js";
 
-import { envKey } from "../product.js";
+import { envKey, product } from "../product.js";
 export * from "./types.js";
 export { flatKeyFor, toEnvName, refPath } from "./keys.js";
 export { DopplerProvider } from "./doppler.js";
 export { EnvProvider } from "./env.js";
+export { NoneProvider } from "./none.js";
 export { OnePasswordProvider } from "./onepassword.js";
+export { notConfiguredMessage, SecretsNotConfiguredError } from "./none.js";
+export { secretsStrategy, secretsStrategyIds } from "./strategies.js";
+export type { SecretsStrategy, SecretsSetupContext } from "./strategies.js";
 export * from "./secret-env.js";
 
 export interface SecretsConfig {
@@ -42,17 +52,19 @@ export interface SecretsConfig {
   /** `"vault/item/field": FLAT_KEY` overrides for doppler/env. */
   keys?: Record<string, string>;
   /**
-   * Where the engine's own named secrets live, overriding the built-in
-   * defaults field by field (see {@link namedSecretRef}). Names in use:
-   * `sudo` (the saved local-dev sudo password) and `journeys_agent_key`
-   * (the journeys pillar's agent API key).
+   * Where the engine's own named secrets live (see {@link namedSecretRef}).
+   * There are no built-in defaults: a name with no entry here is "not
+   * configured" and its feature stays off. Names in use: `sudo` (the saved
+   * local-dev sudo password) and `journeys_agent_key` (the journeys
+   * pillar's agent API key).
    *
    *   refs:
-   *     journeys_agent_key: { vault: Shared, item: CI Keys }
+   *     sudo: { vault: Private, item: Dev Keys, field: ACME_LOCAL_ADMIN_PWD }
+   *     journeys_agent_key: { key: CURSOR_API_KEY }   # doppler / env
    */
   refs?: Record<string, Partial<SecretRef>>;
   /**
-   * The per-engineer developer keys `make den-setup-1password` collects
+   * The per-engineer developer keys `make <cli>-setup-1password` collects
    * into the developer-keys item (see scripts/setup-1password.ts). Default:
    * only the keys the engine itself uses.
    */
@@ -70,6 +82,10 @@ export interface DeveloperKeyDef {
 }
 
 export interface DeveloperKeysConfig {
+  /** The 1Password vault holding the developer-keys item (no default). */
+  vault?: string;
+  /** The developer-keys item (no default). */
+  item?: string;
   /**
    * A dotenv file (relative to the den root, e.g. an app checkout's
    * `.env`) whose values are offered as defaults.
@@ -79,26 +95,21 @@ export interface DeveloperKeysConfig {
 }
 
 export const SECRETS_PROVIDERS: readonly SecretsProviderName[] = [
+  "none",
   "doppler",
   "1password",
   "env",
 ];
 
-const FACTORIES: Record<
-  SecretsProviderName,
-  (c: SecretsConfig) => SecretsProvider
-> = {
-  doppler: (c) => new DopplerProvider({ ...c.doppler, keys: c.keys }),
-  "1password": (c) =>
-    new OnePasswordProvider({
-      account: c.onepassword?.account ?? OP_ACCOUNT_DEFAULT,
-      timeoutMs: OP_CLI_TIMEOUT_MS,
-    }),
-  env: (c) => new EnvProvider(c.keys),
-};
+/** The backend an unset `secrets.provider` falls back to (deprecated). */
+export const IMPLICIT_SECRETS_PROVIDER: SecretsProviderName = "doppler";
 
 function isProviderName(v: unknown): v is SecretsProviderName {
-  return typeof v === "string" && (SECRETS_PROVIDERS as string[]).includes(v);
+  return (
+    typeof v === "string" &&
+    (SECRETS_PROVIDERS as string[]).includes(v) &&
+    secretsStrategy(v) !== undefined
+  );
 }
 
 /** Effective secrets config (team file, then per-engineer override). */
@@ -125,33 +136,48 @@ export function readSecretsConfig(): SecretsConfig {
   };
 }
 
+/** Whether `ref` gives backend `name` enough to address a secret. */
+export function refIsComplete(
+  name: SecretsProviderName,
+  ref: Partial<SecretRef> | undefined,
+): boolean {
+  if (!ref || typeof ref !== "object") return false;
+  return secretsStrategy(name)?.capabilities.refComplete(ref) ?? false;
+}
+
 /**
- * The engine-named secret `name`: `defaults` with any configured
- * `secrets.refs.<name>` fields laid over them. The engine never hard-wires
- * an org's vault or item names; the defaults are neutral placeholders.
+ * The engine-named secret `name`, exactly as `secrets.refs.<name>` gives it,
+ * or null when the distribution has not configured it (or configured too
+ * little for the selected backend). There are no built-in defaults: Den
+ * never assumes a vault, item, field or key of its own.
  */
 export function namedSecretRef(
   name: string,
-  defaults: SecretRef,
   cfg: SecretsConfig = readSecretsConfig(),
-): SecretRef {
-  const override = cfg.refs?.[name] ?? {};
-  const pick = (v: unknown, d: string): string =>
-    typeof v === "string" && v.trim() ? v.trim() : d;
+  provider: SecretsProviderName = resolveProviderName(cfg),
+): SecretRef | null {
+  const raw = cfg.refs?.[name];
+  if (!refIsComplete(provider, raw)) return null;
+  const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
   const ref: SecretRef = {
-    vault: pick(override.vault, defaults.vault),
-    item: pick(override.item, defaults.item),
-    field: pick(override.field, defaults.field),
+    vault: str(raw!.vault),
+    item: str(raw!.item),
+    field: str(raw!.field) || str(raw!.key),
   };
-  const key = override.key ?? defaults.key;
-  if (key) ref.key = key;
+  if (str(raw!.key)) ref.key = str(raw!.key);
   return ref;
 }
 
-export function resolveProviderName(
+export interface ResolvedProvider {
+  name: SecretsProviderName;
+  /** True when nothing chose it: the deprecated implicit doppler default. */
+  implicit: boolean;
+}
+
+export function resolveProvider(
   cfg: SecretsConfig,
   env: NodeJS.ProcessEnv = process.env,
-): SecretsProviderName {
+): ResolvedProvider {
   const fromEnv = env.DEN_SECRETS_PROVIDER;
   if (fromEnv) {
     if (!isProviderName(fromEnv)) {
@@ -159,40 +185,243 @@ export function resolveProviderName(
         `${envKey("SECRETS_PROVIDER")}="${fromEnv}" is not one of ${SECRETS_PROVIDERS.join(", ")}`,
       );
     }
-    return fromEnv;
+    return { name: fromEnv, implicit: false };
   }
   if (cfg.provider !== undefined && !isProviderName(cfg.provider)) {
     throw new Error(
       `secrets.provider "${String(cfg.provider)}" is not one of ${SECRETS_PROVIDERS.join(", ")}`,
     );
   }
-  return cfg.provider ?? "doppler";
+  return cfg.provider
+    ? { name: cfg.provider, implicit: false }
+    : { name: IMPLICIT_SECRETS_PROVIDER, implicit: true };
+}
+
+export function resolveProviderName(
+  cfg: SecretsConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): SecretsProviderName {
+  return resolveProvider(cfg, env).name;
+}
+
+/** The registered strategy for `name` (always registered for a valid name). */
+export function strategyFor(name: SecretsProviderName): SecretsStrategy {
+  const s = secretsStrategy(name);
+  if (!s) throw new Error(`secrets strategy "${name}" is not registered`);
+  return s;
 }
 
 export function createSecretsProvider(
   name: SecretsProviderName,
   cfg: SecretsConfig = {},
 ): SecretsProvider {
-  return FACTORIES[name](cfg);
+  return strategyFor(name).capabilities.create(cfg);
+}
+
+/**
+ * The provider behind detect(): while the strategy reports its backend
+ * unavailable (its CLI is not on PATH), nothing is spawned. Reads report
+ * null / not ready, and get, set and preflight give detect()'s reason
+ * instead of a spawn error.
+ */
+class DetectedProvider implements SecretsProvider {
+  constructor(
+    private readonly inner: SecretsProvider,
+    private readonly strategy: SecretsStrategy,
+    private readonly implicit = false,
+  ) {}
+  get name(): SecretsProviderName {
+    return this.inner.name;
+  }
+  private unavailable(): string | null {
+    // The implicit default is resolved lazily: only a secret actually being
+    // read or written gets here, and only then does it warn (once).
+    if (this.implicit) warnImplicitOnce();
+    const d = this.strategy.detect();
+    return d.available ? null : `not available: ${d.reason ?? "unavailable"}`;
+  }
+  async isReady(): Promise<boolean> {
+    return this.unavailable() ? false : this.inner.isReady();
+  }
+  async get(ref: SecretRef): Promise<string> {
+    const why = this.unavailable();
+    if (why) throw new Error(`${this.name} secrets backend ${why}`);
+    return this.inner.get(ref);
+  }
+  async tryGet(ref: SecretRef): Promise<string | null> {
+    return this.unavailable() ? null : this.inner.tryGet(ref);
+  }
+  async set(ref: SecretRef, value: string): Promise<void> {
+    const why = this.unavailable();
+    if (why) throw new Error(`${this.name} secrets backend ${why}`);
+    return this.inner.set(ref, value);
+  }
+  async preflight(): Promise<PreflightResult> {
+    // Nothing chose a backend, so nothing requires one to be ready.
+    if (this.implicit) return { ok: true };
+    const why = this.unavailable();
+    if (why)
+      return {
+        ok: false,
+        message:
+          `${this.strategy.capabilities.label} ${why}.\n` +
+          `Install it, or set secrets.provider in ${product().configFile} (none | doppler | 1password | env).`,
+      };
+    return this.inner.preflight();
+  }
+  runPrefix(): string[] {
+    // Never wrap a command in an implicit backend.
+    if (this.implicit) return [];
+    return this.unavailable() ? [] : this.inner.runPrefix();
+  }
+}
+
+let warnedImplicit = false;
+function warnImplicitOnce(): void {
+  if (warnedImplicit) return;
+  warnedImplicit = true;
+  console.warn(`⚠️  ${IMPLICIT_PROVIDER_WARNING}`);
 }
 
 let cached: SecretsProvider | null = null;
 let cachedKey = "";
 
-/** The configured backend. Re-resolves when DEN_SECRETS_PROVIDER changes. */
+/**
+ * The configured backend, behind its strategy's detect(). Re-resolves when
+ * DEN_SECRETS_PROVIDER or the config changes.
+ */
 export function getSecretsProvider(): SecretsProvider {
   const cfg = readSecretsConfig();
-  const name = resolveProviderName(cfg);
-  const key = `${name}|${JSON.stringify(cfg)}`;
+  const { name, implicit } = resolveProvider(cfg);
+  const key = `${name}|${implicit}|${JSON.stringify(cfg)}`;
   if (!cached || key !== cachedKey) {
-    cached = createSecretsProvider(name, cfg);
+    cached = new DetectedProvider(
+      createSecretsProvider(name, cfg),
+      strategyFor(name),
+      implicit,
+    );
     cachedKey = key;
   }
   return cached;
 }
 
+export interface SecretsStatus {
+  /** The selected strategy id. */
+  backend: SecretsProviderName;
+  /** Name people see ("1Password"). */
+  label: string;
+  /** True when secrets.provider is unset (the deprecated doppler default). */
+  implicit: boolean;
+  /** detect() of the selected strategy. */
+  detect: DetectResult;
+}
+
+/** The selected strategy and its detect() result. Never spawns, never throws. */
+export function secretsStatus(
+  cfg: SecretsConfig = readSecretsConfig(),
+  env: NodeJS.ProcessEnv = process.env,
+  opts: { detect?: boolean } = {},
+): SecretsStatus {
+  let r: ResolvedProvider;
+  try {
+    r = resolveProvider(cfg, env);
+  } catch (err) {
+    return {
+      backend: "none",
+      label: "none",
+      implicit: false,
+      detect: { available: false, reason: (err as Error).message },
+    };
+  }
+  const s = strategyFor(r.name);
+  return {
+    backend: r.name,
+    label: s.capabilities.label,
+    implicit: r.implicit,
+    // detect:false: report the choice without probing (nothing needs it).
+    detect:
+      opts.detect === false
+        ? { available: false, reason: "not checked: nothing needs it" }
+        : s.detect(env),
+  };
+}
+
+/**
+ * Env vars the selected strategy gives the processes Den starts (the web
+ * server). Only 1password gives any (OP_ACCOUNT, from the distribution's
+ * config or the engineer's shell); every other backend gives none.
+ */
+export function secretsProcessEnv(
+  cfg: SecretsConfig = readSecretsConfig(),
+  env: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  let name: SecretsProviderName;
+  try {
+    name = resolveProviderName(cfg, env);
+  } catch {
+    return {};
+  }
+  return strategyFor(name).capabilities.env?.(cfg, env) ?? {};
+}
+
+/** The engine's own named refs, for the legacy warning. */
+export const ENGINE_SECRET_REFS = ["sudo", "journeys_agent_key"] as const;
+
+export const IMPLICIT_PROVIDER_WARNING =
+  "secrets.provider is not set; the implicit doppler default is deprecated and will be removed in a later minor. " +
+  "Set it explicitly: doppler, 1password, env or none.";
+
+/**
+ * Config warnings about secrets, for the server's startup log and
+ * `validate`: a 1password distribution with no refs (the old built-in
+ * vault/item/field are gone). The implicit doppler default warns lazily,
+ * the first time it resolves a secret (see getSecretsProvider), so a
+ * distribution that needs no secrets never hears about it.
+ */
+export function secretsConfigWarnings(
+  cfg: SecretsConfig = readSecretsConfig(),
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  let r: ResolvedProvider;
+  try {
+    r = resolveProvider(cfg, env);
+  } catch (err) {
+    return [(err as Error).message];
+  }
+  const out: string[] = [];
+  if (
+    r.name === "1password" &&
+    !ENGINE_SECRET_REFS.some((n) => refIsComplete(r.name, cfg.refs?.[n]))
+  ) {
+    out.push(
+      "secrets.provider is 1password but secrets.refs is empty: Den no longer assumes a default vault, item or field. " +
+        `Add the refs to ${product().configFile}, e.g.\n` +
+        "  secrets:\n" +
+        "    refs:\n" +
+        "      sudo: { vault: <vault>, item: <item>, field: <field> }\n" +
+        "      journeys_agent_key: { vault: <vault>, item: <item>, field: CURSOR_API_KEY }\n" +
+        "The vault-backed features (saved sudo password, journeys agent key) stay off until then.",
+    );
+  }
+  return out;
+}
+
+/**
+ * Throw "not configured" for engine ref `name`, or return it. For features
+ * that cannot run without it.
+ */
+export function requireNamedSecretRef(
+  name: string,
+  cfg: SecretsConfig = readSecretsConfig(),
+): SecretRef {
+  const ref = namedSecretRef(name, cfg);
+  if (!ref) throw new SecretsNotConfiguredError(notConfiguredMessage(name));
+  return ref;
+}
+
 /** Test hook. */
 export function resetSecretsProviderCache(): void {
   cached = null;
   cachedKey = "";
+  warnedImplicit = false;
 }