@linyjs/plugin-docs 0.1.0

package/examples/hello-world/node_modules/@linyjs/client-module-interface/src/hooks.ts

@@ -0,0 +1,175 @@
+/**
+ * 客户端资源消费 Hooks
+ * 详见 [前端模块接口设计](../../spec/前端模块接口设计.md) - 资源消费章节
+ */
+
+import { useContext } from 'react'
+import type { IComponent } from './domain.js'
+import {
+  ClientComponentsContext,
+  ClientServicesContext,
+  ClientHooksContext,
+  ClientRouterContext,
+} from './interfaces.js'
+
+/**
+ * 解析资源引用路径
+ * 
+ * 支持两种格式：
+ * 1. 模块内引用：'serviceTag.name' → 需要当前模块名补全
+ * 2. 跨模块引用：'moduleName.serviceTag.name' → 直接使用
+ * 
+ * @param refPath 引用路径
+ * @param currentModuleName 当前模块名称（可选）
+ * @returns 完整的 RegistryKey
+ */
+function resolveRegistryKey(refPath: string, currentModuleName?: string): string {
+  // 如果已经是完整路径（包含两个点），直接返回
+  const dotCount = (refPath.match(/\./g) || []).length
+  if (dotCount >= 2) {
+    return refPath
+  }
+
+  // 模块内引用，需要补全模块名
+  if (currentModuleName) {
+    return `${currentModuleName}.${refPath}`
+  }
+
+  // 如果没有提供模块名，假设用户传入的是完整路径
+  return refPath
+}
+
+/**
+ * 获取当前模块名称的 Hook
+ * 
+ * 通过 React Context 或其他方式获取当前组件所属的模块名
+ * TODO: 未来可以通过 ModuleContext 提供
+ * 目前暂时返回 undefined，依赖用户显式传递完整路径
+ */
+function useCurrentModuleName(): string | undefined {
+  // TODO: 从 ModuleContext 获取当前模块名
+  // const moduleContext = useContext(ModuleContext)
+  // return moduleContext?.moduleName
+  return undefined
+}
+
+/**
+ * 使用客户端组件
+ * 
+ * @example
+ * // 模块内引用
+ * const Avatar = useClientComponent('userComponents.Avatar')
+ * 
+ * // 跨模块引用
+ * const Avatar = useClientComponent('userModule.userComponents.Avatar')
+ * 
+ * @param refPath 组件引用路径
+ * @returns React 组件
+ */
+export function useClientComponent<P = any>(refPath: string): IComponent<P> | undefined {
+  const components = useContext(ClientComponentsContext)
+  const currentModuleName = useCurrentModuleName()
+  
+  const registryKey = resolveRegistryKey(refPath, currentModuleName)
+  const component = components[registryKey]
+  
+  if (!component) {
+    console.warn(`[useClientComponent] Component not found: "${registryKey}"`)
+  }
+  
+  return component as IComponent<P> | undefined
+}
+
+/**
+ * 使用客户端 Hook
+ * 
+ * @example
+ * // 模块内引用
+ * const useAuth = useClientHook('authHooks.useAuth')
+ * 
+ * // 跨模块引用
+ * const useAuth = useClientHook('authModule.authHooks.useAuth')
+ * 
+ * @param refPath Hook 引用路径
+ * @returns Hook 函数
+ */
+export function useClientHook<T extends Function>(refPath: string): T | undefined {
+  const hooks = useContext(ClientHooksContext)
+  const currentModuleName = useCurrentModuleName()
+  
+  const registryKey = resolveRegistryKey(refPath, currentModuleName)
+  const hook = hooks[registryKey]
+  
+  if (!hook) {
+    console.warn(`[useClientHook] Hook not found: "${registryKey}"`)
+  }
+  
+  return hook as T | undefined
+}
+
+/**
+ * 使用客户端服务
+ * 
+ * @example
+ * // 模块内引用
+ * const userService = useClientService<IUserService>('userService')
+ * 
+ * // 跨模块引用
+ * const userService = useClientService<IUserService>('userModule.userService')
+ * 
+ * @param refPath 服务引用路径
+ * @returns 服务实例
+ */
+export function useClientService<T = any>(refPath: string): T | undefined {
+  const services = useContext(ClientServicesContext)
+  const currentModuleName = useCurrentModuleName()
+  
+  const registryKey = resolveRegistryKey(refPath, currentModuleName)
+  const service = services[registryKey]
+  
+  if (!service) {
+    console.warn(`[useClientService] Service not found: "${registryKey}"`)
+  }
+  
+  return service as T | undefined
+}
+
+/**
+ * 使用客户端路由功能
+ * 
+ * 根据传入的 key 返回对应的路由组件或 Hook：
+ * - 'NavLink' → NavLink 组件
+ * - 'Link' → Link 组件
+ * - 'useNavigate' → useNavigate Hook
+ * - 'useParams' → useParams Hook
+ * - 'useLocation' → useLocation Hook
+ * - 'useSearchParams' → useSearchParams Hook
+ * 
+ * @example
+ * // 获取 NavLink 组件
+ * const NavLink = useClientRoute('NavLink')
+ * 
+ * // 获取 useNavigate Hook
+ * const useNavigate = useClientRoute('useNavigate')
+ * const navigate = useNavigate()
+ * 
+ * @param key 路由功能 key
+ * @returns 路由组件或 Hook
+ */
+export function useClientRoute(key: string): any {
+  const router = useContext(ClientRouterContext)
+  
+  if (!router) {
+    console.warn('[useClientRoute] Router context is not available. Make sure RouterProvider is set up.')
+    return undefined
+  }
+  
+  // 从 router 中获取对应的组件或 Hook
+  const value = router[key]
+  
+  if (!value) {
+    console.warn(`[useClientRoute] Route feature not found: "${key}". Available keys: ${Object.keys(router).join(', ')}`)
+  }
+  
+  return value
+}

