@bleedingdev/modern-js-app-tools 3.2.0-ultramodern.0

package/dist/esm-node/builder/shared/bundlerPlugins/HtmlBottomTemplate.mjs

@@ -0,0 +1,23 @@
+import "node:module";
+class BottomTemplatePlugin {
+    apply(compiler) {
+        compiler.hooks.compilation.tap(this.name, (compilation)=>{
+            this.htmlPlugin.getCompilationHooks(compilation).beforeEmit.tap(this.name, (data)=>{
+                if (!data.plugin.options?.__internal__) return data;
+                if (this.bottomTemplateReg.test(data.html)) {
+                    data.html = data.html.replace(this.bottomTemplateReg, '');
+                    const { bottomTemplate } = data.plugin.options;
+                    if (bottomTemplate) data.html = data.html.replace(this.bodyRegExp, (match)=>`\n${bottomTemplate}\n${match}`);
+                }
+                return data;
+            });
+        });
+    }
+    constructor(htmlPlugin){
+        this.bottomTemplateReg = /<!--<\?-\s*bottomTemplate\s*\?>-->/;
+        this.bodyRegExp = /(<\/\s*body\s*>)/i;
+        this.htmlPlugin = htmlPlugin;
+        this.name = 'bottom-template';
+    }
+}
+export { BottomTemplatePlugin };

package/dist/esm-node/builder/shared/bundlerPlugins/RouterPlugin.mjs

