@kontextmind/kxm 0.6.0 → 0.7.10

package/scripts/emit-codex-artifacts.mjs

@@ -1,11 +1,24 @@
 #!/usr/bin/env node
 
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const MARKER_START = "<!-- kxm:codex:commands:start -->";
 const MARKER_END = "<!-- kxm:codex:commands:end -->";
+const SKILL_NAME = /^[a-z][a-z0-9-]*[a-z0-9]$/u;
+const COMMAND_NAME = /^[a-z][a-z0-9-]*$/u;
+const MANIFEST_REL = "plugins/kxm/skill-suite.json";
 
 export const CODEX_COMMANDS_BLOCK = `${MARKER_START}
 ## KXM agent commands
@@ -44,24 +57,243 @@ The \`kxm\` CLI is the unified agent surface for peer collaboration and workflow
 | \`kxm context recall <project>\` | Search durable context metadata | \`--query\`, \`--kinds\`, \`--limit\` |
 | \`kxm context state <project> <key>\` | Query authoritative temporal state | \`--as-of <timestamp>\` |
 | \`kxm context episode <project>\` | Query workflow learning episodes | \`--run\` |
-| \`kxm context promote <project> <key>\` | Propose temporal state change | \`--summary\`, \`--authority\`, \`--confidence\`, \`--evidence\` |
+| \`kxm context promote <project> <proposalId>\` | Promote an approved state proposal (control plane) | required \`--evidence <refs>\` |
 ${MARKER_END}`;
 
