hazo_env 0.6.1 → 0.8.0

package/dist/envsync/dotenv-merge.js

@@ -0,0 +1,35 @@
+// hazo_env/src/envsync/dotenv-merge.ts — pure env-merge/diff helpers for uploadFiles
+//
+// Split out from engine.ts so the merge/diff/override logic is unit-testable
+// with plain fixture strings, no filesystem or tar involved.
+import dotenv from 'dotenv';
+/** Parse dotenv-style KEY=VALUE text into a plain record. */
+export function parseDotenvText(text) {
+    return dotenv.parse(text);
+}
+/**
+ * Merge an archive's .env.local contents with operator-configured overrides.
+ * Overrides always win.
+ */
+export function mergeEnvOverrides(archiveEnv, overrides) {
+    return { ...archiveEnv, ...overrides };
+}
+/**
+ * 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 function diffEnvAgainstCurrent(merged, currentEnv) {
+    return Object.keys(merged)
+        .sort()
+        .map((key) => ({ key, before: currentEnv[key], after: merged[key] }));
+}
+/** Serialize a record back into KEY=VALUE dotenv text. */
+export function serializeDotenv(env) {
+    return Object.entries(env)
+        .map(([key, value]) => `${key}=${value}`)
+        .join('\n') + (Object.keys(env).length ? '\n' : '');
+}

package/dist/envsync/engine.d.ts

@@ -0,0 +1,77 @@
+import { type EnvOverrideDiff } from './dotenv-merge.js';
+import type { EnvsyncConfig } from '../resolve/envsync.js';
+export type { EnvOverrideDiff };
+export interface EnvsyncFileResult {
+    id: string;
+    path: string;
+    bytes: number;
+}
+/**
+ * pg_dump the configured source_db to <work_dir>/db-<id>.pgdump.
+ */
+export declare function downloadDb(cfg: EnvsyncConfig, opts?: {
+    onProgress?: (msg: string) => void;
+    id?: string;
+    now?: () => number;
+}): Promise<EnvsyncFileResult>;
+/**
+ * Drop, recreate, and pg_restore the configured target_db from dumpPath.
+ * Guarded by assertConfirmed + assertNotProd — never runs unconfirmed or
+ * against a target that looks like production.
+ */
+export declare function uploadDb(cfg: EnvsyncConfig, dumpPath: string, opts: {
+    confirm?: boolean;
+    allowProd?: boolean;
+    onProgress?: (msg: string) => void;
+}): Promise<{
+    ok: true;
+}>;
+/**
+ * tar cfg.files_root into <work_dir>/files-<id>.tar.gz, plus the current
+ * .env.local (from process.cwd()) added under the fixed member name
+ * __env.local.
+ *
+ * Approach: stage a temp dir containing ONLY __env.local, then run a single
+ * `tar -czf out -C files_root . -C stageDir __env.local` invocation — tar
+ * accepts multiple -C flags, each retargeting the base dir for the file
+ * args that follow it, so one archive gets both "everything in files_root"
+ * and "one file from elsewhere" without a second tar --append pass (which
+ * would mean rewriting/recompressing the whole gzip stream).
+ */
+export declare function downloadFiles(cfg: EnvsyncConfig, opts?: {
+    onProgress?: (msg: string) => void;
+    id?: string;
+    now?: () => number;
+}): Promise<EnvsyncFileResult>;
+/**
+ * Preview or apply an archive from downloadFiles into cfg.files_root +
+ * process.cwd()/.env.local.
+ *
+ * Always: extract __env.local from the archive, merge cfg.envOverrides on
+ * top (overrides win), and diff the merged result against the CURRENT
+ * target .env.local — i.e. "what's about to change" (see dotenv-merge.ts
+ * for why that's the more useful diff direction than "vs the archive's
+ * original values").
+ *
+ * If opts.confirm is falsy: returns { ok: false, diff } — a dry-run
+ * preview, no writes at all.
+ *
+ * If opts.confirm is truthy: guarded by assertNotProd against
+ * cfg.target_db (reusing the same DB-name guard uploadDb uses — files and
+ * DB uploads are two halves of syncing INTO the same target environment,
+ * so it's the meaningful "is this prod" check available here), then backs
+ * up the existing target .env.local, wipes and repopulates files_root from
+ * the archive, and writes the merged .env.local.
+ */
+export declare function uploadFiles(cfg: EnvsyncConfig, archivePath: string, opts: {
+    confirm?: boolean;
+    allowProd?: boolean;
+    onProgress?: (msg: string) => void;
+}): Promise<{
+    ok: true;
+    diff: EnvOverrideDiff[];
+} | {
+    ok: false;
+    diff: EnvOverrideDiff[];
+}>;
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +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"}