@@ -0,0 +1,158 @@
+import "node:module";
+import { ROUTE_MANIFEST_FILE } from "@modern-js/utils";
+import { merge, mergeWith } from "@modern-js/utils/lodash";
+import { ROUTE_MANIFEST } from "@modern-js/utils/universal/constants";
+import { createHash } from "crypto";
+const PLUGIN_NAME = 'ModernjsRoutePlugin';
+const generateContentHash = (content)=>createHash('md5').update(content).digest('hex').slice(0, 8);
+class RouterPlugin {
+    isTargetNodeOrWebWorker(target) {
+        if ('node' === target || Array.isArray(target) && target.includes('node')) return true;
+        if ('webworker' === target || Array.isArray(target) && target.includes('webworker')) return true;
+        return false;
+    }
+    getEntryChunks(compilation, chunks) {
+        const entrypointsArray = Array.from(compilation.entrypoints.entries());
+        const entryChunkIds = entrypointsArray.map((entrypoint)=>entrypoint[0]);
+        const entryChunks = [
+            ...chunks
+        ].filter((chunk)=>chunk.names?.some((name)=>entryChunkIds.includes(name)));
+        return entryChunks;
+    }
+    getEntryChunkFiles(entryChunks) {
+        return entryChunks.map((chunk)=>[
+                ...chunk.files || []
+            ].find((fname)=>fname.includes('.js')));
+    }
+    apply(compiler) {
+        const { target } = compiler.options;
+        if (this.isTargetNodeOrWebWorker(target)) return;
+        const { rspack } = compiler;
+        const { Compilation, sources } = rspack;
+        const { RawSource } = sources;
+        const normalizePath = (path)=>{
+            if (!path.endsWith('/')) return `${path}/`;
+            return path;
+        };
+        const chunksToHtmlName = new Map();
+        const ROUTE_MANIFEST_HOLDER = "route-manifest";
+        const placeholder = `<!--<?- ${ROUTE_MANIFEST_HOLDER} ?>-->`;
+        compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation)=>{
+            this.HtmlBundlerPlugin.getCompilationHooks(compilation).beforeEmit.tapAsync('RouterManifestPlugin', (data, callback)=>{
+                const { outputName } = data;
+                const { chunks } = data.plugin.options;
+                chunksToHtmlName.set(chunks, outputName);
+                data.html = data.html.replace("<\/script>", `</script>${placeholder}`);
+                callback(null, data);
+            });
+            compilation.hooks.processAssets.tapPromise({
+                name: PLUGIN_NAME,
+                stage: Compilation.PROCESS_ASSETS_STAGE_REPORT
+            }, async ()=>{
+                const stats = compilation.getStats().toJson({
+                    all: false,
+                    publicPath: true,
+                    assets: true,
+                    chunkGroups: true,
+                    chunks: true,
+                    ids: true
+                });
+                const { publicPath, chunks = [], namedChunkGroups } = stats;
+                const routeAssets = {};
+                if (!namedChunkGroups) return;
+                const prevManifestAsset = compilation.getAsset(ROUTE_MANIFEST_FILE);
+                const prevManifestStr = prevManifestAsset ? prevManifestAsset.source.source().toString() : JSON.stringify({
+                    routeAssets: {}
+                });
+                const prevManifest = JSON.parse(prevManifestStr);
+                const asyncEntryNames = [];
+                for (const [name, chunkGroup] of Object.entries(namedChunkGroups)){
+                    if (name.startsWith('async-')) asyncEntryNames.push(name);
+                    const assets = chunkGroup.assets.map((asset)=>{
+                        const filename = asset.name;
+                        return publicPath ? normalizePath(publicPath) + filename : filename;
+                    });
+                    const referenceCssAssets = assets.filter((asset)=>/\.css$/.test(asset));
+                    routeAssets[name] = {
+                        chunkIds: chunkGroup.chunks,
+                        assets,
+                        referenceCssAssets
+                    };
+                    if (prevManifest.routeAssets[name]) mergeWith(routeAssets[name], prevManifest.routeAssets[name], (obj, source)=>{
+                        if (Array.isArray(obj)) return obj.concat(source);
+                        return Object.assign(source, obj);
+                    });
+                }
+                if (asyncEntryNames.length > 0) for (const asyncEntryName of asyncEntryNames){
+                    const syncEntryName = asyncEntryName.replace('async-', '');
+                    const syncEntry = routeAssets[syncEntryName];
+                    const asyncEntry = routeAssets[asyncEntryName];
+                    merge(syncEntry, asyncEntry);
+                }
+                const manifest = {
+                    routeAssets
+                };
+                const entryNames = Array.from(compilation.entrypoints.keys());
+                let entryChunks = [];
+                entryChunks = this.getEntryChunks(compilation, chunks);
+                const entryChunkFiles = this.getEntryChunkFiles(entryChunks);
+                const entryChunkFileIds = entryChunks.map((chunk)=>chunk.id);
+                for(let i = 0; i < entryChunkFiles.length; i++){
+                    const entryName = entryNames[i];
+                    const file = entryChunkFiles[i];
+                    const chunkNames = entryChunks[i].names;
+                    const chunkId = entryChunkFileIds[i];
+                    const asset = compilation.assets[file];
+                    if (!asset || !chunkId) continue;
+                    let relatedAssets = {};
+                    if (entryChunkFiles.length > 1) Object.keys(routeAssets).forEach((routeId)=>{
+                        const segments = routeId.split('_');
+                        const chunkName = segments[0];
+                        if (chunkNames?.includes(chunkName)) relatedAssets[routeId] = routeAssets[routeId];
+                    });
+                    else relatedAssets = routeAssets;
+                    const manifest = {
+                        routeAssets: relatedAssets
+                    };
+                    const injectedContent = `
+            ;(function(){
+              window.${ROUTE_MANIFEST} = ${JSON.stringify(manifest, (k, v)=>{
+                        if (('assets' === k || 'referenceCssAssets' === k) && Array.isArray(v)) return v.map((item)=>item.replace(publicPath, ''));
+                        return v;
+                    })};
+            })();
+          `;
+                    let htmlName;
+                    for (const [chunks, name] of chunksToHtmlName.entries())if (Array.isArray(chunkNames) && Array.isArray(chunks) && chunkNames.every((value, index)=>value === chunks[index])) {
+                        htmlName = name;
+                        break;
+                    }
+                    const oldHtml = compilation.assets[htmlName];
+                    const { enableInlineRouteManifests, disableFilenameHash, staticJsDir, scriptLoading, nonce } = this;
+                    const nonceAttr = nonce ? `nonce="${nonce}"` : '';
+                    if (oldHtml) if (enableInlineRouteManifests) compilation.updateAsset(htmlName, new RawSource(oldHtml.source().toString().replace(placeholder, `<script ${nonceAttr}>${injectedContent}</script>`)), void 0);
+                    else {
+                        const scriptPath = `${staticJsDir}/${ROUTE_MANIFEST_HOLDER}-${entryName}${disableFilenameHash ? '.js' : `.${generateContentHash(injectedContent)}.js`}`;
+                        const scriptUrl = `${publicPath}${scriptPath}`;
+                        const scriptLoadingAttr = 'defer' === scriptLoading ? scriptLoading : 'module' === scriptLoading ? 'type="module"' : '';
+                        const script = `<script ${scriptLoadingAttr} ${nonceAttr} src="${scriptUrl}"></script>`;
+                        compilation.updateAsset(htmlName, new RawSource(oldHtml.source().toString().replace(placeholder, script)), void 0);
+                        compilation.emitAsset(scriptPath, new RawSource(injectedContent));
+                    }
+                }
+                if (prevManifestAsset) compilation.updateAsset(ROUTE_MANIFEST_FILE, new RawSource(JSON.stringify(manifest, null, 2)), void 0);
+                else compilation.emitAsset(ROUTE_MANIFEST_FILE, new RawSource(JSON.stringify(manifest, null, 2)));
+            });
+        });
+    }
+    constructor({ staticJsDir = 'static/js', HtmlBundlerPlugin, enableInlineRouteManifests, disableFilenameHash = false, scriptLoading = 'defer', nonce }){
+        this.name = 'RouterPlugin';
+        this.HtmlBundlerPlugin = HtmlBundlerPlugin;
+        this.enableInlineRouteManifests = enableInlineRouteManifests;
+        this.staticJsDir = staticJsDir;
+        this.disableFilenameHash = disableFilenameHash;
+        this.scriptLoading = scriptLoading;
+        this.nonce = nonce;
+    }
+}
+export { RouterPlugin };

