@codyswann/lisa 2.166.5 → 2.168.0

package/plugins/src/harper-fabric/skills/harper-rest-queries/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: harper-rest-queries
+description: This skill should be used when building or debugging Harper (HarperDB/Fabric) REST collection queries and Resource search methods - filters, FIQL comparison operators, OR/grouping, select, sort, limit/offset pagination, relationship traversal, request context, and transaction boundaries. Use it when adding list endpoints, admin filters, query builders, or multi-write resource methods. Pairs with harper-resources and harper-schema-graphql.
+---
+
+# Harper REST Queries
+
+## Overview
+
+Harper exposes exported tables and custom Resources as REST endpoints when
+`rest: true` is enabled. Collection `GET` requests use URL query parameters for
+filtering, sorting, projection, pagination, and relationship traversal. The same
+query shape is available inside Resources through `search(query)` and
+`tables.X.search(query)`.
+
+Use Harper's native query surface before hand-filtering records in JavaScript.
+Hand-filtering is only acceptable after a selective indexed condition has already
+narrowed the candidate set and the behavior cannot be represented by the REST
+query language.
+
+Cross-check endpoint ownership and generated resource conventions in
+[[harper-resources]]. Cross-check table names, indexes, exported resources, and
+relationships in [[harper-schema-graphql]].
+
+## REST collection syntax
+
+REST queries run against collection paths with a trailing slash:
+
+```text
+GET /products/?category=software
+GET /products/?category=software&active=true
+```
+
+Rules:
+
+- Query attributes that appear in conditions should be indexed with `@indexed`.
+- Multiple `&` conditions are ANDed.
+- `|` combines conditions with OR logic.
+- Use square brackets for grouping generated from user input because they encode
+  cleanly in URLs.
+- Encode reserved characters, especially `:` in dates as `%3A`.
+
+Common condition examples:
+
+```text
+GET /products/?category=software
+GET /products/?price=gt=100
+GET /products/?price=ge=100&price=lt=200
+GET /products/?price=gt=100&price=lt=200
+GET /products/?name==Keyboard*
+GET /products/?rating=5|featured=true
+GET /products/?rating=5&[tag=fast|tag=scalable|tag=efficient]
+GET /products/?discount=null
+GET /products/?listDate=gt=2026-01-05T20%3A07%3A27.955Z
+```
+
+## Operators
+
+Harper REST comparison operators use FIQL-style syntax:
+
+| URL operator | Programmatic comparator | Meaning |
+| --- | --- | --- |
+| `==` | `equals` | Equal with type conversion |
+| `=lt=` / `lt=` | `less_than` | Less than |
+| `=le=` / `le=` | `less_than_equal` | Less than or equal |
+| `=gt=` / `gt=` | `greater_than` | Greater than |
+| `=ge=` / `ge=` | `greater_than_equal` | Greater than or equal |
+| `=ne=` / `!=` | `not_equal` | Not equal |
+| `=ct=` | `contains` | String contains |
+| `=sw=` / `==value*` | `starts_with` | String starts with |
+| `=ew=` | `ends_with` | String ends with |
+| `=` / `===` | strict equality | No automatic URL-value conversion |
+| `!==` | strict inequality | No automatic URL-value conversion |
+
+For FIQL comparators, Harper converts strings such as `null`, `true`, numbers,
+and schema-typed values before searching. Use explicit prefixes when a generated
+URL must control conversion:
+
+```text
+GET /products/?price==number:123
+GET /products/?active==boolean:true
+GET /products/?sku==string:00123
+GET /products/?createdAt==date:2026-01-05T20%3A07%3A27.955Z
+```
+
+## Select, sort, and pagination
+
+Use query functions for projection, paging, and order:
+
+```text
+GET /products/?category=software&select(id,name,price)
+GET /products/?category=software&select([id,name])
+GET /products/?category=software&limit(20)
+GET /products/?category=software&limit(40,60)
+GET /products/?category=software&sort(+name)
+GET /products/?category=software&sort(+rating,-price)
+```
+
+Guidance:
+
+- `select(property)` returns a single property directly.
+- `select(property1,property2)` returns objects with those properties.
+- `select([property1,property2])` returns arrays of selected property values.
+- `limit(end)` returns the first `end` records.
+- `limit(start,end)` uses `start` as the offset and returns through `end`.
+- Prefix sort fields with `+` for ascending and `-` for descending.
+- Prefer sorting on an indexed field used by the primary condition, or a narrow
+  result set that can be sorted cheaply.
+
+Programmatic pagination normally uses `limit` and `offset`:
+
+```javascript
+const pageSize = 20;
+const page = Number(url.searchParams.get('page') ?? 0);
+
+const products = await tables.Products.search({
+  conditions: [{ attribute: 'category', value: 'software' }],
+  sort: { attribute: 'createdAt', descending: true },
+  limit: pageSize,
+  offset: page * pageSize,
+});
+```
+
+## Relationship queries
+
+Relationship attributes can be queried with dot syntax when the relationship is
+declared in `schema.graphql` and the foreign key fields are indexed:
+
+```graphql
+type Product @table @export(name: "products") {
+  id: Long @primaryKey
+  name: String
+  brandId: Long @indexed
+  brand: Brand @relationship(from: brandId)
+}
+
+type Brand @table @export(name: "brands") {
+  id: Long @primaryKey
+  name: String @indexed
+  products: [Product] @relationship(to: brandId)
+}
+```
+
+```text
+GET /products/?brand.name=Microsoft
+GET /brands/?products.name=Keyboard
+GET /products/?brand.name=Microsoft&select(id,name,brand{name})
+```
+
+Filtering on a related table behaves like an inner join. Selecting a relationship
+without filtering can behave like a left join; missing relationships may be
+omitted from returned records. Keep relationship names and directives aligned
+with [[harper-schema-graphql]] before changing a route.
+
+## Programmatic search
+
+Use `search(query)` inside custom Resources when the endpoint needs validation,
+authorization, response shaping, or side effects around Harper's native query
+engine:
+
+```javascript
+export class Products extends tables.Products {
+  static async search(query, context) {
+    const safeQuery = {
+      ...query,
+      conditions: [
+        ...(Array.isArray(query.conditions) ? query.conditions : []),
+        { attribute: 'tenantId', value: context.user.tenantId },
+      ],
+      limit: Math.min(query.limit ?? 50, 100),
+    };
+
+    return super.search(safeQuery, context);
+  }
+}
+```
+
+Call table resources directly from other resource methods when you are composing
+server-side behavior:
+
+```javascript
+const products = await tables.Products.search({
+  conditions: [
+    { attribute: 'category', value: 'software' },
+    { attribute: 'price', comparator: 'less_than', value: 200 },
+  ],
+  sort: { attribute: 'rating', descending: true },
+  limit: 20,
+});
+```
+
+Useful query keys:
+
+| Key | Use |
+| --- | --- |
+| `conditions` | Attribute predicates. Use an array for AND-style filters. |
+| `sort` | Sort descriptor. Prefer indexed fields for large result sets. |
+| `limit` | Maximum records returned. Always cap client-controlled values. |
+| `offset` | Pagination offset. Prefer stable sort when offset is used. |
+| `select` | Projection list. Keep admin-only fields out of public responses. |
+| `explain` | Debug execution order and index usage while tuning. |
+
+`search()` can return an `AsyncIterable`. When iterating manually or stopping
+early, drain it or call the iterator's `return()` in `finally` so Harper can
+release the read transaction:
+
+```javascript
+const iterator = tables.Products
+  .search({ conditions: [{ attribute: 'status', value: 'active' }] })
+  [Symbol.asyncIterator]();
+
+try {
+  const first = await iterator.next();
+  return first.value;
+} finally {
+  await iterator.return?.();
+}
+```
+
+## Context in resource methods
+
+Resource methods may receive request context from Harper's REST runtime. Treat
+that context as the authoritative place for user identity, request headers, and
+request-scoped metadata supplied by the server:
+
+```javascript
+export class Orders extends tables.Orders {
+  static async post(data, context) {
+    const userId = context.user?.id;
+    if (!userId) {
+      throw new Error('Authentication required');
+    }
+
+    return super.post(
+      {
+        ...(await data),
+        createdBy: userId,
+      },
+      context,
+    );
+  }
+}
+```
+
+When one resource delegates to another, pass the same `context` through. This
+keeps authorization, headers/request metadata, and transaction ownership aligned
+for nested operations:
+
+```javascript
+await tables.OrderEvents.post(
+  {
+    orderId,
+    type: 'created',
+  },
+  context,
+);
+```
+
+Do not store `context` in module-level variables. It is request-scoped data and
+must not leak between concurrent requests.
+
+## Transactions
+
+Harper databases are transactionally consistent. Tables in the same database can
+participate in the same atomic unit of work; separate databases do not preserve
+cross-database atomicity.
+
+Resource methods should assume a request-level transaction boundary:
+
+- Reads inside a single request observe a consistent transaction context.
+- Writes across tables in the same database commit together when the request
+  completes successfully.
+- Throwing from the resource method before completion rolls the request work back.
+- Nested table/resource operations should receive the same `context` to stay in
+  the same request transaction.
+- Long-running external calls should happen before writes or after commit-aware
+  handoff; do not hold a transaction open while waiting on an avoidable network
+  dependency.
+
+Example multi-table write:
+
+```javascript
+export class Orders extends tables.Orders {
+  static async post(data, context) {
+    const order = await super.post(await data, context);
+
+    await tables.OrderEvents.post(
+      {
+        orderId: order.id,
+        type: 'created',
+      },
+      context,
+    );
+
+    return order;
+  }
+}
+```
+
+If `OrderEvents.post()` throws, the order creation should not be reported as
+successful. Verify the rollback behavior with an integration test against a real
+Harper process when the route writes more than one table.
+
+## Verification recipes
+
+Filtered, sorted, paginated REST query:
+
+```bash
+curl -fsS "$BASE_URL/products/?category=software&price=gt=100&sort(-rating)&limit(10)" \
+  | jq -e '
+      length <= 10 and
+      all(.[]; .category == "software" and .price > 100)
+    '
+```
+
+Projection:
+
+```bash
+curl -fsS "$BASE_URL/products/?category=software&select(id,name)" \
+  | jq -e 'all(.[]; has("id") and has("name") and (has("cost") | not))'
+```
+
+Relationship traversal:
+
+```bash
+curl -fsS "$BASE_URL/products/?brand.name=Microsoft&select(id,name,brand{name})" \
+  | jq -e 'all(.[]; .brand.name == "Microsoft")'
+```
+
+Pagination stability:
+
+```bash
+first="$(curl -fsS "$BASE_URL/products/?sort(+createdAt)&limit(0,20)")"
+second="$(curl -fsS "$BASE_URL/products/?sort(+createdAt)&limit(20,40)")"
+jq -e --argjson a "$first" --argjson b "$second" -n '
+  (($a | map(.id)) as $left |
+   ($b | map(.id)) as $right |
+   (($left + $right) | unique | length) == (($left | length) + ($right | length)))
+'
+```
+
+Multi-table rollback:
+
+```bash
+order_id="rollback-$(date +%s)"
+
+curl -sS -o /tmp/order-response.json -w "%{http_code}" \
+  -X POST "$BASE_URL/orders/" \
+  -H 'content-type: application/json' \
+  --data "{\"id\":\"$order_id\",\"forceEventFailure\":true}" \
+  | grep -E '4[0-9][0-9]|5[0-9][0-9]'
+
+curl -fsS "$BASE_URL/orders/$order_id" \
+  | jq -e '.error or .message or (.id != "'$order_id'")'
+```
+
+For routes with auth rules, add a negative assertion that a user without the
+required role cannot filter, select, or sort on restricted data.
+
+## Sources
+
+- [REST overview](https://docs.harperdb.io/reference/v5/rest/overview)
+- [REST querying](https://docs.harperdb.io/reference/v5/rest/querying)
+- [Resources overview](https://docs.harperdb.io/reference/v5/resources/overview)
+- [Query optimization](https://docs.harperdb.io/reference/v5/resources/query-optimization)
+- [Database overview](https://docs.harperdb.io/reference/v5/database/overview)

package/plugins/src/harper-fabric/skills/harper-testing/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: harper-testing
+description: This skill should be used when adding, repairing, or designing tests for a Harper (HarperDB/Fabric) component app — Vitest unit tests for pure functions and Resource methods, local Harper integration tests that boot/symlink/seed/assert real endpoints, Playwright e2e tests against REST/GraphQL routes, and schema/verify-script coupling. Use it when a Harper app needs its first test suite, endpoint coverage, seed isolation, or a local smoke/verify path. Pairs with harper-build-and-deploy, harper-schema-graphql, and e2e-coverage-gaps.
+---
+
+# Harper Testing
+
+## Overview
+
+Test Harper apps at the layer that proves the risk:
+
+1. **Pure unit tests** for TypeScript helpers and data transforms.
+2. **Resource unit tests** for `Resource` methods with mocked Harper runtime globals.
+3. **Integration tests** against a running local Harper component with real schema,
+   resources, seed data, and REST/GraphQL responses.
+4. **Playwright e2e tests** against the same HTTP surface a user or client calls.
+
+Harper application source lives in TypeScript under `src/`; deployable
+`harper-app/resources.js`, `harper-app/resource-*.js`, and `harper-app/web/**` are
+generated. Build before integration or e2e tests so the runtime loads the code you
+just changed. See [[harper-build-and-deploy]].
+
+## Test pyramid
+
+| Layer | Tool | Use when | Avoid |
+| --- | --- | --- | --- |
+| Pure unit | Vitest | Validating transforms, validators, serializers, query builders, and other code with no Harper runtime dependency. | Mocking HTTP or tables for logic that can stay pure. |
+| Resource unit | Vitest | Exercising `get`, `post`, `search`, `patch`, or permission/error logic in a resource class without booting Harper. | Treating mocked tables as proof that `config.yaml`, `schema.graphql`, or REST exposure works. |
+| Integration | Vitest or shell smoke | Proving Harper boots, schema loads, `jsResource` registers code, data seeds, and endpoints respond. | Replacing this with resource mocks after config, schema, or generated artifact changes. |
+| E2E | Playwright | Verifying client-observable REST/GraphQL behavior, auth states, error paths, and browser workflows. | Re-testing every pure branch through the browser. |
+
+Use [[e2e-coverage-gaps]] after a suite exists to find missing routes and
+non-happy paths. Use this skill when creating or repairing the test patterns
+themselves.
+
+## Pure unit tests
+
+Keep business transforms importable without Harper globals:
+
+```typescript
+import { describe, expect, it } from 'vitest';
+import { normalizePetName } from '../src/pets/normalize';
+
+describe('normalizePetName', () => {
+  it('trims and title-cases names', () => {
+    expect(normalizePetName('  ada LOVELACE ')).toBe('Ada Lovelace');
+  });
+});
+```
+
+If a resource method contains complex transformation logic, extract the pure part
+and test it directly. Leave a thinner resource test for runtime wiring,
+authorization, and persistence behavior.
+
+## Resource unit tests
+
+Harper injects runtime globals such as `Resource` and `tables` when it loads
+`resources.js`. Unit tests do not get those globals automatically. Test resource
+methods by importing code through a seam that accepts mocks, or by setting the
+minimal globals before importing the resource module.
+
+Prefer dependency injection for new code:
+
+```typescript
+import { describe, expect, it, vi } from 'vitest';
+import { createPetsResource } from '../src/resources/pets';
+
+describe('PetsResource.get', () => {
+  it('adds adoption status from the table record', async () => {
+    const table = {
+      get: vi.fn(async () => ({ id: 'pet-1', name: 'Mina', adoptedAt: null })),
+    };
+    const Pets = createPetsResource({ Resource: class {}, table });
+
+    await expect(Pets.get({ id: 'pet-1' })).resolves.toMatchObject({
+      id: 'pet-1',
+      name: 'Mina',
+      adoptionStatus: 'available',
+    });
+    expect(table.get).toHaveBeenCalledWith({ id: 'pet-1' });
+  });
+});
+```
+
+When existing code must extend `tables.X` directly, isolate the runtime globals in
+a test helper and import the module after setup:
+
+```typescript
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+describe('Pets resource', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.stubGlobal('Resource', class {});
+    vi.stubGlobal('tables', {
+      Pets: class {
+        static async get(target: { id: string }) {
+          return { id: target.id, name: 'Mina' };
+        }
+      },
+    });
+  });
+
+  it('wraps the runtime table', async () => {
+    const { Pets } = await import('../src/resources/pets');
+    await expect(Pets.get({ id: 'pet-1' })).resolves.toMatchObject({
+      id: 'pet-1',
+      name: 'Mina',
+    });
+  });
+});
+```
+
+Keep mocks narrow. Mock only the table methods, `Resource` base behavior,
+`server.resources`, or external fetch calls the method actually uses. If the test
+starts recreating Harper's schema, REST routing, or auth behavior, move it to an
+integration test.
+
+## Integration tests with local Harper
+
+Use integration tests to prove the component runs as Harper will load it:
+
+1. Install dependencies and build TypeScript: `bun install --frozen-lockfile`
+   when needed, then `bun run build`.
+2. Start a local Harper process against the component, usually
+   `harper dev harper-app` for watch mode or `harper run harper-app` for a
+   one-shot test process. Use the project's wrapper command when present.
+3. If the test lives outside the app repo, symlink the built component into
+   Harper's component directory rather than copying generated artifacts by hand.
+   Clean the symlink in teardown.
+4. Seed data through `dataLoader` fixtures when the project owns static fixtures,
+   or through REST/Operations API calls when each test needs dynamic setup.
+5. Assert the real REST/GraphQL endpoint and response body.
+6. Stop Harper and remove test data, temp components, and symlinks.
+
+Shell smoke tests are acceptable when the project already has that convention.
+Keep them strict: exit non-zero on boot failure, seed failure, missing endpoint,
+wrong status, or wrong response shape.
+
+Example integration skeleton:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+bun run build
+
+HARPER_APP_DIR="${PWD}/harper-app"
+HARPER_HOME="${HARPER_HOME:-${PWD}/.harper-test}"
+BASE_URL="${BASE_URL:-http://127.0.0.1:9926}"
+
+mkdir -p "$HARPER_HOME/components"
+ln -sfn "$HARPER_APP_DIR" "$HARPER_HOME/components/pets"
+
+HARPER_HOME="$HARPER_HOME" harper run "$HARPER_APP_DIR" > /tmp/harper-test.log 2>&1 &
+HARPER_PID=$!
+trap 'kill "$HARPER_PID" 2>/dev/null || true; rm -f "$HARPER_HOME/components/pets"' EXIT
+
+for _ in {1..30}; do
+  curl -fsS "$BASE_URL/health" >/dev/null && break
+  sleep 1
+done
+
+curl -fsS -X POST "$BASE_URL/Pets" \
+  -H 'content-type: application/json' \
+  --data '{"id":"pet-it-1","name":"Mina"}' >/dev/null
+
+curl -fsS "$BASE_URL/Pets/pet-it-1" | jq -e '.name == "Mina"'
+```
+
+Adjust the health path, component name, port, and endpoint names to the project.
+Do not commit local `HARPER_HOME`, logs, generated component copies, or secrets.
+
+## Seeding and isolation
+
+Use deterministic test data that cannot collide with developer or CI data:
+
+- Prefix IDs with the test name and a run ID, for example
+  `pet-${process.env.GITHUB_RUN_ID ?? Date.now()}`.
+- Prefer per-test setup/teardown through REST or Operations API when tests mutate
+  records.
+- Prefer `dataLoader` fixtures for stable baseline data that every local boot
+  should have.
+- Make teardown idempotent; deleting a record that is already gone should not fail
+  the suite.
+- Keep seed fixtures aligned with [[harper-schema-graphql]]. A field or type rename
+  must update fixtures, resource tests, verify scripts, and Playwright assertions in
+  the same PR.
+
+`dataLoader` is good for fast, declarative baseline rows. REST seeding is better
+when the test must exercise validation, defaults, auth, or generated IDs exactly as
+clients see them.
+
+## Playwright endpoint tests
+
+Use Playwright for HTTP behavior that needs browser tooling, request contexts,
+storage state, tracing, or cross-browser/project coverage. A first endpoint spec
+should cover one happy path and one non-happy path:
+
+```typescript
+import { expect, test } from '@playwright/test';
+
+test.describe('Pets REST endpoint', () => {
+  test('creates and reads a pet', async ({ request }) => {
+    const id = `pet-pw-${Date.now()}`;
+
+    const create = await request.post('/Pets', {
+      data: { id, name: 'Mina' },
+    });
+    expect(create.ok()).toBe(true);
+
+    const read = await request.get(`/Pets/${id}`);
+    expect(read.status()).toBe(200);
+    await expect(read).toHaveJSON(expect.objectContaining({ id, name: 'Mina' }));
+  });
+
+  test('rejects invalid payloads', async ({ request }) => {
+    const response = await request.post('/Pets', {
+      data: { name: '' },
+    });
+
+    expect(response.status()).toBeGreaterThanOrEqual(400);
+    await expect(response).toHaveJSON(
+      expect.objectContaining({
+        error: expect.any(String),
+      }),
+    );
+  });
+});
+```
+
+If the project uses custom auth, set `storageState`, headers, or a request fixture
+in Playwright config instead of embedding credentials in specs. Never commit
+tokens or local `.env` values.
+
+## Schema and verify coupling
+
+A schema rename or resource route change is a breaking change for every verify
+path that names that table, field, endpoint, fixture, or response shape.
+
+In the same PR as a schema/resource change:
+
+- Update `schema.graphql`, TypeScript resources, fixtures, and data loaders.
+- Update Vitest resource tests and Playwright endpoint specs.
+- Update shell smoke or `scripts/verify*` paths that assert row counts, joins, or
+  response keys.
+- Run `bun run build`, `bun run typecheck`, and the smallest relevant test command.
+- For deploy-affecting changes, boot local Harper or run the project smoke command
+  against the deployed endpoint. See [[harper-build-and-deploy]].
+
+Do not report a Harper test change done only because mocks pass. At least one
+verify path must prove the generated app still boots and exposes the expected
+surface whenever config, schema, resources, generated artifacts, or endpoints are
+part of the change.