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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-cli",
-  "version": "1.1.66-alpha.20260903064712",
+  "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,6 @@ 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([
@@ -236,6 +243,9 @@ function positiveDuration(name, 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));
@@ -918,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 = [];
@@ -930,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);
@@ -945,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;
@@ -1642,6 +1661,9 @@ async function waitForReceipt(expectedGenerationId) {
 }
 
 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;
@@ -1682,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 = {
@@ -1786,30 +1787,9 @@ async function promoteSource(expectedGenerationId, expectedCapabilityIds) {
         : 0,
     })}\n`
   );
-  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);
-    }
-  }
+  const baseEnv = { ...process.env, ...readRuntimeEnvironment() };
+  await runActionPluginInit(baseEnv);
+  await startAndPromoteSource(baseEnv, expectedCapabilityIds);
 }
 
 function closeProxyBounded() {
@@ -1910,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',
@@ -1943,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;