package/dist/esm-node/builder/shared/bundlerPlugins/index.mjs

@@ -0,0 +1,4 @@
+import "node:module";
+export * from "./HtmlAsyncChunkPlugin.mjs";
+export * from "./HtmlBottomTemplate.mjs";
+export * from "./RouterPlugin.mjs";

package/dist/esm-node/builder/shared/createCopyInfo.mjs

@@ -0,0 +1,16 @@
+import "node:module";
+import { resolvePublicDirPaths } from "@modern-js/server-core";
+import path from "path";
+function createCopyInfo(appContext, config) {
+    const configDir = path.resolve(appContext.appDirectory, config.source.configDir || './config');
+    const uploadDir = path.posix.join(configDir.replace(/\\/g, '/'), 'upload');
+    const publicDir = path.posix.join(configDir.replace(/\\/g, '/'), 'public');
+    const customPublicDirPaths = resolvePublicDirPaths(config.server?.publicDir, appContext.appDirectory);
+    return {
+        configDir,
+        uploadDir,
+        publicDir,
+        customPublicDirs: customPublicDirPaths
+    };
+}
+export { createCopyInfo };

package/dist/esm-node/builder/shared/index.mjs

@@ -0,0 +1,4 @@
+import "node:module";
+export * from "./builderPlugins/index.mjs";
+export * from "./createCopyInfo.mjs";
+export * from "./types.mjs";

package/dist/esm-node/builder/shared/loaders/serverModuleLoader.mjs

@@ -0,0 +1,6 @@
+import "node:module";
+function loader() {
+    return "module.exports = {}";
+}
+const serverModuleLoader = loader;
+export default serverModuleLoader;

package/dist/esm-node/builder/shared/types.mjs

@@ -0,0 +1 @@
+import "node:module";

package/dist/esm-node/commands/build.mjs

