envstash-cli 0.7.0 → 0.9.0

package/README.md

@@ -119,11 +119,10 @@ definition and therefore has no undo:
   file are left alone, so pushing a partial `.env` cannot destroy a teammate's
   key. Use `--prune` when you do want the cloud to mirror local exactly.
 - **`push` lists new files before uploading them.** Any file that is not in the
-  cloud yet is shown, with its size, before the first upload. Files that
+  cloud yet is shown, with its size, before the first upload, and files that
   discovery found — not named on the command line and not listed in
-  `.envstash.json` — need a yes: `push` asks on a terminal, and anywhere else
-  (CI, a pipe) it stops unless you pass `--yes` (`-y`). Once a file is in the
-  cloud, later pushes of it go through without asking.
+  `.envstash.json` — are marked `(discovered)`. They are then uploaded. To be
+  asked first, turn on [`confirmNewFiles`](#settings).
 - **`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.
@@ -321,15 +320,15 @@ kind wins — a file cannot silently change identity between dotenv and opaque.
 
 ## Configuration
 
-| Variable              | Purpose                                                   |
-| --------------------- | --------------------------------------------------------- |
-| `ENVSTASH_TOKEN`      | Use this token instead of the stored one — for CI         |
-| `ENVSTASH_HOST`       | Target another server (default `https://www.envstash.co`) |
-| `ENVSTASH_PORT`       | Target a dev server on localhost at this port             |
-| `ENVSTASH_CONFIG_DIR` | Where credentials live (default `~/.envstash`)            |
-| `ENVSTASH_DEV`        | Look for a local dev server to log in to                  |
-| `ENVSTASH_DEBUG`      | Print stack traces on failure                             |
-| `NO_COLOR`            | Disable colour (also off automatically when piped)        |
+| Variable              | Purpose                                                     |
+| --------------------- | ----------------------------------------------------------- |
+| `ENVSTASH_TOKEN`      | Use this token instead of the stored one — for CI           |
+| `ENVSTASH_HOST`       | Target another server (default `https://www.envstash.co`)   |
+| `ENVSTASH_PORT`       | Target a dev server on localhost at this port               |
+| `ENVSTASH_CONFIG_DIR` | Where credentials and settings live (default `~/.envstash`) |
+| `ENVSTASH_DEV`        | Look for a local dev server to log in to                    |
+| `ENVSTASH_DEBUG`      | Print stack traces on failure                               |
+| `NO_COLOR`            | Disable colour (also off automatically when piped)          |
 
 In CI, set `ENVSTASH_TOKEN` from your platform's secret store **and set
 `ENVSTASH_HOST`**, then run `envs pull` — no interactive login required.
@@ -342,6 +341,27 @@ checkout, and without this rule a repo could name a server and be handed your
 credential. If a repo pins a host you have not used, the CLI says so and tells
 you the `--host` to pass if you meant it.
 
+### Settings
+
+Preferences for this machine live in `~/.envstash/settings.json` — a separate
+file from `config.json`, which holds your tokens and is not meant to be edited
+by hand. The file is optional; create it to change a default.
+
+```json
+{
+  "confirmNewFiles": true
+}
+```
+
+| Setting           | Default | Purpose                                                                            |
+| ----------------- | ------- | ---------------------------------------------------------------------------------- |
+| `confirmNewFiles` | `false` | Ask before `push` or `sync` uploads a file that discovery found for the first time |
+
+With `confirmNewFiles` on, `push` and `sync` ask on a terminal, and anywhere
+else (CI, a pipe) they stop unless you pass `--yes` (`-y`). Files you named on
+the command line, files listed in `.envstash.json`, and files already in the
+cloud are never asked about.
+
 ### Working against a local server
 
 Every command takes `--port` as shorthand for a server on this machine, so
@@ -406,6 +426,10 @@ second-guessed.
   regenerated rather than reproduced byte for byte: keys come back sorted, and
   comments and blank lines are not preserved. The values themselves round-trip
   exactly, including multi-line values such as PEM keys.
+- `envs push` also sends the file's text, encrypted like the values, so the
+  dashboard's raw view shows the file as you wrote it — comments, blank lines
+  and key order — with the current values in place. An edit that touches only
+  comments is pushed too.
 
 ## License
 

package/package.json

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

package/src/api.mjs

@@ -325,11 +325,13 @@ export const api = {
       headers: { 'x-envstash-file-kinds': 'env,file' },
     }),
 
-  putFile: (host, token, project, file, entries, prune) =>
+  // `layout` is the file's own text, kept server-side so the dashboard can
+  // show the file with its comments and key order. Older servers ignore it.
+  putFile: (host, token, project, file, entries, prune, layout) =>
     request(host, `/api/cli/projects/${encodeURIComponent(project)}/files/${encodePath(file)}`, {
       method: 'PUT',
       token,
-      body: { entries, prune },
+      body: layout === undefined ? { entries, prune } : { entries, prune, layout },
     }),
 
   putBlob: (host, token, project, file, contentBase64) =>

package/src/commands/push.mjs

