@kweaver-ai/kweaver-sdk 0.8.2 → 0.8.3

package/dist/help/format.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Help text formatter for the kweaver CLI.
+ *
+ * All `--help` output must go through `renderHelp()` to keep a consistent
+ * gh-style layout. See `docs/cli_conventions.md` §8 for the spec.
+ */
+export interface HelpItem {
+    name: string;
+    desc: string;
+}
+export interface HelpSection {
+    title: string;
+    items: HelpItem[];
+}
+export interface HelpFlag {
+    name: string;
+    desc: string;
+}
+export interface HelpFlagGroup {
+    title: string;
+    flags: HelpFlag[];
+}
+export interface RenderHelpOptions {
+    /** Optional one-line tagline shown at the very top. */
+    tagline?: string;
+    /** One or more USAGE lines (without the "USAGE" header). */
+    usage: string | string[];
+    /**
+     * Command / subcommand groupings (rendered as separate sections with
+     * two-column name:desc layout).
+     */
+    sections?: HelpSection[];
+    /**
+     * Flags. Either a flat list (rendered under "FLAGS") or grouped sub-blocks
+     * (each rendered under its own title, e.g. "Login options").
+     */
+    flags?: HelpFlag[] | HelpFlagGroup[];
+    /** One-line "INHERITED FLAGS" summary. Omitted if undefined. */
+    inheritedFlags?: string;
+    /** Environment variable docs. */
+    environment?: HelpFlag[];
+    /** Example invocations (prefix `$ ` added automatically if missing). */
+    examples?: string[];
+    /** Free-form "LEARN MORE" trailing lines. */
+    learnMore?: string[];
+    /** Override the wrap width (default 80). */
+    width?: number;
+}
+/**
+ * Render full help text per the §8 spec.
+ */
+export declare function renderHelp(opts: RenderHelpOptions): string;
+/**
+ * Render a two-column name:desc list.
+ *
+ * Width policy: left column = max(name length) + 2 (capped at half the wrap
+ * width). Description wraps onto continuation lines aligned to the right
+ * column. `indent` controls the leading whitespace (default: 2 spaces).
+ */
+export declare function formatTwoColumn(items: HelpItem[], width?: number, indent?: string): string[];
+/**
+ * Word-wrap a string at the given column. Preserves single newlines as
+ * explicit line breaks.
+ */
+export declare function wrap(text: string, width: number): string[];

package/dist/help/format.js

