@codyswann/lisa 2.164.0 → 2.165.0

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

@@ -0,0 +1,187 @@
+---
+name: harper-realtime
+description: This skill should be used when adding or troubleshooting Harper (HarperDB/Fabric) real-time behavior: MQTT topics, WebSocket resource subscriptions, resource publish/subscribe handlers, SSE-style streaming routes, and local subscriber verification. Pairs with harper-resources, harper-config-yaml, harper-schema-graphql, and harper-build-and-deploy.
+---
+
+# 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/src/harper-fabric/skills/harper-resources/SKILL.md

@@ -70,8 +70,9 @@ jsResource:
 ```
 
 Resources can also be registered programmatically with `server.resources.set()`.
-See [[harper-config-yaml]] for the extension wiring and [[harper-schema-graphql]]
-for how the schema defines the tables resources extend.
+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.
 
 ## Project conventions (TS is source)
 

package/plugins/src/typescript/hooks/lint-on-edit.sh

@@ -4,17 +4,15 @@
 # =============================================================================
 # Lint-on-Edit Hook (PostToolUse - Write|Edit)
 # =============================================================================
-# Runs oxlint --fix, then ESLint --fix --quiet --cache on each edited
-# TypeScript file. Part of the inline self-correction pipeline:
-#   prettier → ast-grep → oxlint --fix → eslint --fix
+# Runs oxlint on each edited TypeScript file. Full ESLint remains enforced at
+# the commit/CI chokepoint via the project lint scripts.
 #
-# oxlint runs first because it's a Rust-native linter (~1000x faster) that
-# covers the majority of rules, leaving only the slow / type-aware / plugin
-# rules for ESLint to handle.
+# oxlint is Rust-native and covers the fast-feedback rule tier in milliseconds;
+# ESLint stays out of the edit-time path.
 #
 # Behavior:
-#   - Exit 0: lint passes or auto-fix resolved all errors
-#   - Exit 2: unfixable errors remain — blocks Claude so it fixes them immediately
+#   - Exit 0: lint passes
+#   - Exit 2: oxlint errors remain - blocks Claude so it fixes them immediately
 #
 # @see .claude/rules/verfication.md "Self-Correction Loop" section
 # =============================================================================
@@ -49,7 +47,7 @@ esac
 
 cd "$CLAUDE_PROJECT_DIR" || exit 0
 
-# Resolve oxlint and ESLint binaries — prefer local node_modules/.bin
+# Resolve oxlint binary - prefer local node_modules/.bin
 if [ -x "./node_modules/.bin/oxlint" ]; then
     OXLINT_CMD="./node_modules/.bin/oxlint"
 elif [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then
@@ -62,19 +60,7 @@ else
     OXLINT_CMD="npx oxlint"
 fi
 
-if [ -x "./node_modules/.bin/eslint" ]; then
-    ESLINT_CMD="./node_modules/.bin/eslint"
-elif [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then
-    ESLINT_CMD="bunx eslint"
-elif [ -f "pnpm-lock.yaml" ]; then
-    ESLINT_CMD="pnpm exec eslint"
-elif [ -f "yarn.lock" ]; then
-    ESLINT_CMD="yarn exec eslint"
-else
-    ESLINT_CMD="npx eslint"
-fi
-
-# 1) oxlint --fix (REQUIRED in the Phase 2 hybrid pipeline)
+# oxlint (REQUIRED in the Phase 2 hybrid pipeline)
 # If oxlint is missing the project is out of sync with the current Lisa
 # governance — fail loudly rather than silently skipping. ESLint alone is
 # no longer a complete lint pass.
@@ -89,46 +75,14 @@ if [ ! -f ".oxlintrc.json" ] && [ ! -f ".oxlintrc.jsonc" ] && [ ! -f "oxlint.con
     exit 2
 fi
 
-echo "Running oxlint --fix on: $FILE_PATH"
-OX_OUTPUT=$($OXLINT_CMD --fix --quiet "$FILE_PATH" 2>&1)
+echo "Running oxlint on: $FILE_PATH"
+OX_OUTPUT=$($OXLINT_CMD --quiet "$FILE_PATH" 2>&1)
 OX_EXIT=$?
 if [ $OX_EXIT -ne 0 ]; then
-    # Re-run without --fix to capture remaining errors
-    OX_OUTPUT=$($OXLINT_CMD --quiet "$FILE_PATH" 2>&1)
-    OX_EXIT=$?
-    if [ $OX_EXIT -ne 0 ]; then
-        echo "oxlint found unfixable errors in: $FILE_PATH" >&2
-        echo "$OX_OUTPUT" >&2
-        exit 2
-    fi
-fi
-
-# 2) ESLint --fix --quiet --cache
-# --quiet: suppress warnings, only show errors
-# --cache: use ESLint cache for performance
-# --rule: disable no-unused-vars auto-fix to prevent removing imports that Claude
-#         plans to use in a subsequent edit (pre-commit hook still catches them)
-echo "Running ESLint --fix on: $FILE_PATH"
-
-# First pass: attempt auto-fix
-OUTPUT=$($ESLINT_CMD --fix --quiet --cache --rule '@typescript-eslint/no-unused-vars: off' "$FILE_PATH" 2>&1)
-FIX_EXIT=$?
-
-if [ $FIX_EXIT -eq 0 ]; then
-    echo "ESLint: No errors in $(basename "$FILE_PATH")"
-    exit 0
-fi
-
-# Auto-fix resolved some issues but errors remain — re-run to get remaining errors
-OUTPUT=$($ESLINT_CMD --quiet --cache "$FILE_PATH" 2>&1)
-LINT_EXIT=$?
-
-if [ $LINT_EXIT -eq 0 ]; then
-    echo "ESLint: Auto-fixed all errors in $(basename "$FILE_PATH")"
-    exit 0
+    echo "oxlint found errors in: $FILE_PATH" >&2
+    echo "$OX_OUTPUT" >&2
+    exit 2
 fi
 
-# Unfixable errors remain — block with feedback
-echo "ESLint found unfixable errors in: $FILE_PATH" >&2
-echo "$OUTPUT" >&2
-exit 2
+echo "oxlint: No errors in $(basename "$FILE_PATH")"
+exit 0