@kweaver-ai/kweaver-sdk 0.7.1 → 0.7.2

package/dist/commands/ds.js

@@ -37,7 +37,10 @@ Subcommands:
   delete <id> [-y]                  Delete a datasource
   tables <id> [--keyword X]         List tables with columns
   connect <db_type> <host> <port> <database> --account X --password Y [--schema Z] [--name N]
+                                              [--reuse-existing|--force-new]
     Test connectivity, register datasource, and discover tables.
+    By default reuses an existing ds with the same (type, host, port, database, account)
+    instead of creating a duplicate. --force-new always creates a new entry.
   import-csv <ds-id> --files <glob_or_list> [--table-prefix X] [--batch-size N]
     Import CSV files into datasource tables via dataflow API.`);
         return 0;
@@ -206,6 +209,52 @@ async function runDsTablesCommand(args) {
     console.log(formatCallOutput(body, pretty));
     return 0;
 }
+export function findExistingDatasource(listBody, sig) {
+    const parsed = JSON.parse(listBody);
+    const entries = Array.isArray(parsed) ? parsed : (parsed.entries ?? []);
+    const tupleMatch = entries.find((e) => e.id &&
+        e.type === sig.type &&
+        e.bin_data?.host === sig.host &&
+        Number(e.bin_data?.port) === Number(sig.port) &&
+        e.bin_data?.database_name === sig.database &&
+        e.bin_data?.account === sig.account);
+    if (tupleMatch) {
+        return {
+            id: String(tupleMatch.id),
+            name: String(tupleMatch.name ?? ""),
+            matchedByName: tupleMatch.name === sig.name,
+            matchedByTuple: true,
+        };
+    }
+    if (sig.name) {
+        const nameMatch = entries.find((e) => e.id && e.name === sig.name);
+        if (nameMatch) {
+            return {
+                id: String(nameMatch.id),
+                name: String(nameMatch.name),
+                matchedByName: true,
+                matchedByTuple: false,
+            };
+        }
+    }
+    return undefined;
+}
+export function findDatasourceIdByName(listBody, name) {
+    const parsed = JSON.parse(listBody);
+    const entries = Array.isArray(parsed) ? parsed : (parsed.entries ?? []);
+    const hit = entries.find((e) => e.id && e.name === name);
+    return hit?.id ? String(hit.id) : undefined;
+}
+function isDuplicateNameError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    // HttpError.message is just "HTTP 400 ..."; the description lives in body.
+    const status = "status" in err ? Number(err.status) : NaN;
+    const body = "body" in err ? String(err.body) : "";
+    if (status !== 400)
+        return false;
+    return /数据源名称已存在|datasource name.*exist|already exists/i.test(body);
+}
 async function runDsConnectCommand(args) {
     let dbType = "";
     let host = "";
@@ -215,6 +264,7 @@ async function runDsConnectCommand(args) {
     let password = "";
     let schema;
     let name;
+    let forceNew = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--account" && args[i + 1]) {
@@ -233,6 +283,14 @@ async function runDsConnectCommand(args) {
             name = args[++i];
             continue;
         }
+        if (arg === "--force-new") {
+            forceNew = true;
+            continue;
+        }
+        if (arg === "--reuse-existing") {
+            forceNew = false;
+            continue;
+        }
         if (!arg.startsWith("-")) {
             if (!dbType)
                 dbType = arg;
@@ -245,7 +303,7 @@ async function runDsConnectCommand(args) {
         }
     }
     if (!dbType || !host || !database || !account || !password) {
-        console.error("Usage: kweaver ds connect <db_type> <host> <port> <database> --account X --password Y [--schema Z] [--name N]");
+        console.error("Usage: kweaver ds connect <db_type> <host> <port> <database> --account X --password Y [--schema Z] [--name N] [--reuse-existing|--force-new]");
         return 1;
     }
     if (Number.isNaN(port) || port < 1) {
@@ -254,6 +312,28 @@ async function runDsConnectCommand(args) {
     }
     const token = await ensureValidToken();
     const base = { baseUrl: token.baseUrl, accessToken: token.accessToken };
+    const dsName = name ?? database;
+    // Pre-flight dedup: connection-tuple match is the silent-orphan vector.
+    // Backend already rejects duplicate names with 400, but won't notice
+    // tuple collisions, so we own that check.
+    if (!forceNew) {
+        const listBody = await listDatasources({ ...base });
+        const hit = findExistingDatasource(listBody, {
+            type: dbType,
+            host,
+            port,
+            database,
+            account,
+            name: dsName,
+        });
+        if (hit) {
+            const why = hit.matchedByTuple
+                ? "matched by (type,host,port,database,account)"
+                : "matched by --name";
+            console.error(`Reusing existing datasource ${hit.id} (${hit.name}); ${why}. Use --force-new to override.`);
+            return printDsConnectOutput(base, hit.id);
+        }
+    }
     console.error("Testing connectivity ...");
     await testDatasource({
         ...base,
@@ -265,27 +345,45 @@ async function runDsConnectCommand(args) {
         password,
         schema,
     });
-    const dsName = name ?? database;
-    const createBody = await createDatasource({
-        ...base,
-        name: dsName,
-        type: dbType,
-        host,
-        port,
-        database,
-        account,
-        password,
-        schema,
-    });
-    const dsId = extractDatasourceId(createBody);
+    let dsId = "";
+    try {
+        const createBody = await createDatasource({
+            ...base,
+            name: dsName,
+            type: dbType,
+            host,
+            port,
+            database,
+            account,
+            password,
+            schema,
+        });
+        dsId = extractDatasourceId(createBody);
+    }
+    catch (err) {
+        // Backend checks name uniqueness but not tuple. If we raced another caller
+        // (or tuple match got disabled by --force-new and the name still collides),
+        // turn the raw 400 into a useful pointer to the existing id.
+        if (isDuplicateNameError(err)) {
+            // Backend rejected the name; look it up specifically (not by tuple —
+            // sibling ds sharing the same connection would mislead the pointer).
+            const listBody = await listDatasources({ ...base });
+            const existingId = findDatasourceIdByName(listBody, dsName);
+            if (existingId) {
+                console.error(`Datasource name '${dsName}' already exists as ${existingId}. Re-run without --force-new to reuse it, or pick a different --name.`);
+                return 1;
+            }
+        }
+        throw err;
+    }
     if (!dsId) {
         console.error("Failed to get datasource ID from create response");
         return 1;
     }
-    const tablesBody = await listTablesWithColumns({
-        ...base,
-        id: dsId,
-    });
+    return printDsConnectOutput(base, dsId);
+}
+async function printDsConnectOutput(base, dsId) {
+    const tablesBody = await listTablesWithColumns({ ...base, id: dsId });
     const tables = JSON.parse(tablesBody);
     const output = {
         datasource_id: dsId,

package/dist/commands/skill.js

@@ -1,8 +1,9 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { resolveBusinessDomain } from "../config/store.js";
-import { deleteSkill, downloadSkill, fetchSkillContent, fetchSkillFile, getSkill, getSkillContentIndex, installSkillArchive, listSkillMarket, listSkills, readSkillFile, registerSkillContent, registerSkillZip, updateSkillStatus, } from "../api/skills.js";
+import { deleteSkill, downloadSkill, fetchSkillContent, fetchSkillFile, getSkill, getSkillContentIndex, installSkillArchive, listSkillMarket, listSkills, readSkillFile, registerSkillZip, updateSkillStatus, } from "../api/skills.js";
+import { bundleSkillDirectoryToZip, bundleSkillFileToZip } from "../utils/skill-bundle.js";
 function printSkillHelp(subcommand) {
     if (subcommand === "list") {
         console.log(`kweaver skill list [--name kw] [--source src] [--status status] [--create-user user]