@@ -0,0 +1,141 @@
+/**
+ * Help text formatter for the kweaver CLI.
+ *
+ * All `--help` output must go through `renderHelp()` to keep a consistent
+ * gh-style layout. See `docs/cli_conventions.md` §8 for the spec.
+ */
+const DEFAULT_WIDTH = 80;
+const INDENT = "  ";
+/**
+ * Render full help text per the §8 spec.
+ */
+export function renderHelp(opts) {
+    const width = opts.width ?? DEFAULT_WIDTH;
+    const out = [];
+    if (opts.tagline) {
+        out.push(opts.tagline);
+        out.push("");
+    }
+    const usageLines = Array.isArray(opts.usage) ? opts.usage : [opts.usage];
+    out.push("USAGE");
+    for (const line of usageLines) {
+        out.push(INDENT + line);
+    }
+    out.push("");
+    if (opts.sections && opts.sections.length > 0) {
+        for (const section of opts.sections) {
+            out.push(section.title.toUpperCase());
+            out.push(...formatTwoColumn(section.items, width));
+            out.push("");
+        }
+    }
+    if (opts.flags) {
+        if (isFlagGroupArray(opts.flags)) {
+            out.push("FLAGS");
+            for (const group of opts.flags) {
+                out.push(INDENT + group.title);
+                out.push(...formatTwoColumn(group.flags.map((f) => ({ name: f.name, desc: f.desc })), width, INDENT.repeat(2)));
+                out.push("");
+            }
+        }
+        else {
+            out.push("FLAGS");
+            out.push(...formatTwoColumn(opts.flags.map((f) => ({ name: f.name, desc: f.desc })), width));
+            out.push("");
+        }
+    }
+    if (opts.inheritedFlags) {
+        out.push("INHERITED FLAGS");
+        out.push(INDENT + opts.inheritedFlags);
+        out.push("");
+    }
+    if (opts.environment && opts.environment.length > 0) {
+        out.push("ENVIRONMENT");
+        out.push(...formatTwoColumn(opts.environment.map((e) => ({ name: e.name, desc: e.desc })), width));
+        out.push("");
+    }
+    if (opts.examples && opts.examples.length > 0) {
+        out.push("EXAMPLES");
+        for (const ex of opts.examples) {
+            const trimmed = ex.trimStart();
+            const line = trimmed.startsWith("$") ? trimmed : `$ ${trimmed}`;
+            out.push(INDENT + line);
+        }
+        out.push("");
+    }
+    if (opts.learnMore && opts.learnMore.length > 0) {
+        out.push("LEARN MORE");
+        for (const line of opts.learnMore) {
+            out.push(INDENT + line);
+        }
+        out.push("");
+    }
+    while (out.length > 0 && out[out.length - 1] === "")
+        out.pop();
+    return out.join("\n");
+}
+/**
+ * Render a two-column name:desc list.
+ *
+ * Width policy: left column = max(name length) + 2 (capped at half the wrap
+ * width). Description wraps onto continuation lines aligned to the right
+ * column. `indent` controls the leading whitespace (default: 2 spaces).
+ */
+export function formatTwoColumn(items, width = DEFAULT_WIDTH, indent = INDENT) {
+    if (items.length === 0)
+        return [];
+    const maxName = items.reduce((m, i) => Math.max(m, i.name.length), 0);
+    const halfWidth = Math.floor(width / 2);
+    const colGap = Math.min(maxName + 2, halfWidth);
+    const descCol = indent.length + colGap;
+    const descWidth = Math.max(20, width - descCol);
+    const out = [];
+    for (const item of items) {
+        const namePadded = item.name.padEnd(colGap, " ");
+        const descLines = wrap(item.desc, descWidth);
+        if (descLines.length === 0) {
+            out.push(indent + item.name);
+            continue;
+        }
+        out.push(indent + namePadded + descLines[0]);
+        for (let i = 1; i < descLines.length; i++) {
+            out.push(" ".repeat(descCol) + descLines[i]);
+        }
+    }
+    return out;
+}
+/**
+ * Word-wrap a string at the given column. Preserves single newlines as
+ * explicit line breaks.
+ */
+export function wrap(text, width) {
+    if (!text)
+        return [];
+    const result = [];
+    for (const para of text.split("\n")) {
+        if (para.length <= width) {
+            result.push(para);
+            continue;
+        }
+        const words = para.split(/\s+/);
+        let line = "";
+        for (const word of words) {
+            if (line.length === 0) {
+                line = word;
+            }
+            else if (line.length + 1 + word.length <= width) {
+                line += " " + word;
+            }
+            else {
+                result.push(line);
+                line = word;
+            }
+        }
+        if (line.length > 0)
+            result.push(line);
+    }
+    return result;
+}
+function isFlagGroupArray(v) {
+    return v.length > 0 && "flags" in v[0];
+}

package/dist/index.d.ts

@@ -59,9 +59,9 @@ export type { InvokeToolArgs } from "./resources/toolboxes.js";
 export { ModelsResource, LlmModelsSubresource, SmallModelsSubresource, ModelInvocationSubresource, } from "./resources/models.js";
 export type { SkillCategory, SkillEditableStatus, SkillStatus, SkillSummary, SkillInfo, SkillFileSummary, SkillContentIndex, SkillFileReadResult, RegisterSkillResult, DeleteSkillResult, UpdateSkillStatusResult, SkillListResult, ListSkillsOptions, ListSkillMarketOptions, GetSkillOptions, RegisterSkillContentOptions, RegisterSkillZipOptions, UpdateSkillMetadataOptions, UpdateSkillMetadataResult, UpdateSkillPackageContentOptions, UpdateSkillPackageZipOptions, UpdateSkillPackageResult, UpdateSkillStatusOptions, ReadSkillFileOptions, DownloadSkillOptions, DownloadedSkillArchive, SkillReleaseHistoryInfo, SkillHistoryVersionOptions, SkillManagementContentData, GetSkillManagementContentOptions, ReadSkillManagementFileOptions, DownloadSkillManagementOptions, } from "./api/skills.js";
 export { listSkills, listSkillMarket, getSkill, getSkillMarketDetail, deleteSkill, updateSkillStatus, updateSkillMetadata, registerSkillContent, registerSkillZip, updateSkillPackageContent, updateSkillPackageZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, listSkillHistory, republishSkillHistory, publishSkillHistory, installSkillArchive, getSkillManagementContent, readSkillManagementFile, downloadSkillManagementArchive, } from "./api/skills.js";
