envstash-cli 0.10.0 → 0.11.0

package/README.md

@@ -244,7 +244,7 @@ on the dashboard under **Shared Files**, not inside any project.
 ```json
 {
   "project": "demo-app",
-  "files": [".env.local", ".env.production"]
+  "files": [".env", ".env.production"]
 }
 ```
 
@@ -259,6 +259,16 @@ and `.agents/` (see below). That list is the default, and
 `.dist` are ignored, since those are meant to be committed and hold placeholder
 values.
 
+`.env.local` and `.env.*.local` are not discovered either. Every dotenv loader
+that layers files puts `.local` on top — `.env`, then `.env.<mode>`, then
+`.env.local`, then the real environment — so by name it is the override a
+developer writes to differ from the shared values on this one checkout. A tool
+that distributes the shared values fills the lower layers and leaves that one
+alone; syncing it would leave no layer that can differ between machines.
+`init`, `push`, and `sync` say when they skip one. To sync it anyway, list it in
+`.envstash.json` or name it on the command line — that is taken as written. A
+`.local` file already in the cloud keeps syncing until you `envs rm` it.
+
 ### Files in `.config/`
 
 A service-account key or a cert is a secret that is not `KEY=value`, and it does

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envstash-cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Git-style CLI for EnvStash — keep your .env files in sync with your cloud account.",
   "keywords": [
     "env",

package/src/commands/misc.mjs

@@ -15,7 +15,7 @@ import {
 import { requireHostToken, resolveHostFor, resolveHostSource } from '../session.mjs'
 import { DEFAULT_SETTINGS, readSettings, settingsPath } from '../settings.mjs'
 import { out, pad, pluralize, sanitize, style } from '../ui.mjs'
-import { announceDiscoveryDirs } from './push.mjs'
+import { announceDiscoveryDirs, announceLocalEnvFiles } from './push.mjs'
 
 /**
  * `envs version` — the version, and the environment it would act in.
@@ -266,6 +266,7 @@ export async function init(flags, args) {
   const files = existing?.files?.length
     ? existing.files
     : discoverTrackedFiles(repoRoot, readSettings().discover)
+  announceLocalEnvFiles(repoRoot, { discovering: !existing?.files?.length, covered: files })
   const path = writeLink(repoRoot, {
     project: name,
     files,
@@ -332,6 +333,7 @@ export async function link(flags, args) {
   const files = existing?.files?.length
     ? existing.files
     : discoverTrackedFiles(repoRoot, readSettings().discover)
+  announceLocalEnvFiles(repoRoot, { discovering: !existing?.files?.length, covered: files })
   const path = writeLink(repoRoot, { project: name, files, host: existing?.host ?? null })
 
   out()

package/src/commands/push.mjs

@@ -13,6 +13,8 @@ import {
   ensureSecretDirIgnored,
   ENV_FILES_TARGET,
   lacksIgnoreRule,
+  LINK_FILE,
+  localEnvFiles,
   SECRET_FILE_DIR,
 } from '../project.mjs'
 import { resolveRepoFile } from '../repo-path.mjs'
@@ -62,6 +64,39 @@ export function announceDiscoveryDirs(repoRoot, { discovering = true } = {}) {
   }
 }
 
+/**
+ * Say which `.local` files the dotenv scan left behind, and how to list one.
+ *
+ * The scan skips them by name: `.local` is the per-checkout override layer, not
+ * the shared values. A developer whose secrets live in `.env.local` would
+ * otherwise see it silently missing from the list a command just decided.
+ *
+ * `covered` is that list. A `.local` file already in the cloud — pushed by an
+ * older version, or by name — is still synced through the cloud listing until
+ * `envs rm`, and saying otherwise would be false. Only when discovery decided
+ * the list (`discovering`) and the scan is on is there anything to point out.
+ */
+export function announceLocalEnvFiles(repoRoot, { discovering = true, covered = [] } = {}) {
+  if (!discovering || !readSettings().discover.includes(ENV_FILES_TARGET)) {
+    return
+  }
+
+  const left = localEnvFiles(repoRoot).filter(name => !covered.includes(name))
+
+  if (left.length === 0) {
+    return
+  }
+
+  out()
+
+  for (const name of left) {
+    out(
+      `  ${style.dim('·')} ${style.bold(name)} is a local override, so it is not synced ` +
+        style.dim(`— list it in ${LINK_FILE} to sync it`)
+    )
+  }
+}
+
 /**
  * `envs push` — send local files up.
  *
@@ -106,6 +141,11 @@ export async function push(flags, args) {
     requested: args,
   })
 
+  announceLocalEnvFiles(context.repoRoot, {
+    discovering: args.length === 0 && !context.link?.files?.length,
+    covered: names,
+  })
+
   const localFiles = loadLocalFiles(context.repoRoot, names, cloudKinds(cloudFiles))
   const presentNames = names.filter(name => localFiles.get(name) !== null)
 

package/src/commands/sync.mjs

@@ -15,7 +15,13 @@ import { resolveRepoFile } from '../repo-path.mjs'
 import { compareProject } from '../status.mjs'
 import { conflictExitCode, isBlocked, isChanging, planSync, PREFER, SYNC_ACTION } from '../sync.mjs'
 import { CliError, out, pad, pluralize, sanitize, style } from '../ui.mjs'
-import { announceDiscoveryDirs, confirmNewFiles, fetchCloudFiles, pushOneBlob } from './push.mjs'
+import {
+  announceDiscoveryDirs,
+  announceLocalEnvFiles,
+  confirmNewFiles,
+  fetchCloudFiles,
+  pushOneBlob,
+} from './push.mjs'
 
 /**
  * `envs sync` — reconcile this repo with the cloud, in both directions at once.
@@ -70,6 +76,11 @@ export async function sync(flags, args) {
     sink: 'write',
   })
 
+  announceLocalEnvFiles(context.repoRoot, {
+    discovering: args.length === 0 && !context.link?.files?.length,
+    covered: names,
+  })
+
   const localFiles = loadLocalFiles(context.repoRoot, names, cloudKinds(cloudFiles))
   const comparison = compareProject({
     cloudFiles: cloudFiles.filter(file => names.includes(file.name)),

package/src/index.mjs

@@ -444,8 +444,8 @@ const COMMAND_HELP = {
     '',
     '  { "discover": [".env*", ".config", ".agents"] }',
     '',
-    '".env*" is the dotenv files in the repo root; anything else is a directory',
-    'whose git-ignored files are synced.',
+    '".env*" is the dotenv files in the repo root, minus templates and .local',
+    'overrides; anything else is a directory whose git-ignored files are synced.',
     '',
     '  envs config',
     '  envs config --json',

package/src/project.mjs

@@ -57,6 +57,17 @@ function runGit(args, { cwd, input } = {}) {
  */
 const TEMPLATE_SUFFIXES = ['.example', '.sample', '.template', '.dist']
 
+/**
+ * The per-checkout override layer. Every dotenv loader that layers files agrees
+ * on the stack — `.env`, `.env.<mode>`, `.env.local`, `.env.<mode>.local`, then
+ * the real environment — and `.local` is, by name, what a developer writes to
+ * differ from the shared values on this one checkout. A tool that distributes
+ * the shared values fills the lower layers and leaves this one alone: syncing
+ * it would leave no layer that can differ between machines. Listing the file in
+ * the link file or naming it on the command line still syncs it.
+ */
+const LOCAL_SUFFIX = '.local'
+
 /**
  * Walk up from `startDir` looking for a repo root.
  *
@@ -165,13 +176,14 @@ export function guessProjectName(repoRoot) {
 }
 
 /**
- * Discover `.env*` files in the repo root.
+ * The dotenv files in the repo root that could hold a real value: `.env` and
+ * `.env.*`, minus templates and type declarations, regular files only.
  *
  * Deliberately not recursive: walking a whole tree would wander into
  * node_modules and vendored fixtures, and a monorepo's nested files are better
  * declared explicitly in the link file than guessed at.
  */
-export function discoverEnvFiles(repoRoot) {
+function rootEnvFiles(repoRoot) {
   let names
 
   try {
@@ -196,6 +208,19 @@ export function discoverEnvFiles(repoRoot) {
     .sort()
 }
 
+/** Discover `.env*` files in the repo root — the shared layers, not `.local`. */
+export function discoverEnvFiles(repoRoot) {
+  return rootEnvFiles(repoRoot).filter(name => !name.endsWith(LOCAL_SUFFIX))
+}
+
+/**
+ * The `.local` files discovery left behind, so a command can say why they are
+ * missing from a list it just decided.
+ */
+export function localEnvFiles(repoRoot) {
+  return rootEnvFiles(repoRoot).filter(name => name.endsWith(LOCAL_SUFFIX))
+}
+
 /**
  * Where credential *files* live, by convention: a service-account JSON, a cert, a
  * private key — the things that are secrets but are not `KEY=value`.