npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@composy/pack

v0.0.2

Published

Shared tsup presets, CLI workflow, and post-build tooling for LDesign packages

Readme

第六轮:后端真实运行统计、内存门禁、产物体积预算(2026-10)

本轮所有附加能力均为 opt-in:正常 pack build、pack analyze(无预算)仍保持原有行为。构建监控的是 Node 子进程,不是父进程的 process.memoryUsage()。

# 单次后端调用的真实墙钟耗时,Linux 下同时输出采样进程树峰值 RSS
pack build --no-version-prompt --profile

# Linux 专属:采样 RSS 超过 512 MiB 时终止整个后端进程组,退出码为 125
pack build --no-version-prompt --max-rss 512
PACK_MAX_RSS=512 pack build --no-version-prompt

# 产物大小门禁,超过预算返回退出码 1,JSON 含 passed/violations
pack analyze --out-dir dist --top 20 --max-bytes 1048576 --max-file-bytes 262144 --json
  • --profile:每次 tsup/tsdown 执行会打印 elapsed wall-clock 毫秒数;在 Linux 使用 /proc 对子进程树 RSS 约每 200ms 采样。数据不代表打包器内部的 transform/bundle/write 阶段耗时,也不是精确的内存高水位。其他操作系统可输出耗时,但 RSS 显示 unavailable。
  • --max-rss <MiB>:默认 0(关闭),仅支持 Linux,合法范围 0–1048576。RSS 是各进程驻留页之和,共享页可能重复计算;瞬时内存尖峰可能在采样间隔内发生,因此它不是 cgroup/容器级硬限制。无法可靠采样时采用保守失败方式,资源超限退出码 125,普通超时仍为 124。禁止与 --watch 组合使用。
  • 进程树发现优先使用 Linux task children 接口;受限容器中若该接口不可用,则按 /proc 进程 PPid 关系遍历(最多 20,000 个进程、512 个进程树节点)。监控是显式选择的,未启用时没有进程内存扫描开销。
  • --top 取值 1–100,--max-bytes 和 --max-file-bytes 为不超过 JS 安全整数的非负字节数。指定预算后,空产物目录判为不通过。产物门禁只检查发布目录现有文件,不重新构建,也不计算 gzip/brotli 压缩体积。
  • 开启 profile 或 RSS 预算时跳过 v4 增量缓存,以免因缓存命中绕过真正的资源测量。预算执行仍受原有包级构建锁保护。内存超限后的重试与 tsdown 自动回退被抑制,避免重复触发 OOM。
  • --profile/--max-rss 不支持 watch 中的单轮资源控制;真实 tsup/tsdown 测试仍需要完整工作区依赖。新增测试 src/build/round6.test.ts,CLI 冒烟验证了预算退出码和内存中断。

@composy/pack

LDesign 统一的 tsup 构建工作流工具包。

第五轮:中断恢复、产物体积分析与构建超时(2026-10)

本轮对上一轮显式启用的目录事务增加持久化 transaction.json。写入 staging、committing、committed、rolling-back、finalizing 等阶段;当进程被强制结束时,在取得包级锁并确认恢复目标后可保守恢复或清理。

# 只对调用 beginBuildOutputTransaction() 创建、带有效 journal 的事务生效
pack recover --out-dir dist
pack recover --out-dir dist --json

# 只读分析已有构建产物,无需启动 tsup/tsdown
pack analyze --out-dir dist
pack analyze --out-dir dist --json

# 对每一次后端执行限定最长 30 秒,默认 0(不限时)
pack build --no-version-prompt --timeout 30000
PACK_BACKEND_TIMEOUT=30000 pack build --no-version-prompt

pack recover 使用与 pack build 相同的包级构建锁,拒绝 src、.cache、.git 等受保护路径、符号链接和不确定的恢复状态。它绝不推测没有 journal 的临时目录属于自己;文件状态不一致时明确报错,保留文件供人工处理。程序化调用者也必须协调同一个锁,避免在仍活跃的 staging 会话上执行恢复。

pack analyze 仅报告已存在目录的总字节数、文件数、扩展名分布和最大的 10 个文件;不宣称能测得构建阶段耗时或子进程峰值内存。--timeout 是每次后端进程的墙钟时间限制,0 为禁用,最大 86,400,000 毫秒;超时返回退出码 124,在类 Unix 系统尽力终止其进程组并保留锁直至强制终止宽限期结束;不能与 --watch 同时使用。Windows 后代进程清理仍需要真实 Windows CI 验证。

仍需注意: 本 API 并未自动接入任意 tsup/tsdown 配置。journal 不是读者可见的原子目录交换;SIGKILL 中断后的可辨识状态已测试,但断电、磁盘写入丢失、跨主机共享盘一致性和文件系统损坏不保证恢复。请在完整仓库内运行真实双后端构建、官方 Vitest、ESLint 和发布检查。

新增回归位于 src/build/round5.test.ts,详细限制、测试记录和逐文件修改见 tools-tsup-config-第五轮深度优化与验证.md。

第四轮:可验证增量缓存与构建目录事务(2026-10)

显式增量缓存(CLI 已接入)

# 必须明确声明构建依赖和最终产物目录;可重复添加 --cache-input
pack build --no-version-prompt --cache --cache-input src --cache-input tsconfig.json --cache-output dist

# 自动配置、版本提示、并发锁与 JSON 计划仍保持原有功能
pack build --cache --cache-input src --cache-output dist --dry-run --json
  • 默认关闭,只有显式 --cache 才跳过构建。必须提供至少一个 --cache-input 和 --cache-output。指定的源文件/目录、构建配置文件、package.json、选定后端可执行文件、CLI 自身、环境变量及输出目录按 SHA-256 内容参与校验;不依赖 mtime,不存在仅因时间戳未变而错误命中的情况。
  • 命中要求上一次成功构建的输入哈希、输出哈希都一致,并且输出非空。文件增加、删除、修改、变更执行权限、符号链接和特殊文件都会触发失效或显式报错。缓存保存使用临时文件与同目录替换;构建过程中输入发生变化则拒绝保存缓存。
  • 遇到 watch、可能升级版本的构建、串行配置、清理/强制操作,以及启用自动回退的 tsdown,会保守地绕过缓存。进程级互斥继续由前一轮构建锁实现。
  • 使用者必须声明完整依赖:例如 tsconfig、额外配置、自动生成代码、代码生成参数、插件配置和 workspace 锁文件。缓存不能推断动态 import、任意插件访问、网络数据、未在包目录内的 monorepo 文件或外部服务变化。如果依赖无法完整声明,不要开启缓存。
  • 缓存是“验证过的跳过执行”,不是远端/离线产物恢复仓库。首次执行会发生全量哈希 I/O;对于体积巨大的构建产物,哈希时间可能高于执行时间,不承诺任意项目都有速度提升。

