envstash-cli 0.1.0

package/src/commands/status.mjs

@@ -0,0 +1,149 @@
+import { api, ApiError } from '../api.mjs'
+import { loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
+import {
+  compareProject,
+  driftExitCode,
+  FILE_STATE,
+  isOutOfSync,
+  KEY_STATE,
+  summarize,
+} from '../status.mjs'
+import { out, pad, pluralize, style } from '../ui.mjs'
+
+const KEY_MARK = {
+  [KEY_STATE.MODIFIED]: { mark: '~', color: style.yellow, note: 'local differs' },
+  [KEY_STATE.LOCAL_ONLY]: { mark: '+', color: style.green, note: 'local only' },
+  [KEY_STATE.CLOUD_ONLY]: { mark: '-', color: style.red, note: 'cloud only' },
+}
+
+/**
+ * `envs status` — every file in the cloud account against what is on disk.
+ *
+ * Only key names and value digests cross the wire, so this is safe to run in a
+ * shared terminal or pipe into a CI log: it can tell you a value changed without
+ * ever knowing what the value is.
+ */
+export async function status(flags, args) {
+  const context = resolveContext(flags)
+  const cloudFiles = await fetchCloudFiles(context)
+
+  const names = resolveFileNames({
+    repoRoot: context.repoRoot,
+    link: context.link,
+    cloudFiles,
+    requested: args,
+  })
+
+  const localFiles = loadLocalFiles(context.repoRoot, names)
+  const files = compareProject({
+    cloudFiles: cloudFiles.filter(file => names.includes(file.name)),
+    localFiles,
+  })
+
+  if (flags.json) {
+    out(JSON.stringify({ project: context.project.name, host: context.host, files }, null, 2))
+    return driftExitCode(flags, files)
+  }
+
+  render(context, files)
+
+  return driftExitCode(flags, files)
+}
+
+/**
+ * A project that does not exist yet is not an error for `status` — it is the
+ * normal state of a repo before its first push, and reporting it as a failure
+ * would make `envs status` useless as a "what would happen if I pushed" check.
+ */
+async function fetchCloudFiles(context) {
+  try {
+    const response = await api.projectStatus(context.host, context.token, context.project.name)
+    return response.files ?? []
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404) {
+      return []
+    }
+
+    throw error
+  }
+}
+
+function render(context, files) {
+  const totals = summarize(files)
+
+  out()
+  out(
+    `  ${style.dim('Project')} ${style.bold(context.project.name)}  ${style.dim(
+      `· ${context.host}`
+    )}${context.project.source === 'guess' ? style.dim('  (guessed from the repo name)') : ''}`
+  )
+  out()
+
+  if (files.length === 0) {
+    out(`  ${style.dim('No env files found locally or in the cloud.')}`)
+    out()
+    out(`  ${style.dim('Create some, then run')} envs push`)
+    out()
+    return
+  }
+
+  const width = Math.max(...files.map(file => file.name.length)) + 2
+
+  for (const file of files) {
+    out(`  ${pad(style.bold(file.name), width)}${fileSummary(file)}`)
+
+    for (const entry of file.keys) {
+      const mark = KEY_MARK[entry.state]
+
+      if (!mark) {
+        continue
+      }
+
+      out(`      ${mark.color(mark.mark)} ${pad(entry.key, 28)}${style.dim(`(${mark.note})`)}`)
+    }
+  }
+
+  out()
+  out(
+    `  ${style.dim(
+      `${pluralize(totals.files, 'file')} · ${totals.same} in sync · ` +
+        `${totals.modified} changed · ${totals.local_only} local-only · ${totals.cloud_only} cloud-only`
+    )}`
+  )
+  out()
+
+  if (isOutOfSync(files)) {
+    out(`  ${style.dim('Run')} envs diff ${style.dim('to inspect, or')} envs pull / envs push`)
+    out()
+  }
+}
+
+function fileSummary(file) {
+  if (file.state === FILE_STATE.CLOUD_ONLY) {
+    return `${style.red('cloud only')} ${style.dim(`— ${pluralize(file.counts.cloud_only, 'key')}, not on disk`)}`
+  }
+
+  if (file.state === FILE_STATE.UNTRACKED) {
+    return `${style.green('untracked')} ${style.dim(`— ${pluralize(file.counts.local_only, 'key')}, not in the cloud`)}`
+  }
+
+  if (file.state === FILE_STATE.IN_SYNC) {
+    return style.dim(`up to date (${pluralize(file.counts.same, 'key')})`)
+  }
+
+  const parts = []
+
+  if (file.counts.modified) {
+    parts.push(style.yellow(`${file.counts.modified} changed`))
+  }
+
+  if (file.counts.local_only) {
+    parts.push(style.green(`${file.counts.local_only} local-only`))
+  }
+
+  if (file.counts.cloud_only) {
+    parts.push(style.red(`${file.counts.cloud_only} cloud-only`))
+  }
+
+  return parts.join(style.dim(', '))
+}

