@forgecart/cli 2.202610130038.0 → 2.202610130322.0

package/dist/src/sync/sync-env.runner.js

@@ -1,20 +1,25 @@
-import { readFile, writeFile } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { isJsonObject } from '../json.js';
 import { print } from '../output.js';
-import { dotenvValue, mergeDotenv, merchantAssignments } from '../util/dotenv.util.js';
+import { STOREFRONT_ENV_FILES, dotenvValue, isStorefrontEnvFile, mergeDotenv, merchantAssignments, readDotenvFile, } from '../util/dotenv.util.js';
 /**
  * The variable a merge's lines arrive in — the pod records a command's line,
  * never its environment, so the lines never land in a record.
  */
-const SYNC_ENV_LINES_VARIABLE = 'FORGECART_SYNC_ENV_LINES';
+const SYNC_ENV_FILES_VARIABLE = 'FORGECART_SYNC_ENV_FILES';
 /**
  * `forgecart sync-env [name]` (#2781) — the workspace's side of `forgecart
- * sync`, which the admin API runs in the pod: it reads the merchant lines of the
- * storefront's `.env`, or, with `--merge`, merges the lines
- * FORGECART_SYNC_ENV_LINES carries under init's merge rule, and prints ONE JSON
- * report — the merchant lines as they stand, and how many keys the merge
- * carried in. The platform's own `FORGECART_*` keys are never read out and
- * never written: a laptop's never land, the pod's never leave.
+ * sync`, which the admin API runs in the pod. It reads EVERY env file the
+ * storefront holds — `.env`, `.env.local`, `.env.development`,
+ * `.env.development.local`, `.env.production`, `.env.production.local` — or,
+ * with `--merge`, merges the lines FORGECART_SYNC_ENV_FILES carries for each
+ * file into the storefront file of that name under init's merge rule, creating
+ * one the storefront lacks. The files stay apart, so the dev-server resolves
+ * every key as the laptop does. It prints ONE JSON report: one entry per env
+ * file the storefront holds — its merchant lines as they stand, and how many
+ * keys the merge carried in. The platform's own `FORGECART_*` keys are never
+ * read out and never written: a laptop's never land, the pod's never leave.
  */
 export class SyncEnvRunner {
     name;
@@ -28,31 +33,60 @@ export class SyncEnvRunner {
         this.options = options;
     }
     async run() {
-        const envPath = join(this.name ? resolve(process.cwd(), this.name) : process.cwd(), '.env');
-        const existing = await this.read(envPath);
-        if (this.options.merge !== true) {
-            this.report({ lines: this.merchantLines(existing), merged: 0 });
-            return;
+        const storefront = this.name ? resolve(process.cwd(), this.name) : process.cwd();
+        const incoming = this.incoming();
+        const files = [];
+        for (const file of STOREFRONT_ENV_FILES) {
+            const settled = await this.settle(storefront, file, incoming.get(file));
+            if (settled !== null)
+                files.push(settled);
         }
-        const managed = this.incoming(process.env[SYNC_ENV_LINES_VARIABLE]);
-        if (managed.size === 0) {
-            this.report({ lines: this.merchantLines(existing), merged: 0 });
-            return;
-        }
-        const next = mergeDotenv(existing, managed);
+        this.report({ files });
+    }
+    /**
+     * One env file once the run is done: the merchant keys carried for it merged
+     * in — the file created when the storefront lacks it — and its merchant lines
+     * as they then stand; null for a file the storefront does not hold.
+     */
+    async settle(storefront, file, managed) {
+        const path = join(storefront, file);
+        const existing = await readDotenvFile(path);
+        if (managed === undefined || managed.size === 0)
+            return this.held(file, existing);
+        const next = mergeDotenv(existing ?? '', managed);
         if (next !== existing)
-            await writeFile(envPath, next, 'utf8');
-        this.report({ lines: this.merchantLines(next), merged: managed.size });
+            await writeFile(path, next, 'utf8');
+        return { file, lines: this.merchantLines(next), merged: managed.size };
+    }
+    /** A file nothing was merged into, as it stands — null when the storefront does not hold it. */
+    held(file, content) {
+        if (content === null)
+            return null;
+        return { file, lines: this.merchantLines(content), merged: 0 };
+    }
+    /**
+     * The merchant keys a merge carries for each env file, keyed to their values
+     * — platform keys and other lines dropped; none for a read.
+     */
+    incoming() {
+        const incoming = new Map();
+        if (this.options.merge !== true)
+            return incoming;
+        for (const entry of this.parseEntries(process.env[SYNC_ENV_FILES_VARIABLE])) {
+            const { file, lines } = this.parseEntry(entry);
+            if (incoming.has(file))
+                throw new Error(this.malformedMessage());
+            incoming.set(file, this.managedOf(lines));
+        }
+        return incoming;
     }
-    /** The merchant keys the variable carries, keyed to their values — platform keys and other lines dropped. */
-    incoming(raw) {
-        const lines = this.parseLines(raw);
+    managedOf(lines) {
         return new Map([...merchantAssignments(lines)].map(([key, line]) => [
             key,
             dotenvValue(line, key),
         ]));
     }
-    parseLines(raw) {
+    parseEntries(raw) {
         if (raw === undefined)
             throw new Error(this.malformedMessage());
         let parsed;
@@ -64,14 +98,24 @@ export class SyncEnvRunner {
         }
         if (!Array.isArray(parsed))
             throw new Error(this.malformedMessage());
-        const items = parsed;
+        return parsed;
+    }
+    /** One entry: an env file the storefront reads — never a path outside them — and its lines. */
+    parseEntry(entry) {
+        if (!isJsonObject(entry))
+            throw new Error(this.malformedMessage());
+        const { file, lines } = entry;
+        if (typeof file !== 'string' || !isStorefrontEnvFile(file) || !Array.isArray(lines)) {
+            throw new Error(this.malformedMessage());
+        }
+        const items = lines;
         if (!items.every((item) => typeof item === 'string')) {
             throw new Error(this.malformedMessage());
         }
-        return items;
+        return { file, lines: items };
     }
     malformedMessage() {
-        return `--merge reads ${SYNC_ENV_LINES_VARIABLE}, which must hold a JSON list of KEY=value lines.`;
+        return `--merge reads ${SYNC_ENV_FILES_VARIABLE}, which must hold a JSON list of { "file", "lines" } entries — each file one of ${STOREFRONT_ENV_FILES.join(', ')}, named once, and its lines KEY=value lines.`;
     }
     merchantLines(content) {
         return [...merchantAssignments(content.split('\n')).values()];
@@ -80,16 +124,5 @@ export class SyncEnvRunner {
     report(report) {
         print(JSON.stringify(report));
     }
-    /** The `.env` text — empty when the storefront has none; any other failure propagates. */
-    async read(path) {
-        try {
-            return await readFile(path, 'utf8');
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                return '';
-            throw error;
-        }
-    }
 }
 //# sourceMappingURL=sync-env.runner.js.map

package/dist/src/sync/sync-env.runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-env.runner.js","sourceRoot":"","sources":["../../../src/sync/sync-env.runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync-env.runner.js","sourceRoot":"","sources":["../../../src/sync/sync-env.runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,cAAc,GAEf,MAAM,wBAAwB,CAAC;AAShC;;;GAGG;AACH,MAAM,uBAAuB,GAAG,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,aAAa;IAML;IACA;IANnB;;;OAGG;IACH,YACmB,IAAwB,EACxB,OAAuB;QADvB,SAAI,GAAJ,IAAI,CAAoB;QACxB,YAAO,GAAP,OAAO,CAAgB;IACvC,CAAC;IAEJ,KAAK,CAAC,GAAG;QACP,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QACjF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACjC,MAAM,KAAK,GAAwB,EAAE,CAAC;QACtC,KAAK,MAAM,IAAI,IAAI,oBAAoB,EAAE,CAAC;YACxC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YACxE,IAAI,OAAO,KAAK,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,MAAM,CAClB,UAAkB,EAClB,IAAuB,EACvB,OAAgD;QAEhD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAClF,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;QAClD,IAAI,IAAI,KAAK,QAAQ;YAAE,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC3D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;IACzE,CAAC;IAED,gGAAgG;IACxF,IAAI,CAAC,IAAuB,EAAE,OAAsB;QAC1D,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAClC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IACjE,CAAC;IAED;;;OAGG;IACK,QAAQ;QACd,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA0C,CAAC;QACnE,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,KAAK,IAAI;YAAE,OAAO,QAAQ,CAAC;QACjD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,EAAE,CAAC;YAC5E,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YAC/C,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;YACjE,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAEO,SAAS,CAAC,KAAwB;QACxC,OAAO,IAAI,GAAG,CACZ,CAAC,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAoB,EAAE,CAAC;YACrE,GAAG;YACH,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC;SACvB,CAAC,CACH,CAAC;IACJ,CAAC;IAEO,YAAY,CAAC,GAAuB;QAC1C,IAAI,GAAG,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAChE,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACrE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,+FAA+F;IACvF,UAAU,CAAC,KAAc;QAC/B,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACnE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;QAC9B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACpF,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,KAAK,GAAc,KAAK,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;YACrE,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAChC,CAAC;IAEO,gBAAgB;QACtB,OAAO,iBAAiB,uBAAuB,mFAAmF,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,8CAA8C,CAAC;IAClN,CAAC;IAEO,aAAa,CAAC,OAAe;QACnC,OAAO,CAAC,GAAG,mBAAmB,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,mEAAmE;IAC3D,MAAM,CAAC,MAAqB;QAClC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/src/sync/sync-record.file.d.ts

@@ -1,11 +1,11 @@
-import type { SyncRecord } from './type/sync.types.js';
+import type { SyncEnvDigests, SyncRecord } from './type/sync.types.js';
 /**
  * The last sync of one storefront (#2781), kept in `.forgecart/sync/state.json`
  * beside the private repository: the channel it ran against — a digest of the
  * admin API and the channel token, never the token — the serving commit the
- * laptop's tree last matched, and a digest of every merchant `.env` line as it
- * last travelled. A record of another channel is no record: a storefront pointed
- * at another channel syncs as a first sync.
+ * laptop's tree last matched, and a digest of every merchant line of every env
+ * file as it last travelled, file by file. A record of another channel is no
+ * record: a storefront pointed at another channel syncs as a first sync.
  */
 export declare class SyncRecordFile {
     private readonly channel;
@@ -17,11 +17,13 @@ export declare class SyncRecordFile {
     constructor(storefront: string, channel: string);
     /** This channel's last sync — null before the first, or after a sync against another channel. */
     read(): Promise<SyncRecord | null>;
-    /** Record a sync that left the laptop on `servingSha`, with the `.env` lines as `env` digests them. */
-    write(servingSha: string, env: Readonly<Record<string, string>>): Promise<void>;
+    /** Record a sync that left the laptop on `servingSha`, with the env files' lines as `env` digests them. */
+    write(servingSha: string, env: Readonly<SyncEnvDigests>): Promise<void>;
     /** The record's fields, checked one by one: a file sync cannot read is an error naming it. */
     private parse;
+    /** The env digests, file by file: every file one a storefront reads, every digest a string. */
     private parseEnv;
+    private parseFileDigests;
     private unreadableMessage;
     /** The record's text — null before the first sync; any other failure propagates. */
     private readIfPresent;

package/dist/src/sync/sync-record.file.js

@@ -1,6 +1,7 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isJsonObject } from '../json.js';
+import { isStorefrontEnvFile } from '../util/dotenv.util.js';
 import { SYNC_STATE_PATH } from './sync-repository.js';
 /** The record's file, in the private state directory. */
 const RECORD_FILE = 'state.json';
@@ -11,9 +12,9 @@ const COMMIT_ID_LENGTHS = new Set([40, 64]);
  * The last sync of one storefront (#2781), kept in `.forgecart/sync/state.json`
  * beside the private repository: the channel it ran against — a digest of the
  * admin API and the channel token, never the token — the serving commit the
- * laptop's tree last matched, and a digest of every merchant `.env` line as it
- * last travelled. A record of another channel is no record: a storefront pointed
- * at another channel syncs as a first sync.
+ * laptop's tree last matched, and a digest of every merchant line of every env
+ * file as it last travelled, file by file. A record of another channel is no
+ * record: a storefront pointed at another channel syncs as a first sync.
  */
 export class SyncRecordFile {
     channel;
@@ -34,7 +35,7 @@ export class SyncRecordFile {
         const record = this.parse(raw);
         return record.channel === this.channel ? record : null;
     }
-    /** Record a sync that left the laptop on `servingSha`, with the `.env` lines as `env` digests them. */
+    /** Record a sync that left the laptop on `servingSha`, with the env files' lines as `env` digests them. */
     async write(servingSha, env) {
         const record = { channel: this.channel, servingSha, env: { ...env } };
         await writeFile(this.path, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
@@ -59,10 +60,22 @@ export class SyncRecordFile {
         }
         return { channel, servingSha, env: this.parseEnv(env) };
     }
+    /** The env digests, file by file: every file one a storefront reads, every digest a string. */
     parseEnv(env) {
         if (!isJsonObject(env))
             throw new Error(this.unreadableMessage());
-        const entries = Object.entries(env);
+        const digests = {};
+        for (const [file, fileDigests] of Object.entries(env)) {
+            if (!isStorefrontEnvFile(file))
+                throw new Error(this.unreadableMessage());
+            digests[file] = this.parseFileDigests(fileDigests);
+        }
+        return digests;
+    }
+    parseFileDigests(fileDigests) {
+        if (!isJsonObject(fileDigests))
+            throw new Error(this.unreadableMessage());
+        const entries = Object.entries(fileDigests);
         if (!entries.every((entry) => typeof entry[1] === 'string')) {
             throw new Error(this.unreadableMessage());
         }

package/dist/src/sync/sync-record.file.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-record.file.js","sourceRoot":"","sources":["../../../src/sync/sync-record.file.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync-record.file.js","sourceRoot":"","sources":["../../../src/sync/sync-record.file.ts"],"names":[],"mappings":"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"}

package/dist/src/sync/sync-round.d.ts

@@ -1,6 +1,6 @@
 import type { CliCredentials } from '../authorization/type/cli-authorization.types.js';
 import { type SyncDivergenceSelection } from './sync-divergence.js';
-import type { SyncDotenvFile } from './sync-dotenv.file.js';
+import type { SyncEnvChannel } from './sync-env-channel.js';
 import type { SyncRecordFile } from './sync-record.file.js';
 import type { SyncRepository } from './sync-repository.js';
 import { type SyncRoundEnd, type SyncRoundOptions } from './type/sync.types.js';
@@ -18,7 +18,8 @@ import type { WorkspaceSyncClient } from './workspace-sync.client.js';
  * rejects with the gates' diagnostics (exit 1). Both changed: ONE selection —
  * local overrides workspace, workspace overrides local, or Abort — never a
  * merge; an abort or an unanswered selection ends the run on exit 4. The
- * merchant lines of `.env` travel with the tree; the platform's keys never do.
+ * merchant lines of every env file travel with the tree, file for file; the
+ * platform's keys never do.
  */
 export declare class SyncRound {
     private readonly options;
@@ -26,26 +27,26 @@ export declare class SyncRound {
     private readonly client;
     private readonly repository;
     private readonly records;
-    private readonly dotenv;
+    private readonly envChannel;
     private readonly selection;
-    constructor(options: SyncRoundOptions, credentials: CliCredentials, client: WorkspaceSyncClient, repository: SyncRepository, records: SyncRecordFile, dotenv: SyncDotenvFile, selection: SyncDivergenceSelection);
+    constructor(options: SyncRoundOptions, credentials: CliCredentials, client: WorkspaceSyncClient, repository: SyncRepository, records: SyncRecordFile, envChannel: SyncEnvChannel, selection: SyncDivergenceSelection);
     /** Run the round; a board that moves under its push is read again, a bounded number of times. */
     run(): Promise<SyncRoundEnd>;
     private attempt;
     /** Decide, print the plan once, and move what it says. */
     private settle;
     private verdictOf;
-    /** The two trees agree: record where they stand, and send `.env` lines the laptop changed. */
+    /** The two trees agree: record where they stand, and send the env lines the laptop changed. */
     private inSync;
-    /** Only the workspace changed — or it overrides the laptop: its tree and its `.env` lines land on the laptop. */
+    /** Only the workspace changed — or it overrides the laptop: its tree and its env files' lines land on the laptop. */
     private pull;
     /** Only the laptop changed, and the run never pushes: nothing moves. */
     private keepLocal;
     /**
      * Push the laptop's tree onto the serving tip — or over it, when local
-     * overrides workspace — as ONE commit in ONE bundle, with the changed `.env`
-     * lines. A tree the gates reject ends the run on exit 1 with their
-     * diagnostics; a board that moved before the push landed is read again.
+     * overrides workspace — as ONE commit in ONE bundle, with the env lines
+     * changed in each file. A tree the gates reject ends the run on exit 1 with
+     * their diagnostics; a board that moved before the push landed is read again.
      */
     private land;
     /** Both sides changed: the selection decides which tree wins, or the run stops with nothing moved. */
@@ -61,8 +62,13 @@ export declare class SyncRound {
     private dryVerdict;
     /** The plan, printed once per round before anything moves. */
     private printPlan;
-    /** The `.env` keys the plan carries, as a count. */
-    private envPlan;
+    /** The env keys the plan carries, as a count per env file: those a pull takes, or those a push sends. */
+    private printEnvPlan;
+    /** The env keys a pull takes, per workspace env file — none when no bundle was read this round. */
+    private printIncomingEnv;
+    /** One plan line per env file — its name, then its merchant keys — or `none` when there is no file. */
+    private printEnvFiles;
+    private planLine;
     private printChanges;
     /** The record — when the private repository still holds its base; else a first sync. */
     private heldRecord;
@@ -80,9 +86,13 @@ export declare class SyncRound {
     private sendPush;
     /** A push the workspace did not take: exit 1, with what refused it. */
     private rejection;
-    /** The `.env` lines a round in sync sends alone — none for a run that never pushes. */
+    /** The env lines a round in sync sends alone — none for a run that never pushes. */
     private sendEnvAlone;
-    /** The workspace's `.env` lines, taken — none when no bundle was read this round. */
+    /** The env files a push carries: those with a line changed since it last travelled. */
+    private carried;
+    /** How many merchant keys a push merged into the workspace, across every env file. */
+    private mergedKeys;
+    /** The workspace's env files' lines, taken — none when no bundle was read this round. */
     private takeEnv;
     private viewOf;
     /** The travelling tree of the recorded base — the empty tree before a first sync. */

package/dist/src/sync/sync-round.js

@@ -11,6 +11,8 @@ const SYNC_FAILED_CODE = 'WORKSPACE_SYNC_FAILED';
 const SHORT_SHA_LENGTH = 12;
 /** How many changed paths a divergence lists per side before it counts the rest. */
 const LISTED_PATHS = 20;
+/** The width a plan line's label is padded to — an env file's name longer than it is followed by one space. */
+const PLAN_LABEL_WIDTH = 10;
 /**
  * One round of `forgecart sync` (#2781): read the board's serving commit,
  * snapshot the laptop's tree, hold the serving tree locally, print the plan
@@ -24,7 +26,8 @@ const LISTED_PATHS = 20;
  * rejects with the gates' diagnostics (exit 1). Both changed: ONE selection —
  * local overrides workspace, workspace overrides local, or Abort — never a
  * merge; an abort or an unanswered selection ends the run on exit 4. The
- * merchant lines of `.env` travel with the tree; the platform's keys never do.
+ * merchant lines of every env file travel with the tree, file for file; the
+ * platform's keys never do.
  */
 export class SyncRound {
     options;
@@ -32,15 +35,15 @@ export class SyncRound {
     client;
     repository;
     records;
-    dotenv;
+    envChannel;
     selection;
-    constructor(options, credentials, client, repository, records, dotenv, selection) {
+    constructor(options, credentials, client, repository, records, envChannel, selection) {
         this.options = options;
         this.credentials = credentials;
         this.client = client;
         this.repository = repository;
         this.records = records;
-        this.dotenv = dotenv;
+        this.envChannel = envChannel;
         this.selection = selection;
     }
     /** Run the round; a board that moves under its push is read again, a bounded number of times. */
@@ -93,20 +96,20 @@ export class SyncRound {
             return SyncVerdict.DIVERGED;
         return this.options.pullOnly ? SyncVerdict.KEEP_LOCAL : SyncVerdict.PUSH;
     }
-    /** The two trees agree: record where they stand, and send `.env` lines the laptop changed. */
+    /** The two trees agree: record where they stand, and send the env lines the laptop changed. */
     async inSync(view) {
         const env = await this.sendEnvAlone(view.record);
         await this.record(view.serving.sha, env.digests);
-        const summary = `in sync at serving ${this.short(view.serving.sha)}; ${String(env.merged)} .env key(s) merged into the workspace`;
+        const summary = `in sync at serving ${this.short(view.serving.sha)}; ${String(env.merged)} env key(s) merged into the workspace`;
         print(summary);
         return { localTree: view.local, servingSha: view.serving.sha, summary };
     }
-    /** Only the workspace changed — or it overrides the laptop: its tree and its `.env` lines land on the laptop. */
+    /** Only the workspace changed — or it overrides the laptop: its tree and its env files' lines land on the laptop. */
     async pull(view) {
         const materialized = await this.repository.materialize(view.local, view.serving.tree);
         const env = await this.takeEnv(view);
         await this.record(view.serving.sha, env.digests);
-        const summary = `pulled serving ${this.short(view.serving.sha)}: ${String(materialized.written)} file(s) written, ${String(materialized.removed)} removed, ${String(env.taken)} .env key(s) taken`;
+        const summary = `pulled serving ${this.short(view.serving.sha)}: ${String(materialized.written)} file(s) written, ${String(materialized.removed)} removed, ${String(env.taken)} env key(s) taken`;
         print(summary);
         return { localTree: view.serving.tree, servingSha: view.serving.sha, summary };
     }
@@ -122,16 +125,16 @@ export class SyncRound {
     }
     /**
      * Push the laptop's tree onto the serving tip — or over it, when local
-     * overrides workspace — as ONE commit in ONE bundle, with the changed `.env`
-     * lines. A tree the gates reject ends the run on exit 1 with their
-     * diagnostics; a board that moved before the push landed is read again.
+     * overrides workspace — as ONE commit in ONE bundle, with the env lines
+     * changed in each file. A tree the gates reject ends the run on exit 1 with
+     * their diagnostics; a board that moved before the push landed is read again.
      */
     async land(view) {
         const sent = await this.repository.changes(view.serving.tree, view.local);
-        const outgoing = await this.dotenv.outgoing(view.record?.env ?? null);
+        const outgoing = await this.envChannel.outgoing(view.record?.env ?? null);
         const commit = await this.repository.pushCommit(view.local, view.serving.sha);
         const bundle = await this.repository.pushBundle(commit, view.serving.sha);
-        const result = await this.sendPush(bundle, outgoing.lines);
+        const result = await this.sendPush(bundle, this.carried(outgoing));
         if (result === null) {
             return { kind: 'moved', point: { localTree: view.local, servingSha: view.serving.sha } };
         }
@@ -139,7 +142,7 @@ export class SyncRound {
             throw this.rejection(result);
         const landed = await this.holdLanded(result.servingSha, view.serving.sha);
         await this.record(landed, outgoing.digests);
-        const summary = `pushed ${String(sent.length)} path(s): serving is ${this.short(landed)}; ${String(result.envKeys)} .env key(s) merged into the workspace`;
+        const summary = `pushed ${String(sent.length)} path(s): serving is ${this.short(landed)}; ${String(this.mergedKeys(result))} env key(s) merged into the workspace`;
         print(summary);
         return this.settled({ localTree: view.local, servingSha: landed, summary });
     }
@@ -169,11 +172,11 @@ export class SyncRound {
     async dryRun(state, record, local) {
         const changes = await this.repository.changes(await this.baseOf(record), local);
         const moved = record?.servingSha !== state.servingSha;
-        const outgoing = await this.dotenv.outgoing(record?.env ?? null);
+        const outgoing = await this.envChannel.outgoing(record?.env ?? null);
         print(`  serving    ${this.short(state.servingSha)}, ${this.lastSync(record)}`);
         print(`  local      ${String(changes.length)} path(s) changed since the last sync`);
         print(`  workspace  ${moved ? 'moved' : 'unchanged'} since the last sync`);
-        print(`  .env       ${String(outgoing.lines.length)} merchant key(s) a push would send`);
+        this.printEnvFiles(outgoing.files, 'a push would send', 'no env file on this laptop');
         print(`  plan       ${this.dryVerdict(changes.length > 0, moved, state.servingSha)}`);
         print('  paths a push would send:');
         for (const change of changes)
@@ -199,24 +202,48 @@ export class SyncRound {
         print(`  serving    ${this.short(view.serving.sha)}, ${this.lastSync(view.record)}`);
         print(`  local      ${String(view.localChanges.length)} path(s) changed since the last sync`);
         print(`  workspace  ${String(view.workspaceChanges.length)} path(s) changed since the last sync`);
-        print(`  .env       ${await this.envPlan(view, verdict)}`);
+        await this.printEnvPlan(view, verdict);
         print(`  plan       ${verdict}`);
         if (verdict !== SyncVerdict.DIVERGED)
             return;
         this.printChanges('changed on this laptop', view.localChanges);
         this.printChanges('changed on the workspace', view.workspaceChanges);
     }
-    /** The `.env` keys the plan carries, as a count. */
-    async envPlan(view, verdict) {
+    /** The env keys the plan carries, as a count per env file: those a pull takes, or those a push sends. */
+    async printEnvPlan(view, verdict) {
         const recorded = view.record?.env ?? null;
         if (verdict === SyncVerdict.PULL) {
-            const taken = await this.dotenv.takeable(view.serving.envLines ?? [], recorded);
-            return `${String(taken)} merchant key(s) to take`;
+            await this.printIncomingEnv(view.serving.envFiles, recorded);
+            return;
         }
-        if (this.options.pullOnly)
-            return 'nothing to send: --pull never pushes';
-        const outgoing = await this.dotenv.outgoing(recorded);
-        return `${String(outgoing.lines.length)} merchant key(s) to send`;
+        if (this.options.pullOnly) {
+            print(this.planLine('env', 'nothing to send: --pull never pushes'));
+            return;
+        }
+        const outgoing = await this.envChannel.outgoing(recorded);
+        this.printEnvFiles(outgoing.files, 'to send', 'no env file on this laptop');
+    }
+    /** The env keys a pull takes, per workspace env file — none when no bundle was read this round. */
+    async printIncomingEnv(workspaceFiles, recorded) {
+        if (workspaceFiles === null) {
+            print(this.planLine('env', 'nothing to take: no bundle was read this round'));
+            return;
+        }
+        const incoming = await this.envChannel.incoming(workspaceFiles, recorded);
+        this.printEnvFiles(incoming, 'to take', 'no env file in the workspace');
+    }
+    /** One plan line per env file — its name, then its merchant keys — or `none` when there is no file. */
+    printEnvFiles(files, action, none) {
+        if (files.length === 0) {
+            print(this.planLine('env', none));
+            return;
+        }
+        for (const { file, lines } of files) {
+            print(this.planLine(file, `${String(lines.length)} merchant key(s) ${action}`));
+        }
+    }
+    planLine(label, text) {
+        return `  ${label.padEnd(PLAN_LABEL_WIDTH)} ${text}`;
     }
     printChanges(heading, changes) {
         print(`  ${heading}:`);
@@ -242,12 +269,12 @@ export class SyncRound {
             return {
                 sha: servingSha,
                 tree: await this.repository.travellingTree(servingSha),
-                envLines: null,
+                envFiles: null,
             };
         }
         const bundle = await this.pulledBundle(record);
         const sha = await this.repository.fetchBundle(bundle.bytes);
-        return { sha, tree: await this.repository.travellingTree(sha), envLines: bundle.envLines };
+        return { sha, tree: await this.repository.travellingTree(sha), envFiles: bundle.envFiles };
     }
     /**
      * The bundle a pull reads: the serving commits since the recorded base when
@@ -281,9 +308,9 @@ export class SyncRound {
         return (await this.repository.hasCommit(landed)) ? landed : cutOn;
     }
     /** The push, or null when the board moved past the commit it was cut on before it landed. */
-    async sendPush(bundle, envLines) {
+    async sendPush(bundle, envFiles) {
         try {
-            return await this.client.push(bundle, envLines);
+            return await this.client.push(bundle, envFiles);
         }
         catch (error) {
             if (error instanceof AdminApiRefusal && error.code === SYNC_DIVERGED_CODE)
@@ -301,22 +328,31 @@ export class SyncRound {
             ...result.seoFindings.flatMap((finding) => indented(`seo: ${finding}`)),
         ]);
     }
-    /** The `.env` lines a round in sync sends alone — none for a run that never pushes. */
+    /** The env lines a round in sync sends alone — none for a run that never pushes. */
     async sendEnvAlone(record) {
         if (this.options.pullOnly)
             return { merged: 0, digests: record?.env ?? {} };
-        const outgoing = await this.dotenv.outgoing(record?.env ?? null);
-        if (outgoing.lines.length === 0)
+        const outgoing = await this.envChannel.outgoing(record?.env ?? null);
+        const carried = this.carried(outgoing);
+        if (carried.length === 0)
             return { merged: 0, digests: outgoing.digests };
-        const result = await this.client.push(null, outgoing.lines);
-        return { merged: result.envKeys, digests: outgoing.digests };
+        const result = await this.client.push(null, carried);
+        return { merged: this.mergedKeys(result), digests: outgoing.digests };
+    }
+    /** The env files a push carries: those with a line changed since it last travelled. */
+    carried(outgoing) {
+        return outgoing.files.filter(({ lines }) => lines.length > 0);
+    }
+    /** How many merchant keys a push merged into the workspace, across every env file. */
+    mergedKeys(result) {
+        return result.envFiles.reduce((total, { merged }) => total + merged, 0);
     }
-    /** The workspace's `.env` lines, taken — none when no bundle was read this round. */
+    /** The workspace's env files' lines, taken — none when no bundle was read this round. */
     async takeEnv(view) {
         const recorded = view.record?.env ?? null;
-        if (view.serving.envLines === null)
+        if (view.serving.envFiles === null)
             return { taken: 0, digests: recorded ?? {} };
-        return this.dotenv.take(view.serving.envLines, this.credentials, recorded);
+        return this.envChannel.take(view.serving.envFiles, this.credentials, recorded);
     }
     async viewOf(record, local, serving) {
         const base = await this.baseOf(record);