hazo_env 0.8.0 → 0.9.0

package/CHANGE_LOG.md

@@ -1,5 +1,14 @@
 # hazo_env — Change Log
 
+## 0.9.0 — 2026-07-24
+
+### Added
+- **`upload-files --skip-env`** (`uploadFiles({ skipEnv: true })`) — restore `files_root` from an archive while leaving the target `.env.local` **completely untouched**: no read, no merge, no backup, no write. For destinations whose env is hand-maintained and must survive a files refresh (e.g. a laptop dev site whose local URLs/secrets differ from the prod archive's — the common case where the default env-merge diff is all `~` clobbers). When set, the returned `diff` is empty (no env comparison is performed) and the CLI prints `.env.local skipped (--skip-env)` in place of the diff.
+  - `src/envsync/engine.ts`: `uploadFiles` gains an optional `skipEnv` flag. Files are still wiped-and-repopulated and the stray `__env.local` archive member is still stripped from `files_root`; only the env half is opted out. Orthogonal to `confirm`/`allowProd` — a dry-run with `skipEnv` returns `{ ok: false, diff: [] }` and writes nothing.
+  - `src/cli.ts`: `hazo-env sync upload-files --skip-env`.
+  - `src/envsync/service.ts`: `POST /files/restore` accepts `{ "skipEnv": true }`; the `serve` control page gains a "skip .env.local" checkbox.
+- **Tests:** `__tests__/envsync-engine-files.test.ts` adds confirmed-restore-with-skipEnv (files replaced, `.env.local` byte-identical, no `.bak-` written) and dry-run-with-skipEnv (empty diff, zero writes) cases.
+
 ## 0.8.0 — 2026-07-23
 
 ### Removed / Breaking

package/README.md

@@ -165,6 +165,7 @@ hazo-env sync upload-db --dump <path> --confirm     # pg_restore into target_db
 hazo-env sync download-files                        # tar files_root (+ current .env.local) → work_dir
 hazo-env sync upload-files --archive <path>         # dry-run: prints the .env.local diff it would apply
 hazo-env sync upload-files --archive <path> --confirm  # actually restores files + merges env overrides
+hazo-env sync upload-files --archive <path> --confirm --skip-env  # restore files only; leave .env.local untouched
 
 hazo-env serve [--port <n>] [--bind <host>]         # HTTP service over the same engine — requires HAZO_ENVSYNC_TOKEN
 ```
@@ -178,7 +179,7 @@ hazo-env current                       # prints env, role, pattern, app, data_ro
 hazo-env doctor [--env <e>] [--all]    # red/green validation table
 
 hazo-env sync download-db | upload-db --dump <p> [--confirm] [--allow-prod-target]
-hazo-env sync download-files | upload-files --archive <p> [--confirm] [--allow-prod-target]
+hazo-env sync download-files | upload-files --archive <p> [--confirm] [--allow-prod-target] [--skip-env]
 hazo-env serve [--port <n>] [--bind <host>]   # requires HAZO_ENVSYNC_TOKEN
 ```
 

package/dist/cli.js

@@ -88,6 +88,7 @@ ${pc.bold('hazo-env sync')} — local Postgres/files sync (pg_dump/pg_restore/ta
   hazo-env sync download-files                        Archive files_root (+ .env.local) to work_dir
   hazo-env sync upload-files --archive <path>         Restore an archive into files_root + .env.local
     --confirm --allow-prod-target                     Required to apply (else prints a diff preview)
+    --skip-env                                        Restore files only; leave .env.local untouched
 `);
         return;
     }
@@ -128,14 +129,20 @@ ${pc.bold('hazo-env sync')} — local Postgres/files sync (pg_dump/pg_restore/ta
             const archivePath = archiveIdx >= 0 ? subArgs[archiveIdx + 1] : undefined;
             const confirm = subArgs.includes('--confirm');
             const allowProd = subArgs.includes('--allow-prod-target');
+            const skipEnv = subArgs.includes('--skip-env');
             if (!archivePath) {
                 console.error(pc.red('Error: sync upload-files requires --archive <path>'));
                 process.exit(1);
             }
-            console.log(`\n${pc.bold('hazo-env sync upload-files')} ${pc.dim(archivePath)}${confirm ? '' : pc.dim('  (preview — pass --confirm to apply)')}\n`);
-            const result = await withLock(cfg.work_dir, 'upload_files', () => uploadFiles(cfg, archivePath, { confirm, allowProd, onProgress }));
+            console.log(`\n${pc.bold('hazo-env sync upload-files')} ${pc.dim(archivePath)}${skipEnv ? pc.dim('  (--skip-env: .env.local left untouched)') : ''}${confirm ? '' : pc.dim('  (preview — pass --confirm to apply)')}\n`);
+            const result = await withLock(cfg.work_dir, 'upload_files', () => uploadFiles(cfg, archivePath, { confirm, allowProd, skipEnv, onProgress }));
             console.log('');
-            printEnvOverrideDiff(result.diff);
+            if (skipEnv) {
+                console.log(`  ${pc.dim('· .env.local skipped (--skip-env) — no env diff computed, target left as-is')}`);
+            }
+            else {
+                printEnvOverrideDiff(result.diff);
+            }
             if (result.ok) {
                 console.log(`\n  ${pc.green('✓')} Restored -> ${cfg.files_root}\n`);
             }
@@ -189,6 +196,7 @@ Usage:
   hazo-env sync download-files              Archive files_root (+ .env.local) to work_dir
   hazo-env sync upload-files --archive <p>  Restore an archive into files_root + .env.local
     --confirm --allow-prod-target           Required to apply (else prints a diff preview)
+    --skip-env                              Restore files only; leave .env.local untouched
   hazo-env serve                            Start the envsync HTTP service (HAZO_ENVSYNC_TOKEN required)
     --port <n> --bind <host>                Override HAZO_ENVSYNC_PORT / HAZO_ENVSYNC_BIND
 `);

package/dist/envsync/engine.d.ts

@@ -66,6 +66,14 @@ export declare function downloadFiles(cfg: EnvsyncConfig, opts?: {
 export declare function uploadFiles(cfg: EnvsyncConfig, archivePath: string, opts: {
     confirm?: boolean;
     allowProd?: boolean;
+    /**
+     * Restore files_root but leave the target `.env.local` completely
+     * untouched — no backup, no merge, no write. Use when the destination
+     * env is hand-maintained (e.g. a laptop dev site whose local URLs/secrets
+     * must survive a prod files refresh). When set, the returned `diff` is
+     * empty because no env comparison is performed.
+     */
+    skipEnv?: boolean;
     onProgress?: (msg: string) => void;
 }): Promise<{
     ok: true;

package/dist/envsync/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/envsync/engine.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAaD;;GAEG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,aAAa,EAClB,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,iBAAiB,CAAC,CAY5B;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACnF,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC,CAwBvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,iBAAiB,CAAC,CA0B5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,aAAa,EAClB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACnF,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC,CAqDzF"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/envsync/engine.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAaD;;GAEG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,aAAa,EAClB,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,iBAAiB,CAAC,CAY5B;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACnF,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC,CAwBvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,iBAAiB,CAAC,CA0B5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,aAAa,EAClB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IACJ,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC,GACA,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC,CAgEzF"}

package/dist/envsync/engine.js

@@ -109,33 +109,40 @@ export async function downloadFiles(cfg, opts) {
  * the archive, and writes the merged .env.local.
  */
 export async function uploadFiles(cfg, archivePath, opts) {
-    const extractDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hazo_envsync_extract_'));
-    let archiveEnvText = '';
-    try {
-        await runCmd('tar', ['-xzf', archivePath, '-C', extractDir, ENV_LOCAL_MEMBER], {
-            onProgress: opts.onProgress,
-        });
-        const extractedEnvLocal = path.join(extractDir, ENV_LOCAL_MEMBER);
-        if (fs.existsSync(extractedEnvLocal)) {
-            archiveEnvText = fs.readFileSync(extractedEnvLocal, 'utf8');
+    const targetEnvLocalPath = path.join(process.cwd(), '.env.local');
+    // When skipEnv is set we never read/merge/diff the archive's env member —
+    // the env half of upload-files is opted out of entirely, so the diff is
+    // empty and no .env.local is ever backed up or written below.
+    let diff = [];
+    let merged = {};
+    if (!opts.skipEnv) {
+        const extractDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hazo_envsync_extract_'));
+        let archiveEnvText = '';
+        try {
+            await runCmd('tar', ['-xzf', archivePath, '-C', extractDir, ENV_LOCAL_MEMBER], {
+                onProgress: opts.onProgress,
+            });
+            const extractedEnvLocal = path.join(extractDir, ENV_LOCAL_MEMBER);
+            if (fs.existsSync(extractedEnvLocal)) {
+                archiveEnvText = fs.readFileSync(extractedEnvLocal, 'utf8');
+            }
         }
+        finally {
+            fs.rmSync(extractDir, { recursive: true, force: true });
+        }
+        const archiveEnv = parseDotenvText(archiveEnvText);
+        merged = mergeEnvOverrides(archiveEnv, cfg.envOverrides);
+        const currentEnvText = fs.existsSync(targetEnvLocalPath)
+            ? fs.readFileSync(targetEnvLocalPath, 'utf8')
+            : '';
+        const currentEnv = parseDotenvText(currentEnvText);
+        diff = diffEnvAgainstCurrent(merged, currentEnv);
     }
-    finally {
-        fs.rmSync(extractDir, { recursive: true, force: true });
-    }
-    const archiveEnv = parseDotenvText(archiveEnvText);
-    const merged = mergeEnvOverrides(archiveEnv, cfg.envOverrides);
-    const targetEnvLocalPath = path.join(process.cwd(), '.env.local');
-    const currentEnvText = fs.existsSync(targetEnvLocalPath)
-        ? fs.readFileSync(targetEnvLocalPath, 'utf8')
-        : '';
-    const currentEnv = parseDotenvText(currentEnvText);
-    const diff = diffEnvAgainstCurrent(merged, currentEnv);
     if (!opts.confirm) {
         return { ok: false, diff };
     }
     assertNotProd(cfg.target_db, cfg.prodDbNames, opts.allowProd);
-    if (fs.existsSync(targetEnvLocalPath)) {
+    if (!opts.skipEnv && fs.existsSync(targetEnvLocalPath)) {
         const ts = Date.now();
         fs.copyFileSync(targetEnvLocalPath, `${targetEnvLocalPath}.bak-${ts}`);
     }
@@ -146,10 +153,13 @@ export async function uploadFiles(cfg, archivePath, opts) {
     await runCmd('tar', ['-xzf', archivePath, '-C', cfg.files_root], { onProgress: opts.onProgress });
     // __env.local extracts as a real file inside files_root — it isn't a real
     // asset, so remove it rather than trying to get tar to exclude it during
-    // extraction (simplest correct approach per spec).
+    // extraction (simplest correct approach per spec). Done regardless of
+    // skipEnv: the member is in the archive either way.
     const extractedEnvMember = path.join(cfg.files_root, ENV_LOCAL_MEMBER);
     if (fs.existsSync(extractedEnvMember))
         fs.rmSync(extractedEnvMember, { force: true });
-    fs.writeFileSync(targetEnvLocalPath, serializeDotenv(merged));
+    if (!opts.skipEnv) {
+        fs.writeFileSync(targetEnvLocalPath, serializeDotenv(merged));
+    }
     return { ok: true, diff };
 }

package/dist/envsync/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/envsync/service.ts"],"names":[],"mappings":"AA4BA,OAAO,IAAI,MAAM,WAAW,CAAC;AAgB7B,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IACpB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA4VD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,0BAA+B,GAAG,oBAAoB,CA8B/F"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/envsync/service.ts"],"names":[],"mappings":"AA4BA,OAAO,IAAI,MAAM,WAAW,CAAC;AAgB7B,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IACpB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA+VD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,0BAA+B,GAAG,oBAAoB,CA8B/F"}

package/dist/envsync/service.js

@@ -220,6 +220,7 @@ async function handleFilesRestore(req, res) {
         const result = await withLock(cfg.work_dir, 'upload_files', () => uploadFiles(cfg, archivePath, {
             confirm: body['confirm'] === true,
             allowProd: body['allowProd'] === true,
+            skipEnv: body['skipEnv'] === true,
             onProgress: progressLogger('upload_files'),
         }));
         sendJson(res, 200, result);
@@ -286,6 +287,7 @@ function controlPageHtml() {
   <div class="row">
     <label><input type="checkbox" id="filesConfirm" /> confirm</label>
     <label><input type="checkbox" id="filesAllowProd" /> allow prod</label>
+    <label><input type="checkbox" id="filesSkipEnv" /> skip .env.local</label>
     <button id="filesRestore" type="button">Restore Files</button>
   </div>
 </section>
@@ -335,6 +337,7 @@ document.getElementById('filesRestore').addEventListener('click', function () {
     archivePath: document.getElementById('archivePath').value,
     confirm: document.getElementById('filesConfirm').checked,
     allowProd: document.getElementById('filesAllowProd').checked,
+    skipEnv: document.getElementById('filesSkipEnv').checked,
   });
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_env",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Canonical environment resolver — typed env names, per-env DB/file/secret config, doctor and CLI for hazo apps",
   "type": "module",
   "main": "./dist/index.js",