@kitn.ai/ui 0.26.0 → 0.28.0

package/src/agent-tooling/construct/construct.v1.schema.json

@@ -0,0 +1,319 @@
+{
+  "$id": "https://ui.kitn.ai/schemas/construct/v1.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*-[a-z0-9-]+$"
+    },
+    "layout": {
+      "type": "string",
+      "enum": [
+        "widget",
+        "fullscreen",
+        "aside",
+        "split",
+        "custom"
+      ]
+    },
+    "provider": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "const": "mock"
+            }
+          },
+          "required": [
+            "mode"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "const": "endpoint"
+            },
+            "url": {
+              "type": "string",
+              "minLength": 1
+            },
+            "wire": {
+              "type": "string",
+              "enum": [
+                "openai",
+                "anthropic"
+              ]
+            }
+          },
+          "required": [
+            "mode",
+            "url",
+            "wire"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "userId": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[\\x20-\\x7E]+$"
+    },
+    "theme": {
+      "type": "object",
+      "properties": {
+        "accent": {
+          "type": "string"
+        },
+        "unreadColor": {
+          "type": "string"
+        },
+        "mode": {
+          "default": "system",
+          "type": "string",
+          "enum": [
+            "light",
+            "dark",
+            "system"
+          ]
+        }
+      },
+      "required": [
+        "mode"
+      ],
+      "additionalProperties": false
+    },
+    "header": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "empty": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "icon": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "title"
+      ],
+      "additionalProperties": false
+    },
+    "home": {
+      "type": "object",
+      "properties": {
+        "greeting": {
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string",
+              "minLength": 1
+            },
+            "subtitle": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        "recentConversation": {
+          "type": "boolean",
+          "const": true
+        },
+        "newConversation": {
+          "type": "object",
+          "properties": {
+            "label": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        "links": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "label": {
+                "type": "string",
+                "minLength": 1
+              },
+              "href": {
+                "type": "string",
+                "minLength": 1
+              },
+              "description": {
+                "type": "string",
+                "minLength": 1
+              },
+              "icon": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "label"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "starters": {
+          "minItems": 1,
+          "maxItems": 6,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "attachments": {
+          "type": "object",
+          "properties": {
+            "accept": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "required": [
+            "accept"
+          ],
+          "additionalProperties": false
+        },
+        "history": {
+          "type": "object",
+          "properties": {
+            "persistence": {
+              "type": "string",
+              "enum": [
+                "none",
+                "local",
+                "endpoint"
+              ]
+            },
+            "url": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": [
+            "persistence"
+          ],
+          "additionalProperties": false
+        },
+        "reasoning": {
+          "type": "string",
+          "enum": [
+            "full",
+            "compact",
+            "off"
+          ]
+        },
+        "reasoningOpen": {
+          "type": "boolean"
+        },
+        "conversations": {
+          "type": "boolean",
+          "const": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "cards": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          },
+          "schema": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {}
+          }
+        },
+        "required": [
+          "name",
+          "schema"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "slots": {
+      "minItems": 1,
+      "maxItems": 8,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      }
+    },
+    "widget": {
+      "type": "object",
+      "properties": {
+        "position": {
+          "type": "string",
+          "enum": [
+            "bottom-end",
+            "bottom-start",
+            "top-end",
+            "top-start"
+          ]
+        },
+        "launcherIcon": {
+          "type": "string",
+          "minLength": 1
+        },
+        "defaultOpen": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "name",
+    "layout",
+    "provider"
+  ],
+  "additionalProperties": false
+}

package/src/agent-tooling/construct/dev.ts

@@ -0,0 +1,148 @@
+/**
+ * kai dev — validate → codegen → npm install (once per dependency change) →
+ * vite dev inside the generated project → watch the construct file.
+ *
+ * HMR comes free: on every construct edit we re-run the SAME generateProject
+ * and rewrite the source files in place; the running Vite server sees changed
+ * modules and hot-updates the open tab. A validation failure never touches the
+ * generated files — the reasons print and the LAST GOOD preview keeps running.
+ * Mock-first and keyless by default.
+ */
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, watch, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { accentContrastNotice, generateProject, writeProject, type GeneratedFile, type GenerateOptions } from './codegen';
+import { validateConstruct, type Construct, type ConstructProblem } from './schema';
+import type { CliIo } from './cli';
+
+export function workDirFor(name: string, root: string): string {
+  return join(root, '.kai', name);
+}
+
+export function installKey(files: GeneratedFile[]): string {
+  const pkg = files.find((f) => f.path === 'package.json');
+  return createHash('sha256').update(pkg?.code ?? '').digest('hex');
+}
+
+export type RegenOutcome =
+  | { ok: true; files: GeneratedFile[]; construct: Construct }
+  | { ok: false; problems: ConstructProblem[] };
+
+/** One regen turn, injectable writer so the watch loop is testable. */
+export function regenerate(
+  raw: unknown,
+  sink: { write: (files: GeneratedFile[], dir: string) => void },
+  dir: string,
+  opts: GenerateOptions = {},
+): RegenOutcome {
+  const validated = validateConstruct(raw);
+  if (!validated.ok) return validated;
+  const files = generateProject(validated.construct, opts);
+  sink.write(files, dir);
+  return { ok: true, files, construct: validated.construct };
+}
+
+/**
+ * One watch-triggered turn: read → regenerate → report. Exported so the
+ * "a throw during regen must not kill the loop" guarantee is unit-testable
+ * without spawning fs.watch, npm install or Vite. Never throws — every
+ * failure (invalid JSON, a rejected construct, or an exception from the
+ * sink's real fs writes) is reported via `io` and swallowed here, because
+ * this same body runs inside an fs.watch listener where an uncaught throw
+ * is an uncaught exception that crashes the whole `kai dev` process rather
+ * than leaving the last good preview running.
+ */
+export function regenTurn(
+  readRaw: () => unknown,
+  sink: { write: (files: GeneratedFile[], dir: string) => void },
+  dir: string,
+  opts: GenerateOptions,
+  io: CliIo,
+): void {
+  try {
+    const raw = readRaw();
+    const out = regenerate(raw, sink, dir, opts);
+    if (!out.ok) {
+      io.error('construct rejected — last good preview stays up:');
+      for (const p of out.problems) io.error(`  ${p.path || '(root)'}: ${p.message}`);
+      return;
+    }
+    io.log('construct changed — regenerated; Vite will hot-update the tab.');
+    const notice = accentContrastNotice(out.construct);
+    if (notice) io.log(notice);
+  } catch (err) {
+    io.error(`regen failed (${err instanceof Error ? err.message : String(err)}) — last good preview stays up`);
+  }
+}
+
+const KEY_FILE = '.kai-install-key';
+
+/**
+ * `npm install` in the generated workdir, but only when the emitted
+ * package.json actually changed since the last install (tracked via a hash
+ * written to KEY_FILE) — shared by `kai dev` (on first run and per regen) and
+ * `kai compile`, so there's one install path, not two.
+ */
+export async function ensureInstalled(dir: string, files: GeneratedFile[], io: CliIo): Promise<void> {
+  const key = installKey(files);
+  const keyPath = join(dir, KEY_FILE);
+  const installed = existsSync(keyPath) && readFileSync(keyPath, 'utf8') === key;
+  if (installed) return;
+  io.log(`installing dependencies in ${dir} (first run or deps changed)…`);
+  await new Promise<void>((done, fail) => {
+    const child = spawn('npm', ['install'], { cwd: dir, stdio: 'inherit' });
+    child.on('exit', (code) => (code === 0 ? done() : fail(new Error(`npm install exited ${code}`))));
+  });
+  writeFileSync(keyPath, key);
+}
+
+export async function dev(
+  constructPath: string,
+  opts: { io?: CliIo; uiSpec?: string } = {},
+): Promise<never> {
+  const io = opts.io ?? { log: (s: string) => console.log(s), error: (s: string) => console.error(s) };
+  const abs = resolve(constructPath);
+  const readRaw = (): unknown => JSON.parse(readFileSync(abs, 'utf8'));
+
+  const first = validateConstruct(readRaw());
+  if (!first.ok) {
+    for (const p of first.problems) io.error(`  ${p.path || '(root)'}: ${p.message}`);
+    process.exit(1);
+  }
+  const dir = workDirFor(first.construct.name, process.cwd());
+  const files = generateProject(first.construct, { uiSpec: opts.uiSpec });
+  writeProject(files, dir);
+  const firstNotice = accentContrastNotice(first.construct);
+  if (firstNotice) io.log(firstNotice);
+
+  await ensureInstalled(dir, files, io);
+
+  // Watch the PARENT DIRECTORY, not the file itself: most editors save by
+  // writing a temp file and renaming it over the original, which replaces the
+  // inode. fs.watch(path) on macOS/FSEvents stays bound to the old inode and
+  // goes permanently silent after that first rename — one edit works, every
+  // edit after it is dropped with no error. Watching the directory and
+  // filtering for the construct's basename survives rename-based saves.
+  const base = basename(abs);
+  watch(dirname(abs), (_event, filename) => {
+    if (filename !== base) return;
+    regenTurn(readRaw, { write: writeProject }, dir, { uiSpec: opts.uiSpec }, io);
+  });
+
+  io.log(`previewing <${first.construct.name}> — edit ${abs} and watch the tab.`);
+  const vite = spawn('npm', ['run', 'dev'], { cwd: dir, stdio: 'inherit' });
+  // Explicit cleanup rather than relying on process-group/SIGINT defaults:
+  // whatever ends this process (a fatal error above, Ctrl-C, a signal from
+  // the shell) takes the Vite child down with it instead of orphaning it.
+  const killVite = () => vite.kill();
+  process.once('exit', killVite);
+  process.once('SIGINT', killVite);
+  process.once('SIGTERM', killVite);
+  return new Promise<never>((_, rejectP) => {
+    vite.on('exit', (code) => {
+      rejectP(new Error(`vite dev exited ${code}`));
+      process.exit(code ?? 0);
+    });
+  });
+}

package/src/agent-tooling/construct/fixtures/demo-widget.construct.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://ui.kitn.ai/schemas/construct/v1.json",
+  "name": "demo-widget",
+  "layout": "widget",
+  "provider": { "mode": "mock" },
+  "theme": { "accent": "#e91e63", "mode": "system" }
+}

package/src/agent-tooling/construct/fixtures/ops-console.construct.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://ui.kitn.ai/schemas/construct/v1.json",
+  "name": "ops-console",
+  "layout": "aside",
+  "provider": { "mode": "endpoint", "url": "/api/chat", "wire": "openai" },
+  "theme": { "accent": "#0ea5e9", "mode": "system" },
+  "capabilities": {
+    "starters": ["Deploy payments to production", "Check the canary status"],
+    "attachments": { "accept": ["image/*", "application/pdf"] },
+    "history": { "persistence": "local" }
+  },
+  "cards": [
+    {
+      "name": "deployment_parameters",
+      "schema": {
+        "type": "object",
+        "title": "Deployment parameters",
+        "required": ["region", "ticket"],
+        "properties": {
+          "region": {
+            "type": "string",
+            "title": "Region",
+            "description": "Where the new revision lands first.",
+            "enum": ["us-east-1", "us-west-2", "eu-west-1"],
+            "default": "us-east-1",
+            "x-kai-widget": "select"
+          },
+          "ticket": {
+            "type": "string",
+            "title": "Change ticket",
+            "description": "CHG-#### from the change calendar. Shaped as you type.",
+            "pattern": "^CHG-[0-9]{4}$",
+            "x-kai-placeholder": "CHG-4821",
+            "x-kai-format": "custom",
+            "x-kai-mask": "CHG-####",
+            "x-kai-mask-guide": "CHG-####"
+          }
+        },
+        "x-kai-order": ["region", "ticket"],
+        "x-kai-submitLabel": "Draft the approval"
+      }
+    }
+  ]
+}

package/src/agent-tooling/construct/fixtures/owner-widget.construct.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://ui.kitn.ai/schemas/construct/v1.json",
+  "name": "acme-support",
+  "layout": "widget",
+  "provider": { "mode": "mock" },
+  "userId": "user_123",
+  "header": { "title": "Acme Support" },
+  "theme": { "unreadColor": "#38BDF8" },
+  "empty": {
+    "title": "Hi, we're Acme Support",
+    "description": "Ask us about orders, refunds, and more."
+  },
+  "home": {
+    "greeting": { "title": "Hi from Acme 👋", "subtitle": "Orders, refunds, anything." },
+    "recentConversation": true,
+    "links": [
+      { "label": "Help center", "href": "https://ui.kitn.ai", "description": "Guides and FAQs", "icon": "book-open" },
+      { "label": "Talk to sales", "description": "We reply fast", "icon": "message-circle" }
+    ]
+  },
+  "widget": {
+    "position": "top-start",
+    "defaultOpen": true
+  },
+  "capabilities": {
+    "attachments": { "accept": ["image/*", "application/pdf"] },
+    "history": { "persistence": "local" },
+    "starters": ["Where's my order?", "Request a refund"],
+    "reasoningOpen": true,
+    "conversations": true
+  }
+}