@jackss119/shelf 1.0.0

package/lib/manifest.mjs

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const MANIFEST_NAME = ".shelf.json";
+// 历史名：读取时自动兼容，saveManifest 落新名并删旧文件
+const LEGACY_MANIFEST_NAMES = [".atk.json", ".agent-toolkit.json"];
+
+export function manifestPath(cwd = process.cwd()) {
+  return path.join(cwd, MANIFEST_NAME);
+}
+
+function existingLegacyPath(cwd = process.cwd()) {
+  for (const name of LEGACY_MANIFEST_NAMES) {
+    const p = path.join(cwd, name);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function loadManifest(cwd = process.cwd()) {
+  let file = manifestPath(cwd);
+  if (!fs.existsSync(file)) {
+    file = existingLegacyPath(cwd) ?? file;
+  }
+  if (!fs.existsSync(file)) {
+    return {
+      source: null,
+      skillsDir: ".claude/skills",
+      skills: {},
+      shelf: {},
+    };
+  }
+  const data = JSON.parse(fs.readFileSync(file, "utf8"));
+  data.skills ??= {};
+  data.shelf ??= {};
+  return data;
+}
+
+export function saveManifest(manifest, cwd = process.cwd()) {
+  const file = manifestPath(cwd);
+  fs.writeFileSync(file, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+  for (let legacy = existingLegacyPath(cwd); legacy; legacy = existingLegacyPath(cwd)) {
+    fs.rmSync(legacy);
+    console.log(`（已迁移 ${path.basename(legacy)} → ${MANIFEST_NAME}）`);
+  }
+}
+
+// shelf 段以 shelf 相对路径（真实名）为键，见 SHELF 决策 #6
+export function setShelfEntry(manifest, shelfPath, entry) {
+  manifest.shelf ??= {};
+  manifest.shelf[shelfPath] = entry;
+}
+
+export function findShelfEntryByLocalPath(manifest, localPath) {
+  const normalized = localPath.replaceAll("\\", "/");
+  for (const [shelfPath, entry] of Object.entries(manifest.shelf ?? {})) {
+    if ((entry.localPath ?? "").replaceAll("\\", "/") === normalized) {
+      return { shelfPath, entry };
+    }
+  }
+  return null;
+}

package/lib/paths.mjs

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+// 从 lib/ 向上找带 shelf/skills 的目录：
+// - monorepo 开发态（packages/shelf/lib → 仓库根）命中
+// - npx 快照（包内含 shelf/）命中
+// - 全局安装的独立 CLI 包内没有内容，返回 null，由 transport 开档口
+function findLocalRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 6; i++) {
+    if (fs.existsSync(path.join(dir, "shelf", "skills"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export const repoRoot = findLocalRoot(here);

package/lib/prompt.mjs

@@ -0,0 +1,17 @@
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+export async function choose(question, choices) {
+  const keys = choices.map((c) => c.key.toLowerCase());
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    while (true) {
+      const ans = (await rl.question(question)).trim().toLowerCase();
+      const hit = choices.find((c) => c.key.toLowerCase() === ans);
+      if (hit) return hit.key.toLowerCase();
+      stdout.write(`  please type one of: ${keys.join(", ")}\n`);
+    }
+  } finally {
+    rl.close();
+  }
+}

package/lib/shelfnames.mjs

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// `_` 前缀只是文件系统里的置顶手段（SHELF 决策 #11）：
+// 展示时隐藏，输入时两种写法都接受，落盘与 manifest 永远用真实名。
+
+const SKIP_NAMES = new Set(["node_modules", ".git", ".DS_Store"]);
+
+export function displayName(realName) {
+  return realName.replace(/^_+/, "");
+}
+
+export function displayPath(realRelPath) {
+  return realRelPath.split("/").map(displayName).join("/");
+}
+
+// 在 parentDir 下把一个展示名/真实名解析回真实目录项；不存在返回 null
+export function resolveSegment(parentDir, segment) {
+  if (fs.existsSync(path.join(parentDir, segment))) return segment;
+  for (const prefix of ["_", "__"]) {
+    const candidate = prefix + segment;
+    if (fs.existsSync(path.join(parentDir, candidate))) return candidate;
+  }
+  return null;
+}
+
+// 把用户输入的 shelf 相对路径（展示名或真实名混用皆可）解析为真实相对路径。
+// allowCreate 供 push 的目标路径使用：从第一个不存在的段起，按字面新建（created 标记返回）。
+export function resolveShelfPath(shelfDir, inputPath, { allowCreate = false } = {}) {
+  const segments = inputPath.replaceAll("\\", "/").split("/").filter(Boolean);
+  if (segments.length === 0) return null;
+
+  const realSegments = [];
+  let created = false;
+  let current = shelfDir;
+  for (let i = 0; i < segments.length; i++) {
+    const real = resolveSegment(current, segments[i]);
+    if (real === null) {
+      if (!allowCreate) return null;
+      realSegments.push(...segments.slice(i));
+      created = true;
+      break;
+    }
+    realSegments.push(real);
+    current = path.join(current, real);
+  }
+  const realRel = realSegments.join("/");
+  return { realRel, abs: path.join(shelfDir, ...realSegments), created };
+}
+
+// 全架按名字找条目（名字即 ID，SHELF 决策 #14/#15）：
+// 目录或文件的真实名/展示名匹配即命中；命中的目录不再深入其内部（内部文件是货物的组成部分，不是货物）。
+export function findByBasename(shelfDir, name) {
+  const hits = [];
+  const walk = (dir, rel) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (SKIP_NAMES.has(entry.name)) continue;
+      const entryRel = rel ? `${rel}/${entry.name}` : entry.name;
+      const matched = entry.name === name || displayName(entry.name) === name;
+      if (matched) {
+        hits.push(entryRel);
+        continue;
+      }
+      if (entry.isDirectory()) walk(path.join(dir, entry.name), entryRel);
+    }
+  };
+  walk(shelfDir, "");
+  return hits;
+}

package/lib/transport.mjs

@@ -0,0 +1,268 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { repoRoot } from "./paths.mjs";
+
+// 内容货架的默认来源（CLI 发布为公开包，这里只暴露仓库地址，不含任何访问权）
+export const DEFAULT_REMOTE = "https://github.com/Jackzz119/my-workspace.git";
+
+// 托管档口：全局安装的 CLI 自己维护的一份 clone，用户不需要手动 clone
+export const managedHomeDir = path.join(os.homedir(), ".shelf", "home");
+const refreshStamp = path.join(os.homedir(), ".shelf", ".last-refresh");
+const REFRESH_INTERVAL_MS = 60 * 1000; // 只为去重连环命令，不是保鲜策略：每次操作都会刷新
+const NL = String.fromCharCode(10);
+
+// shelf 传输层（SHELF 决策 #4 / #16 / #17）解析顺序：
+//   1. SHELF_HOME / ATK_HOME 环境变量指定的 clone
+//   2. CLI 自身所在的 clone（monorepo 内直跑 / npm link 都命中）
+//   3. ~/.shelfrc 的 home
+//   4. 托管档口 ~/.shelf/home（存在即用；每次操作都刷新，写操作强制先拉）
+//   5. npx 快照（包内带 shelf/ 但无 .git）：读操作直接用
+//   6. 都没有：自动 clone 出托管档口；快照场景或显式 ephemeral 时走一次性 clone
+
+function git(args, cwd, opts = {}) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    ...opts,
+  }).trim();
+}
+
+function firstLines(err, n = 3) {
+  return (err.stderr || err.message || "").toString().trim().split(NL).slice(0, n).join(" / ");
+}
+
+function hasShelf(root) {
+  return !!root && fs.existsSync(path.join(root, "shelf"));
+}
+
+function isGitRepo(root) {
+  return !!root && fs.existsSync(path.join(root, ".git"));
+}
+
+function pkgField(root, field) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"))[field] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function repoUrlFromPkg(root) {
+  const repo = pkgField(root, "repository");
+  const url = typeof repo === "string" ? repo : repo?.url;
+  if (!url) return null;
+  return url.startsWith("git+") ? url.slice(4) : url;
+}
+
+function readRc() {
+  for (const name of [".shelfrc", ".atkrc"]) {
+    const rcPath = path.join(os.homedir(), name);
+    if (!fs.existsSync(rcPath)) continue;
+    try {
+      return JSON.parse(fs.readFileSync(rcPath, "utf8"));
+    } catch {
+      console.warn("! ~/" + name + " 不是合法 JSON，已忽略");
+    }
+  }
+  return {};
+}
+
+function resolveRemote(rc, snapshot) {
+  return process.env.SHELF_REMOTE
+    || process.env.ATK_REMOTE
+    || rc.remote
+    || (snapshot ? repoUrlFromPkg(snapshot) : null)
+    || DEFAULT_REMOTE;
+}
+
+// 刷新托管档口：默认带 60 秒去重（防连环命令重复联网），force 无视去重；离线或失败都不阻断命令
+export function refreshManagedHome({ force = false } = {}) {
+  if (!isGitRepo(managedHomeDir)) return false;
+  if (!force) {
+    try {
+      const age = Date.now() - fs.statSync(refreshStamp).mtimeMs;
+      if (age < REFRESH_INTERVAL_MS) return false;
+    } catch { /* 没有戳记就拉一次 */ }
+  }
+  try {
+    git(["pull", "--ff-only", "--quiet"], managedHomeDir);
+    fs.mkdirSync(path.dirname(refreshStamp), { recursive: true });
+    fs.writeFileSync(refreshStamp, new Date().toISOString(), "utf8");
+    return true;
+  } catch (err) {
+    console.warn("! 托管档口更新失败（继续用本地副本）: " + firstLines(err, 1));
+    return false;
+  }
+}
+
+function createManagedHome(remote) {
+  fs.mkdirSync(path.dirname(managedHomeDir), { recursive: true });
+  console.log("⇣ 首次使用：正在把货架 clone 到 " + managedHomeDir + " …");
+  // -c core.autocrlf=false 必须在 clone 当时生效：我们按字节复制文件，
+  // 若 checkout 时做了换行符转换，工作区会永远显示"已修改"，进而卡住自动更新
+  git(["clone", "-c", "core.autocrlf=false", "--quiet", remote, managedHomeDir], os.homedir());
+  fs.writeFileSync(refreshStamp, new Date().toISOString(), "utf8");
+  console.log("✓ 档口就绪，以后所有命令都在本地跑（更新用 shelf home --update）");
+}
+
+function ephemeralClone(remote) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "shelf-"));
+  git(["clone", "--depth=1", "--filter=blob:none", "--sparse", "--quiet", remote, tmp], os.tmpdir());
+  git(["sparse-checkout", "set", "shelf"], tmp);
+  return tmp;
+}
+
+function homeContext(root, mode = "home") {
+  return { mode, root, shelfDir: path.join(root, "shelf"), cleanup() {} };
+}
+
+export function resolveShelfContext({ forWrite = false } = {}) {
+  const rc = readRc();
+
+  const explicit = [process.env.SHELF_HOME, process.env.ATK_HOME, rc.home]
+    .find((r) => hasShelf(r) && isGitRepo(r));
+  if (explicit) return homeContext(explicit);
+
+  if (hasShelf(repoRoot) && isGitRepo(repoRoot)) return homeContext(repoRoot);
+
+  if (hasShelf(managedHomeDir) && isGitRepo(managedHomeDir)) {
+    // 货架前期高频更新：写操作无条件先拉最新（避免基于旧内容提交被远端拒收），
+    // 读操作也每次刷新，仅用 60 秒戳记去重连环命令
+    refreshManagedHome({ force: forWrite });
+    return homeContext(managedHomeDir, "managed");
+  }
+
+  // npm/npx 安装的快照：有 shelf/ 没 .git
+  const snapshot = hasShelf(repoRoot) && !isGitRepo(repoRoot) ? repoRoot : null;
+  if (snapshot && !forWrite) {
+    return { mode: "snapshot", root: snapshot, shelfDir: path.join(snapshot, "shelf"), cleanup() {} };
+  }
+
+  const remote = resolveRemote(rc, snapshot);
+  const ephemeralOnly = process.env.SHELF_EPHEMERAL === "1" || rc.ephemeral === true || !!snapshot;
+
+  if (!ephemeralOnly) {
+    createManagedHome(remote);
+    return homeContext(managedHomeDir, "managed");
+  }
+
+  const tmp = ephemeralClone(remote);
+  let disposed = false;
+  const cleanup = () => {
+    if (disposed) return;
+    disposed = true;
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* 尽力而为 */ }
+  };
+  // process.exit 会跳过 finally，这里兜底，保证任何退出路径都不留临时目录
+  process.on("exit", cleanup);
+  return {
+    mode: "ephemeral",
+    root: tmp,
+    shelfDir: path.join(tmp, "shelf"),
+    cleanup,
+    keep() { disposed = true; },   // push 失败要保留现场时解除自动清理
+  };
+}
+
+export function headCommit(root) {
+  try {
+    return git(["rev-parse", "HEAD"], root) || null;
+  } catch {
+    // npx 快照没有 .git；npm 打包 git 依赖时可能注入 package.json 的 gitHead
+    return pkgField(root, "gitHead");
+  }
+}
+
+export function remoteUrl(root) {
+  try {
+    return git(["config", "--get", "remote.origin.url"], root) || null;
+  } catch {
+    return repoUrlFromPkg(root);
+  }
+}
+
+function hasGitIdentity(root) {
+  try {
+    return !!git(["config", "user.email"], root);
+  } catch {
+    return false;
+  }
+}
+
+// 全新机器可能还没配 git 身份，会导致档口提交失败。只给我们自己建的档口兜底，
+// 绝不改用户自己的 clone。
+function isToolOwnedClone(root) {
+  const r = path.resolve(root);
+  return r === path.resolve(managedHomeDir) || r.startsWith(path.resolve(os.tmpdir()));
+}
+
+function ensureManagedIdentity(root) {
+  if (!isToolOwnedClone(root)) return;
+  if (hasGitIdentity(root)) return;
+  const email = "shelf@" + os.hostname();
+  git(["config", "user.name", "shelf"], root);
+  git(["config", "user.email", email], root);
+  console.log("（本机未配置 git 身份，已给本次 clone 设 shelf <" + email + ">；想换成自己的：git -C " + root + " config user.name 你的名字）");
+}
+
+// 提交失败时把货架工作区恢复原状，避免半改状态被下次 push 误判成「异机修改」
+function restoreWorktree(root, relPaths) {
+  for (const args of [
+    ["reset", "--quiet", "--", ...relPaths],
+    ["checkout", "--", ...relPaths],
+    ["clean", "-qfd", "--", ...relPaths],
+  ]) {
+    try { git(args, root); } catch { /* 尽力而为 */ }
+  }
+}
+
+// 提交 shelf 下的指定路径；有 remote 则尝试 push。
+// 返回 { committed, sha, pushed, pushError, failed }
+export function commitAndPush(root, relPaths, message) {
+  let sha;
+  try {
+    ensureManagedIdentity(root);
+    git(["add", "--", ...relPaths], root);
+
+    let staged = true;
+    try {
+      git(["diff", "--cached", "--quiet", "--", ...relPaths], root);
+      staged = false; // exit 0 = 无差异
+    } catch {
+      staged = true;
+    }
+    if (!staged) return { committed: false, sha: null, pushed: false, pushError: null };
+
+    git(["commit", "--quiet", "-m", message], root);
+    sha = headCommit(root);
+    // 消除换行符转换残留，保持工作区干净，避免下次 git pull 被本地改动挡住
+    try { git(["checkout", "--", ...relPaths], root); } catch { /* 尽力而为 */ }
+  } catch (err) {
+    restoreWorktree(root, relPaths);
+    return { committed: false, sha: null, pushed: false, pushError: firstLines(err), failed: true };
+  }
+
+  if (!remoteUrl(root)) {
+    return { committed: true, sha, pushed: false, pushError: "no-remote" };
+  }
+  try {
+    git(["push", "--quiet"], root);
+    return { committed: true, sha, pushed: true, pushError: null };
+  } catch (err) {
+    const msg = firstLines(err, 2);
+    // 远端比我们新（non-fast-forward）：把本地提交变基到最新远端上，重推一次
+    if (/fetch first|non-fast-forward|rejected/i.test(msg)) {
+      try {
+        git(["pull", "--rebase", "--autostash", "--quiet"], root);
+        git(["push", "--quiet"], root);
+        return { committed: true, sha: headCommit(root), pushed: true, pushError: null, rebased: true };
+      } catch (err2) {
+        return { committed: true, sha, pushed: false, pushError: firstLines(err2, 1) };
+      }
+    }
+    return { committed: true, sha, pushed: false, pushError: firstLines(err, 1) };
+  }
+}

