@kopai/ui 0.0.5 → 0.1.0

package/src/lib/component-catalog.ts

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import { dataFilterSchemas } from "@kopai/core";
+import type { ReactNode } from "react";
+
+// DataSource schema - discriminated union with type-safe params per method
+export const dataSourceSchema = z.discriminatedUnion("method", [
+  z.object({
+    method: z.literal("searchTracesPage"),
+    params: dataFilterSchemas.tracesDataFilterSchema,
+    refetchIntervalMs: z.number().optional(),
+  }),
+  z.object({
+    method: z.literal("searchLogsPage"),
+    params: dataFilterSchemas.logsDataFilterSchema,
+    refetchIntervalMs: z.number().optional(),
+  }),
+  z.object({
+    method: z.literal("searchMetricsPage"),
+    params: dataFilterSchemas.metricsDataFilterSchema,
+    refetchIntervalMs: z.number().optional(),
+  }),
+  z.object({
+    method: z.literal("getTrace"),
+    params: z.object({ traceId: z.string() }),
+    refetchIntervalMs: z.number().optional(),
+  }),
+  z.object({
+    method: z.literal("discoverMetrics"),
+    params: z.object({}).optional(),
+    refetchIntervalMs: z.number().optional(),
+  }),
+]);
+
+export type DataSource = z.infer<typeof dataSourceSchema>;
+
+export const componentDefinitionSchema = z
+  .object({
+    hasChildren: z.boolean(),
+    description: z
+      .string()
+      .describe(
+        "Component description to be displayed by the prompt generator"
+      ),
+    props: z.unknown(),
+  })
+  .describe(
+    "All options and properties necessary to render the React component with renderer"
+  );
+
+export const catalogConfigSchema = z.object({
+  name: z.string().describe("catalog name"),
+  components: z.record(
+    z.string().describe("React component name"),
+    componentDefinitionSchema
+  ),
+});
+
+// Union of all element types with literal type discriminator
+export type InferredElement<C extends Record<string, { props: unknown }>> = {
+  [K in keyof C & string]: {
+    key: string;
+    type: K;
+    children: string[];
+    parentKey: string;
+    dataSource?: z.infer<typeof dataSourceSchema>;
+    props: C[K]["props"] extends z.ZodTypeAny
+      ? z.infer<C[K]["props"]>
+      : unknown;
+  };
+}[keyof C & string];
+
+// Zod schema type for a single element variant (preserves K-to-props mapping)
+type ElementVariantSchema<
+  K extends string,
+  Props extends z.ZodTypeAny,
+> = z.ZodObject<{
+  key: z.ZodString;
+  type: z.ZodLiteral<K>;
+  children: z.ZodArray<z.ZodString>;
+  parentKey: z.ZodString;
+  dataSource: z.ZodOptional<typeof dataSourceSchema>;
+  props: Props;
+}>;
+
+// Union of all element variant schemas
+type ElementVariantSchemas<C extends Record<string, { props: unknown }>> = {
+  [K in keyof C & string]: ElementVariantSchema<
+    K,
+    C[K]["props"] extends z.ZodTypeAny ? C[K]["props"] : z.ZodUnknown
+  >;
+}[keyof C & string];
+
+/**
+ * Creates a component catalog with typed UI tree schema for validation.
+ *
+ * @param catalogConfig - Catalog configuration with name and component definitions
+ * @returns Catalog object with name, components, and generated uiTreeSchema
+ *
+ * @example
+ * ```ts
+ * const catalog = createCatalog({
+ *   name: "my-catalog",
+ *   components: {
+ *     Card: {
+ *       hasChildren: true,
+ *       description: "Container card",
+ *       props: z.object({ title: z.string() }),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createCatalog<
+  C extends Record<string, z.infer<typeof componentDefinitionSchema>>,
+>(catalogConfig: { name: string; components: C }) {
+  const elementVariants = (
+    Object.keys(catalogConfig.components) as (keyof C & string)[]
+  )
+    .map((catalogItemName) => ({
+      catalogItemName,
+      component: catalogConfig.components[catalogItemName],
+    }))
+    .filter(
+      (
+        itemConfig
+      ): itemConfig is typeof itemConfig & { component: C[keyof C] } =>
+        !!itemConfig.component
+    )
+    .map(({ catalogItemName, component }) =>
+      z.object({
+        key: z.string(),
+        type: z.literal(catalogItemName),
+        children: z.array(z.string()),
+        parentKey: z.string(),
+        dataSource: dataSourceSchema.optional(),
+        props: component.props,
+      })
+    );
+
+  type Schemas = ElementVariantSchemas<C>;
+  const elementsUnion = z.discriminatedUnion(
+    "type",
+    elementVariants as unknown as [Schemas, ...Schemas[]]
+  );
+
+  // TODO: implement a mechanism for validating there are no circular references
+  const uiTreeSchema = z.object({
+    root: z.string().describe("root uiElement key in the elements array"),
+    elements: z.record(
+      z.string().describe("equal to the element key"),
+      elementsUnion
+    ),
+  });
+
+  return {
+    name: catalogConfig.name,
+    components: catalogConfig.components,
+    uiTreeSchema,
+  };
+}
+
+export type ComponentDefinition = z.infer<typeof componentDefinitionSchema>;
+
+export type InferProps<P> = P extends z.ZodTypeAny ? z.infer<P> : P;
+
+export type CatalogueComponentProps<CD extends ComponentDefinition> =
+  CD extends { hasChildren: true; props: infer P }
+    ? { element: { props: InferProps<P> }; children: ReactNode }
+    : CD extends { props: infer P }
+      ? { element: { props: InferProps<P> } }
+      : never;

package/src/lib/dashboard-datasource.ts

@@ -0,0 +1,76 @@
+import { observabilityCatalog } from "./observability-catalog.js";
+import { z } from "zod";
+
+type UiTree = z.infer<typeof observabilityCatalog.uiTreeSchema>;
+
+export type DashboardId = string;
+export type UiTreeId = string;
+export type OwnerId = string;
+
+export interface DashboardMeta {
+  dashboardId: DashboardId;
+  uiTreeId: UiTreeId;
+  name: string;
+  ownerId: OwnerId;
+  pinned: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface VersionMeta {
+  uiTreeId: UiTreeId;
+  createdAt: string;
+}
+
+export interface DashboardWriteDatasource {
+  createDashboard(
+    uiTree: UiTree,
+    name: string,
+    ownerId: OwnerId
+  ): Promise<DashboardMeta>;
+
+  // uiTrees are immutable, creates new one with ref to previous
+  updateDashboard(
+    dashboardId: DashboardId,
+    uiTree: UiTree,
+    pinned?: boolean
+  ): Promise<DashboardMeta>;
+
+  deleteDashboard(dashboardId: DashboardId): Promise<void>;
+
+  // Creates new uiTree copying content from specified version
+  restoreVersion(
+    dashboardId: DashboardId,
+    uiTreeId: UiTreeId
+  ): Promise<DashboardMeta>;
+}
+
+export interface DashboardReadDatasource {
+  searchDashboards(params: {
+    limit: number;
+    cursor?: string;
+    pinned?: boolean;
+    ownerId?: OwnerId;
+  }): Promise<{
+    dashboards: (DashboardMeta & { uiTree: UiTree })[];
+    nextCursor?: string;
+  }>;
+
+  getDashboard(
+    dashboardId: DashboardId
+  ): Promise<DashboardMeta & { uiTree: UiTree }>;
+
+  listVersions(params: {
+    dashboardId: DashboardId;
+    limit: number;
+    cursor?: string;
+  }): Promise<{
+    versions: VersionMeta[];
+    nextCursor?: string;
+  }>;
+
+  getDashboardAtVersion(uiTreeId: UiTreeId): Promise<{
+    uiTree: UiTree;
+    createdAt: string;
+  }>;
+}

package/src/lib/generate-prompt-instructions.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { createCatalog } from "./component-catalog.js";
+import { generatePromptInstructions } from "./generate-prompt-instructions.js";
+
+describe("generatePromptInstructions", () => {
+  it("generates full prompt instructions", () => {
+    const catalog = createCatalog({
+      name: "test",
+      components: {
+        Card: {
+          props: z.object({ title: z.string() }),
+          description: "A card container",
+          hasChildren: true,
+        },
+        Button: {
+          props: z.object({ label: z.string() }),
+          description: "Clickable button",
+          hasChildren: false,
+        },
+      },
+    });
+
+    const prompt = generatePromptInstructions(catalog);
+    expect(prompt).toMatchSnapshot();
+  });
+});

package/src/lib/generate-prompt-instructions.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { dataSourceSchema } from "./component-catalog.js";
+
+type Catalog = {
+  name: string;
+  components: Record<
+    string,
+    { hasChildren: boolean; description: string; props: unknown }
+  >;
+  uiTreeSchema: z.ZodTypeAny;
+};
+
+// Helper to format prop type from JSON schema property
+function formatPropType(prop: {
+  type?: string | string[];
+  enum?: string[];
+  items?: object;
+}): string {
+  if (prop.enum) return prop.enum.map((v) => `"${v}"`).join(" | ");
+  if (Array.isArray(prop.type))
+    return prop.type.filter((t) => t !== "null").join(" | ");
+  if (prop.type === "array" && prop.items)
+    return `array of ${formatPropType(prop.items as Parameters<typeof formatPropType>[0])}`;
+  return prop.type ?? "unknown";
+}
+
+// Helper to format props from JSON schema
+function formatPropsFromJsonSchema(jsonSchema: object): string {
+  const schema = jsonSchema as {
+    properties?: Record<string, unknown>;
+    required?: string[];
+  };
+  if (!schema.properties) return "(no props)";
+
+  const required = new Set(schema.required ?? []);
+  const lines: string[] = [];
+
+  for (const [key, value] of Object.entries(schema.properties)) {
+    const prop = value as {
+      type?: string | string[];
+      enum?: string[];
+      description?: string;
+      items?: object;
+    };
+    const isRequired = required.has(key);
+    const typeStr = formatPropType(prop);
+    const reqStr = isRequired ? " (required)" : " (optional)";
+    const descStr = prop.description ? ` - ${prop.description}` : "";
+    lines.push(`- ${key}: ${typeStr}${reqStr}${descStr}`);
+  }
+  return lines.join("\n");
+}
+
+// Helper to build example UI tree
+function buildExampleElements(
+  names: string[],
+  components: Record<string, { hasChildren: boolean }>
+): { root: string; elements: Record<string, unknown> } {
+  const containerName =
+    names.find((n) => components[n]?.hasChildren) ?? names[0];
+  const containerKey = `${String(containerName).toLowerCase()}-1`;
+
+  const childKeys: string[] = [];
+  const elements: Record<string, unknown> = {};
+
+  elements[containerKey] = {
+    key: containerKey,
+    type: String(containerName),
+    props: {},
+    children: childKeys,
+  };
+
+  const otherNames = names.filter((n) => n !== containerName).slice(0, 2);
+  for (const name of otherNames) {
+    const key = `${String(name).toLowerCase()}-1`;
+    childKeys.push(key);
+    elements[key] = {
+      key,
+      type: String(name),
+      props: {},
+      parentKey: containerKey,
+      dataSource: {
+        method: "searchTracesPage",
+        params: { limit: 10 },
+      },
+    };
+  }
+
+  return { root: containerKey, elements };
+}
+
+// Helper to check if a value looks like the dataSource schema
+function isDataSourceSchema(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  if (!Array.isArray(obj.oneOf)) return false;
+  const first = obj.oneOf[0] as Record<string, unknown> | undefined;
+  if (!first?.properties) return false;
+  const props = first.properties as Record<string, unknown>;
+  const method = props.method as Record<string, unknown> | undefined;
+  return method?.const === "searchTracesPage";
+}
+
+// Helper to recursively replace dataSource schema with $ref
+function replaceDataSourceWithRef(obj: unknown): void {
+  if (!obj || typeof obj !== "object") return;
+
+  const record = obj as Record<string, unknown>;
+  for (const key of Object.keys(record)) {
+    const value = record[key];
+    if (key === "dataSource" && isDataSourceSchema(value)) {
+      record[key] = { $ref: "#/$defs/DataSource" };
+    } else if (value && typeof value === "object") {
+      replaceDataSourceWithRef(value);
+    }
+  }
+}
+
+// Helper to build unified schema with $defs
+function buildUnifiedSchema(treeSchema: z.ZodTypeAny): object {
+  const dataSourceJsonSchema = z.toJSONSchema(dataSourceSchema);
+  const treeJsonSchema = z.toJSONSchema(treeSchema) as Record<string, unknown>;
+
+  replaceDataSourceWithRef(treeJsonSchema);
+  treeJsonSchema.$defs = { DataSource: dataSourceJsonSchema };
+
+  return treeJsonSchema;
+}
+
+/**
+ * Generates LLM prompt instructions from a catalog.
+ * Includes component docs, JSON schema, and usage examples.
+ *
+ * @param catalog - The catalog created via createCatalog
+ * @returns Markdown string with component docs, schema, and examples
+ *
+ * @example
+ * ```ts
+ * const instructions = generatePromptInstructions(catalog);
+ * const prompt = `Build a dashboard UI.\n\n${instructions}`;
+ * ```
+ */
+export function generatePromptInstructions(catalog: Catalog): string {
+  const componentNames = Object.keys(catalog.components);
+
+  const componentSections = componentNames
+    .map((name) => {
+      const def = catalog.components[name]!;
+      const propsSchema = z.toJSONSchema(def.props as z.ZodTypeAny);
+      const propsFormatted = formatPropsFromJsonSchema(propsSchema);
+      const roleLine = def.hasChildren
+        ? "Accepts children: yes"
+        : "Accepts dataSource: yes";
+
+      return `### ${name}
+${def.description ?? "No description"}
+
+Props:
+${propsFormatted}
+${roleLine}`;
+    })
+    .join("\n\n---\n\n");
+
+  const unifiedSchema = buildUnifiedSchema(catalog.uiTreeSchema);
+  const exampleElements = buildExampleElements(
+    componentNames,
+    catalog.components
+  );
+
+  return `## Available Components
+
+${componentSections}
+
+---
+
+## Output Schema
+
+${JSON.stringify(unifiedSchema)}
+
+---
+
+## Example
+
+${JSON.stringify(exampleElements)}`;
+}

