@nasti-toolchain/nasti 1.7.1 → 2.0.1

package/dist/index.d.cts

@@ -1,4 +1,40 @@
-import { InputOptions, OutputOptions } from 'rolldown';
+import { InputOptions, OutputOptions, RenderedChunk } from 'rolldown';
+
+type LogType = 'error' | 'warn' | 'info';
+type LogLevel = LogType | 'silent';
+interface LogOptions {
+    /** 是否清屏（仅 allowClearScreen 且 TTY 下生效） */
+    clear?: boolean;
+    /** 是否带 HH:mm:ss 时间戳前缀 */
+    timestamp?: boolean;
+    /** 关联的 Error（用于 hasErrorLogged 去重） */
+    error?: Error | null;
+}
+interface Logger {
+    info(msg: string, options?: LogOptions): void;
+    warn(msg: string, options?: LogOptions): void;
+    /** 同一条 warn 整个进程只输出一次 */
+    warnOnce(msg: string, options?: LogOptions): void;
+    error(msg: string, options?: LogOptions): void;
+    clearScreen(type: LogType): void;
+    /** 该 Error 是否已经走 logger.error 输出过（避免 CLI 兜底重复打印） */
+    hasErrorLogged(error: Error): boolean;
+    hasWarned: boolean;
+}
+interface LoggerOptions {
+    prefix?: string;
+    allowClearScreen?: boolean;
+    customLogger?: Logger;
+    console?: Console;
+}
+declare const LogLevels: Record<LogLevel, number>;
+declare function createLogger(level?: LogLevel, options?: LoggerOptions): Logger;
+interface ServerUrls {
+    local: string[];
+    network: string[];
+}
+/** 打印 dev server 地址：➜ Local / Network，端口加粗 */
+declare function printServerUrls(urls: ServerUrls, info: Logger['info']): void;
 
 interface NastiConfig {
     /** 项目根目录 */
@@ -25,6 +61,56 @@ interface NastiConfig {
     envPrefix?: string | string[];
     /** 日志级别 */
     logLevel?: 'info' | 'warn' | 'error' | 'silent';
+    /** 启动/重启时是否允许清屏（CI/非 TTY 下自动禁用），默认 true */
+    clearScreen?: boolean;
+    /** 自定义 Logger（替换内置实现，logLevel 等选项由自定义实现自行处理） */
+    customLogger?: Logger;
+    /**
+     * 环境配置 map（Environment API，2.0）。默认注入 `{ client, ssr }`。
+     *
+     * `client` 环境与 top-level `resolve`/`build` **精确镜像**：对
+     * `environments.client` 的覆盖会写回 top-level（反之亦然），保证读 flat
+     * config 的既有插件与新 API 看到同一份配置。
+     */
+    environments?: Record<string, EnvironmentOptions>;
+    /** 实验特性（无稳定性保证，随时可能变更/移除） */
+    experimental?: ExperimentalOptions;
+}
+interface ExperimentalOptions {
+    /**
+     * dev 用 Rolldown `dev()` 引擎整体打包 client 环境后从内存服务
+     * （完整打包模式 / Full Bundle Mode）。HMR 由引擎的 patch 机制驱动，
+     * 动态 import 走懒编译端点。依赖 rolldown 实验 API（无 semver 保护，
+     * 版本锁定 rc.13）。unbundled 管线保持默认。
+     * @experimental
+     * @default false
+     */
+    bundledDev?: boolean;
+}
+/** 单个环境的可配置面（Environment API） */
+interface EnvironmentOptions {
+    /**
+     * 产物消费者：决定 per-env 的 resolve 行为与 `import.meta.env.SSR` 取值。
+     * 默认：环境名为 'client' → 'client'，其余 → 'server'。
+     */
+    consumer?: 'client' | 'server';
+    /**
+     * 该环境的构建入口（相对 root）。client 环境忽略此项（入口从 index.html
+     * 提取）；非 client 环境**只有声明了 entry 才会被 `nasti build` 构建**。
+     */
+    entry?: string | string[];
+    /** per-env 路径解析（client 默认含 'browser' condition；server 走 node conditions） */
+    resolve?: ResolveConfig;
+    /** per-env 构建覆盖（未设置的字段回退 top-level build） */
+    build?: BuildConfig;
+}
+/** 解析后的环境配置 */
+interface ResolvedEnvironmentOptions {
+    consumer: 'client' | 'server';
+    /** 非 client 环境的构建入口（绝对路径）；client 恒为 [] */
+    entry: string[];
+    resolve: Required<ResolveConfig>;
+    build: Required<BuildConfig>;
 }
 /** Electron 目标专用配置，支持 Electron 41+ */
 interface ElectronConfig {
@@ -102,6 +188,14 @@ interface BuildConfig {
     rolldownOptions?: NastiRolldownOptions;
     emptyOutDir?: boolean;
     css?: CssConfig;
+    /** 体积表是否计算 gzip 压缩后大小（大产物可关闭以加速构建），默认 true */
+    reportCompressedSize?: boolean;
+    /** 触发大 chunk 警告的体积阈值（单位 kB，按压缩前 chunk 体积），默认 500 */
+    chunkSizeWarningLimit?: number;
+    /** 按 chunk 抽取 CSS 为独立 .css 文件（关闭则全部合并为单个 CSS 文件），默认 true */
+    cssCodeSplit?: boolean;
+    /** 是否压缩抽取出的 CSS（Lightning CSS，不可用时回退正则压缩），默认同 minify */
+    cssMinify?: boolean;
 }
 /**
  * Nasti 暴露的 Rolldown 选项：在 Rolldown {@link InputOptions} 基础上去掉由 Nasti
@@ -112,9 +206,12 @@ type NastiRolldownOptions = Omit<InputOptions, 'input' | 'plugins'> & {
     output?: OutputOptions;
 };
 interface CssConfig {
-    /** CSP nonce to add to inline <style> tags */
+    /** CSP nonce to add to inline <style> tags (dev only since 2.0 — build emits real .css files) */
     nonce?: string;
-    /** Emit CSS as separate files instead of inline injection (CSP-friendly) */
+    /**
+     * @deprecated 2.0 起 build 始终抽取真实 .css 文件（per-chunk hash + <link> 注入），
+     * 该开关不再生效。控制拆分用 `build.cssCodeSplit`，控制压缩用 `build.cssMinify`。
+     */
     emitCssFile?: boolean;
 }
 interface NastiPlugin {
@@ -135,11 +232,46 @@ interface NastiPlugin {
     resolveId?: (this: PluginContext, source: string, importer: string | undefined, options: ResolveIdOptions) => ResolveIdResult | Promise<ResolveIdResult>;
     load?: (this: PluginContext, id: string) => LoadResult | Promise<LoadResult>;
     transform?: (this: PluginContext, code: string, id: string) => TransformResult | Promise<TransformResult>;
+    /**
+     * Rolldown output 阶段钩子：对每个 chunk 的最终代码做变换或按 chunk 收集产物。
+     * 仅在生产构建生效（dev unbundled 管线没有 chunk 概念）。
+     *
+     * `this` 是 Rolldown 真实的（Rollup 兼容）插件上下文，不是 PluginContext stub：
+     * `this.emitFile({type:'asset'})` 经 `output.assetFileNames` 产出带 hash 的文件，
+     * `this.getFileName(ref)` 可立即解析最终文件名。CSS per-chunk 抽取依赖这两点。
+     */
+    renderChunk?: (this: RenderChunkContext, code: string, chunk: RenderedChunk) => string | {
+        code: string;
+        map?: unknown;
+    } | null | undefined | Promise<string | {
+        code: string;
+        map?: unknown;
+    } | null | undefined>;
+    /** 向 chunk hash 折叠额外输入（如该 chunk 关联的 CSS 内容），保证缓存正确性 */
+    augmentChunkHash?: (this: RenderChunkContext, chunk: RenderedChunk) => string | void | Promise<string | void>;
+    /**
+     * Rolldown output 收尾钩子（write 前最后时机）。`this` 同 renderChunk，
+     * 可 emitFile 补充产物（如 cssCodeSplit:false 的合并 CSS、manifest 等）。
+     */
+    generateBundle?: (this: RenderChunkContext, options?: unknown, bundle?: Record<string, unknown>) => void | Promise<void>;
     config?: (config: NastiConfig, env: {
         mode: string;
         command: string;
     }) => NastiConfig | null | void | Promise<NastiConfig | null | void>;
     configResolved?: (config: ResolvedConfig) => void | Promise<void>;
+    /**
+     * Environment API：在环境配置最终解析前调整单个环境的选项。
+     * 对每个环境名调用一次（含默认注入的 client/ssr）。
+     */
+    configEnvironment?: (name: string, options: EnvironmentOptions, env: {
+        mode: string;
+        command: string;
+    }) => EnvironmentOptions | null | void | Promise<EnvironmentOptions | null | void>;
+    /**
+     * Environment API：按环境过滤插件。返回 false 则该插件不进入此环境的
+     * 插件管线。未声明时插件应用于所有环境（与 Vite 默认一致）。
+     */
+    applyToEnvironment?: (environment: EnvironmentInstance) => boolean;
     configureServer?: (server: DevServer) => void | (() => void) | Promise<void | (() => void)>;
     transformIndexHtml?: (html: string) => string | HtmlTagDescriptor[] | {
         html: string;
@@ -154,6 +286,32 @@ interface PluginContext {
     resolve: (source: string, importer?: string) => Promise<ResolveIdResult>;
     emitFile: (file: EmittedFile) => string;
     getModuleInfo: (id: string) => ModuleInfo | null;
+    /**
+     * Environment API：当前钩子运行所在的环境（dev 管线中可用；
+     * 生产构建的 Rolldown 钩子注入在 Phase 2 接线）。
+     */
+    environment?: EnvironmentInstance;
+}
+/**
+ * 环境实例的公共面（核心实现见 core/environment.ts 的 NastiEnvironment）。
+ * 插件经 `this.environment` / `applyToEnvironment(env)` 感知环境。
+ */
+interface EnvironmentInstance {
+    name: string;
+    consumer: 'client' | 'server';
+    mode: 'dev' | 'build';
+    config: ResolvedConfig;
+    options: ResolvedEnvironmentOptions;
+    hot: HotChannel;
+}
+/**
+ * renderChunk / augmentChunkHash 的 `this`：Rolldown 真实插件上下文的最小可用面。
+ * 与 {@link PluginContext}（dev/buildStart 用的 stub）不同，这里的 emitFile 返回
+ * referenceId，getFileName 能解析出带 hash 的最终文件名。
+ */
+interface RenderChunkContext {
+    emitFile: (file: EmittedFile) => string;
+    getFileName: (referenceId: string) => string;
 }
 interface ResolveIdOptions {
     isEntry?: boolean;
@@ -171,6 +329,8 @@ type TransformResult = string | null | undefined | {
     code: string;
     map?: unknown;
     moduleType?: string;
+    /** 透传 Rolldown：'no-treeshake' 可保证模块不被摇出 chunk.moduleIds */
+    moduleSideEffects?: boolean | 'no-treeshake';
 };
 interface EmittedFile {
     type: 'asset' | 'chunk';
@@ -200,6 +360,8 @@ interface ModuleNode {
     transformResult: TransformResult | null;
     lastHMRTimestamp: number;
     isSelfAccepting: boolean;
+    /** Environment API：节点所属环境名（per-env 模块图，默认 'client'） */
+    environment?: string;
 }
 interface ResolvedConfig {
     root: string;
@@ -215,18 +377,41 @@ interface ResolvedConfig {
     electron: Required<ElectronConfig>;
     envPrefix: string[];
     logLevel: 'info' | 'warn' | 'error' | 'silent';
+    clearScreen: boolean;
+    /** 已接线 logLevel 的 Logger 实例，所有 Nasti 输出统一经此通道 */
+    logger: Logger;
+    /**
+     * 解析后的环境 map（默认 client + ssr）。`environments.client` 的
+     * resolve/build 与 top-level **同引用**（精确镜像，运行时有断言校验）。
+     */
+    environments: Record<string, ResolvedEnvironmentOptions>;
+    experimental: Required<ExperimentalOptions>;
 }
 interface DevServer {
     config: ResolvedConfig;
     middlewares: any;
-    moduleGraph: ModuleGraph;
+    /**
+     * client 环境模块图的别名（back-compat）。
+     * @deprecated 跟随 Vite 退役 flat `server.*` 的方向，2.x 移除；
+     * 新代码请用 `server.environments.client.moduleGraph`。
+     */
+    moduleGraph: ModuleGraph$1;
     watcher: any;
     ws: WebSocketServer;
+    /** Environment API：per-env 环境实例（Phase 1 仅 client 有完整运行时） */
+    environments: Record<string, EnvironmentInstance>;
     listen: (port?: number) => Promise<DevServer>;
     close: () => Promise<void>;
     transformRequest: (url: string) => Promise<TransformResult>;
+    /**
+     * SSR：在 server consumer 环境（默认 `ssr`）中加载并执行模块，返回其导出。
+     * Vite `server.ssrLoadModule` 的 back-compat shim（底层是 module runner +
+     * HotChannel invoke 桥）。模块经 moduleRunnerTransform 转换后在进程内求值，
+     * `import.meta.env.SSR === true`，bare import 外部化交给 node 解析。
+     */
+    ssrLoadModule: (url: string) => Promise<Record<string, unknown>>;
 }
-interface ModuleGraph {
+interface ModuleGraph$1 {
     getModuleByUrl: (url: string) => ModuleNode | undefined;
     getModuleById: (id: string) => ModuleNode | undefined;
     getModulesByFile: (file: string) => Set<ModuleNode> | undefined;
@@ -238,6 +423,32 @@ interface WebSocketServer {
     send: (payload: HmrPayload) => void;
     close: () => void;
 }
+type HotChannelListener = (data: unknown, client: HotChannelClient) => void;
+interface HotChannelClient {
+    send: (payload: HmrPayload) => void;
+}
+/** module runner 经 invoke 调用的 RPC 方法集（Vite DevEnvironment.hot.setInvokeHandler 同构） */
+interface HotChannelInvokeHandlers {
+    /** runner 回调 fetchModule → transformRequest → 求值 */
+    fetchModule: (id: string, importer?: string, options?: {
+        cached?: boolean;
+    }) => Promise<unknown>;
+    /** server 环境的内建模块清单（string/RegExp，序列化需对齐 runner 期望） */
+    getBuiltins?: () => Promise<Array<string | RegExp>> | Array<string | RegExp>;
+    /** 网络暴露的 transport 跳过文件系统存在性检查（安全相关，显式带上） */
+    _skipFsCheck?: boolean;
+}
+interface HotChannel {
+    /** 向该环境的所有客户端广播 */
+    send: (payload: HmrPayload) => void;
+    /** 监听客户端自定义事件（custom events / invoke transport） */
+    on?: (event: string, listener: HotChannelListener) => void;
+    off?: (event: string, listener: HotChannelListener) => void;
+    listen?: () => void;
+    close?: () => void | Promise<void>;
+    /** 注册 invoke 处理器（SSR runner 的 RPC 桥；Phase 1 仅定义契约） */
+    setInvokeHandler?: (handlers: HotChannelInvokeHandlers | undefined) => void;
+}
 interface HmrContext {
     file: string;
     timestamp: number;
@@ -282,13 +493,106 @@ declare function defineConfig(config: NastiConfig): NastiConfig;
  */
 declare function resolveConfig(inlineConfig: NastiConfig | undefined, command: 'build' | 'serve'): Promise<ResolvedConfig>;
 
+declare class PluginContainer {
+    private plugins;
+    private config;
+    private ctx;
+    private emittedFiles;
+    /** Environment API：容器所属环境（未传时为 undefined，行为同 1.x client） */
+    readonly environment?: EnvironmentInstance;
+    constructor(config: ResolvedConfig, environment?: EnvironmentInstance);
+    private createContext;
+    /** 返回所有通过 emitFile() 输出的文件 */
+    getEmittedFiles(): Array<{
+        fileName: string;
+        source: string | Uint8Array;
+    }>;
+    buildStart(): Promise<void>;
+    buildEnd(error?: Error): Promise<void>;
+    resolveId(source: string, importer?: string, options?: {
+        isEntry?: boolean;
+    }): Promise<ResolveIdResult>;
+    load(id: string): Promise<LoadResult>;
+    transform(code: string, id: string): Promise<TransformResult>;
+    /** 完整的模块处理管道: resolveId → load → transform */
+    processModule(source: string, importer?: string): Promise<{
+        id: string;
+        code: string;
+    } | null>;
+    getPlugins(): NastiPlugin[];
+}
+
+declare class ModuleGraph {
+    private urlToModuleMap;
+    private idToModuleMap;
+    private fileToModulesMap;
+    getModuleByUrl(url: string): ModuleNode | undefined;
+    getModuleById(id: string): ModuleNode | undefined;
+    getModulesByFile(file: string): Set<ModuleNode> | undefined;
+    ensureEntryFromUrl(url: string): Promise<ModuleNode>;
+    createModule(url: string, id?: string): ModuleNode;
+    /** 注册文件路径到模块的映射 */
+    registerModule(mod: ModuleNode, file: string): void;
+    /**
+     * Reindex a module under a plugin-provided canonical id (e.g. a `\0virtual:foo`
+     * id returned from `resolveId`). Plugins look up their own virtual modules via
+     * `getModuleById(RESOLVED_ID)` to invalidate them on watcher events; without
+     * this remap they'd never find the node because `ensureEntryFromUrl` keys by
+     * the public URL only.
+     */
+    setModuleId(mod: ModuleNode, id: string): void;
+    /** 更新模块依赖关系 */
+    updateModuleImports(mod: ModuleNode, importedIds: Set<string>): void;
+    /** 使模块的转换缓存失效 */
+    invalidateModule(mod: ModuleNode): void;
+    /** 使所有模块缓存失效 */
+    invalidateAll(): void;
+    /** 获取 HMR 传播边界 - 从变更模块向上遍历找到接受更新的边界 */
+    getHmrBoundaries(mod: ModuleNode): {
+        boundary: ModuleNode;
+        acceptedVia: ModuleNode;
+    }[];
+}
+
+interface NastiEnvironmentInit {
+    hot?: HotChannel;
+    mode?: 'dev' | 'build';
+    /** 环境的候选插件（init 时经 applyToEnvironment 过滤） */
+    plugins?: NastiPlugin[];
+}
+declare class NastiEnvironment implements EnvironmentInstance {
+    readonly name: string;
+    readonly consumer: 'client' | 'server';
+    readonly mode: 'dev' | 'build';
+    readonly config: ResolvedConfig;
+    readonly options: ResolvedEnvironmentOptions;
+    readonly hot: HotChannel;
+    /** applyToEnvironment 过滤后的插件（init() 后可用） */
+    plugins: NastiPlugin[];
+    /** per-env 插件容器（init() 后可用；dev 管线使用） */
+    pluginContainer: PluginContainer | null;
+    /** per-env 模块图（dev 管线使用） */
+    moduleGraph: ModuleGraph;
+    private candidatePlugins;
+    private initialized;
+    constructor(name: string, config: ResolvedConfig, init?: NastiEnvironmentInit);
+    /** 过滤插件并建 per-env PluginContainer */
+    init(): Promise<void>;
+    close(): Promise<void>;
+}
+/** 按 applyToEnvironment 过滤环境插件（未声明 = 应用于所有环境） */
+declare function resolveEnvironmentPlugins(environment: EnvironmentInstance, plugins: NastiPlugin[]): NastiPlugin[];
+
 interface BuildResult {
+    /** client 环境的产物（back-compat：1.x 的 BuildResult 形态） */
     output: Array<{
         fileName: string;
         type: string;
         code?: string;
         source?: Uint8Array | string;
     }>;
+    /** 全部已构建环境的产物（2.0 多环境 builder） */
+    environments?: Record<string, BuildResult['output']>;
 }
 declare function build(inlineConfig?: NastiConfig): Promise<BuildResult>;
 
@@ -350,4 +654,40 @@ interface MonacoEditorPluginOptions {
 }
 declare function monacoEditorPlugin(options?: MonacoEditorPluginOptions): NastiPlugin;
 
-export { type BuildConfig, type DevServer, type ElectronConfig, type HmrPayload, type ModuleNode, type MonacoCustomWorker, type MonacoEditorLanguageWorker, type MonacoEditorPluginOptions, type NastiConfig, type NastiPlugin, type NastiRolldownOptions, type ResolvedConfig, type TransformResult, build, buildElectron, createServer, defineConfig, electronPlugin, monacoEditorPlugin, resolveConfig, startElectronDev };
+/** 非 client 环境的占位通道（SSR/edge 在 Phase 2 接上真实 transport） */
+declare function createNoopHotChannel(): HotChannel;
+/**
+ * client 环境的 ws 通道：包装 server/ws.ts 的 WebSocketServer。
+ * 事件监听与 invoke 在现有 ws 协议上预留（custom event 协议 Phase 2 扩展）。
+ */
+declare function createWsHotChannel(ws: WebSocketServer): HotChannel;
+
+type NastiDebugScope = `nasti:${string}`;
+interface DebuggerOptions {
+    /** 仅当 DEBUG 精确包含该命名空间（而非 nasti:* 通配）时才启用 */
+    onlyWhenFocused?: boolean | string;
+}
+declare function createDebugger(namespace: NastiDebugScope, options?: DebuggerOptions): ((...args: unknown[]) => void) | undefined;
+
+interface EnvRecord {
+    [key: string]: string;
+}
+/**
+ * 从 .env 文件加载环境变量，按优先级合并：
+ *   .env < .env.[mode] < .env.local < .env.[mode].local
+ */
+declare function loadEnv(mode: string, root: string, prefixes: string[]): EnvRecord;
+/**
+ * 将过滤后的 env 转为 Rolldown define 对象
+ * 例: { VITE_FOO: 'bar' } → { 'import.meta.env.VITE_FOO': '"bar"' }
+ * 同时注入 import.meta.env.MODE / DEV / PROD / SSR
+ *
+ * per-env define 钩子（Phase1→Phase2 接口契约）：`overrides` 允许调用方按
+ * 环境覆盖任意 define —— server 环境传 `ssrDefineOverrides('server')` 注入
+ * `import.meta.env.SSR='true'`，不再写死 'false'。
+ */
+declare function buildEnvDefine(env: EnvRecord, mode: string, overrides?: Record<string, string>): Record<string, string>;
+/** 按环境 consumer 派生 import.meta.env.SSR 的 define 覆盖 */
+declare function ssrDefineOverrides(consumer: 'client' | 'server'): Record<string, string>;
+
+export { type BuildConfig, type DevServer, type ElectronConfig, type EnvironmentInstance, type EnvironmentOptions, type HmrPayload, type HotChannel, type HotChannelClient, type HotChannelInvokeHandlers, type LogLevel, LogLevels, type LogOptions, type Logger, type ModuleNode, type MonacoCustomWorker, type MonacoEditorLanguageWorker, type MonacoEditorPluginOptions, type NastiConfig, NastiEnvironment, type NastiPlugin, type NastiRolldownOptions, type PluginContext, type RenderChunkContext, type ResolvedConfig, type ResolvedEnvironmentOptions, type TransformResult, build, buildElectron, buildEnvDefine, createDebugger, createLogger, createNoopHotChannel, createServer, createWsHotChannel, defineConfig, electronPlugin, loadEnv, monacoEditorPlugin, printServerUrls, resolveConfig, resolveEnvironmentPlugins, ssrDefineOverrides, startElectronDev };