npm package: @nuucognition/mesh-integration-tests
Description: End-to-end verification that mesh-core, mesh-convex-component, and mesh-adapter-convex work together correctly. Proves the full Convex Track pipeline: markdown -> parse -> save to Convex -> load back -> verify.
Latest version: 1.0.0

# @nuucognition/mesh-integration-tests

End-to-end verification that mesh-core, mesh-convex-component, and mesh-adapter-convex work together correctly. Proves the full Convex Track pipeline: markdown -> parse -> save to Convex -> load back -> verify.

This is a test-only package with no public exports.

## Quick start

```bash
# Run all 27 tests (in-memory, no deployment needed)
pnpm --filter @nuucognition/mesh-integration-tests test

# Start real Convex dev server (first time creates project)
pnpm --filter @nuucognition/mesh-integration-tests dev

# Seed fixture data to real backend
pnpm --filter @nuucognition/mesh-integration-tests seed

# Clear seeded data
pnpm --filter @nuucognition/mesh-integration-tests seed:clear
```

## Test suites

### Component-level tests (`tests/integration/`)

Test mesh-core + mesh-convex-component directly via `convex-test` in-memory sandbox.

| File | Tests | Covers |
|------|-------|--------|
| `roundtrip.test.ts` | 6 | Save/load cycle, ID preservation, types/tags, links, content equality, empty mesh |
| `load-mesh.test.ts` | 3 | Backlink index, tag index, type index |
| `blob-ops.test.ts` | 3 | Blob save/load, URL retrieval, name index |
| `frontmatter.test.ts` | 2 | Nested YAML preservation, identical re-parse |

### Adapter E2E tests (`tests/e2e/`)

Test the full pipeline through `MeshConvexAdapter` -> `MeshConvex` -> Convex component -> mesh-core.

| File | Tests | Covers |
|------|-------|--------|
| `adapter-roundtrip.test.ts` | 6 | Full adapter save/load pipeline, IDs, metadata, content, indexes, empty mesh |
| `adapter-crud.test.ts` | 4 | Save/delete, missing delete, overwrite, multi-doc lifecycle |
| `adapter-blobs.test.ts` | 3 | Blob save/load, blob delete, name index |

**Total: 27 tests across 7 files.**

## Fixtures

### Documents (`tests/fixtures/documents/`)

| File | Purpose |
|------|---------|
| `note.md` | Basic document with ID, type, tags |
| `task.md` | Document with wiki-links and multiple tags |
| `linked-doc.md` | Links, embeds, and a broken link |
| `complex-frontmatter.md` | Nested YAML (objects, arrays, booleans, numbers) |

### Blobs (`tests/fixtures/blobs/`)

| File | Size | Content type |
|------|------|-------------|
| `photo.jpg` | 3.5KB | `image/jpeg` |
| `avatar.jpg` | 4KB | `image/jpeg` |
| `icon.jpg` | 1.8KB | `image/jpeg` |
| `diagram.svg` | 861B | `image/svg+xml` |

### Loader API (`tests/fixtures/index.ts`)

| Function | Returns |
|----------|---------|
| `loadFixture(name)` | `{ title, content }` |
| `loadAllFixtures()` | `{ title, content }[]` |
| `loadBlobFixture(file)` | `Buffer` |
| `loadAllBlobFixtures()` | `{ blobKey, data, contentType }[]` |

## Real Convex dev server

In addition to the in-memory test sandbox, this package includes a real Convex app for interactive exploration via the Convex dashboard.

### Setup

```bash
pnpm dev    # starts Convex dev server, generates convex/_generated/ and .env.local
pnpm seed   # seeds 2 meshes + 4 documents + 4 blobs
```

### Architecture

```
scripts/seed.ts (ConvexHttpClient over HTTP)
  -> convex/seed.ts (app-level mutation)
    -> components.mesh.meshes.create / documents.save / blobs.save
      -> mesh:meshes, mesh:documents, mesh:blobs tables
         (visible at dashboard.convex.dev)
```

### Proxy layer

`ConvexHttpClient` can only call app-level functions, not component functions directly. `convex/meshProxy.ts` provides thin wrappers:

- **Meshes**: `createMesh`, `getMesh`, `listMeshes`, `removeMesh`
- **Documents**: `saveDocument`, `listDocuments`, `getDocumentContent`, `removeDocument`
- **Blobs**: `generateUploadUrl`, `saveBlob`, `listBlobs`, `removeBlob`

### Seeded data

| Mesh ID | Name | Documents | Blobs |
|---------|------|-----------|-------|
| `test-fixtures` | Test Fixtures | 4 | 4 |
| `empty-mesh` | Empty Mesh | 0 | 0 |

## Test helpers (`tests/setup.ts`)

| Helper | Purpose |
|--------|---------|
| `createIntegrationTest()` | Creates `convex-test` instance with mesh component schema + modules |
| `createAdapterTest()` | Creates `MeshConvexAdapter` + `MeshConvex` wired to test instance |
| `loadMeshFromConvex(t, api, meshId)` | Inlined load flow for component-level tests |

## Package layout

```
convex/                 Real Convex app (for dev server)
  convex.config.ts      App definition + mesh component install
  schema.ts             Empty app schema
  meshProxy.ts          Proxy functions forwarding to component
  seed.ts               Batch seed/clear mutations
scripts/
  seed.ts               Client-side seeder using ConvexHttpClient
tests/
  setup.ts              Test harness (convex-test wiring)
  fixtures/
    documents/          4 markdown fixture files
    blobs/              4 image fixture files
    index.ts            Loader functions
  integration/          4 component-level test files (14 tests)
  e2e/                  3 adapter E2E test files (13 tests)
```

## Related packages

- `@nuucognition/mesh-core` — core types, parsing, building
- `@nuucognition/mesh-convex-component` — Convex component and client
- `@nuucognition/mesh-adapter-convex` — adapter bridge