+function refuse(message) {
+  throw new Error(message);
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function posixContained(value, label) {
+  if (typeof value !== "string" || !value || value.includes("\\") || value.includes("\0")) {
+    refuse(`${label} must be a contained relative path`);
+  }
+  const normalized = value.startsWith("./") ? value.slice(2) : value;
+  if (!normalized || normalized.startsWith("/") || normalized.split("/").some((part) => !part || part === "." || part === "..")) {
+    refuse(`${label} must be a contained relative path`);
+  }
+  return value;
+}
+
+function containedRoot(root) {
+  return existsSync(root) ? realpathSync(root) : resolve(root);
+}
+
+function assertPathStaysInRoot(resolvedRoot, current, relativePath) {
+  const real = realpathSync(current);
+  const prefix = resolvedRoot.endsWith(sep) ? resolvedRoot : `${resolvedRoot}${sep}`;
+  if (real !== resolvedRoot && !real.startsWith(prefix)) {
+    refuse(`path escapes repository: ${relativePath}`);
+  }
+  return real;
+}
+
+function assertExistingAncestorsAreRegularContained(root, relativePath, { required = false } = {}) {
+  const resolvedRoot = containedRoot(root);
+  const parts = posixContained(relativePath, "path").split("/");
+  let current = resolvedRoot;
+  for (let i = 0; i < parts.length; i++) {
+    current = join(current, parts[i]);
+    const rel = parts.slice(0, i + 1).join("/");
+    let info;
+    try {
+      info = lstatSync(current);
+    } catch {
+      if (required) refuse(`path is missing: ${rel}`);
+      return;
+    }
+    if (info.isSymbolicLink()) refuse(`symlinks are not allowed: ${rel}`);
+    if (!info.isDirectory()) {
+      refuse(`path must be a regular contained directory: ${rel}`);
+    }
+    assertPathStaysInRoot(resolvedRoot, current, rel);
+  }
+}
+
+function assertRegularContainedPath(root, relativePath, { directory = false } = {}) {
+  const resolvedRoot = containedRoot(root);
+  const parts = posixContained(relativePath, "path").split("/");
+  let current = resolvedRoot;
+  for (let i = 0; i < parts.length; i++) {
+    current = join(current, parts[i]);
+    let info;
+    try {
+      info = lstatSync(current);
+    } catch {
+      refuse(`path is missing: ${relativePath}`);
+    }
+    if (info.isSymbolicLink()) refuse(`symlinks are not allowed: ${relativePath}`);
+    const last = i === parts.length - 1;
+    if (last ? (directory ? !info.isDirectory() : !info.isFile()) : !info.isDirectory()) {
+      refuse(`path must be a regular contained ${directory ? "directory" : "file"}: ${relativePath}`);
+    }
+  }
+  assertPathStaysInRoot(resolvedRoot, current, relativePath);
+  return current;
+}
+
+function validateSkillSuiteManifest(manifest) {
+  if (!isPlainObject(manifest)) refuse("skill suite manifest must be an object");
+  for (const key of ["id", "version", "name", "description"]) {
+    if (typeof manifest[key] !== "string" || !manifest[key].trim()) {
+      refuse(`skill suite manifest missing ${key}`);
+    }
+  }
+  if (!Array.isArray(manifest.skills) || manifest.skills.length === 0) {
+    refuse("skill suite manifest skills must be a nonempty array");
+  }
+  const names = new Set();
+  const commands = new Set();
+  for (const skill of manifest.skills) {
+    if (!isPlainObject(skill)) refuse("skill suite entry must be an object");
+    const extra = Object.keys(skill).filter((key) => !["name", "path", "ownedCommands", "intent"].includes(key));
+    if (extra.length > 0) refuse(`skill suite entry has unknown field(s): ${extra.join(", ")}`);
+    if (typeof skill.name !== "string" || !SKILL_NAME.test(skill.name)) {
+      refuse(`invalid skill name: ${skill.name ?? ""}`);
+    }
+    if (names.has(skill.name)) refuse(`duplicate skill name: ${skill.name}`);
+    names.add(skill.name);
+    posixContained(skill.path, `skill path for ${skill.name}`);
+    if (!skill.path.startsWith("./skills/") || skill.path !== `./skills/${skill.name}`) {
+      refuse(`skill path must be ./skills/${skill.name}`);
+    }
+    if (typeof skill.intent !== "string" || skill.intent.length < 10 || skill.intent.length > 200) {
+      refuse(`skill ${skill.name} intent must be 10-200 characters`);
+    }
+    if (!Array.isArray(skill.ownedCommands) || skill.ownedCommands.some((cmd) => typeof cmd !== "string" || !COMMAND_NAME.test(cmd))) {
+      refuse(`skill ${skill.name} ownedCommands must be command tokens`);
+    }
+    for (const command of skill.ownedCommands) {
+      if (commands.has(command)) refuse(`command ${command} is owned by multiple skills`);
+      commands.add(command);
+    }
+  }
+  return manifest;
+}
+
+/**
+ * Read and validate the committed skill-suite manifest. Missing, symlink,
+ * malformed, or shape-invalid manifests fail closed.
+ *
+ * @param {string} repoRoot
+ * @returns {{ id: string, version: string, name: string, description: string, skills: Array<{ name: string, path: string, ownedCommands: string[], intent: string }> }}
+ */
+export function loadSkillSuiteManifest(repoRoot) {
+  const root = resolve(repoRoot);
+  const fullPath = assertRegularContainedPath(root, MANIFEST_REL);
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(fullPath, "utf8"));
+  } catch {
+    refuse("skill suite manifest is malformed");
+  }
+  return validateSkillSuiteManifest(parsed);
+}
+
+function listFilesRecursive(dir, relativeBase = "") {
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = relativeBase ? `${relativeBase}/${entry.name}` : entry.name;
+    const full = join(dir, entry.name);
+    if (entry.isSymbolicLink() || lstatSync(full).isSymbolicLink()) {
+      refuse(`symlinks are not allowed: ${rel}`);
+    }
+    if (entry.isDirectory()) results.push(...listFilesRecursive(full, rel));
+    else if (entry.isFile()) results.push(rel);
+    else refuse(`unsupported skill artifact: ${rel}`);
+  }
+  return results.sort();
+}
+
+function ownedSkillDir(root, skillName) {
+  return assertRegularContainedPath(root, `plugins/kxm/skills/${skillName}`, { directory: true });
+}
+
+/**
+ * Return generated skill-mirror artifact paths relative to the repo root.
+ *
+ * @param {string} [repoRoot]
+ * @returns {string[]}
+ */
+export function listSkillMirrorArtifacts(repoRoot = process.cwd()) {
+  const root = resolve(repoRoot);
+  const suiteManifest = loadSkillSuiteManifest(root);
+  const artifacts = [];
+  for (const skill of suiteManifest.skills) {
+    const srcSkillDir = ownedSkillDir(root, skill.name);
+    const files = listFilesRecursive(srcSkillDir);
+    if (!files.includes("SKILL.md")) refuse(`SKILL.md missing for ${skill.name}`);
+    for (const rel of files) artifacts.push(`.agents/skills/${skill.name}/${rel}`);
+  }
+  return artifacts;
+}
+
+/**
+ * Emit the portable .agents/skills mirror from the authored plugin skills tree
+ * and update the AGENTS.md command block. Owned skills are replaced; unrelated
+ * skills are preserved. Missing or invalid manifests fail closed.
+ *
+ * @param {string} [repoRoot]
+ */
 export function emitCodexArtifacts(repoRoot = process.cwd()) {
   const root = resolve(repoRoot);
-  const srcSkillsDir = join(root, "plugins", "kxm", "skills");
+  const suiteManifest = loadSkillSuiteManifest(root);
   const destSkillsDir = join(root, ".agents", "skills");
+  assertExistingAncestorsAreRegularContained(root, ".agents/skills");
+  mkdirSync(destSkillsDir, { recursive: true });
+  assertExistingAncestorsAreRegularContained(root, ".agents/skills", { required: true });
+  const destRoot = realpathSync(destSkillsDir);
+  const repoReal = containedRoot(root);
+  const repoPrefix = repoReal.endsWith(sep) ? repoReal : `${repoReal}${sep}`;
+  if (destRoot !== repoReal && !destRoot.startsWith(repoPrefix)) {
+    refuse("path escapes repository: .agents/skills");
+  }
+  const ownedSkillNames = suiteManifest.skills.map((skill) => skill.name);
+  const emittedSkillPaths = [];
+  const preservedSkillNames = [];
 
-  // 1. Emit .agents/skills from authored skill tree
-  if (existsSync(srcSkillsDir)) {
-    mkdirSync(destSkillsDir, { recursive: true });
-    cpSync(srcSkillsDir, destSkillsDir, { recursive: true });
+  for (const skill of suiteManifest.skills) {
+    const srcSkillDir = ownedSkillDir(root, skill.name);
+    listFilesRecursive(srcSkillDir);
+    const destSkillPath = join(destSkillsDir, skill.name);
+    if (existsSync(destSkillPath)) {
+      if (lstatSync(destSkillPath).isSymbolicLink()) {
+        refuse(`symlinks are not allowed: .agents/skills/${skill.name}`);
+      }
+      rmSync(destSkillPath, { recursive: true, force: true });
+    }
+    cpSync(srcSkillDir, destSkillPath, {
+      recursive: true,
+      dereference: false,
+    });
+    if (lstatSync(destSkillPath).isSymbolicLink()) {
+      rmSync(destSkillPath, { recursive: true, force: true });
+      refuse(`symlinks are not allowed: .agents/skills/${skill.name}`);
+    }
+    const realDest = realpathSync(destSkillPath);
+    const prefix = destRoot.endsWith(sep) ? destRoot : `${destRoot}${sep}`;
+    if (realDest !== destRoot && !realDest.startsWith(prefix)) {
+      rmSync(destSkillPath, { recursive: true, force: true });
+      refuse(`path escapes repository: .agents/skills/${skill.name}`);
+    }
+    listFilesRecursive(destSkillPath);
+    emittedSkillPaths.push(destSkillPath);
+  }
+
+  for (const entry of readdirSync(destSkillsDir, { withFileTypes: true })) {
+    if (entry.isDirectory() && !ownedSkillNames.includes(entry.name)) {
+      preservedSkillNames.push(entry.name);
+    }
   }
 
-  // 2. Emit marker-delimited AGENTS.md block
   const agentsPath = join(root, "AGENTS.md");
   let agentsUpdated = false;
   if (existsSync(agentsPath)) {
+    if (lstatSync(agentsPath).isSymbolicLink()) refuse("AGENTS.md must be a regular file");
     const original = readFileSync(agentsPath, "utf8");
     let updated;
     if (original.includes(MARKER_START) && original.includes(MARKER_END)) {
@@ -82,10 +314,22 @@ export function emitCodexArtifacts(repoRoot = process.cwd()) {
     }
   }
 
-  return { destSkillsDir, agentsPath, agentsUpdated };
+  return {
+    destSkillsDir,
+    agentsPath,
+    agentsUpdated,
+    ownedSkills: ownedSkillNames,
+    preservedSkills: preservedSkillNames,
+    emittedSkillPaths,
+    artifacts: listSkillMirrorArtifacts(root),
+  };
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   const result = emitCodexArtifacts();
-  process.stdout.write(`Codex artifacts emitted: skills -> ${result.destSkillsDir}, AGENTS.md updated -> ${result.agentsUpdated}\n`);
+  process.stdout.write(
+    `Codex artifacts emitted: skills -> ${result.destSkillsDir}, ` +
+    `owned=${result.ownedSkills.length}, preserved=${result.preservedSkills.length}, ` +
+    `AGENTS.md updated -> ${result.agentsUpdated}\n`,
+  );
 }

package/scripts/harness-run.d.mts

@@ -32,11 +32,19 @@ export function parseJson(text: string): unknown;
 export function piProviderOf(model?: string): string | undefined;
 export function piModelId(model?: string): string | undefined;
 export function piAuthCheckArgs(request: { model: string; role: string }): string[];
+export function resolveLaunch(cliId: string, options?: {
+  platform?: NodeJS.Platform | string | undefined;
+  pathEnv?: string | undefined;
+  existsSync?: ((path: string) => boolean) | undefined;
+  realpathSync?: ((path: string) => string) | undefined;
+  execPath?: string | undefined;
+}): { command: string; args: string[] };
 export function resolveLauncher(cliId: string, options?: {
-  platform?: NodeJS.Platform | string;
-  pathEnv?: string;
-  existsSync?: (path: string) => boolean;
-  realpathSync?: (path: string) => string;
+  platform?: NodeJS.Platform | string | undefined;
+  pathEnv?: string | undefined;
+  existsSync?: ((path: string) => boolean) | undefined;
+  realpathSync?: ((path: string) => string) | undefined;
+  execPath?: string | undefined;
 }): string;
 export function unsupportedLauncherMessage(target: string, platform?: string): string;
 export function parseAuth(harness: string, stdio: {

package/scripts/harness-run.mjs

@@ -269,7 +269,15 @@ function isAbsoluteOn(path, platform) {
   return path.startsWith("/");
 }
 
-export function resolveLauncher(cliId, options = {}) {
+/** Allowlisted npm-global inner launchers, relative to the directory that contains `name.cmd`. */
+export const WIN_NPM_INNER_EXE = Object.freeze({
+  claude: Object.freeze(["node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe"]),
+});
+export const WIN_NPM_INNER_NODE_SCRIPT = Object.freeze({
+  pi: Object.freeze(["node_modules", "@earendil-works", "pi-coding-agent", "dist", "bundle", "cli.js"]),
+});
+
+export function resolveLaunch(cliId, options = {}) {
   const platform = options.platform ?? process.platform;
   const pathEnv = options.pathEnv ?? process.env.PATH ?? "";
   const exists = options.existsSync ?? existsSync;
@@ -282,25 +290,57 @@ export function resolveLauncher(cliId, options = {}) {
   if (cliId.includes("\0")) throw failClosed("launcher id is invalid");
 
   const explicit = cliId.includes("/") || cliId.includes("\\") || isAbsoluteOn(cliId, platform);
-  if (explicit) return assertWinExecutable(cliId, platform, options);
+  if (explicit) return { command: assertWinExecutable(cliId, platform, options), args: [] };
 
   const dirs = pathEnv.split(delim).filter(Boolean);
   let rejectedShim;
-  for (const dir of dirs) {
-    if (platform === "win32") {
-      const exeName = cliId.toLowerCase().endsWith(".exe") ? cliId : `${cliId}.exe`;
+  if (platform === "win32") {
+    const exeName = cliId.toLowerCase().endsWith(".exe") ? cliId : `${cliId}.exe`;
+    for (const dir of dirs) {
       const exe = path.join(dir, exeName);
-      if (exists(exe)) return canonicalize(exe, { ...options, platform });
-      for (const ext of [".cmd", ".bat", ".ps1", ""]) {
-        const shim = path.join(dir, `${cliId}${ext}`);
-        if (exists(shim)) {
-          rejectedShim = shim;
-          break;
+      if (exists(exe)) return { command: canonicalize(exe, { ...options, platform }), args: [] };
+    }
+    for (const dir of dirs) {
+      const cmdShim = path.join(dir, `${cliId}.cmd`);
+      if (!exists(cmdShim)) continue;
+      const exeSegs = WIN_NPM_INNER_EXE[cliId];
+      if (exeSegs) {
+        const inner = path.join(dir, ...exeSegs);
+        if (exists(inner)) {
+          return { command: assertWinExecutable(inner, platform, options), args: [] };
+        }
+      }
+      const scriptSegs = WIN_NPM_INNER_NODE_SCRIPT[cliId];
+      if (scriptSegs) {
+        const script = path.join(dir, ...scriptSegs);
+        const nodeExe = options.execPath ?? process.execPath;
+        if (exists(script) && exists(nodeExe)) {
+          return {
+            command: canonicalize(nodeExe, { ...options, platform }),
+            args: [canonicalize(script, { ...options, platform })],
+          };
         }
       }
-      if (rejectedShim) break;
-    } else if (exists(path.join(dir, cliId))) {
-      return canonicalize(path.join(dir, cliId), { ...options, platform });
+      rejectedShim = cmdShim;
+      break;
+    }
+    if (!rejectedShim) {
+      for (const dir of dirs) {
+        for (const ext of [".bat", ".ps1", ""]) {
+          const shim = path.join(dir, `${cliId}${ext}`);
+          if (exists(shim)) {
+            rejectedShim = shim;
+            break;
+          }
+        }
+        if (rejectedShim) break;
+      }
+    }
+  } else {
+    for (const dir of dirs) {
+      if (exists(path.join(dir, cliId))) {
+        return { command: canonicalize(path.join(dir, cliId), { ...options, platform }), args: [] };
+      }
     }
   }
   if (rejectedShim) {
@@ -309,6 +349,10 @@ export function resolveLauncher(cliId, options = {}) {
   throw failClosed(`missing binary ${cliId}; install and authenticate the native CLI`);
 }
 
+export function resolveLauncher(cliId, options = {}) {
+  return resolveLaunch(cliId, options).command;
+}
+
 function canonicalize(target, options = {}) {
   const platform = options.platform ?? process.platform;
   if (platform === "win32" && process.platform !== "win32") return target;
@@ -510,6 +554,7 @@ export function buildArgv(request, ctx = {}) {
       "--sandbox",
       "read-only",
       "--ignore-user-config",
+      "-c", 'approval_policy="never"',
       ...(schemaPath ? ["--output-schema", schemaPath] : []),
       "--json",
       "-",
@@ -1572,19 +1617,22 @@ export async function runHarness(request, deps = {}) {
     schemaText: schemaInput?.text,
   });
   const cliId = request.harness;
-  const resolved = resolveLauncher(cliId, {
+  const launch = resolveLaunch(cliId, {
     platform,
     pathEnv: env.PATH,
     existsSync: exists,
     realpathSync: deps.realpathSync,
+    execPath: deps.execPath ?? process.execPath,
   });
+  const resolved = launch.command;
+  const launchArgs = launch.args;
 
   const authArgs = request.harness === "claude"
     ? [...claudeIsolationArgs(mcpConfigPath), ...route.auth.args]
     : request.harness === "pi"
       ? piAuthCheckArgs(request)
       : [...route.auth.args];
-  const auth = spawnSyncImpl(resolved, authArgs, {
+  const auth = spawnSyncImpl(resolved, [...launchArgs, ...authArgs], {
     cwd,
     env,
     encoding: "utf8",
@@ -1628,7 +1676,7 @@ export async function runHarness(request, deps = {}) {
   let killRequest;
   let child;
   try {
-    child = spawnImpl(resolved, argv, {
+    child = spawnImpl(resolved, [...launchArgs, ...argv], {
       cwd,
       env,
       shell: false,

package/scripts/kxm-bump-version.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+/**
+ * Bump the package version across all tracked surfaces.
+ *
+ * Usage:
+ *   node scripts/kxm-bump-version.mjs <new-version>       # explicit version
+ *   node scripts/kxm-bump-version.mjs patch               # bump patch
+ *   node scripts/kxm-bump-version.mjs minor               # bump minor
+ *   node scripts/kxm-bump-version.mjs major               # bump major
+ *
+ * Surfaces updated (must stay in sync with scripts/check-versions.mjs):
+ *   1. package.json                          .version
+ *   2. package-lock.json                     .version + .packages[""].version
+ *   3. plugins/kxm/package.json              .version
+ *   4. plugins/kxm/.claude-plugin/plugin.json .version
+ *   5. .claude-plugin/marketplace.json       .plugins[name=kxm].version
+ *   6. plugins/kxm/src/mcp-server.ts         const VERSION = "..."
+ *   7. plugins/kxm/dist/mcp-server.js        const VERSION = "..." (rebuilt)
+ *
+ * After running this script, run `npm run build` to rebuild dist bundles.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/;
+
+export function parseSemver(version) {
+  const match = SEMVER_RE.exec(version);
+  if (!match) return undefined;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4],
+    build: match[5],
+  };
+}
+
+export function bumpVersion(current, kind) {
+  const parsed = parseSemver(current);
+  if (!parsed) throw new Error(`invalid current version: ${current}`);
+  switch (kind) {
+    case "major":
+      return `${parsed.major + 1}.0.0`;
+    case "minor":
+      return `${parsed.major}.${parsed.minor + 1}.0`;
+    case "patch":
+      return `${parsed.major}.${parsed.minor}.${parsed.patch + 1}`;
+    default:
+      throw new Error(`unknown bump kind: ${kind} (use major, minor, or patch)`);
+  }
+}
+
+/** Replace a version string in a JSON file using targeted string patching. */
+function patchJsonVersion(filePath, oldVersion, newVersion) {
+  const raw = readFileSync(filePath, "utf8");
+  const escaped = oldVersion.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`("version"\\s*:\\s*)"${escaped}"`, "g");
+  const patched = raw.replace(pattern, `$1"${newVersion}"`);
+  if (patched === raw) {
+    throw new Error(`no version field found to patch in ${filePath}`);
+  }
+  writeFileSync(filePath, patched, "utf8");
+}
+
+/** Replace a version string in a TypeScript/JavaScript source file. */
+function patchSourceVersion(filePath, newVersion) {
+  const raw = readFileSync(filePath, "utf8");
+  const patched = raw.replace(
+    /const VERSION = "[^"]+"/,
+    `const VERSION = "${newVersion}"`,
+  );
+  if (patched === raw) {
+    throw new Error(`no VERSION constant found in ${filePath}`);
+  }
+  writeFileSync(filePath, patched, "utf8");
+}
+
+export function applyVersionBump(root, newVersion) {
+  if (!parseSemver(newVersion)) {
+    throw new Error(`invalid semver: ${newVersion}`);
+  }
+
+  // Read current version
+  const pkgPath = resolve(root, "package.json");
+  const oldVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+
+  // JSON surfaces (targeted patch preserves formatting)
+  const jsonFiles = [
+    "package.json",
+    "package-lock.json",
+    "plugins/kxm/package.json",
+    "plugins/kxm/.claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
+  ];
+  for (const rel of jsonFiles) {
+    patchJsonVersion(resolve(root, rel), oldVersion, newVersion);
+  }
+
+  // TypeScript source
+  patchSourceVersion(resolve(root, "plugins/kxm/src/mcp-server.ts"), newVersion);
+
+  // Generated dist (update in place if it exists; check:generated rebuilds anyway)
+  const distPath = resolve(root, "plugins/kxm/dist/mcp-server.js");
+  try {
+    patchSourceVersion(distPath, newVersion);
+  } catch {
+    // dist may not exist yet; will be rebuilt by npm run build
+  }
+
+  return { oldVersion, newVersion };
+}
+
+export function main(argv = process.argv.slice(2), root = process.cwd()) {
+  const arg = argv[0];
+  if (!arg) {
+    process.stderr.write("usage: node scripts/kxm-bump-version.mjs <version|patch|minor|major>\n");
+    return 1;
+  }
+
+  const pkgPath = resolve(root, "package.json");
+  const currentVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+
+  let newVersion;
+  if (SEMVER_RE.test(arg)) {
+    newVersion = arg;
+  } else {
+    newVersion = bumpVersion(currentVersion, arg);
+  }
+
+  if (newVersion === currentVersion) {
+    process.stdout.write(`version unchanged: ${currentVersion}\n`);
+    return 0;
+  }
+
+  const result = applyVersionBump(root, newVersion);
+  process.stdout.write(`bumped ${result.oldVersion} -> ${result.newVersion}\n`);
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = main();
+}