package/src/config.mjs

@@ -0,0 +1,188 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { CliError } from './ui.mjs'
+
+/**
+ * The canonical origin, www and not the apex: envstash.co 308-redirects to
+ * www.envstash.co, and fetch drops the Authorization header when a redirect
+ * crosses origins. Pointing at the apex therefore signs in fine and then fails
+ * every authenticated call with a 401.
+ */
+export const DEFAULT_HOST = 'https://www.envstash.co'
+
+/** Where credentials live. Overridable so tests never touch a real ~/.envstash. */
+export function configDir() {
+  return process.env.ENVSTASH_CONFIG_DIR ?? join(homedir(), '.envstash')
+}
+
+export function configPath() {
+  return join(configDir(), 'config.json')
+}
+
+/**
+ * Credentials are keyed by host so a developer can be signed in to production
+ * and a local dev server at the same time without one clobbering the other.
+ *
+ * {
+ *   "defaultHost": "https://www.envstash.co",
+ *   "hosts": { "https://www.envstash.co": { "token": "envs_…", "email": "…" } }
+ * }
+ */
+export function readConfig() {
+  const path = configPath()
+
+  if (!existsSync(path)) {
+    return { defaultHost: DEFAULT_HOST, hosts: {} }
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    return {
+      defaultHost: parsed.defaultHost ?? DEFAULT_HOST,
+      hosts: parsed.hosts ?? {},
+    }
+  } catch {
+    throw new CliError(`Could not read ${path} — it is not valid JSON.`, {
+      hint: 'Delete the file and run `envs login` again.',
+    })
+  }
+}
+
+/**
+ * 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.
+ */
+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 })
+
+  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. */
+export function normalizeHost(host) {
+  const withScheme = /^https?:\/\//i.test(host) ? host : `https://${host}`
+  return withScheme.replace(/\/+$/, '')
+}
+
+/**
+ * Resolve which host to talk to. Explicit flag beats environment, which beats
+ * the stored default — the usual precedence, so `--host` always wins.
+ */
+export function resolveHost(flagHost) {
+  if (flagHost) {
+    return normalizeHost(flagHost)
+  }
+
+  if (process.env.ENVSTASH_HOST) {
+    return normalizeHost(process.env.ENVSTASH_HOST)
+  }
+
+  return normalizeHost(readConfig().defaultHost)
+}
+
+/**
+ * The token for a host. `ENVSTASH_TOKEN` wins so CI can inject a token without
+ * running an interactive login.
+ *
+ * `allowEnvToken` is how the confused deputy is closed. Stored tokens have
+ * always been keyed by host, so an unknown host simply has none — but the
+ * environment token used to be returned for *any* host, which meant a
+ * `.envstash.json` that came with a cloned repo could name a server and be
+ * handed CI's production credential. Callers that resolved the host from a repo
+ * file pass false; nothing else changes.
+ */
+export function getToken(host, { allowEnvToken = true } = {}) {
+  if (allowEnvToken && process.env.ENVSTASH_TOKEN) {
+    return process.env.ENVSTASH_TOKEN
+  }
+
+  return readConfig().hosts[host]?.token ?? null
+}
+
+export function requireToken(host, { allowEnvToken = true } = {}) {
+  const token = getToken(host, { allowEnvToken })
+
+  if (!token) {
+    if (!allowEnvToken && process.env.ENVSTASH_TOKEN) {
+      throw new CliError(`Refusing to send ENVSTASH_TOKEN to ${host}.`, {
+        hint: `.envstash.json in this repo chose that host. Pass --host ${host} if you meant it.`,
+      })
+    }
+
+    throw new CliError(`Not signed in to ${host}.`, { hint: 'Run `envs login` first.' })
+  }
+
+  return token
+}
+
+/**
+ * Store a credential.
+ *
+ * `makeDefault` exists so a host that a repo file chose cannot quietly become
+ * the default for every other repo on the machine. Signing in somewhere is a
+ * deliberate act; being pointed somewhere by a file you cloned is not.
+ */
+export function saveToken(host, token, email, { makeDefault = true } = {}) {
+  const config = readConfig()
+
+  config.hosts[host] = { token, email }
+
+  if (makeDefault) {
+    config.defaultHost = host
+  }
+
+  writeConfig(config)
+}
+
+export function clearToken(host) {
+  const config = readConfig()
+
+  if (!config.hosts[host]) {
+    return false
+  }
+
+  delete config.hosts[host]
+  writeConfig(config)
+
+  return true
+}
+
+/** True when the developer has signed in to this host before. */
+export function isKnownHost(host) {
+  return Boolean(readConfig().hosts[host])
+}
+
+export function getStoredEmail(host) {
+  return readConfig().hosts[host]?.email ?? null
+}
+
+/** Remove the whole credential file. Backs `envs logout --all`. */
+export function clearAllCredentials() {
+  const path = configPath()
+
+  if (!existsSync(path)) {
+    return false
+  }
+
+  rmSync(path)
+
+  return true
+}
+
+export { dirname }

