@llm4ts/shell 0.17.0 → 0.18.0

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/services/cards/port.ts

@@ -0,0 +1,31 @@
+// CardsPort: the typed contract pages program against.
+// The wire shape is specified in contracts/cards.openapi.yaml; keep the two
+// in sync when either changes.
+
+export interface Money {
+  /** Minor units are NOT used; amount is a decimal number of major units. */
+  readonly amount: number;
+  /** ISO 4217 code, e.g. "EUR". */
+  readonly currency: string;
+}
+
+export type CardKind = 'debit' | 'credit';
+
+export type CardStatus = 'active' | 'blocked';
+
+export interface CardSummary {
+  readonly id: string;
+  readonly label: string;
+  /** Masked PAN, e.g. "**** **** **** 4242". */
+  readonly maskedPan: string;
+  readonly kind: CardKind;
+  readonly status: CardStatus;
+  readonly balance: Money;
+}
+
+export interface CardsPort {
+  listCards(customerId: string): Promise<ReadonlyArray<CardSummary>>;
+}
+
+/** Adapters are created through a factory so wiring stays in the registry. */
+export type CardsPortFactory = () => CardsPort;

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/services/profile/mock.ts

@@ -0,0 +1,45 @@
+// Mock adapter for ProfilePort: deterministic fixture data plus a small
+// artificial delay so pages exercise their loading states. Updates are kept
+// in memory for the lifetime of the adapter.
+
+import type { Profile, ProfilePort, ProfilePortFactory } from './port';
+
+const DELAY_MS = 20;
+
+const delay = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+const FIXTURE_PROFILE: Profile = {
+  customerId: 'CUST-1001',
+  fullName: 'Ada Doe',
+  email: 'ada.doe@example.invalid',
+  phone: '+00 555 0100',
+};
+
+export const makeMockProfilePort: ProfilePortFactory = () => {
+  const profiles = new Map<string, Profile>([
+    [FIXTURE_PROFILE.customerId, FIXTURE_PROFILE],
+  ]);
+
+  const port: ProfilePort = {
+    async getProfile(customerId) {
+      await delay(DELAY_MS);
+      const profile = profiles.get(customerId);
+      if (profile === undefined) {
+        throw new Error(`Unknown customer: ${customerId}`);
+      }
+      return profile;
+    },
+    async updateProfile(customerId, update) {
+      await delay(DELAY_MS);
+      const current = profiles.get(customerId);
+      if (current === undefined) {
+        throw new Error(`Unknown customer: ${customerId}`);
+      }
+      const next: Profile = { customerId: current.customerId, ...update };
+      profiles.set(customerId, next);
+      return next;
+    },
+  };
+  return port;
+};

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/services/profile/port.ts

@@ -0,0 +1,24 @@
+// ProfilePort: the typed contract pages program against.
+// The wire shape is specified in contracts/profile.openapi.yaml; keep the two
+// in sync when either changes.
+
+export interface Profile {
+  readonly customerId: string;
+  readonly fullName: string;
+  readonly email: string;
+  readonly phone: string;
+}
+
+export interface ProfileUpdate {
+  readonly fullName: string;
+  readonly email: string;
+  readonly phone: string;
+}
+
+export interface ProfilePort {
+  getProfile(customerId: string): Promise<Profile>;
+  updateProfile(customerId: string, update: ProfileUpdate): Promise<Profile>;
+}
+
+/** Adapters are created through a factory so wiring stays in the registry. */
+export type ProfilePortFactory = () => ProfilePort;

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/services/registry.ts

