envstash-cli 0.5.2 → 0.6.0

package/src/sync.mjs

@@ -0,0 +1,137 @@
+import { FILE_STATE, KEY_STATE } from './status.mjs'
+
+/**
+ * What `envs sync` decided to do about one file.
+ *
+ * `MERGE` is the interesting one and the reason the command exists: both sides
+ * moved, and neither is wholly right.
+ */
+export const SYNC_ACTION = {
+  /** Already identical. */
+  NONE: 'none',
+  /** Only the cloud has it — write it to disk. */
+  PULL: 'pull',
+  /** Only disk has it — send it up. */
+  PUSH: 'push',
+  /** Both sides moved; copy each side's additions to the other. */
+  MERGE: 'merge',
+  /** An opaque file that differs. Bytes do not merge — a human has to choose. */
+  CONFLICT: 'conflict',
+}
+
+/** `--prefer` values. */
+export const PREFER = { LOCAL: 'local', CLOUD: 'cloud' }
+
+/**
+ * Decide what sync does, for a whole comparison. Pure: no network, no disk.
+ *
+ * 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.
+ *
+ * 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
+ * a conflict and both sides are left exactly as they are. `--prefer local` or
+ * `--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))
+}
+
+function planFile(file, prefer) {
+  const plan = {
+    name: file.name,
+    kind: file.kind,
+    action: SYNC_ACTION.NONE,
+    /** Keys to send up. */
+    upload: [],
+    /** Keys to bring down. */
+    download: [],
+    /** Keys that differ on both sides and nobody has chosen between. */
+    conflicts: [],
+  }
+
+  if (file.state === FILE_STATE.IN_SYNC) {
+    return plan
+  }
+
+  if (file.state === FILE_STATE.CLOUD_ONLY) {
+    return { ...plan, action: SYNC_ACTION.PULL }
+  }
+
+  if (file.state === FILE_STATE.UNTRACKED) {
+    return { ...plan, action: SYNC_ACTION.PUSH }
+  }
+
+  // DIFFERS. An opaque file has no keys to merge — half a certificate is not a
+  // certificate — so the whole file is the unit, and the whole file is the
+  // conflict until someone names a winner.
+  if (file.kind === 'file') {
+    if (prefer === PREFER.LOCAL) {
+      return { ...plan, action: SYNC_ACTION.PUSH }
+    }
+
+    if (prefer === PREFER.CLOUD) {
+      return { ...plan, action: SYNC_ACTION.PULL }
+    }
+
+    return { ...plan, action: SYNC_ACTION.CONFLICT }
+  }
+
+  const keysIn = state => file.keys.filter(entry => entry.state === state).map(entry => entry.key)
+  const modified = keysIn(KEY_STATE.MODIFIED)
+
+  const upload = keysIn(KEY_STATE.LOCAL_ONLY)
+  const download = keysIn(KEY_STATE.CLOUD_ONLY)
+
+  if (prefer === PREFER.LOCAL) {
+    upload.push(...modified)
+  } else if (prefer === PREFER.CLOUD) {
+    download.push(...modified)
+  }
+
+  return {
+    ...plan,
+    action: SYNC_ACTION.MERGE,
+    upload: upload.sort(),
+    download: download.sort(),
+    conflicts: prefer ? [] : modified,
+  }
+}
+
+/** True when this file needs a decision sync will not make on its own. */
+export function isBlocked(plan) {
+  return plan.action === SYNC_ACTION.CONFLICT || plan.conflicts.length > 0
+}
+
+/** True when the plan would touch anything at all. */
+export function isChanging(plan) {
+  return (
+    plan.action === SYNC_ACTION.PULL ||
+    plan.action === SYNC_ACTION.PUSH ||
+    plan.upload.length > 0 ||
+    plan.download.length > 0
+  )
+}
+
+/**
+ * Exit 1 when a conflict is left unresolved, the way `status` and `diff` exit 1
+ * on drift: sync having run is not the same as the repo being in sync, and a
+ * hook or a CI job should hear the difference. `--exit-zero` opts out, as it
+ * does there.
+ */
+export function conflictExitCode(flags, plans) {
+  if (flags['exit-zero']) {
+    return 0
+  }
+
+  return plans.some(isBlocked) ? 1 : 0
+}