完整输出目录事务(程序化 API,未自动接入任意 CLI 配置)

import { beginBuildOutputTransaction } from '@composy/pack/build/outputTransaction'

const transaction = beginBuildOutputTransaction({ packageRoot: process.cwd(), outDir: 'dist' })
try {
  // 调用方必须把实际打包器的输出目录设置为 transaction.stagingDir。
  await runMyBundler({ outDir: transaction.stagingDir })
  transaction.commit()
  await verifyMyPublishedOutputs()
  transaction.finalize()
}
catch (error) {
  transaction.rollback()
  transaction.dispose()
  throw error
}

这组 API 将新构建写到独立临时目录,检查非空、符号链接和特殊文件;发布时将旧目录移入备份并替换为新目录。发布后验证失败可执行 rollback() 恢复旧目录;验证完成后执行 finalize() 清理备份。严禁指定 src/、bin/、.git/、.cache/、packages/ 等受保护的工程目录。直接使用 pack build 不会自动启用此 API,因为任意 tsup/tsdown 配置的 outDir、多配置和 onSuccess 回调尚无法安全强制重定向。

原子性边界: 同一磁盘的 rename 减少部分写入,但目录替换由多步操作构成,其他无锁读取者可能看到短暂空缺;SIGKILL、断电和多宿主共享盘的崩溃恢复仍未实现。必须在构建时持有包级锁并保证没有别的进程写同一目录,不能把它宣传为崩溃原子的事务提交。

新增测试文件 src/build/round4.test.ts;完整逐文件说明在 tools-tsup-config-第四轮深度优化与验证.md。

配置与目录结构

本包的权威工程配置集中在 .ldesign/:pack.config.ts 定义自身构建,eslint.config.js、 tsconfig.json 和 tsconfig.typecheck.json 分别维护 lint、构建类型与独立类型检查设置。 根目录保留的同名 ESLint/TypeScript 文件供 CLI、编辑器和既有脚本自动发现;TypeScript 入口只补充 包根相对的 rootDir 路径锚点,权威规则仍由 .ldesign/ 维护。源码仍位于 src/,不因配置归档改变源码布局。