package/src/context.mjs

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync } from 'node:fs'
+
+import { parseEnvFile } from './env-file.mjs'
+import { discoverEnvFiles, findRepoRoot, readLink, resolveProject } from './project.mjs'
+import { resolveInsideRepo } from './repo-path.mjs'
+import { requireHostToken } from './session.mjs'
+import { errOut, pluralize, style } from './ui.mjs'
+
+/**
+ * Everything the sync commands need, resolved once: which server, which token,
+ * which repo, which project.
+ */
+export function resolveContext(flags) {
+  const { host, token } = requireHostToken(flags)
+  const repoRoot = findRepoRoot()
+  const link = readLink(repoRoot)
+  const project = resolveProject(repoRoot, flags.project)
+
+  return { host, token, repoRoot, link, project }
+}
+
+/**
+ * Decide which files this command covers.
+ *
+ * Explicit arguments win. Otherwise the link file's list is authoritative if
+ * present — an explicit list is the only way to include a nested path like
+ * `apps/web/.env.local`, which discovery does not scan for. With no link file,
+ * fall back to the union of local `.env*` files and whatever the cloud holds.
+ */
+export function resolveFileNames({ repoRoot, link, cloudFiles, requested }) {
+  if (requested?.length) {
+    return check([...new Set(requested)].sort())
+  }
+
+  if (link?.files?.length) {
+    return check([...new Set(link.files)].sort())
+  }
+
+  const names = new Set([...discoverEnvFiles(repoRoot), ...cloudFiles.map(file => file.name)])
+
+  return check([...names].sort())
+}
+
+/**
+ * Validate the whole set before any of it is used.
+ *
+ * Refusing rather than silently dropping: a name that escapes the repo is
+ * either a server doing something it has no business doing or a link file that
+ * came with someone else's repo, and both are worth stopping the command for.
+ * Checked here so a bad name never reaches the disk, the network, or the
+ * comparison.
+ */
+function check(names) {
+  for (const name of names) {
+    resolveInsideRepo('/', name)
+  }
+
+  return names
+}
+
+/**
+ * Read the named files off disk. A missing file maps to null rather than being
+ * skipped, so the comparison can distinguish "not on disk" from "empty".
+ */
+export function loadLocalFiles(repoRoot, names) {
+  const files = new Map()
+
+  for (const name of names) {
+    // Resolved rather than joined: `join` happily walks out of the repo, and
+    // this is the read side of the same hole `pull` had on the write side.
+    const path = resolveInsideRepo(repoRoot, name)
+
+    if (!existsSync(path)) {
+      files.set(name, null)
+      continue
+    }
+
+    const { entries, skipped } = parseEnvFile(readFileSync(path, 'utf8'))
+
+    files.set(name, entries)
+
+    if (skipped.length > 0) {
+      warnUnreadableLines(name, entries, skipped)
+    }
+  }
+
+  return files
+}
+
+/**
+ * Say out loud that part of a file was not understood.
+ *
+ * It belongs here rather than in each command because this is the one place a
+ * local file is read, and every sync command comes through it. To stderr, so
+ * the warning is visible on a terminal without getting mixed into the report
+ * that `envs status > report.txt` is meant to capture.
+ */
+function warnUnreadableLines(name, entries, skipped) {
+  const shown = skipped.length > 10 ? `${skipped.slice(0, 10).join(', ')}, …` : skipped.join(', ')
+  const where = `${skipped.length === 1 ? 'Line' : 'Lines'} ${shown}`
+
+  errOut()
+
+  if (entries.length === 0) {
+    errOut(`  ${style.yellow('!')} ${name} has no ${style.bold('KEY=value')} lines — it is empty`)
+    errOut(`      ${style.dim(`as far as EnvStash is concerned. ${where} could not be read.`)}`)
+  } else {
+    errOut(
+      `  ${style.yellow('!')} ${name}: ${pluralize(skipped.length, 'line')} not in ` +
+        `${style.bold('KEY=value')} form, skipped.`
+    )
+    errOut(
+      `      ${style.dim(`${where}. Nothing on ${skipped.length === 1 ? 'it' : 'them'} is synced.`)}`
+    )
+  }
+
+  errOut()
+}

