@kweaver-ai/kweaver-sdk 0.8.2 → 0.8.4

package/dist/cli.js

@@ -7,16 +7,93 @@ import { runCallCommand } from "./commands/call.js";
 import { runConfigCommand } from "./commands/config.js";
 import { runContextLoaderCommand } from "./commands/context-loader.js";
 import { runDataflowCommand } from "./commands/dataflow.js";
-import { runDsCommand } from "./commands/ds.js";
 import { runExploreCommand } from "./commands/explore.js";
-import { runDataviewCommand } from "./commands/dataview.js";
+import { runResourceCommand } from "./commands/resource.js";
 import { runModelCommand } from "./commands/model.js";
 import { runSkillCommand } from "./commands/skill.js";
 import { runTokenCommand } from "./commands/token.js";
 import { runToolboxCommand } from "./commands/toolbox.js";
 import { runToolCommand } from "./commands/tool.js";
 import { runVegaCommand } from "./commands/vega.js";
+import { renderHelp } from "./help/format.js";
 function printHelp() {
+    console.log(renderHelp({
+        tagline: "KWeaver SDK — operate KWeaver platform from CLI",
+        usage: [
+            "kweaver [global flags] <command> <subcommand> [flags]",
+            "kweaver --version | -V",
+            "kweaver --help | -h",
+        ],
+        sections: [
+            {
+                title: "AUTHENTICATION & CONFIG",
+                items: [
+                    { name: "auth", desc: "Login / switch / list saved platform credentials" },
+                    { name: "token", desc: "Print current access token (auto-refresh)" },
+                    { name: "config", desc: "Per-platform business-domain config" },
+                ],
+            },
+            {
+                title: "DECISION AGENT",
+                items: [
+                    { name: "agent", desc: "Agent CRUD, chat, sessions, publish" },
+                    { name: "toolbox", desc: "Agent toolbox lifecycle" },
+                    { name: "tool", desc: "Tools inside toolbox" },
+                ],
+            },
+            {
+                title: "AI DATA PLATFORM",
+                items: [
+                    { name: "bkn", desc: "Knowledge network — build, query, action, metric" },
+                    { name: "resource (res)", desc: "Resources — list, find, get, query, delete" },
+                    { name: "dataflow", desc: "Dataflow document workflows (run, runs, logs)" },
+                    { name: "vega", desc: "Vega observability — catalog, resource, query" },
+                    { name: "context-loader (context)", desc: "MCP/HTTP context loader (reads BKN schema/instances)" },
+                ],
+            },
+            {
+                title: "TRACE AI",
+                items: [
+                    { name: "trace", desc: "Diagnose conversations / build eval-sets / schema validate" },
+                ],
+            },
+            {
+                title: "FOUNDATION",
+                items: [
+                    { name: "call (curl)", desc: "curl-style API call with auto-injected auth headers" },
+                    { name: "explore", desc: "Interactive web UI" },
+                    { name: "model", desc: "Model factory — LLM / small-model CRUD + chat" },
+                    { name: "skill", desc: "Skill registry / market" },
+                    { name: "help", desc: "Show help — use `help all` for full signatures" },
+                ],
+            },
+        ],
+        flags: [
+            { name: "--base-url <url>", desc: "Override platform URL  (env: KWEAVER_BASE_URL)" },
+            { name: "--token <value>", desc: "Override access token  (env: KWEAVER_TOKEN; disables write commands)" },
+            { name: "--user <id|name>", desc: "Use specific user credentials (env: KWEAVER_USER)" },
+            { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+            { name: "--compact", desc: "Compact JSON output (pipeline-friendly)" },
+            { name: "--help, -h", desc: "Show help" },
+            { name: "--version, -V", desc: "Show version" },
+        ],
+        environment: [
+            { name: "KWEAVER_PROFILE", desc: "Isolate active-platform/user state per shell" },
+            { name: "KWEAVERC_CONFIG_DIR", desc: "Override config root (~/.kweaver)" },
+        ],
+        examples: [
+            "kweaver auth https://platform.example.com",
+            "kweaver agent chat <agent_id> -m \"hello\"",
+            "kweaver bkn build <kn-id> --wait",
+        ],
+        learnMore: [
+            "Use `kweaver <command> --help` for command-specific help",
+            "Use `kweaver help all` for full command signatures (migration fallback)",
+            "For agents/multi-terminal: prefer `--user <id>` over `auth switch`",
+        ],
+    }));
+}
+function printHelpFull() {
     console.log(`kweaver
 
 Usage:
@@ -56,13 +133,6 @@ Usage:
   kweaver agent publish <agent_id> [-bd value]
   kweaver agent unpublish <agent_id> [-bd value]
 
-  kweaver ds list [--keyword X] [--type T] [-bd value]
-  kweaver ds get <id>
-  kweaver ds delete <id> [-y]
-  kweaver ds tables <id> [--keyword X]
-  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]
@@ -76,17 +146,18 @@ Usage:
   kweaver model small list|get|add|edit|delete|test|embeddings|rerank|--template ...
   kweaver model --help
 
-  kweaver dataview list [--datasource-id id] [--type atomic|custom] [--limit n] [-bd value]
-  kweaver dataview find --name <name> [--exact] [--datasource-id id] [--wait] [--timeout ms] [-bd value]
-  kweaver dataview get <id> [-bd value]
-  kweaver dataview query <id> [--sql sql] [--limit n] [--offset n] [--need-total] [--raw-sql] [-bd value]
-  kweaver dataview delete <id> [-y] [-bd value]
+  kweaver resource list [--datasource-id id] [--type table|logicview] [--limit n] [-bd value]
+  kweaver resource find --name <name> [--exact] [--datasource-id id] [--wait] [--timeout ms] [-bd value]
+  kweaver resource get <id> [-bd value]
+  kweaver resource query <id> [--limit n] [--offset n] [--need-total] [-bd value]
+  kweaver resource delete <id> [-y] [-bd value]
 
   kweaver bkn list [options]
   kweaver bkn get <kn-id> [options]
   kweaver bkn search <kn-id> <query> [--max-concepts N] [--mode M] [-bd value]
   kweaver bkn create [options]
-  kweaver bkn create-from-ds [options]
+  kweaver bkn create-from-catalog [options]
+  [deprecated] kweaver bkn create-from-ds [options]   (alias for create-from-catalog)
   kweaver bkn update <kn-id> [options]
   kweaver bkn delete <kn-id> [-y]
   kweaver bkn build <kn-id> [--wait] [--no-wait] [--timeout N]
@@ -173,10 +244,9 @@ Commands:
   token          Print the current access token, refreshing it first if needed
   call (curl)    Call an API with curl-style flags and auto-injected token headers
   agent          Agent CRUD, chat, sessions, history, publish/unpublish
-  ds             Manage datasources (list, get, delete, tables, connect)
   dataflow       Dataflow document workflows (list, run, runs, logs)
   model          Model factory: LLM/small-model CRUD (manager) and llm chat (OpenAI-compatible API)
-  dataview|dv    List, find, get, query (SQL), delete data views (atomic / custom)
+  resource|res   List, find, get, query, delete vega-backend resources (table / logicview)
   bkn            Knowledge network (CRUD, build, validate, export, stats, push/pull,
                  object-type, relation-type, subgraph, action-type, action-execution, action-log)
   config         Per-platform configuration (business domain)
@@ -238,27 +308,37 @@ export async function run(argv) {
         console.log(pkg.version);
         return 0;
     }
-    if (argv.length === 0 || !command || command === "--help" || command === "-h" || command === "help") {
+    if (argv.length === 0 || !command || command === "--help" || command === "-h") {
         printHelp();
         return 0;
     }
+    if (command === "help") {
+        const topic = rest[0];
+        if (!topic) {
+            printHelp();
+            return 0;
+        }
+        if (topic === "all") {
+            printHelpFull();
+            return 0;
+        }
+        // `help <command>` → forward to `<command> --help`
+        return run([...rest, "--help"]);
+    }
     if (command === "auth") {
         return runAuthCommand(rest);
     }
     if (command === "call" || command === "curl") {
         return runCallCommand(rest);
     }
-    if (command === "ds") {
-        return runDsCommand(rest);
-    }
     if (command === "dataflow") {
         return runDataflowCommand(rest);
     }
     if (command === "model") {
         return runModelCommand(rest);
     }
-    if (command === "dataview" || command === "dv") {
-        return runDataviewCommand(rest);
+    if (command === "resource" || command === "res") {
+        return runResourceCommand(rest);
     }
     if (command === "token") {
         return runTokenCommand(rest);

package/dist/client.d.ts

@@ -3,7 +3,7 @@ import { ConversationsResource } from "./resources/conversations.js";
 import { ContextLoaderResource } from "./resources/context-loader.js";
 import { DataflowsResource } from "./resources/dataflows.js";
 import { DataSourcesResource } from "./resources/datasources.js";
-import { DataViewsResource } from "./resources/dataviews.js";
+import { ResourcesResource } from "./resources/resources.js";
 import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
 import { BknResource } from "./resources/bkn.js";
 import { SkillsResource } from "./resources/skills.js";
@@ -96,10 +96,16 @@ export declare class KWeaverClient implements ClientContext {
     readonly conversations: ConversationsResource;
     /** Dataflow DAG automation (create/run/poll/delete). */
     readonly dataflows: DataflowsResource;
-    /** Data source management (connect, test, list tables). */
+    /**
+     * Data source management (connect, test, list tables).
+     *
+     * @deprecated Datasource is a legacy concept. Use `client.vega.catalogs` for
+     * catalog CRUD and `client.resources` for resource queries. This property is
+     * kept as a thin back-compat layer and may be removed in a future major release.
+     */
     readonly datasources: DataSourcesResource;
-    /** Data view creation and retrieval. */
-    readonly dataviews: DataViewsResource;
+    /** Vega-backend resource management (table/logicview resources under a catalog). */
+    readonly resources: ResourcesResource;
     /** Vega observability platform (catalogs, resources, connector types). */
     readonly vega: VegaResource;
     /** ADP/KWeaver skill registry, market, progressive read, and install helpers. */

package/dist/client.js

@@ -8,7 +8,7 @@ import { ConversationsResource } from "./resources/conversations.js";
 import { ContextLoaderResource } from "./resources/context-loader.js";
 import { DataflowsResource } from "./resources/dataflows.js";
 import { DataSourcesResource } from "./resources/datasources.js";
-import { DataViewsResource } from "./resources/dataviews.js";
+import { ResourcesResource } from "./resources/resources.js";
 import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
 import { BknResource } from "./resources/bkn.js";
 import { SkillsResource } from "./resources/skills.js";
@@ -58,10 +58,16 @@ export class KWeaverClient {
     conversations;
     /** Dataflow DAG automation (create/run/poll/delete). */
     dataflows;
-    /** Data source management (connect, test, list tables). */
+    /**
+     * Data source management (connect, test, list tables).
+     *
+     * @deprecated Datasource is a legacy concept. Use `client.vega.catalogs` for
+     * catalog CRUD and `client.resources` for resource queries. This property is
+     * kept as a thin back-compat layer and may be removed in a future major release.
+     */
     datasources;
-    /** Data view creation and retrieval. */
-    dataviews;
+    /** Vega-backend resource management (table/logicview resources under a catalog). */
+    resources;
     /** Vega observability platform (catalogs, resources, connector types). */
     vega;
     /** ADP/KWeaver skill registry, market, progressive read, and install helpers. */
@@ -100,7 +106,7 @@ export class KWeaverClient {
             this.conversations = new ConversationsResource(this);
             this.dataflows = new DataflowsResource(this);
             this.datasources = new DataSourcesResource(this);
-            this.dataviews = new DataViewsResource(this);
+            this.resources = new ResourcesResource(this);
             this.vega = new VegaResource(this);
             this.skills = new SkillsResource(this);
             this.toolboxes = new ToolboxesResource(this);
@@ -156,7 +162,7 @@ export class KWeaverClient {
         this.conversations = new ConversationsResource(this);
         this.dataflows = new DataflowsResource(this);
         this.datasources = new DataSourcesResource(this);
-        this.dataviews = new DataViewsResource(this);
+        this.resources = new ResourcesResource(this);
         this.vega = new VegaResource(this);
         this.skills = new SkillsResource(this);
         this.toolboxes = new ToolboxesResource(this);

package/dist/commands/agent-members.js

@@ -6,6 +6,7 @@ import { getAgent, updateAgent } from "../api/agent-list.js";
 import { getSkill } from "../api/skills.js";
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
 import { resolveBusinessDomain } from "../config/store.js";
+import { renderHelp } from "../help/format.js";
 /** Deep-clone a JSON-serializable object so mutations don't leak to callers. */
 function clone(value) {
     return JSON.parse(JSON.stringify(value));
@@ -353,17 +354,32 @@ async function runSkillList(args) {
 export async function runAgentSkillCommand(args) {
     const [verb, ...rest] = args;
     if (!verb || verb === "--help" || verb === "-h") {
-        console.log(`kweaver agent skill
-
-Subcommands:
-  add <agent-id> <skill-id>... [--strict] [-bd <bd>]      Attach skills to an agent
-  remove <agent-id> <skill-id>... [-bd <bd>]              Detach skills from an agent
-  list <agent-id> [--pretty|--compact] [-bd <bd>]         List skills attached to an agent
-
-Notes:
-  --strict         On add, reject skills that exist but are not in 'published' status.
-                   Default behaviour: warn and continue.
-  Dedupe is automatic for add; remove silently skips not-attached ids.`);
+        console.log(renderHelp({
+            tagline: "Manage skills attached to an agent",
+            usage: "kweaver agent skill <subcommand> [flags]",
+            sections: [{
+                    title: "AVAILABLE COMMANDS",
+                    items: [
+                        { name: "add", desc: "Attach skills to an agent" },
+                        { name: "remove", desc: "Detach skills from an agent" },
+                        { name: "list", desc: "List skills attached to an agent" },
+                    ],
+                }],
+            flags: [
+                { name: "--strict", desc: "On add, reject skills that exist but are not in 'published' status. Default behaviour: warn and continue." },
+                { name: "-bd <bd>", desc: "Business domain" },
+                { name: "--pretty|--compact", desc: "Output formatting for list" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver agent skill add <agent-id> <skill-id>... [--strict] [-bd <bd>]",
+                "kweaver agent skill remove <agent-id> <skill-id>... [-bd <bd>]",
+                "kweaver agent skill list <agent-id> [--pretty|--compact] [-bd <bd>]",
+            ],
+            learnMore: [
+                "Dedupe is automatic for add; remove silently skips not-attached ids.",
+            ],
+        }));
         return 0;
     }
     try {