adding test stuff

Author: devalbo

.claude/settings.local.json

@@ -3,7 +3,8 @@
     "allow": [
       "Bash(npm run build:*)",
       "WebFetch(domain:localhost)",
-      "Bash(npx tsc:*)"
+      "Bash(npx tsc:*)",
+      "Bash(npm run test:run:*)"
     ]
   }
 }

.gitignore

@@ -22,3 +22,12 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
+
+*storybook.log
+storybook-static
+
+# Playwright BDD
+.features-gen
+test-results
+playwright-report
+playwright/.cache

.storybook/main.ts

@@ -0,0 +1,17 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  "stories": [
+    "../src/**/*.mdx",
+    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"
+  ],
+  "addons": [
+    "@chromatic-com/storybook",
+    "@storybook/addon-vitest",
+    "@storybook/addon-a11y",
+    "@storybook/addon-docs",
+    "@storybook/addon-onboarding"
+  ],
+  "framework": "@storybook/react-vite"
+};
+export default config;

.storybook/preview.tsx

@@ -0,0 +1,115 @@
+import React from 'react'
+import type { Preview, Decorator } from '@storybook/react-vite'
+import { createStore, createIndexes, Store, Indexes } from 'tinybase'
+import { Provider } from 'tinybase/ui-react'
+import { FOAF, VCARD } from '@inrupt/vocab-common-rdf'
+
+// Create sample store with test data for stories
+function createSampleStore(): { store: Store; indexes: Indexes } {
+  const store = createStore()
+  const indexes = createIndexes(store)
+
+  // Initialize tables
+  store.setTables({
+    resources: {},
+    personas: {},
+    contacts: {},
+    groups: {},
+    typeIndexes: {},
+  })
+
+  // Add sample personas
+  store.setRow('personas', 'persona-1', {
+    '@id': 'https://pod.example.com/profiles/alice#me',
+    '@type': FOAF.Person,
+    [FOAF.name]: 'Alice Smith',
+    [FOAF.nick]: 'alice',
+    [VCARD.hasEmail]: 'mailto:alice@example.com',
+  })
+
+  store.setRow('personas', 'persona-2', {
+    '@id': 'https://pod.example.com/profiles/bob#me',
+    '@type': FOAF.Person,
+    [FOAF.name]: 'Bob Developer',
+    [VCARD.hasEmail]: 'mailto:bob@work.com',
+  })
+
+  // Add sample contacts
+  store.setRow('contacts', 'contact-1', {
+    '@id': 'https://pod.example.com/contacts/john#',
+    '@type': VCARD.Individual,
+    [VCARD.fn]: 'John Doe',
+    [VCARD.nickname]: 'johnny',
+    [VCARD.hasEmail]: 'mailto:john@example.com',
+    [VCARD.hasOrganizationName]: 'Acme Corp',
+  })
+
+  store.setRow('contacts', 'contact-2', {
+    '@id': 'https://pod.example.com/contacts/jane#',
+    '@type': VCARD.Individual,
+    [VCARD.fn]: 'Jane Smith',
+    [VCARD.hasEmail]: 'mailto:jane@example.com',
+  })
+
+  store.setRow('contacts', 'contact-3', {
+    '@id': 'https://pod.example.com/contacts/ai-bot#',
+    '@type': 'https://schema.org/SoftwareApplication',
+    [VCARD.fn]: 'AI Assistant',
+    [VCARD.note]: 'A helpful AI chatbot',
+  })
+
+  // Add sample groups
+  store.setRow('groups', 'group-1', {
+    '@id': 'https://pod.example.com/groups/acme#org',
+    '@type': 'http://www.w3.org/ns/org#Organization',
+    [VCARD.fn]: 'Acme Corporation',
+    'http://purl.org/dc/terms/description': 'A sample organization',
+  })
+
+  store.setRow('groups', 'group-2', {
+    '@id': 'https://pod.example.com/groups/team-alpha#team',
+    '@type': VCARD.Group,
+    [VCARD.fn]: 'Team Alpha',
+    'http://purl.org/dc/terms/description': 'The best team',
+  })
+
+  // Set default persona
+  store.setValue('defaultPersonaId', 'persona-1')
+
+  return { store, indexes }
+}
+
+// Global decorator that wraps all stories in TinyBase Provider
+const withTinyBase: Decorator = (Story, context) => {
+  // Allow stories to provide their own store via parameters
+  const customStore = context.parameters.store
+  const { store, indexes } = customStore || createSampleStore()
+
+  return (
+    <Provider store={store} indexes={indexes}>
+      <Story />
+    </Provider>
+  )
+}
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    // Default background
+    backgrounds: {
+      default: 'light',
+      values: [
+        { name: 'light', value: '#f5f5f5' },
+        { name: 'dark', value: '#1a1a1a' },
+      ],
+    },
+  },
+  decorators: [withTinyBase],
+}
+
+export default preview

