khotan-data 0.1.1 → 0.2.0

package/dist/templates/plug-debugger.tsx

@@ -5,6 +5,7 @@ import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
+import { khotanFetch, isKhotanApiError, ApiErrorState } from "./api-state";
 
 // ============================================================================
 // Plug Debugger — Lightweight Postman for your plugs
@@ -331,6 +332,7 @@ export function PlugDebugger({
 }: PlugDebuggerProps) {
   const [meta, setMeta] = useState<PlugMeta | null>(null);
   const [loading, setLoading] = useState(true);
+  const [metaError, setMetaError] = useState<unknown>(null);
 
   const [method, setMethod] = useState<string>("GET");
   const [path, setPath] = useState("");
@@ -353,15 +355,17 @@ export function PlugDebugger({
   const containerRef = useRef<HTMLDivElement>(null);
 
   const fetchMeta = useCallback(async () => {
+    setLoading(true);
+    setMetaError(null);
     try {
-      const res = await fetch(`${basePath}/debug/${plugName}`);
-      if (!res.ok) {
-        setMeta(null);
-        return;
-      }
-      setMeta(await res.json());
-    } catch {
+      setMeta(await khotanFetch<PlugMeta>(`${basePath}/debug/${plugName}`));
+    } catch (err) {
       setMeta(null);
+      // A 404 means debug is off or the plug isn't registered — handled by the
+      // dedicated "not available" message below. Surface everything else.
+      if (!(isKhotanApiError(err) && err.status === 404)) {
+        setMetaError(err);
+      }
     } finally {
       setLoading(false);
     }
@@ -401,6 +405,10 @@ export function PlugDebugger({
     );
   }
 
+  if (metaError) {
+    return <ApiErrorState error={metaError} onRetry={() => void fetchMeta()} />;
+  }
+
   if (!meta) {
     return (
       <div className="rounded-lg border border-border p-6 text-center">

package/dist/templates/runs-table.tsx

@@ -2,6 +2,7 @@
 
 import { Fragment, useCallback, useEffect, useState } from "react";
 import { RefreshCw } from "lucide-react";
+import { khotanFetch, ApiErrorState } from "./api-state";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
@@ -359,7 +360,7 @@ export function KhotanRunsTable({ pageSize = 10 }: { pageSize?: number } = {}) {
   const [data, setData] = useState<PageResponse<RunLogItem> | null>(null);
   const [offset, setOffset] = useState(0);
   const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
+  const [error, setError] = useState<unknown>(null);
   const [refreshKey, setRefreshKey] = useState(0);
   const [expandedRunId, setExpandedRunId] = useState<string | null>(null);
   const [streamingEnabled, setStreamingEnabled] = useState(false);
@@ -378,20 +379,16 @@ export function KhotanRunsTable({ pageSize = 10 }: { pageSize?: number } = {}) {
       setLoading(true);
       setError(null);
       try {
-        const res = await fetch(
+        const json = await khotanFetch<PageResponse<RunLogItem>>(
           `/api/khotan/runs?limit=${String(pageSize)}&offset=${String(offset)}`,
         );
-        if (!res.ok) {
-          throw new Error("Failed to load runs");
-        }
-        const json = (await res.json()) as PageResponse<RunLogItem>;
         if (!cancelled) {
           setData(json);
           setLastUpdatedAt(new Date().toISOString());
         }
       } catch (err) {
         if (!cancelled) {
-          setError(err instanceof Error ? err.message : "Unknown error");
+          setError(err);
         }
       } finally {
         if (!cancelled) {
@@ -454,138 +451,144 @@ export function KhotanRunsTable({ pageSize = 10 }: { pageSize?: number } = {}) {
       </CardHeader>
       <CardContent className="space-y-4">
         {error ? (
-          <div className="rounded-md border border-destructive/30 bg-destructive/5 p-3 text-sm text-destructive">
-            {error}
-          </div>
+          <ApiErrorState
+            error={error}
+            onRetry={() => setRefreshKey((v) => v + 1)}
+            compact
+          />
         ) : null}
 
-        <Table>
-          <TableHeader>
-            <TableRow>
-              <TableHead>Started</TableHead>
-              <TableHead>Status</TableHead>
-              <TableHead>Source</TableHead>
-              <TableHead>Plug</TableHead>
-              <TableHead>Run Type</TableHead>
-              <TableHead>Counts</TableHead>
-              <TableHead>Workflow</TableHead>
-              <TableHead />
-            </TableRow>
-          </TableHeader>
-          <TableBody>
-            {loading ? (
+        {error ? null : (
+          <Table>
+            <TableHeader>
               <TableRow>
-                <TableCell
-                  colSpan={8}
-                  className="text-sm text-muted-foreground"
-                >
-                  Loading runs...
-                </TableCell>
+                <TableHead>Started</TableHead>
+                <TableHead>Status</TableHead>
+                <TableHead>Source</TableHead>
+                <TableHead>Plug</TableHead>
+                <TableHead>Run Type</TableHead>
+                <TableHead>Counts</TableHead>
+                <TableHead>Workflow</TableHead>
+                <TableHead />
               </TableRow>
-            ) : data?.items.length ? (
-              data.items.map((item) => (
-                <Fragment key={item.id}>
-                  <TableRow>
-                    <TableCell className="text-sm text-muted-foreground">
-                      <div>{formatDateTime(item.startedAt)}</div>
-                      <div className="text-xs">
-                        {item.completedAt
-                          ? `completed ${formatDateTime(item.completedAt)}`
-                          : "in progress"}
-                      </div>
-                    </TableCell>
-                    <TableCell>
-                      <Badge variant={statusVariant[item.status]}>
-                        {statusLabel[item.status]}
-                      </Badge>
-                      {item.error ? (
-                        <div
-                          className="mt-1 max-w-56 truncate text-xs text-destructive"
-                          title={item.error}
-                        >
-                          {item.error}
-                        </div>
-                      ) : null}
-                    </TableCell>
-                    <TableCell className="font-medium">
-                      {formatSource(item)}
-                    </TableCell>
-                    <TableCell className="text-muted-foreground">
-                      {item.plugName ?? "-"}
-                    </TableCell>
-                    <TableCell className="font-mono text-xs">
-                      {item.runType}
-                    </TableCell>
-                    <TableCell className="max-w-64 text-xs text-muted-foreground">
-                      {formatCounts(item)}
-                    </TableCell>
-                    <TableCell className="font-mono text-xs text-muted-foreground">
-                      {item.workflowRunId ?? "-"}
-                    </TableCell>
-                    <TableCell className="text-right">
-                      <Button
-                        variant="outline"
-                        size="sm"
-                        onClick={() =>
-                          setExpandedRunId((current) =>
-                            current === item.id ? null : item.id,
-                          )
-                        }
-                      >
-                        {expandedRunId === item.id ? "Hide" : "Details"}
-                      </Button>
-                    </TableCell>
-                  </TableRow>
-                  {expandedRunId === item.id ? (
+            </TableHeader>
+            <TableBody>
+              {loading ? (
+                <TableRow>
+                  <TableCell
+                    colSpan={8}
+                    className="text-sm text-muted-foreground"
+                  >
+                    Loading runs...
+                  </TableCell>
+                </TableRow>
+              ) : data?.items.length ? (
+                data.items.map((item) => (
+                  <Fragment key={item.id}>
                     <TableRow>
-                      <TableCell colSpan={8}>
-                        <RunDetails
-                          run={item}
-                          streamingEnabled={streamingEnabled}
-                          onChanged={() => setRefreshKey((v) => v + 1)}
-                          onStreamInbound={pulseLiveIndicator}
-                        />
+                      <TableCell className="text-sm text-muted-foreground">
+                        <div>{formatDateTime(item.startedAt)}</div>
+                        <div className="text-xs">
+                          {item.completedAt
+                            ? `completed ${formatDateTime(item.completedAt)}`
+                            : "in progress"}
+                        </div>
+                      </TableCell>
+                      <TableCell>
+                        <Badge variant={statusVariant[item.status]}>
+                          {statusLabel[item.status]}
+                        </Badge>
+                        {item.error ? (
+                          <div
+                            className="mt-1 max-w-56 truncate text-xs text-destructive"
+                            title={item.error}
+                          >
+                            {item.error}
+                          </div>
+                        ) : null}
+                      </TableCell>
+                      <TableCell className="font-medium">
+                        {formatSource(item)}
+                      </TableCell>
+                      <TableCell className="text-muted-foreground">
+                        {item.plugName ?? "-"}
+                      </TableCell>
+                      <TableCell className="font-mono text-xs">
+                        {item.runType}
+                      </TableCell>
+                      <TableCell className="max-w-64 text-xs text-muted-foreground">
+                        {formatCounts(item)}
+                      </TableCell>
+                      <TableCell className="font-mono text-xs text-muted-foreground">
+                        {item.workflowRunId ?? "-"}
+                      </TableCell>
+                      <TableCell className="text-right">
+                        <Button
+                          variant="outline"
+                          size="sm"
+                          onClick={() =>
+                            setExpandedRunId((current) =>
+                              current === item.id ? null : item.id,
+                            )
+                          }
+                        >
+                          {expandedRunId === item.id ? "Hide" : "Details"}
+                        </Button>
                       </TableCell>
                     </TableRow>
-                  ) : null}
-                </Fragment>
-              ))
-            ) : (
-              <TableRow>
-                <TableCell
-                  colSpan={8}
-                  className="text-sm text-muted-foreground"
-                >
-                  No runs recorded yet.
-                </TableCell>
-              </TableRow>
-            )}
-          </TableBody>
-        </Table>
+                    {expandedRunId === item.id ? (
+                      <TableRow>
+                        <TableCell colSpan={8}>
+                          <RunDetails
+                            run={item}
+                            streamingEnabled={streamingEnabled}
+                            onChanged={() => setRefreshKey((v) => v + 1)}
+                            onStreamInbound={pulseLiveIndicator}
+                          />
+                        </TableCell>
+                      </TableRow>
+                    ) : null}
+                  </Fragment>
+                ))
+              ) : (
+                <TableRow>
+                  <TableCell
+                    colSpan={8}
+                    className="text-sm text-muted-foreground"
+                  >
+                    No runs recorded yet.
+                  </TableCell>
+                </TableRow>
+              )}
+            </TableBody>
+          </Table>
+        )}
 
-        <div className="flex items-center justify-between gap-3">
-          <p className="text-sm text-muted-foreground">
-            Page {Math.floor(offset / pageSize) + 1}
-          </p>
-          <div className="flex items-center gap-2">
-            <Button
-              variant="outline"
-              size="sm"
-              disabled={offset === 0 || loading}
-              onClick={() => setOffset(Math.max(offset - pageSize, 0))}
-            >
-              Previous
-            </Button>
-            <Button
-              variant="outline"
-              size="sm"
-              disabled={!data?.page.hasMore || loading}
-              onClick={() => setOffset(offset + pageSize)}
-            >
-              Next
-            </Button>
+        {error ? null : (
+          <div className="flex items-center justify-between gap-3">
+            <p className="text-sm text-muted-foreground">
+              Page {Math.floor(offset / pageSize) + 1}
+            </p>
+            <div className="flex items-center gap-2">
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={offset === 0 || loading}
+                onClick={() => setOffset(Math.max(offset - pageSize, 0))}
+              >
+                Previous
+              </Button>
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={!data?.page.hasMore || loading}
+                onClick={() => setOffset(offset + pageSize)}
+              >
+                Next
+              </Button>
+            </div>
           </div>
-        </div>
+        )}
       </CardContent>
     </Card>
   );

package/dist/templates/skill-setup.md

@@ -90,9 +90,44 @@ The schema command auto-detects your Drizzle schema directory, updates `drizzle.
 |----------|----------|---------|
 | `DATABASE_URL` | Yes | Postgres connection (used by Drizzle) |
 | `KHOTAN_SECRET` | For variables | AES-256-GCM key for encrypting plug vars |
-| `KHOTAN_DEBUG` | For debugging | Enables `/debug/*` routes and the `plug` CLI (`probe` alias) |
+| `KHOTAN_DEBUG` | For debugging | Enables `/debug/*` routes and the `plug` CLI (`probe` alias). Automatically disabled when `NODE_ENV=production` |
 | `KHOTAN_WEBHOOK_URL` | For webhooks | Public URL for wire callbacks |
-| `CRON_SECRET` | For production cron | Protects the built-in `/api/khotan/cron` dispatcher route |
+| `CRON_SECRET` | For production cron | Protects the built-in `/api/khotan/cron` dispatcher route. The route fails closed in production when this is unset |
+
+## Securing the Management API
+
+The management API (`/api/khotan/*`) and the Hub dashboard expose plug
+credentials and operational controls. **They are public unless you gate them.**
+
+Pass an `authorize` hook to `khotan({ ... })`. It receives the raw `Request` and
+returns `true` to allow the request or `false` to reject it with `401`. It
+composes directly with session libraries like better-auth:
+
+```typescript
+import { khotan, drizzleAdapter } from "khotan-data/factory";
+import { auth } from "@/lib/auth";
+import { db } from "@/db";
+
+const khotanData = khotan({
+  adapter: drizzleAdapter(db),
+  authorize: async (request) => {
+    const session = await auth.api.getSession({ headers: request.headers });
+    return Boolean(session?.user); // or: session?.user?.role === "admin"
+  },
+  plugs: [/* ... */],
+});
+```
+
+Notes:
+- `authorize` is **not** a replacement for `KHOTAN_SECRET` — that key only
+  encrypts credentials at rest, it does not authenticate requests.
+- Inbound webhooks (`POST /webhook/:plug`, verified per-plug via `onVerify`),
+  the cron dispatcher (`CRON_SECRET`), and debug routes (`KHOTAN_DEBUG`,
+  non-production only) are exempt from `authorize` automatically.
+- Also protect the Hub dashboard page (e.g. `/config`) with your app's
+  middleware — `authorize` only guards the API, not your React pages.
+- Without `authorize`, khotan logs a startup warning. Always configure it
+  before deploying.
 
 ## Next.js Config
 

package/dist/templates/topology-canvas.tsx

@@ -18,6 +18,7 @@ import {
   type NodeProps,
 } from "@xyflow/react";
 import "@xyflow/react/dist/style.css";
+import { khotanFetch, ApiErrorState } from "./api-state";
 import { Badge } from "@/components/ui/badge";
 import {
   Card,
@@ -1056,8 +1057,9 @@ function TopologyCanvasInner() {
   const [nodes, setNodes, onNodesChange] = useNodesState<TopologyNodeData>([]);
   const [edges, setEdges, onEdgesChange] = useEdgesState([]);
   const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
+  const [error, setError] = useState<unknown>(null);
   const [lastUpdatedAt, setLastUpdatedAt] = useState<string | null>(null);
+  const [refreshKey, setRefreshKey] = useState(0);
 
   useEffect(() => {
     let cancelled = false;
@@ -1068,30 +1070,22 @@ function TopologyCanvasInner() {
           setError(null);
         }
 
-        const [plugsRes, flowsRes, runsRes] = await Promise.all([
-          fetch("/api/khotan/plugs"),
-          fetch("/api/khotan/flows"),
-          fetch("/api/khotan/runs?limit=100"),
+        const [plugs, flows, runsRaw] = await Promise.all([
+          khotanFetch<PlugRecord[]>("/api/khotan/plugs"),
+          khotanFetch<FlowRecord[]>("/api/khotan/flows"),
+          khotanFetch<unknown>("/api/khotan/runs?limit=100"),
         ]);
 
-        if (!plugsRes.ok || !flowsRes.ok || !runsRes.ok) {
-          throw new Error("Failed to load topology data from /api/khotan");
-        }
-
-        const plugs = (await plugsRes.json()) as PlugRecord[];
-        const flows = (await flowsRes.json()) as FlowRecord[];
-        const runs = normalizeRuns(await runsRes.json());
+        const runs = normalizeRuns(runsRaw);
 
         const webhookGroups = await Promise.all(
           plugs.map(async (plug) => {
             try {
-              const res = await fetch(
+              const handlers = await khotanFetch<
+                Array<Omit<WebhookHandlerRecord, "plugName">>
+              >(
                 `/api/khotan/webhook-handlers/${encodeURIComponent(plug.name)}`,
               );
-              if (!res.ok) return [] as WebhookHandlerRecord[];
-              const handlers = (await res.json()) as Array<
-                Omit<WebhookHandlerRecord, "plugName">
-              >;
               return handlers.map((handler) => ({
                 ...handler,
                 plugName: plug.name,
@@ -1113,11 +1107,7 @@ function TopologyCanvasInner() {
         setLastUpdatedAt(new Date().toISOString());
       } catch (loadError) {
         if (!cancelled) {
-          setError(
-            loadError instanceof Error
-              ? loadError.message
-              : "Unknown topology load failure",
-          );
+          setError(loadError);
         }
       } finally {
         if (!cancelled) {
@@ -1135,7 +1125,7 @@ function TopologyCanvasInner() {
       cancelled = true;
       window.clearInterval(interval);
     };
-  }, []);
+  }, [refreshKey]);
 
   const model = useMemo(() => {
     return snapshot ? buildTopologyModel(snapshot) : null;
@@ -1180,19 +1170,18 @@ function TopologyCanvasInner() {
 
   if (error) {
     return (
-      <Card className="border-red-200 bg-white/80 shadow-xl backdrop-blur">
+      <Card className="border-white/70 bg-white/80 shadow-xl backdrop-blur">
         <CardHeader>
           <CardTitle>Topology Canvas</CardTitle>
           <CardDescription>
             Could not load the graph from the local Khotan API.
           </CardDescription>
         </CardHeader>
-        <CardContent className="space-y-3 text-sm">
-          <p className="text-red-600">{error}</p>
-          <p className="text-slate-500">
-            Make sure the catch-all Khotan route is mounted and your dev server
-            is running.
-          </p>
+        <CardContent>
+          <ApiErrorState
+            error={error}
+            onRetry={() => setRefreshKey((v) => v + 1)}
+          />
         </CardContent>
       </Card>
     );

package/dist/templates/var-panel.tsx

@@ -6,6 +6,7 @@ import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
+import { khotanFetch, ApiErrorState } from "./api-state";
 
 // ============================================================================
 // Var Panel — UI for managing plug variables
@@ -44,6 +45,7 @@ export function VarPanel({
   const [configured, setConfigured] = useState(false);
   const [loading, setLoading] = useState(true);
   const [saving, setSaving] = useState(false);
+  const [loadError, setLoadError] = useState<unknown>(null);
   const [error, setError] = useState<string | null>(null);
   const [success, setSuccess] = useState<string | null>(null);
   const [editing, setEditing] = useState(false);
@@ -52,21 +54,23 @@ export function VarPanel({
   );
 
   const fetchVariables = useCallback(async () => {
+    setLoading(true);
+    setLoadError(null);
     try {
-      const res = await fetch(`${basePath}/variables/${plugName}`);
-      if (!res.ok) {
-        setFields([]);
-        setConfigured(false);
-        return;
-      }
-      const data = await res.json();
+      const data = await khotanFetch<{
+        fields?: VarField[];
+        values?: Record<string, string>;
+        configured?: boolean;
+      }>(`${basePath}/variables/${plugName}`);
       setFields((data.fields ?? []).filter((f: VarField) => !f.hidden));
       setValues(data.values ?? {});
       setConfigured(data.configured ?? false);
-      setFormValues(data.configured ? data.values : {});
+      setFormValues(data.configured ? (data.values ?? {}) : {});
       setError(null);
-    } catch {
-      setError("Failed to load variables");
+    } catch (err) {
+      setFields([]);
+      setConfigured(false);
+      setLoadError(err);
     } finally {
       setLoading(false);
     }
@@ -144,6 +148,25 @@ export function VarPanel({
     );
   }
 
+  if (loadError) {
+    return (
+      <Card>
+        <CardHeader className="pb-2">
+          <CardTitle className="text-sm font-medium capitalize">
+            {displayName} Variables
+          </CardTitle>
+        </CardHeader>
+        <CardContent>
+          <ApiErrorState
+            error={loadError}
+            onRetry={() => void fetchVariables()}
+            compact
+          />
+        </CardContent>
+      </Card>
+    );
+  }
+
   if (fields.length === 0) return null;
 
   return (