fix(secrets): align ref contracts and non-interactive ref persistence

src/secrets/ref-contract.ts

@@ -0,0 +1,66 @@
+import {
+  DEFAULT_SECRET_PROVIDER_ALIAS,
+  type SecretRef,
+  type SecretRefSource,
+} from "../config/types.secrets.js";
+
+const FILE_SECRET_REF_SEGMENT_PATTERN = /^(?:[^~]|~0|~1)*$/;
+
+export const RAW_FILE_REF_ID = "value";
+
+export type SecretRefDefaultsCarrier = {
+  secrets?: {
+    defaults?: {
+      env?: string;
+      file?: string;
+      exec?: string;
+    };
+    providers?: Record<string, { source?: string }>;
+  };
+};
+
+export function secretRefKey(ref: SecretRef): string {
+  return `${ref.source}:${ref.provider}:${ref.id}`;
+}
+
+export function resolveDefaultSecretProviderAlias(
+  config: SecretRefDefaultsCarrier,
+  source: SecretRefSource,
+  options?: { preferFirstProviderForSource?: boolean },
+): string {
+  const configured =
+    source === "env"
+      ? config.secrets?.defaults?.env
+      : source === "file"
+        ? config.secrets?.defaults?.file
+        : config.secrets?.defaults?.exec;
+  if (configured?.trim()) {
+    return configured.trim();
+  }
+
+  if (options?.preferFirstProviderForSource) {
+    const providers = config.secrets?.providers;
+    if (providers) {
+      for (const [providerName, provider] of Object.entries(providers)) {
+        if (provider?.source === source) {
+          return providerName;
+        }
+      }
+    }
+  }
+
+  return DEFAULT_SECRET_PROVIDER_ALIAS;
+}
+
+export function isValidFileSecretRefId(value: string): boolean {
+  if (value === RAW_FILE_REF_ID) {
+    return true;
+  }
+  if (!value.startsWith("/")) {
+    return false;
+  }
+  return value
+    .slice(1)
+    .split("/")
+    .every((segment) => FILE_SECRET_REF_SEGMENT_PATTERN.test(segment));
+}