它不是单纯的一组 preset,而是一套围绕包构建的完整能力集合:

  • 统一的 tsup preset
  • 可直接调用的 pack CLI
  • 无配置自动构建,常规 tools/* 包不再必须维护 .ldesign/pack.config.ts
  • 外部依赖、banner、输出扩展名等构建细节工具
  • src 多入口自动收集,避免每个工具包重复写递归扫描脚本
  • 构建后的复制、manifest、摘要与 Top Files
  • package.json 声明产物校验,防止 exports / bin 指向不存在文件
  • 面向 monorepo 的诊断与排障能力

为什么需要它

在多包仓库里,最常见的问题不是“不会打包”,而是“每个包都在重复写、重复改、重复排查”:

  • 每个包都维护一份高度相似的 tsup 配置
  • external、banner、shebang、outExtension 策略容易逐步漂移
  • 构建完成后还要复制文件、生成清单、看产物体积
  • 遇到 pnpm 链接异常、.bin 缺失、配置没找到时,排查路径长且重复

@composy/pack 的目标是把这些重复劳动统一抽到一处,并保持足够强的类型约束和可读性。

功能总览

1. 五个开箱即用的 preset

| preset | 适用场景 | 默认输出 | 关键特性 | | ---------------------- | ---------------- | ------------- | ---------------------------------------------------- | | defineLibraryConfig | 大多数通用库包 | esm + cjs | 平衡默认值、类型声明、统一 externals | | defineNodeConfig | 纯 Node 运行时包 | esm + cjs | 默认 target 更现代,并跳过可选 .node 原生文件 | | defineCliConfig | CLI 工具 | esm + cjs | 自动或显式识别 CLI 入口并注入 shebang | | defineBrowserConfig | 浏览器包 | esm | 强制 platform: 'browser',可选浏览器框架 externals | | defineAdvancedConfig | 复杂或多入口包 | 按配置决定 | 保留更多 tsup 原生控制能力 |

2. 统一构建基础设施

  • commonExternals、cliCommonExternals、browserCommonExternals
  • mergeExternals()
  • makeVersionBanner()、mergeBanner()、shebangBanner
  • outExtensionJsCjs
  • runOnSuccessHook()
  • runPostBuildTasks()
  • collectSourceEntries()
  • verifyPackageOutputs()
  • BuildProgressTracker

3. 统一 CLI 工作流

pack 内置五类能力:

  • pack build:解析配置并转发参数给默认构建后端 tsup;tsdown 仅在显式选择时使用,只有可识别的后端启动/配置加载错误才自动回退 tsup;源码编译失败直接报错
  • pack init:快速生成 .ldesign/pack.config.ts
  • pack inspect:查看最终解析到的包、配置与构建后端 CLI 路径
  • pack explain:解释配置查找和零配置推断结果,不执行构建
  • pack doctor:直接诊断配置缺失、构建后端链接异常和 .bin 问题

执行日志

每次 pack 命令都会在目标项目下创建完整执行日志:

.ldesign/.logs/pack/<ISO 时间>-<pid>.log

日志包含命令行、运行环境、构建后端输出、stderr、异常堆栈、退出码与耗时。常见的 token、密码、secret 与 API key 参数会自动脱敏;日志目录不可写时不会改变构建结果。pack run --tool <name> 会把指定命令及其全部子进程输出写入 .ldesign/.logs/<name>/,适用于声明生成、webview 编译等多阶段构建。

  • pack verify:检查 main、module、types、bin 与 exports 声明的文件是否存在

4. 统一产物整理

所有 preset 都能直接复用:

  • 构建后复制文件与目录
  • 生成 manifest
  • 打印构建摘要与 Top Files
  • 在非交互终端中自动退化输出

当前版本重点改进

这一版围绕“正确性、默认值一致性、可维护性”做了进一步收敛:

  • 修复 mergeBanner() 在函数 banner 场景下使用伪上下文的问题
  • 显式 packageRoot / callerDir 现在会优先于 npm_package_json
  • CLI shebang 注入改为按包根目录解析输出路径,避免多包仓库下写错位置
  • preset 不再粗暴覆盖显式 sourcemap / minify 配置
  • Node 内置模块 externals 规则改为基于 builtinModules 动态生成,覆盖子路径导入
  • 浏览器框架 externals 现在能识别 react/jsx-runtime、react-dom/client 等常见子路径
  • post-build 复制新增安全校验,避免把目录复制进自身子目录
  • 新增 collectSourceEntries(),用于统一构建 src 下所有运行时 TypeScript 文件
  • pack build 支持无配置自动推断:优先使用显式配置,没有配置时根据 package.json 与 src 生成临时 tsup config
  • 新增 pack verify / verifyPackageOutputs(),用于校验 package.json 声明产物
  • 零配置构建现在会从 package.json 的 main/module/exports/bin 推断 format 与输出目录,并从 engines.node 推断更合适的 Node target
  • pack verify --strict 可把“未声明任何发布产物”升级为失败;声明路径逃出包根或指向目录也会失败
  • 新增基于 dist/ 的本地自检脚本,能对关键行为做回归验证
  • CLI 源码入口收敛为 src/bin/pack.ts,库入口构建显式排除 src/bin
  • pack build 新增 --retry <count> 与 PACK_RETRY_ATTEMPTS,用于重试 Windows 环境里偶发的 spawn EPERM
  • package output 通配校验现在会缓存扫描目录,减少多条 exports 通配声明带来的重复 I/O
  • 控制台输出改为稳定的 key/value 面板、Top Files 摘要和 TTY/非 TTY 兼容样式

安装

pnpm add -D @composy/pack tsup

如果你在 monorepo 中使用 workspace 依赖,也可以直接这样写:

{
  "devDependencies": {
    "@composy/pack": "workspace:*"
  }
}

要求:

  • Node.js >= 18
  • 推荐在 type: module 项目中使用
  • 非 ESM 项目同样可使用,只要 tsup 配置和入口定义正确

30 秒快速开始

1. 添加脚本

{
  "scripts": {
    "build": "pack build",
    "dev": "pack build --watch"
  }
}

2. 执行构建

pnpm run build

常规工具包可以不写 .ldesign/pack.config.ts。pack build 会先查找显式配置;没有配置时,会根据 package.json、src/index.ts、src/**/*.ts、src/**/*.d.ts 和 package.json#bin 自动生成临时配置。默认仍输出 esm、cjs 和 d.ts 到 dist;如果 package.json 已经声明了 module、main、exports 或非 dist 输出目录,自动配置会优先贴合这些发布声明。其中 src/**/*.d.ts 只参与声明生成上下文,不会被当作 JS 运行时入口打包。

3. 只有特殊需求才创建配置

需要自定义 copy、external、platform、tsconfig、webview 构建或非 src 布局时,再生成配置:

pack init --template library

CLI 说明

pack build

普通交互终端在构建前会询问是否升级当前包版本。确认后可选择 patch、minor、major、预发布通道或输入完整 semver;构建成功后,当前 workspace 中依赖该包的子包会同步依赖版本,匹配的 pnpm catalog 与 lockfile 也会更新,并在当前包目录生成详细的 CHANGELOG.md。日志包含版本前后值、每个 workspace 消费方的依赖字段变更、catalog/lockfile 状态,以及 Git 提交分类、作者、提交哈希、Breaking Changes 和统计信息。构建、同步或日志写入失败时会恢复版本文件和已修改的 workspace 文件。

只有实际升级版本时才生成日志;未升级版本、--dry-run 和 --watch 不会写入 CHANGELOG.md。没有 Git 历史时会保留完整的版本事务摘要。

CI、脚本和其他非 TTY 环境不会阻塞询问;需要升级时显式传入 --version-bump patch|minor|major|alpha|beta|rc|<semver>,也可以使用 PACK_VERSION_BUMP。可用 --no-version-prompt、--no-workspace-update、--no-lockfile-update 关闭对应行为;子模块场景可用 --workspace-root <path|auto|local> 控制 workspace 边界。

自动向上查找配置文件;找不到配置时自动推断一份临时 tsup config,并把剩余参数透传给 tsup:

pack build
pack build --watch
pack build --minify
pack build --print-config
pack build --dry-run
pack build --retry 5

--dry-run 会完成配置解析和零配置推断,并输出实际会使用的配置路径;配合 --json 可用于 CI 或批量迁移脚本确认构建计划,但不会启动 tsup,也不会写入 dist。

