create-bubbles 0.1.26 → 0.1.27

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/src/scanner.ts

@@ -23,6 +23,7 @@ const identifierContinuePattern = /[\p{ID_Continue}_$]/u
 const whitespacePattern = /\s/u
 const hexPattern = /^[\dA-Fa-f]+$/
 
+/** 扫描文本中的翻译调用及其静态字符串参数，返回词条与从 1 开始的行列位置；跳过插值模板和动态表达式。 */
 export function scanSource(source: string, options: ScanOptions = {}): MessageOccurrence[] {
   const callNames = normalizeCallNames(options.callNames)
   const occurrences: MessageOccurrence[] = []
@@ -81,6 +82,7 @@ export function scanSource(source: string, options: ScanOptions = {}): MessageOc
   return occurrences
 }
 
+/** 去除空调用名和重复项，并优先匹配更长的名称；未配置时使用 tr。 */
 function normalizeCallNames(callNames: readonly string[] | undefined): string[] {
   const names = callNames ?? ['tr']
   return [...new Set(names.filter((name) => name.length > 0))].sort(
@@ -88,6 +90,7 @@ function normalizeCallNames(callNames: readonly string[] | undefined): string[]
   )
 }
 
+/** 检查候选调用名的两侧，避免把较长标识符中的片段识别为翻译函数。 */
 function hasIdentifierBoundaries(source: string, index: number, callName: string): boolean {
   const firstCharacter = callName[0]
   const lastCharacter = callName[callName.length - 1]
@@ -101,6 +104,7 @@ function hasIdentifierBoundaries(source: string, index: number, callName: string
   )
 }
 
