@christang/keel 5.73.1 → 5.75.0

package/README.md

@@ -46,22 +46,35 @@ Node.js `>=20.19.0` (the bundled OpenSpec CLI needs it).
 
 ## Install
 
-Two pieces: the `keel` CLI and the `keel` plugin.
-
-**CLI** — one command (also installs the bundled OpenSpec CLI):
+**Claude Code** — the plugin is the whole install. It is the published `@christang/keel`
+package, so it carries the `keel` CLI and the bundled OpenSpec along with the skills and hooks,
+and the agent's `keel` commands run the copy the plugin brought:
 
 ```bash
-npm install -g @christang/keel
-keel --version
+claude plugin marketplace add TanglmChris/keel
+claude plugin install keel@keel-marketplace
 ```
 
-**Plugin** — the execution skills and runtime hooks:
+Updates arrive by themselves once a project is set up: `keel --init --target claude` (and
+`keel --install`) declares auto-update for `keel-marketplace` in the project's
+`.claude/settings.json`, which Claude reads before its own default of off. A new release is fetched
+in the background after a session's first message; `/reload-plugins` applies it in the running
+session, and otherwise it applies at the next start. To opt out, set that entry's `autoUpdate` to
+`false`; Keel keeps a value the project states, and `keel --doctor` reports which one is declared.
+
+**Codex, and your own terminal** — install the CLI as well (it also installs the bundled
+OpenSpec CLI):
 
 ```bash
-claude plugin install keel@<marketplace>   # Claude Code
+npm install -g @christang/keel
+keel --version
 codex plugin add keel@<marketplace>        # Codex
 ```
 
+A global `keel` comes first on PATH, ahead of the plugin's copy, so on Claude Code the agent runs
+it instead. Keep it at the plugin's version or remove it (`npm rm -g @christang/keel`); the
+session-start line names it whenever the two disagree.
+
 <details>
 <summary>Install the latest unreleased build from GitHub</summary>
 

package/README.zh-CN.md

@@ -38,22 +38,30 @@ Node.js `>=20.19.0`（内置的 OpenSpec CLI 需要）。
 
 ## 安装
 
-两部分：`keel` CLI 和 `keel` 插件。
-
-**CLI** —— 一条命令（同时装上捆绑的 OpenSpec CLI）：
+**Claude Code** —— 装插件就够了。插件本身就是发布的 `@christang/keel` 包，技能和 hook 之外还带着
+`keel` CLI 和捆绑的 OpenSpec；agent 运行的 `keel` 就是插件带来的这一份：
 
 ```bash
-npm install -g @christang/keel
-keel --version
+claude plugin marketplace add TanglmChris/keel
+claude plugin install keel@keel-marketplace
 ```
 
-**插件** —— 执行技能和运行时 hook：
+项目初始化后，更新会自己到来：`keel --init --target claude`（以及 `keel --install`）会在项目的
+`.claude/settings.json` 里为 `keel-marketplace` 声明自动更新，Claude 先读这个声明，而不是它默认的"关闭"。
+新版本会在会话发出第一条消息后在后台下载；执行 `/reload-plugins` 即在当前会话生效，否则下次启动时生效。
+不想自动更新，就把那一项的 `autoUpdate` 设为 `false`；项目写明的值 Keel 会保留，`keel --doctor` 会报告当前声明的是哪一个。
+
+**Codex，以及你自己的终端** —— 另外装一份 CLI（同时装上捆绑的 OpenSpec CLI）：
 
 ```bash
-claude plugin install keel@<marketplace>   # Claude Code
+npm install -g @christang/keel
+keel --version
 codex plugin add keel@<marketplace>        # Codex
 ```
 
+全局装的 `keel` 在 PATH 里排在插件那份前面，所以在 Claude Code 里 agent 会用它。要么让它和插件同版本，
+要么卸掉（`npm rm -g @christang/keel`）；两者版本不一致时，会话启动那一行会指出来。
+
 > 捆绑的 OpenSpec 依赖在安装时会打印一行 opt-in 的 shell 补全提示。如果你的 npm 拦截安装脚本，
 > 这行提示会被跳过，它纯属装饰，keel 照常工作。
 

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.73.1 -->
+<!-- keel:start version=5.75.0 -->
 ## Keel Bootstrap
 
 - Start every session with `keel context`; OpenSpec artifacts and Git are the only durable authority — never native memory, goals, or transcripts.