@@ -20,7 +21,15 @@ function printSkillHelp(subcommand) {
     }
     if (subcommand === "register") {
         console.log(`kweaver skill register (--content-file <path> | --zip-file <path>)
-                       [--source src] [--extend-info json] [-bd value] [--pretty|--compact]`);
+                       [--source src] [--extend-info json] [-bd value] [--pretty|--compact]
+
+  --content-file accepts either:
+    - a single file named SKILL.md (auto-bundled into a 1-file zip)
+    - a skill directory containing SKILL.md (bundled into a zip)
+  Both paths upload as multipart zip; the backend's file_type=content
+  registration is unreliable (publish-then-read returns 404) so the CLI
+  always goes through zip.
+  --zip-file accepts a pre-built .zip with SKILL.md at the archive root.`);
         return;
     }
     if (subcommand === "set-status" || subcommand === "status") {
@@ -54,6 +63,7 @@ Subcommands:
   market [--name kw] [--source src] [--page N] [--page-size N] [-bd value]
   get <skill-id> [-bd value]
   register --content-file <path> | --zip-file <path> [--source src] [--extend-info json]
+           (--content-file accepts a file named SKILL.md or a directory; both auto-zip)
   set-status <skill-id> <unpublish|published|offline> [-bd value]
   delete <skill-id> [-y] [-bd value]
   content <skill-id> [--raw] [--output file] [-bd value]
@@ -394,13 +404,23 @@ export async function runSkillCommand(args) {
             if (subcommand === "register") {
                 const opts = parseSkillRegisterArgs(rest);
                 if (opts.contentFile) {
-                    const content = readFileSync(resolve(opts.contentFile), "utf8");
-                    const result = await registerSkillContent({
+                    // Always bundle into zip — the backend's file_type=content path
+                    // doesn't write skill_file_index, so SKILL.md is unreachable
+                    // after publish via /skills/:id/content. Going through zip
+                    // (single SKILL.md or full directory) is the only path that
+                    // produces a readable skill end-to-end.
+                    const abs = resolve(opts.contentFile);
+                    const stat = statSync(abs);
+                    const bytes = stat.isDirectory()
+                        ? await bundleSkillDirectoryToZip(abs)
+                        : await bundleSkillFileToZip(abs);
+                    const result = await registerSkillZip({
                         ...token,
                         businessDomain: opts.businessDomain,
-                        content,
                         source: opts.source,
                         extendInfo: opts.extendInfo,
+                        filename: `${basename(abs).replace(/\.zip$/i, "")}.zip`,
+                        bytes,
                     });
                     console.log(format(result, opts.pretty));
                     return 0;

package/dist/config/stateless.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Stateless token mode: user passed --token on the CLI for this invocation.
+ *
+ * In stateless mode the CLI must not mutate ~/.kweaver/ — we error out from
+ * any command that would write tokens, sessions, or per-platform config.
+ *
+ * KWEAVER_TOKEN env (without --token flag) is NOT considered stateless: the
+ * env-var path predates this feature and keeps its existing semantics for
+ * backward compatibility. The cli.ts argv parser sets KWEAVER_TOKEN_SOURCE=flag
+ * only when --token was passed explicitly.
+ */
+export declare function isStatelessTokenMode(): boolean;
+export declare function assertNotStatelessForWrite(commandName: string): void;

package/dist/config/stateless.js

@@ -0,0 +1,20 @@
+/**
+ * Stateless token mode: user passed --token on the CLI for this invocation.
+ *
+ * In stateless mode the CLI must not mutate ~/.kweaver/ — we error out from
+ * any command that would write tokens, sessions, or per-platform config.
+ *
+ * KWEAVER_TOKEN env (without --token flag) is NOT considered stateless: the
+ * env-var path predates this feature and keeps its existing semantics for
+ * backward compatibility. The cli.ts argv parser sets KWEAVER_TOKEN_SOURCE=flag
+ * only when --token was passed explicitly.
+ */
+export function isStatelessTokenMode() {
+    return process.env.KWEAVER_TOKEN_SOURCE === "flag";
+}
+export function assertNotStatelessForWrite(commandName) {
+    if (isStatelessTokenMode()) {
+        throw new Error(`Cannot run \`${commandName}\` with --token. The --token flag is for stateless invocations and ` +
+            `must not mutate ~/.kweaver/. Drop --token, or use \`kweaver auth login\` to obtain a saved session.`);
+    }
+}

