envstash-cli 0.1.0

package/src/env-file.mjs

@@ -0,0 +1,243 @@
+import { createHash } from 'node:crypto'
+
+import { CliError } from './ui.mjs'
+
+/**
+ * Parse a `.env` file into ordered key/value entries.
+ *
+ * This follows the dotenv conventions developers already expect:
+ *
+ *   KEY=value                 unquoted, trimmed, trailing `# comment` stripped
+ *   KEY="value"               double-quoted, \n \r \t \\ \" escapes expanded
+ *   KEY='value'               single-quoted, entirely literal
+ *   export KEY=value          the `export ` prefix is ignored
+ *   KEY=                      empty string
+ *   # comment                 skipped
+ *
+ * Quoted values may span multiple lines, which matters because private keys and
+ * certificates are routinely stored that way and a line-at-a-time parser silently
+ * truncates them.
+ *
+ * Later assignments win, matching how a shell sources a file.
+ */
+export function parseEnv(contents) {
+  return parseEnvFile(contents).entries
+}
+
+/**
+ * `parseEnv`, plus the 1-based numbers of the lines it could not read.
+ *
+ * Skipping a stray line is the right default — see below — but doing it
+ * silently is not, because the degenerate case is invisible: a `.env` that is
+ * actually JavaScript (`export const A = 'b'`) parses to zero entries, and
+ * `push` then reports a perfectly successful push of nothing at all. Callers
+ * use `skipped` to say so. Line numbers rather than line contents: a line the
+ * parser rejected may still hold a secret.
+ */
+export function parseEnvFile(contents) {
+  const entries = []
+  const skipped = []
+  const seen = new Map()
+
+  let index = 0
+  let lineNumber = 1
+  const text = contents.replace(/^/, '')
+
+  while (index < text.length) {
+    const lineEnd = findLineEnd(text, index)
+    const line = text.slice(index, lineEnd)
+    const trimmed = line.trim()
+
+    if (trimmed === '' || trimmed.startsWith('#')) {
+      index = lineEnd + 1
+      lineNumber += 1
+      continue
+    }
+
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*/.exec(line)
+
+    if (!match) {
+      // Not an assignment. Skip rather than fail: a `.env` with a stray line is
+      // still worth reading, and refusing to parse would block `envs status`
+      // over something cosmetic.
+      skipped.push(lineNumber)
+      index = lineEnd + 1
+      lineNumber += 1
+      continue
+    }
+
+    const key = match[1]
+    const valueStart = index + match[0].length
+    const quote = text[valueStart]
+
+    let value
+    let nextIndex
+
+    if (quote === '"' || quote === "'") {
+      const parsed = readQuoted(text, valueStart, quote)
+      value = parsed.value
+      nextIndex = findLineEnd(text, parsed.endIndex) + 1
+    } else {
+      const raw = text.slice(valueStart, lineEnd)
+      value = stripInlineComment(raw).trim()
+      nextIndex = lineEnd + 1
+    }
+
+    if (seen.has(key)) {
+      entries[seen.get(key)].value = value
+    } else {
+      seen.set(key, entries.length)
+      entries.push({ key, value })
+    }
+
+    // Counted rather than incremented: a quoted value may have spanned several
+    // lines, and a later skipped line has to report the number a human sees.
+    lineNumber += countNewlines(text, index, nextIndex)
+    index = nextIndex
+  }
+
+  return { entries, skipped }
+}
+
+function findLineEnd(text, from) {
+  const newline = text.indexOf('\n', from)
+  return newline === -1 ? text.length : newline
+}
+
+function countNewlines(text, from, to) {
+  let count = 0
+
+  for (let index = from; index < to && index < text.length; index += 1) {
+    if (text[index] === '\n') {
+      count += 1
+    }
+  }
+
+  return count
+}
+
+/**
+ * Read a quoted value starting at the opening quote. Returns the decoded value
+ * and the index just past the closing quote. An unterminated quote consumes to
+ * end of input rather than throwing — same reasoning as the skipped-line case.
+ */
+function readQuoted(text, start, quote) {
+  let value = ''
+  let index = start + 1
+
+  while (index < text.length) {
+    const char = text[index]
+
+    if (char === '\\' && quote === '"') {
+      const next = text[index + 1]
+      value += unescape(next)
+      index += 2
+      continue
+    }
+
+    if (char === quote) {
+      return { value, endIndex: index + 1 }
+    }
+
+    value += char
+    index += 1
+  }
+
+  return { value, endIndex: index }
+}
+
+function unescape(char) {
+  switch (char) {
+    case 'n':
+      return '\n'
+    case 'r':
+      return '\r'
+    case 't':
+      return '\t'
+    case '\\':
+      return '\\'
+    case '"':
+      return '"'
+    case undefined:
+      return '\\'
+    default:
+      return `\\${char}`
+  }
+}
+
+/**
+ * Strip a trailing `# comment` from an unquoted value.
+ *
+ * The `#` only starts a comment when preceded by whitespace or at the start, so
+ * a value like `pass#word` survives intact — losing half a password to a comment
+ * rule is the kind of bug that costs an afternoon.
+ */
+function stripInlineComment(raw) {
+  for (let index = 0; index < raw.length; index += 1) {
+    if (raw[index] !== '#') {
+      continue
+    }
+
+    if (index === 0 || /\s/.test(raw[index - 1])) {
+      return raw.slice(0, index)
+    }
+  }
+
+  return raw
+}
+
+/** True when a value cannot be written bare and must be quoted. */
+function needsQuoting(value) {
+  return value === '' || /[\s"'#\\$`]/.test(value)
+}
+
+/**
+ * A shell-safe environment variable name — the same grammar the server enforces
+ * in `isValidKey`.
+ *
+ * Values are escaped on the way out, but the key was interpolated raw, so a key
+ * containing a newline let whoever supplied it write arbitrary lines into the
+ * file. That matters because the entries handed to `envs pull` come from the
+ * server, not from the developer.
+ */
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** Serialize entries back to `.env` text. Round-trips with `parseEnv`. */
+export function serializeEnv(entries) {
+  const lines = entries.map(({ key, value }) => {
+    if (!KEY_PATTERN.test(key)) {
+      throw new CliError(`Refusing to write the key ${JSON.stringify(String(key))}.`, {
+        hint: 'An environment variable name must be letters, digits and underscores.',
+      })
+    }
+
+    if (!needsQuoting(value)) {
+      return `${key}=${value}`
+    }
+
+    const escaped = value
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, '\\n')
+      .replace(/\r/g, '\\r')
+
+    return `${key}="${escaped}"`
+  })
+
+  return lines.length > 0 ? `${lines.join('\n')}\n` : ''
+}
+
+/**
+ * The digest `envs status` compares against the server's.
+ *
+ * Must stay byte-identical to `valueDigest` in src/lib/crypto.ts — the whole
+ * comparison rests on both sides hashing the same way.
+ */
+export function digestValue(value) {
+  return createHash('sha256').update(value, 'utf8').digest('hex').slice(0, 12)
+}
+
+/** Entries as a Map, for lookup-heavy code like the status comparison. */
+export function entriesToMap(entries) {
+  return new Map(entries.map(entry => [entry.key, entry.value]))
+}