-export type { ViewField, DataView, CreateDataViewOptions, GetDataViewOptions, ListDataViewsOptions, DeleteDataViewOptions, FindDataViewOptions, QueryDataViewOptions, DataViewQueryResult, } from "./api/dataviews.js";
-export { parseDataView, createDataView, getDataView, listDataViews, deleteDataView, findDataView, queryDataView, } from "./api/dataviews.js";
-export { DataViewsResource } from "./resources/dataviews.js";
+export type { ViewField, Resource, CreateResourceOptions, GetResourceOptions, ListResourcesOptions, DeleteResourceOptions, FindResourceOptions, QueryResourceOptions, ResourceQueryResult, } from "./api/resources.js";
+export { parseResource, createResource, getResource, listResources, deleteResource, findResource, queryResource, } from "./api/resources.js";
+export { ResourcesResource } from "./resources/resources.js";
 export type { MfManagerBaseOptions, ListLlmModelsOptions, GetLlmModelOptions, AddLlmModelOptions, EditLlmModelOptions, DeleteLlmModelsOptions, TestLlmModelOptions, ListSmallModelsOptions, GetSmallModelOptions, AddSmallModelOptions, EditSmallModelOptions, DeleteSmallModelsOptions, TestSmallModelOptions, } from "./api/models.js";
 export { MF_MODEL_MANAGER_PATH_PREFIX, assertSmallModelConfigAdapterExclusive, assertSmallModelEditBody, listLlmModels, getLlmModel, addLlmModel, editLlmModel, deleteLlmModels, testLlmModel, listSmallModels, getSmallModel, addSmallModel, editSmallModel, deleteSmallModels, testSmallModel, } from "./api/models.js";
 export type { MfApiBaseOptions, ChatMessage, ModelChatCompletionsOptions, ModelChatResult, ModelEmbeddingOptions, ModelRerankOptions, } from "./api/model-invocation.js";

package/dist/index.js

@@ -45,8 +45,8 @@ export { SkillsResource } from "./resources/skills.js";
 export { ToolboxesResource } from "./resources/toolboxes.js";
 export { ModelsResource, LlmModelsSubresource, SmallModelsSubresource, ModelInvocationSubresource, } from "./resources/models.js";
 export { listSkills, listSkillMarket, getSkill, getSkillMarketDetail, deleteSkill, updateSkillStatus, updateSkillMetadata, registerSkillContent, registerSkillZip, updateSkillPackageContent, updateSkillPackageZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, listSkillHistory, republishSkillHistory, publishSkillHistory, installSkillArchive, getSkillManagementContent, readSkillManagementFile, downloadSkillManagementArchive, } from "./api/skills.js";
-export { parseDataView, createDataView, getDataView, listDataViews, deleteDataView, findDataView, queryDataView, } from "./api/dataviews.js";
-export { DataViewsResource } from "./resources/dataviews.js";
+export { parseResource, createResource, getResource, listResources, deleteResource, findResource, queryResource, } from "./api/resources.js";
+export { ResourcesResource } from "./resources/resources.js";
 export { MF_MODEL_MANAGER_PATH_PREFIX, assertSmallModelConfigAdapterExclusive, assertSmallModelEditBody, listLlmModels, getLlmModel, addLlmModel, editLlmModel, deleteLlmModels, testLlmModel, listSmallModels, getSmallModel, addSmallModel, editSmallModel, deleteSmallModels, testSmallModel, } from "./api/models.js";
 export { MF_MODEL_API_PATH_PREFIX, consumeOpenAiSseText, modelChatCompletions, modelEmbedding, modelEmbeddings, modelRerank, } from "./api/model-invocation.js";
 export { listBusinessDomains } from "./api/business-domains.js";

