@composy/kit

@composy/kit 是 LDesign 工具链的公共能力集合，面向 Node.js、CLI、构建脚本、仓库自动化和内部平台包。它把文件系统、压缩归档、Git、缓存、日志、校验、配置、进程、包管理、SSL、项目探测和通用工具函数按模块拆分，方便按需导入和复用。

特性

• 按能力拆分源码目录，根入口和子路径入口都可使用。
• 使用 TypeScript 严格类型维护公共 API。
• 默认通过 @composy/pack 零配置构建，不需要包内 tsup 配置即可产出 ESM、CJS 和 .d.ts。
• 统一的 manager、utils、types 组合式 API，适合被 tools/*、packages/* 和业务脚本复用。
• 保留可脚本化、CI/headless 友好的同步和异步接口。

安装

pnpm add @composy/kit

要求：

• Node.js >=16
• 推荐 TypeScript >=5

快速开始

import { CacheManager, FileSystem, Logger, PackageUtils, StringUtils } from '@composy/kit'

await FileSystem.ensureDir('tmp')

const slug = StringUtils.slugify('LDesign Kit Demo')
const logger = Logger.create({
  level: 'info',
  transports: [{ type: 'console' }],
})

logger.info('kit ready', { slug })

const cache = CacheManager.create()
await cache.set(slug, { ready: true })

const packageName = PackageUtils.parsePackageName('@composy/[email protected]')
console.log(packageName)

子路径导入

import { FileSystem } from '@composy/kit/filesystem'
import { Logger } from '@composy/kit/logger'
import { PackageUtils } from '@composy/kit/package'
import { ValidationRules, Validator } from '@composy/kit/validation'

模块清单

• archive：归档创建、解压、ZIP/TAR 管理。
• builder：Vite/Rollup 兼容构建器、构建结果格式化和配置工具。
• cache：内存缓存、文件缓存、缓存管理器、统计信息。
• cli：命令解析、输出格式化、交互式命令辅助。
• config：配置加载、缓存、监听、Schema 校验。
• console：控制台主题、进度条、任务进度。
• database：连接池、事务、迁移、查询构建。
• events：事件总线、事件中间件、增强事件发射器。
• filesystem：文件读写、目录遍历、glob、路径辅助、文件监听。
• git：仓库状态、分支、提交、远端和差异操作。
• iconfont：SVG 到 IconFont 的批量转换和资源生成。
• logger：控制台、文件、自定义 transport、批量日志和子日志器。
• network：HTTP 客户端、服务端、请求构建和响应处理。
• notification：系统通知封装。
• package：package.json、依赖、脚本、版本和包信息工具。
• performance：性能采样、监控和基准测试。
• process：命令执行、守护进程、服务管理。
• project：项目类型、构建工具、包管理器和依赖探测。
• scaffold：脚手架、模板、插件、环境管理。
• ssl：密钥对、CSR、证书、指纹和证书强度分析。
• utils：字符串、数字、数组、对象、日期、网络、安全等通用工具。
• validation：规则校验、Schema 校验、表单校验和通用 Validator。

本轮补强的 API

Logger

const logger = Logger.create({
  level: 'debug',
  format: 'json',
  transports: [
    { type: 'console' },
    { type: 'file', filename: 'logs/app.log' },
    {
      type: 'custom',
      write(message) {
        process.stdout.write(`${message}\n`)
      },
    },
  ],
})

const child = logger.child({ module: 'auth' })
child.info('login success', { userId: 1 })

支持能力：

• Logger.create(options) 和 Logger.create(name, options)。
• console、file、rotating-file、custom transport 描述式配置。
• metadata、子日志器继承、JSON/text/custom formatter。
• async、batchSize、batchTimeout。
• Logger.getDefault() 默认实例。

FileSystem

const data = await FileSystem.readFile<{ name: string }>('package.json', 'json')
await FileSystem.writeFile('tmp/data.json', data, 'json')

const files = await FileSystem.readDir('src', { recursive: true, filter: 'files' })
const matched = await FileSystem.glob('src/**/*.{ts,tsx}', { cwd: process.cwd() })

readDir() 返回 FileInfo[]，stat() 返回带 isFile、isDirectory、createdAt、modifiedAt 的普通对象，便于声明文件稳定输出。

PackageUtils

PackageUtils.parsePackageName('@types/[email protected]')
PackageUtils.satisfiesRange('1.2.3', '^1.0.0')
await PackageUtils.detectPackageManager(process.cwd())
await PackageUtils.getPackageInfo('lodash')

Validation

Validator 支持部分对象校验：非空对象只校验实际出现的字段，空对象仍会触发 required 规则。这样同一个 Validator 可以同时服务 create、update 和 patch 输入。

SSL

SSLManager 提供 generateCSR() 兼容方法，证书指纹默认返回原始 hex 字符串，证书强度分析会识别 md5WithRSAEncryption、sha1With... 这类复合算法名。

构建与验证

pnpm run type-check
pnpm run test:run
pnpm run build
pnpm exec pack verify

当前构建脚本：

{
  "build": "pnpm run build:raw && pnpm run build:verify",
  "build:raw": "pack build",
  "build:verify": "pack verify",
  "build:watch": "pack build --watch"
}

pack build 会自动读取 package.json、src/index.ts 和子模块入口，输出：

• dist/**/*.js：ESM
• dist/**/*.cjs：CommonJS
• dist/**/*.d.ts：类型声明

目录结构

src/
  archive/
  builder/
  cache/
  cli/
  config/
  console/
  database/
  events/
  filesystem/
  git/
  iconfont/
  logger/
  network/
  notification/
  package/
  performance/
  process/
  project/
  scaffold/
  ssl/
  types/
  utils/
  validation/

维护约定

• 公共 API 需要显式类型或稳定的返回结构。
• 新能力优先放在对应模块或公共工具层，不在调用方重复实现。
• 构建统一走 @composy/pack，不为工具包新增平行 bundler 链路。
• 新增用户可见 API 后同步 README、docs 或 examples。

License

MIT

Registry API

@composy/kit/registry provides a lightweight capability registry for tools that need to discover or lazy-load Kit modules without importing the full root entrypoint.

import {
  listKitModules,
  loadKitModule,
  resolveKitModuleName,
  searchKitModules,
} from '@composy/kit/registry'

const modules = listKitModules({ category: 'automation' })
const filesystemName = resolveKitModuleName('fs')
const redisMatches = searchKitModules('redis')
const utils = await loadKitModule('utils')

console.log(modules.map(module => module.name))
console.log(filesystemName, redisMatches[0]?.descriptor.name)
console.log(utils.StringUtils.camelCase('kit-registry'))

Use this entrypoint for CLIs, scaffold generators, documentation pages, and plugin systems that need stable module metadata plus on-demand module namespaces.

通过 @composy/cli 统一接入

接入类型：helper 统一命令：ldesign kit 命令别名：无 包内原生 bin：无独立 bin 当前包通过 helper 方式接入，统一命令会调用 @composy/cli 内置封装。

pnpm add -D @composy/cli
ldesign kit --help
ldesign tools run kit --help