@penvhq/cli 0.4.0 → 0.5.0

package/dist/index.js

@@ -8,6 +8,8 @@ import {
   assertNever,
   effectiveMeta,
   formatValueFile as formatValueFile2,
+  holdsProjection as holdsProjection3,
+  holdsRecords,
   isPublicVariable,
   isRequired,
   isSecret,
@@ -18,9 +20,66 @@ import {
   tryParseDuration,
   variableName as variableName3
 } from "@penvhq/core";
-import { createGithubSink as createGithubSink2 } from "@penvhq/sink-github";
 import { defineCommand as defineCommand3 } from "citty";
 
+// src/env-flags.ts
+import { PenvError } from "@penvhq/core";
+var BASE_RESERVED = ["help", "version", "h", "v", "_", "--"];
+var COMMAND_FLAGS = [
+  ...BASE_RESERVED,
+  "env",
+  "out",
+  "allow-decrypt",
+  "destination",
+  "dest",
+  "d",
+  "location",
+  "l",
+  "yes",
+  "y"
+];
+function shadowedEnvironments(config) {
+  const flags = new Set(COMMAND_FLAGS);
+  return config.environments.filter((environment) => flags.has(environment));
+}
+function shorthandCandidates(args, declared) {
+  const reserved = /* @__PURE__ */ new Set([...BASE_RESERVED, ...declared]);
+  return Object.keys(args).filter((key) => !reserved.has(key) && args[key] === true);
+}
+function quoteList(values) {
+  return values.map((value) => `\`--${value}\``).join(", ");
+}
+function environmentFromShorthand(config, candidates, explicit) {
+  if (candidates.length === 0) {
+    return void 0;
+  }
+  const hits = candidates.filter((candidate) => config.environments.includes(candidate));
+  const strangers = candidates.filter((candidate) => !config.environments.includes(candidate));
+  if (strangers.length > 0) {
+    throw new PenvError(
+      "UNKNOWN_FLAG",
+      `${quoteList(strangers)} ${strangers.length === 1 ? "is not a flag" : "are not flags"} this command takes, and ${strangers.length === 1 ? "names" : "name"} no declared environment`,
+      `Declared environments work as bare flags: ${quoteList(config.environments)}. Anything else needs \`--env <name>\`.`
+    );
+  }
+  if (hits.length > 1) {
+    throw new PenvError(
+      "ENVIRONMENT_FLAG_AMBIGUOUS",
+      `${quoteList(hits)} name two environments at once, and a command acts on exactly one`,
+      "Pass a single environment flag, or the canonical `--env <name>`."
+    );
+  }
+  const hit = hits[0];
+  if (hit !== void 0 && explicit !== void 0 && explicit !== hit) {
+    throw new PenvError(
+      "ENVIRONMENT_FLAG_AMBIGUOUS",
+      `\`--env ${explicit}\` and \`--${hit}\` name two environments at once`,
+      "Drop one of them \u2014 `--env` is the canonical spelling."
+    );
+  }
+  return hit;
+}
+
 // src/project.ts
 import { dirname as dirname2, resolve as resolve2 } from "path";
 import {
@@ -30,7 +89,7 @@ import {
   isReservedToken,
   loadConfig,
   openValue,
-  PenvError as PenvError2,
+  PenvError as PenvError3,
   parameterId,
   ReservedTokenError,
   refFromAccessPath,
@@ -43,25 +102,19 @@ import { FilesystemProvider } from "@penvhq/provider-filesystem";
 import { createRequire } from "module";
 import { dirname, resolve } from "path";
 import { pathToFileURL } from "url";
-import { PenvError } from "@penvhq/core";
+import { holdsProjection, PenvError as PenvError2 } from "@penvhq/core";
 import { createFilesystemProvider } from "@penvhq/provider-filesystem";
-import { createKubernetesProvider } from "@penvhq/provider-kubernetes";
 import { createMockProvider } from "@penvhq/provider-mock";
-import { createSsmProvider } from "@penvhq/provider-ssm";
-import { createVaultProvider } from "@penvhq/provider-vault";
 var PLUGIN_FACTORY_EXPORT = "penvProviderFactory";
-var LOCAL_TREE_TYPE = "filesystem";
+var LOCAL_TREE_TYPE = "@penvhq/provider-filesystem";
 var REGISTRY = /* @__PURE__ */ new Map([
   [LOCAL_TREE_TYPE, ({ root, config }) => createFilesystemProvider({ root, config })],
-  ["vault", ({ providerConfig }) => createVaultProvider({ path: providerConfig?.path ?? "penv" })],
-  ["ssm", ({ providerConfig }) => createSsmProvider({ path: providerConfig?.path ?? "penv" })],
   [
-    "kubernetes",
-    ({ providerConfig }) => createKubernetesProvider(kubernetesOptions(providerConfig))
-  ],
-  ["mock", ({ root }) => createMockProvider({ storePath: resolve(root, ".penv-mock.json") })]
+    "@penvhq/provider-mock",
+    ({ root }) => createMockProvider({ storePath: resolve(root, ".penv-mock.json") })
+  ]
 ]);
-var CONTRACT_METHODS = [
+var RECORD_CONTRACT_METHODS = [
   "read",
   "write",
   "list",
@@ -70,6 +123,7 @@ var CONTRACT_METHODS = [
   "writeMeta",
   "removeMeta"
 ];
+var PROJECTION_CONTRACT_METHODS = ["verify", "push", "list"];
 var pluginModuleCache = /* @__PURE__ */ new Map();
 function isProviderRegistered(type) {
   return REGISTRY.has(type);
@@ -89,31 +143,30 @@ async function createSourceProvider(type, context) {
 }
 async function loadPluginProvider(type, context) {
   const fromDir = resolutionBase(context);
-  const specifier = pluginSpecifier(context.providerConfig, type);
-  const resolved = resolvePlugin(specifier, fromDir);
+  const resolved = resolvePlugin(type, fromDir);
   if (resolved === void 0) {
-    throw unknownProvider(type, context.environment, specifier);
+    throw unknownProvider(type, context.environment);
   }
   let mod;
   try {
     mod = await importPlugin(resolved);
   } catch {
-    throw new PenvError(
+    throw new PenvError2(
       "PROVIDER_PLUGIN_LOAD",
-      `The provider package \`${specifier}\` for type \`${type}\` failed to load`,
+      `The provider package \`${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(
+    throw new PenvError2(
       "PROVIDER_PLUGIN_INVALID",
-      `\`${specifier}\` does not export \`${PLUGIN_FACTORY_EXPORT}\``,
+      `\`${type}\` 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);
+  assertSatisfiesContract(provider, type);
   return provider;
 }
 function assertProvidersRegistered(config, projectRoot) {
@@ -121,15 +174,11 @@ function assertProvidersRegistered(config, projectRoot) {
     if (isProviderRegistered(provider.type)) {
       continue;
     }
-    const specifier = pluginSpecifier(provider, provider.type);
-    if (resolvePlugin(specifier, projectRoot) === void 0) {
-      throw unknownProvider(provider.type, environment, specifier);
+    if (resolvePlugin(provider.type, projectRoot) === void 0) {
+      throw unknownProvider(provider.type, environment);
     }
   }
 }
-function pluginSpecifier(providerConfig, type) {
-  return providerConfig?.module ?? `@penvhq/provider-${type}`;
-}
 function resolutionBase(context) {
   return dirname(context.root);
 }
@@ -151,32 +200,26 @@ function importPlugin(resolvedPath) {
   return loading;
 }
 function assertSatisfiesContract(provider, specifier) {
-  for (const method of CONTRACT_METHODS) {
+  const projection = holdsProjection(provider);
+  const methods = projection ? PROJECTION_CONTRACT_METHODS : RECORD_CONTRACT_METHODS;
+  const contract = projection ? "the @penvhq/core ProjectionProvider contract its declared capabilities select" : "the @penvhq/core Provider contract that the filesystem provider defines";
+  for (const method of methods) {
     if (typeof provider[method] !== "function") {
-      throw new PenvError(
+      throw new PenvError2(
         "PROVIDER_PLUGIN_INVALID",
         `The provider from \`${specifier}\` is missing \`${method}()\``,
-        "It must satisfy the @penvhq/core Provider contract that the filesystem provider defines."
+        `It must satisfy ${contract}.`
       );
     }
   }
 }
-function kubernetesOptions(providerConfig) {
-  const path = providerConfig?.path ?? "penv";
-  const slash = path.indexOf("/");
-  if (slash === -1) return { secretName: path };
-  const namespace = path.slice(0, slash);
-  const secretName = path.slice(slash + 1) || "penv";
-  return namespace === "" ? { secretName } : { namespace, secretName };
-}
-function unknownProvider(type, environment, specifier) {
-  const known = [...REGISTRY.keys()].map((name) => `\`${name}\``).join(", ");
+function unknownProvider(type, environment) {
+  const preinstalled = [...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(
+  return new PenvError2(
     "UNKNOWN_PROVIDER",
-    `The provider type \`${type}\`${where} in penv.config.ts is not one this penv build carries`,
-    remedy
+    `The provider \`${type}\`${where} in penv.config.ts is not installed in this project`,
+    `Install it with \`npm i ${type}\` \u2014 a provider's \`type\` is the package penv imports. The CLI ships ${preinstalled} pre-installed.`
   );
 }
 
@@ -197,7 +240,7 @@ function openProject(cwd) {
 }
 function localTree(project) {
   if (!(project.provider instanceof FilesystemProvider)) {
-    throw new PenvError2(
+    throw new PenvError3(
       "PROVIDER_NOT_LOCAL",
       `This command reads the local .penv tree synchronously, which the \`${project.provider.type}\` provider is not`,
       "Run this against a filesystem-backed project, or use a command that speaks the async provider contract."
@@ -217,8 +260,9 @@ async function sourceProviderFor(project, environment) {
     environment
   });
 }
-function targetEnvironment(project, explicit) {
-  return resolveEnvironment(project.config, explicit);
+function targetEnvironment(project, explicit, shorthand) {
+  const fromFlags = shorthand === void 0 ? void 0 : environmentFromShorthand(project.config, shorthand, explicit);
+  return resolveEnvironment(project.config, explicit ?? fromFlags);
 }
 var KEY_SEPARATOR = /[./\\]/;
 var NO_ENVIRONMENTS = { environments: [], providers: {} };
@@ -226,7 +270,7 @@ function refFromKey(key, config) {
   const segments = key.split(KEY_SEPARATOR).filter((segment) => segment.length > 0);
   const name = segments[segments.length - 1];
   if (name === void 0) {
-    throw new PenvError2(
+    throw new PenvError3(
       "PARAMETER_KEY",
       `\`${key}\` names no parameter`,
       "A key is `<namespace>/<name>` or `<namespace>.<name>`, e.g. `redis/password`."
@@ -245,13 +289,13 @@ function assertWritableKey(key) {
   const ref = refFromAccessPath(segments);
   if (ref !== void 0) {
     const suggestion = [...ref.namespace, ref.name].join("/");
-    throw new PenvError2(
+    throw new PenvError3(
       "PARAMETER_KEY_CASING",
       `\`${key}\` is not a canonical parameter name`,
       `Parameter files are lower-case and hyphenated. Did you mean \`${suggestion}\`? That is the file that backs the \`${key}\` key in your schema.`
     );
   }
-  throw new PenvError2(
+  throw new PenvError3(
     "PARAMETER_KEY_UNREACHABLE",
     `No value file can be named that reaches \`${key}\``,
     "Parameter files are lower-case and hyphenated, and this key maps to no such file \u2014 a run of capitals like `apiURL` cannot be reached (use `api-url`, which the schema reads as `apiUrl`). Run `penv validate` or `penv fill` to see the names penv expects."
@@ -540,7 +584,7 @@ function padVisible(text, width) {
 }
 
 // src/ui.ts
-import { PenvError as PenvError3 } from "@penvhq/core";
+import { PenvError as PenvError4 } from "@penvhq/core";
 var CHECK = "\u2713";
 var WARN = "\u26A0";
 var CROSS = "\u2717";
@@ -614,7 +658,7 @@ function write(lines) {
   }
 }
 function reportError(error) {
-  if (error instanceof PenvError3) {
+  if (error instanceof PenvError4) {
     const suffix = error.remedy === void 0 ? void 0 : `
   ${error.remedy}`;
     const message = suffix !== void 0 && error.message.endsWith(suffix) ? error.message.slice(0, -suffix.length) : error.message;
@@ -648,31 +692,92 @@ async function guard(run) {
 }
 
 // src/commands/push.ts
-import { checkNameCollisions, PenvError as PenvError4, requireValue, variableName as variableName2 } from "@penvhq/core";
-import { checkGithubNames, createGithubSink } from "@penvhq/sink-github";
+import {
+  checkNameCollisions,
+  holdsProjection as holdsProjection2,
+  PenvError as PenvError5,
+  requireValue,
+  variableName as variableName2
+} from "@penvhq/core";
 import { defineCommand } from "citty";
+
+// src/input.ts
+import { createInterface } from "readline";
+function lineReader(input = process.stdin, output = process.stdout) {
+  const rl = createInterface({ input, output });
+  const buffered = [];
+  const waiting = [];
+  let closed = false;
+  rl.on("line", (line) => {
+    const next = waiting.shift();
+    if (next === void 0) {
+      buffered.push(line);
+    } else {
+      next(line);
+    }
+  });
+  rl.on("close", () => {
+    closed = true;
+    for (const next of waiting.splice(0)) {
+      next(void 0);
+    }
+  });
+  return {
+    ask(question) {
+      const early = buffered.shift();
+      if (early !== void 0) {
+        return Promise.resolve(early);
+      }
+      if (closed) {
+        return Promise.resolve(void 0);
+      }
+      rl.setPrompt(question);
+      rl.prompt();
+      return new Promise((resolve7) => {
+        waiting.push(resolve7);
+      });
+    },
+    close() {
+      rl.close();
+    }
+  };
+}
+
+// src/commands/push.ts
 var LAST_PUSHED_KEY = "lastPushedAt";
-function sinkFor(project, environment, override) {
-  const declared = project.config.sinks?.[environment];
-  if (declared === void 0) {
-    throw new PenvError4(
-      "NO_SINK",
-      `Environment ${environment} declares no sink in penv.config.ts, so penv has nowhere to push`,
-      `Add a \`sinks\` entry, e.g. \`sinks: { ${environment}: { type: "github" } }\`, then run \`penv push --env ${environment}\` again.`
+async function destinationFor(project, environment, options) {
+  if (options.destination !== void 0) {
+    const providerConfig = {
+      type: options.destination,
+      ...options.location === void 0 ? {} : { location: options.location }
+    };
+    const provider2 = options.provider ?? await createSourceProvider(options.destination, {
+      root: project.penvDir,
+      config: project.config,
+      providerConfig,
+      environment
+    });
+    return { provider: provider2, location: options.location };
+  }
+  const declared = project.config.providers[environment];
+  const location = declared?.location;
+  if (declared === void 0 || declared.type === LOCAL_TREE_TYPE) {
+    throw new PenvError5(
+      "NO_DESTINATION",
+      `Environment ${environment}'s provider is the local .penv tree itself, so penv has nowhere to push`,
+      `Declare a provider for it in penv.config.ts \u2014 e.g. \`${environment}: { type: "@penvhq/provider-github", location: "owner/repo" }\` \u2014 or push somewhere once with \`penv push --env ${environment} --destination <package> --location <place>\`.`
     );
   }
-  const repo = declared.repo;
-  if (override !== void 0) {
-    return { sink: override, repo };
-  }
-  if (declared.type === "github") {
-    return { sink: createGithubSink(repo === void 0 ? {} : { repo }), repo };
+  if (options.provider !== void 0) {
+    return { provider: options.provider, location };
   }
-  throw new PenvError4(
-    "UNKNOWN_SINK",
-    `Environment ${environment} declares sink type \`${declared.type}\`, which penv does not know`,
-    'The only sink in this release is `github`. Set `type: "github"`.'
-  );
+  const provider = await createSourceProvider(declared.type, {
+    root: project.penvDir,
+    config: project.config,
+    providerConfig: declared,
+    environment
+  });
+  return { provider, location };
 }
 function plan(resolutions, config, environment, allowDecrypt) {
   const outbound = [];
@@ -684,10 +789,10 @@ function plan(resolutions, config, environment, allowDecrypt) {
     let encrypted = false;
     if (winner.file.encrypted) {
       if (!allowDecrypt) {
-        throw new PenvError4(
+        throw new PenvError5(
           "ENCRYPTED_VALUE_REFUSED",
-          `Parameter ${resolution.parameter} for environment ${environment} resolves to the encrypted value file ${PENV_DIR}/${winner.location}, and a push sends plaintext for GitHub to re-seal`,
-          "Re-run with `--allow-decrypt` to decrypt it locally and push it, or push an environment whose values are plaintext. penv's encryption stops at the sink; the destination seals it under its own key."
+          `Parameter ${resolution.parameter} for environment ${environment} resolves to the encrypted value file ${PENV_DIR}/${winner.location}, and a push sends plaintext for the destination to re-seal`,
+          "Re-run with `--allow-decrypt` to decrypt it locally and push it, or push an environment whose values are plaintext. penv's encryption stops at the projection; the destination seals it under its own key."
         );
       }
       requireValue(resolution, environment);
@@ -717,10 +822,46 @@ function recordPush(tree, ref, environment, iso) {
   const meta = withLastPushed(tree.readMetaSync(ref), environment, iso);
   tree.writeMetaSync(ref, meta);
 }
-async function runPush(options) {
-  const project = openProject(options.cwd);
-  const environment = targetEnvironment(project, options.environment);
-  const { sink, repo } = sinkFor(project, environment, options.sink);
+async function terminalConfirm(question) {
+  if (process.stdin.isTTY !== true) {
+    return false;
+  }
+  const reader = lineReader();
+  try {
+    const answer = await reader.ask(`${question} [y/N] `);
+    return answer !== void 0 && /^y(es)?$/i.test(answer.trim());
+  } finally {
+    reader.close();
+  }
+}
+async function ensureTargetApproved(provider, environment, options) {
+  if (provider.targetExists === void 0) {
+    return false;
+  }
+  if (await provider.targetExists(environment)) {
+    return false;
+  }
+  if (provider.ensureTarget === void 0) {
+    throw new PenvError5(
+      "MISSING_TARGET",
+      `The destination has no environment \`${environment}\` to receive this push, and this provider cannot create one`,
+      `Create the environment on the destination side, then run \`penv push --env ${environment}\` again.`
+    );
+  }
+  const approved = options.yes === true || await (options.confirm ?? terminalConfirm)(
+    `The destination has no environment \`${environment}\`. Create it?`
+  );
+  if (!approved) {
+    throw new PenvError5(
+      "MISSING_TARGET",
+      `The destination has no environment \`${environment}\` to receive this push`,
+      `Re-run with \`--yes\` to create it, answer \`y\` at the prompt, or create it on the destination side yourself.`
+    );
+  }
+  await provider.ensureTarget(environment);
+  return true;
+}
+async function pushProjection(project, provider, environment, location, options) {
   const tree = localTree(project);
   const keys = keySourceFor(project, environment);
   const resolutions = resolveAllSync(tree, environment, keys, true);
@@ -729,16 +870,17 @@ async function runPush(options) {
   if (collision !== void 0) {
     throw collision;
   }
-  const nameError = checkGithubNames(refs, project.config)[0];
+  const nameError = provider.checkNames?.(refs, project.config)[0];
   if (nameError !== void 0) {
     throw nameError;
   }
   const outbound = plan(resolutions, project.config, environment, options.allowDecrypt === true);
-  await sink.verify();
+  await provider.verify();
+  const createdTarget = outbound.some((item) => item.scope.kind === "environment") && await ensureTargetApproved(provider, environment, options);
   let repositorySecrets = 0;
   let environmentSecrets = 0;
   for (const item of outbound) {
-    await sink.push(item.variable, item.value, item.scope);
+    await provider.push(item.variable, item.value, item.scope);
     if (item.scope.kind === "repository") {
       repositorySecrets += 1;
     } else {
@@ -748,15 +890,70 @@ async function runPush(options) {
   }
   return {
     environment,
-    repo,
+    destination: provider.type,
+    mode: "projection",
+    location,
     pushed: outbound.length,
+    meta: 0,
     repositorySecrets,
     environmentSecrets,
-    decrypted: outbound.filter((item) => item.encrypted).length
+    decrypted: outbound.filter((item) => item.encrypted).length,
+    createdTarget
+  };
+}
+function crossesToRecords(file, environment) {
+  const scope = file.scope;
+  if (scope.kind === "unscoped") {
+    return true;
+  }
+  return scope.kind === "environment" && scope.environment === environment;
+}
+async function pushRecords(project, provider, environment, location) {
+  const tree = localTree(project);
+  const files = tree.listSync().filter((file) => crossesToRecords(file, environment));
+  let pushed = 0;
+  for (const file of files) {
+    const value = tree.readSync(file);
+    if (value === void 0) {
+      continue;
+    }
+    await provider.write(file, value);
+    pushed += 1;
+  }
+  const refs = refsFrom(files);
+  let meta = 0;
+  for (const ref of refs) {
+    const block = tree.readMetaSync(ref);
+    if (block === void 0) {
+      continue;
+    }
+    await provider.writeMeta(ref, block);
+    meta += 1;
+  }
+  return {
+    environment,
+    destination: provider.type,
+    mode: "records",
+    location,
+    pushed,
+    meta,
+    repositorySecrets: 0,
+    environmentSecrets: 0,
+    decrypted: 0,
+    createdTarget: false
   };
 }
+async function runPush(options) {
+  const project = openProject(options.cwd);
+  const environment = targetEnvironment(project, options.environment, options.envFlags);
+  const { provider, location } = await destinationFor(project, environment, options);
+  if (holdsProjection2(provider)) {
+    return pushProjection(project, provider, environment, location, options);
+  }
+  return pushRecords(project, provider, environment, location);
+}
 function renderPush(result2) {
-  if (result2.pushed === 0) {
+  if (result2.pushed === 0 && result2.meta === 0) {
     return formatRows([
       {
         glyph: CHECK,
@@ -765,7 +962,23 @@ function renderPush(result2) {
       }
     ]);
   }
-  const target = `GitHub Actions for environment ${result2.environment}${result2.repo === void 0 ? "" : ` (${result2.repo})`}`;
+  const target = `${result2.destination} for environment ${result2.environment}${result2.location === void 0 ? "" : ` (${result2.location})`}`;
+  if (result2.mode === "records") {
+    return formatRows([
+      {
+        glyph: CHECK,
+        label: "Pushed",
+        subject: `${result2.pushed} value ${result2.pushed === 1 ? "file" : "files"}, ${result2.meta} meta`,
+        detail: `mirrored verbatim to ${target}`
+      },
+      {
+        glyph: CHECK,
+        label: "Sealed values",
+        subject: "crossed byte-for-byte, still sealed",
+        detail: "the destination holds envelopes; no key was needed to push them"
+      }
+    ]);
+  }
   const rows = [
     {
       glyph: CHECK,
@@ -780,12 +993,20 @@ function renderPush(result2) {
       detail: "environment secrets override repository secrets, as penv's env scope overrides the default"
     }
   ];
+  if (result2.createdTarget) {
+    rows.push({
+      glyph: CHECK,
+      label: "Created",
+      subject: `the destination environment ${result2.environment}`,
+      detail: "it did not exist yet; created on your approval"
+    });
+  }
   if (result2.decrypted > 0) {
     rows.push({
       glyph: WARN,
       label: "Decrypted",
       subject: `${result2.decrypted} ${result2.decrypted === 1 ? "secret" : "secrets"}`,
-      detail: "sent as plaintext for GitHub to re-seal under its own key"
+      detail: "sent as plaintext for the destination to re-seal under its own key"
     });
   }
   return formatRows(rows);
@@ -793,13 +1014,28 @@ function renderPush(result2) {
 var pushCommand = defineCommand({
   meta: {
     name: "push",
-    description: "Push an environment's resolved values to its sink (GitHub Actions Secrets)"
+    description: "Push an environment's values to its provider"
   },
   args: {
     env: { type: "string", description: "The environment to push" },
     "allow-decrypt": {
       type: "boolean",
-      description: "Decrypt sealed values locally and push them as plaintext for GitHub to re-seal"
+      description: "Decrypt sealed values locally and push them as plaintext for the destination to re-seal"
+    },
+    destination: {
+      type: "string",
+      alias: ["dest", "d"],
+      description: "Push once to this provider package instead of the declared one"
+    },
+    location: {
+      type: "string",
+      alias: "l",
+      description: "The destination-side place, when --destination needs one"
+    },
+    yes: {
+      type: "boolean",
+      alias: "y",
+      description: "Create a missing destination-side environment without prompting"
     }
   },
   run({ args }) {
@@ -807,7 +1043,22 @@ var pushCommand = defineCommand({
       const result2 = await runPush({
         cwd: process.cwd(),
         ...args.env === void 0 ? {} : { environment: args.env },
-        ...args["allow-decrypt"] === void 0 ? {} : { allowDecrypt: args["allow-decrypt"] }
+        ...args["allow-decrypt"] === void 0 ? {} : { allowDecrypt: args["allow-decrypt"] },
+        ...args.destination === void 0 ? {} : { destination: args.destination },
+        ...args.location === void 0 ? {} : { location: args.location },
+        ...args.yes === void 0 ? {} : { yes: args.yes },
+        envFlags: shorthandCandidates(args, [
+          "env",
+          "allow-decrypt",
+          "allowDecrypt",
+          "destination",
+          "dest",
+          "d",
+          "location",
+          "l",
+          "yes",
+          "y"
+        ])
       });
       write(renderPush(result2));
     });
@@ -822,7 +1073,7 @@ import {
   checkNameCollisions as checkNameCollisions2,
   jitiFor,
   NameCollisionError,
-  PenvError as PenvError5,
+  PenvError as PenvError6,
   ReservedTokenError as ReservedTokenError2,
   resolveAll,
   SCHEMA_HARVEST_ENV,
@@ -961,14 +1212,14 @@ async function loadSchemaExclusively(file, schemaPath, environment) {
 }
 async function runValidate(options) {
   const project = openProject(options.cwd);
-  const environment = targetEnvironment(project, options.environment);
+  const environment = targetEnvironment(project, options.environment, options.envFlags);
   const schemaPath = schemaFileOf(project.config);
   const issues = [];
   let files;
   try {
     files = await project.provider.list();
   } catch (error) {
-    if (!(error instanceof PenvError5)) {
+    if (!(error instanceof PenvError6)) {
       throw error;
     }
     return {
@@ -1076,7 +1327,8 @@ var validateCommand = defineCommand2({
     return guard(async () => {
       const result2 = await runValidate({
         cwd: process.cwd(),
-        ...args.env === void 0 ? {} : { environment: args.env }
+        ...args.env === void 0 ? {} : { environment: args.env },
+        envFlags: shorthandCandidates(args, ["env"])
       });
       write(renderValidate(result2));
       if (!result2.ok) {
@@ -1099,10 +1351,19 @@ function skipped(check, label) {
 }
 async function runDoctor(options) {
   const project = openProject(options.cwd);
-  const environment = targetEnvironment(project, options.environment);
+  const environment = targetEnvironment(project, options.environment, options.envFlags);
   const findings = [];
   const now = new Date(options.now ?? (/* @__PURE__ */ new Date()).toISOString());
   const stuckThresholdMs = options.stuckThresholdMs ?? STUCK_THRESHOLD_MS;
+  for (const shadowed of shadowedEnvironments(project.config)) {
+    findings.push({
+      check: "environment-flag-shadow",
+      severity: "warning",
+      label: "Environment shadows a flag",
+      subject: shadowed,
+      detail: `\`--${shadowed}\` is a flag penv defines, so this environment has no shorthand \u2014 \`--env ${shadowed}\` always works`
+    });
+  }
   const { schema, issues } = await loadSchema(project, environment);
   if (schema !== void 0) {
     findings.push({ check: "schema", severity: "pass", label: "Schema valid" });
@@ -1159,7 +1420,7 @@ async function runDoctor(options) {
     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(...await projectionFindings(project, environment, options.projection));
   findings.push({
     check: "provider",
     severity: "pass",
@@ -1395,15 +1656,6 @@ function encryptionFindings(subjects, environment) {
   ];
 }
 var EDIT_SKEW_MS = 12e4;
-function buildSink(declared, override) {
-  if (override !== void 0) {
-    return override;
-  }
-  if (declared.type === "github") {
-    return createGithubSink2(declared.repo === void 0 ? {} : { repo: declared.repo });
-  }
-  return void 0;
-}
 function errorDetail(error) {
   if (error instanceof Error) {
     return error.message.split("\n")[0] ?? error.message;
@@ -1413,32 +1665,43 @@ function errorDetail(error) {
 function scopeLabel(scope) {
   return scope.kind === "repository" ? "repository secrets" : `environment secrets for ${scope.environment}`;
 }
-async function sinkFindings(project, environment, override) {
-  const declared = project.config.sinks?.[environment];
-  if (declared === void 0) {
-    return [];
-  }
-  const sink = buildSink(declared, override);
-  if (sink === void 0) {
-    return [
-      {
-        check: "sink-unreachable",
-        severity: "unknown",
-        label: "Sink",
-        subject: `sink type \`${declared.type}\` is not one penv knows`,
-        detail: "penv cannot check a sink it cannot build"
-      }
-    ];
+async function projectionFindings(project, environment, override) {
+  let projection;
+  if (override !== void 0) {
+    projection = override;
+  } else {
+    const declared = project.config.providers[environment];
+    if (declared === void 0 || declared.type === LOCAL_TREE_TYPE) {
+      return [];
+    }
+    let source;
+    try {
+      source = await sourceProviderFor(project, environment);
+    } catch (error) {
+      return [
+        {
+          check: "projection-unreachable",
+          severity: "unknown",
+          label: "Destination",
+          subject: `could not build the ${declared.type} provider for ${environment}`,
+          detail: errorDetail(error)
+        }
+      ];
+    }
+    if (!holdsProjection3(source)) {
+      return [];
+    }
+    projection = source;
   }
   try {
-    await sink.verify();
+    await projection.verify();
   } catch (error) {
     return [
       {
-        check: "sink-unreachable",
+        check: "projection-unreachable",
         severity: "unknown",
-        label: "Sink",
-        subject: `could not reach the ${declared.type} sink for ${environment}`,
+        label: "Destination",
+        subject: `could not reach the ${projection.type} destination for ${environment}`,
         detail: errorDetail(error)
       }
     ];
@@ -1446,15 +1709,15 @@ async function sinkFindings(project, environment, override) {
   let repoSecrets;
   let envSecrets;
   try {
-    repoSecrets = await sink.list({ kind: "repository" });
-    envSecrets = await sink.list({ kind: "environment", environment });
+    repoSecrets = await projection.list({ kind: "repository" });
+    envSecrets = await projection.list({ kind: "environment", environment });
   } catch (error) {
     return [
       {
-        check: "sink-unreachable",
+        check: "projection-unreachable",
         severity: "unknown",
-        label: "Sink",
-        subject: `could not list secrets in the ${declared.type} sink for ${environment}`,
+        label: "Destination",
+        subject: `could not list secrets in the ${projection.type} destination for ${environment}`,
         detail: errorDetail(error)
       }
     ];
@@ -1492,7 +1755,7 @@ async function sinkFindings(project, environment, override) {
     }
     if (!destOf(item.scope).has(key)) {
       nameDrift.push({
-        check: "sink-name-drift",
+        check: "projection-name-drift",
         severity: "warning",
         label: "Declared, not pushed",
         subject: item.variable,
@@ -1504,7 +1767,7 @@ async function sinkFindings(project, environment, override) {
   for (const secret of repoSecrets) {
     if (!allVariables.has(upper(secret.name))) {
       nameDrift.push({
-        check: "sink-name-drift",
+        check: "projection-name-drift",
         severity: "warning",
         label: "In destination, not declared",
         subject: secret.name,
@@ -1515,7 +1778,7 @@ async function sinkFindings(project, environment, override) {
   for (const secret of envSecrets) {
     if (!expectedEnv.has(upper(secret.name))) {
       nameDrift.push({
-        check: "sink-name-drift",
+        check: "projection-name-drift",
         severity: "warning",
         label: "In destination, not declared",
         subject: secret.name,
@@ -1539,7 +1802,7 @@ async function sinkFindings(project, environment, override) {
       continue;
     }
     manualEdits.push({
-      check: "sink-manual-edit",
+      check: "projection-manual-edit",
       severity: "warning",
       label: "Edited outside penv",
       subject: item.variable,
@@ -1550,9 +1813,9 @@ async function sinkFindings(project, environment, override) {
   findings.push(
     ...nameDrift.length > 0 ? nameDrift : [
       {
-        check: "sink-name-drift",
+        check: "projection-name-drift",
         severity: "pass",
-        label: "Sink names",
+        label: "Destination names",
         subject: `every parameter resolving for ${environment} is present, and nothing undeclared is`
       }
     ]
@@ -1560,17 +1823,17 @@ async function sinkFindings(project, environment, override) {
   findings.push(
     ...manualEdits.length > 0 ? manualEdits : [
       {
-        check: "sink-manual-edit",
+        check: "projection-manual-edit",
         severity: "pass",
-        label: "Sink hand-edits",
+        label: "Destination hand-edits",
         subject: `no secret has changed outside penv since its last push for ${environment}`
       }
     ]
   );
   findings.push({
-    check: "sink-value-drift",
+    check: "projection-value-drift",
     severity: "unknown",
-    label: "Sink values",
+    label: "Destination values",
     subject: "cannot be read back from a write-only destination",
     detail: "value drift between the tree and the destination is unknowable by design"
   });
@@ -1599,6 +1862,9 @@ async function rotationSubjects(project, environment, local, override) {
     return { kind: "read", subjects: local };
   }
   const source = override ?? await sourceProviderFor(project, environment);
+  if (!holdsRecords(source)) {
+    return { kind: "read", subjects: local };
+  }
   try {
     const subjects = await Promise.all(
       local.map(async ({ resolution }) => ({
@@ -1747,6 +2013,9 @@ async function providerDriftFindings(project, environment, override) {
     ];
   }
   const source = override ?? await sourceProviderFor(project, environment);
+  if (!holdsRecords(source)) {
+    return [];
+  }
   let local;
   let remote;
   try {
@@ -1866,7 +2135,7 @@ function renderDoctor(report) {
 var doctorCommand = defineCommand3({
   meta: {
     name: "doctor",
-    description: "Report missing, weak, unused, fallback, plaintext-secret, and sink-drift issues"
+    description: "Report missing, weak, unused, fallback, plaintext-secret, and drift issues"
   },
   args: {
     env: { type: "string", description: "The environment to report on" }
@@ -1875,7 +2144,8 @@ var doctorCommand = defineCommand3({
     return guard(async () => {
       const report = await runDoctor({
         cwd: process.cwd(),
-        ...args.env === void 0 ? {} : { environment: args.env }
+        ...args.env === void 0 ? {} : { environment: args.env },
+        envFlags: shorthandCandidates(args, ["env"])
       });
       write(renderDoctor(report));
       if (!report.ok) {
@@ -1890,14 +2160,14 @@ import {
   formatValueFile as formatValueFile4,
   isSecret as isSecret3,
   openValue as openValue3,
-  PenvError as PenvError7,
+  PenvError as PenvError8,
   parameterId as parameterId4,
   sealValue as sealValue2
 } from "@penvhq/core";
 import { defineCommand as defineCommand5 } from "citty";
 
 // src/commands/set.ts
-import { formatValueFile as formatValueFile3, isSecret as isSecret2, PenvError as PenvError6, parameterId as parameterId3, sealValue } from "@penvhq/core";
+import { formatValueFile as formatValueFile3, isSecret as isSecret2, PenvError as PenvError7, parameterId as parameterId3, sealValue } from "@penvhq/core";
 import { defineCommand as defineCommand4 } from "citty";
 function scopeFrom(options) {
   if (options.local === true) {
@@ -1917,7 +2187,7 @@ function targetScope(project, options, key) {
     return scopeFrom(options);
   }
   if (environment.trim().length === 0) {
-    throw new PenvError6(
+    throw new PenvError7(
       "ENVIRONMENT_FLAG_EMPTY",
       `\`--env\` for parameter ${key} names no environment`,
       `Pass a declared environment \u2014 ${project.config.environments.map((e) => `\`${e}\``).join(", ")} \u2014 e.g. \`--env production\`, or drop \`--env\` to write the scope that has no environment.`
@@ -1930,7 +2200,7 @@ function policyEnvironment(project, options) {
 }
 function sealFor(project, file, value, parameter, environment) {
   if (environment === void 0) {
-    throw new PenvError6(
+    throw new PenvError7(
       "SECRET_SCOPE_AMBIGUOUS",
       `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."
@@ -2032,7 +2302,7 @@ function twins(project, key, options) {
 }
 function environmentFor(project, options, verb) {
   if (options.environment === void 0) {
-    throw new PenvError7(
+    throw new PenvError8(
       "SECRET_SCOPE_AMBIGUOUS",
       `\`penv ${verb}\` names no environment, and keys are declared per environment`,
       "Pass `--env <environment>`. penv cannot tell which environment's key applies to a file that names none, and will not pick one for you."
@@ -2051,7 +2321,7 @@ async function runEncrypt(options) {
   const value = await readOne(project, plain);
   if (value === void 0) {
     const already = await readOne(project, sealed);
-    throw new PenvError7(
+    throw new PenvError8(
       "PARAMETER_ABSENT",
       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."
@@ -2072,7 +2342,7 @@ async function runDecrypt(options) {
   const [plain, sealed] = twins(project, options.key, options);
   const parameter = parameterId4(plain);
   if (isSecret3(await project.provider.readMeta(plain), environment)) {
-    throw new PenvError7(
+    throw new PenvError8(
       "SECRET_DECRYPT_REFUSED",
       `Parameter ${parameter} is declared a secret for environment ${environment}, so penv will not write it in plaintext`,
       "A secret with a plaintext value file is a `penv doctor` failure. Drop `secret` from the parameter's meta if it is not one, or run `penv generate --allow-decrypt` if you need the plaintext value in a `.env` artifact."
@@ -2080,7 +2350,7 @@ async function runDecrypt(options) {
   }
   const stored = await readOne(project, sealed);
   if (stored === void 0) {
-    throw new PenvError7(
+    throw new PenvError8(
       "PARAMETER_ABSENT",
       `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.`
@@ -2103,7 +2373,7 @@ async function runDecrypt(options) {
     removed: formatValueFile4(sealed)
   };
 }
-var UndecryptableAt = class extends PenvError7 {
+var UndecryptableAt = class extends PenvError8 {
   constructor(parameter, environment, location, detail) {
     super(
       "VALUE_UNDECRYPTABLE",
@@ -2158,57 +2428,14 @@ var decryptCommand = defineCommand5({
 });
 
 // src/commands/fill.ts
-import { PenvError as PenvError8 } from "@penvhq/core";
+import { PenvError as PenvError9 } from "@penvhq/core";
 import { defineCommand as defineCommand6 } from "citty";
-
-// src/input.ts
-import { createInterface } from "readline";
-function lineReader(input = process.stdin, output = process.stdout) {
-  const rl = createInterface({ input, output });
-  const buffered = [];
-  const waiting = [];
-  let closed = false;
-  rl.on("line", (line) => {
-    const next = waiting.shift();
-    if (next === void 0) {
-      buffered.push(line);
-    } else {
-      next(line);
-    }
-  });
-  rl.on("close", () => {
-    closed = true;
-    for (const next of waiting.splice(0)) {
-      next(void 0);
-    }
-  });
-  return {
-    ask(question) {
-      const early = buffered.shift();
-      if (early !== void 0) {
-        return Promise.resolve(early);
-      }
-      if (closed) {
-        return Promise.resolve(void 0);
-      }
-      rl.setPrompt(question);
-      rl.prompt();
-      return new Promise((resolve7) => {
-        waiting.push(resolve7);
-      });
-    },
-    close() {
-      rl.close();
-    }
-  };
-}
-
-// src/commands/fill.ts
 var BLOCKING = /* @__PURE__ */ new Set(["config", "collision", "reserved"]);
 async function runFill(options) {
   const validation = await runValidate({
     cwd: options.cwd,
-    ...options.environment === void 0 ? {} : { environment: options.environment }
+    ...options.environment === void 0 ? {} : { environment: options.environment },
+    ...options.envFlags === void 0 ? {} : { envFlags: options.envFlags }
   });
   const environment = validation.environment;
   const blockers = validation.issues.filter((issue) => BLOCKING.has(issue.kind));
@@ -2216,7 +2443,7 @@ async function runFill(options) {
     const detail = blockers.map(
       (issue) => `  - ${issue.message}${issue.remedy === void 0 ? "" : ` (${issue.remedy})`}`
     ).join("\n");
-    throw new PenvError8(
+    throw new PenvError9(
       "FILL_BLOCKED",
       `penv fill cannot run: environment ${environment} has ${blockers.length} unresolved configuration ${blockers.length === 1 ? "issue" : "issues"}:
 ${detail}`,
@@ -2338,7 +2565,8 @@ var fillCommand = defineCommand6({
             await runFill({
               cwd: process.cwd(),
               ...args.env === void 0 ? {} : { environment: args.env },
-              ask
+              ask,
+              envFlags: shorthandCandidates(args, ["env"])
             })
           )
         );
@@ -2355,7 +2583,7 @@ import { isAbsolute, relative, resolve as resolve3 } from "path";
 import {
   checkNameCollisions as checkNameCollisions3,
   effectiveMeta as effectiveMeta2,
-  PenvError as PenvError9,
+  PenvError as PenvError10,
   requireValue as requireValue2,
   serializeDotenv,
   variableName as variableName4
@@ -2379,7 +2607,7 @@ function entriesFor(project, environment, allowDecrypt) {
     const winner = resolution.winner;
     if (winner?.file.encrypted === true) {
       if (!allowDecrypt) {
-        throw new PenvError9(
+        throw new PenvError10(
           "ENCRYPTED_VALUE_REFUSED",
           `Parameter ${resolution.parameter} for environment ${environment} resolves to the encrypted value file ${PENV_DIR}/${winner.location}, and \`penv generate\` writes plaintext`,
           `Re-run with \`--allow-decrypt\` to write the decrypted value into the artifact, or generate for an environment whose values are plaintext. The artifact is gitignored; a committed plaintext secret is a \`penv doctor\` failure.`
@@ -2403,12 +2631,12 @@ function entriesFor(project, environment, allowDecrypt) {
 }
 function generateDotenv(options) {
   const project = openProject(options.cwd);
-  const environment = targetEnvironment(project, options.environment);
+  const environment = targetEnvironment(project, options.environment, options.envFlags);
   return serializeDotenv(entriesFor(project, environment, options.allowDecrypt === true).entries);
 }
 function runGenerate(options) {
   const project = openProject(options.cwd);
-  const environment = targetEnvironment(project, options.environment);
+  const environment = targetEnvironment(project, options.environment, options.envFlags);
   const { entries, decrypted } = entriesFor(project, environment, options.allowDecrypt === true);
   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");
@@ -2454,7 +2682,8 @@ var generateCommand = defineCommand7({
         cwd,
         ...args.env === void 0 ? {} : { environment: args.env },
         ...args.out === void 0 ? {} : { out: args.out },
-        ...args["allow-decrypt"] === void 0 ? {} : { allowDecrypt: args["allow-decrypt"] }
+        ...args["allow-decrypt"] === void 0 ? {} : { allowDecrypt: args["allow-decrypt"] },
+        envFlags: shorthandCandidates(args, ["env", "out", "allow-decrypt", "allowDecrypt"])
       });
       write(renderGenerate(result2, cwd));
     });
@@ -2462,7 +2691,7 @@ var generateCommand = defineCommand7({
 });
 
 // src/commands/get.ts
-import { PenvError as PenvError10, requireValue as requireValue3, resolveParameter } from "@penvhq/core";
+import { PenvError as PenvError11, requireValue as requireValue3, resolveParameter } from "@penvhq/core";
 import { defineCommand as defineCommand8 } from "citty";
 async function runGet(options) {
   const project = openProject(options.cwd);
@@ -2472,7 +2701,7 @@ async function runGet(options) {
   const resolution = await resolveParameter(ref, environment, project.provider, keys);
   const value = requireValue3(resolution, environment);
   if (value === void 0) {
-    throw new PenvError10(
+    throw new PenvError11(
       "PARAMETER_ABSENT",
       `Parameter ${resolution.parameter} resolves to no value for environment ${environment}`,
       `Set it with \`penv set ${options.key} --env ${environment}\`, or run \`penv get ${options.key} --env ${environment} --explain\` to see every file penv looked at.`
@@ -2559,7 +2788,7 @@ import {
   isReservedToken as isReservedToken3,
   loadConfigFrom as loadConfigFrom2,
   lookupEnvironment,
-  PenvError as PenvError12,
+  PenvError as PenvError13,
   parseDotenv,
   ReservedTokenError as ReservedTokenError3,
   refFromVariable,
@@ -2679,7 +2908,7 @@ import {
   DEFAULT_SCHEMA_FILE as DEFAULT_SCHEMA_FILE2,
   isLegalEnvironmentName,
   loadConfigFrom,
-  PenvError as PenvError11,
+  PenvError as PenvError12,
   RESERVED_TOKENS,
   schemaFileOf as schemaFileOf2,
   schemaInsideTree,
@@ -2723,7 +2952,7 @@ function suggestEnvironments(root) {
   return [...found].sort();
 }
 function emptyFlag(flag) {
-  return new PenvError11(
+  return new PenvError12(
     "INIT_FLAG_EMPTY",
     `\`--${flag}\` was given without a value`,
     flag === "schema" ? `Name the module that exports the schema, e.g. \`--schema src/env.ts\`, or drop the flag to use ${DEFAULT_SCHEMA_FILE2}.` : "Name the environment, e.g. `--env production`, or drop the flag to leave the whitelist empty and declare it in penv.config.ts."
@@ -2786,7 +3015,7 @@ function planInit(root, flags = {}) {
     throw emptyFlag("alias");
   }
   if (!ALIAS_NAME.test(alias)) {
-    throw new PenvError11(
+    throw new PenvError12(
       "INIT_ALIAS_INVALID",
       `\`${alias}\` is not an alias penv can write`,
       `An alias is \`@name\` \u2014 a tsconfig \`paths\` entry a bundler resolves \u2014 or \`#name\`, a package.json \`imports\` entry Node resolves itself. Those are the two things a module specifier can be that is not a package.`
@@ -2882,6 +3111,15 @@ ${body}
 // code. Importing it loads configuration and throws (naming the parameter and
 // environment) if anything required is missing or invalid.
 export const env = load(schema);
+
+// Registers the schema's shape with penv's types (erased at runtime, so
+// nothing cycles). This is what makes \`override\` keys in penv.config.ts
+// autocomplete from this schema \u2014 a typo'd parameter id is a compile error.
+declare module "@penvhq/core" {
+  interface PenvSchemaShape {
+    readonly shape: z.infer<typeof schema>;
+  }
+}
 `;
 }
 function renderEnvironments(decisions) {
@@ -2891,14 +3129,14 @@ function renderEnvironments(decisions) {
   // can read off your codebase, and an environment you do not have is worse
   // than one you have not declared yet. Name yours, and give each a provider:
   //   environments: ["development", "production"],
-  //   providers: { development: { type: "filesystem" }, production: { type: "filesystem" } },
+  //   providers: { development: { type: "@penvhq/provider-filesystem" }, production: { type: "@penvhq/provider-filesystem" } },
   environments: [],
 
   providers: {},
 `;
   }
   const names = decisions.environments.map((name) => JSON.stringify(name)).join(", ");
-  const providers = decisions.environments.map((name) => `    ${JSON.stringify(name)}: { type: "filesystem" },
+  const providers = decisions.environments.map((name) => `    ${JSON.stringify(name)}: { type: "@penvhq/provider-filesystem" },
 `).join("");
   return `${shared}  environments: [${names}],
 
@@ -3077,7 +3315,7 @@ ${objectIndent}${source.slice(close)}`;
 ${entryIndent}${member},${source.slice(open + 1)}`;
 }
 function shapeError(what, target, alias) {
-  return new PenvError11(
+  return new PenvError12(
     "TSCONFIG_SHAPE",
     `penv cannot add the \`${alias}\` path alias to tsconfig.json: ${what}`,
     `Add it by hand: \`{ "compilerOptions": { "paths": { "${alias}": ["${target}"] } } }\`.`
@@ -3357,7 +3595,7 @@ function assertImportable(ref, variable) {
   if (!ref.name.includes(".")) {
     return;
   }
-  throw new PenvError12(
+  throw new PenvError13(
     "IMPORT_UNPARSEABLE_NAME",
     `The variable ${variable} becomes the parameter \`${ref.name}\`, whose \`.\` would be read as a scope`,
     `Filenames are split on \`.\`. Rename ${variable} in the source file, then import it again.`
@@ -3376,10 +3614,10 @@ function assertRoundTrips(ref, variable, config) {
     return;
   }
   const generated = variableName5(ref, config);
-  throw new PenvError12(
+  throw new PenvError13(
     "IMPORT_LOSSY_NAME",
     `The variable ${variable} becomes the parameter \`${ref.name}\`, which regenerates as ${generated}`,
-    `\`penv generate\` would write ${generated}, so anything reading \`process.env["${variable}"]\` would read \`undefined\`. Declare the name you want in the \`names\` block of penv.config.ts \u2014 \`names: { "${ref.name}": "${variable}" }\` \u2014 then import it again. Nothing was imported.`
+    `\`penv generate\` would write ${generated}, so anything reading \`process.env["${variable}"]\` would read \`undefined\`. Declare the name you want in the \`override\` block of penv.config.ts \u2014 \`override: { "${ref.name}": "${variable}" }\` \u2014 then import it again. Nothing was imported.`
   );
 }
 function collisionsIn(refs, config) {
@@ -3460,7 +3698,7 @@ function explicitEnvironment(options, source, config) {
   if (value.length > 0) {
     return value;
   }
-  throw new PenvError12(
+  throw new PenvError13(
     "IMPORT_ENV_FLAG_EMPTY",
     `\`--env\` for the import of ${source} names no environment`,
     `Pass a declared environment \u2014 ${config.environments.map((e) => `\`${e}\``).join(", ")} \u2014 e.g. \`--env production\`, or drop \`--env\` to import ${source} as the scope that has no environment. Nothing was imported.`
@@ -3470,7 +3708,7 @@ function assertEnvironmentAgrees(derived, explicit, source) {
   if (derived === void 0 || explicit === void 0 || derived === explicit) {
     return;
   }
-  throw new PenvError12(
+  throw new PenvError13(
     "IMPORT_ENV_CONFLICT",
     `The file ${source} is scoped to environment ${derived}, but \`--env ${explicit}\` names ${explicit}`,
     `Drop \`--env\` to import ${source} as ${derived}, pass \`--env ${derived}\` to say the same thing twice, or point \`penv import\` at the file that holds ${explicit}'s values. Nothing was imported.`
@@ -3514,7 +3752,7 @@ function importDotenv(options) {
   const cwd = resolve5(options.cwd);
   const file = isAbsolute2(options.file) ? options.file : resolve5(cwd, options.file);
   if (!existsSync3(file)) {
-    throw new PenvError12(
+    throw new PenvError13(
       "IMPORT_FILE_MISSING",
       `There is no file at ${file} to import`,
       "Point `penv import` at an existing dotenv file, e.g. `penv import .env`."
@@ -3659,7 +3897,7 @@ var importCommand = defineCommand10({
 
 // src/commands/key.ts
 import { randomBytes } from "crypto";
-import { KEY_BYTES, KEYCHAIN_SERVICE, PenvError as PenvError13 } from "@penvhq/core";
+import { KEY_BYTES, KEYCHAIN_SERVICE, PenvError as PenvError14 } from "@penvhq/core";
 import { defineCommand as defineCommand11 } from "citty";
 
 // src/keychain.ts
@@ -3692,7 +3930,7 @@ function runKeyCreate(options) {
   const environment = targetEnvironment(project, options.environment);
   const declared = project.config.keys?.[environment];
   if (declared === void 0) {
-    throw new PenvError13(
+    throw new PenvError14(
       "KEY_SOURCE_UNDECLARED",
       `Environment ${environment} declares no key source, so penv does not know what a key for it would be`,
       `Add a \`keys\` entry to penv.config.ts \u2014 e.g. \`keys: { ${environment}: { source: "env", id: "${environment}" } }\` \u2014 then run this again.`
@@ -3706,14 +3944,14 @@ function runKeyCreate(options) {
       try {
         existing = keychain.getPassword(KEYCHAIN_SERVICE, declared.id);
       } catch (cause) {
-        throw new PenvError13(
+        throw new PenvError14(
           "KEYCHAIN_UNAVAILABLE",
           `penv could not read your OS keychain to check for an existing key \`${declared.id}\``,
           `Unlock your keychain and run this again. Original error: ${cause instanceof Error ? cause.message : String(cause)}`
         );
       }
       if (existing !== null) {
-        throw new PenvError13(
+        throw new PenvError14(
           "KEY_EXISTS",
           `Environment ${environment} already has a key \`${declared.id}\` in your OS keychain`,
           "Replacing it would orphan every value already sealed under it \u2014 they could never be decrypted again. Re-run with `--force` only if you are certain nothing is sealed under the current key."
@@ -3872,7 +4110,7 @@ import {
   formatMetaFile,
   formatValueFile as formatValueFile5,
   openValue as openValue4,
-  PenvError as PenvError14,
+  PenvError as PenvError15,
   parameterId as parameterId5,
   sealValue as sealValue3
 } from "@penvhq/core";
@@ -3891,7 +4129,7 @@ async function planFile(project, source, target, parameter) {
   }
   const environment = environmentOf2(source);
   if (environment === void 0) {
-    throw new PenvError14(
+    throw new PenvError15(
       "SECRET_SCOPE_AMBIGUOUS",
       `${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."
@@ -3900,7 +4138,7 @@ async function planFile(project, source, target, parameter) {
   const keys = keySourceFor(project, environment);
   const opened = openValue4(source, stored, keys);
   if (opened.kind === "failed") {
-    throw new PenvError14(
+    throw new PenvError15(
       "VALUE_UNDECRYPTABLE",
       `${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."
@@ -3923,7 +4161,7 @@ async function runMove(options) {
   assertWritableKey(options.to);
   const to = refFromKey(options.to, project.config);
   if (parameterId5(from) === parameterId5(to)) {
-    throw new PenvError14(
+    throw new PenvError15(
       "PARAMETER_UNCHANGED",
       `\`${options.from}\` and \`${options.to}\` are the same parameter`,
       "Name a different destination, e.g. `penv mv redis-password redis/password`."
@@ -3933,7 +4171,7 @@ async function runMove(options) {
   const sources = filesOf(all, from);
   const meta = await project.provider.readMeta(from);
   if (sources.length === 0 && meta === void 0) {
-    throw new PenvError14(
+    throw new PenvError15(
       "PARAMETER_ABSENT",
       `Parameter ${parameterId5(from)} has no value files and no meta, so there is nothing to move`,
       `\`penv list\` shows every parameter penv holds.`
@@ -3941,7 +4179,7 @@ async function runMove(options) {
   }
   const occupied2 = filesOf(all, to);
   if (occupied2.length > 0 || await project.provider.readMeta(to) !== void 0) {
-    throw new PenvError14(
+    throw new PenvError15(
       "PARAMETER_EXISTS",
       `Parameter ${parameterId5(to)} already exists, and penv will not merge two parameters into one`,
       `Remove or rename ${parameterId5(to)} first. \`penv get ${options.to} --explain\` shows every file it holds.`
@@ -4023,14 +4261,45 @@ var mvCommand = defineCommand13({
 });
 
 // src/commands/pull.ts
+import { holdsProjection as holdsProjection4, refFromVariable as refFromVariable2 } from "@penvhq/core";
 import { defineCommand as defineCommand14 } from "citty";
+async function pullProjection(project, source, environment) {
+  const tree = localTree(project);
+  const names = /* @__PURE__ */ new Set();
+  for (const secret of await source.list({ kind: "repository" })) {
+    names.add(secret.name);
+  }
+  for (const secret of await source.list({ kind: "environment", environment })) {
+    names.add(secret.name);
+  }
+  let meta = 0;
+  for (const name of [...names].sort()) {
+    const ref = refFromVariable2(name);
+    if (tree.readMetaSync(ref) === void 0) {
+      tree.writeMetaSync(ref, {});
+      meta += 1;
+    }
+  }
+  return {
+    environment,
+    source: source.type,
+    localSource: false,
+    values: 0,
+    meta,
+    refs: names.size,
+    valuesUnreadable: true
+  };
+}
 async function runPull(options) {
   const project = openProject(options.cwd);
-  const environment = targetEnvironment(project, options.environment);
-  const source = await sourceProviderFor(project, environment);
+  const environment = targetEnvironment(project, options.environment, options.envFlags);
+  const source = options.source ?? await sourceProviderFor(project, environment);
   if (source.type === LOCAL_TREE_TYPE) {
     return { environment, source: source.type, localSource: true, values: 0, meta: 0, refs: 0 };
   }
+  if (holdsProjection4(source)) {
+    return pullProjection(project, source, environment);
+  }
   const tree = localTree(project);
   const files = await source.list();
   let values = 0;
@@ -4065,6 +4334,22 @@ function renderPull(result2) {
       }
     ]);
   }
+  if (result2.valuesUnreadable === true) {
+    return formatRows([
+      {
+        glyph: CHECK,
+        label: "Pulled",
+        subject: `${result2.refs} ${result2.refs === 1 ? "parameter name" : "parameter names"}`,
+        detail: `from ${result2.source} for environment ${result2.environment}`
+      },
+      {
+        glyph: WARN,
+        label: "Values not readable",
+        subject: "this destination never returns a secret's value",
+        detail: "fill them locally with `penv set` or `penv fill` \u2014 `penv validate` names every gap"
+      }
+    ]);
+  }
   return formatRows([
     {
       glyph: CHECK,
@@ -4086,13 +4371,17 @@ var pullCommand = defineCommand14({
     description: "Materialise the local .penv tree from an environment's source-of-truth provider"
   },
   args: {
-    env: { type: "string", description: "The environment to pull" }
+    env: {
+      type: "string",
+      description: "The environment to pull (or pass it as a bare flag: --production)"
+    }
   },
   run({ args }) {
     return guard(async () => {
       const result2 = await runPull({
         cwd: process.cwd(),
-        ...args.env === void 0 ? {} : { environment: args.env }
+        ...args.env === void 0 ? {} : { environment: args.env },
+        envFlags: shorthandCandidates(args, ["env"])
       });
       write(renderPull(result2));
     });
@@ -4175,7 +4464,8 @@ var removeCommand = defineCommand15({
 import {
   beginRotation,
   completeRotation,
-  PenvError as PenvError15,
+  holdsRecords as holdsRecords2,
+  PenvError as PenvError16,
   retainsPrevious,
   rotationOf as rotationOf2
 } from "@penvhq/core";
@@ -4204,7 +4494,7 @@ async function writeRotatedValue(project, provider, ref, environment, value) {
 }
 function requireNewValue(value, phase, key) {
   if (value === void 0) {
-    throw new PenvError15(
+    throw new PenvError16(
       "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."
@@ -4214,7 +4504,7 @@ function requireNewValue(value, phase, key) {
 }
 function requireRetaining(provider, environment) {
   if (!retainsPrevious(provider)) {
-    throw new PenvError15(
+    throw new PenvError16(
       "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."
@@ -4226,12 +4516,20 @@ 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 source = await sourceProviderFor(project, environment);
+  if (!holdsRecords2(source)) {
+    throw new PenvError16(
+      "ROTATION_NOT_RECORDS",
+      `Environment ${environment} is backed by \`${source.type}\`, which holds a resolved projection penv cannot rotate in place`,
+      "Rotate the parameter in the environment that holds the records (the local tree, Vault, SSM), then `penv push` the result to this destination."
+    );
+  }
+  const provider = source;
   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 PenvError15(
+    throw new PenvError16(
       "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.'
@@ -4241,7 +4539,7 @@ async function runRotate(options) {
   const complete = options.complete === true;
   if (mechanism === "atomic-cutover") {
     if (begin || complete) {
-      throw new PenvError15(
+      throw new PenvError16(
         "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."
@@ -4255,7 +4553,7 @@ async function runRotate(options) {
   }
   const retaining = requireRetaining(provider, environment);
   if (begin === complete) {
-    throw new PenvError15(
+    throw new PenvError16(
       "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."