@@ -0,0 +1,20 @@
+// Service registry: the single place adapters are wired to ports.
+// Pages obtain ports ONLY through these getters — never by importing an
+// adapter directly. Swapping the mock for a real gateway adapter is a
+// one-line change per domain (replace the makeMock* factory).
+
+import { makeMockCardsPort } from './cards/mock';
+import type { CardsPort } from './cards/port';
+import { makeMockProfilePort } from './profile/mock';
+import type { ProfilePort } from './profile/port';
+
+const cardsPort: CardsPort = makeMockCardsPort();
+const profilePort: ProfilePort = makeMockProfilePort();
+
+export function getCardsPort(): CardsPort {
+  return cardsPort;
+}
+
+export function getProfilePort(): ProfilePort {
+  return profilePort;
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/theme/components.css

@@ -0,0 +1,269 @@
+/* DemoBank component styles. One class family per design-system component,
+   prefixed db-. Pages never define their own CSS files; they compose these
+   components. See CONTRIBUTING.md. */
+
+body {
+  margin: 0;
+  font-family: var(--db-font-family);
+  font-size: var(--db-font-size-md);
+  color: var(--db-color-ink);
+  background: var(--db-color-surface-sunken);
+}
+
+/* App shell */
+.db-shell-header {
+  display: flex;
+  align-items: center;
+  gap: var(--db-space-6);
+  padding: var(--db-space-3) var(--db-space-6);
+  background: var(--db-color-brand-strong);
+  color: var(--db-color-brand-contrast);
+}
+
+.db-shell-brand {
+  font-size: var(--db-font-size-lg);
+  font-weight: 700;
+  letter-spacing: 0.02em;
+}
+
+.db-shell-nav {
+  display: flex;
+  gap: var(--db-space-4);
+}
+
+.db-shell-nav a {
+  color: var(--db-color-brand-contrast);
+  text-decoration: none;
+  font-size: var(--db-font-size-sm);
+  opacity: 0.9;
+}
+
+.db-shell-nav a:hover {
+  opacity: 1;
+  text-decoration: underline;
+}
+
+.db-shell-user {
+  margin-left: auto;
+  font-size: var(--db-font-size-sm);
+  opacity: 0.9;
+}
+
+/* PageLayout */
+.db-page {
+  max-width: 56rem;
+  margin: 0 auto;
+  padding: var(--db-space-8) var(--db-space-6);
+}
+
+.db-page-header {
+  display: flex;
+  align-items: flex-end;
+  gap: var(--db-space-4);
+  margin-bottom: var(--db-space-6);
+}
+
+.db-page-title {
+  margin: 0;
+  font-size: var(--db-font-size-xl);
+}
+
+.db-page-subtitle {
+  margin: var(--db-space-1) 0 0;
+  color: var(--db-color-ink-muted);
+  font-size: var(--db-font-size-sm);
+}
+
+.db-page-actions {
+  margin-left: auto;
+  display: flex;
+  gap: var(--db-space-2);
+}
+
+/* Card */
+.db-card {
+  background: var(--db-color-surface);
+  border: 1px solid var(--db-color-border);
+  border-radius: var(--db-radius-md);
+  box-shadow: var(--db-shadow-card);
+  padding: var(--db-space-6);
+  margin-bottom: var(--db-space-6);
+}
+
+.db-card-title {
+  margin: 0 0 var(--db-space-4);
+  font-size: var(--db-font-size-lg);
+}
+
+/* Button */
+.db-button {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--db-space-2);
+  padding: var(--db-space-2) var(--db-space-4);
+  border-radius: var(--db-radius-sm);
+  border: 1px solid transparent;
+  font: inherit;
+  font-size: var(--db-font-size-sm);
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.db-button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.db-button--primary {
+  background: var(--db-color-brand);
+  color: var(--db-color-brand-contrast);
+}
+
+.db-button--primary:hover:not(:disabled) {
+  background: var(--db-color-brand-strong);
+}
+
+.db-button--secondary {
+  background: var(--db-color-surface);
+  color: var(--db-color-brand);
+  border-color: var(--db-color-brand);
+}
+
+.db-button--ghost {
+  background: transparent;
+  color: var(--db-color-brand);
+}
+
+/* Field */
+.db-field {
+  display: block;
+  margin-bottom: var(--db-space-4);
+}
+
+.db-field-label {
+  display: block;
+  margin-bottom: var(--db-space-1);
+  font-size: var(--db-font-size-sm);
+  font-weight: 600;
+}
+
+.db-field input,
+.db-field select,
+.db-field textarea {
+  width: 100%;
+  box-sizing: border-box;
+  padding: var(--db-space-2) var(--db-space-3);
+  border: 1px solid var(--db-color-border);
+  border-radius: var(--db-radius-sm);
+  font: inherit;
+  background: var(--db-color-surface);
+}
+
+.db-field--invalid input,
+.db-field--invalid select,
+.db-field--invalid textarea {
+  border-color: var(--db-color-danger);
+}
+
+.db-field-error {
+  margin: var(--db-space-1) 0 0;
+  color: var(--db-color-danger);
+  font-size: var(--db-font-size-sm);
+}
+
+/* Form */
+.db-form-actions {
+  display: flex;
+  gap: var(--db-space-2);
+  margin-top: var(--db-space-6);
+}
+
+.db-form-status {
+  margin: var(--db-space-4) 0 0;
+  padding: var(--db-space-2) var(--db-space-3);
+  border-radius: var(--db-radius-sm);
+  font-size: var(--db-font-size-sm);
+}
+
+.db-form-status--success {
+  background: var(--db-color-success-soft);
+  color: var(--db-color-success);
+}
+
+/* DataTable */
+.db-table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.db-table caption {
+  caption-side: top;
+  text-align: left;
+  font-size: var(--db-font-size-sm);
+  color: var(--db-color-ink-muted);
+  margin-bottom: var(--db-space-2);
+}
+
+.db-table th,
+.db-table td {
+  text-align: left;
+  padding: var(--db-space-2) var(--db-space-3);
+  border-bottom: 1px solid var(--db-color-border);
+  font-size: var(--db-font-size-sm);
+}
+
+.db-table th {
+  color: var(--db-color-ink-muted);
+  font-weight: 600;
+}
+
+.db-table-empty {
+  padding: var(--db-space-6);
+  text-align: center;
+  color: var(--db-color-ink-muted);
+}
+
+/* Stepper */
+.db-stepper {
+  display: flex;
+  gap: var(--db-space-4);
+  list-style: none;
+  margin: 0 0 var(--db-space-6);
+  padding: 0;
+}
+
+.db-stepper-step {
+  display: flex;
+  align-items: center;
+  gap: var(--db-space-2);
+  font-size: var(--db-font-size-sm);
+  color: var(--db-color-ink-muted);
+}
+
+.db-stepper-step--active {
+  color: var(--db-color-ink);
+  font-weight: 600;
+}
+
+.db-stepper-index {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  border-radius: 50%;
+  background: var(--db-color-surface);
+  border: 1px solid var(--db-color-border);
+}
+
+.db-stepper-step--active .db-stepper-index {
+  background: var(--db-color-brand);
+  border-color: var(--db-color-brand);
+  color: var(--db-color-brand-contrast);
+}
+
+/* Utility */
+.db-loading {
+  color: var(--db-color-ink-muted);
+  font-size: var(--db-font-size-sm);
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/theme/tokens.css

@@ -0,0 +1,38 @@
+/* DemoBank design tokens. Components consume ONLY these custom properties —
+   never hard-coded colors or spacing. See CONTRIBUTING.md. */
+:root {
+  /* Color */
+  --db-color-ink: #16232e;
+  --db-color-ink-muted: #5a6b78;
+  --db-color-surface: #ffffff;
+  --db-color-surface-sunken: #f2f5f7;
+  --db-color-border: #d4dde3;
+  --db-color-brand: #0f5f5c;
+  --db-color-brand-strong: #0a4341;
+  --db-color-brand-contrast: #ffffff;
+  --db-color-danger: #b4232a;
+  --db-color-danger-soft: #fbeaea;
+  --db-color-success: #1d6b3a;
+  --db-color-success-soft: #e8f4ec;
+
+  /* Typography */
+  --db-font-family:
+    'Avenir Next', 'Segoe UI', system-ui, -apple-system, sans-serif;
+  --db-font-size-sm: 0.8125rem;
+  --db-font-size-md: 0.9375rem;
+  --db-font-size-lg: 1.125rem;
+  --db-font-size-xl: 1.5rem;
+
+  /* Spacing (4px scale) */
+  --db-space-1: 0.25rem;
+  --db-space-2: 0.5rem;
+  --db-space-3: 0.75rem;
+  --db-space-4: 1rem;
+  --db-space-6: 1.5rem;
+  --db-space-8: 2rem;
+
+  /* Shape */
+  --db-radius-sm: 4px;
+  --db-radius-md: 8px;
+  --db-shadow-card: 0 1px 3px rgba(22, 35, 46, 0.12);
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/tests/cards.page.test.tsx

@@ -0,0 +1,81 @@
+// House test style for list pages: swap the registry for an instrumented
+// port, render inside AuthProvider, assert rows render and the port was
+// called with the signed-in customer's id.
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach } from 'vitest';
+import { AuthProvider } from '@/auth/AuthProvider';
+import type { CardSummary } from '@/services/cards/port';
+import CardsPage from '@/app/cards/page';
+
+const { listCards } = vi.hoisted(() => ({
+  listCards:
+    vi.fn<(customerId: string) => Promise<ReadonlyArray<CardSummary>>>(),
+}));
+
+vi.mock('@/services/registry', () => ({
+  getCardsPort: () => ({ listCards }),
+}));
+
+const FIXTURE_CARDS: ReadonlyArray<CardSummary> = [
+  {
+    id: 'card-100',
+    label: 'Test Debit',
+    maskedPan: '**** **** **** 1111',
+    kind: 'debit',
+    status: 'active',
+    balance: { amount: 10, currency: 'EUR' },
+  },
+  {
+    id: 'card-200',
+    label: 'Test Credit',
+    maskedPan: '**** **** **** 2222',
+    kind: 'credit',
+    status: 'blocked',
+    balance: { amount: -5, currency: 'EUR' },
+  },
+];
+
+const renderPage = () =>
+  render(
+    <AuthProvider>
+      <CardsPage />
+    </AuthProvider>,
+  );
+
+describe('CardsPage', () => {
+  beforeEach(() => {
+    listCards.mockReset();
+    listCards.mockResolvedValue(FIXTURE_CARDS);
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it('renders a loading state, then one row per card from the port', async () => {
+    renderPage();
+    expect(screen.getByText('Loading your cards…')).toBeDefined();
+
+    expect(await screen.findByText('Test Debit')).toBeDefined();
+    expect(screen.getByText('Test Credit')).toBeDefined();
+    expect(screen.getByText('**** **** **** 1111')).toBeDefined();
+    expect(screen.getAllByRole('row')).toHaveLength(3); // header + 2 cards
+  });
+
+  it('asks the port for the signed-in customer', async () => {
+    renderPage();
+    await screen.findByText('Test Debit');
+
+    expect(listCards).toHaveBeenCalledTimes(1);
+    expect(listCards).toHaveBeenCalledWith('CUST-1001');
+  });
+
+  it('shows the empty state when the port returns no cards', async () => {
+    listCards.mockResolvedValue([]);
+    renderPage();
+
+    expect(await screen.findByText('You have no cards yet.')).toBeDefined();
+  });
+});

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/tests/profile.page.test.tsx

@@ -0,0 +1,87 @@
+// House test style for form pages: swap the registry for an instrumented
+// port, render inside AuthProvider, assert the fields render, validation
+// fires, and the port receives the expected payload on save.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { AuthProvider } from '@/auth/AuthProvider';
+import type { Profile, ProfileUpdate } from '@/services/profile/port';
+import ProfilePage from '@/app/profile/page';
+
+const { getProfile, updateProfile } = vi.hoisted(() => ({
+  getProfile: vi.fn<(customerId: string) => Promise<Profile>>(),
+  updateProfile:
+    vi.fn<(customerId: string, update: ProfileUpdate) => Promise<Profile>>(),
+}));
+
+vi.mock('@/services/registry', () => ({
+  getProfilePort: () => ({ getProfile, updateProfile }),
+}));
+
+const FIXTURE_PROFILE: Profile = {
+  customerId: 'CUST-1001',
+  fullName: 'Ada Doe',
+  email: 'ada.doe@example.invalid',
+  phone: '+00 555 0100',
+};
+
+const renderPage = () =>
+  render(
+    <AuthProvider>
+      <ProfilePage />
+    </AuthProvider>,
+  );
+
+describe('ProfilePage', () => {
+  beforeEach(() => {
+    getProfile.mockReset();
+    updateProfile.mockReset();
+    getProfile.mockResolvedValue(FIXTURE_PROFILE);
+    updateProfile.mockImplementation(async (customerId, update) => ({
+      customerId,
+      ...update,
+    }));
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it('renders the profile fields with values from the port', async () => {
+    renderPage();
+
+    expect(await screen.findByLabelText('Full name')).toBeDefined();
+    expect(screen.getByLabelText('Email')).toBeDefined();
+    expect(screen.getByLabelText('Phone')).toBeDefined();
+    expect(screen.getByDisplayValue('Ada Doe')).toBeDefined();
+    expect(screen.getByDisplayValue('ada.doe@example.invalid')).toBeDefined();
+    expect(getProfile).toHaveBeenCalledWith('CUST-1001');
+  });
+
+  it('fires validation and does not call the port on invalid input', async () => {
+    renderPage();
+    const email = await screen.findByLabelText('Email');
+
+    fireEvent.change(email, { target: { value: 'not-an-email' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Save changes' }));
+
+    expect(await screen.findByText('Enter a valid email address.')).toBeDefined();
+    expect(updateProfile).not.toHaveBeenCalled();
+  });
+
+  it('saves through the port with the expected payload', async () => {
+    renderPage();
+    const fullName = await screen.findByLabelText('Full name');
+
+    fireEvent.change(fullName, { target: { value: 'Ada Q. Doe' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Save changes' }));
+
+    expect(await screen.findByText('Profile saved.')).toBeDefined();
+    expect(updateProfile).toHaveBeenCalledTimes(1);
+    expect(updateProfile).toHaveBeenCalledWith('CUST-1001', {
+      fullName: 'Ada Q. Doe',
+      email: 'ada.doe@example.invalid',
+      phone: '+00 555 0100',
+    });
+  });
+});

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/tsconfig.json

@@ -0,0 +1,54 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "ES2022"
+    ],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "preserve",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "allowJs": false,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "incremental": false,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    },
+    "types": [
+      "react",
+      "react-dom",
+      "node"
+    ],
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "tests/**/*.ts",
+    "tests/**/*.tsx",
+    "vitest.config.ts",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    ".next",
+    "out"
+  ]
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/vitest.config.ts

@@ -0,0 +1,17 @@
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  esbuild: {
+    jsx: 'automatic',
+  },
+  test: {
+    environment: 'jsdom',
+    include: ['tests/**/*.test.ts', 'tests/**/*.test.tsx'],
+  },
+});