@@ -0,0 +1,64 @@
+import "node:module";
+import node_path from "node:path";
+import { fs, logger } from "@modern-js/utils";
+import { loadServerPlugins } from "../utils/loadPlugins.mjs";
+import { setupTsRuntime } from "../utils/register.mjs";
+import { generateRoutes } from "../utils/routes.mjs";
+async function copyEnvFiles(appDirectory, distDirectory) {
+    try {
+        const files = await fs.readdir(appDirectory);
+        const envFileRegex = /^\.env(\.[a-zA-Z0-9_-]+)*$/;
+        const envFiles = files.filter((file)=>envFileRegex.test(file));
+        if (0 === envFiles.length) return void logger.debug('No .env files found to copy');
+        const copyPromises = envFiles.map(async (envFile)=>{
+            const sourcePath = node_path.resolve(appDirectory, envFile);
+            const targetPath = node_path.resolve(distDirectory, envFile);
+            try {
+                const stat = await fs.stat(sourcePath);
+                if (stat.isDirectory()) return;
+                await fs.copy(sourcePath, targetPath);
+            } catch (error) {
+                logger.warn(`Failed to copy ${envFile}:`, error);
+            }
+        });
+        await Promise.all(copyPromises);
+    } catch (error) {
+        logger.warn('Failed to copy .env files:', error);
+    }
+}
+const build = async (api, options)=>{
+    if (options?.analyze) process.env.BUNDLE_ANALYZE = 'true';
+    const resolvedConfig = api.getNormalizedConfig();
+    const appContext = api.getAppContext();
+    const hooks = api.getHooks();
+    const combinedAlias = [].concat(resolvedConfig?.resolve?.alias ?? []).concat(resolvedConfig?.source?.alias ?? []);
+    await loadServerPlugins(api, appContext.appDirectory, appContext.metaName);
+    await setupTsRuntime(appContext.appDirectory, appContext.distDirectory, combinedAlias, {
+        moduleType: appContext.moduleType,
+        tsconfigPath: resolvedConfig?.server?.tsconfigPath
+    });
+    const { apiOnly } = appContext;
+    if (apiOnly) {
+        await hooks.onBeforeBuild.call({
+            environments: {},
+            bundlerConfigs: void 0,
+            isFirstCompile: false,
+            isWatch: false
+        });
+        await generateRoutes(appContext);
+        await hooks.onAfterBuild.call({
+            environments: {},
+            stats: void 0,
+            isFirstCompile: false,
+            isWatch: false
+        });
+        return;
+    }
+    logger.info('Starting production build...');
+    if (!appContext.builder) throw new Error('Expect the Builder to have been initialized, But the appContext.builder received `undefined`');
+    await appContext.builder.onAfterBuild(async ()=>copyEnvFiles(appContext.appDirectory, appContext.distDirectory));
+    await appContext.builder.build({
+        watch: options?.watch
+    });
+};
+export { build };

package/dist/esm-node/commands/deploy.mjs

@@ -0,0 +1,11 @@
+import "node:module";
+import { getServerPlugins } from "../utils/loadPlugins.mjs";
+const deploy = async (api, options)=>{
+    const hooks = api.getHooks();
+    const { metaName } = api.getAppContext();
+    await getServerPlugins(api, metaName);
+    await hooks.onBeforeDeploy.call(options);
+    await hooks.deploy.call();
+    await hooks.onAfterDeploy.call(options);
+};
+export { deploy };

package/dist/esm-node/commands/dev.mjs

