left-skills 0.1.8 → 0.2.0

package/README.md

@@ -2,89 +2,98 @@
 
 # left-skills
 
-**shift-left for skills** — 在 skill 投入使用前就度量它用没用,而不是等用户撞 bug。
+**shift-left for skills** — measure how your AI skills are used before users hit bugs.
 
 [![npm version](https://img.shields.io/npm/v/left-skills)](https://www.npmjs.com/package/left-skills)
 [![license](https://img.shields.io/npm/l/left-skills)](./LICENSE)
 [![stars](https://img.shields.io/github/stars/cuikexi/left-skills)](https://github.com/cuikexi/left-skills)
 
+[中文](./README.zh.md)
+
 </div>
 
-## 命名由来
+## Why "left-skills"?
 
-`left-skills` = **shift-left for skills**。把质量/度量左移到"投入使用前"——你写完 skill,先看它用没用、写得好不好,而不是等用户撞 bug 才发现。
+`left-skills` = **shift-left for skills**. Move quality/measurement "left" — to *before* a skill is put into use — instead of waiting for users to hit bugs. Know which skills never get called, fix them early.
 
 ## How It Works
 
 ```
-打 /skill 或 AI 调 skill
-    │ Claude Code hook 触发
+type /skill or AI invokes a skill
+    │ Claude Code hook fires
     ▼
-left-skills hook(三数据源)
-  - UserPromptExpansion.command_name   (手动 /slash)
-  - PreToolUse.tool_input.skill        (AI 调 Skill 工具)
-  - UserPromptSubmit.prompt            (自然语言提及)
-    │ 解析 payload,取 skill 名
+left-skills hook (3 sources)
+  - UserPromptExpansion.command_name   (manual /slash)
+  - PreToolUse.tool_input.skill        (AI invokes Skill tool)
+  - UserPromptSubmit.prompt            (natural-language mention)
+    │ parse payload, extract skill name
     ▼
-~/.left-skills/usage.json (append 记录)
+~/.left-skills/usage.json (append records)
     │
     ▼
-left-skills usage 报告(手动/AI/提及 分开 + 从未调用 ⚠)
+left-skills usage report (manual / AI / mention split + never-called ⚠)
 ```
 
 ## Installation
 
 ```bash
 npm i -g left-skills
-left-skills install   # 输出 hook 片段,复制进 ~/.claude/settings.json 的 hooks 字段
+left-skills install --write   # auto-config hooks into ~/.claude/settings.json (merge + backup .bak)
 ```
 
-详见 [docs/install.md](docs/install.md)。
+> Don't want auto-write? `left-skills install` prints a snippet to add manually. See [docs/install.md](docs/install.md).
+
+## Uninstall
+
+```bash
+left-skills uninstall           # remove hooks (backup .bak)
+npm uninstall -g left-skills    # remove binary
+```
 
 ## Quick Start
 
 ```bash
-left-skills usage            # 人看报告
-left-skills usage --json     # AI 用(JSON)
-left-skills usage --since 7  # 近 7 天
+left-skills usage            # human-readable report
+left-skills usage --json     # for AI (JSON)
+left-skills usage --since 7  # last 7 days
 ```
 
-报告示例:
+Example:
 
 ```
-skill 调用报告(14 个 skill)
+skill usage report (14 skills)
 ────────────────────────────────────
-  3  grill-me            (手动1 + AI1 + 提及1,最近 今天)
-  0  gitlab-ci-generate  ⚠ 从未调用
+  3  grill-me            (manual1 + AI1 + mention1, last today)
+  0  gitlab-ci-generate  ⚠ never called
 ```
 
 ## Highlights
 
-- **三数据源 hook 埋点**:手动 /slash、AI 调 Skill、自然语言提及,分开记
-- **诚实报告**:手动/AI/提及 分开标(不混"调用次数"),从未调用 ⚠
-- **给 AI 用**:`--json` 输出,AI 能解析决策(改/删 skill)
-- **单文件 bundle**:TS 打包单 `.js`,随 skill 生态分发
+- **3-source hook tracking**: manual `/slash`, AI Skill-tool invoke, natural-language mention — tracked separately
+- **Honest reporting**: manual/AI/mention split (no fake "call count"), never-called ⚠
+- **For AI use**: `--json` output, AI can parse to decide (improve/delete skill)
+- **Single-file bundle**: TS bundled to one `.js`, ships via skill ecosystem
 
 ## Limitations
 
-- 只 **Claude Code**(Cursor / Codex 后扩)
-- **AI 纯 progressive disclosure 自主激活**(不走 Skill 工具)抓不到——只手动 /slash + AI 调 Skill 工具 + 自然语言提及
-- 需装 hook 配置(用户加 settings.json)
-- MVP 期(早期,API 可能变)
+- **Claude Code only** (Cursor / Codex later)
+- **AI pure progressive-disclosure auto-activation** (not via Skill tool) can't be tracked — only manual `/slash` + AI Skill-tool + natural-language mention
+- Requires hook config (user adds to settings.json)
+- MVP stage (early, API may change)
 
 ## Contributing
 
-PR 欢迎。开发:
+PRs welcome. Dev setup:
 
 ```bash
 git clone https://github.com/cuikexi/left-skills
 cd left-skills
 npm install
 npm run build
-npm link   # 本地 left-skills 进 PATH
+npm link   # local left-skills into PATH
 ```
 
-提 PR 前 `npm run build` 确保 dist 最新。理念 / roadmap 见 [docs/roadmap.md](docs/roadmap.md)。
+Run `npm run build` before PR to ensure dist is fresh. Philosophy / roadmap see [docs/roadmap.md](docs/roadmap.md).
 
 ## Star History
 

package/README.zh.md

@@ -0,0 +1,104 @@
+<div align="center">
+
+# left-skills
+
+**shift-left for skills** — 在 skill 投入使用前就度量它用没用,而不是等用户撞 bug。
+
+[![npm version](https://img.shields.io/npm/v/left-skills)](https://www.npmjs.com/package/left-skills)
+[![license](https://img.shields.io/npm/l/left-skills)](./LICENSE)
+[![stars](https://img.shields.io/github/stars/cuikexi/left-skills)](https://github.com/cuikexi/left-skills)
+
+[English](./README.md)
+
+</div>
+
+## 命名由来
+
+`left-skills` = **shift-left for skills**。把质量/度量左移到"投入使用前"——你写完 skill,先看它用没用、写得好不好,而不是等用户撞 bug 才发现。
+
+## How It Works
+
+```
+打 /skill 或 AI 调 skill
+    │ Claude Code hook 触发
+    ▼
+left-skills hook(三数据源)
+  - UserPromptExpansion.command_name   (手动 /slash)
+  - PreToolUse.tool_input.skill        (AI 调 Skill 工具)
+  - UserPromptSubmit.prompt            (自然语言提及)
+    │ 解析 payload,取 skill 名
+    ▼
+~/.left-skills/usage.json (append 记录)
+    │
+    ▼
+left-skills usage 报告(手动/AI/提及 分开 + 从未调用 ⚠)
+```
+
+## Installation
+
+```bash
+npm i -g left-skills
+left-skills install --write   # 自动配 hook 到 ~/.claude/settings.json(合并去重 + 备份 .bak)
+```
+
+> 不想自动写?`left-skills install` 输出片段手动加。详见 [docs/install.md](docs/install.md)。
+
+## 卸载
+
+```bash
+left-skills uninstall           # 删 hook(备份 .bak)
+npm uninstall -g left-skills    # 卸 binary
+```
+
+## Quick Start
+
+```bash
+left-skills usage            # 人看报告
+left-skills usage --json     # AI 用(JSON)
+left-skills usage --since 7  # 近 7 天
+```
+
+报告示例:
+
+```
+skill 调用报告(14 个 skill)
+────────────────────────────────────
+  3  grill-me            (手动1 + AI1 + 提及1,最近 今天)
+  0  gitlab-ci-generate  ⚠ 从未调用
+```
+
+## Highlights
+
+- **三数据源 hook 埋点**:手动 `/slash`、AI 调 Skill、自然语言提及,分开记
+- **诚实报告**:手动/AI/提及 分开标(不混"调用次数"),从未调用 ⚠
+- **给 AI 用**:`--json` 输出,AI 能解析决策(改/删 skill)
+- **单文件 bundle**:TS 打包单 `.js`,随 skill 生态分发
+
+## Limitations
+
+- 只 **Claude Code**(Cursor / Codex 后扩)
+- **AI 纯 progressive disclosure 自主激活**(不走 Skill 工具)抓不到——只手动 `/slash` + AI 调 Skill 工具 + 自然语言提及
+- 需装 hook 配置(用户加 settings.json)
+- MVP 期(早期,API 可能变)
+
+## Contributing
+
+PR 欢迎。开发:
+
+```bash
+git clone https://github.com/cuikexi/left-skills
+cd left-skills
+npm install
+npm run build
+npm link   # 本地 left-skills 进 PATH
+```
+
+提 PR 前 `npm run build` 确保 dist 最新。理念 / roadmap 见 [docs/roadmap.md](docs/roadmap.md)。
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=cuikexi/left-skills&type=Date)](https://star-history.com/#cuikexi/left-skills&date)
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli.js

@@ -3047,22 +3047,26 @@ var {
 var import_node_fs = require("fs");
 var import_node_path = require("path");
 var import_node_os = require("os");
-var STORE_PATH = (0, import_node_path.join)((0, import_node_os.homedir)(), ".left-skills", "usage.json");
-function ensureStore() {
-  const dir = (0, import_node_path.dirname)(STORE_PATH);
+function getStorePath() {
+  return process.env.LEFT_SKILLS_STORE || (0, import_node_path.join)((0, import_node_os.homedir)(), ".left-skills", "usage.json");
+}
+function ensureStore(path) {
+  const dir = (0, import_node_path.dirname)(path);
   if (!(0, import_node_fs.existsSync)(dir)) (0, import_node_fs.mkdirSync)(dir, { recursive: true });
-  if (!(0, import_node_fs.existsSync)(STORE_PATH)) (0, import_node_fs.writeFileSync)(STORE_PATH, "[]", "utf-8");
+  if (!(0, import_node_fs.existsSync)(path)) (0, import_node_fs.writeFileSync)(path, "[]", "utf-8");
 }
 function appendRecord(record) {
-  ensureStore();
+  const path = getStorePath();
+  ensureStore(path);
   const records = readRecords();
   records.push(record);
-  (0, import_node_fs.writeFileSync)(STORE_PATH, JSON.stringify(records, null, 2), "utf-8");
+  (0, import_node_fs.writeFileSync)(path, JSON.stringify(records, null, 2), "utf-8");
 }
 function readRecords() {
-  ensureStore();
+  const path = getStorePath();
+  ensureStore(path);
   try {
-    return JSON.parse((0, import_node_fs.readFileSync)(STORE_PATH, "utf-8"));
+    return JSON.parse((0, import_node_fs.readFileSync)(path, "utf-8"));
   } catch {
     return [];
   }
@@ -3198,26 +3202,98 @@ function relativeTime(iso) {
   return `${days} \u5929\u524D`;
 }
 
+// src/install.ts
+var import_node_fs3 = require("fs");
+var import_node_os3 = require("os");
+var import_node_path3 = require("path");
+function hookSnippet() {
+  const cmd = "left-skills hook";
+  return {
+    hooks: {
+      UserPromptExpansion: [
+        { matcher: ".*", hooks: [{ type: "command", command: `${cmd} UserPromptExpansion` }] }
+      ],
+      PreToolUse: [
+        { matcher: "Skill", hooks: [{ type: "command", command: `${cmd} PreToolUse` }] }
+      ],
+      UserPromptSubmit: [
+        { hooks: [{ type: "command", command: `${cmd} UserPromptSubmit` }] }
+      ]
+    }
+  };
+}
+function writeHooksToSettings(settingsPath) {
+  if ((0, import_node_fs3.existsSync)(settingsPath)) {
+    (0, import_node_fs3.copyFileSync)(settingsPath, settingsPath + ".bak");
+  }
+  let settings = {};
+  if ((0, import_node_fs3.existsSync)(settingsPath)) {
+    try {
+      settings = JSON.parse((0, import_node_fs3.readFileSync)(settingsPath, "utf-8"));
+    } catch {
+      settings = {};
+    }
+  }
+  const snippet = hookSnippet();
+  if (!settings.hooks) settings.hooks = {};
+  for (const [event, entries] of Object.entries(snippet.hooks)) {
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = entries;
+    } else {
+      for (const entry of entries) {
+        const exists = settings.hooks[event].some((e) => JSON.stringify(e) === JSON.stringify(entry));
+        if (!exists) settings.hooks[event].push(entry);
+      }
+    }
+  }
+  (0, import_node_fs3.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
+function removeHooksFromSettings(settingsPath) {
+  if (!(0, import_node_fs3.existsSync)(settingsPath)) return;
+  (0, import_node_fs3.copyFileSync)(settingsPath, settingsPath + ".bak");
+  let settings = {};
+  try {
+    settings = JSON.parse((0, import_node_fs3.readFileSync)(settingsPath, "utf-8"));
+  } catch {
+    return;
+  }
+  if (!settings.hooks) return;
+  for (const event of Object.keys(settings.hooks)) {
+    settings.hooks[event] = settings.hooks[event].filter((entry) => {
+      entry.hooks = (entry.hooks || []).filter((h) => !(h.command && h.command.includes("left-skills")));
+      return entry.hooks.length > 0;
+    });
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  (0, import_node_fs3.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
+function globalSettingsPath() {
+  return (0, import_node_path3.join)((0, import_node_os3.homedir)(), ".claude", "settings.json");
+}
+
 // package.json
 var package_default = {
   name: "left-skills",
-  version: "0.1.8",
+  version: "0.2.0",
   description: "\u7ED9 AI \u7528\u7684 skill \u751F\u547D\u5468\u671F\u7BA1\u7406\u5DE5\u5177 \u2014 MVP: skill \u8C03\u7528\u4F7F\u7528\u7EDF\u8BA1",
   bin: {
     "left-skills": "./dist/cli.js"
   },
   scripts: {
     build: "tsup",
-    dev: "tsup --watch"
+    dev: "tsup --watch",
+    test: "node --import tsx --test test/**/*.test.ts"
   },
   dependencies: {
     commander: "^12.0.0",
     "gray-matter": "^4.0.3"
   },
   devDependencies: {
-    typescript: "^5.4.0",
+    "@types/node": "^20.0.0",
     tsup: "^8.0.0",
-    "@types/node": "^20.0.0"
+    tsx: "^4.22.4",
+    typescript: "^5.4.0"
   },
   author: "cuikexi",
   license: "MIT",
@@ -3253,6 +3329,23 @@ program2.command("usage").description("skill \u8C03\u7528\u4F7F\u7528\u62A5\u544
     console.log(formatHuman(report));
   }
 });
+program2.command("install").description("\u8F93\u51FA hook \u914D\u7F6E\u7247\u6BB5(\u9ED8\u8BA4)\u6216 --write \u81EA\u52A8\u5199\u8FDB ~/.claude/settings.json(\u5408\u5E76+\u5907\u4EFD .bak)").option("--write", "\u81EA\u52A8\u5199 hook \u5230 settings.json(\u5408\u5E76\u53BB\u91CD + \u5907\u4EFD .bak)", false).action((opts) => {
+  if (opts.write) {
+    const path = globalSettingsPath();
+    writeHooksToSettings(path);
+    console.log(`\u2713 hook \u5DF2\u5199\u5165 ${path}(\u5DF2\u5907\u4EFD .bak)`);
+    console.log("  \u6253 /skill \u6216 AI \u8C03 skill \u4F1A\u81EA\u52A8\u8BB0\u5F55,\u8DD1 left-skills usage \u770B\u62A5\u544A");
+  } else {
+    console.log(JSON.stringify(hookSnippet(), null, 2));
+    console.log("\n# \u628A\u4E0A\u9762\u7247\u6BB5\u52A0\u8FDB ~/.claude/settings.json \u7684 hooks \u5B57\u6BB5,\u6216\u8DD1 left-skills install --write \u81EA\u52A8\u5199");
+  }
+});
+program2.command("uninstall").description("\u5220 ~/.claude/settings.json \u7684 left-skills hook(\u5E72\u51C0\u5378\u8F7D,\u5907\u4EFD .bak)").action(() => {
+  const path = globalSettingsPath();
+  removeHooksFromSettings(path);
+  console.log(`\u2713 left-skills hook \u5DF2\u4ECE ${path} \u5220\u9664(\u5DF2\u5907\u4EFD .bak)`);
+  console.log("  \u518D\u8DD1 npm uninstall -g left-skills \u5378\u8F7D binary");
+});
 program2.command("hook <event>").description("hook \u5165\u53E3(\u8BFB stdin payload)").action(async (event) => {
   const payload = await readStdinPayload();
   if (!payload) return;
@@ -3270,20 +3363,4 @@ program2.command("hook <event>").description("hook \u5165\u53E3(\u8BFB stdin pay
       break;
   }
 });
-program2.command("install").description("\u8F93\u51FA hook \u914D\u7F6E\u7247\u6BB5(\u52A0\u8FDB ~/.claude/settings.json \u7684 hooks \u5B57\u6BB5)").action(() => {
-  const cmd = "left-skills hook";
-  console.log(JSON.stringify({
-    hooks: {
-      UserPromptExpansion: [
-        { matcher: ".*", hooks: [{ type: "command", command: `${cmd} UserPromptExpansion` }] }
-      ],
-      PreToolUse: [
-        { matcher: "Skill", hooks: [{ type: "command", command: `${cmd} PreToolUse` }] }
-      ],
-      UserPromptSubmit: [
-        { hooks: [{ type: "command", command: `${cmd} UserPromptSubmit` }] }
-      ]
-    }
-  }, null, 2));
-});
 program2.parse();

package/package.json

@@ -1,22 +1,24 @@
 {
   "name": "left-skills",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "给 AI 用的 skill 生命周期管理工具 — MVP: skill 调用使用统计",
   "bin": {
     "left-skills": "./dist/cli.js"
   },
   "scripts": {
     "build": "tsup",
-    "dev": "tsup --watch"
+    "dev": "tsup --watch",
+    "test": "node --import tsx --test test/**/*.test.ts"
   },
   "dependencies": {
     "commander": "^12.0.0",
     "gray-matter": "^4.0.3"
   },
   "devDependencies": {
-    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0",
     "tsup": "^8.0.0",
-    "@types/node": "^20.0.0"
+    "tsx": "^4.22.4",
+    "typescript": "^5.4.0"
   },
   "author": "cuikexi",
   "license": "MIT",