@lark-apaas/fullstack-cli 1.1.59-alpha.1 → 1.1.59-alpha.20260717075919

package/package.json

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

package/templates/nest-cli.json

@@ -21,5 +21,9 @@
         }
       }
     ]
+  },
+  "x-miaoda-preview": {
+    "compiler": "swc",
+    "typeCheck": "deferred"
   }
-}
+}

package/templates/scripts/dev.js

@@ -3,10 +3,15 @@
 
 const fs = require('fs');
 const path = require('path');
-const { spawn, execSync } = require('child_process');
+const { spawn, execFileSync, execSync } = require('child_process');
 const readline = require('readline');
 const {
+  buildListeningPortLookupArgs,
+  createDeferredTypecheckGate,
   createPreviewPhaseReporter,
+  normalizeTcpPort,
+  parseTscWatchSummary,
+  resolvePreviewServerCommand,
   waitForTcpReady,
 } = require('./preview-startup-timing.cjs');
 
@@ -40,8 +45,12 @@ const MAX_RESTART_COUNT = process.env.MAX_RESTART_COUNT != null && process.env.M
   : Infinity;
 const RESTART_DELAY = parseInt(process.env.RESTART_DELAY, 10) || 2;
 const MAX_DELAY = 8;
-const SERVER_PORT = process.env.SERVER_PORT || '3000';
-const CLIENT_DEV_PORT = process.env.CLIENT_DEV_PORT || '8080';
+const SERVER_PORT = normalizeTcpPort(process.env.SERVER_PORT, 3000, 'SERVER_PORT');
+const CLIENT_DEV_PORT = normalizeTcpPort(
+  process.env.CLIENT_DEV_PORT,
+  8080,
+  'CLIENT_DEV_PORT'
+);
 
 fs.mkdirSync(LOG_DIR, { recursive: true });
 
