@christang/keel 5.73.1 → 5.75.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@christang/keel",
   "displayName": "Keel",
   "description": "Keel OpenSpec execution discipline CLI for Claude Code, Codex, and OpenCode.",
-  "version": "5.73.1",
+  "version": "5.75.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,6 +17,7 @@
     "src/core/",
     "assets/",
     "README.md",
+    "npm-shrinkwrap.json",
     "plugins/",
     "!**/__pycache__",
     "!**/*.pyc"

package/plugins/keel/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.73.1",
+  "version": "5.75.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.73.1",
+  "version": "5.75.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/scripts/session-start.js

@@ -160,13 +160,16 @@ function protocolVersion(cwd) {
 // stamped into its managed block. Keel reports the disagreement and stops
 // there — installing and updating are the host's, which already has commands
 // for both.
-function versionReport(cwd, cli) {
+function versionReport(cwd, cli, pathCli = null) {
   const plugin = pluginManifest();
   const found = [
     ["plugin", plugin.version],
     ["CLI", cli],
     ["protocol", protocolVersion(cwd)],
   ];
+  // A PATH copy is compared only when it exists. Its absence is the
+  // plugin-only install, which is not drift and not an unread version.
+  if (pathCli) found.push(["PATH keel", pathCli]);
   // Missing is not mismatched. A version nobody can discover never produces a
   // line on its own, or a repository with no managed block would be warned at
   // every session until its reader stopped looking — and fewer than two
@@ -184,10 +187,31 @@ function versionReport(cwd, cli) {
     .map(([name]) => name)
     .join(" and ");
   const missing = unread ? ` (${unread} undiscovered, not compared)` : "";
+  // Naming the reload rather than a restart (#164): the host's
+  // `/reload-plugins` swaps hooks in the running session, so "restart" sent
+  // the reader to the expensive remedy for a cheap one.
+  // The host puts the user's PATH ahead of plugin `bin/` directories, so a
+  // global install is what the agent's own `keel` commands run even though
+  // this hook ran the plugin's. Both remedies are named; neither is run.
+  const shadow = pathCli && pathCli !== cli
+    ? ` The \`keel\` on PATH (${pathCli}) shadows this plugin's CLI for the `
+      + "agent's commands, because the host puts your PATH first: remove it "
+      + "with `npm rm -g @christang/keel`, since the plugin carries its own, "
+      + `or align it with \`npm i -g @christang/keel@${cli}\`.`
+    : "";
   return `runtime versions disagree: ${named}${missing}. A session's hooks are `
-    + "fixed at session start, so an updated plugin applies only after "
-    + `restarting. Updating is ${plugin.remedy}, which Keel names and does `
-    + "not run.";
+    + "fixed when it loads the plugin, so an updated plugin applies after "
+    + "`/reload-plugins` or at the next session start. Updating is "
+    + `${plugin.remedy}, which Keel names and does not run.${shadow}`;
+}
+
+// The `keel` a bare command resolves, asked only when this hook ran its own
+// CLI; with no such command there is nothing to compare.
+function pathCliVersion(cwd) {
+  const probe = runKeel(cwd, ["--version"], "keel");
+  if (probe.error || probe.status !== 0) return null;
+  const match = String(probe.stdout || "").match(/\d+\.\d+\.\d+/);
+  return match ? match[0] : null;
 }
 
 // The Keel mark. A keel is the carina, the ridge on a bird's sternum, so the
@@ -244,8 +268,38 @@ function panel(lines) {
   ].join("\n");
 }
 
-function runKeel(cwd, args) {
-  const cli = (process.env.KEEL_CLI || "keel").trim();
+// On Claude the plugin is the published package (#164), so the CLI it shipped
+// with sits three levels above this script. It is recognized by the package's
+// name and not by the path alone: a Codex cache holds only `plugins/keel`, and
+// whatever lies above that is not this plugin's to run.
+function packagedCli() {
+  const root = path.join(__dirname, "..", "..", "..");
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(root, "package.json"), "utf8")
+    );
+    const cli = path.join(root, "bin", "keel.js");
+    if (pkg.name === "@christang/keel" && fs.existsSync(cli)) return cli;
+  } catch {
+    // No package around this script: the plugin was copied on its own.
+  }
+  return null;
+}
+
+// An explicit KEEL_CLI first, then the CLI this plugin shipped with, then
+// whatever `keel` is on PATH. The packaged CLI runs under the node running
+// this hook, so it needs neither PATH nor an executable mode.
+function keelCommand() {
+  const explicit = (process.env.KEEL_CLI || "").trim();
+  if (explicit) return { command: explicit, packaged: false };
+  const own = packagedCli();
+  if (own) {
+    return { command: `"${process.execPath}" "${own}"`, packaged: true };
+  }
+  return { command: "keel", packaged: false };
+}
+
+function runKeel(cwd, args, cli) {
   return spawnSync(`${cli} ${args.join(" ")}`, {
     cwd,
     shell: true,
@@ -283,7 +337,8 @@ function main() {
     return 0;
   }
 
-  const version = runKeel(cwd, ["--version"]);
+  const cli = keelCommand();
+  const version = runKeel(cwd, ["--version"], cli.command);
   const versionMatch = String(version.stdout || "").match(/(\d+)\.\d+\.\d+/);
   if (
     version.error
@@ -298,7 +353,7 @@ function main() {
     return 0;
   }
 
-  const result = runKeel(cwd, ["context", "--json"]);
+  const result = runKeel(cwd, ["context", "--json"], cli.command);
   if (result.error || result.status !== 0 || !String(result.stdout || "").trim()) {
     fallback("`keel context --json` failed or timed out.");
     return 0;
@@ -375,7 +430,11 @@ function main() {
         + "does not guess among candidates."
     );
   }
-  const drift = versionReport(cwd, versionMatch[0]);
+  const drift = versionReport(
+    cwd,
+    versionMatch[0],
+    cli.packaged ? pathCliVersion(cwd) : null
+  );
   if (drift) {
     lines.push(`- ${drift}`);
     human.splice(human.length - 1, 0, drift[0].toUpperCase() + drift.slice(1));

package/scripts/bump_version.js

@@ -4,22 +4,23 @@
 // One-shot version bump across every place Keel pins its version.
 //
 // The Keel validation suite requires the same version in package.json,
-// package-lock.json, both native plugin manifests, the validator constants,
-// the protocol docs, and the changelog. This script updates all of them
-// together so a release never ships half-aligned.
+// npm-shrinkwrap.json, both native plugin manifests, the Claude marketplace
+// entry and the package release it pins, the validator constants, the
+// protocol docs, and the changelog. This script updates all of them together
+// so a release never ships half-aligned.
 //
 // Usage:
 //   node scripts/bump_version.js <patch|minor|major|explicit-version>
 //
-// After running: fill in the CHANGELOG entry, then `npm test`, commit,
-// tag `vX.Y.Z`, push, and publish a GitHub Release.
+// After running, follow the steps it prints: the release lands through a pull
+// request, and nothing is tagged by hand (#162).
 
 const fs = require("fs");
 const path = require("path");
 
 const ROOT = path.resolve(__dirname, "..");
 const PKG_PATH = path.join(ROOT, "package.json");
-const LOCK_PATH = path.join(ROOT, "package-lock.json");
+const LOCK_PATH = path.join(ROOT, "npm-shrinkwrap.json");
 const CHANGELOG_PATH = path.join(ROOT, "keel", "CHANGELOG.md");
 const CHANGELOG_HEADER = "# Keel Changelog\n\n";
 const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
@@ -58,7 +59,24 @@ function bumpPackageFiles(newVersion) {
     lock.packages[""].version = newVersion;
   }
   writeJson(LOCK_PATH, lock);
-  process.stdout.write("  updated package-lock.json\n");
+  process.stdout.write("  updated npm-shrinkwrap.json\n");
+}
+
+// On Claude the plugin is the published package (#164): the marketplace entry
+// is its manifest, labeled with the release and pinned to that same release of
+// `@christang/keel`. Both numbers move, or a refresh installs the old package.
+function bumpClaudeMarketplace(newVersion) {
+  const relPath = ".claude-plugin/marketplace.json";
+  const filePath = path.join(ROOT, relPath);
+  const market = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  const entry = (market.plugins || []).find((plugin) => plugin.name === "keel");
+  if (!entry || !entry.source || typeof entry.source !== "object") {
+    fail(`expected an npm-sourced keel entry in ${relPath}`);
+  }
+  entry.version = newVersion;
+  entry.source.version = newVersion;
+  writeJson(filePath, market);
+  process.stdout.write(`  updated ${relPath}\n`);
 }
 
 function replaceInFile(relPath, replacements) {
@@ -145,6 +163,7 @@ function main() {
   process.stdout.write(`Bumping ${oldVersion} -> ${newVersion}\n`);
 
   bumpPackageFiles(newVersion);
+  bumpClaudeMarketplace(newVersion);
   replaceInFile("plugins/keel/.claude-plugin/plugin.json", [
     [`"version": "${oldVersion}"`, `"version": "${newVersion}"`],
   ]);

package/scripts/install_to_repo.py

@@ -532,6 +532,13 @@ def collect_actions(repo: Path, target: str) -> list[InstallAction]:
         )
     if "claude" in targets and not unmanaged_keel_content_warning(repo, "CLAUDE.md"):
         actions.append(managed_content_action("CLAUDE.md", CLAUDE_IMPORT_BLOCK))
+    if "claude" in targets:
+        actions.append(
+            InstallAction(
+                relative_path=Path(".claude/settings.json"),
+                strategy="claude-marketplace-settings",
+            )
+        )
 
     actions.append(openspec_config_action())
     actions.append(keel_config_action())
@@ -923,6 +930,82 @@ def action_source_content(action: InstallAction) -> str:
     return action.content or ""
 
 
+# Claude reads a marketplace's auto-update setting first from `autoUpdate` on
+# its `extraKnownMarketplaces` entry in any settings file, and defaults it off
+# for every marketplace that is not Anthropic's own (#164). The project's
+# committed `.claude/settings.json` is such a file, so declaring it here is what
+# lets a Keel release reach a project with nobody toggling anything.
+KEEL_MARKETPLACE_NAME = "keel-marketplace"
+KEEL_MARKETPLACE_ENTRY = {
+    "source": {"source": "github", "repo": "TanglmChris/keel"},
+    "autoUpdate": True,
+}
+
+
+def load_settings_object(existing: str, purpose: str) -> dict:
+    if not existing.strip():
+        return {}
+    try:
+        settings = json.loads(existing)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"cannot {purpose} .claude/settings.json because it is not valid JSON: {exc}"
+        ) from exc
+    if not isinstance(settings, dict):
+        raise ValueError(
+            f"cannot {purpose} .claude/settings.json because it is not a JSON object"
+        )
+    return settings
+
+
+def merge_claude_marketplace_settings(existing: str) -> tuple[str, str]:
+    """Declare auto-update for the Keel marketplace, keeping the project's say.
+
+    An existing entry keeps its own source — a developer may have added the
+    marketplace from a local directory under this name — and any `autoUpdate`
+    it states, because a project that wrote `false` has decided.
+    """
+    settings = load_settings_object(existing, "declare plugin auto-update in")
+    markets = settings.get("extraKnownMarketplaces", {})
+    if not isinstance(markets, dict):
+        raise ValueError(
+            "cannot declare plugin auto-update because .claude/settings.json "
+            "field 'extraKnownMarketplaces' is not an object"
+        )
+    entry = markets.get(KEEL_MARKETPLACE_NAME)
+    if isinstance(entry, dict):
+        declared = dict(entry)
+        declared.setdefault("autoUpdate", True)
+    else:
+        declared = json.loads(json.dumps(KEEL_MARKETPLACE_ENTRY))
+    merged_settings = dict(settings)
+    merged_settings["extraKnownMarketplaces"] = {**markets, KEEL_MARKETPLACE_NAME: declared}
+    merged = json.dumps(merged_settings, indent=2, ensure_ascii=False) + "\n"
+    before = (
+        json.dumps(settings, indent=2, ensure_ascii=False) + "\n"
+        if existing.strip()
+        else ""
+    )
+    return merged, "skip" if before == merged else "update"
+
+
+def remove_claude_marketplace_settings(existing: str) -> tuple[str | None, str]:
+    """Remove the entry only when it is exactly the one Keel writes."""
+    settings = load_settings_object(existing, "remove plugin auto-update from")
+    markets = settings.get("extraKnownMarketplaces")
+    if not isinstance(markets, dict) or markets.get(KEEL_MARKETPLACE_NAME) != KEEL_MARKETPLACE_ENTRY:
+        return existing, "skip"
+    remaining = {k: v for k, v in markets.items() if k != KEEL_MARKETPLACE_NAME}
+    updated = dict(settings)
+    if remaining:
+        updated["extraKnownMarketplaces"] = remaining
+    else:
+        updated.pop("extraKnownMarketplaces", None)
+    if not updated:
+        return None, "remove"
+    return json.dumps(updated, indent=2, ensure_ascii=False) + "\n", "remove-managed"
+
+
 def load_hook_config(content: str) -> dict:
     try:
         config = json.loads(content)
@@ -1047,6 +1130,15 @@ def plan_action(
     destination = require_inside_repo(repo, action.relative_path)
     source_content = action_source_content(action)
 
+    if action.strategy == "claude-marketplace-settings":
+        existing = destination.read_text(encoding="utf-8") if destination.exists() else ""
+        merged, kind = merge_claude_marketplace_settings(existing)
+        return PlannedAction(
+            "create" if not destination.exists() else kind,
+            action.relative_path,
+            merged if kind != "skip" or not destination.exists() else None,
+        )
+
     if action.strategy == "keel-hook-settings":
         existing = destination.read_text(encoding="utf-8") if destination.exists() else ""
         merged, kind = merge_keel_hook_settings(existing, source_content)
@@ -1113,6 +1205,17 @@ def plan_uninstall_managed(repo: Path, relative_path: str) -> PlannedAction:
     return PlannedAction("remove-managed", Path(relative_path), updated)
 
 
+def plan_uninstall_claude_marketplace_settings(repo: Path) -> PlannedAction:
+    relative = Path(".claude/settings.json")
+    path = require_inside_repo(repo, relative)
+    if not path.is_file():
+        return PlannedAction("skip", relative)
+    updated, kind = remove_claude_marketplace_settings(path.read_text(encoding="utf-8"))
+    if kind == "skip":
+        return PlannedAction("skip", relative)
+    return PlannedAction(kind, relative, updated)
+
+
 def plan_uninstall_template(
     repo: Path,
     relative_path: str,
@@ -1242,6 +1345,10 @@ def plan_uninstall_actions(repo: Path, target: str) -> list[PlannedAction]:
     actions.append(plan_uninstall_managed(repo, "AGENTS.md"))
     if "claude" in targets:
         actions.append(plan_uninstall_managed(repo, "CLAUDE.md"))
+        actions.append(plan_uninstall_claude_marketplace_settings(repo))
+        # Removing the settings file can leave `.claude/` holding nothing that
+        # anyone wrote, and uninstall leaves no empty directory of its own.
+        actions.append(rmdir_if_empty_action(".claude"))
 
     for action in openspec_schema_actions():
         if action.source_path is not None: