@shipfox/client-runners 0.2.0

package/src/components/manual-registration-token-list.tsx

@@ -0,0 +1,246 @@
+import type {ManualRegistrationTokenDto} from '@shipfox/api-runners-dto';
+import {Button, IconButton} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@shipfox/react-ui/dropdown-menu';
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+import {
+  Modal,
+  ModalBody,
+  ModalContent,
+  ModalFooter,
+  ModalHeader,
+  ModalTitle,
+} from '@shipfox/react-ui/modal';
+import {Skeleton} from '@shipfox/react-ui/skeleton';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@shipfox/react-ui/table';
+import {Code, Text} from '@shipfox/react-ui/typography';
+import {useQueryClient} from '@tanstack/react-query';
+import {useState} from 'react';
+import {
+  manualRegistrationTokenQueryKeys,
+  useRevokeManualRegistrationTokenMutation,
+} from '#hooks/api/manual-registration-tokens.js';
+import {manualRegistrationTokenErrorMessage} from './manual-registration-token-errors.js';
+import {
+  formatManualRegistrationTokenDate,
+  formatManualRegistrationTokenTimestamp,
+  manualRegistrationTokenDisplayName,
+} from './manual-registration-token-format.js';
+import {TokenDate} from './token-date.js';
+import {TokenName} from './token-name.js';
+
+export function ManualRegistrationTokenList({
+  workspaceId,
+  tokens,
+}: {
+  workspaceId: string;
+  tokens: ManualRegistrationTokenDto[];
+}) {
+  return (
+    <>
+      <div className="max-[760px]:hidden">
+        <Table className="table-fixed">
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-[34%]">Name</TableHead>
+              <TableHead>Prefix</TableHead>
+              <TableHead className="w-128">Expires</TableHead>
+              <TableHead className="w-128">Created</TableHead>
+              <TableHead className="w-80 text-right">Actions</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {tokens.map((token) => (
+              <TableRow key={token.id}>
+                <TableCell>
+                  <TokenName name={manualRegistrationTokenDisplayName(token)} />
+                </TableCell>
+                <TableCell>
+                  <Code variant="paragraph" className="block truncate">
+                    {token.prefix}
+                  </Code>
+                </TableCell>
+                <TableCell>
+                  <ManualRegistrationTokenDate value={token.expires_at} />
+                </TableCell>
+                <TableCell>
+                  <ManualRegistrationTokenDate value={token.created_at} />
+                </TableCell>
+                <TableCell className="text-right">
+                  <RevokeManualRegistrationTokenButton workspaceId={workspaceId} token={token} />
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+      <ul
+        className="hidden flex-col gap-10 max-[760px]:flex"
+        aria-label="Manual registration tokens"
+      >
+        {tokens.map((token) => (
+          <li
+            key={token.id}
+            className="rounded-8 border border-border-neutral-base bg-background-neutral-base p-14"
+          >
+            <div className="flex items-start justify-between gap-12">
+              <div className="min-w-0 flex-1">
+                <TokenName name={manualRegistrationTokenDisplayName(token)} />
+                <Code variant="paragraph" className="block truncate text-foreground-neutral-muted">
+                  {token.prefix}
+                </Code>
+              </div>
+              <RevokeManualRegistrationTokenButton workspaceId={workspaceId} token={token} />
+            </div>
+            <dl className="mt-12 grid grid-cols-2 gap-10 text-sm">
+              <div>
+                <dt className="text-foreground-neutral-muted">Expires</dt>
+                <dd>
+                  <ManualRegistrationTokenDate value={token.expires_at} />
+                </dd>
+              </div>
+              <div>
+                <dt className="text-foreground-neutral-muted">Created</dt>
+                <dd>
+                  <ManualRegistrationTokenDate value={token.created_at} />
+                </dd>
+              </div>
+            </dl>
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+}
+
+function ManualRegistrationTokenDate({value}: {value: string | null}) {
+  return (
+    <TokenDate
+      value={value}
+      date={formatManualRegistrationTokenDate(value)}
+      timestamp={formatManualRegistrationTokenTimestamp(value)}
+    />
+  );
+}
+
+function RevokeManualRegistrationTokenButton({
+  workspaceId,
+  token,
+}: {
+  workspaceId: string;
+  token: ManualRegistrationTokenDto;
+}) {
+  const queryClient = useQueryClient();
+  const revokeToken = useRevokeManualRegistrationTokenMutation();
+  const [open, setOpen] = useState(false);
+  const tokenName = manualRegistrationTokenDisplayName(token);
+
+  async function handleRevoke() {
+    try {
+      await revokeToken.mutateAsync({workspaceId, tokenId: token.id});
+      await queryClient.invalidateQueries({
+        queryKey: manualRegistrationTokenQueryKeys.list(workspaceId),
+      });
+      setOpen(false);
+    } catch {
+      // React Query stores the error for the inline modal alert.
+    }
+  }
+
+  function handleOpenChange(nextOpen: boolean) {
+    setOpen(nextOpen);
+    if (nextOpen) {
+      revokeToken.reset();
+    }
+  }
+
+  function openRevokeConfirmation() {
+    revokeToken.reset();
+    setOpen(true);
+  }
+
+  return (
+    <>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <IconButton
+            type="button"
+            size="sm"
+            variant="transparent"
+            icon="more2Line"
+            aria-label={`Open ${tokenName} registration token actions`}
+          />
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" size="sm">
+          <DropdownMenuItem onSelect={openRevokeConfirmation}>Revoke token</DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <Modal open={open} onOpenChange={handleOpenChange}>
+        <ModalContent aria-describedby={undefined} className="max-w-[420px]">
+          <ModalTitle className="sr-only">Revoke token</ModalTitle>
+          <ModalHeader title="Revoke token?" />
+          <ModalBody className="gap-16">
+            <Text size="sm" className="text-foreground-neutral-muted">
+              {tokenName} will stop creating new runner sessions. Existing sessions and job leases
+              expire on their own.
+            </Text>
+            {revokeToken.isError ? (
+              <Callout role="alert" type="error">
+                <Text size="sm">{manualRegistrationTokenErrorMessage(revokeToken.error)}</Text>
+              </Callout>
+            ) : null}
+          </ModalBody>
+          <ModalFooter>
+            <Button size="sm" variant="secondary" onClick={() => setOpen(false)}>
+              Cancel
+            </Button>
+            <Button
+              size="sm"
+              variant="danger"
+              isLoading={revokeToken.isPending}
+              onClick={handleRevoke}
+            >
+              Revoke
+            </Button>
+          </ModalFooter>
+        </ModalContent>
+      </Modal>
+    </>
+  );
+}
+
+export function EmptyManualRegistrationTokens() {
+  return (
+    <EmptyState
+      icon="key2Line"
+      title="No usable manual registration tokens"
+      description="Create a token to connect a runner to this workspace."
+    />
+  );
+}
+
+export function ManualRegistrationTokenTableSkeleton() {
+  return (
+    <div
+      role="status"
+      aria-label="Loading manual registration tokens"
+      className="flex flex-col gap-8"
+    >
+      {[0, 1, 2].map((row) => (
+        <Skeleton key={row} className="h-44 w-full" />
+      ))}
+    </div>
+  );
+}

package/src/components/manual-registration-tokens-settings-section.test.tsx

@@ -0,0 +1,251 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {Toaster} from '@shipfox/react-ui/toast';
+import {formatDate, formatTimestamp} from '@shipfox/react-ui/utils';
+import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
+import {fireEvent, render, screen, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type {ReactElement} from 'react';
+import {WorkspaceManualRegistrationTokensSettingsSection} from './manual-registration-tokens-settings-section.js';
+
+const RUNNERS_TEST_WORKSPACE_ID = '11111111-1111-4111-8111-111111111111';
+function jsonResponse(body: unknown, init: ResponseInit = {}) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {'content-type': 'application/json'},
+    ...init,
+  });
+}
+
+function manualRegistrationToken(overrides: Partial<Record<string, string | null>> = {}) {
+  return {
+    id: '33333333-3333-4333-8333-333333333333',
+    workspace_id: RUNNERS_TEST_WORKSPACE_ID,
+    prefix: 'sf_mrt_abcde',
+    name: 'Deploy runner',
+    expires_at: '2026-05-09T00:00:00.000Z',
+    revoked_at: null,
+    created_at: '2026-05-08T00:00:00.000Z',
+    updated_at: '2026-05-08T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+function renderManualRegistrationTokens(element: ReactElement) {
+  const queryClient = new QueryClient({defaultOptions: {queries: {retry: false}}});
+
+  return render(
+    <QueryClientProvider client={queryClient}>
+      {element}
+      <Toaster />
+    </QueryClientProvider>,
+  );
+}
+
+function firstButton(name: string): HTMLElement {
+  const button = screen.getAllByRole('button', {name})[0];
+  if (!button) throw new Error(`Button not found: ${name}`);
+  return button;
+}
+
+function lastButton(name: string): HTMLElement {
+  const buttons = screen.getAllByRole('button', {name});
+  const button = buttons.at(-1);
+  if (!button) throw new Error(`Button not found: ${name}`);
+  return button;
+}
+
+async function chooseTokenAction(user: ReturnType<typeof userEvent.setup>, tokenName: string) {
+  await user.click(firstButton(`Open ${tokenName} registration token actions`));
+  const menuItem = await screen.findByRole('menuitem', {name: 'Revoke token'});
+  expect(menuItem.querySelector('svg')).not.toBeInTheDocument();
+
+  await user.click(menuItem);
+  expect(await screen.findByRole('dialog')).toBeVisible();
+  expect(screen.getByText('Revoke token?')).toBeVisible();
+}
+
+describe('WorkspaceManualRegistrationTokensSettingsSection', () => {
+  test('renders an empty usable-token state', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({manual_registration_tokens: []}));
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderManualRegistrationTokens(
+      <WorkspaceManualRegistrationTokensSettingsSection workspaceId={RUNNERS_TEST_WORKSPACE_ID} />,
+    );
+
+    expect(await screen.findByText('No usable manual registration tokens')).toBeVisible();
+    expect(screen.getByRole('button', {name: 'Create token'})).toBeVisible();
+  });
+
+  test('creates a token and reveals the raw token inline once', async () => {
+    const user = userEvent.setup();
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(jsonResponse({manual_registration_tokens: []}))
+      .mockResolvedValueOnce(
+        jsonResponse(
+          {
+            id: '44444444-4444-4444-8444-444444444444',
+            raw_token: 'sf_mrt_raw-created-token',
+            prefix: 'sf_mrt_raw-c',
+            name: 'Local runner',
+            workspace_id: RUNNERS_TEST_WORKSPACE_ID,
+            expires_at: '2026-05-09T00:00:00.000Z',
+            created_at: '2026-05-08T00:00:00.000Z',
+          },
+          {status: 201},
+        ),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          manual_registration_tokens: [manualRegistrationToken({name: 'Local runner'})],
+        }),
+      );
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderManualRegistrationTokens(
+      <WorkspaceManualRegistrationTokensSettingsSection workspaceId={RUNNERS_TEST_WORKSPACE_ID} />,
+    );
+    await screen.findByText('No usable manual registration tokens');
+    await user.click(screen.getByRole('button', {name: 'Create token'}));
+    fireEvent.change(await screen.findByLabelText('Token name'), {
+      target: {value: 'Local runner'},
+    });
+    await user.click(lastButton('Create token'));
+
+    expect(await screen.findByText('Token created')).toBeVisible();
+    expect(screen.getByText('sf_mrt_raw-created-token')).toBeVisible();
+  });
+
+  test('renders compact dates with exact timestamp tooltips', async () => {
+    const user = userEvent.setup();
+    const createdAt = '2026-05-08T00:00:00.000Z';
+    const expiresAt = '2026-05-09T00:00:00.000Z';
+    const fetchImpl = vi.fn().mockResolvedValueOnce(
+      jsonResponse({
+        manual_registration_tokens: [
+          manualRegistrationToken({created_at: createdAt, expires_at: expiresAt}),
+        ],
+      }),
+    );
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderManualRegistrationTokens(
+      <WorkspaceManualRegistrationTokensSettingsSection workspaceId={RUNNERS_TEST_WORKSPACE_ID} />,
+    );
+    const expiresDate = await screen.findAllByText(formatDate(expiresAt));
+    const createdDate = await screen.findAllByText(formatDate(createdAt));
+    const expiresDateTrigger = expiresDate[0];
+    const createdDateTrigger = createdDate[0];
+    if (!expiresDateTrigger || !createdDateTrigger) throw new Error('Token dates not rendered');
+
+    expect(screen.queryByText(formatTimestamp(expiresAt))).not.toBeInTheDocument();
+    await user.hover(expiresDateTrigger);
+
+    expect(await screen.findByRole('tooltip')).toHaveTextContent(formatTimestamp(expiresAt));
+
+    await user.unhover(expiresDateTrigger);
+    await user.hover(createdDateTrigger);
+
+    expect(await screen.findByRole('tooltip')).toHaveTextContent(formatTimestamp(createdAt));
+  });
+
+  test('truncates long token names and shows the full name in a tooltip', async () => {
+    const user = userEvent.setup();
+    const tokenName = 'self-hosted-runner-for-production-release-candidate-validation-on-metal';
+    const fetchImpl = vi.fn().mockResolvedValueOnce(
+      jsonResponse({
+        manual_registration_tokens: [manualRegistrationToken({name: tokenName})],
+      }),
+    );
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderManualRegistrationTokens(
+      <WorkspaceManualRegistrationTokensSettingsSection workspaceId={RUNNERS_TEST_WORKSPACE_ID} />,
+    );
+    const nameTrigger = await screen.findAllByRole('button', {name: tokenName});
+    const visibleNameTrigger = nameTrigger[0];
+    if (!visibleNameTrigger) throw new Error('Token name not rendered');
+
+    expect(screen.getByRole('table')).toHaveClass('table-fixed');
+    expect(visibleNameTrigger).toHaveClass('truncate');
+    await user.hover(visibleNameTrigger);
+
+    expect(await screen.findByRole('tooltip')).toHaveTextContent(tokenName);
+  });
+
+  test('surfaces create errors without clearing the form', async () => {
+    const user = userEvent.setup();
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(jsonResponse({manual_registration_tokens: []}))
+      .mockResolvedValueOnce(
+        jsonResponse({message: 'Token quota reached', code: 'quota-reached'}, {status: 422}),
+      );
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderManualRegistrationTokens(
+      <WorkspaceManualRegistrationTokensSettingsSection workspaceId={RUNNERS_TEST_WORKSPACE_ID} />,
+    );
+    await screen.findByText('No usable manual registration tokens');
+    await user.click(screen.getByRole('button', {name: 'Create token'}));
+    fireEvent.change(await screen.findByLabelText('Token name'), {
+      target: {value: 'Local runner'},
+    });
+    await user.click(lastButton('Create token'));
+
+    expect(await screen.findByText('Could not create token')).toBeVisible();
+    expect(screen.getByText('Token quota reached')).toBeVisible();
+    expect(screen.getByLabelText('Token name')).toHaveValue('Local runner');
+  });
+
+  test('revokes a token after row confirmation and removes it from the list', async () => {
+    const user = userEvent.setup();
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({manual_registration_tokens: [manualRegistrationToken()]}),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(manualRegistrationToken({revoked_at: '2026-05-08T01:00:00.000Z'})),
+      )
+      .mockResolvedValueOnce(jsonResponse({manual_registration_tokens: []}));
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderManualRegistrationTokens(
+      <WorkspaceManualRegistrationTokensSettingsSection workspaceId={RUNNERS_TEST_WORKSPACE_ID} />,
+    );
+    expect((await screen.findAllByText('Deploy runner')).length).toBeGreaterThan(0);
+    await chooseTokenAction(user, 'Deploy runner');
+    await user.click(lastButton('Revoke'));
+
+    await waitFor(() => expect(screen.queryByText('Deploy runner')).not.toBeInTheDocument());
+    expect(screen.getByText('No usable manual registration tokens')).toBeVisible();
+  });
+
+  test('shows a recoverable revoke error', async () => {
+    const user = userEvent.setup();
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({manual_registration_tokens: [manualRegistrationToken()]}),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(
+          {message: 'Manual registration token not found', code: 'not-found'},
+          {status: 404},
+        ),
+      );
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderManualRegistrationTokens(
+      <WorkspaceManualRegistrationTokensSettingsSection workspaceId={RUNNERS_TEST_WORKSPACE_ID} />,
+    );
+    expect((await screen.findAllByText('Deploy runner')).length).toBeGreaterThan(0);
+    await chooseTokenAction(user, 'Deploy runner');
+    await user.click(lastButton('Revoke'));
+
+    expect(await screen.findByText('Manual registration token not found')).toBeVisible();
+    expect(screen.getAllByText('Deploy runner').length).toBeGreaterThan(0);
+  });
+});