package/dist/resources/{dataviews.d.ts → resources.d.ts}

@@ -1,6 +1,6 @@
-import type { DataView, DataViewQueryResult } from "../api/dataviews.js";
+import type { Resource, ResourceQueryResult } from "../api/resources.js";
 import type { ClientContext } from "../client.js";
-export declare class DataViewsResource {
+export declare class ResourcesResource {
     private readonly ctx;
     constructor(ctx: ClientContext);
     create(opts: {
@@ -12,26 +12,25 @@ export declare class DataViewsResource {
             type: string;
         }>;
     }): Promise<string>;
-    get(id: string): Promise<DataView>;
+    get(id: string): Promise<Resource>;
     list(opts?: {
         datasourceId?: string;
-        type?: string;
+        category?: string;
         limit?: number;
-    }): Promise<DataView[]>;
+    }): Promise<Resource[]>;
     find(name: string, opts?: {
         datasourceId?: string;
         exact?: boolean;
         wait?: boolean;
         timeoutMs?: number;
-    }): Promise<DataView[]>;
+    }): Promise<Resource[]>;
     delete(id: string): Promise<void>;
     query(id: string, opts?: {
-        sql?: string;
         offset?: number;
         limit?: number;
         needTotal?: boolean;
-        outputFields?: string[];
-        filters?: Record<string, unknown>;
-        sort?: Array<Record<string, unknown>>;
-    }): Promise<DataViewQueryResult>;
+        filterCondition?: unknown;
+        sort?: string;
+        direction?: "asc" | "desc";
+    }): Promise<ResourceQueryResult>;
 }

package/dist/resources/{dataviews.js → resources.js}

