@codyswann/lisa 2.195.3 → 2.195.6

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

@@ -0,0 +1,239 @@
+---
+name: harper-operations
+description: "operating, monitoring, or…"
+---
+
+# 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)

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

@@ -0,0 +1,4 @@
+display_name: "Harper Operations"
+short_description: "operating, monitoring, or…"
+default_prompt:
+  - "Use $harper-operations: operating, monitoring, or…."

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

@@ -0,0 +1,187 @@
+---
+name: harper-realtime
+description: "adding or troubleshooting…"
+---
+
+# Harper Realtime
+
+## Overview
+
+Harper exposes live data through the same Resource model used for REST and
+GraphQL. Exported tables/resources can be addressed as MQTT topics and WebSocket
+paths, while custom resources can override the messaging handlers when the default
+table behavior is not enough.
+
+Use real-time primitives when the product needs pushed state: live feeds, activity
+streams, collaborative views, device telemetry, or status updates. Do not replace
+these with client polling unless the issue explicitly asks for polling.
+
+## Resource and topic model
+
+- A GraphQL type marked `@table @export` creates a default exported table resource.
+- An exported JavaScript Resource class from `resources.js` creates a resource
+  endpoint with the class name as the path/topic root.
+- Resource paths map naturally to subscription targets: collection-level
+  subscriptions use the resource name, and record-level subscriptions append the
+  record id or path segment.
+- MQTT supports multi-level topics and wildcards. Use `resource/#` for a resource
+  subtree and `resource/+/status` for one path segment.
+- WebSocket subscriptions target the REST resource URL. For example,
+  `ws://localhost:9926/Activity/123` subscribes to the `Activity` resource record
+  with id `123`.
+
+Keep the URL/topic names stable. If a UI depends on `Activity/123`, changing the
+resource export name is an API break.
+
+## Resource methods
+
+The MQTT plugin routes broker messages through Resource methods:
+
+| Method | Use |
+| --- | --- |
+| `subscribe(target, context)` | Authorize and shape subscription reads for a resource or record. |
+| `publish(target, message, context)` | Accept or transform messages written to a topic/resource. |
+| `connect(incomingMessages)` | Customize WebSocket connection behavior for a resource. |
+
+For table-backed resources, prefer default behavior until the product needs a
+custom message shape, authorization check, fan-out, or derived event. When
+overriding, preserve built-in table behavior with `super.subscribe(...)` or
+`super.publish(...)` where that behavior is still wanted.
+
+```javascript
+export class Activity extends tables.Activity {
+  static async publish(target, message, context) {
+    const payload = await message;
+    await super.publish(target, payload, context);
+    return { ...payload, acceptedAt: Date.now() };
+  }
+}
+```
+
+For WebSocket-only behavior, implement `connect(incomingMessages)` and return an
+async iterable. Use the default `super.connect()` stream when you only need to
+push extra server messages or clean up on disconnect.
+
+## Transport choices
+
+| Transport | Best fit | Notes |
+| --- | --- | --- |
+| MQTT | Device streams, backend subscribers, wildcard topics, durable clients. | Plain MQTT defaults to port `1883`; MQTTS defaults to `8883`. |
+| MQTT over WebSocket | Browser or edge clients using MQTT semantics. | Uses the HTTP port, default `9926`, with the `mqtt` WebSocket subprotocol. |
+| Resource WebSocket | Browser live views tied to one REST resource path. | Enabled with the `rest` plugin unless `rest.webSocket: false` is set. |
+| SSE/custom streaming route | One-way browser updates when WebSocket is not appropriate. | Implement as a project route; do not assume SSE automatically subscribes to Resource changes. |
+
+Authentication is usually required for MQTT. When `mqtt.requireAuthentication` is
+`false`, authorization still applies at the resource/table level, so public
+connections must be explicitly allowed by roles or resource logic.
+
+## config.yaml wiring
+
+Component-level `config.yaml` enables the app surface:
+
+```yaml
+rest: true
+graphqlSchema:
+  files: schema.graphql
+jsResource:
+  files: resources.js
+```
+
+The root Harper `harper-config.yaml`, not the component `config.yaml`, owns broker
+ports and MQTT authentication:
+
+```yaml
+mqtt:
+  network:
+    port: 1883
+    securePort: 8883
+  webSocket: true
+  requireAuthentication: true
+```
+
+Keep the `rest`, `graphqlSchema`, and `jsResource` declarations together when a
+project has a custom component `config.yaml`. Harper does not merge custom
+component config with defaults. See [[harper-config-yaml]].
+
+## Filtering and message shape
+
+- Prefer record-level subscriptions (`Resource/<id>`) when the UI watches one
+  entity; use collection or wildcard subscriptions only when the product needs a
+  feed.
+- Keep published messages typed and small. Send the changed record or a compact
+  event envelope, not a full page payload.
+- Include stable identifiers in custom events: resource name, id, operation, and
+  timestamp are usually enough.
+- Treat inaccessible or unauthenticated subscribe attempts as authorization
+  failures, not empty streams.
+- Do not disable the audit log for tables that need real-time messages or
+  replication; Harper uses it for live subscriptions.
+
+## Fabric and replication
+
+For clustered/Fabric deployments, real-time behavior must match the deploy target:
+
+- Verify against the same environment that users connect to, not only a local
+  single-node process.
+- Use `replicated=true` when deploying a component that needs to run across Fabric
+  nodes. See [[harper-build-and-deploy]].
+- Keep event handlers idempotent. A subscriber may reconnect and replay from the
+  latest known state.
+- If a bug appears only across nodes, capture the target URL, topic/path, node
+  count when known, and the exact publish/subscribe commands in the evidence.
+
+## Local verification
+
+1. Build generated Harper assets from source:
+
+   ```bash
+   bun run build
+   ```
+
+2. Start the component:
+
+   ```bash
+   harper dev harper-app
+   ```
+
+3. In another shell, subscribe to a topic or WebSocket path:
+
+   ```bash
+   npx mqtt sub -h localhost -p 1883 -u HDB_ADMIN -P "$HARPER_PASSWORD" -t 'Activity/#' -v
+   ```
+
+   ```bash
+   npx wscat -c ws://localhost:9926/Activity/123
+   ```
+
+4. Publish or mutate the watched record:
+
+   ```bash
+   npx mqtt pub -h localhost -p 1883 -u HDB_ADMIN -P "$HARPER_PASSWORD" -t 'Activity/123' -m '{"status":"live"}'
+   ```
+
+5. Confirm the subscriber receives the expected message shape and that a normal
+   REST/GraphQL read returns the same resulting state.
+
+Record the command, topic/path, payload, and observed message in PR evidence. If a
+local Harper binary or credentials are unavailable, report that blocker instead of
+claiming the subscription was verified.
+
+## Project conventions
+
+- Write resource code in TypeScript under `src/`; `harper-app/resources.js` is a
+  generated artifact. See [[harper-resources]].
+- If real-time work changes `config.yaml`, update the project Fabric runbook and
+  re-run the smoke path. See [[harper-config-yaml]].
+- Prefer a pushed update over a polling workaround when the issue asks for live
+  behavior.
+- For Lisa plugin edits, change `plugins/src/harper-fabric`, run
+  `bun run build:plugins`, and commit both source and generated plugin copies.
+
+## Sources
+
+- [Resources overview](https://docs.harperdb.io/reference/v5/resources/overview)
+- [Resource API](https://docs.harperdb.io/reference/v5/resources/resource-api)
+- [WebSockets](https://docs.harperdb.io/reference/v5/rest/websockets)
+- [MQTT configuration](https://docs.harperdb.io/reference/v4/mqtt/configuration)
+- [Transaction logging](https://docs.harperdb.io/reference/v5/database/transaction)

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

@@ -0,0 +1,4 @@
+display_name: "Harper Realtime"
+short_description: "adding or troubleshooting…"
+default_prompt:
+  - "Use $harper-realtime: adding or troubleshooting…."

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

@@ -0,0 +1,142 @@
+---
+name: harper-resources
+description: "writing or editing Harper…"
+---
+
+# Harper Resources
+
+## Overview
+
+A **Resource** is a class that provides a unified interface for a set of records or
+entities. Resources are how you add custom server-side behavior to a Harper app.
+They are loaded by the `jsResource` extension (default file `resources.js`) and,
+when **exported**, become live REST and GraphQL endpoints.
+
+A resource either **extends a database table** (to customize an existing table's
+behavior) or **extends the base `Resource` class** (to expose data from anywhere —
+an external API, a computed view, an in-memory source).
+
+## Method → HTTP verb mapping
+
+The Resource API mirrors REST. Override the method matching the operation you want
+to customize:
+
+| Method | HTTP | Use |
+| --- | --- | --- |
+| `get(target)` | GET | Retrieve a record/collection |
+| `post(data)` | POST | Create |
+| `put(target, data)` | PUT | Replace |
+| `patch(target, data)` | PATCH | Partial update |
+| `delete(target)` | DELETE | Remove |
+| `search(query)` | GET (query) | Query with conditions |
+| `subscribe` / `publish` | MQTT/WebSocket | Real-time |
+
+## Extending a table
+
+Add computed fields or guard logic while keeping the table's built-in behavior via
+`super`:
+
+```javascript
+export class MyTable extends tables.MyTable {
+  static async get(target) {
+    const record = await super.get(target);
+    return { ...record, computedField: 'value' };
+  }
+}
+```
+
+## Wrapping an external source
+
+```javascript
+export class MyExternalData extends Resource {
+  static async get(target) {
+    const response = await fetch(`https://api.example.com/${target.id}`);
+    return response.json();
+  }
+}
+```
+
+## Making a resource an endpoint
+
+A resource becomes an endpoint when it is **exported** and `rest: true` (and/or
+`graphqlSchema`) is enabled in `config.yaml`:
+
+```yaml
+rest: true
+graphqlSchema:
+  files: schema.graphql
+jsResource:
+  files: resources.js
+```
+
+Resources can also be registered programmatically with `server.resources.set()`.
+See [[harper-config-yaml]] for the extension wiring, [[harper-schema-graphql]] for
+how the schema defines the tables resources extend, and [[harper-realtime]] when
+`subscribe`, `publish`, or WebSocket behavior is part of the feature.
+
+## Throwing HTTP status errors
+
+Harper's thrown-error response writer reads **`error.statusCode`** (falling back
+to `500`). A plain `error.status` is **ignored** — throw an error with only
+`status` set and every intended `4xx` is served as a `500`. Verified on
+harperdb 4.7.32.
+
+Always set `statusCode` (keep `status` too only if callers or tests read it):
+
+```javascript
+static async post(target, data, context) {
+  if (!context.user) {
+    const error = new Error('Authentication required');
+    error.statusCode = 401; // NOT `error.status` — Harper reads statusCode
+    throw error;
+  }
+  // ...
+}
+```
+
+A shared helper keeps every throw site correct:
+
+```javascript
+function throwStatus(message, status) {
+  // Set both: `statusCode` is what Harper serves; `status` is kept for
+  // returned-response symmetry and any caller/test that reads it.
+  throw Object.assign(new Error(message), { status, statusCode: status });
+}
+```
+
+The `harper-require-statuscode-on-thrown-error` ast-grep rule flags errors that
+carry `status` without `statusCode`. Pass `context` through to `super` and nested
+table calls so authorization and the request transaction stay aligned — see
+[[harper-rest-queries]] for context propagation and iterator draining.
+
+## Project conventions (TS is source)
+
+- **Write resources in TypeScript under `src/`. `harper-app/resources.js` is a
+  generated artifact** produced by `bun run build`. Never edit `resources.js` by
+  hand — change the TypeScript and rebuild. See [[harper-build-and-deploy]].
+- Operational scripts that touch resources (seed, smoke, verify, ingest, crawl,
+  extraction) must run from compiled JavaScript or generated Harper assets, not
+  stale checked-in JS.
+- Prefer immutable data flow: `readonly` types, pure transformations, copies, and
+  explicit returns. Do not mutate parameters, records, arrays, or config objects
+  unless an API forces it, and document the exception locally.
+- Avoid `any`, broad casts, and `ts-ignore`. If an external API forces an escape
+  hatch, isolate it behind a typed adapter.
+
+## Build the real thing
+
+If an endpoint needs a schema change, a seed path, or a deploy script change, make
+that change — do not ship a client-side workaround or silently downgrade to a stub
+or mock. A change is unfinished until the local build and the relevant deployed or
+smoke path agree.
+
+## Verification
+
+Run `bun run build`, `bun run typecheck`, and the smallest relevant test. For an
+endpoint change, also hit the actual REST/GraphQL route against a local or deployed
+Harper instance (the project smoke command) and confirm the response shape.
+
+## Sources
+
+- [Resources overview](https://docs.harperdb.io/reference/v5/resources/overview)
+- [Applications](https://docs.harperdb.io/docs/developers/applications)

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

@@ -0,0 +1,4 @@
+display_name: "Harper Resources"
+short_description: "writing or editing Harper…"
+default_prompt:
+  - "Use $harper-resources: writing or editing Harper…."