package/dist/envsync/engine.js

@@ -0,0 +1,155 @@
+// hazo_env/src/envsync/engine.ts — local pg_dump/pg_restore/tar orchestration
+//
+// Four pure-ish orchestration functions over an EnvsyncConfig. Everything
+// runs locally via exec.ts's spawn wrapper (no SSH, no bash script string-
+// building) — real argv arrays for pg_dump/pg_restore/dropdb/createdb/tar.
+// Modeled on migrate/db-dump-restore.ts's step shape, minus the SSH layer.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { runCmd, runShell } from './exec.js';
+import { assertFreeSpace } from './retention.js';
+import { assertConfirmed, assertNotProd } from './guards.js';
+import { mergeEnvOverrides, diffEnvAgainstCurrent, parseDotenvText, serializeDotenv, } from './dotenv-merge.js';
+// Free-space floor checked before writing a new dump/archive into work_dir.
+// Not configurable in Phase 1 — a fixed conservative floor is good enough
+// to catch "disk is basically full" before pg_dump/tar fail mid-write.
+const MIN_FREE_BYTES = 500 * 1024 * 1024; // 500 MiB
+const ENV_LOCAL_MEMBER = '__env.local';
+function defaultId(now) {
+    return String((now ?? Date.now)());
+}
+/**
+ * pg_dump the configured source_db to <work_dir>/db-<id>.pgdump.
+ */
+export async function downloadDb(cfg, opts) {
+    assertFreeSpace(cfg.work_dir, MIN_FREE_BYTES);
+    fs.mkdirSync(cfg.work_dir, { recursive: true });
+    const id = opts?.id ?? defaultId(opts?.now);
+    const filePath = path.join(cfg.work_dir, `db-${id}.pgdump`);
+    opts?.onProgress?.(`Dumping ${cfg.source_db} -> ${filePath}`);
+    await runCmd('pg_dump', ['-Fc', cfg.source_db, '-f', filePath], { onProgress: opts?.onProgress });
+    const bytes = fs.statSync(filePath).size;
+    return { id, path: filePath, bytes };
+}
+/**
+ * Drop, recreate, and pg_restore the configured target_db from dumpPath.
+ * Guarded by assertConfirmed + assertNotProd — never runs unconfirmed or
+ * against a target that looks like production.
+ */
+export async function uploadDb(cfg, dumpPath, opts) {
+    assertConfirmed(opts.confirm, cfg.target_db);
+    assertNotProd(cfg.target_db, cfg.prodDbNames, opts.allowProd);
+    if (cfg.pre_restore_cmd) {
+        opts.onProgress?.('Running pre_restore_cmd...');
+        await runShell(cfg.pre_restore_cmd, { onProgress: opts.onProgress });
+    }
+    opts.onProgress?.(`Dropping ${cfg.target_db}...`);
+    await runCmd('dropdb', ['--if-exists', cfg.target_db], { onProgress: opts.onProgress });
+    opts.onProgress?.(`Creating ${cfg.target_db}...`);
+    await runCmd('createdb', ['-O', cfg.owner, cfg.target_db], { onProgress: opts.onProgress });
+    opts.onProgress?.(`Restoring ${dumpPath} -> ${cfg.target_db}...`);
+    await runCmd('pg_restore', ['-d', cfg.target_db, dumpPath], { onProgress: opts.onProgress });
+    if (cfg.post_restore_cmd) {
+        opts.onProgress?.('Running post_restore_cmd...');
+        await runShell(cfg.post_restore_cmd, { onProgress: opts.onProgress });
+    }
+    return { ok: true };
+}
+/**
+ * tar cfg.files_root into <work_dir>/files-<id>.tar.gz, plus the current
+ * .env.local (from process.cwd()) added under the fixed member name
+ * __env.local.
+ *
+ * Approach: stage a temp dir containing ONLY __env.local, then run a single
+ * `tar -czf out -C files_root . -C stageDir __env.local` invocation — tar
+ * accepts multiple -C flags, each retargeting the base dir for the file
+ * args that follow it, so one archive gets both "everything in files_root"
+ * and "one file from elsewhere" without a second tar --append pass (which
+ * would mean rewriting/recompressing the whole gzip stream).
+ */
+export async function downloadFiles(cfg, opts) {
+    assertFreeSpace(cfg.work_dir, MIN_FREE_BYTES);
+    fs.mkdirSync(cfg.work_dir, { recursive: true });
+    fs.mkdirSync(cfg.files_root, { recursive: true });
+    const id = opts?.id ?? defaultId(opts?.now);
+    const filePath = path.join(cfg.work_dir, `files-${id}.tar.gz`);
+    const stageDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hazo_envsync_stage_'));
+    try {
+        const envLocalSrc = path.join(process.cwd(), '.env.local');
+        const stagedEnvLocal = path.join(stageDir, ENV_LOCAL_MEMBER);
+        fs.writeFileSync(stagedEnvLocal, fs.existsSync(envLocalSrc) ? fs.readFileSync(envLocalSrc) : '');
+        opts?.onProgress?.(`Archiving ${cfg.files_root} -> ${filePath}`);
+        await runCmd('tar', ['-czf', filePath, '-C', cfg.files_root, '.', '-C', stageDir, ENV_LOCAL_MEMBER], { onProgress: opts?.onProgress });
+    }
+    finally {
+        fs.rmSync(stageDir, { recursive: true, force: true });
+    }
+    const bytes = fs.statSync(filePath).size;
+    return { id, path: filePath, bytes };
+}
+/**
+ * Preview or apply an archive from downloadFiles into cfg.files_root +
+ * process.cwd()/.env.local.
+ *
+ * Always: extract __env.local from the archive, merge cfg.envOverrides on
+ * top (overrides win), and diff the merged result against the CURRENT
+ * target .env.local — i.e. "what's about to change" (see dotenv-merge.ts
+ * for why that's the more useful diff direction than "vs the archive's
+ * original values").
+ *
+ * If opts.confirm is falsy: returns { ok: false, diff } — a dry-run
+ * preview, no writes at all.
+ *
+ * If opts.confirm is truthy: guarded by assertNotProd against
+ * cfg.target_db (reusing the same DB-name guard uploadDb uses — files and
+ * DB uploads are two halves of syncing INTO the same target environment,
+ * so it's the meaningful "is this prod" check available here), then backs
+ * up the existing target .env.local, wipes and repopulates files_root from
+ * 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');
+        }
+    }
+    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)) {
+        const ts = Date.now();
+        fs.copyFileSync(targetEnvLocalPath, `${targetEnvLocalPath}.bak-${ts}`);
+    }
+    opts.onProgress?.(`Clearing ${cfg.files_root}...`);
+    fs.rmSync(cfg.files_root, { recursive: true, force: true });
+    fs.mkdirSync(cfg.files_root, { recursive: true });
+    opts.onProgress?.(`Extracting ${archivePath} -> ${cfg.files_root}...`);
+    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).
+    const extractedEnvMember = path.join(cfg.files_root, ENV_LOCAL_MEMBER);
+    if (fs.existsSync(extractedEnvMember))
+        fs.rmSync(extractedEnvMember, { force: true });
+    fs.writeFileSync(targetEnvLocalPath, serializeDotenv(merged));
+    return { ok: true, diff };
+}

package/dist/envsync/exec.d.ts

@@ -0,0 +1,21 @@
+export interface ExecOptions {
+    onProgress?: (line: string) => void;
+}
+/**
+ * Run `cmd` with `args` as a real argv array — never a shell string, so no
+ * config value can smuggle shell metacharacters into the command line.
+ * Streams stdout/stderr lines to opts.onProgress. Resolves on exit 0,
+ * rejects on non-zero exit or a spawn error (e.g. ENOENT).
+ */
+export declare function runCmd(cmd: string, args: string[], opts?: ExecOptions): Promise<void>;
+/**
+ * Shell-string execution — the ONE exception to "always argv arrays".
+ * Reserved exclusively for the two operator-supplied full command strings
+ * (EnvsyncConfig.pre_restore_cmd / post_restore_cmd). Those come from the
+ * INI file the operator controls (not end-user input), the same trust
+ * level as backup.ts's pre_restore_cmd/post_restore_cmd which already run
+ * as raw bash on the remote in migrate/db-dump-restore.ts. Do not call
+ * this with any value that isn't operator config.
+ */
+export declare function runShell(command: string, opts?: ExecOptions): Promise<void>;
+//# sourceMappingURL=exec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/envsync/exec.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AASD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB3E"}

