envstash-cli 0.10.0 → 0.12.0

package/README.md

@@ -127,8 +127,11 @@ definition and therefore has no undo:
 - **`diff` masks values**, showing at most the first 4 characters and the
   length, and nothing at all of a value 12 characters or shorter. Use
   `--show-values` to reveal them.
-- **`sync` never deletes** in either direction, and never overwrites a value
-  that differs on both sides without being told which side wins.
+- **`sync` never prunes keys** in either direction, and never overwrites a
+  value that differs on both sides without being told which side wins. It does
+  follow a whole-file deletion: a file this machine has synced before and you
+  have since deleted is removed from the cloud. A machine that never had the
+  file pulls it instead, so a fresh clone cannot delete anything.
 - **`remove` needs every file named** — there is no "remove everything"
   default — and it only touches the cloud copy; files on your machines stay.
 - Pulled files are written `0600` — replaced atomically, so a file that
@@ -171,21 +174,31 @@ $ envs sync
   See them with envs diff, then choose a side: envs sync --prefer local or envs sync --prefer cloud
 ```
 
-| Situation                          | What `sync` does                    |
-| ---------------------------------- | ----------------------------------- |
-| File on disk, not in the cloud     | pushes it                           |
-| File in the cloud, not on disk     | pulls it                            |
-| Key on one side only               | copies it to the other side         |
-| Key on both sides, different value | **conflict** — left alone, reported |
-| Everything matches                 | nothing                             |
-
-**It never deletes.** Sync does not prune in either direction. There is no
-record of the last sync, so nothing can know whether a key that exists on one
-side only is one you just added or one a teammate removed — the same limit
-`envs status` acknowledges by saying `local-only` rather than `added`. Copying
-is the guess whose failure mode is a key coming back, which the next
-`envs status` shows you and `envs rm` undoes. Deleting is the guess whose
-failure mode is a secret that exists nowhere any more.
+| Situation                                          | What `sync` does                    |
+| -------------------------------------------------- | ----------------------------------- |
+| File on disk, not in the cloud                     | pushes it                           |
+| File in the cloud, not on disk, never synced here  | pulls it                            |
+| File in the cloud, not on disk, synced here before | removes it from the cloud           |
+| Key on one side only                               | copies it to the other side         |
+| Key on both sides, different value                 | **conflict** — left alone, reported |
+| Everything matches                                 | nothing                             |
+
+**It never prunes keys.** There is no record of the last sync at key level, so
+nothing can know whether a key that exists on one side only is one you just
+added or one a teammate removed — the same limit `envs status` acknowledges by
+saying `local-only` rather than `added`. Copying is the guess whose failure
+mode is a key coming back, which the next `envs status` shows you and
+`envs rm` undoes. Deleting is the guess whose failure mode is a secret that
+exists nowhere any more.
+
+**It does follow a deleted file.** Whole files are the one place a record
+exists: every `sync`, `pull` and `push` notes, in `~/.envstash/synced.json`,
+which files this machine ended up with on both sides. A file on that list that
+is gone from disk was deleted here, and `sync` removes it from the cloud and
+says so. A cloud file not on the list is pulled as before — a fresh clone has
+no record, so it can never delete anything — and `envs rm` takes a file off
+the list, so one a teammate adds back later is pulled rather than removed
+again.
 
 **A conflict is never guessed at either.** When the same key holds different
 values on each side, both copies are left exactly as they are, the key is
@@ -244,7 +257,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 +272,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.12.0",
   "description": "Git-style CLI for EnvStash — keep your .env files in sync with your cloud account.",
   "keywords": [
     "env",
@@ -31,12 +31,13 @@
   "engines": {
     "node": ">=18.17"
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "scripts": {
     "build": "pnpm pack --dry-run",
     "test": "node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "pnpm run test",
     "release": "pnpm publish"
+  },
+  "publishConfig": {
+    "access": "public"
   }
-}
+}

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/pull.mjs

@@ -10,6 +10,7 @@ import {
 import { serializeEnv } from '../env-file.mjs'
 import { writeSecretFile } from '../local-write.mjs'
 import { compareProject, FILE_STATE } from '../status.mjs'
+import { recordSyncedFiles } from '../sync-record.mjs'
 import { CliError, out, pluralize, style } from '../ui.mjs'
 
 /**
@@ -137,6 +138,13 @@ export async function pull(flags, args) {
 
   out()
 
+  // Every file compared is now on both sides — written, already there, or
+  // skipped because it was there with changes — so a later `envs sync` may
+  // treat its disappearance from disk as a deletion.
+  if (!flags['dry-run']) {
+    recordSyncedFiles(context, scope, { synced: comparison.map(file => file.name) })
+  }
+
   if (skipped > 0) {
     out(
       `  ${style.dim('Skipped')} ${pluralize(skipped, 'file')} ${style.dim('with local changes.')}`

package/src/commands/push.mjs

@@ -13,11 +13,14 @@ import {
   ensureSecretDirIgnored,
   ENV_FILES_TARGET,
   lacksIgnoreRule,
+  LINK_FILE,
+  localEnvFiles,
   SECRET_FILE_DIR,
 } from '../project.mjs'
 import { resolveRepoFile } from '../repo-path.mjs'
 import { readSettings } from '../settings.mjs'
 import { compareProject, FILE_STATE } from '../status.mjs'
+import { recordSyncedFiles } from '../sync-record.mjs'
 import { CliError, confirm, isInteractive, out, pad, pluralize, style } from '../ui.mjs'
 
 /**
@@ -62,6 +65,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 +142,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)
 
@@ -209,6 +250,13 @@ export async function push(flags, args) {
 
   out()
 
+  // Every file compared is on both sides once the loop is through — sent up
+  // just now, or already there — so a later `envs sync` may treat its
+  // disappearance from disk as a deletion.
+  if (!flags['dry-run']) {
+    recordSyncedFiles(context, scope, { synced: comparison.map(file => file.name) })
+  }
+
   if (!flags['dry-run'] && pushed > 0) {
     // The shared scope's internal name is not for printing — say what it means.
     const destination = shared ? 'your shared files' : context.project.name

package/src/commands/remove.mjs

@@ -1,5 +1,6 @@
 import { api, ApiError } from '../api.mjs'
 import { resolveContext, SHARED_SCOPE } from '../context.mjs'
+import { recordSyncedFiles } from '../sync-record.mjs'
 import { CliError, out, pluralize, style } from '../ui.mjs'
 
 /**
@@ -58,6 +59,13 @@ export async function remove(flags, args) {
 
   out()
 
+  // Forget them, whether or not the cloud still had them: a file by the same
+  // name that a teammate adds later is new to this machine, not deleted here,
+  // and `envs sync` must pull it rather than remove it again.
+  if (!flags['dry-run']) {
+    recordSyncedFiles(context, scope, { forgotten: [...new Set(args)] })
+  }
+
   if (!flags['dry-run'] && removed > 0) {
     const source = shared ? 'your shared files' : context.project.name
     out(

package/src/commands/sync.mjs

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 
-import { api } from '../api.mjs'
+import { api, ApiError } from '../api.mjs'
 import { formatSize } from '../blob.mjs'
 import {
   cloudKinds,
@@ -13,9 +13,16 @@ import { entriesToMap, mergeEnvText, serializeEnv } from '../env-file.mjs'
 import { writeSecretFile } from '../local-write.mjs'
 import { resolveRepoFile } from '../repo-path.mjs'
 import { compareProject } from '../status.mjs'
+import { readSyncedFiles, recordSyncedFiles } from '../sync-record.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.
@@ -32,9 +39,15 @@ import { announceDiscoveryDirs, confirmNewFiles, fetchCloudFiles, pushOneBlob }
  * copies are left untouched, and the command exits 1. `--prefer local` or
  * `--prefer cloud` resolves them in one direction, as a separate deliberate act.
  *
- * Nothing is ever deleted: sync never prunes, in either direction. A key that
+ * No key is ever deleted: sync never prunes, in either direction. A key that
  * exists on one side only is copied rather than removed, so the worst a wrong
  * guess costs is a key coming back — never one that exists nowhere any more.
+ *
+ * Whole files are different, because for them there is a record: every sync,
+ * pull and push writes down which files this machine had on both sides
+ * afterwards. A file on that record that is now gone from disk was deleted
+ * here, and sync removes it from the cloud. One not on the record is pulled,
+ * as before — a fresh clone has no record and so never deletes anything.
  */
 export async function sync(flags, args) {
   const shared = Boolean(flags.shared)
@@ -70,6 +83,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)),
@@ -83,7 +101,7 @@ export async function sync(flags, args) {
     return 0
   }
 
-  const plans = planSync(comparison, { prefer })
+  const plans = planSync(comparison, { prefer, synced: readSyncedFiles(context, scope) })
   const byName = new Map(comparison.map(file => [file.name, file]))
 
   // The same listing — and, when `confirmNewFiles` is set, the same gate —
@@ -100,7 +118,7 @@ export async function sync(flags, args) {
   out()
 
   const width = Math.max(...plans.map(plan => plan.name.length)) + 2
-  const totals = { pulled: 0, pushed: 0, files: 0 }
+  const totals = { pulled: 0, pushed: 0, removed: 0, files: 0 }
 
   for (const plan of plans) {
     const applied = await applyPlan(flags, context, scope, plan, byName.get(plan.name), localFiles)
@@ -110,10 +128,23 @@ export async function sync(flags, args) {
     if (applied.changed) {
       totals.pulled += applied.pulled
       totals.pushed += applied.pushed
+      totals.removed += plan.action === SYNC_ACTION.DELETE ? 1 : 0
       totals.files += 1
     }
   }
 
+  // Every plan but a deletion leaves the file on both sides — a conflict
+  // included, since both copies stay — so that is what the next run may treat
+  // as "deleted here" if it goes missing. Not under --dry-run: nothing moved.
+  if (!flags['dry-run']) {
+    const removed = plans.filter(plan => plan.action === SYNC_ACTION.DELETE)
+
+    recordSyncedFiles(context, scope, {
+      synced: plans.filter(plan => !removed.includes(plan)).map(plan => plan.name),
+      forgotten: removed.map(plan => plan.name),
+    })
+  }
+
   out()
   renderSummary(flags, plans, totals, prefer)
 
@@ -164,6 +195,10 @@ async function applyPlan(flags, context, scope, plan, file, localFiles) {
     return await pushWholeFile(flags, context, scope, plan, file, localFiles.get(plan.name))
   }
 
+  if (plan.action === SYNC_ACTION.DELETE) {
+    return await deleteWholeFile(flags, context, scope, plan)
+  }
+
   return await mergeOneFile(flags, context, scope, plan, localFiles.get(plan.name) ?? [])
 }
 
@@ -189,6 +224,32 @@ async function pullWholeFile(flags, context, scope, plan) {
   return { changed: true, pulled: count, pushed: 0, detail }
 }
 
+/**
+ * A file this machine had and the developer deleted: the cloud copy goes too.
+ *
+ * "Already gone" is a state, not a failure, exactly as `envs rm` treats it —
+ * a teammate may have removed it first. Either way the file is absent on both
+ * sides afterwards, which is what the record is then told.
+ */
+async function deleteWholeFile(flags, context, scope, plan) {
+  if (!flags['dry-run']) {
+    try {
+      await api.deleteFile(context.host, context.token, scope, plan.name)
+    } catch (error) {
+      if (!(error instanceof ApiError && error.status === 404)) {
+        throw error
+      }
+    }
+  }
+
+  return {
+    changed: true,
+    pulled: 0,
+    pushed: 0,
+    detail: 'removed from the cloud — deleted here since the last sync',
+  }
+}
+
 /** A dotenv file's text on disk, sent with its keys as the server's layout —
  *  or nothing, for a file that is not there to read. */
 function localText(context, name) {
@@ -313,7 +374,11 @@ function render(flags, plan, applied, width) {
   const name = pad(plan.name, width)
 
   if (applied.detail) {
-    const mark = flags['dry-run'] ? style.dim('·') : style.green('✓')
+    const mark = flags['dry-run']
+      ? style.dim('·')
+      : plan.action === SYNC_ACTION.DELETE
+        ? style.red('✗')
+        : style.green('✓')
     const verb = flags['dry-run'] ? 'would be ' : ''
     // Named on the same line as the work that did happen, so a merge that was
     // three-quarters successful does not read as wholly successful.
@@ -366,6 +431,7 @@ function renderSummary(flags, plans, totals, prefer) {
     const moved = [
       totals.pulled > 0 ? `${pluralize(totals.pulled, 'key')} down` : null,
       totals.pushed > 0 ? `${pluralize(totals.pushed, 'key')} up` : null,
+      totals.removed > 0 ? `${pluralize(totals.removed, 'file')} removed from the cloud` : null,
     ].filter(Boolean)
 
     const summary = `${pluralize(totals.files, 'file')}${moved.length > 0 ? ` · ${moved.join(', ')}` : ''}`

package/src/index.mjs

@@ -359,9 +359,13 @@ const COMMAND_HELP = {
   sync: [
     'Reconcile this repo and the cloud in both directions, in one command.',
     '',
-    'Every file and every key that exists on one side only is copied to the',
-    'other. Nothing is ever deleted — sync does not prune in either direction —',
-    'so the worst a wrong guess costs is a key coming back, never one lost.',
+    'Every key that exists on one side only is copied to the other. No key is',
+    'ever pruned, so the worst a wrong guess costs is a key coming back, never',
+    'one lost.',
+    '',
+    'Whole files follow your deletions: a file this machine has synced before',
+    'and you have since deleted is removed from the cloud. A cloud file this',
+    'machine has never had is pulled, so a fresh clone never deletes anything.',
     '',
     'A key that exists on both sides with different values is a conflict: there',
     'is no record of the last sync, so nothing here knows which side moved. Both',
@@ -444,8 +448,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`.

