@kweaver-ai/kweaver-sdk 0.7.2 → 0.7.3

package/README.md

@@ -193,7 +193,7 @@ kweaver context-loader search-schema|tool-call|kn-search|kn-schema-search <kn-id
 kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
 kweaver context-loader config set/use/list/show                       (deprecated; <kn-id> may be omitted to fall back to saved config)
 kweaver toolbox create/list/publish/unpublish/delete
-kweaver tool upload/list/enable/disable
+kweaver tool upload/list/enable/disable/execute/debug (execute and debug accept --path for OpenAPI path params)
 kweaver call <path> [-X METHOD] [-d BODY] [-H header] [-F key=value]
 ```
 
@@ -242,6 +242,11 @@ kweaver tool upload --toolbox <BOX_ID> ./openapi.json
 # 3. Publish the toolbox and enable the tool
 kweaver toolbox publish <BOX_ID>
 kweaver tool enable --toolbox <BOX_ID> <TOOL_ID>
+
+# Invoke / debug: envelope supports `--header`, `--query`, `--body`, and **`--path`**
+# for OpenAPI `{param}` placeholders (required for paths like `/data-views/{id}`).
+kweaver tool debug --toolbox <BOX_ID> <TOOL_ID> \
+  --path '{"id":"<DATA_VIEW_UUID>"}' [--body '<json>']
 ```
 
 **No-auth platforms:** If OAuth is not enabled, use `kweaver auth <url> --no-auth` (or run a normal `auth login`; a **404** on `POST /oauth2/clients` switches to no-auth automatically). Credentials are still saved under `~/.kweaver/` and work with `auth use` / `auth list`. Optional: `KWEAVER_NO_AUTH=1` with `KWEAVER_BASE_URL` when no token env is set. SDK: `new KWeaverClient({ baseUrl, auth: false })` or `kweaver.configure({ baseUrl, auth: false })`.

package/dist/api/datasources.d.ts

@@ -71,3 +71,10 @@ export interface ScanMetadataOptions {
     businessDomain?: string;
 }
 export declare function scanMetadata(options: ScanMetadataOptions): Promise<string>;
+export interface ScanDatasourceMetadataOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+export declare function scanDatasourceMetadata(options: ScanDatasourceMetadataOptions): Promise<string>;

package/dist/api/datasources.js

@@ -208,3 +208,11 @@ export async function scanMetadata(options) {
     }
     return taskId;
 }
+// Looks up a datasource's type then triggers a metadata scan, so callers
+// don't have to repeat the GET-then-scan dance whenever a flow needs the
+// platform catalog refreshed (after import-csv, before discovering tables).
+export async function scanDatasourceMetadata(options) {
+    const dsBody = await getDatasource(options);
+    const dsType = JSON.parse(dsBody).type ?? "mysql";
+    return scanMetadata({ ...options, dsType });
+}

package/dist/api/toolboxes.d.ts

