@codyswann/lisa 2.195.4 → 2.195.7

package/plugins/lisa-harper-fabric/.codex-plugin/skills/harper-rest-queries/SKILL.md

@@ -0,0 +1,403 @@
+---
+name: harper-rest-queries
+description: "building or debugging Harper…"
+---
+
+# 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,
+});
+```
+
+## Sort with no conditions crashes the planner
+
+A `search()` that carries a `sort` but an **empty `conditions: []`** array throws
+at runtime — the planner cannot seed the btree scan from the sort attribute. This
+is a latent `500` the first time an unfiltered, sorted collection page is
+requested (verified on harperdb 4.7.32).
+
+```javascript
+// ✗ crashes: sort with nothing to seed the scan
+tables.Advisor.search({
+  conditions: [],
+  sort: { attribute: 'lastName' },
+});
+```
+
+Seed a floor/sentinel condition on the sort attribute so the planner has an index
+range to walk, then apply the sort:
+
+```javascript
+// ✓ floor condition on the sort attribute seeds the scan
+tables.Advisor.search({
+  conditions: [
+    { attribute: 'lastName', comparator: 'greater_than_equal', value: '' },
+  ],
+  sort: { attribute: 'lastName' },
+});
+```
+
+Centralize this in the page helper (`searchPageAndCount`) rather than duplicating
+a sentinel at each call site. The `harper-no-empty-conditions-with-sort` ast-grep
+rule flags the crashing shape.
+
+## 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`. An early `return`/`break` out of a
+`for await (... of tables.X.search(...))` loop abandons the iterator before the
+scan completes and **leaks the open read transaction** (verified on
+harperdb 4.7.32). When iterating manually or stopping early, drain it or call the
+iterator's `return()` in `finally` so Harper releases the read transaction — or
+bound the query (`search({ ..., limit: 1 })`) when you only need the first row.
+The `harper-no-early-return-in-search-loop` ast-grep rule flags early exits from
+these loops:
+
+```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/lisa-harper-fabric/.codex-plugin/skills/harper-rest-queries/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Harper Rest Queries"
+short_description: "building or debugging Harper…"
+default_prompt:
+  - "Use $harper-rest-queries: building or debugging Harper…."

package/plugins/lisa-harper-fabric/.codex-plugin/skills/harper-schema-graphql/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: harper-schema-graphql
+description: "editing a Harper (HarperDB/Fabri…"
+---
+
+# Harper schema.graphql
+
+## Overview
+
+Harper defines its database tables and types from **GraphQL schema files**, loaded
+by the `graphqlSchema` extension (default `*.graphql`; this project uses
+`harper-app/schema.graphql`). The schema is the source of truth for the data model:
+the tables it declares are what resources extend ([[harper-resources]]) and what
+the REST/GraphQL surface exposes.
+
+## Defining tables
+
+A table is a GraphQL type. Harper-specific directives mark a type as a persisted
+table and control exposure, primary keys, indexes, audit timestamps, sealed
+records, and relationships. Lisa's Harper Fabric template pins `harperdb` to the
+Harper 4 line (`^4.7.29`), so use this v4 directive reference for template
+projects:
+
+```graphql
+type Dog @table @export(name: "dogs") {
+  id: Long @primaryKey
+  name: String @indexed
+  breed: String
+  ownerId: Long @indexed
+  owner: Owner @relationship(from: ownerId)
+  createdAt: Long @createdTime
+  updatedAt: Long @updatedTime
+}
+```
+
+| Directive | Scope | Syntax | Use |
+| --- | --- | --- | --- |
+| `@table` | Type | `type Product @table { ... }` | Creates a persisted table named after the type. Optional arguments: `table: "products"` to override the table name, `database: "commerce"` to choose a database, `expiration: 3600` for TTL-style records, and `audit: true` to force audit logging. |
+| `@export` | Type | `type Product @table @export(name: "products") { ... }` | Exposes the table as a resource endpoint for REST/MQTT and related surfaces. `name` is optional; without it the type name is the path segment. |
+| `@sealed` | Type | `type Product @table @sealed { ... }` | Rejects undeclared properties. Omit it when the table intentionally accepts extra record fields. |
+| `@primaryKey` | Field | `id: Long @primaryKey` | Marks the unique table key. If omitted on insert, Harper v4 can auto-generate a UUID for `String`/`ID` keys or an auto-incrementing integer for `Int`/`Long`/`Any` keys. Prefer `Long` or `Any` for generated numeric keys. |
+| `@indexed` | Field | `sku: String @indexed` | Adds a secondary index used by REST filters, SQL, and NoSQL/search paths. Array fields index each element. For vectors in Harper v4.6+, use `embedding: [Float] @indexed(type: "HNSW")`. |
+| `@createdTime` | Field | `createdAt: Long @createdTime` | Writes Unix epoch milliseconds when the record is created. |
+| `@updatedTime` | Field | `updatedAt: Long @updatedTime` | Writes Unix epoch milliseconds whenever the record is updated. |
+| `@relationship(from: field)` | Field | `owner: Owner @relationship(from: ownerId)` | The foreign key is on this table and references the target table primary key. If the foreign key field is an array, the relationship is many-to-many. |
+| `@relationship(to: field)` | Field | `dogs: [Dog] @relationship(to: ownerId)` | The foreign key is on the target table. The relationship field must be an array. |
+| `@relationship(from: field, to: field)` | Field | `product: Product @relationship(from: productSku, to: sku)` | Joins this table's field to a non-primary-key field on the target table. Index both join fields. |
+
+Use v5 docs only when the downstream project has intentionally moved off the Lisa
+template's Harper 4 dependency; do not mix v5-only syntax into a `harperdb`
+`^4.7.29` project.
+
+## How the schema drives the app
+
+- The `graphqlSchema` extension creates/migrates tables from the schema on load.
+- `rest: true` exposes exported tables/resources as REST endpoints; the GraphQL
+  surface is generated from the same schema.
+- Resources that `extends tables.X` depend on `X` existing in the schema. A rename
+  or removal in the schema is a breaking change for every resource and verify path
+  that references it.
+
+## Schema evolution
+
+Schema changes are deploy-time data-model changes, not just type edits. Harper's
+`graphqlSchema` extension ensures declared tables and attributes exist when the
+component loads, but it does not perform semantic data migrations such as
+renaming tables, copying field values, or rewriting existing rows for you.
+
+Classify each change before editing:
+
+| Change | Compatibility | What Harper does | Required agent work |
+| --- | --- | --- | --- |
+| Add optional field | Usually safe | Adds the declared attribute shape; existing rows read as missing/`null` until written. | Update resources, seeds, and verification that should include the field. |
+| Add required/non-null field | Breaking for existing rows and writers | The schema can declare the field, but existing records do not magically gain valid values. | Backfill first or deploy as optional, populate, then tighten in a later deploy. |
+| Add `@indexed` | Usually safe, operationally sensitive | Creates/uses a secondary index for the attribute. Large tables may pay rebuild cost. | Verify filtered REST/search paths and note index build risk in the deploy runbook. |
+| Add `@sealed` | Breaking when rows or writers use extra properties | Future writes with undeclared properties are rejected. | Audit current data/writers, declare needed fields, or migrate callers before sealing. |
+| Rename field | Breaking | Treated as a new field; the old field and its values are not transformed. | Add the new field, copy values with a migration, update code, verify, then remove old usage. |
+| Rename type/table | Breaking | Harper v4 does not rename tables; changing the type name creates a new empty table and leaves the old table/data untouched. | Create the new table, copy data, update resources/routes, verify both read/write paths, then retire the old table intentionally. |
+| Change field type | Breaking | Existing stored values are not coerced into the new type in a controlled migration. | Add a replacement field/table, transform data with code, verify, then remove old usage. |
+| Remove field/type | Breaking | Schema no longer declares it, but dependent resources, routes, queries, seeds, and clients can still reference it. | Delete references first, run a migration/cleanup if needed, and verify old API paths fail or redirect intentionally. |
+
+Migration recipe for production data:
+
+1. Add the new schema shape in a backward-compatible way: new table or nullable
+   replacement field, keeping the old field/table available.
+2. Write a one-shot migration using a Harper resource method or Operations
+   API/script that reads old rows, transforms values, and writes the new shape.
+   Make it idempotent; reruns should skip rows already migrated or compare a
+   migration marker.
+3. Deploy to one Fabric environment and run the migration before switching
+   readers/writers. For replicated Fabric deployments, assume every node may see
+   the new code/schema at slightly different times; keep old and new reads
+   compatible until replication and smoke checks are green.
+4. Update resources, REST/GraphQL queries, data-loader seeds, and verify scripts
+   in the same PR. A schema PR is incomplete if `bun run verify` or the project
+   smoke path cannot prove the migrated read/write behavior.
+5. Roll back by reverting code/schema only when the old field/table remains
+   intact. Once cleanup drops old data or callers, rollback needs a reverse
+   migration and a restored compatibility path.
+
+## Project conventions
+
+- `schema.graphql` is **source** and lives at the component root that Fabric
+  packages (`harper-app/schema.graphql`). Keep it there.
+- A schema change is a data-model change. In the **same change**:
+  - Update the conceptual schema docs.
+  - Update any verify/smoke paths that assert joins, relationships, or row counts —
+    those assertions encode the data model and must track it.
+  - Update resources and seed/data-loader paths that reference changed tables.
+- Document deploy-affecting consequences (new tables, migrations) in the Fabric
+  runbook. See [[harper-build-and-deploy]].
+
+## Verification
+
+After a schema change, boot the app (`harper dev harper-app` or the project run
+command) and confirm tables migrate cleanly and the dependent endpoints respond.
+Run any verify path that asserts row counts or joins against the changed model.
+
+## Sources
+
+- [Harper v4 Schema](https://docs.harperdb.io/reference/v4/database/schema)
+- [Components overview](https://docs.harperdb.io/reference/v4/components/overview)
+- [Operations API](https://docs.harperdb.io/reference/v4/operations-api/operations)

package/plugins/lisa-harper-fabric/.codex-plugin/skills/harper-schema-graphql/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Harper Schema Graphql"
+short_description: "editing a Harper (HarperDB/Fabri…"
+default_prompt:
+  - "Use $harper-schema-graphql: editing a Harper (HarperDB/Fabri…."