@ynight/framework 0.0.0-stage → 0.0.1

package/dist/server/define-server.d.ts

@@ -0,0 +1,19 @@
+import type { ServerExtension } from './types';
+/**
+ * 声明业务认证、授权和生命周期钩子，不在模块导入时监听端口。
+ *
+ * 该函数仅做类型断言（identity），让业务侧可以显式标注 ServerExtension 字面量并享受
+ * 完整的类型提示（auth/devAnonymous/onReady/onClose 等字段），同时避免被 TS 推导成
+ * 宽泛的 `{ ... }` 类型。
+ *
+ * 用法：
+ * ```ts
+ * export default defineServer({
+ *   auth: { authenticate, authorize },
+ *   devAnonymous: true,
+ *   onReady(app) { ... },
+ * });
+ * ```
+ */
+export declare function defineServer(extension: ServerExtension): ServerExtension;
+//# sourceMappingURL=define-server.d.ts.map

package/dist/server/define-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-server.d.ts","sourceRoot":"","sources":["../../src/server/define-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,eAAe,GAAG,eAAe,CAExE"}

package/dist/server/define-server.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineServer = defineServer;
+/**
+ * 声明业务认证、授权和生命周期钩子，不在模块导入时监听端口。
+ *
+ * 该函数仅做类型断言（identity），让业务侧可以显式标注 ServerExtension 字面量并享受
+ * 完整的类型提示（auth/devAnonymous/onReady/onClose 等字段），同时避免被 TS 推导成
+ * 宽泛的 `{ ... }` 类型。
+ *
+ * 用法：
+ * ```ts
+ * export default defineServer({
+ *   auth: { authenticate, authorize },
+ *   devAnonymous: true,
+ *   onReady(app) { ... },
+ * });
+ * ```
+ */
+function defineServer(extension) {
+    return extension;
+}
+//# sourceMappingURL=define-server.js.map