package/dist/utils/skill-bundle.d.ts

@@ -0,0 +1,5 @@
+export declare class SkillBundleError extends Error {
+    constructor(message: string);
+}
+export declare function bundleSkillDirectoryToZip(rootDir: string): Promise<Uint8Array>;
+export declare function bundleSkillFileToZip(filePath: string): Promise<Uint8Array>;

package/dist/utils/skill-bundle.js

@@ -0,0 +1,74 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join, posix, relative, sep } from "node:path";
+import JSZip from "jszip";
+const SKILL_MD = "SKILL.md";
+export class SkillBundleError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SkillBundleError";
+    }
+}
+function walk(rootDir) {
+    const out = [];
+    const stack = [rootDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(abs);
+            }
+            else if (entry.isFile()) {
+                out.push(abs);
+            }
+        }
+    }
+    return out;
+}
+function toPosixRelPath(rootDir, abs) {
+    const rel = relative(rootDir, abs);
+    return sep === posix.sep ? rel : rel.split(sep).join(posix.sep);
+}
+export async function bundleSkillDirectoryToZip(rootDir) {
+    const stat = statSync(rootDir);
+    if (!stat.isDirectory()) {
+        throw new SkillBundleError(`not a directory: ${rootDir}`);
+    }
+    const files = walk(rootDir);
+    if (files.length === 0) {
+        throw new SkillBundleError(`empty skill directory: ${rootDir}`);
+    }
+    const hasSkillMd = files.some((f) => toPosixRelPath(rootDir, f).toLowerCase() === SKILL_MD.toLowerCase());
+    if (!hasSkillMd) {
+        throw new SkillBundleError(`${SKILL_MD} not found at the root of ${rootDir} (server requires it)`);
+    }
+    const zip = new JSZip();
+    for (const abs of files) {
+        const relPath = toPosixRelPath(rootDir, abs);
+        zip.file(relPath, readFileSync(abs));
+    }
+    const buf = await zip.generateAsync({
+        type: "uint8array",
+        compression: "DEFLATE",
+        compressionOptions: { level: 6 },
+    });
+    return buf;
+}
+export async function bundleSkillFileToZip(filePath) {
+    const stat = statSync(filePath);
+    if (!stat.isFile()) {
+        throw new SkillBundleError(`not a file: ${filePath}`);
+    }
+    const fileName = basename(filePath);
+    if (fileName.toLowerCase() !== SKILL_MD.toLowerCase()) {
+        throw new SkillBundleError(`--content-file expects a file named ${SKILL_MD} (got ${fileName}). ` +
+            `Pass a directory containing ${SKILL_MD} for skills with assets.`);
+    }
+    const zip = new JSZip();
+    zip.file(SKILL_MD, readFileSync(filePath));
+    return zip.generateAsync({
+        type: "uint8array",
+        compression: "DEFLATE",
+        compressionOptions: { level: 6 },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -63,6 +63,7 @@
     "ink": "^6.8.0",
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
+    "jszip": "^3.10.1",
     "marked": "^11.2.0",
     "react": "^19.2.4",
     "string-width": "^8.2.0",