package/examples/hello-world/node_modules/@linyjs/client-module-interface/src/index.ts

@@ -0,0 +1,87 @@
+/**
+ * @linyjs/client-module-interface
+ *
+ * 前端模块接口定义
+ * 详见 [前端模块接口设计](../../spec/前端模块接口设计.md)
+ * 详见 [前端插件式架构设计](../../spec/前端插件式架构设计.md)
+ */
+
+// 基础依赖注入类型
+export type {
+  IService,
+  IServiceConstructor,
+  IServiceFactory,
+  IServiceMaker,
+  IServiceMetadata,
+  IServiceDef,
+  IModule,
+  ILoadedModule,
+  IModuleHandler,
+  IModuleContainer,
+  ModuleEventType,
+  IModuleEvent,
+} from './di.js'
+
+// 模块状态枚举（运行时值）
+export { ModuleState } from './di.js'
+
+// 前端领域类型
+export type {
+  IComponent,
+  IRouteGuard,
+  IRouteLoader,
+  IRoute,
+  RegistryKey,
+} from './domain.js'
+
+// 路由适配器
+export type {
+  IRouterOptions,
+  INavigateOptions,
+  IRouterAdapter,
+} from './router.js'
+export { RouterType } from './router.js'
+
+// 服务接口、元数据、ServiceDef 组合类型
+export type {
+  IAtom,
+  IRouteService,
+  IGlobalStateService,
+  IComponentListService,
+  IHooksService,
+  IClientServiceUsageType,
+  IRouteMetadata,
+  IGlobalStateMetadata,
+  IComponentListMetadata,
+  IHooksMetadata,
+  INormalServiceMetadata,
+  IRouteDef,
+  IGlobalStateDef,
+  IComponentListDef,
+  IHooksDef,
+  INormalServiceDef,
+  IClientServiceDef,
+} from './interfaces.js'
+
+// React Context（运行时值）
+export {
+  ClientComponentsContext,
+  ClientGlobalStateContext,
+  ClientServicesContext,
+  ClientHooksContext,
+  ClientRouterContext,
+} from './interfaces.js'
+
+// 客户端应用接口
+export type {
+  IClientRegistries,
+  IClientApplication,
+} from './application.js'
+
+// 资源消费 Hooks
+export {
+  useClientComponent,
+  useClientHook,
+  useClientService,
+  useClientRoute,
+} from './hooks.js'

package/examples/hello-world/node_modules/@linyjs/client-module-interface/src/interfaces.ts

