@cairnvibe/sdk 0.1.0

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@cairnvibe/sdk",
+  "version": "0.1.0",
+  "description": "In-app AI copilot — <Copilot/> for React/Next.js, <cairn-widget> for any framework — plus the server handlers and realtime voice relay behind them.",
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/Vikasverma9515/cairn.git", "directory": "packages/sdk" },
+  "homepage": "https://github.com/Vikasverma9515/cairn#readme",
+  "bugs": "https://github.com/Vikasverma9515/cairn/issues",
+  "type": "module",
+  "bin": {
+    "cairn-realtime": "dist/realtime-cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.tsx",
+    "./server": "./dist/server.js",
+    "./dashboard": "./dist/dashboard.js",
+    "./dashboard-sqlite": "./dist/dashboard-sqlite.js",
+    "./transcribe-server": "./dist/transcribe-server.js",
+    "./speak-server": "./dist/speak-server.js",
+    "./realtime-server": "./dist/realtime-server.js",
+    "./widget": "./dist/cairn-widget.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && echo '{\"type\":\"commonjs\"}' > dist/package.json && npm run build:widget",
+    "build:widget": "esbuild src/web-component.ts --bundle --minify --format=iife --outfile=dist/cairn-widget.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "next": ">=13",
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.32.1",
+    "@cairnvibe/core": "^0.1.0",
+    "better-sqlite3": "^13.0.3",
+    "groq-sdk": "^1.6.0",
+    "lucide-react": "^1.37.0",
+    "ws": "^8.21.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/react": "^18.3.3",
+    "@types/ws": "^8.18.1",
+    "esbuild": "^0.21.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.9"
+  }
+}

package/src/context-collector.ts

@@ -0,0 +1,21 @@
+// Collects the minimal, privacy-conscious context the runtime sends to
+// /api/copilot: the current route (passed in separately by the caller) and
+// the ids of interactive elements currently visible in the viewport. Never
+// sends full DOM, page text, or anything not covered by `data-ai`.
+
+export function collectVisible(): string[] {
+  if (typeof document === "undefined" || typeof window === "undefined") return [];
+
+  const elements = document.querySelectorAll<HTMLElement>("[data-ai]");
+  const ids: string[] = [];
+
+  elements.forEach((el) => {
+    const rect = el.getBoundingClientRect();
+    const inViewport = rect.bottom > 0 && rect.top < window.innerHeight && rect.right > 0 && rect.left < window.innerWidth;
+    if (!inViewport) return;
+    const id = el.getAttribute("data-ai");
+    if (id) ids.push(id);
+  });
+
+  return ids;
+}

package/src/dashboard-sqlite.ts

