@absolutejs/deploy 0.6.0 → 0.7.0

package/README.md

@@ -287,6 +287,83 @@ limit). Persist the JSON; pass `account` back to subsequent
 mode `600`. Override `certPath` / `keyPath` / `mode` / `owner` /
 `reload` as needed.
 
+## `@absolutejs/deploy/env` — env-file sync + secret propagation (0.7.0)
+
+The "universal place to rotate a key across the myriad of services"
+loop. Composes with `@absolutejs/secrets`: that library handles the
+in-process side (resolve, rotate, redact, in-process listeners);
+this module handles the deploy-side (push values to remote env
+files, atomic swap, conditional service reload).
+
+```ts
+import { createSecretBroker, inMemoryAdapter } from '@absolutejs/secrets';
+import { hetznerTarget } from '@absolutejs/deploy/hetzner';
+import {
+  syncSecretsToDeployments,
+  deploymentsUsing,
+  type EnvDeployment,
+} from '@absolutejs/deploy/env';
+
+// One source of truth — the SecretBroker. Swap in whatever adapter
+// (env, file, vault, etc.) makes sense for your team.
+const broker = createSecretBroker({
+  adapter: inMemoryAdapter({
+    initial: {
+      DATABASE_URL: 'postgres://prod-db',
+      STRIPE_KEY: 'sk_live_old',
+    },
+  }),
+});
+
+// Each deployed service is one EnvDeployment.
+const api = await hetznerTarget({ name: 'api-1', /* … */ });
+const worker = await hetznerTarget({ name: 'worker-1', /* … */ });
+
+const deployments: EnvDeployment[] = [
+  {
+    target: api,
+    remotePath: '/etc/api.env',
+    secretNames: ['STRIPE_KEY', 'DATABASE_URL'],
+    extras: { NODE_ENV: 'production', PORT: '3000' },
+    reload: 'systemctl reload api',
+  },
+  {
+    target: worker,
+    remotePath: '/etc/worker.env',
+    secretNames: ['DATABASE_URL'],
+    extras: { NODE_ENV: 'production' },
+    reload: 'systemctl restart worker',
+  },
+];
+
+// First-time push (and every subsequent re-sync — idempotent).
+await syncSecretsToDeployments(broker, deployments);
+
+// Rotate STRIPE_KEY everywhere it's used:
+await broker.rotate('STRIPE_KEY');
+await syncSecretsToDeployments(
+  broker,
+  deploymentsUsing('STRIPE_KEY', deployments)
+);
+```
+
+`broker.rotate()` updates the broker's underlying store + fires the
+existing `onRotate` listeners (long-lived DB clients swap creds in
+place). `syncSecretsToDeployments` propagates to every deployed box
+that uses the secret, atomically rewrites the env file, runs the
+reload command only if the diff was non-empty.
+
+Format: standard `KEY=value` per line, sorted alphabetically (stable
+diffs), values double-quoted when needed. systemd reads it via
+`EnvironmentFile=`; Docker via `--env-file`; most shell start
+scripts source it. The serializer rejects newlines in values + keys
+that don't match `[A-Z_][A-Z0-9_]*`.
+
+Best-effort fan-out: one broken target doesn't stop the rest. Each
+result carries either `result: EnvSyncResult` or `error: Error`.
+The operator inspects the array, fixes the broken target, re-runs —
+re-runs are idempotent.
+
 ## Renewals — `renewCertificate` (0.6.0)
 
 `issueCertificate` is one-shot; `renewCertificate` is the conditional

