@chiimagnus/applebookscli 0.1.6 → 0.2.1

package/README.md

@@ -1,108 +1,108 @@
 # AppleBooksCLI
 
-AppleBooksCLI 是一个用于 macOS Apple Books 的命令行工具。你可以直接查询自己的书库、阅读状态、划线与笔记，读取可用的 EPUB/PDF 内容，导出笔记，并在需要时安全地修改笔记或藏书。
+English | [简体中文](README.zh.md)
 
-## 主要功能
+[AppleBooksCLI](https://github.com/chiimagnus/AppleBooksCLI) is a command-line tool for Apple Books on macOS. It can query your library, reading state, highlights, and notes; read available EPUB/PDF content; export notes; and safely update existing notes or collections when requested.
 
-- 浏览、搜索 Apple Books 书库与阅读状态。
-- 查询划线、笔记、最近批注，并按书籍或时间定位。
-- 查看单条批注时获得可直接跳回 Apple Books 对应划线位置的链接。
-- 读取可用 EPUB 的目录、章节、元数据与批注上下文。
-- 提取 PDF 划线与笔记。
-- 导出 JSON、CSV、Markdown 或 HTML。
-- 安全修改笔记、管理藏书，并在写入前自动备份。
-- 安装随 CLI 一起分发的 `applebookscli` Skill，供 Codex/AI 直接使用。
+## Features
 
-## 系统要求
+- Browse and search the Apple Books library and reading state.
+- Query highlights, notes, and recent annotations, with book- and time-based filtering.
+- Open a single annotation back at its Apple Books location when a deep link is available.
+- Read available EPUB tables of contents, chapters, metadata, and annotation context.
+- Extract PDF highlights and notes.
+- Export JSON, CSV, Markdown, or HTML.
+- **Safely update notes and manage collections, with an automatic backup before writes.**
+- Provide a standard `applebookscli` Agent Skill in English and Chinese.
 
-- macOS 12 或更高版本。
-- npm 发布的预编译版本目前支持 Apple Silicon（arm64）。
-- 读取 Apple Books 数据时，macOS 可能要求为终端或调用进程授予 Full Disk Access。
-- 未下载的 EPUB、DRM 内容或当前系统无法读取的内容会明确提示不可用或能力受限；AppleBooksCLI 不绕过系统保护。
+## Requirements
 
-## 安装
+- macOS may require Full Disk Access for the terminal or calling process before Apple Books data can be read.
+- Undownloaded EPUBs, DRM-protected content, or content the current system cannot read are reported as unavailable or capability-limited. AppleBooksCLI does not bypass system protections.
 
-安装稳定版：
+## Install
 
 ```sh
-npm install --global @chiimagnus/applebookscli
-applebookscli --version
+npm install --global @chiimagnus/applebookscli@latest
+npx -y skills@1.5.23 add "chiimagnus/AppleBooksCLI#v$(applebookscli --version)" --skill applebookscli --global
 ```
 
-如果需要试用 beta：
+For the Chinese Skill, replace `applebookscli` with `applebookscli-zh` in the second command.
 
-```sh
-npm install --global @chiimagnus/applebookscli@beta
-```
+Future npm upgrades keep an Agent Skills CLI-managed Skill on the same CLI release tag automatically. `--ignore-scripts` disables that automatic update.
+
+## Help
 
-更新到最新稳定版：
+The installed CLI is the source of truth for current commands and arguments:
 
 ```sh
-npm install --global @chiimagnus/applebookscli@latest
+applebookscli --help
+applebookscli <group> --help
+applebookscli <group> <subcommand> --help
 ```
 
-## 快速开始
+## Quick start
 
 ```sh
-# 浏览书库
+# Browse the library
 applebookscli books list
 
-# 查看正在阅读的书
+# Show books currently in progress
 applebookscli reading in-progress
 
-# 查看最近创建的批注
+# Show recently created annotations
 applebookscli annotations recent
 
-# 查看书库统计
+# Show library statistics
 applebookscli stats
 ```
 
-需要结构化结果时，大多数查询命令支持 `--json`：
+Most query commands support `--json` when structured output is needed:
 
 ```sh
 applebookscli books list --json
 applebookscli annotations recent --json
 ```
 
-## 笔记、划线与定位
+## Notes, highlights, and locations
 
-先找到批注，再用 UUID 查看具体内容：
+Find an annotation first, then inspect it by UUID:
 
 ```sh
 applebookscli annotations recent --json
 applebookscli annotations get <annotation-uuid>
 ```
 
-单条批注结果会包含对应的 `appleBooksURL`，可以直接跳回 Apple Books 中该书或对应划线位置。
+A single-annotation result includes an `appleBooksURL` when available so you can jump back to the book or highlight location in Apple Books.
 
-如果需要查看划线前后的正文：
+To read text around a highlight:
 
 ```sh
 applebookscli content context <annotation-uuid>
 ```
 
-搜索、按书筛选、颜色、时间范围等能力以当前帮助为准：
+Use the current help for search, book filters, colors, and time ranges:
 
 ```sh
 applebookscli annotations --help
 ```
 
-## EPUB 与 PDF
+## EPUB and PDF
 
 ```sh
-# EPUB 内容相关命令
+# EPUB content commands
 applebookscli content --help
 
-# 查看 PDF inventory
+# List PDF inventory
 applebookscli pdf list
 
-# 提取某个 PDF 的 highlights
+# Extract highlights from a PDF
 applebookscli pdf highlights --help
 ```
 
-EPUB 在读取正文前会先检查本地 materialization 状态，不主动触发 iCloud hydration，也不会绕过 DRM。PDF 只处理当前可解析为可读本地文件的 source；对 iCloud placeholder 的 non-hydrating 行为尚未建立等价保证。
+Before reading EPUB text, AppleBooksCLI checks local materialization state without intentionally triggering iCloud hydration and does not bypass DRM. PDF commands only operate on sources that currently resolve to readable local files; equivalent non-hydrating behavior for iCloud placeholders has not been established.
 
-## 导出
+## Export
 
 ```sh
 # Markdown
@@ -112,15 +112,15 @@ applebookscli export --format markdown --output ~/Desktop/apple-books.md
 applebookscli export --format json --output ~/Desktop/apple-books.json
 ```
 
-还支持 CSV、HTML、按书分组、筛选划线/笔记、Obsidian 格式、封面与完整笔记归档等选项。有 CFI 的 EPUB 批注在 HTML/Markdown 中会把 `Location` 本身做成 Apple Books deep link；无 CFI 时退化为书籍级链接。JSON/CSV 保留对应 `appleBooksURL`：
+CSV, HTML, grouping by book, highlight/note filtering, Obsidian formatting, covers, and complete-notes archives are also available. EPUB annotations with a CFI make the `Location` text itself an Apple Books deep link in HTML/Markdown; without a CFI, the link falls back to the book level. JSON/CSV preserve the corresponding `appleBooksURL`:
 
 ```sh
 applebookscli export --help
 ```
 
-## 安全写入
+## Safe writes
 
-AppleBooksCLI 可以修改已有笔记和管理藏书。写入前会自动创建备份，并在写入后验证结果；普通查询不会隐式修改 Apple Books 数据。
+AppleBooksCLI can update existing notes and manage collections. It creates a backup before writing and verifies the result afterward. Ordinary queries do not implicitly modify Apple Books data.
 
 ```sh
 applebookscli annotations update-note --help
@@ -128,13 +128,13 @@ applebookscli collections --help
 applebookscli backups --help
 ```
 
-单条 collection / annotation mutation 可加 `--sync`，在本地 commit + cloud projection 后等待当前 Mac 的 CloudKit acknowledgement：
+A single collection or annotation mutation can add `--sync` to wait for current-Mac CloudKit acknowledgement after the local commit and cloud projection:
 
 ```sh
 applebookscli collections create "My Shelf" --sync --json
 ```
 
-连续多条写入时，优先正常提交各 mutation，最后只 flush 一次：
+For several writes, commit the normal mutations first and flush once at the end:
 
 ```sh
 applebookscli collections create "Shelf A" --json
@@ -142,42 +142,19 @@ applebookscli annotations update-note <annotation-uuid> --note "New note" --json
 applebookscli sync --json
 ```
 
-`sync` 只处理已存在的 pending collection/member/annotation cloud records；无 pending 时不触发生命周期。acknowledgement 只证明**当前 Mac** 已完成 Apple Books CloudKit upload，不等于另一台设备已经显示。post-commit `cloud_sync_failed` 不能触发自动重试；BKLibrary restore 也不等同于可逐条 flush 的 cloud mutation。
-
-## 安装 AppleBooksCLI Skill
-
-npm 包中包含配套的 `applebookscli` Skill：
+`sync` only processes already pending collection/member/annotation cloud records and does not trigger the lifecycle when none are pending. Acknowledgement proves only that **this Mac** completed the Apple Books CloudKit upload; it does not prove that another device already displays the change. A post-commit `cloud_sync_failed` must not cause an automatic mutation retry, and restoring a BKLibrary snapshot is not equivalent to replaying individually flushable cloud mutations.
 
-```sh
-applebookscli skill install
-```
+## Optional configuration
 
-它会安装到 `${CODEX_HOME:-~/.codex}/skills/applebookscli`。如果目标已经存在，CLI 默认不会覆盖；需要明确替换时使用：
+Most users do not need a configuration file. `~/.config/applebookscli/config.json` is only needed for an additional EPUB directory or to supplement title/author metadata for historical annotations.
 
-```sh
-applebookscli skill install --force
-```
-
-## 可选配置
-
-大多数用户不需要配置文件。只有需要指定额外的 EPUB 目录，或给历史批注补充书名/作者信息时，才需要 `~/.config/applebookscli/config.json`。
-
-示例见 [`Config/applebookscli.example.json`](Config/applebookscli.example.json)。
-
-## 获取帮助
-
-CLI 自带完整帮助，具体命令与参数以当前安装版本为准：
-
-```sh
-applebookscli --help
-applebookscli <group> --help
-applebookscli <group> <subcommand> --help
-```
+See [`Config/applebookscli.example.json`](Config/applebookscli.example.json).
 
-## 开发与维护
+## Development and maintenance
 
-架构、CLI contract、写入安全、发布流程和其它维护者文档从 [`docs/index.md`](docs/index.md) 开始。
+Start with [`docs/index.md`](docs/index.md) for architecture, CLI contract, write safety, release workflow, and other maintainer documentation.
 
 ## License
 
-AppleBooksCLI 使用 GNU Affero General Public License v3（AGPLv3）。第三方 notice 与许可证文本见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 和 [`ThirdPartyLicenses/`](ThirdPartyLicenses/)。
+AppleBooksCLI is licensed under the [AGPLv3 LICENSE](LICENSE).
+Third-party notices and license texts are in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) and [`ThirdPartyLicenses/`](ThirdPartyLicenses/).