package/dist/envsync/exec.js

@@ -0,0 +1,62 @@
+// hazo_env/src/envsync/exec.ts — local command execution for envsync
+//
+// Simpler cousin of migrate/ssh-exec.ts::runSsh: no SSH, no known_hosts,
+// just spawn(cmd, args) against the local machine. envsync only ever talks
+// to local Postgres and local paths — operators move dump/archive files
+// between hosts manually, outside this code.
+import { spawn } from 'node:child_process';
+function streamLines(chunk, onProgress) {
+    if (!onProgress)
+        return;
+    for (const line of chunk.toString().split('\n')) {
+        if (line.trim())
+            onProgress(line);
+    }
+}
+/**
+ * Run `cmd` with `args` as a real argv array — never a shell string, so no
+ * config value can smuggle shell metacharacters into the command line.
+ * Streams stdout/stderr lines to opts.onProgress. Resolves on exit 0,
+ * rejects on non-zero exit or a spawn error (e.g. ENOENT).
+ */
+export function runCmd(cmd, args, opts) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(cmd, args);
+        proc.stdout.on('data', (chunk) => streamLines(chunk, opts?.onProgress));
+        proc.stderr.on('data', (chunk) => streamLines(chunk, opts?.onProgress));
+        proc.on('error', (err) => reject(err));
+        proc.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`${cmd} exited with code ${code}`));
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}
+/**
+ * Shell-string execution — the ONE exception to "always argv arrays".
+ * Reserved exclusively for the two operator-supplied full command strings
+ * (EnvsyncConfig.pre_restore_cmd / post_restore_cmd). Those come from the
+ * INI file the operator controls (not end-user input), the same trust
+ * level as backup.ts's pre_restore_cmd/post_restore_cmd which already run
+ * as raw bash on the remote in migrate/db-dump-restore.ts. Do not call
+ * this with any value that isn't operator config.
+ */
+export function runShell(command, opts) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(command, { shell: true });
+        proc.stdout.on('data', (chunk) => streamLines(chunk, opts?.onProgress));
+        proc.stderr.on('data', (chunk) => streamLines(chunk, opts?.onProgress));
+        proc.on('error', (err) => reject(err));
+        proc.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`shell command exited with code ${code}`));
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}