@@ -0,0 +1,117 @@
+/**
+ * 前端服务接口、元数据类型、React Context、ServiceDef 组合类型
+ * 详见 [前端模块接口设计](../../spec/前端模块接口设计.md)
+ */
+
+import type { IServiceDef, IServiceMetadata } from './di.js'
+import type { IRoute, IComponent } from './domain.js'
+
+// ==================== jotai Atom 兼容类型 ====================
+
+/**
+ * jotai Atom 兼容类型
+ * 避免直接依赖 jotai，使用者应使用 jotai 的 atom() 创建
+ * 此处仅做类型兼容，实际 Atom 结构由 jotai 保证
+ */
+export interface IAtom<T = any> {
+  readonly key: symbol
+  init?: T
+  [key: string]: unknown
+}
+
+// ==================== 服务接口 ====================
+
+/** 路由服务 — 声明页面路由 */
+export interface IRouteService {
+  getRoutes(): IRoute[]
+  basePath?: string
+}
+
+/** 全局状态服务 — 声明 jotai atoms */
+export interface IGlobalStateService {
+  atoms: Record<string, IAtom>
+}
+
+/** 组件列表服务 — 声明可跨模块共享的组件 */
+export interface IComponentListService {
+  components: Record<string, IComponent>
+}
+
+/** Hooks 服务 — 声明可跨模块共享的 hooks */
+export interface IHooksService {
+  hooks: Record<string, Function>
+}
+
+// ==================== 元数据类型 ====================
+
+/** 前端服务用途类型 */
+export type IClientServiceUsageType = 'route' | 'global_state' | 'component' | 'hook' | 'normal_service'
+
+/** 路由元数据 */
+export interface IRouteMetadata extends IServiceMetadata {
+  usageType: 'route'
+}
+
+/** 全局状态元数据 */
+export interface IGlobalStateMetadata extends IServiceMetadata {
+  usageType: 'global_state'
+}
+
+/** 组件列表元数据 */
+export interface IComponentListMetadata extends IServiceMetadata {
+  usageType: 'component'
+}
+
+/** Hooks 元数据 */
+export interface IHooksMetadata extends IServiceMetadata {
+  usageType: 'hook'
+}
+
+/** 普通服务元数据 */
+export interface INormalServiceMetadata extends IServiceMetadata {
+  usageType: 'normal_service'
+}
+
+// ==================== ServiceDef 组合类型 ====================
+
+/** 路由服务定义 */
+export type IRouteDef = IServiceDef<IRouteService, IRouteMetadata>
+
+/** 全局状态服务定义 */
+export type IGlobalStateDef = IServiceDef<IGlobalStateService, IGlobalStateMetadata>
+
+/** 组件列表服务定义 */
+export type IComponentListDef = IServiceDef<IComponentListService, IComponentListMetadata>
+
+/** Hooks 服务定义 */
+export type IHooksDef = IServiceDef<IHooksService, IHooksMetadata>
+
+/** 普通服务定义 */
+export type INormalServiceDef = IServiceDef<any, INormalServiceMetadata>
+
+/** 前端 ServiceDef 联合类型 */
+export type IClientServiceDef =
+  | IRouteDef
+  | IGlobalStateDef
+  | IComponentListDef
+  | IHooksDef
+  | INormalServiceDef
+
+// ==================== React Context ====================
+
+import { createContext } from 'react'
+
+/** 组件注册表 Context */
+export const ClientComponentsContext = createContext<Record<string, IComponent>>({})
+
+/** 全局状态 Context（jotai atoms） */
+export const ClientGlobalStateContext = createContext<Record<string, IAtom>>({})
+
+/** 服务注册表 Context */
+export const ClientServicesContext = createContext<Record<string, any>>({})
+
+/** Hooks 注册表 Context */
+export const ClientHooksContext = createContext<Record<string, Function>>({})
+
+/** 路由适配器 Context */
+export const ClientRouterContext = createContext<any>(null)

package/examples/hello-world/node_modules/@linyjs/client-module-interface/src/router.ts

@@ -0,0 +1,49 @@
+/**
+ * 路由适配器
+ * 详见 [前端模块接口设计](../../spec/前端模块接口设计.md)
+ */
+
+import type { IRoute } from './domain.js'
+
+/** 路由器类型枚举 */
+export enum RouterType {
+  REACT_ROUTER = 'react-router',
+  WECHAT_MINI_PROGRAM = 'wechat-mini-program',
+  CUSTOM = 'custom',
+}
+
+/** 路由器配置选项 */
+export interface IRouterOptions {
+  /** 路由基础路径 */
+  basename?: string
+  /** 其他配置 */
+  [key: string]: unknown
+}
+
+/** 导航选项 */
+export interface INavigateOptions {
+  replace?: boolean
+  state?: unknown
+}
+
+/** 路由适配器接口 */
+export interface IRouterAdapter {
+  /** 初始化路由 */
+  init(routes: IRoute[], options?: IRouterOptions): void
+  /** 获取路由组件（用于渲染到 React 树中） */
+  getRouterComponent(): import('react').ComponentType
+  /** 编程式导航 */
+  navigate(to: string, options?: INavigateOptions): void
+  /** 返回上一页 */
+  goBack(): void
+  /** 前进到下一页 */
+  goForward(): void
+  /** 获取当前位置 */
+  getCurrentLocation(): Location
+  /** 监听位置变化 */
+  listen(listener: (location: Location) => void): () => void
+  /** 获取路由参数 */
+  getParams(): Record<string, string>
+  /** 获取查询参数 */
+  getSearchParams(): URLSearchParams
+}

