chore: update package name to @rush-fs/core and version to 0.1.0-alpha.0; enhance documentation for migration and usage

CoderSerio · CoderSerio · commit 8c904ec67768 · 2026-02-22T02:43:14.000+08:00
diff --git a/.github/workflows/Release.yml b/.github/workflows/Release.yml
@@ -1,8 +1,9 @@
-# Release：仅维护者触发，构建四平台并发布到 npm
-# 触发方式：
-#   1. 手动：Actions → Release → Run workflow（使用当前 main 的 package.json version）
-#   2. 打 tag：git tag v0.0.3 && git push origin v0.0.3（需先已把 package.json 改为 0.0.3 并 push）
-# 仓库需配置 Secrets → NPM_TOKEN（npm 的 Automation token，Publish 权限）
+# Release: Maintainer-only; builds four platforms and publishes to npm.
+# Main package: @rush-fs/core (see package.json). Platform packages: @rush-fs/rush-fs-darwin-arm64, etc.
+# Trigger:
+#   1. Manual: Actions → Release → Run workflow (uses current main's package.json version)
+#   2. Tag: git tag v0.x.x && git push origin v0.x.x (bump version in package.json / Cargo.toml and push first)
+# Required: Secrets → NPM_TOKEN (npm Automation token with Publish permission)
 name: Release
 env:
   DEBUG: napi:*
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,19 @@ All notable changes to Rush-FS are documented here. The format is based on [Keep
 
 - (Add new changes here before each release.)
 
+## [0.1.0-alpha.0] - (release date TBD)
+
+**This is an alpha release.** API and behavior may change before 0.1.0 stable. Feedback and issues are welcome.
+
+### Changed
+
+- **Package name:** The main npm package is now **`@rush-fs/core`** (scoped). Install with `pnpm add @rush-fs/core` or `npm i @rush-fs/core`, and import with `import { readdir, readFile, ... } from '@rush-fs/core'`.
+- **Migration from `rush-fs`:** If you were using the old unscoped package `rush-fs`, replace it with `@rush-fs/core` in `package.json` and in all imports. The API is unchanged; only the package name and version differ. The old `rush-fs` package may be deprecated on npm in a separate step; prefer `@rush-fs/core` for new installs.
+
+## [0.0.5] - (release date TBD)
+
+- Re-publish with `optionalDependencies` correctly injected after `napi prepublish`, so `pnpm i rush-fs` / `npm i rush-fs` auto-installs the platform native binding. No API or behavior changes from 0.0.4.
+
 ## [0.0.4] - (release date TBD)
 
 ### Fixed
@@ -23,6 +36,8 @@ All notable changes to Rush-FS are documented here. The format is based on [Keep
 
 ---
 
-[Unreleased]: https://github.com/CoderSerio/rush-fs/compare/v0.0.4...HEAD
+[Unreleased]: https://github.com/CoderSerio/rush-fs/compare/v0.1.0-alpha.0...HEAD
+[0.1.0-alpha.0]: https://github.com/CoderSerio/rush-fs/compare/v0.0.5...v0.1.0-alpha.0
+[0.0.5]: https://github.com/CoderSerio/rush-fs/compare/v0.0.4...v0.0.5
 [0.0.4]: https://github.com/CoderSerio/rush-fs/compare/v0.0.3...v0.0.4
 [0.0.3]: https://github.com/CoderSerio/rush-fs/releases/tag/v0.0.3
diff --git a/Cargo.toml b/Cargo.toml
@@ -3,7 +3,7 @@
 authors = []
 edition = "2021"
 name    = "rush_fs"
-version = "0.0.3"
+version = "0.1.0-alpha.0"
 
 [lib]
 crate-type = ["cdylib"]
diff --git a/README.md b/README.md
@@ -6,26 +6,29 @@
 
 <p align="center">
   <img src="https://img.shields.io/badge/Written%20in-Rust-orange?style=flat-square" alt="Written in Rust">
-  <img src="https://img.shields.io/npm/v/rush-fs?style=flat-square" alt="NPM Version">
-  <img src="https://img.shields.io/npm/l/rush-fs?style=flat-square" alt="License">
+  <img src="https://img.shields.io/npm/v/@rush-fs/core?style=flat-square" alt="NPM Version">
+  <img src="https://img.shields.io/npm/l/@rush-fs/core?style=flat-square" alt="License">
+  <img src="https://img.shields.io/badge/status-alpha-orange?style=flat-square" alt="Alpha">
   <a href="https://github.com/CoderSerio/rush-fs/graphs/contributors"><img src="https://img.shields.io/github/contributors/CoderSerio/rush-fs?style=flat-square" alt="Contributors"></a>
 </p>
 
 <p align="center">
   API-aligned with Node.js <code>fs</code> for painless drop-in replacement in existing projects; get multi-fold performance in heavy file operations, powered by Rust.
 </p>
 
+<p align="center"><strong>⚠️ Alpha:</strong> The package is currently in <strong>alpha</strong>. API and behavior may change before 0.1.0 stable.</p>
+
 </div>
 
 ## Installation
 
 ```bash
-npm install rush-fs
+npm install @rush-fs/core
 # or
-pnpm add rush-fs
+pnpm add @rush-fs/core
 ```
 
-When you install `rush-fs`, the package manager should automatically install the **platform-specific native binding** for your OS/arch via `optionalDependencies` (e.g. `@rush-fs/rush-fs-darwin-arm64` on macOS ARM). If the native binding is missing and you see "Cannot find native binding", try:
+When you install `@rush-fs/core`, the package manager should automatically install the **platform-specific native binding** for your OS/arch via `optionalDependencies` (e.g. `@rush-fs/rush-fs-darwin-arm64` on macOS ARM). If the native binding is missing and you see "Cannot find native binding", try:
 
 1. Remove `node_modules` and the lockfile (`package-lock.json` or `pnpm-lock.yaml`), then run `pnpm install` (or `npm i`) again.
 2. Or install the platform package explicitly:  
@@ -34,10 +37,12 @@ When you install `rush-fs`, the package manager should automatically install the
    **Windows x64:** `pnpm add @rush-fs/rush-fs-win32-x64-msvc`  
    **Linux x64 (glibc):** `pnpm add @rush-fs/rush-fs-linux-x64-gnu`
 
+**Migration from `rush-fs`:** The package was renamed to `@rush-fs/core`. See [CHANGELOG.md](./CHANGELOG.md#010-alpha0) for details.
+
 ## Usage
 
 ```ts
-import { readdir, stat, readFile, writeFile, mkdir, rm } from 'rush-fs'
+import { readdir, stat, readFile, writeFile, mkdir, rm } from '@rush-fs/core'
 
 // Read directory
 const files = await readdir('./src')
@@ -192,7 +197,7 @@ We are rewriting `fs` APIs one by one.
 >
 > - ✅: Fully Supported
 > - 🚧: Partially Supported / WIP
-> - ✨: New feature from rush-fs
+> - ✨: New feature from @rush-fs/core
 > - ❌: Not Supported Yet
 
 ### `readdir`
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -6,25 +6,28 @@
 
 <p align="center">
   <img src="https://img.shields.io/badge/Written%20in-Rust-orange?style=flat-square" alt="Written in Rust">
-  <img src="https://img.shields.io/npm/v/rush-fs?style=flat-square" alt="NPM Version">
-  <img src="https://img.shields.io/npm/l/rush-fs?style=flat-square" alt="License">
+  <img src="https://img.shields.io/npm/v/@rush-fs/core?style=flat-square" alt="NPM Version">
+  <img src="https://img.shields.io/npm/l/@rush-fs/core?style=flat-square" alt="License">
+  <img src="https://img.shields.io/badge/status-alpha-orange?style=flat-square" alt="Alpha">
   <a href="https://github.com/CoderSerio/rush-fs/graphs/contributors"><img src="https://img.shields.io/github/contributors/CoderSerio/rush-fs?style=flat-square" alt="Contributors"></a>
 </p>
 
 <p align="center">
   与 Node.js <code>fs</code> API 对齐，可无痛替换现有项目中的 fs；在海量文件操作场景下获得数倍于内置 fs 的性能，由 Rust 驱动。
 </p>
+
+<p align="center"><strong>⚠️ Alpha：</strong>当前为 <strong>alpha</strong> 版本，在 0.1.0 正式版前 API 与行为可能变更。</p>
 </div>
 
 ## 安装
 
 ```bash
-npm install rush-fs
+npm install @rush-fs/core
 # or
-pnpm add rush-fs
+pnpm add @rush-fs/core
 ```
 
-安装 `rush-fs` 时，包管理器会通过 `optionalDependencies` 自动安装**当前平台**的本地绑定（例如 macOS ARM 上的 `@rush-fs/rush-fs-darwin-arm64`）。若未安装或出现「Cannot find native binding」：
+安装 `@rush-fs/core` 时，包管理器会通过 `optionalDependencies` 自动安装**当前平台**的本地绑定（例如 macOS ARM 上的 `@rush-fs/rush-fs-darwin-arm64`）。若未安装或出现「Cannot find native binding」：
 
 1. 删除 `node_modules` 和锁文件（`package-lock.json` 或 `pnpm-lock.yaml`）后重新执行 `pnpm install`（或 `npm i`）。
 2. 或手动安装对应平台包：  
@@ -33,10 +36,12 @@ pnpm add rush-fs
    **Windows x64：** `pnpm add @rush-fs/rush-fs-win32-x64-msvc`  
    **Linux x64 (glibc)：** `pnpm add @rush-fs/rush-fs-linux-x64-gnu`
 
+**从 `rush-fs` 迁移：** 自 0.1.0-alpha 起主包更名为 `@rush-fs/core`，详见 [CHANGELOG.md](./CHANGELOG.md#010-alpha0)。
+
 ## 用法
 
 ```ts
-import { readdir, stat, readFile, writeFile, mkdir, rm } from 'rush-fs'
+import { readdir, stat, readFile, writeFile, mkdir, rm } from '@rush-fs/core'
 
 // 读取目录
 const files = await readdir('./src')
@@ -191,7 +196,7 @@ graph TD
 >
 > - ✅：完全支持
 > - 🚧：部分支持 / 开发中
-> - ✨：rush-fs 的新增能力
+> - ✨：@rush-fs/core 的新增能力
 > - ❌：暂未支持
 
 ### `readdir`
diff --git a/docs/content/about.mdx b/docs/content/about.mdx
@@ -5,7 +5,7 @@ Rush-FS is an API-aligned, drop-in replacement for the Node.js `fs` module, powe
 ## Links
 
 - [GitHub](https://github.com/CoderSerio/rush-fs)
-- [npm](https://www.npmjs.com/package/rush-fs)
+- [npm](https://www.npmjs.com/package/@rush-fs/core)
 - [API Overview](/api)
 - [Benchmarks](/benchmarks)
 
diff --git a/docs/content/api/access.mdx b/docs/content/api/access.mdx
@@ -5,7 +5,7 @@ Check whether the process can access a file with the given mode (F_OK, R_OK, W_O
 ## Basic usage
 
 ```ts
-import { access } from 'rush-fs'
+import { access } from '@rush-fs/core'
 import { constants } from 'node:fs'
 
 await access('./file.txt') // F_OK default
diff --git a/docs/content/api/append-file.mdx b/docs/content/api/append-file.mdx
@@ -5,7 +5,7 @@ Append data to a file, creating the file if it does not exist.
 ## Basic usage
 
 ```ts
-import { appendFile } from 'rush-fs'
+import { appendFile } from '@rush-fs/core'
 
 await appendFile('./log.txt', 'new line\n')
 await appendFile('./log.txt', buffer, { encoding: 'utf8', mode: 0o644 })
diff --git a/docs/content/api/chmod.mdx b/docs/content/api/chmod.mdx
@@ -5,7 +5,7 @@ Change the permissions of a file or directory (mode bits).
 ## Basic usage
 
 ```ts
-import { chmod } from 'rush-fs'
+import { chmod } from '@rush-fs/core'
 
 await chmod('./script.sh', 0o755)
 await chmod('./file.txt', 0o644)
diff --git a/docs/content/api/chown.mdx b/docs/content/api/chown.mdx
@@ -5,7 +5,7 @@ Change the owner and group of a file or directory (Unix). On Windows this is a n
 ## Basic usage
 
 ```ts
-import { chown } from 'rush-fs'
+import { chown } from '@rush-fs/core'
 
 await chown('./file', uid, gid)
 ```
diff --git a/docs/content/api/copy-file.mdx b/docs/content/api/copy-file.mdx
@@ -5,7 +5,7 @@ Copy a file from `src` to `dest`. Does not copy directory trees.
 ## Basic usage
 
 ```ts
-import { copyFile } from 'rush-fs'
+import { copyFile } from '@rush-fs/core'
 import { constants } from 'node:fs'
 
 await copyFile('./a.txt', './b.txt')
diff --git a/docs/content/api/cp.mdx b/docs/content/api/cp.mdx
@@ -5,7 +5,7 @@ Copy files and directories recursively (Node.js 16.7+). Supports **concurrency**
 ## Basic usage
 
 ```ts
-import { cp } from 'rush-fs'
+import { cp } from '@rush-fs/core'
 
 await cp('./src', './dest', { recursive: true })
 await cp('./src', './dest', { recursive: true, force: true, concurrency: 4 })
diff --git a/docs/content/api/exists.mdx b/docs/content/api/exists.mdx
@@ -5,7 +5,7 @@ Check if a path exists (file, directory, or symlink). Returns a boolean; does no
 ## Basic usage
 
 ```ts
-import { exists } from 'rush-fs'
+import { exists } from '@rush-fs/core'
 
 const ok = await exists('./package.json')
 if (ok) await doSomething()
diff --git a/docs/content/api/glob.mdx b/docs/content/api/glob.mdx
@@ -5,7 +5,7 @@ Match files and directories by glob pattern (e.g. `**/*.js`). Supports **concurr
 ## Basic usage
 
 ```ts
-import { glob } from 'rush-fs'
+import { glob } from '@rush-fs/core'
 
 const files = await glob('**/*.ts', { cwd: './src' })
 const entries = await glob('**/*.rs', { cwd: './crate', withFileTypes: true, concurrency: 4, gitIgnore: true })
diff --git a/docs/content/api/index.mdx b/docs/content/api/index.mdx
@@ -53,6 +53,6 @@ Each supported API has a **dedicated doc page** in the sidebar (e.g. [readdir](/
 
 ## Sync variants
 
-Supported APIs expose both async (e.g. `readdir`) and sync (e.g. `readdirSync`) forms. Import the same names from `rush-fs` as you would from `node:fs`.
+Supported APIs expose both async (e.g. `readdir`) and sync (e.g. `readdirSync`) forms. Import the same names from `@rush-fs/core` as you would from `node:fs`.
 
 For full TypeScript signatures and option details, see the [README Status & Roadmap](https://github.com/CoderSerio/rush-fs#status--roadmap) section.
diff --git a/docs/content/api/link.mdx b/docs/content/api/link.mdx
@@ -5,7 +5,7 @@ Create a hard link from `existingPath` to `newPath`. Both paths refer to the sam
 ## Basic usage
 
 ```ts
-import { link } from 'rush-fs'
+import { link } from '@rush-fs/core'
 
 await link('./existing.txt', './hardlink.txt')
 ```
diff --git a/docs/content/api/lstat.mdx b/docs/content/api/lstat.mdx
@@ -5,7 +5,7 @@ Get file/directory metadata without following symlinks. For the link target, use
 ## Basic usage
 
 ```ts
-import { lstat } from 'rush-fs'
+import { lstat } from '@rush-fs/core'
 
 const s = await lstat('./some-link')
 console.log(s.isSymbolicLink(), s.size)
diff --git a/docs/content/api/mkdir.mdx b/docs/content/api/mkdir.mdx
@@ -5,7 +5,7 @@ Create a directory. With `recursive: true`, creates all parent directories; retu
 ## Basic usage
 
 ```ts
-import { mkdir } from 'rush-fs'
+import { mkdir } from '@rush-fs/core'
 
 await mkdir('./new-dir')
 await mkdir('./a/b/c', { recursive: true })
diff --git a/docs/content/api/mkdtemp.mdx b/docs/content/api/mkdtemp.mdx
@@ -5,7 +5,7 @@ Create a unique temporary directory with the given prefix. Uses OS random source
 ## Basic usage
 
 ```ts
-import { mkdtemp } from 'rush-fs'
+import { mkdtemp } from '@rush-fs/core'
 
 const dir = await mkdtemp('/tmp/myapp-')
 console.log(dir) // e.g. /tmp/myapp-abc123
diff --git a/docs/content/api/read-file.mdx b/docs/content/api/read-file.mdx
@@ -5,7 +5,7 @@ Read the entire contents of a file. Returns a `Buffer` or a decoded string depen
 ## Basic usage
 
 ```ts
-import { readFile } from 'rush-fs'
+import { readFile } from '@rush-fs/core'
 
 // As UTF-8 string (default)
 const text = await readFile('./package.json', { encoding: 'utf8' })
diff --git a/docs/content/api/readdir.mdx b/docs/content/api/readdir.mdx
@@ -5,7 +5,7 @@ Read the contents of a directory. Supports non-recursive and recursive modes; re
 ## Basic usage
 
 ```ts
-import { readdir } from 'rush-fs'
+import { readdir } from '@rush-fs/core'
 
 // Names only (default)
 const names = await readdir('./src')
diff --git a/docs/content/api/readlink.mdx b/docs/content/api/readlink.mdx
@@ -5,7 +5,7 @@ Read the target path of a symbolic link. Fails for non-symlinks.
 ## Basic usage
 
 ```ts
-import { readlink } from 'rush-fs'
+import { readlink } from '@rush-fs/core'
 
 const target = await readlink('./mylink')
 console.log(target) // resolved target path
diff --git a/docs/content/api/realpath.mdx b/docs/content/api/realpath.mdx
@@ -5,7 +5,7 @@ Resolve the canonical absolute path for a path, resolving `.`, `..`, and symlink
 ## Basic usage
 
 ```ts
-import { realpath } from 'rush-fs'
+import { realpath } from '@rush-fs/core'
 
 const abs = await realpath('./some/relative/path')
 console.log(abs) // e.g. /home/user/proj/some/relative/path
diff --git a/docs/content/api/rename.mdx b/docs/content/api/rename.mdx
@@ -5,7 +5,7 @@ Rename or move a file or directory from `oldPath` to `newPath`. Cross-device mov
 ## Basic usage
 
 ```ts
-import { rename } from 'rush-fs'
+import { rename } from '@rush-fs/core'
 
 await rename('./old.txt', './new.txt')
 await rename('./dir', './renamed-dir')
diff --git a/docs/content/api/rm.mdx b/docs/content/api/rm.mdx
@@ -5,7 +5,7 @@ Remove files and directories. Supports recursive removal with optional **concurr
 ## Basic usage
 
 ```ts
-import { rm } from 'rush-fs'
+import { rm } from '@rush-fs/core'
 
 // Remove a file
 await rm('./tmp.txt')
diff --git a/docs/content/api/rmdir.mdx b/docs/content/api/rmdir.mdx
@@ -5,7 +5,7 @@ Remove an empty directory. Fails if the directory is not empty; use `rm` with `r
 ## Basic usage
 
 ```ts
-import { rmdir } from 'rush-fs'
+import { rmdir } from '@rush-fs/core'
 
 await rmdir('./empty-dir')
 ```
diff --git a/docs/content/api/stat.mdx b/docs/content/api/stat.mdx
@@ -5,7 +5,7 @@ Get file/directory metadata. Follows symlinks; use `lstat` to inspect the link i
 ## Basic usage
 
 ```ts
-import { stat } from 'rush-fs'
+import { stat } from '@rush-fs/core'
 
 const s = await stat('./package.json')
 console.log(s.size, s.isFile(), s.isDirectory())
diff --git a/docs/content/api/symlink.mdx b/docs/content/api/symlink.mdx
@@ -5,7 +5,7 @@ Create a symbolic link at `path` pointing to `target`. On Windows, `type` can be
 ## Basic usage
 
 ```ts
-import { symlink } from 'rush-fs'
+import { symlink } from '@rush-fs/core'
 
 await symlink('./target.txt', './link.txt')
 await symlink('./target-dir', './link-dir', 'dir') // Windows: directory symlink
diff --git a/docs/content/api/truncate.mdx b/docs/content/api/truncate.mdx
@@ -5,7 +5,7 @@ Truncate or extend a file to the given length. If the file is longer, extra byte
 ## Basic usage
 
 ```ts
-import { truncate } from 'rush-fs'
+import { truncate } from '@rush-fs/core'
 
 await truncate('./file.txt', 100) // trim or extend to 100 bytes
 await truncate('./file.txt')      // truncate to 0
diff --git a/docs/content/api/unlink.mdx b/docs/content/api/unlink.mdx
@@ -5,7 +5,7 @@ Remove a file. Fails for directories; use `rm` with `recursive: true` for direct
 ## Basic usage
 
 ```ts
-import { unlink } from 'rush-fs'
+import { unlink } from '@rush-fs/core'
 
 await unlink('./temp.txt')
 ```
diff --git a/docs/content/api/utimes.mdx b/docs/content/api/utimes.mdx
diff --git a/docs/content/api/write-file.mdx b/docs/content/api/write-file.mdx
diff --git a/docs/content/guide/quick-start.mdx b/docs/content/guide/quick-start.mdx
diff --git a/docs/content/guide/what-is-rush-fs.mdx b/docs/content/guide/what-is-rush-fs.mdx
diff --git a/docs/content/index.mdx b/docs/content/index.mdx
diff --git a/index.js b/index.js
diff --git a/package.json b/package.json