零配置推断会尽量遵循 package.json:

  • module、exports.import 会启用 esm
  • main、exports.require 会启用 cjs
  • main/module/types/exports 指向 build/* 这类目录时,outDir 会跟随声明目录
  • engines.node 为 >=20 或 >=22 时,target 会提升到 node20 或 node22

--retry <count> 只针对瞬时 spawn EPERM 这类子进程启动失败生效。默认值在 Windows 上为 3,其他平台为 1;也可以通过 PACK_RETRY_ATTEMPTS=5 统一设置。

配置文件查找顺序:

  1. .ldesign/pack.config.ts
  2. .ldesign/pack.config.js
  3. .ldesign/pack.config.mjs
  4. pack.config.ts
  5. pack.config.js
  6. pack.config.mjs
  7. .ldesign/tsup.config.ts(兼容旧项目)
  8. .ldesign/tsup.config.js(兼容旧项目)
  9. .ldesign/tsup.config.mjs(兼容旧项目)
  10. tsup.config.ts(兼容旧项目)
  11. tsup.config.js(兼容旧项目)
  12. tsup.config.mjs(兼容旧项目)
  13. 无配置时,根据当前包自动生成临时配置

pack init

快速生成标准模板:

pack init --template library
pack init --template cli --entry src/cli.ts
pack init --template browser --out-dir build
pack init --template advanced --force

支持模板:

  • library
  • cli
  • node
  • browser
  • advanced

pack inspect

输出当前解析结果:

pack inspect
pack inspect --json
pack inspect --cwd packages/core
pack inspect --config tsup.config.ts

输出信息包括:

  • 当前工作目录
  • 最近解析到的包名与 package.json
  • 实际使用的配置文件
  • 配置来源:explicit、discovered 或 auto
  • tsup CLI 入口路径

pack explain

解释当前工作目录会如何解析构建配置,适合在大批量迁移到零配置 pack build 前做预检:

pack explain
pack explain --json
pack explain --cwd tools/runtime
pack explain --config .ldesign/pack.config.ts

当没有显式配置时,它会展示自动推断出来的库入口、CLI 入口、本地声明补充文件数量、输出格式、target 与 d.ts 设置;当存在显式配置时,它会明确标出配置来源,避免误以为正在走零配置路径。

pack doctor

用于快速定位“为什么当前包跑不起来”:

pack doctor
pack doctor --json

检查项包括:

  • 最近的 package.json
  • 可解析的 tsup 配置,或可推断的自动配置计划
  • tsup/package.json 是否可解析
  • node_modules/.bin/tsup 是否存在

在 pnpm workspace 里,如果 .bin 丢失,它会直接提示优先重建链接,而不是建议你先改脚本规避。

pack verify

用于在构建完成后校验 package.json 声明的产物路径:

pack verify
pack verify --json
pack verify --strict

它会检查:

  • main / module / types / typings
  • bin
  • exports 中的相对路径,包含 ./dist/build/*.js 这类通配路径

通配路径遵循文件系统 glob 的目录边界:单层 * 只匹配当前目录中的字符,递归 ** 可以跨越零层或多层目录。例如 ./dist/**/*.d.ts 同时支持 dist/index.d.ts 与 dist/types/index.d.ts;这能覆盖多层 exports 构建产物, 又不会让 ./dist/*.js 意外匹配到更深层目录。

缺失任意声明产物、声明路径逃出包根或声明路径指向目录时,命令会以非 0 状态退出,适合接在 build 后面作为发布前保护。默认情况下,未声明任何产物只会给出 warning;如果 CI 需要强制发布包必须声明 main/module/types/bin/exports,使用 pack verify --strict。

pack run

将一个多阶段命令包装为单份完整工具日志。命令字符串应放在 -- 后,以便 shell 负责阶段串联:

pack run --tool launcher -- "pnpm run build:raw && pnpm run build:types && pnpm run build:verify"

该命令会实时转发 stdout 和 stderr,记录每个阶段的完整输出与最终退出码;它不会改变原命令的执行目录或返回码。

Preset 详解

defineLibraryConfig

最适合大多数通用库包。

import { defineLibraryConfig } from '@composy/pack'

export default defineLibraryConfig({
  entry: ['src/index.ts'],
  manifest: true,
})

默认行为:

  • format: ['esm', 'cjs']
  • target: 'node18'
  • dts: true
  • clean: true
  • sourcemap 在开发环境默认开启
  • minify 默认关闭

defineNodeConfig

面向 Node 运行时工具库或服务端包。

import { defineNodeConfig } from '@composy/pack'

export default defineNodeConfig({
  copy: ['README.md'],
  entry: ['src/index.ts'],
  target: 'es2022',
})

额外特点:

  • 默认 target 更现代
  • 会跳过某些可选 .node 原生文件,降低跨平台构建失败概率

defineCliConfig

适合单入口或多入口 CLI。

import { defineCliConfig } from '@composy/pack'

export default defineCliConfig({
  cliEntry: 'pack',
  entry: {
    index: 'src/index.ts',
    pack: 'src/cli.ts',
  },
})

CLI preset 会额外处理:

  • 自动或显式识别 CLI 入口
  • 为对应 JS 产物注入 #!/usr/bin/env node
  • 当多入口又未明确指定 cliEntry 时,在摘要中给出 warning

defineBrowserConfig

适合浏览器端 SDK、工具包或轻量 runtime。

import { defineBrowserConfig } from '@composy/pack'

export default defineBrowserConfig({
  entry: ['src/index.ts'],
  useBrowserExternals: true,
})

特点:

  • 默认只输出 esm
  • 强制 platform: 'browser'
  • shims: false
  • 生产环境默认压缩

defineAdvancedConfig

适用于多入口、多平台或需要更细粒度覆盖 tsup 选项的场景。

import { defineAdvancedConfig } from '@composy/pack'

export default defineAdvancedConfig({
  entry: {
    index: 'src/index.ts',
    runtime: 'src/runtime.ts',
  },
  format: ['esm', 'cjs'],
  platform: 'node',
  summary: {
    artifactLimit: 6,
    topFiles: 12,
  },
})

高级 preset 不是为了隐藏 tsup,而是为了在保留 pack 统一体验的前提下,给你更多底层控制能力。

共享能力

构建后复制与 manifest

import { defineLibraryConfig } from '@composy/pack'

export default defineLibraryConfig({
  copy: [
    'README.md',
    {
      from: 'assets',
      to: 'assets',
    },
    {
      from: 'CHANGELOG.md',
      required: false,
    },
  ],
  manifest: {
    extra: {
      owner: 'platform-team',
    },
    fileName: '.ldesign-build.json',
  },
})

copy 支持:

  • 字符串简写
  • 文件与目录复制
  • 自定义目标路径
  • required: false 的软依赖文件

manifest 记录:

  • 包名、版本、模式
  • 输出目录
  • 构建耗时
  • 文件统计
  • 全部输出文件
  • 已复制产物列表

externals 复用

import { commonExternals, defineLibraryConfig, mergeExternals } from '@composy/pack'

export default defineLibraryConfig({
  external: mergeExternals(commonExternals, ['typescript']),
})

可直接复用:

  • commonExternals
  • cliCommonExternals
  • browserCommonExternals
  • browserFrameworkExternals
  • mergeExternals

banner 与输出扩展名策略

import {
  defineLibraryConfig,
  makeVersionBanner,
  mergeBanner,
  outExtensionJsCjs,
} from '@composy/pack'

export default defineLibraryConfig({
  banner: mergeBanner(
    { js: makeVersionBanner('@demo/core', '1.0.0') },
    { js: '/** custom banner */' }
  ),
  outExtension: outExtensionJsCjs,
})