package/examples/hello-world/node_modules/@linyjs/client-module-interface/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "lib": ["ES2022", "dom"],
+    "jsx": "react-jsx"
+  },
+  "include": ["src"]
+}

package/examples/hello-world/node_modules/@linyjs/server-module-interface/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@linyjs/server-module-interface",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/examples/hello-world/node_modules/@linyjs/server-module-interface/src/application.ts

@@ -0,0 +1,21 @@
+/**
+ * 服务端应用接口
+ * 详见 [服务端插件式架构设计](../../spec/服务端插件式架构设计.md)
+ */
+
+import type { IModule, IModuleHandler, IModuleContainer } from './di.js'
+
+/** 服务端应用接口 */
+export interface IServerApplication {
+  /** 设置模块生命周期处理器 */
+  setHandler(handler: IModuleHandler): void
+
+  /** 加载一组模块，按依赖拓扑排序后由容器实例化服务 */
+  loadModules(modules: IModule[]): Promise<void>
+
+  /** 获取服务实例 */
+  getService<T>(moduleName: string, serviceTag: string): T
+
+  /** 销毁所有已加载模块（逆序调用 handler.onModuleUnloaded） */
+  destroyAll(): Promise<void>
+}

package/examples/hello-world/node_modules/@linyjs/server-module-interface/src/di.ts

@@ -0,0 +1,127 @@
+/**
+ * 基础依赖注入类型定义
+ * 详见 [依赖注入机制设计](../../spec/依赖注入机制设计.md)
+ */
+
+/** 所有服务的基础类型 */
+export type IService = object
+
+/** 服务类构造器类型 */
+export interface IServiceConstructor<S extends IService> {
+  new (...args: any[]): S
+}
+
+/** 服务工厂函数类型 */
+export type IServiceFactory<S extends IService> = (...args: any[]) => S
+
+/** 服务实现类型（类或工厂函数） */
+export type IServiceMaker<S extends IService> =
+  | IServiceConstructor<S>
+  | IServiceFactory<S>
+
+/** 服务元数据基础类型 */
+export type IServiceMetadata = Record<string, any>
+
+/** 服务定义 */
+export interface IServiceDef<
+  S extends IService = IService,
+  M extends IServiceMetadata = IServiceMetadata
+> {
+  /** 服务唯一标识（模块内唯一） */
+  serviceTag: string
+  /** 服务实现，可以是类或工厂函数 */
+  serviceImpl: IServiceMaker<S>
+  /** 依赖的其他服务列表，支持 'serviceTag' 或 'moduleName.serviceTag' 格式 */
+  dependencies?: string[]
+  /** 元数据 */
+  meta?: M
+}
+
+/** 模块定义 */
+export interface IModule {
+  /** 模块名称 */
+  name: string
+  /** 依赖的其他模块名称 */
+  moduleDependencies?: string[]
+  /** 服务定义列表 */
+  serviceDefs: IServiceDef[]
+}
+
+// ==================== 模块状态与事件 ====================
+
+/** 模块状态枚举 */
+export enum ModuleState {
+  Unloaded = 'unloaded',
+  Loading = 'loading',
+  Loaded = 'loaded',
+  Error = 'error',
+  Unloading = 'unloading',
+}
+
+/** 模块事件类型 */
+export type ModuleEventType =
+  | 'module_loaded'
+  | 'module_unloaded'
+  | 'module_error'
+  | 'module_state_changed'
+
+/** 模块事件 */
+export interface IModuleEvent {
+  type: ModuleEventType
+  moduleName: string
+  module?: ILoadedModule
+  error?: Error
+  timestamp: number
+}
+
+/** 已加载模块的运行时表示 */
+export interface ILoadedModule {
+  /** 模块名称 */
+  name: string
+  /** 模块状态 */
+  state: ModuleState
+  /** 服务实例映射表 */
+  services: Map<string, IService>
+  /** 源模块定义 */
+  sourceModule?: IModule
+  /** 加载时间戳 */
+  loadedAt?: number
+}
+
+/** 模块生命周期处理器 */
+export interface IModuleHandler {
+  /** 模块加载完成后执行 */
+  onModuleLoaded?(module: ILoadedModule): void | Promise<void>
+  /** 模块卸载后执行 */
+  onModuleUnloaded?(module: ILoadedModule): void | Promise<void>
+  /** 模块加载错误时执行 */
+  onModuleError?(moduleName: string, error: Error): void | Promise<void>
+}
+
+/** 模块容器接口 */
+export interface IModuleContainer {
+  /** 设置模块生命周期处理器 */
+  setModuleHandler(handler: IModuleHandler): void
+
+  /** 加载模块 */
+  loadModules(modules: IModule[]): Promise<void>
+
+  /** 卸载模块 */
+  unloadModule(moduleName: string): Promise<void>
+  /** 重新加载模块 */
+  reloadModule(moduleName: string, newModule?: IModule): Promise<void>
+
+  /** 检查模块是否已加载 */
+  isModuleLoaded(moduleName: string): boolean
+  /** 获取已加载模块 */
+  getLoadedModule(moduleName: string): ILoadedModule | undefined
+  /** 获取模块状态 */
+  getModuleState(moduleName: string): ModuleState
+  /** 获取服务实例 */
+  getService<T>(moduleName: string, serviceTag: string): T
+
+  /** 监听模块事件 */
+  on(event: ModuleEventType, listener: (event: IModuleEvent) => void): void
+  /** 取消监听模块事件 */
+  off(event: ModuleEventType, listener: (event: IModuleEvent) => void): void
+}

