@kweaver-ai/kweaver-sdk 0.6.10 → 0.7.2

package/dist/commands/auth.js

@@ -1,4 +1,5 @@
 import { isNoAuth } from "../config/no-auth.js";
+import { assertNotStatelessForWrite } from "../config/stateless.js";
 import { autoSelectBusinessDomain, clearPlatformSession, deletePlatform, deleteUser, getActiveUser, getConfigDir, getCurrentPlatform, getPlatformAlias, hasPlatform, listPlatforms, listUserProfiles, loadClientConfig, loadTokenConfig, loadUserTokenConfig, resolveBusinessDomain, resolvePlatformIdentifier, resolveUserId, saveNoAuthPlatform, setActiveUser, setCurrentPlatform, setPlatformAlias, } from "../config/store.js";
 import { decodeJwtPayload } from "../config/jwt.js";
 import { eacpModifyPassword } from "../auth/eacp-modify-password.js";
@@ -71,6 +72,13 @@ Login options:
     const LOGIN_SUBCOMMANDS = new Set(["status", "list", "use", "delete", "logout", "export", "whoami", "users", "switch"]);
     if (target && !LOGIN_SUBCOMMANDS.has(target)) {
         try {
+            try {
+                assertNotStatelessForWrite("auth login");
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                return 1;
+            }
             const normalizedTarget = normalizeBaseUrl(target);
             const alias = readOption(args, "--alias");
             let username = readOption(args, "--username") ?? readOption(args, "-u");
@@ -268,7 +276,8 @@ Login options:
             }
             console.log(`Config directory: ${getConfigDir()}`);
             console.log(`Platform:         ${active.url} (KWEAVER_BASE_URL)`);
-            console.log(`Token present:    yes (KWEAVER_TOKEN)`);
+            const tokenProvenance = process.env.KWEAVER_TOKEN_SOURCE === "flag" ? "CLI (flag: --token)" : "KWEAVER_TOKEN";
+            console.log(`Token present:    yes (${tokenProvenance})`);
             console.log(`Refresh token:    n/a (env)`);
             return 0;
         }
@@ -358,6 +367,13 @@ Login options:
             console.error(`No saved token for ${useTarget}. Run \`kweaver auth login ${useTarget}\` first.`);
             return 1;
         }
+        try {
+            assertNotStatelessForWrite("auth use");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         setCurrentPlatform(useTarget);
         console.log(`Current platform: ${useTarget}`);
         return 0;
@@ -375,6 +391,13 @@ Login options:
             console.error(`No saved token for ${deleteTarget}.`);
             return 1;
         }