+/** 判断字符是否可以继续组成 JavaScript 标识符，兼容 Unicode 连接字符。 */
 function isIdentifierContinue(character: string | undefined): boolean {
   return (
     character !== undefined &&
@@ -110,6 +114,7 @@ function isIdentifierContinue(character: string | undefined): boolean {
   )
 }
 
+/** 从指定位置跳过空白字符，返回下一个非空白字符的索引。 */
 function skipWhitespace(source: string, startIndex: number): number {
   let index = startIndex
   while (index < source.length && whitespacePattern.test(source[index] ?? '')) {
@@ -118,6 +123,7 @@ function skipWhitespace(source: string, startIndex: number): number {
   return index
 }
 
+/** 解析引号包裹的静态词条并还原转义；未闭合、非法换行或包含模板插值时返回 undefined。 */
 function parseString(
   source: string,
   startIndex: number,
@@ -157,6 +163,7 @@ function parseString(
   return undefined
 }
 
+/** 解析反斜杠后的字符转义、续行和 Unicode 转义，返回解码结果与后续扫描位置。 */
 function parseEscape(source: string, slashIndex: number): ParsedEscape | undefined {
   const escaped = source[slashIndex + 1]
   if (escaped === undefined) {
@@ -208,6 +215,7 @@ function parseEscape(source: string, slashIndex: number): ParsedEscape | undefin
   return { value: escaped, nextIndex: slashIndex + 2 }
 }
 
+/** 解码指定长度的十六进制转义；位数不足或包含非十六进制字符时返回 undefined。 */
 function parseFixedHexEscape(
   source: string,
   slashIndex: number,
@@ -226,6 +234,7 @@ function parseFixedHexEscape(
   }
 }
 
+/** 解码花括号包裹的 Unicode 码点，并拒绝缺失括号或超出 Unicode 范围的值。 */
 function parseCodePointEscape(source: string, slashIndex: number): ParsedEscape | undefined {
   const digitsStart = slashIndex + 3
   const closingBraceIndex = source.indexOf('}', digitsStart)
@@ -249,6 +258,7 @@ function parseCodePointEscape(source: string, slashIndex: number): ParsedEscape
   }
 }
 
+/** 收集每行起始偏移，兼容 LF、CRLF 和 CR 换行。 */
 function collectLineStarts(source: string): number[] {
   const starts = [0]
 
@@ -266,6 +276,7 @@ function collectLineStarts(source: string): number[] {
   return starts
 }
 
+/** 使用二分查找将字符偏移转换为从 1 开始的行号与列号。 */
 function locatePosition(
   lineStarts: readonly number[],
   index: number,

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/src/sync.ts

@@ -58,6 +58,7 @@ const defaultFormat: CatalogFormat = {
   trailingEol: true,
 }
 
+/** 校验并计算单个语言包的词条差异，按 dryRun 选项决定是否写入并返回变更报告。 */
 export async function syncCatalog(options: SyncCatalogOptions): Promise<SyncFileReport> {
   const keys = normalizeKeys(options.keys)
   const plan = await planCatalog(options, keys)
@@ -69,6 +70,7 @@ export async function syncCatalog(options: SyncCatalogOptions): Promise<SyncFile
   return plan.report
 }
 
+/** 先校验项目内全部语言包，再按需并行写入各文件；写入原子性以单文件为单位。 */
 export async function syncProject(options: SyncProjectOptions): Promise<SyncFileReport[]> {
   const keys = normalizeKeys(options.keys)
   const plans = await Promise.all(
@@ -97,6 +99,7 @@ export async function syncProject(options: SyncProjectOptions): Promise<SyncFile
   return plans.map((plan) => plan.report)
 }
 
+/** 读取语言包并生成保留翻译的增删计划；拒绝相对路径及未经允许的空扫描清理。 */
 async function planCatalog(
   options: SyncCatalogOptions,
   keys: ReadonlySet<string>,
@@ -145,6 +148,7 @@ async function planCatalog(
   }
 }
 
+/** 读取并校验扁平字符串语言包，同时记录原格式；文件缺失时返回空词条与默认格式。 */
 async function readCatalog(path: string): Promise<CatalogState> {
   let source: string
 
@@ -197,6 +201,7 @@ async function readCatalog(path: string): Promise<CatalogState> {
   }
 }
 
+/** 检测语言包的 BOM、换行符、缩进和末尾换行，以便写回时沿用。 */
 function detectFormat(source: string): CatalogFormat {
   const bom = source.startsWith('\uFEFF')
   const json = bom ? source.slice(1) : source
@@ -212,6 +217,7 @@ function detectFormat(source: string): CatalogFormat {
   }
 }
 
+/** 按照检测到的文件格式序列化词条，恢复 BOM、换行符和末尾换行。 */
 function serializeCatalog(messages: Record<string, string>, format: CatalogFormat): string {
   const serialized = JSON.stringify(messages, undefined, format.indent) ?? '{}'
   const withEol = format.eol === '\n' ? serialized : serialized.split('\n').join(format.eol)
@@ -220,6 +226,7 @@ function serializeCatalog(messages: Record<string, string>, format: CatalogForma
   return format.bom ? `\uFEFF${withTrailingEol}` : withTrailingEol
 }
 
+/** 先写入同目录临时文件，再重命名替换目标；失败时尝试清理临时文件并传播异常。 */
 async function writeAtomic(path: string, content: string): Promise<void> {
   const directory = dirname(path)
   const temporaryPath = join(directory, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`)
@@ -235,6 +242,7 @@ async function writeAtomic(path: string, content: string): Promise<void> {
   }
 }
 
+/** 将扫描词条去重，并在包含非字符串键时抛出 TypeError。 */
 function normalizeKeys(keys: Iterable<string>): ReadonlySet<string> {
   const normalized = new Set<string>()
 
@@ -249,18 +257,22 @@ function normalizeKeys(keys: Iterable<string>): ReadonlySet<string> {
   return normalized
 }
 
+/** 按字符串比较顺序原地排序词条，使报告顺序不依赖运行环境的语言设置。 */
 function sortKeys(keys: string[]): string[] {
   return keys.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
 }
 
+/** 判断错误是否带有可读取的文件系统错误码。 */
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
   return error instanceof Error && 'code' in error
 }
 
+/** 将未知异常转换为可输出的错误文本。 */
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+/** 生成语言包校验错误中的值类型描述，单独区分 null 和数组。 */
 function valueType(value: unknown): string {
   if (value === null) {
     return 'null'

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/test/command.test.ts

@@ -189,6 +189,7 @@ describe('runCli', () => {
   })
 })
 
+/** 在测试根目录写入 ESM 配置，声明源码扫描规则、两种语言包及同步报告路径。 */
 async function writeConfig(root: string): Promise<void> {
   await writeFile(
     join(root, 'i18n.config.mjs'),

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/test/temporary-directory.ts

@@ -4,6 +4,11 @@ import { join } from 'node:path'
 
 import { afterEach, beforeEach } from 'vite-plus/test'
 
+/**
+ * 注册测试生命周期钩子，在每个用例开始前创建独立临时目录，结束后递归清理其中的文件。
+ *
+ * @returns 通过 getter 动态读取当前用例目录路径的对象。
+ */
 export function useTemporaryDirectory(): { readonly path: string } {
   let path = ''
 

package/template-vp-monorepo-react-nestjs/packages/i18n/core/src/format.ts

@@ -1,5 +1,6 @@
 export type MessageValues = Record<string, string | number>
 
+/** 替换消息中的 `{key}` 占位符；未提供对应值时保留原占位符。 */
 export function formatMessage(message: string, values?: MessageValues): string {
   if (!values) return message
 

package/template-vp-monorepo-react-nestjs/packages/i18n/core/src/i18n.ts

@@ -13,6 +13,11 @@ import type {
 
 const emptyMessageLoader: LoadMessages = async () => undefined
 
+/**
+ * 创建国际化状态容器，提供翻译、异步切换语言和可选的语言偏好持久化。
+ * 接收初始语言和词条，以及可选的词条加载器、存储与存储键。
+ * @returns 可被 React 或 Vue 适配层订阅的国际化容器。
+ */
 export const createI18n = ({
   locale,
   message = {},
@@ -24,8 +29,10 @@ export const createI18n = ({
     {
       locale,
       message,
+      /** 使用当前词条翻译并插值；词条缺失时回退到原始键。 */
       tr: (key: string, values?: MessageValues): string =>
         formatMessage(store.getState().message[key] ?? key, values),
+      /** 加载目标语言后更新状态；加载失败时记录警告并切换为空词条。 */
       loadLocale: async (nextLocale) => {
         let nextMessages: Messages = {}
         try {
@@ -40,6 +47,7 @@ export const createI18n = ({
         }))
       },
     },
+    /** 状态变化后持久化当前语言，供下次初始化恢复偏好。 */
     ({ newState }) => {
       if (storage && storageKey) storage.setItem(storageKey, newState.locale)
     },
@@ -48,6 +56,11 @@ export const createI18n = ({
   return store
 }
 
+/**
+ * 优先恢复持久化的语言偏好，加载首屏词条后创建国际化容器。
+ * @param options 默认语言、词条加载器和可选的持久化配置。
+ * @returns 完成初始词条加载的容器；加载失败时使用空词条。
+ */
 export async function initI18n(options: I18nInitOptions = {}): Promise<I18nStore> {
   const { storageKey, storage, locale: defaultLocale, loaderMessage } = options
   const loadMessages = loaderMessage ?? emptyMessageLoader
@@ -67,6 +80,7 @@ export async function initI18n(options: I18nInitOptions = {}): Promise<I18nStore
 export const createI18nStore = createI18n
 
 export class i18n {
+  /** 保留类式初始化入口，等待初始语言加载完成后返回容器。 */
   static init(options?: I18nInitOptions): Promise<I18nStore> {
     return initI18n(options)
   }

package/template-vp-monorepo-react-nestjs/packages/i18n/core/src/storage.ts

@@ -10,7 +10,13 @@ export interface JsonStorage {
   removeItem: (key: string) => void
 }
 
+/**
+ * 为字符串存储添加 JSON 序列化，并隔离存储访问和序列化异常。
+ * @param storage 可选的底层存储；未传入时读取为空、写入无操作。
+ * @returns 读取失败时清理对应缓存并返回 `null` 的存储适配器。
+ */
 export const createJsonStorage = (storage?: StateStorage): JsonStorage => {
+  /** 尝试移除指定缓存，忽略底层存储异常以免中断页面渲染。 */
   const removeItem = (key: string) => {
     try {
       storage?.removeItem(key)
@@ -20,6 +26,7 @@ export const createJsonStorage = (storage?: StateStorage): JsonStorage => {
   }
 
   return {
+    /** 解析缓存 JSON；缓存缺失返回 `null`，读取或解析异常时尝试清理缓存。 */
     getItem: <T>(key: string) => {
       try {
         const value = storage?.getItem(key)
@@ -30,6 +37,7 @@ export const createJsonStorage = (storage?: StateStorage): JsonStorage => {
         return null
       }
     },
+    /** 写入序列化后的值；结果为 `undefined` 时删除缓存，异常时忽略此次写入。 */
     setItem: <T>(key: string, value: T) => {
       try {
         const json = JSON.stringify(value)

package/template-vp-monorepo-react-nestjs/packages/i18n/core/src/store.ts

@@ -6,6 +6,7 @@ export interface Store<T extends object> {
   subscribe: (listener: StoreListener) => () => void
 }
 
+/** 比较对象的可枚举字符串键数量与对应值；非对象输入返回 `false`。 */
 export const shallowEqualObject = <T>(a: T, b: T): boolean => {
   if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
     return false
@@ -20,6 +21,12 @@ export const shallowEqualObject = <T>(a: T, b: T): boolean => {
   return aKeys.every((key) => Object.is(a[key as keyof T], b[key as keyof T]))
 }
 
+/**
+ * 创建可订阅的内存状态容器，仅在浅比较发现变化时通知订阅者。
+ * @param initState 初始状态。
+ * @param onChange 状态提交后、订阅者通知前执行的回调。
+ * @returns 提供状态读取、函数式更新和取消订阅能力的容器。
+ */
 export function createStore<T extends object>(
   initState: T,
   onChange: ({ newState, oldState }: { newState: T; oldState: T }) => void,
@@ -29,6 +36,7 @@ export function createStore<T extends object>(
 
   return {
     getState: () => state,
+    /** 通过更新函数计算新状态，跳过浅相等结果，并同步通知变更。 */
     setState: (updater) => {
       const oldState = state
       const newState = updater(oldState)
@@ -38,6 +46,7 @@ export function createStore<T extends object>(
       onChange({ newState, oldState })
       for (const listener of listeners) listener()
     },
+    /** 注册状态变化监听器，返回移除该监听器的清理函数。 */
     subscribe: (listener) => {
       listeners.add(listener)
       return () => {

package/template-vp-monorepo-react-nestjs/packages/i18n/react/src/index.tsx

@@ -10,6 +10,10 @@ export interface I18nProviderProps {
 
 export const I18nContext = createContext<I18nStore | undefined>(undefined)
 
+/**
+ * 订阅最近的国际化上下文，返回翻译方法、语言切换方法和当前语言。
+ * @throws 未被 `I18nProvider` 包裹时抛出错误。
+ */
 export const useI18n = () => {
   const store = useContext(I18nContext)
   if (!store) throw new Error('useI18n must be used within I18nProvider')
@@ -18,6 +22,7 @@ export const useI18n = () => {
   return { tr, loadLocale, locale }
 }
 
+/** 向子组件提供指定的国际化容器，允许不同子树使用独立的语言状态。 */
 export const I18nProvider = ({ children, store }: I18nProviderProps) => {
   return <I18nContext.Provider value={store}>{children}</I18nContext.Provider>
 }

package/template-vp-monorepo-react-nestjs/packages/i18n/react/src/use-store.ts

@@ -1,8 +1,11 @@
 import { useSyncExternalStore } from 'react'
 import type { I18nState, I18nStore } from '@bubblesjs/i18n-core'
 
+/** 订阅国际化容器，并返回选择器提取的状态。 */
 export function useI18nStore<T>(store: I18nStore, selector: (state: I18nState) => T): T
+/** 订阅国际化容器，并返回完整状态。 */
 export function useI18nStore(store: I18nStore): I18nState
+/** 将外部容器订阅接入 React，根据选择器返回状态片段或完整快照。 */
 export function useI18nStore<T>(
   store: I18nStore,
   selector?: (state: I18nState) => T,

package/template-vp-monorepo-react-nestjs/packages/i18n/vue/src/index.ts

@@ -30,12 +30,18 @@ export const I18nProvider = defineComponent({
       required: true,
     },
   },
+  /** 为后代组件注入国际化容器，并原样渲染默认插槽。 */
   setup(props, { slots }) {
     provide(I18nKey, props.store)
     return () => slots.default?.()
   },
 })
 
+/**
+ * 订阅注入的国际化容器，提供始终读取最新词条的翻译和语言切换方法。
+ * @returns 翻译方法、异步语言切换方法和响应式语言引用。
+ * @throws 未被 `I18nProvider` 包裹时抛出错误。
+ */
 export function useI18n(): UseI18nReturn {
   const store = inject(I18nKey)
   if (!store) throw new Error('useI18n must be used within I18nProvider')

package/template-vp-monorepo-react-nestjs/packages/i18n/vue/src/use-store.ts

@@ -2,8 +2,11 @@ import { computed, onScopeDispose, shallowRef } from 'vue'
 import type { ComputedRef, ShallowRef } from 'vue'
 import type { I18nState, I18nStore } from '@bubblesjs/i18n-core'
 
+/** 订阅国际化容器，并以计算属性返回选择器提取的状态。 */
 export function useI18nStore<T>(store: I18nStore, selector: (state: I18nState) => T): ComputedRef<T>
+/** 订阅国际化容器，并以浅引用返回完整状态。 */
 export function useI18nStore(store: I18nStore): ShallowRef<I18nState>
+/** 将容器状态接入 Vue 响应系统，并在当前作用域销毁时自动取消订阅。 */
 export function useI18nStore<T>(
   store: I18nStore,
   selector?: (state: I18nState) => T,

package/template-vp-monorepo-react-nestjs/packages/shared/package.json

@@ -30,7 +30,11 @@
   },
   "scripts": {
     "dev": "vp pack --watch",
-    "build": "vp pack"
+    "build": "vp pack",
+    "test": "vp test"
+  },
+  "dependencies": {
+    "zod": "catalog:"
   },
   "devDependencies": {
     "typescript": "catalog:",

package/template-vp-monorepo-react-nestjs/packages/shared/src/index.ts

@@ -1,13 +1,2 @@
-export type {
-  ApiErrorDetail,
-  ApiFailure,
-  AuthUser,
-  CurrentUser,
-  LoginRequest,
-  LoginResult,
-  LogoutResult,
-  RegisterRequest,
-  RegisterResult,
-  SessionTerminalType,
-} from './types'
-export { ACCOUNT_PATTERN, isSessionTerminal, normalizeAccount, SESSION_TERMINALS } from './utils'
+export type * from './types'
+export * from './utils'

package/template-vp-monorepo-react-nestjs/packages/shared/src/types/access-maintenance.ts

@@ -0,0 +1,68 @@
+import type { AccessScope, PageQuery, UserSummary } from './access'
+
+export interface CleanupPreviewItem {
+  permissionKey: string
+  title: string
+  menuIds: string[]
+  roleCount: number
+  blockedReasons: string[]
+}
+
+export interface CleanupPreview {
+  catalogVersion: string
+  deploymentId: string | null
+  proofDigest: string | null
+  eligible: boolean
+  blockedReasons: string[]
+  items: CleanupPreviewItem[]
+  totals: {
+    permissions: number
+    menus: number
+    roleAssignments: number
+  }
+}
+
+export interface CleanupRequest {
+  permissionKeys: string[]
+  proofDigest: string
+}
+
+export interface CleanupResult {
+  removedPermissionKeys: string[]
+  alreadyCleanedPermissionKeys: string[]
+  removedMenuCount: number
+  removedRoleAssignmentCount: number
+}
+
+export interface DeploymentServiceVersion {
+  version: string
+  instanceIds: string[]
+  requiredPermissionKeys: string[]
+}
+
+export interface DeploymentProof {
+  deploymentId: string
+  completed: true
+  verifiedAt: string
+  expiresAt: string
+  serviceVersions: DeploymentServiceVersion[]
+}
+
+export interface AuditRecord {
+  id: string
+  actor: UserSummary
+  scope: AccessScope
+  action: string
+  objectType: string
+  objectId: string
+  summary: Record<string, string | number | boolean | null | string[]>
+  requestId: string
+  createdAt: string
+}
+
+export interface AuditQuery extends PageQuery {
+  action?: string
+  actorId?: string
+  from?: string
+  to?: string
+}

package/template-vp-monorepo-react-nestjs/packages/shared/src/types/access-menus.ts

@@ -0,0 +1,94 @@
+import type { AccessScope, EntityStatus, ScopeType, UserSummary, VersionRequest } from './access'
+
+export type MenuNodeType = 'directory' | 'page' | 'operation'
+
+export interface MenuNode {
+  id: string
+  scopeType: ScopeType
+  parentId: string | null
+  type: MenuNodeType
+  name: string
+  icon: string
+  sort: number
+  hidden: boolean
+  status: EntityStatus
+  routeKey: string | null
+  permissionKey: string | null
+  protected: boolean
+  children: MenuNode[]
+}
+
+export interface AccessContext {
+  user: UserSummary
+  scope: AccessScope
+  administrator: ScopeType | null
+  permissionKeys: string[]
+  menus: MenuNode[]
+  menuVersion: number
+  catalogVersion: string
+}
+
+export interface MenuTreeResult {
+  scopeType: ScopeType
+  version: number
+  items: MenuNode[]
+}
+
+export interface PermissionDefinition {
+  key: string
+  scopeType: ScopeType
+  kind: 'page' | 'operation'
+  title: string
+  routeKey: string
+  pagePermissionKey: string | null
+  adminOnly: boolean
+  deprecated: boolean
+}
+
+export interface PermissionTreeResult {
+  catalogVersion: string
+  items: MenuNode[]
+  permissions: PermissionDefinition[]
+  grantablePermissionKeys: string[]
+}
+
+export interface AccessPageDefinition {
+  scopeType: ScopeType
+  routeKey: string
+  path: string
+  title: string
+  permissionKey: string
+  icon: string
+  operationKeys: string[]
+}
+
+export interface CreateMenuRequest extends VersionRequest {
+  parentId: string | null
+  type: MenuNodeType
+  name: string
+  icon?: string
+  sort?: number
+  hidden?: boolean
+  status?: EntityStatus
+  routeKey?: string
+  permissionKey?: string
+}
+
+export interface UpdateMenuRequest extends VersionRequest {
+  parentId?: string | null
+  name?: string
+  icon?: string
+  sort?: number
+  hidden?: boolean
+  status?: EntityStatus
+}
+
+export interface FunctionCatalogResult {
+  catalogVersion: string
+  items: PermissionDefinition[]
+}
+
+export interface FilterSupportedAccessMenusInput {
+  menus: readonly MenuNode[]
+  supportedRouteKeys: Iterable<string>
+}