@kairyou/agent-tools 0.7.1 → 0.7.4

package/README.md

@@ -75,8 +75,8 @@ npx -y @kairyou/agent-tools@latest <capability> -a <agent...>
 
 `--dry-run` previews, `--uninstall` unwires the integration from the agent, and
 re-running the install command updates. The installer only touches config
-entries it wrote itself; shared files under `~/.agent-tools` are kept on
-uninstall.
+entries it wrote itself, and `config.jsonc` updates only add missing default
+keys without touching your edits or comments.
 
 | Capability | Claude Code | Codex | OpenCode |
 | --- | --- | --- | --- |
@@ -90,19 +90,19 @@ uninstall.
 npx -y @kairyou/agent-tools@latest statusline -a claude
 ```
 
-The installer writes `statusLine` to `~/.claude/settings.json`. The default
-output is:
+The installer writes `statusLine` to `~/.claude/settings.json`. Example output:
 
 ```text
+# Pick and order the fields via statusline.fields in ~/.agent-tools/config.jsonc:
 ⎇ main | Opus 4.8 | 5h 7% ⟳2h54m | w 41% ⟳3d1h
-```
 
-Here `5h` and `w` are Claude's rolling usage windows; `⟳` is the reset countdown.
-When a compatible API relay is active, the statusline also appends provider usage.
+# With a compatible API relay, its quota info is shown instead, e.g.:
+⎇ main | Opus 4.8 | API | balance $362 | today $61.7 | 30d $566
+```
 
