envstash-cli 0.4.4 → 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.4",
+  "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/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,6 +1,12 @@
 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'
@@ -25,9 +31,24 @@ export function announceIgnoredSecretDir(repoRoot) {
  * 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 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
@@ -36,7 +57,7 @@ export async function push(flags, args) {
     announceIgnoredSecretDir(context.repoRoot)
   }
 
-  const cloudFiles = await fetchCloudFiles(context)
+  const cloudFiles = await fetchCloudFiles(context, scope)
 
   const names = resolveFileNames({
     repoRoot: context.repoRoot,
@@ -70,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
     }
 
@@ -90,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)
@@ -130,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()
   }
 
@@ -142,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)}.`,
@@ -160,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')
   )
@@ -178,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.',