@aliyunrds/ctxdb 0.0.1 → 0.0.3

package/dist/cli/main.js

@@ -7,12 +7,13 @@ import {
   SUPPORTED_AGENTS,
   agentFromEnv,
   agentHomeDir,
+  configuredAgents,
   isAgent,
   isComplete,
   load,
   removeAgent,
   save
-} from "../chunk-L4YJ7LDI.js";
+} from "../chunk-QSSNPN3M.js";
 
 // src/cli/util.ts
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
@@ -36,6 +37,8 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   // kb
   "no-wait",
   // kb upload-text / upload-file
+  "verbose",
+  // memory search / kb search (three-tier projection)
   "raw"
   // kb search / memory search --knowledge (W3 compaction bypass)
 ]);
@@ -86,9 +89,64 @@ function summarize(v) {
     return String(v);
   }
 }
+var GREEN = "\x1B[32m";
+var RED = "\x1B[31m";
+var DIM = "\x1B[2m";
+var BOLD = "\x1B[1m";
+var RESET = "\x1B[0m";
+var CHECK = `${GREEN}\u2714${RESET}`;
+var CROSS = `${RED}\u2718${RESET}`;
+function isSetupResult(v) {
+  if (typeof v !== "object" || v === null) return false;
+  return "steps" in v && Array.isArray(v.steps);
+}
+function isStatusResult(v) {
+  if (typeof v !== "object" || v === null) return false;
+  return "agent" in v && "connected" in v;
+}
+function formatSetupResult(r) {
+  const lines = [];
+  lines.push(`${r.ok ? CHECK : CROSS} ${BOLD}ctxdb setup${RESET} ${r.ok ? "completed" : "failed"}
+`);
+  for (const s of r.steps) {
+    const icon = s.ok ? CHECK : CROSS;
+    const detail = s.detail ? `  ${DIM}${s.detail}${RESET}` : "";
+    lines.push(`  ${icon} ${s.step}${detail}`);
+  }
+  return lines.join("\n");
+}
+function formatStatusResult(r) {
+  const lines = [];
+  const ok = r.connected ? CHECK : CROSS;
+  lines.push(`${ok} ${BOLD}ctxdb status${RESET} ${DIM}(${r.agent})${RESET}
+`);
+  const display = [
+    ["base_url", r.base_url],
+    ["user_id", r.user_id],
+    ["api_key", r.api_key_set ? "set" : "not set"],
+    ["auto_capture", r.auto_capture],
+    ["auto_recall", r.auto_recall],
+    ["top_k", r.top_k],
+    ["threshold", r.threshold],
+    ["knowledge_top_k", r.knowledge_top_k],
+    ["connected", r.connected],
+    ["version", r.version]
+  ];
+  if (r.ping_error) display.push(["ping_error", r.ping_error]);
+  const maxKey = Math.max(...display.map(([k]) => k.length));
+  for (const [k, v] of display) {
+    const valStr = typeof v === "boolean" ? v ? `${GREEN}yes${RESET}` : `${RED}no${RESET}` : String(v ?? "-");
+    lines.push(`  ${DIM}${k.padEnd(maxKey)}${RESET}  ${valStr}`);
+  }
+  return lines.join("\n");
+}
 function printResult(value, json) {
   if (json) {
     process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+  } else if (isSetupResult(value)) {
+    process.stdout.write(formatSetupResult(value) + "\n");
+  } else if (isStatusResult(value)) {
+    process.stdout.write(formatStatusResult(value) + "\n");
   } else {
     process.stdout.write(summarize(value) + "\n");
   }
@@ -120,97 +178,7 @@ function fail(message, code = 1) {
 `);
   process.exit(code);
 }
-var PACKAGE_VERSION = "0.0.1";
-
-// src/cli/top.ts
-import { homedir } from "os";
-import { join } from "path";
-async function init(args) {
-  const agent = agentFromFlags(args.flags);
-  const cfg = load({ agent });
-  if (typeof args.flags["api-key"] === "string") cfg.apiKey = args.flags["api-key"];
-  if (typeof args.flags["base-url"] === "string") {
-    cfg.baseUrl = args.flags["base-url"].replace(/\/+$/, "");
-  } else if (!cfg.baseUrl) {
-    cfg.baseUrl = DEFAULT_BASE_URL;
-  }
-  const cliUserId = typeof args.flags["user-id"] === "string" ? args.flags["user-id"] : void 0;
-  cfg.userId = cliUserId ?? cfg.userId ?? DEFAULT_USER_ID;
-  save(cfg, void 0, { agent });
-  let validated = false;
-  let pingError = null;
-  if (!args.flags["no-validate"] && cfg.apiKey) {
-    try {
-      const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
-      await client.get("/v1/ping/");
-      validated = true;
-    } catch (err) {
-      pingError = err?.message ?? String(err);
-    }
-  }
-  printResult(
-    {
-      ok: true,
-      config_path: join(homedir(), ".ctxdb", "ctxdb.json"),
-      agent,
-      api_key_set: Boolean(cfg.apiKey),
-      base_url: cfg.baseUrl,
-      user_id: cfg.userId,
-      validated,
-      ping_error: pingError
-    },
-    !!args.flags.json
-  );
-  return 0;
-}
-async function status(args) {
-  const agent = agentFromFlags(args.flags);
-  const cfg = load({ agent });
-  const complete = isComplete(cfg);
-  let connected = false;
-  let pingError = null;
-  if (complete) {
-    try {
-      const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
-      await client.get("/v1/ping/");
-      connected = true;
-    } catch (err) {
-      pingError = err?.message ?? String(err);
-    }
-  }
-  printResult(
-    {
-      ok: complete,
-      agent,
-      base_url: cfg.baseUrl,
-      user_id: cfg.userId,
-      api_key_set: Boolean(cfg.apiKey),
-      auto_capture: cfg.autoCapture,
-      auto_recall: cfg.autoRecall,
-      top_k: cfg.topK,
-      threshold: cfg.threshold,
-      knowledge_top_k: cfg.knowledgeTopK,
-      connected,
-      ping_error: pingError,
-      version: PACKAGE_VERSION
-    },
-    !!args.flags.json
-  );
-  return complete && connected ? 0 : 1;
-}
-async function ping(args) {
-  const agent = agentFromFlags(args.flags);
-  const cfg = load({ agent });
-  if (!isComplete(cfg)) {
-    fail(
-      `config incomplete for agent ${agent} \u2014 run \`ctxdb setup --agent ${agent}\` or set CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID`
-    );
-  }
-  const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
-  const resp = await client.get("/v1/ping/");
-  printResult(resp, !!args.flags.json);
-  return 0;
-}
+var PACKAGE_VERSION = "0.0.3";
 
 // src/setup/installer.ts
 import {
@@ -226,19 +194,20 @@ import {
   unlinkSync,
   statSync
 } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join2, dirname } from "path";
