envstash-cli 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# envstash
+
+Keep your `.env` files in sync with your EnvStash account, with commands that
+behave the way `git` taught you to expect.
+
+```bash
+pnpm add -g envstash-cli
+```
+
+Ships two binaries — `envstash` and the short form `envs`. They are the same
+program.
+
+## Quick start
+
+```bash
+envs login          # authorize this machine in the browser
+envs init           # create a project, named after your git remote
+envs push           # send your .env files up
+```
+
+On another machine, or a fresh clone:
+
+```bash
+envs pull
+```
+
+## Commands
+
+| Command  | What it does                                      |
+| -------- | ------------------------------------------------- |
+| `login`  | Authorize this machine with a browser device code |
+| `logout` | Revoke this machine's token                       |
+| `whoami` | Show the signed-in account                        |
+| `init`   | Create a project and link this repo to it         |
+| `link`   | Link this repo to a project that already exists   |
+| `list`   | List every project in your account                |
+| `status` | Compare cloud files against local files           |
+| `diff`   | Show which keys differ, and how                   |
+| `pull`   | Write the cloud's version of each file to disk    |
+| `push`   | Send local files to the cloud                     |
+
+Run `envs help <command>` for details on any one of them.
+
+## `envs status`
+
+Checks every file in your cloud account against what is on disk.
+
+```
+$ envs status
+
+  Project demo-app  · https://www.envstash.co
+
+  .env.local       1 changed, 1 local-only, 1 cloud-only
+      - PORT                        (cloud only)
+      ~ SESSION_SECRET              (local differs)
+      + SMTP_PASSWORD               (local only)
+  .env.production  up to date (2 keys)
+
+  2 files · 4 in sync · 1 changed · 1 local-only · 1 cloud-only
+```
+
+| Mark | Meaning                                            |
+| ---- | -------------------------------------------------- |
+| `~`  | The key exists on both sides with different values |
+| `+`  | The key exists only on disk                        |
+| `-`  | The key exists only in the cloud                   |
+
+**No secret values are sent during a status check.** The server returns key
+names and a truncated SHA-256 digest of each value; the CLI hashes your local
+values and compares. That makes `envs status` safe to run on a shared screen or
+pipe into a CI log — it can tell you a value changed without either side
+transmitting what it is.
+
+### Exit codes
+
+`envs status` exits **1 when anything is out of sync** and 0 when everything
+matches, so a pre-commit hook or a CI job catches drift with no extra flags:
+
+```bash
+envs status || echo "your .env has drifted from the cloud"
+```
+
+This deliberately differs from `git status`, which always exits 0 and makes
+signalling opt-in via `git diff --exit-code`. Drift in a secrets store is
+something you almost always want to be told about loudly.
+
+Pass `--exit-zero` when a script must not fail on drift — most often inside a
+shell running under `set -e`:
+
+```bash
+envs status --exit-zero
+```
+
+`envs diff` follows the same rule. `--exit-code` is still accepted and is now a
+no-op, since it names the default.
+
+## Safety defaults
+
+Both sync directions are conservative, because a `.env` file is git-ignored by
+definition and therefore has no undo:
+
+- **`pull` skips files with local changes.** Use `--force` to overwrite.
+- **`push` never deletes.** Keys in the cloud that are absent from your local
+  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.
+- **`diff` masks values.** Use `--show-values` to reveal them.
+- Pulled files are written `0600`, and `~/.envstash/config.json` is `0600`
+  inside a `0700` directory.
+
+Preview either direction with `--dry-run`.
+
+## Project linking
+
+`envs init` writes `.envstash.json` in your repo root:
+
+```json
+{
+  "project": "demo-app",
+  "files": [".env.local", ".env.production"]
+}
+```
+
+**Commit this file.** It contains no secrets — only the project name and which
+files to track — and it is what lets a teammate clone the repo and run
+`envs pull` with no further setup.
+
+Without a link file the CLI guesses the project from your git remote's repo
+name and discovers `.env*` files in the repo root. Files ending in `.example`,
+`.sample`, `.template`, and `.dist` are ignored, since those are meant to be
+committed and hold placeholder values.
+
+Monorepos can track nested paths by listing them explicitly:
+
+```json
+{ "project": "my-monorepo", "files": ["apps/web/.env.local", "apps/api/.env"] }
+```
+
+## 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_CONFIG_DIR` | Where credentials live (default `~/.envstash`)            |
+| `ENVSTASH_DEV`        | Log in to a local dev server when one is running          |
+| `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.
+
+Naming the host is what keeps the token yours. `ENVSTASH_TOKEN` is only sent to
+a host the environment chose (`ENVSTASH_HOST` or `--host`) or one you have
+signed in to before — never to a host that `.envstash.json` asked for. That file
+is committed, so on a fork build or an untrusted branch it arrives with the
+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.
+
+### Logging in to a local server
+
+`envs login --dev` (or `ENVSTASH_DEV=1`) looks for an EnvStash dev server on
+ports 3000, 3001, 3002 and 3003 and logs in to the first one that answers, so the
+link it opens points at the server you are running rather than production.
+Production is the fallback when none answer, and an explicit `--host` always
+wins over detection.
+
+A port is only accepted if it responds as an EnvStash server, so an unrelated
+process holding 3000 is skipped rather than logged in to.
+
+## Notes
+
+- Requires Node 18.17 or newer.
+- Zero runtime dependencies.
+- Values are stored per key, not per file. A pulled file is therefore
+  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.
+
+## License
+
+MIT

package/bin/envs.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// `envs` is the short form of `envstash`. Both bins are declared in package.json
+// so npm links each one; this is a real executable, not a shell alias, which
+// means it also works from CI and from npx.
+import { run } from '../src/index.mjs'
+
+await run(process.argv.slice(2))

package/bin/envstash.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/index.mjs'
+
+await run(process.argv.slice(2))

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "envstash-cli",
+  "version": "0.1.0",
+  "description": "Git-style CLI for EnvStash — keep your .env files in sync with your cloud account.",
+  "keywords": [
+    "env",
+    "dotenv",
+    "secrets",
+    "environment-variables",
+    "cli",
+    "envstash"
+  ],
+  "homepage": "https://envstash.co",
+  "bugs": "https://github.com/masaok/envstash-next/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/masaok/envstash-next.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "envstash": "bin/envstash.mjs",
+    "envs": "bin/envs.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm pack --dry-run",
+    "test": "node --test \"test/*.test.mjs\"",
+    "release": "pnpm publish"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,155 @@
+import { CliError } from './ui.mjs'
+
+/** An error the server described in its JSON body. */
+export class ApiError extends CliError {
+  constructor(status, code, message, hint) {
+    super(message, { hint })
+    this.name = 'ApiError'
+    this.status = status
+    this.code = code
+  }
+}
+
+/**
+ * One request to the EnvStash API.
+ *
+ * Errors are normalized here so commands never branch on status codes: the
+ * server always answers failures with `{ error, message }`, and anything that
+ * is not JSON (a proxy error page, a 502 from the edge) is reported as a
+ * transport problem rather than crashing on a parse.
+ */
+export async function request(host, path, { method = 'GET', token, body, signal } = {}) {
+  const headers = { accept: 'application/json' }
+
+  if (token) {
+    headers.authorization = `Bearer ${token}`
+  }
+
+  if (body !== undefined) {
+    headers['content-type'] = 'application/json'
+  }
+
+  let response
+
+  try {
+    response = await fetch(`${host}${path}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal,
+    })
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw error
+    }
+
+    throw new CliError(`Could not reach ${host}.`, {
+      hint: 'Check your connection, or pass --host if you meant a different server.',
+    })
+  }
+
+  const text = await response.text()
+  let payload = null
+
+  if (text) {
+    try {
+      payload = JSON.parse(text)
+    } catch {
+      payload = null
+    }
+  }
+
+  if (!response.ok) {
+    // A 401 on a request that *did* carry a token, after a redirect to another
+    // origin, is almost never a stale token: fetch strips the Authorization
+    // header when a redirect crosses origins, so the server never saw it. Say
+    // that instead of sending the user round the login loop again.
+    const crossOriginRedirect =
+      token && response.status === 401 && redirectedAcrossOrigin(host, response)
+
+    if (crossOriginRedirect) {
+      throw new ApiError(
+        401,
+        'unauthorized',
+        `${host} redirected to ${crossOriginRedirect}, which drops the credentials.`,
+        `Use --host ${crossOriginRedirect} (or set ENVSTASH_HOST) — a redirect across origins strips the Authorization header.`
+      )
+    }
+
+    if (!payload?.message) {
+      throw new ApiError(
+        response.status,
+        'http_error',
+        `${host}${path} returned HTTP ${response.status}.`
+      )
+    }
+
+    throw new ApiError(
+      response.status,
+      payload.error ?? 'error',
+      payload.message,
+      response.status === 401 ? 'Run `envs login` to sign in again.' : undefined
+    )
+  }
+
+  return payload ?? {}
+}
+
+/**
+ * The origin a request ended up on, when following redirects moved it off the
+ * origin it started on. Returns null otherwise — including when the response
+ * carries no URL, as the stubbed responses in the tests do.
+ */
+function redirectedAcrossOrigin(host, response) {
+  if (!response.redirected || !response.url) {
+    return null
+  }
+
+  try {
+    const finalOrigin = new URL(response.url).origin
+
+    return finalOrigin === new URL(host).origin ? null : finalOrigin
+  } catch {
+    return null
+  }
+}
+
+export const api = {
+  startDeviceAuth: (host, label) =>
+    request(host, '/api/cli/auth/device', { method: 'POST', body: { label } }),
+
+  pollDeviceAuth: (host, deviceCode, signal) =>
+    request(host, '/api/cli/auth/token', { method: 'POST', body: { deviceCode }, signal }),
+
+  logout: (host, token) => request(host, '/api/cli/auth/logout', { method: 'POST', token }),
+
+  whoami: (host, token) => request(host, '/api/cli/whoami', { token }),
+
+  listProjects: (host, token) => request(host, '/api/cli/projects', { token }),
+
+  createProject: (host, token, name) =>
+    request(host, '/api/cli/projects', { method: 'POST', token, body: { name } }),
+
+  projectStatus: (host, token, project) =>
+    request(host, `/api/cli/projects/${encodeURIComponent(project)}/status`, { token }),
+
+  getFile: (host, token, project, file) =>
+    request(host, `/api/cli/projects/${encodeURIComponent(project)}/files/${encodePath(file)}`, {
+      token,
+    }),
+
+  putFile: (host, token, project, file, entries, prune) =>
+    request(host, `/api/cli/projects/${encodeURIComponent(project)}/files/${encodePath(file)}`, {
+      method: 'PUT',
+      token,
+      body: { entries, prune },
+    }),
+}
+
+/** Encode each path segment but keep the "/" separators that address a nested file. */
+function encodePath(file) {
+  return file
+    .split('/')
+    .map(segment => encodeURIComponent(segment))
+    .join('/')
+}

