@penvhq/cli 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,22 +1,28 @@
 // src/index.ts
 import { setKeychain } from "@penvhq/core";
-import { runMain as cittyRunMain, defineCommand as defineCommand15 } from "citty";
+import { runMain as cittyRunMain, defineCommand as defineCommand17 } from "citty";
 
 // src/commands/doctor.ts
 import {
   accessPath as accessPath3,
+  assertNever,
   effectiveMeta,
+  formatValueFile as formatValueFile2,
   isPublicVariable,
   isRequired,
   isSecret,
+  isStuck,
+  openValue as openValue2,
   resolveAll as resolveAll2,
+  rotationOf,
+  tryParseDuration,
   variableName as variableName3
 } from "@penvhq/core";
 import { createGithubSink as createGithubSink2 } from "@penvhq/sink-github";
 import { defineCommand as defineCommand3 } from "citty";
 
 // src/project.ts
-import { dirname, resolve } from "path";
+import { dirname as dirname2, resolve as resolve2 } from "path";
 import {
   candidatesFor,
   formatValueFile,
@@ -32,12 +38,30 @@ import {
 import { FilesystemProvider } from "@penvhq/provider-filesystem";
 
 // src/registry.ts
+import { createRequire } from "module";
+import { dirname, resolve } from "path";
+import { pathToFileURL } from "url";
 import { PenvError } from "@penvhq/core";
 import { createFilesystemProvider } from "@penvhq/provider-filesystem";
+import { createMockProvider } from "@penvhq/provider-mock";
+import { createVaultProvider } from "@penvhq/provider-vault";
+var PLUGIN_FACTORY_EXPORT = "penvProviderFactory";
 var LOCAL_TREE_TYPE = "filesystem";
 var REGISTRY = /* @__PURE__ */ new Map([
-  [LOCAL_TREE_TYPE, ({ root, config }) => createFilesystemProvider({ root, config })]
+  [LOCAL_TREE_TYPE, ({ root, config }) => createFilesystemProvider({ root, config })],
+  ["vault", ({ providerConfig }) => createVaultProvider({ path: providerConfig?.path ?? "penv" })],
+  ["mock", ({ root }) => createMockProvider({ storePath: 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);
 }
@@ -48,20 +72,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 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 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 unknownProvider(type, environment) {
+function pluginSpecifier(providerConfig, type) {
+  return providerConfig?.module ?? `@penvhq/provider-${type}`;
+}
+function resolutionBase(context) {
+  return dirname(context.root);
+}
+function resolvePlugin(specifier, fromDir) {
+  try {
+    const require2 = createRequire(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(pathToFileURL(resolvedPath).href);
+  pluginModuleCache.set(resolvedPath, loading);
+  return loading;
+}
+function assertSatisfiesContract(provider, specifier) {
+  for (const method of CONTRACT_METHODS) {
+    if (typeof provider[method] !== "function") {
+      throw new 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 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
   );
 }
 
@@ -69,9 +167,9 @@ function unknownProvider(type, environment) {
 var PENV_DIR = ".penv";
 function openProject(cwd) {
   const { config, file } = loadConfig(cwd);
-  const root = dirname(file);
-  const penvDir = resolve(root, PENV_DIR);
-  assertProvidersRegistered(config);
+  const root = dirname2(file);
+  const penvDir = resolve2(root, PENV_DIR);
+  assertProvidersRegistered(config, root);
   return {
     root,
     configFile: file,
@@ -90,6 +188,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 resolveEnvironment(project.config, explicit);
 }
@@ -471,36 +581,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"
     });
   }
@@ -520,19 +630,19 @@ var pushCommand = 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
 import { resolve as resolvePath } from "path";
-import { pathToFileURL } from "url";
+import { pathToFileURL as pathToFileURL2 } from "url";
 import {
   accessPath as accessPath2,
   checkNameCollisions as checkNameCollisions2,
@@ -610,16 +720,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 = schemaFileOf(project.config);
-  const file = pathToFileURL(resolvePath(project.root, schemaPath)).href;
+  const file = pathToFileURL2(resolvePath(project.root, schemaPath)).href;
   return exclusively(() => loadSchemaExclusively(file, schemaPath, environment));
 }
 async function loadSchemaExclusively(file, schemaPath, environment) {
@@ -721,9 +831,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;
@@ -739,24 +849,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}`);
@@ -774,12 +884,12 @@ var validateCommand = defineCommand2({
   },
   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;
       }
     });
@@ -787,6 +897,7 @@ var validateCommand = defineCommand2({
 });
 
 // src/commands/doctor.ts
+var STUCK_THRESHOLD_MS = 864e5;
 function skipped(check, label) {
   return {
     check,
@@ -800,6 +911,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" });
@@ -848,6 +961,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",
@@ -1265,6 +1386,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 } = rotationOf(meta, environment);
+    if (policy === void 0 || lastRotated === null) {
+      continue;
+    }
+    const interval = 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 (!isStuck(meta, environment, now, stuckThresholdMs)) {
+      continue;
+    }
+    const { rotatingSince } = 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 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 = openValue2(here.file, here.stored, keys);
+      if (opened.kind !== "plaintext") {
+        findings.push({
+          check: "provider-value-drift",
+          severity: "unknown",
+          label: "Provider value unreadable",
+          subject: formatValueFile2(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: formatValueFile2(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: formatValueFile2(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,
@@ -1307,9 +1668,9 @@ var doctorCommand = defineCommand3({
 
 // src/commands/encrypt.ts
 import {
-  formatValueFile as formatValueFile3,
+  formatValueFile as formatValueFile4,
   isSecret as isSecret3,
-  openValue as openValue2,
+  openValue as openValue3,
   PenvError as PenvError7,
   parameterId as parameterId4,
   sealValue as sealValue2
@@ -1317,7 +1678,7 @@ import {
 import { defineCommand as defineCommand5 } from "citty";
 
 // src/commands/set.ts
-import { formatValueFile as formatValueFile2, isSecret as isSecret2, PenvError as PenvError6, parameterId as parameterId3, sealValue } from "@penvhq/core";
+import { formatValueFile as formatValueFile3, isSecret as isSecret2, PenvError as PenvError6, parameterId as parameterId3, sealValue } from "@penvhq/core";
 import { defineCommand as defineCommand4 } from "citty";
 function scopeFrom(options) {
   if (options.local === true) {
@@ -1352,38 +1713,50 @@ function sealFor(project, file, value, parameter, environment) {
   if (environment === void 0) {
     throw new PenvError6(
       "SECRET_SCOPE_AMBIGUOUS",
-      `Parameter ${parameter} is a secret, and ${PENV_DIR}/${formatValueFile2(file)} names no environment`,
+      `Parameter ${parameter} is a secret, and ${PENV_DIR}/${formatValueFile3(file)} names no environment`,
       "Keys are declared per environment in the `keys` block of penv.config.ts, so penv cannot tell which key should seal a file that every environment reads. Write it at an environment scope \u2014 add `--env <environment>` \u2014 or drop `secret` from the parameter's meta."
     );
   }
   return 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 = isSecret2(await project.provider.readMeta(ref), environment);
+async function sealAwareWrite(options) {
+  const { project, provider, ref, scope, value, environment } = options;
+  const secret = isSecret2(await provider.readMeta(ref), environment);
   const file = {
     namespace: ref.namespace,
     name: ref.name,
     scope,
     encrypted: secret
   };
-  const stored = secret ? sealFor(project, file, options.value, parameterId3(ref), environment) : options.value;
-  await project.provider.write(file, stored);
-  await project.provider.remove({ ...file, encrypted: !secret });
-  return { parameter: options.key, location: formatValueFile2(file), encrypted: secret };
+  const stored = secret ? sealFor(project, file, value, parameterId3(ref), environment) : value;
+  await provider.write(file, stored);
+  await provider.remove({ ...file, encrypted: !secret });
+  return { encrypted: secret, location: formatValueFile3(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" } : {}
     }
   ]);
 }
@@ -1460,7 +1833,7 @@ async function runEncrypt(options) {
     const already = await readOne(project, sealed);
     throw new PenvError7(
       "PARAMETER_ABSENT",
-      already === void 0 ? `Parameter ${parameter} has no value file at ${PENV_DIR}/${formatValueFile3(plain)}` : `Parameter ${parameter} is already encrypted at ${PENV_DIR}/${formatValueFile3(sealed)}`,
+      already === void 0 ? `Parameter ${parameter} has no value file at ${PENV_DIR}/${formatValueFile4(plain)}` : `Parameter ${parameter} is already encrypted at ${PENV_DIR}/${formatValueFile4(sealed)}`,
       already === void 0 ? `Write it first with \`penv set ${options.key} --env ${environment}\`, which seals it automatically when the parameter's meta declares it a secret.` : "Nothing to do."
     );
   }
@@ -1469,8 +1842,8 @@ async function runEncrypt(options) {
   await project.provider.remove(plain);
   return {
     parameter,
-    location: formatValueFile3(sealed),
-    removed: formatValueFile3(plain)
+    location: formatValueFile4(sealed),
+    removed: formatValueFile4(plain)
   };
 }
 async function runDecrypt(options) {
@@ -1489,16 +1862,16 @@ async function runDecrypt(options) {
   if (stored === void 0) {
     throw new PenvError7(
       "PARAMETER_ABSENT",
-      `Parameter ${parameter} has no encrypted value file at ${PENV_DIR}/${formatValueFile3(sealed)}`,
+      `Parameter ${parameter} has no encrypted value file at ${PENV_DIR}/${formatValueFile4(sealed)}`,
       `Nothing to decrypt. \`penv get ${options.key} --env ${environment} --explain\` shows every file penv looked at.`
     );
   }
-  const opened = openValue2(sealed, stored, keySourceFor(project, environment));
+  const opened = openValue3(sealed, stored, keySourceFor(project, environment));
   if (opened.kind === "failed") {
     throw new UndecryptableAt(
       parameter,
       environment,
-      formatValueFile3(sealed),
+      formatValueFile4(sealed),
       opened.failure.detail
     );
   }
@@ -1506,8 +1879,8 @@ async function runDecrypt(options) {
   await project.provider.remove(sealed);
   return {
     parameter,
-    location: formatValueFile3(plain),
-    removed: formatValueFile3(sealed)
+    location: formatValueFile4(plain),
+    removed: formatValueFile4(sealed)
   };
 }
 var UndecryptableAt = class extends PenvError7 {
@@ -1519,13 +1892,13 @@ var UndecryptableAt = class extends PenvError7 {
     );
   }
 };
-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`
     }
   ]);
 }
@@ -1548,8 +1921,8 @@ var encryptCommand = defineCommand5({
   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"));
     });
   }
 });
@@ -1558,15 +1931,15 @@ var decryptCommand = defineCommand5({
   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
 import { writeFileSync } from "fs";
-import { isAbsolute, relative, resolve as resolve2 } from "path";
+import { isAbsolute, relative, resolve as resolve3 } from "path";
 import {
   checkNameCollisions as checkNameCollisions3,
   effectiveMeta as effectiveMeta2,
@@ -1625,7 +1998,7 @@ 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 ? resolve2(project.root, DEFAULT_OUTPUT) : isAbsolute(options.out) ? options.out : resolve2(options.cwd, options.out);
+  const file = options.out === void 0 ? resolve3(project.root, DEFAULT_OUTPUT) : isAbsolute(options.out) ? options.out : resolve3(options.cwd, options.out);
   writeFileSync(file, serializeDotenv(entries), "utf8");
   return { file, environment, entries: entries.length, decrypted };
 }
@@ -1633,20 +2006,20 @@ function displayPath(cwd, file) {
   const rel = 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"
     });
   }
@@ -1665,13 +2038,13 @@ var generateCommand = defineCommand6({
   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));
     });
   }
 });
@@ -1762,10 +2135,10 @@ var getCommand = defineCommand7({
 
 // src/commands/import.ts
 import { copyFileSync, existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
-import { basename, isAbsolute as isAbsolute2, relative as relative2, resolve as resolve4 } from "path";
+import { basename, isAbsolute as isAbsolute2, relative as relative2, resolve as resolve5 } from "path";
 import {
   accessPath as accessPath4,
-  assertNever,
+  assertNever as assertNever2,
   checkNameCollisions as checkNameCollisions4,
   FilenameGrammarError,
   findConfigFile,
@@ -1886,7 +2259,7 @@ function hasImportsBlock(cwd) {
 
 // src/commands/init.ts
 import { existsSync as existsSync2, mkdirSync, readdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname2, join as join2, resolve as resolve3 } from "path";
+import { dirname as dirname3, join as join2, resolve as resolve4 } from "path";
 import { createInterface } from "readline/promises";
 import {
   DEFAULT_SCHEMA_FILE as DEFAULT_SCHEMA_FILE2,
@@ -2356,7 +2729,7 @@ function renderTsconfig(target, alias) {
 `;
 }
 function ensurePenvDir(root) {
-  const dir = resolve3(root, PENV_DIR2);
+  const dir = resolve4(root, PENV_DIR2);
   if (existsSync2(dir)) {
     return { target: "penv-dir", action: "kept", text: `Found ${PENV_DIR2}/` };
   }
@@ -2373,7 +2746,7 @@ function writeSchemaFile(root, fields, draft, decisions = DEFAULT_DECISIONS) {
       note: "(yours \u2014 penv never regenerates it)"
     };
   }
-  mkdirSync(dirname2(file), { recursive: true });
+  mkdirSync(dirname3(file), { recursive: true });
   writeFileSync2(file, renderSchemaModule(fields, draft), "utf8");
   return {
     target: "schema",
@@ -2461,20 +2834,20 @@ function scaffold(root, fields, draft, decisions = DEFAULT_DECISIONS) {
   ];
 }
 function runInit(options) {
-  const root = resolve3(options.cwd);
+  const root = resolve4(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.`
     ] : []
   ];
@@ -2513,7 +2886,7 @@ var initCommand = defineCommand8({
   },
   run({ args }) {
     return guard(async () => {
-      const root = resolve3(process.cwd());
+      const root = resolve4(process.cwd());
       const environments = environmentsFromFlag(args.env);
       const plan2 = planInit(root, {
         ...args.schema === void 0 ? {} : { schema: args.schema },
@@ -2647,7 +3020,7 @@ function environmentOf(scope) {
     case "local":
       return void 0;
     default:
-      return assertNever(scope, "scope");
+      return assertNever2(scope, "scope");
   }
 }
 function scopeWithEnvironment(scope, environment) {
@@ -2660,7 +3033,7 @@ function scopeWithEnvironment(scope, environment) {
     case "environment-local":
       return scope;
     default:
-      return assertNever(scope, "scope");
+      return assertNever2(scope, "scope");
   }
 }
 function explicitEnvironment(options, source, config) {
@@ -2719,8 +3092,8 @@ function configInEffect(cwd, environment) {
   return { config: openProject(cwd).config, decisions };
 }
 function importDotenv(options) {
-  const cwd = resolve4(options.cwd);
-  const file = isAbsolute2(options.file) ? options.file : resolve4(cwd, options.file);
+  const cwd = resolve5(options.cwd);
+  const file = isAbsolute2(options.file) ? options.file : resolve5(cwd, options.file);
   if (!existsSync3(file)) {
     throw new PenvError11(
       "IMPORT_FILE_MISSING",
@@ -2803,19 +3176,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;
@@ -2823,10 +3196,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 {
@@ -2871,11 +3244,11 @@ import { KEY_BYTES, KEYCHAIN_SERVICE, PenvError as PenvError12 } from "@penvhq/c
 import { defineCommand as defineCommand10 } from "citty";
 
 // src/keychain.ts
-import { createRequire } from "module";
+import { createRequire as createRequire2 } from "module";
 var cached;
 function entryConstructor() {
   if (cached === void 0) {
-    const require2 = createRequire(import.meta.url);
+    const require2 = createRequire2(import.meta.url);
     cached = require2("@napi-rs/keyring").Entry;
   }
   return cached;
@@ -2939,19 +3312,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",
@@ -2988,7 +3361,7 @@ var keyCommand = defineCommand10({
 });
 
 // src/commands/list.ts
-import { assertNever as assertNever2, resolveAll as resolveAll3, variableName as variableName6 } from "@penvhq/core";
+import { assertNever as assertNever3, resolveAll as resolveAll3, variableName as variableName6 } from "@penvhq/core";
 import { defineCommand as defineCommand11 } from "citty";
 function scopeLabel2(scope) {
   switch (scope.kind) {
@@ -3001,7 +3374,7 @@ function scopeLabel2(scope) {
     case "unscoped":
       return "default";
     default:
-      return assertNever2(scope, "scope");
+      return assertNever3(scope, "scope");
   }
 }
 async function runList(options) {
@@ -3023,11 +3396,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 = defineCommand11({
   meta: { name: "list", description: "List parameters" },
@@ -3037,11 +3410,11 @@ var listCommand = defineCommand11({
   },
   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));
     });
   }
 });
@@ -3050,8 +3423,8 @@ var listCommand = defineCommand11({
 import {
   accessPath as accessPath5,
   formatMetaFile,
-  formatValueFile as formatValueFile4,
-  openValue as openValue3,
+  formatValueFile as formatValueFile5,
+  openValue as openValue4,
   PenvError as PenvError13,
   parameterId as parameterId5,
   sealValue as sealValue3
@@ -3073,16 +3446,16 @@ async function planFile(project, source, target, parameter) {
   if (environment === void 0) {
     throw new PenvError13(
       "SECRET_SCOPE_AMBIGUOUS",
-      `${PENV_DIR}/${formatValueFile4(source)} is encrypted at a scope that names no environment, so penv cannot tell which key would re-seal it`,
+      `${PENV_DIR}/${formatValueFile5(source)} is encrypted at a scope that names no environment, so penv cannot tell which key would re-seal it`,
       "Keys are declared per environment in the `keys` block of penv.config.ts. Decrypt it with `penv decrypt`, move the parameter, then encrypt it again at its new address."
     );
   }
   const keys = keySourceFor(project, environment);
-  const opened = openValue3(source, stored, keys);
+  const opened = openValue4(source, stored, keys);
   if (opened.kind === "failed") {
     throw new PenvError13(
       "VALUE_UNDECRYPTABLE",
-      `${PENV_DIR}/${formatValueFile4(source)} could not be decrypted, so penv cannot re-seal it at its new address: ${opened.failure.detail}`,
+      `${PENV_DIR}/${formatValueFile5(source)} could not be decrypted, so penv cannot re-seal it at its new address: ${opened.failure.detail}`,
       "A sealed value is bound to the file it lives in, so moving it means opening it and sealing it again. Make the key available and run this again. Nothing has been moved."
     );
   }
@@ -3150,8 +3523,8 @@ async function runMove(options) {
     from: parameterId5(from),
     to: parameterId5(to),
     files: planned.map((file) => ({
-      from: formatValueFile4(file.source),
-      to: formatValueFile4(file.target),
+      from: formatValueFile5(file.source),
+      to: formatValueFile5(file.target),
       resealed: file.resealed
     })),
     // The meta's path, not the parameter's dotted id: `redis.password` is what
@@ -3161,20 +3534,20 @@ async function runMove(options) {
     schema: { was: accessPath5(from).join("."), now: accessPath5(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;
@@ -3200,9 +3573,86 @@ var mvCommand = defineCommand12({
   }
 });
 
-// src/commands/remove.ts
-import { formatValueFile as formatValueFile5 } from "@penvhq/core";
+// src/commands/pull.ts
 import { defineCommand as defineCommand13 } from "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 = defineCommand13({
+  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
+import { formatValueFile as formatValueFile6 } from "@penvhq/core";
+import { defineCommand as defineCommand14 } from "citty";
 async function runRemove(options) {
   const project = openProject(options.cwd);
   const ref = refFromKey(options.key);
@@ -3219,17 +3669,17 @@ async function runRemove(options) {
       continue;
     }
     await project.provider.remove(file);
-    removed.push(formatValueFile5(file));
+    removed.push(formatValueFile6(file));
   }
   return {
     parameter: options.key,
     removed,
-    considered: files.map((file) => formatValueFile5(file))
+    considered: files.map((file) => formatValueFile6(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,
@@ -3239,14 +3689,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 = defineCommand13({
+var removeCommand = defineCommand14({
   meta: { name: "remove", description: "Delete a parameter" },
   args: {
     key: { type: "positional", required: true, description: "The parameter, e.g. redis/password" },
@@ -3272,11 +3722,197 @@ var removeCommand = defineCommand13({
   }
 });
 
+// src/commands/rotate.ts
+import {
+  beginRotation,
+  completeRotation,
+  PenvError as PenvError14,
+  retainsPrevious,
+  rotationOf as rotationOf2
+} from "@penvhq/core";
+import { defineCommand as defineCommand15 } from "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 PenvError14(
+      "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 (!retainsPrevious(provider)) {
+    throw new PenvError14(
+      "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 } = rotationOf2(before, environment);
+  if (mechanism === void 0) {
+    throw new PenvError14(
+      "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 PenvError14(
+        "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 = 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 PenvError14(
+      "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 = beginRotation(before, environment, nowIso);
+    await retaining.writeMeta(ref, after2);
+    return result(ref, environment, mechanism, "begin", retaining.type, true, after2);
+  }
+  const after = 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 } = rotationOf2(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 = defineCommand15({
+  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
 import { existsSync as existsSync4, watch } from "fs";
-import { basename as basename2, dirname as dirname3, resolve as resolve5 } from "path";
+import { basename as basename2, dirname as dirname4, resolve as resolve6 } from "path";
 import { schemaFileOf as schemaFileOf4, schemaInsideTree as schemaInsideTree2 } from "@penvhq/core";
-import { defineCommand as defineCommand14 } from "citty";
+import { defineCommand as defineCommand16 } from "citty";
 var DEBOUNCE_MS = 100;
 function runWatch(options) {
   const project = openProject(options.cwd);
@@ -3297,12 +3933,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) {
@@ -3333,7 +3969,7 @@ function runWatch(options) {
     watcher.close();
   }
   function armRecovery(target, recursive, only) {
-    const parent = dirname3(target);
+    const parent = dirname4(target);
     const name = basename2(target);
     let recovery;
     try {
@@ -3407,10 +4043,10 @@ function runWatch(options) {
     watchers.add(watcher);
   }
   addWatcher(project.penvDir, true);
-  addWatcher(dirname3(project.configFile), false, configFile);
+  addWatcher(dirname4(project.configFile), false, configFile);
   if (schemaInsideTree2(project.config) === void 0) {
-    const schemaFile = resolve5(project.root, schemaFileOf4(project.config));
-    addWatcher(dirname3(schemaFile), false, basename2(schemaFile));
+    const schemaFile = resolve6(project.root, schemaFileOf4(project.config));
+    addWatcher(dirname4(schemaFile), false, basename2(schemaFile));
   }
   void validate();
   return {
@@ -3426,8 +4062,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 = [
@@ -3453,7 +4089,7 @@ function renderDrift(drift, environment) {
   }
   return lines;
 }
-var watchCommand = defineCommand14({
+var watchCommand = defineCommand16({
   meta: {
     name: "watch",
     description: "Re-validate whenever .penv/ or penv.config.ts changes"
@@ -3466,8 +4102,8 @@ var watchCommand = defineCommand14({
       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:
@@ -3481,10 +4117,10 @@ var watchCommand = defineCommand14({
         }
       });
       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();
         });
       });
     });
@@ -3492,7 +4128,7 @@ var watchCommand = defineCommand14({
 });
 
 // src/index.ts
-var main = defineCommand15({
+var main = defineCommand17({
   meta: {
     name: "penv",
     description: "Configuration that shares a data model with your production secret manager"
@@ -3504,7 +4140,9 @@ var main = defineCommand15({
     get: getCommand,
     set: setCommand,
     mv: mvCommand,
+    pull: pullCommand,
     push: pushCommand,
+    rotate: rotateCommand,
     remove: removeCommand,
     list: listCommand,
     encrypt: encryptCommand,
@@ -3527,7 +4165,9 @@ export {
   main,
   renderDoctor,
   renderMove,
+  renderPull,
   renderPush,
+  renderRotate,
   renderWatch,
   runDecrypt,
   runDoctor,
@@ -3539,8 +4179,10 @@ export {
   runList,
   runMain,
   runMove,
+  runPull,
   runPush,
   runRemove,
+  runRotate,
   runSet,
   runValidate,
   runWatch