hazo_env 0.6.1 → 0.8.0

package/CHANGE_LOG.md

@@ -1,5 +1,42 @@
 # hazo_env — Change Log
 
+## 0.8.0 — 2026-07-23
+
+### Removed / Breaking
+The old SSH/PostgREST-row-copy migration stack is fully removed — it predates `envsync` (0.7.0) and is completely superseded by it. `envsync` (`hazo-env sync download-db|upload-db|download-files|upload-files`, `hazo-env serve`) is the only supported way to move a DB or files between environments going forward; it runs entirely local `pg_dump`/`pg_restore`/`tar`, no SSH, no PostgREST row copy.
+
+- **Deleted modules:** `src/migrate/transport.ts`, `src/migrate/db.ts`, `src/migrate/db.postgrest.ts`, `src/migrate/db-dump-restore.ts`, `src/migrate/files.ts` (rsync-over-SSH), `src/migrate/snapshot.ts`, `src/migrate/verify.ts`, `src/migrate/audit.ts`, `src/mask/registry.ts`, `src/mask/ruleset.ts` (all of `src/mask/`), `src/resolve/backup.ts`, `src/resolve/migrate.ts`.
+- **Deleted orchestrators (cascade — their entire purpose was wiring the modules above):** `src/migrate/run.ts` (`runMigration`), `src/migrate/clear.ts` (`clearEnv`), `src/migrate/progress.ts` (`writeMigrationProgress`/`readMigrationProgress`/`clearMigrationProgress` — had no remaining caller once `run.ts`/`clear.ts` were gone).
+- **Removed exports from `src/index.ts`:** `runMigration`, `clearEnv`, `verifyFiles`, `takeSnapshot`, `restoreSnapshot`, `writeMigrationProgress`, `readMigrationProgress`, `clearMigrationProgress`, `registerMask`, `loadRuleset`, `syncRulesetFromIni`, `parseIniRules`, `resolveBackupConfig`, `restoreDbViaDump`. Removed types: `MaskRule`, `MaskTransform`, `BackupConfig`.
+- **Removed types from `src/types/index.ts`:** `TransportMode`, `ScrubMode`, `HashMode`, `MigrationProgress`, `MigrationRequest`, `MigrationResult`, `VerifyReport`, `MigrateConfig`, `ClearRequest`, `ClearResult`, `MaskTransform`.
+- **Removed CLI commands:** `hazo-env migrate`, `hazo-env verify`, `hazo-env snapshot`, `hazo-env restore`, `hazo-env mask sync|list`, `hazo-env clear`. Remaining commands: `current`, `doctor`, `sync`, `serve`.
+- **Kept as generic, currently-unconsumed-in-this-repo infra** (per explicit design decision — `hazo_env` is a shared package, and these are SSH-exec primitives, not migration-specific): `runSsh`, `assertSafeSshField` (`src/migrate/ssh-exec.ts`), `resolveSshConfig` (`src/resolve/ssh.ts`), `src/resolve/connect.ts`, `src/resolve/files.ts`, `src/env.server.ts`, `src/doctor.ts` — all still exported from `src/index.ts` exactly as before.
+- **test-app:** removed `/migrate`, `/masking`, `/verify` pages + nav entries, `/api/migrate`, `/api/clear`, `/api/verify` routes, `config/hazo_env_masking.ini`, and the `verify-fixtures`/`clear-env` harness scenarios (both drove the now-deleted API routes). `scripts/seed.mjs` no longer seeds the `hazo_users` PII fixture or `hazo_files`/on-disk verify fixtures — nothing consumes them anymore.
+- **Removed `config/hazo_env_masking.ini.sample`** — sample masking ruleset, orphaned now that `mask sync` / `registerMask()` no longer exist.
+- **Removed test suites:** `__tests__/migration.test.ts`, `__tests__/masking.test.ts`, `__tests__/verify.test.ts`, `__tests__/backup.test.ts`, `__tests__/progress.test.ts` (all covered deleted modules).
+
+### Migration guide
+Replace any `runMigration({ from, to, ... })` call with `hazo-env sync download-db` on the source host + `hazo-env sync upload-db --dump <path> --confirm` on the target, or the equivalent `downloadDb`/`uploadDb` from `hazo_env/dist/envsync/engine.js` for programmatic use. Files: `hazo-env sync download-files` / `upload-files`. There is no PII-masking pass in `envsync` — if you relied on `registerMask()`/`hazo_env_masking.ini`, scrub the dump/archive yourself before `upload-db`/`upload-files` (or scrub at the destination) until/unless masking is reintroduced as an `envsync` feature.
+
+## 0.7.0 — 2026-07-23
+
+### Added
+- **`envsync`** — local Postgres/files sync engine, independent of the existing SSH-based `migrate`/`backup` transports. Orchestrates `pg_dump`/`pg_restore`/`dropdb`/`createdb`/`tar` as real argv (never shell-string-built) against local Postgres + a local files root.
+  - `src/envsync/engine.ts`: `downloadDb`, `uploadDb`, `downloadFiles`, `uploadFiles`. `downloadFiles` packs the current `.env.local` into the archive under a fixed member name; `uploadFiles` extracts it, merges `[migrate.env_overrides]` on top, and diffs the result against the *current* target `.env.local` before ever writing (dry-run by default — pass `confirm:true` to apply).
+  - `src/envsync/lock.ts`: `withLock()` — single-run guard (in-process + on-disk `<work_dir>/.envsync.lock`, self-healing on a dead PID) so two envsync ops (CLI or HTTP) can never race each other.
+  - `src/envsync/retention.ts`: `pruneWorkDir()` (keep-N per file kind) + `assertFreeSpace()` (500MiB floor before writing a new dump/archive).
+  - `src/envsync/guards.ts`: `assertConfirmed` / `assertNotProd` — destructive ops (`uploadDb`, confirmed `uploadFiles`) refuse to run without an explicit `confirm:true`, and refuse a target that looks like production without `allowProd:true`.
+  - `src/resolve/envsync.ts`: `resolveEnvsyncConfig()` — reads `[envsync]` + `[migrate.env_overrides]` from `hazo_env_config.ini`, `${VAR}`-expanded, null-on-missing (mirrors `resolveBackupConfig`).
+- **`hazo-env sync` CLI** — `download-db`, `upload-db --dump <path> [--confirm] [--allow-prod-target]`, `download-files`, `upload-files --archive <path> [--confirm] [--allow-prod-target]`. Every op runs under `withLock`; `upload-files` without `--confirm` pretty-prints the env-var diff preview (key, before → after) instead of writing anything.
+- **`hazo-env serve` CLI + `startEnvsyncService()`** (`src/envsync/service.ts`) — a plain `node:http` service (no framework dependency) exposing the same engine over HTTP, for driving envsync from a browser/ops UI instead of a terminal:
+  - `GET /status`, `POST /db/download`, `POST /db/upload`, `POST /files/archive`, `POST /files/restore`, plus `GET /` — a minimal self-contained HTML control page (inline CSS/JS, no build step, no external assets).
+  - Security model: every route requires `Authorization: Bearer <HAZO_ENVSYNC_TOKEN>` (no exceptions — the server refuses to start at all if the token env var is unset); binds `127.0.0.1` by default (`HAZO_ENVSYNC_BIND` to widen); default port `7845` (`HAZO_ENVSYNC_PORT` to override); every write op goes through the same `withLock` + `assertConfirmed`/`assertNotProd` guards the CLI uses, so the HTTP layer adds no bypass — a concurrent request gets `409`, an unconfirmed/prod-looking destructive op gets `400`.
+  - `startEnvsyncService(opts?: {port, bind, token})` — opts override env vars, making the service testable with `port: 0` (OS-assigned ephemeral port) and no real token/env-var setup.
+
+### Notes
+- `envsync` is a server/ops-only surface (CLI + HTTP service) — it is not wired into the browser-based `hazo_ui` autotest harness in `test-app/` (that harness only exercises pure client-safe functions; `envsync` needs a real local Postgres + real `files_root`). Its behavior is verified in `__tests__/envsync-*.test.ts`, in particular `__tests__/envsync-service.test.ts` for the HTTP surface.
+- `src/envsync/*` and `src/resolve/envsync.ts` are not re-exported from the package's `index.ts` — reach them via `hazo_env/dist/envsync/*` / the `hazo-env` CLI, not the public API surface.
+
 ## 0.6.1 — 2026-07-21
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # hazo_env
 