进度与摘要

import { defineAdvancedConfig } from '@composy/pack'

export default defineAdvancedConfig({
  progress: {
    showCurrentFile: true,
    throttleMs: 100,
  },
  summary: {
    artifactLimit: 5,
    topFiles: 10,
  },
})

progress 支持:

  • false 关闭动态进度
  • throttleMs 控制刷新频率
  • showCurrentFile 控制是否展示当前处理文件

summary 支持:

  • false 关闭最终摘要
  • topFiles 控制 Top Files 数量
  • artifactLimit 控制复制产物预览条数
  • showArtifacts 与 showNotices 控制展示细节

包自身的构建与验证

本包自身通过 .ldesign/pack.config.ts 构建。

构建策略:

  • src/**/*.ts 会作为库入口参与构建
  • src/**/*.test.ts 与 src/**/*.spec.ts 会被显式排除
  • src/bin/pack.ts 由 CLI preset 单独构建到 dist/bin/pack.js
  • 最终同时产出 esm、cjs 与 d.ts

常用命令:

pnpm run type-check
pnpm run lint:check
pnpm run build
pnpm run test
pnpm run test:run
pnpm run verify

说明:

  • build 会生成当前包的 esm、cjs 与 d.ts 产物
  • build 结束后会自动执行 pack verify,确保 package.json 声明的产物全部存在
  • test 与 test:run 都会对当前 dist/ 产物执行自检;如果未先构建,会直接给出提示
  • quality:check / verify 串联 ESLint、类型检查、构建、package 产物校验与 dist 自检
  • format:check 保留为独立格式检查,不阻断发布产物验证链路

类型导出

你可以直接复用以下类型:

  • LibraryConfigOverrides
  • NodeConfigOverrides
  • CliConfigOverrides
  • BrowserConfigOverrides
  • AdvancedConfigOverrides
  • SharedPresetOverrides
  • ExternalMatcher
  • TsupPlugin
  • BuildManifest
  • BuildManifestOptions
  • PostBuildTasksResult
  • ProgressTrackerOptions
  • BuildSummaryOptions

更底层的封装能力也有导出:

  • createPresetRuntime
  • PresetRuntime
  • PresetDisplayMeta
  • PresetOnSuccessContext
  • WrapOnSuccessOptions

深度导入

默认推荐从根入口导入:

import { defineLibraryConfig } from '@composy/pack'

如果你确实需要深度导入,也支持:

import { commonExternals } from '@composy/pack/build/external'
import { printBuildSummary } from '@composy/pack/log/logger'
import { defineCliConfig } from '@composy/pack/preset/cli'

从 @composy/tsup-config 迁移

迁移要点:

  1. 包名改为 @composy/pack
  2. CLI 命令改为 pack
  3. 旧的 ldesign-tsup 工作流统一收敛到 pack
  4. CLI 产物入口改为 dist/bin/pack.js

示例:

- import { defineLibraryConfig } from '@composy/tsup-config'
+ import { defineLibraryConfig } from '@composy/pack'
- ldesign-tsup build
+ pack build