@@ -102,16 +111,38 @@ function killProcessGroup(pid, signal) {
 
 function killOrphansByPort(port) {
   try {
-    const pids = execSync(`lsof -ti :${port}`, { encoding: 'utf8', timeout: 5000 }).trim();
-    if (pids) {
-      const pidList = pids.split('\n').filter(Boolean);
-      for (const p of pidList) {
-        try { process.kill(parseInt(p, 10), 'SIGKILL'); } catch {}
+    const output = execFileSync('lsof', buildListeningPortLookupArgs(port), {
+      encoding: 'utf8',
+      timeout: 5000,
+    }).trim();
+    const killedPids = [];
+    const failures = [];
+    if (output) {
+      for (const pidText of output.split('\n').filter(Boolean)) {
+        const pid = Number(pidText);
+        try {
+          process.kill(pid, 'SIGKILL');
+          killedPids.push(pidText);
+        } catch (error) {
+          if (error?.code !== 'ESRCH') {
+            failures.push(
+              `${pidText}: ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+        }
       }
-      return pidList;
     }
-  } catch {}
-  return [];
+    return {
+      pids: killedPids,
+      error: failures.length > 0 ? failures.join('; ') : null,
+    };
+  } catch (error) {
+    if (error?.status === 1) return { pids: [], error: null };
+    return {
+      pids: [],
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
 }
 
 // ── Process supervision ───────────────────────────────────────────────────────
@@ -126,7 +157,7 @@ function sleep(ms) {
  * Start and supervise a process with auto-restart and log piping.
  * Returns a promise that resolves when the process loop ends.
  */
-function startProcess({ name, command, args, cleanupPort }) {
+function startProcess({ name, command, args, cleanupPort, phaseDetail = {}, onReady, onOutputLine }) {
   const logFilePath = path.join(LOG_DIR, `${name}.std.log`);
   const logFd = fs.openSync(logFilePath, 'a');
 
@@ -136,6 +167,30 @@ function startProcess({ name, command, args, cleanupPort }) {
   const run = async () => {
     let restartCount = 0;
 
+    if (cleanupPort) {
+      const portCleanup = killOrphansByPort(cleanupPort);
+      const stalePids = portCleanup.pids;
+      logEvent(
+        portCleanup.error ? 'ERROR' : stalePids.length > 0 ? 'WARN' : 'INFO',
+        name,
+        portCleanup.error
+          ? `Port ${cleanupPort} preflight failed: ${portCleanup.error}`
+          : stalePids.length > 0
+          ? `Killed stale processes on port ${cleanupPort} before first spawn: ${stalePids.join(' ')}`
+          : `Port ${cleanupPort} is clear before first spawn`
+      );
+      previewPhaseReporter.emit(
+        name === 'server' ? 'backend_port_preflight' : 'client_port_preflight',
+        portCleanup.error ? 'error' : 'success',
+        {
+          exact: true,
+          cleanup_count: stalePids.length,
+          ...(portCleanup.error ? { error: portCleanup.error } : {}),
+        }
+      );
+      if (stalePids.length > 0) await sleep(500);
+    }
+
     while (!stopping) {
       const child = spawn(command, args, {
         detached: true,
@@ -151,11 +206,17 @@ function startProcess({ name, command, args, cleanupPort }) {
       const startTime = Date.now();
       const attempt = restartCount + 1;
       logEvent('INFO', name, `Process started (PGID: ${child.pid}): ${command} ${args.join(' ')}`);
-      const processPhase = name === 'server' ? 'backend_process_spawn' : 'client_process_spawn';
+      const processPhase =
+        name === 'server'
+          ? 'backend_process_spawn'
+          : name === 'server-typecheck'
+            ? 'backend_typecheck_process_spawn'
+            : 'client_process_spawn';
       previewPhaseReporter.emit(processPhase, 'success', {
         at_ms: startTime,
         attempt,
         exact: true,
+        ...phaseDetail,
       });
       if (name === 'server') {
         void waitForTcpReady({
@@ -164,29 +225,60 @@ function startProcess({ name, command, args, cleanupPort }) {
           interval_ms: 50,
           timeout_ms: 120000,
           should_continue: () => entry.child === child && !stopping,
-        }).then((result) => {
-          if (result.cancelled) return;
-          previewPhaseReporter.emit(
-            'backend_tcp_ready',
-            result.ready ? 'success' : 'error',
-            { ...result, attempt, exact: false }
-          );
-        }).catch((error) => {
-          if (entry.child !== child || stopping) return;
-          previewPhaseReporter.emit('backend_tcp_ready', 'error', {
-            duration_ms: Date.now() - startTime,
-            attempt,
-            exact: false,
-            precision_ms: 50,
-            error: error instanceof Error ? error.message : String(error),
+        })
+          .then(result => {
+            if (result.cancelled) return;
+            previewPhaseReporter.emit(
+              'backend_tcp_ready',
+              result.ready ? 'success' : 'error',
+              { ...result, attempt, exact: false }
+            );
+            if (result.ready && onReady) {
+              try {
+                onReady(result);
+              } catch (error) {
+                logEvent(
+                  'ERROR',
+                  name,
+                  `Backend ready callback failed: ${error instanceof Error ? error.message : String(error)}`
+                );
+              }
+            }
+          })
+          .catch(error => {
+            if (entry.child !== child || stopping) return;
+            previewPhaseReporter.emit('backend_tcp_ready', 'error', {
+              duration_ms: Date.now() - startTime,
+              attempt,
+              exact: false,
+              precision_ms: 50,
+              error: error instanceof Error ? error.message : String(error),
+            });
           });
-        });
       }
 
       // Pipe stdout and stderr through readline for timestamped logging
+      let typecheckSummaryReported = false;
       const pipeLines = (stream) => {
         const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
         rl.on('line', (line) => {
+          if (onOutputLine) onOutputLine(line);
+          if (name === 'server-typecheck' && !typecheckSummaryReported) {
+            const summary = parseTscWatchSummary(line);
+            if (summary) {
+              typecheckSummaryReported = true;
+              previewPhaseReporter.emit(
+                'backend_typecheck_ready',
+                summary.passed ? 'success' : 'error',
+                {
+                  duration_ms: Date.now() - startTime,
+                  attempt,
+                  exact: true,
+                  ...summary,
+                }
+              );
+            }
+          }
           const msg = `[${timestamp()}] [${name}] ${line}\n`;
           try { fs.writeSync(logFd, msg); } catch {}
           writeOutput(msg);
@@ -215,7 +307,15 @@ function startProcess({ name, command, args, cleanupPort }) {
 
       // Port cleanup fallback
       if (cleanupPort) {
-        const orphans = killOrphansByPort(cleanupPort);
+        const portCleanup = killOrphansByPort(cleanupPort);
+        const orphans = portCleanup.pids;
+        if (portCleanup.error) {
+          logEvent(
+            'ERROR',
+            name,
+            `Port ${cleanupPort} cleanup failed: ${portCleanup.error}`
+          );
+        }
         if (orphans.length > 0) {
           logEvent('WARN', name, `Killed orphan processes on port ${cleanupPort}: ${orphans.join(' ')}`);
           await sleep(500);
@@ -277,8 +377,12 @@ async function cleanup() {
   }
 
   // Port cleanup fallback
-  killOrphansByPort(SERVER_PORT);
-  killOrphansByPort(CLIENT_DEV_PORT);
+  for (const port of [SERVER_PORT, CLIENT_DEV_PORT]) {
+    const portCleanup = killOrphansByPort(port);
+    if (portCleanup.error) {
+      logEvent('ERROR', 'main', `Port ${port} cleanup failed: ${portCleanup.error}`);
+    }
+  }
 
   logEvent('INFO', 'main', 'All processes stopped');
 
@@ -332,11 +436,101 @@ async function main() {
   }
 
   // Start server and client
+  const serverCommand = resolvePreviewServerCommand({
+    project_root: PROJECT_ROOT,
+  });
+  logEvent(
+    'INFO',
+    'server',
+    `Selected ${serverCommand.compiler} compiler (${serverCommand.reason})`
+  );
+  previewPhaseReporter.emit('backend_compiler_selected', 'success', {
+    exact: true,
+    compiler: serverCommand.compiler,
+    type_check: serverCommand.type_check,
+    type_check_mode: serverCommand.type_check_mode,
+    reason: serverCommand.reason,
+    missing_modules: serverCommand.missing_modules,
+  });
+  const typecheckGate = createDeferredTypecheckGate();
+  let serverTypecheckStarted = false;
+  const startServerTypecheck = trigger => {
+    if (serverTypecheckStarted || !serverCommand.type_check_command) return;
+    try {
+      logEvent(
+        'INFO',
+        'server-typecheck',
+        `Starting deferred server type checker after ${trigger}`
+      );
+      previewPhaseReporter.emit('backend_typecheck_deferred_start', 'success', {
+        exact: true,
+        type_check_mode: serverCommand.type_check_mode,
+        trigger,
+      });
+      const typecheckPromise = startProcess({
+        name: 'server-typecheck',
+        command: serverCommand.type_check_command.command,
+        args: serverCommand.type_check_command.args,
+        phaseDetail: { type_check_mode: serverCommand.type_check_mode },
+      });
+      serverTypecheckStarted = true;
+      void typecheckPromise.catch(error => {
+        logEvent(
+          'ERROR',
+          'server-typecheck',
+          `Deferred server type checker failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      });
+    } catch (error) {
+      previewPhaseReporter.emit('backend_typecheck_deferred_start', 'error', {
+        exact: true,
+        type_check_mode: serverCommand.type_check_mode,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      logEvent(
+        'ERROR',
+        'server-typecheck',
+        `Failed to start deferred server type checker: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  };
+  const handleBackendReady = () => {
+    if (!serverCommand.type_check_command) return;
+    const decision = typecheckGate.onBackendReady();
+    if (decision.should_start) {
+      startServerTypecheck(decision.reason);
+      return;
+    }
+    logEvent(
+      'INFO',
+      'server-typecheck',
+      'Skipped type checking during initial preview startup'
+    );
+    previewPhaseReporter.emit('backend_typecheck_skipped', 'success', {
+      exact: true,
+      type_check_mode: serverCommand.type_check_mode,
+      reason: decision.reason,
+      next_trigger: 'source_change_or_backend_restart',
+    });
+  };
+  const handleServerOutput = line => {
+    if (!serverCommand.type_check_command || serverTypecheckStarted) return;
+    const decision = typecheckGate.onCompilerOutput(line);
+    if (decision?.should_start) startServerTypecheck(decision.reason);
+  };
   const serverPromise = startProcess({
     name: 'server',
-    command: 'npm',
-    args: ['run', 'dev:server'],
+    command: serverCommand.command,
+    args: serverCommand.args,
     cleanupPort: SERVER_PORT,
+    phaseDetail: {
+      compiler: serverCommand.compiler,
+      type_check: serverCommand.type_check,
+      type_check_mode: serverCommand.type_check_mode,
+      compiler_selection_reason: serverCommand.reason,
+    },
+    onReady: handleBackendReady,
+    onOutputLine: handleServerOutput,
   });
 
   const clientPromise = startProcess({

package/templates/scripts/preview-startup-timing.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
+const fs = require('fs');
 const net = require('net');
+const path = require('path');
 
 const PREFIX = '[MiaodaPreviewPhase] ';
 const RUN_ID_PATTERN = /^prv_[A-Za-z0-9_-]{1,128}$/;
@@ -37,6 +39,277 @@ function createPreviewPhaseReporter(options = {}) {
   return { emit };
 }
 
+function createTscServerCommand(reason, missingModules = []) {
+  return {
+    command: 'npm',
+    args: ['run', 'dev:server', '--', '--builder', 'tsc'],
+    compiler: 'tsc',
+    type_check: true,
+    type_check_mode: 'compiler_integrated',
+    type_check_command: null,
+    reason,
+    missing_modules: missingModules,
+  };
+}
+
+function normalizeTcpPort(value, fallback, name = 'TCP port') {
+  const candidate = value == null || value === '' ? fallback : value;
+  const serialized = String(candidate);
+  if (!/^\d+$/.test(serialized)) {
+    throw new Error(`${name} must be a valid TCP port`);
+  }
+  const port = Number(serialized);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`${name} must be a valid TCP port`);
+  }
+  return port;
+}
+
+function buildListeningPortLookupArgs(port) {
+  const validatedPort = normalizeTcpPort(port, 0);
+  return [`-tiTCP:${validatedPort}`, '-sTCP:LISTEN'];
+}
+
+function hasRuntimeCompilerPluginConsumer(projectRoot, sourceRoot) {
+  const root = path.resolve(projectRoot, sourceRoot || 'src');
+  const stack = [root];
+  let scannedFiles = 0;
+  let scannedBytes = 0;
+  const maxFiles = 2000;
+  const maxBytes = 16 * 1024 * 1024;
+  const consumerPatterns = [
+    /\bSwaggerModule\s*\.\s*(?:createDocument|loadPluginMetadata)\b/,
+    /\bcreateDocument\s*\(/,
+    /\bloadPluginMetadata\s*\(/,
+    /\bDevTools(?:V2)?Module\s*\.\s*mount\b/,
+  ];
+
+  if (!fs.existsSync(root)) return true;
+
+  try {
+    while (stack.length > 0) {
+      const current = stack.pop();
+      for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          if (!['node_modules', 'dist', '.git'].includes(entry.name)) {
+            stack.push(path.join(current, entry.name));
+          }
+          continue;
+        }
+        if (!entry.isFile() || !/\.(?:[cm]?js|tsx?)$/.test(entry.name)) {
+          continue;
+        }
+        scannedFiles += 1;
+        const filePath = path.join(current, entry.name);
+        const stat = fs.statSync(filePath);
+        scannedBytes += stat.size;
+        if (scannedFiles > maxFiles || scannedBytes > maxBytes) return true;
+        const source = fs.readFileSync(filePath, 'utf8');
+        if (consumerPatterns.some(pattern => pattern.test(source))) return true;
+      }
+    }
+  } catch {
+    // If we cannot prove the compiler plugin is unobservable at runtime, keep TSC.
+    return true;
+  }
+  return false;
+}
+
+function resolvePreviewServerCommand(options = {}) {
+  const projectRoot = options.project_root || path.resolve(__dirname, '..');
+  let packageJson = options.package_json;
+  if (!packageJson) {
+    try {
+      packageJson = JSON.parse(
+        fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8')
+      );
+    } catch {
+      packageJson = {};
+    }
+  }
+
+  let nestCliConfig = options.nest_cli_config;
+  if (!nestCliConfig) {
+    try {
+      nestCliConfig = JSON.parse(
+        fs.readFileSync(path.join(projectRoot, 'nest-cli.json'), 'utf8')
+      );
+    } catch {
+      nestCliConfig = {};
+    }
+  }
+
+  const serverScript = packageJson?.scripts?.['dev:server'] || '';
+  const normalizedServerScript = serverScript
+    .trim()
+    .replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=[^\s]+\s+)*/, '')
+    .replace(/\s+/g, ' ');
+  const isNestWatchScript = normalizedServerScript === 'nest start --watch';
+  if (!isNestWatchScript) {
+    return {
+      command: 'npm',
+      args: ['run', 'dev:server'],
+      compiler: 'configured',
+      type_check: false,
+      type_check_mode: 'configured',
+      type_check_command: null,
+      reason: 'custom_server_script',
+      missing_modules: [],
+    };
+  }
+
+  const configuredBuilder = nestCliConfig?.compilerOptions?.builder;
+  if (configuredBuilder && configuredBuilder !== 'tsc') {
+    return {
+      command: 'npm',
+      args: ['run', 'dev:server'],
+      compiler: 'configured',
+      type_check: false,
+      type_check_mode: 'configured',
+      type_check_command: null,
+      reason: 'custom_nest_builder',
+      missing_modules: [],
+    };
+  }
+
+  const serverTypecheckScript =
+    packageJson?.scripts?.['type:check:server'] || '';
+  const normalizedTypecheckScript = serverTypecheckScript
+    .trim()
+    .replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=[^\s]+\s+)*/, '')
+    .replace(/\s+/g, ' ');
+  const isNonEmittingTscScript =
+    /^(?:npx )?tsc --noEmit --project [A-Za-z0-9_./-]+$/.test(
+      normalizedTypecheckScript
+    );
+  if (!isNonEmittingTscScript) {
+    return createTscServerCommand('server_typecheck_script_unavailable');
+  }
+
+  const previewCapability = nestCliConfig?.['x-miaoda-preview'];
+  if (
+    previewCapability?.compiler !== 'swc' ||
+    previewCapability?.typeCheck !== 'deferred'
+  ) {
+    return createTscServerCommand('preview_swc_capability_not_declared');
+  }
+
+  const compilerPlugins = Array.isArray(nestCliConfig?.compilerOptions?.plugins)
+    ? nestCliConfig.compilerOptions.plugins
+    : [];
+  const compilerPluginNames = compilerPlugins.map(plugin =>
+    typeof plugin === 'string' ? plugin : plugin?.name || ''
+  );
+  if (
+    compilerPluginNames.some(pluginName => pluginName !== '@nestjs/swagger')
+  ) {
+    return createTscServerCommand('unsupported_nest_compiler_plugins');
+  }
+  if (compilerPluginNames.includes('@nestjs/swagger')) {
+    const runtimeConsumer =
+      typeof options.has_runtime_compiler_plugin_consumer === 'boolean'
+        ? options.has_runtime_compiler_plugin_consumer
+        : hasRuntimeCompilerPluginConsumer(
+            projectRoot,
+            nestCliConfig?.sourceRoot || 'src'
+          );
+    if (runtimeConsumer) {
+      return createTscServerCommand(
+        'runtime_compiler_plugin_consumer_detected'
+      );
+    }
+  }
+
+  const resolveModule =
+    options.resolve_module ||
+    (moduleName => {
+      const resolved = require.resolve(moduleName, { paths: [projectRoot] });
+      if (moduleName === '@swc/core') {
+        const swc = require(resolved);
+        if (typeof swc.transformSync !== 'function') {
+          throw new Error('@swc/core native binding is unavailable');
+        }
+      }
+      return resolved;
+    });
+  const requiredModules = ['@swc/cli', '@swc/core'];
+  const missingModules = requiredModules.filter(moduleName => {
+    try {
+      resolveModule(moduleName);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+
+  if (missingModules.length > 0) {
+    return createTscServerCommand('swc_dependencies_missing', missingModules);
+  }
+
+  return {
+    command: 'npm',
+    args: ['run', 'dev:server', '--', '--builder', 'swc'],
+    compiler: 'swc',
+    type_check: true,
+    type_check_mode: 'deferred_tsc_watch',
+    type_check_command: {
+      command: 'npm',
+      args: [
+        'run',
+        'type:check:server',
+        '--',
+        '--watch',
+        '--preserveWatchOutput',
+        '--locale',
+        'en',
+      ],
+    },
+    reason: 'swc_dependencies_ready',
+    missing_modules: [],
+  };
+}
+
+function createDeferredTypecheckGate() {
+  let initialBackendReadySeen = false;
+
+  return {
+    onBackendReady() {
+      if (!initialBackendReadySeen) {
+        initialBackendReadySeen = true;
+        return {
+          should_start: false,
+          reason: 'initial_preview_startup',
+        };
+      }
+      return {
+        should_start: true,
+        reason: 'backend_restart',
+      };
+    },
+    onCompilerOutput(line) {
+      if (
+        !initialBackendReadySeen ||
+        !/Successfully compiled:\s+\d+\s+files?\s+with\s+swc\b/i.test(line)
+      ) {
+        return null;
+      }
+      return {
+        should_start: true,
+        reason: 'source_change',
+      };
+    },
+  };
+}
+
+function parseTscWatchSummary(line) {
+  const match = /Found\s+(\d+)\s+errors?\.\s+Watching for file changes\./i.exec(
+    line
+  );
+  if (!match) return null;
+  const errorCount = Number(match[1]);
+  return { error_count: errorCount, passed: errorCount === 0 };
+}
+
 function connectTcpOnce({ host, port, timeout_ms }) {
   return new Promise(resolve => {
     const socket = net.createConnection({ host, port });
@@ -54,7 +327,7 @@ function connectTcpOnce({ host, port, timeout_ms }) {
 }
 
 async function waitForTcpReady(options) {
-  const host = options.host || '127.0.0.1';
+  const hosts = options.host ? [options.host] : ['127.0.0.1', '::1'];
   const port = Number(options.port);
   const timeoutMs = options.timeout_ms == null ? 120000 : options.timeout_ms;
   const intervalMs = options.interval_ms == null ? 50 : options.interval_ms;
@@ -80,11 +353,17 @@ async function waitForTcpReady(options) {
       };
     }
     attempts += 1;
-    const ready = await connect({
-      host,
-      port,
-      timeout_ms: Math.max(1, Math.min(intervalMs, timeoutMs)),
-    });
+    const ready = (
+      await Promise.all(
+        hosts.map(host =>
+          connect({
+            host,
+            port,
+            timeout_ms: Math.max(1, Math.min(intervalMs, timeoutMs)),
+          })
+        )
+      )
+    ).some(Boolean);
     const atMs = now();
     if (!shouldContinue()) {
       return {
@@ -121,6 +400,11 @@ async function waitForTcpReady(options) {
 }
 
 module.exports = {
+  buildListeningPortLookupArgs,
+  createDeferredTypecheckGate,
   createPreviewPhaseReporter,
+  normalizeTcpPort,
+  parseTscWatchSummary,
+  resolvePreviewServerCommand,
   waitForTcpReady,
 };