@kontextmind/kxm 0.7.0 → 0.7.10

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();
+}

package/scripts/kxm-hub.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 import { spawn, spawnSync } from "node:child_process";
-import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -15,6 +17,19 @@ const startedAt = new Date().toISOString();
 const controlFile = "hub.stop";
 const controlPath = join(stateDir, controlFile);
 
+// --- Persistent hub credentials (kxm.hub-env.v1) -------------------------
+// Precedence: KXM_AUTH_TOKEN/KXM_PROJECT_TOKENS env, then the persisted
+// user-state file, then a generated admin token that is persisted so later
+// restarts, workers, and dashboards reuse the same credential.
+function resolveUserStateRoot() {
+  const explicit = process.env.KXM_STATE_HOME?.trim();
+  if (explicit) return resolve(explicit);
+  const home = homedir();
+  if (process.platform === "win32") return resolve(process.env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local"), "KXM");
+  if (process.platform === "darwin") return resolve(home, "Library", "Application Support", "KXM");
+  return resolve(process.env.XDG_STATE_HOME?.trim() || join(home, ".local", "state"), "kxm");
+}
+
 function processExists(pid) {
   try {
     process.kill(pid, 0);
@@ -24,6 +39,119 @@ function processExists(pid) {
   }
 }
 
+function parseHubEnvFile() {
+  const file = join(resolveUserStateRoot(), "hub-env.json");
+  let raw;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return { file, record: undefined };
+    throw new Error(`KXM hub could not read the persisted hub env at ${file}: ${error.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`KXM hub env file is malformed at ${file}; fix or remove it (it holds only KXM_AUTH_TOKEN/KXM_PROJECT_TOKENS values): ${error.message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || parsed.schema !== "kxm.hub-env.v1") {
+    throw new Error(`KXM hub env file at ${file} does not use schema kxm.hub-env.v1`);
+  }
+  return { file, record: parsed };
+}
+
+function generateAdminToken() {
+  return `kxm_admin_${randomBytes(24).toString("base64url")}`;
+}
+
+function persistHubEnv(file, record) {
+  mkdirSync(resolve(file, ".."), { recursive: true });
+  const temporary = join(resolve(file, ".."), `.hub-env-${process.pid}.tmp`);
+  writeFileSync(temporary, `${JSON.stringify(record, undefined, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  try {
+    renameSync(temporary, file);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+function parseProjectTokensEnv(raw) {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    throw new Error("KXM_PROJECT_TOKENS must be a JSON object of project names to tokens");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("KXM_PROJECT_TOKENS must be a JSON object of project names to tokens");
+  }
+  for (const [project, token] of Object.entries(parsed)) {
+    if (!project.trim() || typeof token !== "string" || !token.trim()) {
+      throw new Error("KXM_PROJECT_TOKENS must contain non-empty project names and token strings");
+    }
+  }
+  return parsed;
+}
+
+/** Resolve credentials, persisting generated/env values into the user-state file. */
+function resolveCredentials() {
+  const { file, record } = parseHubEnvFile();
+  const envToken = process.env.KXM_AUTH_TOKEN?.trim();
+  const envProjectTokens = parseProjectTokensEnv(process.env.KXM_PROJECT_TOKENS);
+  let authToken = envToken || record?.authToken;
+  let authTokenSource = envToken ? "env" : record?.authToken ? "file" : "none";
+  if (!authToken) {
+    authToken = generateAdminToken();
+    authTokenSource = "generated";
+  }
+  const projectTokens = envProjectTokens || record?.projectTokens;
+  const projectTokensSource = envProjectTokens ? "env" : record?.projectTokens ? "file" : "none";
+  const envChanged = (authTokenSource === "env" && record?.authToken !== authToken)
+    || (projectTokensSource === "env" && JSON.stringify(record?.projectTokens ?? undefined) !== JSON.stringify(projectTokens ?? undefined));
+  if (authTokenSource === "generated" || envChanged) {
+    persistHubEnv(file, {
+      schema: "kxm.hub-env.v1",
+      createdAt: record?.createdAt || new Date().toISOString(),
+      ...(authToken ? { authToken } : {}),
+      ...(projectTokens ? { projectTokens } : {}),
+    });
+  }
+  return { authToken, authTokenSource, projectTokens, projectTokensSource, file };
+}
+
+let credentials;
+try {
+  credentials = resolveCredentials();
+} catch (error) {
+  process.stderr.write(`kxm hub: ${error.message}\n`);
+  process.exit(1);
+}
+const launchEnv = { ...process.env };
+if (credentials.authToken) launchEnv.KXM_AUTH_TOKEN = credentials.authToken;
+if (credentials.projectTokens) launchEnv.KXM_PROJECT_TOKENS = JSON.stringify(credentials.projectTokens);
+if (credentials.authTokenSource !== "env") {
+  process.stdout.write(`kxm hub: using ${credentials.authTokenSource === "generated" ? "newly generated" : "persisted"} KXM_AUTH_TOKEN from ${credentials.file}\n`);
+}
+
+function terminateTree(pid) {
+  // Best-effort cleanup of an orphaned hub server whose wrapper died
+  // without reclaiming (e.g. SIGKILL). The wrapper could not be stopped
+  // gracefully in that state, so the server is asked to shut down first and
+  // forced after a short grace period.
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  try { process.kill(pid, "SIGTERM"); } catch { /* already gone */ }
+  const deadline = Date.now() + 3000;
+  while (Date.now() < deadline) {
+    if (!processExists(pid)) return;
+    const wait = Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+    if (wait !== "timed-out") return;
+  }
+  try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
+}
+
 function claimPidFile() {
   const record = { version: 1, pid: process.pid, role: "hub", startedAt, controlFile };
   for (let attempt = 0; attempt < 3; attempt += 1) {
@@ -50,9 +178,16 @@ function claimPidFile() {
       if (existing?.version === 1 && existing.role === "hub" && Number.isInteger(existing.pid) && processExists(existing.pid)) {
         throw new Error(`KXM hub is already managed by PID ${existing.pid}`);
       }
-      // A well-formed claim whose owner is dead is safe to reclaim. Keep
+      // A well-formed claim whose wrapper is dead is safe to reclaim. Keep
       // malformed claims fail-closed because they may belong to another tool.
       if (existing?.version === 1 && existing.role === "hub" && Number.isInteger(existing.pid) && !processExists(existing.pid)) {
+        // The wrapper is gone. An orphaned server child recorded by the dead
+        // wrapper is cleaned up before reclaiming so a SIGKILLed wrapper does
+        // not leave a port-holding server behind.
+        if (Number.isInteger(existing.serverPid) && existing.serverPid !== existing.pid && processExists(existing.serverPid)) {
+          process.stderr.write(`kxm hub: cleaning up orphaned hub server PID ${existing.serverPid} from a dead wrapper\n`);
+          terminateTree(existing.serverPid);
+        }
         rmSync(pidPath, { force: true });
         continue;
       }
@@ -79,8 +214,15 @@ const child = spawn(process.execPath, [
   ...process.argv.slice(2),
 ], {
   stdio: ["inherit", "inherit", "inherit", "ipc"],
-  env: process.env,
+  env: launchEnv,
 });
+// Record the server child PID inside the claim so a later wrapper can clean
+// up an orphaned server if this wrapper is killed without running cleanupPid.
+if (child.pid) {
+  try {
+    writeFileSync(pidPath, `${JSON.stringify({ version: 1, pid: process.pid, serverPid: child.pid, role: "hub", startedAt, controlFile })}\n`, "utf8");
+  } catch { /* claim already written; serverPid tracking is best-effort */ }
+}
 let stopping = false;
 
 child.once("error", (error) => {

package/scripts/kxm-publish-npm.mjs

@@ -275,7 +275,9 @@ export async function main(env = process.env, stdout = process.stdout, stderr =
   const token = env.GITHUB_TOKEN || env.GH_TOKEN;
   const npmToken = env.NODE_AUTH_TOKEN || env.NPM_TOKEN;
   const repo = env.GITHUB_REPOSITORY;
-  const tag = env.GITHUB_REF_NAME || env.TAG;
+  // KXM_RELEASE_TAG is explicit for workflow_dispatch runs; GITHUB_REF_NAME
+  // is the branch name for that event, not the requested release tag.
+  const tag = env.KXM_RELEASE_TAG || env.TAG || env.GITHUB_REF_NAME;
   const assetName = env.KXM_ASSET;
   const assetPath = env.KXM_ASSET_PATH;
   const declaredSha256 = env.KXM_ASSET_SHA256;

package/scripts/kxm-release-github.mjs

@@ -427,7 +427,9 @@ export function fileSha256(path) {
 export async function main(env = process.env, stdout = process.stdout, stderr = process.stderr) {
   const token = env.GITHUB_TOKEN || env.GH_TOKEN;
   const repo = env.GITHUB_REPOSITORY;
-  const tag = env.GITHUB_REF_NAME;
+  // KXM_RELEASE_TAG is explicit for workflow_dispatch runs; GITHUB_REF_NAME
+  // is the branch name for that event, not the requested release tag.
+  const tag = env.KXM_RELEASE_TAG || env.TAG || env.GITHUB_REF_NAME;
   const assetName = env.KXM_ASSET;
   const assetPath = env.KXM_ASSET_PATH;
   const declared = env.KXM_ASSET_SHA256;