故障排查建议

  • 先看 pack doctor,再动脚本
  • 常规 tools/* 包优先尝试零配置 pack build
  • 只有存在特殊构建需求时,再把显式配置放到 .ldesign/pack.config.ts
  • 遇到 node_modules/.bin/tsup 缺失时,优先重建 pnpm 链接
  • 多入口 CLI 包请显式设置 cliEntry
  • Windows 沙箱或杀软环境偶发 spawn EPERM 时,优先使用 pack build --retry 5 或设置 PACK_RETRY_ATTEMPTS
  • 如果你显式传了 sourcemap 或 minify,preset 现在会保留你的配置,不再强制覆盖

License

MIT

通过 @composy/cli 统一接入

  • 接入类型:bin
  • 统一命令:ldesign tsup
  • 命令别名:tsup-config
  • 包内原生 bin:pack

当前包通过独立 bin 接入,统一命令会转发到包自身 CLI。

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

2026-10-10 源码补全与增强说明

上传的归档中缺少整个 src/build/ 目录及 .ldesign/ 核心配置。本次恢复这些模块,保留原有外部 API 和发布入口,但仍需在完整仓库安装依赖后复验 tsup、tsdown、Vitest 和 ESLint 的实际集成。

  • 类型安全和构建兼容:恢复全部 src/build/* 引用;新增可独立引导自身的 .ldesign/pack.config.ts;恢复 TypeScript / ESLint 配置。ESM 扩展名根据消费包 package.json.type 在 .js、.mjs 间选择,CJS 固定使用 .cjs。
  • 可解释的零配置:自动收集源入口、排除测试与声明文件,对重名入口主动失败;根据 bin 推断 CLI 入口,混合入口使用 defineCliConfig 并定向注入 shebang。通过 explain 查看 evidence、warnings,而无需写入文件。
  • 产物安全:verifyPackageOutputs 校验 main/module/types/bin/exports/browser 的产物路径;递归 ** 与单层 * 分离;拒绝路径逃逸和符号链接。copy 强制检查源/目标目录边界、拒绝递归复制。Manifest 原子替换、可选 SHA-256,并排除旧 Manifest 的自引用统计。
  • 性能:源目录和产物扫描使用迭代栈;Manifest 文件哈希使用固定 64 KiB 缓冲区,不因单个大型产物而将其整体加载到内存。子进程日志判错缓存仅保存最近 64 KiB,终端仍完整转发。
  • CLI 稳健性:-- 后参数不再被 pack 消费;支持 --key=value;数值参数拒绝非纯数字;inspect 在没有可选 tsdown 时保持可用;dry-run 不生成缓存配置;tsdown shim 在执行后清理。

可选 Manifest 哈希

import { defineLibraryConfig } from '@composy/pack'

export default defineLibraryConfig({
  entry: ['src/index.ts'],
  manifest: {
    fileName: '.ldesign-build.json',
    hashes: true,
    extra: { product: 'composy' },
  },
})

CLI 零配置与扩展名

  • 若包有 bin 并且源目录有可明确匹配的 src/bin/<name>.ts 或 src/cli/<name>.ts,自动配置启用 CLI 预设,并按入口应用 shebang。
  • 未声明 "type": "module" 的 Node 包,默认 ESM 输出为 .mjs、类型声明为 .d.mts;type=module 时使用 .js、.d.ts。请使 package.json exports 与实际输出一致,然后执行 pack verify --strict。
  • 对输出目录做复制、Manifest 等变更时,推荐在 CI 中启用 pack verify --strict,避免发布引用损坏。

第二轮可靠性增强(2026-10)

  • 复制事务:runPostBuildTasks({ copy, manifest }) 会先在输出目录的同一文件系统上暂存所有待复制文件,覆盖旧产物前创建备份,后续复制/Manifest 失败会恢复已有文件;成功后清除暂存。此功能不能替代整个构建目录的崩溃原子提交,暂存阶段也需要额外磁盘空间。
  • 安全路径:所有复制源、目标和 exports 检查均拒绝不安全的路径与符号链接祖先,避免跟随链接进入非预期目录。冲突的复制目标会在修改输出目录之前被拒绝。
  • 后端回退:--backend tsdown 仅在识别到启动、CLI/loader 不兼容等问题时才可能回退到 tsup。语法/类型/插件编译失败不会重试另一套打包器,避免浪费 CPU、内存和覆盖中间产物。使用 --no-fallback 可完全关闭。
  • 串行配置:--serial-configs N 支持异步配置函数并在请求的下标不存在时抛错;与 --watch 同时使用时给出明确提示。此行为不等于整个配置数组的预验证。
  • Manifest 完整性:扫描目录或读取文件元数据失败时,后处理会失败并撤销本轮复制,而不是静默生成缺失产物的 Manifest。大文件 SHA-256 继续使用固定大小缓冲区。

运行 pnpm run test:run 和 pnpm run typecheck 可在完整工作区验证;新增回归用例位于 src/build/round2.test.ts。双后端 ESM/CJS/DTS 的真实集成测试仍需在装有依赖的 CI 中执行。

第三轮:跨进程构建锁与严格发布产物验证(2026-10)

本轮新增的锁用于协调 通过 pack 启动的进程,不控制直接调用 tsup/tsdown 的其他工具,也不等同于完整构建目录的崩溃原子提交。

  • 同包构建互斥:pack build 在任何版本文件修改前创建 .cache/ldesign-pack/build.lock。同包的 watch 和普通构建不会同时写入相同输出目录。锁文件以独占创建和随机持有者标识实现,不按运行时间强制抢占仍存活的本机进程。
  • 工作区版本修改互斥:可能执行版本升级时(显式 --version-bump 或交互式版本确认),先取得工作区根目录的 .cache/ldesign-pack/workspace-version.lock,再获取包级锁。防止不同子包通过 pack 同时更新同一组 workspace package.json、catalog 或 lockfile;不修改版本的不同子包仍能并行构建。
  • 异常中断恢复:如果持有者本机 PID 已退出,经过短暂安全宽限期后可回收遗留锁;解析失败的陈旧锁也能在一定时间后恢复。远端机器上的锁不因时间过长而自动抢占,需运维人员确认并处理。
  • 严格产物检查:用于生成 Manifest 的严格扫描现在会拒绝符号链接、设备和其他非普通文件,避免产物清单静默漏报。对已有 copy 事务,扫描失败时会回滚复制操作。pack verify 的 wildcard 扫描也不再把权限错误伪装成产物不存在。
# 默认最多等待 30 秒;如已有构建,可选择立即失败或延长等待
pack build --lock-timeout 0
pack build --lock-timeout 120000
PACK_LOCK_TIMEOUT=60000 pack build

# 只分析而不执行构建,也不会获取构建锁或生成临时配置
pack build --dry-run --json

--lock-timeout 为毫秒,允许 0 至 600000。上述锁不覆盖进程被强制杀死时的整个 dist 回滚;也不能提供严格缓存命中、跨主机任意文件系统的一致性或替代 CI 中的真实双后端测试。新增回归用例见 src/build/round3.test.ts。

第七轮增强:事务构建、依赖调度、结构化报告

CLI 性能与生命周期日志

--report 是显式启用的构建执行报告,--event-log 是 JSONL 事件文件;两者不会修改原来的默认日志格式,也不会保存环境变量或后端 stdout/stderr。

pack build --no-version-prompt \
  --report .cache/ldesign-pack/latest-report.json \
  --event-log .cache/ldesign-pack/events.jsonl

pack report --json
pack report --file .cache/ldesign-pack/latest-report.json

报告记录实际耗时、真实子进程退出码、缓存状态和后端尝试次数。Linux 上 RSS 仅在启用 --profile 或 --max-rss 时有采样数据;未采样使用 null,不会虚构内存值或编译各阶段耗时。--report 写入错误只发出警告,不会使已经成功的构建被误报为失败。诊断路径必须位于当前工作目录内,不能穿越符号链接。

事务式构建 API(显式接入)

import { runTransactionalBuild } from '@composy/pack/build/buildPipeline'

await runTransactionalBuild({
  packageRoot: process.cwd(),
  outDir: 'dist',
  async build(stagingDir) {
    // 在此执行你能够确保“所有产物仅写入 stagingDir”的打包任务。
    // 此示例不默认修改任意第三方 tsup/tsdown 配置。
  },
  async verifyPublished(outputDir) {
    // 可选:检查发布后的公共输出目录;失败会回滚到旧目录。
  },
})

执行过程取得包级跨进程锁,并使用持久化 journal。对已存在、尚未恢复的事务采取拒绝继续而非自动清理策略,需要运行 pack recover --out-dir dist。两次目录重命名不是内核原子的目录交换,极端崩溃和断电仍有恢复边界。任意自定义插件可能写出 stagingDir,因此不会在默认 pack build 上不加验证地启用事务。

Monorepo 依赖 DAG 调度 API

import { runBuildGraph } from '@composy/pack/build/buildGraph'

const result = await runBuildGraph([
  { name: 'core', dependencies: [] },
  { name: 'ui', dependencies: ['core'] },
  { name: 'docs', dependencies: ['core'] },
], {
  concurrency: 2,
  build: async (name) => { /* 调用各包已有的构建流程 */ },
})

