@penvhq/cli 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -27,7 +27,9 @@ __export(index_exports, {
   main: () => main,
   renderDoctor: () => renderDoctor,
   renderMove: () => renderMove,
+  renderPull: () => renderPull,
   renderPush: () => renderPush,
+  renderRotate: () => renderRotate,
   renderWatch: () => renderWatch,
   runDecrypt: () => runDecrypt,
   runDoctor: () => runDoctor,
@@ -39,15 +41,17 @@ __export(index_exports, {
   runList: () => runList,
   runMain: () => runMain,
   runMove: () => runMove,
+  runPull: () => runPull,
   runPush: () => runPush,
   runRemove: () => runRemove,
+  runRotate: () => runRotate,
   runSet: () => runSet,
   runValidate: () => runValidate,
   runWatch: () => runWatch
 });
 module.exports = __toCommonJS(index_exports);
-var import_core20 = require("@penvhq/core");
-var import_citty15 = require("citty");
+var import_core21 = require("@penvhq/core");
+var import_citty17 = require("citty");
 
 // src/commands/doctor.ts
 var import_core7 = require("@penvhq/core");
@@ -55,17 +59,35 @@ var import_sink_github2 = require("@penvhq/sink-github");
 var import_citty3 = require("citty");
 
 // src/project.ts
-var import_node_path = require("path");
+var import_node_path2 = require("path");
 var import_core2 = require("@penvhq/core");
 var import_provider_filesystem2 = require("@penvhq/provider-filesystem");
 
 // src/registry.ts
+var import_node_module = require("module");
+var import_node_path = require("path");
+var import_node_url = require("url");
 var import_core = require("@penvhq/core");
 var import_provider_filesystem = require("@penvhq/provider-filesystem");
+var import_provider_mock = require("@penvhq/provider-mock");
+var import_provider_vault = require("@penvhq/provider-vault");
+var PLUGIN_FACTORY_EXPORT = "penvProviderFactory";
 var LOCAL_TREE_TYPE = "filesystem";
 var REGISTRY = /* @__PURE__ */ new Map([
-  [LOCAL_TREE_TYPE, ({ root, config }) => (0, import_provider_filesystem.createFilesystemProvider)({ root, config })]
+  [LOCAL_TREE_TYPE, ({ root, config }) => (0, import_provider_filesystem.createFilesystemProvider)({ root, config })],
+  ["vault", ({ providerConfig }) => (0, import_provider_vault.createVaultProvider)({ path: providerConfig?.path ?? "penv" })],
+  ["mock", ({ root }) => (0, import_provider_mock.createMockProvider)({ storePath: (0, import_node_path.resolve)(root, ".penv-mock.json") })]
 ]);
+var CONTRACT_METHODS = [
+  "read",
+  "write",
+  "list",
+  "remove",
+  "readMeta",
+  "writeMeta",
+  "removeMeta"
+];
+var pluginModuleCache = /* @__PURE__ */ new Map();
 function isProviderRegistered(type) {
   return REGISTRY.has(type);
 }
@@ -76,20 +98,94 @@ function createProvider(type, context) {
   }
   return factory(context);
 }
-function assertProvidersRegistered(config) {
+async function createSourceProvider(type, context) {
+  if (REGISTRY.has(type)) {
+    return createProvider(type, context);
+  }
+  return loadPluginProvider(type, context);
+}
+async function loadPluginProvider(type, context) {
+  const fromDir = resolutionBase(context);
+  const specifier = pluginSpecifier(context.providerConfig, type);
+  const resolved = resolvePlugin(specifier, fromDir);
+  if (resolved === void 0) {
+    throw unknownProvider(type, context.environment, specifier);
+  }
+  let mod;
+  try {
+    mod = await importPlugin(resolved);
+  } catch {
+    throw new import_core.PenvError(
+      "PROVIDER_PLUGIN_LOAD",
+      `The provider package \`${specifier}\` for type \`${type}\` failed to load`,
+      "It resolved but threw while importing. Check it builds and its dependencies are installed."
+    );
+  }
+  const factory = mod[PLUGIN_FACTORY_EXPORT];
+  if (typeof factory !== "function") {
+    throw new import_core.PenvError(
+      "PROVIDER_PLUGIN_INVALID",
+      `\`${specifier}\` does not export \`${PLUGIN_FACTORY_EXPORT}\``,
+      `A penv provider package must export \`${PLUGIN_FACTORY_EXPORT}(context) => Provider\`.`
+    );
+  }
+  const provider = await factory(context);
+  assertSatisfiesContract(provider, specifier);
+  return provider;
+}
+function assertProvidersRegistered(config, projectRoot) {
   for (const [environment, provider] of Object.entries(config.providers)) {
-    if (!isProviderRegistered(provider.type)) {
-      throw unknownProvider(provider.type, environment);
+    if (isProviderRegistered(provider.type)) {
+      continue;
     }
+    const specifier = pluginSpecifier(provider, provider.type);
+    if (resolvePlugin(specifier, projectRoot) === void 0) {
+      throw unknownProvider(provider.type, environment, specifier);
+    }
+  }
+}
+function pluginSpecifier(providerConfig, type) {
+  return providerConfig?.module ?? `@penvhq/provider-${type}`;
+}
+function resolutionBase(context) {
+  return (0, import_node_path.dirname)(context.root);
+}
+function resolvePlugin(specifier, fromDir) {
+  try {
+    const require2 = (0, import_node_module.createRequire)((0, import_node_path.resolve)(fromDir, "noop.js"));
+    return require2.resolve(specifier);
+  } catch {
+    return void 0;
+  }
+}
+function importPlugin(resolvedPath) {
+  const cached2 = pluginModuleCache.get(resolvedPath);
+  if (cached2 !== void 0) {
+    return cached2;
   }
+  const loading = import((0, import_node_url.pathToFileURL)(resolvedPath).href);
+  pluginModuleCache.set(resolvedPath, loading);
+  return loading;
 }
-function unknownProvider(type, environment) {
+function assertSatisfiesContract(provider, specifier) {
+  for (const method of CONTRACT_METHODS) {
+    if (typeof provider[method] !== "function") {
+      throw new import_core.PenvError(
+        "PROVIDER_PLUGIN_INVALID",
+        `The provider from \`${specifier}\` is missing \`${method}()\``,
+        "It must satisfy the @penvhq/core Provider contract that the filesystem provider defines."
+      );
+    }
+  }
+}
+function unknownProvider(type, environment, specifier) {
   const known = [...REGISTRY.keys()].map((name) => `\`${name}\``).join(", ");
   const where = environment === void 0 ? "" : ` for environment ${environment}`;
+  const remedy = specifier === void 0 ? `This build registers ${known}. Name a registered provider, or install the build that carries \`${type}\`.` : `Install its package with \`npm i ${specifier}\`, or name a built-in provider: ${known}.`;
   return new import_core.PenvError(
     "UNKNOWN_PROVIDER",
     `The provider type \`${type}\`${where} in penv.config.ts is not one this penv build carries`,
-    `This build registers ${known}. Name a registered provider, or install the build that carries \`${type}\`.`
+    remedy
   );
 }
 
@@ -97,9 +193,9 @@ function unknownProvider(type, environment) {
 var PENV_DIR = ".penv";
 function openProject(cwd) {
   const { config, file } = (0, import_core2.loadConfig)(cwd);
-  const root = (0, import_node_path.dirname)(file);
-  const penvDir = (0, import_node_path.resolve)(root, PENV_DIR);
-  assertProvidersRegistered(config);
+  const root = (0, import_node_path2.dirname)(file);
+  const penvDir = (0, import_node_path2.resolve)(root, PENV_DIR);
+  assertProvidersRegistered(config, root);
   return {
     root,
     configFile: file,
@@ -118,6 +214,18 @@ function localTree(project) {
   }
   return project.provider;
 }
+async function sourceProviderFor(project, environment) {
+  const providerConfig = project.config.providers[environment];
+  if (providerConfig === void 0) {
+    return createProvider(LOCAL_TREE_TYPE, { root: project.penvDir, config: project.config });
+  }
+  return createSourceProvider(providerConfig.type, {
+    root: project.penvDir,
+    config: project.config,
+    providerConfig,
+    environment
+  });
+}
 function targetEnvironment(project, explicit) {
   return (0, import_core2.resolveEnvironment)(project.config, explicit);
 }
@@ -493,36 +601,36 @@ async function runPush(options) {
     decrypted: outbound.filter((item) => item.encrypted).length
   };
 }
-function renderPush(result) {
-  if (result.pushed === 0) {
+function renderPush(result2) {
+  if (result2.pushed === 0) {
     return formatRows([
       {
         glyph: CHECK,
         label: "Nothing to push",
-        subject: `no values resolve for environment ${result.environment}`
+        subject: `no values resolve for environment ${result2.environment}`
       }
     ]);
   }
-  const target = `GitHub Actions for environment ${result.environment}${result.repo === void 0 ? "" : ` (${result.repo})`}`;
+  const target = `GitHub Actions for environment ${result2.environment}${result2.repo === void 0 ? "" : ` (${result2.repo})`}`;
   const rows = [
     {
       glyph: CHECK,
       label: "Pushed",
-      subject: `${result.pushed} ${result.pushed === 1 ? "secret" : "secrets"}`,
+      subject: `${result2.pushed} ${result2.pushed === 1 ? "secret" : "secrets"}`,
       detail: `to ${target}`
     },
     {
       glyph: CHECK,
       label: "Scopes",
-      subject: `${result.environmentSecrets} environment, ${result.repositorySecrets} repository`,
+      subject: `${result2.environmentSecrets} environment, ${result2.repositorySecrets} repository`,
       detail: "environment secrets override repository secrets, as penv's env scope overrides the default"
     }
   ];
-  if (result.decrypted > 0) {
+  if (result2.decrypted > 0) {
     rows.push({
       glyph: WARN,
       label: "Decrypted",
-      subject: `${result.decrypted} ${result.decrypted === 1 ? "secret" : "secrets"}`,
+      subject: `${result2.decrypted} ${result2.decrypted === 1 ? "secret" : "secrets"}`,
       detail: "sent as plaintext for GitHub to re-seal under its own key"
     });
   }
@@ -542,19 +650,19 @@ var pushCommand = (0, import_citty.defineCommand)({
   },
   run({ args }) {
     return guard(async () => {
-      const result = await runPush({
+      const result2 = await runPush({
         cwd: process.cwd(),
         ...args.env === void 0 ? {} : { environment: args.env },
         ...args["allow-decrypt"] === void 0 ? {} : { allowDecrypt: args["allow-decrypt"] }
       });
-      write(renderPush(result));
+      write(renderPush(result2));
     });
   }
 });
 
 // src/commands/validate.ts
-var import_node_path2 = require("path");
-var import_node_url = require("url");
+var import_node_path3 = require("path");
+var import_node_url2 = require("url");
 var import_core6 = require("@penvhq/core");
 var import_citty2 = require("citty");
 var import_jiti = require("jiti");
@@ -623,16 +731,16 @@ function validationIssuesOf(cause, schemaPath) {
 }
 var schemaLoads = Promise.resolve();
 function exclusively(work) {
-  const result = schemaLoads.then(work, work);
-  schemaLoads = result.then(
+  const result2 = schemaLoads.then(work, work);
+  schemaLoads = result2.then(
     () => void 0,
     () => void 0
   );
-  return result;
+  return result2;
 }
 function loadSchema(project, environment) {
   const schemaPath = (0, import_core6.schemaFileOf)(project.config);
-  const file = (0, import_node_url.pathToFileURL)((0, import_node_path2.resolve)(project.root, schemaPath)).href;
+  const file = (0, import_node_url2.pathToFileURL)((0, import_node_path3.resolve)(project.root, schemaPath)).href;
   return exclusively(() => loadSchemaExclusively(file, schemaPath, environment));
 }
 async function loadSchemaExclusively(file, schemaPath, environment) {
@@ -734,9 +842,9 @@ async function runValidate(options) {
       }
     }
     drift = computeDrift({ schema, resolutions, config: project.config, environment });
-    const result = schema.safeParse(object);
-    if (!result.success) {
-      for (const problem of result.error.issues) {
+    const result2 = schema.safeParse(object);
+    if (!result2.success) {
+      for (const problem of result2.error.issues) {
         const path = problem.path.join(".");
         if (undecryptable.has(path)) {
           continue;
@@ -752,24 +860,24 @@ async function runValidate(options) {
   }
   return { ok: issues.length === 0, environment, parameters: refs.length, issues, drift };
 }
-function renderValidate(result) {
-  if (result.ok) {
+function renderValidate(result2) {
+  if (result2.ok) {
     return formatRows([
       {
         glyph: CHECK,
         label: "Schema valid",
-        subject: `${result.parameters} parameters for environment ${result.environment}`
+        subject: `${result2.parameters} parameters for environment ${result2.environment}`
       }
     ]);
   }
-  const rows = result.issues.map((issue) => ({
+  const rows = result2.issues.map((issue) => ({
     glyph: WARN,
     label: LABELS[issue.kind],
     subject: issue.subject,
     detail: issue.message
   }));
   const lines = formatRows(rows);
-  const remedies = [...new Set(result.issues.map((issue) => issue.remedy))];
+  const remedies = [...new Set(result2.issues.map((issue) => issue.remedy))];
   for (const remedy of remedies) {
     if (remedy !== void 0) {
       lines.push(`  ${remedy}`);
@@ -787,12 +895,12 @@ var validateCommand = (0, import_citty2.defineCommand)({
   },
   run({ args }) {
     return guard(async () => {
-      const result = await runValidate({
+      const result2 = await runValidate({
         cwd: process.cwd(),
         ...args.env === void 0 ? {} : { environment: args.env }
       });
-      write(renderValidate(result));
-      if (!result.ok) {
+      write(renderValidate(result2));
+      if (!result2.ok) {
         process.exitCode = 1;
       }
     });
@@ -800,6 +908,7 @@ var validateCommand = (0, import_citty2.defineCommand)({
 });
 
 // src/commands/doctor.ts
+var STUCK_THRESHOLD_MS = 864e5;
 function skipped(check, label) {
   return {
     check,
@@ -813,6 +922,8 @@ async function runDoctor(options) {
   const project = openProject(options.cwd);
   const environment = targetEnvironment(project, options.environment);
   const findings = [];
+  const now = new Date(options.now ?? (/* @__PURE__ */ new Date()).toISOString());
+  const stuckThresholdMs = options.stuckThresholdMs ?? STUCK_THRESHOLD_MS;
   const { schema, issues } = await loadSchema(project, environment);
   if (schema !== void 0) {
     findings.push({ check: "schema", severity: "pass", label: "Schema valid" });
@@ -861,6 +972,14 @@ async function runDoctor(options) {
   findings.push(...plaintextSecretFindings(subjects, environment));
   findings.push(...publicSecretFindings(subjects, environment, project.config));
   findings.push(...encryptionFindings(subjects, environment));
+  const rotation = await rotationSubjects(project, environment, subjects, options.source);
+  if (rotation.kind === "unreachable") {
+    findings.push(rotation.finding);
+  } else {
+    findings.push(...overdueFindings(rotation.subjects, environment, now));
+    findings.push(...stuckFindings(rotation.subjects, environment, now, stuckThresholdMs));
+  }
+  findings.push(...await providerDriftFindings(project, environment, options.source));
   findings.push(...await sinkFindings(project, environment, options.sink));
   findings.push({
     check: "provider",
@@ -1278,6 +1397,246 @@ async function sinkFindings(project, environment, override) {
   });
   return findings;
 }
+function humanizeMs(ms) {
+  const abs = Math.max(0, ms);
+  const day = 864e5;
+  const hour = 36e5;
+  const minute = 6e4;
+  const round = (value, unit) => {
+    const n = Math.round(value);
+    return `${n} ${unit}${n === 1 ? "" : "s"}`;
+  };
+  if (abs >= day) return round(abs / day, "day");
+  if (abs >= hour) return round(abs / hour, "hour");
+  if (abs >= minute) return round(abs / minute, "minute");
+  return round(abs / 1e3, "second");
+}
+function refPathOf(ref) {
+  return [...ref.namespace, ref.name].join("/");
+}
+async function rotationSubjects(project, environment, local, override) {
+  const providerConfig = project.config.providers[environment];
+  if (override === void 0 && (providerConfig === void 0 || providerConfig.type === LOCAL_TREE_TYPE)) {
+    return { kind: "read", subjects: local };
+  }
+  const source = override ?? await sourceProviderFor(project, environment);
+  try {
+    const subjects = await Promise.all(
+      local.map(async ({ resolution }) => ({
+        resolution,
+        meta: await source.readMeta(resolution.ref)
+      }))
+    );
+    return { kind: "read", subjects };
+  } catch (error) {
+    return {
+      kind: "unreachable",
+      finding: {
+        check: "rotation-overdue",
+        severity: "unknown",
+        label: "Rotation",
+        subject: `could not reach the ${providerConfig?.type ?? source.type} source of truth for ${environment}`,
+        detail: errorDetail(error)
+      }
+    };
+  }
+}
+function overdueFindings(subjects, environment, now) {
+  const findings = [];
+  for (const { resolution, meta } of subjects) {
+    const { policy, lastRotated } = (0, import_core7.rotationOf)(meta, environment);
+    if (policy === void 0 || lastRotated === null) {
+      continue;
+    }
+    const interval = (0, import_core7.tryParseDuration)(policy);
+    if (interval === void 0) {
+      findings.push({
+        check: "rotation-overdue",
+        severity: "warning",
+        label: "Rotation policy invalid",
+        subject: resolution.parameter,
+        detail: `rotationPolicy \`${policy}\` is not a duration penv can parse (e.g. \`90d\`, \`24h\`)`
+      });
+      continue;
+    }
+    const last = Date.parse(lastRotated);
+    if (Number.isNaN(last)) {
+      continue;
+    }
+    const overdueBy = now.getTime() - last - interval;
+    if (overdueBy <= 0) {
+      continue;
+    }
+    findings.push({
+      check: "rotation-overdue",
+      severity: "warning",
+      label: "Rotation overdue",
+      subject: resolution.parameter,
+      detail: `overdue by ~${humanizeMs(overdueBy)}, policy ${policy}`,
+      remedy: `penv rotate ${refPathOf(resolution.ref)} --env ${environment}`
+    });
+  }
+  if (findings.length > 0) {
+    return findings;
+  }
+  return [
+    {
+      check: "rotation-overdue",
+      severity: "pass",
+      label: "Rotation freshness",
+      subject: `no parameter is past its rotation policy for ${environment}`
+    }
+  ];
+}
+function stuckFindings(subjects, environment, now, stuckThresholdMs) {
+  const findings = [];
+  for (const { resolution, meta } of subjects) {
+    if (!(0, import_core7.isStuck)(meta, environment, now, stuckThresholdMs)) {
+      continue;
+    }
+    const { rotatingSince } = (0, import_core7.rotationOf)(meta, environment);
+    if (rotatingSince === null) {
+      continue;
+    }
+    const openFor = now.getTime() - Date.parse(rotatingSince);
+    findings.push({
+      check: "rotation-stuck",
+      severity: "warning",
+      label: "Rotation stuck",
+      subject: resolution.parameter,
+      detail: `dual-valid window open ~${humanizeMs(openFor)}, past the ${humanizeMs(stuckThresholdMs)} grace window`,
+      remedy: `penv rotate ${refPathOf(resolution.ref)} --complete --env ${environment}`
+    });
+  }
+  if (findings.length > 0) {
+    return findings;
+  }
+  return [
+    {
+      check: "rotation-stuck",
+      severity: "pass",
+      label: "Rotation progress",
+      subject: `no dual-valid rotation has stayed open past its grace window for ${environment}`
+    }
+  ];
+}
+function driftKey(file) {
+  return [file.namespace.join("/"), file.name, scopeKey(file.scope)].join(" ");
+}
+function scopeKey(scope) {
+  switch (scope.kind) {
+    case "unscoped":
+      return "unscoped";
+    case "environment":
+      return `environment:${scope.environment}`;
+    case "local":
+      return "local";
+    case "environment-local":
+      return `environment-local:${scope.environment}`;
+    default:
+      return (0, import_core7.assertNever)(scope, "scope");
+  }
+}
+function relevantToEnvironment(file, environment) {
+  const scope = file.scope;
+  if (scope.kind === "unscoped") return true;
+  if (scope.kind === "environment") return scope.environment === environment;
+  return false;
+}
+async function readRelevant(provider, environment) {
+  const files = (await provider.list()).filter((file) => relevantToEnvironment(file, environment));
+  const stored = await Promise.all(files.map((file) => provider.read(file)));
+  const entries = /* @__PURE__ */ new Map();
+  for (const [index, file] of files.entries()) {
+    const value = stored[index];
+    if (value !== void 0) {
+      entries.set(driftKey(file), { file, stored: value });
+    }
+  }
+  return entries;
+}
+async function providerDriftFindings(project, environment, override) {
+  const providerConfig = project.config.providers[environment];
+  if (providerConfig === void 0 || providerConfig.type === LOCAL_TREE_TYPE) {
+    return [
+      {
+        check: "provider-value-drift",
+        severity: "pass",
+        label: "Provider values",
+        subject: `${environment} keeps its values in the local .penv tree, so there is no other source of truth to compare against`
+      }
+    ];
+  }
+  const source = override ?? await sourceProviderFor(project, environment);
+  let local;
+  let remote;
+  try {
+    local = await readRelevant(project.provider, environment);
+    remote = await readRelevant(source, environment);
+  } catch (error) {
+    return [
+      {
+        check: "provider-value-drift",
+        severity: "unknown",
+        label: "Provider values",
+        subject: `could not reach the ${providerConfig.type} provider for ${environment}`,
+        detail: errorDetail(error)
+      }
+    ];
+  }
+  const keys = keySourceFor(project, environment);
+  const findings = [];
+  const addresses = [.../* @__PURE__ */ new Set([...local.keys(), ...remote.keys()])].sort();
+  for (const address of addresses) {
+    const here = local.get(address);
+    const there = remote.get(address);
+    if (here !== void 0 && there !== void 0) {
+      const opened = (0, import_core7.openValue)(here.file, here.stored, keys);
+      if (opened.kind !== "plaintext") {
+        findings.push({
+          check: "provider-value-drift",
+          severity: "unknown",
+          label: "Provider value unreadable",
+          subject: (0, import_core7.formatValueFile)(here.file),
+          detail: `the local value is sealed and did not open, so it cannot be compared against the ${providerConfig.type} source of truth`
+        });
+        continue;
+      }
+      if (opened.value !== there.stored) {
+        findings.push({
+          check: "provider-value-drift",
+          severity: "failure",
+          label: "Provider value drift",
+          subject: (0, import_core7.formatValueFile)(here.file),
+          detail: `the local tree and the ${providerConfig.type} source of truth hold different values`
+        });
+      }
+      continue;
+    }
+    const present = here ?? there;
+    if (present === void 0) {
+      continue;
+    }
+    findings.push({
+      check: "provider-value-drift",
+      severity: "warning",
+      label: here !== void 0 ? "Only in the local tree" : "Only in the source",
+      subject: (0, import_core7.formatValueFile)(present.file),
+      detail: here !== void 0 ? `present locally, absent from the ${providerConfig.type} source of truth` : `present in the ${providerConfig.type} source of truth, absent from the local tree`
+    });
+  }
+  if (findings.length > 0) {
+    return findings;
+  }
+  return [
+    {
+      check: "provider-value-drift",
+      severity: "pass",
+      label: "Provider values",
+      subject: `every value matches the ${providerConfig.type} source of truth for ${environment}`
+    }
+  ];
+}
 function renderDoctor(report) {
   const rows = report.findings.map((finding) => ({
     glyph: finding.severity === "pass" ? CHECK : finding.severity === "unknown" ? UNKNOWN : WARN,
@@ -1364,32 +1723,44 @@ function sealFor(project, file, value, parameter, environment) {
   }
   return (0, import_core8.sealValue)(file, value, keySourceFor(project, environment), parameter, environment);
 }
-async function runSet(options) {
-  const project = openProject(options.cwd);
-  const ref = refFromKey(options.key, project.config);
-  const scope = targetScope(project, options, options.key);
-  const environment = policyEnvironment(project, options);
-  const secret = (0, import_core8.isSecret)(await project.provider.readMeta(ref), environment);
+async function sealAwareWrite(options) {
+  const { project, provider, ref, scope, value, environment } = options;
+  const secret = (0, import_core8.isSecret)(await provider.readMeta(ref), environment);
   const file = {
     namespace: ref.namespace,
     name: ref.name,
     scope,
     encrypted: secret
   };
-  const stored = secret ? sealFor(project, file, options.value, (0, import_core8.parameterId)(ref), environment) : options.value;
-  await project.provider.write(file, stored);
-  await project.provider.remove({ ...file, encrypted: !secret });
-  return { parameter: options.key, location: (0, import_core8.formatValueFile)(file), encrypted: secret };
+  const stored = secret ? sealFor(project, file, value, (0, import_core8.parameterId)(ref), environment) : value;
+  await provider.write(file, stored);
+  await provider.remove({ ...file, encrypted: !secret });
+  return { encrypted: secret, location: (0, import_core8.formatValueFile)(file) };
 }
-function renderSet(result) {
+async function runSet(options) {
+  const project = openProject(options.cwd);
+  const ref = refFromKey(options.key, project.config);
+  const scope = targetScope(project, options, options.key);
+  const environment = policyEnvironment(project, options);
+  const { encrypted, location } = await sealAwareWrite({
+    project,
+    provider: project.provider,
+    ref,
+    scope,
+    value: options.value,
+    environment
+  });
+  return { parameter: options.key, location, encrypted };
+}
+function renderSet(result2) {
   return formatRows([
     {
       glyph: CHECK,
       label: "Wrote",
-      subject: `${PENV_DIR}/${result.location}`,
+      subject: `${PENV_DIR}/${result2.location}`,
       // The `.enc` suffix says this already, but only to a reader who knows the
       // grammar. Meta decided it, not the command line, so the command says so.
-      ...result.encrypted ? { detail: "encrypted, per the parameter's meta policy" } : {}
+      ...result2.encrypted ? { detail: "encrypted, per the parameter's meta policy" } : {}
     }
   ]);
 }
@@ -1525,13 +1896,13 @@ var UndecryptableAt = class extends import_core9.PenvError {
     );
   }
 };
-function renderReseal(result, verb) {
+function renderReseal(result2, verb) {
   return formatRows([
     {
       glyph: CHECK,
       label: verb,
-      subject: `${PENV_DIR}/${result.location}`,
-      detail: `${PENV_DIR}/${result.removed} removed`
+      subject: `${PENV_DIR}/${result2.location}`,
+      detail: `${PENV_DIR}/${result2.removed} removed`
     }
   ]);
 }
@@ -1554,8 +1925,8 @@ var encryptCommand = (0, import_citty5.defineCommand)({
   args: SCOPE_ARGS,
   run({ args }) {
     return guard(async () => {
-      const result = await runEncrypt({ cwd: process.cwd(), key: args.key, ...scopeOptions(args) });
-      write(renderReseal(result, "Encrypted"));
+      const result2 = await runEncrypt({ cwd: process.cwd(), key: args.key, ...scopeOptions(args) });
+      write(renderReseal(result2, "Encrypted"));
     });
   }
 });
@@ -1564,15 +1935,15 @@ var decryptCommand = (0, import_citty5.defineCommand)({
   args: SCOPE_ARGS,
   run({ args }) {
     return guard(async () => {
-      const result = await runDecrypt({ cwd: process.cwd(), key: args.key, ...scopeOptions(args) });
-      write(renderReseal(result, "Decrypted"));
+      const result2 = await runDecrypt({ cwd: process.cwd(), key: args.key, ...scopeOptions(args) });
+      write(renderReseal(result2, "Decrypted"));
     });
   }
 });
 
 // src/commands/generate.ts
 var import_node_fs = require("fs");
-var import_node_path3 = require("path");
+var import_node_path4 = require("path");
 var import_core10 = require("@penvhq/core");
 var import_citty6 = require("citty");
 var DEFAULT_OUTPUT = ".env";
@@ -1624,28 +1995,28 @@ function runGenerate(options) {
   const project = openProject(options.cwd);
   const environment = targetEnvironment(project, options.environment);
   const { entries, decrypted } = entriesFor(project, environment, options.allowDecrypt === true);
-  const file = options.out === void 0 ? (0, import_node_path3.resolve)(project.root, DEFAULT_OUTPUT) : (0, import_node_path3.isAbsolute)(options.out) ? options.out : (0, import_node_path3.resolve)(options.cwd, options.out);
+  const file = options.out === void 0 ? (0, import_node_path4.resolve)(project.root, DEFAULT_OUTPUT) : (0, import_node_path4.isAbsolute)(options.out) ? options.out : (0, import_node_path4.resolve)(options.cwd, options.out);
   (0, import_node_fs.writeFileSync)(file, (0, import_core10.serializeDotenv)(entries), "utf8");
   return { file, environment, entries: entries.length, decrypted };
 }
 function displayPath(cwd, file) {
-  const rel = (0, import_node_path3.relative)(cwd, file);
+  const rel = (0, import_node_path4.relative)(cwd, file);
   return rel === "" || rel.startsWith("..") ? file : rel.split("\\").join("/");
 }
-function renderGenerate(result, cwd) {
+function renderGenerate(result2, cwd) {
   const rows = [
     {
       glyph: CHECK,
       label: "Generated",
-      subject: displayPath(cwd, result.file),
-      detail: `${result.entries} variables for environment ${result.environment}`
+      subject: displayPath(cwd, result2.file),
+      detail: `${result2.entries} variables for environment ${result2.environment}`
     }
   ];
-  if (result.decrypted > 0) {
+  if (result2.decrypted > 0) {
     rows.push({
       glyph: WARN,
       label: "Decrypted",
-      subject: `${result.decrypted} ${result.decrypted === 1 ? "secret" : "secrets"}`,
+      subject: `${result2.decrypted} ${result2.decrypted === 1 ? "secret" : "secrets"}`,
       detail: "written as plaintext into the artifact"
     });
   }
@@ -1664,13 +2035,13 @@ var generateCommand = (0, import_citty6.defineCommand)({
   run({ args }) {
     return guard(async () => {
       const cwd = process.cwd();
-      const result = runGenerate({
+      const result2 = runGenerate({
         cwd,
         ...args.env === void 0 ? {} : { environment: args.env },
         ...args.out === void 0 ? {} : { out: args.out },
         ...args["allow-decrypt"] === void 0 ? {} : { allowDecrypt: args["allow-decrypt"] }
       });
-      write(renderGenerate(result, cwd));
+      write(renderGenerate(result2, cwd));
     });
   }
 });
@@ -1761,13 +2132,13 @@ var getCommand = (0, import_citty7.defineCommand)({
 
 // src/commands/import.ts
 var import_node_fs4 = require("fs");
-var import_node_path6 = require("path");
+var import_node_path7 = require("path");
 var import_core14 = require("@penvhq/core");
 var import_citty9 = require("citty");
 
 // src/detect.ts
 var import_node_fs2 = require("fs");
-var import_node_path4 = require("path");
+var import_node_path5 = require("path");
 var import_core12 = require("@penvhq/core");
 var SIGNATURES = [
   { name: "Next.js", packages: ["next"], publicPrefixes: ["NEXT_PUBLIC_"] },
@@ -1793,11 +2164,11 @@ function exportsSchema(file) {
   );
 }
 function occupied(cwd, relative3) {
-  const file = (0, import_node_path4.join)(cwd, ...relative3.split("/"));
+  const file = (0, import_node_path5.join)(cwd, ...relative3.split("/"));
   return (0, import_node_fs2.existsSync)(file) && !exportsSchema(file);
 }
 function schemaFileFor(cwd) {
-  const dir = (0, import_node_fs2.existsSync)((0, import_node_path4.join)(cwd, "src")) ? "src/" : "";
+  const dir = (0, import_node_fs2.existsSync)((0, import_node_path5.join)(cwd, "src")) ? "src/" : "";
   const preferred = `${dir}env.ts`;
   if (!occupied(cwd, preferred)) {
     return { file: preferred };
@@ -1825,7 +2196,7 @@ function dependenciesOf(cwd) {
   return names;
 }
 function manifestOf(cwd) {
-  const file = (0, import_node_path4.join)(cwd, "package.json");
+  const file = (0, import_node_path5.join)(cwd, "package.json");
   if (!(0, import_node_fs2.existsSync)(file)) {
     return void 0;
   }
@@ -1868,7 +2239,7 @@ function hasImportsBlock(cwd) {
 
 // src/commands/init.ts
 var import_node_fs3 = require("fs");
-var import_node_path5 = require("path");
+var import_node_path6 = require("path");
 var import_promises = require("readline/promises");
 var import_core13 = require("@penvhq/core");
 var import_citty8 = require("citty");
@@ -1933,7 +2304,7 @@ function configOf(decisions) {
   return { environments: decisions.environments, providers: {}, schemaFile: decisions.schemaFile };
 }
 function declaredIn(root) {
-  const file = (0, import_node_path5.join)(root, CONFIG_FILE);
+  const file = (0, import_node_path6.join)(root, CONFIG_FILE);
   if (!(0, import_node_fs3.existsSync)(file)) {
     return void 0;
   }
@@ -2329,7 +2700,7 @@ function renderTsconfig(target, alias) {
 `;
 }
 function ensurePenvDir(root) {
-  const dir = (0, import_node_path5.resolve)(root, PENV_DIR2);
+  const dir = (0, import_node_path6.resolve)(root, PENV_DIR2);
   if ((0, import_node_fs3.existsSync)(dir)) {
     return { target: "penv-dir", action: "kept", text: `Found ${PENV_DIR2}/` };
   }
@@ -2337,7 +2708,7 @@ function ensurePenvDir(root) {
   return { target: "penv-dir", action: "created", text: `Created ${PENV_DIR2}/` };
 }
 function writeSchemaFile(root, fields, draft, decisions = DEFAULT_DECISIONS) {
-  const file = (0, import_node_path5.join)(root, ...decisions.schemaFile.split("/"));
+  const file = (0, import_node_path6.join)(root, ...decisions.schemaFile.split("/"));
   if ((0, import_node_fs3.existsSync)(file)) {
     return {
       target: "schema",
@@ -2346,7 +2717,7 @@ function writeSchemaFile(root, fields, draft, decisions = DEFAULT_DECISIONS) {
       note: "(yours \u2014 penv never regenerates it)"
     };
   }
-  (0, import_node_fs3.mkdirSync)((0, import_node_path5.dirname)(file), { recursive: true });
+  (0, import_node_fs3.mkdirSync)((0, import_node_path6.dirname)(file), { recursive: true });
   (0, import_node_fs3.writeFileSync)(file, renderSchemaModule(fields, draft), "utf8");
   return {
     target: "schema",
@@ -2356,7 +2727,7 @@ function writeSchemaFile(root, fields, draft, decisions = DEFAULT_DECISIONS) {
   };
 }
 function writeConfigFile(root, decisions = DEFAULT_DECISIONS) {
-  const file = (0, import_node_path5.join)(root, CONFIG_FILE);
+  const file = (0, import_node_path6.join)(root, CONFIG_FILE);
   if ((0, import_node_fs3.existsSync)(file)) {
     return { target: "config", action: "kept", text: `Kept ${CONFIG_FILE}` };
   }
@@ -2366,7 +2737,7 @@ function writeConfigFile(root, decisions = DEFAULT_DECISIONS) {
 function writeTsconfigAlias(root, decisions = DEFAULT_DECISIONS) {
   const alias = decisions.alias;
   const imports = alias.startsWith(IMPORTS_PREFIX);
-  const file = (0, import_node_path5.join)(root, imports ? PACKAGE_FILE : TSCONFIG_FILE);
+  const file = (0, import_node_path6.join)(root, imports ? PACKAGE_FILE : TSCONFIG_FILE);
   const where = imports ? PACKAGE_FILE : TSCONFIG_FILE;
   if (!(0, import_node_fs3.existsSync)(file)) {
     if (imports) {
@@ -2409,14 +2780,14 @@ function writeTsconfigAlias(root, decisions = DEFAULT_DECISIONS) {
   };
 }
 function writeGitignore(root, decisions = DEFAULT_DECISIONS) {
-  const file = (0, import_node_path5.join)(root, PENV_DIR2, GITIGNORE_FILE);
+  const file = (0, import_node_path6.join)(root, PENV_DIR2, GITIGNORE_FILE);
   const relative3 = `${PENV_DIR2}/${GITIGNORE_FILE}`;
   const wanted = renderGitignore(decisions);
   const existing = (0, import_node_fs3.existsSync)(file) ? (0, import_node_fs3.readFileSync)(file, "utf8") : void 0;
   if (existing === wanted) {
     return { target: "gitignore", action: "kept", text: `Kept ${relative3}` };
   }
-  (0, import_node_fs3.mkdirSync)((0, import_node_path5.join)(root, PENV_DIR2), { recursive: true });
+  (0, import_node_fs3.mkdirSync)((0, import_node_path6.join)(root, PENV_DIR2), { recursive: true });
   (0, import_node_fs3.writeFileSync)(file, wanted, "utf8");
   return {
     target: "gitignore",
@@ -2434,20 +2805,20 @@ function scaffold(root, fields, draft, decisions = DEFAULT_DECISIONS) {
   ];
 }
 function runInit(options) {
-  const root = (0, import_node_path5.resolve)(options.cwd);
+  const root = (0, import_node_path6.resolve)(options.cwd);
   const decisions = options.decisions ?? planInit(root).decisions;
   return { root, decisions, steps: scaffold(root, [], false, decisions) };
 }
-function renderInit(result) {
-  const steps = result.steps.map((step) => {
+function renderInit(result2) {
+  const steps = result2.steps.map((step) => {
     const glyph = step.action === "conflicted" ? WARN : CHECK;
     return step.note === void 0 ? { glyph, text: step.text } : { glyph, text: step.text, note: step.note };
   });
   return [
     ...formatSteps(steps),
     "",
-    `Done. Declare your parameters in ${result.decisions.schemaFile}, then \`penv set <key>\`.`,
-    ...result.decisions.environments.length === 0 ? [
+    `Done. Declare your parameters in ${result2.decisions.schemaFile}, then \`penv set <key>\`.`,
+    ...result2.decisions.environments.length === 0 ? [
       `Then declare your environments in ${CONFIG_FILE}: penv leaves the whitelist empty rather than inventing one, and every command needs it.`
     ] : []
   ];
@@ -2486,7 +2857,7 @@ var initCommand = (0, import_citty8.defineCommand)({
   },
   run({ args }) {
     return guard(async () => {
-      const root = (0, import_node_path5.resolve)(process.cwd());
+      const root = (0, import_node_path6.resolve)(process.cwd());
       const environments = environmentsFromFlag(args.env);
       const plan2 = planInit(root, {
         ...args.schema === void 0 ? {} : { schema: args.schema },
@@ -2577,7 +2948,7 @@ function assertDeclared(segment, config) {
   throw new import_core14.UnknownEnvironmentError(segment, config.environments);
 }
 function scopeFromFilename(file, config) {
-  const name = (0, import_node_path6.basename)(file);
+  const name = (0, import_node_path7.basename)(file);
   const segments = name.split(".");
   const start = segments.indexOf(DOTENV_SEGMENT);
   if (start === -1) {
@@ -2661,7 +3032,7 @@ function environmentNamed(file, explicit) {
   if (explicit !== void 0 && explicit.trim().length > 0) {
     return explicit.trim();
   }
-  const segments = (0, import_node_path6.basename)(file).split(".");
+  const segments = (0, import_node_path7.basename)(file).split(".");
   const start = segments.indexOf(DOTENV_SEGMENT);
   if (start === -1) {
     return void 0;
@@ -2692,8 +3063,8 @@ function configInEffect(cwd, environment) {
   return { config: openProject(cwd).config, decisions };
 }
 function importDotenv(options) {
-  const cwd = (0, import_node_path6.resolve)(options.cwd);
-  const file = (0, import_node_path6.isAbsolute)(options.file) ? options.file : (0, import_node_path6.resolve)(cwd, options.file);
+  const cwd = (0, import_node_path7.resolve)(options.cwd);
+  const file = (0, import_node_path7.isAbsolute)(options.file) ? options.file : (0, import_node_path7.resolve)(cwd, options.file);
   if (!(0, import_node_fs4.existsSync)(file)) {
     throw new import_core14.PenvError(
       "IMPORT_FILE_MISSING",
@@ -2752,7 +3123,7 @@ function importDotenv(options) {
   };
 }
 function displayPath2(root, file) {
-  const rel = (0, import_node_path6.relative)(root, file);
+  const rel = (0, import_node_path7.relative)(root, file);
   return rel === "" || rel.startsWith("..") ? file : rel.split("\\").join("/");
 }
 function keptSchemaStep(step, variables) {
@@ -2776,19 +3147,19 @@ function skippedValidationStep(environments) {
     note: `(no environment set \u2014 run \`penv validate --env ${example}\`)`
   };
 }
-function renderImport(result, validation) {
-  const steps = [{ glyph: CHECK, text: `Found ${result.variables} variables` }];
-  if (result.orphanComments > 0) {
-    const plural = result.orphanComments === 1 ? "comment" : "comments";
+function renderImport(result2, validation) {
+  const steps = [{ glyph: CHECK, text: `Found ${result2.variables} variables` }];
+  if (result2.orphanComments > 0) {
+    const plural = result2.orphanComments === 1 ? "comment" : "comments";
     steps.push({
       glyph: WARN,
-      text: `Dropped ${result.orphanComments} orphan ${plural}`,
+      text: `Dropped ${result2.orphanComments} orphan ${plural}`,
       note: "attached to no variable, so nothing to describe"
     });
   }
-  for (const step of result.steps) {
+  for (const step of result2.steps) {
     if (step.target === "schema" && step.action === "kept") {
-      steps.push(keptSchemaStep(step, result.variables));
+      steps.push(keptSchemaStep(step, result2.variables));
       continue;
     }
     const glyph = step.action === "conflicted" ? WARN : CHECK;
@@ -2796,10 +3167,10 @@ function renderImport(result, validation) {
       step.note === void 0 ? { glyph, text: step.text } : { glyph, text: step.text, note: step.note }
     );
   }
-  steps.push({ glyph: CHECK, text: `Created ${displayPath2(result.root, result.backup)}` });
+  steps.push({ glyph: CHECK, text: `Created ${displayPath2(result2.root, result2.backup)}` });
   const lines = formatSteps(steps);
   if (validation === void 0) {
-    lines.push(...formatSteps([skippedValidationStep(result.environments)]));
+    lines.push(...formatSteps([skippedValidationStep(result2.environments)]));
   } else if (validation.ok) {
     lines.push(...formatSteps([{ glyph: CHECK, text: "Validated configuration" }]));
   } else {
@@ -2844,12 +3215,12 @@ var import_core15 = require("@penvhq/core");
 var import_citty10 = require("citty");
 
 // src/keychain.ts
-var import_node_module = require("module");
+var import_node_module2 = require("module");
 var import_meta = {};
 var cached;
 function entryConstructor() {
   if (cached === void 0) {
-    const require2 = (0, import_node_module.createRequire)(import_meta.url);
+    const require2 = (0, import_node_module2.createRequire)(import_meta.url);
     cached = require2("@napi-rs/keyring").Entry;
   }
   return cached;
@@ -2913,19 +3284,19 @@ function runKeyCreate(options) {
     key
   };
 }
-function renderKeyCreate(result) {
-  if (result.source === "keychain") {
+function renderKeyCreate(result2) {
+  if (result2.source === "keychain") {
     return [
-      `A new key for environment ${result.environment}, stored in your OS keychain as \`${result.id}\`.`,
+      `A new key for environment ${result2.environment}, stored in your OS keychain as \`${result2.id}\`.`,
       "",
       "penv kept no copy. Anything sealed under it is unreadable without your keychain, and running",
       "`penv key create` again would replace it \u2014 so it lives in exactly one place, on this machine."
     ];
   }
   return [
-    `A new key for environment ${result.environment}. penv did not store it.`,
+    `A new key for environment ${result2.environment}. penv did not store it.`,
     "",
-    `  ${result.variable}=${result.key}`,
+    `  ${result2.variable}=${result2.key}`,
     "",
     "Export it where penv runs, and put it wherever this environment's secrets already live \u2014",
     "a KMS, your CI's secret store, a password manager. Anything sealed under it is unreadable",
@@ -2997,11 +3368,11 @@ async function runList(options) {
   }
   return { environment, parameters };
 }
-function renderList(result) {
-  if (result.parameters.length === 0) {
-    return [`No parameters in ${PENV_DIR}/ for environment ${result.environment}.`];
+function renderList(result2) {
+  if (result2.parameters.length === 0) {
+    return [`No parameters in ${PENV_DIR}/ for environment ${result2.environment}.`];
   }
-  return columns(result.parameters.map((entry) => [entry.parameter, entry.scope, entry.variable]));
+  return columns(result2.parameters.map((entry) => [entry.parameter, entry.scope, entry.variable]));
 }
 var listCommand = (0, import_citty11.defineCommand)({
   meta: { name: "list", description: "List parameters" },
@@ -3011,11 +3382,11 @@ var listCommand = (0, import_citty11.defineCommand)({
   },
   run({ args }) {
     return guard(async () => {
-      const result = await runList({
+      const result2 = await runList({
         cwd: process.cwd(),
         ...args.env === void 0 ? {} : { environment: args.env }
       });
-      write(args.json === true ? [JSON.stringify(result, null, 2)] : renderList(result));
+      write(args.json === true ? [JSON.stringify(result2, null, 2)] : renderList(result2));
     });
   }
 });
@@ -3127,20 +3498,20 @@ async function runMove(options) {
     schema: { was: (0, import_core17.accessPath)(from).join("."), now: (0, import_core17.accessPath)(to).join(".") }
   };
 }
-function renderMove(result) {
-  const rows = result.files.map((file) => ({
+function renderMove(result2) {
+  const rows = result2.files.map((file) => ({
     glyph: CHECK,
     label: "Moved",
     subject: `${PENV_DIR}/${file.to}`,
     ...file.resealed ? { detail: "re-sealed for its new address" } : {}
   }));
-  if (result.meta !== void 0) {
-    rows.push({ glyph: CHECK, label: "Moved", subject: `${PENV_DIR}/${result.meta}` });
+  if (result2.meta !== void 0) {
+    rows.push({ glyph: CHECK, label: "Moved", subject: `${PENV_DIR}/${result2.meta}` });
   }
   const lines = formatRows(rows);
   lines.push(
     "",
-    `  .penv/env.ts still declares \`${result.schema.was}\`. Rename it to \`${result.schema.now}\`,`,
+    `  .penv/env.ts still declares \`${result2.schema.was}\`. Rename it to \`${result2.schema.now}\`,`,
     "  or `penv validate` will report the value as unused and the declaration as unset."
   );
   return lines;
@@ -3166,9 +3537,86 @@ var mvCommand = (0, import_citty12.defineCommand)({
   }
 });
 
+// src/commands/pull.ts
+var import_citty13 = require("citty");
+async function runPull(options) {
+  const project = openProject(options.cwd);
+  const environment = targetEnvironment(project, options.environment);
+  const source = await sourceProviderFor(project, environment);
+  if (source.type === LOCAL_TREE_TYPE) {
+    return { environment, source: source.type, localSource: true, values: 0, meta: 0, refs: 0 };
+  }
+  const tree = localTree(project);
+  const files = await source.list();
+  let values = 0;
+  for (const file of files) {
+    const value = await source.read(file);
+    if (value === void 0) {
+      continue;
+    }
+    tree.writeSync(file, value);
+    values += 1;
+  }
+  const refs = refsFrom(files);
+  let meta = 0;
+  for (const ref of refs) {
+    const block = await source.readMeta(ref);
+    if (block === void 0) {
+      continue;
+    }
+    tree.writeMetaSync(ref, block);
+    meta += 1;
+  }
+  return { environment, source: source.type, localSource: false, values, meta, refs: refs.length };
+}
+function renderPull(result2) {
+  if (result2.localSource) {
+    return formatRows([
+      {
+        glyph: CHECK,
+        label: "Nothing to pull",
+        subject: `environment ${result2.environment} has no separate source of truth`,
+        detail: "its values live in the local .penv tree already"
+      }
+    ]);
+  }
+  return formatRows([
+    {
+      glyph: CHECK,
+      label: "Pulled",
+      subject: `${result2.values} ${result2.values === 1 ? "value" : "values"}`,
+      detail: `from the ${result2.source} provider for environment ${result2.environment}`
+    },
+    {
+      glyph: CHECK,
+      label: "Parameters",
+      subject: `${result2.refs} ${result2.refs === 1 ? "parameter" : "parameters"}, ${result2.meta} with meta`,
+      detail: "written into the local .penv tree"
+    }
+  ]);
+}
+var pullCommand = (0, import_citty13.defineCommand)({
+  meta: {
+    name: "pull",
+    description: "Materialise the local .penv tree from an environment's source-of-truth provider"
+  },
+  args: {
+    env: { type: "string", description: "The environment to pull" }
+  },
+  run({ args }) {
+    return guard(async () => {
+      const result2 = await runPull({
+        cwd: process.cwd(),
+        ...args.env === void 0 ? {} : { environment: args.env }
+      });
+      write(renderPull(result2));
+    });
+  }
+});
+
 // src/commands/remove.ts
 var import_core18 = require("@penvhq/core");
-var import_citty13 = require("citty");
+var import_citty14 = require("citty");
 async function runRemove(options) {
   const project = openProject(options.cwd);
   const ref = refFromKey(options.key);
@@ -3193,9 +3641,9 @@ async function runRemove(options) {
     considered: files.map((file) => (0, import_core18.formatValueFile)(file))
   };
 }
-function renderRemove(result) {
-  if (result.removed.length === 0) {
-    const first = result.considered[0] ?? result.parameter;
+function renderRemove(result2) {
+  if (result2.removed.length === 0) {
+    const first = result2.considered[0] ?? result2.parameter;
     return formatRows([
       {
         glyph: WARN,
@@ -3205,14 +3653,14 @@ function renderRemove(result) {
       }
     ]);
   }
-  const rows = result.removed.map((location) => ({
+  const rows = result2.removed.map((location) => ({
     glyph: CHECK,
     label: "Removed",
     subject: `${PENV_DIR}/${location}`
   }));
   return formatRows(rows);
 }
-var removeCommand = (0, import_citty13.defineCommand)({
+var removeCommand = (0, import_citty14.defineCommand)({
   meta: { name: "remove", description: "Delete a parameter" },
   args: {
     key: { type: "positional", required: true, description: "The parameter, e.g. redis/password" },
@@ -3238,15 +3686,195 @@ var removeCommand = (0, import_citty13.defineCommand)({
   }
 });
 
+// src/commands/rotate.ts
+var import_core19 = require("@penvhq/core");
+var import_citty15 = require("citty");
+function rotatingFile(ref, environment) {
+  return {
+    namespace: ref.namespace,
+    name: ref.name,
+    scope: { kind: "environment", environment },
+    encrypted: false
+  };
+}
+async function writeRotatedValue(project, provider, ref, environment, value) {
+  if (provider.type === LOCAL_TREE_TYPE) {
+    await sealAwareWrite({
+      project,
+      provider,
+      ref,
+      scope: { kind: "environment", environment },
+      value,
+      environment
+    });
+    return;
+  }
+  await provider.write(rotatingFile(ref, environment), value);
+}
+function requireNewValue(value, phase, key) {
+  if (value === void 0) {
+    throw new import_core19.PenvError(
+      "ROTATION_NO_VALUE",
+      `A ${phase} rotation of ${key} writes a new value, and none was given`,
+      "Pass the new value as the argument \u2014 `penv rotate <key> <value>` \u2014 or pipe it in on stdin."
+    );
+  }
+  return value;
+}
+function requireRetaining(provider, environment) {
+  if (!(0, import_core19.retainsPrevious)(provider)) {
+    throw new import_core19.PenvError(
+      "ROTATION_NOT_RETAINING",
+      `A dual-valid rotation needs the previous value to stay readable during the grace window, and the \`${provider.type}\` provider for environment ${environment} does not retain it`,
+      "Point this environment at a provider that keeps prior versions (its `readPrevious` is what penv reads during the window), or, if a momentary overlap is not required, declare the parameter `atomic-cutover` in its meta and flip it in one step."
+    );
+  }
+  return provider;
+}
+async function runRotate(options) {
+  const project = openProject(options.cwd);
+  const environment = targetEnvironment(project, options.environment);
+  const ref = refFromKey(options.key, project.config);
+  const provider = await sourceProviderFor(project, environment);
+  const nowIso = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const before = await provider.readMeta(ref);
+  const { mechanism } = (0, import_core19.rotationOf)(before, environment);
+  if (mechanism === void 0) {
+    throw new import_core19.PenvError(
+      "ROTATION_NO_MECHANISM",
+      `Parameter ${options.key} declares no rotation mechanism for environment ${environment}, so penv does not know how to rotate it`,
+      'Set `rotationMechanism` in the parameter\'s meta to `"dual-valid"` (a grace-window overlap) or `"atomic-cutover"` (a single flip), then run `penv rotate` again.'
+    );
+  }
+  const begin = options.begin === true;
+  const complete = options.complete === true;
+  if (mechanism === "atomic-cutover") {
+    if (begin || complete) {
+      throw new import_core19.PenvError(
+        "ROTATION_MECHANISM_MISMATCH",
+        `Parameter ${options.key} is atomic-cutover, which flips in one step, so \`--begin\`/\`--complete\` do not apply`,
+        "Run `penv rotate <key> <value>` with no phase flag to flip it. `--begin`/`--complete` bracket a dual-valid grace window, which atomic-cutover has none of."
+      );
+    }
+    const value = requireNewValue(options.value, "cutover", options.key);
+    await writeRotatedValue(project, provider, ref, environment, value);
+    const after2 = (0, import_core19.completeRotation)(before, environment, nowIso);
+    await provider.writeMeta(ref, after2);
+    return result(ref, environment, mechanism, "cutover", provider.type, true, after2);
+  }
+  const retaining = requireRetaining(provider, environment);
+  if (begin === complete) {
+    throw new import_core19.PenvError(
+      "ROTATION_PHASE_REQUIRED",
+      `A dual-valid rotation of ${options.key} needs exactly one of \`--begin\` or \`--complete\``,
+      "`--begin` writes the new value and opens the grace window; `--complete` closes it once every reader has moved to the new value. Run them in that order, one at a time."
+    );
+  }
+  if (begin) {
+    const value = requireNewValue(options.value, "begin", options.key);
+    await writeRotatedValue(project, retaining, ref, environment, value);
+    const after2 = (0, import_core19.beginRotation)(before, environment, nowIso);
+    await retaining.writeMeta(ref, after2);
+    return result(ref, environment, mechanism, "begin", retaining.type, true, after2);
+  }
+  const after = (0, import_core19.completeRotation)(before, environment, nowIso);
+  await retaining.writeMeta(ref, after);
+  return result(ref, environment, mechanism, "complete", retaining.type, false, after);
+}
+function result(ref, environment, mechanism, phase, source, wroteValue, after) {
+  const { state, rotatingSince, lastRotated } = (0, import_core19.rotationOf)(after, environment);
+  return {
+    parameter: [...ref.namespace, ref.name].join("/"),
+    environment,
+    mechanism,
+    phase,
+    source,
+    wroteValue,
+    state,
+    rotatingSince,
+    lastRotated
+  };
+}
+function renderRotate(result2) {
+  if (result2.phase === "begin") {
+    return formatRows([
+      {
+        glyph: CHECK,
+        label: "Rotating",
+        subject: result2.parameter,
+        detail: `dual-valid window open for environment ${result2.environment} (since ${result2.rotatingSince})`
+      },
+      {
+        glyph: CHECK,
+        label: "Previous",
+        subject: "still readable",
+        detail: `on the ${result2.source} provider until \`penv rotate ${result2.parameter} --complete\``
+      }
+    ]);
+  }
+  if (result2.phase === "complete") {
+    return formatRows([
+      {
+        glyph: CHECK,
+        label: "Rotated",
+        subject: result2.parameter,
+        detail: `dual-valid window closed for environment ${result2.environment} (completed ${result2.lastRotated})`
+      }
+    ]);
+  }
+  return formatRows([
+    {
+      glyph: CHECK,
+      label: "Rotated",
+      subject: result2.parameter,
+      detail: `atomic-cutover flip for environment ${result2.environment} (completed ${result2.lastRotated})`
+    }
+  ]);
+}
+var rotateCommand = (0, import_citty15.defineCommand)({
+  meta: {
+    name: "rotate",
+    description: "Rotate a parameter's value by the mechanism its meta declares"
+  },
+  args: {
+    key: { type: "positional", required: true, description: "The parameter, e.g. redis/password" },
+    value: {
+      type: "positional",
+      required: false,
+      description: "The new value; read from stdin if omitted. Not needed with --complete"
+    },
+    env: { type: "string", description: "The environment to rotate in" },
+    begin: { type: "boolean", description: "Open a dual-valid grace window with the new value" },
+    complete: { type: "boolean", description: "Close a dual-valid grace window" }
+  },
+  run({ args }) {
+    return guard(async () => {
+      const value = args.complete === true ? void 0 : args.value ?? await readStdin();
+      write(
+        renderRotate(
+          await runRotate({
+            cwd: process.cwd(),
+            key: args.key,
+            ...value === void 0 ? {} : { value },
+            ...args.env === void 0 ? {} : { environment: args.env },
+            ...args.begin === void 0 ? {} : { begin: args.begin },
+            ...args.complete === void 0 ? {} : { complete: args.complete }
+          })
+        )
+      );
+    });
+  }
+});
+
 // src/commands/watch.ts
 var import_node_fs5 = require("fs");
-var import_node_path7 = require("path");
-var import_core19 = require("@penvhq/core");
-var import_citty14 = require("citty");
+var import_node_path8 = require("path");
+var import_core20 = require("@penvhq/core");
+var import_citty16 = require("citty");
 var DEBOUNCE_MS = 100;
 function runWatch(options) {
   const project = openProject(options.cwd);
-  const configFile = (0, import_node_path7.basename)(project.configFile);
+  const configFile = (0, import_node_path8.basename)(project.configFile);
   const debounceMs = options.debounceMs ?? DEBOUNCE_MS;
   const watchers = /* @__PURE__ */ new Set();
   let timer;
@@ -3263,12 +3891,12 @@ function runWatch(options) {
     }
     running = true;
     try {
-      const result = await runValidate({
+      const result2 = await runValidate({
         cwd: options.cwd,
         ...options.environment === void 0 ? {} : { environment: options.environment }
       });
       if (!closed) {
-        options.onResult?.(result);
+        options.onResult?.(result2);
       }
     } catch (error) {
       if (!closed) {
@@ -3299,8 +3927,8 @@ function runWatch(options) {
     watcher.close();
   }
   function armRecovery(target, recursive, only) {
-    const parent = (0, import_node_path7.dirname)(target);
-    const name = (0, import_node_path7.basename)(target);
+    const parent = (0, import_node_path8.dirname)(target);
+    const name = (0, import_node_path8.basename)(target);
     let recovery;
     try {
       recovery = (0, import_node_fs5.watch)(parent, { recursive: false }, (_event, filename) => {
@@ -3311,7 +3939,7 @@ function runWatch(options) {
           stop(recovery);
           return;
         }
-        if (filename !== null && (0, import_node_path7.basename)(filename) !== name) {
+        if (filename !== null && (0, import_node_path8.basename)(filename) !== name) {
           return;
         }
         if (!(0, import_node_fs5.existsSync)(target)) {
@@ -3346,7 +3974,7 @@ function runWatch(options) {
         schedule();
         return;
       }
-      if (only !== void 0 && (filename === null || (0, import_node_path7.basename)(filename) !== only)) {
+      if (only !== void 0 && (filename === null || (0, import_node_path8.basename)(filename) !== only)) {
         return;
       }
       schedule();
@@ -3373,10 +4001,10 @@ function runWatch(options) {
     watchers.add(watcher);
   }
   addWatcher(project.penvDir, true);
-  addWatcher((0, import_node_path7.dirname)(project.configFile), false, configFile);
-  if ((0, import_core19.schemaInsideTree)(project.config) === void 0) {
-    const schemaFile = (0, import_node_path7.resolve)(project.root, (0, import_core19.schemaFileOf)(project.config));
-    addWatcher((0, import_node_path7.dirname)(schemaFile), false, (0, import_node_path7.basename)(schemaFile));
+  addWatcher((0, import_node_path8.dirname)(project.configFile), false, configFile);
+  if ((0, import_core20.schemaInsideTree)(project.config) === void 0) {
+    const schemaFile = (0, import_node_path8.resolve)(project.root, (0, import_core20.schemaFileOf)(project.config));
+    addWatcher((0, import_node_path8.dirname)(schemaFile), false, (0, import_node_path8.basename)(schemaFile));
   }
   void validate();
   return {
@@ -3392,8 +4020,8 @@ function runWatch(options) {
     }
   };
 }
-function renderWatch(result) {
-  return ["", ...renderValidate(result), ...renderDrift(result.drift, result.environment)];
+function renderWatch(result2) {
+  return ["", ...renderValidate(result2), ...renderDrift(result2.drift, result2.environment)];
 }
 function renderDrift(drift, environment) {
   const rows = [
@@ -3419,7 +4047,7 @@ function renderDrift(drift, environment) {
   }
   return lines;
 }
-var watchCommand = (0, import_citty14.defineCommand)({
+var watchCommand = (0, import_citty16.defineCommand)({
   meta: {
     name: "watch",
     description: "Re-validate whenever .penv/ or penv.config.ts changes"
@@ -3432,8 +4060,8 @@ var watchCommand = (0, import_citty14.defineCommand)({
       const handle = runWatch({
         cwd: process.cwd(),
         ...args.env === void 0 ? {} : { environment: args.env },
-        onResult: (result) => {
-          write(renderWatch(result));
+        onResult: (result2) => {
+          write(renderWatch(result2));
         },
         // A failing cycle is reported and watching continues. `reportError`
         // marks the process failed, which `validate` wants and a loop does not:
@@ -3447,10 +4075,10 @@ var watchCommand = (0, import_citty14.defineCommand)({
         }
       });
       write(["Watching .penv/ and penv.config.ts. Ctrl-C to stop."]);
-      await new Promise((resolve6) => {
+      await new Promise((resolve7) => {
         process.once("SIGINT", () => {
           handle.close();
-          resolve6();
+          resolve7();
         });
       });
     });
@@ -3458,7 +4086,7 @@ var watchCommand = (0, import_citty14.defineCommand)({
 });
 
 // src/index.ts
-var main = (0, import_citty15.defineCommand)({
+var main = (0, import_citty17.defineCommand)({
   meta: {
     name: "penv",
     description: "Configuration that shares a data model with your production secret manager"
@@ -3470,7 +4098,9 @@ var main = (0, import_citty15.defineCommand)({
     get: getCommand,
     set: setCommand,
     mv: mvCommand,
+    pull: pullCommand,
     push: pushCommand,
+    rotate: rotateCommand,
     remove: removeCommand,
     list: listCommand,
     encrypt: encryptCommand,
@@ -3482,8 +4112,8 @@ var main = (0, import_citty15.defineCommand)({
   }
 });
 function runMain() {
-  (0, import_core20.setKeychain)(defaultKeychain);
-  return (0, import_citty15.runMain)(main);
+  (0, import_core21.setKeychain)(defaultKeychain);
+  return (0, import_citty17.runMain)(main);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -3494,7 +4124,9 @@ function runMain() {
   main,
   renderDoctor,
   renderMove,
+  renderPull,
   renderPush,
+  renderRotate,
   renderWatch,
   runDecrypt,
   runDoctor,
@@ -3506,8 +4138,10 @@ function runMain() {
   runList,
   runMain,
   runMove,
+  runPull,
   runPush,
   runRemove,
+  runRotate,
   runSet,
   runValidate,
   runWatch