package/src/components/manual-registration-tokens-settings-section.tsx

@@ -0,0 +1,110 @@
+import type {CreateManualRegistrationTokenResponseDto} from '@shipfox/api-runners-dto';
+import {QueryLoadError} from '@shipfox/client-ui';
+import {Button} from '@shipfox/react-ui/button';
+import {Icon} from '@shipfox/react-ui/icon';
+import {
+  Modal,
+  ModalBody,
+  ModalContent,
+  ModalHeader,
+  ModalTitle,
+  ModalTrigger,
+} from '@shipfox/react-ui/modal';
+import {Header, Text} from '@shipfox/react-ui/typography';
+import {useState} from 'react';
+import {useManualRegistrationTokensQuery} from '#hooks/api/manual-registration-tokens.js';
+import {
+  CreatedManualRegistrationTokenPanel,
+  CreateManualRegistrationTokenForm,
+} from './create-manual-registration-token-form.js';
+import {
+  EmptyManualRegistrationTokens,
+  ManualRegistrationTokenList,
+  ManualRegistrationTokenTableSkeleton,
+} from './manual-registration-token-list.js';
+
+export function WorkspaceManualRegistrationTokensSettingsSection({
+  workspaceId,
+}: {
+  workspaceId: string;
+}) {
+  const tokensQuery = useManualRegistrationTokensQuery(workspaceId);
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [createdToken, setCreatedToken] = useState<CreateManualRegistrationTokenResponseDto | null>(
+    null,
+  );
+  const tokens = tokensQuery.data?.manual_registration_tokens ?? [];
+
+  function handleOpenChange(nextOpen: boolean) {
+    setIsModalOpen(nextOpen);
+    if (!nextOpen) {
+      setCreatedToken(null);
+    }
+  }
+
+  return (
+    <div className="flex min-w-0 flex-col gap-32">
+      <section className="flex flex-col gap-16">
+        <div className="flex items-center justify-between gap-16 max-[640px]:items-start">
+          <div className="flex flex-col gap-4">
+            <Header variant="h3">Runner registration tokens</Header>
+            <Text size="sm" className="text-foreground-neutral-muted">
+              Register individual runner agents that run jobs directly in this workspace. Tokens are
+              reusable until revoked.
+            </Text>
+          </div>
+          <div className="flex items-center gap-12">
+            {tokensQuery.isFetching && !tokensQuery.isPending ? (
+              <Icon
+                name="loader4Line"
+                className="mt-2 size-18 text-foreground-neutral-muted"
+                aria-label="Refreshing tokens"
+              />
+            ) : null}
+            <Modal open={isModalOpen} onOpenChange={handleOpenChange}>
+              <ModalTrigger asChild>
+                <Button>Create token</Button>
+              </ModalTrigger>
+              <ModalContent aria-describedby={undefined}>
+                <ModalTitle className="sr-only">Create manual registration token</ModalTitle>
+                <ModalHeader>
+                  <Text
+                    size="lg"
+                    aria-hidden="true"
+                    className="overflow-ellipsis overflow-hidden whitespace-nowrap"
+                  >
+                    Create manual registration token
+                  </Text>
+                </ModalHeader>
+                {createdToken ? (
+                  <ModalBody className="gap-16">
+                    <CreatedManualRegistrationTokenPanel token={createdToken} />
+                  </ModalBody>
+                ) : (
+                  <CreateManualRegistrationTokenForm
+                    workspaceId={workspaceId}
+                    onCreated={setCreatedToken}
+                  />
+                )}
+              </ModalContent>
+            </Modal>
+          </div>
+        </div>
+
+        {tokensQuery.isPending ? <ManualRegistrationTokenTableSkeleton /> : null}
+
+        {tokensQuery.isError && tokensQuery.data === undefined ? (
+          <QueryLoadError query={tokensQuery} subject="manual registration tokens" />
+        ) : null}
+
+        {tokensQuery.data !== undefined && tokens.length === 0 ? (
+          <EmptyManualRegistrationTokens />
+        ) : null}
+
+        {tokens.length > 0 ? (
+          <ManualRegistrationTokenList workspaceId={workspaceId} tokens={tokens} />
+        ) : null}
+      </section>
+    </div>
+  );
+}