@@ -0,0 +1,78 @@
+import "node:module";
+import node_path from "node:path";
+import { applyPlugins } from "@modern-js/prod-server";
+import { createDevServer } from "@modern-js/server";
+import { DEFAULT_DEV_HOST, SERVER_DIR, getMeta, logger } from "@modern-js/utils";
+import { setServer } from "../utils/createServer.mjs";
+import { loadServerPlugins } from "../utils/loadPlugins.mjs";
+import { printInstructions } from "../utils/printInstructions.mjs";
+import { setupTsRuntime } from "../utils/register.mjs";
+import { generateRoutes } from "../utils/routes.mjs";
+const dev = async (api, options, devServerOptions)=>{
+    if (options.analyze) process.env.BUNDLE_ANALYZE = 'true';
+    const normalizedConfig = api.getNormalizedConfig();
+    const appContext = api.getAppContext();
+    const hooks = api.getHooks();
+    const combinedAlias = [].concat(normalizedConfig?.resolve?.alias ?? []).concat(normalizedConfig?.source?.alias ?? []);
+    await setupTsRuntime(appContext.appDirectory, appContext.distDirectory, combinedAlias, {
+        moduleType: appContext.moduleType,
+        tsconfigPath: normalizedConfig?.server?.tsconfigPath
+    });
+    const { appDirectory, port, apiOnly, metaName, serverRoutes } = appContext;
+    const meta = getMeta(metaName);
+    const serverConfigPath = node_path.resolve(appDirectory, SERVER_DIR, `${meta}.server`);
+    await hooks.onBeforeDev.call();
+    if (!appContext.builder && !apiOnly) throw new Error('Expect the Builder to have been initialized, But the appContext.builder received `undefined`');
+    await generateRoutes(appContext);
+    const pluginInstances = await loadServerPlugins(api, appDirectory, metaName);
+    const serverOptions = {
+        metaName,
+        dev: {
+            https: normalizedConfig.dev.https,
+            setupMiddlewares: normalizedConfig.dev.setupMiddlewares
+        },
+        appContext: {
+            appDirectory,
+            internalDirectory: appContext.internalDirectory,
+            apiDirectory: appContext.apiDirectory,
+            lambdaDirectory: appContext.lambdaDirectory,
+            sharedDirectory: appContext.sharedDirectory,
+            bffRuntimeFramework: appContext.bffRuntimeFramework
+        },
+        serverConfigPath,
+        routes: serverRoutes,
+        pwd: appDirectory,
+        config: normalizedConfig,
+        plugins: pluginInstances,
+        ...devServerOptions
+    };
+    const host = normalizedConfig.dev?.host || DEFAULT_DEV_HOST;
+    if (apiOnly) {
+        const { server } = await createDevServer({
+            ...serverOptions,
+            runCompile: false
+        }, devServerOptions?.applyPlugins || applyPlugins);
+        server.listen({
+            port,
+            host
+        }, ()=>{
+            printInstructions(hooks, appContext, normalizedConfig);
+        });
+        setServer(server);
+    } else {
+        const { server, afterListen } = await createDevServer({
+            ...serverOptions,
+            builder: appContext.builder
+        }, devServerOptions?.applyPlugins || applyPlugins);
+        server.listen({
+            port,
+            host
+        }, async (err)=>{
+            if (err) logger.error('Occur error %s, when start dev server', err);
+            logger.debug('listen dev server done');
+            await afterListen();
+        });
+        setServer(server);
+    }
+};
+export { dev };

package/dist/esm-node/commands/index.mjs

@@ -0,0 +1,48 @@
+import "node:module";
+import { i18n, localeKeys } from "../locale/index.mjs";
+import { runtimeCommand } from "./runtime.mjs";
+const devCommand = async (program, api)=>{
+    program.command('dev').alias('start').usage('[options]').description(i18n.t(localeKeys.command.dev.describe)).option('-c --config <config>', i18n.t(localeKeys.command.shared.config)).option('-e --entry [entry...]', i18n.t(localeKeys.command.dev.entry)).option('--analyze', i18n.t(localeKeys.command.shared.analyze)).option('--api-only', i18n.t(localeKeys.command.dev.apiOnly)).option('--web-only', i18n.t(localeKeys.command.dev.webOnly)).action(async (options)=>{
+        const { dev } = await import("./dev.mjs");
+        await dev(api, options);
+    });
+};
+const buildCommand = async (program, api)=>{
+    program.command('build').usage('[options]').description(i18n.t(localeKeys.command.build.describe)).option('-c --config <config>', i18n.t(localeKeys.command.shared.config)).option('--analyze', i18n.t(localeKeys.command.shared.analyze)).option('-w --watch', i18n.t(localeKeys.command.build.watch)).action(async (options)=>{
+        const { build } = await import("./build.mjs");
+        await build(api, options);
+    });
+};
+const serverCommand = (program, api)=>{
+    program.command('serve').usage('[options]').description(i18n.t(localeKeys.command.serve.describe)).option('--api-only', i18n.t(localeKeys.command.dev.apiOnly)).option('-c --config <config>', i18n.t(localeKeys.command.shared.config)).action(async ()=>{
+        const { serve } = await import("./serve.mjs");
+        await serve(api);
+    });
+};
+const deployCommand = (program, api)=>{
+    program.command('deploy').usage('[options]').option('-c --config <config>', i18n.t(localeKeys.command.shared.config)).option('-s --skip-build', i18n.t(localeKeys.command.shared.skipBuild)).description(i18n.t(localeKeys.command.deploy.describe)).action(async (options)=>{
+        if (!options.skipBuild) {
+            const { build } = await import("./build.mjs");
+            await build(api);
+        }
+        const { deploy } = await import("./deploy.mjs");
+        await deploy(api, options);
+        process.exit(0);
+    });
+};
+const inspectCommand = (program, api)=>{
+    program.command('inspect').description('inspect the internal configs').option("--env <env>", i18n.t(localeKeys.command.inspect.env), 'development').option('--output <output>', i18n.t(localeKeys.command.inspect.output), './').option('--verbose', i18n.t(localeKeys.command.inspect.verbose)).option('-c --config <config>', i18n.t(localeKeys.command.shared.config)).action(async (options)=>{
+        const { inspect } = await import("./inspect.mjs");
+        inspect(api, options);
+    });
+};
+const infoCommand = (program, api)=>{
+    program.command('info').usage('[options]').description(i18n.t(localeKeys.command.info.describe)).option('-c --config <config>', i18n.t(localeKeys.command.shared.config)).option('--json', 'output as JSON format for machine reading').action(async (options)=>{
+        const { info } = await import("./info.mjs");
+        await info(api, options);
+    });
+};
+const runtimeOperationsCommand = async (program, api)=>{
+    await runtimeCommand(program, api);
+};
+export { buildCommand, deployCommand, devCommand, infoCommand, inspectCommand, runtimeOperationsCommand, serverCommand };