package/dist/env.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @absolutejs/deploy/env — push environment-variable files to remote
+ * targets and fan-out secret rotations across the fleet.
+ *
+ * Composes with `@absolutejs/secrets`: that library handles the
+ * in-process side (resolve, rotate, redact, in-process listeners);
+ * this module handles the deploy-side (push values to remote env
+ * files, atomic swap, conditional service reload).
+ *
+ * Narrow `SecretSource` interface — `@absolutejs/secrets`'
+ * `SecretBroker` satisfies it structurally without a hard dep
+ * either direction.
+ *
+ * Standard format: a remote env file at
+ * `/etc/<appName>.env` (or wherever you choose) that systemd reads
+ * via `EnvironmentFile=`, Docker reads via `--env-file`, and most
+ * shell start scripts source. One `KEY=value` per line, no
+ * newlines inside values.
+ */
+import type { Target } from './targets';
+/**
+ * Minimal interface this module needs to read secret values. The
+ * `SecretBroker` from `@absolutejs/secrets` satisfies it structurally;
+ * any other implementation (a Map, an AWS Secrets Manager client
+ * wrapper, etc.) works as long as it exposes `resolve(name)`.
+ */
+export type SecretSource = {
+    resolve: (name: string) => Promise<{
+        value: string;
+        fingerprint?: string;
+    } | null>;
+};
+export declare const serializeEnvFile: (values: Record<string, string>) => string;
+/**
+ * Parse a remote env file's contents. Ignores blank lines and `#`
+ * comments. Lines that don't match `KEY=VALUE` throw — the deploy
+ * primitive owns the file, so unknown content is loud, not silent.
+ */
+export declare const parseEnvFile: (text: string) => Record<string, string>;
+export type EnvDeployment = {
+    /** The cloud Target whose remote filesystem we write to. */
+    target: Target;
+    /** Remote path for the env file (e.g. `/etc/myapp.env`). */
+    remotePath: string;
+    /**
+     * Names of secrets this deployment consumes from the SecretSource.
+     * Each name is resolved before the file is written.
+     */
+    secretNames?: ReadonlyArray<string>;
+    /**
+     * Non-secret env vars to merge in (NODE_ENV, PORT, LOG_LEVEL).
+     * If an `extras` key collides with a `secretNames` entry, throws —
+     * silent overrides are worse than a loud rejection.
+     */
+    extras?: Record<string, string>;
+    /** chmod for the file. Default `'600'`. */
+    mode?: string;
+    /** chown for the file. Default unchanged. */
+    owner?: string;
+    /**
+     * Command to run after the file changes. Skipped when the diff is
+     * empty — bouncing a service for an identical file is the wrong
+     * default.
+     */
+    reload?: string;
+};
+export type EnvSyncResult = {
+    /** Keys present in the new spec but not the existing file. */
+    added: string[];
+    /** Keys whose values changed (fingerprints, NOT plaintext, for safety). */
+    changed: string[];
+    /** Keys removed from the spec (still in the existing file). */
+    removed: string[];
+    /** Keys whose values matched — file wasn't rewritten for these. */
+    unchanged: string[];
+    /** True iff `deployment.reload` was invoked. */
+    reloaded: boolean;
+    /** True iff the file content changed (atomic-write happened). */
+    wrote: boolean;
+    /** Remote path that was synced. */
+    remotePath: string;
+};
+/**
+ * Push an env file to a single target. Atomic: write to a `.new`
+ * tempfile, chmod / chown, then `mv` into place. Diffs the merged
+ * values against the existing file content and skips the
+ * write+reload when nothing changed.
+ */
+export declare const syncEnvToTarget: (deployment: EnvDeployment, values: Record<string, string>) => Promise<EnvSyncResult>;
+export type DeploymentSyncResult = {
+    deployment: EnvDeployment;
+    result?: EnvSyncResult;
+    error?: Error;
+};
+/**
+ * Fan-out push: for each deployment, resolve its `secretNames` via
+ * the source, merge with `extras`, and push to the target. Resolves
+ * are fresh every call — so calling this again after
+ * `broker.rotate(name)` propagates the new value to every
+ * deployment that uses it.
+ *
+ * Best-effort across the fan-out: a per-target failure is captured
+ * in the result, but doesn't stop the rest. Operator inspects the
+ * returned array, fixes the broken target, re-runs.
+ */
+export declare const syncSecretsToDeployments: (source: SecretSource, deployments: ReadonlyArray<EnvDeployment>) => Promise<DeploymentSyncResult[]>;
+/**
+ * Returns just the deployments that use a given secret name. Useful
+ * for "rotate one secret and propagate ONLY to the consumers" —
+ * `syncSecretsToDeployments(source, deploymentsUsing(name, deployments))`.
+ */
+export declare const deploymentsUsing: (name: string, deployments: ReadonlyArray<EnvDeployment>) => EnvDeployment[];

package/dist/env.js