// result.statuses: { core: 'success', ui: 'success', docs: 'success' }

调度器会在执行前检查未知包、重复依赖与环,并在依赖失败时跳过下游节点,独立分支继续执行。build 回调负责实际构建与路径隔离;自第八轮起可通过 pack workspace 自动发现包并执行脚本;底层 DAG API 仍可独立使用。

类型化事件

import { createBuildEventHub, formatBuildEvent } from '@composy/pack/build/buildEvents'

const hub = createBuildEventHub(1000)
const unsubscribe = hub.on('*', event => console.log(formatBuildEvent(event, 'human')))
hub.emit('build:start', { backend: 'tsup' })
hub.emit('build:end', { status: 0 })
unsubscribe()

事件格式化支持 human、json、github;GitHub 注释中的换行和百分号会被转义。该接口仅用于仪表与审计;监听器异常不会改变构建结果。pack build 的事件文件记录已知的生命周期事件,无法提供打包后端未暴露的内部阶段数据。

第八轮:Monorepo Workspace 构建调度

pack workspace 可以直接读取仓库的 pnpm-workspace.yaml 或根 package.json 的 workspaces,生成由本地 dependencies、devDependencies、optionalDependencies 构成的构建 DAG;不会自动执行构建。

# 在 workspace 根目录或任意子包目录查询真实构建顺序
pack workspace --json

# 选择单个包,自动附带所依赖的工作区包
pack workspace --filter @composy/core

# 依赖优先、最多同时运行 4 个 npm build 脚本
pack workspace --execute --concurrency 4

# 指定脚本和包;先查看计划,再执行
pack workspace --filter @composy/launcher --script build --execute --dry-run
pack workspace --filter @composy/launcher --script build --execute

# CI 使用 JSON 汇总,失败退出码为 1
pack workspace --execute --json

行为约定:

  • 只解析安全的 glob 子集:*、**、! 排除规则。暂不支持花括号、字符类和复杂 YAML 写法;遇到不支持的格式直接报错,不会静默漏扫。
  • 相同工作区包名会报错;本地依赖循环会报错;显式 workspace: 引用但在工作区内找不到目标也会报错。支持 workspace:@scope/name@^ 别名与 workspace:../path 形式。
  • --filter 支持多次指定精确包名,自动追加传递依赖。没有声明脚本的目标包按失败处理,依赖它的包会跳过;独立包继续运行。
  • 不扫描 node_modules、.git、.cache、dist 等生成目录,不跟随符号链接。基于 glob 前缀裁剪目录,工作区目录和包数量受到保护性上限约束。
  • --execute 通过各包目录的 npm run <script> 启动子进程(继承 Node/npm 启动环境);--json 模式下子进程输出转向 stderr,标准输出保留为单个 JSON 结果;默认并行度为 2,最大 32。
  • --dry-run 在 --execute 模式下也只输出 DAG 计划,不运行 npm 脚本。这个调度器不具备受信任代码沙箱:脚本与插件仍拥有调用它们的用户权限。
  • 目前没有自动变更影响分析、分布式缓存、运行中子进程的硬取消,也没有将任意后端配置强制套入目录事务。优先在真实依赖工作区验证这些差异。

库 API 可使用 discoverWorkspaceGraph({ root, filter }) 和 findPackageWorkspaceRoot(start),随后将 graph.nodes 交给 runBuildGraph 的自定义回调。API 不会替调用者执行 npm 脚本或更改 package.json。

第九轮:Monorepo 可取消调度与逐包构建报告

pack workspace --execute 现在支持进程信号取消和准确的逐包构建遥测:

# 执行工作区构建,记录每个包的结果、执行时间与退出码
pack workspace --execute --concurrency 4 --workspace-report .cache/pack/workspace-report.json

# 标准输出保持可解析的 JSON,npm 输出转向标准错误流
pack workspace --execute --json --workspace-report .cache/pack/workspace-report.json
  • 收到 SIGINT(通常为 Ctrl+C)或 SIGTERM 后,不再调度新包;运行中的任务取消、尚未运行的节点标记为 cancelled,且等待清理结束后再返回。CLI 分别返回 130 / 143。
  • POSIX 系统下,每个 npm 命令处于独立的进程组。取消时先发送 SIGTERM,400 毫秒后发送 SIGKILL 清理仍存活的组成员。Windows 使用 taskkill /T /F 尝试清理进程树,能力随系统权限变化。
  • 普通构建失败仍表现为 failed;依赖它的包表现为 skipped,不依赖的包继续执行。取消与失败不会混淆。
  • --workspace-report 只在 workspace --execute 下可用。JSON 报告使用安全的工作区相对路径、临时文件写入与原子重命名,禁止 .. 与符号链接路径。
  • 逐包 elapsedMs 是调度器测得的真实墙钟耗时;未运行的包为 null。exitCode 对正常退出的脚本保留实际进程退出码,因信号或启动错误失败的场景可为 null。报告不伪造打包器内部阶段耗时、峰值 RSS 或 npm 插件元数据。
  • 库调用方可使用 runBuildGraph(nodes, { signal, build(name, signal) }) 与 executeWorkspaceBuild({ graph, signal, ... })。自定义回调必须自行响应取消信号;调度器不可能强制终止任意 JavaScript Promise。