@@ -1,7 +1,7 @@
-import { statSync } from 'node:fs'
+import { readFileSync, statSync } from 'node:fs'
 
 import { api, ApiError } from '../api.mjs'
-import { formatSize, MAX_BLOB_BYTES } from '../blob.mjs'
+import { digestFileBytes, formatSize, MAX_BLOB_BYTES } from '../blob.mjs'
 import {
   cloudKinds,
   loadLocalFiles,
@@ -11,6 +11,7 @@ import {
 } from '../context.mjs'
 import { ensureSecretDirIgnored, 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 { CliError, confirm, isInteractive, out, pad, pluralize, style } from '../ui.mjs'
 
@@ -87,10 +88,20 @@ export async function push(flags, args) {
 
   out()
 
+  const cloudByName = new Map(cloudFiles.map(file => [file.name, file]))
   let pushed = 0
 
   for (const file of comparison) {
-    if (file.state === FILE_STATE.IN_SYNC && !flags.force) {
+    // A dotenv file's text travels with its keys, so the dashboard can show it
+    // as written — comments, order and all. Read here rather than threaded
+    // through `loadLocalFiles`, whose entries every other command consumes.
+    const layout =
+      file.kind === 'file'
+        ? undefined
+        : readFileSync(resolveRepoFile(context.repoRoot, file.name), 'utf8')
+    const layoutStale = isLayoutStale(cloudByName.get(file.name), layout)
+
+    if (file.state === FILE_STATE.IN_SYNC && !layoutStale && !flags.force) {
       out(`  ${style.dim('=')} ${file.name} ${style.dim('already up to date')}`)
       continue
     }
@@ -119,7 +130,8 @@ export async function push(flags, args) {
       scope,
       file.name,
       entries,
-      Boolean(flags.prune)
+      Boolean(flags.prune),
+      layout
     )
 
     pushed += 1
@@ -145,7 +157,7 @@ export async function push(flags, args) {
     }
 
     if (parts.length === 0) {
-      parts.push(style.dim('no changes'))
+      parts.push(style.dim(layoutStale ? 'comments and layout updated' : 'no changes'))
     }
 
     out(`  ${style.green('✓')} ${file.name}  ${parts.join(style.dim(', '))}`)
@@ -172,18 +184,24 @@ export async function push(flags, args) {
 }
 
 /**
- * Show — and for discovered files, ask about — every file this push would
- * create in the cloud, before the first byte goes up.
+ * Show every file this push would create in the cloud, before the first byte
+ * goes up — and, when the developer has asked to be asked, get a yes for the
+ * ones discovery found.
  *
  * 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.
+ * `.config/`, recursively, and used to upload the lot and only then list it.
+ * The list now always comes first, marking which files were discovered.
  *
- * Asked on a terminal; refused without `--yes` anywhere else, since a CI job
- * cannot answer and silently uploading is the thing being fixed.
+ * Uploading them is the default: a developer who runs `envs push` in their own
+ * repo means "send my files up", and a question on every new file trained the
+ * answer to be `y`. Setting `"confirmNewFiles": true` in
+ * `~/.envstash/settings.json` restores the gate. 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 the gate asks about.
+ *
+ * With the gate on: asked on a terminal; refused without `--yes` anywhere
+ * else, since a CI job cannot answer.
  *
  * `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.
@@ -213,6 +231,10 @@ export async function confirmNewFiles(flags, context, args, comparison, { comman
     return
   }
 
+  if (!readSettings().confirmNewFiles) {
+    return
+  }
+
   const count = pluralize(discovered.length, 'discovered file')
 
   if (isInteractive()) {
@@ -293,6 +315,22 @@ export async function pushOneBlob(flags, context, scope, file, local) {
   return 1
 }
 
+/**
+ * True when the server keeps layouts and its copy of this file's text is not
+ * the local one — a comment or a reordering, which moves no value and so
+ * leaves the file "in sync" by the key comparison alone.
+ *
+ * A server without `layoutDigest` in its listing (before migration 0010)
+ * keeps no layouts, and re-pushing for one would never settle.
+ */
+export function isLayoutStale(cloudFile, layout) {
+  if (layout === undefined || !cloudFile || !('layoutDigest' in cloudFile)) {
+    return false
+  }
+
+  return cloudFile.layoutDigest !== digestFileBytes(Buffer.from(layout, 'utf8'))
+}
+
 export async function fetchCloudFiles(context, scope) {
   try {
     const response = await api.projectStatus(context.host, context.token, scope)

package/src/commands/sync.mjs

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 
 import { api } from '../api.mjs'
 import { formatSize } from '../blob.mjs'
@@ -84,9 +84,9 @@ export async function sync(flags, args) {
   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.
+  // The same listing — and, when `confirmNewFiles` is set, the same gate —
+  // `push` puts in front of a file discovery found on its own. Sync uploads
+  // new files too.
   await confirmNewFiles(flags, context, args, comparison, { command: 'sync' })
 
   out()
@@ -187,6 +187,13 @@ async function pullWholeFile(flags, context, scope, plan) {
   return { changed: true, pulled: count, pushed: 0, detail }
 }
 
+/** 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) {
+  const path = resolveRepoFile(context.repoRoot, name)
+  return existsSync(path) ? readFileSync(path, 'utf8') : undefined
+}
+
 /** 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') {
@@ -202,7 +209,15 @@ async function pushWholeFile(flags, context, scope, plan, file, 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)
+    await api.putFile(
+      context.host,
+      context.token,
+      scope,
+      plan.name,
+      entries,
+      false,
+      localText(context, plan.name)
+    )
   }
 
   return {
@@ -257,7 +272,17 @@ async function mergeOneFile(flags, context, scope, plan, local) {
       .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)
+      // The text as it stands after the download half rewrote it, so the
+      // server's layout is the merged file, not the pre-merge one.
+      await api.putFile(
+        context.host,
+        context.token,
+        scope,
+        plan.name,
+        entries,
+        false,
+        localText(context, plan.name)
+      )
     }
 
     pushed = entries.length

package/src/index.mjs

@@ -288,7 +288,9 @@ function printHelp(topic) {
   )
   out(`    --prefer <side>    ${style.dim('Resolve conflicts as "local" or "cloud" (sync)')}`)
   out(`    --dry-run          ${style.dim('Show what would happen (pull, push, sync, remove)')}`)
-  out(`    -y, --yes          ${style.dim('Upload newly discovered files without asking (push)')}`)
+  out(
+    `    -y, --yes          ${style.dim('Skip the new-file question, if you turned it on (push, sync)')}`
+  )
   out(
     `    --shared           ${style.dim('Target your account-wide shared files (pull, push, sync, remove)')}`
   )
@@ -378,9 +380,10 @@ const COMMAND_HELP = {
     'Keys in the cloud that are absent locally are left alone unless --prune is',
     'given, so pushing a partial .env cannot delete a teammate’s key.',
     '',
-    'Files that would be new in the cloud are listed before anything uploads.',
-    'Ones found by discovery — not named, not in .envstash.json — need a yes:',
-    'asked on a terminal, --yes (-y) anywhere else.',
+    'Files that would be new in the cloud are listed before anything uploads,',
+    'then uploaded. To be asked first about ones found by discovery — not',
+    'named, not in .envstash.json — put { "confirmNewFiles": true } in',
+    '~/.envstash/settings.json; --yes (-y) then answers for one run.',
     '',
     '--shared sends the named files to your account-wide shared files — for',
     'credentials that follow you across projects, like a global .npmrc. Pull',
@@ -388,7 +391,7 @@ const COMMAND_HELP = {
     '',
     '  envs push',
     '  envs push --dry-run',
-    '  envs push --yes             Upload newly discovered files without asking',
+    '  envs push --yes             Skip the new-file question, if you turned it on',
     '  envs push --prune',
     '  envs push --shared .npmrc',
   ],

package/src/settings.mjs

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { configDir } from './config.mjs'
+import { CliError } from './ui.mjs'
+
+/**
+ * Preferences for this machine, next to — and deliberately not inside — the
+ * credential file. `config.json` holds every token and is rewritten by login
+ * and logout; a file meant to be edited by hand should not be one where a
+ * stray comma signs the developer out of everything.
+ *
+ * Per machine rather than per repo: `.envstash.json` travels with a clone, and
+ * how much a developer wants to be asked is theirs to decide, not the repo's.
+ *
+ * {
+ *   "confirmNewFiles": true
+ * }
+ */
+const DEFAULTS = {
+  /** Ask before uploading a file that discovery found for the first time. */
+  confirmNewFiles: false,
+}
+
+export function settingsPath() {
+  return join(configDir(), 'settings.json')
+}
+
+/**
+ * The settings, with defaults for whatever the file does not say — or for a
+ * file that is not there, which is the normal case.
+ *
+ * A value of the wrong type is refused rather than coerced: `"false"` is a
+ * truthy string, and reading it as "yes, ask me" or as "no, don't" would both
+ * be a guess about a safety preference.
+ */
+export function readSettings() {
+  const path = settingsPath()
+
+  if (!existsSync(path)) {
+    return { ...DEFAULTS }
+  }
+
+  let parsed
+
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    throw new CliError(`Could not read ${path} — it is not valid JSON.`, {
+      hint: 'Fix the file, or delete it to go back to the defaults.',
+    })
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new CliError(`${path} must hold a JSON object.`, {
+      hint: 'Example: { "confirmNewFiles": true }',
+    })
+  }
+
+  const settings = { ...DEFAULTS }
+
+  for (const [key, fallback] of Object.entries(DEFAULTS)) {
+    if (!(key in parsed)) {
+      continue
+    }
+
+    if (typeof parsed[key] !== typeof fallback) {
+      throw new CliError(
+        `"${key}" in ${path} must be ${typeof fallback === 'boolean' ? 'true or false' : `a ${typeof fallback}`}.`,
+        { hint: `Example: { "${key}": ${JSON.stringify(!fallback)} }` }
+      )
+    }
+
+    settings[key] = parsed[key]
+  }
+
+  return settings
+}