@object-ui/app-shell 6.2.3 → 7.0.0

package/dist/views/metadata-admin/external/ExternalDatasourcePanel.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * ExternalDatasourcePanel — the Studio home for an External Datasource
+ * Federation datasource (ADR-0015 §6.4).
+ *
+ * Rendered inside `DatasourcePreview` whenever a datasource is federated
+ * (`schemaMode !== 'managed'`). It groups the buildable P5 surfaces:
+ *
+ *   • Tables      — browse remote tables + import them as Objects.
+ *   • Validation  — check declared objects against the live remote schema
+ *                   (doubles as on-demand drift detection).
+ *
+ * A header strip offers "Refresh catalog" (re-introspect + persist the
+ * `external_catalog` snapshot) and shows when the snapshot was last taken.
+ *
+ * The connection wizard (drivers / credentials / secrets) intentionally lives
+ * in System Settings, not here — this surface is metadata-design work.
+ */
+import * as React from 'react';
+import { DatabaseZap, RefreshCw, Loader2, Clock } from 'lucide-react';
+import { Button, Tabs, TabsList, TabsTrigger, TabsContent, } from '@object-ui/components';
+import { SchemaBrowser } from './SchemaBrowser';
+import { ValidationPanel } from './ValidationPanel';
+import { refreshCatalog, ExternalServiceUnavailableError, } from './api';
+export function ExternalDatasourcePanel({ datasource, schemaMode, allowWrites, }) {
+    const [catalog, setCatalog] = React.useState(null);
+    const [refreshing, setRefreshing] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const handleRefresh = React.useCallback(async () => {
+        if (!datasource)
+            return;
+        setRefreshing(true);
+        setError(null);
+        try {
+            const c = await refreshCatalog(datasource);
+            setCatalog(c);
+        }
+        catch (err) {
+            setError(err instanceof ExternalServiceUnavailableError
+                ? 'Federation is not enabled on this server.'
+                : err instanceof Error
+                    ? err.message
+                    : String(err));
+        }
+        finally {
+            setRefreshing(false);
+        }
+    }, [datasource]);
+    // Unsaved datasource: the REST routes key off a saved `:name`, so nothing
+    // can be introspected yet. Guide the user to save first.
+    if (!datasource) {
+        return (_jsx("div", { className: "rounded border bg-muted/20 p-3 text-xs text-muted-foreground", children: "Save the datasource first to browse its remote tables and validate federated objects." }));
+    }
+    return (_jsxs("div", { className: "rounded border bg-background", children: [_jsxs("div", { className: "flex flex-wrap items-center gap-x-3 gap-y-1.5 border-b bg-muted/30 px-3 py-2", children: [_jsxs("span", { className: "inline-flex items-center gap-1.5 text-xs font-medium", children: [_jsx(DatabaseZap, { className: "h-4 w-4 text-sky-500" }), "External Datasource"] }), _jsx("span", { className: "rounded border bg-background px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-wider text-muted-foreground", children: schemaMode ?? 'external' }), _jsx("span", { className: `rounded px-1.5 py-0.5 text-[10px] uppercase tracking-wider ${allowWrites
+                            ? 'bg-amber-100 text-amber-800 dark:bg-amber-950/40 dark:text-amber-300'
+                            : 'bg-muted text-muted-foreground'}`, children: allowWrites ? 'writes allowed' : 'read-only' }), _jsxs("div", { className: "ml-auto flex items-center gap-2", children: [catalog?.snapshotAt && (_jsxs("span", { className: "inline-flex items-center gap-1 text-[11px] text-muted-foreground", children: [_jsx(Clock, { className: "h-3 w-3" }), "snapshot ", formatSnapshot(catalog.snapshotAt)] })), _jsxs(Button, { variant: "outline", size: "sm", onClick: () => void handleRefresh(), disabled: refreshing, children: [refreshing ? (_jsx(Loader2, { className: "h-3.5 w-3.5 animate-spin" })) : (_jsx(RefreshCw, { className: "h-3.5 w-3.5" })), _jsx("span", { className: "ml-1.5", children: "Refresh catalog" })] })] })] }), error && (_jsx("div", { className: "border-b border-destructive/40 bg-destructive/5 px-3 py-2 text-xs text-destructive", children: error })), _jsxs(Tabs, { defaultValue: "tables", className: "p-3", children: [_jsxs(TabsList, { children: [_jsx(TabsTrigger, { value: "tables", children: "Tables" }), _jsx(TabsTrigger, { value: "validation", children: "Validation" })] }), _jsx(TabsContent, { value: "tables", className: "mt-3", children: _jsx(SchemaBrowser, { datasource: datasource }) }), _jsx(TabsContent, { value: "validation", className: "mt-3", children: _jsx(ValidationPanel, { datasource: datasource }) })] })] }));
+}
+function formatSnapshot(iso) {
+    const t = new Date(iso).getTime();
+    if (Number.isNaN(t))
+        return iso;
+    try {
+        return new Date(t).toLocaleString();
+    }
+    catch {
+        return iso;
+    }
+}

