@kweaver-ai/kweaver-sdk 0.7.1 → 0.7.3

package/dist/commands/context-loader.js

@@ -2,12 +2,28 @@ import { ensureValidToken, formatHttpError, resolveActivePlatform, with401Refres
 import { callTool, searchSchema, queryObjectInstance, queryInstanceSubgraph, getLogicPropertiesValues, getActionInfo, findSkills, listTools, listResources, readResource, listResourceTemplates, listPrompts, getPrompt, } from "../api/context-loader.js";
 import { knSearchHttp, semanticSearch } from "../api/semantic-search.js";
 import { addContextLoaderEntry, getCurrentContextLoaderKn, loadContextLoaderConfig, removeContextLoaderEntry, resolveBusinessDomain, setCurrentContextLoader, } from "../config/store.js";
+import { assertNotStatelessForWrite } from "../config/stateless.js";
+const CONTEXT_LOADER_CONFIG_DEPRECATION = "[deprecated] `kweaver context-loader config ...` will be removed in a future release. " +
+    "Pass <kn-id> as the first positional to runtime subcommands instead, e.g. " +
+    "`kweaver context-loader tools <kn-id>` (or use the `--kn-id <id>` flag).";
 const MCP_NOT_CONFIGURED = "Context-loader MCP is not configured. Run: kweaver context-loader config set --kn-id <kn-id>";
-function ensureContextLoaderConfig() {
+const MCP_PATH = "/api/agent-retrieval/v1/mcp";
+function ensureContextLoaderConfig(knIdOverride) {
     const active = resolveActivePlatform();
     if (!active) {
         throw new Error("No platform selected. Set KWEAVER_BASE_URL or run: kweaver auth <platform-url>");
     }
+    // Override path (positional <kn-id> or --kn-id flag): derive MCP URL from
+    // the active platform; do not touch the deprecated saved config.
+    if (knIdOverride) {
+        return {
+            baseUrl: active.url,
+            mcpUrl: active.url.replace(/\/+$/, "") + MCP_PATH,
+            knId: knIdOverride,
+            accessToken: "",
+            businessDomain: resolveBusinessDomain(active.url),
+        };
+    }
     const kn = getCurrentContextLoaderKn();
     if (!kn) {
         throw new Error(MCP_NOT_CONFIGURED);
@@ -20,6 +36,50 @@ function ensureContextLoaderConfig() {
         businessDomain: resolveBusinessDomain(active.url),
     };
 }
+// Subcommands that consult `ensureContextLoaderConfig`. The number is the
+// minimum non-flag positional count expected by the handler itself (after
+// kn-id is extracted). When the leading non-flag positional count exceeds
+// this minimum, the first one is treated as <kn-id>.
+const RUNTIME_MIN_POSITIONALS = {
+    tools: 0,
+    resources: 0,
+    templates: 0,
+    prompts: 0,
+    prompt: 1,
+    resource: 1,
+    "search-schema": 1,
+    "tool-call": 1,
+    "kn-search": 1,
+    "kn-schema-search": 1,
+    "query-object-instance": 1,
+    "query-instance-subgraph": 1,
+    "get-logic-properties": 1,
+    "get-action-info": 1,
+    "find-skills": 1,
+};
+function extractKnIdOverride(subcommand, rest) {
+    // 1) Explicit flag wins. `--kn-id <id>` / `-k <id>` is allowed for every
+    //    runtime subcommand and is consumed before the handler sees `rest`.
+    for (let i = 0; i < rest.length; i += 1) {
+        if ((rest[i] === "--kn-id" || rest[i] === "-k") && rest[i + 1]) {
+            const id = rest[i + 1];
+            rest.splice(i, 2);
+            return id;
+        }
+    }
+    // 2) Positional <kn-id> as the first non-flag arg, when leading non-flag
+    //    positional count exceeds what the handler itself requires.
+    const min = RUNTIME_MIN_POSITIONALS[subcommand];
+    if (min === undefined)
+        return undefined;
+    let cut = 0;
+    while (cut < rest.length && !rest[cut].startsWith("-"))
+        cut += 1;
+    if (cut > min) {
+        return rest.shift();
+    }
+    return undefined;
+}
 function formatOutput(value, pretty) {
     const json = JSON.stringify(value, null, pretty ? 2 : 0);
     return json;
@@ -29,34 +89,38 @@ export async function runContextLoaderCommand(args) {
     if (!subcommand || subcommand === "--help" || subcommand === "-h") {
         console.log(`kweaver context-loader
 
+KN selection (for runtime subcommands below):
+  Pass <kn-id> as the FIRST positional, e.g. \`kweaver context-loader tools <kn-id>\`,
+  or use the global \`--kn-id <id>\` / \`-k <id>\` flag. When omitted, falls back to
+  the deprecated saved config managed by \`kweaver context-loader config\`.
+
 Subcommands:
-  config set --kn-id <id> [--name n]   Add or update kn config (MCP URL derived from platform)
-  config use <name>                    Switch current config
-  config list                         List all configs and current
-  config remove <name>                 Remove a config
-  config show                         Show current config (knId + mcpUrl)
-  tools                               tools/list - list available tools
-  resources                           resources/list - list resources
-  resource <uri>                      resources/read - read resource by URI
-  templates                           resources/templates/list - list resource templates
-  prompts                             prompts/list - list prompts
-  prompt <name> [--args json]          prompts/get - get prompt by name
-  search-schema <query> [options]      MCP search_schema (object/relation/action/metric types)
-  tool-call <name> --args '<json>'     MCP tools/call for any server tool
-  kn-search <query> [--only-schema]    Compatibility: HTTP kn_search
-  kn-schema-search <query> [--max N]   Compatibility: HTTP semantic-search
-  query-object-instance <json>         Layer 2: Query instances (args as JSON)
-  query-instance-subgraph <json>       Layer 2: Query subgraph (args as JSON)
-  get-logic-properties <json>          Layer 3: Get logic property values (args as JSON)
-  get-action-info <json>               Layer 3: Get action info (args as JSON)
-  find-skills <ot_id> [options]        Layer 3: Recall skills for an object type
+  config set --kn-id <id> [--name n]   [deprecated] Add or update kn config
+  config use <name>                    [deprecated] Switch current config
+  config list                          [deprecated] List all configs and current
+  config remove <name>                 [deprecated] Remove a config
+  config show                          [deprecated] Show current config (knId + mcpUrl)
+  tools <kn-id>                        tools/list - list available tools
+  resources <kn-id>                    resources/list - list resources
+  resource <kn-id> <uri>               resources/read - read resource by URI
+  templates <kn-id>                    resources/templates/list - list resource templates
+  prompts <kn-id>                      prompts/list - list prompts
+  prompt <kn-id> <name> [--args json]  prompts/get - get prompt by name
+  search-schema <kn-id> <query> [opts] MCP search_schema (object/relation/action/metric)
+  tool-call <kn-id> <name> --args '<json>'  MCP tools/call for any server tool
+  kn-search <kn-id> <query> [--only-schema]  Compatibility: HTTP kn_search
+  kn-schema-search <kn-id> <query> [--max N] Compatibility: HTTP semantic-search
+  query-object-instance <kn-id> <json>       Layer 2: Query instances
+  query-instance-subgraph <kn-id> <json>     Layer 2: Query subgraph
+  get-logic-properties <kn-id> <json>        Layer 3: Get logic property values
+  get-action-info <kn-id> <json>             Layer 3: Get action info
+  find-skills <kn-id> <ot_id> [options]      Layer 3: Recall skills for an object type
 
 Examples:
-  kweaver context-loader config set --kn-id d5iv6c9818p72mpje8pg
-  kweaver context-loader config set --kn-id xyz123 --name project-a
-  kweaver context-loader search-schema "利润率" --scope object,metric --max 5
-  kweaver context-loader tool-call search_schema --args '{"query":"利润率"}'
-  kweaver context-loader kn-search "高血压 治疗 药品" --only-schema --pretty`);
+  kweaver context-loader tools d5iv6c9818p72mpje8pg
+  kweaver context-loader search-schema d5iv6c9818p72mpje8pg "利润率" --scope object,metric --max 5
+  kweaver context-loader tool-call d5iv6c9818p72mpje8pg search_schema --args '{"query":"利润率"}'
+  kweaver context-loader kn-search d5iv6c9818p72mpje8pg "高血压 治疗 药品" --only-schema --pretty`);
         return 0;
     }
     if (subcommand === "config") {
@@ -68,9 +132,12 @@ Examples:
         pretty = true;
         rest.splice(prettyIdx, 1);
     }
+    // Extract `<kn-id>` (positional or --kn-id/-k flag) before per-subcommand
+    // arg parsing. When provided it bypasses the deprecated saved config.
+    const knIdOverride = extractKnIdOverride(subcommand, rest);
     const dispatch = async () => {
         const token = await ensureValidToken();
-        const base = ensureContextLoaderConfig();
+        const base = ensureContextLoaderConfig(knIdOverride);
         const options = { ...base, accessToken: token.accessToken };
         if (subcommand === "tools")
             return runListTools(options, rest, pretty);
@@ -122,16 +189,30 @@ Examples:
 async function runConfigCommand(args) {
     const [action, ...rest] = args;
     if (!action || action === "--help" || action === "-h") {
-        console.log(`kweaver context-loader config
+        console.log(`kweaver context-loader config  [deprecated]
 
 Subcommands:
   set --kn-id <id> [--name <name>]   Add or update kn config (default name: default)
   use <name>                         Switch current config
   list                               List all configs and current
   remove <name>                      Remove a config
-  show                               Show current config (knId + mcpUrl)`);
+  show                               Show current config (knId + mcpUrl)
+
+Note: this command group is deprecated and will be removed in a future release.
+      It is disabled entirely in stateless mode (\`--token\`).`);
         return 0;
     }
+    // Stateless mode (`--token`) does not support any context-loader config
+    // operations; the saved config lives under `~/.kweaver/` and is foreign
+    // to the stateless paradigm.
+    try {
+        assertNotStatelessForWrite(`context-loader config ${action}`);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    console.warn(CONTEXT_LOADER_CONFIG_DEPRECATION);
     const active = resolveActivePlatform();
     if (!active) {
         console.error("No platform selected. Set KWEAVER_BASE_URL or run: kweaver auth <platform-url>");
@@ -435,29 +516,24 @@ async function runToolCall(options, args, pretty) {
 async function runKnSearch(options, args, pretty) {
     let query;
     let onlySchema = false;
-    let knIdOverride;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--only-schema") {
             onlySchema = true;
         }
-        else if ((arg === "--kn-id" || arg === "-k") && args[i + 1]) {
-            knIdOverride = args[i + 1];
-            i += 1;
-        }
         else if (!arg.startsWith("-") && !query) {
             query = arg;
         }
     }
     if (!query) {
-        console.error("Usage: kweaver context-loader kn-search <query> [--kn-id <id>] [--only-schema]");
+        console.error("Usage: kweaver context-loader kn-search <kn-id> <query> [--only-schema]");
         return 1;
     }
     const raw = await knSearchHttp({
         baseUrl: options.baseUrl,
         accessToken: options.accessToken,
         businessDomain: options.businessDomain,
-        knId: knIdOverride ?? options.knId,
+        knId: options.knId,
         query,
         onlySchema,
     });

package/dist/commands/dataflow.js

@@ -7,6 +7,9 @@ import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/
 import { resolveBusinessDomain } from "../config/store.js";
 import { getDataflowLogsPage, listDataflowRuns, listDataflows, runDataflowWithFile, runDataflowWithRemoteUrl, } from "../api/dataflow2.js";
 import { createDataflow } from "../api/dataflow.js";
+import { createVegaResource } from "../api/vega.js";
+import { createKnowledgeNetwork } from "../api/knowledge-networks.js";
+import { loadTemplate, listTemplates, renderTemplate, generateSourceIdentifier, getTemplatesDir, } from "../utils/template-loader.js";
 function renderTable(rows) {
     if (rows.length === 0)
         return "";
@@ -101,26 +104,6 @@ export async function runDataflowCommand(args) {
         .strict()
         .fail((message, error) => {
         throw error ?? new Error(message);
-    })
-        .command("create <json>", "Create a new dataflow (DAG) from a JSON definition", (command) => command
-        .positional("json", {
-        type: "string",
-        describe: "JSON body string or @file-path to read from file",
-    })
-        .option("biz-domain", { alias: "bd", type: "string" }), async (argv) => {
-        exitCode = await with401RefreshRetry(async () => {
-            const base = await requireTokenAndBusinessDomain(argv.bizDomain);
-            let raw = argv.json;
-            if (raw.startsWith("@")) {
-                const filePath = raw.slice(1);
-                await access(filePath, constants.R_OK);
-                raw = (await readFile(filePath, "utf8")).toString();
-            }
-            const body = JSON.parse(raw);
-            const dagId = await createDataflow({ ...base, body });
-            console.log(JSON.stringify({ id: dagId }, null, 2));
-            return 0;
-        });
     })
         .command("list", "List all dataflows", (command) => command
         .option("biz-domain", {
@@ -280,6 +263,197 @@ export async function runDataflowCommand(args) {
             }
             return 0;
         });
+    })
+        .command("templates", "List all available templates", {
+        json: { type: "boolean", default: false, describe: "Output as JSON" },
+    }, (argv) => {
+        const templatesDir = getTemplatesDir();
+        return Promise.all([
+            listTemplates("dataset", templatesDir),
+            listTemplates("bkn", templatesDir),
+            listTemplates("dataflow", templatesDir),
+        ]).then(([datasetTemplates, bknTemplates, dataflowTemplates]) => {
+            if (argv.json) {
+                console.log(JSON.stringify({
+                    dataset: datasetTemplates,
+                    bkn: bknTemplates,
+                    dataflow: dataflowTemplates,
+                }, null, 2));
+            }
+            else {
+                console.log("Dataset Templates:");
+                for (const t of datasetTemplates) {
+                    console.log(`  - ${t.name.padEnd(18)} ${t.description}`);
+                }
+                console.log("");
+                console.log("BKN Templates:");
+                for (const t of bknTemplates) {
+                    console.log(`  - ${t.name.padEnd(18)} ${t.description}`);
+                }
+                console.log("");
+                console.log("Dataflow Templates:");
+                for (const t of dataflowTemplates) {
+                    console.log(`  - ${t.name.padEnd(18)} ${t.description}`);
+                }
+            }
+        });
+    })
+        .command("create-dataset", "Create a dataset from a template", (command) => command
+        .option("template", { type: "string", demandOption: true, describe: "Template name" })
+        .option("set", { type: "array", string: true, describe: "Set parameter (key=value), can be used multiple times" })
+        .option("json", { type: "boolean", default: false, describe: "Output as JSON" })
+        .option("biz-domain", { alias: "bd", type: "string" }), async (argv) => {
+        exitCode = await with401RefreshRetry(async () => {
+            const base = await requireTokenAndBusinessDomain(argv.bizDomain);
+            const templatesDir = getTemplatesDir();
+            // Parse --set arguments
+            const args = {};
+            if (argv.set) {
+                for (const item of argv.set) {
+                    const eqIdx = item.indexOf("=");
+                    if (eqIdx > 0) {
+                        const key = item.slice(0, eqIdx);
+                        const value = item.slice(eqIdx + 1);
+                        args[key] = value;
+                    }
+                }
+            }
+            // Load template
+            const loaded = await loadTemplate(argv.template, "dataset", templatesDir);
+            if (!loaded) {
+                console.error(`Template not found: ${argv.template}`);
+                return 1;
+            }
+            // Auto-generate source_identifier if not provided
+            if (!args["source_identifier"]) {
+                const prefixMap = {
+                    "document": "dataflow_document",
+                    "document-content": "dataflow_content",
+                    "document-element": "dataflow_element",
+                };
+                const prefix = prefixMap[loaded.manifest.name] || "dataflow";
+                args["source_identifier"] = generateSourceIdentifier(prefix);
+            }
+            // Render template
+            const rendered = renderTemplate(loaded.template, loaded.manifest, args);
+            // Create dataset via API
+            const response = await createVegaResource({
+                ...base,
+                body: JSON.stringify(rendered),
+            });
+            const result = JSON.parse(response);
+            if (argv.json) {
+                console.log(JSON.stringify({ success: true, id: result.id, name: args.name }, null, 2));
+            }
+            else {
+                console.log(`dataset created: id=${result.id}`);
+            }
+            return 0;
+        });
+    })
+        .command("create-bkn", "Create a BKN (knowledge network) from a template", (command) => command
+        .option("template", { type: "string", demandOption: true, describe: "Template name" })
+        .option("set", { type: "array", string: true, describe: "Set parameter (key=value), can be used multiple times" })
+        .option("json", { type: "boolean", default: false, describe: "Output as JSON" })
+        .option("biz-domain", { alias: "bd", type: "string" }), async (argv) => {
+        exitCode = await with401RefreshRetry(async () => {
+            const base = await requireTokenAndBusinessDomain(argv.bizDomain);
+            const templatesDir = getTemplatesDir();
+            // Parse --set arguments
+            const args = {};
+            if (argv.set) {
+                for (const item of argv.set) {
+                    const eqIdx = item.indexOf("=");
+                    if (eqIdx > 0) {
+                        const key = item.slice(0, eqIdx);
+                        const value = item.slice(eqIdx + 1);
+                        args[key] = value;
+                    }
+                }
+            }
+            // Load template
+            const loaded = await loadTemplate(argv.template, "bkn", templatesDir);
+            if (!loaded) {
+                console.error(`Template not found: ${argv.template}`);
+                return 1;
+            }
+            // Render template
+            const rendered = renderTemplate(loaded.template, loaded.manifest, args);
+            rendered.business_domain = base.businessDomain;
+            // Create BKN via API
+            const response = await createKnowledgeNetwork({
+                ...base,
+                body: JSON.stringify(rendered),
+                validate_dependency: false,
+            });
+            const result = JSON.parse(response);
+            if (argv.json) {
+                console.log(JSON.stringify({ success: true, id: result.id, name: args.name }, null, 2));
+            }
+            else {
+                console.log(`bkn created: id=${result.id}`);
+            }
+            return 0;
+        });
+    })
+        .command("create [json]", "Create a new dataflow (DAG) from a JSON definition or template", (command) => command
+        .positional("json", {
+        type: "string",
+        describe: "JSON body string or @file-path to read from file",
+    })
+        .option("template", { type: "string", describe: "Template name (use instead of json)" })
+        .option("set", { type: "array", string: true, describe: "Set parameter (key=value), can be used multiple times" })
+        .option("biz-domain", { alias: "bd", type: "string" })
+        .check((argv) => {
+        const hasJson = typeof argv.json === "string";
+        const hasTemplate = typeof argv.template === "string";
+        if (hasJson && hasTemplate) {
+            throw new Error("Cannot use both json and --template");
+        }
+        if (!hasJson && !hasTemplate) {
+            throw new Error("Either json or --template is required");
+        }
+        return true;
+    }), async (argv) => {
+        exitCode = await with401RefreshRetry(async () => {
+            const base = await requireTokenAndBusinessDomain(argv.bizDomain);
+            let body;
+            if (argv.template) {
+                // Use template
+                const templatesDir = getTemplatesDir();
+                // Parse --set arguments
+                const args = {};
+                if (argv.set) {
+                    for (const item of argv.set) {
+                        const eqIdx = item.indexOf("=");
+                        if (eqIdx > 0) {
+                            const key = item.slice(0, eqIdx);
+                            const value = item.slice(eqIdx + 1);
+                            args[key] = value;
+                        }
+                    }
+                }
+                const loaded = await loadTemplate(argv.template, "dataflow", templatesDir);
+                if (!loaded) {
+                    console.error(`Template not found: ${argv.template}`);
+                    return 1;
+                }
+                body = renderTemplate(loaded.template, loaded.manifest, args);
+            }
+            else {
+                // Use JSON
+                let raw = argv.json;
+                if (raw.startsWith("@")) {
+                    const filePath = raw.slice(1);
+                    await access(filePath, constants.R_OK);
+                    raw = (await readFile(filePath, "utf8")).toString();
+                }
+                body = JSON.parse(raw);
+            }
+            const dagId = await createDataflow({ ...base, body });
+            console.log(JSON.stringify({ id: dagId }, null, 2));
+            return 0;
+        });
     })
         .demandCommand(1);
     try {

package/dist/commands/ds.d.ts

@@ -5,13 +5,35 @@ export declare function parseDsListArgs(args: string[]): {
     businessDomain: string;
     pretty: boolean;
 };
+/**
+ * Match candidate signature against a list response (the kind returned by
+ * `listDatasources`). Connection metadata lives under `bin_data` — host,
+ * port, account, plus type-specific fields (`database_name` for MySQL etc.).
+ *
+ * Exported for unit testing.
+ */
+export interface DsMatchSignature {
+    type: string;
+    host: string;
+    port: number;
+    database: string;
+    account: string;
+    name?: string;
+}
+export interface DsMatchHit {
+    id: string;
+    name: string;
+    matchedByName: boolean;
+    matchedByTuple: boolean;
+}
+export declare function findExistingDatasource(listBody: string, sig: DsMatchSignature): DsMatchHit | undefined;
+export declare function findDatasourceIdByName(listBody: string, name: string): string | undefined;
 export declare function parseImportCsvArgs(args: string[]): {
     datasourceId: string;
     files: string;
     tablePrefix: string;
     batchSize: number;
     businessDomain: string;
-    recreate: boolean;
 };
 export declare function resolveFiles(pattern: string): Promise<string[]>;
 export interface ImportCsvResult {