feat(secrets): finalize mode rename and validated exec docs

src/secrets/plan.ts

@@ -1,4 +1,4 @@
-import type { SecretRef } from "../config/types.secrets.js";
+import type { SecretProviderConfig, SecretRef } from "../config/types.secrets.js";
 
 export type SecretsPlanTargetType =
   | "models.providers.apiKey"
@@ -28,6 +28,8 @@ export type SecretsApplyPlan = {
   protocolVersion: 1;
   generatedAt: string;
   generatedBy: "openclaw secrets configure" | "manual";
+  providerUpserts?: Record<string, SecretProviderConfig>;
+  providerDeletes?: string[];
   targets: SecretsPlanTarget[];
   options?: {
     scrubEnv?: boolean;
@@ -36,6 +38,72 @@ export type SecretsApplyPlan = {
   };
 };
 
+const PROVIDER_ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function isSecretProviderConfigShape(value: unknown): value is SecretProviderConfig {
+  if (!isObjectRecord(value) || typeof value.source !== "string") {
+    return false;
+  }
+
+  if (value.source === "env") {
+    if (value.allowlist !== undefined && !isStringArray(value.allowlist)) {
+      return false;
+    }
+    return true;
+  }
+
+  if (value.source === "file") {
+    if (typeof value.path !== "string" || value.path.trim().length === 0) {
+      return false;
+    }
+    if (value.mode !== undefined && value.mode !== "json" && value.mode !== "singleValue") {
+      return false;
+    }
+    return true;
+  }
+
+  if (value.source === "exec") {
+    if (typeof value.command !== "string" || value.command.trim().length === 0) {
+      return false;
+    }
+    if (value.args !== undefined && !isStringArray(value.args)) {
+      return false;
+    }
+    if (
+      value.passEnv !== undefined &&
+      (!Array.isArray(value.passEnv) || !value.passEnv.every((entry) => typeof entry === "string"))
+    ) {
+      return false;
+    }
+    if (
+      value.trustedDirs !== undefined &&
+      (!Array.isArray(value.trustedDirs) ||
+        !value.trustedDirs.every((entry) => typeof entry === "string"))
+    ) {
+      return false;
+    }
+    if (value.env !== undefined) {
+      if (!isObjectRecord(value.env)) {
+        return false;
+      }
+      if (!Object.values(value.env).every((entry) => typeof entry === "string")) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  return false;
+}
+
 export function isSecretsApplyPlan(value: unknown): value is SecretsApplyPlan {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -67,6 +135,30 @@ export function isSecretsApplyPlan(value: unknown): value is SecretsApplyPlan {
       return false;
     }
   }
+  if (typed.providerUpserts !== undefined) {
+    if (!isObjectRecord(typed.providerUpserts)) {
+      return false;
+    }
+    for (const [providerAlias, providerValue] of Object.entries(typed.providerUpserts)) {
+      if (!PROVIDER_ALIAS_PATTERN.test(providerAlias)) {
+        return false;
+      }
+      if (!isSecretProviderConfigShape(providerValue)) {
+        return false;
+      }
+    }
+  }
+  if (typed.providerDeletes !== undefined) {
+    if (
+      !Array.isArray(typed.providerDeletes) ||
+      typed.providerDeletes.some(
+        (providerAlias) =>
+          typeof providerAlias !== "string" || !PROVIDER_ALIAS_PATTERN.test(providerAlias),
+      )
+    ) {
+      return false;
+    }
+  }
   return true;
 }