package/dist/server/define-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-server.js","sourceRoot":"","sources":["../../src/server/define-server.ts"],"names":[],"mappings":";;AAkBA,oCAEC;AAlBD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,YAAY,CAAC,SAA0B;IACrD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/server/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 框架 server 子模块的统一出口。
+ *
+ * 暴露：
+ * - 基础类（BaseController / BaseService）：业务侧继承的根类
+ * - 应用入口（createApplication / startApplication）：装配与启动
+ * - 旧版迁移入口（createLegacyApplication / LegacyApplicationOptions / ManagedLegacyApplication）
+ * - 配置助手（defineConfig / resolveApplicationPaths / resolveConfig）
+ * - 路由/服务声明助手（defineRoutes / defineServer）
+ * - Koa 类型透传（DefaultContext / Next）
+ * - 框架上下文与中间件类型（Context / Middleware / Request）
+ * - 配置/应用相关类型集合（ApplicationContext、ApplicationPaths、AuthAdapter、RouteDefinition 等）
+ *
+ * 业务侧只需 `import { ... } from '@ynight/framework/server'` 即可获得全部装配期 API 与类型。
+ */
+export { BaseController, BaseService } from './base-class';
+export { createApplication, startApplication } from './application';
+export { createLegacyApplication } from './legacy';
+export type { LegacyApplicationOptions, ManagedLegacyApplication } from './legacy';
+export { defineConfig, resolveApplicationPaths, resolveConfig } from './config';
+export { defineRoutes } from './define-routes';
+export { defineServer } from './define-server';
+export type { DefaultContext, Next } from 'koa';
+export type { Context, Middleware, Request } from './context';
+export type { ApplicationContext, ApplicationPaths, ConfigInput, AuthAdapter, AuthIdentity, BusinessControllers, BusinessMiddlewares, BusinessServices, ElpisClientConfig, ElpisConfig, ElpisMode, ElpisModelConfig, ElpisPublicConfig, ElpisServerConfig, FrameworkApplication, JsonSchema, ManagedApplication, ResolvedElpisConfig, RouteAccess, RouteDefinition, RouteRequestSchemas, RouterSchemas, ServerExtension, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACnD,YAAY,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,YAAY,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC9D,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,eAAe,GAChB,MAAM,SAAS,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineServer = exports.defineRoutes = exports.resolveConfig = exports.resolveApplicationPaths = exports.defineConfig = exports.createLegacyApplication = exports.startApplication = exports.createApplication = exports.BaseService = exports.BaseController = void 0;
+/**
+ * 框架 server 子模块的统一出口。
+ *
+ * 暴露：
+ * - 基础类（BaseController / BaseService）：业务侧继承的根类
+ * - 应用入口（createApplication / startApplication）：装配与启动
+ * - 旧版迁移入口（createLegacyApplication / LegacyApplicationOptions / ManagedLegacyApplication）
+ * - 配置助手（defineConfig / resolveApplicationPaths / resolveConfig）
+ * - 路由/服务声明助手（defineRoutes / defineServer）
+ * - Koa 类型透传（DefaultContext / Next）
+ * - 框架上下文与中间件类型（Context / Middleware / Request）
+ * - 配置/应用相关类型集合（ApplicationContext、ApplicationPaths、AuthAdapter、RouteDefinition 等）
+ *
+ * 业务侧只需 `import { ... } from '@ynight/framework/server'` 即可获得全部装配期 API 与类型。
+ */
+var base_class_1 = require("./base-class");
+Object.defineProperty(exports, "BaseController", { enumerable: true, get: function () { return base_class_1.BaseController; } });
+Object.defineProperty(exports, "BaseService", { enumerable: true, get: function () { return base_class_1.BaseService; } });
+var application_1 = require("./application");
+Object.defineProperty(exports, "createApplication", { enumerable: true, get: function () { return application_1.createApplication; } });
+Object.defineProperty(exports, "startApplication", { enumerable: true, get: function () { return application_1.startApplication; } });
+var legacy_1 = require("./legacy");
+Object.defineProperty(exports, "createLegacyApplication", { enumerable: true, get: function () { return legacy_1.createLegacyApplication; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_1.defineConfig; } });
+Object.defineProperty(exports, "resolveApplicationPaths", { enumerable: true, get: function () { return config_1.resolveApplicationPaths; } });
+Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_1.resolveConfig; } });
+var define_routes_1 = require("./define-routes");
+Object.defineProperty(exports, "defineRoutes", { enumerable: true, get: function () { return define_routes_1.defineRoutes; } });
+var define_server_1 = require("./define-server");
+Object.defineProperty(exports, "defineServer", { enumerable: true, get: function () { return define_server_1.defineServer; } });
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;GAcG;AACH,2CAA2D;AAAlD,4GAAA,cAAc,OAAA;AAAE,yGAAA,WAAW,OAAA;AACpC,6CAAoE;AAA3D,gHAAA,iBAAiB,OAAA;AAAE,+GAAA,gBAAgB,OAAA;AAC5C,mCAAmD;AAA1C,iHAAA,uBAAuB,OAAA;AAEhC,mCAAgF;AAAvE,sGAAA,YAAY,OAAA;AAAE,iHAAA,uBAAuB,OAAA;AAAE,uGAAA,aAAa,OAAA;AAC7D,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AACrB,iDAA+C;AAAtC,6GAAA,YAAY,OAAA"}

package/dist/server/legacy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 迁移桥接：保留旧 app/config/extend 与路由装配，返回统一的 listen/close。
+ *
+ * 设计要点：
+ * - 认证与响应仍由旧应用自身提供；
+ * - 不会额外注入 SDK 页面或绕过其原有中间件；
+ * - 新项目应优先使用 {@link createApplication}；
+ * - 旧应用可先通过该入口迁入 SDK 依赖（例如先复用 elpis/core 的应用容器）。
+ */
+export { createApplication as createLegacyApplication } from '@ynight/core';
+/** 透传旧版 core 选项与托管应用的类型别名，便于业务侧按统一名称引用。 */
+export type { ElipsCoreOptions as LegacyApplicationOptions, ManagedElipsApplication as ManagedLegacyApplication, } from '@ynight/core';
+//# sourceMappingURL=legacy.d.ts.map

package/dist/server/legacy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy.d.ts","sourceRoot":"","sources":["../../src/server/legacy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,iBAAiB,IAAI,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC5E,2CAA2C;AAC3C,YAAY,EACV,gBAAgB,IAAI,wBAAwB,EAC5C,uBAAuB,IAAI,wBAAwB,GACpD,MAAM,cAAc,CAAC"}

package/dist/server/legacy.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLegacyApplication = void 0;
+/**
+ * 迁移桥接：保留旧 app/config/extend 与路由装配，返回统一的 listen/close。
+ *
+ * 设计要点：
+ * - 认证与响应仍由旧应用自身提供；
+ * - 不会额外注入 SDK 页面或绕过其原有中间件；
+ * - 新项目应优先使用 {@link createApplication}；
+ * - 旧应用可先通过该入口迁入 SDK 依赖（例如先复用 elpis/core 的应用容器）。
+ */
+var core_1 = require("@ynight/core");
+Object.defineProperty(exports, "createLegacyApplication", { enumerable: true, get: function () { return core_1.createApplication; } });
+//# sourceMappingURL=legacy.js.map