package/src/index.mjs

@@ -0,0 +1,299 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { diff } from './commands/diff.mjs'
+import { login, logout } from './commands/login.mjs'
+import { init, link, list, whoami } from './commands/misc.mjs'
+import { pull } from './commands/pull.mjs'
+import { push } from './commands/push.mjs'
+import { status } from './commands/status.mjs'
+import { DEFAULT_HOST } from './config.mjs'
+import { CLI_ALIASES, CLI_COMMAND_PAD, CLI_COMMANDS, CLI_ENV_VARS } from './manifest.mjs'
+import { CliError, errOut, out, style } from './ui.mjs'
+
+/**
+ * Flags that take a value. Everything else is a boolean, which is what lets
+ * `--force` and `--project my-app` be parsed without a schema per command.
+ */
+const VALUE_FLAGS = new Set(['host', 'project', 'label'])
+
+/** The implementation of each command, by name. */
+const HANDLERS = { login, logout, whoami, init, link, list, status, diff, pull, push }
+
+/**
+ * Summaries and aliases come from the manifest rather than being repeated here,
+ * so `envs --help` and the dashboard's CLI page cannot describe different
+ * products. A name in the manifest with no handler is a startup error below,
+ * which is the failure mode worth having: loud, immediate, and impossible to
+ * ship past.
+ */
+const COMMANDS = Object.fromEntries(
+  CLI_COMMANDS.map(command => {
+    const run = HANDLERS[command.name]
+
+    if (!run) {
+      throw new Error(`manifest.mjs lists "${command.name}" but no handler implements it`)
+    }
+
+    return [command.name, { run, summary: command.summary }]
+  })
+)
+
+const ALIASES = CLI_ALIASES
+
+/**
+ * Parse argv into flags and positionals.
+ *
+ * Everything after `--` is treated as a positional, so a file literally named
+ * `--weird` can still be addressed.
+ */
+export function parseArgs(argv) {
+  const flags = {}
+  const args = []
+
+  let index = 0
+  let literal = false
+
+  while (index < argv.length) {
+    const token = argv[index]
+
+    if (literal) {
+      args.push(token)
+      index += 1
+      continue
+    }
+
+    if (token === '--') {
+      literal = true
+      index += 1
+      continue
+    }
+
+    if (token.startsWith('--')) {
+      const [name, inlineValue] = splitFlag(token.slice(2))
+
+      if (VALUE_FLAGS.has(name)) {
+        flags[name] = inlineValue ?? argv[index + 1]
+        index += inlineValue === undefined ? 2 : 1
+        continue
+      }
+
+      flags[name] = inlineValue === undefined ? true : inlineValue
+      index += 1
+      continue
+    }
+
+    if (token.startsWith('-') && token.length > 1) {
+      flags[token.slice(1)] = true
+      index += 1
+      continue
+    }
+
+    args.push(token)
+    index += 1
+  }
+
+  return { flags, args }
+}
+
+function splitFlag(text) {
+  const equals = text.indexOf('=')
+
+  return equals === -1 ? [text, undefined] : [text.slice(0, equals), text.slice(equals + 1)]
+}
+
+function version() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url))
+    return JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version
+  } catch {
+    return '0.0.0'
+  }
+}
+
+export async function run(argv) {
+  const { flags, args } = parseArgs(argv)
+  const [name, ...rest] = args
+
+  if (flags.version || flags.v || name === 'version') {
+    out(version())
+    return finish(0)
+  }
+
+  if (!name || flags.help || flags.h || name === 'help') {
+    printHelp(rest[0] ?? (name === 'help' ? rest[0] : undefined))
+    return finish(name && name !== 'help' ? 0 : 0)
+  }
+
+  const resolved = ALIASES[name] ?? name
+  const command = COMMANDS[resolved]
+
+  if (!command) {
+    errOut(`envs: unknown command "${name}"`)
+    errOut(`Run ${style.bold('envs --help')} to see the available commands.`)
+    return finish(1)
+  }
+
+  try {
+    const code = await command.run(flags, rest)
+    return finish(code ?? 0)
+  } catch (error) {
+    if (error instanceof CliError) {
+      errOut()
+      errOut(`  ${style.red('✗')} ${error.message}`)
+
+      if (error.hint) {
+        errOut(`    ${style.dim(error.hint)}`)
+      }
+
+      errOut()
+      return finish(error.exitCode ?? 1)
+    }
+
+    errOut()
+    errOut(`  ${style.red('✗')} ${error?.message ?? 'Unexpected error'}`)
+    errOut()
+
+    if (process.env.ENVSTASH_DEBUG) {
+      errOut(error?.stack ?? '')
+    } else {
+      errOut(`  ${style.dim('Set ENVSTASH_DEBUG=1 for a stack trace.')}`)
+      errOut()
+    }
+
+    return finish(1)
+  }
+}
+
+/**
+ * Set the exit code rather than calling process.exit, so buffered stdout is
+ * flushed before the process ends. `process.exit` truncates output when stdout
+ * is a pipe — which is exactly the case when someone runs `envs status | less`.
+ */
+function finish(code) {
+  process.exitCode = code
+  return code
+}
+
+function printHelp(topic) {
+  if (topic && COMMANDS[ALIASES[topic] ?? topic]) {
+    printCommandHelp(ALIASES[topic] ?? topic)
+    return
+  }
+
+  out()
+  out(`  ${style.bold('envstash')} ${style.dim(`v${version()}`)} — keep your .env files in sync`)
+  out()
+  out(`  ${style.dim('Usage:')} envs <command> [files…] [options]`)
+  out()
+  out(`  ${style.bold('Commands')}`)
+
+  for (const [name, command] of Object.entries(COMMANDS)) {
+    out(`    ${name.padEnd(CLI_COMMAND_PAD)}${style.dim(command.summary)}`)
+  }
+
+  out()
+  out(`  ${style.bold('Common options')}`)
+  out(`    --project <name>   ${style.dim('Target a project other than the linked one')}`)
+  out(`    --host <url>       ${style.dim('Target another EnvStash server')}`)
+  out(`    --json             ${style.dim('Machine-readable output (status, list, whoami)')}`)
+  out(`    --exit-zero        ${style.dim('Always exit 0, even when out of sync (status, diff)')}`)
+  out(`    --dry-run          ${style.dim('Show what would happen (pull, push)')}`)
+  out(`    --dev              ${style.dim('Log in to a local dev server if one is running')}`)
+  out()
+  out(`  ${style.bold('Environment')}`)
+
+  const envPad =
+    CLI_ENV_VARS.reduce((widest, variable) => Math.max(widest, variable.name.length), 0) + 2
+
+  for (const variable of CLI_ENV_VARS) {
+    out(`    ${variable.name.padEnd(envPad)}${style.dim(variable.purpose(DEFAULT_HOST))}`)
+  }
+
+  out()
+  out(`  ${style.dim('Run')} envs help <command> ${style.dim('for details on one command.')}`)
+  out()
+}
+
+const COMMAND_HELP = {
+  status: [
+    'Compare every file in your cloud account against what is on disk.',
+    '',
+    'Only key names and value digests are sent — never plaintext — so this is',
+    'safe to run in a shared terminal or a CI log.',
+    '',
+    'Exits 1 when anything is out of sync, so a hook or a CI job catches drift',
+    'without extra flags. Pass --exit-zero in scripts that must not fail.',
+    '',
+    '  envs status                 Compare every tracked file',
+    '  envs status .env.local      Compare one file',
+    '  envs status --json          Machine-readable output',
+    '  envs status --exit-zero     Always exit 0',
+  ],
+  diff: [
+    'Show which keys differ and what they differ to.',
+    '',
+    'Values are masked by default; --show-values reveals them.',
+    '',
+    'Like status, exits 1 when anything is out of sync; --exit-zero opts out.',
+    '',
+    '  envs diff',
+    '  envs diff --show-values',
+    '  envs diff .env.production',
+  ],
+  pull: [
+    'Write the cloud’s version of each file to disk.',
+    '',
+    'Files with local changes are skipped unless --force is given, because a',
+    'git-ignored .env that gets overwritten has no undo.',
+    '',
+    '  envs pull',
+    '  envs pull --dry-run',
+    '  envs pull --force',
+  ],
+  push: [
+    'Send local files to the cloud.',
+    '',
+    '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.',
+    '',
+    '  envs push',
+    '  envs push --dry-run',
+    '  envs push --prune',
+  ],
+  login: [
+    'Authorize this machine using a browser device code.',
+    '',
+    '  envs login',
+    '  envs login --no-browser     Print the URL instead of opening it',
+    '  envs login --host <url>     Sign in to another server',
+  ],
+  logout: [
+    'Revoke this machine’s token and remove it locally.',
+    '',
+    '  envs logout',
+    '  envs logout --all           Remove credentials for every host',
+  ],
+  init: [
+    'Create a project and write .envstash.json linking this repo to it.',
+    '',
+    '  envs init                   Name it after the git remote',
+    '  envs init my-app',
+  ],
+  link: ['Link this repo to a project that already exists.', '', '  envs link my-app'],
+  list: ['List every project in your account.', '', '  envs list', '  envs list --json'],
+  whoami: ['Show which account this machine is signed in as.', '', '  envs whoami'],
+}
+
+function printCommandHelp(name) {
+  out()
+  out(`  ${style.bold(`envs ${name}`)} — ${COMMANDS[name].summary}`)
+  out()
+
+  for (const line of COMMAND_HELP[name] ?? []) {
+    out(line ? `  ${line}` : '')
+  }
+
+  out()
+}

