envstash-cli 0.1.1 → 0.2.0

package/README.md

@@ -141,8 +141,9 @@ Monorepos can track nested paths by listing them explicitly:
 | --------------------- | --------------------------------------------------------- |
 | `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`        | Log in to a local dev server when one is running          |
+| `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)        |
 
@@ -157,16 +158,42 @@ 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
+### Working against 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.
+Every command takes `--port` as shorthand for a server on this machine, so
+`--port 3001` says what `--host http://localhost:3001` says:
 
-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.
+```bash
+envs status --port 3001
+envs pull --port 3001
+```
+
+`ENVSTASH_PORT=3001` does the same for a whole shell. Passing `--host` and
+`--port` together is refused rather than resolved — they are two ways of naming
+one server, and picking one silently is how a command ends up talking to the
+server you meant to exclude.
+
+`envs login` is deliberately not affected by any of this. **It signs in to
+`https://www.envstash.co` unless you say otherwise**, even if your last login
+was to a dev server: where the previous login went is not an instruction about
+where the next one should go.
+
+To sign in to a local server, name it — `envs login --port 3001` — or let the
+CLI find it:
+
+```bash
+envs login --dev
+```
+
+`--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. Production is the
+fallback when none answer, and an explicit `--host` or `--port` always wins over
+detection.
+
+A port is only accepted by detection if it responds as an EnvStash server, so an
+unrelated process holding 3000 is skipped rather than logged in to. `--port`
+does not probe: naming a port is you being explicit, and that is not
+second-guessed.
 
 ## Notes
 

package/package.json

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

package/src/dev-host.mjs

@@ -8,6 +8,7 @@
  * mean "dev".
  */
 import { DEFAULT_HOST } from './config.mjs'
+import { CliError } from './ui.mjs'
 
 /**
  * The ports `scripts/dev-with-port.mjs` hands out, which are in turn the ports
@@ -82,3 +83,52 @@ export function isDevMode(flags) {
 
 /** The host used when dev mode finds nothing — production, the last resort. */
 export const FALLBACK_HOST = DEFAULT_HOST
+
+/**
+ * The host a `--port` (or `ENVSTASH_PORT`) asked for, or null when neither did.
+ *
+ * A port with no host can only mean a server on this machine, so it expands to
+ * the same `http://localhost:<port>` shape detection produces. It exists because
+ * the alternative for every non-login command was spelling out
+ * `--host http://localhost:3001` — long enough that people export ENVSTASH_HOST
+ * for the shell instead, and then forget it is set when they go back to
+ * production.
+ *
+ * Unlike detection this does not probe: naming a port is the developer being
+ * explicit, and second-guessing an explicit answer is how `--host` would behave
+ * if it checked too.
+ */
+export function resolvePortHost(flags) {
+  // `hasOwn` rather than a truthiness check: `--port` with nothing after it
+  // parses to undefined, and that is a mistake worth naming rather than a
+  // reason to fall through to the environment.
+  const fromFlag = Boolean(flags) && Object.hasOwn(flags, 'port')
+  const raw = fromFlag ? flags.port : process.env.ENVSTASH_PORT
+
+  if (!fromFlag && !raw) {
+    return null
+  }
+
+  return { host: `http://localhost:${parsePort(raw, fromFlag)}`, source: fromFlag ? 'flag' : 'env' }
+}
+
+/**
+ * A port is an integer in 1–65535 and nothing else.
+ *
+ * Refusing the rest matters more here than it looks: every value that slips
+ * through becomes a host, and a host that is quietly wrong fails later, as a
+ * connection error against a server the developer never meant to name.
+ */
+function parsePort(value, fromFlag) {
+  const text = String(value ?? '').trim()
+  const port = Number(text)
+
+  if (!text || !Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new CliError(
+      `${fromFlag ? '--port' : 'ENVSTASH_PORT'} needs a port number${text ? `, not "${text}"` : ''}.`,
+      { hint: 'For example: --port 3001' }
+    )
+  }
+
+  return port
+}

package/src/index.mjs

@@ -16,7 +16,7 @@ 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'])
+const VALUE_FLAGS = new Set(['host', 'port', 'project', 'label'])
 
 /** The implementation of each command, by name. */
 const HANDLERS = { login, logout, whoami, init, link, list, status, diff, pull, push }