-Canonical environment resolver for hazo apps. Typed env names, per-env DB/file/secret config, a DB+files migration engine with PII masking, a `doctor` diagnostic command, and a `hazo-env` CLI.
+Canonical environment resolver for hazo apps. Typed env names, per-env DB/file/secret config, a local Postgres/files sync engine (`envsync`), a `doctor` diagnostic command, and a `hazo-env` CLI.
 
 ## What it does
 
@@ -8,10 +8,9 @@ Canonical environment resolver for hazo apps. Typed env names, per-env DB/file/s
 - **Per-env DB config** — `resolveConnectConfig()` maps the current env to its `hazo_connect` config (SQLite or PostgREST) with zero hardcoded connection strings in app code.
 - **Per-env file config** — `resolveFilesConfig()` maps the current env to a `hazo_files` config rooted at the declared `data_root`.
 - **Secrets** — `getSecret()` resolves from `.env.local` only; placeholders in `hazo_env_config.ini` are substituted at runtime without storing secrets.
-- **Migration engine** — `runMigration({ from, to })` copies a DB + files between envs. Validates → snapshots target → copies tables (paged, schema-checked) → copies files → verifies → writes hazo_audit entry. Prod target refused without an explicit confirm token.
-- **PII masking** — masking rules declared per table/column in `hazo_env_masking.ini` (seed) and synced to `hazo_app_config` at runtime. Built-in transforms: `mask_email`, `fake_name`, `mask_phone`, `jitter_date`, `hash`, `tokenize`, `drop`, `nullify`. Custom transforms via `registerMask()`. Applied automatically when the migration target role is `test` or `staging`.
-- **Doctor** — `doctor()` / `hazo-env doctor` validates pattern, DB reachability, required secrets (no values printed), data_root writability, schema level, and (with `--probe --all`) migration parity across envs + masking ruleset column validation.
-- **CLI** — `hazo-env current | doctor | snapshot | migrate | verify | restore | mask`.
+- **`envsync`** — local Postgres/files sync engine (`hazo-env sync` / `hazo-env serve`). Dumps/restores a database via `pg_dump`/`pg_restore` and archives/restores a files root via `tar`, entirely on one host — no SSH, no PostgREST row-copy. See "envsync" below.
+- **Doctor** — `doctor()` / `hazo-env doctor` validates pattern, DB reachability, required secrets (no values printed), data_root writability, schema level, and (with `--probe --all`) migration parity across envs.
+- **CLI** — `hazo-env current | doctor | sync | serve`.
 
 ## Installation
 
