@aliyunrds/ctxdb 1.0.6 → 1.0.8-beta.0

package/dist/{chunk-L4GVGVOP.js → chunk-CAXRYH6E.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   CtxdbError
-} from "./chunk-ARZX2RLR.js";
+} from "./chunk-AAZLOCVB.js";
 
 // src/lib/kb.ts
 import {
@@ -94,6 +94,51 @@ async function createKb(client, kbName, description = "") {
   return client.postJson(KB_COLLECTION, { name: kbName, description: description || "" });
 }
 async function uploadText(client, kbName, docName, text, mimeType = "text/plain", filePath) {
+  return client.postJson(
+    DOCUMENTS,
+    buildTextDocumentBody(kbName, docName, text, mimeType, filePath)
+  );
+}
+async function updateText(client, locator, text) {
+  const body = {
+    ...buildUpdateLocatorFields(locator),
+    text
+  };
+  const response = await client.putJson(DOCUMENTS, body);
+  return readCanonicalUpdateDocument(response, "text update");
+}
+function buildUpdateLocatorFields(locator) {
+  if (!locator || typeof locator !== "object") {
+    throw new CtxdbError("update requires exactly one document locator");
+  }
+  const candidate = locator;
+  const hasDocumentId = Object.hasOwn(candidate, "documentId");
+  const hasLogicalField = ["kbName", "docName", "filePath"].some((field) => Object.hasOwn(candidate, field));
+  if (hasDocumentId === hasLogicalField) {
+    throw new CtxdbError("update requires exactly one document locator");
+  }
+  if (hasDocumentId) {
+    if (typeof candidate.documentId !== "string" || candidate.documentId.trim() === "") {
+      throw new CtxdbError("update requires a non-empty document ID");
+    }
+    return { document_id: candidate.documentId };
+  }
+  if (typeof candidate.kbName !== "string" || candidate.kbName.trim() === "" || typeof candidate.docName !== "string" || candidate.docName.trim() === "") {
+    throw new CtxdbError("logical update requires KB name and document name");
+  }
+  if (candidate.filePath !== void 0 && (typeof candidate.filePath !== "string" || candidate.filePath.trim() === "")) {
+    throw new CtxdbError("logical update file path must be a non-empty string");
+  }
+  const fields = {
+    knowledge_base_name: candidate.kbName,
+    name: candidate.docName
+  };
+  if (typeof candidate.filePath === "string") {
+    fields.file_path = candidate.filePath;
+  }
+  return fields;
+}
+function buildTextDocumentBody(kbName, docName, text, mimeType, filePath) {
   const body = {
     knowledge_base_name: kbName,
     name: docName,
@@ -101,74 +146,133 @@ async function uploadText(client, kbName, docName, text, mimeType = "text/plain"
     mime_type: mimeType
   };
   if (filePath !== void 0 && filePath !== "") body.file_path = filePath;
-  return client.postJson(DOCUMENTS, body);
+  return body;
 }
 async function uploadFile(client, kbName, localPath, options = {}) {
-  const expanded = expandHome(localPath);
-  if (!existsSync(expanded)) throw new Error(`file not found: ${expanded}`);
-  const stat = statSync(expanded);
-  if (!stat.isFile()) throw new Error(`not a file: ${expanded}`);
-  try {
-    accessSync(expanded, fsConstants.R_OK);
-  } catch (error) {
-    throw new Error(
-      `file is not readable: ${expanded}${error?.message ? ` (${error.message})` : ""}`
-    );
-  }
+  return writeFile(
+    client,
+    {
+      mode: "create",
+      kbName,
+      docName: options.docName,
+      filePath: options.filePath
+    },
+    localPath,
+    options.timeoutMs
+  );
+}
+async function updateFile(client, locator, localPath, options = {}) {
+  buildUpdateLocatorFields(locator);
+  return writeFile(
+    client,
+    { mode: "update", locator },
+    localPath,
+    options.timeoutMs
+  );
+}
+async function writeFile(client, target, localPath, requestedTimeoutMs) {
+  const { expanded, stat } = inspectLocalFile(localPath);
   const filename = basename(expanded);
-  const docName = options.docName ?? filename;
   const mime = guessMime(expanded);
   const content = await openAsBlob(expanded, { type: mime });
-  const fields = {
-    knowledge_base_name: kbName,
-    name: docName
-  };
-  if (options.filePath !== void 0 && options.filePath !== "") {
-    fields.file_path = options.filePath;
-  }
-  const timeoutMs = options.timeoutMs ?? DEFAULT_FILE_UPLOAD_TIMEOUT_MS;
+  const fields = target.mode === "create" ? {
+    knowledge_base_name: target.kbName,
+    name: target.docName ?? filename,
+    ...target.filePath ? { file_path: target.filePath } : {}
+  } : buildUpdateLocatorFields(target.locator);
+  const timeoutMs = requestedTimeoutMs ?? DEFAULT_FILE_UPLOAD_TIMEOUT_MS;
   try {
-    return await client.postMultipart(
+    const response = target.mode === "create" ? await client.postMultipart(
+      FILES,
+      fields,
+      { file: { filename, content, mimeType: mime } },
+      { timeoutMs }
+    ) : await client.putMultipart(
       FILES,
       fields,
       { file: { filename, content, mimeType: mime } },
       { timeoutMs }
     );
+    return target.mode === "update" ? readCanonicalUpdateDocument(response, "file update") : response;
   } catch (error) {
     if (!shouldFallbackToChunk(error)) throw error;
   }
-  return uploadFileInChunks(client, {
-    kbName,
+  return writeFileInChunks(client, {
+    target,
     filename,
-    docName,
-    filePath: options.filePath,
     mime,
     content,
     fileSize: stat.size,
     timeoutMs
   });
 }
-async function uploadFileInChunks(client, options) {
-  const kb = await client.get(KB_DETAIL, {
-    knowledge_base_name: options.kbName
-  });
-  const knowledgeBaseId = readRequiredString(kb, "id", "knowledge base detail");
+function validateLocalFile(localPath) {
+  inspectLocalFile(localPath);
+}
+function inspectLocalFile(localPath) {
+  const expanded = expandHome(localPath);
+  if (!existsSync(expanded)) throw new Error(`file not found: ${expanded}`);
+  const stat = statSync(expanded);
+  if (!stat.isFile()) throw new Error(`not a file: ${expanded}`);
+  try {
+    accessSync(expanded, fsConstants.R_OK);
+  } catch (error) {
+    throw new Error(
+      `file is not readable: ${expanded}${error?.message ? ` (${error.message})` : ""}`
+    );
+  }
+  return { expanded, stat };
+}
+async function writeFileInChunks(client, options) {
+  let expectedKnowledgeBaseId;
   const initParams = {
-    knowledge_base_id: knowledgeBaseId,
     file_name: options.filename,
-    name: options.docName,
     mime_type: options.mime
   };
-  if (options.filePath !== void 0 && options.filePath !== "") {
-    initParams.file_path = options.filePath;
+  if (options.target.mode === "create") {
+    expectedKnowledgeBaseId = await resolveKnowledgeBaseId(
+      client,
+      options.target.kbName
+    );
+    initParams.knowledge_base_id = expectedKnowledgeBaseId;
+    initParams.name = options.target.docName ?? options.filename;
+    if (options.target.filePath) initParams.file_path = options.target.filePath;
+  } else if ("documentId" in options.target.locator) {
+    initParams.document_id = options.target.locator.documentId;
+  } else {
+    expectedKnowledgeBaseId = await resolveKnowledgeBaseId(
+      client,
+      options.target.locator.kbName
+    );
+    initParams.knowledge_base_id = expectedKnowledgeBaseId;
+    initParams.name = options.target.locator.docName;
+    if (options.target.locator.filePath) {
+      initParams.file_path = options.target.locator.filePath;
+    }
   }
-  const initResponse = await client.postJson(
+  const initResponse = options.target.mode === "create" ? await client.postJson(
+    CHUNK_INIT,
+    {},
+    initParams,
+    { timeoutMs: options.timeoutMs }
+  ) : await client.putJson(
     CHUNK_INIT,
     {},
     initParams,
     { timeoutMs: options.timeoutMs }
   );
-  const init = unwrapBox(initResponse, "chunk init");
+  const normalizedInit = unwrapBareOrBox(initResponse, "chunk init");
+  const init = normalizedInit.value;
+  const initKnowledgeBaseId = readOptionalString(init, "knowledge_base_id");
+  if (!initKnowledgeBaseId) {
+    if (!(options.target.mode === "create" && normalizedInit.boxed)) {
+      throw new CtxdbError("chunk init returned invalid knowledge_base_id");
+    }
+  } else if (expectedKnowledgeBaseId && initKnowledgeBaseId !== expectedKnowledgeBaseId) {
+    throw new CtxdbError(
+      `chunk init returned mismatched knowledge_base_id ${initKnowledgeBaseId}`
+    );
+  }
   const uploadTicket = readRequiredString(
     init,
     "upload_ticket",
@@ -237,19 +341,56 @@ async function uploadFileInChunks(client, options) {
         headers: { "X-Upload-Ticket": uploadTicket }
       }
     );
-    const completed = unwrapBox(completeResponse, "chunk complete");
+    const normalizedComplete = unwrapBareOrBox(
+      completeResponse,
+      "chunk complete"
+    );
+    const completed = normalizedComplete.value;
+    const completedKnowledgeBaseId = readOptionalString(
+      completed,
+      "knowledge_base_id"
+    );
+    if (!completedKnowledgeBaseId) {
+      if (!(options.target.mode === "create" && normalizedComplete.boxed)) {
+        throw new CtxdbError(
+          "chunk complete returned invalid knowledge_base_id"
+        );
+      }
+    } else if (initKnowledgeBaseId && completedKnowledgeBaseId !== initKnowledgeBaseId) {
+      throw new CtxdbError(
+        `chunk complete returned mismatched knowledge_base_id ${completedKnowledgeBaseId}`
+      );
+    }
     const completedDocumentId = readRequiredString(
       completed,
       "document_id",
       "chunk complete"
     );
-    const reusedSucceededDocument = completedDocumentId !== documentId && completed.status === "succeeded";
+    const completedStatus = readOptionalString(completed, "status");
+    if (!completedStatus && !normalizedComplete.boxed) {
+      throw new CtxdbError("chunk complete returned invalid status");
+    }
+    const reusedSucceededDocument = completedDocumentId !== documentId && completedStatus === "succeeded";
     if (completedDocumentId !== documentId && !reusedSucceededDocument) {
       throw new CtxdbError(
         `chunk complete returned mismatched document_id ${completedDocumentId}`
       );
     }
-    return getDocument(client, options.kbName, completedDocumentId);
+    if (options.target.mode === "update") {
+      const canonicalKnowledgeBaseId = completedKnowledgeBaseId ?? initKnowledgeBaseId;
+      if (!canonicalKnowledgeBaseId) {
+        throw new CtxdbError(
+          "chunk update returned invalid knowledge_base_id"
+        );
+      }
+      const detail = await getDocumentByKnowledgeBaseId(
+        client,
+        canonicalKnowledgeBaseId,
+        completedDocumentId
+      );
+      return readCanonicalUpdateDocument(detail, "chunk update detail");
+    }
+    return getDocument(client, options.target.kbName, completedDocumentId);
   } catch (error) {
     if (!completeStarted) {
       try {
@@ -268,6 +409,10 @@ async function uploadFileInChunks(client, options) {
     throw error;
   }
 }
+async function resolveKnowledgeBaseId(client, kbName) {
+  const kb = await client.get(KB_DETAIL, { knowledge_base_name: kbName });
+  return readRequiredString(kb, "id", "knowledge base detail");
+}
 function shouldFallbackToChunk(error) {
   if (!error || typeof error !== "object") return false;
   const candidate = error;
@@ -303,6 +448,31 @@ function unwrapBox(response, operation) {
   }
   return box.data;
 }
+function unwrapBareOrBox(response, operation) {
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    throw new CtxdbError(`${operation} returned an invalid response`);
+  }
+  const object = response;
+  if (Object.hasOwn(object, "data")) {
+    return { value: unwrapBox(response, operation), boxed: true };
+  }
+  return { value: object, boxed: false };
+}
+function readCanonicalUpdateDocument(response, operation) {
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    throw new CtxdbError(`${operation} returned an invalid response`);
+  }
+  readRequiredString(response, "id", operation);
+  readRequiredString(response, "knowledge_base_id", operation);
+  return response;
+}
+function readOptionalString(value, field) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  const result = value[field];
+  return typeof result === "string" && result.trim() !== "" ? result : void 0;
+}
 function readRequiredString(value, field, source) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new CtxdbError(`${source} returned an invalid response`);
@@ -334,6 +504,12 @@ async function getDocument(client, kbName, docId) {
     document_id: docId
   });
 }
+async function getDocumentByKnowledgeBaseId(client, knowledgeBaseId, docId) {
+  return client.get(DOCUMENT_DETAIL, {
+    knowledge_base_id: knowledgeBaseId,
+    document_id: docId
+  });
+}
 async function listDocuments(client, kbName) {
   const resp = await client.get(DOCUMENTS, { knowledge_base_name: kbName });
   if (Array.isArray(resp)) return resp;
@@ -344,12 +520,24 @@ async function listDocuments(client, kbName) {
   return [];
 }
 async function pollIngest(client, kbName, docId, options = {}) {
+  return pollIngestWith(
+    () => getDocument(client, kbName, docId),
+    options
+  );
+}
+async function pollIngestByKnowledgeBaseId(client, knowledgeBaseId, docId, options = {}) {
+  return pollIngestWith(
+    () => getDocumentByKnowledgeBaseId(client, knowledgeBaseId, docId),
+    options
+  );
+}
+async function pollIngestWith(getLatest, options) {
   const timeoutMs = options.timeoutMs ?? DEFAULT_INGEST_TIMEOUT_MS;
   const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
   const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const now = options.now ?? (() => performance.now());
   const deadline = now() + timeoutMs;
-  let doc = await getDocument(client, kbName, docId);
+  let doc = await getLatest();
   let timedOut = false;
   while (ingestInFlight(doc)) {
     if (now() >= deadline) {
@@ -358,7 +546,7 @@ async function pollIngest(client, kbName, docId, options = {}) {
     }
     await sleep(intervalMs);
     try {
-      doc = await getDocument(client, kbName, docId);
+      doc = await getLatest();
     } catch {
       break;
     }
@@ -434,10 +622,14 @@ export {
   listKnowledgeBases,
   createKb,
   uploadText,
+  updateText,
   uploadFile,
+  updateFile,
+  validateLocalFile,
   getDocument,
   listDocuments,
   pollIngest,
+  pollIngestByKnowledgeBaseId,
   compactKbQueryResponse,
   minimalKbQueryResponse
 };

package/dist/{chunk-6BB65W5W.js → chunk-HF2CWTRU.js}

@@ -4,12 +4,12 @@ import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-B7JCQL4O.js";
+} from "./chunk-NJJBT52C.js";
 import {
   CtxdbError,
   debug,
   isDebug
-} from "./chunk-ARZX2RLR.js";
+} from "./chunk-AAZLOCVB.js";
 
 // src/lib/capture-orchestrator.ts
 import {

package/dist/{chunk-B7JCQL4O.js → chunk-NJJBT52C.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   configDir
-} from "./chunk-ARZX2RLR.js";
+} from "./chunk-AAZLOCVB.js";
 
 // src/lib/circuit.ts
 import { statSync, writeFileSync, unlinkSync, mkdirSync, readdirSync, readFileSync } from "fs";

package/dist/chunk-R67JELM7.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import {
+  define_CTXDB_DISTRIBUTION_MANIFEST_default
+} from "./chunk-VIG4SYLU.js";
+
+// src/lib/distribution-capabilities.ts
+var PUBLIC_DISTRIBUTION = {
+  id: "public",
+  packageName: "@aliyunrds/ctxdb",
+  packageRegistry: null,
+  capabilities: {
+    interactiveLogin: false,
+    managedCredentials: false
+  }
+};
+var DISTRIBUTION_MANIFEST = typeof define_CTXDB_DISTRIBUTION_MANIFEST_default === "undefined" ? PUBLIC_DISTRIBUTION : define_CTXDB_DISTRIBUTION_MANIFEST_default;
+
+export {
+  DISTRIBUTION_MANIFEST
+};

package/dist/{chunk-Z6OHSEF2.js → chunk-ULAWTBBC.js}

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
+import {
+  DISTRIBUTION_MANIFEST
+} from "./chunk-R67JELM7.js";
 
 // src/lib/self-update.ts
 import { spawnSync } from "child_process";
 import { fileURLToPath } from "url";
 import { dirname } from "path";
 import semver from "semver";
-var PACKAGE_NAME = "@aliyunrds/ctxdb";
 var NPM_VIEW_TIMEOUT_MS = 1e4;
 function npmCommand(platform = process.platform) {
   return platform === "win32" ? "npm.cmd" : "npm";
@@ -17,6 +19,9 @@ function detectInstallMethod() {
   const dir = dirname(fileURLToPath(import.meta.url));
   return dir.includes("/node_modules/") || dir.includes("\\node_modules\\") ? "npm" : "unknown";
 }
+function registryArgs(registry) {
+  return registry ? ["--registry", registry] : [];
+}
 function checkLatestVersion(currentVersion, options = {}) {
   const current = semver.valid(currentVersion);
   if (!current) {
@@ -29,12 +34,18 @@ function checkLatestVersion(currentVersion, options = {}) {
   }
   const platform = options.platform ?? process.platform;
   const run = options.spawnSyncFn ?? spawnSync;
-  const result = run(npmCommand(platform), ["view", PACKAGE_NAME, "version"], {
-    encoding: "utf-8",
-    timeout: options.timeoutMs ?? NPM_VIEW_TIMEOUT_MS,
-    stdio: ["ignore", "pipe", "pipe"],
-    shell: platform === "win32"
-  });
+  const packageName = options.packageName ?? DISTRIBUTION_MANIFEST.packageName;
+  const registry = options.registry === void 0 ? DISTRIBUTION_MANIFEST.packageRegistry : options.registry;
+  const result = run(
+    npmCommand(platform),
+    ["view", packageName, "version", ...registryArgs(registry)],
+    {
+      encoding: "utf-8",
+      timeout: options.timeoutMs ?? NPM_VIEW_TIMEOUT_MS,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: platform === "win32"
+    }
+  );
   if (result.status !== 0 || !result.stdout?.trim()) {
     return {
       latest: null,
@@ -82,7 +93,9 @@ function runSelfUpdate(currentVersion, passthroughArgs = [], options = {}) {
       error: "ctxdb was not installed via npm. Update manually with your package manager."
     };
   }
-  const check = checkLatestVersion(currentVersion);
+  const packageName = options.packageName ?? DISTRIBUTION_MANIFEST.packageName;
+  const registry = options.registry === void 0 ? DISTRIBUTION_MANIFEST.packageRegistry : options.registry;
+  const check = checkLatestVersion(currentVersion, { packageName, registry });
   if (check.error) {
     return {
       ok: false,
@@ -98,13 +111,17 @@ function runSelfUpdate(currentVersion, passthroughArgs = [], options = {}) {
     );
     return { ok: true, updated: false, fromVersion: currentVersion };
   }
-  process.stderr.write(`ctxdb: updating ${PACKAGE_NAME} v${currentVersion} \u2192 v${check.latest}...
+  process.stderr.write(`ctxdb: updating ${packageName} v${currentVersion} \u2192 v${check.latest}...
 `);
-  const install = spawnSync(npmCommand(), ["install", "-g", `${PACKAGE_NAME}@${check.latest}`], {
-    stdio: "inherit",
-    encoding: "utf-8",
-    shell: process.platform === "win32"
-  });
+  const install = spawnSync(
+    npmCommand(),
+    ["install", "-g", `${packageName}@${check.latest}`, ...registryArgs(registry)],
+    {
+      stdio: "inherit",
+      encoding: "utf-8",
+      shell: process.platform === "win32"
+    }
+  );
   if (install.status !== 0) {
     return {
       ok: false,
@@ -153,10 +170,11 @@ var NOTIFICATION_THROTTLE_MS = 3 * SUCCESS_TTL_MS;
 var LOCK_STALE_AFTER_MS = 10 * 60 * 1e3;
 function versionCheckPaths(home = homedir()) {
   const cacheDir = join(home, ".ctxdb", "cache");
+  const distributionSuffix = DISTRIBUTION_MANIFEST.id === "public" ? "" : `-${DISTRIBUTION_MANIFEST.id}`;
   return {
     cacheDir,
-    statePath: join(cacheDir, "version-check.json"),
-    lockPath: join(cacheDir, "version-check.lock")
+    statePath: join(cacheDir, `version-check${distributionSuffix}.json`),
+    lockPath: join(cacheDir, `version-check${distributionSuffix}.lock`)
   };
 }
 function createInitialVersionCheckState(currentVersion) {

package/dist/chunk-VIG4SYLU.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+// <define:__CTXDB_DISTRIBUTION_MANIFEST__>
+var define_CTXDB_DISTRIBUTION_MANIFEST_default = { id: "public", packageName: "@aliyunrds/ctxdb", packageRegistry: null, capabilities: { interactiveLogin: false, managedCredentials: false } };
+
+export {
+  define_CTXDB_DISTRIBUTION_MANIFEST_default
+};

package/dist/{chunk-VHNHVMCA.js → chunk-WSMZOFZQ.js}

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   listKnowledgeBases
-} from "./chunk-L4GVGVOP.js";
+} from "./chunk-CAXRYH6E.js";
 import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-B7JCQL4O.js";
+} from "./chunk-NJJBT52C.js";
 import {
   CtxdbError
-} from "./chunk-ARZX2RLR.js";
+} from "./chunk-AAZLOCVB.js";
 
 // src/lib/kb-catalog.ts
 function sanitizeKeyEntities(raw) {