@jackss119/shelf 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jackzz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# shelf
+
+个人内容货架 CLI：把技能、模板、文档、代码片段放在一个 git 仓库里，在任何设备上取用和回传。
+
+```bash
+npm i -g @jackss119/shelf
+shelf init        # 在当前项目落下 manifest + 操作手册
+```
+
+首次运行时，shelf 会自动把内容仓库 clone 到 `~/.shelf/home` 当作本地档口，之后所有命令都在本地跑（每次操作前自动拉最新）。**你不需要手动 clone 任何东西。**
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `shelf` | 交互浏览货架：数字进目录 · `p 1,3-5` 拉取所选 · `a` 全部 · `..` 上级 · `q` 退出 |
+| `shelf pull <路径...> [--dest <目录>]` | 按路径拉取到当前目录 |
+| `shelf create <本地路径> [--to <货架目录>]` | 上架新内容：全架查重名，交互选位（`m <名>` 建目录 · `d` 放这里） |
+| `shelf push <本地路径>` | 更新已有内容：按记账/名字自动定位，不用填地址 |
+| `shelf sync [--dry-run]` | 按账本对账：库上新版自动更新本地；本地有改动则显示 diff 由你定方向 |
+| `shelf init` | 初始化工作区（`.shelf.json` + `shelf-ops` 操作手册） |
+| `shelf home [--update]` | 查看货架在哪、什么模式；`--update` 立即拉取最新 |
+
+`atk` 是 `shelf` 的别名。
+
+## 货架从哪来
+
+按序解析，第一个命中的生效：
+
+1. `SHELF_HOME` 环境变量指向的 clone
+2. CLI 自身所在的 clone（monorepo 开发态 / `npm link`）
+3. `~/.shelfrc` 里的 `{"home": "..."}`
+4. 托管档口 `~/.shelf/home`（不存在就自动创建）
+
+用别的内容仓库：设 `SHELF_REMOTE=<git地址>`，或写进 `~/.shelfrc` 的 `{"remote": "..."}`。
+临时机器不想留档口：设 `SHELF_EPHEMERAL=1`，写操作走一次性 clone，用完即删。
+
+## 给 AI 用
+
+`shelf init` 会在工作区装下 `shelf-ops` 操作手册，Claude Code / Codex 读到它就知道全部命令、退出码语义和冲突处理守则。非交互环境下：`create` 需要 `--to`，`push`/`create` 的确认需要 `--yes`，异机冲突需要人工确认后加 `--force`。
+
+## License
+
+MIT

package/bin/shelf.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import {
+  cmdShelfBrowse,
+  cmdShelfPull,
+  cmdShelfPush,
+  cmdShelfCreate,
+  cmdShelfSync,
+  cmdShelfInit,
+  cmdShelfHome,
+} from "../lib/commands/shelf.mjs";
+
+function usage() {
+  console.log(`shelf — 个人内容货架 CLI（别名 atk）
+
+Usage:
+  shelf                  交互浏览货架（数字进目录，p 1,3-5 拉取，a 全部）
+  shelf pull <路径...>    按路径拉取，如 shelf pull skills/common/intj
+                         [--dest <目录>]
+  shelf create <本地路径> 上架新货：全架查重名，交互选位（m <名> 建目录，
+                         d 放下）[--to <货架目录>] [--yes]
+  shelf push <本地路径>   更新已有货：按记账/名字自动定位
+                         [--yes] [--force] [--force-secret]
+  shelf sync [--dry-run] 按账本对账：库上新版自动更新本地；本地有改动
+                         则显示 diff 由你决定推上库还是覆盖本地
+  shelf init             初始化工作区（.shelf.json + shelf-ops 手册）
+  shelf home [--update]  查看货架在哪、什么模式；--update 拉取最新
+
+货架定位：SHELF_HOME 环境变量 > 本 clone > ~/.shelfrc > 托管档口 ~/.shelf/home
+免 clone 直跑：npx -y -p github:Jackzz119/my-workspace shelf <命令>`);
+}
+
+const argv = process.argv.slice(2);
+const sub = argv[0];
+const rest = argv.slice(1);
+
+try {
+  switch (sub) {
+    case undefined:
+    case "browse":
+      await cmdShelfBrowse();
+      break;
+    case "pull":
+      await cmdShelfPull(rest);
+      break;
+    case "create":
+      await cmdShelfCreate(rest);
+      break;
+    case "push":
+      await cmdShelfPush(rest);
+      break;
+    case "sync":
+      await cmdShelfSync(rest);
+      break;
+    case "init":
+      await cmdShelfInit(rest);
+      break;
+    case "home":
+      await cmdShelfHome(rest);
+      break;
+    case "-h":
+    case "--help":
+    case "help":
+      usage();
+      break;
+    case "skills":
+    case "list":
+      console.error(`'shelf ${sub}' 已随老版技能命令清退：浏览用 shelf，按路径拉取用 shelf pull <路径> --dest .claude/skills，保持最新用 shelf sync`);
+      process.exit(1);
+      break;
+    default:
+      console.error(`Unknown command: ${sub}\n`);
+      usage();
+      process.exit(1);
+  }
+} catch (err) {
+  console.error(err.message || err);
+  process.exit(1);
+}