@chiimagnus/applebookscli 0.1.6 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # AppleBooksCLI
 
-AppleBooksCLI 是一个用于 macOS Apple Books 的命令行工具。你可以直接查询自己的书库、阅读状态、划线与笔记，读取可用的 EPUB/PDF 内容，导出笔记，并在需要时安全地修改笔记或藏书。
+[AppleBooksCLI](https://github.com/chiimagnus/AppleBooksCLI) 是一个用于 macOS Apple Books 的命令行工具。你可以直接查询自己的书库、阅读状态、划线与笔记，读取可用的 EPUB/PDF 内容，导出笔记，并在需要时安全地修改笔记或藏书。
 
 ## 主要功能
 
@@ -10,35 +10,36 @@ AppleBooksCLI 是一个用于 macOS Apple Books 的命令行工具。你可以
 - 读取可用 EPUB 的目录、章节、元数据与批注上下文。
 - 提取 PDF 划线与笔记。
 - 导出 JSON、CSV、Markdown 或 HTML。
-- 安全修改笔记、管理藏书，并在写入前自动备份。
-- 安装随 CLI 一起分发的 `applebookscli` Skill，供 Codex/AI 直接使用。
+- **安全修改笔记、管理藏书，并在写入前自动备份。**
+- 提供标准 `applebookscli` Agent Skill。
 
 ## 系统要求
 
-- macOS 12 或更高版本。
-- npm 发布的预编译版本目前支持 Apple Silicon（arm64）。
 - 读取 Apple Books 数据时，macOS 可能要求为终端或调用进程授予 Full Disk Access。
 - 未下载的 EPUB、DRM 内容或当前系统无法读取的内容会明确提示不可用或能力受限；AppleBooksCLI 不绕过系统保护。
 
 ## 安装
 
-安装稳定版：
-
 ```sh
-npm install --global @chiimagnus/applebookscli
-applebookscli --version
-```
+# 安装 CLI
+npm install --global @chiimagnus/applebookscli@latest
 
-如果需要试用 beta：
+# 安装 SKILL.md；首次安装时由 Agent Skills CLI 选择目标 Agent
+CLI_VERSION="$(applebookscli --version)"
+npx -y skills@1.5.23 add "chiimagnus/AppleBooksCLI#v${CLI_VERSION}" --skill applebookscli --global
 
-```sh
-npm install --global @chiimagnus/applebookscli@beta
 ```
 
-更新到最新稳定版：
+之后通过 npm 升级 CLI 时，若该 Skill 仍由 Agent Skills CLI 管理，npm `postinstall` 会把它自动切到相同的 `v<CLI版本>` tag 并调用官方 updater；没有安装 Skill 的用户不会受到影响。使用 `--ignore-scripts` 会显式关闭这条自动联动。此前手工复制的 Skill 没有 source tracking，只需按上面的标准命令重新安装一次即可接入后续自动更新。
+
+## 获取帮助
+
+CLI 自带完整帮助，具体命令与参数以当前安装版本为准：
 
 ```sh
-npm install --global @chiimagnus/applebookscli@latest
+applebookscli --help
+applebookscli <group> --help
+applebookscli <group> <subcommand> --help
 ```
 
 ## 快速开始
@@ -144,40 +145,17 @@ 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：
-
-```sh
-applebookscli skill install
-```
-
-它会安装到 `${CODEX_HOME:-~/.codex}/skills/applebookscli`。如果目标已经存在，CLI 默认不会覆盖；需要明确替换时使用：
-
-```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
-```
-
 ## 开发与维护
 
 架构、CLI contract、写入安全、发布流程和其它维护者文档从 [`docs/index.md`](docs/index.md) 开始。
 
 ## License
 
-AppleBooksCLI 使用 GNU Affero General Public License v3（AGPLv3）。第三方 notice 与许可证文本见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 和 [`ThirdPartyLicenses/`](ThirdPartyLicenses/)。
+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,75 @@
+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 skillName = "applebookscli";
+const source = "chiimagnus/AppleBooksCLI";
+const sourceURL = "https://github.com/chiimagnus/AppleBooksCLI.git";
+const skillsVersion = "1.5.23";
+
+async function runUpdater() {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      "npx",
+      ["-y", `skills@${skillsVersion}`, "update", skillName, "-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 entry = lock.skills?.[skillName];
+  if (
+    !entry ||
+    entry.sourceType !== "github" ||
+    (entry.source !== source && entry.sourceUrl !== sourceURL)
+  ) {
+    return;
+  }
+
+  const targetRef = `v${packageJSON.version}`;
+  if (entry.ref !== targetRef) {
+    const mode = (await stat(lockPath)).mode & 0o777;
+    const temporary = `${lockPath}.${process.pid}.tmp`;
+    entry.ref = targetRef;
+    await writeFile(temporary, `${JSON.stringify(lock, null, 2)}\n`, { mode });
+    await rename(temporary, lockPath);
+  }
+
+  const code = await runUpdater();
+  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.0",
   "description": "Native Apple Books CLI for macOS on Apple Silicon.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -17,16 +17,16 @@
   "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",
     "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。