package/src/sync-record.mjs

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeFileAtomic } from './atomic-write.mjs'
+import { configDir } from './config.mjs'
+
+/**
+ * Which files this machine has had on both sides — the record `envs sync`
+ * needs to tell a deletion from a file it has simply never pulled.
+ *
+ * Without it, a file that exists only in the cloud is ambiguous: either this
+ * machine never had it, or it had it and the developer deleted it. The first
+ * wants a pull and the second wants the cloud to follow, and the comparison
+ * alone cannot say which. So every command that leaves a file present on both
+ * sides writes the name down here, and sync reads the note back: a cloud-only
+ * file that is on it was deleted here, and sync removes it from the cloud.
+ *
+ * Per machine, not per repo: it lives beside the credentials rather than in
+ * `.envstash.json`, because "this checkout once had the file" is a fact about
+ * this checkout, and a link file travels with the clone. It is keyed by host,
+ * scope and repo path so a second clone of the same project starts with no
+ * record and pulls — the conservative guess — rather than inheriting the
+ * first clone's history.
+ *
+ * Names only, never values, so the file is as sensitive as the link file. It
+ * is still written `0600` in the `0700` config directory, like everything else
+ * there.
+ */
+export function syncRecordPath() {
+  return join(configDir(), 'synced.json')
+}
+
+/** The names this machine has synced for one host, scope and repo. */
+export function readSyncedFiles(context, scope) {
+  const entry = readRecord()[recordKey(context, scope)]
+
+  if (!entry || typeof entry !== 'object') {
+    return new Set()
+  }
+
+  return new Set(Object.keys(entry))
+}
+
+/**
+ * Note that `synced` are now on both sides, and `forgotten` are not.
+ *
+ * Forgetting matters as much as remembering: a file `envs rm` took out of the
+ * cloud, or sync removed, must not be treated as "deleted here" the next time
+ * a teammate adds a file by the same name.
+ */
+export function recordSyncedFiles(context, scope, { synced = [], forgotten = [] }) {
+  const record = readRecord()
+  const key = recordKey(context, scope)
+  const entry = { ...(record[key] ?? {}) }
+  const now = new Date().toISOString()
+
+  for (const name of synced) {
+    entry[name] = now
+  }
+
+  for (const name of forgotten) {
+    delete entry[name]
+  }
+
+  if (Object.keys(entry).length === 0) {
+    delete record[key]
+  } else {
+    record[key] = entry
+  }
+
+  mkdirSync(configDir(), { recursive: true, mode: 0o700 })
+  writeFileAtomic(syncRecordPath(), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 })
+}
+
+function recordKey(context, scope) {
+  return `${context.host} ${scope} ${context.repoRoot}`
+}
+
+/**
+ * A record that cannot be read counts as empty. Empty is the safe reading —
+ * every cloud-only file becomes a pull — and a corrupt note about past syncs
+ * is not worth failing a sync over.
+ */
+function readRecord() {
+  const path = syncRecordPath()
+
+  if (!existsSync(path)) {
+    return {}
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}
+  } catch {
+    return {}
+  }
+}

