@antelopejs/dms-frontend 0.6.4 → 0.7.0

package/dist/commands/build-action.d.ts

@@ -5,6 +5,8 @@ export interface BuildOptions {
     force?: boolean;
     offline?: boolean;
     bootstrapSecret?: string;
+    from?: string;
+    workspace?: string;
 }
 interface BuildStep {
     script: string;

package/dist/commands/build-action.js

@@ -7,9 +7,29 @@ const node_path_1 = require("node:path");
 const cli_1 = require("@antelopejs/core/cli");
 const child_output_1 = require("../child-output");
 const common_1 = require("../common");
+const snapshot_1 = require("../snapshot");
 const output_1 = require("../output");
 const vite_output_1 = require("../vite-output");
 const workspace_task_1 = require("./workspace-task");
+function buildSource(options) {
+    if (!options.from) {
+        return { backendUrl: (0, common_1.requireBackendUrl)(options.backendUrl) };
+    }
+    if (options.offline) {
+        throw new cli_1.CliError({
+            title: "--from and --offline cannot be combined",
+            reason: "A snapshot build never asks the backend already.",
+            fixes: ["Drop --offline"],
+        });
+    }
+    const snapshot = (0, snapshot_1.readSnapshot)(options.from);
+    return {
+        backendUrl: options.backendUrl
+            ? (0, common_1.parseBackendUrl)(options.backendUrl)
+            : snapshot.backendUrl,
+        snapshot: { dir: options.from, snapshot },
+    };
+}
 exports.BUILD_STEPS = [
     {
         script: "build:client",
@@ -102,19 +122,25 @@ async function runBuild(options) {
     }
 }
 async function buildProduction(options, startedAt) {
-    const backendUrl = (0, common_1.requireBackendUrl)(options.backendUrl);
-    const sessionSecret = (0, common_1.resolveSessionSecret)("build");
-    const bootstrapSecret = (0, common_1.normalizeBootstrapSecret)(options.bootstrapSecret);
+    const { backendUrl, snapshot } = buildSource(options);
+    const bootstrapSecret = snapshot
+        ? undefined
+        : (0, common_1.normalizeBootstrapSecret)(options.bootstrapSecret);
     const ui = (0, cli_1.getProcessUi)();
     (0, output_1.writeHeader)("build", [backendUrl, "production"]);
-    const { workspaceDir, layers, manifestFromCache, manifestFetchedAt } = await (0, workspace_task_1.setUpWorkspace)({
+    const { workspaceDir, layers, manifestFromCache, manifestFetchedAt, buildOrigin, } = await (0, workspace_task_1.setUpWorkspace)({
         backendUrl,
         force: !!options.force,
         mode: "build",
-        offline: (0, common_1.flagOrEnv)(options.offline, "DMS_OFFLINE"),
+        offline: snapshot ? false : (0, common_1.flagOrEnv)(options.offline, "DMS_OFFLINE"),
         bootstrapSecret,
+        workspaceDir: options.workspace,
+        snapshot,
     });
-    if (manifestFromCache) {
+    if (snapshot) {
+        ui.message("info", `Building from the snapshot of ${snapshot.snapshot.backendUrl}${(0, output_1.cachedAge)(snapshot.snapshot.takenAt)}`, { detail: `Modules digest ${snapshot.snapshot.digest}` });
+    }
+    else if (manifestFromCache) {
         ui.message("warn", `Building from the manifest and layers archive${(0, output_1.cachedAge)(manifestFetchedAt)}`, { detail: "The output may not match the current backend." });
     }
     ui.message("info", "Building for production", {
@@ -129,7 +155,6 @@ async function buildProduction(options, startedAt) {
         nameFile: (0, child_output_1.createFileNamer)(layers),
         env: {
             ...process.env,
-            DMS_SESSION_SECRET: sessionSecret,
             NODE_OPTIONS: "--max-old-space-size=4096",
             NODE_PATH: (0, node_path_1.join)(workspaceDir, "node_modules"),
             [vite_output_1.VITE_LOG_LEVEL_VARIABLE]: (0, vite_output_1.viteLogLevel)(isVerbose),
@@ -137,6 +162,7 @@ async function buildProduction(options, startedAt) {
     };
     for (const step of exports.BUILD_STEPS)
         await runBuildStep(step, context);
+    (0, snapshot_1.writeBuildOrigin)(workspaceDir, buildOrigin);
     (0, vite_output_1.reportViteWarnings)(context.warnings, isVerbose, ui);
     (0, output_1.writeBlankLine)();
     ui.summary({
@@ -145,8 +171,10 @@ async function buildProduction(options, startedAt) {
         durationMs: Date.now() - startedAt,
         nextSteps: [
             {
-                command: `ajs dms start -b ${backendUrl}`,
-                description: "with the DMS_SESSION_SECRET this build used",
+                command: options.workspace
+                    ? `ajs dms start -b ${backendUrl} --workspace ${options.workspace}`
+                    : `ajs dms start -b ${backendUrl}`,
+                description: "with DMS_SESSION_SECRET and the server's secrets in its environment",
             },
         ],
     });

package/dist/commands/build.js

@@ -39,9 +39,13 @@ const config_1 = require("../config");
 const cli_1 = require("@antelopejs/core/cli");
 const BUILD_EXAMPLES = [
     {
-        description: "With DMS_SESSION_SECRET set in the environment or ./.env",
+        description: "With DMS_BOOTSTRAP_SECRET set in the environment or ./.env",
         command: "ajs dms build -b https://dms.example.com",
     },
+    {
+        description: "From a snapshot, without the backend or any secret, into the project (a container image)",
+        command: "ajs dms build --from dms-snapshot --workspace .dms-frontend",
+    },
     {
         description: "Rebuild from the cache while the backend is down",
         command: "ajs dms build -b https://dms.example.com --offline",
@@ -50,8 +54,10 @@ const BUILD_EXAMPLES = [
 function cmdBuild() {
     const command = new commander_1.Command("build")
         .summary("Build the production frontend")
-        .description("Build the production frontend from the manifest and layers archive the backend serves, into the workspace's dist directory. Needs a DMS_SESSION_SECRET of 32 characters or more.")
-        .addOption(config_1.Options.backendUrl("Backend URL to build for; required, as -b or the variable"))
+        .description("Build the production frontend from the manifest and layers archive the backend serves, or from a snapshot of them, into the workspace's dist directory. The build holds no secret: the server reads its own from its environment when it starts.")
+        .addOption(config_1.Options.backendUrl("Backend URL to build for; required, as -b or the variable, unless --from names a snapshot"))
+        .addOption(new commander_1.Option("--from <dir>", "Build from the snapshot in this directory (ajs dms snapshot), without the backend"))
+        .addOption(config_1.Options.workspace("Build into this directory instead of the workspace under ~/.antelopejs, to ship it with the project"))
         .addOption(config_1.Options.force("Extract the layers archive from scratch and reinstall the workspace dependencies"))
         .addOption(config_1.Options.offline("Build from the last cached manifest and layers archive, without the backend"))
         .addOption(config_1.Options.bootstrapSecret())

package/dist/commands/snapshot-action.d.ts

@@ -0,0 +1,6 @@
+export interface SnapshotOptions {
+    backendUrl?: string;
+    output: string;
+    bootstrapSecret?: string;
+}
+export declare function runSnapshot(options: SnapshotOptions): Promise<void>;

package/dist/commands/snapshot-action.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSnapshot = runSnapshot;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const cli_1 = require("@antelopejs/core/cli");
+const common_1 = require("../common");
+const output_1 = require("../output");
+const snapshot_1 = require("../snapshot");
+async function runSnapshot(options) {
+    const startedAt = Date.now();
+    const backendUrl = (0, common_1.requireBackendUrl)(options.backendUrl);
+    const bootstrapSecret = (0, common_1.normalizeBootstrapSecret)(options.bootstrapSecret);
+    if (!bootstrapSecret) {
+        throw new common_1.UsageError({
+            title: "A snapshot needs the bootstrap credential",
+            reason: "Without it the backend withholds the modules' backend proxies, and a build from the snapshot would not route them.",
+            fixes: [
+                "Set DMS_BOOTSTRAP_SECRET to the backend's frontend.bootstrapSecret",
+            ],
+        });
+    }
+    (0, output_1.writeHeader)("snapshot", [backendUrl]);
+    const task = (0, cli_1.getProcessTasks)().start("Fetching the manifest and layers");
+    const scratch = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "dms-snapshot-"));
+    try {
+        const manifest = await (0, common_1.fetchManifest)(backendUrl, undefined, bootstrapSecret);
+        const layers = (0, node_path_1.join)(scratch, snapshot_1.SNAPSHOT_LAYERS_DIR);
+        await (0, common_1.downloadAndExtractLayers)(backendUrl, manifest.pack, layers, true, bootstrapSecret);
+        const snapshot = (0, snapshot_1.writeSnapshot)(options.output, backendUrl, manifest, layers);
+        task.succeed(`Fetched ${manifest.modules.length} frontend module${manifest.modules.length === 1 ? "" : "s"}`);
+        (0, output_1.writeBlankLine)();
+        (0, cli_1.getProcessUi)().summary({
+            headline: `Took a snapshot of modules ${snapshot.digest}, without private values`,
+            artifact: options.output,
+            durationMs: Date.now() - startedAt,
+            nextSteps: [
+                {
+                    command: `ajs dms build --from ${options.output} --workspace .dms-frontend`,
+                    description: "without the backend or any secret",
+                },
+            ],
+        });
+    }
+    catch (error) {
+        (0, output_1.endInterruptedTask)(task, error, "Snapshot stopped");
+        throw error;
+    }
+    finally {
+        (0, node_fs_1.rmSync)(scratch, { recursive: true, force: true });
+    }
+}

package/dist/commands/snapshot.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function cmdSnapshot(): Command;

package/dist/commands/snapshot.js

@@ -0,0 +1,55 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdSnapshot = cmdSnapshot;
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const cli_1 = require("@antelopejs/core/cli");
+const SNAPSHOT_EXAMPLES = [
+    {
+        description: "With DMS_BOOTSTRAP_SECRET set, after a backend release",
+        command: "ajs dms snapshot -b https://dms.example.com -o dms-snapshot",
+    },
+];
+function cmdSnapshot() {
+    const command = new commander_1.Command("snapshot")
+        .summary("Keep what a build needs from the backend, without its secrets")
+        .description("Fetch the manifest and the layers archive the backend serves, and write them into a directory with every private value emptied, so that ajs dms build --from builds without the backend or any credential. Take it again when the backend's frontend modules change: start says when they no longer match.")
+        .addOption(config_1.Options.backendUrl("Backend URL to take the snapshot from; required, as -b or the variable"))
+        .addOption(new commander_1.Option("-o, --output <dir>", "Directory to write the snapshot to").default("dms-snapshot"))
+        .addOption(config_1.Options.bootstrapSecret())
+        .action(async (options) => (await Promise.resolve().then(() => __importStar(require("./snapshot-action")))).runSnapshot(options));
+    return (0, cli_1.withExamples)(command, SNAPSHOT_EXAMPLES);
+}

package/dist/commands/start-action.d.ts

@@ -1,5 +1,6 @@
 export interface StartOptions {
     backendUrl?: string;
     port: string;
+    workspace?: string;
 }
 export declare function runStart(options: StartOptions): Promise<void>;

package/dist/commands/start-action.js

@@ -10,7 +10,34 @@ const ports_1 = require("../ports");
 const server_process_1 = require("../server-process");
 const update_check_1 = require("../update-check");
 const module_set_1 = require("../module-set");
+const snapshot_1 = require("../snapshot");
+const config_1 = require("../config");
+const manifest_secrets_1 = require("../manifest-secrets");
+const private_values_1 = require("../private-values");
 const BUILD_TIME_MANIFEST = "the build-time manifest";
+function builtPrivateOptions(workspaceDir) {
+    try {
+        const { modules } = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(workspaceDir, config_1.SERVER_OPTIONS_FILE), "utf8"));
+        return modules ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+function reportUnfilledPrivateValues(workspaceDir) {
+    const unfilled = (0, private_values_1.unfilledPrivateValues)(builtPrivateOptions(workspaceDir), (0, private_values_1.parsePrivateOptions)(process.env[private_values_1.PRIVATE_OPTIONS_VARIABLE]), Object.values(manifest_secrets_1.MANIFEST_SECRET_ENV));
+    const ui = (0, cli_1.getProcessUi)();
+    unfilled.forEach(({ module, path }, index) => {
+        const isLast = index === unfilled.length - 1;
+        ui.message("warn", `${module}: private option ${path.join(".")} is not set`, {
+            details: isLast
+                ? [
+                    `${ui.symbols.levels.hint} Set ${unfilled.length === 1 ? "it" : "them"} in ${private_values_1.PRIVATE_OPTIONS_VARIABLE}, a JSON object of options by module id, with the values the backend uses`,
+                ]
+                : [],
+        });
+    });
+}
 const PRODUCTION = "production";
 function serverNodeEnv() {
     const nodeEnv = process.env.NODE_ENV || PRODUCTION;
@@ -24,22 +51,68 @@ function serverNodeEnv() {
     }
     return nodeEnv;
 }
+async function reportDrift(backendUrl, origin) {
+    const ui = (0, cli_1.getProcessUi)();
+    const bootstrapSecret = process.env.DMS_BOOTSTRAP_SECRET?.trim();
+    if (!origin)
+        return;
+    if (origin.authenticated === false) {
+        ui.message("info", `Built from modules ${origin.digest}; not compared with the backend`, {
+            detail: "The build read the manifest without DMS_BOOTSTRAP_SECRET, which leaves out the backend proxies.",
+        });
+        return;
+    }
+    if (!bootstrapSecret) {
+        ui.message("info", `Built from modules ${origin.digest}; not compared with the backend`, { detail: "Set DMS_BOOTSTRAP_SECRET to have start compare them." });
+        return;
+    }
+    const drift = await (0, module_set_1.compareWithBackend)(backendUrl, origin.digest, snapshot_1.manifestDigest, bootstrapSecret);
+    if (drift.status === "matches") {
+        ui.message("info", `The backend serves the modules ${origin.digest} this build was made from`);
+        return;
+    }
+    if (drift.status === "unknown") {
+        ui.message("info", `Built from modules ${origin.digest}; not compared with the backend: ${drift.reason}`);
+        return;
+    }
+    const refresh = origin.source === "snapshot"
+        ? `Refresh the snapshot and rebuild: ajs dms snapshot -b ${backendUrl} -o <dir>, then ajs dms build --from <dir>`
+        : `Rebuild: ajs dms build -b ${backendUrl}`;
+    ui.message("warn", `The backend serves modules ${drift.served}; this build was made from ${origin.digest} (${origin.source}${(0, output_1.cachedAge)(origin.takenAt)})`, {
+        details: [
+            "Pages of modules added or removed since, or whose routes changed, are missing or stale.",
+            `${ui.symbols.levels.hint} ${refresh}`,
+        ],
+    });
+}
 async function runStart(options) {
     const startedAt = Date.now();
-    const backendUrl = (0, common_1.requireBackendUrl)(options.backendUrl);
+    const explicitWorkspace = options.workspace
+        ? (0, node_path_1.resolve)(options.workspace)
+        : undefined;
+    const origin = explicitWorkspace
+        ? (0, snapshot_1.readBuildOrigin)(explicitWorkspace)
+        : undefined;
+    const backendUrl = (0, common_1.requireBackendUrl)(options.backendUrl ?? origin?.backendUrl);
     const requestedPort = (0, common_1.parsePort)(options.port);
     const sessionSecret = (0, common_1.resolveSessionSecret)("start");
-    const workspaceDir = (0, common_1.getWorkspaceDir)(backendUrl);
+    const workspaceDir = explicitWorkspace ?? (0, common_1.getWorkspaceDir)(backendUrl);
     const serverPath = (0, node_path_1.join)(workspaceDir, "server.mjs");
     const clientPath = (0, node_path_1.join)(workspaceDir, "dist", "client", "index.html");
     if (!(0, node_fs_1.existsSync)(serverPath) || !(0, node_fs_1.existsSync)(clientPath)) {
         throw new cli_1.CliError({
             title: `No production build for ${backendUrl}`,
             reason: `${(0, output_1.showWorkspace)(workspaceDir)} has no built server or client.`,
-            fixes: [`Build it first: ajs dms build -b ${backendUrl}`],
+            fixes: [
+                explicitWorkspace
+                    ? `Build it first: ajs dms build --from <snapshot> --workspace ${options.workspace}`
+                    : `Build it first: ajs dms build -b ${backendUrl}`,
+            ],
         });
     }
-    (0, common_1.writeWorkspaceMeta)(workspaceDir, backendUrl, (0, common_1.canonicalizeBackendUrl)(backendUrl));
+    if (!explicitWorkspace) {
+        (0, common_1.writeWorkspaceMeta)(workspaceDir, backendUrl, (0, common_1.canonicalizeBackendUrl)(backendUrl));
+    }
     const builtAt = (0, node_fs_1.statSync)(clientPath).mtime.toISOString();
     (0, output_1.writeHeader)("start", [
         backendUrl,
@@ -57,7 +130,8 @@ async function runStart(options) {
     }
     const port = reserved.port;
     const secrets = (0, common_1.resolveManifestSecrets)((0, common_1.collectManifestSecrets)((0, common_1.readCachedManifest)(workspaceDir)?.manifest.modules ?? []));
-    (0, common_1.reportManifestSecrets)(secrets, (count) => `Set ${count === 1 ? "it" : "them"}, or rebuild with DMS_BOOTSTRAP_SECRET so the manifest carries ${count === 1 ? "it" : "them"}`);
+    (0, common_1.reportManifestSecrets)(secrets, (count) => `Set ${count === 1 ? "it" : "them"} in the server's environment, with the value${count === 1 ? "" : "s"} the backend uses`);
+    reportUnfilledPrivateValues(workspaceDir);
     const secretSources = (0, common_1.describeSecretSources)(secrets.sources, BUILD_TIME_MANIFEST);
     const nodeEnv = serverNodeEnv();
     await reserved.release();
@@ -88,6 +162,7 @@ async function runStart(options) {
             });
             void (0, module_set_1.reportFrontendReady)(backendUrl, ((0, common_1.readCachedManifest)(workspaceDir)?.manifest.modules ?? []).map((module) => module.name), process.env.DMS_BOOTSTRAP_SECRET);
             void (0, update_check_1.reportAvailableUpdate)({ isFollowed: true });
+            void reportDrift(backendUrl, origin ?? (0, snapshot_1.readBuildOrigin)(workspaceDir));
         },
     });
     process.exitCode = code;

package/dist/commands/start.js

@@ -42,13 +42,18 @@ const START_EXAMPLES = [
         description: "After ajs dms build -b https://dms.example.com",
         command: "ajs dms start -b https://dms.example.com -p 3001",
     },
+    {
+        description: "From a build shipped with the project, in a read-only container",
+        command: "ajs dms start --workspace .dms-frontend -p 3000",
+    },
 ];
 function cmdStart() {
     const command = new commander_1.Command("start")
         .summary("Serve the production build")
-        .description("Serve the production frontend ajs dms build made for the same backend URL. Needs the DMS_SESSION_SECRET the build used.")
-        .addOption(config_1.Options.backendUrl("Backend URL the build was made for; required, as -b or the variable"))
+        .description("Serve the production frontend ajs dms build made for the same backend URL, or the one in --workspace. Reads DMS_SESSION_SECRET and the server's secrets (DMS_HTML_RENDER_SECRET, DMS_OAUTH_RELAY_SECRET) from its environment, and says once ready whether the backend still serves the modules the build was made from.")
+        .addOption(config_1.Options.backendUrl("Backend URL to serve; required, as -b or the variable, unless --workspace holds a build that records it"))
         .addOption(config_1.Options.port)
+        .addOption(config_1.Options.workspace("Serve the build in this directory (ajs dms build --workspace); start writes nothing into it"))
         .action(async (options) => (await Promise.resolve().then(() => __importStar(require("./start-action")))).runStart(options));
     return (0, cli_1.withExamples)(command, START_EXAMPLES);
 }

package/dist/config.d.ts

@@ -6,6 +6,7 @@ export declare const DMS_FRONTEND_HOME: string;
 export declare const DEPS_HASH_FILE = ".deps-hash";
 export declare const WORKSPACE_DIR_MODE = 448;
 export declare function writeSecretBearingFile(file: string, content: string): void;
+export declare function writeShareableFile(file: string, content: string): void;
 export declare const TEMPLATE_FILES: ReadonlyArray<readonly [string, string]>;
 export declare const LAYERS_SUBDIR = "frontend-modules";
 export declare const FRONTEND_MODULE_ENTRY = "dms.frontend.ts";
@@ -31,13 +32,14 @@ export declare const Options: {
     force(description: string): Option;
     offline(description: string): Option;
     strict: Option;
+    workspace(description: string): Option;
     bootstrapSecret(discovery?: string): Option;
 };
 export interface BootstrapDiscoveryOptions extends DiscoveryOptions {
     cwd?: string;
 }
 export declare function normalizeBootstrapSecret(value: string | undefined, source?: string): string | undefined;
-export type SessionSecretMode = "dev" | "build" | "start";
+export type SessionSecretMode = "dev" | "start";
 export declare function resolveSessionSecret(mode: SessionSecretMode, value?: string | undefined): string;
 export declare function resolveBootstrapSecret(explicit: string | undefined, backendUrl: string, options?: BootstrapDiscoveryOptions): string | undefined;
 export declare function sha256Hex(input: string): string;

package/dist/config.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Options = exports.UsageError = exports.TAILWIND_SOURCE_GLOB = exports.PNPM_LIFECYCLE_SCRIPTS = exports.layerCopyIgnore = exports.LAYER_COPY_BLOCKLIST = exports.PUBLIC_ENDPOINTS_FILE = exports.AUTH_ESTABLISH_FILE = exports.SERVER_OPTIONS_FILE = exports.SERVER_MODULE_ENTRY = exports.FRONTEND_BUILD_ENTRY = exports.FRONTEND_MODULE_ENTRY = exports.LAYERS_SUBDIR = exports.TEMPLATE_FILES = exports.WORKSPACE_DIR_MODE = exports.DEPS_HASH_FILE = exports.DMS_FRONTEND_HOME = void 0;
 exports.writeSecretBearingFile = writeSecretBearingFile;
+exports.writeShareableFile = writeShareableFile;
 exports.parseBackendUrl = parseBackendUrl;
 exports.requireBackendUrl = requireBackendUrl;
 exports.parsePort = parsePort;
@@ -30,9 +31,16 @@ const SECRET_BEARING_FILE_MODE = 0o600;
 const TEMP_FILE_SUFFIX = ".tmp";
 exports.WORKSPACE_DIR_MODE = 0o700;
 function writeSecretBearingFile(file, content) {
+    writeFileAtomically(file, content, SECRET_BEARING_FILE_MODE);
+}
+const SHAREABLE_FILE_MODE = 0o644;
+function writeShareableFile(file, content) {
+    writeFileAtomically(file, content, SHAREABLE_FILE_MODE);
+}
+function writeFileAtomically(file, content, mode) {
     const temp = `${file}.${process.pid}${TEMP_FILE_SUFFIX}`;
-    (0, node_fs_1.writeFileSync)(temp, content, { mode: SECRET_BEARING_FILE_MODE });
-    (0, node_fs_1.chmodSync)(temp, SECRET_BEARING_FILE_MODE);
+    (0, node_fs_1.writeFileSync)(temp, content, { mode });
+    (0, node_fs_1.chmodSync)(temp, mode);
     (0, node_fs_1.renameSync)(temp, file);
 }
 exports.TEMPLATE_FILES = [
@@ -174,6 +182,9 @@ exports.Options = {
         return new commander_1.Option("--offline", `${description} (env: DMS_OFFLINE)`);
     },
     strict: new commander_1.Option("--strict", "Exit 1 when the workspace cannot be prepared, and 2 when the backend URL is missing or invalid, instead of warning and exiting 0 (env: DMS_PREPARE_STRICT)"),
+    workspace(description) {
+        return new commander_1.Option("--workspace <dir>", description).env("DMS_WORKSPACE_DIR");
+    },
     bootstrapSecret(discovery) {
         return new commander_1.Option("--bootstrap-secret <secret>", discovery
             ? `${BOOTSTRAP_SECRET_DESCRIPTION}. ${discovery}`
@@ -226,7 +237,7 @@ function resolveSessionSecret(mode, value = process.env.DMS_SESSION_SECRET) {
         title: `DMS_SESSION_SECRET ${describeSessionSecret(value)}`,
         reason: mode === "dev"
             ? "dev generates an ephemeral secret only when the variable is not set at all."
-            : "build and start sign sessions with it, so it must stay the same across restarts.",
+            : "start signs sessions with it, so it must stay the same across restarts.",
         fixes: [
             "Create one: openssl rand -hex 32, then set it in the environment or ./.env",
         ],

package/dist/help.js

@@ -11,9 +11,10 @@ exports.ENVIRONMENT_VARIABLES = [
     ["DMS_BOOTSTRAP_SECRET", "Same as --bootstrap-secret"],
     [
         "DMS_SESSION_SECRET",
-        "Session key, 32 characters or more; build and start need one, dev makes one when unset",
+        "Session key, 32 characters or more; start needs one, dev makes one when unset",
     ],
     ["DMS_OFFLINE", "Same as --offline, unless 0, false, no or off"],
+    ["DMS_WORKSPACE_DIR", "Same as build and start --workspace"],
     ["DMS_PREPARE_STRICT", "Same as prepare --strict, read like DMS_OFFLINE"],
     ["PORT", "Same as -p"],
     [
@@ -38,11 +39,15 @@ exports.ENVIRONMENT_VARIABLES = [
     ],
     [
         "DMS_HTML_RENDER_SECRET",
-        "E-mail render secret, used when the backend publishes none in the manifest",
+        "E-mail render secret, the backend's htmlRender.serviceSecret; start needs it, a build keeps none",
     ],
     [
         "DMS_OAUTH_RELAY_SECRET",
-        "OAuth relay secret, used when the backend publishes none in the manifest",
+        "OAuth relay secret the backend expects; start needs it, a build keeps none",
+    ],
+    [
+        "DMS_PRIVATE_OPTIONS",
+        "Any module's private options for start, as JSON by module id; a build keeps none",
     ],
     [
         "DMS_AUTH_ESTABLISH_ENDPOINTS",

package/dist/index.js

@@ -8,6 +8,7 @@ const build_1 = require("./commands/build");
 const clean_1 = require("./commands/clean");
 const dev_1 = require("./commands/dev");
 const prepare_1 = require("./commands/prepare");
+const snapshot_1 = require("./commands/snapshot");
 const start_1 = require("./commands/start");
 const verify_source_1 = require("./commands/verify-source");
 const workspaces_1 = require("./commands/workspaces");
@@ -116,6 +117,7 @@ const runCLI = async () => {
     program.addCommand((0, dev_1.cmdDev)());
     program.addCommand((0, build_1.cmdBuild)());
     program.addCommand((0, start_1.cmdStart)());
+    program.addCommand((0, snapshot_1.cmdSnapshot)());
     program.addCommand((0, prepare_1.cmdPrepare)());
     program.addCommand((0, workspaces_1.cmdWorkspaces)());
     program.addCommand((0, clean_1.cmdClean)());

package/dist/manifest.d.ts

@@ -29,13 +29,19 @@ export interface ManifestCacheEntry {
     fetchedAt: string;
 }
 export declare function readCachedManifest(workspaceDir: string): ManifestCacheEntry | undefined;
+export declare function writeCachedManifest(workspaceDir: string, manifest: Manifest, privateValues: PrivateValues, fetchedAt?: string): void;
+export type PrivateValues = "keep" | "drop";
 export type ManifestCacheUse = "fallback" | "offline" | "never";
 export interface ResolvedManifest {
     manifest: Manifest;
     fromCache: boolean;
     fetchedAt?: string;
 }
-export declare function resolveManifest(workspaceDir: string, backendUrl: string, cacheUse: ManifestCacheUse, clientUrl?: string, bootstrapSecret?: string): Promise<ResolvedManifest>;
+export declare function resolveManifest(workspaceDir: string, backendUrl: string, cacheUse: ManifestCacheUse, { clientUrl, bootstrapSecret, privateValues, }?: {
+    clientUrl?: string;
+    bootstrapSecret?: string;
+    privateValues?: PrivateValues;
+}): Promise<ResolvedManifest>;
 export declare function assertCachedLayerPathsExist(modules: ServedWithPath[], fetchedAt?: string): void;
 export type ServedWithPath = ManifestModule & {
     path: string;

package/dist/manifest.js

@@ -7,12 +7,14 @@ exports.fetchFromBackend = fetchFromBackend;
 exports.describeManifestVersion = describeManifestVersion;
 exports.fetchManifest = fetchManifest;
 exports.readCachedManifest = readCachedManifest;
+exports.writeCachedManifest = writeCachedManifest;
 exports.resolveManifest = resolveManifest;
 exports.assertCachedLayerPathsExist = assertCachedLayerPathsExist;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const cli_1 = require("@antelopejs/core/cli");
 const config_1 = require("./config");
+const private_values_1 = require("./private-values");
 const output_1 = require("./output");
 const workspace_1 = require("./workspace");
 class ManifestUnauthorizedError extends cli_1.CliError {
@@ -215,18 +217,19 @@ function readCachedManifest(workspaceDir) {
         return undefined;
     }
 }
-function writeCachedManifest(workspaceDir, manifest) {
-    const entry = {
-        manifest,
-        fetchedAt: new Date().toISOString(),
-    };
-    (0, config_1.writeSecretBearingFile)((0, node_path_1.join)(workspaceDir, MANIFEST_CACHE_FILE), `${JSON.stringify(entry, null, 2)}\n`);
+function writeCachedManifest(workspaceDir, manifest, privateValues, fetchedAt = new Date().toISOString()) {
+    const entry = { manifest, fetchedAt };
+    const write = privateValues === "keep" ? config_1.writeSecretBearingFile : config_1.writeShareableFile;
+    write((0, node_path_1.join)(workspaceDir, MANIFEST_CACHE_FILE), `${JSON.stringify(entry, null, 2)}\n`);
 }
-async function resolveManifest(workspaceDir, backendUrl, cacheUse, clientUrl, bootstrapSecret) {
+async function resolveManifest(workspaceDir, backendUrl, cacheUse, { clientUrl, bootstrapSecret, privateValues = "keep", } = {}) {
     if (cacheUse !== "offline") {
         try {
-            const manifest = await fetchManifest(backendUrl, clientUrl, bootstrapSecret);
-            writeCachedManifest(workspaceDir, manifest);
+            const served = await fetchManifest(backendUrl, clientUrl, bootstrapSecret);
+            const manifest = privateValues === "keep"
+                ? served
+                : { ...served, modules: (0, private_values_1.withoutPrivateValues)(served.modules) };
+            writeCachedManifest(workspaceDir, manifest, privateValues);
             return { manifest, fromCache: false };
         }
         catch (err) {
@@ -239,13 +242,13 @@ async function resolveManifest(workspaceDir, backendUrl, cacheUse, clientUrl, bo
                 throw err;
             if (cacheUse === "never")
                 throw cacheNotUsed(err, backendUrl, cached);
-            return fromCachedEntry(cached);
+            return fromCachedEntry(workspaceDir, cached, privateValues);
         }
     }
     const cached = readCachedManifest(workspaceDir);
     if (!cached)
         throw new NoCachedManifestError();
-    return fromCachedEntry(cached);
+    return fromCachedEntry(workspaceDir, cached, privateValues);
 }
 function cacheNotUsed(failure, backendUrl, cached) {
     const problem = failure instanceof cli_1.CliError
@@ -261,12 +264,13 @@ function cacheNotUsed(failure, backendUrl, cached) {
         ],
     }, { cause: failure });
 }
-function fromCachedEntry(cached) {
-    return {
-        manifest: cached.manifest,
-        fromCache: true,
-        fetchedAt: cached.fetchedAt,
-    };
+function fromCachedEntry(workspaceDir, cached, privateValues) {
+    let { manifest } = cached;
+    if (privateValues === "drop") {
+        manifest = { ...manifest, modules: (0, private_values_1.withoutPrivateValues)(manifest.modules) };
+        writeCachedManifest(workspaceDir, manifest, "drop", cached.fetchedAt);
+    }
+    return { manifest, fromCache: true, fetchedAt: cached.fetchedAt };
 }
 function assertCachedLayerPathsExist(modules, fetchedAt) {
     const missing = modules.filter((mod) => !(0, node_fs_1.existsSync)(mod.path));

package/dist/materialize.js

@@ -114,11 +114,21 @@ function writePublicEndpoints(workspaceDir, layers) {
     };
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(workspaceDir, config_1.PUBLIC_ENDPOINTS_FILE), `${JSON.stringify(declared, null, 2)}\n`);
 }
+function holdsValue(value) {
+    if (typeof value === "string")
+        return value !== "";
+    if (value !== null && typeof value === "object")
+        return Object.values(value).some(holdsValue);
+    return false;
+}
 function writeServerOptions(workspaceDir, layers) {
     const modules = Object.fromEntries(layers.flatMap((layer) => layer.privateOptions
         ? [[(0, layers_1.getLayerSafeName)(layer), layer.privateOptions]]
         : []));
-    (0, config_1.writeSecretBearingFile)((0, node_path_1.join)(workspaceDir, config_1.SERVER_OPTIONS_FILE), `${JSON.stringify({ modules, environment: manifest_secrets_1.MANIFEST_SECRET_ENV }, null, 2)}\n`);
+    const write = Object.values(modules).some(holdsValue)
+        ? config_1.writeSecretBearingFile
+        : config_1.writeShareableFile;
+    write((0, node_path_1.join)(workspaceDir, config_1.SERVER_OPTIONS_FILE), `${JSON.stringify({ modules, environment: manifest_secrets_1.MANIFEST_SECRET_ENV }, null, 2)}\n`);
 }
 function writeFrontendModuleRegistry(workspaceDir, layers) {
     const registry = (0, derived_outputs_1.createFrontendModuleRegistry)(workspaceDir, layers);

package/dist/module-set.d.ts

@@ -14,3 +14,14 @@ export interface ModuleSetFollowOptions {
 export declare function moduleSetFingerprint(modules: readonly ModuleSetMember[]): string;
 export declare function followModuleSet(options: ModuleSetFollowOptions): () => void;
 export declare function reportFrontendReady(backendUrl: string, moduleNames: readonly string[], bootstrapSecret?: string): Promise<boolean>;
+export type BuildDrift = {
+    status: "matches";
+    served: string;
+} | {
+    status: "drifted";
+    served: string;
+} | {
+    status: "unknown";
+    reason: string;
+};
+export declare function compareWithBackend(backendUrl: string, builtDigest: string, digestOf: (modules: readonly ManifestModule[]) => string, bootstrapSecret?: string): Promise<BuildDrift>;

package/dist/module-set.js

@@ -4,6 +4,7 @@ exports.MODULE_SET_POLL_INTERVAL_MS = void 0;
 exports.moduleSetFingerprint = moduleSetFingerprint;
 exports.followModuleSet = followModuleSet;
 exports.reportFrontendReady = reportFrontendReady;
+exports.compareWithBackend = compareWithBackend;
 const manifest_1 = require("./manifest");
 const workspace_1 = require("./workspace");
 exports.MODULE_SET_POLL_INTERVAL_MS = 3000;
@@ -82,3 +83,20 @@ async function reportFrontendReady(backendUrl, moduleNames, bootstrapSecret) {
         return false;
     }
 }
+const DRIFT_CHECK_TIMEOUT_MS = 10_000;
+async function compareWithBackend(backendUrl, builtDigest, digestOf, bootstrapSecret) {
+    try {
+        const manifest = await Promise.race([
+            (0, manifest_1.fetchManifest)(backendUrl, undefined, bootstrapSecret),
+            new Promise((_resolve, reject) => setTimeout(() => reject(new Error("the backend did not answer in time")), DRIFT_CHECK_TIMEOUT_MS).unref()),
+        ]);
+        const served = digestOf(manifest.modules);
+        return { status: served === builtDigest ? "matches" : "drifted", served };
+    }
+    catch (error) {
+        return {
+            status: "unknown",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/private-values.d.ts

@@ -0,0 +1,9 @@
+import type { FrontendModuleOptions, ManifestModule } from "./workspace";
+export declare function withoutPrivateValues(modules: readonly ManifestModule[]): ManifestModule[];
+export declare const PRIVATE_OPTIONS_VARIABLE = "DMS_PRIVATE_OPTIONS";
+export interface UnfilledPrivateValue {
+    module: string;
+    path: string[];
+}
+export declare function parsePrivateOptions(raw: string | undefined): Record<string, FrontendModuleOptions>;
+export declare function unfilledPrivateValues(modules: Readonly<Record<string, FrontendModuleOptions>>, given: Readonly<Record<string, FrontendModuleOptions>>, covered: readonly (readonly string[])[]): UnfilledPrivateValue[];

package/dist/private-values.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRIVATE_OPTIONS_VARIABLE = void 0;
+exports.withoutPrivateValues = withoutPrivateValues;
+exports.parsePrivateOptions = parsePrivateOptions;
+exports.unfilledPrivateValues = unfilledPrivateValues;
+const config_1 = require("./config");
+function emptied(value) {
+    if (typeof value === "string")
+        return "";
+    if (Array.isArray(value))
+        return value.map(emptied);
+    if (value !== null && typeof value === "object")
+        return emptiedOptions(value);
+    return value;
+}
+function emptiedOptions(options) {
+    return Object.fromEntries(Object.entries(options).map(([key, value]) => [key, emptied(value)]));
+}
+function withoutPrivateValues(modules) {
+    return modules.map((module) => module.privateOptions
+        ? { ...module, privateOptions: emptiedOptions(module.privateOptions) }
+        : { ...module });
+}
+exports.PRIVATE_OPTIONS_VARIABLE = "DMS_PRIVATE_OPTIONS";
+function isOptions(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parsePrivateOptions(raw) {
+    if (!raw?.trim())
+        return {};
+    let given;
+    try {
+        given = JSON.parse(raw);
+    }
+    catch {
+        given = undefined;
+    }
+    if (!isOptions(given) || !Object.values(given).every(isOptions)) {
+        throw new config_1.UsageError({
+            title: `${exports.PRIVATE_OPTIONS_VARIABLE} is not a JSON object of options by module id`,
+            fixes: [
+                `Set it like ${exports.PRIVATE_OPTIONS_VARIABLE}='{"<module id>":{"<option>":"<value>"}}', with the ids of generated-server-options.json`,
+            ],
+        });
+    }
+    return given;
+}
+function readPath(options, path) {
+    let value = options;
+    for (const key of path) {
+        if (typeof value !== "object" || value === null)
+            return undefined;
+        if (!Object.prototype.hasOwnProperty.call(value, key))
+            return undefined;
+        value = value[key];
+    }
+    return value;
+}
+function* emptyStrings(value, path = []) {
+    if (value === "")
+        yield path;
+    else if (typeof value === "object" && value !== null)
+        for (const [key, child] of Object.entries(value))
+            yield* emptyStrings(child, [...path, key]);
+}
+function unfilledPrivateValues(modules, given, covered) {
+    const isCovered = (path) => covered.some((other) => other.length === path.length &&
+        other.every((key, index) => key === path[index]));
+    return Object.entries(modules).flatMap(([module, options]) => [...emptyStrings(options)]
+        .filter((path) => path.length > 0 && !isCovered(path))
+        .filter((path) => {
+        const value = readPath(given[module], path);
+        return typeof value !== "string" || value === "";
+    })
+        .map((path) => ({ module, path })));
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,25 @@
+import type { Manifest, ManifestModule } from "./workspace";
+export declare const SNAPSHOT_FILE = "snapshot.json";
+export declare const SNAPSHOT_LAYERS_DIR = "layers";
+export declare const BUILD_ORIGIN_FILE = ".build-origin.json";
+declare const SNAPSHOT_FORMAT = 1;
+export interface FrontendSnapshot {
+    format: typeof SNAPSHOT_FORMAT;
+    backendUrl: string;
+    takenAt: string;
+    digest: string;
+    manifest: Manifest;
+}
+export interface BuildOrigin {
+    source: "snapshot" | "backend";
+    backendUrl: string;
+    takenAt: string;
+    digest: string;
+    authenticated: boolean;
+}
+export declare function manifestDigest(modules: readonly ManifestModule[]): string;
+export declare function writeSnapshot(dir: string, backendUrl: string, manifest: Manifest, layersSource: string): FrontendSnapshot;
+export declare function readSnapshot(dir: string): FrontendSnapshot;
+export declare function writeBuildOrigin(workspaceDir: string, origin: BuildOrigin): void;
+export declare function readBuildOrigin(workspaceDir: string): BuildOrigin | undefined;
+export {};

package/dist/snapshot.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILD_ORIGIN_FILE = exports.SNAPSHOT_LAYERS_DIR = exports.SNAPSHOT_FILE = void 0;
+exports.manifestDigest = manifestDigest;
+exports.writeSnapshot = writeSnapshot;
+exports.readSnapshot = readSnapshot;
+exports.writeBuildOrigin = writeBuildOrigin;
+exports.readBuildOrigin = readBuildOrigin;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const cli_1 = require("@antelopejs/core/cli");
+const config_1 = require("./config");
+const module_set_1 = require("./module-set");
+const private_values_1 = require("./private-values");
+exports.SNAPSHOT_FILE = "snapshot.json";
+exports.SNAPSHOT_LAYERS_DIR = "layers";
+exports.BUILD_ORIGIN_FILE = ".build-origin.json";
+const SNAPSHOT_FORMAT = 1;
+const DIGEST_LENGTH = 16;
+function manifestDigest(modules) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update((0, module_set_1.moduleSetFingerprint)(modules.map(({ path: _path, ...module }) => module)))
+        .digest("hex")
+        .slice(0, DIGEST_LENGTH);
+}
+function writeSnapshot(dir, backendUrl, manifest, layersSource) {
+    const modules = (0, private_values_1.withoutPrivateValues)(manifest.modules).map(({ path: _path, ...module }) => module);
+    const snapshot = {
+        format: SNAPSHOT_FORMAT,
+        backendUrl: (0, config_1.canonicalizeBackendUrl)(backendUrl),
+        takenAt: new Date().toISOString(),
+        digest: manifestDigest(modules),
+        manifest: { pack: manifest.pack, modules },
+    };
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const layers = (0, node_path_1.join)(dir, exports.SNAPSHOT_LAYERS_DIR);
+    (0, node_fs_1.rmSync)(layers, { recursive: true, force: true });
+    (0, node_fs_1.cpSync)(layersSource, layers, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, exports.SNAPSHOT_FILE), `${JSON.stringify(snapshot, null, 2)}\n`);
+    return snapshot;
+}
+function readSnapshot(dir) {
+    const file = (0, node_path_1.join)(dir, exports.SNAPSHOT_FILE);
+    const refresh = "Take one: ajs dms snapshot -b <backend url> -o <dir>";
+    if (!(0, node_fs_1.existsSync)(file)) {
+        throw new cli_1.CliError({
+            title: `No snapshot in ${dir}`,
+            reason: `${exports.SNAPSHOT_FILE} is missing.`,
+            fixes: [refresh],
+        });
+    }
+    let snapshot;
+    try {
+        snapshot = JSON.parse((0, node_fs_1.readFileSync)(file, "utf8"));
+    }
+    catch (error) {
+        throw new cli_1.CliError({ title: `${file} is not valid JSON`, fixes: [refresh] }, { cause: error });
+    }
+    if (snapshot.format !== SNAPSHOT_FORMAT ||
+        !Array.isArray(snapshot.manifest?.modules) ||
+        typeof snapshot.backendUrl !== "string") {
+        throw new cli_1.CliError({
+            title: `${file} is not a snapshot this loader can build from`,
+            reason: `It needs format ${SNAPSHOT_FORMAT}, a backend URL and a manifest.`,
+            fixes: [refresh],
+        });
+    }
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(dir, exports.SNAPSHOT_LAYERS_DIR))) {
+        throw new cli_1.CliError({
+            title: `The snapshot in ${dir} has no ${exports.SNAPSHOT_LAYERS_DIR} directory`,
+            fixes: [refresh],
+        });
+    }
+    return snapshot;
+}
+function writeBuildOrigin(workspaceDir, origin) {
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(workspaceDir, exports.BUILD_ORIGIN_FILE), `${JSON.stringify(origin, null, 2)}\n`);
+}
+function readBuildOrigin(workspaceDir) {
+    try {
+        const origin = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(workspaceDir, exports.BUILD_ORIGIN_FILE), "utf8"));
+        return typeof origin.digest === "string"
+            ? origin
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/workspace-setup.d.ts

@@ -2,6 +2,7 @@ import { type ChildProcess, type SpawnOptions } from "node:child_process";
 import { type PathMapper } from "./child-output";
 import { type ManifestSecrets } from "./manifest-secrets";
 import { ResolvedLayer } from "./workspace";
+import { type BuildOrigin, type FrontendSnapshot } from "./snapshot";
 export declare function computeDepsHash(layerPaths: string[], workspacePackage?: string, installInputs?: readonly string[]): string;
 export declare function needsInstall(workspaceDir: string, layerPaths: string[], force: boolean): boolean;
 export declare function saveDepsHash(workspaceDir: string, layerPaths: string[]): void;
@@ -27,6 +28,11 @@ export interface SetupWorkspaceOptions {
     clientUrl?: string;
     workspaceKey?: string;
     bootstrapSecret?: string;
+    workspaceDir?: string;
+    snapshot?: {
+        dir: string;
+        snapshot: FrontendSnapshot;
+    };
     beforeInstall?: () => Promise<void>;
 }
 export interface SetupWorkspaceResult {
@@ -35,5 +41,6 @@ export interface SetupWorkspaceResult {
     manifestFromCache: boolean;
     manifestFetchedAt?: string;
     manifestSecrets: ManifestSecrets;
+    buildOrigin: BuildOrigin;
 }
 export declare function setupWorkspace(opts: SetupWorkspaceOptions): Promise<SetupWorkspaceResult>;

package/dist/workspace-setup.js

@@ -19,6 +19,7 @@ const manifest_secrets_1 = require("./manifest-secrets");
 const renderer_range_1 = require("./renderer-range");
 const materialize_1 = require("./materialize");
 const workspace_1 = require("./workspace");
+const snapshot_1 = require("./snapshot");
 const cancellation_1 = require("./cancellation");
 const output_1 = require("./output");
 const config_1 = require("./config");
@@ -219,14 +220,25 @@ function manifestCacheUse(mode, offline) {
         return "offline";
     return mode === "build" ? "never" : "fallback";
 }
-async function setupWorkspace(opts) {
+async function snapshotLayers({ dir, snapshot }, workspaceDir) {
+    const { manifest, takenAt } = snapshot;
+    const cacheDir = (0, node_path_1.join)(dir, snapshot_1.SNAPSHOT_LAYERS_DIR);
+    (0, layers_1.assertCachedArchivesExist)(manifest.modules, cacheDir, takenAt);
+    (0, manifest_1.writeCachedManifest)(workspaceDir, manifest, "drop", takenAt);
+    return {
+        manifest,
+        fromCache: false,
+        layers: await (0, layers_1.buildLayersFromCache)(manifest.modules, cacheDir),
+    };
+}
+async function servedLayers(opts, workspaceDir) {
     const { backendUrl, force, mode, offline, clientUrl, bootstrapSecret } = opts;
-    const workspaceKey = opts.workspaceKey ?? (0, config_1.canonicalizeBackendUrl)(backendUrl);
-    const workspaceDir = (0, workspace_1.ensureWorkspace)(workspaceKey);
-    (0, workspace_1.writeWorkspaceMeta)(workspaceDir, backendUrl, workspaceKey);
-    const resolved = await (0, manifest_1.resolveManifest)(workspaceDir, backendUrl, manifestCacheUse(mode, offline), clientUrl, bootstrapSecret);
+    const resolved = await (0, manifest_1.resolveManifest)(workspaceDir, backendUrl, manifestCacheUse(mode, offline), {
+        clientUrl,
+        bootstrapSecret,
+        privateValues: mode === "build" ? "drop" : "keep",
+    });
     const { manifest, fromCache, fetchedAt } = resolved;
-    let layers;
     if (mode === "dev") {
         (0, layers_1.assertLayerPathsServed)(manifest.modules, backendUrl, {
             bootstrapSecret,
@@ -235,26 +247,45 @@ async function setupWorkspace(opts) {
         if (fromCache) {
             (0, manifest_1.assertCachedLayerPathsExist)(manifest.modules, fetchedAt);
         }
-        layers = (0, layers_1.buildLayersFromPaths)(manifest.modules);
+        return { ...resolved, layers: (0, layers_1.buildLayersFromPaths)(manifest.modules) };
     }
-    else {
-        const cacheDir = (0, node_path_1.join)(workspaceDir, ".layers-cache");
-        if (fromCache) {
-            if (!(0, node_fs_1.existsSync)(cacheDir)) {
-                throw new cli_1.CliError({
-                    title: "No layers archive was downloaded for this workspace",
-                    fixes: [
-                        "Run once without --offline, with the backend reachable, first",
-                    ],
-                });
-            }
-            (0, layers_1.assertCachedArchivesExist)(manifest.modules, cacheDir, fetchedAt);
+    const cacheDir = (0, node_path_1.join)(workspaceDir, ".layers-cache");
+    if (fromCache) {
+        if (!(0, node_fs_1.existsSync)(cacheDir)) {
+            throw new cli_1.CliError({
+                title: "No layers archive was downloaded for this workspace",
+                fixes: [
+                    "Run once without --offline, with the backend reachable, first",
+                ],
+            });
         }
-        else {
-            await (0, layers_1.downloadAndExtractLayers)(backendUrl, manifest.pack, cacheDir, force, bootstrapSecret);
-        }
-        layers = await (0, layers_1.buildLayersFromCache)(manifest.modules, cacheDir);
+        (0, layers_1.assertCachedArchivesExist)(manifest.modules, cacheDir, fetchedAt);
+    }
+    else {
+        await (0, layers_1.downloadAndExtractLayers)(backendUrl, manifest.pack, cacheDir, force, bootstrapSecret);
     }
+    return {
+        ...resolved,
+        layers: await (0, layers_1.buildLayersFromCache)(manifest.modules, cacheDir),
+    };
+}
+async function setupWorkspace(opts) {
+    const { backendUrl, force } = opts;
+    const workspaceKey = opts.workspaceKey ?? (0, config_1.canonicalizeBackendUrl)(backendUrl);
+    const workspaceDir = opts.workspaceDir
+        ? (0, workspace_1.ensureExplicitWorkspace)(opts.workspaceDir)
+        : (0, workspace_1.ensureWorkspace)(workspaceKey);
+    (0, workspace_1.writeWorkspaceMeta)(workspaceDir, backendUrl, workspaceKey);
+    const { manifest, fromCache, fetchedAt, layers } = opts.snapshot
+        ? await snapshotLayers(opts.snapshot, workspaceDir)
+        : await servedLayers(opts, workspaceDir);
+    const buildOrigin = {
+        source: opts.snapshot ? "snapshot" : "backend",
+        backendUrl: (0, config_1.canonicalizeBackendUrl)(backendUrl),
+        takenAt: opts.snapshot?.snapshot.takenAt ?? fetchedAt ?? new Date().toISOString(),
+        digest: (0, snapshot_1.manifestDigest)(manifest.modules),
+        authenticated: !!opts.snapshot || (!!opts.bootstrapSecret && !fromCache),
+    };
     (0, renderer_range_1.assertLayersSupportRenderer)(layers, { workspaceDir });
     (0, materialize_1.copyStaticTemplates)(workspaceDir);
     (0, materialize_1.writeWorkspacePackageJson)(workspaceDir, layers);
@@ -274,5 +305,6 @@ async function setupWorkspace(opts) {
         manifestFromCache: fromCache,
         manifestFetchedAt: fetchedAt,
         manifestSecrets: (0, manifest_secrets_1.collectManifestSecrets)(manifest.modules),
+        buildOrigin,
     };
 }

package/dist/workspace.d.ts

@@ -56,6 +56,7 @@ export declare function projectWorkspaceKey(projectDir: string): string;
 export declare function projectDirFromWorkspaceKey(workspaceKey: string | undefined): string | undefined;
 export declare function getWorkspaceDir(backendUrl: string): string;
 export declare function ensureWorkspace(workspaceKey: string): string;
+export declare function ensureExplicitWorkspace(dir: string): string;
 export interface WorkspaceEntry {
     dir: string;
     backendUrl: string;

package/dist/workspace.js

@@ -6,6 +6,7 @@ exports.projectWorkspaceKey = projectWorkspaceKey;
 exports.projectDirFromWorkspaceKey = projectDirFromWorkspaceKey;
 exports.getWorkspaceDir = getWorkspaceDir;
 exports.ensureWorkspace = ensureWorkspace;
+exports.ensureExplicitWorkspace = ensureExplicitWorkspace;
 exports.listWorkspaces = listWorkspaces;
 exports.directorySize = directorySize;
 exports.writeWorkspaceMeta = writeWorkspaceMeta;
@@ -38,6 +39,11 @@ function ensureWorkspace(workspaceKey) {
     (0, node_fs_1.chmodSync)(dir, config_1.WORKSPACE_DIR_MODE);
     return dir;
 }
+function ensureExplicitWorkspace(dir) {
+    const absolute = (0, node_path_1.resolve)(dir);
+    (0, node_fs_1.mkdirSync)(absolute, { recursive: true });
+    return absolute;
+}
 function listWorkspaces() {
     const listing = { workspaces: [], skipped: [] };
     if (!(0, node_fs_1.existsSync)(config_1.DMS_FRONTEND_HOME))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",

package/templates/vue/server/module-server.mjs

@@ -49,15 +49,33 @@ function readJsonFile(url, fallback) {
   }
 }
 
-/** Sets `value` at `path` when the object holding it exists but lacks it. */
-function fillPath(target, path, value) {
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** The object holding `path`'s last key, when every key up to it is own. */
+function holderOf(target, path) {
   let node = target;
   for (const key of path.slice(0, -1)) {
-    if (typeof node[key] !== "object" || node[key] === null) return;
+    if (UNSAFE_KEYS.has(key) || !Object.hasOwn(node, key)) return undefined;
     node = node[key];
+    if (typeof node !== "object" || node === null) return undefined;
   }
+  return UNSAFE_KEYS.has(path.at(-1)) ? undefined : node;
+}
+
+/** Sets `value` at `path` when the object holding it exists but lacks it. */
+function fillPath(target, path, value) {
+  const holder = holderOf(target, path);
+  const key = path.at(-1);
+  if (holder && (holder[key] === undefined || holder[key] === ""))
+    holder[key] = value;
+}
+
+/** Sets `value` at `path` only where the build left an empty string. */
+function fillEmptied(target, path, value) {
+  const holder = holderOf(target, path);
   const key = path.at(-1);
-  if (typeof node[key] !== "string" || node[key] === "") node[key] = value;
+  if (holder && Object.hasOwn(holder, key) && holder[key] === "")
+    holder[key] = value;
 }
 
 /**
@@ -77,12 +95,56 @@ export function privateOptionsWithFallbacks(modules, environment, env) {
   return modules;
 }
 
+/** Each string leaf of `value`, array items included, with its path. */
+function* stringLeaves(value, path = []) {
+  if (typeof value === "string") yield [path, value];
+  else if (typeof value === "object" && value !== null)
+    for (const [key, child] of Object.entries(value))
+      yield* stringLeaves(child, [...path, key]);
+}
+
+/**
+ * Fills the private values a build left empty from `DMS_PRIVATE_OPTIONS`, a
+ * JSON object of private options by module id
+ * (`{"acme__shop-frontend-vue":{"apiKey":"…"}}`): any module's secrets, where
+ * `DMS_HTML_RENDER_SECRET` and `DMS_OAUTH_RELAY_SECRET` name two of them. Only
+ * a value the build emptied is filled, array items included: a value the
+ * manifest carries wins, and no option or section is added or replaced.
+ *
+ * @param modules The private options by module id
+ * @param json The variable's value; nothing is filled when unset
+ * @param warn Reports a value that is not a JSON object, never its content
+ */
+export function privateOptionsFromJson(modules, json, warn) {
+  if (!json) return modules;
+  let given;
+  try {
+    given = JSON.parse(json);
+  } catch {
+    given = undefined;
+  }
+  if (typeof given !== "object" || given === null || Array.isArray(given)) {
+    warn("DMS_PRIVATE_OPTIONS is not a JSON object of options by module id");
+    return modules;
+  }
+  for (const [id, options] of Object.entries(given)) {
+    if (UNSAFE_KEYS.has(id) || !Object.hasOwn(modules, id)) continue;
+    for (const [path, value] of stringLeaves(options))
+      if (path.length > 0) fillEmptied(modules[id], path, value);
+  }
+  return modules;
+}
+
 function readPrivateOptions(env = process.env) {
   const { modules = {}, environment = {} } = readJsonFile(
     SERVER_OPTIONS_FILE,
     {},
   );
-  return privateOptionsWithFallbacks(modules, environment, env);
+  return privateOptionsFromJson(
+    privateOptionsWithFallbacks(modules, environment, env),
+    env.DMS_PRIVATE_OPTIONS,
+    (message) => console.warn(message),
+  );
 }
 
 function readPublicOptions() {