@@ -0,0 +1,203 @@
+// @bun
+// src/env.ts
+var KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+var NEEDS_QUOTING = /[\s"'`$\\#&|;<>(){}*?!]/;
+var validateKey = (key) => {
+  if (!KEY_PATTERN.test(key)) {
+    throw new Error(`[deploy/env] invalid env key "${key}" \u2014 must match /^[A-Z_][A-Z0-9_]*$/`);
+  }
+};
+var serializeLine = (key, value) => {
+  validateKey(key);
+  if (value.includes(`
+`) || value.includes("\r")) {
+    throw new Error(`[deploy/env] value for "${key}" contains a newline \u2014 env files cannot represent multi-line values. Use a separate file path for multi-line secrets.`);
+  }
+  if (NEEDS_QUOTING.test(value) || value.startsWith("=") || value === "") {
+    const escaped = value.replaceAll("\\", "\\\\").replaceAll('"', "\\\"");
+    return `${key}="${escaped}"`;
+  }
+  return `${key}=${value}`;
+};
+var serializeEnvFile = (values) => {
+  const lines = [];
+  for (const key of Object.keys(values).sort()) {
+    const value = values[key];
+    if (value === undefined)
+      continue;
+    lines.push(serializeLine(key, value));
+  }
+  return `${lines.join(`
+`)}
+`;
+};
+var unquoteValue = (raw) => {
+  if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+    const inner = raw.slice(1, -1);
+    return inner.replaceAll("\\\"", '"').replaceAll("\\\\", "\\");
+  }
+  if (raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'")) {
+    return raw.slice(1, -1);
+  }
+  return raw;
+};
+var parseEnvFile = (text) => {
+  const result = {};
+  for (const rawLine of text.split(`
+`)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#"))
+      continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) {
+      throw new Error(`[deploy/env] malformed env line: "${rawLine}"`);
+    }
+    const key = line.slice(0, eq).trim();
+    const value = unquoteValue(line.slice(eq + 1).trim());
+    validateKey(key);
+    result[key] = value;
+  }
+  return result;
+};
+var shellQuote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+var tryReadRemoteFile = async (target, remotePath) => {
+  const result = await target.exec(`if [ -f ${shellQuote(remotePath)} ]; then cat ${shellQuote(remotePath)}; else echo __ABS_DEPLOY_ENV_ABSENT__; fi`);
+  if (result.exitCode !== 0) {
+    throw new Error(`[deploy/env] failed to read ${remotePath}: exit ${result.exitCode}: ${result.stderr || result.stdout}`);
+  }
+  if (result.stdout.trim() === "__ABS_DEPLOY_ENV_ABSENT__")
+    return;
+  return result.stdout;
+};
+var mergeValues = (deployment, resolved) => {
+  const out = {};
+  for (const [key, value] of Object.entries(deployment.extras ?? {})) {
+    validateKey(key);
+    out[key] = value;
+  }
+  for (const [key, value] of Object.entries(resolved)) {
+    if (out[key] !== undefined) {
+      throw new Error(`[deploy/env] "${key}" defined in BOTH extras and secretNames for ${deployment.remotePath} \u2014 remove one`);
+    }
+    out[key] = value;
+  }
+  return out;
+};
+var diffEnv = (previous, next) => {
+  const added = [];
+  const changed = [];
+  const removed = [];
+  const unchanged = [];
+  const allKeys = new Set([...Object.keys(previous), ...Object.keys(next)]);
+  for (const key of [...allKeys].sort()) {
+    const prev = previous[key];
+    const curr = next[key];
+    if (curr === undefined)
+      removed.push(key);
+    else if (prev === undefined)
+      added.push(key);
+    else if (prev === curr)
+      unchanged.push(key);
+    else
+      changed.push(key);
+  }
+  return { added, changed, removed, unchanged };
+};
+var writeRemoteFileAtomically = async (target, remotePath, contents, mode, owner) => {
+  const tempPath = `${remotePath}.new.${Math.floor(Date.now() / 1000)}`;
+  const dir = remotePath.split("/").slice(0, -1).join("/") || "/";
+  const mkdir = await target.exec(`mkdir -p ${shellQuote(dir)}`);
+  if (mkdir.exitCode !== 0) {
+    throw new Error(`[deploy/env] mkdir ${dir} failed: ${mkdir.stderr || mkdir.stdout}`);
+  }
+  const writeResult = await target.exec(`cat > ${shellQuote(tempPath)}`, {
+    stdin: contents
+  });
+  if (writeResult.exitCode !== 0) {
+    throw new Error(`[deploy/env] write to ${tempPath} failed: ${writeResult.stderr || writeResult.stdout}`);
+  }
+  const chmod = await target.exec(`chmod ${shellQuote(mode)} ${shellQuote(tempPath)}`);
+  if (chmod.exitCode !== 0) {
+    throw new Error(`[deploy/env] chmod failed: ${chmod.stderr || chmod.stdout}`);
+  }
+  if (owner !== undefined) {
+    const chown = await target.exec(`chown ${shellQuote(owner)} ${shellQuote(tempPath)}`);
+    if (chown.exitCode !== 0) {
+      throw new Error(`[deploy/env] chown failed: ${chown.stderr || chown.stdout}`);
+    }
+  }
+  const mv = await target.exec(`mv ${shellQuote(tempPath)} ${shellQuote(remotePath)}`);
+  if (mv.exitCode !== 0) {
+    throw new Error(`[deploy/env] mv failed: ${mv.stderr || mv.stdout}`);
+  }
+};
+var syncEnvToTarget = async (deployment, values) => {
+  const mode = deployment.mode ?? "600";
+  const merged = mergeValues(deployment, values);
+  const previousText = await tryReadRemoteFile(deployment.target, deployment.remotePath);
+  const previous = previousText === undefined ? {} : parseEnvFile(previousText);
+  const diff = diffEnv(previous, merged);
+  const changed = diff.added.length + diff.changed.length + diff.removed.length;
+  if (changed === 0) {
+    return {
+      ...diff,
+      reloaded: false,
+      remotePath: deployment.remotePath,
+      wrote: false
+    };
+  }
+  const nextText = serializeEnvFile(merged);
+  await writeRemoteFileAtomically(deployment.target, deployment.remotePath, nextText, mode, deployment.owner);
+  let reloaded = false;
+  if (deployment.reload !== undefined) {
+    const reload = await deployment.target.exec(deployment.reload);
+    if (reload.exitCode !== 0) {
+      throw new Error(`[deploy/env] reload command failed: ${reload.stderr || reload.stdout}`);
+    }
+    reloaded = true;
+  }
+  return {
+    ...diff,
+    reloaded,
+    remotePath: deployment.remotePath,
+    wrote: true
+  };
+};
+var resolveSecrets = async (source, names) => {
+  const out = {};
+  for (const name of names) {
+    const resolved = await source.resolve(name);
+    if (resolved === null) {
+      throw new Error(`[deploy/env] secret "${name}" not found in source`);
+    }
+    out[name] = resolved.value;
+  }
+  return out;
+};
+var syncSecretsToDeployments = async (source, deployments) => {
+  const results = [];
+  for (const deployment of deployments) {
+    try {
+      const resolved = await resolveSecrets(source, deployment.secretNames ?? []);
+      const result = await syncEnvToTarget(deployment, resolved);
+      results.push({ deployment, result });
+    } catch (error) {
+      results.push({
+        deployment,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  return results;
+};
+var deploymentsUsing = (name, deployments) => deployments.filter((d) => (d.secretNames ?? []).includes(name));
+export {
+  syncSecretsToDeployments,
+  syncEnvToTarget,
+  serializeEnvFile,
+  parseEnvFile,
+  deploymentsUsing
+};
+
+//# debugId=61C727D3C5F9CC6864756E2164756E21
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/env.ts"],
+  "sourcesContent": [
+    "/**\n * @absolutejs/deploy/env — push environment-variable files to remote\n * targets and fan-out secret rotations across the fleet.\n *\n * Composes with `@absolutejs/secrets`: that library handles the\n * in-process side (resolve, rotate, redact, in-process listeners);\n * this module handles the deploy-side (push values to remote env\n * files, atomic swap, conditional service reload).\n *\n * Narrow `SecretSource` interface — `@absolutejs/secrets`'\n * `SecretBroker` satisfies it structurally without a hard dep\n * either direction.\n *\n * Standard format: a remote env file at\n * `/etc/<appName>.env` (or wherever you choose) that systemd reads\n * via `EnvironmentFile=`, Docker reads via `--env-file`, and most\n * shell start scripts source. One `KEY=value` per line, no\n * newlines inside values.\n */\n\nimport type { Target } from './targets';\n\n// =============================================================================\n// SecretSource — narrow interface @absolutejs/secrets' broker satisfies\n// =============================================================================\n\n/**\n * Minimal interface this module needs to read secret values. The\n * `SecretBroker` from `@absolutejs/secrets` satisfies it structurally;\n * any other implementation (a Map, an AWS Secrets Manager client\n * wrapper, etc.) works as long as it exposes `resolve(name)`.\n */\nexport type SecretSource = {\n\tresolve: (\n\t\tname: string\n\t) => Promise<{ value: string; fingerprint?: string } | null>;\n};\n\n// =============================================================================\n// Env-file (de)serialization\n// =============================================================================\n\nconst KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;\nconst NEEDS_QUOTING = /[\\s\"'`$\\\\#&|;<>(){}*?!]/;\n\nconst validateKey = (key: string): void => {\n\tif (!KEY_PATTERN.test(key)) {\n\t\tthrow new Error(\n\t\t\t`[deploy/env] invalid env key \"${key}\" — must match /^[A-Z_][A-Z0-9_]*$/`\n\t\t);\n\t}\n};\n\nconst serializeLine = (key: string, value: string): string => {\n\tvalidateKey(key);\n\tif (value.includes('\\n') || value.includes('\\r')) {\n\t\tthrow new Error(\n\t\t\t`[deploy/env] value for \"${key}\" contains a newline — env files cannot represent multi-line values. Use a separate file path for multi-line secrets.`\n\t\t);\n\t}\n\tif (NEEDS_QUOTING.test(value) || value.startsWith('=') || value === '') {\n\t\tconst escaped = value.replaceAll('\\\\', '\\\\\\\\').replaceAll('\"', '\\\\\"');\n\t\treturn `${key}=\"${escaped}\"`;\n\t}\n\treturn `${key}=${value}`;\n};\n\nexport const serializeEnvFile = (values: Record<string, string>): string => {\n\tconst lines: string[] = [];\n\tfor (const key of Object.keys(values).sort()) {\n\t\tconst value = values[key];\n\t\tif (value === undefined) continue;\n\t\tlines.push(serializeLine(key, value));\n\t}\n\treturn `${lines.join('\\n')}\\n`;\n};\n\nconst unquoteValue = (raw: string): string => {\n\tif (\n\t\traw.length >= 2 &&\n\t\traw.startsWith('\"') &&\n\t\traw.endsWith('\"')\n\t) {\n\t\tconst inner = raw.slice(1, -1);\n\t\treturn inner.replaceAll('\\\\\"', '\"').replaceAll('\\\\\\\\', '\\\\');\n\t}\n\tif (\n\t\traw.length >= 2 &&\n\t\traw.startsWith(\"'\") &&\n\t\traw.endsWith(\"'\")\n\t) {\n\t\treturn raw.slice(1, -1);\n\t}\n\treturn raw;\n};\n\n/**\n * Parse a remote env file's contents. Ignores blank lines and `#`\n * comments. Lines that don't match `KEY=VALUE` throw — the deploy\n * primitive owns the file, so unknown content is loud, not silent.\n */\nexport const parseEnvFile = (text: string): Record<string, string> => {\n\tconst result: Record<string, string> = {};\n\tfor (const rawLine of text.split('\\n')) {\n\t\tconst line = rawLine.trim();\n\t\tif (line.length === 0 || line.startsWith('#')) continue;\n\t\tconst eq = line.indexOf('=');\n\t\tif (eq <= 0) {\n\t\t\tthrow new Error(`[deploy/env] malformed env line: \"${rawLine}\"`);\n\t\t}\n\t\tconst key = line.slice(0, eq).trim();\n\t\tconst value = unquoteValue(line.slice(eq + 1).trim());\n\t\tvalidateKey(key);\n\t\tresult[key] = value;\n\t}\n\treturn result;\n};\n\n// =============================================================================\n// Deployment spec + sync primitive\n// =============================================================================\n\nexport type EnvDeployment = {\n\t/** The cloud Target whose remote filesystem we write to. */\n\ttarget: Target;\n\t/** Remote path for the env file (e.g. `/etc/myapp.env`). */\n\tremotePath: string;\n\t/**\n\t * Names of secrets this deployment consumes from the SecretSource.\n\t * Each name is resolved before the file is written.\n\t */\n\tsecretNames?: ReadonlyArray<string>;\n\t/**\n\t * Non-secret env vars to merge in (NODE_ENV, PORT, LOG_LEVEL).\n\t * If an `extras` key collides with a `secretNames` entry, throws —\n\t * silent overrides are worse than a loud rejection.\n\t */\n\textras?: Record<string, string>;\n\t/** chmod for the file. Default `'600'`. */\n\tmode?: string;\n\t/** chown for the file. Default unchanged. */\n\towner?: string;\n\t/**\n\t * Command to run after the file changes. Skipped when the diff is\n\t * empty — bouncing a service for an identical file is the wrong\n\t * default.\n\t */\n\treload?: string;\n};\n\nexport type EnvSyncResult = {\n\t/** Keys present in the new spec but not the existing file. */\n\tadded: string[];\n\t/** Keys whose values changed (fingerprints, NOT plaintext, for safety). */\n\tchanged: string[];\n\t/** Keys removed from the spec (still in the existing file). */\n\tremoved: string[];\n\t/** Keys whose values matched — file wasn't rewritten for these. */\n\tunchanged: string[];\n\t/** True iff `deployment.reload` was invoked. */\n\treloaded: boolean;\n\t/** True iff the file content changed (atomic-write happened). */\n\twrote: boolean;\n\t/** Remote path that was synced. */\n\tremotePath: string;\n};\n\nconst shellQuote = (value: string): string =>\n\t`'${value.replaceAll(\"'\", \"'\\\\''\")}'`;\n\nconst tryReadRemoteFile = async (\n\ttarget: Target,\n\tremotePath: string\n): Promise<string | undefined> => {\n\tconst result = await target.exec(\n\t\t`if [ -f ${shellQuote(remotePath)} ]; then cat ${shellQuote(remotePath)}; else echo __ABS_DEPLOY_ENV_ABSENT__; fi`\n\t);\n\tif (result.exitCode !== 0) {\n\t\tthrow new Error(\n\t\t\t`[deploy/env] failed to read ${remotePath}: exit ${result.exitCode}: ${result.stderr || result.stdout}`\n\t\t);\n\t}\n\tif (result.stdout.trim() === '__ABS_DEPLOY_ENV_ABSENT__') return undefined;\n\treturn result.stdout;\n};\n\nconst mergeValues = (\n\tdeployment: EnvDeployment,\n\tresolved: Record<string, string>\n): Record<string, string> => {\n\tconst out: Record<string, string> = {};\n\tfor (const [key, value] of Object.entries(deployment.extras ?? {})) {\n\t\tvalidateKey(key);\n\t\tout[key] = value;\n\t}\n\tfor (const [key, value] of Object.entries(resolved)) {\n\t\tif (out[key] !== undefined) {\n\t\t\tthrow new Error(\n\t\t\t\t`[deploy/env] \"${key}\" defined in BOTH extras and secretNames for ${deployment.remotePath} — remove one`\n\t\t\t);\n\t\t}\n\t\tout[key] = value;\n\t}\n\treturn out;\n};\n\nconst diffEnv = (\n\tprevious: Record<string, string>,\n\tnext: Record<string, string>\n): Pick<EnvSyncResult, 'added' | 'changed' | 'removed' | 'unchanged'> => {\n\tconst added: string[] = [];\n\tconst changed: string[] = [];\n\tconst removed: string[] = [];\n\tconst unchanged: string[] = [];\n\tconst allKeys = new Set([...Object.keys(previous), ...Object.keys(next)]);\n\tfor (const key of [...allKeys].sort()) {\n\t\tconst prev = previous[key];\n\t\tconst curr = next[key];\n\t\tif (curr === undefined) removed.push(key);\n\t\telse if (prev === undefined) added.push(key);\n\t\telse if (prev === curr) unchanged.push(key);\n\t\telse changed.push(key);\n\t}\n\treturn { added, changed, removed, unchanged };\n};\n\nconst writeRemoteFileAtomically = async (\n\ttarget: Target,\n\tremotePath: string,\n\tcontents: string,\n\tmode: string,\n\towner?: string\n): Promise<void> => {\n\tconst tempPath = `${remotePath}.new.${Math.floor(Date.now() / 1000)}`;\n\tconst dir = remotePath.split('/').slice(0, -1).join('/') || '/';\n\tconst mkdir = await target.exec(`mkdir -p ${shellQuote(dir)}`);\n\tif (mkdir.exitCode !== 0) {\n\t\tthrow new Error(\n\t\t\t`[deploy/env] mkdir ${dir} failed: ${mkdir.stderr || mkdir.stdout}`\n\t\t);\n\t}\n\t// Write via stdin redirect — no shell escaping of the env file content.\n\tconst writeResult = await target.exec(`cat > ${shellQuote(tempPath)}`, {\n\t\tstdin: contents\n\t});\n\tif (writeResult.exitCode !== 0) {\n\t\tthrow new Error(\n\t\t\t`[deploy/env] write to ${tempPath} failed: ${writeResult.stderr || writeResult.stdout}`\n\t\t);\n\t}\n\tconst chmod = await target.exec(\n\t\t`chmod ${shellQuote(mode)} ${shellQuote(tempPath)}`\n\t);\n\tif (chmod.exitCode !== 0) {\n\t\tthrow new Error(\n\t\t\t`[deploy/env] chmod failed: ${chmod.stderr || chmod.stdout}`\n\t\t);\n\t}\n\tif (owner !== undefined) {\n\t\tconst chown = await target.exec(\n\t\t\t`chown ${shellQuote(owner)} ${shellQuote(tempPath)}`\n\t\t);\n\t\tif (chown.exitCode !== 0) {\n\t\t\tthrow new Error(\n\t\t\t\t`[deploy/env] chown failed: ${chown.stderr || chown.stdout}`\n\t\t\t);\n\t\t}\n\t}\n\tconst mv = await target.exec(\n\t\t`mv ${shellQuote(tempPath)} ${shellQuote(remotePath)}`\n\t);\n\tif (mv.exitCode !== 0) {\n\t\tthrow new Error(`[deploy/env] mv failed: ${mv.stderr || mv.stdout}`);\n\t}\n};\n\n/**\n * Push an env file to a single target. Atomic: write to a `.new`\n * tempfile, chmod / chown, then `mv` into place. Diffs the merged\n * values against the existing file content and skips the\n * write+reload when nothing changed.\n */\nexport const syncEnvToTarget = async (\n\tdeployment: EnvDeployment,\n\tvalues: Record<string, string>\n): Promise<EnvSyncResult> => {\n\tconst mode = deployment.mode ?? '600';\n\tconst merged = mergeValues(deployment, values);\n\tconst previousText = await tryReadRemoteFile(\n\t\tdeployment.target,\n\t\tdeployment.remotePath\n\t);\n\tconst previous = previousText === undefined ? {} : parseEnvFile(previousText);\n\tconst diff = diffEnv(previous, merged);\n\tconst changed = diff.added.length + diff.changed.length + diff.removed.length;\n\n\tif (changed === 0) {\n\t\treturn {\n\t\t\t...diff,\n\t\t\treloaded: false,\n\t\t\tremotePath: deployment.remotePath,\n\t\t\twrote: false\n\t\t};\n\t}\n\n\tconst nextText = serializeEnvFile(merged);\n\tawait writeRemoteFileAtomically(\n\t\tdeployment.target,\n\t\tdeployment.remotePath,\n\t\tnextText,\n\t\tmode,\n\t\tdeployment.owner\n\t);\n\n\tlet reloaded = false;\n\tif (deployment.reload !== undefined) {\n\t\tconst reload = await deployment.target.exec(deployment.reload);\n\t\tif (reload.exitCode !== 0) {\n\t\t\tthrow new Error(\n\t\t\t\t`[deploy/env] reload command failed: ${reload.stderr || reload.stdout}`\n\t\t\t);\n\t\t}\n\t\treloaded = true;\n\t}\n\n\treturn {\n\t\t...diff,\n\t\treloaded,\n\t\tremotePath: deployment.remotePath,\n\t\twrote: true\n\t};\n};\n\n// =============================================================================\n// Multi-target fan-out via a SecretSource\n// =============================================================================\n\nconst resolveSecrets = async (\n\tsource: SecretSource,\n\tnames: ReadonlyArray<string>\n): Promise<Record<string, string>> => {\n\tconst out: Record<string, string> = {};\n\tfor (const name of names) {\n\t\tconst resolved = await source.resolve(name);\n\t\tif (resolved === null) {\n\t\t\tthrow new Error(\n\t\t\t\t`[deploy/env] secret \"${name}\" not found in source`\n\t\t\t);\n\t\t}\n\t\tout[name] = resolved.value;\n\t}\n\treturn out;\n};\n\nexport type DeploymentSyncResult = {\n\tdeployment: EnvDeployment;\n\tresult?: EnvSyncResult;\n\terror?: Error;\n};\n\n/**\n * Fan-out push: for each deployment, resolve its `secretNames` via\n * the source, merge with `extras`, and push to the target. Resolves\n * are fresh every call — so calling this again after\n * `broker.rotate(name)` propagates the new value to every\n * deployment that uses it.\n *\n * Best-effort across the fan-out: a per-target failure is captured\n * in the result, but doesn't stop the rest. Operator inspects the\n * returned array, fixes the broken target, re-runs.\n */\nexport const syncSecretsToDeployments = async (\n\tsource: SecretSource,\n\tdeployments: ReadonlyArray<EnvDeployment>\n): Promise<DeploymentSyncResult[]> => {\n\tconst results: DeploymentSyncResult[] = [];\n\tfor (const deployment of deployments) {\n\t\ttry {\n\t\t\tconst resolved = await resolveSecrets(\n\t\t\t\tsource,\n\t\t\t\tdeployment.secretNames ?? []\n\t\t\t);\n\t\t\tconst result = await syncEnvToTarget(deployment, resolved);\n\t\t\tresults.push({ deployment, result });\n\t\t} catch (error) {\n\t\t\tresults.push({\n\t\t\t\tdeployment,\n\t\t\t\terror: error instanceof Error ? error : new Error(String(error))\n\t\t\t});\n\t\t}\n\t}\n\treturn results;\n};\n\n/**\n * Returns just the deployments that use a given secret name. Useful\n * for \"rotate one secret and propagate ONLY to the consumers\" —\n * `syncSecretsToDeployments(source, deploymentsUsing(name, deployments))`.\n */\nexport const deploymentsUsing = (\n\tname: string,\n\tdeployments: ReadonlyArray<EnvDeployment>\n): EnvDeployment[] =>\n\tdeployments.filter((d) => (d.secretNames ?? []).includes(name));\n"
+  ],
+  "mappings": "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",
+  "debugId": "61C727D3C5F9CC6864756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/deploy",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Generic Bun-project deploy pipeline. A Target (localTarget / sshTarget) is anywhere you can exec + upload — DigitalOcean droplets, Linode, Hetzner, Vultr, your own boxes. Bundled pipeline: prepare → upload → install → build → link → restart → verify. Atomic symlink swap, release history, prune, hooks. SSH shells out to system ssh/rsync — zero ssh2 deps.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "release"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts src/digitalocean.ts src/hetzner.ts src/dns.ts src/cloudflare.ts src/tls.ts --outdir dist --sourcemap --target=bun && tsc --project tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/index.ts src/digitalocean.ts src/hetzner.ts src/dns.ts src/cloudflare.ts src/tls.ts src/env.ts --outdir dist --sourcemap --target=bun && tsc --project tsconfig.build.json",
     "test": "bun test tests/",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write \"./**/*.{ts,json,md}\"",
@@ -71,6 +71,11 @@
       "types": "./dist/tls.d.ts",
       "import": "./dist/tls.js",
       "default": "./dist/tls.js"
+    },
+    "./env": {
+      "types": "./dist/env.d.ts",
+      "import": "./dist/env.js",
+      "default": "./dist/env.js"
     }
   },
   "files": ["dist", "README.md"]