AGENTS.md

@@ -21,7 +21,7 @@ Context for AI assistants working on this repo.
 | `src/utils/` | settings, storeExport, typeIndex helpers, validation. |
 | `src/cli/` | CliTerminal, command registry, parse-args, types. |
 | `src/components/` | PersonaList/Form, ContactList/Form, GroupList/Form, MembershipManager, FileMetadataPanel. |
-| `docs/` | DESIGN.md, IMPLEMENTATION_PLAN.md. |
+| `docs/` | CODING_GUIDELINES.md, DESIGN.md, IMPLEMENTATION_PLAN.md, testing/. |
 
 ## What’s done so far
 
@@ -71,5 +71,6 @@ When someone wants to use this in an app they’re working on, point them to the
 ## Useful docs
 
 - **README.md** – Overview, limitations, Use as a library (Zod + JSON Schema), Integration Guide (copy-paste vs install-from-GitHub), Getting Started (Node note, Live demo + 404 troubleshooting), CLI command list.  
+- **docs/CODING_GUIDELINES.md** – TypeScript (strict types, no sloppy types), short functions, simple React components, naming, file length.  
 - **docs/IMPLEMENTATION_PLAN.md** – Feature/phases.  
 - **DESIGN.md** – Design notes.

README.md

@@ -438,6 +438,54 @@ export|import                 Data portability
 clear                         Clear terminal
 ```
 
+## Testing
+
+- **Unit tests (Vitest):** `npm test` or `npm run test:run`; coverage: `npm run test:coverage`
+- **BDD / E2E (Playwright):** Generate specs from Gherkin, then run Playwright:
+  ```bash
+  npx bddgen && npx playwright test
+  ```
+  Or use the scripts: `npm run test:e2e` or `npm run test:bdd` (same thing). With browser visible: `npm run test:e2e:headed`.
+
+  **Start the server manually (recommended if E2E hangs):** In one terminal start the app; in another run the tests. Playwright will reuse the existing server on port 5173 (`reuseExistingServer` when not in CI).
+  1. **Terminal 1:** `npm run dev` — leave it running (app at http://localhost:5173).
+  2. **Terminal 2:** `npx bddgen && npx playwright test` (or `npm run test:e2e`).
+
+  If you use a different port for the app, set `E2E_BASE_URL` so Playwright hits the right URL (e.g. `E2E_BASE_URL=http://localhost:3000 npx playwright test` after starting the app on 3000).
+
+### Try the BDD steps manually
+
+You can run through the BDD scenarios by hand to verify behavior without Playwright:
+
+1. **App shell**
+   - Open the app (`npm run dev`, then http://localhost:5173).
+   - Check the browser tab title contains `tb-solid-pod`.
+   - Click the **Terminal** tab and confirm you see the CLI welcome message or prompt.
+
+2. **CLI contacts**
+   - Go to the **Terminal** tab.
+   - Run: `contact add JohnDoe --email=john@example.com` → you should see **Added contact: JohnDoe**.
+   - Run: `contact add JaneSmith` then `contact list` → you should see **JaneSmith** in the list.
+   - Run: `contact` → you should see **Usage: contact**, **Subcommands**, **add**, and **list** in the help.
+
+3. **CLI personas**
+   - In the Terminal, run: `persona create TestUser --email=test@example.com` → you should see **Created persona: TestUser**.
+   - Run: `persona list` → you should see **Persona** (or personas list / empty message).
+   - Run: `persona` → you should see **Usage: persona**, **Subcommands**, and **create** in the help.
+
+4. **CLI navigation**
+   - Run: `help` → you should see **help**, **contact**, **persona** in the output.
+   - Run: `contact list` then `clear` → terminal output should clear.
+
+5. **UI tabs**
+   - Click **Contacts** → you should see the contacts view (list or empty state).
+   - Click **Personas** → you should see the personas view.
+   - Confirm **Personas**, **Contacts**, and **Terminal** tabs are visible.
+
+Feature files live under `tests/features/` (e.g. `cli-contacts.feature`, `app.feature`). Step definitions are in `tests/features/steps/`. After changing `.feature` or steps, run `npx bddgen` before `npx playwright test`.
+
+For more detail (where results are stored, unit/BDD/Storybook guidelines), see **[docs/testing/](docs/testing/README.md)**. For coding standards (strict TypeScript, short functions, simple components), see **[docs/CODING_GUIDELINES.md](docs/CODING_GUIDELINES.md)**.
+
 ## License
 
 AGPL-3.0-or-later. See [LICENSE](LICENSE).

docs/CODING_GUIDELINES.md

@@ -0,0 +1,41 @@
+# Coding guidelines
+
+Keep the codebase maintainable: strict types, small units of work, and simple React components.
+
+## TypeScript
+
+- **Strict types only.** The project uses `strict: true` in `tsconfig.json`. Do not relax it.
+- **Avoid `any`.** Use `unknown` and narrow with type guards, or define proper interfaces. If you must escape types, use a minimal cast and comment why.
+- **Prefer explicit types** for function parameters and return values in public APIs (exports, component props). Let inference do the work inside small, local functions when it’s obvious.
+- **Model data with interfaces or types.** Use Zod schemas as the source of truth for domain shapes; align TypeScript types with them (e.g. `z.infer<typeof MySchema>`).
+- **No sloppy object types.** Avoid `Record<string, unknown>` in public APIs unless you’re truly handling arbitrary data; prefer named properties and interfaces.
+
+## Functions
+
+- **Keep functions short.** Aim for a single level of abstraction and one clear responsibility. If a function is long or doing several things, split it.
+- **Extract helpers** for repeated logic or non-trivial calculations. Put them in a small, testable function or a shared util.
+- **Limit parameters.** If a function takes more than a few arguments, consider an options object or a small typed config.
+
+## React components
+
+- **Keep components small.** If a component is long or has many branches, extract subcomponents or custom hooks.
+- **Avoid overly complex components.** Prefer many small components over one large one. Use composition.
+- **Custom hooks for stateful logic.** If a component has non-trivial state or effects, move that logic into a `useSomething` hook and keep the component mostly presentational.
+- **Props: typed and minimal.** Define a clear props interface; avoid spreading large objects “just in case.”
+
+## General
+
+- **Naming:** Use clear, consistent names. Prefer `handleSubmit` over `onClick` for handlers passed as props; keep event handlers and callbacks obvious.
+- **File length:** If a file grows past roughly 200–300 lines, consider splitting (e.g. by component, by feature, or into a small folder).
+- **Comments:** Comment *why* when it’s not obvious from the code; avoid restating what the code does.
+- **Tests:** New behavior should have unit tests where practical. Follow existing patterns in `tests/unit/` and use the test helpers (e.g. `renderWithProviders`, `createTestStore`).
+
+## Dependencies
+
+- **When picking a library, prefer ones written in TypeScript with strict typing conventions.** Good type definitions (or first-party TypeScript) reduce runtime bugs and make refactors safer; avoid libraries that rely on loose or hand-maintained `@types` if a better-typed alternative exists.
+
+## Process
+
+- **When a refactor or code change breaks a test, do not automatically fix the test.** The developer who made the change is responsible for resolving the failure: either update the code so the test passes again, or change the test only after deciding that the new behavior is correct and the test’s expectations were wrong. Do not silently adjust tests to match new behavior without that decision.
+
+These guidelines apply to `src/` and `tests/`; tooling and config can be more permissive where needed.