@@ -0,0 +1,52 @@
+// A real, durable MissesStore — same interface as the in-memory default in
+// dashboard.ts, but backed by SQLite so failure-dashboard data survives
+// restarts and redeploys. This is what "swap for a real one" (dashboard.ts)
+// actually looks like, not a toy.
+
+import fs from "node:fs";
+import path from "node:path";
+import Database from "better-sqlite3";
+import type { MissesStore, MissRecord } from "./dashboard";
+
+// Namespaced (not just "misses") so this can safely share a Database
+// connection/file with a consumer's own tables (the demo app does this).
+const TABLE = "cairn_misses";
+
+/**
+ * @param target Either a file path (opened/created, parent dir made if
+ * needed) or an already-open better-sqlite3 `Database` — pass an open
+ * connection to share it with your own tables instead of opening a second file.
+ */
+export function createSqliteMissesStore(target: string | Database.Database): MissesStore {
+  const db = typeof target === "string" ? openFile(target) : target;
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS ${TABLE} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      attempted TEXT NOT NULL,
+      route TEXT NOT NULL,
+      at TEXT NOT NULL
+    )
+  `);
+
+  const insert = db.prepare(`INSERT INTO ${TABLE} (attempted, route, at) VALUES (?, ?, ?)`);
+  const selectAll = db.prepare(`SELECT attempted, route, at FROM ${TABLE} ORDER BY id ASC`);
+  const deleteAll = db.prepare(`DELETE FROM ${TABLE}`);
+
+  return {
+    report(context) {
+      insert.run(context.attempted, context.route, new Date().toISOString());
+    },
+    list() {
+      return selectAll.all() as MissRecord[];
+    },
+    clear() {
+      deleteAll.run();
+    },
+  };
+}
+
+function openFile(filePath: string): Database.Database {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  return new Database(filePath);
+}

package/src/dashboard.ts

@@ -0,0 +1,82 @@
+// Server-side aggregation of the element-ladder misses the client already
+// logs to localStorage (see element-ladder.ts). Opt-in: the Copilot widget
+// only reports here if `reportMissesEndpoint` is set. Same
+// build-a-handler-function shape as `createCopilotHandler` in server.ts.
+
+export interface MissRecord {
+  attempted: string;
+  route: string;
+  at: string;
+}
+
+export interface MissesStore {
+  report(context: { attempted: string; route: string }): void;
+  list(): MissRecord[];
+  clear(): void;
+}
+
+/** In-memory store — fine for a demo or a single-instance deployment. Swap for a real one via the same interface. */
+export function createMissesStore(): MissesStore {
+  const records: MissRecord[] = [];
+  return {
+    report(context) {
+      records.push({ ...context, at: new Date().toISOString() });
+    },
+    list() {
+      return [...records];
+    },
+    clear() {
+      records.length = 0;
+    },
+  };
+}
+
+export interface MissesSummary {
+  attempted: string;
+  route: string;
+  count: number;
+  lastSeen: string;
+}
+
+export function summarizeMisses(records: MissRecord[]): MissesSummary[] {
+  const groups = new Map<string, MissesSummary>();
+  for (const r of records) {
+    const key = `${r.route}::${r.attempted}`;
+    const existing = groups.get(key);
+    if (existing) {
+      existing.count += 1;
+      if (r.at > existing.lastSeen) existing.lastSeen = r.at;
+    } else {
+      groups.set(key, { attempted: r.attempted, route: r.route, count: 1, lastSeen: r.at });
+    }
+  }
+  return Array.from(groups.values()).sort((a, b) => b.count - a.count);
+}
+
+function isValidMissReport(body: unknown): body is { attempted: string; route: string } {
+  if (typeof body !== "object" || body === null) return false;
+  const candidate = body as Record<string, unknown>;
+  return typeof candidate.attempted === "string" && typeof candidate.route === "string";
+}
+
+export interface MissesHandler {
+  /** Wire to `POST` — the widget calls this on every lookup miss. */
+  post(body: unknown): Promise<{ status: number; body: { ok: true } | { error: string } }>;
+  /** Wire to `GET` — returns misses grouped by route+target with counts, most frequent first. */
+  get(): Promise<{ status: number; body: MissesSummary[] }>;
+}
+
+export function createMissesHandler(store: MissesStore): MissesHandler {
+  return {
+    async post(body: unknown) {
+      if (!isValidMissReport(body)) {
+        return { status: 400, body: { error: "invalid miss report" } };
+      }
+      store.report(body);
+      return { status: 200, body: { ok: true } };
+    },
+    async get() {
+      return { status: 200, body: summarizeMisses(store.list()) };
+    },
+  };
+}

package/src/element-ladder.ts

@@ -0,0 +1,67 @@
+// The 4-step Element Ladder (BUILD_PLAN.md invariant #3): a lookup failure
+// must degrade to explain-only, never guess and click the wrong thing.
+//
+//   1. data-ai="..."     — exact, authoritative
+//   2. aria-label / role — accessible-name fallback
+//   3. visible text      — last resort, exact then substring match
+//   4. FAIL               — caller degrades to explain + logs the miss
+
+export function findElement(target: string): HTMLElement | null {
+  if (typeof document === "undefined") return null;
+
+  const byDataAi = document.querySelector<HTMLElement>(`[data-ai="${cssEscape(target)}"]`);
+  if (byDataAi) return byDataAi;
+
+  const byAriaLabel = document.querySelector<HTMLElement>(`[aria-label="${cssEscape(target)}"]`);
+  if (byAriaLabel) return byAriaLabel;
+
+  const byRole = document.querySelector<HTMLElement>(`[role="${cssEscape(target)}"]`);
+  if (byRole) return byRole;
+
+  const candidates = document.querySelectorAll<HTMLElement>(
+    "button, a, [role='button'], input[type='submit'], input[type='button']",
+  );
+  const normalizedTarget = normalize(target);
+
+  for (const el of Array.from(candidates)) {
+    if (normalize(el.textContent ?? "") === normalizedTarget) return el;
+  }
+  for (const el of Array.from(candidates)) {
+    if (normalize(el.textContent ?? "").includes(normalizedTarget)) return el;
+  }
+
+  return null;
+}
+
+export function highlightElement(el: HTMLElement, glowMs = 4000): void {
+  el.scrollIntoView({ behavior: "smooth", block: "center" });
+  el.classList.add("cairn-glow");
+  window.setTimeout(() => el.classList.remove("cairn-glow"), glowMs);
+}
+
+export interface MissContext {
+  attempted: string;
+  route: string;
+}
+
+const MISS_LOG_KEY = "cairn:misses";
+const MISS_LOG_LIMIT = 200;
+
+export function logMiss(context: MissContext): void {
+  try {
+    const existingRaw = window.localStorage.getItem(MISS_LOG_KEY);
+    const existing: (MissContext & { at: string })[] = existingRaw ? JSON.parse(existingRaw) : [];
+    existing.push({ ...context, at: new Date().toISOString() });
+    window.localStorage.setItem(MISS_LOG_KEY, JSON.stringify(existing.slice(-MISS_LOG_LIMIT)));
+  } catch {
+    // localStorage unavailable (SSR, private mode, quota) — never let logging break the UI.
+  }
+}
+
+function normalize(s: string): string {
+  return s.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+function cssEscape(s: string): string {
+  return s.replace(/["\\]/g, "\\$&");
+}