@kairyou/agent-tools 0.7.2 → 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,10 +90,10 @@ 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
 
 # With a compatible API relay, its quota info is shown instead, e.g.:
@@ -104,10 +104,6 @@ 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.
 
-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.
-
 ### Provider usage
 
 For API relay / gateway setups: shows the relay's balance / quota inside the

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,9 +87,10 @@ 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
 
 # 使用兼容的 API 中转时, 显示中转的额度信息, 比如:
@@ -98,9 +100,6 @@ npx -y @kairyou/agent-tools@latest statusline -a claude
 其中 `5h` / `w` 是 Claude 的滚动用量窗口, `⟳` 后面是重置倒计时;
 中转额度信息的兼容性与配置见下方 [Provider usage](#provider-usage).
 
-如需控制显示项, 修改 `~/.agent-tools/config.jsonc` 里的
-`statusline.fields`. 安装器更新时只会补充缺失的默认键, 不会动你的修改和注释.
-
 ### Provider usage
 
 面向使用 API 中转的场景: 在 agent 内直接显示中转网关的余额/额度, 按量付费或

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.7.2",
+  "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, "/");
@@ -445,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",
@@ -558,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;
     }
@@ -586,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.`
@@ -612,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}`);
 }
 
@@ -623,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,
@@ -634,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"
+);