package/src/components/provisioner-token-errors.ts

@@ -0,0 +1,12 @@
+import {ApiError} from '@shipfox/client-api';
+
+export function provisionerTokenErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    if (error.code === 'network-error') {
+      return "We couldn't reach the server. Check your connection and try again.";
+    }
+    return error.message;
+  }
+  if (error instanceof Error) return error.message;
+  return 'Something went wrong. Try again.';
+}

package/src/components/provisioner-token-form-errors.test.ts

@@ -0,0 +1,35 @@
+import {ApiError} from '@shipfox/client-api';
+import {provisionerTokenCreateErrorToFormError} from './provisioner-token-form-errors.js';
+
+describe('provisionerTokenCreateErrorToFormError', () => {
+  test('routes ApiError to a form-level alert with the server message', () => {
+    const error = new ApiError({code: 'rate-limited', message: 'Try later', status: 429});
+
+    const result = provisionerTokenCreateErrorToFormError(error);
+
+    expect(result).toEqual({kind: 'form', message: 'Try later'});
+  });
+
+  test('routes network ApiError to a form-level alert with connection copy', () => {
+    const error = new ApiError({code: 'network-error', message: 'Network failed', status: 0});
+
+    const result = provisionerTokenCreateErrorToFormError(error);
+
+    expect(result).toEqual({
+      kind: 'form',
+      message: "We couldn't reach the server. Check your connection and try again.",
+    });
+  });
+
+  test('routes Error to a form-level alert with the error message', () => {
+    const result = provisionerTokenCreateErrorToFormError(new Error('boom'));
+
+    expect(result).toEqual({kind: 'form', message: 'boom'});
+  });
+
+  test('falls back to generic copy for non-Error throwables', () => {
+    const result = provisionerTokenCreateErrorToFormError('weird');
+
+    expect(result).toEqual({kind: 'form', message: 'Something went wrong. Try again.'});
+  });
+});

package/src/components/provisioner-token-form-errors.ts

@@ -0,0 +1,9 @@
+import {provisionerTokenErrorMessage} from './provisioner-token-errors.js';
+
+export type ProvisionerTokenCreateFormErrorMapping = {kind: 'form'; message: string};
+
+export function provisionerTokenCreateErrorToFormError(
+  error: unknown,
+): ProvisionerTokenCreateFormErrorMapping {
+  return {kind: 'form', message: provisionerTokenErrorMessage(error)};
+}