@@ -1,25 +1,25 @@
-import { createDataView, deleteDataView, findDataView, getDataView, listDataViews, queryDataView, } from "../api/dataviews.js";
-export class DataViewsResource {
+import { RESOURCE_LIST_DEFAULT_LIMIT, createResource, deleteResource, findResource, getResource, listResources, queryResource, } from "../api/resources.js";
+export class ResourcesResource {
     ctx;
     constructor(ctx) {
         this.ctx = ctx;
     }
     async create(opts) {
-        return createDataView({ ...this.ctx.base(), ...opts });
+        return createResource({ ...this.ctx.base(), ...opts });
     }
     async get(id) {
-        return getDataView({ ...this.ctx.base(), id });
+        return getResource({ ...this.ctx.base(), id });
     }
     async list(opts = {}) {
-        return listDataViews({
+        return listResources({
             ...this.ctx.base(),
             datasourceId: opts.datasourceId,
-            type: opts.type,
-            limit: opts.limit,
+            category: opts.category,
+            limit: opts.limit ?? RESOURCE_LIST_DEFAULT_LIMIT,
         });
     }
     async find(name, opts) {
-        return findDataView({
+        return findResource({
             ...this.ctx.base(),
             name,
             datasourceId: opts?.datasourceId,
@@ -29,19 +29,18 @@ export class DataViewsResource {
         });
     }
     async delete(id) {
-        await deleteDataView({ ...this.ctx.base(), id });
+        await deleteResource({ ...this.ctx.base(), id });
     }
     async query(id, opts) {
-        return queryDataView({
+        return queryResource({
             ...this.ctx.base(),
             id,
-            sql: opts?.sql,
             offset: opts?.offset,
             limit: opts?.limit,
             needTotal: opts?.needTotal,
-            outputFields: opts?.outputFields,
-            filters: opts?.filters,
+            filterCondition: opts?.filterCondition,
             sort: opts?.sort,
+            direction: opts?.direction,
         });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",

package/dist/api/dataviews.d.ts

@@ -1,117 +0,0 @@
-/** Field metadata returned by the data-views API. */
-export interface ViewField {
-    name: string;
-    type: string;
-    display_name?: string;
-    comment?: string;
-}
-/** Normalized data view model (mdl-data-model). */
-export interface DataView {
-    id: string;
-    name: string;
-    query_type: string;
-    datasource_id: string;
-    /** View type, e.g. "atomic" or "custom". */
-    type?: string;
-    /** Underlying data source engine, e.g. "mysql", "postgresql". */
-    data_source_type?: string;
-    /** Human-readable data source name. */
-    data_source_name?: string;
-    /** Full SQL expression stored in the view definition (Trino catalog.schema.table). */
-    sql_str?: string;
-    /** Fully-qualified table reference (catalog."schema"."table"). */
-    meta_table_name?: string;
-    /** Field metadata. Populated by `get`; absent (`undefined`) in `list` results. */
-    fields?: ViewField[];
-}
-export declare function parseDataView(raw: Record<string, unknown>): DataView;
-export interface CreateDataViewOptions {
-    baseUrl: string;
-    accessToken: string;
-    name: string;
-    datasourceId: string;
-    table: string;
-    fields?: Array<{
-        name: string;
-        type: string;
-    }>;
-    businessDomain?: string;
-}
-export declare function createDataView(options: CreateDataViewOptions): Promise<string>;
-export interface ListDataViewsOptions {
-    baseUrl: string;
-    accessToken: string;
-    businessDomain?: string;
-    /** Filter by data source id. */
-    datasourceId?: string;
-    /** Server-side keyword filter (fuzzy). */
-    name?: string;
-    /** View type filter (e.g. atomic, custom). */
-    type?: string;
-    /** Max items; default -1 (all). */
-    limit?: number;
-}
-export declare function listDataViews(options: ListDataViewsOptions): Promise<DataView[]>;
-export interface DeleteDataViewOptions {
-    baseUrl: string;
-    accessToken: string;
-    id: string;
-    businessDomain?: string;
-}
-export declare function deleteDataView(options: DeleteDataViewOptions): Promise<void>;
-export interface GetDataViewOptions {
-    baseUrl: string;
-    accessToken: string;
-    id: string;
-    businessDomain?: string;
-}
-export declare function getDataView(options: GetDataViewOptions): Promise<DataView>;
-export interface FindDataViewOptions {
-    baseUrl: string;
-    accessToken: string;
-    businessDomain?: string;
-    /** View name to search for (sent as keyword to server). */
-    name: string;
-    /** Filter by data source id. */
-    datasourceId?: string;
-    /** When true, apply client-side exact name match after keyword search (default false). */
-    exact?: boolean;
-    /** When true, poll until a result appears or timeout (default false). */
-    wait?: boolean;
-    /** Total wait budget in ms (default 30000). Only used when wait is true. */
-    timeoutMs?: number;
-}
-/**
- * Find data views by name. Uses server-side keyword filtering; when `exact` is true,
- * applies client-side `name ===` filter. Optional polling with exponential backoff.
- */
-export declare function findDataView(options: FindDataViewOptions): Promise<DataView[]>;
-/** Options for querying data view rows via mdl-uniquery (SQL / view definition). */
-export interface QueryDataViewOptions {
-    baseUrl: string;
-    accessToken: string;
-    id: string;
-    sql?: string;
-    offset?: number;
-    limit?: number;
-    needTotal?: boolean;
-    outputFields?: string[];
-    filters?: Record<string, unknown>;
-    sort?: Array<Record<string, unknown>>;
-    businessDomain?: string;
-}
-/** Query result from mdl-uniquery data-views POST (shape varies by backend). */
-export interface DataViewQueryResult {
-    columns?: Array<{
-        name: string;
-        type?: string;
-        vega_type?: string;
-    }>;
-    entries?: unknown;
-    total_count?: number;
-}
-/**
- * Execute a query against a data view (POST /api/mdl-uniquery/v1/data-views/:id).
- * When `sql` is omitted, the server uses the view's stored SQL definition.
- */
-export declare function queryDataView(options: QueryDataViewOptions): Promise<DataViewQueryResult>;