@maka/meteor-sdk 0.2.12 → 0.2.13

package/README.md

@@ -70,13 +70,44 @@ output), the same output `meteor build` produces.
 ```js
 await sdk.bundle(project, {
   outputPath: "/path/to/output",
-  minifyMode: "production", // default; real minification, can take
-                             // multiple minutes and multiple GB of RAM
-                             // for a cold build -- pass "development"
-                             // for a fast smoke build
+  minifyMode: "production", // DEFAULT IS "development" -- pass
+                            // "production" explicitly for deploys.
+                            // Real minification can take minutes and
+                            // multiple GB of RAM on a cold build.
+  buildMode: "production",  // default; also "development"/"test"
+  serverArch: undefined,    // default: the build host's arch
+  webArchs: undefined,      // default: the project's platform list
+  programs: "all",          // "all" (default) | "server" | "client"
 });
 ```
 
+#### Split server/client bundles (`programs`)
+
+`programs: "server"` writes a bundle with no client programs whose
+`programs/server/config.json` still records the *intended*
+`clientArchs`. It boots normally and serves pages with 404 until the
+client programs exist -- webapp logs a note per reload and starts
+serving the moment they appear (process restart, or `SIGHUP`, which
+autoupdate already wires to a client-program reload plus a hot-code
+push to connected browsers).
+
+`programs: "client"` writes a standalone client artifact: a `star.json`
+listing only the web programs plus `programs/<arch>/` trees that are
+byte-identical to a full bundle's -- so they are drop-in *siblings* for
+a server bundle. Copy `programs/<arch>` into the server bundle's
+`programs/` directory (never untar the client artifact wholesale over a
+server bundle: its root `star.json` would clobber the server's), or
+point the server at an external location with
+`METEOR_CLIENT_BUNDLE_DIR=/path/to/client-artifact/programs` (honored
+by both webapp's static serving and dynamic `import()`).
+
+Swap discipline for live servers: activate a new client release with an
+**atomic symlink flip**, never by copying into the live directory -- a
+half-written `program.json` observed by a reload is a fatal error by
+design. Client-only deploys are for client-safe changes; anything
+touching methods, publications or schemas ships server-first or as a
+full bundle.
+
 ### `createAppRunner(project, options)`
 
 Runs an app the way `meteor run` does, with a stoppable handle instead of
@@ -281,8 +312,10 @@ why) if you ever need to diagnose unexpected rebuilds.
   springboarding/multi-release-per-process.** Out of scope for this SDK.
 - **`createAppRunner()`/`testRun()` don't manage a Mongo process** -- bring
   your own `mongoUrl`.
-- **`bundle()`'s default `minifyMode: "production"` is slow** -- pass
-  `"development"` for fast iteration.
+- **`bundle()` defaults to `minifyMode: "development"`** (fast, no real
+  minification) -- deploys must pass `"production"` explicitly, and that
+  mode is legitimately slow on a cold build. (Earlier revisions of this
+  README claimed production was the default; the code never agreed.)
 - A rare, environment-specific gap, out of scope for this package to
   fix: a from-scratch install can hit an npm/Windows spawn issue when a
   dependency needs a native rebuild for the first time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/meteor-sdk",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Programmatic Node API over the Meteor build tool (bundle/run/create/etc.) -- for driving Meteor's build system from plain Node code instead of shelling out to a meteor CLI (there isn't one anymore; see README.md). \"dependencies\" is generated by scripts/write-tool-package-json.js from scripts/dev-bundle-tool-package.js at the monorepo root -- do not hand-edit that field, edit that file and re-run the script instead.",
   "main": "src/index.js",
   "exports": {
@@ -25,7 +25,7 @@
   "scripts": {
     "prepack": "node scripts/prepack.js",
     "build": "node scripts/prepack.js",
-    "test": "node --test --test-force-exit --test-concurrency=1 test/exports-map.test.js test/ddp.test.js test/test-run.test.js test/errors.test.js test/load-project.test.js test/bundle.test.js test/create.test.js test/close.test.js test/fiber-stubs.test.js test/esm-passthrough.test.js"
+    "test": "node --test --test-force-exit --test-concurrency=1 test/exports-map.test.js test/ddp.test.js test/test-run.test.js test/errors.test.js test/load-project.test.js test/bundle.test.js test/bundle-split.test.js test/create.test.js test/close.test.js test/fiber-stubs.test.js test/esm-passthrough.test.js"
   },
   "repository": {
     "type": "git",

package/packages/webapp/webapp_server.js

@@ -903,6 +903,18 @@ async function runWebAppServer() {
         clientArchs.forEach(arch => {
           generateClientProgram(arch, staticFilesByArch);
         });
+        // A configured arch with no program on disk is legal (split
+        // server/client deploy: the client artifact hasn't landed yet)
+        // but silent was wrong -- say so once per reload so an operator
+        // can tell "not deployed yet" from "deployed to the wrong path".
+        clientArchs
+          .filter(arch => !(arch in staticFilesByArch))
+          .forEach(arch => {
+            Log.info(
+              'webapp: no client program for ' + arch + ' yet; ' +
+              'serving begins when it appears (restart or SIGHUP).'
+            );
+          });
         WebAppInternals.staticFilesByArch = staticFilesByArch;
       } catch (e) {
         Log.error('Error reloading the client program: ' + e.stack);
@@ -940,8 +952,17 @@ async function runWebAppServer() {
     arch,
     staticFilesByArch = WebAppInternals.staticFilesByArch
   ) {
+    // METEOR_CLIENT_BUNDLE_DIR relocates the client programs for split
+    // server/client deploys (a directory holding <arch>/ program dirs);
+    // default is the classic sibling layout. Keep in sync with boot.js's
+    // dynamic-import root, which honors the same variable -- and note
+    // the ENOENT return below is a FEATURE the split relies on: a
+    // server-only bundle boots with clientArchs recorded as intent and
+    // starts serving the moment the client artifact lands (restart, or
+    // SIGHUP via autoupdate's enqueueVersionsRefresh).
     const clientDir = pathJoin(
-      pathDirname(__meteor_bootstrap__.serverDir),
+      process.env.METEOR_CLIENT_BUNDLE_DIR ||
+        pathDirname(__meteor_bootstrap__.serverDir),
       arch
     );
 

package/src/bundle.js

@@ -25,6 +25,19 @@ async function bundle(project, options) {
     throw new MeteorSdkError("bundle() requires options.outputPath");
   }
 
+  // Validate BEFORE the expensive build, same spirit as the outputPath
+  // check above. 'server' writes a bundle without client programs whose
+  // config.json still records the intended clientArchs; 'client' writes
+  // a standalone client-only star (no server program, no main.js) whose
+  // programs/<arch> trees are drop-in siblings for a server bundle.
+  const programs = options.programs || "all";
+  if (!["all", "server", "client"].includes(programs)) {
+    throw new MeteorSdkError(
+      "bundle() options.programs must be 'all', 'server' or 'client' " +
+        "(got " + JSON.stringify(options.programs) + ")"
+    );
+  }
+
   const bundler = require("../tools/isobuild/bundler.js");
 
   const result = await bundler.bundle({
@@ -35,6 +48,7 @@ async function bundle(project, options) {
       buildMode: options.buildMode || "production",
       serverArch: options.serverArch,
       webArchs: options.webArchs,
+      programs,
     },
   });
 

package/tools/isobuild/bundler.js

@@ -3300,6 +3300,12 @@ Find out more about Meteor at meteor.com.
  *     of debugOnly, prodOnly and testOnly packages, default 'production'
  *   - webArchs: array of 'web.*' options to build (defaults to
  *     projectContext.platformList.getWebArchs())
+ *   - programs: 'all' (default), 'server' or 'client'. 'server' writes a
+ *     bundle without client programs whose config.json still records the
+ *     intended clientArchs (webapp serves them when the client artifact
+ *     arrives at the sibling path); 'client' writes a standalone
+ *     client-only star -- programs/<arch> trees byte-identical to a full
+ *     bundle's, no server program, no main.js.
  *   - warnings: a MessageSet of linting messages or null if linting
  *     wasn't performed at all (either disabled or lack of linters).
  *
@@ -3364,6 +3370,16 @@ async function bundle({
   }
   const minifyMode = buildOptions.minifyMode || 'development';
   const buildMode = buildOptions.buildMode || 'production';
+  // Which programs to build and write: 'all' (default), 'server' (skip
+  // the client targets but still record the INTENDED clientArchs in
+  // programs/server/config.json, so webapp serves them once the client
+  // artifact arrives -- missing-at-boot is already tolerated, see
+  // webapp_server.js generateClientProgram's ENOENT path), or 'client'
+  // (skip the server target; writeSiteArchive already gates main.js,
+  // README and config.json on targets.server, so the client-only
+  // artifact falls out honest: a star.json listing only web archs plus
+  // programs/<arch>/ trees byte-identical to a full bundle's).
+  const programs = buildOptions.programs || 'all';
 
   var releaseName =
     release.current.isCheckout() ? "none" : release.current.name;
@@ -3389,6 +3405,11 @@ async function bundle({
     throw new Error('Unrecognized build mode: ' + buildMode);
   }
 
+  if (! ['all', 'server', 'client'].includes(programs)) {
+    throw new Error('Unrecognized programs selection: ' + programs +
+                    " (expected 'all', 'server' or 'client')");
+  }
+
   var messages = await buildmessage.capture({
     title: "building the application"
   }, async function () {
@@ -3520,13 +3541,25 @@ async function bundle({
       previousBuilders[arch] = written.builder;
     }
 
-    // Client
-    for (const arch of webArchs) {
-      targets[arch] = await makeClientTarget(app, arch, {minifiers});
+    // Client. Skipped entirely for a server-only build -- but note
+    // webArchs itself is NOT emptied: makeServerTarget below still
+    // receives the full list, so programs/server/config.json records
+    // the INTENDED clientArchs and the server will serve those programs
+    // the moment the separately-deployed client artifact appears at the
+    // sibling path (webapp tolerates missing-at-boot; ENOENT skip in
+    // generateClientProgram).
+    if (programs !== 'server') {
+      for (const arch of webArchs) {
+        targets[arch] = await makeClientTarget(app, arch, {minifiers});
+      }
     }
 
-    // Server
-    if (! hasCachedBundle) {
+    // Server. Skipped for a client-only build: writeSiteArchive already
+    // gates main.js/README/config.json on targets.server, so the
+    // resulting artifact is an honest client-only star -- programs list
+    // holds only web archs, and the program dirs are byte-identical to
+    // a full bundle's (drop-in compatible as siblings).
+    if (! hasCachedBundle && programs !== 'client') {
       targets.server = await makeServerTarget(app, webArchs);
     }
 

package/tools/static-assets/server/boot.js

@@ -207,9 +207,18 @@ var specialArgPaths = {
     var clientArchs = configJson.clientArchs ||
       Object.keys(configJson.clientPaths);
 
+    // METEOR_CLIENT_BUNDLE_DIR relocates the CLIENT programs (split
+    // server/client deploys -- a directory containing <arch>/ program
+    // dirs). Must agree with webapp_server.js's generateClientProgram,
+    // which honors the same variable: dynamic-import fetches modules
+    // from disk independently of webapp's static file map, so missing
+    // this one silently breaks import() while pages still serve.
+    var clientProgramsDir =
+      process.env.METEOR_CLIENT_BUNDLE_DIR || programsDir;
+
     clientArchs.forEach(function (arch) {
       dynamicImportInfo[arch] = {
-        dynamicRoot: path.join(programsDir, arch, "dynamic")
+        dynamicRoot: path.join(clientProgramsDir, arch, "dynamic")
       };
     });