package/dist/server/legacy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy.js","sourceRoot":"","sources":["../../src/server/legacy.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,qCAA4E;AAAnE,+GAAA,iBAAiB,OAA2B"}

package/dist/server/types.d.ts

@@ -0,0 +1,272 @@
+import type http from 'node:http';
+import type { Context, Middleware } from './context';
+import type Koa from 'koa';
+import type { LoadedModel } from '@ynight/model-runtime';
+/**
+ * 框架运行模式：
+ * - development：开发态，启用热加载与 devAnonymous 默认开关
+ * - production：生产态，要求显式认证适配器并校验 entry
+ * - test：测试态，由测试套件使用
+ */
+export type ElpisMode = 'development' | 'production' | 'test';
+/** 服务端运行时配置：监听地址/端口、入口文件、业务目录与优雅关闭超时。 */
+export interface ElpisServerConfig {
+    /** 监听 host，可被环境变量 ELPIS_HOST 覆盖，默认 127.0.0.1。 */
+    host?: string;
+    /** 监听端口，可被环境变量 ELPIS_PORT 覆盖，默认 3000。 */
+    port?: number;
+    /** 生产模式必须显式提供；CLI 启动脚本会读取该入口。 */
+    entry?: string;
+    /** 业务模块根目录名，默认 'server'。CLI 编译后会按该相对路径输出。 */
+    businessDir?: string;
+    /** 优雅关闭超时（毫秒），默认 10000。 */
+    closeTimeoutMs?: number;
+}
+/** 模型层配置：业务模型目录与控件契约索引文件。 */
+export interface ElpisModelConfig {
+    /** 业务模型目录，默认 'model'。 */
+    dir?: string;
+    /** 控件契约 JSON Schema 索引文件的相对路径；存在则在启动期校验模型。 */
+    controlContracts?: string;
+}
+/** 客户端 / 公共资源相关配置。 */
+export interface ElpisClientConfig {
+    /** 客户端扩展配置（如动态组件清单）的相对路径。 */
+    extensions?: string;
+    /** Dashboard（控制台）入口 URL 前缀，默认 '/dashboard'，不允许包含 ? 或 #。 */
+    dashboardBase?: string;
+}
+/** 框架公共配置：标题、首页、项目列表策略与默认项目。 */
+export interface ElpisPublicConfig {
+    /** 管理后台标题，显示在浏览器 Title 与登录页。 */
+    title?: string;
+    /** 业务首页路径，默认 '/project-list'。 */
+    homePage?: string;
+    /** 项目入口策略：未配置时仅展示列表；auto 仅在唯一可访问项目时直达；never 直达默认项目。 */
+    projectListMode?: 'always' | 'auto' | 'never';
+    /** projectListMode 为 never 时使用的默认项目 key。 */
+    defaultProjectKey?: string;
+}
+/**
+ * 用户在 elpis.config 中编写的原始配置。
+ * 各字段均可选；框架会用默认值补齐，并通过 {@link ResolvedElpisConfig} 暴露解析后的版本。
+ */
+export interface ElpisConfig {
+    server?: ElpisServerConfig;
+    model?: ElpisModelConfig;
+    client?: ElpisClientConfig;
+    public?: ElpisPublicConfig;
+    dev?: {
+        webPort?: number;
+    };
+    build?: {
+        outDir?: string;
+    };
+}
+/**
+ * 经过 {@link resolveConfig} 解析后的运行时配置：补齐默认值、应用环境变量覆盖、并归一化路径。
+ * 框架装配阶段始终使用本类型，避免各处重复判空。
+ */
+export interface ResolvedElpisConfig {
+    server: Required<Pick<ElpisServerConfig, 'host' | 'port'>> & Omit<ElpisServerConfig, 'host' | 'port'>;
+    model: Required<Pick<ElpisModelConfig, 'dir'>> & Omit<ElpisModelConfig, 'dir'>;
+    client: Required<Pick<ElpisClientConfig, 'dashboardBase'>> & Omit<ElpisClientConfig, 'dashboardBase'>;
+    public: Required<Pick<ElpisPublicConfig, 'title' | 'homePage'>> & Pick<ElpisPublicConfig, 'projectListMode' | 'defaultProjectKey'>;
+    dev: Required<NonNullable<ElpisConfig['dev']>>;
+    build: Required<NonNullable<ElpisConfig['build']>>;
+}
+/**
+ * 框架在装配阶段计算出的所有目录集合。
+ * - sourceRoot：业务源码根（含 elpis.config）
+ * - compiledRoot：CLI 编译输出根（生产为 source/app，开发为 .elpis/dev/app）
+ * - frameworkAssetsRoot：框架内置 HTML/JS 资产目录，用于 History 路由页面兜底
+ * - publicRoot：托管给前端的静态资源目录（默认 ./public，可被 publicRootOverride 覆盖）
+ * - generatedRoot：开发期生成产物根（.elpis）
+ * - outputRoot：build.outDir 的绝对路径
+ * - serverRoot：业务服务端模块根
+ * - modelRoot：业务模型根
+ * - sharedRoot：跨端共享模块根
+ */
+export interface ApplicationPaths {
+    sourceRoot: string;
+    compiledRoot: string;
+    frameworkAssetsRoot: string;
+    publicRoot: string;
+    generatedRoot: string;
+    outputRoot: string;
+    serverRoot: string;
+    modelRoot: string;
+    sharedRoot: string;
+}
+/**
+ * 已认证身份信息。
+ * - id：业务唯一标识，框架以此判定授权
+ * - name：可选显示名
+ * - 其他任意字段透传给业务，但不会暴露给前端（除非业务自行处理）
+ */
+export interface AuthIdentity {
+    id: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * 认证与授权适配器接口。框架不内置任何身份实现，由业务按需注入。
+ */
+export interface AuthAdapter {
+    /** 未认证响应的 WWW-Authenticate challenge 值，例如 Basic realm="elpis"。 */
+    challenge?: string;
+    /**
+     * 解析请求并返回当前身份。未登录返回 null。
+     * 注意：返回 null 时框架会自动回退到 devAnonymous（仅非生产）或返回 401。
+     */
+    authenticate(ctx: Context): AuthIdentity | null | Promise<AuthIdentity | null>;
+    /**
+     * 判定当前身份是否对指定资源/动作具备访问权限。
+     * 路由级（路由声明 access）与项目级（isProjectAllowed）都会调用此方法。
+     */
+    authorize(ctx: Context, access: RouteAccess, identity: AuthIdentity): boolean | Promise<boolean>;
+}
+/**
+ * 授权访问描述。框架将"模块 + 动作"交给业务适配器判定。
+ * - module：模块标识（如路由路径、'project'、'public' 等）
+ * - action：动作标识（如 'read'、'get'、'post' 等 HTTP 方法）
+ */
+export interface RouteAccess {
+    module: string;
+    action: string;
+}
+/**
+ * 业务侧通过 defineServer 注入的扩展。
+ * 框架不直接监听端口（除 startApplication 外），由 core 容器管理生命周期。
+ */
+export interface ServerExtension {
+    auth?: AuthAdapter;
+    /** development/test 的显式匿名回退；生产忽略该开关，始终要求认证。 */
+    devAnonymous?: boolean;
+    /** 应用装配完成后（startApplication 之前）的钩子；可注册额外中间件或探针。 */
+    onReady?(app: FrameworkApplication): void | Promise<void>;
+    /** 容器关闭时的钩子；用于释放数据库连接等资源。 */
+    onClose?(app: FrameworkApplication): void | Promise<void>;
+}
+/** 通过 defineRoutes 返回的单个路由声明；registerRoute 据此装配。 */
+export interface RouteDefinition {
+    /** HTTP 方法，框架会在装配阶段转小写后匹配 Router。 */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+    /** 路由路径，必须以 / 开头。 */
+    path: string;
+    /** 是否要求请求携带 projectKey（header 或 query）；缺失返回 400。 */
+    projectRequired?: boolean;
+    /** 路由级访问控制；缺失时仅依赖模块级授权。 */
+    access?: RouteAccess;
+    /**
+     * 内联请求参数校验规则；存在时优先于 router-schema 目录下的同名规则。
+     * 当前请求校验失败时直接返回 400 并附带 Ajv 错误详情。
+     */
+    schema?: RouteRequestSchemas;
+    /** 路由处理函数；Koa 中间件已统一处理鉴权/校验，到此处即为纯业务。 */
+    handler(ctx: Context): unknown | Promise<unknown>;
+}
+/** JSON Schema 允许对象 Schema，也允许表示恒真／恒假的布尔 Schema。 */
+export type JsonSchema = Record<string, unknown> | boolean;
+/**
+ * 单个 HTTP 方法下的请求参数校验集合。
+ * 任一字段缺省表示对应位置不参与校验。
+ * 校验在中间件中按 body/query/params/headers 顺序执行，任意位置失败立即返回 400。
+ */
+export interface RouteRequestSchemas {
+    body?: JsonSchema;
+    query?: JsonSchema;
+    params?: JsonSchema;
+    headers?: JsonSchema;
+}
+/**
+ * router-schema 目录下的整体结构：
+ * 第一层 key 为路由路径（必须以 / 开头），第二层 key 为 HTTP 方法（小写）。
+ * 用于集中维护跨多个业务路由的共享参数校验规则。
+ */
+export type RouterSchemas = Record<string, Record<string, RouteRequestSchemas>>;
+/** 业务 service 模块容器，key 为文件名（去扩展名），value 为对应类的实例。 */
+export interface BusinessServices {
+    [key: string]: unknown;
+}
+/** 业务 controller 模块容器，key 为文件名（去扩展名），value 为对应类的实例。 */
+export interface BusinessControllers {
+    [key: string]: unknown;
+}
+/** 业务中间件索引容器；中间件在装载阶段已挂载，这里主要用于业务可见性。 */
+export interface BusinessMiddlewares {
+    [key: string]: unknown;
+}
+/**
+ * 框架自身装配的服务集合。
+ * - models：已加载并通过契约校验的业务模型（含 projects）
+ * - routerSchemas：router-schema 目录加载结果，框架路由也可复用
+ * - controlContracts：控件契约 JSON Schema 索引；运行时用于校验模型中 props
+ */
+export interface FrameworkServices {
+    models: LoadedModel[];
+    routerSchemas: RouterSchemas;
+    controlContracts: Record<string, unknown>;
+}
+/**
+ * 框架装配后的 Koa 应用实例。
+ * 通过 Object.defineProperties 在装配阶段追加 config/paths/mode 等只读字段，
+ * 业务模块（service/controller/middleware）在构造时即拿到该实例。
+ */
+export interface FrameworkApplication extends Koa {
+    readonly config: ResolvedElpisConfig;
+    readonly paths: ApplicationPaths;
+    readonly mode: ElpisMode;
+    readonly framework: FrameworkServices;
+    service: BusinessServices;
+    controller: BusinessControllers;
+    middlewares: BusinessMiddlewares;
+    readonly routerSchema: RouterSchemas;
+    readonly serverExtension: ServerExtension;
+}
+/**
+ * 用户配置输入；可以是对象，也可以是基于 mode 的工厂函数（用于区分 dev/prod 行为）。
+ */
+export type ConfigInput = ElpisConfig | ((context: {
+    mode: ElpisMode;
+}) => ElpisConfig);
+/**
+ * createApplication 所需的入参集合。
+ * - rootDir / sourceRoot / moduleRoot：源码与编译产物目录区分
+ * - mode：覆盖环境变量推断的运行模式
+ * - moduleExtension：业务模块的编译扩展名（CLI dev/build 后应显式传 .js）
+ * - server：认证与生命周期钩子
+ * - publicRoot：覆盖前端静态资源目录（主要用于 CLI dev 模式）
+ */
+export interface ApplicationContext {
+    rootDir: string;
+    /** 配置所在的业务源码根；未提供时使用 rootDir。 */
+    sourceRoot?: string;
+    /** CLI 编译输出的业务模块根；提供后从此目录加载 server/model 等模块。 */
+    moduleRoot?: string;
+    mode?: ElpisMode;
+    /** 业务模块实际使用的编译扩展名；CLI 编译后应显式传入 .js。 */
+    moduleExtension?: '.ts' | '.js' | '.cjs';
+    config?: ConfigInput;
+    server?: ServerExtension;
+    publicRoot?: string;
+}
+/**
+ * createApplication 返回的托管应用。
+ * - app：框架装配的 Koa 实例，可继续 app.use() 注入额外中间件
+ * - listen：异步监听，端口/地址可覆盖
+ * - close：优雅关闭（等待连接耗尽或 closeTimeoutMs）
+ */
+export interface ManagedApplication {
+    app: FrameworkApplication;
+    listen(options?: {
+        host?: string;
+        port?: number;
+    }): Promise<http.Server>;
+    close(): Promise<void>;
+}
+/** defineRoutes 接收的工厂函数；返回 RouteDefinition[] 表示一组路由声明。 */
+export type RouteFactory = (app: FrameworkApplication) => RouteDefinition[];
+/** 框架公开的中间件别名，便于业务侧类型提示。 */
+export type ElpisMiddleware = Middleware;
+//# sourceMappingURL=types.d.ts.map

package/dist/server/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}