package/src/manifest.mjs

@@ -0,0 +1,68 @@
+/**
+ * The single description of what the CLI offers.
+ *
+ * This list was previously written out four times — in the CLI's own help, in
+ * the dashboard's CLI page, and in two READMEs — which is three opportunities
+ * for the product to describe a command it no longer has. Everything that
+ * renders a command list or an environment table now derives it from here:
+ *
+ *   packages/cli/src/index.mjs    `envs --help`
+ *   src/config/cli/cli-manifest   the typed view the dashboard renders
+ *
+ * Plain ESM with no dependencies, because the CLI ships as plain ESM with no
+ * dependencies and the app can import it; the reverse is not true.
+ */
+
+/** @typedef {{ name: string, summary: string, aliases?: string[] }} CommandSpec */
+
+/** @type {CommandSpec[]} */
+export const CLI_COMMANDS = [
+  { name: 'login', summary: 'Authorize this machine against your account', aliases: ['sign-in'] },
+  { name: 'logout', summary: 'Revoke this machine’s token', aliases: ['sign-out'] },
+  { name: 'whoami', summary: 'Show the signed-in account' },
+  { name: 'init', summary: 'Create a project and link this repo to it' },
+  { name: 'link', summary: 'Link this repo to an existing project' },
+  { name: 'list', summary: 'List every project in your account', aliases: ['ls'] },
+  { name: 'status', summary: 'Compare cloud files against local files', aliases: ['st'] },
+  { name: 'diff', summary: 'Show which keys differ, and how' },
+  { name: 'pull', summary: 'Write the cloud’s version of each file to disk' },
+  { name: 'push', summary: 'Send local files to the cloud' },
+]
+
+/**
+ * Alias -> canonical name, built from the same list the help text is built from,
+ * so an alias can never be advertised without being routable.
+ *
+ * @type {Record<string, string>}
+ */
+export const CLI_ALIASES = Object.fromEntries(
+  CLI_COMMANDS.flatMap(command => (command.aliases ?? []).map(alias => [alias, command.name]))
+)
+
+/** @typedef {{ name: string, purpose: string }} EnvVarSpec */
+
+/**
+ * `purpose` takes the default host as an argument rather than baking it in, so
+ * the dashboard can render its own domain and the CLI can render the one it
+ * ships with, from one sentence.
+ *
+ * @type {Array<{ name: string, purpose: (defaultHost: string) => string }>}
+ */
+export const CLI_ENV_VARS = [
+  { name: 'ENVSTASH_TOKEN', purpose: () => 'Use this token instead of the stored one — for CI' },
+  { name: 'ENVSTASH_HOST', purpose: host => `Target another server (default ${host})` },
+  {
+    name: 'ENVSTASH_CONFIG_DIR',
+    purpose: () => 'Where credentials live (default ~/.envstash)',
+  },
+  {
+    name: 'ENVSTASH_DEV',
+    purpose: () => 'Log in to a local dev server when one is running (same as --dev)',
+  },
+  { name: 'ENVSTASH_DEBUG', purpose: () => 'Print stack traces on failure' },
+  { name: 'NO_COLOR', purpose: () => 'Disable colour (also off automatically when piped)' },
+]
+
+/** Widest command name, so help output can align without a magic number. */
+export const CLI_COMMAND_PAD =
+  CLI_COMMANDS.reduce((widest, command) => Math.max(widest, command.name.length), 0) + 2