envstash-cli 0.5.2 → 0.6.0

package/src/commands/push.mjs

@@ -1,3 +1,5 @@
+import { statSync } from 'node:fs'
+
 import { api, ApiError } from '../api.mjs'
 import { formatSize, MAX_BLOB_BYTES } from '../blob.mjs'
 import {
@@ -8,8 +10,9 @@ import {
   SHARED_SCOPE,
 } from '../context.mjs'
 import { ensureSecretDirIgnored, SECRET_FILE_DIR } from '../project.mjs'
+import { resolveRepoFile } from '../repo-path.mjs'
 import { compareProject, FILE_STATE } from '../status.mjs'
-import { CliError, out, pluralize, style } from '../ui.mjs'
+import { CliError, confirm, isInteractive, out, pad, pluralize, style } from '../ui.mjs'
 
 /** Say that .gitignore was edited — quietly rewriting a user's file is worse. */
 export function announceIgnoredSecretDir(repoRoot) {
@@ -80,6 +83,8 @@ export async function push(flags, args) {
     localFiles: new Map(presentNames.map(name => [name, localFiles.get(name)])),
   })
 
+  await confirmNewFiles(flags, context, args, comparison)
+
   out()
 
   let pushed = 0
@@ -121,16 +126,22 @@ export async function push(flags, args) {
 
     const parts = []
 
-    if (result.created) {
-      parts.push(style.green(`${result.created} new`))
+    // Numbers, not whatever the server sent: these are interpolated straight
+    // into the terminal.
+    const created = Number(result.created) || 0
+    const updated = Number(result.updated) || 0
+    const deleted = Number(result.deleted) || 0
+
+    if (created) {
+      parts.push(style.green(`${created} new`))
     }
 
-    if (result.updated) {
-      parts.push(style.yellow(`${result.updated} changed`))
+    if (updated) {
+      parts.push(style.yellow(`${updated} changed`))
     }
 
-    if (result.deleted) {
-      parts.push(style.red(`${result.deleted} deleted`))
+    if (deleted) {
+      parts.push(style.red(`${deleted} deleted`))
     }
 
     if (parts.length === 0) {
@@ -160,12 +171,93 @@ export async function push(flags, args) {
   return 0
 }
 
+/**
+ * Show — and for discovered files, ask about — every file this push would
+ * create in the cloud, before the first byte goes up.
+ *
+ * Discovery sweeps root `.env*` files and everything git-ignored under
+ * `.config/`, recursively, and used to upload the lot and only then list it. A
+ * gcloud token cache or a stray SQLite file was in the cloud before the
+ * developer saw its name. A file already in the cloud, named on the command
+ * line, or listed in `.envstash.json` was chosen by someone; a file discovery
+ * found for the first time was not, so that is the set that needs a yes.
+ *
+ * Asked on a terminal; refused without `--yes` anywhere else, since a CI job
+ * cannot answer and silently uploading is the thing being fixed.
+ *
+ * `envs sync` uploads new files too, and runs the same gate — `command` only
+ * changes which command name the messages tell the developer to re-run.
+ */
+export async function confirmNewFiles(flags, context, args, comparison, { command = 'push' } = {}) {
+  const created = comparison.filter(file => file.state === FILE_STATE.UNTRACKED)
+
+  if (created.length === 0) {
+    return
+  }
+
+  const chosen = new Set([...args, ...(context.link?.files ?? [])])
+  const discovered = created.filter(file => !chosen.has(file.name))
+  const width = Math.max(...created.map(file => file.name.length)) + 2
+
+  out()
+  out(`  ${style.bold(`New in the cloud — ${pluralize(created.length, 'file')}:`)}`)
+
+  for (const file of created) {
+    const note = discovered.includes(file) ? style.dim('  (discovered)') : ''
+    out(
+      `    ${style.green('+')} ${pad(file.name, width)}${style.dim(describeNew(context, file))}${note}`
+    )
+  }
+
+  if (discovered.length === 0 || flags['dry-run'] || flags.yes || flags.y) {
+    return
+  }
+
+  const count = pluralize(discovered.length, 'discovered file')
+
+  if (isInteractive()) {
+    out()
+
+    if (await confirm(`  Upload ${count}? [y/N] `)) {
+      return
+    }
+
+    throw new CliError(`${titleCase(command)} cancelled — nothing was uploaded.`, {
+      hint: `Name the files you want (\`envs ${command} .env.local\`), or list them in .envstash.json.`,
+    })
+  }
+
+  throw new CliError(
+    `Not uploading ${count} without confirmation: ${discovered.map(file => file.name).join(', ')}.`,
+    {
+      hint: `Re-run with --yes to upload them, name the ones you want (\`envs ${command} .env.local\`), or list them in .envstash.json.`,
+    }
+  )
+}
+
+function titleCase(word) {
+  return word.charAt(0).toUpperCase() + word.slice(1)
+}
+
+/** "3 keys, 120 B" or "file, 2.1 KB" — what a new file would put in the cloud. */
+function describeNew(context, file) {
+  let size = ''
+
+  try {
+    size = `, ${formatSize(statSync(resolveRepoFile(context.repoRoot, file.name)).size)}`
+  } catch {
+    // Read a moment ago, so this only fails if it vanished; the name is enough.
+  }
+
+  return file.kind === 'file' ? `file${size}` : `${pluralize(file.counts.local_only, 'key')}${size}`
+}
+
 /**
  * Push one opaque file. Whole-file semantics: no prune, no per-key counts —
  * the report is created / updated / unchanged, with the size, because "what
  * went up" for a blob is the file itself.
  */
-async function pushOneBlob(flags, context, scope, file, local) {
+export async function pushOneBlob(flags, context, scope, file, local) {
   if (local.bytes.length > MAX_BLOB_BYTES) {
     throw new CliError(
       `${file.name} is ${formatSize(local.bytes.length)} — files are capped at ${formatSize(MAX_BLOB_BYTES)}.`,
@@ -201,7 +293,7 @@ async function pushOneBlob(flags, context, scope, file, local) {
   return 1
 }
 
-async function fetchCloudFiles(context, scope) {
+export async function fetchCloudFiles(context, scope) {
   try {
     const response = await api.projectStatus(context.host, context.token, scope)
     return response.files ?? []

package/src/commands/status.mjs

@@ -9,7 +9,7 @@ import {
   KEY_STATE,
   summarize,
 } from '../status.mjs'
-import { out, pad, pluralize, style } from '../ui.mjs'
+import { out, pad, pluralize, sanitize, style } from '../ui.mjs'
 
 const KEY_MARK = {
   [KEY_STATE.MODIFIED]: { mark: '~', color: style.yellow, note: 'local differs' },
@@ -100,7 +100,9 @@ function render(context, files) {
         continue
       }
 
-      out(`      ${mark.color(mark.mark)} ${pad(entry.key, 28)}${style.dim(`(${mark.note})`)}`)
+      out(
+        `      ${mark.color(mark.mark)} ${pad(sanitize(entry.key), 28)}${style.dim(`(${mark.note})`)}`
+      )
     }
   }
 

package/src/commands/sync.mjs

@@ -0,0 +1,371 @@
+import { readFileSync } from 'node:fs'
+
+import { api } from '../api.mjs'
+import { formatSize } from '../blob.mjs'
+import {
+  cloudKinds,
+  loadLocalFiles,
+  resolveContext,
+  resolveFileNames,
+  SHARED_SCOPE,
+} from '../context.mjs'
+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 { conflictExitCode, isBlocked, isChanging, planSync, PREFER, SYNC_ACTION } from '../sync.mjs'
+import { CliError, out, pad, pluralize, sanitize, style } from '../ui.mjs'
+import { announceIgnoredSecretDir, confirmNewFiles, fetchCloudFiles, pushOneBlob } from './push.mjs'
+
+/**
+ * `envs sync` — reconcile this repo with the cloud, in both directions at once.
+ *
+ * `pull` and `push` each ask the developer to have already decided which side
+ * is right. Most of the time neither is: a teammate added a key while you added
+ * a different one, and what you want is both. Sync is that — the union of the
+ * two sides, applied in whichever direction each difference implies.
+ *
+ * What it will not do is choose between two different values for the same key,
+ * because there is no record of the last sync and therefore no way to know
+ * which side moved (the same limit `envs status` acknowledges by saying
+ * `local_only` rather than `added`). Those are reported as conflicts, both
+ * 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
+ * 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.
+ */
+export async function sync(flags, args) {
+  const shared = Boolean(flags.shared)
+
+  if (shared && args.length === 0) {
+    throw new CliError('Syncing shared files needs their names.', {
+      hint: 'Example: envs sync --shared .npmrc',
+    })
+  }
+
+  const prefer = resolvePrefer(flags)
+  const context = resolveContext(flags)
+  const scope = shared ? SHARED_SCOPE : context.project.name
+
+  // Same reasoning as `push`: before discovery, so a file in a not-yet-ignored
+  // .config/ is covered by this run rather than the next one, and never under
+  // --dry-run, because a preview that edits files is not a preview.
+  if (!flags['dry-run']) {
+    announceIgnoredSecretDir(context.repoRoot)
+  }
+
+  const cloudFiles = await fetchCloudFiles(context, scope)
+
+  const names = resolveFileNames({
+    repoRoot: context.repoRoot,
+    link: context.link,
+    cloudFiles,
+    requested: args,
+    // Sync writes as well as reads, so a skipped symlink is reported the way
+    // `pull` reports one.
+    sink: 'write',
+  })
+
+  const localFiles = loadLocalFiles(context.repoRoot, names, cloudKinds(cloudFiles))
+  const comparison = compareProject({
+    cloudFiles: cloudFiles.filter(file => names.includes(file.name)),
+    localFiles,
+  })
+
+  if (comparison.length === 0) {
+    out()
+    out(`  ${style.dim('Nothing to sync — no files found locally or in the cloud.')}`)
+    out()
+    return 0
+  }
+
+  const plans = planSync(comparison, { prefer })
+  const byName = new Map(comparison.map(file => [file.name, file]))
+
+  // The same gate `push` puts in front of a file discovery found on its own.
+  // Sync uploads new files too, and "it synced" is no more of an excuse for a
+  // gcloud token cache reaching the cloud unasked than "it pushed" was.
+  await confirmNewFiles(flags, context, args, comparison, { command: 'sync' })
+
+  out()
+  out(
+    `  ${style.dim(shared ? 'Shared files' : 'Project')} ${style.bold(
+      shared ? 'in your account' : context.project.name
+    )}  ${style.dim(`· ${context.host}`)}`
+  )
+  out()
+
+  const width = Math.max(...plans.map(plan => plan.name.length)) + 2
+  const totals = { pulled: 0, pushed: 0, files: 0 }
+
+  for (const plan of plans) {
+    const applied = await applyPlan(flags, context, scope, plan, byName.get(plan.name), localFiles)
+
+    render(flags, plan, applied, width)
+
+    if (applied.changed) {
+      totals.pulled += applied.pulled
+      totals.pushed += applied.pushed
+      totals.files += 1
+    }
+  }
+
+  out()
+  renderSummary(flags, plans, totals, prefer)
+
+  return conflictExitCode(flags, plans)
+}
+
+/**
+ * `--prefer local` / `--prefer cloud`, validated before anything is fetched.
+ *
+ * A typo here — `--prefer mine` — would otherwise read as "no preference" and
+ * quietly report conflicts the developer believed they had just resolved.
+ */
+function resolvePrefer(flags) {
+  if (!('prefer' in flags)) {
+    return undefined
+  }
+
+  if (flags.prefer === PREFER.LOCAL || flags.prefer === PREFER.CLOUD) {
+    return flags.prefer
+  }
+
+  throw new CliError(`--prefer takes "local" or "cloud", not ${JSON.stringify(flags.prefer)}.`, {
+    hint: 'envs sync --prefer local keeps your values; --prefer cloud keeps the cloud’s.',
+  })
+}
+
+/** What `applyPlan` returns when it did not touch anything. */
+const NOTHING = { changed: false, pulled: 0, pushed: 0, detail: null }
+
+/**
+ * Carry out one file's plan.
+ *
+ * Returns what actually happened rather than printing as it goes, so the report
+ * can be laid out in one place and a dry run produces the same shape without
+ * touching anything. `pulled` and `pushed` count keys and are therefore zero
+ * for an opaque file, which has none; `changed` is what says a file moved.
+ */
+async function applyPlan(flags, context, scope, plan, file, localFiles) {
+  if (plan.action === SYNC_ACTION.NONE || plan.action === SYNC_ACTION.CONFLICT) {
+    return NOTHING
+  }
+
+  if (plan.action === SYNC_ACTION.PULL) {
+    return await pullWholeFile(flags, context, scope, plan)
+  }
+
+  if (plan.action === SYNC_ACTION.PUSH) {
+    return await pushWholeFile(flags, context, scope, plan, file, localFiles.get(plan.name))
+  }
+
+  return await mergeOneFile(flags, context, scope, plan, localFiles.get(plan.name) ?? [])
+}
+
+/** A file the cloud has and disk does not: written whole, exactly as `pull` would. */
+async function pullWholeFile(flags, context, scope, plan) {
+  const response = await api.getFile(context.host, context.token, scope, plan.name)
+
+  // Branching on the response's own kind, not the local guess: the server is
+  // the authority on what it stored.
+  const isBlob = response.kind === 'file'
+  const body = isBlob
+    ? Buffer.from(response.contentBase64 ?? '', 'base64')
+    : serializeEnv(response.entries ?? [])
+  const count = isBlob ? 0 : (response.entries?.length ?? 0)
+  const detail = isBlob
+    ? `new from the cloud (file, ${formatSize(body.length)})`
+    : `new from the cloud (${pluralize(count, 'key')})`
+
+  if (!flags['dry-run']) {
+    writeSecretFile(context.repoRoot, plan.name, body)
+  }
+
+  return { changed: true, pulled: count, pushed: 0, detail }
+}
+
+/** A file on disk the cloud has never seen — or one `--prefer local` settles. */
+async function pushWholeFile(flags, context, scope, plan, file, local) {
+  if (plan.kind === 'file') {
+    // `pushOneBlob` enforces the size cap and prints its own line, so nothing
+    // is reported for it here.
+    await pushOneBlob(flags, context, scope, file, local)
+
+    return { changed: true, pulled: 0, pushed: 0, detail: null }
+  }
+
+  const entries = local ?? []
+
+  if (!flags['dry-run']) {
+    // Never prune. Sync's whole contract is that it does not delete, and this
+    // path also runs for `--prefer local` on a file that already exists.
+    await api.putFile(context.host, context.token, scope, plan.name, entries, false)
+  }
+
+  return {
+    changed: true,
+    pulled: 0,
+    pushed: entries.length,
+    detail: `sent up (${pluralize(entries.length, 'key')})`,
+  }
+}
+
+/**
+ * Both sides moved: copy each side's keys to the other.
+ *
+ * The local file is edited in place rather than regenerated — `mergeEnvText`
+ * keeps its comments and layout — because a merge has an opinion about a few
+ * keys and none at all about the rest of the file.
+ */
+async function mergeOneFile(flags, context, scope, plan, local) {
+  const localValues = entriesToMap(local)
+  let pulled = 0
+  let pushed = 0
+
+  if (plan.download.length > 0) {
+    const response = await api.getFile(context.host, context.token, scope, plan.name)
+    const cloudValues = entriesToMap(response.entries ?? [])
+
+    // A key the status listing promised but the file no longer has is dropped,
+    // not written as an empty string: the two calls are not one transaction.
+    const changes = plan.download
+      .filter(key => cloudValues.has(key))
+      .map(key => ({ key, value: cloudValues.get(key) }))
+
+    if (changes.length > 0 && !flags['dry-run']) {
+      const path = resolveRepoFile(context.repoRoot, plan.name)
+
+      writeSecretFile(
+        context.repoRoot,
+        plan.name,
+        mergeEnvText(readFileSync(path, 'utf8'), changes)
+      )
+    }
+
+    pulled = changes.length
+  }
+
+  if (plan.upload.length > 0) {
+    // Only the keys this merge decided on — not the whole local file. Pushing
+    // everything would overwrite the cloud's value for every conflicting key,
+    // which is precisely the decision sync refuses to make on its own.
+    const entries = plan.upload
+      .filter(key => localValues.has(key))
+      .map(key => ({ key, value: localValues.get(key) }))
+
+    if (entries.length > 0 && !flags['dry-run']) {
+      await api.putFile(context.host, context.token, scope, plan.name, entries, false)
+    }
+
+    pushed = entries.length
+  }
+
+  const parts = []
+
+  if (pulled > 0) {
+    parts.push(`${pluralize(pulled, 'key')} pulled`)
+  }
+
+  if (pushed > 0) {
+    parts.push(`${pluralize(pushed, 'key')} pushed`)
+  }
+
+  return {
+    changed: pulled > 0 || pushed > 0,
+    pulled,
+    pushed,
+    detail: parts.join(', ') || null,
+  }
+}
+
+/** One line per file, plus an indented line per conflicting key. */
+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 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.
+    const note =
+      plan.conflicts.length > 0
+        ? `${style.dim(' · ')}${style.yellow(pluralize(plan.conflicts.length, 'conflict'))}`
+        : ''
+
+    out(`  ${mark} ${name}${style.dim(`${verb}${applied.detail}`)}${note}`)
+  } else if (!isChanging(plan) && !isBlocked(plan)) {
+    out(`  ${style.dim('=')} ${name}${style.dim('already in sync')}`)
+  }
+
+  if (plan.action === SYNC_ACTION.CONFLICT) {
+    out(
+      `  ${style.yellow('!')} ${name}${style.yellow('conflict')} ${style.dim(
+        '— the file differs on both sides and its contents do not merge'
+      )}`
+    )
+    return
+  }
+
+  if (plan.conflicts.length === 0) {
+    return
+  }
+
+  if (!applied.detail) {
+    out(
+      `  ${style.yellow('!')} ${name}${style.yellow(pluralize(plan.conflicts.length, 'conflict'))}`
+    )
+  }
+
+  for (const key of plan.conflicts) {
+    out(
+      `      ${style.yellow('~')} ${pad(sanitize(key), 28)}${style.dim('(differs on both sides)')}`
+    )
+  }
+}
+
+function renderSummary(flags, plans, totals, prefer) {
+  const blocked = plans.filter(isBlocked)
+
+  if (totals.files === 0 && blocked.length === 0) {
+    out(`  ${style.dim('Everything is already in sync.')}`)
+    out()
+    return
+  }
+
+  if (totals.files > 0) {
+    const moved = [
+      totals.pulled > 0 ? `${pluralize(totals.pulled, 'key')} down` : null,
+      totals.pushed > 0 ? `${pluralize(totals.pushed, 'key')} up` : null,
+    ].filter(Boolean)
+
+    const summary = `${pluralize(totals.files, 'file')}${moved.length > 0 ? ` · ${moved.join(', ')}` : ''}`
+
+    out(`  ${style.dim(flags['dry-run'] ? `Would sync ${summary}.` : `Synced ${summary}.`)}`)
+  }
+
+  if (blocked.length === 0) {
+    out()
+    return
+  }
+
+  out(
+    `  ${style.yellow(pluralize(blocked.length, 'file'))} ${style.dim(
+      'left alone — the same key holds different values on each side.'
+    )}`
+  )
+
+  // Nothing to suggest when they already said which side wins and the answer
+  // is still "it conflicts" — that only happens for an opaque file, and there
+  // --prefer did settle it.
+  if (!prefer) {
+    out(
+      `  ${style.dim('See them with')} envs diff${style.dim(', then choose a side:')} ` +
+        `envs sync --prefer local ${style.dim('or')} envs sync --prefer cloud`
+    )
+  }
+
+  out()
+}

package/src/config.mjs

@@ -1,7 +1,8 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 
+import { writeFileAtomic } from './atomic-write.mjs'
 import { CliError } from './ui.mjs'
 
 /**
@@ -53,31 +54,73 @@ export function readConfig() {
 /**
  * Write credentials with 0600 on the file and 0700 on the directory.
  *
- * The mode is set explicitly after writing rather than relying on the process
- * umask: a permissive umask (common in containers and CI images) would otherwise
- * leave a long-lived token world-readable.
+ * The mode is set explicitly rather than relying on the process umask: a
+ * permissive umask (common in containers and CI images) would otherwise leave a
+ * long-lived token world-readable. Atomic, because this one file holds every
+ * token on the machine, and writing it in place meant a crash mid-write lost
+ * all of them.
  */
 export function writeConfig(config) {
   const dir = configDir()
 
   mkdirSync(dir, { recursive: true, mode: 0o700 })
 
-  const path = configPath()
-  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  writeFileAtomic(configPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
 
   try {
     chmodSync(dir, 0o700)
-    chmodSync(path, 0o600)
   } catch {
     // Windows and some network filesystems do not support POSIX modes. The
     // write already succeeded; permissions are best-effort there.
   }
 }
 
-/** Normalize a host so `envstash.co`, with a trailing slash, and https all agree. */
+/**
+ * Normalize a host so `envstash.co`, with a trailing slash, and https all agree.
+ *
+ * Plain `http://` is refused except on this machine. Every request carries a
+ * bearer token and most carry secrets, so a typo'd `--host http://…` or a cloned
+ * repo's link file saying so would otherwise send both across the network in the
+ * clear. A dev server on localhost is the one legitimate use, and it never
+ * leaves the machine.
+ */
 export function normalizeHost(host) {
-  const withScheme = /^https?:\/\//i.test(host) ? host : `https://${host}`
-  return withScheme.replace(/\/+$/, '')
+  const raw = String(host)
+
+  if (/[\u0000-\u001f\u007f-\u009f]/.test(raw)) {
+    throw new CliError('Refusing a server address that contains control characters.', {
+      hint: 'Check --host, ENVSTASH_HOST, and the host in .envstash.json.',
+    })
+  }
+
+  const withScheme = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`
+  const normalized = withScheme.replace(/\/+$/, '')
+
+  if (/^http:/i.test(normalized) && !isLoopbackUrl(normalized)) {
+    throw new CliError(`Refusing to use ${normalized} over plain http.`, {
+      hint: 'Use https:// — plain http is only allowed for localhost, where nothing leaves this machine.',
+    })
+  }
+
+  return normalized
+}
+
+/** localhost, *.localhost, 127.0.0.0/8 and ::1 — the addresses that stay on this machine. */
+export function isLoopbackUrl(url) {
+  let hostname
+
+  try {
+    hostname = new URL(url).hostname.toLowerCase()
+  } catch {
+    return false
+  }
+
+  return (
+    hostname === 'localhost' ||
+    hostname.endsWith('.localhost') ||
+    hostname === '[::1]' ||
+    /^127(?:\.\d{1,3}){3}$/.test(hostname)
+  )
 }
 
 /**