package/dist/server/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/server/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":""}

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 框架 server 公共入口：转出服务端模块的全部公开导出。
+ *
+ * 业务侧典型用法：
+ * ```ts
+ * import { createApplication, defineServer } from '@ynight/framework/server';
+ * ```
+ *
+ * 注意：本文件只做单一 re-export，新增符号请直接编辑 server/index.ts。
+ */
+export * from './server/index';
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,gBAAgB,CAAC"}

package/dist/server.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * 框架 server 公共入口：转出服务端模块的全部公开导出。
+ *
+ * 业务侧典型用法：
+ * ```ts
+ * import { createApplication, defineServer } from '@ynight/framework/server';
+ * ```
+ *
+ * 注意：本文件只做单一 re-export，新增符号请直接编辑 server/index.ts。
+ */
+tslib_1.__exportStar(require("./server/index"), exports);
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;GASG;AACH,yDAA+B"}

package/package.json

@@ -1,6 +1,109 @@
 {
   "name": "@ynight/framework",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Elpis 管理后台框架运行时与内置客户端资源",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@git.code.tencent.com/YNight/elpis.git"
+  },
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/server/index.js",
+  "types": "./dist/server/index.d.ts",
+  "files": [
+    "dist",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/server/index.d.ts",
+      "require": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "require": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    },
+    "./model": {
+      "types": "./dist/model/index.d.ts",
+      "require": "./dist/model/index.js",
+      "default": "./dist/model/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.mjs"
+    },
+    "./style.css": "./dist/client/style.css",
+    "./assets": {
+      "types": "./dist/assets/index.d.ts",
+      "require": "./dist/assets/index.js",
+      "default": "./dist/assets/index.js"
+    }
+  },
+  "sideEffects": [
+    "**/*.css",
+    "**/*.less"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@koa/router": "^15.1.1",
+    "@types/koa": "^2.15.0",
+    "@types/node": "^22.0.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "ajv-i18n": "^4.2.0",
+    "koa": "^2.15.0",
+    "koa-bodyparser": "^4.4.1",
+    "koa-static": "^5.0.0",
+    "lodash": "^4.18.1",
+    "tslib": "^2.8.1",
+    "@ynight/contracts": "0.0.1",
+    "@ynight/core": "0.0.1",
+    "@ynight/model-runtime": "0.0.1"
+  },
+  "peerDependencies": {
+    "element-plus": "^2.13.1",
+    "pinia": "^3.0.4",
+    "vue": "^3.5.26",
+    "vue-router": "^4.6.4"
+  },
+  "devDependencies": {
+    "@types/koa-bodyparser": "^4.3.13",
+    "@types/koa-static": "^4.0.4",
+    "@types/lodash": "^4.17.25",
+    "@types/mocha": "^10.0.10",
+    "css-loader": "^7.1.2",
+    "element-plus": "^2.13.1",
+    "esbuild-loader": "^4.4.1",
+    "mini-css-extract-plugin": "^2.9.4",
+    "less": "^4.5.1",
+    "less-loader": "^12.3.0",
+    "mocha": "^11.8.0",
+    "pinia": "^3.0.4",
+    "rimraf": "^5.0.10",
+    "typescript": "^5.9.3",
+    "ts-node": "^10.9.2",
+    "vue-loader": "^17.4.2",
+    "vue-tsc": "^3.3.8",
+    "vue": "^3.5.26",
+    "vue-router": "^4.6.4",
+    "webpack": "^5.104.1"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "rimraf dist && tsc -p tsconfig.json && node scripts/build-client.mjs && vue-tsc -p tsconfig.client.json --declaration --emitDeclarationOnly && node scripts/write-client-package.mjs",
+    "type-check": "tsc --noEmit -p tsconfig.json && vue-tsc --noEmit -p tsconfig.client.json",
+    "type-test": "tsc --noEmit -p tsconfig.type-tests.json",
+    "test:server": "TS_NODE_PROJECT=tsconfig.test.json mocha --require ts-node/register --extension ts test/application.test.ts",
+    "test": "pnpm run test:server && pnpm run type-test",
+    "lint": "eslint src"
+  }
 }