@lark-apaas/fullstack-cli 1.1.59 → 1.1.61-alpha.20260818172555

package/templates/scripts/cache-generation-prune.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const generationIdPattern = /^[a-f0-9]{64}$/;
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+function emit(event, details = {}) {
+  process.stdout.write(`${JSON.stringify({ event, ...details })}\n`);
+}
+
+function resolveCurrentGeneration(projectRoot) {
+  const cacheStore = path.join(projectRoot, '.miaoda-cache');
+  const generationsRoot = path.join(cacheStore, 'generations');
+  const currentPointer = path.join(cacheStore, 'current');
+  const cacheStat = fs.lstatSync(cacheStore);
+  const generationsStat = fs.lstatSync(generationsRoot);
+  const pointerStat = fs.lstatSync(currentPointer);
+  if (
+    !cacheStat.isDirectory() ||
+    cacheStat.isSymbolicLink() ||
+    !generationsStat.isDirectory() ||
+    generationsStat.isSymbolicLink() ||
+    !pointerStat.isSymbolicLink()
+  ) {
+    throw new Error('MIAODA_CACHE_GENERATION_STORE_REJECTED');
+  }
+
+  const pointer = fs.readlinkSync(currentPointer);
+  const match = /^generations\/([a-f0-9]{64})$/.exec(pointer);
+  if (!match) throw new Error('MIAODA_CACHE_GENERATION_POINTER_REJECTED');
+  const generationId = match[1];
+  const realGenerationsRoot = fs.realpathSync(generationsRoot);
+  const currentRoot = fs.realpathSync(currentPointer);
+  if (currentRoot !== path.join(realGenerationsRoot, generationId)) {
+    throw new Error('MIAODA_CACHE_GENERATION_POINTER_ESCAPED');
+  }
+  const generation = JSON.parse(
+    fs.readFileSync(path.join(currentRoot, 'generation.json'), 'utf8')
+  );
+  if (generation.generationId !== generationId) {
+    throw new Error('MIAODA_CACHE_GENERATION_POINTER_ID_MISMATCH');
+  }
+  return { cacheStore, generationsRoot, realGenerationsRoot, generationId };
+}
+
+export function pruneSupersededCacheGenerations(projectRootInput) {
+  const projectRoot = fs.realpathSync(path.resolve(projectRootInput));
+  const {
+    generationsRoot,
+    realGenerationsRoot,
+    generationId: currentGenerationId,
+  } = resolveCurrentGeneration(projectRoot);
+  const removedGenerationIds = [];
+  for (const entry of fs.readdirSync(generationsRoot, {
+    withFileTypes: true,
+  })) {
+    if (
+      !generationIdPattern.test(entry.name) ||
+      entry.name === currentGenerationId
+    ) {
+      continue;
+    }
+    const target = path.join(generationsRoot, entry.name);
+    const stat = fs.lstatSync(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new Error(`MIAODA_CACHE_GENERATION_ENTRY_REJECTED: ${entry.name}`);
+    }
+    if (
+      fs.realpathSync(target) !== path.join(realGenerationsRoot, entry.name)
+    ) {
+      throw new Error(`MIAODA_CACHE_GENERATION_ENTRY_ESCAPED: ${entry.name}`);
+    }
+    fs.rmSync(target, { recursive: true, force: false });
+    removedGenerationIds.push(entry.name);
+  }
+  return { currentGenerationId, removedGenerationIds };
+}
+
+function run(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, options);
+    child.once('error', reject);
+    child.once('exit', (code, signal) => resolve({ code, signal }));
+  });
+}
+
+async function pruneWithDirectoryLock(projectRoot, waitMs) {
+  const lockDirectory = path.join(
+    projectRoot,
+    '.miaoda-cache',
+    '.generation.lock.d'
+  );
+  const deadline = Date.now() + waitMs;
+  while (true) {
+    try {
+      fs.mkdirSync(lockDirectory);
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      if (Date.now() >= deadline) {
+        emit('miaoda_cache_generation_prune_skipped', {
+          reason: 'lock-timeout',
+        });
+        return;
+      }
+      await delay(100);
+    }
+  }
+  try {
+    emit('miaoda_cache_generations_pruned', {
+      ...pruneSupersededCacheGenerations(projectRoot),
+      lock: 'directory',
+    });
+  } finally {
+    fs.rmdirSync(lockDirectory);
+  }
+}
+
+async function main() {
+  const projectRoot = fs.realpathSync(
+    path.resolve(process.env.MIAODA_WORKSPACE_ROOT || process.cwd())
+  );
+  const waitArg = process.argv.find(arg => arg.startsWith('--wait-ms='));
+  const requestedWaitMs = Number(waitArg?.slice('--wait-ms='.length) || 60_000);
+  const waitMs = Number.isFinite(requestedWaitMs)
+    ? Math.max(0, requestedWaitMs)
+    : 60_000;
+  if (process.argv.includes('--lock-held')) {
+    emit('miaoda_cache_generations_pruned', {
+      ...pruneSupersededCacheGenerations(projectRoot),
+      lock: 'flock',
+    });
+    return;
+  }
+
+  const script = fileURLToPath(import.meta.url);
+  try {
+    const result = await run(
+      'flock',
+      [
+        '-w',
+        String(Math.ceil(waitMs / 1000)),
+        path.join(projectRoot, '.miaoda-cache', '.generation.lock'),
+        process.execPath,
+        script,
+        '--lock-held',
+      ],
+      { cwd: projectRoot, env: process.env, stdio: 'inherit' }
+    );
+    if (result.code === 0) return;
+    emit('miaoda_cache_generation_prune_skipped', {
+      reason: result.signal ? `flock-signal-${result.signal}` : 'lock-timeout',
+    });
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    await pruneWithDirectoryLock(projectRoot, waitMs);
+  }
+}
+
+if (path.resolve(process.argv[1] || '') === fileURLToPath(import.meta.url)) {
+  main().catch(error => {
+    process.stderr.write(
+      `${JSON.stringify({
+        event: 'miaoda_cache_generation_prune_failed',
+        error: error instanceof Error ? error.message : String(error),
+      })}\n`
+    );
+    process.exitCode = 1;
+  });
+}