package/src/lib/log-buffer.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { LogBuffer } from "./log-buffer.js";
+import type { denormalizedSignals } from "@kopai/core";
+
+type OtelLogsRow = denormalizedSignals.OtelLogsRow;
+
+const BASE_NS = 1700000000000000000n;
+const ts = (offsetMs: number) =>
+  (BASE_NS + BigInt(offsetMs) * 1000000n).toString();
+
+function makeRow(offsetMs: number, body: string, service = "svc"): OtelLogsRow {
+  return {
+    Timestamp: ts(offsetMs),
+    Body: body,
+    ServiceName: service,
+    SeverityText: "INFO",
+    SeverityNumber: 9,
+  };
+}
+
+describe("LogBuffer", () => {
+  it("stores and returns rows sorted by timestamp", () => {
+    const buf = new LogBuffer();
+    buf.merge([makeRow(200, "second"), makeRow(100, "first")]);
+    const all = buf.getAll();
+    expect(all).toHaveLength(2);
+    expect(all[0]!.Body).toBe("first");
+    expect(all[1]!.Body).toBe("second");
+  });
+
+  it("deduplicates rows with same key", () => {
+    const buf = new LogBuffer();
+    const row = makeRow(100, "hello");
+    buf.merge([row]);
+    buf.merge([row]);
+    expect(buf.size).toBe(1);
+  });
+
+  it("trims oldest rows when exceeding maxSize", () => {
+    const buf = new LogBuffer(3);
+    buf.merge([makeRow(10, "a"), makeRow(20, "b"), makeRow(30, "c")]);
+    expect(buf.size).toBe(3);
+
+    buf.merge([makeRow(40, "d")]);
+    expect(buf.size).toBe(3);
+    // oldest ("a" at ts=10) should be gone
+    const bodies = buf.getAll().map((r) => r.Body);
+    expect(bodies).toEqual(["b", "c", "d"]);
+  });
+
+  it("getNewestTimestamp returns latest timestamp", () => {
+    const buf = new LogBuffer();
+    buf.merge([makeRow(100, "a"), makeRow(300, "c"), makeRow(200, "b")]);
+    expect(buf.getNewestTimestamp()).toBe(ts(300));
+  });
+
+  it("getNewestTimestamp returns undefined for empty buffer", () => {
+    const buf = new LogBuffer();
+    expect(buf.getNewestTimestamp()).toBeUndefined();
+  });
+
+  it("clear resets the buffer", () => {
+    const buf = new LogBuffer();
+    buf.merge([makeRow(100, "a")]);
+    expect(buf.size).toBe(1);
+    buf.clear();
+    expect(buf.size).toBe(0);
+    expect(buf.getAll()).toEqual([]);
+  });
+
+  it("handles empty merge", () => {
+    const buf = new LogBuffer();
+    buf.merge([]);
+    expect(buf.size).toBe(0);
+  });
+
+  it("distinguishes rows with same timestamp but different body", () => {
+    const buf = new LogBuffer();
+    buf.merge([makeRow(100, "hello"), makeRow(100, "world")]);
+    expect(buf.size).toBe(2);
+  });
+
+  it("distinguishes rows with same timestamp+body but different service", () => {
+    const buf = new LogBuffer();
+    buf.merge([makeRow(100, "hello", "svc-a"), makeRow(100, "hello", "svc-b")]);
+    expect(buf.size).toBe(2);
+  });
+});