package/src/sync.mjs

@@ -17,6 +17,8 @@ export const SYNC_ACTION = {
   MERGE: 'merge',
   /** An opaque file that differs. Bytes do not merge — a human has to choose. */
   CONFLICT: 'conflict',
+  /** This machine had it and no longer does — remove it from the cloud. */
+  DELETE: 'delete',
 }
 
 /** `--prefer` values. */
@@ -27,14 +29,20 @@ export const PREFER = { LOCAL: 'local', CLOUD: 'cloud' }
  *
  * The rule, and the reason for it:
  *
- * There is no record of the last sync, so "which side moved" is unknowable —
- * the same fact that makes `envs status` say `local_only` and `cloud_only`
- * rather than "added" and "deleted". Sync therefore performs the one merge
- * that cannot lose anything: every key that exists on one side only is copied
- * to the other, in whichever direction that implies, and nothing is ever
- * deleted or pruned. When the guess is wrong, the cost is a key coming back
- * that a teammate had removed — visible in the next `envs status`, and fixed
- * with `envs rm` — rather than a secret that exists nowhere any more.
+ * There is no record of the last sync at key level, so "which side moved" is
+ * unknowable — the same fact that makes `envs status` say `local_only` and
+ * `cloud_only` rather than "added" and "deleted". Sync therefore performs the
+ * one merge that cannot lose anything: every key that exists on one side only
+ * is copied to the other, in whichever direction that implies, and no key is
+ * ever pruned. When the guess is wrong, the cost is a key coming back that a
+ * teammate had removed — visible in the next `envs status`, and fixed with
+ * `envs rm` — rather than a secret that exists nowhere any more.
+ *
+ * Whole files are the one place a record does exist. `synced` names the files
+ * this machine has had on both sides (see sync-record.mjs), so a cloud-only
+ * file on that list is not one to pull back: it was deleted here, and the
+ * cloud copy is removed to match. A cloud-only file not on the list is still
+ * pulled — this machine may simply never have had it.
  *
  * A key that exists on both sides with different values is the one case where
  * copying would destroy something, so sync refuses to guess: it is reported as