@@ -63,6 +63,8 @@ export interface InvokeToolOptions extends BaseOpts {
     header?: Record<string, unknown>;
     /** Optional query params to forward. */
     query?: Record<string, unknown>;
+    /** Path parameter map for OpenAPI `{param}` placeholders (e.g. `{ id: "<uuid>" }`). */
+    path?: Record<string, unknown>;
     /** JSON body forwarded to the downstream tool. */
     body?: unknown;
     /** Per-call timeout in seconds; backend default applies when omitted. */

package/dist/api/toolboxes.js

@@ -20,7 +20,7 @@ import { buildHeaders } from "./headers.js";
 //   POST   /tool-box/{box}/tool/{tool}/debug       debug tool (envelope JSON)
 //
 // Envelope shape required by /proxy and /debug:
-//   { "timeout": <s>, "header": {...}, "query": {...}, "body": {...} }
+//   { "timeout": <s>, "header": {...}, "query": {...}, "body": {...}, "path": {...} }
 // Flat-shape requests cause the forwarder to drop downstream Authorization
 // headers, which manifests as 401 "token expired" from the underlying tool.
 const PATH = "/api/agent-operator-integration/v1/tool-box";
@@ -145,6 +145,7 @@ function buildEnvelope(opts) {
         envelope.timeout = opts.timeout;
     envelope.header = opts.header ?? {};
     envelope.query = opts.query ?? {};
+    envelope.path = opts.path ?? {};
     envelope.body = opts.body ?? {};
     return JSON.stringify(envelope);
 }

package/dist/cli.js

@@ -62,6 +62,10 @@ Usage:
   kweaver ds connect <db_type> <host> <port> <database> --account X --password Y [--schema S] [--name N]
                      [--reuse-existing|--force-new]
 
+  kweaver dataflow templates [--json]
+  kweaver dataflow create-dataset --template <name> --set "key=value" [--json] [-bd value]
+  kweaver dataflow create-bkn --template <name> --set "key=value" [--json] [-bd value]
+  kweaver dataflow create (--template <name> --set "key=value" | <json>) [-bd value]
   kweaver dataflow list [-bd value]
   kweaver dataflow run <dagId> (--file <path> | --url <remote-url> --name <filename>) [-bd value]
   kweaver dataflow runs <dagId> [--since <date-like>] [-bd value]
@@ -116,7 +120,7 @@ Usage:
   kweaver tool enable|disable --toolbox <box-id> <tool-id>... [-bd value]
   kweaver tool execute|debug --toolbox <box-id> <tool-id>
                              [--body '<json>'|--body-file <path>]
-                             [--header '<json>'] [--query '<json>'] [--timeout <s>]
+                             [--header '<json>'] [--query '<json>'] [--path '<json>'] [--timeout <s>]
 
   kweaver vega health|stats|inspect
   kweaver vega catalog list|get|health|test-connection|discover|resources [options]
@@ -139,7 +143,19 @@ Usage:
 Global options:
   --base-url <url>  Override platform base URL for this command (env: KWEAVER_BASE_URL)
   --token <value>   Override access token for this command (env: KWEAVER_TOKEN; disables write-to-disk commands)
-  --user <id|name>  Use a specific user's credentials for this command (env: KWEAVER_USER)
+  --user <id|name>  Use a specific user's credentials for this command, transient (env: KWEAVER_USER)
+
+Multi-shell account isolation:
+  KWEAVER_PROFILE=<name>     Scope state.json (active platform / active user) to a named
+                             profile. Tokens under platforms/ are still shared, so each
+                             profile reuses logins. Required for \`auth switch\` and
+                             \`auth use\` (use --global to override). Name must match
+                             [A-Za-z0-9_-]{1,64}.
+  KWEAVERC_CONFIG_DIR=<dir>  Override the entire config root (~/.kweaver by default).
+                             Use this for hard isolation (separate token store per shell).
+
+For agents / multi-terminal scripts: prefer \`--user <id>\` (transient, no persistence)
+over \`auth switch\` (persistent, requires KWEAVER_PROFILE).
   --pretty / --compact
                     Toggle pretty-printed JSON output. Supported by every
                     command that prints a JSON payload (default: pretty).

package/dist/commands/auth.js

@@ -1,9 +1,31 @@
 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 { autoSelectBusinessDomain, clearPlatformSession, deletePlatform, deleteUser, getActiveUser, getConfigDir, getCurrentPlatform, getPlatformAlias, getProfileName, 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";
 import { buildCopyCommand, fetchEacpUserInfo, formatHttpError, InitialPasswordChangeRequiredError, normalizeBaseUrl, oauth2Login, oauth2PasswordSigninLogin, promptForUsername, promptForPassword, refreshTokenLogin, resolveActivePlatform, } from "../auth/oauth.js";
+function consumeGlobalFlag(args) {
+    const idx = args.indexOf("--global");
+    if (idx === -1)
+        return { args, isGlobal: false };
+    return { args: [...args.slice(0, idx), ...args.slice(idx + 1)], isGlobal: true };
+}
+function requireProfileOrGlobal(command, isGlobal) {
+    if (isGlobal)
+        return null;
+    try {
+        if (getProfileName())
+            return null;
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+    return (`kweaver auth ${command} mutates the active account globally and would affect every shell using ~/.kweaver.\n` +
+        `Pick one:\n` +
+        `  - Transient: prepend \`--user <id|name>\` (or \`KWEAVER_USER=<id>\`) to the command you actually want to run; no persistent switch.\n` +
+        `  - Persistent (this shell only): \`export KWEAVER_PROFILE=<name>\`, then re-run.\n` +
+        `  - Intentionally global (CI / single-user setup): re-run with \`--global\`.`);
+}
 export async function runAuthCommand(args) {
     const target = args[0];
     const rest = args.slice(1);
@@ -357,10 +379,16 @@ Login options:
         return 0;
     }
     if (target === "use") {
-        const resolvedTarget = args[1] ? resolvePlatformIdentifier(args[1]) : "";
+        const { args: useArgs, isGlobal } = consumeGlobalFlag(args);
+        const refusal = requireProfileOrGlobal("use", isGlobal);
+        if (refusal !== null) {
+            console.error(refusal);
+            return 1;
+        }
+        const resolvedTarget = useArgs[1] ? resolvePlatformIdentifier(useArgs[1]) : "";
         const useTarget = resolvedTarget && /^https?:\/\//.test(resolvedTarget) ? normalizeBaseUrl(resolvedTarget) : resolvedTarget;
         if (!useTarget) {
-            console.error("Usage: kweaver auth use <platform-url|alias>");
+            console.error("Usage: kweaver auth use [--global] <platform-url|alias>");
             return 1;
         }
         if (!hasPlatform(useTarget)) {
@@ -490,18 +518,25 @@ You can use either userId or username with --user in switch/logout/delete.`);
 }
 function runAuthSwitchCommand(args) {
     if (args[0] === "--help" || args[0] === "-h") {
-        console.log(`kweaver auth switch [platform-url|alias] --user <userId|username>
+        console.log(`kweaver auth switch [--global] [platform-url|alias] --user <userId|username>
 
 Switch the active user for a platform.
 You can specify either the userId (sub claim) or the username (preferred_username from id_token).`);
         return 0;
     }
-    const userArg = readOption(args, "--user");
+    const { args: switchArgs, isGlobal } = consumeGlobalFlag(args);
+    const refusal = requireProfileOrGlobal("switch", isGlobal);
+    if (refusal !== null) {
+        console.error(refusal);
+        return 1;
+    }
+    const cleanedArgs = switchArgs;
+    const userArg = readOption(cleanedArgs, "--user") ?? process.env.KWEAVER_USER;
     if (!userArg) {
-        console.error("Usage: kweaver auth switch [platform-url|alias] --user <userId|username>");
+        console.error("Usage: kweaver auth switch [--global] [platform-url|alias] --user <userId|username>");
         return 1;
     }
-    const filteredArgs = args.filter((a) => a !== "--user" && a !== userArg);
+    const filteredArgs = cleanedArgs.filter((a) => a !== "--user" && a !== userArg);
     const platform = resolvePlatformArg(filteredArgs);
     if (!platform) {
         console.error("No active platform. Run `kweaver auth login <platform-url>` first.");

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

@@ -32,6 +32,7 @@ export declare function parseKnCreateFromDsArgs(args: string[]): {
     dsId: string;
     name: string;
     tables: string[];
+    pkMap: Record<string, string>;
     build: boolean;
     timeout: number;
     businessDomain: string;
@@ -51,8 +52,8 @@ export declare function parseKnCreateFromCsvArgs(args: string[]): {
     tablePrefix: string;
     batchSize: number;
     tables: string[];
+    pkMap: Record<string, string>;
     build: boolean;
-    recreate: boolean;
     timeout: number;
     businessDomain: string;
     noRollback: boolean;

package/dist/commands/bkn-ops.js

@@ -5,7 +5,7 @@ import { loadNetwork, allObjects, allRelations, allActions, generateChecksum, va
 import { prepareBknDirectoryForImport, stripBknEncodingCliArgs, } from "../utils/bkn-encoding.js";
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
 import { createKnowledgeNetwork, createObjectTypes, deleteKnowledgeNetwork, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
-import { listTablesWithColumns, scanMetadata, getDatasource } from "../api/datasources.js";
+import { listTablesWithColumns, scanDatasourceMetadata } from "../api/datasources.js";
 import { createDataView, findDataView } from "../api/dataviews.js";
 import { resolveFiles } from "./ds.js";
 import { buildTableName } from "./import-csv.js";
@@ -13,7 +13,7 @@ import { downloadBkn, uploadBkn, listActionSchedules, getActionSchedule, createA
 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";
+import { pollWithBackoff, detectPrimaryKey, detectDisplayKey, formatPkDetectionError, parsePkMap, 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,
@@ -480,6 +480,8 @@ Create a knowledge network from a datasource (dataviews + object types + optiona
 Options:
   --name <s>       Knowledge network name (required)
   --tables <a,b>   Comma-separated table names (default: all)
+  --pk-map <s>     Explicit primary keys: <table>:<field>[,<table>:<field>...]
+                   Required when auto-detection fails (no unique column in sample)
   --build (default)  Build after creation
   --no-build       Skip build after creation
   --timeout <n>    Build timeout in seconds (default: 300)
@@ -490,6 +492,7 @@ export function parseKnCreateFromDsArgs(args) {
     let dsId = "";
     let name = "";
     let tablesStr = "";
+    let pkMapStr = "";
     let build = true;
     let timeout = 300;
     let businessDomain = "";
@@ -507,6 +510,10 @@ export function parseKnCreateFromDsArgs(args) {
             tablesStr = args[++i];
             continue;
         }
+        if (arg === "--pk-map" && args[i + 1]) {
+            pkMapStr = args[++i];
+            continue;
+        }
         if (arg === "--build") {
             build = true;
             continue;
@@ -541,9 +548,10 @@ export function parseKnCreateFromDsArgs(args) {
     if (!dsId || !name) {
         throw new Error("Usage: kweaver bkn create-from-ds <ds-id> --name X [options]");
     }
+    const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { dsId, name, tables, build, timeout, businessDomain, pretty, noRollback };
+    return { dsId, name, tables, pkMap, build, timeout, businessDomain, pretty, noRollback };
 }
 /** Sanitize a table name into a BKN-safe ID (alphanumeric + underscore). */
 function sanitizeBknId(name) {
@@ -587,6 +595,7 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
         const tableRetryDelayMs = 4000;
         let allTables = [];
         let targetTables = [];
+        let scanAttempted = false;
         for (let attempt = 1; attempt <= maxTableListAttempts; attempt += 1) {
             const tablesBody = await listTablesWithColumns({ ...base, id: options.dsId });
             allTables = JSON.parse(tablesBody);
@@ -596,8 +605,24 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
             if (targetTables.length > 0)
                 break;
             if (attempt < maxTableListAttempts) {
-                console.error(`No tables available (attempt ${attempt}/${maxTableListAttempts}); retrying in ${tableRetryDelayMs / 1000}s...`);
-                await new Promise((r) => setTimeout(r, tableRetryDelayMs));
+                // First miss: the catalog often hasn't picked up tables created
+                // out-of-band (e.g. ds import-csv from an older SDK that didn't
+                // self-scan). Trigger a scan once before falling back to plain
+                // sleep-retries.
+                if (!scanAttempted) {
+                    scanAttempted = true;
+                    console.error(`No tables available (attempt ${attempt}/${maxTableListAttempts}); scanning datasource metadata before retry...`);
+                    try {
+                        await scanDatasourceMetadata({ ...base, id: options.dsId });
+                    }
+                    catch (err) {
+                        console.error(`Scan warning (continuing): ${formatHttpError(err)}`);
+                    }
+                }
+                else {
+                    console.error(`No tables available (attempt ${attempt}/${maxTableListAttempts}); retrying in ${tableRetryDelayMs / 1000}s...`);
+                    await new Promise((r) => setTimeout(r, tableRetryDelayMs));
+                }
             }
         }
         if (targetTables.length === 0) {
@@ -608,6 +633,31 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
         // 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");
+        // Pre-flight: resolve PK for every table BEFORE any side effect.
+        // Auto-detection silently picking the wrong column was the cause of
+        // issue #97 (KN built with ~5 indexed docs out of 2036 source rows).
+        // Resolve order: --pk-map override → cardinality-based detection → fail-fast.
+        const tablePks = {};
+        const unknownPkMapTables = Object.keys(options.pkMap).filter((name) => !targetTables.some((t) => t.name === name));
+        if (unknownPkMapTables.length > 0) {
+            throw new Error(`--pk-map references unknown table(s): ${unknownPkMapTables.join(", ")}`);
+        }
+        for (const t of targetTables) {
+            const override = options.pkMap[t.name];
+            if (override) {
+                if (!t.columns.some((c) => c.name === override)) {
+                    throw new Error(`--pk-map specifies '${override}' for table '${t.name}', but no such column. ` +
+                        `Columns: ${t.columns.map((c) => c.name).join(", ")}`);
+                }
+                tablePks[t.name] = override;
+                continue;
+            }
+            const result = detectPrimaryKey(t, sampleRows?.[t.name]);
+            if (!result.pk) {
+                throw new Error(formatPkDetectionError(t.name, result));
+            }
+            tablePks[t.name] = result.pk;
+        }
         // 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) ...`);
@@ -653,7 +703,7 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
             // (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 pk = tablePks[t.name];
                 const dk = detectDisplayKey(t, pk);
                 return {
                     branch: "main",
@@ -759,7 +809,7 @@ Options:
   --tables <a,b>       Tables to include in KN (default: all imported)
   --build (default)    Build after creation
   --no-build           Skip build
-  --recreate           Use "insert" mode on first batch (only effective for new tables)
+  --pk-map <s>         Explicit primary keys: <table>:<field>[,<table>:<field>...]
   --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)`;
@@ -770,8 +820,8 @@ export function parseKnCreateFromCsvArgs(args) {
     let tablePrefix = "";
     let batchSize = 500;
     let tablesStr = "";
+    let pkMapStr = "";
     let build = true;
-    let recreate = false;
     let timeout = 300;
     let businessDomain = "";
     let noRollback = false;
@@ -809,8 +859,8 @@ export function parseKnCreateFromCsvArgs(args) {
             build = false;
             continue;
         }
-        if (arg === "--recreate") {
-            recreate = true;
+        if (arg === "--pk-map" && args[i + 1]) {
+            pkMapStr = args[++i];
             continue;
         }
         if (arg === "--no-rollback") {
@@ -835,9 +885,10 @@ export function parseKnCreateFromCsvArgs(args) {
     if (!dsId || !files || !name) {
         throw new Error("Usage: kweaver bkn create-from-csv <ds-id> --files <glob> --name X [options]");
     }
+    const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { dsId, files, name, tablePrefix, batchSize, tables, build, recreate, timeout, businessDomain, noRollback };
+    return { dsId, files, name, tablePrefix, batchSize, tables, pkMap, build, timeout, businessDomain, noRollback };
 }
 export async function runKnCreateFromCsvCommand(args) {
     let options;
@@ -874,35 +925,15 @@ export async function runKnCreateFromCsvCommand(args) {
         "--table-prefix", options.tablePrefix,
         "--batch-size", String(options.batchSize),
         "-bd", options.businessDomain,
-        ...(options.recreate ? ["--recreate"] : []),
     ];
     const importResult = await runDsImportCsv(importArgs);
     if (importResult.code !== 0) {
         console.error("CSV import failed — aborting KN creation");
         return importResult.code;
     }
-    // Phase 1.5: Scan datasource metadata so platform discovers newly imported tables
-    console.error("Scanning datasource metadata ...");
-    try {
-        const token = await ensureValidToken();
-        const dsBody = await getDatasource({
-            baseUrl: token.baseUrl,
-            accessToken: token.accessToken,
-            id: options.dsId,
-            businessDomain: options.businessDomain,
-        });
-        const dsParsed = JSON.parse(dsBody);
-        await scanMetadata({
-            baseUrl: token.baseUrl,
-            accessToken: token.accessToken,
-            id: options.dsId,
-            dsType: dsParsed.type ?? "mysql",
-            businessDomain: options.businessDomain,
-        });
-    }
-    catch (err) {
-        console.error(`Scan warning (continuing): ${String(err)}`);
-    }
+    // (Phase 1.5 metadata scan removed — runDsImportCsv now self-scans on
+    // success, and runKnCreateFromDsCommand's table-discovery retry triggers
+    // a scan if the catalog still lags. Two layers of fallback are enough.)
     // Phase 2: Create KN from datasource
     console.error("Phase 2: Creating knowledge network ...");
     const tableNames = options.tables.length > 0 ? options.tables : importResult.tables;
@@ -910,6 +941,7 @@ export async function runKnCreateFromCsvCommand(args) {
         console.error("No tables available for KN creation — aborting");
         return 1;
     }
+    const pkMapEntries = Object.entries(options.pkMap);
     const knArgs = [
         options.dsId,
         "--name", options.name,
@@ -917,6 +949,9 @@ export async function runKnCreateFromCsvCommand(args) {
         options.build ? "--build" : "--no-build",
         "--timeout", String(options.timeout),
         "-bd", options.businessDomain,
+        ...(pkMapEntries.length > 0
+            ? ["--pk-map", pkMapEntries.map(([t, f]) => `${t}:${f}`).join(",")]
+            : []),
         ...(options.noRollback ? ["--no-rollback"] : []),
     ];
     return runKnCreateFromDsCommand(knArgs, importResult.sampleRows);

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

@@ -18,14 +18,38 @@ export declare function parseOntologyQueryFlags(args: string[]): {
     businessDomain: string;
 };
 export declare const DISPLAY_HINTS: string[];
-/** Detect primary key: first column (left-to-right) with all unique values in the sample. */
+export interface PkCandidate {
+    name: string;
+    cardinality: number;
+}
+export interface PkDetectionResult {
+    /** Detected PK column name, or null when detection is not confident. */
+    pk: string | null;
+    /** All columns sorted by cardinality desc. Empty when no sample. */
+    candidates: PkCandidate[];
+    /** 0 when no sample data was provided. */
+    sampleSize: number;
+}
+export declare const PK_NAME_HINTS: string[];
+/**
+ * Detect primary key from a row sample. Returns null pk when no column has
+ * unique values across the sample — caller must fail-fast and prompt for --pk-map.
+ * Among columns that ARE fully unique, prefers PK-like names (id, *_id, pk).
+ */
 export declare function detectPrimaryKey(table: {
     name: string;
     columns: Array<{
         name: string;
         type: string;
     }>;
-}, rows?: Array<Record<string, string | null>>): string;
+}, rows?: Array<Record<string, string | null>>): PkDetectionResult;
+/** Format a user-facing error message when PK auto-detection fails. */
+export declare function formatPkDetectionError(tableName: string, result: PkDetectionResult): string;
+/**
+ * Parse --pk-map string into a Record<table, field>.
+ * Format: "<table>:<field>[,<table>:<field>...]". Throws on invalid input.
+ */
+export declare function parsePkMap(input: string): Record<string, string>;
 export declare function detectDisplayKey(table: {
     name: string;
     columns: Array<{

package/dist/commands/bkn-utils.js

@@ -68,18 +68,75 @@ export function parseOntologyQueryFlags(args) {
 }
 // ── Schema detection helpers ─────────────────────────────────────────────────
 export const DISPLAY_HINTS = ["name", "title", "label", "display_name", "description"];
-/** Detect primary key: first column (left-to-right) with all unique values in the sample. */
+export const PK_NAME_HINTS = ["id", "_id", "pk"];
+/**
+ * Detect primary key from a row sample. Returns null pk when no column has
+ * unique values across the sample — caller must fail-fast and prompt for --pk-map.
+ * Among columns that ARE fully unique, prefers PK-like names (id, *_id, pk).
+ */
 export function detectPrimaryKey(table, rows) {
-    if (rows && rows.length > 0) {
-        for (const col of table.columns) {
-            const values = rows.map((r) => r[col.name]);
-            const unique = new Set(values);
-            if (unique.size === rows.length)
-                return col.name;
+    if (!rows || rows.length === 0) {
+        return { pk: null, candidates: [], sampleSize: 0 };
+    }
+    const candidates = table.columns
+        .map((col) => {
+        const unique = new Set(rows.map((r) => r[col.name]));
+        return { name: col.name, cardinality: unique.size };
+    })
+        .sort((a, b) => b.cardinality - a.cardinality);
+    const fullCardinality = candidates.filter((c) => c.cardinality === rows.length);
+    if (fullCardinality.length === 0) {
+        return { pk: null, candidates, sampleSize: rows.length };
+    }
+    const named = fullCardinality.find((c) => {
+        const lower = c.name.toLowerCase();
+        return PK_NAME_HINTS.some((h) => lower === h || lower.endsWith(`_${h}`));
+    });
+    return {
+        pk: named?.name ?? fullCardinality[0].name,
+        candidates,
+        sampleSize: rows.length,
+    };
+}
+/** Format a user-facing error message when PK auto-detection fails. */
+export function formatPkDetectionError(tableName, result) {
+    const lines = [`Cannot auto-detect primary key for table '${tableName}'.`];
+    if (result.sampleSize === 0) {
+        lines.push(`  No sample data available — chain with 'kweaver ds import-csv' or use --pk-map.`);
+    }
+    else {
+        lines.push(`  No column has unique values in the ${result.sampleSize}-row sample.`);
+        lines.push(`  Top candidates by cardinality:`);
+        const top = result.candidates.slice(0, 5);
+        const maxNameLen = Math.max(...top.map((c) => c.name.length));
+        for (const c of top) {
+            lines.push(`    ${c.name.padEnd(maxNameLen)}  ${c.cardinality} unique`);
+        }
+    }
+    lines.push(``);
+    lines.push(`  Re-run with --pk-map to specify explicitly:`);
+    lines.push(`    --pk-map ${tableName}:<column>`);
+    return lines.join("\n");
+}
+/**
+ * Parse --pk-map string into a Record<table, field>.
+ * Format: "<table>:<field>[,<table>:<field>...]". Throws on invalid input.
+ */
+export function parsePkMap(input) {
+    const result = {};
+    for (const pair of input.split(",").map((s) => s.trim()).filter(Boolean)) {
+        const idx = pair.indexOf(":");
+        if (idx <= 0 || idx >= pair.length - 1) {
+            throw new Error(`Invalid --pk-map entry '${pair}'. Expected '<table>:<field>[,<table>:<field>...]'`);
+        }
+        const table = pair.slice(0, idx).trim();
+        const field = pair.slice(idx + 1).trim();
+        if (!table || !field) {
+            throw new Error(`Invalid --pk-map entry '${pair}'. Expected '<table>:<field>[,<table>:<field>...]'`);
         }
+        result[table] = field;
     }
-    // Fallback: first column
-    return table.columns[0]?.name ?? "id";
+    return result;
 }
 export function detectDisplayKey(table, primaryKey) {
     for (const col of table.columns) {