package/dist/esm-node/commands/info.mjs

@@ -0,0 +1,77 @@
+import "node:module";
+import { getEntryOptions, isApiOnly } from "@modern-js/utils";
+import { isMainEntry } from "../utils/routes.mjs";
+const info = async (api, options = {})=>{
+    const normalizedConfig = api.getNormalizedConfig();
+    const appContext = api.getAppContext();
+    const hooks = api.getHooks();
+    const apiOnly = await isApiOnly(appContext.appDirectory, normalizedConfig.source?.entriesDir, appContext.apiDirectory);
+    if (apiOnly) {
+        const projectInfo = {
+            entries: [],
+            apiOnly: true
+        };
+        printProjectInfo(projectInfo, options.json);
+        return;
+    }
+    const [{ getBundleEntry }] = await Promise.all([
+        import("../plugins/analyze/getBundleEntry.mjs")
+    ]);
+    const { entrypoints } = await hooks.modifyEntrypoints.call({
+        entrypoints: await getBundleEntry(hooks, appContext, normalizedConfig)
+    });
+    const { source: { mainEntryName }, server: { ssr, ssrByEntries }, output: { ssg, ssgByEntries } } = normalizedConfig;
+    const { packageName } = appContext;
+    const entries = entrypoints.map((entrypoint)=>{
+        const { entryName, entry, isAutoMount, isCustomSourceEntry, customEntry } = entrypoint;
+        const isMain = isMainEntry(entryName, mainEntryName);
+        const ssrOptions = getEntryOptions(entryName, isMain, ssr, ssrByEntries, packageName);
+        const ssgOptions = getEntryOptions(entryName, isMain, ssg, ssgByEntries, packageName);
+        let ssrMode = false;
+        if (ssrOptions) {
+            if ('boolean' == typeof ssrOptions) ssrMode = 'stream';
+            else if ('object' == typeof ssrOptions) ssrMode = 'string' === ssrOptions.mode ? 'string' : 'stream';
+        }
+        return {
+            entryName,
+            isMainEntry: isMain,
+            entry,
+            isAutoMount: isAutoMount ?? true,
+            isCustomSourceEntry: isCustomSourceEntry ?? false,
+            customEntry: customEntry ?? false,
+            ssr: ssrMode,
+            ssg: Boolean(ssgOptions)
+        };
+    });
+    const projectInfo = {
+        entries,
+        apiOnly: false
+    };
+    printProjectInfo(projectInfo, options.json);
+};
+function printProjectInfo(projectInfo, jsonOnly) {
+    if (jsonOnly) return void console.log(JSON.stringify(projectInfo, null, 2));
+    console.log('');
+    console.log('===== Modern.js Project Info =====');
+    console.log('');
+    console.log(JSON.stringify(projectInfo, null, 2));
+    console.log('');
+    console.log('===== Entry Details =====');
+    console.log('');
+    if (projectInfo.apiOnly) return void console.log('This is an API-only project (no page entries).');
+    if (0 === projectInfo.entries.length) return void console.log('No entries found.');
+    for (const entry of projectInfo.entries){
+        console.log(`Entry: ${entry.entryName}`);
+        console.log(`  - Path: ${entry.entry}`);
+        console.log(`  - Main Entry: ${entry.isMainEntry}`);
+        console.log(`  - Auto Mount: ${entry.isAutoMount}`);
+        console.log(`  - Custom Entry: ${entry.customEntry}`);
+        console.log(`  - Custom Source Entry: ${entry.isCustomSourceEntry}`);
+        console.log("  - Rendering Mode:");
+        if (entry.ssg) console.log("    - SSG: enabled");
+        else if (entry.ssr) console.log(`    - SSR: ${entry.ssr} mode`);
+        else console.log("    - CSR: enabled (default)");
+        console.log('');
+    }
+}
+export { info };