package/dist/views/metadata-admin/external/ImportObjectDialog.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ImportObjectDialog — the mapping/import step of the external-datasource
+ * Studio surface (ADR-0015 §6.4 "Mapping editor").
+ *
+ * Flow:
+ *   1. On open, POST `…/tables/:remote/draft` → an `ObjectDraft`
+ *      (structured definition + reviewable `*.object.ts` source).
+ *   2. Show the suggested object name, any `// REVIEW:` columns the
+ *      type-compat matrix flagged as lossy/unknown, and the generated
+ *      source.
+ *   3. "Import as Object" PUTs the draft's definition to the metadata
+ *      store (`/meta/object/:name`) and reports success.
+ *
+ * The dialog never mutates the remote schema — it only reads the draft and
+ * writes a local Object definition.
+ */
+import * as React from 'react';
+import { type RemoteTable } from './api';
+export interface ImportObjectDialogProps {
+    datasource: string;
+    table: RemoteTable | null;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Notified after a successful import (so the parent can refresh). */
+    onImported?: (objectName: string) => void;
+}
+export declare function ImportObjectDialog({ datasource, table, open, onOpenChange, onImported, }: ImportObjectDialogProps): React.JSX.Element;

package/dist/views/metadata-admin/external/ImportObjectDialog.js