package/examples/hello-world/node_modules/@linyjs/server-module-interface/src/domain.ts

@@ -0,0 +1,75 @@
+/**
+ * 服务端领域类型
+ * 详见 [服务端模块接口设计](../../spec/服务端模块接口设计.md)
+ */
+
+/** 路由上下文 — 由中间件逐步填充的可变上下文 */
+export interface IRouteContext {
+  [key: string]: unknown
+}
+
+/** 中间件 next 函数 */
+export type INextFunction = () => void | Promise<void>
+
+/** 路由处理函数返回值 - 根据 responseType 自动推断 */
+export type IRouteHandlerResult = 
+  | any                                    // responseType='json': 直接返回任意数据
+  | string                                 // responseType='file': 返回文件路径（简单场景）
+  | { filePath: string; filename?: string; contentType?: string }  // responseType='file': 完整配置
+  | NodeJS.ReadableStream                  // responseType='video_stream': 返回流对象
+  | { data: any; status?: number }        // responseType='json': 带状态码的响应
+  | void                                   // 无返回值
+
+/** 路由处理函数 */
+export type IRouteHandler = (
+  params: Record<string, any>,
+  ctx: IRouteContext
+) => IRouteHandlerResult | Promise<IRouteHandlerResult>
+
+/** 中间件处理函数 */
+export type IMiddlewareHandler = (
+  params: Record<string, any>,
+  ctx: IRouteContext,
+  next: INextFunction
+) => void | Promise<void>
+
+/** 路由 */
+export interface IRoute {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+  path: string
+  /**
+   * 中间件引用列表，元素为 IMiddleware.middlewareId。
+   * 解析规则：
+   *  - 裸 ID（如 'auth'）：优先在当前模块内查找，找不到则按模块依赖顺序向外查找
+   *  - 跨模块引用（如 'security.auth'）：显式指定 moduleName，格式为 "moduleName.middlewareId"
+   *  - 引用的 middlewareId 不存在时，Handler 应在加载阶段抛出错误，拒绝注册该路由
+   *  - 数组顺序即执行顺序，按从前到后依次调用
+   */
+  middlewares: string[]
+  handler: IRouteHandler
+  /**
+   * 响应类型声明（可选），用于框架层自动处理响应格式化
+   * - 'json': 自动序列化为 JSON，设置 Content-Type: application/json
+   * - 'file': 自动发送文件，支持断点续传
+   * - 'video_stream': 流式传输视频，支持 range 请求
+   * 
+   * 如果未指定，框架会根据 handler 返回值的 type 字段自动推断
+   */
+  responseType?: 'json' | 'file' | 'video_stream'
+  meta?: Record<string, any>
+}
+
+/** 中间件 */
+export interface IMiddleware {
+  /** 中间件唯一标识，模块内唯一。跨模块引用时通过 "moduleName.middlewareId" 定位 */
+  middlewareId: string
+  handler: IMiddlewareHandler
+}
+
+/** 定时任务 */
+export interface ICronJob {
+  name: string
+  /** cron 表达式 */
+  schedule: string
+  run(): Promise<void>
+}