-To choose what appears, edit `statusline.fields` in
-`~/.agent-tools/config.jsonc`. Installer updates only add missing default keys
-and never touch your edits or comments.
+Here `5h` and `w` are Claude's rolling usage windows and `⟳` is the reset
+countdown; see [Provider usage](#provider-usage) below for relay quota
+compatibility and configuration.
 
 ### Provider usage
 
@@ -149,6 +149,19 @@ Keep `preset` set to `auto` for automatic detection. Select a specific protocol
 only when you know which usage endpoint the gateway exposes; a configured
 custom route id is also accepted.
 
+Output examples:
+
+```text
+# Relay plan quota.
+API | D $0.0/$100 | W $0.0/$300 | Exp 07-08
+
+# Wallet balance.
+API | balance $362 | today $61.7 | 30d $566
+```
+
+Fields: `D/W/M` are daily/weekly/monthly spend against plan limits; `Exp` is
+the plan expiry; `balance` is wallet credit; `today` and `30d` are API spend.
+
 #### Custom gateway routes
 
 For gateways the built-in probes cannot reach (e.g. cookie-authenticated
@@ -198,19 +211,6 @@ export async function run(context, { requestJson, agentConfig }) {
 through to the next route (with `providerUsage.debug` enabled, failures are
 logged to `~/.agent-tools/logs/usage-debug.log`).
 
-Output examples:
-
-```text
-# Relay plan quota.
-API | D $0.0/$100 | W $0.0/$300 | Exp 07-08
-
-# Wallet balance.
-API | balance $362 | today $61.7 | 30d $566
-```
-
-Fields: `D/W/M` are daily/weekly/monthly spend against plan limits; `Exp` is
-the plan expiry; `balance` is wallet credit; `today` and `30d` are API spend.
-
 ### Vision (cross-model image understanding)
 
 Lets a main model that cannot see images ask a multimodal model specific questions about an image (local path or http(s) URL) and reason on from the answers. Typical uses: reading error screenshots, implementing UI from design mockups, locating the glitch in a bug-report screenshot. One installer capability bundling three parts: the `inspect_image` MCP stdio server, the `at-vision` policy skill, and a human diagnostic CLI.

package/README.zh-CN.md

@@ -72,7 +72,8 @@ npx -y @kairyou/agent-tools@latest <capability> -a <agent...>
 ```
 
 `--dry-run` 预览, `--uninstall` 解除对应集成, 重新执行安装命令即为更新.
-安装器只改动自己写入的配置项; 卸载会保留 `~/.agent-tools` 下的共享文件.
+安装器只改动自己写入的配置项, 更新 `config.jsonc` 时只补充缺失的默认键,
+不会动你的修改和注释.
 
 | Capability | Claude Code | Codex | OpenCode |
 | --- | --- | --- | --- |
@@ -86,17 +87,18 @@ npx -y @kairyou/agent-tools@latest <capability> -a <agent...>
 npx -y @kairyou/agent-tools@latest statusline -a claude
 ```
 
-安装器会把 `statusLine` 写入 `~/.claude/settings.json`. 默认显示:
+安装器会把 `statusLine` 写入 `~/.claude/settings.json`. 输出示例:
 
 ```text
+# 显示项与顺序由 ~/.agent-tools/config.jsonc 的 statusline.fields 控制:
 ⎇ main | Opus 4.8 | 5h 7% ⟳2h54m | w 41% ⟳3d1h
-```
 
-其中 `5h` / `w` 是 Claude 的滚动用量窗口, `⟳` 后面是重置倒计时.
-使用兼容的 API 中转时, statusline 还会追加 provider usage.
+# 使用兼容的 API 中转时, 显示中转的额度信息, 比如:
+⎇ main | Opus 4.8 | API | balance $362 | today $61.7 | 30d $566
+```
 
-如需控制显示项, 修改 `~/.agent-tools/config.jsonc` 里的
-`statusline.fields`. 安装器更新时只会补充缺失的默认键, 不会动你的修改和注释.
+其中 `5h` / `w` 是 Claude 的滚动用量窗口, `⟳` 后面是重置倒计时;
+中转额度信息的兼容性与配置见下方 [Provider usage](#provider-usage).
 
 ### Provider usage
 
@@ -138,6 +140,19 @@ provider 的 `base_url` 和密钥; Claude Code: 读取 `ANTHROPIC_BASE_URL` 与
 保持 `preset: "auto"` 即可自动探测. 只有明确知道网关开放的是哪种用量协议时,
 才指定相应的内置 preset 或已配置的自定义 route id.
 
+显示效果示例:
+
+```text
+# 中转套餐额度.
+API | D $0.0/$100 | W $0.0/$300 | Exp 07-08
+
+# 钱包余额.
+API | balance $362 | today $61.7 | 30d $566
+```
+
+字段含义: `D/W/M` 是日/周/月套餐消耗与上限, `Exp` 是套餐到期日,
+`balance` 是钱包余额, `today` / `30d` 是今日与近 30 天 API 消耗.
+
 #### 自定义网关路由
 
 内置探测覆盖不到的网关(比如 cookie 认证的中转), 可以自己写路由模块并在
@@ -184,19 +199,6 @@ export async function run(context, { requestJson, agentConfig }) {
 `text` 是自由字符串; 成功返回 `{ text }`, 抛错则回落到下一条路由
 (开启 `providerUsage.debug` 后, 失败会记录到 `~/.agent-tools/logs/usage-debug.log`).
 
-显示效果示例:
-
-```text
-# 中转套餐额度.
-API | D $0.0/$100 | W $0.0/$300 | Exp 07-08
-
-# 钱包余额.
-API | balance $362 | today $61.7 | 30d $566
-```
-
-字段含义: `D/W/M` 是日/周/月套餐消耗与上限, `Exp` 是套餐到期日,
-`balance` 是钱包余额, `today` / `30d` 是今日与近 30 天 API 消耗.
-
 ### Vision(跨模型识图)
 
 让不支持图片的主模型借助多模态模型识图: 针对图片(本地路径或 http(s) URL)提出具体问题, 拿到答案后继续自己的推理. 常见场景: 读取报错截图, 按设计稿还原 UI, 定位测试反馈截图里的界面问题. 一个安装器 capability 包含三部分: `inspect_image` MCP stdio server, `at-vision` 策略 skill, 以及人工诊断 CLI.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.7.1",
+  "version": "0.7.4",
   "description": "Reusable Agent Skills and installable integrations (statusline, provider usage, vision) for Codex, Claude Code, and opencode.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kairyou/agent-tools.git"
+  },
   "engines": {
     "node": ">=22"
   },

package/scripts/install.mjs

@@ -45,6 +45,7 @@
 //   -h, --help                Show this help.
 
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -93,6 +94,7 @@ const USAGE_SKILL_NAME = "at-usage";
 const USAGE_SKILL_SRC = path.join(REPO_ROOT, "integrations", "usage", "skills", USAGE_SKILL_NAME);
 const VISION_BUNDLED_MCP_SERVER = path.join(REPO_ROOT, "dist", "vision", "mcp-server.mjs");
 const VISION_BUNDLED_CLI = path.join(REPO_ROOT, "dist", "vision", "cli.mjs");
+const INSTALL_STATE_PATH = path.join(INSTALL_ROOT, "install-state.json");
 
 function fwd(p) {
   return p.replace(/\\/g, "/");
@@ -242,7 +244,9 @@ function installRuntimeAssets(opts) {
   }
   console.log(`runtime: ${INSTALL_ROOT}`);
   for (const [src, dest, options] of files) copyRuntimeFile(src, dest, opts.dryRun, options);
-  if (wants(opts, "usage")) syncUsageRoutesDir(opts.dryRun);
+  // The statusline refreshes via the usage engine, so it needs packaged
+  // routes too.
+  if (wants(opts, "usage") || wants(opts, "statusline")) syncUsageRoutesDir(opts.dryRun);
 }
 
 // Repo-shipped usage routes are replaced wholesale so routes removed from the
@@ -443,13 +447,12 @@ const VISION_RATE_LIMIT_STATE = path.join(INSTALL_ROOT, "cache", "vision-rate-li
 const VISION_DIST_DIR = path.join(REPO_ROOT, "dist", "vision");
 const VISION_RUNTIME_SERVER = path.join(VISION_RUNTIME_DIR, "mcp-server.mjs");
 const VISION_RUNTIME_CLI = path.join(VISION_RUNTIME_DIR, "cli.mjs");
-const SKILL_MARKER = ".agent-tools-managed.json";
-const VISION_SKILL_MARKER_DATA = Object.freeze({
+const VISION_SKILL_IDENTITY = Object.freeze({
   owner: "@kairyou/agent-tools",
   capability: "vision",
   artifact: "skill",
 });
-const USAGE_SKILL_MARKER_DATA = Object.freeze({
+const USAGE_SKILL_IDENTITY = Object.freeze({
   owner: "@kairyou/agent-tools",
   capability: "usage",
   artifact: "skill",
@@ -556,26 +559,110 @@ function installVisionRuntime(opts) {
   }
 }
 
-function isManagedSkillDir(dest, markerData) {
-  const marker = path.join(dest, SKILL_MARKER);
-  if (!fs.existsSync(marker)) return false;
+function skillManifestKey(dest) {
+  const resolved = fwd(path.resolve(dest));
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function skillHash(skillFile) {
+  if (!fs.existsSync(skillFile)) return "";
+  return createHash("sha256").update(fs.readFileSync(skillFile)).digest("hex");
+}
+
+function matchesIdentity(value, identity) {
+  return Object.entries(identity).every(([key, expected]) => value?.[key] === expected);
+}
+
+function readInstallState() {
+  const value = readJson(INSTALL_STATE_PATH);
+  if (Object.keys(value).length === 0) return { version: 1, artifacts: {} };
+  if (
+    value.version !== 1 ||
+    !value.artifacts ||
+    typeof value.artifacts !== "object" ||
+    Array.isArray(value.artifacts)
+  ) {
+    throw new Error(`Cannot parse ${INSTALL_STATE_PATH}: unsupported install state schema`);
+  }
+  return value;
+}
+
+function writeInstallState(state) {
+  if (Object.keys(state.artifacts).length === 0) {
+    fs.rmSync(INSTALL_STATE_PATH, { force: true });
+    return;
+  }
+  const text = JSON.stringify(state, null, 2) + "\n";
+  const suffix = `${process.pid}-${Date.now()}`;
+  const stage = `${INSTALL_STATE_PATH}.stage-${suffix}`;
+  const backup = `${INSTALL_STATE_PATH}.backup-${suffix}`;
+  let movedCurrent = false;
+  fs.mkdirSync(path.dirname(INSTALL_STATE_PATH), { recursive: true });
   try {
-    const value = JSON.parse(fs.readFileSync(marker, "utf8"));
-    return Object.entries(markerData).every(([key, expected]) => value?.[key] === expected);
-  } catch {
-    return false;
+    fs.writeFileSync(stage, text);
+    if (fs.existsSync(INSTALL_STATE_PATH)) {
+      fs.renameSync(INSTALL_STATE_PATH, backup);
+      movedCurrent = true;
+    }
+    fs.renameSync(stage, INSTALL_STATE_PATH);
+    fs.rmSync(backup, { force: true });
+  } catch (error) {
+    fs.rmSync(stage, { force: true });
+    if (movedCurrent && !fs.existsSync(INSTALL_STATE_PATH) && fs.existsSync(backup)) {
+      fs.renameSync(backup, INSTALL_STATE_PATH);
+    }
+    throw error;
+  } finally {
+    fs.rmSync(stage, { force: true });
+    if (fs.existsSync(INSTALL_STATE_PATH)) fs.rmSync(backup, { force: true });
   }
+  console.log(`  wrote ${INSTALL_STATE_PATH}`);
+}
+
+function managedSkillStatus(dest, identity) {
+  const entry = readInstallState().artifacts[skillManifestKey(dest)];
+  if (entry) {
+    if (!matchesIdentity(entry, identity)) return "other";
+    const currentHash = skillHash(path.join(dest, "SKILL.md"));
+    return currentHash && currentHash === entry.sha256 ? "managed" : "modified";
+  }
+  return "unmanaged";
+}
+
+function recordManagedSkill(dest, identity) {
+  const state = readInstallState();
+  state.artifacts[skillManifestKey(dest)] = {
+    path: fwd(path.resolve(dest)),
+    ...identity,
+    sha256: skillHash(path.join(dest, "SKILL.md")),
+  };
+  writeInstallState(state);
+}
+
+function forgetManagedSkill(dest) {
+  const state = readInstallState();
+  if (!state.artifacts[skillManifestKey(dest)]) return;
+  delete state.artifacts[skillManifestKey(dest)];
+  writeInstallState(state);
 }
 
 function installManagedSkillDir(
   skillsRoot,
-  { name, source, markerData, replacements, remove, dryRun }
+  { name, source, identity, replacements, remove, dryRun }
 ) {
   const dest = path.join(skillsRoot, name);
-  const isManaged = () => isManagedSkillDir(dest, markerData);
+  const status = fs.existsSync(dest) ? managedSkillStatus(dest, identity) : "missing";
   if (remove) {
-    if (!fs.existsSync(dest)) return;
-    if (!isManaged()) {
+    if (!fs.existsSync(dest)) {
+      if (!dryRun) forgetManagedSkill(dest);
+      return;
+    }
+    if (status === "modified") {
+      if (!dryRun) forgetManagedSkill(dest);
+      console.log(`  kept modified skill and released ownership ${dest}`);
+      return;
+    }
+    if (status !== "managed") {
       console.log(`  kept unmanaged ${dest}`);
       return;
     }
@@ -584,10 +671,18 @@ function installManagedSkillDir(
       return;
     }
     fs.rmSync(dest, { recursive: true, force: true });
+    forgetManagedSkill(dest);
     console.log(`  removed ${dest}`);
     return;
   }
-  if (fs.existsSync(dest) && !isManaged()) {
+  if (status === "modified") {
+    console.error(
+      `  Refusing to overwrite modified managed skill directory ${dest}. ` +
+        `Move or restore it, then re-run the install.`
+    );
+    process.exit(1);
+  }
+  if (fs.existsSync(dest) && status !== "managed") {
     console.error(
       `  Refusing to overwrite existing unowned skill directory ${dest}. ` +
         `Move or remove it, then re-run the install.`
@@ -610,10 +705,7 @@ function installManagedSkillDir(
     skill = skill.replaceAll(token, value);
   }
   fs.writeFileSync(skillFile, skill);
-  fs.writeFileSync(
-    path.join(dest, SKILL_MARKER),
-    JSON.stringify(markerData, null, 2) + "\n"
-  );
+  recordManagedSkill(dest, identity);
   console.log(`  wrote ${dest}`);
 }
 
@@ -621,7 +713,7 @@ function installVisionSkillDir(skillsRoot, { remove, dryRun }) {
   installManagedSkillDir(skillsRoot, {
     name: VISION_SKILL_NAME,
     source: VISION_SKILL_SRC,
-    markerData: VISION_SKILL_MARKER_DATA,
+    identity: VISION_SKILL_IDENTITY,
     replacements: { "{{VISION_CLI_PATH}}": fwd(VISION_RUNTIME_CLI) },
     remove,
     dryRun,
@@ -632,7 +724,7 @@ function installUsageSkillDir(skillsRoot, agent, { remove, dryRun }) {
   installManagedSkillDir(skillsRoot, {
     name: USAGE_SKILL_NAME,
     source: USAGE_SKILL_SRC,
-    markerData: USAGE_SKILL_MARKER_DATA,
+    identity: USAGE_SKILL_IDENTITY,
     replacements: {
       "{{USAGE_CLI_PATH}}": fwd(RUNTIME.usageCli),
       "{{USAGE_AGENT}}": agent,

package/scripts/release.mjs

@@ -3,52 +3,20 @@
 //
 // Usage:
 //   npm run release [-- minor|major]   # default: patch
-//   npm run release -- --dry-run       # npm test + preview tarball, no bump/publish
+//   npm run release -- --dry-run       # npm test + preview tarball, no bump/push
 //
-// Steps: clean-tree check -> npm auth check -> npm test -> npm version -> npm publish -> git push
+// Local steps: clean-tree check -> npm test -> npm version -> git push --follow-tags.
+// Publishing runs on GitHub Actions via npm trusted publishing (OIDC, no
+// tokens, no npm login): .github/workflows/release.yml publishes when the
+// version tag lands.
 //
 // Release when scripts/ integrations/ config.default.jsonc or
 // package.json deps change — npx users only get these from the published package.
 // (skills/ ships from GitHub via `npx skills add`; no release needed.)
 
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
 
 const BUMPS = ["patch", "minor", "major"];
-const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-const PACKAGE_NAME = packageJson.name;
-
-if (typeof PACKAGE_NAME !== "string" || PACKAGE_NAME.trim() === "") {
-  console.error("package.json must define a non-empty name before releasing.");
-  process.exit(2);
-}
-
-function readNpmConfig(key) {
-  const npmExecPath = process.env.npm_execpath;
-  const result = npmExecPath
-    ? spawnSync(process.execPath, [npmExecPath, "config", "get", key], { encoding: "utf8" })
-    : spawnSync("npm", ["config", "get", key], { encoding: "utf8", shell: true });
-
-  if (result.status !== 0) {
-    const detail = result.stderr?.trim() || result.error?.message || "npm config exited unexpectedly";
-    console.error(`Unable to read npm config ${key}:\n${detail}`);
-    process.exit(result.status ?? 2);
-  }
-
-  const value = result.stdout?.trim();
-  return value && value !== "undefined" && value !== "null" ? value : undefined;
-}
-
-const packageScope = PACKAGE_NAME.match(/^(@[^/]+)\//)?.[1];
-const REGISTRY = (packageScope && readNpmConfig(`${packageScope}:registry`)) || readNpmConfig("registry");
-
-try {
-  const registryUrl = new URL(REGISTRY);
-  if (!["http:", "https:"].includes(registryUrl.protocol)) throw new Error("unsupported protocol");
-} catch {
-  console.error("npm registry config must be a valid HTTP(S) URL before releasing.");
-  process.exit(2);
-}
 
 let bump = "patch";
 let dryRun = false;
@@ -61,66 +29,33 @@ for (const arg of process.argv.slice(2)) {
   }
 }
 
-function run(command, opts = {}) {
-  const { onFailure, ...spawnOptions } = opts;
+function run(command) {
   console.log(`\n> ${command}`);
-  const result = spawnSync(command, { stdio: "inherit", shell: true, ...spawnOptions });
+  const result = spawnSync(command, { stdio: "inherit", shell: true });
   if (result.status !== 0) {
     console.error(`\nAborted: \`${command}\` exited with ${result.status}.`);
-    onFailure?.();
     process.exit(result.status ?? 1);
   }
 }
 
