dotcrypt 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -6,6 +6,24 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+### Added
+
+- `status` command: shows, per environment, whether you or your team changed something since your
+  last sync and what to do next. No password needed.
+- Sync tracking: fingerprints recorded in `.git/dotcrypt/sync-state.json` (per clone, never
+  committed) so dotcrypt can tell local changes from incoming ones.
+- `encrypt` now prints the Git command to send the `.enc` file to your team.
+
+### Changed
+
+- Simpler dashboard: plain-language states ("You have unshared changes", "New changes from your
+  team", ...), one main button per environment, a copyable commit/push command, a "How sharing
+  works" guide, and a Compare dialog to choose between your version and your team's.
+
+### Fixed
+
+- The dashboard no longer reports "Local changed" right after decrypting.
+
 ## [1.0.0] - 2026-11-10
 
 ### Added

package/README.md

@@ -60,6 +60,7 @@ Prefer the terminal? Everything in the dashboard is also available as a CLI comm
 
 | Command | Description |
 | --- | --- |
+| `status` | Show what changed for each environment and what to do next. No password needed. |
 | `init [-n name] [--envs a,b,c] [-d env] [-y] [-f]` | Create `.dotcrypt.json` and add ignore rules for plaintext env files to `.gitignore`. |
 | `encrypt [-e env] [-p password] [-f] [--replace]` | Encrypt the mapped local file (e.g. `.env.staging`) into its `.enc` file. |
 | `decrypt [-e env] [-p password] [-f]` | Decrypt the `.enc` file into the mapped local file. |
@@ -136,35 +137,62 @@ Custom plaintext paths that the default `.env` / `.env.*` rules don't cover are
 
 ## Team workflow
 
-**Project owner (once):**
+The idea in one sentence: **your secrets live in normal `.env` files; you share them by
+encrypting them into `.enc` files and pushing those through Git.**
 
-```bash
-dotcrypt init                     # creates .dotcrypt.json, updates .gitignore
-# create .env.development, .env.staging, ...
-dotcrypt encrypt -e development   # choose a strong password
-dotcrypt encrypt -e production    # use a *different* password per environment
-git add .dotcrypt.json .gitignore *.enc
-git commit -m "Add encrypted environments"
-```
+The easiest way to work is the dashboard (`dotcrypt ui`). Each environment card says in plain
+words what state it is in and shows one button for the next step. `dotcrypt status` shows the
+same thing in the terminal.
 
-Share each environment's password **out of band** (password manager, not chat or the repo).
+**Setting up (once, by one person):**
 
-**Teammate on a new machine:**
+1. Run `dotcrypt init` (or open `dotcrypt ui` and click through the setup).
+2. Create your `.env` files as usual and click **Share with team** on each card (or run
+   `dotcrypt encrypt -e <env>`). You choose a password per environment.
+3. Commit and push `.dotcrypt.json`, `.gitignore` and the `.enc` files. The card shows the exact
+   command.
+4. Give teammates the passwords privately (a password manager, not chat or the repo).
 
-```bash
-git pull
-dotcrypt decrypt -e development
-```
+**You added or changed a variable:**
 
-**Changing a secret:**
+1. Edit the `.env` file in your editor.
+2. The card now says **You have unshared changes**. Click **Share changes**
+   (CLI: `dotcrypt encrypt -e <env>`).
+3. Commit and push the `.enc` file. The card shows the command, for example:
+   `git add .env.development.enc && git commit -m "Update development secrets" && git push`.
 
-```bash
-git pull                                  # always start from the latest vault
-dotcrypt diff -e development       # see what differs before acting
-# edit .env.development
-dotcrypt encrypt -e development
-git add .env.development.enc && git commit -m "Update dev env" && git push
-```
+**A teammate changed something:**
+
+1. `git pull`.
+2. The card says **New changes from your team**. Click **Get latest**
+   (CLI: `dotcrypt decrypt -e <env>`).
+
+**A new teammate joins:** they clone the repo, run `npx dotcrypt ui`, click **Get secrets** on
+each card, and enter the password you gave them.
+
+**Both of you changed the same environment:** the card says **Changed on both sides**. Click
+**Review** to see which variable names differ, then choose **Keep mine and share it** or **Use
+team's version**. If you need parts of both, copy the missing variables into your file first,
+then keep yours.
+
+### How dotcrypt knows what changed
+
+`.enc` files are re-encrypted with a fresh random IV every time, so comparing timestamps or file
+contents can't tell who changed what. Instead, every time you share, get, or compare an
+environment, dotcrypt records fingerprints (SHA-256) of both files at that moment in
+`.git/dotcrypt/sync-state.json`. That file is local to your clone and never committed. Later it
+compares the current files with those fingerprints:
+
+| State | Meaning | Next step |
+| --- | --- | --- |
+| Up to date | Neither file changed since your last sync. | Nothing. |
+| You have unshared changes | Your `.env` changed. | Share, then commit and push. |
+| New changes from your team | The `.enc` changed (e.g. after `git pull`). | Get latest. |
+| Changed on both sides | Both changed. | Review and choose a version. |
+| Not shared yet / Ready to download | Only one of the two files exists. | Share / Get secrets. |
+| Not checked yet | No fingerprint yet (e.g. first run on an existing checkout). | Compare once with the password. |
+
+Neither the dashboard nor `status` needs a password to show these states.
 
 **Someone leaves the team / password leaked:**
 
@@ -289,17 +317,18 @@ dashboard assets are not built, run `npm run build:ui` in this repository.
 A local dashboard built with React, [shadcn/ui](https://ui.shadcn.com) (Base UI primitives) and
 Tailwind. It shows:
 
-- every environment in `.dotcrypt.json`: local file and vault file status, sizes, last-modified /
-  last-encrypted times, and the default environment
-- a health badge per environment (Synced, Local changed, Not encrypted, Not decrypted, Vault
-  unreadable, Plaintext tracked)
-- Git safety: whether plaintext files are ignored or (dangerously) tracked, whether `.enc` files are
-  committed, and a one-click fix for missing `.gitignore` rules
+- a short "How sharing works" guide (hide it, and reopen it from **How it works** in the header)
+- one card per environment with a plain-language state (see [Team workflow](#how-dotcrypt-knows-what-changed))
+  and a single button for the next step: **Share changes**, **Get latest**, **Review**, ...
+- the Git command to send a shared `.enc` file to your team (with a copy button), and a hint when a
+  teammate pushed something newer
+- Git safety: whether plaintext files are ignored or (dangerously) tracked, and a one-click fix for
+  missing `.gitignore` rules
 - an activity log for the session
 
-You can initialize a vault, add environments, set the default, and run encrypt, decrypt, diff and
-rotate-key from the dashboard. Overwrites show the key-name diff and need confirmation, just like
-the CLI. The dashboard refreshes every 5 seconds, so changes made in the terminal or by `git pull`
+Less common actions (compare, force share or get, change password, make default) are in each
+card's **⋯** menu. Changes that overwrite a file show the variable names involved and ask for
+confirmation, just like the CLI. The dashboard refreshes every 5 seconds, so changes made in the terminal or by `git pull`
 show up automatically.
 
 ### Dashboard security model

package/bin/cli.js

@@ -19,6 +19,7 @@ import {
   decryptEnvironment,
   diffEnvironment,
   encryptEnvironment,
+  getVaultStatus,
   initVault,
   inspectVault,
   loadEnvelope,
@@ -297,7 +298,68 @@ async function encryptCommand(opts) {
     return;
   }
   log.success(`Encrypted ${env.file} -> ${env.encryptedFile}`);
-  log.dim(`Commit ${env.encryptedFile} to share it with your team.`);
+  log.dim(`Share it with your team: ${shareCommand(env)}`);
+}
+
+function shareCommand(env) {
+  return `git add ${env.encryptedFile} && git commit -m "Update ${env.name} secrets" && git push`;
+}
+
+const SYNC_TEXT = {
+  synced: [chalk.green('✔'), 'Up to date'],
+  'local-changes': [chalk.yellow('↑'), 'You have changes your team does not have'],
+  'incoming-changes': [chalk.cyan('↓'), 'New changes from your team'],
+  conflict: [chalk.red('!'), 'Changed both locally and by your team'],
+  unknown: [chalk.dim('?'), 'Not checked yet on this machine'],
+  'not-shared': [chalk.yellow('↑'), 'Not shared yet'],
+  'not-downloaded': [chalk.cyan('↓'), 'Shared by your team, not on this machine yet'],
+  empty: [chalk.dim('·'), 'No env file yet'],
+  broken: [chalk.red('✖'), 'Encrypted file is unreadable'],
+};
+
+function nextStep(env) {
+  const flag = `-e ${env.name}`;
+  switch (env.sync) {
+    case 'local-changes':
+    case 'not-shared':
+      return `dotcrypt encrypt ${flag}`;
+    case 'incoming-changes':
+    case 'not-downloaded':
+      return `dotcrypt decrypt ${flag}`;
+    case 'conflict':
+      return `dotcrypt diff ${flag}, then keep yours (encrypt) or take theirs (decrypt)`;
+    case 'unknown':
+      return `dotcrypt diff ${flag}`;
+    case 'empty':
+      return `create ${env.file}, then dotcrypt encrypt ${flag}`;
+    case 'broken':
+      return env.vault.error ?? `${env.encryptedFile} belongs to "${env.vault.environment}"`;
+    default:
+      return null;
+  }
+}
+
+function statusCommand() {
+  const status = getVaultStatus(loadConfig());
+  log.info(chalk.bold(status.vault.name) + chalk.dim(`  ${status.root}`));
+  log.info('');
+  const width = Math.max(...status.environments.map((env) => env.name.length + (env.isDefault ? 10 : 0)));
+  for (const env of status.environments) {
+    const share = env.vaultGit;
+    const unsent = env.vault.exists && share.inRepo && (share.uncommitted || share.unpushed);
+    const [icon, text] =
+      env.sync === 'synced' && unsent ? [chalk.yellow('↑'), 'Encrypted, but not pushed to your team yet'] : SYNC_TEXT[env.sync];
+    const label = env.isDefault ? `${env.name} ${chalk.dim('(default)')}` : env.name;
+    const pad = ' '.repeat(width - env.name.length - (env.isDefault ? 10 : 0));
+    log.info(`  ${icon} ${label}${pad}  ${text}`);
+    const step = nextStep(env);
+    if (step) log.dim(`      → ${step}`);
+    if (env.git.tracked) log.warn(`    ${env.file} is TRACKED by Git! Run "git rm --cached ${env.file}" and rotate its secrets.`);
+    if (unsent) {
+      log.dim(`      → ${env.encryptedFile} is not pushed yet: ${share.uncommitted ? shareCommand(env) : 'git push'}`);
+    }
+    if (share.behind) log.dim(`      → a teammate pushed a newer ${env.encryptedFile}: git pull`);
+  }
 }
 
 async function decryptCommand(opts) {
@@ -424,6 +486,11 @@ program
     `\nPasswords are read from (in order): the CLI flag, $${PASSWORD_ENV} ($${NEW_PASSWORD_ENV} for rotate-key's new password), or an interactive prompt.`,
   );
 
+program
+  .command('status')
+  .description('show what changed and what to do next for each environment (no password needed)')
+  .action(statusCommand);
+
 program
   .command('init')
   .description(`create ${CONFIG_FILENAME} and protect plaintext env files in .gitignore`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotcrypt",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Securely sync multiple .env environments across machines via Git using AES-256-GCM encrypted files.",
   "type": "module",
   "main": "src/crypto.js",

package/src/sync.js

@@ -0,0 +1,100 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { MAX_FILE_SIZE, gitOutput } from './utils.js';
+
+/**
+ * Remembers, per machine, the fingerprints of the local env file and the vault file at the moment
+ * they were last known to match (after encrypt, decrypt, or an identical diff). Comparing the
+ * current files against that baseline tells us who changed what, without needing the password:
+ *
+ *   local changed only  -> you have changes to share
+ *   vault changed only  -> a teammate shared changes (after git pull)
+ *   both changed        -> conflict
+ *
+ * The state lives inside the Git directory (.git/dotcrypt/sync-state.json), so it is never
+ * committed and every clone or worktree tracks its own files.
+ */
+
+const STATE_VERSION = 1;
+
+export function fingerprint(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/** SHA-256 of a file, or null when it is missing, too large or unreadable. */
+export function fingerprintFile(absPath) {
+  try {
+    if (fs.statSync(absPath).size > MAX_FILE_SIZE) return null;
+    const data = fs.readFileSync(absPath);
+    try {
+      return fingerprint(data);
+    } finally {
+      data.fill(0);
+    }
+  } catch {
+    return null;
+  }
+}
+
+function locateState(root) {
+  const out = gitOutput(root, ['rev-parse', '--absolute-git-dir', '--show-prefix']);
+  if (!out) return null;
+  const [gitDir, prefix = ''] = out.split('\n');
+  if (!gitDir) return null;
+  return { file: path.join(gitDir, 'dotcrypt', 'sync-state.json'), project: prefix.replace(/\/$/, '') || '.' };
+}
+
+function readState(file) {
+  try {
+    const state = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (state?.version === STATE_VERSION && state.projects && typeof state.projects === 'object') return state;
+  } catch {
+    // Missing or corrupt state simply means "unknown"; it is rebuilt on the next sync.
+  }
+  return { version: STATE_VERSION, projects: {} };
+}
+
+/** Opens the sync state for a project root. All methods are no-ops outside a Git repository. */
+export function openSyncState(root) {
+  const location = locateState(root);
+  const state = location ? readState(location.file) : null;
+  const entries = () => (state ? (state.projects[location.project] ?? {}) : {});
+
+  return {
+    get(envName) {
+      const entry = Object.hasOwn(entries(), envName) ? entries()[envName] : null;
+      return entry && typeof entry.local === 'string' && typeof entry.vault === 'string' ? entry : null;
+    },
+    set(envName, { local, vault }) {
+      if (!state || !local || !vault) return;
+      state.projects[location.project] = { ...entries(), [envName]: { local, vault, syncedAt: new Date().toISOString() } };
+      try {
+        fs.mkdirSync(path.dirname(location.file), { recursive: true });
+        const tmp = `${location.file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, location.file);
+      } catch {
+        // Best effort: sync tracking must never make encrypt or decrypt fail.
+      }
+    },
+  };
+}
+
+/**
+ * Plain-language sync state of one environment:
+ * empty | not-shared | not-downloaded | unknown | synced | local-changes | incoming-changes | conflict
+ */
+export function computeSync({ localExists, vaultExists, localHash, vaultHash, baseline }) {
+  if (!localExists && !vaultExists) return 'empty';
+  if (!vaultExists) return 'not-shared';
+  if (!localExists) return 'not-downloaded';
+  if (!baseline || !localHash || !vaultHash) return 'unknown';
+  const localChanged = localHash !== baseline.local;
+  const vaultChanged = vaultHash !== baseline.vault;
+  if (localChanged && vaultChanged) return 'conflict';
+  if (localChanged) return 'local-changes';
+  if (vaultChanged) return 'incoming-changes';
+  return 'synced';
+}

package/src/utils.js

@@ -219,6 +219,36 @@ export function gitStatusOf(root, relPath) {
   };
 }
 
+/** Returns trimmed stdout of a Git command, or null when it fails or Git is unavailable. */
+export function gitOutput(root, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    }).trimEnd();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Describes how far a committed file is from the team:
+ *  - uncommitted: changed or new in the working tree
+ *  - unpushed: committed locally but not on the upstream branch yet
+ *  - behind: the upstream branch has a newer version (visible after a fetch)
+ * Each flag is false when unknown (no repo, no upstream).
+ */
+export function gitShareStatus(root, relPath) {
+  const file = toPosix(relPath);
+  const uncommitted = Boolean(gitOutput(root, ['status', '--porcelain', '--untracked-files=all', '--', file]));
+  const hasUpstream = gitOutput(root, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']) !== null;
+  if (!hasUpstream) return { uncommitted, unpushed: false, behind: false, hasUpstream };
+  const touched = (range) => Boolean(gitOutput(root, ['log', '-1', '--format=%H', range, '--', file]));
+  return { uncommitted, unpushed: touched('@{u}..HEAD'), behind: touched('HEAD..@{u}'), hasUpstream };
+}
+
 export function parseEnv(content) {
   return dotenv.parse(content);
 }

package/src/vault.js

@@ -18,11 +18,13 @@ import {
   diffEnv,
   ensureGitignore,
   fileExists,
+  gitShareStatus,
   gitStatusOf,
   parseEnv,
   safeReadFile,
   safeWriteFile,
 } from './utils.js';
+import { computeSync, fingerprint, fingerprintFile, openSyncState } from './sync.js';
 
 export const MIN_PASSWORD_LENGTH = 12;
 
@@ -116,7 +118,7 @@ function fileInfo(root, absPath) {
 }
 
 /** Describes an environment without decrypting anything. Never exposes secret values. */
-export function getEnvironmentStatus(ctx, name) {
+export function getEnvironmentStatus(ctx, name, syncState = openSyncState(ctx.root)) {
   const env = resolveEnvironment(ctx, name);
   const local = fileInfo(ctx.root, env.plainPath);
   const vault = { ...fileInfo(ctx.root, env.encPath), valid: false };
@@ -136,25 +138,35 @@ export function getEnvironmentStatus(ctx, name) {
 
   const git = gitStatusOf(ctx.root, env.file);
   const vaultGit = gitStatusOf(ctx.root, env.encryptedFile);
-  const localNewerThanVault = Boolean(
-    local.modifiedAt && vault.encryptedAt && Date.parse(local.modifiedAt) > Date.parse(vault.encryptedAt),
-  );
+  const broken = vault.exists && !(vault.valid && vault.environmentMatches);
+  const sync = broken
+    ? 'broken'
+    : computeSync({
+        localExists: local.exists,
+        vaultExists: vault.exists,
+        localHash: local.exists && vault.exists ? fingerprintFile(env.plainPath) : null,
+        vaultHash: local.exists && vault.exists ? fingerprintFile(env.encPath) : null,
+        baseline: syncState.get(env.name),
+      });
 
   return {
     name: env.name,
     file: env.file,
     encryptedFile: env.encryptedFile,
     isDefault: ctx.config.defaultEnvironment === env.name,
+    sync,
     local,
     vault,
     git,
-    vaultGit: vaultGit.inRepo ? { inRepo: true, tracked: vaultGit.tracked } : { inRepo: false },
-    localNewerThanVault,
+    vaultGit: vaultGit.inRepo
+      ? { inRepo: true, tracked: vaultGit.tracked, ...gitShareStatus(ctx.root, env.encryptedFile) }
+      : { inRepo: false },
   };
 }
 
 export function getVaultStatus(ctx) {
-  const environments = listEnvironments(ctx.config).map((name) => getEnvironmentStatus(ctx, name));
+  const syncState = openSyncState(ctx.root);
+  const environments = listEnvironments(ctx.config).map((name) => getEnvironmentStatus(ctx, name, syncState));
   return {
     root: ctx.root,
     configFile: CONFIG_FILENAME,
@@ -164,6 +176,11 @@ export function getVaultStatus(ctx) {
   };
 }
 
+/** Records that the local file and the vault file currently hold the same content. */
+function markSynced(ctx, env, plaintext) {
+  openSyncState(ctx.root).set(env.name, { local: fingerprint(plaintext), vault: fingerprintFile(env.encPath) });
+}
+
 /**
  * Encrypts the local file into the vault file.
  * Options:
@@ -218,7 +235,10 @@ export function encryptEnvironment(ctx, name, password, { overwrite = false, rep
     let diff;
     if (previous) {
       try {
-        if (buffersEqual(previous, plaintext)) return { status: 'unchanged', environment: env.name, warnings };
+        if (buffersEqual(previous, plaintext)) {
+          markSynced(ctx, env, plaintext);
+          return { status: 'unchanged', environment: env.name, warnings };
+        }
         diff = diffEnv(parseEnv(previous), parseEnv(plaintext));
       } finally {
         previous.fill(0);
@@ -233,6 +253,7 @@ export function encryptEnvironment(ctx, name, password, { overwrite = false, rep
 
     const envelope = encrypt(plaintext, password, { environment: env.name, sourceFile: env.file });
     safeWriteFile(ctx.root, env.encPath, serializeEnvelope(envelope), { mode: 0o644 });
+    markSynced(ctx, env, plaintext);
     return { status: vaultExisted ? 'updated' : 'created', environment: env.name, diff, warnings };
   } finally {
     plaintext.fill(0);
@@ -255,6 +276,7 @@ export function decryptEnvironment(ctx, name, password, { overwrite = false } =
       const current = safeReadFile(ctx.root, env.plainPath);
       try {
         if (buffersEqual(current, plaintext)) {
+          markSynced(ctx, env, plaintext);
           return { status: 'unchanged', environment: env.name, warnings: plaintextWarnings(ctx.root, env.file) };
         }
         if (!overwrite) {
@@ -269,6 +291,7 @@ export function decryptEnvironment(ctx, name, password, { overwrite = false } =
     }
 
     safeWriteFile(ctx.root, env.plainPath, plaintext, { mode: 0o600 });
+    markSynced(ctx, env, plaintext);
     return {
       status: localExisted ? 'updated' : 'created',
       environment: env.name,
@@ -299,7 +322,11 @@ export function rotateEnvironmentKey(ctx, name, oldPassword, newPassword) {
     check.fill(0);
     if (!ok) throw new VaultError('Verification of the re-encrypted data failed. The original file was not modified.');
 
+    const syncState = openSyncState(ctx.root);
+    const baseline = syncState.get(env.name);
+    const wasSynced = baseline?.vault === fingerprintFile(env.encPath);
     safeWriteFile(ctx.root, env.encPath, serializeEnvelope(rotated), { mode: 0o644 });
+    if (wasSynced) syncState.set(env.name, { local: baseline.local, vault: fingerprintFile(env.encPath) });
     return { status: 'rotated', environment: env.name };
   } finally {
     plaintext.fill(0);
@@ -334,6 +361,7 @@ export function diffEnvironment(ctx, name, password) {
     if (local) {
       localVars = parseEnv(local);
       identical = buffersEqual(local, plaintext);
+      if (identical) markSynced(ctx, env, plaintext);
     }
   } finally {
     plaintext.fill(0);