package/src/commands/diff.mjs

@@ -0,0 +1,137 @@
+import { api, ApiError } from '../api.mjs'
+import { loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
+import { entriesToMap } from '../env-file.mjs'
+import { compareProject, driftExitCode, FILE_STATE, KEY_STATE } from '../status.mjs'
+import { maskValue, out, style } from '../ui.mjs'
+
+/**
+ * `envs diff` — the same comparison as `status`, with values.
+ *
+ * Values are masked unless `--show-values` is passed. A diff is the one command
+ * whose whole purpose is to show what changed, and it is also the one most
+ * likely to be run with someone watching the screen; masking by default makes
+ * revealing a secret a deliberate act.
+ */
+export async function diff(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,
+  })
+
+  const changed = files.filter(file => file.state !== FILE_STATE.IN_SYNC)
+
+  if (changed.length === 0) {
+    out()
+    out(`  ${style.dim('No differences.')} ${style.bold(context.project.name)} is up to date.`)
+    out()
+    return 0
+  }
+
+  // Only fetch plaintext for files that actually differ, and only when the user
+  // asked to see values.
+  const cloudValues = new Map()
+
+  if (flags['show-values']) {
+    for (const file of changed) {
+      if (file.state === FILE_STATE.UNTRACKED) {
+        continue
+      }
+
+      const response = await api.getFile(
+        context.host,
+        context.token,
+        context.project.name,
+        file.name
+      )
+      cloudValues.set(file.name, entriesToMap(response.entries ?? []))
+    }
+  }
+
+  out()
+
+  for (const file of changed) {
+    out(`  ${style.bold(file.name)} ${style.dim(`— ${describeFile(file)}`)}`)
+
+    const local = entriesToMap(localFiles.get(file.name) ?? [])
+    const cloud = cloudValues.get(file.name)
+
+    for (const entry of file.keys) {
+      if (entry.state === KEY_STATE.SAME) {
+        continue
+      }
+
+      renderKey(entry, local, cloud, Boolean(flags['show-values']))
+    }
+
+    out()
+  }
+
+  if (!flags['show-values']) {
+    out(`  ${style.dim('Values are masked. Pass --show-values to reveal them.')}`)
+    out()
+  }
+
+  return driftExitCode(flags, files)
+}
+
+function renderKey(entry, local, cloud, showValues) {
+  const reveal = value => (showValues ? value : maskValue(value))
+
+  if (entry.state === KEY_STATE.MODIFIED) {
+    out(`    ${style.yellow('~')} ${entry.key}`)
+    out(
+      `        ${style.red('cloud')} ${cloud ? reveal(cloud.get(entry.key) ?? '') : style.dim('•'.repeat(8))}`
+    )
+    out(`        ${style.green('local')} ${reveal(local.get(entry.key) ?? '')}`)
+    return
+  }
+
+  if (entry.state === KEY_STATE.LOCAL_ONLY) {
+    out(
+      `    ${style.green('+')} ${entry.key}  ${reveal(local.get(entry.key) ?? '')} ${style.dim('(local only)')}`
+    )
+    return
+  }
+
+  out(
+    `    ${style.red('-')} ${entry.key}  ${
+      cloud ? reveal(cloud.get(entry.key) ?? '') : style.dim('•'.repeat(8))
+    } ${style.dim('(cloud only)')}`
+  )
+}
+
+function describeFile(file) {
+  if (file.state === FILE_STATE.CLOUD_ONLY) {
+    return 'in the cloud, not on disk'
+  }
+
+  if (file.state === FILE_STATE.UNTRACKED) {
+    return 'on disk, not in the cloud'
+  }
+
+  return 'differs'
+}
+
+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
+  }
+}