package/bin/keel

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+"use strict";
+
+// The bare `keel` a Claude plugin's `bin/` puts on the agent's PATH (#164).
+// On Claude the plugin is this published package, and the host adds `bin/`
+// to PATH by file name, so `keel.js` alone would answer to `keel.js`. npm's
+// own `bin` map keeps pointing at `keel.js`; this file only gives the plugin
+// the same name.
+require("./keel.js");

package/bin/keel.js

@@ -755,6 +755,46 @@ function openspecReportedVersion(command) {
   return match ? match[0] : null;
 }
 
+// What the project declares about Keel plugin auto-update (#164). Claude reads
+// it first from `autoUpdate` on the marketplace's `extraKnownMarketplaces`
+// entry, and `keel --install --target claude` writes it. The host reports no
+// auto-update state Keel could read, so this is the declaration only; whether
+// updates actually arrive is the host's to show.
+function pluginAutoUpdateDeclaration(repo) {
+  const settingsPath = path.join(repo, ".claude", "settings.json");
+  const observation =
+    "Keel reads the declaration; the host does not expose whether updates run";
+  let entry;
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    entry = ((settings && settings.extraKnownMarketplaces) || {})[
+      "keel-marketplace"
+    ];
+  } catch {
+    entry = undefined;
+  }
+  if (entry && entry.autoUpdate === true) {
+    return [
+      "ok",
+      `.claude/settings.json declares keel-marketplace autoUpdate: true; ${observation}`,
+    ];
+  }
+  if (entry && entry.autoUpdate === false) {
+    return [
+      "manual",
+      ".claude/settings.json declares keel-marketplace autoUpdate: false, "
+        + "which is the project's choice; updates arrive only through "
+        + "`claude plugin update`",
+    ];
+  }
+  return [
+    "manual",
+    "not declared, so Claude leaves auto-update off for this marketplace; "
+      + "run keel --install --target claude, or enable it under /plugin → "
+      + "Marketplaces",
+  ];
+}
+
 // The root is the repository under diagnosis, never PACKAGE_ROOT. Rooting this
 // at Keel's own install location made the line a statement about a repository
 // the reader was never shown: a consumer pinning 9.9.9 was told the version
@@ -769,21 +809,28 @@ function openspecReportedVersion(command) {
 // project that does not depend on OpenSpec directly. A lockfile that exists and
 // cannot be parsed is a read failure. Collapsing them would either warn at
 // everyone or hide a real failure.
+//
+// The lockfile is the one npm installs from: `npm-shrinkwrap.json` when it
+// exists, else `package-lock.json`. A package that publishes itself — Keel
+// does since #164 — carries the shrinkwrap, because npm never publishes a
+// `package-lock.json`.
 function declaredOpenSpecVersion(repo) {
-  const lockPath = path.join(repo, "package-lock.json");
-  if (!fs.existsSync(lockPath)) return { state: "none", version: null };
+  const lockName = ["npm-shrinkwrap.json", "package-lock.json"].find((name) =>
+    fs.existsSync(path.join(repo, name))
+  );
+  if (!lockName) return { state: "none", version: null, lockName: null };
   let lock;
   try {
-    lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    lock = JSON.parse(fs.readFileSync(path.join(repo, lockName), "utf8"));
   } catch {
-    return { state: "unreadable", version: null };
+    return { state: "unreadable", version: null, lockName };
   }
   for (const [name, entry] of Object.entries(lock.packages || {})) {
     if (name.endsWith("@fission-ai/openspec") && entry && entry.version) {
-      return { state: "declared", version: entry.version };
+      return { state: "declared", version: entry.version, lockName };
     }
   }
-  return { state: "none", version: null };
+  return { state: "none", version: null, lockName };
 }
 
 // "Not installed" and "installed and Keel cannot reach it" need different
@@ -1565,6 +1612,10 @@ function printTargetSurface(repo, target) {
             : "claude plugin install keel@<marketplace>"
         } and verify in a fresh session`
     );
+    if (target === "claude") {
+      const [status, detail] = pluginAutoUpdateDeclaration(repo);
+      printDoctorLine("plugin auto-update", status, detail);
+    }
   }
 
   const openspecSkillRoot = openspecSkillRootForTarget(target);
@@ -1686,7 +1737,7 @@ function runDoctor(options) {
     const declaredText = {
       declared: `repo pins ${declared.version}`,
       none: "repo declares no OpenSpec version",
-      unreadable: "repo package-lock.json unreadable",
+      unreadable: `repo ${declared.lockName} unreadable`,
     }[declared.state];
     const versions = `${resolvedVersion || "version unreadable"}, ${declaredText}`;
     printDoctorLine(