package/README.zh.md

@@ -0,0 +1,160 @@
+# AppleBooksCLI
+
+[English](README.md) | 简体中文
+
+[AppleBooksCLI](https://github.com/chiimagnus/AppleBooksCLI) 是一个用于 macOS Apple Books 的命令行工具。你可以直接查询自己的书库、阅读状态、划线与笔记，读取可用的 EPUB/PDF 内容，导出笔记，并在需要时安全地修改笔记或藏书。
+
+## 主要功能
+
+- 浏览、搜索 Apple Books 书库与阅读状态。
+- 查询划线、笔记、最近批注，并按书籍或时间定位。
+- 查看单条批注时获得可直接跳回 Apple Books 对应划线位置的链接。
+- 读取可用 EPUB 的目录、章节、元数据与批注上下文。
+- 提取 PDF 划线与笔记。
+- 导出 JSON、CSV、Markdown 或 HTML。
+- **安全修改笔记、管理藏书，并在写入前自动备份。**
+- 提供标准 `applebookscli` Agent Skill，并提供英文/中文两个版本。
+
+## 系统要求
+
+- 读取 Apple Books 数据时，macOS 可能要求为终端或调用进程授予 Full Disk Access。
+- 未下载的 EPUB、DRM 内容或当前系统无法读取的内容会明确提示不可用或能力受限；AppleBooksCLI 不绕过系统保护。
+
+## 安装
+
+```sh
+npm install --global @chiimagnus/applebookscli@latest
+npx -y skills@1.5.23 add "chiimagnus/AppleBooksCLI#v$(applebookscli --version)" --skill applebookscli-zh --global
+```
+
+英文 Skill 把第二条命令里的 `applebookscli-zh` 改成 `applebookscli` 即可。
+
+以后通过 npm 升级 CLI 时，由 Agent Skills CLI 管理的 Skill 会自动跟随到相同的 CLI release tag。使用 `--ignore-scripts` 会关闭这项自动更新。
+
+## 获取帮助
+
+CLI 自带完整帮助，具体命令与参数以当前安装版本为准：
+
+```sh
+applebookscli --help
+applebookscli <group> --help
+applebookscli <group> <subcommand> --help
+```
+
+## 快速开始
+
+```sh
+# 浏览书库
+applebookscli books list
+
+# 查看正在阅读的书
+applebookscli reading in-progress
+
+# 查看最近创建的批注
+applebookscli annotations recent
+
+# 查看书库统计
+applebookscli stats
+```
+
+需要结构化结果时，大多数查询命令支持 `--json`：
+
+```sh
+applebookscli books list --json
+applebookscli annotations recent --json
+```
+
+## 笔记、划线与定位
+
+先找到批注，再用 UUID 查看具体内容：
+
+```sh
+applebookscli annotations recent --json
+applebookscli annotations get <annotation-uuid>
+```
+
+单条批注结果会包含对应的 `appleBooksURL`，可以直接跳回 Apple Books 中该书或对应划线位置。
+
+如果需要查看划线前后的正文：
+
+```sh
+applebookscli content context <annotation-uuid>
+```
+
+搜索、按书筛选、颜色、时间范围等能力以当前帮助为准：
+
+```sh
+applebookscli annotations --help
+```
+
+## EPUB 与 PDF
+
+```sh
+# EPUB 内容相关命令
+applebookscli content --help
+
+# 查看 PDF inventory
+applebookscli pdf list
+
+# 提取某个 PDF 的 highlights
+applebookscli pdf highlights --help
+```
+
+EPUB 在读取正文前会先检查本地 materialization 状态，不主动触发 iCloud hydration，也不会绕过 DRM。PDF 只处理当前可解析为可读本地文件的 source；对 iCloud placeholder 的 non-hydrating 行为尚未建立等价保证。
+
+## 导出
+
+```sh
+# Markdown
+applebookscli export --format markdown --output ~/Desktop/apple-books.md
+
+# JSON
+applebookscli export --format json --output ~/Desktop/apple-books.json
+```
+
+还支持 CSV、HTML、按书分组、筛选划线/笔记、Obsidian 格式、封面与完整笔记归档等选项。有 CFI 的 EPUB 批注在 HTML/Markdown 中会把 `Location` 本身做成 Apple Books deep link；无 CFI 时退化为书籍级链接。JSON/CSV 保留对应 `appleBooksURL`：
+
+```sh
+applebookscli export --help
+```
+
+## 安全写入
+
+AppleBooksCLI 可以修改已有笔记和管理藏书。写入前会自动创建备份，并在写入后验证结果；普通查询不会隐式修改 Apple Books 数据。
+
+```sh
+applebookscli annotations update-note --help
+applebookscli collections --help
+applebookscli backups --help
+```
+
+单条 collection / annotation mutation 可加 `--sync`，在本地 commit + cloud projection 后等待当前 Mac 的 CloudKit acknowledgement：
+
+```sh
+applebookscli collections create "My Shelf" --sync --json
+```
+
+连续多条写入时，优先正常提交各 mutation，最后只 flush 一次：
+
+```sh
+applebookscli collections create "Shelf A" --json
+applebookscli annotations update-note <annotation-uuid> --note "New note" --json
+applebookscli sync --json
+```
+
+`sync` 只处理已存在的 pending collection/member/annotation cloud records；无 pending 时不触发生命周期。acknowledgement 只证明**当前 Mac** 已完成 Apple Books CloudKit upload，不等于另一台设备已经显示。post-commit `cloud_sync_failed` 不能触发自动重试；BKLibrary restore 也不等同于可逐条 flush 的 cloud mutation。
+
+## 可选配置
+
+大多数用户不需要配置文件。只有需要指定额外的 EPUB 目录，或给历史批注补充书名/作者信息时，才需要 `~/.config/applebookscli/config.json`。
+
+示例见 [`Config/applebookscli.example.json`](Config/applebookscli.example.json)。
+
+## 开发与维护
+
+架构、CLI contract、写入安全、发布流程和其它维护者文档从 [`docs/index.md`](docs/index.md) 开始。
+
+## License
+
+AppleBooksCLI 使用 [AGPLv3 LICENSE](LICENSE)。
+第三方 notice 与许可证文本见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 和 [`ThirdPartyLicenses/`](ThirdPartyLicenses/)。

package/libexec/applebookscli/sync-installed-skill.mjs

@@ -0,0 +1,74 @@
+import { readFile, rename, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+const skillNames = ["applebookscli", "applebookscli-zh"];
+const source = "chiimagnus/AppleBooksCLI";
+const sourceURL = "https://github.com/chiimagnus/AppleBooksCLI.git";
+const skillsVersion = "1.5.23";
+
+async function runUpdater(names) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      "npx",
+      ["-y", `skills@${skillsVersion}`, "update", ...names, "-g", "-y"],
+      {
+        stdio: "ignore",
+        env: { ...process.env, DISABLE_TELEMETRY: "1" },
+      },
+    );
+    child.once("error", reject);
+    child.once("exit", resolve);
+  });
+}
+
+async function main() {
+  const packageJSON = JSON.parse(
+    await readFile(new URL("../../package.json", import.meta.url), "utf8"),
+  );
+  // ponytail: skills@1.5.23 还没有公开的“只重绑 ref”命令；只改它自己的 source ref，target 更新仍完全交给官方 updater。
+  const lockPath = process.env.XDG_STATE_HOME
+    ? join(process.env.XDG_STATE_HOME, "skills", ".skill-lock.json")
+    : join(homedir(), ".agents", ".skill-lock.json");
+
+  let rawLock;
+  try {
+    rawLock = await readFile(lockPath, "utf8");
+  } catch {
+    return;
+  }
+
+  const lock = JSON.parse(rawLock);
+  const managed = skillNames.filter((name) => {
+    const entry = lock.skills?.[name];
+    return entry?.sourceType === "github" &&
+      (entry.source === source || entry.sourceUrl === sourceURL);
+  });
+  if (managed.length === 0) return;
+
+  const targetRef = `v${packageJSON.version}`;
+  const changed = managed.some((name) => lock.skills[name].ref !== targetRef);
+  if (changed) {
+    const mode = (await stat(lockPath)).mode & 0o777;
+    const temporary = `${lockPath}.${process.pid}.tmp`;
+    for (const name of managed) lock.skills[name].ref = targetRef;
+    await writeFile(temporary, `${JSON.stringify(lock, null, 2)}\n`, { mode });
+    await rename(temporary, lockPath);
+  }
+
+  const code = await runUpdater(managed);
+  if (code !== 0) {
+    console.warn(
+      `applebookscli: Skill update to ${targetRef} did not complete; Agent Skills CLI can retry later.`,
+    );
+  }
+}
+
+try {
+  await main();
+} catch (error) {
+  console.warn(
+    `applebookscli: optional Skill update skipped: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chiimagnus/applebookscli",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Native Apple Books CLI for macOS on Apple Silicon.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -17,16 +17,17 @@
   "cpu": [
     "arm64"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
   "bin": {
     "applebookscli": "bin/applebookscli"
   },
+  "scripts": {
+    "postinstall": "node libexec/applebookscli/sync-installed-skill.mjs"
+  },
   "files": [
     "bin/applebookscli",
     "libexec/applebookscli/applebookscli-pdf-worker",
-    "share/applebookscli/skill/applebookscli/SKILL.md",
+    "libexec/applebookscli/sync-installed-skill.mjs",
+    "README.zh.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md",
     "ThirdPartyLicenses"

package/share/applebookscli/skill/applebookscli/SKILL.md

@@ -1,36 +0,0 @@
----
-name: applebookscli
-description: 通过 `applebookscli` 查询、定位、导出或受保护地修改 Apple Books 图书、阅读状态、EPUB/PDF、批注笔记与藏书，以及执行云同步、备份恢复或访问诊断时使用。
----
-
-# AppleBooksCLI
-
-使用已安装的 `applebookscli` 作为 Apple Books 数据操作入口。用户询问自己的数据时，实际查询后再回答，不用能力说明代替结果。
-
-## 命令与 identity
-
-命令、参数和枚举以当前 `--help` 为准；需要机器结果时优先 `--json`，`export` 使用 `--format json`。`doctor` 只用于诊断实际的 permission / unavailable / schema 问题。
-
-优先使用稳定 identity：book asset ID、annotation UUID、collection ID、backup handle。标题/作者/名称先 search/list 并确认唯一；local PK 只在用户明确指定或没有稳定 identity 时使用。不要静默选择多候选中的第一项。
-
-## Annotation 与写入
-
-“最新笔记”只在 nonempty note 中比较；“最新”默认按创建时间，“最近修改”按修改时间。具体 annotation 优先返回高亮、note、必要时间与 `appleBooksURL`；需要前后正文时才用 `content context`。
-
-`annotations update-note --note` 是整段替换。用户要求追加时先读原 note，再构造完整新值。`annotations delete` soft-delete 整条 annotation，不用于清空 note。
-
-只有用户明确要求修改或 restore 时才写。不要直接读写 Apple Books SQLite，也不要额外手工 quit/launch Books；guarded mutation rail 已负责 backup、Books lifecycle、事务、read-back 与 cloud projection。
-
-`committed=true` 后出现 warning 不能自动重试；结果未知时先做最窄只读确认。单条 mutation 只有在用户要求立即确认上传时才加 `--sync`。连续多条写入先正常执行，最后一次 `applebookscli sync --json`，避免每条都触发 lifecycle。
-
-`--sync` / `sync` 成功只证明当前 Mac 的 Apple Books cloud records 获得 CloudKit acknowledgement；没有 second-device 证据时不要声称另一设备已经显示。`cloud_sync_failed` 是 post-commit warning。`backups restore` 是 BKLibrary snapshot replacement，不要把 restore 后的 `sync` 解释成 snapshot diff 已逐条上传。
-
-## EPUB、PDF 与导出
-
-EPUB 不可用时按需要用 `content status --json` 解释原因；不绕过 DRM，也不主动 hydration。PDF 只处理当前可解析的本地 source；不要把 PDF 命令当作已证明 non-hydrating 的 iCloud placeholder probe。
-
-完整笔记归档使用 `--complete-notes` 的 fail-closed 路径；失败时不能降级成普通 export 后声称完整。普通导出遵守用户给定的输出与 overwrite 策略。
-
-## 完成判断
-
-不要把 exit 0 当成目标完成；以返回数据证明结果，并区分 empty、not found、unavailable、degraded、warning 与 CloudKit acknowledgement。