@kweaver-ai/kweaver-sdk 0.4.1 → 0.4.4

package/dist/commands/bkn.js

@@ -1,12 +1,18 @@
 import { createInterface } from "node:readline";
-import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadNetwork, allObjects, allRelations, allActions, generateChecksum, validateNetwork } from "@kweaver-ai/bkn";
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
+import { HttpError } from "../utils/http.js";
 import { listKnowledgeNetworks, getKnowledgeNetwork, createKnowledgeNetwork, updateKnowledgeNetwork, deleteKnowledgeNetwork, listObjectTypes, listRelationTypes, listActionTypes, getObjectType, createObjectTypes, updateObjectType, deleteObjectTypes, getRelationType, createRelationTypes, updateRelationType, deleteRelationTypes, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
 import { objectTypeQuery, objectTypeProperties, subgraph, actionTypeQuery, actionTypeExecute, actionExecutionGet, actionLogsList, actionLogGet, actionLogCancel, } from "../api/ontology-query.js";
 import { semanticSearch } from "../api/semantic-search.js";
 import { listTablesWithColumns } from "../api/datasources.js";
 import { createDataView } from "../api/dataviews.js";
+import { downloadBkn, uploadBkn } from "../api/bkn-backend.js";
 import { formatCallOutput } from "./call.js";
+import { resolveBusinessDomain } from "../config/store.js";
 export function formatSimpleKnList(text, pretty, includeDetail = false) {
     const parsed = JSON.parse(text);
     const entries = Array.isArray(parsed.entries) ? parsed.entries : [];
@@ -23,7 +29,7 @@ export function parseKnListArgs(args) {
     let limit = 50;
     let sort = "update_time";
     let direction = "desc";
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let detail = false;
     let pretty = true;
     let verbose = false;
@@ -94,13 +100,15 @@ export function parseKnListArgs(args) {
         }
         throw new Error(`Unsupported kn list argument: ${arg}`);
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { offset, limit, sort, direction, businessDomain, detail, pretty, verbose, name_pattern, tag };
 }
 export function parseKnGetArgs(args) {
     let knId = "";
     let stats = false;
     let exportMode = false;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let pretty = true;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
@@ -136,6 +144,8 @@ export function parseKnGetArgs(args) {
     if (!knId) {
         throw new Error("Missing kn-id. Usage: kweaver bkn get <kn-id> [options]");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, stats, export: exportMode, businessDomain, pretty };
 }
 const BODY_FILE_FLAGS = [
@@ -151,7 +161,7 @@ export function parseKnCreateArgs(args) {
     let bodyFile;
     let import_mode;
     let validate_dependency;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let pretty = true;
     const flags = {};
     for (let i = 0; i < args.length; i += 1) {
@@ -229,12 +239,14 @@ export function parseKnCreateArgs(args) {
             payload.color = flags.color;
         body = JSON.stringify(payload);
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { body, import_mode, validate_dependency, businessDomain, pretty };
 }
 export function parseKnUpdateArgs(args) {
     let knId = "";
     let bodyFile;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let pretty = true;
     const flags = {};
     for (let i = 0; i < args.length; i += 1) {
@@ -304,11 +316,13 @@ export function parseKnUpdateArgs(args) {
             payload.color = flags.color;
         body = JSON.stringify(payload);
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, body, businessDomain, pretty };
 }
 export function parseKnDeleteArgs(args) {
     let knId = "";
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let yes = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
@@ -336,8 +350,100 @@ export function parseKnDeleteArgs(args) {
     if (!knId) {
         throw new Error("Missing kn-id. Usage: kweaver bkn delete <kn-id>");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, businessDomain, yes };
 }
+export function parseKnPushArgs(args) {
+    let directory = "";
+    let branch = "main";
+    let businessDomain = "";
+    let pretty = true;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            throw new Error("help");
+        }
+        if (arg === "--branch") {
+            branch = args[i + 1] ?? "main";
+            if (!branch || branch.startsWith("-")) {
+                throw new Error("Missing value for --branch");
+            }
+            i += 1;
+            continue;
+        }
+        if (arg === "-bd" || arg === "--biz-domain") {
+            businessDomain = args[i + 1] ?? "bd_public";
+            if (!businessDomain || businessDomain.startsWith("-")) {
+                throw new Error("Missing value for biz-domain flag");
+            }
+            i += 1;
+            continue;
+        }
+        if (arg === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if (!arg.startsWith("-") && !directory) {
+            directory = arg;
+            continue;
+        }
+        throw new Error(`Unsupported bkn push argument: ${arg}`);
+    }
+    if (!directory) {
+        throw new Error("Missing directory. Usage: kweaver bkn push <directory> [--branch main] [-bd value]");
+    }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
+    return { directory, branch, businessDomain, pretty };
+}
+export function parseKnPullArgs(args) {
+    let knId = "";
+    let directory = "";
+    let branch = "main";
+    let businessDomain = "";
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            throw new Error("help");
+        }
+        if (arg === "--branch") {
+            branch = args[i + 1] ?? "main";
+            if (!branch || branch.startsWith("-")) {
+                throw new Error("Missing value for --branch");
+            }
+            i += 1;
+            continue;
+        }
+        if (arg === "-bd" || arg === "--biz-domain") {
+            businessDomain = args[i + 1] ?? "bd_public";
+            if (!businessDomain || businessDomain.startsWith("-")) {
+                throw new Error("Missing value for biz-domain flag");
+            }
+            i += 1;
+            continue;
+        }
+        if (!arg.startsWith("-")) {
+            if (!knId) {
+                knId = arg;
+            }
+            else if (!directory) {
+                directory = arg;
+            }
+            else {
+                throw new Error(`Unexpected positional argument: ${arg}`);
+            }
+            continue;
+        }
+        throw new Error(`Unsupported bkn pull argument: ${arg}`);
+    }
+    if (!knId) {
+        throw new Error("Missing kn-id. Usage: kweaver bkn pull <kn-id> [<directory>] [--branch main] [-bd value]");
+    }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
+    return { knId, directory: directory || knId, branch, businessDomain };
+}
 function parseJsonObject(text, errorMessage) {
     let parsed;
     try {
@@ -366,7 +472,7 @@ function parseSearchAfterArray(text) {
 }
 export function parseKnObjectTypeQueryArgs(args) {
     let pretty = true;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let limit;
     let searchAfter;
     const positionalArgs = [];
@@ -425,6 +531,8 @@ export function parseKnObjectTypeQueryArgs(args) {
     if (typeof body.limit !== "number" || !Number.isFinite(body.limit) || body.limit < 1) {
         throw new Error("Missing limit. Provide it in body JSON or via --limit <n>.");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return {
         knId,
         otId,
@@ -443,6 +551,9 @@ Subcommands:
   update <kn-id> [options]  Update a knowledge network
   delete <kn-id>       Delete a knowledge network
   build <kn-id> [--wait|--no-wait] [--timeout n]   Trigger full build
+  validate <directory>   Validate a local BKN directory (no upload)
+  push <directory> [--branch main]   Upload BKN directory as tar
+  pull <kn-id> [<directory>] [--branch main]   Download BKN tar and extract
   export <kn-id>       Export knowledge network (alias for get --export)
   stats <kn-id>        Get statistics (alias for get --stats)
   search <kn-id> <query> [options]   Semantic search within a knowledge network
@@ -452,7 +563,7 @@ Subcommands:
   object-type update <kn-id> <ot-id> [options]   Update object type
   object-type delete <kn-id> <ot-ids> [-y]   Delete object type(s)
   object-type query <kn-id> <ot-id> ['<json>']   Query object instances (ontology-query; supports --limit/--search-after)
-  object-type properties <kn-id> <ot-id> '<json>'   Query object properties
+  object-type properties <kn-id> <ot-id> '<json>'   Query instance properties (json: {"_instance_identities":[{pk:val}],"properties":[...]})
   relation-type list <kn-id>   List relation types (schema)
   relation-type get <kn-id> <rt-id>   Get relation type details
   relation-type create <kn-id> [options]   Create relation type (--name --source --target [--mapping src:tgt])
@@ -474,56 +585,71 @@ export async function runKnCommand(args) {
         console.log(KN_HELP);
         return 0;
     }
-    if (subcommand === "list") {
-        return runKnListCommand(rest);
-    }
-    if (subcommand === "get") {
-        return runKnGetCommand(rest);
-    }
-    if (subcommand === "create") {
-        return runKnCreateCommand(rest);
-    }
-    if (subcommand === "create-from-ds") {
-        return runKnCreateFromDsCommand(rest);
-    }
-    if (subcommand === "update") {
-        return runKnUpdateCommand(rest);
-    }
-    if (subcommand === "delete") {
-        return runKnDeleteCommand(rest);
-    }
-    if (subcommand === "build") {
-        return runKnBuildCommand(rest);
-    }
-    if (subcommand === "export") {
-        return runKnGetCommand([...(rest[0] ? [rest[0]] : []), "--export", ...rest.slice(1)]);
-    }
-    if (subcommand === "stats") {
-        return runKnGetCommand([...(rest[0] ? [rest[0]] : []), "--stats", ...rest.slice(1)]);
-    }
-    if (subcommand === "search") {
-        return runKnSearchCommand(rest);
-    }
-    if (subcommand === "object-type") {
-        return runKnObjectTypeCommand(rest);
-    }
-    if (subcommand === "relation-type") {
-        return runKnRelationTypeCommand(rest);
-    }
-    if (subcommand === "subgraph") {
-        return runKnSubgraphCommand(rest);
-    }
-    if (subcommand === "action-type") {
-        return runKnActionTypeCommand(rest);
-    }
-    if (subcommand === "action-execution") {
-        return runKnActionExecutionCommand(rest);
+    const dispatch = () => {
+        if (subcommand === "list")
+            return runKnListCommand(rest);
+        if (subcommand === "get")
+            return runKnGetCommand(rest);
+        if (subcommand === "create")
+            return runKnCreateCommand(rest);
+        if (subcommand === "create-from-ds")
+            return runKnCreateFromDsCommand(rest);
+        if (subcommand === "update")
+            return runKnUpdateCommand(rest);
+        if (subcommand === "delete")
+            return runKnDeleteCommand(rest);
+        if (subcommand === "build")
+            return runKnBuildCommand(rest);
+        if (subcommand === "validate")
+            return runKnValidateCommand(rest);
+        if (subcommand === "push")
+            return runKnPushCommand(rest);
+        if (subcommand === "pull")
+            return runKnPullCommand(rest);
+        if (subcommand === "export")
+            return runKnGetCommand([...(rest[0] ? [rest[0]] : []), "--export", ...rest.slice(1)]);
+        if (subcommand === "stats")
+            return runKnGetCommand([...(rest[0] ? [rest[0]] : []), "--stats", ...rest.slice(1)]);
+        if (subcommand === "search")
+            return runKnSearchCommand(rest);
+        if (subcommand === "object-type")
+            return runKnObjectTypeCommand(rest);
+        if (subcommand === "relation-type")
+            return runKnRelationTypeCommand(rest);
+        if (subcommand === "subgraph")
+            return runKnSubgraphCommand(rest);
+        if (subcommand === "action-type")
+            return runKnActionTypeCommand(rest);
+        if (subcommand === "action-execution")
+            return runKnActionExecutionCommand(rest);
+        if (subcommand === "action-log")
+            return runKnActionLogCommand(rest);
+        return Promise.resolve(-1);
+    };
+    try {
+        const code = await dispatch();
+        if (code === -1) {
+            console.error(`Unknown bkn subcommand: ${subcommand}`);
+            return 1;
+        }
+        return code;
     }
-    if (subcommand === "action-log") {
-        return runKnActionLogCommand(rest);
+    catch (error) {
+        // Auto-retry on 401: force-refresh the token and re-run the subcommand.
+        // The subcommand will call ensureValidToken() again and pick up the fresh token.
+        if (error instanceof HttpError && error.status === 401) {
+            try {
+                await ensureValidToken({ forceRefresh: true });
+                return await dispatch();
+            }
+            catch (retryError) {
+                console.error(formatHttpError(retryError));
+                return 1;
+            }
+        }
+        console.error(formatHttpError(error));
+        return 1;
     }
-    console.error(`Unknown bkn subcommand: ${subcommand}`);
-    return 1;
 }
 /** Parse object-type create args: --name --dataview-id --primary-key --display-key [--property '<json>' ...] */
 function parseObjectTypeCreateArgs(args) {
@@ -531,7 +657,7 @@ function parseObjectTypeCreateArgs(args) {
     let dataviewId = "";
     let primaryKey = "";
     let displayKey = "";
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let branch = "main";
     let pretty = true;
     const properties = [];
@@ -597,13 +723,15 @@ function parseObjectTypeCreateArgs(args) {
         }));
     }
     const body = JSON.stringify({ entries: [entry], branch });
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, body, businessDomain, branch, pretty };
 }
 /** Parse object-type update args: --name X [--display-key Y] */
 function parseObjectTypeUpdateArgs(args) {
     let name;
     let displayKey;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let pretty = true;
     const positional = [];
     for (let i = 0; i < args.length; i += 1) {
@@ -641,11 +769,13 @@ function parseObjectTypeUpdateArgs(args) {
     if (Object.keys(payload).length === 0) {
         throw new Error("No update fields. Use --name or --display-key.");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, otId, body: JSON.stringify(payload), businessDomain, pretty };
 }
 /** Parse object-type delete args: <kn-id> <ot-ids> [-y] */
 function parseObjectTypeDeleteArgs(args) {
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let yes = false;
     const positional = [];
     for (let i = 0; i < args.length; i += 1) {
@@ -667,12 +797,14 @@ function parseObjectTypeDeleteArgs(args) {
     if (!knId || !otIds) {
         throw new Error("Usage: kweaver bkn object-type delete <kn-id> <ot-ids> [-y]");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, otIds, businessDomain, yes };
 }
 /** Parse common flags for ontology-query subcommands; returns { filteredArgs, pretty, businessDomain } */
 function parseOntologyQueryFlags(args) {
     let pretty = true;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     const filteredArgs = [];
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
@@ -690,11 +822,13 @@ function parseOntologyQueryFlags(args) {
         }
         filteredArgs.push(arg);
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { filteredArgs, pretty, businessDomain };
 }
 export function parseKnActionTypeExecuteArgs(args) {
     let pretty = true;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let wait = true;
     let timeout = 300;
     const positional = [];
@@ -733,6 +867,8 @@ export function parseKnActionTypeExecuteArgs(args) {
     if (!knId || !atId || !body) {
         throw new Error("Missing kn-id, at-id, or body. Usage: kweaver bkn action-type execute <kn-id> <at-id> '<json>' [options]");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return {
         knId,
         atId,
@@ -791,7 +927,9 @@ kweaver bkn object-type properties <kn-id> <ot-id> '<json>' [--pretty] [-bd valu
 list: List object types (schema) from ontology-manager.
 get: Get single object type details.
 create/update/delete: Schema CRUD (create requires dataview-id).
-query/properties: Query via ontology-query API. For query, --limit and --search-after are merged into the JSON body.`);
+query/properties: Query via ontology-query API. For query, --limit and --search-after are merged into the JSON body.
+
+properties JSON format: {"_instance_identities":[{"<primary-key>":"<value>"}],"properties":["prop1","prop2"]}`);
         return 0;
     }
     try {
@@ -896,7 +1034,8 @@ query/properties: Query via ontology-query API. For query, --limit and --search-
             const parsed = parseOntologyQueryFlags(rest);
             const [knId, otId, body] = parsed.filteredArgs;
             if (!knId || !otId || !body) {
-                console.error("Usage: kweaver bkn object-type properties <kn-id> <ot-id> '<json>' [options]");
+                console.error(`Usage: kweaver bkn object-type properties <kn-id> <ot-id> '<json>' [options]
+JSON: {"_instance_identities":[{"<primary-key>":"<value>"}],"properties":["prop1","prop2"]}`);
                 return 1;
             }
             const token = await ensureValidToken();
@@ -930,7 +1069,7 @@ function parseRelationTypeCreateArgs(args) {
     let name = "";
     let source = "";
     let target = "";
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let branch = "main";
     let pretty = true;
     const mappings = [];
@@ -990,12 +1129,14 @@ function parseRelationTypeCreateArgs(args) {
         })),
     };
     const body = JSON.stringify({ entries: [entry], branch });
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, body, businessDomain, branch, pretty };
 }
 /** Parse relation-type update args: [--name X] */
 function parseRelationTypeUpdateArgs(args) {
     let name;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let pretty = true;
     const positional = [];
     for (let i = 0; i < args.length; i += 1) {
@@ -1024,11 +1165,13 @@ function parseRelationTypeUpdateArgs(args) {
     if (name === undefined) {
         throw new Error("No update fields. Use --name.");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, rtId, body: JSON.stringify({ name }), businessDomain, pretty };
 }
 /** Parse relation-type delete args: <kn-id> <rt-ids> [-y] */
 function parseRelationTypeDeleteArgs(args) {
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let yes = false;
     const positional = [];
     for (let i = 0; i < args.length; i += 1) {
@@ -1050,6 +1193,8 @@ function parseRelationTypeDeleteArgs(args) {
     if (!knId || !rtIds) {
         throw new Error("Usage: kweaver bkn relation-type delete <kn-id> <rt-ids> [-y]");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, rtIds, businessDomain, yes };
 }
 async function runKnRelationTypeCommand(args) {
@@ -1189,6 +1334,17 @@ Query subgraph via ontology-query API. JSON body format see references/json-form
         return 1;
     }
     try {
+        // Auto-detect query_type=relation_path when body contains source_object_type_id
+        let queryType;
+        try {
+            const parsedBody = JSON.parse(body);
+            if (parsedBody.source_object_type_id) {
+                queryType = "relation_path";
+            }
+        }
+        catch {
+            // Not valid JSON — let the API return the error
+        }
         const token = await ensureValidToken();
         const result = await subgraph({
             baseUrl: token.baseUrl,
@@ -1196,6 +1352,7 @@ Query subgraph via ontology-query API. JSON body format see references/json-form
             knId,
             body,
             businessDomain,
+            queryType,
         });
         console.log(formatCallOutput(result, pretty));
         return 0;
@@ -1414,7 +1571,7 @@ Options for list: --limit, --need-total, --action-type-id, --status, --trigger-t
         return 0;
     }
     let pretty = true;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let limit;
     let needTotal;
     let actionTypeId;
@@ -1468,6 +1625,8 @@ Options for list: --limit, --need-total, --action-type-id, --status, --trigger-t
         }
         filteredArgs.push(arg);
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     try {
         const token = await ensureValidToken();
         const base = {
@@ -1707,7 +1866,7 @@ function parseKnCreateFromDsArgs(args) {
     let tablesStr = "";
     let build = true;
     let timeout = 300;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     let pretty = true;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
@@ -1751,6 +1910,8 @@ function parseKnCreateFromDsArgs(args) {
     if (!dsId || !name) {
         throw new Error("Usage: kweaver bkn create-from-ds <ds-id> --name X [options]");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { dsId, name, tables, build, timeout, businessDomain, pretty };
 }
 async function runKnCreateFromDsCommand(args) {
@@ -1956,7 +2117,7 @@ export function parseKnBuildArgs(args) {
     let knId = "";
     let wait = true;
     let timeout = 300;
-    let businessDomain = "bd_public";
+    let businessDomain = "";
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h")
@@ -1988,6 +2149,8 @@ export function parseKnBuildArgs(args) {
     if (!knId) {
         throw new Error("Missing kn-id. Usage: kweaver bkn build <kn-id> [options]");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, wait, timeout, businessDomain };
 }
 async function runKnBuildCommand(args) {
@@ -2048,6 +2211,193 @@ async function runKnBuildCommand(args) {
         return 1;
     }
 }
+// ── push / pull (BKN tar import/export) ──────────────────────────────────────
+export function packDirectoryToTar(dirPath) {
+    const absPath = resolve(dirPath);
+    const entries = readdirSync(absPath);
+    const args = ["cf", "-", "-C", absPath, ...entries];
+    const result = spawnSync("tar", args, {
+        encoding: "buffer",
+        env: { ...process.env, COPYFILE_DISABLE: "1" },
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        throw new Error(`tar pack failed: ${result.stderr?.toString() ?? result.status}`);
+    }
+    return result.stdout;
+}
+export function extractTarToDirectory(tarBuffer, dirPath) {
+    const absPath = resolve(dirPath);
+    mkdirSync(absPath, { recursive: true });
+    const result = spawnSync("tar", ["xf", "-", "-C", absPath], {
+        input: tarBuffer,
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        throw new Error(`tar extract failed: ${result.stderr?.toString() ?? result.status}`);
+    }
+}
+const KN_PUSH_HELP = `kweaver bkn push <directory> [options]
+
+Pack a BKN directory into a tar and upload to import as a knowledge network.
+
+Options:
+  --branch <s>       Branch name (default: main)
+  -bd, --biz-domain  Business domain (default: bd_public)
+  --pretty           Pretty-print JSON output`;
+const KN_PULL_HELP = `kweaver bkn pull <kn-id> [<directory>] [options]
+
+Download a BKN tar from a knowledge network and extract to a local directory.
+
+Options:
+  <directory>        Output directory (default: <kn-id>)
+  --branch <s>       Branch name (default: main)
+  -bd, --biz-domain  Business domain (default: bd_public)`;
+async function runKnValidateCommand(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log("Usage: kweaver bkn validate <directory>\n\nValidate a local BKN directory without uploading.");
+        return 0;
+    }
+    const directory = args.find((a) => !a.startsWith("-"));
+    if (!directory) {
+        console.error("Missing directory. Usage: kweaver bkn validate <directory>");
+        return 1;
+    }
+    const absDir = resolve(directory);
+    try {
+        const stat = statSync(absDir);
+        if (!stat.isDirectory()) {
+            console.error(`Not a directory: ${directory}`);
+            return 1;
+        }
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            console.error(`Directory not found: ${directory}`);
+            return 1;
+        }
+        throw err;
+    }
+    try {
+        const network = await loadNetwork(absDir);
+        const result = validateNetwork(network);
+        if (!result.ok) {
+            for (const e of result.errors)
+                console.error(`  - ${e}`);
+            console.error(`BKN validation failed: ${result.errors.length} error(s)`);
+            return 1;
+        }
+        const objs = allObjects(network);
+        const rels = allRelations(network);
+        const acts = allActions(network);
+        console.log(`Valid: ${objs.length} object types, ${rels.length} relation types, ${acts.length} action types`);
+        return 0;
+    }
+    catch (error) {
+        console.error(`BKN validation failed: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+async function runKnPushCommand(args) {
+    let options;
+    try {
+        options = parseKnPushArgs(args);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(KN_PUSH_HELP);
+            return 0;
+        }
+        console.error(formatHttpError(error));
+        return 1;
+    }
+    const absDir = resolve(options.directory);
+    try {
+        const stat = statSync(absDir);
+        if (!stat.isDirectory()) {
+            console.error(`Not a directory: ${options.directory}`);
+            return 1;
+        }
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            console.error(`Directory not found: ${options.directory}`);
+            return 1;
+        }
+        throw err;
+    }
+    try {
+        const network = await loadNetwork(absDir);
+        const objs = allObjects(network);
+        const rels = allRelations(network);
+        const acts = allActions(network);
+        console.error(`Validated: ${objs.length} object types, ${rels.length} relation types, ${acts.length} action types`);
+    }
+    catch (error) {
+        console.error(`BKN validation failed: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+    try {
+        await generateChecksum(absDir);
+        console.error("Checksum generated");
+    }
+    catch (error) {
+        console.error(`Checksum generation failed: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+    try {
+        const tarBuffer = packDirectoryToTar(absDir);
+        const token = await ensureValidToken();
+        const body = await uploadBkn({
+            baseUrl: token.baseUrl,
+            accessToken: token.accessToken,
+            tarBuffer,
+            businessDomain: options.businessDomain,
+            branch: options.branch,
+        });
+        console.log(formatCallOutput(body, options.pretty));
+        return 0;
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        return 1;
+    }
+}
+async function runKnPullCommand(args) {
+    let options;
+    try {
+        options = parseKnPullArgs(args);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(KN_PULL_HELP);
+            return 0;
+        }
+        console.error(formatHttpError(error));
+        return 1;
+    }
+    try {
+        const token = await ensureValidToken();
+        const tarBuffer = await downloadBkn({
+            baseUrl: token.baseUrl,
+            accessToken: token.accessToken,
+            knId: options.knId,
+            businessDomain: options.businessDomain,
+            branch: options.branch,
+        });
+        const absDir = resolve(options.directory);
+        extractTarToDirectory(tarBuffer, absDir);
+        console.log(`Extracted to ${absDir}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        return 1;
+    }
+}
 // ── search ──────────────────────────────────────────────────────────────────
 const KN_SEARCH_HELP = `kweaver bkn search <kn-id> <query> [--max-concepts <n>] [--mode <mode>] [--pretty] [-bd value]
 
@@ -2065,7 +2415,7 @@ export function parseKnSearchArgs(args) {
     let maxConcepts = 10;
     let mode = "keyword_vector_retrieval";
     let pretty = false;
-    let businessDomain = process.env.KWEAVER_BUSINESS_DOMAIN ?? "bd_public";
+    let businessDomain = process.env.KWEAVER_BUSINESS_DOMAIN ?? "";
     const positional = [];
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -2096,6 +2446,8 @@ export function parseKnSearchArgs(args) {
     if (!knId || !query) {
         throw new Error("Usage: kweaver bkn search <kn-id> <query> [options]");
     }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
     return { knId, query, maxConcepts, mode, pretty, businessDomain };
 }
 async function runKnSearchCommand(args) {