package/src/lib/log-buffer.ts

@@ -0,0 +1,62 @@
+import type { denormalizedSignals } from "@kopai/core";
+
+type OtelLogsRow = denormalizedSignals.OtelLogsRow;
+
+function logKey(row: OtelLogsRow): string {
+  const body = row.Body ?? "";
+  let hash = 0;
+  for (let i = 0; i < body.length; i++) {
+    hash = (hash << 5) - hash + body.charCodeAt(i);
+    hash = hash & hash;
+  }
+  return `${row.Timestamp}-${row.ServiceName ?? ""}-${Math.abs(hash).toString(36)}`;
+}
+
+export class LogBuffer {
+  private readonly maxSize: number;
+  private rows: OtelLogsRow[] = [];
+  private keys = new Set<string>();
+
+  constructor(maxSize = 1000) {
+    this.maxSize = maxSize;
+  }
+
+  /** Merge new rows, dedup, sort by timestamp, trim oldest when over max. */
+  merge(incoming: OtelLogsRow[]): void {
+    for (const row of incoming) {
+      const k = logKey(row);
+      if (this.keys.has(k)) continue;
+      this.keys.add(k);
+      this.rows.push(row);
+    }
+    // Sort ascending by timestamp
+    this.rows.sort((a, b) => {
+      if (a.Timestamp < b.Timestamp) return -1;
+      if (a.Timestamp > b.Timestamp) return 1;
+      return 0;
+    });
+    // Trim oldest
+    if (this.rows.length > this.maxSize) {
+      const removed = this.rows.splice(0, this.rows.length - this.maxSize);
+      for (const r of removed) this.keys.delete(logKey(r));
+    }
+  }
+
+  getAll(): OtelLogsRow[] {
+    return this.rows.slice();
+  }
+
+  getNewestTimestamp(): string | undefined {
+    if (this.rows.length === 0) return undefined;
+    return this.rows[this.rows.length - 1]!.Timestamp;
+  }
+
+  get size(): number {
+    return this.rows.length;
+  }
+
+  clear(): void {
+    this.rows = [];
+    this.keys.clear();
+  }
+}