@tuskira/gateway-web

Console d'administration pour la passerelle d'agents IA Tuskira. React 19 + Vite + TypeScript (strict) + Tailwind CSS 4 + shadcn/ui.

Développement

Nécessite Node 26+ et npm 11+ (pas de pnpm).

npm install
npm run dev

Le serveur de développement proxyfie /api vers http://localhost:8081 (voir vite.config.ts), donc exécutez la passerelle sur :8081 en parallèle de l'interface utilisateur. Connectez-vous à /login avec une clé API (gk_…) émise par la passerelle.

Depuis la racine du dépôt, vous pouvez plutôt exécuter :

make ui-install
make ui-dev

Compilation

npm run build

Émet un bundle de production dans dist/. En production, la passerelle elle-même sert ce bundle à / sur :8081, ainsi l'application communique avec l'API en same-origin — aucun proxy n'est nécessaire.

make ui-build   # from the repo root

Utiliser la console comme bibliothèque

La console est également empaquetée sous le nom @tuskira/gateway-web, ce qui vous permet de monter ses pages au sein de votre propre application React. Le paquet n'est pas disponible sur le registre npm. Chaque release GitHub le fournit sous forme d'archive tarball, et sa version correspond toujours au tag de release de la passerelle. React, React DOM, React Router (react-router-dom 7) et TanStack Query 5 sont des dépendances de pair ; tout le reste s'installe avec le paquet.

npm install https://github.com/Tuskira/ai-agent-gateway/releases/download/v<version>/tuskira-gateway-web-<version>.tgz \
  react react-dom react-router-dom @tanstack/react-query

npm enregistre le hachage d'intégrité du tarball dans package-lock.json.

import {
  AppShell, AuthProvider, RequireAuth, LoginPage, Toaster, TooltipProvider,
  configureGateway, gatewayPageRoutes,
} from '@tuskira/gateway-web'
import '@tuskira/gateway-web/style.css' // Tailwind output + design tokens
import '@tuskira/gateway-web/fonts.css' // optional: self-hosted Inter / JetBrains Mono

configureGateway({
  apiBase: '/gw/api/v1',                  // default '/api/v1'
  mcpBase: 'https://gw.example.com/mcp',  // default: guessed from the page origin
  onUnauthenticated: () => router.navigate('/login'), // default: window.location.assign('/login')
})

const router = createBrowserRouter(
  [
    { path: '/login', element: <LoginPage /> },
    { element: <RequireAuth />, children: [{ element: <AppShell />, children: gatewayPageRoutes() }] },
  ],
  { basename: '/gateway' },
)

Enveloppez le routeur dans QueryClientProvider, AuthProvider et TooltipProvider, et rendez <Toaster /> une seule fois, comme le fait src/App.tsx. gatewayRoutes() renvoie l'arbre complet (login, docs, change-password, shell et la redirection catch-all) si vous voulez que la console possède l'ensemble du routeur. Seul ce que @tuskira/gateway-web exporte est pris en charge ; n'importez pas depuis src/.

Ajouter vos propres pages

Passez une extension pour placer vos propres groupes de barre latérale et pages à l'intérieur du shell de la console et du garde d'authentification :

gatewayRoutes({ extension: { navGroups: [...], routes: [...] } })

import { Plug } from 'lucide-react'
import { AppShell, gatewayPageRoutes, type ConsoleExtension } from '@tuskira/gateway-web'

const extension: ConsoleExtension = {
  navGroups: [
    // New group, placed before the core "Observe" group (appended without `before`).
    { label: 'Billing', before: 'Observe', items: [
      { label: 'Invoices', path: '/invoices', icon: Plug, description: 'Invoices and usage.' },
    ] },
    // Same label as a core group: the items are added to that group.
    { label: 'Access', items: [
      { label: 'Audit', path: '/audit', icon: Plug, description: 'Audit trail.' },
    ] },
  ],
  routes: [
    { path: '/invoices', Component: InvoicesPage },
    { path: '/audit', Component: AuditPage },
  ],
}

// Own router: pass the extension to both the routes and the shell.
{ element: <AppShell extension={extension} />, children: gatewayPageRoutes(extension) }

gatewayRoutes({ extension }) fait les deux pour vous. Un élément de navigation dont le chemin n'a pas de route affiche l'espace réservé « bientôt disponible ». Définissez end: true sur un élément dont le chemin est un préfixe des chemins d'autres éléments afin qu'il ne soit actif que sur son propre chemin.

Le navigateur doit atteindre l'API de la passerelle sur le chemin que vous définissez comme apiBase. Lorsque l'application hôte sert la console, ajoutez une règle de proxy inverse qui redirige /api/v1/* (ou le chemin de votre apiBase, réécrit vers /api/v1) vers la passerelle sur le port 8081. Conservez le chemin, tous les en-têtes de requête et de réponse (Authorization, X-CSRF-Token, X-Gateway-Acting-Tenant) et les cookies inchangés, sinon la connexion et les vérifications CSRF échoueront.

Compilez le paquet avec npm run build:lib, qui génère dist-lib/ (index.js, types/, style.css, fonts.css). npm pack produit ensuite l'archive tarball ; le workflow de publication l'attache à la release GitHub à chaque tag v*.

Contrôles de qualité

npm run lint        # eslint
npm run typecheck    # tsc --noEmit (project references)
npm run test         # vitest
npm run format:check # prettier --check

Ajout d'un composant shadcn/ui

npx shadcn@latest add <component>

Le fichier components.json de ce projet cible le modèle Vite, la base radix, la couleur de base neutral et les variables CSS pour le thème, avec l'alias d'import @/* résolvant vers src/*. Les nouveaux composants sont écrits dans src/components/ui/.

Jetons de design

tokens.json (racine du dépôt) est la source de vérité unique pour le système de design — couleurs, espacements, rayons, ombres, polices. Exécutez npm run gen:tokens après l'avoir modifié pour régénérer :

• src/styles/tokens.css — les jetons bruts sous forme de propriétés personnalisées CSS (:root pour les valeurs claires, .dark pour les surcharges sombres), en conservant les noms de jetons du designer (--indigo-9, --sev-high, --r-4, --shadow-1, ...).
• src/styles/tokens.ts — les mêmes échelles de couleurs catégorielles (colors.indigo, colors.slate, colors.sev, colors.status, colors.brand) plus fonts, radii, shadows, pour les consommateurs non-CSS (par ex. les couleurs de séries recharts).

src/index.css mappe les variables sémantiques de shadcn (--background, --primary, --sidebar, ...) sur ces jetons, et enregistre les entrées @theme de Tailwind v4 afin que des utilitaires comme bg-indigo-9, text-text-muted, border-border-strong, shadow-1, rounded-r-4 et font-mono soient disponibles partout dans l'application. Ne modifiez pas manuellement src/styles/tokens.css / src/styles/tokens.ts — ils sont écrasés par le générateur. src/test/tokens.test.ts vérifie que chaque entrée de tokens.ts possède une déclaration correspondante dans tokens.css.

Organisation des dossiers