@@ -0,0 +1,77 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * ImportObjectDialog — the mapping/import step of the external-datasource
+ * Studio surface (ADR-0015 §6.4 "Mapping editor").
+ *
+ * Flow:
+ *   1. On open, POST `…/tables/:remote/draft` → an `ObjectDraft`
+ *      (structured definition + reviewable `*.object.ts` source).
+ *   2. Show the suggested object name, any `// REVIEW:` columns the
+ *      type-compat matrix flagged as lossy/unknown, and the generated
+ *      source.
+ *   3. "Import as Object" PUTs the draft's definition to the metadata
+ *      store (`/meta/object/:name`) and reports success.
+ *
+ * The dialog never mutates the remote schema — it only reads the draft and
+ * writes a local Object definition.
+ */
+import * as React from 'react';
+import { AlertTriangle, Database, FileCode2, Loader2, CheckCircle2 } from 'lucide-react';
+import { Button, Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, } from '@object-ui/components';
+import { generateObjectDraft, importObjectDraft, ExternalServiceUnavailableError, } from './api';
+export function ImportObjectDialog({ datasource, table, open, onOpenChange, onImported, }) {
+    const [phase, setPhase] = React.useState('loading');
+    const [draft, setDraft] = React.useState(null);
+    const [error, setError] = React.useState(null);
+    // Load the draft whenever the dialog opens for a (new) table.
+    React.useEffect(() => {
+        if (!open || !table)
+            return;
+        let cancelled = false;
+        setPhase('loading');
+        setDraft(null);
+        setError(null);
+        (async () => {
+            try {
+                const d = await generateObjectDraft(datasource, table.name, {
+                    remoteSchema: table.schema,
+                });
+                if (cancelled)
+                    return;
+                setDraft(d);
+                setPhase('ready');
+            }
+            catch (err) {
+                if (cancelled)
+                    return;
+                setError(err instanceof ExternalServiceUnavailableError
+                    ? 'Federation is not enabled on this server.'
+                    : err instanceof Error
+                        ? err.message
+                        : String(err));
+                setPhase('error');
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [open, table, datasource]);
+    const handleImport = React.useCallback(async () => {
+        if (!draft)
+            return;
+        setPhase('importing');
+        setError(null);
+        try {
+            await importObjectDraft(draft);
+            setPhase('done');
+            onImported?.(draft.name);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : String(err));
+            setPhase('ready');
+        }
+    }, [draft, onImported]);
+    const remoteLabel = table ? [table.schema, table.name].filter(Boolean).join('.') : '';
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { className: "max-w-2xl", children: [_jsxs(DialogHeader, { children: [_jsxs(DialogTitle, { className: "flex items-center gap-2", children: [_jsx(Database, { className: "h-4 w-4" }), "Import as Object"] }), _jsxs(DialogDescription, { children: ["Map remote table ", _jsx("span", { className: "font-mono", children: remoteLabel }), " into an ObjectStack object bound to ", _jsx("span", { className: "font-mono", children: datasource }), ". The remote schema is never modified."] })] }), phase === 'loading' && (_jsxs("div", { className: "flex items-center gap-2 py-8 justify-center text-sm text-muted-foreground", children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin" }), " Generating draft\u2026"] })), phase === 'error' && (_jsx("div", { className: "rounded border border-destructive/40 bg-destructive/5 p-3 text-sm text-destructive", children: error })), phase === 'done' && draft && (_jsxs("div", { className: "flex flex-col items-center gap-2 py-8 text-center", children: [_jsx(CheckCircle2, { className: "h-8 w-8 text-emerald-500" }), _jsxs("div", { className: "text-sm", children: ["Imported object ", _jsx("span", { className: "font-mono font-medium", children: draft.name }), "."] }), _jsx("div", { className: "text-xs text-muted-foreground", children: "Review its binding and run validation to confirm it matches the remote table." })] })), (phase === 'ready' || phase === 'importing') && draft && (_jsxs("div", { className: "space-y-3", children: [_jsxs("div", { className: "flex flex-wrap items-baseline gap-x-2 text-sm", children: [_jsx("span", { className: "text-muted-foreground", children: "Object name" }), _jsx("span", { className: "font-mono font-medium", children: draft.name })] }), error && (_jsx("div", { className: "rounded border border-destructive/40 bg-destructive/5 p-2 text-xs text-destructive", children: error })), draft.review.length > 0 && (_jsxs("div", { className: "rounded border border-amber-300 bg-amber-50 dark:bg-amber-950/20 p-2.5", children: [_jsxs("div", { className: "flex items-center gap-1.5 text-xs font-medium text-amber-800 dark:text-amber-300", children: [_jsx(AlertTriangle, { className: "h-3.5 w-3.5" }), draft.review.length, " column", draft.review.length === 1 ? '' : 's', " need review"] }), _jsx("ul", { className: "mt-1.5 space-y-1 text-[11px] text-amber-900/90 dark:text-amber-200/80", children: draft.review.map((r) => (_jsxs("li", { className: "flex flex-wrap gap-x-1.5", children: [_jsx("span", { className: "font-mono", children: r.column }), _jsxs("span", { className: "text-amber-700/70 dark:text-amber-400/70", children: ["(", r.remoteType, ")"] }), _jsxs("span", { children: ["\u2014 ", r.note] })] }, r.column))) })] })), _jsxs("div", { className: "space-y-1.5", children: [_jsxs("div", { className: "flex items-center gap-1.5 text-[11px] font-medium text-muted-foreground uppercase tracking-wider", children: [_jsx(FileCode2, { className: "h-3 w-3" }), " Generated source"] }), _jsx("pre", { className: "max-h-64 overflow-auto rounded border bg-muted/30 p-2.5 text-[11px] leading-relaxed font-mono", children: draft.source })] })] })), _jsx(DialogFooter, { children: phase === 'done' ? (_jsx(Button, { onClick: () => onOpenChange(false), children: "Close" })) : (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "ghost", onClick: () => onOpenChange(false), disabled: phase === 'importing', children: "Cancel" }), _jsx(Button, { onClick: handleImport, disabled: phase !== 'ready' || !draft, children: phase === 'importing' ? (_jsxs("span", { className: "flex items-center gap-1.5", children: [_jsx(Loader2, { className: "h-3.5 w-3.5 animate-spin" }), " Importing\u2026"] })) : ('Import as Object') })] })) })] }) }));
+}

package/dist/views/metadata-admin/external/SchemaBrowser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SchemaBrowser — the "schema browser" surface of the external-datasource
+ * Studio panel (ADR-0015 §6.4).
+ *
+ * Lists the remote tables a federated datasource exposes (filtered server-side
+ * by `external.allowedSchemas`), with an optional client-side text filter and
+ * a per-table "Import" action that opens {@link ImportObjectDialog}.
+ *
+ * Data is fetched on demand (mount + explicit "Refresh"), never on a timer —
+ * introspecting a warehouse is expensive, so the user stays in control.
+ */
+import * as React from 'react';
+export interface SchemaBrowserProps {
+    datasource: string;
+}
+export declare function SchemaBrowser({ datasource }: SchemaBrowserProps): React.JSX.Element;

package/dist/views/metadata-admin/external/SchemaBrowser.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * SchemaBrowser — the "schema browser" surface of the external-datasource
+ * Studio panel (ADR-0015 §6.4).
+ *
+ * Lists the remote tables a federated datasource exposes (filtered server-side
+ * by `external.allowedSchemas`), with an optional client-side text filter and
+ * a per-table "Import" action that opens {@link ImportObjectDialog}.
+ *
+ * Data is fetched on demand (mount + explicit "Refresh"), never on a timer —
+ * introspecting a warehouse is expensive, so the user stays in control.
+ */
+import * as React from 'react';
+import { RefreshCw, Loader2, Search, Table2, Download, Columns3 } from 'lucide-react';
+import { Button } from '@object-ui/components';
+import { listRemoteTables, ExternalServiceUnavailableError, } from './api';
+import { ImportObjectDialog } from './ImportObjectDialog';
+export function SchemaBrowser({ datasource }) {
+    const [state, setState] = React.useState('idle');
+    const [tables, setTables] = React.useState([]);
+    const [error, setError] = React.useState(null);
+    const [query, setQuery] = React.useState('');
+    const [importing, setImporting] = React.useState(null);
+    const [dialogOpen, setDialogOpen] = React.useState(false);
+    const load = React.useCallback(async () => {
+        setState('loading');
+        setError(null);
+        try {
+            const rows = await listRemoteTables(datasource);
+            setTables(rows);
+            setState('loaded');
+        }
+        catch (err) {
+            if (err instanceof ExternalServiceUnavailableError) {
+                setState('unavailable');
+            }
+            else {
+                setError(err instanceof Error ? err.message : String(err));
+                setState('error');
+            }
+        }
+    }, [datasource]);
+    React.useEffect(() => {
+        void load();
+    }, [load]);
+    const filtered = React.useMemo(() => {
+        const q = query.trim().toLowerCase();
+        if (!q)
+            return tables;
+        return tables.filter((t) => {
+            const label = [t.schema, t.name].filter(Boolean).join('.').toLowerCase();
+            return label.includes(q);
+        });
+    }, [tables, query]);
+    const openImport = (t) => {
+        setImporting(t);
+        setDialogOpen(true);
+    };
+    if (state === 'unavailable') {
+        return _jsx(UnavailableHint, {});
+    }
+    return (_jsxs("div", { className: "space-y-3", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsxs("div", { className: "relative flex-1", children: [_jsx(Search, { className: "absolute left-2 top-1/2 -translate-y-1/2 h-3.5 w-3.5 text-muted-foreground" }), _jsx("input", { value: query, onChange: (e) => setQuery(e.target.value), placeholder: "Filter tables\u2026", className: "w-full rounded border bg-background pl-7 pr-2 py-1.5 text-xs outline-none focus:ring-1 focus:ring-ring" })] }), _jsxs(Button, { variant: "outline", size: "sm", onClick: () => void load(), disabled: state === 'loading', children: [state === 'loading' ? (_jsx(Loader2, { className: "h-3.5 w-3.5 animate-spin" })) : (_jsx(RefreshCw, { className: "h-3.5 w-3.5" })), _jsx("span", { className: "ml-1.5", children: "Refresh" })] })] }), error && (_jsx("div", { className: "rounded border border-destructive/40 bg-destructive/5 p-2.5 text-xs text-destructive", children: error })), state === 'loading' && tables.length === 0 && (_jsxs("div", { className: "flex items-center justify-center gap-2 py-10 text-sm text-muted-foreground", children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin" }), " Introspecting remote schema\u2026"] })), state === 'loaded' && filtered.length === 0 && (_jsx("div", { className: "py-10 text-center text-sm text-muted-foreground", children: tables.length === 0
+                    ? 'No remote tables found (check the datasource’s allowedSchemas).'
+                    : 'No tables match the filter.' })), filtered.length > 0 && (_jsx("div", { className: "rounded border bg-background overflow-hidden", children: _jsxs("table", { className: "w-full text-xs", children: [_jsx("thead", { className: "bg-muted/40 text-muted-foreground", children: _jsxs("tr", { children: [_jsx("th", { className: "px-2.5 py-1.5 text-left font-medium", children: "Table" }), _jsx("th", { className: "px-2.5 py-1.5 text-right font-medium", children: "Columns" }), _jsx("th", { className: "px-2.5 py-1.5 text-right font-medium", children: "Rows (est.)" }), _jsx("th", { className: "px-2.5 py-1.5 w-px" })] }) }), _jsx("tbody", { className: "divide-y", children: filtered.map((t) => {
+                                const key = [t.schema, t.name].filter(Boolean).join('.');
+                                return (_jsxs("tr", { className: "hover:bg-muted/30", children: [_jsx("td", { className: "px-2.5 py-1.5", children: _jsxs("span", { className: "inline-flex items-center gap-1.5 font-mono", children: [_jsx(Table2, { className: "h-3.5 w-3.5 text-muted-foreground" }), t.schema && _jsxs("span", { className: "text-muted-foreground", children: [t.schema, "."] }), _jsx("span", { className: "font-medium", children: t.name })] }) }), _jsx("td", { className: "px-2.5 py-1.5 text-right tabular-nums", children: _jsxs("span", { className: "inline-flex items-center gap-1 text-muted-foreground", children: [_jsx(Columns3, { className: "h-3 w-3" }), t.columnCount] }) }), _jsx("td", { className: "px-2.5 py-1.5 text-right tabular-nums text-muted-foreground", children: typeof t.rowCountEstimate === 'number'
+                                                ? t.rowCountEstimate.toLocaleString()
+                                                : '—' }), _jsx("td", { className: "px-2.5 py-1.5", children: _jsxs(Button, { variant: "ghost", size: "sm", onClick: () => openImport(t), children: [_jsx(Download, { className: "h-3.5 w-3.5" }), _jsx("span", { className: "ml-1.5", children: "Import" })] }) })] }, key));
+                            }) })] }) })), _jsx(ImportObjectDialog, { datasource: datasource, table: importing, open: dialogOpen, onOpenChange: setDialogOpen })] }));
+}
+function UnavailableHint() {
+    return (_jsxs("div", { className: "rounded border border-amber-300 bg-amber-50 dark:bg-amber-950/20 p-3 text-xs text-amber-900 dark:text-amber-200", children: ["Federation is not enabled on this server. The", _jsx("span", { className: "font-mono", children: " external-datasource " }), "service must be registered for table browsing, drafting, and validation to work."] }));
+}

package/dist/views/metadata-admin/external/ValidationPanel.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ValidationPanel — the "validation panel" surface of the external-datasource
+ * Studio panel (ADR-0015 §6.4).
+ *
+ * Runs `POST …/validate` on demand and renders, per federated Object bound to
+ * this datasource, whether it still matches the live remote table — plus the
+ * structured schema diffs (missing column, type mismatch, …) when it doesn't.
+ *
+ * This doubles as the on-demand "drift" view: a previously-green object that
+ * now reports `missing_column` / `type_mismatch` is exactly remote drift.
+ */
+import * as React from 'react';
+export interface ValidationPanelProps {
+    datasource: string;
+}
+export declare function ValidationPanel({ datasource }: ValidationPanelProps): React.JSX.Element;

package/dist/views/metadata-admin/external/ValidationPanel.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * ValidationPanel — the "validation panel" surface of the external-datasource
+ * Studio panel (ADR-0015 §6.4).
+ *
+ * Runs `POST …/validate` on demand and renders, per federated Object bound to
+ * this datasource, whether it still matches the live remote table — plus the
+ * structured schema diffs (missing column, type mismatch, …) when it doesn't.
+ *
+ * This doubles as the on-demand "drift" view: a previously-green object that
+ * now reports `missing_column` / `type_mismatch` is exactly remote drift.
+ */
+import * as React from 'react';
+import { ShieldCheck, ShieldAlert, Loader2, PlayCircle, CheckCircle2 } from 'lucide-react';
+import { Button } from '@object-ui/components';
+import { validateDatasource, ExternalServiceUnavailableError, } from './api';
+const DIFF_LABEL = {
+    missing_table: 'Missing table',
+    missing_column: 'Missing column',
+    type_mismatch: 'Type mismatch',
+    nullability_mismatch: 'Nullability mismatch',
+    unmapped_column: 'Unmapped column',
+    pk_mismatch: 'Primary-key mismatch',
+};
+export function ValidationPanel({ datasource }) {
+    const [state, setState] = React.useState('idle');
+    const [results, setResults] = React.useState([]);
+    const [ok, setOk] = React.useState(null);
+    const [error, setError] = React.useState(null);
+    const run = React.useCallback(async () => {
+        setState('running');
+        setError(null);
+        try {
+            const report = await validateDatasource(datasource);
+            setResults(report.results);
+            setOk(report.ok);
+            setState('done');
+        }
+        catch (err) {
+            if (err instanceof ExternalServiceUnavailableError) {
+                setState('unavailable');
+            }
+            else {
+                setError(err instanceof Error ? err.message : String(err));
+                setState('error');
+            }
+        }
+    }, [datasource]);
+    if (state === 'unavailable') {
+        return (_jsx("div", { className: "rounded border border-amber-300 bg-amber-50 dark:bg-amber-950/20 p-3 text-xs text-amber-900 dark:text-amber-200", children: "Federation is not enabled on this server, so validation is unavailable." }));
+    }
+    return (_jsxs("div", { className: "space-y-3", children: [_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsxs("p", { className: "text-xs text-muted-foreground", children: ["Check that every federated object on", ' ', _jsx("span", { className: "font-mono", children: datasource }), " still matches its live remote table."] }), _jsxs(Button, { variant: "outline", size: "sm", onClick: () => void run(), disabled: state === 'running', children: [state === 'running' ? (_jsx(Loader2, { className: "h-3.5 w-3.5 animate-spin" })) : (_jsx(PlayCircle, { className: "h-3.5 w-3.5" })), _jsx("span", { className: "ml-1.5", children: "Run validation" })] })] }), error && (_jsx("div", { className: "rounded border border-destructive/40 bg-destructive/5 p-2.5 text-xs text-destructive", children: error })), state === 'done' && ok !== null && (_jsxs("div", { className: `flex items-center gap-2 rounded border p-2.5 text-sm ${ok
+                    ? 'border-emerald-300 bg-emerald-50 dark:bg-emerald-950/20 text-emerald-800 dark:text-emerald-300'
+                    : 'border-destructive/40 bg-destructive/5 text-destructive'}`, children: [ok ? _jsx(CheckCircle2, { className: "h-4 w-4" }) : _jsx(ShieldAlert, { className: "h-4 w-4" }), ok
+                        ? `All ${results.length} object${results.length === 1 ? '' : 's'} match the remote schema.`
+                        : `${results.filter((r) => !r.ok).length} of ${results.length} object${results.length === 1 ? '' : 's'} diverge from the remote schema.`] })), state === 'done' && results.length === 0 && (_jsx("div", { className: "py-8 text-center text-sm text-muted-foreground", children: "No federated objects are bound to this datasource yet. Import a table from the Tables tab to get started." })), results.length > 0 && (_jsx("ul", { className: "space-y-2", children: results.map((r) => (_jsx(ResultRow, { result: r }, r.object))) }))] }));
+}
+function ResultRow({ result }) {
+    return (_jsxs("li", { className: "rounded border bg-background", children: [_jsxs("div", { className: "flex items-center gap-2 px-2.5 py-1.5", children: [result.ok ? (_jsx(ShieldCheck, { className: "h-3.5 w-3.5 text-emerald-500" })) : (_jsx(ShieldAlert, { className: "h-3.5 w-3.5 text-destructive" })), _jsx("span", { className: "font-mono text-xs font-medium", children: result.object }), !result.ok && (_jsxs("span", { className: "ml-auto text-[11px] text-muted-foreground", children: [result.diffs.length, " diff", result.diffs.length === 1 ? '' : 's'] }))] }), result.diffs.length > 0 && (_jsx("ul", { className: "border-t divide-y", children: result.diffs.map((d, i) => (_jsx(DiffRow, { diff: d }, `${d.kind}:${d.column ?? ''}:${i}`))) }))] }));
+}
+function DiffRow({ diff }) {
+    const where = [diff.remoteSchema, diff.remoteName].filter(Boolean).join('.');
+    const isError = diff.severity === 'error';
+    return (_jsxs("li", { className: "flex flex-wrap items-baseline gap-x-2 gap-y-0.5 px-2.5 py-1.5 text-[11px]", children: [_jsx("span", { className: `rounded px-1 py-0.5 font-medium uppercase tracking-wide text-[9px] ${isError
+                    ? 'bg-destructive/10 text-destructive'
+                    : 'bg-amber-100 text-amber-800 dark:bg-amber-950/40 dark:text-amber-300'}`, children: DIFF_LABEL[diff.kind] ?? diff.kind }), where && _jsx("span", { className: "font-mono text-muted-foreground", children: where }), diff.column && _jsxs("span", { className: "font-mono", children: [".", diff.column] }), (diff.expected !== undefined || diff.actual !== undefined) && (_jsxs("span", { className: "text-muted-foreground", children: ["expected ", _jsx("span", { className: "font-mono", children: diff.expected ?? '—' }), ", actual", ' ', _jsx("span", { className: "font-mono", children: diff.actual ?? '—' })] }))] }));
+}

package/dist/views/metadata-admin/external/api.d.ts

@@ -0,0 +1,100 @@
+/** A remote table discovered via introspection (allowedSchemas-filtered). */
+export interface RemoteTable {
+    schema?: string;
+    name: string;
+    columnCount: number;
+    rowCountEstimate?: number;
+}
+/** Options controlling how a remote table is drafted into an Object. */
+export interface GenerateDraftOpts {
+    remoteSchema?: string;
+    rename?: Record<string, string>;
+    primaryKey?: string[];
+    includeColumns?: string[];
+    excludeColumns?: string[];
+}
+/** A generated Object draft: structured definition + `*.object.ts` source. */
+export interface ObjectDraft {
+    name: string;
+    datasource: string;
+    definition: Record<string, unknown>;
+    source: string;
+    review: Array<{
+        column: string;
+        remoteType: string;
+        note: string;
+    }>;
+}
+export type SchemaDiffEntryKind = 'missing_table' | 'missing_column' | 'type_mismatch' | 'nullability_mismatch' | 'unmapped_column' | 'pk_mismatch';
+/** A single divergence between a federated Object and its remote table. */
+export interface SchemaDiffEntry {
+    kind: SchemaDiffEntryKind;
+    remoteSchema?: string;
+    remoteName?: string;
+    column?: string;
+    expected?: string;
+    actual?: string;
+    severity: 'error' | 'warning';
+}
+/** Per-object validation outcome. */
+export interface SchemaValidationResult {
+    ok: boolean;
+    datasource: string;
+    object: string;
+    diffs: SchemaDiffEntry[];
+}
+/** A single remote column captured in a catalog snapshot. */
+export interface ExternalColumn {
+    name: string;
+    sqlType: string;
+    nullable: boolean;
+    primaryKey?: boolean;
+    suggestedFieldType?: string;
+}
+/** A single remote table/view captured in a catalog snapshot. */
+export interface ExternalTable {
+    remoteSchema?: string;
+    remoteName: string;
+    columns: ExternalColumn[];
+    indexes?: Array<{
+        name: string;
+        columns: string[];
+        unique: boolean;
+    }>;
+    rowCountEstimate?: number;
+}
+/** The persisted snapshot of a federated datasource's remote schema. */
+export interface ExternalCatalog {
+    name: string;
+    datasource: string;
+    snapshotAt: string;
+    dialect?: string;
+    tables: ExternalTable[];
+}
+/**
+ * Raised when the server replies `503 external_service_unavailable` — the
+ * federation service is not wired into this host. Callers render a friendly
+ * "enable federation on the server" message instead of a generic failure.
+ */
+export declare class ExternalServiceUnavailableError extends Error {
+    constructor();
+}
+/** List remote tables, optionally filtered to a single remote schema. */
+export declare function listRemoteTables(datasource: string, opts?: {
+    schema?: string;
+}): Promise<RemoteTable[]>;
+/** Generate an Object draft (structured + `*.object.ts` source) from a table. */
+export declare function generateObjectDraft(datasource: string, remoteName: string, opts?: GenerateDraftOpts): Promise<ObjectDraft>;
+/** Refresh and return the cached remote-schema snapshot. */
+export declare function refreshCatalog(datasource: string): Promise<ExternalCatalog>;
+/** Validate every federated Object bound to this datasource. */
+export declare function validateDatasource(datasource: string): Promise<{
+    ok: boolean;
+    results: SchemaValidationResult[];
+}>;
+/**
+ * Persist a generated Object draft as a real `object` metadata item
+ * (PUT `/api/v1/meta/object/:name`, mirroring `MetadataClient.save`). The
+ * draft's `definition` is the parseable ObjectSchema body.
+ */
+export declare function importObjectDraft(draft: ObjectDraft): Promise<void>;

package/dist/views/metadata-admin/external/api.js

@@ -0,0 +1,124 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Thin REST client for the External Datasource Federation routes
+ * (ADR-0015 §6.2, framework `registerExternalDatasourceRoutes`).
+ *
+ * Mounted server-side under `/api/v1/datasources/:name/external/*`:
+ *
+ *   GET  /tables[?schema=]              → { tables: RemoteTable[] }
+ *   POST /tables/:remote/draft          → { draft: ObjectDraft }
+ *   POST /refresh-catalog               → { catalog: ExternalCatalog }
+ *   POST /validate                      → { ok, results: SchemaValidationResult[] }
+ *
+ * Every route degrades to `503 external_service_unavailable` when the host
+ * has not wired the `external-datasource` service — callers surface that as a
+ * "federation not enabled on this server" hint rather than a hard error.
+ *
+ * All calls go through `createAuthenticatedFetch()` so the Bearer token,
+ * `X-Tenant-ID`, and `Accept-Language` are injected exactly like every other
+ * app-shell REST call (RecordDetailView, ObjectView, …).
+ */
+import { createAuthenticatedFetch } from '@object-ui/auth';
+/**
+ * Raised when the server replies `503 external_service_unavailable` — the
+ * federation service is not wired into this host. Callers render a friendly
+ * "enable federation on the server" message instead of a generic failure.
+ */
+export class ExternalServiceUnavailableError extends Error {
+    constructor() {
+        super('external_service_unavailable');
+        this.name = 'ExternalServiceUnavailableError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+const authFetch = createAuthenticatedFetch();
+function serverBase() {
+    const raw = import.meta.env?.VITE_SERVER_URL ?? '';
+    return raw.replace(/\/+$/, '');
+}
+function externalBase(datasource) {
+    return `${serverBase()}/api/v1/datasources/${encodeURIComponent(datasource)}/external`;
+}
+async function jsonOrThrow(res) {
+    if (res.status === 503) {
+        // Body is `{ error: 'external_service_unavailable' }` — treat distinctly.
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = undefined;
+        }
+        const code = body && typeof body === 'object' && 'error' in body
+            ? String(body.error)
+            : '';
+        if (code === 'external_service_unavailable')
+            throw new ExternalServiceUnavailableError();
+    }
+    if (!res.ok) {
+        let detail = `${res.status} ${res.statusText}`;
+        try {
+            const body = await res.json();
+            if (body && typeof body === 'object' && 'error' in body) {
+                detail = String(body.error);
+            }
+        }
+        catch {
+            /* keep status-text detail */
+        }
+        throw new Error(detail);
+    }
+    return (await res.json());
+}
+/** List remote tables, optionally filtered to a single remote schema. */
+export async function listRemoteTables(datasource, opts = {}) {
+    const qs = opts.schema ? `?schema=${encodeURIComponent(opts.schema)}` : '';
+    const res = await authFetch(`${externalBase(datasource)}/tables${qs}`, {
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+    });
+    const data = await jsonOrThrow(res);
+    return data.tables ?? [];
+}
+/** Generate an Object draft (structured + `*.object.ts` source) from a table. */
+export async function generateObjectDraft(datasource, remoteName, opts = {}) {
+    const res = await authFetch(`${externalBase(datasource)}/tables/${encodeURIComponent(remoteName)}/draft`, {
+        method: 'POST',
+        headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+        body: JSON.stringify(opts),
+    });
+    const data = await jsonOrThrow(res);
+    return data.draft;
+}
+/** Refresh and return the cached remote-schema snapshot. */
+export async function refreshCatalog(datasource) {
+    const res = await authFetch(`${externalBase(datasource)}/refresh-catalog`, {
+        method: 'POST',
+        headers: { Accept: 'application/json' },
+    });
+    const data = await jsonOrThrow(res);
+    return data.catalog;
+}
+/** Validate every federated Object bound to this datasource. */
+export async function validateDatasource(datasource) {
+    const res = await authFetch(`${externalBase(datasource)}/validate`, {
+        method: 'POST',
+        headers: { Accept: 'application/json' },
+    });
+    return jsonOrThrow(res);
+}
+/**
+ * Persist a generated Object draft as a real `object` metadata item
+ * (PUT `/api/v1/meta/object/:name`, mirroring `MetadataClient.save`). The
+ * draft's `definition` is the parseable ObjectSchema body.
+ */
+export async function importObjectDraft(draft) {
+    const res = await authFetch(`${serverBase()}/api/v1/meta/object/${encodeURIComponent(draft.name)}`, {
+        method: 'PUT',
+        headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+        body: JSON.stringify(draft.definition),
+    });
+    await jsonOrThrow(res);
+}

package/dist/views/metadata-admin/i18n.d.ts

@@ -29,5 +29,6 @@ export declare function t(key: string, locale?: SupportedLocale | string): strin
  *   tFormat('engine.directory.description', 'zh-CN', { count: 28, writable: 4 })
  */
 export declare function tFormat(key: string, locale: SupportedLocale | string | undefined, vars: Record<string, string | number>): string;
+export declare function translateValidationMessage(message: string | undefined, locale?: SupportedLocale | string): string;
 /** Returns the locale string most browsers report (matches navigator.language). */
 export declare function detectLocale(): SupportedLocale;