package/dist/esm-node/commands/inspect.mjs

@@ -0,0 +1,16 @@
+import "node:module";
+const inspect = async (api, options)=>{
+    const appContext = api.getAppContext();
+    if (!appContext.builder) throw new Error('Expect the Builder to have been initialized, But the appContext.builder received `undefined`');
+    const metaName = 'modern-js' === appContext.metaName ? 'modern.js' : appContext.metaName;
+    return appContext.builder.inspectConfig({
+        mode: options.env,
+        verbose: options.verbose,
+        outputPath: options.output,
+        writeToDisk: true,
+        extraConfigs: {
+            [metaName]: api.getNormalizedConfig()
+        }
+    });
+};
+export { inspect };

package/dist/esm-node/commands/runtime.mjs

@@ -0,0 +1,117 @@
+import "node:module";
+const DEFAULT_RUNTIME_HOST = 'http://127.0.0.1:8080';
+const DEFAULT_RUNTIME_STATUS_PATH = '/_modern/runtime/status';
+const DEFAULT_RUNTIME_FALLBACK_SIGNAL_PATH = '/_modern/contract-gates/runtime-fallback';
+const DEFAULT_RUNTIME_TOKEN_HEADER = 'x-modernjs-runtime-signal-token';
+const DEFAULT_TIMEOUT_MS = 5000;
+const resolveRuntimeEndpoint = (input, defaultPath)=>{
+    const rawInput = input?.trim();
+    if (!rawInput) return `${DEFAULT_RUNTIME_HOST}${defaultPath}`;
+    if (rawInput.startsWith('http://') || rawInput.startsWith('https://')) return rawInput;
+    const normalized = rawInput.startsWith('/') ? rawInput : `/${rawInput}`;
+    return `${DEFAULT_RUNTIME_HOST}${normalized}`;
+};
+const resolveToken = ({ token, tokenEnv })=>{
+    if ('string' == typeof token && token.trim().length > 0) return token.trim();
+    if ('string' == typeof tokenEnv && tokenEnv.trim().length > 0) {
+        const value = process.env[tokenEnv.trim()];
+        if ('string' == typeof value && value.trim().length > 0) return value.trim();
+    }
+};
+const parseTimeoutMs = (value)=>{
+    if ('string' != typeof value || 0 === value.trim().length) return DEFAULT_TIMEOUT_MS;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_TIMEOUT_MS;
+    return parsed;
+};
+const parseMetadata = (metadata)=>{
+    if ('string' != typeof metadata || 0 === metadata.trim().length) return;
+    const parsed = JSON.parse(metadata);
+    if (!parsed || 'object' != typeof parsed || Array.isArray(parsed)) throw new Error('metadata must be a JSON object');
+    return parsed;
+};
+const fetchWithTimeout = async (url, init, timeoutMs)=>{
+    const controller = new AbortController();
+    const timeout = setTimeout(()=>{
+        controller.abort();
+    }, timeoutMs);
+    try {
+        return await fetch(url, {
+            ...init,
+            signal: controller.signal
+        });
+    } finally{
+        clearTimeout(timeout);
+    }
+};
+const parseResponseBody = async (response)=>{
+    const text = await response.text();
+    if (!text) return {};
+    try {
+        return JSON.parse(text);
+    } catch (_error) {
+        return {
+            raw: text
+        };
+    }
+};
+const printOutput = (payload, jsonOnly)=>{
+    if (jsonOnly) return void console.log(JSON.stringify(payload, null, 2));
+    console.log(JSON.stringify(payload, null, 2));
+};
+const createRuntimeFallbackSignalPayload = (options)=>{
+    const payload = {
+        appName: options.app,
+        reason: options.reason || 'runtime_fallback',
+        phase: options.phase || 'load'
+    };
+    if (options.entry) payload.entry = options.entry;
+    if (options.runtimeDigest) payload.runtimeDigest = options.runtimeDigest;
+    const metadata = parseMetadata(options.metadata);
+    if (metadata) payload.metadata = metadata;
+    return payload;
+};
+const runtimeCommand = async (program, _api)=>{
+    const runtime = program.command('runtime').description('runtime operations');
+    runtime.command('status').description('read runtime status snapshot').option('--endpoint <endpoint>', 'runtime status endpoint URL or path').option('--token <token>', 'runtime status auth token').option('--token-env <name>', 'environment variable name that stores runtime status auth token', 'MODERN_RUNTIME_SIGNAL_TOKEN').option('--header-name <name>', 'auth header name', DEFAULT_RUNTIME_TOKEN_HEADER).option('--timeout <ms>', 'request timeout in milliseconds', '5000').option('--json', 'output as JSON format for machine reading').action(async (options)=>{
+        const endpoint = resolveRuntimeEndpoint(options.endpoint, DEFAULT_RUNTIME_STATUS_PATH);
+        const timeoutMs = parseTimeoutMs(options.timeout);
+        const token = resolveToken({
+            token: options.token,
+            tokenEnv: options.tokenEnv
+        });
+        const headerName = options.headerName?.trim() || DEFAULT_RUNTIME_TOKEN_HEADER;
+        const headers = new Headers();
+        if (token) headers.set(headerName, token);
+        const response = await fetchWithTimeout(endpoint, {
+            method: 'GET',
+            headers
+        }, timeoutMs);
+        const payload = await parseResponseBody(response);
+        if (!response.ok) throw new Error(`runtime status request failed with ${response.status}: ${JSON.stringify(payload)}`);
+        printOutput(payload, options.json);
+    });
+    runtime.command('fallback-signal').description('emit runtime fallback signal for canary gate mutation').requiredOption('--app <appName>', 'remote app name').option('--endpoint <endpoint>', 'runtime fallback signal endpoint URL or path').option('--reason <reason>', 'fallback reason', 'runtime_fallback').option('--phase <phase>', 'fallback phase', 'load').option('--entry <entry>', 'remote entry URL').option('--runtime-digest <digest>', 'runtime digest value').option('--metadata <json>', 'metadata JSON object string').option('--token <token>', 'runtime signal auth token').option('--token-env <name>', 'environment variable name that stores runtime signal auth token', 'MODERN_RUNTIME_SIGNAL_TOKEN').option('--header-name <name>', 'auth header name', DEFAULT_RUNTIME_TOKEN_HEADER).option('--timeout <ms>', 'request timeout in milliseconds', '5000').option('--json', 'output as JSON format for machine reading').action(async (options)=>{
+        const endpoint = resolveRuntimeEndpoint(options.endpoint, DEFAULT_RUNTIME_FALLBACK_SIGNAL_PATH);
+        const timeoutMs = parseTimeoutMs(options.timeout);
+        const token = resolveToken({
+            token: options.token,
+            tokenEnv: options.tokenEnv
+        });
+        const headerName = options.headerName?.trim() || DEFAULT_RUNTIME_TOKEN_HEADER;
+        const payload = createRuntimeFallbackSignalPayload(options);
+        const headers = new Headers({
+            'content-type': 'application/json'
+        });
+        if (token) headers.set(headerName, token);
+        const response = await fetchWithTimeout(endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(payload)
+        }, timeoutMs);
+        const responsePayload = await parseResponseBody(response);
+        if (!response.ok) throw new Error(`runtime fallback signal request failed with ${response.status}: ${JSON.stringify(responsePayload)}`);
+        printOutput(responsePayload, options.json);
+    });
+};
+export { createRuntimeFallbackSignalPayload, resolveRuntimeEndpoint, resolveToken, runtimeCommand };