@@ -197,11 +197,16 @@ function printHelp(topic) {
   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(`    --port <n>         ${style.dim('Target a dev server on localhost at this port')}`)
   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.dim('login always signs in to')} ${DEFAULT_HOST} ${style.dim('unless one of those says otherwise.')}`
+  )
+  out()
   out(`  ${style.bold('Environment')}`)
 
   const envPad =
@@ -265,9 +270,14 @@ const COMMAND_HELP = {
   login: [
     'Authorize this machine using a browser device code.',
     '',
+    'Signs in to production unless you say otherwise — a previous login to a dev',
+    'server does not change where the next one goes.',
+    '',
     '  envs login',
     '  envs login --no-browser     Print the URL instead of opening it',
     '  envs login --host <url>     Sign in to another server',
+    '  envs login --port 3001      Sign in to a dev server on localhost:3001',
+    '  envs login --dev            Find a local dev server and sign in to it',
   ],
   logout: [
     'Revoke this machine’s token and remove it locally.',

package/src/manifest.mjs

@@ -51,13 +51,17 @@ export const CLI_ALIASES = Object.fromEntries(
 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_PORT',
+    purpose: () => 'Target a dev server on localhost at this port (same as --port)',
+  },
   {
     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)',
+    purpose: () => 'Look for a local dev server to log in to (same as --dev)',
   },
   { name: 'ENVSTASH_DEBUG', purpose: () => 'Print stack traces on failure' },
   { name: 'NO_COLOR', purpose: () => 'Disable colour (also off automatically when piped)' },

package/src/session.mjs

@@ -1,6 +1,7 @@
-import { requireToken, resolveHost } from './config.mjs'
-import { detectDevHost, isDevMode } from './dev-host.mjs'
+import { DEFAULT_HOST, requireToken, resolveHost } from './config.mjs'
+import { detectDevHost, isDevMode, resolvePortHost } from './dev-host.mjs'
 import { findRepoRoot, readLink } from './project.mjs'
+import { CliError } from './ui.mjs'
 
 /**
  * Resolve host and token together.
@@ -18,6 +19,39 @@ export function requireHostToken(flags) {
   return { host, token: requireToken(host, { allowEnvToken: source !== 'link' }) }
 }
 
+/**
+ * The host the developer named for this command, or null when they named none.
+ *
+ * The ladder is the usual one — what you typed beats what your shell exported —
+ * with `--port` sitting beside `--host` at each rung, because they are two ways
+ * of saying the same thing. Passing both is therefore a contradiction rather
+ * than a precedence question, and it is refused: silently picking one is how a
+ * command ends up talking to a server the developer explicitly excluded.
+ */
+export function resolveExplicitHost(flags) {
+  const port = resolvePortHost(flags)
+
+  if (flags?.host && port?.source === 'flag') {
+    throw new CliError(`--host and --port both name a server: ${flags.host} and ${port.host}.`, {
+      hint: 'Pass one of them.',
+    })
+  }
+
+  if (flags?.host) {
+    return { host: resolveHost(flags.host), source: 'flag' }
+  }
+
+  if (port?.source === 'flag') {
+    return port
+  }
+
+  if (process.env.ENVSTASH_HOST) {
+    return { host: resolveHost(undefined), source: 'env' }
+  }
+
+  return port
+}
+
 /**
  * Resolve the host and say where the decision came from.
  *
@@ -27,8 +61,10 @@ export function requireHostToken(flags) {
  * less trust.
  */
 export function resolveHostSource(flags) {
-  if (flags?.host || process.env.ENVSTASH_HOST) {
-    return { host: resolveHost(flags?.host), source: flags?.host ? 'flag' : 'env' }
+  const explicit = resolveExplicitHost(flags)
+
+  if (explicit) {
+    return explicit
   }
 
   try {
@@ -64,18 +100,28 @@ export function isLinkChosenHost(flags, host) {
 /**
  * Host for an interactive login.
  *
- * The usual precedence with one step inserted: in dev mode a running local
- * server beats the stored default, so `pnpm cli:dev login` opens the server the
- * developer is running. An explicit `--host` or `ENVSTASH_HOST` still wins over
- * detection — asking for a specific server should never be second-guessed — and
- * production remains the last resort when no dev server answers.
+ * Login does not inherit the stored default the way every other command does,
+ * and that is the point: the stored default is wherever the *last* login went,
+ * so one `pnpm cli:dev login` used to make every later `pnpm envs login` sign in
+ * to localhost — which looks like it worked, right up to the point where a
+ * production command finds no credential. Production is the default here, and
+ * reaching a dev server is something you ask for.
+ *
+ * Above that: in dev mode a running local server beats production, so
+ * `pnpm cli:dev login` opens the server the developer is running. An explicit
+ * `--host`, `--port`, or `ENVSTASH_HOST` wins over detection — asking for a
+ * specific server should never be second-guessed. A host this repo's link file
+ * pinned still applies, since that is a deliberate per-repo choice, and
+ * `login` already refuses one it has never signed in to.
  *
  * `onDevHost` reports what detection found so the command can say so. Deciding
  * and printing are split because the decision is what the tests care about.
  */
 export async function resolveLoginHost(flags, { onDevHost } = {}) {
-  if (flags?.host || process.env.ENVSTASH_HOST) {
-    return resolveHost(flags?.host)
+  const explicit = resolveExplicitHost(flags)
+
+  if (explicit) {
+    return explicit.host
   }
 
   if (isDevMode(flags)) {
@@ -88,5 +134,7 @@ export async function resolveLoginHost(flags, { onDevHost } = {}) {
     }
   }
 
-  return resolveHostFor(flags)
+  const resolved = resolveHostSource(flags)
+
+  return resolved.source === 'link' ? resolved.host : DEFAULT_HOST
 }