@@ -42,11 +50,11 @@ export const PREFER = { LOCAL: 'local', CLOUD: 'cloud' }
  * `--prefer cloud` is how a developer says which side wins, and it is
  * deliberately a separate, typed-out act.
  */
-export function planSync(files, { prefer } = {}) {
-  return files.map(file => planFile(file, prefer))
+export function planSync(files, { prefer, synced = new Set() } = {}) {
+  return files.map(file => planFile(file, prefer, synced))
 }
 
-function planFile(file, prefer) {
+function planFile(file, prefer, synced) {
   const plan = {
     name: file.name,
     kind: file.kind,
@@ -64,7 +72,7 @@ function planFile(file, prefer) {
   }
 
   if (file.state === FILE_STATE.CLOUD_ONLY) {
-    return { ...plan, action: SYNC_ACTION.PULL }
+    return { ...plan, action: synced.has(file.name) ? SYNC_ACTION.DELETE : SYNC_ACTION.PULL }
   }
 
   if (file.state === FILE_STATE.UNTRACKED) {
@@ -117,6 +125,7 @@ export function isChanging(plan) {
   return (
     plan.action === SYNC_ACTION.PULL ||
     plan.action === SYNC_ACTION.PUSH ||
+    plan.action === SYNC_ACTION.DELETE ||
     plan.upload.length > 0 ||
     plan.download.length > 0
   )