package/src/dev-host.mjs

@@ -0,0 +1,84 @@
+/**
+ * Find the local dev server, so `envs login` in this repo prints an "Open …"
+ * link pointing at the server the developer is actually running.
+ *
+ * Without this, `pnpm cli:dev login` opens production, the approval lands
+ * against production, and the token saved is a production token — all of which
+ * looks like it worked. Detecting the dev server is what makes the dev script
+ * mean "dev".
+ */
+import { DEFAULT_HOST } from './config.mjs'
+
+/**
+ * The ports `scripts/dev-with-port.mjs` hands out, which are in turn the ports
+ * registered as callback URLs on the GitHub App. Keep the three lists in step:
+ * an unregistered port does not fail at startup, it fails at login.
+ */
+export const DEV_PORTS = [3000, 3001, 3002, 3003]
+
+/** Short enough that probing four closed ports is not a visible pause. */
+const PROBE_TIMEOUT_MS = 400
+
+/**
+ * A dev server is identified by the CLI's own health endpoint answering in the
+ * documented error shape, not by the port being open.
+ *
+ * Anything can hold 3000 — another framework's dev server, a stale container —
+ * and pointing the login at it would turn "no dev server running" into a
+ * confusing failure several steps later, after the browser has already opened.
+ */
+async function isEnvstashServer(origin, timeoutMs) {
+  try {
+    const response = await fetch(`${origin}/api/cli/whoami`, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+
+    // Unauthenticated by design: no token is sent, so an EnvStash server answers
+    // 401 in the shape every CLI route uses.
+    if (response.status !== 401) {
+      return false
+    }
+
+    const body = await response.json()
+
+    return body?.error === 'unauthorized'
+  } catch {
+    // Connection refused, timeout, HTML where JSON was expected — all the same
+    // answer: there is no EnvStash dev server on this port.
+    return false
+  }
+}
+
+/**
+ * First dev port answering as an EnvStash server, or null when none do.
+ *
+ * Probed in order rather than in parallel: the ports express a preference, and
+ * whichever one a developer's primary server claimed should win over a second
+ * server they left running in another terminal.
+ */
+export async function detectDevHost({ ports = DEV_PORTS, timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+  for (const port of ports) {
+    const origin = `http://localhost:${port}`
+
+    if (await isEnvstashServer(origin, timeoutMs)) {
+      return origin
+    }
+  }
+
+  return null
+}
+
+/**
+ * Whether to look for a dev server at all.
+ *
+ * Opt-in on purpose. Detection that ran for every user would mean a stray
+ * process on port 3000 could silently redirect a production login, so the
+ * default stays production and the repo's own `cli:dev` script asks for dev.
+ */
+export function isDevMode(flags) {
+  return Boolean(flags?.dev) || Boolean(process.env.ENVSTASH_DEV)
+}
+
+/** The host used when dev mode finds nothing — production, the last resort. */
+export const FALLBACK_HOST = DEFAULT_HOST