envstash-cli 0.4.3 → 0.5.0

package/README.md

@@ -116,6 +116,21 @@ definition and therefore has no undo:
 
 Preview either direction with `--dry-run`.
 
+## Shared files
+
+Some credentials follow you rather than a repo — a global `.npmrc`, an AI-tool
+key file. Push those once to your account-wide shared files, then pull them into
+whichever repo needs them:
+
+```bash
+envs push --shared .npmrc     # from any repo, once
+envs pull --shared .npmrc     # in every repo that needs it
+```
+
+`--shared` always needs the files named: discovery sweeps up a repo's own
+files, and the shared scope is deliberately outside that. Shared files appear
+on the dashboard under **Shared Files**, not inside any project.
+
 ## Project linking
 
 `envs init` writes `.envstash.json` in your repo root:

package/package.json

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

package/src/commands/misc.mjs

@@ -13,6 +13,7 @@ import {
 } from '../project.mjs'
 import { requireHostToken, resolveHostFor, resolveHostSource } from '../session.mjs'
 import { out, pad, pluralize, style } from '../ui.mjs'
+import { announceIgnoredSecretDir } from './push.mjs'
 
 /**
  * `envs version` — the version, and the environment it would act in.
@@ -140,6 +141,10 @@ export async function init(flags, args) {
 
   await api.createProject(host, token, name)
 
+  // Before discovery, so a not-yet-ignored .config/ lands in the link file
+  // this init writes rather than being silently absent from it.
+  announceIgnoredSecretDir(repoRoot)
+
   const files = existing?.files?.length ? existing.files : discoverTrackedFiles(repoRoot)
   const path = writeLink(repoRoot, {
     project: name,
@@ -201,6 +206,9 @@ export async function link(flags, args) {
   // that points at nothing.
   await api.projectStatus(host, token, name)
 
+  // Same moment as in init: discovery is about to decide the link file's list.
+  announceIgnoredSecretDir(repoRoot)
+
   const files = existing?.files?.length ? existing.files : discoverTrackedFiles(repoRoot)
   const path = writeLink(repoRoot, { project: name, files, host: existing?.host ?? null })
 

package/src/commands/pull.mjs

@@ -3,7 +3,13 @@ import { dirname } from 'node:path'
 
 import { api, ApiError } from '../api.mjs'
 import { formatSize } from '../blob.mjs'
-import { cloudKinds, loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
+import {
+  cloudKinds,
+  loadLocalFiles,
+  resolveContext,
+  resolveFileNames,
+  SHARED_SCOPE,
+} from '../context.mjs'
 import { serializeEnv } from '../env-file.mjs'
 import { resolveInsideRepo } from '../repo-path.mjs'
 import { compareProject, FILE_STATE } from '../status.mjs'
@@ -16,17 +22,38 @@ import { CliError, out, pluralize, style } from '../ui.mjs'
  * most likely to be run reflexively on a new machine, and silently replacing an
  * uncommitted `.env` destroys work that exists nowhere else — `.env` files are
  * git-ignored by definition, so there is no undo.
+ *
+ * `--shared` pulls the named files from the account-wide shared scope instead
+ * of this repo's project. Names are required, mirroring `push --shared`: which
+ * of your shared files belong in this particular repo is a per-repo decision,
+ * not something to infer from the scope's whole contents.
  */
 export async function pull(flags, args) {
+  const shared = Boolean(flags.shared)
+
+  if (shared && args.length === 0) {
+    throw new CliError('Pulling shared files needs their names.', {
+      hint: 'Example: envs pull --shared .npmrc',
+    })
+  }
+
   const context = resolveContext(flags)
+  const scope = shared ? SHARED_SCOPE : context.project.name
 
   let cloudFiles
 
   try {
-    const response = await api.projectStatus(context.host, context.token, context.project.name)
+    const response = await api.projectStatus(context.host, context.token, scope)
     cloudFiles = response.files ?? []
   } catch (error) {
     if (error instanceof ApiError && error.status === 404) {
+      if (shared) {
+        // The scope is created by the first shared push; until then it 404s.
+        throw new CliError('You have no shared files yet.', {
+          hint: 'Push one first: envs push --shared <file>',
+        })
+      }
+
       throw new CliError(`No project named "${context.project.name}" in your account.`, {
         hint: 'Run `envs init` to create it, or pass --project to target another one.',
       })
@@ -44,9 +71,16 @@ export async function pull(flags, args) {
 
   if (names.length === 0) {
     out()
-    out(
-      `  ${style.dim('Nothing to pull —')} ${style.bold(context.project.name)} ${style.dim('has no files in the cloud.')}`
-    )
+
+    if (shared) {
+      out(`  ${style.dim('Nothing to pull — none of those names are in your shared files.')}`)
+      out(`  ${style.dim('See what is there on the dashboard, or push with')} envs push --shared`)
+    } else {
+      out(
+        `  ${style.dim('Nothing to pull —')} ${style.bold(context.project.name)} ${style.dim('has no files in the cloud.')}`
+      )
+    }
+
     out()
     return 0
   }
@@ -80,7 +114,7 @@ export async function pull(flags, args) {
       continue
     }
 
-    const response = await api.getFile(context.host, context.token, context.project.name, file.name)
+    const response = await api.getFile(context.host, context.token, scope, file.name)
 
     // A blob comes back whole; a dotenv file is regenerated from entries. The
     // branch is on the response's own kind — the server is the authority.

package/src/commands/push.mjs

@@ -1,9 +1,29 @@
 import { api, ApiError } from '../api.mjs'
 import { formatSize, MAX_BLOB_BYTES } from '../blob.mjs'
-import { cloudKinds, loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
+import {
+  cloudKinds,
+  loadLocalFiles,
+  resolveContext,
+  resolveFileNames,
+  SHARED_SCOPE,
+} from '../context.mjs'
+import { ensureSecretDirIgnored, SECRET_FILE_DIR } from '../project.mjs'
 import { compareProject, FILE_STATE } from '../status.mjs'
 import { CliError, out, pluralize, style } from '../ui.mjs'
 
+/** Say that .gitignore was edited — quietly rewriting a user's file is worse. */
+export function announceIgnoredSecretDir(repoRoot) {
+  if (!ensureSecretDirIgnored(repoRoot)) {
+    return
+  }
+
+  out()
+  out(
+    `  ${style.green('+')} Added ${style.bold(`${SECRET_FILE_DIR}/`)} to .gitignore ` +
+      style.dim('— secrets sync through EnvStash, not git')
+  )
+}
+
 /**
  * `envs push` — send local files up.
  *
@@ -11,10 +31,33 @@ import { CliError, out, pluralize, style } from '../ui.mjs'
  * is passed. Pushing a partial `.env` is normal — a developer working on one
  * feature often has only the keys they need — and treating absence as deletion
  * would let that quietly destroy a teammate's key.
+ *
+ * `--shared` sends the named files to the account-wide shared scope instead of
+ * this repo's project — for credentials that follow the developer rather than
+ * a repo (a global `.npmrc`, an AI-tool key file). Names are required there:
+ * discovery exists to sweep up a repo's own files, and sweeping a repo's files
+ * into the account-wide scope is exactly the mistake it would make.
  */
 export async function push(flags, args) {
+  const shared = Boolean(flags.shared)
+
+  if (shared && args.length === 0) {
+    throw new CliError('Pushing shared files needs their names.', {
+      hint: 'Example: envs push --shared .npmrc',
+    })
+  }
+
   const context = resolveContext(flags)
-  const cloudFiles = await fetchCloudFiles(context)
+  const scope = shared ? SHARED_SCOPE : context.project.name
+
+  // Before discovery, so files in a not-yet-ignored .config/ are picked up by
+  // this very push rather than the next one. Not under --dry-run: a preview
+  // that edits files is not a preview.
+  if (!flags['dry-run']) {
+    announceIgnoredSecretDir(context.repoRoot)
+  }
+
+  const cloudFiles = await fetchCloudFiles(context, scope)
 
   const names = resolveFileNames({
     repoRoot: context.repoRoot,
@@ -48,7 +91,7 @@ export async function push(flags, args) {
     }
 
     if (file.kind === 'file') {
-      pushed += await pushOneBlob(flags, context, file, localFiles.get(file.name))
+      pushed += await pushOneBlob(flags, context, scope, file, localFiles.get(file.name))
       continue
     }
 
@@ -68,7 +111,7 @@ export async function push(flags, args) {
     const result = await api.putFile(
       context.host,
       context.token,
-      context.project.name,
+      scope,
       file.name,
       entries,
       Boolean(flags.prune)
@@ -108,7 +151,9 @@ export async function push(flags, args) {
   out()
 
   if (!flags['dry-run'] && pushed > 0) {
-    out(`  ${style.dim(`Pushed ${pluralize(pushed, 'file')} to ${context.project.name}.`)}`)
+    // The shared scope's internal name is not for printing — say what it means.
+    const destination = shared ? 'your shared files' : context.project.name
+    out(`  ${style.dim(`Pushed ${pluralize(pushed, 'file')} to ${destination}.`)}`)
     out()
   }
 
@@ -120,7 +165,7 @@ export async function push(flags, args) {
  * the report is created / updated / unchanged, with the size, because "what
  * went up" for a blob is the file itself.
  */
-async function pushOneBlob(flags, context, file, local) {
+async function pushOneBlob(flags, context, scope, file, local) {
   if (local.bytes.length > MAX_BLOB_BYTES) {
     throw new CliError(
       `${file.name} is ${formatSize(local.bytes.length)} — files are capped at ${formatSize(MAX_BLOB_BYTES)}.`,
@@ -138,7 +183,7 @@ async function pushOneBlob(flags, context, file, local) {
   const result = await api.putBlob(
     context.host,
     context.token,
-    context.project.name,
+    scope,
     file.name,
     local.bytes.toString('base64')
   )
@@ -156,13 +201,14 @@ async function pushOneBlob(flags, context, file, local) {
   return 1
 }
 
-async function fetchCloudFiles(context) {
+async function fetchCloudFiles(context, scope) {
   try {
-    const response = await api.projectStatus(context.host, context.token, context.project.name)
+    const response = await api.projectStatus(context.host, context.token, scope)
     return response.files ?? []
   } catch (error) {
     if (error instanceof ApiError && error.status === 404) {
-      // First push to a new project: the server creates it on write.
+      // First push to a new project — or to a shared scope that has never
+      // held a file: the server creates either on write.
       return []
     }
 

package/src/context.mjs

@@ -7,6 +7,15 @@ import { resolveInsideRepo } from './repo-path.mjs'
 import { requireHostToken } from './session.mjs'
 import { errOut, pluralize, style } from './ui.mjs'
 
+/**
+ * The server-side name of the per-user shared-files scope, mirrored from
+ * SHARED_SCOPE in src/lib/secrets/store.ts. `--shared` sends files here instead
+ * of to a project: same routes, this name in the project segment. The `~` is
+ * what makes it unclaimable — project names cannot contain one, so no project
+ * of the user's can ever be shadowed by it.
+ */
+export const SHARED_SCOPE = '~shared'
+
 /**
  * Everything the sync commands need, resolved once: which server, which token,
  * which repo, which project.

package/src/index.mjs

@@ -261,6 +261,7 @@ function printHelp(topic) {
   )
   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(`    --shared           ${style.dim('Target your account-wide shared files (pull, push)')}`)
   out(`    --dev              ${style.dim('Log in to a local dev server if one is running')}`)
   out()
   out(
@@ -313,9 +314,13 @@ const COMMAND_HELP = {
     'Files with local changes are skipped unless --force is given, because a',
     'git-ignored .env that gets overwritten has no undo.',
     '',
+    '--shared pulls from your account-wide shared files instead of this repo’s',
+    'project, and needs the file named.',
+    '',
     '  envs pull',
     '  envs pull --dry-run',
     '  envs pull --force',
+    '  envs pull --shared .npmrc',
   ],
   push: [
     'Send local files to the cloud.',
@@ -323,9 +328,14 @@ const COMMAND_HELP = {
     '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.',
     '',
+    '--shared sends the named files to your account-wide shared files — for',
+    'credentials that follow you across projects, like a global .npmrc. Pull',
+    'them into any repo with `envs pull --shared <file>`.',
+    '',
     '  envs push',
     '  envs push --dry-run',
     '  envs push --prune',
+    '  envs push --shared .npmrc',
   ],
   login: [
     'Authorize this machine using a browser device code.',

package/src/project.mjs

@@ -280,6 +280,74 @@ export function discoverSecretFiles(repoRoot) {
   return candidates.filter(name => ignored.has(name)).sort()
 }
 
+/**
+ * Make sure `.config/` is git-ignored before discovery asks about it.
+ *
+ * Being ignored is discovery's signal for "secret", which makes an unignored
+ * `.config/` silently invisible to `envs push` — a real footgun: the developer
+ * sees a directory full of credentials and a push that ignores them, with
+ * nothing saying why. Rather than documenting that, push and init close it:
+ * when the directory has contents, nothing in it is tracked by git, and it is
+ * not already ignored, `.config/` is added to .gitignore. A `.config/` with
+ * tracked files is a repo that commits configuration there on purpose, and is
+ * left alone.
+ *
+ * Returns true when .gitignore was changed — the caller must say so out loud,
+ * because a CLI editing a file it does not own should never do it silently.
+ */
+export function ensureSecretDirIgnored(repoRoot) {
+  let entries
+
+  try {
+    entries = readdirSync(join(repoRoot, SECRET_FILE_DIR))
+  } catch {
+    return false
+  }
+
+  if (entries.length === 0) {
+    return false
+  }
+
+  // Also the git-and-repo probe: outside a repository (or without git) this
+  // throws, and an ignore rule would mean nothing there anyway.
+  let tracked
+
+  try {
+    tracked = runGit(['ls-files', '--', SECRET_FILE_DIR], { cwd: repoRoot }).trim()
+  } catch {
+    return false
+  }
+
+  if (tracked !== '') {
+    return false
+  }
+
+  // A synthetic name, so one question covers the directory: any rule broad
+  // enough to ignore this probe ignores everything discovery would find.
+  const probe = `${SECRET_FILE_DIR}/envstash-ignore-probe`
+
+  if (gitIgnoredNames(repoRoot, [probe]).has(probe)) {
+    return false
+  }
+
+  const path = join(repoRoot, '.gitignore')
+  let existing = ''
+
+  try {
+    existing = readFileSync(path, 'utf8')
+  } catch {
+    // No .gitignore yet — the addition below becomes the whole file.
+  }
+
+  const addition = `# secret files — synced through EnvStash, not git\n${SECRET_FILE_DIR}/\n`
+  const body =
+    existing === '' ? addition : `${existing}${existing.endsWith('\n') ? '' : '\n'}\n${addition}`
+
+  writeFileSync(path, body)
+
+  return true
+}
+
 /** Everything auto-discovery offers to track: root dotenv files, then `.config/` files. */
 export function discoverTrackedFiles(repoRoot) {
   return [...discoverEnvFiles(repoRoot), ...discoverSecretFiles(repoRoot)]