@@ -20,7 +19,7 @@ npm install hazo_env
 ```
 
 Peer deps (required): `hazo_core`, `hazo_config`.
-Peer deps (optional): `hazo_connect` (for `resolveConnectConfig`), `hazo_files` (for `resolveFilesConfig`), `hazo_secure` (for masking transforms), `hazo_pdf` (for `mask_pdf` transform), `hazo_audit` (for migration audit entries).
+Peer deps (optional): `hazo_connect` (for `resolveConnectConfig`), `hazo_files` (for `resolveFilesConfig`).
 
 ## Quick start
 
@@ -154,73 +153,33 @@ const report = await doctor({ probe: true, all: true });
 // masking ruleset column validation against live schema.
 ```
 
-### Migration engine (server-only)
+### envsync — local Postgres/files sync (server/ops-only)
 
-```ts
-import { runMigration, verifyFiles, takeSnapshot, restoreSnapshot,
-         writeMigrationProgress, readMigrationProgress, clearMigrationProgress } from 'hazo_env';
-
-// Copy prod → staging (with PII masking applied automatically)
-const result = await runMigration({
-  from: 'prod',
-  to: 'staging',
-  dryRun: false,                         // set true for a plan with counts, no writes
-  // allowProdTarget: true,              // required when `to` is 'prod'
-  // confirmToken: '<token>',            // required together with allowProdTarget
-  onProgress: (p) => console.log(p.phase, p.message),
-  // jobId: '<id>',                      // optional — persist progress to progressDir/<id>.json
-  // progressDir: '/tmp/hazo_jobs',      // required when jobId is set
-});
-// result.ok, result.db, result.files, result.snapshotId, result.warnings, result.durationMs
-
-// Stand-alone verification (with optional hazo_connect adapter for L2–L5 checks)
-await verifyFiles('staging', dataRoot, { hash: 'sample', checkOrphans: true, adapter });
-// report.ok, report.checked, report.hashed, report.missing[], report.sizeMismatch[],
-// report.hashMismatch[], report.orphans[], report.skippedReason?
-
-// Manual snapshot / restore
-const snap = takeSnapshot(connectConfig);   // returns { snapshotId }
-restoreSnapshot(connectConfig, snapshotId);
-
-// Filesystem progress store (used by hazo_jobs integration)
-writeMigrationProgress(dir, jobId, progress);
-readMigrationProgress(dir, jobId);    // → MigrationProgress | null
-clearMigrationProgress(dir, jobId);
-```
-
-**Masking** — customize per table/column in `config/hazo_env_masking.ini`. Sync to the DB with `hazo-env mask sync`. Register custom transforms with `registerMask(name, fn)`.
+`envsync` copies a database or files root between environments that live on the same host (or where you're willing to move a dump/archive by hand) using plain `pg_dump`/`pg_restore`/`tar` — no SSH, no PostgREST row-copy loop, no masking pass. It's driven via the CLI or an optional local HTTP service; the engine functions (`downloadDb`, `uploadDb`, `downloadFiles`, `uploadFiles`) live at `hazo_env/dist/envsync/engine.js` and are intentionally **not** re-exported from the package's main `index.ts` — reach them through that subpath or through the CLI.
 
-**Masking ruleset API** — load, parse, and sync rulesets programmatically:
+```bash
+# Config: [envsync] section in hazo_env_config.ini — source_db, target_db, files_root, work_dir, keep
 
-```ts
-import { loadRuleset, syncRulesetFromIni, parseIniRules } from 'hazo_env';
-import type { MaskRule } from 'hazo_env';
+hazo-env sync download-db                          # pg_dump source_db → work_dir
+hazo-env sync upload-db --dump <path> --confirm     # pg_restore into target_db (--allow-prod-target for a prod target)
+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
 
-const rules: MaskRule[] = parseIniRules(iniText);           // parse INI text → rules array
-const loaded  = await loadRuleset(adapter);                 // read from hazo_app_config DB
-await syncRulesetFromIni(adapter, '/path/to/masking.ini'); // write parsed rules to DB
+hazo-env serve [--port <n>] [--bind <host>]         # HTTP service over the same engine — requires HAZO_ENVSYNC_TOKEN
 ```
 
+Every destructive op runs under a single-writer lock (`withLock`) and refuses to touch anything that looks like a production target without `--allow-prod-target` (`allowProd: true` programmatically). See `CHANGE_LOG.md` (0.7.0 entry) for the full engine/service design notes.
+
 ## CLI
 
 ```
 hazo-env current                       # prints env, role, pattern, app, data_root
 hazo-env doctor [--env <e>] [--all]    # red/green validation table
-hazo-env snapshot <env>                # snapshot the target env DB
 
-hazo-env migrate --from <env> --to <env> [options]
-  --transport auto|local|ssh|api       # default auto
-  --no-db | --no-files                 # skip DB or file copy
-  --scrub auto|none                    # default auto (mask when target is test/staging)
-  --tables a,b,c                       # restrict to specific tables
-  --dry-run                            # plan + counts, no writes
-  --allow-prod-target --confirm <tok>  # required when writing prod
-
-hazo-env verify <env> [--hash none|sample|full] [--no-orphans]
-hazo-env restore <env> --snapshot <snapshot-id>
-
-hazo-env mask sync                     # sync hazo_env_masking.ini → hazo_app_config
-hazo-env mask list                     # print active masking rules
+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 serve [--port <n>] [--bind <host>]   # requires HAZO_ENVSYNC_TOKEN
 ```
 
 ## Config reference (`hazo_env_config.ini`)
@@ -235,46 +194,7 @@ Key sections:
 
 Secret placeholders use `${ENV_VAR_NAME}` syntax — hazo_env substitutes them from `.env.local` at runtime.
 
-## dump-restore transport
-
-The `dump-restore` transport copies a database via SSH `pg_dump`/`pg_restore` (binary format). Use it when the source and target share the same Postgres server (e.g. prod→dev on the same VPS) and you want a fast binary copy without going through the PostgREST row-copy loop.
-
-### Config: `[backup.<env>]`
-
-Add a section to `config/hazo_env_config.ini`:
-
-```ini
-[backup.dev]
-ssh_env         = prod         ; reuse [transport.ssh.prod] SSH connection
-target_db       = myapp_dev    ; DB to drop/recreate
-owner           = adminuser    ; createdb -O <owner>
-dump_source     = /var/backups/myapp-*.pgdump  ; glob (newest used) or "fresh"
-fresh_dump_db   = myapp        ; source DB for pg_dump when dump_source=fresh
-pre_restore_cmd = sudo systemctl stop myapp-postgrest-dev
-post_restore_cmd= sudo systemctl start myapp-postgrest-dev
-```
-
-> **No PII scrubbing on this path.** The binary `pg_restore` copies raw rows; hazo_env's `scrubHook` only runs inside the PostgREST row-copy loop. If you need scrubbed data in dev, use the default `api` transport instead.
-
-### CLI
-
-```bash
-npx hazo-env migrate --from prod --to dev --transport dump-restore
-```
-
-### Programmatic API
-
-```ts
-import { resolveBackupConfig, restoreDbViaDump } from 'hazo_env';
-
-const backup = resolveBackupConfig('dev'); // reads [backup.dev] from INI
-if (backup) {
-  const result = await restoreDbViaDump(backup, {
-    onProgress: (msg) => console.log(msg),
-  });
-  // result.mode === 'dump-restore'
-}
-```
+For `envsync`'s own `[envsync]` / `[migrate.env_overrides]` config sections, see the `envsync` section above and `CHANGE_LOG.md` (0.7.0 entry).
 
 ## License
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// hazo_env/src/cli.ts — CLI entry: hazo-env current | doctor | snapshot | migrate | verify | restore
+// hazo_env/src/cli.ts — CLI entry: hazo-env current | doctor | sync | serve
 import pc from 'picocolors';
 import { getEnv } from './index.client.js';
 import { describeEnv, getEnvRole, getPattern } from './env.server.js';
@@ -58,201 +58,120 @@ async function runDoctor() {
         process.exit(1);
     }
 }
-async function runSnapshot() {
-    const targetEnv = args[0] ?? getEnv();
-    console.log(`\n${pc.bold('hazo-env snapshot')} ${pc.dim(targetEnv)}\n`);
-    const { takeSnapshot } = await import('./migrate/snapshot.js');
-    const { resolveConnectConfig } = await import('./resolve/connect.js');
-    const toConfig = resolveConnectConfig({ env: targetEnv, allowOtherEnv: true });
-    const result = takeSnapshot(toConfig);
-    console.log(`  ${pc.green('✓')} Snapshot: ${result.snapshotId}\n`);
+function printEnvOverrideDiff(diff) {
+    if (!diff.length) {
+        console.log(`  ${pc.dim('(no env vars to apply)')}`);
+        return;
+    }
+    console.log(`  ${pc.bold('.env.local changes:')}`);
+    const keyWidth = Math.max(...diff.map((d) => d.key.length)) + 2;
+    for (const d of diff) {
+        const marker = d.before === d.after ? pc.dim('=') : pc.yellow('~');
+        const before = d.before ?? pc.dim('(unset)');
+        console.log(`  ${marker} ${d.key.padEnd(keyWidth)} ${before} -> ${d.after}`);
+    }
 }
-async function runMigrate() {
-    const fromIdx = args.findIndex((a) => a === '--from');
-    const toIdx = args.findIndex((a) => a === '--to');
-    const from = fromIdx >= 0 ? args[fromIdx + 1] : undefined;
-    const to = toIdx >= 0 ? args[toIdx + 1] : undefined;
-    const dryRun = args.includes('--dry-run');
-    const noFiles = args.includes('--no-files');
-    const noDb = args.includes('--no-db');
-    const allowProdTarget = args.includes('--allow-prod-target');
-    const confirmIdx = args.findIndex((a) => a === '--confirm');
-    const confirmToken = confirmIdx >= 0 ? args[confirmIdx + 1] : undefined;
-    const tablesIdx = args.findIndex((a) => a === '--tables');
-    const tablesArg = tablesIdx >= 0 ? args[tablesIdx + 1] : undefined;
-    const tables = tablesArg ? tablesArg.split(',').map((t) => t.trim()) : undefined;
-    const transportIdx = args.findIndex((a) => a === '--transport');
-    const transport = transportIdx >= 0 ? args[transportIdx + 1] : undefined;
-    if (!from || !to) {
-        console.error(pc.red('Error: migrate requires --from <env> and --to <env>'));
+async function runSync() {
+    const subCmd = args[0];
+    const subArgs = args.slice(1);
+    const { resolveEnvsyncConfig } = await import('./resolve/envsync.js');
+    const { withLock, EnvsyncLockError } = await import('./envsync/lock.js');
+    const { pruneWorkDir } = await import('./envsync/retention.js');
+    const { downloadDb, uploadDb, downloadFiles, uploadFiles } = await import('./envsync/engine.js');
+    if (!subCmd || !['download-db', 'upload-db', 'download-files', 'upload-files'].includes(subCmd)) {
+        console.log(`
+${pc.bold('hazo-env sync')} — local Postgres/files sync (pg_dump/pg_restore/tar)
+
+  hazo-env sync download-db                          Dump [envsync] source_db to work_dir
+  hazo-env sync upload-db --dump <path>               Restore a dump into target_db
+    --confirm --allow-prod-target                     Required to actually apply
+  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)
+`);
+        return;
+    }
+    const cfg = resolveEnvsyncConfig();
+    if (!cfg) {
+        console.error(pc.red('Error: envsync not configured — missing [envsync] section in hazo_env_config.ini'));
         process.exit(1);
     }
-    console.log(`\n${pc.bold('hazo-env migrate')}  ${pc.dim(`${from} → ${to}${dryRun ? ' (dry-run)' : ''}`)}\n`);
-    const { runMigration } = await import('./migrate/run.js');
+    const onProgress = (msg) => console.log(`  ${pc.dim('·')} ${msg}`);
     try {
-        const result = await runMigration({
-            from,
-            to,
-            include: { db: !noDb, files: !noFiles },
-            tables: tables ?? '*',
-            dryRun,
-            allowProdTarget,
-            confirmToken,
-            transport: transport,
-            onProgress: (p) => {
-                const pct = p.percent != null ? `${p.percent}%`.padStart(4) + ' ' : '     ';
-                console.log(`  ${pct}${pc.dim(p.phase.padEnd(12))} ${p.message}`);
-            },
-        });
-        if (result.ok) {
-            console.log(`\n  ${pc.green('✓')} Migration ${dryRun ? 'plan built (dry-run)' : 'complete'}`);
-            if (result.db)
-                console.log(`  ${pc.dim('DB:')} ${result.db.tables} tables, ${result.db.rows} rows${result.db.scrubbed ? `, ${result.db.scrubbed} scrubbed` : ''}`);
-            if (result.files)
-                console.log(`  ${pc.dim('Files:')} ${result.files.copied} copied`);
-            if (result.snapshotId && !result.snapshotId.startsWith('no-db:'))
-                console.log(`  ${pc.dim('Snapshot:')} ${result.snapshotId}`);
-            if (result.warnings.length)
-                result.warnings.forEach((w) => console.log(`  ${pc.yellow('⚠')} ${w}`));
+        if (subCmd === 'download-db') {
+            console.log(`\n${pc.bold('hazo-env sync download-db')} ${pc.dim(cfg.source_db)}\n`);
+            const result = await withLock(cfg.work_dir, 'download_db', () => downloadDb(cfg, { onProgress }));
+            pruneWorkDir(cfg.work_dir, { keep: cfg.keep });
+            console.log(`\n  ${pc.green('✓')} Dumped -> ${result.path} (${result.bytes} bytes)\n`);
+        }
+        else if (subCmd === 'upload-db') {
+            const dumpIdx = subArgs.findIndex((a) => a === '--dump');
+            const dumpPath = dumpIdx >= 0 ? subArgs[dumpIdx + 1] : undefined;
+            const confirm = subArgs.includes('--confirm');
+            const allowProd = subArgs.includes('--allow-prod-target');
+            if (!dumpPath) {
+                console.error(pc.red('Error: sync upload-db requires --dump <path>'));
+                process.exit(1);
+            }
+            console.log(`\n${pc.bold('hazo-env sync upload-db')} ${pc.dim(`${dumpPath} -> ${cfg.target_db}`)}\n`);
+            await withLock(cfg.work_dir, 'upload_db', () => uploadDb(cfg, dumpPath, { confirm, allowProd, onProgress }));
+            console.log(`\n  ${pc.green('✓')} Restored -> ${cfg.target_db}\n`);
+        }
+        else if (subCmd === 'download-files') {
+            console.log(`\n${pc.bold('hazo-env sync download-files')} ${pc.dim(cfg.files_root)}\n`);
+            const result = await withLock(cfg.work_dir, 'download_files', () => downloadFiles(cfg, { onProgress }));
+            pruneWorkDir(cfg.work_dir, { keep: cfg.keep });
+            console.log(`\n  ${pc.green('✓')} Archived -> ${result.path} (${result.bytes} bytes)\n`);
+        }
+        else if (subCmd === 'upload-files') {
+            const archiveIdx = subArgs.findIndex((a) => a === '--archive');
+            const archivePath = archiveIdx >= 0 ? subArgs[archiveIdx + 1] : undefined;
+            const confirm = subArgs.includes('--confirm');
+            const allowProd = subArgs.includes('--allow-prod-target');
+            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('');
+            printEnvOverrideDiff(result.diff);
+            if (result.ok) {
+                console.log(`\n  ${pc.green('✓')} Restored -> ${cfg.files_root}\n`);
+            }
+            else {
+                console.log(`\n  ${pc.yellow('⚠')} Dry-run only — re-run with --confirm to apply\n`);
+            }
         }
     }
     catch (e) {
+        if (e instanceof EnvsyncLockError) {
+            console.error(`\n  ${pc.red('✗')} ${e.message}\n`);
+            process.exit(1);
+        }
         const msg = e instanceof Error ? e.message : String(e);
         console.error(`\n  ${pc.red('✗')} ${msg}\n`);
         process.exit(1);
     }
-    console.log('');
-}
-async function runVerify() {
-    const targetEnv = args[0] ?? getEnv();
-    // Parse --hash full|sample|none (default: sample) and --no-orphans
-    const hashIdx = args.indexOf('--hash');
-    const hashArg = hashIdx >= 0 ? args[hashIdx + 1] : 'sample';
-    const hash = (hashArg === 'full' || hashArg === 'none' || hashArg === 'sample') ? hashArg : 'sample';
-    const checkOrphans = !args.includes('--no-orphans');
-    console.log(`\n${pc.bold('hazo-env verify')} ${pc.dim(targetEnv)} ${pc.dim(`--hash ${hash}`)}\n`);
-    const { verifyFiles } = await import('./migrate/verify.js');
-    const { resolveFilesConfig } = await import('./resolve/files.js');
-    const dataRoot = resolveFilesConfig().local.basePath;
-    const report = await verifyFiles(targetEnv, dataRoot, { hash, checkOrphans });
-    if (report.skippedReason) {
-        console.log(`  ${pc.yellow('⚠')} ${report.skippedReason}`);
-    }
-    console.log(`  Checked: ${report.checked} files${report.hashed != null ? `, hashed: ${report.hashed}` : ''}`);
-    if (report.orphans.length)
-        console.log(`  ${pc.dim('ℹ')} Orphans (no DB row): ${report.orphans.join(', ')}`);
-    if (report.ok) {
-        console.log(`  ${pc.green('✓')} All files verified\n`);
-    }
-    else {
-        if (report.missing.length)
-            console.log(`  ${pc.red('✗')} Missing: ${report.missing.join(', ')}`);
-        if (report.sizeMismatch.length)
-            console.log(`  ${pc.yellow('⚠')} Size mismatch: ${report.sizeMismatch.join(', ')}`);
-        if (report.hashMismatch.length)
-            console.log(`  ${pc.yellow('⚠')} Hash mismatch: ${report.hashMismatch.join(', ')}`);
-        console.log('');
-        process.exit(1); // S4: standalone verify exits 1 on failure (CI-friendly)
-    }
-}
-async function runRestore() {
-    const targetEnv = args[0];
-    const snapshotIdx = args.findIndex((a) => a === '--snapshot');
-    const snapshotId = snapshotIdx >= 0 ? args[snapshotIdx + 1] : undefined;
-    if (!targetEnv || !snapshotId) {
-        console.error(pc.red('Error: restore requires <env> --snapshot <snapshot-id>'));
-        process.exit(1);
-    }
-    console.log(`\n${pc.bold('hazo-env restore')} ${pc.dim(`${targetEnv} ← ${snapshotId}`)}\n`);
-    const { restoreSnapshot } = await import('./migrate/snapshot.js');
-    const { resolveConnectConfig } = await import('./resolve/connect.js');
-    const toConfig = resolveConnectConfig({ env: targetEnv, allowOtherEnv: true });
-    restoreSnapshot(toConfig, snapshotId);
-    console.log(`  ${pc.green('✓')} Restored\n`);
 }
-async function runClear() {
-    const targetEnv = args[0] ?? getEnv();
-    const allowProd = args.includes('--allow-prod-target');
-    const confirm = args.find((a) => a.startsWith('--confirm='))?.split('=')[1];
-    console.log(`\n${pc.bold('hazo-env clear')} ${pc.dim(targetEnv)}\n`);
-    const { clearEnv } = await import('./migrate/clear.js');
+async function runServe() {
+    const portIdx = args.findIndex((a) => a === '--port');
+    const port = portIdx >= 0 ? Number(args[portIdx + 1]) : undefined;
+    const bindIdx = args.findIndex((a) => a === '--bind');
+    const bind = bindIdx >= 0 ? args[bindIdx + 1] : undefined;
+    const { startEnvsyncService } = await import('./envsync/service.js');
     try {
-        let lastMsg = '';
-        const result = await clearEnv({
-            env: targetEnv,
-            allowProdTarget: allowProd,
-            confirmToken: confirm,
-            onProgress: (p) => {
-                if (p.message !== lastMsg) {
-                    const pctStr = p.percent != null ? ` [${p.percent}%]` : '';
-                    console.log(`  ${pc.dim('·')} ${p.message}${pctStr}`);
-                    lastMsg = p.message;
-                }
-            },
-        });
-        if (result.ok) {
-            console.log(`  ${pc.green('✓')} Cleared ${result.tablesCleared} tables${result.filesCleared ? ' + files' : ''} in ${result.durationMs}ms\n`);
-            if (result.warnings.length)
-                result.warnings.forEach((w) => console.log(`  ${pc.yellow('⚠')} ${w}`));
-        }
+        const { server } = startEnvsyncService({ port, bind });
+        const address = server.address();
+        const actualPort = address && typeof address === 'object' ? address.port : port;
+        const actualBind = bind ?? process.env['HAZO_ENVSYNC_BIND'] ?? '127.0.0.1';
+        console.log(`\n${pc.bold('hazo-env serve')}  ${pc.dim(`envsync service listening on ${actualBind}:${actualPort}`)}\n`);
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        console.error(`\n  ${pc.red('✗')} ${msg}\n`);
+        console.error(`\n${pc.red('Error:')} ${msg}\n`);
         process.exit(1);
     }
-    console.log('');
-}
-async function runMask() {
-    const subCmd = args[0];
-    if (subCmd === 'sync') {
-        console.log(`\n${pc.bold('hazo-env mask sync')}\n`);
-        try {
-            const connectMod = await import('hazo_connect/server').catch(() => null);
-            if (!connectMod) {
-                console.error(pc.red('Error: hazo_connect is required for mask sync.'));
-                process.exit(1);
-            }
-            const { resolveConnectConfig } = await import('./resolve/connect.js');
-            const { syncRulesetFromIni } = await import('./mask/ruleset.js');
-            const dbConfig = resolveConnectConfig({ allowOtherEnv: false });
-            if (dbConfig.type !== 'sqlite' || !dbConfig.sqlite) {
-                console.error(pc.red('Error: mask sync only supports SQLite databases.'));
-                process.exit(1);
-            }
-            const adapter = connectMod.createHazoConnect({
-                type: 'sqlite',
-                sqlite: { database_path: dbConfig.sqlite.database_path },
-            });
-            const count = await syncRulesetFromIni(adapter);
-            console.log(`  ${pc.green('✓')} Synced ${count} rules into hazo_app_config\n`);
-        }
-        catch (e) {
-            console.error(`\n  ${pc.red('✗')} ${e instanceof Error ? e.message : String(e)}\n`);
-            process.exit(1);
-        }
-        return;
-    }
-    if (subCmd === 'list') {
-        console.log(`\n${pc.bold('hazo-env mask list')}\n`);
-        const { listTransforms } = await import('./mask/registry.js');
-        const transforms = await listTransforms();
-        if (transforms.length === 0) {
-            console.log('  (no transforms registered)\n');
-        }
-        else {
-            for (const name of transforms)
-                console.log(`  ${pc.dim('•')} ${name}`);
-            console.log('');
-        }
-        return;
-    }
-    console.log(`
-${pc.bold('hazo-env mask')} — masking commands
-
-  hazo-env mask sync    Load hazo_env_masking.ini into hazo_app_config
-  hazo-env mask list    List registered transform functions
-`);
 }
 function printHelp() {
     console.log(`
