@lark-apaas/fullstack-cli 1.1.66-alpha.20260902192310 → 1.1.66-alpha.20260903130240

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-cli",
-  "version": "1.1.66-alpha.20260902192310",
+  "version": "1.1.66-alpha.20260903130240",
   "description": "CLI tool for fullstack template management",
   "type": "module",
   "main": "dist/index.js",

package/templates/scripts/dev.js

@@ -931,7 +931,11 @@ async function main() {
     initializeActionPlugins();
   }
 
-  // Start server and client
+  // Client startup never waits for the source Nest process. With a verified
+  // handoff owner, the image runtime already serves port 3000 and owns the
+  // delayed source lifecycle; dev.js starts only Vite and watches that owner.
+  // Without that receipt this block keeps the legacy ownership model: start
+  // source Nest and Vite together.
   const serverPromise = handoffOwnsBackend
     ? Promise.resolve()
     : startProcess({

package/templates/scripts/server-handoff-runtime.mjs

@@ -8,6 +8,15 @@ import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
+// Restore-time state machine:
+//   validate immutable generation -> start cached Nest -> bind public proxy
+//   -> publish owner -> serve the first HTML response
+//   -> wait a fixed 15s -> start source Nest in the background
+//   -> switch only after source readiness, then drain/stop the cache.
+// Source startup is therefore outside the first-screen critical path. The
+// browser's MiaodaPreviewRendered event is observability only and is not a
+// control-plane input. A failed source start terminates the handoff runtime so
+// the backend immediately returns to the legacy startup-failure lifecycle.
 const SCHEMA_VERSION = 7;
 const BUNDLE_ENTRY = 'payload/server.bundle.cjs';
 const MAX_GENERATION_FILES = 50_000;
@@ -16,8 +25,8 @@ const MAX_GENERATION_FILE_BYTES = 64 * 1024 * 1024;
 const MAX_FILE_INDEX_BYTES = 16 * 1024 * 1024;
 const MAX_MANIFEST_BYTES = 1024 * 1024;
 const MAX_READINESS_RESPONSE_BYTES = 64 * 1024;
-const SOURCE_RETRY_INITIAL_DELAY_MS = 250;
-const SOURCE_RETRY_MAX_DELAY_MS = 5_000;
+const DEFAULT_SOURCE_START_DELAY_MS = 15_000;
+const TEST_SOURCE_START_DELAY_ARG = '--miaoda-test-source-start-delay-ms=';
 const RUNTIME_CONTROL_ENV_KEYS = new Set([
   'MIAODA_COLD_START_DECISION_FILE',
   'MIAODA_DEPENDENCY_READY_FILE',
@@ -91,6 +100,7 @@ const shutdownTimeoutMs = positiveDuration(
   5_000
 );
 const drainTimeoutMs = positiveDuration('MIAODA_NEST_DRAIN_TIMEOUT_MS', 5_000);
+const sourceStartDelayMs = sourceStartDelayForRuntime();
 const processStartTicks =
   readLinuxProcessStartTicks(process.pid) ||
   String(
@@ -221,12 +231,32 @@ let resolveLifetime;
 const lifetime = new Promise(resolve => {
   resolveLifetime = resolve;
 });
+let firstHtmlTransferredAtMs = 0;
+let resolveFirstHtmlTransferred;
+const firstHtmlTransferred = new Promise(resolve => {
+  resolveFirstHtmlTransferred = resolve;
+});
 
 function positiveDuration(name, fallback) {
   const value = Number(process.env[name] || fallback);
   return Number.isFinite(value) && value > 0 ? value : fallback;
 }
 
+function sourceStartDelayForRuntime() {
+  // Production starts this file without extra argv, so the delay is fixed.
+  // The explicit argument exists only to keep integration tests fast and
+  // deterministic; inherited workspace environment cannot shorten the delay.
+  const testArgument = process.argv
+    .slice(2)
+    .find(argument => argument.startsWith(TEST_SOURCE_START_DELAY_ARG));
+  if (!testArgument) return DEFAULT_SOURCE_START_DELAY_MS;
+  const value = Number(testArgument.slice(TEST_SOURCE_START_DELAY_ARG.length));
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error('MIAODA_NEST_TEST_SOURCE_START_DELAY_INVALID');
+  }
+  return value;
+}
+
 function validateRuntimeConfiguration() {
   if (process.env.MIAODA_NEST_BUNDLE_HANDOFF_ENABLED !== 'true') {
     throw new Error('MIAODA_NEST_BUNDLE_HANDOFF_DISABLED');
@@ -898,7 +928,11 @@ function waitForHttp(
           if (response.statusCode !== 200) {
             attemptSettled = true;
             response.resume();
-            retry();
+            finish(
+              new Error(
+                `${record.name} HTTP readiness rejected with status ${response.statusCode}`
+              )
+            );
             return;
           }
           const chunks = [];
@@ -910,7 +944,9 @@ function waitForHttp(
             if (responseBytes > MAX_READINESS_RESPONSE_BYTES) {
               attemptSettled = true;
               response.destroy();
-              retry();
+              finish(
+                new Error(`${record.name} HTTP readiness response too large`)
+              );
               return;
             }
             chunks.push(buffer);
@@ -925,7 +961,10 @@ function waitForHttp(
               )
             )
               finish();
-            else retry();
+            else
+              finish(
+                new Error(`${record.name} HTTP readiness payload rejected`)
+              );
           });
           response.once('error', () => {
             if (attemptSettled || settled) return;
@@ -964,6 +1003,36 @@ function retain(upstream) {
   };
 }
 
+function observeFirstCacheHtmlTransfer(request, response, upstreamResponse) {
+  if (
+    firstHtmlTransferredAtMs ||
+    request.method !== 'GET' ||
+    activeUpstream !== cacheUpstream ||
+    upstreamResponse.statusCode < 200 ||
+    upstreamResponse.statusCode >= 400 ||
+    !String(upstreamResponse.headers['content-type'] || '')
+      .toLowerCase()
+      .startsWith('text/html')
+  ) {
+    return;
+  }
+  response.once('finish', () => {
+    if (firstHtmlTransferredAtMs) return;
+    firstHtmlTransferredAtMs = Date.now();
+    resolveFirstHtmlTransferred(firstHtmlTransferredAtMs);
+    process.stderr.write(
+      `${JSON.stringify({
+        event: 'miaoda_nest_html_transferred',
+        bootId,
+        generationId: currentGenerationId,
+        sourceStartDelayMs,
+        atMs: firstHtmlTransferredAtMs,
+        elapsedMs: firstHtmlTransferredAtMs - restoreEpochMs,
+      })}\n`
+    );
+  });
+}
+
 function createProxy() {
   const server = http.createServer((request, response) => {
     const upstream = activeUpstream;
@@ -982,6 +1051,7 @@ function createProxy() {
         headers: request.headers,
       },
       upstreamResponse => {
+        observeFirstCacheHtmlTransfer(request, response, upstreamResponse);
         response.writeHead(
           upstreamResponse.statusCode || 502,
           upstreamResponse.statusMessage || '',
@@ -1590,6 +1660,21 @@ async function waitForReceipt(expectedGenerationId) {
   if (shuttingDown) throw new Error('MIAODA_NEST_RUNTIME_STOPPING');
 }
 
+async function waitForSourceStartWindow() {
+  // `finish` on the public proxy response proves the complete cached HTML body
+  // has been handed to Node's HTTP layer. It is intentionally independent of
+  // frontend callbacks and of source readiness.
+  if (sourceStartDelayMs === 0) return;
+  const htmlTransferredAtMs = await firstHtmlTransferred;
+  const deadline = htmlTransferredAtMs + sourceStartDelayMs;
+  while (!shuttingDown && Date.now() < deadline) {
+    await new Promise(resolve =>
+      setTimeout(resolve, Math.min(50, deadline - Date.now()))
+    );
+  }
+  if (shuttingDown) throw new Error('MIAODA_NEST_RUNTIME_STOPPING');
+}
+
 async function runActionPluginInit(baseEnv) {
   const record = spawnOwned(
     'action-plugin-init',
@@ -1619,27 +1704,6 @@ async function waitForDrain(upstream) {
   }
 }
 
-function reportSourcePromotionFailure(stage, error, retryDelayMs) {
-  process.stderr.write(
-    `${JSON.stringify({
-      event: 'miaoda_nest_source_promotion_retry',
-      stage,
-      error: error instanceof Error ? error.message : String(error),
-      retryDelayMs,
-      cacheContinuesServing: true,
-    })}\n`
-  );
-}
-
-async function waitForSourceRetry(delayMs) {
-  const deadline = Date.now() + delayMs;
-  while (!shuttingDown && Date.now() < deadline) {
-    await new Promise(resolve =>
-      setTimeout(resolve, Math.min(50, deadline - Date.now()))
-    );
-  }
-}
-
 async function startAndPromoteSource(baseEnv, expectedCapabilityIds) {
   const sourcePort = await reservePort(probeHost(publicHost));
   const candidate = {
@@ -1708,30 +1772,24 @@ async function startAndPromoteSource(baseEnv, expectedCapabilityIds) {
 
 async function promoteSource(expectedGenerationId, expectedCapabilityIds) {
   await waitForReceipt(expectedGenerationId);
-  let retryDelayMs = SOURCE_RETRY_INITIAL_DELAY_MS;
-  let baseEnv;
-  while (!shuttingDown && !baseEnv) {
-    try {
-      baseEnv = { ...process.env, ...readRuntimeEnvironment() };
-      await runActionPluginInit(baseEnv);
-    } catch (error) {
-      baseEnv = undefined;
-      reportSourcePromotionFailure('environment-and-init', error, retryDelayMs);
-      await waitForSourceRetry(retryDelayMs);
-      retryDelayMs = Math.min(retryDelayMs * 2, SOURCE_RETRY_MAX_DELAY_MS);
-    }
-  }
-  retryDelayMs = SOURCE_RETRY_INITIAL_DELAY_MS;
-  while (!shuttingDown && !promoted) {
-    try {
-      await startAndPromoteSource(baseEnv, expectedCapabilityIds);
-    } catch (error) {
-      if (shuttingDown) break;
-      reportSourcePromotionFailure('source-readiness', error, retryDelayMs);
-      await waitForSourceRetry(retryDelayMs);
-      retryDelayMs = Math.min(retryDelayMs * 2, SOURCE_RETRY_MAX_DELAY_MS);
-    }
-  }
+  await waitForSourceStartWindow();
+  const sourceStartingAtMs = Date.now();
+  process.stderr.write(
+    `${JSON.stringify({
+      event: 'miaoda_nest_source_starting',
+      bootId,
+      generationId: currentGenerationId,
+      sourceStartDelayMs,
+      atMs: sourceStartingAtMs,
+      elapsedMs: sourceStartingAtMs - restoreEpochMs,
+      htmlToSourceStartMs: firstHtmlTransferredAtMs
+        ? sourceStartingAtMs - firstHtmlTransferredAtMs
+        : 0,
+    })}\n`
+  );
+  const baseEnv = { ...process.env, ...readRuntimeEnvironment() };
+  await runActionPluginInit(baseEnv);
+  await startAndPromoteSource(baseEnv, expectedCapabilityIds);
 }
 
 function closeProxyBounded() {
@@ -1832,6 +1890,10 @@ async function main() {
     [generation.entryFile],
     {
       env: {
+        // The first-screen bundle is self-contained. NODE_PATH deliberately
+        // points at the restored workspace only for latent external package
+        // loads; the Builder probe starts from an isolated copy and rejects
+        // workspace module resolution on the supported probe surface.
         NODE_PATH: generation.workspaceNodeModulesPath,
         NODE_OPTIONS: '',
         NODE_ENV: 'development',
@@ -1865,13 +1927,15 @@ async function main() {
     generation.expectedCapabilityIds
   ).catch(error => {
     if (!shuttingDown) {
+      const detail = error instanceof Error ? error.message : String(error);
       process.stderr.write(
         `${JSON.stringify({
-          event: 'miaoda_nest_source_promotion_stopped',
-          error: error instanceof Error ? error.message : String(error),
-          cacheContinuesServing: true,
+          event: 'miaoda_nest_source_promotion_failed',
+          error: detail,
+          cacheContinuesServing: false,
         })}\n`
       );
+      void shutdown(`source-promotion-failed:${detail}`, 1);
     }
   });
   await lifetime;