+        try {
+            assertNotStatelessForWrite("auth delete");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         if (deleteUserArg) {
             const deleteUserId = resolveUserId(deleteTarget, deleteUserArg) ?? deleteUserArg;
             deleteUser(deleteTarget, deleteUserId);
@@ -404,6 +427,13 @@ Login options:
             console.error(`No saved token for ${logoutTarget}.`);
             return 1;
         }
+        try {
+            assertNotStatelessForWrite("auth logout");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         const logoutUserId = logoutUserArg ? resolveUserId(logoutTarget, logoutUserArg) ?? logoutUserArg : undefined;
         clearPlatformSession(logoutTarget, logoutUserId);
         const userHint = logoutUserId ? ` (user: ${logoutUserId})` : "";
@@ -487,6 +517,13 @@ You can specify either the userId (sub claim) or the username (preferred_usernam
         }
         return 1;
     }
+    try {
+        assertNotStatelessForWrite("auth switch");
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
     setActiveUser(platform, resolvedId);
     const profiles = listUserProfiles(platform);
     const profile = profiles.find((p) => p.userId === resolvedId);
@@ -535,7 +572,10 @@ Options:
         // complete picture without forcing them to pick a mode.
         const jwtPayload = decodeJwtPayload(accessToken);
         if (jsonOutput) {
-            const out = { platform: envUrl, source: "env" };
+            const out = {
+                platform: envUrl,
+                source: process.env.KWEAVER_TOKEN_SOURCE === "flag" ? "flag" : "env",
+            };
             if (userInfo)
                 out.userInfo = userInfo;
             if (jwtPayload)
@@ -544,7 +584,7 @@ Options:
             return 0;
         }
         console.log(`Platform: ${envUrl}`);
-        console.log(`Source:   env (KWEAVER_TOKEN)`);
+        console.log(`Source:   ${process.env.KWEAVER_TOKEN_SOURCE === "flag" ? "CLI (flag: --token)" : "env (KWEAVER_TOKEN)"}`);
         if (userInfo) {
             console.log(`Type:     ${userInfo.type}`);
             console.log(`User ID:  ${userInfo.id}`);

package/dist/commands/bkn-ops.d.ts

@@ -1,4 +1,6 @@
 import { type BknEncodingImportOptions } from "../utils/bkn-encoding.js";
+export declare const BKN_OBJECT_NAME_MAX_LENGTH = 40;
+export declare function assertValidBknObjectNames(names: string[], context: string): void;
 export declare function parseKnBuildArgs(args: string[]): {
     knId: string;
     wait: boolean;
@@ -34,6 +36,7 @@ export declare function parseKnCreateFromDsArgs(args: string[]): {
     timeout: number;
     businessDomain: string;
     pretty: boolean;
+    noRollback: boolean;
 };
 /** Generate a BKN ObjectType YAML markdown file for a table. */
 export declare function generateObjectTypeBkn(tableName: string, dvId: string, pk: string, dk: string, columns: Array<{
@@ -52,6 +55,7 @@ export declare function parseKnCreateFromCsvArgs(args: string[]): {
     recreate: boolean;
     timeout: number;
     businessDomain: string;
+    noRollback: boolean;
 };
 export declare function runKnCreateFromCsvCommand(args: string[]): Promise<number>;
 export interface ActionScheduleParsed {

package/dist/commands/bkn-ops.js

@@ -4,14 +4,36 @@ import { resolve } from "node:path";
 import { loadNetwork, allObjects, allRelations, allActions, generateChecksum, validateNetwork } from "@kweaver-ai/bkn";
 import { prepareBknDirectoryForImport, stripBknEncodingCliArgs, } from "../utils/bkn-encoding.js";
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
-import { createKnowledgeNetwork, createObjectTypes, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
+import { createKnowledgeNetwork, createObjectTypes, deleteKnowledgeNetwork, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
 import { listTablesWithColumns, scanMetadata, getDatasource } from "../api/datasources.js";
 import { createDataView, findDataView } from "../api/dataviews.js";
+import { resolveFiles } from "./ds.js";
+import { buildTableName } from "./import-csv.js";
 import { downloadBkn, uploadBkn, listActionSchedules, getActionSchedule, createActionSchedule, updateActionSchedule, setActionScheduleStatus, deleteActionSchedules, listJobs, getJob, getJobTasks, deleteJobs, } from "../api/bkn-backend.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { runDsImportCsv } from "./ds.js";
 import { pollWithBackoff, detectPrimaryKey, detectDisplayKey, confirmYes, } from "./bkn-utils.js";
+// ── BKN object name validation ──────────────────────────────────────────────
+// Mirrors bkn-backend OBJECT_NAME_MAX_LENGTH (interfaces/common.go:28) and
+// validateObjectName (driveradapters/validate.go:85). 40 utf-8 codepoints,
+// non-empty. Backend rejects the whole batch on first violation, so we surface
+// every offender locally before any side-effecting call.
+export const BKN_OBJECT_NAME_MAX_LENGTH = 40;
+export function assertValidBknObjectNames(names, context) {
+    const offenders = [];
+    for (const name of names) {
+        const len = [...name].length;
+        if (len === 0 || len > BKN_OBJECT_NAME_MAX_LENGTH) {
+            offenders.push({ name, length: len });
+        }
+    }
+    if (offenders.length === 0)
+        return;
+    const lines = offenders.map((o) => `  - ${o.name} (${o.length} chars)`);
+    throw new Error(`${context}: ${offenders.length} name(s) violate BKN object-name limit ` +
+        `(1..${BKN_OBJECT_NAME_MAX_LENGTH} utf-8 chars):\n${lines.join("\n")}`);
+}
 // ── Build ───────────────────────────────────────────────────────────────────
 const KN_BUILD_HELP = `kweaver bkn build <kn-id> [options]
 
@@ -461,6 +483,7 @@ Options:
   --build (default)  Build after creation
   --no-build       Skip build after creation
   --timeout <n>    Build timeout in seconds (default: 300)
+  --no-rollback    Keep partially-created KN on failure (debug; default: rollback)
   -bd, --biz-domain  Business domain (default: bd_public)
   --pretty         Pretty-print output (default)`;
 export function parseKnCreateFromDsArgs(args) {
@@ -471,6 +494,7 @@ export function parseKnCreateFromDsArgs(args) {
     let timeout = 300;
     let businessDomain = "";
     let pretty = true;
+    let noRollback = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h")
@@ -491,6 +515,10 @@ export function parseKnCreateFromDsArgs(args) {
             build = false;
             continue;
         }
+        if (arg === "--no-rollback") {
+            noRollback = true;
+            continue;
+        }
         if (arg === "--timeout" && args[i + 1]) {
             timeout = parseInt(args[++i], 10);
             if (Number.isNaN(timeout) || timeout < 1)
@@ -515,7 +543,7 @@ export function parseKnCreateFromDsArgs(args) {
     }
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { dsId, name, tables, build, timeout, businessDomain, pretty };
+    return { dsId, name, tables, build, timeout, businessDomain, pretty, noRollback };
 }
 /** Sanitize a table name into a BKN-safe ID (alphanumeric + underscore). */
 function sanitizeBknId(name) {
@@ -576,7 +604,12 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
             console.error("No tables available");
             return 1;
         }
-        // Phase 1: Create DataViews for each table
+        // Pre-flight: catch every offending OT name before any side effect.
+        // Backend rejects the whole batch on first violation (validate.go:90),
+        // so retroactive rollback is wasted work if we can fail fast here.
+        assertValidBknObjectNames(targetTables.map((t) => t.name), "Object type names derived from table names");
+        // Phase 1: Create DataViews for each table. findDataView is idempotent;
+        // not tracked for rollback so a retry can reuse what's already there.
         console.error(`Creating data views for ${targetTables.length} table(s) ...`);
         const viewMap = {};
         for (const t of targetTables) {
@@ -597,7 +630,8 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
                 }));
             viewMap[t.name] = dvId;
         }
-        // Phase 2: Create the KN record
+        // Phase 2: Create the KN. If any subsequent step fails we DELETE this
+        // KN — backend cascades to OTs (knowledge_network_service.go:917-969).
         const knBody = JSON.stringify({
             name: options.name,
             branch: "main",
@@ -611,72 +645,91 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
         const knItem = Array.isArray(knParsed) ? knParsed[0] : knParsed;
         const knId = String(knItem?.id ?? "");
         console.error(`Knowledge network created: ${knId}`);
-        // Phase 3: Create object types via REST API
-        console.error(`Creating ${targetTables.length} object type(s) ...`);
+        let createdKnId = knId;
         const otResults = [];
-        for (const t of targetTables) {
-            const pk = detectPrimaryKey(t, sampleRows?.[t.name]);
-            const dk = detectDisplayKey(t, pk);
-            const uniqueProps = [pk, dk].filter((x, i, a) => a.indexOf(x) === i);
-            const entry = {
-                branch: "main",
-                name: t.name,
-                data_source: { type: "data_view", id: viewMap[t.name] },
-                primary_keys: [pk],
-                display_key: dk,
-                data_properties: t.columns.map((c) => ({
-                    name: c.name,
-                    display_name: c.name,
-                    type: "string",
-                    mapped_field: { name: c.name, type: c.type || "varchar" },
-                })),
-            };
-            const otBody = JSON.stringify({ entries: [entry] });
+        let statusStr = "skipped";
+        try {
+            // Phase 3: Single batched POST. Backend wraps all entries in one tx
+            // (object_type_service.go:213-355) — all-or-nothing.
+            console.error(`Creating ${targetTables.length} object type(s) ...`);
+            const entries = targetTables.map((t) => {
+                const pk = detectPrimaryKey(t, sampleRows?.[t.name]);
+                const dk = detectDisplayKey(t, pk);
+                return {
+                    branch: "main",
+                    name: t.name,
+                    data_source: { type: "data_view", id: viewMap[t.name] },
+                    primary_keys: [pk],
+                    display_key: dk,
+                    data_properties: t.columns.map((c) => ({
+                        name: c.name,
+                        display_name: c.name,
+                        type: "string",
+                        mapped_field: { name: c.name, type: c.type || "varchar" },
+                    })),
+                    _meta: { pk, dk },
+                };
+            });
+            const wireEntries = entries.map(({ _meta: _, ...rest }) => rest);
+            const otBody = JSON.stringify({ entries: wireEntries });
             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,
-            });
-            console.error(`  Created: ${t.name} (${t.columns.length} fields, pk=${pk}, dk=${dk})`);
-        }
-        if (otResults.length === 0) {
-            const errorOutput = {
-                kn_id: knId,
-                kn_name: options.name,
-                error: "No object types were created",
-            };
-            console.log(JSON.stringify(errorOutput, null, options.pretty ? 2 : 0));
-            return 1;
-        }
-        let statusStr = "skipped";
-        if (options.build) {
-            console.error("Building ...");
-            await buildKnowledgeNetwork({ ...base, knId });
-            const TERMINAL = ["completed", "failed", "success"];
-            try {
-                statusStr = await pollWithBackoff({
-                    fn: async () => {
-                        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))
-                            return { done: true, value: state };
-                        return { done: false, value: "running" };
-                    },
-                    interval: 2000,
-                    timeout: options.timeout * 1000,
+            const otItems = Array.isArray(otParsed) ? otParsed : (otParsed.entries ?? []);
+            for (let i = 0; i < entries.length; i += 1) {
+                const t = targetTables[i];
+                const meta = entries[i]._meta;
+                otResults.push({
+                    name: t.name,
+                    id: otItems[i]?.id ?? "",
+                    field_count: t.columns.length,
                 });
+                console.error(`  Created: ${t.name} (${t.columns.length} fields, pk=${meta.pk}, dk=${meta.dk})`);
             }
-            catch {
-                // timeout — statusStr remains "skipped"
+            if (options.build) {
+                console.error("Building ...");
+                await buildKnowledgeNetwork({ ...base, knId });
+                const TERMINAL = ["completed", "failed", "success"];
+                try {
+                    statusStr = await pollWithBackoff({
+                        fn: async () => {
+                            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))
+                                return { done: true, value: state };
+                            return { done: false, value: "running" };
+                        },
+                        interval: 2000,
+                        timeout: options.timeout * 1000,
+                    });
+                }
+                catch {
+                    // build timeout — KN itself is fine, just mark skipped
+                }
+            }
+            // Reached the end without throwing — clear the rollback handle.
+            createdKnId = undefined;
+        }
+        finally {
+            if (createdKnId !== undefined) {
+                if (options.noRollback) {
+                    console.error(`Leaving partial KN ${createdKnId} in place (--no-rollback)`);
+                }
+                else {
+                    console.error(`Rolling back KN ${createdKnId} ...`);
+                    try {
+                        await deleteKnowledgeNetwork({ ...base, knId: createdKnId });
+                        console.error(`Rolled back KN ${createdKnId}`);
+                    }
+                    catch (rollbackErr) {
+                        console.error(`Rollback failed for KN ${createdKnId}: ${formatHttpError(rollbackErr)}`);
+                    }
+                }
             }
         }
         const output = {
@@ -708,6 +761,7 @@ Options:
   --no-build           Skip build
   --recreate           Use "insert" mode on first batch (only effective for new tables)
   --timeout <n>        Build timeout in seconds (default: 300)
+  --no-rollback        Keep partially-created KN on failure (debug; default: rollback)
   -bd, --biz-domain    Business domain (default: bd_public)`;
 export function parseKnCreateFromCsvArgs(args) {
     let dsId = "";
@@ -720,6 +774,7 @@ export function parseKnCreateFromCsvArgs(args) {
     let recreate = false;
     let timeout = 300;
     let businessDomain = "";
+    let noRollback = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h")
@@ -758,6 +813,10 @@ export function parseKnCreateFromCsvArgs(args) {
             recreate = true;
             continue;
         }
+        if (arg === "--no-rollback") {
+            noRollback = true;
+            continue;
+        }
         if (arg === "--timeout" && args[i + 1]) {
             timeout = parseInt(args[++i], 10);
             if (Number.isNaN(timeout) || timeout < 1)
@@ -778,7 +837,7 @@ export function parseKnCreateFromCsvArgs(args) {
     }
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { dsId, files, name, tablePrefix, batchSize, tables, build, recreate, timeout, businessDomain };
+    return { dsId, files, name, tablePrefix, batchSize, tables, build, recreate, timeout, businessDomain, noRollback };
 }
 export async function runKnCreateFromCsvCommand(args) {
     let options;
@@ -793,6 +852,20 @@ export async function runKnCreateFromCsvCommand(args) {
         console.error(formatHttpError(error));
         return 1;
     }
+    // Pre-flight: predict OT names from (table-prefix + csv basename) and
+    // reject before any CSV is imported. CSV import is expensive; failing
+    // here saves the user a multi-minute round trip.
+    try {
+        const filePaths = await resolveFiles(options.files);
+        const predictedNames = options.tables.length > 0
+            ? options.tables
+            : filePaths.map((p) => buildTableName(p, options.tablePrefix));
+        assertValidBknObjectNames(predictedNames, "Object type names derived from CSV file names");
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        return 1;
+    }
     // Phase 1: Import CSVs
     console.error("Phase 1: Importing CSVs ...");
     const importArgs = [
@@ -844,6 +917,7 @@ export async function runKnCreateFromCsvCommand(args) {
         options.build ? "--build" : "--no-build",
         "--timeout", String(options.timeout),
         "-bd", options.businessDomain,
+        ...(options.noRollback ? ["--no-rollback"] : []),
     ];
     return runKnCreateFromDsCommand(knArgs, importResult.sampleRows);
 }

package/dist/commands/bkn-query.js

@@ -31,13 +31,18 @@ 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
+        // Map body shape to ontology-query subgraph query_type:
+        // - relation_type_paths mode → ?query_type=relation_path
+        // - source_object_type_id mode → omit query_type (default path; do not send relation_path)
         let queryType;
         try {
             const parsedBody = JSON.parse(body);
-            if (parsedBody.source_object_type_id) {
+            if (Array.isArray(parsedBody.relation_type_paths)) {
                 queryType = "relation_path";
             }
+            else if (parsedBody.source_object_type_id) {
+                queryType = "";
+            }
         }
         catch {
             // Not valid JSON — let the API return the error

package/dist/commands/config.js

@@ -2,6 +2,7 @@ import { listBusinessDomains } from "../api/business-domains.js";
 import { fetchEacpUserInfo, resolveActivePlatform, withTokenRetry } from "../auth/oauth.js";
 import { HttpError } from "../utils/http.js";
 import { loadPlatformBusinessDomain, resolveBusinessDomain, savePlatformBusinessDomain, } from "../config/store.js";
+import { assertNotStatelessForWrite } from "../config/stateless.js";
 const HELP = `kweaver config
 
 Subcommands:
@@ -50,6 +51,13 @@ export async function runConfigCommand(args) {
             return 1;
         }
         const platform = active.url;
+        try {
+            assertNotStatelessForWrite("config set-bd");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         savePlatformBusinessDomain(platform, value);
         const provenance = active.source === "env" ? `${platform} via KWEAVER_BASE_URL` : platform;
         console.log(`Business domain set to: ${value} (${provenance})`);