package/dist/envsync/guards.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Throw unless confirm is explicitly true. Used to gate destructive ops
+ * (dropdb/createdb/pg_restore, wiping files_root) behind an explicit
+ * caller opt-in rather than running on a bare invocation.
+ */
+export declare function assertConfirmed(confirm: boolean | undefined, targetName: string): void;
+/**
+ * Throw if targetName looks like a production target (is in prodNames) and
+ * the caller hasn't explicitly opted in via allowProd.
+ */
+export declare function assertNotProd(targetName: string, prodNames: string[], allowProd: boolean | undefined): void;
+//# sourceMappingURL=guards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/envsync/guards.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAMtF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAM3G"}

package/dist/envsync/guards.js

@@ -0,0 +1,20 @@
+// hazo_env/src/envsync/guards.ts — destructive-op safety helpers for envsync
+/**
+ * Throw unless confirm is explicitly true. Used to gate destructive ops
+ * (dropdb/createdb/pg_restore, wiping files_root) behind an explicit
+ * caller opt-in rather than running on a bare invocation.
+ */
+export function assertConfirmed(confirm, targetName) {
+    if (!confirm) {
+        throw new Error(`Refusing to upload_db into "${targetName}" without confirm=true — pass confirm to proceed.`);
+    }
+}
+/**
+ * Throw if targetName looks like a production target (is in prodNames) and
+ * the caller hasn't explicitly opted in via allowProd.
+ */
+export function assertNotProd(targetName, prodNames, allowProd) {
+    if (prodNames.includes(targetName) && !allowProd) {
+        throw new Error(`Refusing: "${targetName}" looks like a production target. Pass allowProd:true to override.`);
+    }
+}