package/src/ui.mjs

@@ -1,3 +1,5 @@
+import { createInterface } from 'node:readline'
+
 /**
  * Terminal output helpers.
  *
@@ -71,20 +73,97 @@ export function fail(message, options) {
 }
 
 /**
- * Mask a secret for display: keep a little of the head and tail so a human can
- * recognise which value it is, hide the middle. Short values are hidden whole —
- * showing 2 of 6 characters of a PIN is worse than showing none.
+ * Mask a secret for display: a little of the head, so a human can tell which
+ * value it is, and the length. Never the tail — the end of a key is often the
+ * part a provider prints as its fingerprint, and head plus tail together gave
+ * away 8 characters of every secret on screen. Short values are hidden whole,
+ * length included — showing 2 of 6 characters of a PIN, or that it has 6, is
+ * worse than showing nothing.
  */
+const MASK = '•'.repeat(8)
+
 export function maskValue(value) {
   if (value === '') {
     return style.dim('(empty)')
   }
 
   if (value.length <= 12) {
-    return style.dim('•'.repeat(8))
+    return style.dim(MASK)
   }
 
-  return `${value.slice(0, 4)}${style.dim('•'.repeat(8))}${value.slice(-4)}`
+  return `${sanitize(value.slice(0, 4))}${style.dim(`${MASK} (${value.length} chars)`)}`
+}
+
+/**
+ * Terminal control sequences, whole: CSI (`ESC [ … final`), OSC and the other
+ * string commands (`ESC ] … BEL` or `… ESC \\`), and two-byte escapes. Removed
+ * as units so a stripped sequence does not leave its `[2J` behind as litter.
+ */
+const ESCAPE_SEQUENCE =
+  /\u001b(?:\[[0-?]*[ -/]*[@-~]|[\]PX^_][^\u0007\u001b]*(?:\u0007|\u001b\\)?|[@-Z\\-_]?)/g
+
+/**
+ * Everything else a terminal acts on rather than prints: C0 controls, DEL, the
+ * C1 range (U+009B is a one-character CSI), and the Unicode line separators and
+ * bidi overrides that can reorder or break a line visually.
+ */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g
+
+/**
+ * Make a string safe to print when someone else chose it.
+ *
+ * Key names, error messages and account details come from the server, and a
+ * hostile one could otherwise send escape sequences that clear the screen and
+ * draw a convincing "all in sync" over the real output. Newlines become spaces
+ * by default, because a forged line is the attack; pass `{ newlines: true }`
+ * where a line break is meant.
+ */
+export function sanitize(text, { newlines = false } = {}) {
+  const stripped = String(text ?? '').replace(ESCAPE_SEQUENCE, '')
+
+  return stripped.replace(CONTROL, char => {
+    if (char === '\n') {
+      return newlines ? '\n' : ' '
+    }
+
+    return char === '\t' ? ' ' : ''
+  })
+}
+
+/**
+ * True when a human is there to answer a question: both ends are a terminal.
+ * Checking stdin alone is not enough — `envs push > log.txt` has a keyboard but
+ * no screen to show the question on.
+ */
+export function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY)
+}
+
+/**
+ * Ask a yes/no question; anything but y or yes is no.
+ *
+ * Resolves false if input ends before an answer (Ctrl-D, a closed pipe), so an
+ * unanswered question can never be read as consent.
+ */
+export async function confirm(question, { input = process.stdin, output = process.stdout } = {}) {
+  const rl = createInterface({ input, output })
+
+  return await new Promise(resolve => {
+    let answered = false
+
+    rl.once('close', () => {
+      if (!answered) {
+        output.write('\n')
+        resolve(false)
+      }
+    })
+
+    rl.question(question, answer => {
+      answered = true
+      rl.close()
+      resolve(/^y(es)?$/i.test(answer.trim()))
+    })
+  })
 }
 
 /** Pad to a display width, ignoring colour codes. */