@codyswann/lisa 2.167.0 → 2.169.0

package/plugins/lisa-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/lisa-harper-fabric/skills/harper-rest-queries/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Harper Rest Queries"
+short_description: "building or debugging Harper (HarperDB/Fabric) REST collection queries and Resource search methods - filters, FIQL comparison operators…"
+default_prompt:
+  - "Use $harper-rest-queries: building or debugging Harper (HarperDB/Fabric) REST collection queries and Resource search methods - filters, FIQL comparison operators…."

package/plugins/lisa-harper-fabric-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.167.0",
+  "version": "2.169.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-agy/skills/harper-operations/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: harper-operations
+description: This skill should be used when operating, monitoring, or debugging a Harper (HarperDB/Fabric) component after it builds or deploys - Operations API calls, component inventory, log retrieval, health checks, job lookup, local 500 debugging, and escalation boundaries. Pairs with harper-build-and-deploy, harper-config-yaml, harper-resources, and harper-rest-queries.
+---
+
+# Harper Operations
+
+## Overview
+
+Use Harper's Operations API when the app built or deployed but runtime behavior is
+unknown: a REST endpoint returns 500, a component did not load, logs show worker
+errors, a table shape differs from the expected schema, or a deploy job needs to be
+checked. The Operations API is the administrative surface; application REST
+endpoints are the user-facing data/resource surface.
+
+Cross-check deploy packaging and Fabric topology in [[harper-build-and-deploy]].
+Cross-check active extensions and config replacement behavior in
+[[harper-config-yaml]]. Cross-check custom Resource method ownership in
+[[harper-resources]] and query shape in [[harper-rest-queries]].
+
+## Endpoint, auth, and request shape
+
+Operations API requests are JSON `POST` requests to the operations endpoint. Harper
+listens on port `9925` at the root path by default:
+
+```bash
+curl -sS http://<harper-host>:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"operation":"system_information"}'
+```
+
+For local development:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"operation":"get_components"}'
+```
+
+Authentication options:
+
+- Basic auth: `Authorization: Basic ...`, or `curl -u "$USER:$PASS"`.
+- JWT operation token: `Authorization: Bearer <token>` from
+  `create_authentication_tokens`.
+- CLI: `harper login <target>` for persistent remote auth, or environment
+  credentials such as `HARPER_CLI_USERNAME` / `HARPER_CLI_PASSWORD`.
+
+Most operational reads require a `super_user` or a role explicitly allowed to run
+the named operation. If an operation is denied, check role `operations` permissions
+before assuming the endpoint or component is broken.
+
+## High-value operations
+
+| Operation | Use it for | Example |
+| --- | --- | --- |
+| `get_components` | Confirm component names, files, and configuration loaded from `harper-config.yaml`. | `{"operation":"get_components"}` |
+| `describe_all` | See all database/table definitions and record counts visible to the caller. | `{"operation":"describe_all"}` |
+| `describe_table` | Confirm table/database names, attributes, and primary key shape. | `{"operation":"describe_table","database":"data","table":"Product"}` |
+| `system_information` | Capture runtime, host, and process information for health/debug reports. | `{"operation":"system_information"}` |
+| `read_log` | Read Harper's primary `hdb.log` with level/time/filter controls. | `{"operation":"read_log","level":"error","limit":50,"order":"desc"}` |
+| `search_jobs_by_start_date` | Find background jobs when deploys, imports, or long operations are involved. | `{"operation":"search_jobs_by_start_date","from_date":"2026-06-16T00:00:00.000+0000","to_date":"2026-06-17T00:00:00.000+0000"}` |
+| `get_job` | Inspect one known job id returned by a search or operation response. | `{"operation":"get_job","id":"<job-id>"}` |
+| `get_configuration` | Find runtime paths such as `rootPath`, `componentsRoot`, ports, and logging config. | `{"operation":"get_configuration"}` |
+
+Use CLI shortcuts when the operation only needs flat key/value arguments:
+
+```bash
+harper get_components target="$HARPER_TARGET" json=true
+harper describe_all target="$HARPER_TARGET" json=true
+harper read_log target="$HARPER_TARGET" level=error limit=50 order=desc json=true
+```
+
+If the CLI cannot represent the nested request body, use `curl` against the
+Operations API directly.
+
+## Reading logs
+
+`read_log` reads the primary Harper log (`hdb.log`) and is restricted to
+`super_user` roles unless a custom role grants it. Useful parameters include
+`level`, `from`, `until`, `limit`, `order`, and `filter`.
+
+Recent errors:
+
+```bash
+curl -sS "$HARPER_TARGET" \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "operation": "read_log",
+    "level": "error",
+    "limit": 50,
+    "order": "desc"
+  }'
+```
+
+Filter by component, route, or correlation id:
+
+```bash
+curl -sS "$HARPER_TARGET" \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "operation": "read_log",
+    "filter": "orders",
+    "from": "2026-06-16 00:00:00",
+    "limit": 100,
+    "order": "desc"
+  }'
+```
+
+In local `harper dev`, also watch the terminal output. The dev command restarts
+worker threads on file changes and prints console/log output close to the failing
+request. Use `harper run` or a deployed local instance when you need to restart the
+main thread, not only workers.
+
+## Logging from Resources
+
+For Resource methods, log enough to identify the request path, authenticated user
+or tenant id, and failing branch without emitting secrets or whole request bodies.
+Prefer structured, searchable messages:
+
+```javascript
+export class Orders extends tables.Orders {
+  static async post(data, context) {
+    const input = await data;
+    console.info('orders.post received', {
+      orderId: input.id,
+      userId: context.user?.id,
+    });
+
+    try {
+      return await super.post(input, context);
+    } catch (error) {
+      console.error('orders.post failed', {
+        orderId: input.id,
+        message: error?.message,
+      });
+      throw error;
+    }
+  }
+}
+```
+
+Guidance:
+
+- Use `console.info` or `console.debug` for normal trace points, and
+  `console.warn` / `console.error` for actionable failures.
+- Never log passwords, tokens, cookies, API keys, raw Authorization headers, or
+  full personal data payloads.
+- Include a request id or deterministic entity id when the caller can provide one.
+- Remove noisy temporary logs once the root cause is fixed, or lower them to debug.
+
+## Debugging a 500 endpoint
+
+When a deployed REST endpoint returns 500, follow this path before changing code:
+
+1. Identify the exact endpoint, method, payload, authenticated user, target URL,
+   and timestamp. Save a reproducible `curl` command with headers scrubbed.
+2. Confirm the component is installed and named as expected:
+
+   ```bash
+   harper get_components target="$HARPER_TARGET" json=true
+   ```
+
+3. Read recent errors around the failing timestamp:
+
+   ```bash
+   harper read_log target="$HARPER_TARGET" level=error limit=100 order=desc json=true
+   ```
+
+4. Check table/resource shape when the failure mentions a missing table, attribute,
+   index, relationship, or schema directive:
+
+   ```bash
+   curl -sS "$HARPER_TARGET" \
+     -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+     -H 'Content-Type: application/json' \
+     --data '{"operation":"describe_all"}'
+   ```
+
+5. Reproduce locally with the same built artifact path:
+
+   ```bash
+   bun run build
+   harper dev harper-app
+   curl -i http://localhost:9926/<project>/<resource-path>
+   ```
+
+6. Isolate the smallest Resource method or table call involved. If the route uses a
+   custom Resource, call its underlying table/search operation directly when safe,
+   then add one temporary log at the branch boundary that chooses the failing path.
+7. Fix source files, not generated deploy artifacts. Rebuild and repeat the same
+   local `curl`, then repeat the deployed smoke path after redeploy.
+
+Treat the incident as unresolved until the same request path returns the expected
+status and the logs no longer show the error.
+
+## Health and deploy checks
+
+After deploy or restart, check:
+
+- Component inventory: `get_components` includes the expected project and files.
+- System/runtime info: `system_information` returns from the target node.
+- Configuration: `get_configuration` shows the expected operations/API ports,
+  `rootPath`, `componentsRoot`, and logging configuration.
+- Schema/data shape: `describe_all` or `describe_table` matches the expected
+  database/table definitions and exported tables.
+- Logs: `read_log` has no new error entries for the deploy/restart window.
+- Jobs: `search_jobs_by_start_date` and `get_job` show background work completed
+  when deploy, import, backup, or long-running data operations were involved.
+- Public smoke: the project-specific HTTP smoke command passes from the same route
+  users will hit. For Fabric, verify through the public route and any direct
+  node/region route the project exposes.
+
+## What is not available
+
+Do not invent observability that the target does not expose:
+
+- If there is no Fabric credential or operations role, you cannot prove remote
+  component state; ask for credentials or a trusted operator readback.
+- If the app does not emit a request id, logs may not be attributable to one HTTP
+  request. Reproduce in a narrow time window or add a safe correlation id first.
+- If a Fabric project hides direct node/region URLs, verify through the public
+  route and record that node-level proof is unavailable.
+- If Harper returns an auth/permission denial for `read_log`,
+  `system_information`, or component operations, treat it as an access blocker,
+  not as evidence that logs or components are empty.
+- Third-party APM, trace collection, and performance tuning are outside this
+  skill. Capture Harper-native facts first, then escalate to the project's
+  runbook or platform owner.
+
+## Sources
+
+- [Operations API Overview](https://docs.harperdb.io/reference/v5/operations-api/overview)
+- [Operations Reference](https://docs.harperdb.io/reference/v5/operations-api/operations)
+- [Logging Operations](https://docs.harperdb.io/reference/v5/logging/operations)
+- [Applications / Component Operations](https://docs.harperdb.io/reference/v5/components/applications)