package/lib/version.mjs

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+function walkFiles(dir, base = dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walkFiles(full, base));
+    } else if (entry.isFile()) {
+      out.push(path.relative(base, full).split(path.sep).join("/"));
+    }
+  }
+  return out;
+}
+
+export function contentHash(target) {
+  const hash = crypto.createHash("sha256");
+  if (fs.statSync(target).isFile()) {
+    hash.update("file\0");
+    hash.update(fs.readFileSync(target));
+    return `sha256:${hash.digest("hex")}`;
+  }
+  const files = walkFiles(target).sort();
+  for (const rel of files) {
+    hash.update(rel);
+    hash.update("\0");
+    hash.update(fs.readFileSync(path.join(target, rel)));
+    hash.update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@jackss119/shelf",
+  "version": "1.0.0",
+  "description": "Personal content shelf CLI: browse, pull and push skills, templates, docs and snippets across every machine you work on.",
+  "type": "module",
+  "bin": {
+    "shelf": "bin/shelf.mjs",
+    "atk": "bin/shelf.mjs"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jackzz119/my-workspace.git",
+    "directory": "packages/shelf"
+  },
+  "homepage": "https://github.com/Jackzz119/my-workspace/tree/main/packages/shelf#readme",
+  "bugs": {
+    "url": "https://github.com/Jackzz119/my-workspace/issues"
+  },
+  "keywords": [
+    "cli",
+    "skills",
+    "claude-code",
+    "codex",
+    "agent",
+    "dotfiles",
+    "sync",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}