+import { homedir } from "os";
+import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { execFileSync } from "child_process";
 var UNINSTALL_NPM_HINT = "To also remove the npm binaries: `npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared`";
 var UNINSTALL_ORDER_HINT = "When you eventually want to uninstall: run `ctxdb teardown --purge-all` FIRST, then `npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared`. (npm 7+ removed uninstall lifecycle hooks, so the order matters \u2014 otherwise agent settings.json hooks + ~/.ctxdb/ residue stay behind.)";
 function skillInstallRoot(agent) {
   switch (agent) {
     case "qoder":
-      return join2(homedir2(), ".qoder", "skills");
+      return join(homedir(), ".qoder", "skills");
     case "codex":
-      return join2(homedir2(), ".codex", "skills");
+      return join(homedir(), ".codex", "skills");
     case "claude":
-      return join2(homedir2(), ".claude", "skills");
+      return join(homedir(), ".claude", "skills");
   }
 }
 var SKILL_DIR_NAME = "ctxdb";
@@ -246,7 +215,7 @@ function skillResourceDir(agent) {
   return agentSupportsHooks(agent) ? "hooks-driven" : "cli-only";
 }
 function skillInstallDir(agent) {
-  return join2(skillInstallRoot(agent), SKILL_DIR_NAME);
+  return join(skillInstallRoot(agent), SKILL_DIR_NAME);
 }
 function agentSupportsHooks(agent) {
   return agent === "qoder" || agent === "codex" || agent === "claude";
@@ -254,11 +223,11 @@ function agentSupportsHooks(agent) {
 function hookConfigPath(agent) {
   switch (agent) {
     case "qoder":
-      return join2(homedir2(), ".qoder", "settings.json");
+      return join(homedir(), ".qoder", "settings.json");
     case "codex":
-      return join2(homedir2(), ".codex", "hooks.json");
+      return join(homedir(), ".codex", "hooks.json");
     case "claude":
-      return join2(homedir2(), ".claude", "settings.json");
+      return join(homedir(), ".claude", "settings.json");
   }
 }
 var LEGACY_QODER_SKILL_DIRS = [
@@ -324,6 +293,14 @@ async function runSetup(options) {
       detail: hookPaths ? `${hookPaths.userPromptSubmit} + ${hookPaths.stop}` : "could not locate hook scripts in dist/ or src/"
     });
     if (!hookPaths) return { ok: false, steps };
+    const nodePath = process.execPath;
+    const nodeCheck = verifyNodeBinary(nodePath);
+    steps.push({
+      step: "resolve-node",
+      ok: nodeCheck.ok,
+      detail: nodeCheck.ok ? `${nodePath} (${nodeCheck.version})` : `node not executable: ${nodeCheck.error}`
+    });
+    if (!nodeCheck.ok) return { ok: false, steps };
     try {
       backupSettingsJson(agent);
       steps.push({ step: "backup-settings", ok: true });
@@ -439,7 +416,7 @@ function runRemove(agent, options = {}) {
     const dirs = agent === "qoder" ? [
       skillInstallDir("qoder"),
       ...LEGACY_QODER_SKILL_DIRS.map(
-        (d) => join2(homedir2(), ".qoder", "skills", d)
+        (d) => join(homedir(), ".qoder", "skills", d)
       )
     ] : [skillInstallDir(agent)];
     for (const p of dirs) {
@@ -532,7 +509,7 @@ function runTeardown(options = {}) {
     }
   }
   if (purgeConfig) {
-    const cfgPath = join2(homedir2(), ".ctxdb", "ctxdb.json");
+    const cfgPath = join(homedir(), ".ctxdb", "ctxdb.json");
     if (existsSync(cfgPath)) {
       try {
         unlinkSync(cfgPath);
@@ -553,7 +530,7 @@ function runTeardown(options = {}) {
     }
   }
   if (purgeLogs) {
-    const logsDir = join2(homedir2(), ".ctxdb", "logs");
+    const logsDir = join(homedir(), ".ctxdb", "logs");
     if (existsSync(logsDir)) {
       try {
         rmSync(logsDir, { recursive: true, force: true });
@@ -574,7 +551,7 @@ function runTeardown(options = {}) {
     }
   }
   if (purgeRoot) {
-    const root = join2(homedir2(), ".ctxdb");
+    const root = join(homedir(), ".ctxdb");
     if (existsSync(root)) {
       try {
         const remaining = readdirSync(root);
@@ -601,6 +578,70 @@ function runTeardown(options = {}) {
   const hints = ok ? [UNINSTALL_NPM_HINT] : void 0;
   return { ok, steps, hints };
 }
+function verifyNodeBinary(nodePath) {
+  if (!existsSync(nodePath)) return { ok: false, error: `not found: ${nodePath}` };
+  try {
+    const out = execFileSync(nodePath, ["--version"], { timeout: 5e3, encoding: "utf-8" }).trim();
+    return { ok: true, version: out };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+}
+function checkHookNodePaths(agent) {
+  const empty = {
+    installed: false,
+    nodePaths: [],
+    nodeOk: true,
+    detail: "no hooks installed"
+  };
+  const path = hookConfigPath(agent);
+  if (!path || !existsSync(path)) return empty;
+  let data;
+  try {
+    data = JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return empty;
+  }
+  if (!data?.hooks || typeof data.hooks !== "object") return empty;
+  const nodePaths = /* @__PURE__ */ new Set();
+  for (const event of HOOK_EVENTS) {
+    const entries = data.hooks[event];
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (!entryIsCtxdb(entry)) continue;
+      for (const h of entry.hooks ?? []) {
+        if (h?.type !== "command" || typeof h.command !== "string") continue;
+        const cmd = h.command;
+        if (cmd.includes("@aliyunrds/ctxdb")) {
+          const parts = cmd.split(" ");
+          if (parts.length >= 2 && !parts[0].endsWith(".js") && !parts[0].endsWith(".ts")) {
+            nodePaths.add(parts[0]);
+          }
+        }
+      }
+    }
+  }
+  if (nodePaths.size === 0) {
+    return { installed: true, nodePaths: [], nodeOk: true, detail: "hooks use shebang (no explicit node path)" };
+  }
+  const paths = [...nodePaths];
+  const bad = [];
+  let goodVersion = "";
+  for (const p of paths) {
+    const v = verifyNodeBinary(p);
+    if (!v.ok) bad.push(`${p}: ${v.error}`);
+    else if (!goodVersion) goodVersion = v.version ?? "";
+  }
+  if (bad.length > 0) {
+    return {
+      installed: true,
+      nodePaths: paths,
+      nodeOk: false,
+      detail: `node not executable: ${bad.join("; ")} \u2014 re-run \`ctxdb setup --agent ${agent}\``
+    };
+  }
+  return { installed: true, nodePaths: paths, nodeOk: true, detail: `${paths[0]} (${goodVersion})` };
+}
 var SETTINGS_BACKUP_KEEP = 5;
 function backupSettingsJson(agent) {
   const path = hookConfigPath(agent);
@@ -622,7 +663,7 @@ function rotateBackups(prefix, keep) {
   const candidates = [];
   for (const name of entries) {
     if (!name.startsWith(baseName)) continue;
-    const full = join2(dir, name);
+    const full = join(dir, name);
     try {
       const st = statSync(full);
       if (st.isFile()) candidates.push({ path: full, mtime: st.mtimeMs });
@@ -674,20 +715,20 @@ function locateHookPaths() {
   if (!pkgRoot) return null;
   const preferSrc = here.includes("/src/") || here.includes("\\src\\");
   if (preferSrc) {
-    const src = hookPathsFromDir(join2(pkgRoot, "src", "hooks"), "ts");
+    const src = hookPathsFromDir(join(pkgRoot, "src", "hooks"), "ts");
     if (src) return src;
   }
-  const distDir = join2(pkgRoot, "dist", "hooks");
+  const distDir = join(pkgRoot, "dist", "hooks");
   const dist = hookPathsFromDir(distDir, "js");
   if (dist) return dist;
-  return hookPathsFromDir(join2(pkgRoot, "src", "hooks"), "ts");
+  return hookPathsFromDir(join(pkgRoot, "src", "hooks"), "ts");
 }
 function hookPathsFromDir(dir, ext) {
   if (!existsSync(dir)) return null;
-  const ups = join2(dir, `user-prompt-submit.${ext}`);
-  const stp = join2(dir, `stop.${ext}`);
-  const ss = join2(dir, `session-start.${ext}`);
-  const ptu = join2(dir, `pre-tool-use.${ext}`);
+  const ups = join(dir, `user-prompt-submit.${ext}`);
+  const stp = join(dir, `stop.${ext}`);
+  const ss = join(dir, `session-start.${ext}`);
+  const ptu = join(dir, `pre-tool-use.${ext}`);
   if (existsSync(ups) && existsSync(stp) && existsSync(ss)) {
     return {
       userPromptSubmit: ups,
@@ -704,19 +745,19 @@ function locateSkillDir(variant) {
   if (!pkgRoot) return null;
   const preferSrc = here.includes("/src/") || here.includes("\\src\\");
   if (preferSrc) {
-    const srcSkill2 = join2(pkgRoot, "src", "setup", "skills", variant);
+    const srcSkill2 = join(pkgRoot, "src", "setup", "skills", variant);
     if (existsSync(srcSkill2)) return srcSkill2;
   }
-  const distSkill = join2(pkgRoot, "dist", "setup", "skills", variant);
+  const distSkill = join(pkgRoot, "dist", "setup", "skills", variant);
   if (existsSync(distSkill)) return distSkill;
-  const srcSkill = join2(pkgRoot, "src", "setup", "skills", variant);
+  const srcSkill = join(pkgRoot, "src", "setup", "skills", variant);
   if (existsSync(srcSkill)) return srcSkill;
   return null;
 }
 function walkUpToPackageJson(start, expectedName) {
   let cur = start;
   for (let i = 0; i < 8; i++) {
-    const p = join2(cur, "package.json");
+    const p = join(cur, "package.json");
     if (existsSync(p)) {
       try {
         const pkg = JSON.parse(readFileSync(p, "utf-8"));
@@ -733,8 +774,8 @@ function walkUpToPackageJson(start, expectedName) {
 function copySkillDir(src, dest, agent) {
   mkdirSync(dest, { recursive: true });
   for (const entry of readdirSync(src)) {
-    const srcPath = join2(src, entry);
-    const destPath = join2(dest, entry);
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
     const st = statSync(srcPath);
     if (st.isDirectory()) {
       copySkillDir(srcPath, destPath, agent);
@@ -773,7 +814,7 @@ var LEGACY_MARKER_KEYS = ["_ctxdbQoder", "_ctxdbPackage"];
 var LEGACY_MARKER_VALUES = ["@aliyunrds/ctxdb-qoder"];
 var TOOL_SCOPED_EVENTS = /* @__PURE__ */ new Set(["PreToolUse", "PostToolUse"]);
 function appendOne(hooks, event, command, agent) {
-  const commandWithAgent = `${command} --agent=${agent}`;
+  const commandWithAgent = `${process.execPath} ${command} --agent=${agent}`;
   if (!Array.isArray(hooks[event])) hooks[event] = [];
   const dup = hooks[event].some(
     (entry2) => Array.isArray(entry2?.hooks) && entry2.hooks.some(
@@ -806,7 +847,7 @@ function entryIsCtxdb(entry) {
   );
 }
 function codexConfigTomlPath() {
-  return join2(homedir2(), ".codex", "config.toml");
+  return join(homedir(), ".codex", "config.toml");
 }
 function inspectCodexHooksFeature(rawContent) {
   const content = rawContent.replace(/^/, "");
@@ -1001,6 +1042,190 @@ function describeCodexFeatureMutation(status2, createdNew) {
       return "updated ~/.codex/config.toml";
   }
 }
+function runUpgrade(options = {}) {
+  const agents = options.agent ? [options.agent] : configuredAgents(options.configPath);
+  if (agents.length === 0) {
+    return {
+      ok: false,
+      agents: {},
+      hints: options.agent ? [`agent "${options.agent}" not configured \u2014 run \`ctxdb setup --agent ${options.agent}\` first`] : ["no agents configured \u2014 run `ctxdb setup --agent <name>` first"]
+    };
+  }
+  if (options.agent) {
+    const configured = configuredAgents(options.configPath);
+    if (!configured.includes(options.agent)) {
+      return {
+        ok: false,
+        agents: {},
+        hints: [`agent "${options.agent}" not configured \u2014 run \`ctxdb setup --agent ${options.agent}\` first`]
+      };
+    }
+  }
+  const results = {};
+  for (const agent of agents) {
+    results[agent] = upgradeOneAgent(agent);
+  }
+  const anyOk = Object.values(results).some((r) => r.ok);
+  return { ok: anyOk, agents: results };
+}
+function upgradeOneAgent(agent) {
+  const steps = [];
+  const homeCheck = checkAgentHome(agent);
+  steps.push(homeCheck);
+  if (!homeCheck.ok) {
+    return { ok: true, steps, hints: [`${agent}: skipped \u2014 agent home not found`] };
+  }
+  try {
+    const srcDir = locateSkillDir(skillResourceDir(agent));
+    if (srcDir) {
+      const dest = skillInstallDir(agent);
+      copySkillDir(srcDir, dest, agent);
+      steps.push({ step: "install-skill", ok: true, detail: dest });
+    } else {
+      steps.push({
+        step: "install-skill",
+        ok: false,
+        detail: "skill source directory not found"
+      });
+      return { ok: false, steps };
+    }
+  } catch (err) {
+    steps.push({ step: "install-skill", ok: false, detail: err?.message ?? String(err) });
+    return { ok: false, steps };
+  }
+  if (agentSupportsHooks(agent)) {
+    const hookPaths = locateHookPaths();
+    if (!hookPaths) {
+      steps.push({ step: "locate-hooks", ok: false, detail: "hook scripts not found in dist/ or src/" });
+      return { ok: false, steps };
+    }
+    const nodePath = process.execPath;
+    const nodeCheck = verifyNodeBinary(nodePath);
+    if (!nodeCheck.ok) {
+      steps.push({ step: "resolve-node", ok: false, detail: `node not executable: ${nodeCheck.error}` });
+      return { ok: false, steps };
+    }
+    try {
+      backupSettingsJson(agent);
+      const removed = stripCtxdbHooks(agent);
+      appendHooks(agent, hookPaths);
+      steps.push({
+        step: "refresh-hooks",
+        ok: true,
+        detail: `${HOOK_EVENTS.length} hooks written (node: ${nodePath})${removed > 0 ? `, replaced ${removed} stale` : ""}`
+      });
+    } catch (err) {
+      steps.push({ step: "refresh-hooks", ok: false, detail: err?.message ?? String(err) });
+      return { ok: false, steps };
+    }
+    try {
+      chmodSync(hookPaths.userPromptSubmit, 493);
+      chmodSync(hookPaths.stop, 493);
+      chmodSync(hookPaths.sessionStart, 493);
+      if (hookPaths.preToolUse && existsSync(hookPaths.preToolUse)) {
+        chmodSync(hookPaths.preToolUse, 493);
+      }
+    } catch {
+    }
+    if (agent === "codex") {
+      steps.push(enableCodexHooksFeature());
+    }
+  }
+  return { ok: steps.every((s) => s.ok), steps };
+}
+
+// src/cli/top.ts
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+async function init(args) {
+  const agent = agentFromFlags(args.flags);
+  const cfg = load({ agent });
+  if (typeof args.flags["api-key"] === "string") cfg.apiKey = args.flags["api-key"];
+  if (typeof args.flags["base-url"] === "string") {
+    cfg.baseUrl = args.flags["base-url"].replace(/\/+$/, "");
+  } else if (!cfg.baseUrl) {
+    cfg.baseUrl = DEFAULT_BASE_URL;
+  }
+  const cliUserId = typeof args.flags["user-id"] === "string" ? args.flags["user-id"] : void 0;
+  cfg.userId = cliUserId ?? cfg.userId ?? DEFAULT_USER_ID;
+  save(cfg, void 0, { agent });
+  let validated = false;
+  let pingError = null;
+  if (!args.flags["no-validate"] && cfg.apiKey) {
+    try {
+      const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+      await client.get("/v1/ping/");
+      validated = true;
+    } catch (err) {
+      pingError = err?.message ?? String(err);
+    }
+  }
+  printResult(
+    {
+      ok: true,
+      config_path: join2(homedir2(), ".ctxdb", "ctxdb.json"),
+      agent,
+      api_key_set: Boolean(cfg.apiKey),
+      base_url: cfg.baseUrl,
+      user_id: cfg.userId,
+      validated,
+      ping_error: pingError
+    },
+    !!args.flags.json
+  );
+  return 0;
+}
+async function status(args) {
+  const agent = agentFromFlags(args.flags);
+  const cfg = load({ agent });
+  const complete = isComplete(cfg);
+  let connected = false;
+  let pingError = null;
+  if (complete) {
+    try {
+      const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+      await client.get("/v1/ping/");
+      connected = true;
+    } catch (err) {
+      pingError = err?.message ?? String(err);
+    }
+  }
+  const hookHealth = checkHookNodePaths(agent);
+  printResult(
+    {
+      ok: complete,
+      agent,
+      base_url: cfg.baseUrl,
+      user_id: cfg.userId,
+      api_key_set: Boolean(cfg.apiKey),
+      auto_capture: cfg.autoCapture,
+      auto_recall: cfg.autoRecall,
+      top_k: cfg.topK,
+      threshold: cfg.threshold,
+      knowledge_top_k: cfg.knowledgeTopK,
+      connected,
+      ping_error: pingError,
+      hooks_node: hookHealth.detail,
+      hooks_node_ok: hookHealth.nodeOk,
+      version: PACKAGE_VERSION
+    },
+    !!args.flags.json
+  );
+  return complete && connected ? 0 : 1;
+}
+async function ping(args) {
+  const agent = agentFromFlags(args.flags);
+  const cfg = load({ agent });
+  if (!isComplete(cfg)) {
+    fail(
+      `config incomplete for agent ${agent} \u2014 run \`ctxdb setup --agent ${agent}\` or set CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID`
+    );
+  }
+  const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+  const resp = await client.get("/v1/ping/");
+  printResult(resp, !!args.flags.json);
+  return 0;
+}
 
 // src/cli/setup-cli.ts
 function parseAgent(args) {
@@ -1066,6 +1291,27 @@ ${h}
   return result.ok ? 0 : 1;
 }
 
+// src/cli/upgrade.ts
+function upgrade(args) {
+  const agentFlag = args.flags.agent;
+  if (agentFlag && !isAgent(agentFlag)) {
+    process.stderr.write(
+      `unknown --agent: ${agentFlag} (expected one of ${SUPPORTED_AGENTS.join(" / ")})
+`
+    );
+    return 2;
+  }
+  const result = runUpgrade({ agent: agentFlag });
+  const json = !!args.flags.json;
+  printResult(result, json);
+  if (!json && result.hints) {
+    for (const h of result.hints) process.stderr.write(`
+${h}
+`);
+  }
+  return result.ok ? 0 : 1;
+}
+
 // src/lib/kb.ts
 import { readFileSync as readFileSync2, existsSync as existsSync2, statSync as statSync2 } from "fs";
 import { basename, extname } from "path";
@@ -1145,10 +1391,16 @@ async function uploadText(client, kbId, docName, text, mimeType = "text/plain",
   );
 }
 async function uploadFile(client, kbId, localPath, options = {}) {
+  const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
   const expanded = expandHome(localPath);
   if (!existsSync2(expanded)) throw new Error(`file not found: ${expanded}`);
   const stat = statSync2(expanded);
   if (!stat.isFile()) throw new Error(`not a file: ${expanded}`);
+  if (stat.size > MAX_UPLOAD_BYTES) {
+    throw new Error(
+      `file too large (${(stat.size / 1024 / 1024).toFixed(1)} MB), maximum is 100 MB`
+    );
+  }
   const filename = basename(expanded);
   const docName = options.docName ?? filename;
   const content = readFileSync2(expanded);
@@ -1160,19 +1412,22 @@ async function uploadFile(client, kbId, localPath, options = {}) {
   if (options.filePath !== void 0 && options.filePath !== "") {
     fields.file_path = options.filePath;
   }
+  const uploadOpts = { timeoutMs: options.timeoutMs };
   return tryNewThenLegacy(
     FILES,
     () => client.postMultipart(
       FILES,
       fields,
-      { file: { filename, content, mimeType: mime } }
+      { file: { filename, content, mimeType: mime } },
+      uploadOpts
     ),
     () => {
       const { knowledge_base_id: _drop, ...legacyFields } = fields;
       return client.postMultipart(
         `${KB_COLLECTION}/${encodeURIComponent(kbId)}/files`,
         legacyFields,
-        { file: { filename, content, mimeType: mime } }
+        { file: { filename, content, mimeType: mime } },
+        uploadOpts
       );
     }
   );
@@ -1453,7 +1708,8 @@ async function kbUploadFile(args) {
   const { kb, created } = await findOrCreateKb(ctx.client, kbName);
   const doc = await uploadFile(ctx.client, kb.id, localPath, {
     docName: typeof args.flags["doc-name"] === "string" ? args.flags["doc-name"] : void 0,
-    filePath: typeof args.flags["file-path"] === "string" ? args.flags["file-path"] : void 0
+    filePath: typeof args.flags["file-path"] === "string" ? args.flags["file-path"] : void 0,
+    timeoutMs: DEFAULT_FILE_INGEST_TIMEOUT_MS
   });
   if (args.flags["no-wait"]) {
     printResult({ kb, kb_created: created, document: doc }, !!args.flags.json);
@@ -1554,6 +1810,10 @@ COMMANDS
                                  --purge-logs   also deletes ~/.ctxdb/logs/.
                                  --purge-all    deletes everything under ~/.ctxdb/
                                  (does not run npm uninstall).
+  upgrade [--agent <name>] [--json]
+                                 Refresh skills + hooks for configured agents.
+                                 Run after npm update -g @aliyunrds/ctxdb.
+                                 Does not modify credentials.
 
   memory add <text> [--agent=<name>] [--user-id=...] [--metadata=K1=V1,K2=V2] [--no-infer]
   memory search <query> [--agent=<name>] [--top-k=10] [--threshold=0.4] [--knowledge]
@@ -1568,8 +1828,9 @@ COMMANDS
   memory delete <memory-id> | --all [--agent=<name>]
 
   kb upload-text <kb-name> <doc-name> --text=<body> [--agent=<name>]
-                 [--kb-description=...] [--no-wait]
-  kb upload-file <kb-name> <file-path> [--agent=<name>] [--doc-name=...] [--no-wait]
+                 [--kb-description=...] [--file-path=<server-logical-path>] [--no-wait]
+  kb upload-file <kb-name> <local-path> [--agent=<name>] [--doc-name=...]
+                 [--file-path=<server-logical-path>] [--no-wait]
   kb list [--agent=<name>]
   kb documents-list <kb-name-or-id> [--agent=<name>]
   kb document-get <kb-name-or-id> <doc-id> [--agent=<name>]
@@ -1593,6 +1854,7 @@ var ROUTES = {
   ping,
   setup,
   teardown,
+  upgrade,
   memory: {
     add: memoryAdd,
     search: memorySearch,