package/templates/scripts/cache-runtime-coordinator.mjs

@@ -0,0 +1,487 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  validateCacheGeneration,
+  validateCacheGenerationReceipt,
+  writeCacheGenerationValidationReceipt,
+} from './cache-generation-preflight.mjs';
+
+const projectRoot = path.resolve(
+  process.env.MIAODA_WORKSPACE_ROOT || process.cwd()
+);
+const scriptsRoot = path.dirname(fileURLToPath(import.meta.url));
+const cacheRoot = fs.realpathSync(
+  path.resolve(
+    process.env.MIAODA_CACHE_ROOT ||
+      path.join(projectRoot, '.miaoda-cache', 'current')
+  )
+);
+const runtimeManifestFile = path.resolve(
+  process.env.MIAODA_PLATFORM_RUNTIME_MANIFEST ||
+    '/opt/miaoda/preview-runtime/runtime-manifest.json'
+);
+const dependencyReadyFile = path.resolve(
+  process.env.MIAODA_DEPENDENCY_READY_FILE ||
+    path.join(projectRoot, '.miaoda-runtime', 'dependencies-ready.json')
+);
+const publicServerPort = Number(process.env.SERVER_PORT || 3000);
+const publicClientPort = Number(process.env.CLIENT_DEV_PORT || 8080);
+const publicServerHost = process.env.SERVER_HOST || '0.0.0.0';
+const publicClientHost = process.env.CLIENT_DEV_HOST || '0.0.0.0';
+const transitionReadyTimeoutMs = Number(
+  process.env.MIAODA_CACHE_TRANSITION_READY_TIMEOUT_MS || 60_000
+);
+const dependencyHandoffExitCode = 75;
+const validateOnly = process.argv.includes('--validate-only');
+const requestedArtifactScope = (() => {
+  const index = process.argv.indexOf('--artifact-scope');
+  const value = index >= 0 ? process.argv[index + 1] : 'all';
+  if (!['all', 'vite', 'server'].includes(value)) {
+    throw new Error('MIAODA_CACHE_ARTIFACT_SCOPE_INVALID');
+  }
+  return value;
+})();
+const validateWorkspaceInputs = !process.argv.includes(
+  '--skip-workspace-inputs'
+);
+const validateConfigEnvironment = !process.argv.includes(
+  '--skip-config-environment'
+);
+
+function log(stream, message) {
+  for (const line of String(message).split(/\r?\n/)) {
+    if (!line) continue;
+    if (/^MIAODA_LOG\t(?:client|server)\t/.test(line)) {
+      process.stdout.write(`${line}\n`);
+    } else {
+      process.stdout.write(`MIAODA_LOG\t${stream}\t${line}\n`);
+    }
+  }
+}
+
+function emit(event, details = {}) {
+  process.stdout.write(`${JSON.stringify({ event, ...details })}\n`);
+}
+
+function validateGeneration() {
+  let validated;
+  const receiptFile = process.env.MIAODA_CACHE_VALIDATION_RECEIPT_FILE;
+  if (receiptFile) {
+    try {
+      validated = validateCacheGenerationReceipt({
+        projectRoot,
+        cacheRoot,
+        runtimeManifestFile,
+        receiptFile,
+        artifactScope: requestedArtifactScope,
+      });
+    } catch (error) {
+      emit('miaoda_cache_validation_receipt_miss', {
+        reason: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  validated ??= validateCacheGeneration({
+    projectRoot,
+    cacheRoot,
+    runtimeManifestFile,
+    artifactScope: requestedArtifactScope,
+    validateWorkspaceInputs,
+    validateConfigEnvironment,
+  });
+  if (requestedArtifactScope === 'all') {
+    if (validated.generation.applicationKind === 'fullstack') {
+      if (
+        validated.generation.schemaVersion !== 4 ||
+        validated.generation.serverRuntimeMode !==
+          'workspace-source-dependencies'
+      ) {
+        throw new Error('MIAODA_CACHE_COORDINATOR_GENERATION_UNSUPPORTED');
+      }
+    } else if (validated.generation.applicationKind !== 'frontend-only') {
+      throw new Error('MIAODA_CACHE_COORDINATOR_GENERATION_UNSUPPORTED');
+    }
+  }
+  return validated;
+}
+
+let validated;
+try {
+  validated = validateGeneration();
+  const requiredFiles = [path.join(scriptsRoot, 'vite-cache-runtime.mjs')];
+  if (validated.generation.applicationKind === 'fullstack') {
+    requiredFiles.push(
+      path.join(scriptsRoot, 'server-transition-runtime.mjs'),
+      path.join(scriptsRoot, 'server-cache-module-resolver.cjs')
+    );
+  }
+  for (const requiredFile of requiredFiles) {
+    if (!fs.existsSync(requiredFile)) {
+      throw new Error(`MIAODA_CACHE_BOOTSTRAP_INPUT_MISSING: ${requiredFile}`);
+    }
+  }
+  if (validateOnly) {
+    const receiptFile = process.env.MIAODA_CACHE_VALIDATION_RECEIPT_FILE;
+    if (receiptFile && validated.validation?.validatedBy === 'full-sha') {
+      writeCacheGenerationValidationReceipt({ validated, receiptFile });
+    }
+    process.stdout.write(
+      `${JSON.stringify({
+        valid: true,
+        generationId: validated.generation.generationId,
+        schemaVersion: validated.generation.schemaVersion,
+        applicationKind: validated.generation.applicationKind,
+        artifactScope: requestedArtifactScope,
+        receiptWritten: Boolean(
+          receiptFile && validated.validation?.validatedBy === 'full-sha'
+        ),
+      })}\n`
+    );
+    process.exit(0);
+  }
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
+  process.exit(2);
+}
+
+function assertPort(port, name) {
+  if (!Number.isSafeInteger(port) || port <= 0 || port > 65_535) {
+    throw new Error(`${name}_INVALID`);
+  }
+}
+assertPort(publicServerPort, 'MIAODA_COORDINATOR_SERVER_PORT');
+assertPort(publicClientPort, 'MIAODA_COORDINATOR_CLIENT_PORT');
+
+if (validated.generation.applicationKind === 'frontend-only') {
+  const child = spawn(
+    process.execPath,
+    [path.join(scriptsRoot, 'vite-cache-runtime.mjs')],
+    {
+      cwd: projectRoot,
+      env: {
+        ...process.env,
+        MIAODA_CACHE_ROOT: cacheRoot,
+      },
+      detached: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }
+  );
+  child.stdout?.on('data', chunk => log('client', chunk));
+  child.stderr?.on('data', chunk => log('client', chunk));
+  let frontendClosing = false;
+  const stopFrontend = signal => {
+    if (frontendClosing) return;
+    frontendClosing = true;
+    killProcessGroup(child, signal);
+  };
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.once(signal, () => stopFrontend(signal));
+  }
+  const exit = await new Promise(resolve => {
+    child.once('error', () => resolve({ code: 1, signal: null }));
+    child.once('exit', (code, signal) => resolve({ code, signal }));
+  });
+  emit('miaoda_cache_frontend_runtime_exit', exit);
+  process.exit(exit.code ?? (frontendClosing ? 0 : 1));
+}
+
+function reservePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      const port = address && typeof address !== 'string' ? address.port : 0;
+      server.close(error => (error ? reject(error) : resolve(port)));
+    });
+  });
+}
+
+function killProcessGroup(child, signal = 'SIGTERM') {
+  if (!child || child.exitCode !== null || child.signalCode !== null) return;
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {}
+  }
+}
+
+const children = new Set();
+let closing = false;
+
+function spawnManaged({ name, command, args, env }) {
+  const child = spawn(command, args, {
+    cwd: projectRoot,
+    env: { ...process.env, ...env },
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  child.runtimeName = name;
+  children.add(child);
+  child.stdout?.on('data', chunk => log(name, chunk));
+  child.stderr?.on('data', chunk => log(name, chunk));
+  child.once('exit', (code, signal) => {
+    children.delete(child);
+    emit('miaoda_cache_runtime_child_exit', {
+      name,
+      pid: child.pid,
+      code,
+      signal,
+    });
+  });
+  return child;
+}
+
+async function waitForHttp({
+  port,
+  requestPath,
+  expectedStatus = 200,
+  bodyIncludes,
+  child,
+}) {
+  const deadline = Date.now() + transitionReadyTimeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    if (child && (child.exitCode !== null || child.signalCode !== null)) {
+      throw new Error(`${child.runtimeName} exited before readiness`);
+    }
+    try {
+      const response = await fetch(
+        `http://127.0.0.1:${port}${requestPath || '/'}`
+      );
+      const body = await response.text();
+      if (
+        response.status === expectedStatus &&
+        (!bodyIncludes || body.includes(bodyIncludes))
+      ) {
+        return { status: response.status, body };
+      }
+      lastError = new Error(
+        `${requestPath} returned ${response.status}, expected ${expectedStatus}`
+      );
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(
+    `MIAODA_RUNTIME_READY_TIMEOUT: ${
+      lastError instanceof Error ? lastError.message : String(lastError)
+    }`
+  );
+}
+
+const transitionPorts = {
+  server: await reservePort(),
+  client: await reservePort(),
+};
+const transitionPair = {
+  epoch: `transition-${validated.generation.generationId.slice(0, 12)}`,
+  kind: 'transition',
+  server: { port: transitionPorts.server },
+  client: { port: transitionPorts.client },
+};
+
+const transitionServer = spawnManaged({
+  name: 'server',
+  command: process.execPath,
+  args: [path.join(scriptsRoot, 'server-transition-runtime.mjs')],
+  env: {
+    SERVER_HOST: '127.0.0.1',
+    SERVER_PORT: String(transitionPorts.server),
+    MIAODA_CACHE_ROOT: cacheRoot,
+  },
+});
+const transitionClient = spawnManaged({
+  name: 'client',
+  command: process.execPath,
+  args: [path.join(scriptsRoot, 'vite-cache-runtime.mjs')],
+  env: {
+    CLIENT_DEV_HOST: '127.0.0.1',
+    CLIENT_DEV_PORT: String(transitionPorts.client),
+    MIAODA_CACHE_ROOT: cacheRoot,
+    MIAODA_RUNTIME_MANAGED_BY_COORDINATOR: 'true',
+  },
+});
+transitionPair.server.child = transitionServer;
+transitionPair.client.child = transitionClient;
+
+try {
+  await Promise.all([
+    waitForHttp({
+      port: transitionPorts.server,
+      // server-transition-runtime owns the business-path probe and exposes a
+      // stable, side-effect-free readiness contract to the coordinator.
+      requestPath: '/dev/cache-runtime',
+      child: transitionServer,
+    }),
+    waitForHttp({
+      port: transitionPorts.client,
+      requestPath: '/dev/cache-runtime',
+      child: transitionClient,
+    }),
+  ]);
+} catch (error) {
+  for (const child of [transitionServer, transitionClient]) {
+    killProcessGroup(child);
+    setTimeout(() => killProcessGroup(child, 'SIGKILL'), 1_000).unref();
+  }
+  throw error;
+}
+
+const activePair = transitionPair;
+const clientWebSockets = new Set();
+
+function proxyHttp(kind, request, response) {
+  const pair = activePair;
+  const backend = pair[kind];
+  const headers = { ...request.headers };
+  headers['x-miaoda-release-epoch'] = pair.epoch;
+  const upstream = http.request(
+    {
+      host: '127.0.0.1',
+      port: backend.port,
+      method: request.method,
+      path: request.url,
+      headers,
+    },
+    upstreamResponse => {
+      const responseHeaders = { ...upstreamResponse.headers };
+      responseHeaders['x-miaoda-release-epoch'] = pair.epoch;
+      response.writeHead(upstreamResponse.statusCode || 502, responseHeaders);
+      upstreamResponse.pipe(response);
+    }
+  );
+  upstream.once('error', error => {
+    if (!response.headersSent) response.statusCode = 502;
+    response.end(error.message);
+  });
+  request.pipe(upstream);
+}
+
+function proxyUpgrade(kind, request, socket, head) {
+  const pair = activePair;
+  const backend = pair[kind];
+  const upstream = net.createConnection(
+    { host: '127.0.0.1', port: backend.port },
+    () => {
+      let headers = `${request.method} ${request.url} HTTP/${request.httpVersion}\r\n`;
+      let hasEpoch = false;
+      for (let index = 0; index < request.rawHeaders.length; index += 2) {
+        const name = request.rawHeaders[index];
+        if (name.toLowerCase() === 'x-miaoda-release-epoch') hasEpoch = true;
+        headers += `${name}: ${request.rawHeaders[index + 1]}\r\n`;
+      }
+      if (!hasEpoch) headers += `x-miaoda-release-epoch: ${pair.epoch}\r\n`;
+      upstream.write(`${headers}\r\n`);
+      if (head.length > 0) upstream.write(head);
+      socket.pipe(upstream).pipe(socket);
+    }
+  );
+  upstream.once('error', () => socket.destroy());
+  if (kind === 'client') {
+    const record = { socket, upstream, epoch: pair.epoch };
+    clientWebSockets.add(record);
+    const release = () => clientWebSockets.delete(record);
+    socket.once('close', release);
+    upstream.once('close', release);
+  }
+}
+
+function createPublicProxy(kind, port, host) {
+  const server = http.createServer((request, response) =>
+    proxyHttp(kind, request, response)
+  );
+  server.on('upgrade', (request, socket, head) =>
+    proxyUpgrade(kind, request, socket, head)
+  );
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => resolve(server));
+  });
+}
+
+const [serverProxy, clientProxy] = await Promise.all([
+  createPublicProxy('server', publicServerPort, publicServerHost),
+  createPublicProxy('client', publicClientPort, publicClientHost),
+]);
+emit('miaoda_cache_transition_pair_ready', {
+  generationId: validated.generation.generationId,
+  epoch: transitionPair.epoch,
+  serverPort: publicServerPort,
+  clientPort: publicClientPort,
+});
+
+for (const child of [transitionServer, transitionClient]) {
+  child.once('exit', () => {
+    if (closing) return;
+    process.exitCode = 1;
+    emit('miaoda_cache_transition_pair_lost', {
+      failed: child.runtimeName,
+      epoch: transitionPair.epoch,
+    });
+    void close('transition-pair-lost');
+  });
+}
+
+function dependencyRestoreReady() {
+  try {
+    const marker = JSON.parse(fs.readFileSync(dependencyReadyFile, 'utf8'));
+    if (marker.generationId !== validated.generation.generationId) return false;
+    const nodeModules = fs.realpathSync(path.join(projectRoot, 'node_modules'));
+    return fs.statSync(nodeModules).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+let handoffStarted = false;
+async function handoffToOriginalRuntime() {
+  if (closing || handoffStarted || !dependencyRestoreReady()) return;
+  handoffStarted = true;
+  emit('miaoda_cache_dependency_handoff_started', {
+    generationId: validated.generation.generationId,
+    exitCode: dependencyHandoffExitCode,
+  });
+  await close('dependencies-ready');
+  process.exit(dependencyHandoffExitCode);
+}
+
+const dependencyPoller = setInterval(() => {
+  if (dependencyRestoreReady()) void handoffToOriginalRuntime();
+}, 250);
+dependencyPoller.unref();
+if (dependencyRestoreReady()) void handoffToOriginalRuntime();
+
+async function close(signal) {
+  if (closing) return;
+  closing = true;
+  clearInterval(dependencyPoller);
+  for (const connection of clientWebSockets) {
+    connection.socket.destroy();
+    connection.upstream.destroy();
+  }
+  serverProxy.closeAllConnections?.();
+  clientProxy.closeAllConnections?.();
+  await Promise.all([
+    new Promise(resolve => serverProxy.close(resolve)),
+    new Promise(resolve => clientProxy.close(resolve)),
+  ]);
+  for (const child of children) killProcessGroup(child);
+  setTimeout(() => {
+    for (const child of children) killProcessGroup(child, 'SIGKILL');
+  }, 2_000).unref();
+  emit('miaoda_cache_runtime_coordinator_stopped', { signal });
+}
+
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.once(signal, () => void close(signal));
+}