@@ -264,19 +183,14 @@ Usage:
   hazo-env doctor --all                     Run health checks for all declared environments
   hazo-env doctor --env <env>               Run health checks for a specific environment
   hazo-env doctor --probe                   Also probe live DB reachability
-  hazo-env migrate --from <env> --to <env>  Migrate DB + files between environments
-    --dry-run                               Show plan without executing
-    --no-db / --no-files                    Skip DB or file copy
-    --allow-prod-target --confirm <token>   Override prod-target safety
-  hazo-env verify <env>                     Verify files for an environment
-    --hash full|sample|none                Hash-check all / sampled / none (default: sample)
-    --no-orphans                           Skip orphan detection
-  hazo-env restore <env> --snapshot <id>   Restore a snapshot
-  hazo-env snapshot <env>                   Take a snapshot of an environment
-  hazo-env mask sync                        Load masking ruleset from INI into DB
-  hazo-env mask list                        List registered mask transforms
-  hazo-env clear <env>                      Wipe DB tables + files for an environment
-    --allow-prod-target --confirm=<token>   Override prod-target safety
+  hazo-env sync download-db                 Dump [envsync] source_db to work_dir
+  hazo-env sync upload-db --dump <path>     Restore a dump into target_db
+    --confirm --allow-prod-target           Required to actually apply
+  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)
+  hazo-env serve                            Start the envsync HTTP service (HAZO_ENVSYNC_TOKEN required)
+    --port <n> --bind <host>                Override HAZO_ENVSYNC_PORT / HAZO_ENVSYNC_BIND
 `);
 }
 (async () => {
@@ -287,23 +201,11 @@ Usage:
         else if (command === 'doctor') {
             await runDoctor();
         }
-        else if (command === 'snapshot') {
-            await runSnapshot();
-        }
-        else if (command === 'migrate') {
-            await runMigrate();
-        }
-        else if (command === 'verify') {
-            await runVerify();
-        }
-        else if (command === 'restore') {
-            await runRestore();
-        }
-        else if (command === 'mask') {
-            await runMask();
+        else if (command === 'sync') {
+            await runSync();
         }
-        else if (command === 'clear') {
-            await runClear();
+        else if (command === 'serve') {
+            await runServe();
         }
         else {
             printHelp();

package/dist/envsync/dotenv-merge.d.ts

@@ -0,0 +1,24 @@
+export interface EnvOverrideDiff {
+    key: string;
+    before: string | undefined;
+    after: string;
+}
+/** Parse dotenv-style KEY=VALUE text into a plain record. */
+export declare function parseDotenvText(text: string): Record<string, string>;
+/**
+ * Merge an archive's .env.local contents with operator-configured overrides.
+ * Overrides always win.
+ */
+export declare function mergeEnvOverrides(archiveEnv: Record<string, string>, overrides: Record<string, string>): Record<string, string>;
+/**
+ * Diff the merged (about-to-be-written) env against the CURRENT target
+ * .env.local content — this is "what's about to change" from the
+ * operator's point of view, since currentEnv is what uploadFiles is about
+ * to overwrite. (Diffing against the archive's original values instead
+ * would show "what changed since the download", which is less useful when
+ * deciding whether to confirm an upload.)
+ */
+export declare function diffEnvAgainstCurrent(merged: Record<string, string>, currentEnv: Record<string, string>): EnvOverrideDiff[];
+/** Serialize a record back into KEY=VALUE dotenv text. */
+export declare function serializeDotenv(env: Record<string, string>): string;
+//# sourceMappingURL=dotenv-merge.d.ts.map

package/dist/envsync/dotenv-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dotenv-merge.d.ts","sourceRoot":"","sources":["../../src/envsync/dotenv-merge.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEpE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,eAAe,EAAE,CAInB;AAED,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAInE"}