@codyswann/lisa 2.166.3 → 2.166.4

package/package.json

@@ -85,7 +85,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.166.3",
+  "version": "2.166.4",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

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

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

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

package/plugins/lisa-harper-fabric/skills/harper-config-yaml/SKILL.md

@@ -66,6 +66,175 @@ For real-time work, component `config.yaml` keeps `rest`, `graphqlSchema`, and
 MQTT topic paths. Broker ports and MQTT authentication live in the root
 `harper-config.yaml`, not the component file. See [[harper-realtime]].
 
+## `dataLoader`: seed data
+
+Use `dataLoader` for versioned seed/reference records that should exist whenever
+the component is deployed. Define table shape first with `graphqlSchema`, then
+point `dataLoader.files` at one or more JSON/YAML files:
+
+```yaml
+graphqlSchema:
+  files: 'schema.graphql'
+dataLoader:
+  files:
+    - 'data/roles.yaml'
+    - 'data/reference/*.json'
+```
+
+Each data file targets exactly one table and has `database`, `table`, and
+`records` keys:
+
+```yaml
+database: app
+table: Role
+records:
+  - id: admin
+    name: Administrator
+    permissions:
+      - users:read
+      - users:write
+  - id: viewer
+    name: Viewer
+    permissions:
+      - users:read
+```
+
+Harper runs the loader on full system starts and component deployments. It is
+safe to re-run when files are idempotent: new records are inserted, unchanged
+records are skipped, and records are updated from the file only when the tracked
+file content changed. User-created records and user edits made after an initial
+load are preserved; changed data-loaded records are patched instead of blindly
+replaced.
+
+Choose `dataLoader` for small, source-controlled reference/configuration data
+that should ship with the component. Use a REST/Operations API script or job for
+large imports, environment-specific backfills, or one-off migrations where retry
+scope and operator approval matter.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -s http://localhost:9926/app/Role/admin
+harper dev harper-app # restart/redeploy and confirm the seed did not duplicate
+```
+
+## `fastifyRoutes`: custom HTTP routes
+
+Prefer `jsResource` plus `rest` for normal CRUD/action APIs. Use `fastifyRoutes`
+only when the route shape does not fit the Resource model: webhooks, custom
+serialization, unusual path matching, or a compatibility endpoint.
+
+```yaml
+rest: true
+graphqlSchema:
+  files: 'schema.graphql'
+jsResource:
+  files: 'resources.js'
+fastifyRoutes:
+  files: 'routes/*.js'
+  urlPath: 'hooks'
+```
+
+Route modules default-export an async function that receives the Fastify server
+and Harper helpers:
+
+```js
+export default async (server, { hdbCore, logger }) => {
+  server.route({
+    method: 'POST',
+    url: '/payment/:provider',
+    preValidation: hdbCore.preValidation,
+    handler: async (request, reply) => {
+      logger.debug(`payment webhook ${request.params.provider}`);
+      request.body = {
+        operation: 'insert',
+        schema: 'app',
+        table: 'WebhookEvent',
+        records: [
+          {
+            id: request.headers['x-event-id'],
+            provider: request.params.provider,
+            payload: request.body,
+          },
+        ],
+      };
+      const result = await hdbCore.request(request);
+      return { ok: true, result };
+    },
+  });
+};
+```
+
+Use Fastify's `request.params`, `request.query`, `request.body`, and `request.headers`
+for route inputs. Keep auth explicit: `hdbCore.request` should be paired with
+`hdbCore.preValidation` so Harper authenticates the request. Avoid
+`requestWithoutAuthentication` unless the route has its own signature/JWT check
+and all user-provided values are bound or escaped; never build SQL strings by
+interpolating params/body values.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -i -X POST http://localhost:9926/app/hooks/payment/stripe \
+  -H 'Authorization: Basic ...' \
+  -H 'Content-Type: application/json' \
+  -H 'x-event-id: evt_123' \
+  --data '{"status":"paid"}'
+```
+
+## `static`: serve web assets and SPAs
+
+Use `static` to serve generated browser output or other immutable assets from
+the component. In Lisa Harper Fabric projects, `harper-app/web/**` is generated
+by the project build; edit the source UI under `src/`, not the deployed files.
+
+```yaml
+static:
+  files: 'web/**'
+  urlPath: '.'
+  index: true
+```
+
+`files` selects what is served. `urlPath` mounts those files under a URL prefix:
+`urlPath: 'app'` makes `web/index.html` available at `/app/index.html`; the
+default application path still includes the Harper project/component prefix. Use
+`index: true` to serve `index.html` for directory requests, and `extensions:
+['html']` when clean URLs should resolve to `.html` files.
+
+For client-side-routed SPAs, return the app shell for unmatched asset paths:
+
+```yaml
+static:
+  files: 'web/**'
+  urlPath: '.'
+  index: true
+  fallthrough: false
+  notFound:
+    file: 'web/index.html'
+    statusCode: 200
+```
+
+That fallback is for browser routes such as `/reports/weekly`; it should not hide
+missing API endpoints or broken asset names. Keep API routes under a clear
+prefix, and check that hashed JS/CSS assets still return their actual files.
+
+Harper's documented `static` config controls path matching and not-found
+behavior, not custom cache policy. Treat MIME type and cache headers as runtime
+behavior to verify with `curl -I`; if the app needs precise cache headers,
+front it with an edge/proxy policy or a custom route designed for that asset
+surface.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -I http://localhost:9926/app/
+curl -I http://localhost:9926/app/assets/index.js
+curl -I http://localhost:9926/app/client-side-route
+```
+
 ## External components and custom plugins
 
 A component you depend on from npm needs a `package:` directive matching a
@@ -109,4 +278,6 @@ dropped an extension often fails only at runtime, not at build time.
 ## Sources
 
 - [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
-- [Built-in extensions](https://docs.harperdb.io/docs/reference/components/built-in-extensions)
+- [Data Loader](https://docs.harperdb.io/reference/v5/database/data-loader)
+- [Fastify Routes](https://docs.harperdb.io/reference/v5/fastify-routes/overview)
+- [Static Files](https://docs.harperdb.io/reference/v5/static-files/overview)

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

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

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

@@ -66,6 +66,175 @@ For real-time work, component `config.yaml` keeps `rest`, `graphqlSchema`, and
 MQTT topic paths. Broker ports and MQTT authentication live in the root
 `harper-config.yaml`, not the component file. See [[harper-realtime]].
 
+## `dataLoader`: seed data
+
+Use `dataLoader` for versioned seed/reference records that should exist whenever
+the component is deployed. Define table shape first with `graphqlSchema`, then
+point `dataLoader.files` at one or more JSON/YAML files:
+
+```yaml
+graphqlSchema:
+  files: 'schema.graphql'
+dataLoader:
+  files:
+    - 'data/roles.yaml'
+    - 'data/reference/*.json'
+```
+
+Each data file targets exactly one table and has `database`, `table`, and
+`records` keys:
+
+```yaml
+database: app
+table: Role
+records:
+  - id: admin
+    name: Administrator
+    permissions:
+      - users:read
+      - users:write
+  - id: viewer
+    name: Viewer
+    permissions:
+      - users:read
+```
+
+Harper runs the loader on full system starts and component deployments. It is
+safe to re-run when files are idempotent: new records are inserted, unchanged
+records are skipped, and records are updated from the file only when the tracked
+file content changed. User-created records and user edits made after an initial
+load are preserved; changed data-loaded records are patched instead of blindly
+replaced.
+
+Choose `dataLoader` for small, source-controlled reference/configuration data
+that should ship with the component. Use a REST/Operations API script or job for
+large imports, environment-specific backfills, or one-off migrations where retry
+scope and operator approval matter.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -s http://localhost:9926/app/Role/admin
+harper dev harper-app # restart/redeploy and confirm the seed did not duplicate
+```
+
+## `fastifyRoutes`: custom HTTP routes
+
+Prefer `jsResource` plus `rest` for normal CRUD/action APIs. Use `fastifyRoutes`
+only when the route shape does not fit the Resource model: webhooks, custom
+serialization, unusual path matching, or a compatibility endpoint.
+
+```yaml
+rest: true
+graphqlSchema:
+  files: 'schema.graphql'
+jsResource:
+  files: 'resources.js'
+fastifyRoutes:
+  files: 'routes/*.js'
+  urlPath: 'hooks'
+```
+
+Route modules default-export an async function that receives the Fastify server
+and Harper helpers:
+
+```js
+export default async (server, { hdbCore, logger }) => {
+  server.route({
+    method: 'POST',
+    url: '/payment/:provider',
+    preValidation: hdbCore.preValidation,
+    handler: async (request, reply) => {
+      logger.debug(`payment webhook ${request.params.provider}`);
+      request.body = {
+        operation: 'insert',
+        schema: 'app',
+        table: 'WebhookEvent',
+        records: [
+          {
+            id: request.headers['x-event-id'],
+            provider: request.params.provider,
+            payload: request.body,
+          },
+        ],
+      };
+      const result = await hdbCore.request(request);
+      return { ok: true, result };
+    },
+  });
+};
+```
+
+Use Fastify's `request.params`, `request.query`, `request.body`, and `request.headers`
+for route inputs. Keep auth explicit: `hdbCore.request` should be paired with
+`hdbCore.preValidation` so Harper authenticates the request. Avoid
+`requestWithoutAuthentication` unless the route has its own signature/JWT check
+and all user-provided values are bound or escaped; never build SQL strings by
+interpolating params/body values.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -i -X POST http://localhost:9926/app/hooks/payment/stripe \
+  -H 'Authorization: Basic ...' \
+  -H 'Content-Type: application/json' \
+  -H 'x-event-id: evt_123' \
+  --data '{"status":"paid"}'
+```
+
+## `static`: serve web assets and SPAs
+
+Use `static` to serve generated browser output or other immutable assets from
+the component. In Lisa Harper Fabric projects, `harper-app/web/**` is generated
+by the project build; edit the source UI under `src/`, not the deployed files.
+
+```yaml
+static:
+  files: 'web/**'
+  urlPath: '.'
+  index: true
+```
+
+`files` selects what is served. `urlPath` mounts those files under a URL prefix:
+`urlPath: 'app'` makes `web/index.html` available at `/app/index.html`; the
+default application path still includes the Harper project/component prefix. Use
+`index: true` to serve `index.html` for directory requests, and `extensions:
+['html']` when clean URLs should resolve to `.html` files.
+
+For client-side-routed SPAs, return the app shell for unmatched asset paths:
+
+```yaml
+static:
+  files: 'web/**'
+  urlPath: '.'
+  index: true
+  fallthrough: false
+  notFound:
+    file: 'web/index.html'
+    statusCode: 200
+```
+
+That fallback is for browser routes such as `/reports/weekly`; it should not hide
+missing API endpoints or broken asset names. Keep API routes under a clear
+prefix, and check that hashed JS/CSS assets still return their actual files.
+
+Harper's documented `static` config controls path matching and not-found
+behavior, not custom cache policy. Treat MIME type and cache headers as runtime
+behavior to verify with `curl -I`; if the app needs precise cache headers,
+front it with an edge/proxy policy or a custom route designed for that asset
+surface.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -I http://localhost:9926/app/
+curl -I http://localhost:9926/app/assets/index.js
+curl -I http://localhost:9926/app/client-side-route
+```
+
 ## External components and custom plugins
 
 A component you depend on from npm needs a `package:` directive matching a
@@ -109,4 +278,6 @@ dropped an extension often fails only at runtime, not at build time.
 ## Sources
 
 - [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
-- [Built-in extensions](https://docs.harperdb.io/docs/reference/components/built-in-extensions)
+- [Data Loader](https://docs.harperdb.io/reference/v5/database/data-loader)
+- [Fastify Routes](https://docs.harperdb.io/reference/v5/fastify-routes/overview)
+- [Static Files](https://docs.harperdb.io/reference/v5/static-files/overview)

package/plugins/lisa-harper-fabric-copilot/.claude-plugin/plugin.json

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