-function printCommands(message, commands) {
-  console.error(`\n${message}\n`);
-  for (const command of commands) console.error(`  ${command}`);
-}
-
 const status = spawnSync("git status --porcelain", { shell: true, encoding: "utf8" });
 if (!dryRun && status.stdout.trim() !== "") {
   console.error("Working tree is not clean — commit or stash first:\n" + status.stdout);
   process.exit(1);
 }
 
-if (!dryRun) {
-  // Fail before npm version creates a commit and tag when the saved token is stale.
-  run(`npm whoami --registry=${REGISTRY}`, {
-    onFailure() {
-      printCommands("npm authentication is missing or expired. Log in, verify the account, then retry:", [
-        `npm login --registry=${REGISTRY}`,
-        `npm whoami --registry=${REGISTRY}`,
-        `npm run release -- ${bump}`,
-      ]);
-    },
-  });
-}
-
 run("npm test");
 
 if (dryRun) {
   // Shows exactly which files would ship; verify nothing is missing/extra.
   run("npm pack --dry-run");
-  console.log("\nDry run complete. No version bump, nothing published.");
+  console.log("\nDry run complete. No version bump, nothing pushed.");
   process.exit(0);
 }
 
 run(`npm version ${bump}`);
-run("npm publish", {
-  onFailure() {
-    printCommands(
-      "npm publish failed after the version commit and tag were created. Do not run the release command again. Fix authentication/permissions, then resume:",
-      [
-        `npm login --registry=${REGISTRY}`,
-        `npm whoami --registry=${REGISTRY}`,
-        `npm owner ls ${PACKAGE_NAME}`,
-        "npm publish",
-        `npm view ${PACKAGE_NAME} version`,
-        "git push --follow-tags",
-      ],
-    );
-  },
-});
 run("git push --follow-tags");
 
-console.log("\nRelease complete.");
+console.log(
+  "\nTag pushed. GitHub Actions publishes it: https://github.com/kairyou/agent-tools/actions"
+);