@kweaver-ai/kweaver-sdk 0.4.0 → 0.4.2

package/dist/commands/bkn.js

@@ -1,9 +1,15 @@
 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 } from "@kweaver-ai/bkn";
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
-import { listKnowledgeNetworks, getKnowledgeNetwork, createKnowledgeNetwork, updateKnowledgeNetwork, deleteKnowledgeNetwork, listObjectTypes, listRelationTypes, listActionTypes, } from "../api/knowledge-networks.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";
 export function formatSimpleKnList(text, pretty, includeDetail = false) {
     const parsed = JSON.parse(text);
@@ -336,6 +342,92 @@ export function parseKnDeleteArgs(args) {
     }
     return { knId, businessDomain, yes };
 }
+export function parseKnPushArgs(args) {
+    let directory = "";
+    let branch = "main";
+    let businessDomain = "bd_public";
+    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]");
+    }
+    return { directory, branch, businessDomain, pretty };
+}
+export function parseKnPullArgs(args) {
+    let knId = "";
+    let directory = "";
+    let branch = "main";
+    let businessDomain = "bd_public";
+    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]");
+    }
+    return { knId, directory: directory || knId, branch, businessDomain };
+}
 function parseJsonObject(text, errorMessage) {
     let parsed;
     try {
@@ -436,16 +528,28 @@ const KN_HELP = `kweaver bkn
 Subcommands:
   list [options]       List business knowledge networks
   get <kn-id> [options]   Get knowledge network detail (use --stats or --export)
-  create [options]     Create a knowledge network
+  create [options]     Create a knowledge network (empty or from --body-file)
+  create-from-ds <ds-id> --name X [--tables a,b] [--build]   Create KN from datasource
   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
+  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
   object-type list <kn-id>   List object types (schema)
+  object-type get <kn-id> <ot-id>   Get object type details
+  object-type create <kn-id> [options]   Create object type (--name --dataview-id --primary-key --display-key)
+  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])
+  relation-type update <kn-id> <rt-id> [options]   Update relation type
+  relation-type delete <kn-id> <rt-ids> [-y]   Delete relation type(s)
   subgraph <kn-id> '<json>'   Query subgraph
   action-type list <kn-id>   List action types (schema)
   action-type query <kn-id> <at-id> '<json>'   Query action info
@@ -471,12 +575,24 @@ export async function runKnCommand(args) {
     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 === "push") {
+        return runKnPushCommand(rest);
+    }
+    if (subcommand === "pull") {
+        return runKnPullCommand(rest);
+    }
     if (subcommand === "export") {
         return runKnGetCommand([...(rest[0] ? [rest[0]] : []), "--export", ...rest.slice(1)]);
     }
@@ -507,6 +623,150 @@ export async function runKnCommand(args) {
     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) {
+    let name = "";
+    let dataviewId = "";
+    let primaryKey = "";
+    let displayKey = "";
+    let businessDomain = "bd_public";
+    let branch = "main";
+    let pretty = true;
+    const properties = [];
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h")
+            throw new Error("help");
+        if (arg === "--name" && args[i + 1]) {
+            name = args[++i];
+            continue;
+        }
+        if (arg === "--dataview-id" && args[i + 1]) {
+            dataviewId = args[++i];
+            continue;
+        }
+        if (arg === "--primary-key" && args[i + 1]) {
+            primaryKey = args[++i];
+            continue;
+        }
+        if (arg === "--display-key" && args[i + 1]) {
+            displayKey = args[++i];
+            continue;
+        }
+        if (arg === "--property" && args[i + 1]) {
+            properties.push(args[++i]);
+            continue;
+        }
+        if ((arg === "-bd" || arg === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[++i];
+            continue;
+        }
+        if (arg === "--branch" && args[i + 1]) {
+            branch = args[++i];
+            continue;
+        }
+        if (arg === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if (!arg.startsWith("-"))
+            positional.push(arg);
+    }
+    const knId = positional[0];
+    if (!knId || !name || !dataviewId || !primaryKey || !displayKey) {
+        throw new Error("Usage: kweaver bkn object-type create <kn-id> --name X --dataview-id Y --primary-key Z --display-key W");
+    }
+    const entry = {
+        name,
+        data_source: { type: "data_view", id: dataviewId },
+        primary_keys: [primaryKey],
+        display_key: displayKey,
+    };
+    if (properties.length > 0) {
+        entry.data_properties = properties.map((p) => JSON.parse(p));
+    }
+    else {
+        const autoProps = new Set([primaryKey, displayKey]);
+        entry.data_properties = Array.from(autoProps).map((n) => ({
+            name: n,
+            display_name: n,
+            type: "string",
+        }));
+    }
+    const body = JSON.stringify({ entries: [entry], branch });
+    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 pretty = true;
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h")
+            throw new Error("help");
+        if (arg === "--name" && args[i + 1]) {
+            name = args[++i];
+            continue;
+        }
+        if (arg === "--display-key" && args[i + 1]) {
+            displayKey = args[++i];
+            continue;
+        }
+        if ((arg === "-bd" || arg === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[++i];
+            continue;
+        }
+        if (arg === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if (!arg.startsWith("-"))
+            positional.push(arg);
+    }
+    const [knId, otId] = positional;
+    if (!knId || !otId) {
+        throw new Error("Usage: kweaver bkn object-type update <kn-id> <ot-id> [--name X] [--display-key Y]");
+    }
+    const payload = {};
+    if (name !== undefined)
+        payload.name = name;
+    if (displayKey !== undefined)
+        payload.display_key = displayKey;
+    if (Object.keys(payload).length === 0) {
+        throw new Error("No update fields. Use --name or --display-key.");
+    }
+    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 yes = false;
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h")
+            throw new Error("help");
+        if (arg === "--yes" || arg === "-y") {
+            yes = true;
+            continue;
+        }
+        if ((arg === "-bd" || arg === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[++i];
+            continue;
+        }
+        if (!arg.startsWith("-"))
+            positional.push(arg);
+    }
+    const [knId, otIds] = positional;
+    if (!knId || !otIds) {
+        throw new Error("Usage: kweaver bkn object-type delete <kn-id> <ot-ids> [-y]");
+    }
+    return { knId, otIds, businessDomain, yes };
+}
 /** Parse common flags for ontology-query subcommands; returns { filteredArgs, pretty, businessDomain } */
 function parseOntologyQueryFlags(args) {
     let pretty = true;
@@ -581,18 +841,126 @@ export function parseKnActionTypeExecuteArgs(args) {
         timeout,
     };
 }
+const PK_CANDIDATES = new Set(["id", "pk", "key"]);
+const PK_TYPES = new Set(["integer", "unsigned integer", "string", "varchar", "bigint", "int"]);
+const DISPLAY_HINTS = ["name", "title", "label", "display_name", "description"];
+function detectPrimaryKey(table) {
+    for (const col of table.columns) {
+        if (PK_CANDIDATES.has(col.name.toLowerCase()) && PK_TYPES.has(col.type.toLowerCase())) {
+            return col.name;
+        }
+    }
+    for (const col of table.columns) {
+        if (PK_TYPES.has(col.type.toLowerCase())) {
+            return col.name;
+        }
+    }
+    return table.columns[0]?.name ?? "id";
+}
+function detectDisplayKey(table, primaryKey) {
+    for (const col of table.columns) {
+        if (DISPLAY_HINTS.some((h) => col.name.toLowerCase().includes(h))) {
+            return col.name;
+        }
+    }
+    return primaryKey;
+}
+function confirmYes(prompt) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(`${prompt} [y/N] `, (answer) => {
+            rl.close();
+            const trimmed = answer.trim().toLowerCase();
+            resolve(trimmed === "y" || trimmed === "yes");
+        });
+    });
+}
 async function runKnObjectTypeCommand(args) {
     const [action, ...rest] = args;
     if (!action || action === "--help" || action === "-h") {
         console.log(`kweaver bkn object-type list <kn-id> [--pretty] [-bd value]
+kweaver bkn object-type get <kn-id> <ot-id> [--pretty] [-bd value]
+kweaver bkn object-type create <kn-id> --name X --dataview-id Y --primary-key Z --display-key W [--property '<json>' ...]
+kweaver bkn object-type update <kn-id> <ot-id> [--name X] [--display-key Y]
+kweaver bkn object-type delete <kn-id> <ot-ids> [-y]
 kweaver bkn object-type query <kn-id> <ot-id> ['<json>'] [--limit <n>] [--search-after '<json-array>'] [--pretty] [-bd value]
 kweaver bkn object-type properties <kn-id> <ot-id> '<json>' [--pretty] [-bd value]
 
 list: List object types (schema) from ontology-manager.
-query/properties: Query via ontology-query API. For query, --limit and --search-after are merged into the JSON body.`);
+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.
+
+properties JSON format: {"_instance_identities":[{"<primary-key>":"<value>"}],"properties":["prop1","prop2"]}`);
         return 0;
     }
     try {
+        if (action === "get") {
+            const parsed = parseOntologyQueryFlags(rest);
+            const [knId, otId] = parsed.filteredArgs;
+            if (!knId || !otId) {
+                console.error("Usage: kweaver bkn object-type get <kn-id> <ot-id> [options]");
+                return 1;
+            }
+            const token = await ensureValidToken();
+            const body = await getObjectType({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId,
+                otId,
+                businessDomain: parsed.businessDomain,
+            });
+            console.log(formatCallOutput(body, parsed.pretty));
+            return 0;
+        }
+        if (action === "create") {
+            const opts = parseObjectTypeCreateArgs(rest);
+            const token = await ensureValidToken();
+            const body = await createObjectTypes({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId: opts.knId,
+                body: opts.body,
+                businessDomain: opts.businessDomain,
+                branch: opts.branch,
+            });
+            console.log(formatCallOutput(body, opts.pretty));
+            return 0;
+        }
+        if (action === "update") {
+            const opts = parseObjectTypeUpdateArgs(rest);
+            const token = await ensureValidToken();
+            const body = await updateObjectType({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId: opts.knId,
+                otId: opts.otId,
+                body: opts.body,
+                businessDomain: opts.businessDomain,
+            });
+            console.log(formatCallOutput(body, opts.pretty));
+            return 0;
+        }
+        if (action === "delete") {
+            const opts = parseObjectTypeDeleteArgs(rest);
+            if (!opts.yes) {
+                const confirmed = await confirmYes(`Delete object type(s) ${opts.otIds}?`);
+                if (!confirmed) {
+                    console.error("Aborted.");
+                    return 1;
+                }
+            }
+            const token = await ensureValidToken();
+            await deleteObjectTypes({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId: opts.knId,
+                otIds: opts.otIds,
+                businessDomain: opts.businessDomain,
+            });
+            console.log(`Deleted ${opts.otIds}`);
+            return 0;
+        }
         if (action === "list") {
             const parsed = parseOntologyQueryFlags(rest);
             const [knId] = parsed.filteredArgs;
@@ -628,7 +996,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();
@@ -643,44 +1012,255 @@ query/properties: Query via ontology-query API. For query, --limit and --search-
             console.log(formatCallOutput(result, parsed.pretty));
             return 0;
         }
-        console.error(`Unknown object-type action: ${action}. Use list, query, or properties.`);
+        console.error(`Unknown object-type action: ${action}. Use list, get, create, update, delete, query, or properties.`);
+        return 1;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(`kweaver bkn object-type create <kn-id> --name X --dataview-id Y --primary-key Z --display-key W [--property '<json>' ...]
+kweaver bkn object-type update <kn-id> <ot-id> [--name X] [--display-key Y]
+kweaver bkn object-type delete <kn-id> <ot-ids> [-y]`);
+            return 0;
+        }
+        console.error(formatHttpError(error));
+        return 1;
+    }
+}
+/** Parse relation-type create args: --name --source --target [--mapping src:tgt ...] */
+function parseRelationTypeCreateArgs(args) {
+    let name = "";
+    let source = "";
+    let target = "";
+    let businessDomain = "bd_public";
+    let branch = "main";
+    let pretty = true;
+    const mappings = [];
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h")
+            throw new Error("help");
+        if (arg === "--name" && args[i + 1]) {
+            name = args[++i];
+            continue;
+        }
+        if (arg === "--source" && args[i + 1]) {
+            source = args[++i];
+            continue;
+        }
+        if (arg === "--target" && args[i + 1]) {
+            target = args[++i];
+            continue;
+        }
+        if (arg === "--mapping" && args[i + 1]) {
+            const m = args[++i];
+            if (!m.includes(":")) {
+                throw new Error(`Invalid mapping format '${m}'. Expected source_prop:target_prop.`);
+            }
+            const [s, t] = m.split(":", 2);
+            mappings.push([s, t]);
+            continue;
+        }
+        if ((arg === "-bd" || arg === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[++i];
+            continue;
+        }
+        if (arg === "--branch" && args[i + 1]) {
+            branch = args[++i];
+            continue;
+        }
+        if (arg === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if (!arg.startsWith("-"))
+            positional.push(arg);
+    }
+    const knId = positional[0];
+    if (!knId || !name || !source || !target) {
+        throw new Error("Usage: kweaver bkn relation-type create <kn-id> --name X --source <ot-id> --target <ot-id> [--mapping src:tgt ...]");
+    }
+    const entry = {
+        name,
+        source_object_type_id: source,
+        target_object_type_id: target,
+        type: "direct",
+        mapping_rules: mappings.map(([s, t]) => ({
+            source_property: { name: s },
+            target_property: { name: t },
+        })),
+    };
+    const body = JSON.stringify({ entries: [entry], branch });
+    return { knId, body, businessDomain, branch, pretty };
+}
+/** Parse relation-type update args: [--name X] */
+function parseRelationTypeUpdateArgs(args) {
+    let name;
+    let businessDomain = "bd_public";
+    let pretty = true;
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h")
+            throw new Error("help");
+        if (arg === "--name" && args[i + 1]) {
+            name = args[++i];
+            continue;
+        }
+        if ((arg === "-bd" || arg === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[++i];
+            continue;
+        }
+        if (arg === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if (!arg.startsWith("-"))
+            positional.push(arg);
+    }
+    const [knId, rtId] = positional;
+    if (!knId || !rtId) {
+        throw new Error("Usage: kweaver bkn relation-type update <kn-id> <rt-id> [--name X]");
+    }
+    if (name === undefined) {
+        throw new Error("No update fields. Use --name.");
+    }
+    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 yes = false;
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h")
+            throw new Error("help");
+        if (arg === "--yes" || arg === "-y") {
+            yes = true;
+            continue;
+        }
+        if ((arg === "-bd" || arg === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[++i];
+            continue;
+        }
+        if (!arg.startsWith("-"))
+            positional.push(arg);
+    }
+    const [knId, rtIds] = positional;
+    if (!knId || !rtIds) {
+        throw new Error("Usage: kweaver bkn relation-type delete <kn-id> <rt-ids> [-y]");
+    }
+    return { knId, rtIds, businessDomain, yes };
+}
+async function runKnRelationTypeCommand(args) {
+    const [action, ...rest] = args;
+    if (!action || action === "--help" || action === "-h") {
+        console.log(`kweaver bkn relation-type list <kn-id> [--pretty] [-bd value]
+kweaver bkn relation-type get <kn-id> <rt-id> [--pretty] [-bd value]
+kweaver bkn relation-type create <kn-id> --name X --source <ot-id> --target <ot-id> [--mapping src:tgt ...]
+kweaver bkn relation-type update <kn-id> <rt-id> [--name X]
+kweaver bkn relation-type delete <kn-id> <rt-ids> [-y]
+
+list: List relation types (schema) from ontology-manager.
+get: Get single relation type details.
+create/update/delete: Schema CRUD.`);
+        return 0;
+    }
+    try {
+        if (action === "get") {
+            const parsed = parseOntologyQueryFlags(rest);
+            const [knId, rtId] = parsed.filteredArgs;
+            if (!knId || !rtId) {
+                console.error("Usage: kweaver bkn relation-type get <kn-id> <rt-id> [options]");
+                return 1;
+            }
+            const token = await ensureValidToken();
+            const body = await getRelationType({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId,
+                rtId,
+                businessDomain: parsed.businessDomain,
+            });
+            console.log(formatCallOutput(body, parsed.pretty));
+            return 0;
+        }
+        if (action === "create") {
+            const opts = parseRelationTypeCreateArgs(rest);
+            const token = await ensureValidToken();
+            const body = await createRelationTypes({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId: opts.knId,
+                body: opts.body,
+                businessDomain: opts.businessDomain,
+                branch: opts.branch,
+            });
+            console.log(formatCallOutput(body, opts.pretty));
+            return 0;
+        }
+        if (action === "update") {
+            const opts = parseRelationTypeUpdateArgs(rest);
+            const token = await ensureValidToken();
+            const body = await updateRelationType({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId: opts.knId,
+                rtId: opts.rtId,
+                body: opts.body,
+                businessDomain: opts.businessDomain,
+            });
+            console.log(formatCallOutput(body, opts.pretty));
+            return 0;
+        }
+        if (action === "delete") {
+            const opts = parseRelationTypeDeleteArgs(rest);
+            if (!opts.yes) {
+                const confirmed = await confirmYes(`Delete relation type(s) ${opts.rtIds}?`);
+                if (!confirmed) {
+                    console.error("Aborted.");
+                    return 1;
+                }
+            }
+            const token = await ensureValidToken();
+            await deleteRelationTypes({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId: opts.knId,
+                rtIds: opts.rtIds,
+                businessDomain: opts.businessDomain,
+            });
+            console.log(`Deleted ${opts.rtIds}`);
+            return 0;
+        }
+        if (action === "list") {
+            const parsed = parseOntologyQueryFlags(rest);
+            const [knId] = parsed.filteredArgs;
+            if (!knId) {
+                console.error("Usage: kweaver bkn relation-type list <kn-id> [options]");
+                return 1;
+            }
+            const token = await ensureValidToken();
+            const body = await listRelationTypes({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId,
+                businessDomain: parsed.businessDomain,
+            });
+            console.log(formatCallOutput(body, parsed.pretty));
+            return 0;
+        }
+        console.error(`Unknown relation-type action: ${action}. Use list, get, create, update, or delete.`);
         return 1;
     }
     catch (error) {
-        console.error(formatHttpError(error));
-        return 1;
-    }
-}
-async function runKnRelationTypeCommand(args) {
-    const [action, ...rest] = args;
-    if (!action || action === "--help" || action === "-h") {
-        console.log(`kweaver bkn relation-type list <kn-id> [--pretty] [-bd value]
-
-List relation types (schema) from ontology-manager.`);
-        return 0;
-    }
-    if (action !== "list") {
-        console.error(`Unknown relation-type action: ${action}. Use list.`);
-        return 1;
-    }
-    try {
-        const parsed = parseOntologyQueryFlags(rest);
-        const [knId] = parsed.filteredArgs;
-        if (!knId) {
-            console.error("Usage: kweaver bkn relation-type list <kn-id> [options]");
-            return 1;
+        if (error instanceof Error && error.message === "help") {
+            console.log(`kweaver bkn relation-type create <kn-id> --name X --source <ot-id> --target <ot-id> [--mapping src:tgt ...]
+kweaver bkn relation-type update <kn-id> <rt-id> [--name X]
+kweaver bkn relation-type delete <kn-id> <rt-ids> [-y]`);
+            return 0;
         }
-        const token = await ensureValidToken();
-        const body = await listRelationTypes({
-            baseUrl: token.baseUrl,
-            accessToken: token.accessToken,
-            knId,
-            businessDomain: parsed.businessDomain,
-        });
-        console.log(formatCallOutput(body, parsed.pretty));
-        return 0;
-    }
-    catch (error) {
         console.error(formatHttpError(error));
         return 1;
     }
@@ -699,7 +1279,7 @@ async function runKnSubgraphCommand(args) {
         if (error instanceof Error && error.message === "help") {
             console.log(`kweaver bkn subgraph <kn-id> '<json>' [--pretty] [-bd value]
 
-Query subgraph via ontology-query API. JSON body format see ref/ontology/ontology-query.yaml.`);
+Query subgraph via ontology-query API. JSON body format see references/json-formats.md#subgraph.`);
             return 0;
         }
         throw error;
@@ -710,6 +1290,17 @@ Query subgraph via ontology-query API. JSON body format see ref/ontology/ontolog
         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,
@@ -717,6 +1308,7 @@ Query subgraph via ontology-query API. JSON body format see ref/ontology/ontolog
             knId,
             body,
             businessDomain,
+            queryType,
         });
         console.log(formatCallOutput(result, pretty));
         return 0;
@@ -1210,6 +1802,183 @@ async function runKnCreateCommand(args) {
         return 1;
     }
 }
+const KN_CREATE_FROM_DS_HELP = `kweaver bkn create-from-ds <ds-id> --name X [options]
+
+Create a knowledge network from a datasource (dataviews + object types + optional build).
+
+Options:
+  --name <s>       Knowledge network name (required)
+  --tables <a,b>   Comma-separated table names (default: all)
+  --build (default)  Build after creation
+  --no-build       Skip build after creation
+  --timeout <n>    Build timeout in seconds (default: 300)
+  -bd, --biz-domain  Business domain (default: bd_public)
+  --pretty         Pretty-print output (default)`;
+function parseKnCreateFromDsArgs(args) {
+    let dsId = "";
+    let name = "";
+    let tablesStr = "";
+    let build = true;
+    let timeout = 300;
+    let businessDomain = "bd_public";
+    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 === "--name" && args[i + 1]) {
+            name = args[++i];
+            continue;
+        }
+        if (arg === "--tables" && args[i + 1]) {
+            tablesStr = args[++i];
+            continue;
+        }
+        if (arg === "--build") {
+            build = true;
+            continue;
+        }
+        if (arg === "--no-build") {
+            build = false;
+            continue;
+        }
+        if (arg === "--timeout" && args[i + 1]) {
+            timeout = parseInt(args[++i], 10);
+            if (Number.isNaN(timeout) || timeout < 1)
+                timeout = 300;
+            continue;
+        }
+        if ((arg === "-bd" || arg === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[++i];
+            continue;
+        }
+        if (arg === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if (!arg.startsWith("-") && !dsId) {
+            dsId = arg;
+        }
+    }
+    const tables = tablesStr ? tablesStr.split(",").map((s) => s.trim()).filter(Boolean) : [];
+    if (!dsId || !name) {
+        throw new Error("Usage: kweaver bkn create-from-ds <ds-id> --name X [options]");
+    }
+    return { dsId, name, tables, build, timeout, businessDomain, pretty };
+}
+async function runKnCreateFromDsCommand(args) {
+    let options;
+    try {
+        options = parseKnCreateFromDsArgs(args);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(KN_CREATE_FROM_DS_HELP);
+            return 0;
+        }
+        console.error(formatHttpError(error));
+        return 1;
+    }
+    try {
+        const token = await ensureValidToken();
+        const base = {
+            baseUrl: token.baseUrl,
+            accessToken: token.accessToken,
+            businessDomain: options.businessDomain,
+        };
+        const tablesBody = await listTablesWithColumns({ ...base, id: options.dsId });
+        const allTables = JSON.parse(tablesBody);
+        const targetTables = options.tables.length > 0
+            ? allTables.filter((t) => options.tables.includes(t.name))
+            : allTables;
+        if (targetTables.length === 0) {
+            console.error("No tables available");
+            return 1;
+        }
+        const viewMap = {};
+        for (const t of targetTables) {
+            const dvId = await createDataView({
+                ...base,
+                name: t.name,
+                datasourceId: options.dsId,
+                table: t.name,
+                fields: t.columns.map((c) => ({ name: c.name, type: c.type })),
+            });
+            viewMap[t.name] = dvId;
+        }
+        const knBody = JSON.stringify({
+            name: options.name,
+            branch: "main",
+            base_branch: "",
+        });
+        const knResponse = await createKnowledgeNetwork({
+            ...base,
+            body: knBody,
+        });
+        const knParsed = JSON.parse(knResponse);
+        const knItem = Array.isArray(knParsed) ? knParsed[0] : knParsed;
+        const knId = String(knItem?.id ?? "");
+        const otResults = [];
+        for (const t of targetTables) {
+            const pk = detectPrimaryKey(t);
+            const dk = detectDisplayKey(t, pk);
+            const entry = {
+                name: t.name,
+                data_source: { type: "data_view", id: viewMap[t.name] },
+                primary_keys: [pk],
+                display_key: dk,
+                data_properties: [pk, dk].filter((x, i, a) => a.indexOf(x) === i).map((n) => ({
+                    name: n,
+                    display_name: n,
+                    type: "string",
+                })),
+            };
+            const otBody = JSON.stringify({ entries: [entry], branch: "main" });
+            const otResponse = await createObjectTypes({
+                ...base,
+                knId,
+                body: otBody,
+            });
+            const otParsed = JSON.parse(otResponse);
+            const otItem = otParsed.entries?.[0];
+            otResults.push({
+                name: t.name,
+                id: otItem?.id ?? "",
+                field_count: t.columns.length,
+            });
+        }
+        let statusStr = "skipped";
+        if (options.build) {
+            console.error("Building ...");
+            await buildKnowledgeNetwork({ ...base, knId });
+            const deadline = Date.now() + options.timeout * 1000;
+            const TERMINAL = ["completed", "failed", "success"];
+            while (Date.now() < deadline) {
+                await new Promise((r) => setTimeout(r, 2000));
+                const statusBody = await getBuildStatus({ ...base, knId });
+                const statusParsed = JSON.parse(statusBody);
+                const jobs = Array.isArray(statusParsed) ? statusParsed : (statusParsed.entries ?? []);
+                const state = (jobs[0]?.state ?? "running").toLowerCase();
+                if (TERMINAL.includes(state)) {
+                    statusStr = state;
+                    break;
+                }
+            }
+        }
+        const output = {
+            kn_id: knId,
+            kn_name: options.name,
+            object_types: otResults,
+            status: statusStr,
+        };
+        console.log(JSON.stringify(output, null, options.pretty ? 2 : 0));
+        return 0;
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        return 1;
+    }
+}
 async function runKnUpdateCommand(args) {
     let options;
     try {
@@ -1287,6 +2056,253 @@ async function runKnDeleteCommand(args) {
         return 1;
     }
 }
+const KN_BUILD_HELP = `kweaver bkn build <kn-id> [options]
+
+Trigger a full build for a knowledge network.
+
+Options:
+  --wait (default)     Poll until build completes
+  --no-wait            Return immediately after triggering
+  --timeout <seconds>  Max wait time when --wait (default: 300)
+  -bd, --biz-domain    Business domain (default: bd_public)`;
+export function parseKnBuildArgs(args) {
+    let knId = "";
+    let wait = true;
+    let timeout = 300;
+    let businessDomain = "bd_public";
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h")
+            throw new Error("help");
+        if (arg === "--wait") {
+            wait = true;
+            continue;
+        }
+        if (arg === "--no-wait") {
+            wait = false;
+            continue;
+        }
+        if (arg === "--timeout" && args[i + 1]) {
+            timeout = parseInt(args[i + 1], 10);
+            if (Number.isNaN(timeout) || timeout < 1)
+                timeout = 300;
+            i += 1;
+            continue;
+        }
+        if ((arg === "-bd" || arg === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (!arg.startsWith("-") && !knId) {
+            knId = arg;
+        }
+    }
+    if (!knId) {
+        throw new Error("Missing kn-id. Usage: kweaver bkn build <kn-id> [options]");
+    }
+    return { knId, wait, timeout, businessDomain };
+}
+async function runKnBuildCommand(args) {
+    let options;
+    try {
+        options = parseKnBuildArgs(args);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(KN_BUILD_HELP);
+            return 0;
+        }
+        console.error(formatHttpError(error));
+        return 1;
+    }
+    const TERMINAL_STATES = ["completed", "failed", "success"];
+    try {
+        const token = await ensureValidToken();
+        await buildKnowledgeNetwork({
+            baseUrl: token.baseUrl,
+            accessToken: token.accessToken,
+            knId: options.knId,
+            businessDomain: options.businessDomain,
+        });
+        console.error(`Build started for ${options.knId}`);
+        if (!options.wait) {
+            console.error("Build triggered (not waiting).");
+            return 0;
+        }
+        console.error("Waiting for build to complete ...");
+        const deadline = Date.now() + options.timeout * 1000;
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 2000));
+            const body = await getBuildStatus({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId: options.knId,
+                businessDomain: options.businessDomain,
+            });
+            const parsed = JSON.parse(body);
+            const jobs = Array.isArray(parsed) ? parsed : (parsed.entries ?? parsed.data ?? []);
+            const job = jobs[0];
+            const state = (job?.state ?? "running").toLowerCase();
+            const detail = job?.state_detail;
+            if (TERMINAL_STATES.includes(state)) {
+                console.log(state);
+                if (detail) {
+                    console.log(`Detail: ${detail}`);
+                }
+                return state === "failed" ? 1 : 0;
+            }
+        }
+        console.error(`Build did not complete within ${options.timeout}s`);
+        return 1;
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        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 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]