安全边界: 进程组清理不能约束主动脱离进程组、脱离工作区或提升权限的孙进程;Windows 上的进程树清理属于尽力而为。正常构建仍不自动进行输出目录事务重定向。真实 tsup/tsdown 的完整集成仍需在已安装依赖的真实工作区验证。

第十轮:工作区 fail-fast、逐包超时与资源预算

默认的 pack workspace --execute 仍按依赖传播失败:失败包的下游被跳过,独立分支继续。新增以下显式策略:

# 一个包失败后停止派发,并请求终止其他正在执行的脚本
pack workspace --execute --concurrency 4 --fail-fast

# 每个包最多运行 5 分钟;0 表示不限制
pack workspace --execute --package-timeout 300000 \
  --workspace-report .cache/pack/workspace-report.json

# Linux:采样 npm 进程及后代的 RSS;超出 512 MiB 后尝试终止
pack workspace --execute --workspace-max-rss 512 --json

# 组合策略。--dry-run 仍只显示依赖图,不执行构建
pack workspace --execute --concurrency 4 --fail-fast \
  --package-timeout 300000 --workspace-max-rss 512

行为与报告字段:

  • --fail-fast 默认关闭;开启后首次失败保留 failed 及其原始报错,活动包收到取消信号,待运行包标记为 cancelled。report.stopReason 为 fail-fast,而外部 SIGINT/SIGTERM 的原因是 signal;正常完成是 null。report.cancelled 保留“是否收到外部取消信号”的原有含义。
  • --package-timeout 的单位是毫秒,合法范围为 0–86,400,000。超时包的 status 为 failed,exitCode 为 124,timedOut: true。未开启 fail-fast 时,独立包继续,失败包的下游被 skipped。
  • --workspace-max-rss 的单位是 MiB,最大为 1,048,576,仅支持可读取 /proc 的 Linux。确认超限:exitCode: 125、rssLimitExceeded: true;无法可靠采样:exitCode: 125、resourceCheckFailed: true,不会冒充已确认超限。已采样时记录 sampledPeakRssBytes / rssSampleCount,否则不制造数据。
  • 这些选项只能用于 workspace --execute;--timeout 和 --max-rss 仍专用于单包 pack build。--dry-run 从不启动 npm 脚本,--json 的标准输出保留单份结构化结果。
  • 报告采用原有 schema 1 并新增可选字段,可继续读取旧报告;写入时校验 2 MB 上限,与读取上限一致。npm 脚本及自定义 runner 仍以调用者身份运行,不具备隔离能力。

库 API:runBuildGraph(nodes, { failFast: true, build(name, signal) }) 和 executeWorkspaceBuild({ graph, failFast: true, packageTimeoutMs, packageMaxRssMiB })。自定义 runPackage 必须响应收到的 AbortSignal 并等待自己的子进程清理;调度器无法安全终止任意未合作的 Promise。

限制: RSS 为约 100ms 的周期采样,不是硬内存上限,瞬时峰值可能遗漏;具有脱离进程组能力的子进程不在普通进程组清理保证内。真实 tsup/tsdown 完整打包、Windows 进程树处理、正式 CI 发布仍应单独验证。

第十一轮:显式工作区安全续建(2026-10-10)

pack workspace 在 v11 增加可选的已完成包复用与中断续建检查点。默认关闭,不改变 v10 的构建或失败传播行为。

pack workspace --execute --concurrency 4 \
  --resume-state .cache/pack/workspace-resume.json \
  --resume-input src \
  --resume-input build.cjs \
  --resume-output dist \
  --workspace-report .cache/pack/workspace-report.json

注意:示例假定每个包都有 src、build.cjs,构建生成非空 dist 目录。实际项目应按自己的配置/插件/生成器补齐 --resume-input,例如 tsconfig.json、.ldesign/pack.config.ts 或其他影响输出的文件。包自身 package.json、工作区根 package.json 及现有的常见 lockfile/workspace 声明会自动参与指纹;Node 版本、平台、架构、工作区图、脚本、全部环境变量也参与校验。不自动枚举任意动态插件、远程输入或包外文件,输入声明不完整时不要启用。

  • 脚本成功且发布目录非空后,按 SHA-256 保存输入和产物树指纹;每个包成功后立即将状态原子写入 .cache/pack,不等待所有包成功。
  • 下次执行仅在历史结果有效且输入/产物均未改变时标记为 reused,不会再次运行 npm 脚本。依赖包在本轮真正重新执行后,其下游一律重新执行,即使下游文件哈希没有变化。
  • 启动一个包之前先持久化删除其旧成功检查点;如果进程遭到 SIGKILL,未完成的包不会误作为已完成复用。修改输入/根 lockfile、破坏产物、修改脚本/工作区依赖图都会使相关记录失效。
  • 检查点路径只能位于工作区的 .cache/pack/ 下,不能覆盖源码和 manifest。拒绝符号链接、不存在的声明输入、输出与输入/其他包路径重叠及空产物。通过跨进程 build.lock 协调同一工作区内同样启用续建的 pack 进程。
  • --execute --dry-run 仍只预览,不创建检查点或执行 npm;--resume-state 必须与 --resume-input(可多次)和 --resume-output 同时使用。
  • 工作区报告继续使用 Schema 1,增加 status: "reused",此类任务没有执行耗时或实际退出码(均为 null)。既有旧报告仍可解析。

边界条件: 这是已发布产物的验证后跳过执行,不是持久化产物仓库、分布式缓存、构建的全自动依赖分析或完整构建目录事务。工具无法阻止非协作脚本写入任意目录,也不能证明开发者声明了全部动态依赖;两个不使用同一协作锁的外部构建进程也可能冲突。正式 tsup/tsdown 打包、Windows CI、Vitest 和发布检查需要在真实依赖工作区进一步执行。

库 API 可使用 createWorkspaceResume({ graph, script, statePath, inputs, outputDir }) 后传入 executeWorkspaceBuild({ graph, resume, ... })。直接调用该 API 时必须由调用者持有工作区锁;CLI 会自动获取并在结束时释放。