package/dist/envsync/lock.d.ts

@@ -0,0 +1,12 @@
+export declare class EnvsyncLockError extends Error {
+    code: string;
+    constructor(message: string);
+}
+/**
+ * Run fn() while holding a single-run lock for workDir. Throws
+ * EnvsyncLockError (code 'ENVSYNC_LOCKED') if a lock is already held,
+ * either in-process or on disk. Always releases the lock in a finally,
+ * even if fn() throws.
+ */
+export declare function withLock<T>(workDir: string, op: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=lock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/envsync/lock.ts"],"names":[],"mappings":"AAWA,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,IAAI,SAAoB;gBACZ,OAAO,EAAE,MAAM;CAI5B;AAqDD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAyB/F"}

package/dist/envsync/lock.js

@@ -0,0 +1,84 @@
+// hazo_env/src/envsync/lock.ts — single-run guard for envsync operations
+//
+// Combines an in-process mutex (so two calls within the same Node process
+// can't overlap) with an on-disk lockfile inside work_dir (so a second CLI
+// invocation, or a second process, can't overlap either). The on-disk lock
+// self-heals: if the PID recorded in the lockfile is no longer alive (e.g.
+// the previous run crashed), the stale lock is cleared automatically.
+import fs from 'node:fs';
+import path from 'node:path';
+export class EnvsyncLockError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = 'ENVSYNC_LOCKED';
+        this.name = 'EnvsyncLockError';
+    }
+}
+// In-process mutex, keyed by work_dir so unrelated envsync configs (e.g. in
+// tests using different temp dirs) never contend with each other.
+const inProcessLocks = new Set();
+function lockFilePath(workDir) {
+    return path.join(workDir, '.envsync.lock');
+}
+function isPidAlive(pid) {
+    try {
+        // Signal 0 performs no-op existence/permission check without killing anything.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Inspect (and clear, if stale) any on-disk lockfile in workDir.
+ * Throws EnvsyncLockError if a live lock is held by another process.
+ */
+function checkOnDiskLock(workDir, op) {
+    const lockPath = lockFilePath(workDir);
+    if (!fs.existsSync(lockPath))
+        return;
+    let data = null;
+    try {
+        data = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    }
+    catch {
+        // Corrupt/unreadable lockfile — treat as stale and clear it.
+        fs.rmSync(lockPath, { force: true });
+        return;
+    }
+    if (data && typeof data.pid === 'number' && isPidAlive(data.pid)) {
+        throw new EnvsyncLockError(`envsync: another operation ("${data.op}", pid ${data.pid}) is already in progress in ${workDir} — refusing to start "${op}"`);
+    }
+    // Stale lock from a dead process — auto-clear.
+    fs.rmSync(lockPath, { force: true });
+}
+/**
+ * Run fn() while holding a single-run lock for workDir. Throws
+ * EnvsyncLockError (code 'ENVSYNC_LOCKED') if a lock is already held,
+ * either in-process or on disk. Always releases the lock in a finally,
+ * even if fn() throws.
+ */
+export async function withLock(workDir, op, fn) {
+    if (inProcessLocks.has(workDir)) {
+        throw new EnvsyncLockError(`envsync: another operation is already in progress in this process for ${workDir} — refusing to start "${op}"`);
+    }
+    fs.mkdirSync(workDir, { recursive: true });
+    checkOnDiskLock(workDir, op);
+    inProcessLocks.add(workDir);
+    const lockPath = lockFilePath(workDir);
+    const data = { pid: process.pid, timestamp: Date.now(), op };
+    fs.writeFileSync(lockPath, JSON.stringify(data));
+    try {
+        return await fn();
+    }
+    finally {
+        inProcessLocks.delete(workDir);
+        try {
+            fs.rmSync(lockPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+}

package/dist/envsync/retention.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Delete old envsync files in workDir, keeping the newest `opts.keep` per
+ * pattern (db-*.pgdump and files-*.tar.gz are pruned as separate groups).
+ * "Newest" is by mtime. Returns the names of files that were deleted.
+ */
+export declare function pruneWorkDir(workDir: string, opts: {
+    keep: number;
+}): {
+    deleted: string[];
+};
+/**
+ * Throw if workDir's filesystem has less than minBytes available.
+ * Uses fs.statfsSync (Node 18.15+/20+) to read available blocks directly —
+ * no shelling out to `df`.
+ */
+export declare function assertFreeSpace(workDir: string, minBytes: number): void;
+//# sourceMappingURL=retention.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../src/envsync/retention.ts"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAuB3F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CASvE"}

package/dist/envsync/retention.js

@@ -0,0 +1,52 @@
+// hazo_env/src/envsync/retention.ts — work_dir housekeeping for envsync
+//
+// Prunes old dump/archive files so work_dir doesn't grow without bound, and
+// checks free disk space before a new dump/archive is created.
+import fs from 'node:fs';
+import path from 'node:path';
+// The two file kinds envsync ever writes into work_dir (see engine.ts).
+// Each kind is pruned independently, keeping the newest N of *each* kind —
+// otherwise a single "keep 3" would let one kind starve the other.
+const RETAINED_PATTERNS = [
+    /^db-.+\.pgdump$/,
+    /^files-.+\.tar\.gz$/,
+];
+/**
+ * Delete old envsync files in workDir, keeping the newest `opts.keep` per
+ * pattern (db-*.pgdump and files-*.tar.gz are pruned as separate groups).
+ * "Newest" is by mtime. Returns the names of files that were deleted.
+ */
+export function pruneWorkDir(workDir, opts) {
+    const deleted = [];
+    if (!fs.existsSync(workDir))
+        return { deleted };
+    const entries = fs.readdirSync(workDir);
+    for (const pattern of RETAINED_PATTERNS) {
+        const group = entries
+            .filter((name) => pattern.test(name))
+            .map((name) => {
+            const full = path.join(workDir, name);
+            const mtime = fs.statSync(full).mtimeMs;
+            return { name, full, mtime };
+        })
+            .sort((a, b) => b.mtime - a.mtime); // newest first
+        for (const stale of group.slice(Math.max(opts.keep, 0))) {
+            fs.rmSync(stale.full, { force: true });
+            deleted.push(stale.name);
+        }
+    }
+    return { deleted };
+}
+/**
+ * Throw if workDir's filesystem has less than minBytes available.
+ * Uses fs.statfsSync (Node 18.15+/20+) to read available blocks directly —
+ * no shelling out to `df`.
+ */
+export function assertFreeSpace(workDir, minBytes) {
+    fs.mkdirSync(workDir, { recursive: true });
+    const stat = fs.statfsSync(workDir);
+    const availableBytes = stat.bavail * stat.bsize;
+    if (availableBytes < minBytes) {
+        throw new Error(`envsync: insufficient free space in ${workDir} — ${availableBytes} bytes available, ${minBytes} required`);
+    }
+}

package/dist/envsync/service.d.ts

@@ -0,0 +1,21 @@
+import http from 'node:http';
+export interface StartEnvsyncServiceOptions {
+    port?: number;
+    bind?: string;
+    token?: string;
+}
+export interface EnvsyncServiceHandle {
+    server: http.Server;
+    close(): Promise<void>;
+}
+/**
+ * Start the envsync HTTP service. Throws synchronously if no bearer token
+ * is configured (via opts.token or HAZO_ENVSYNC_TOKEN) — this service must
+ * never run unauthenticated.
+ *
+ * opts override env vars, which makes this testable without real env vars
+ * or real ports: pass { port: 0 } for an OS-assigned ephemeral port and read
+ * the actual port off `server.address()`.
+ */
+export declare function startEnvsyncService(opts?: StartEnvsyncServiceOptions): EnvsyncServiceHandle;
+//# sourceMappingURL=service.d.ts.map

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

@@ -0,0 +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"}