@codyswann/lisa 2.166.2 → 2.166.4

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.2",
+  "version": "2.166.4",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-copilot/skills/harper-build-and-deploy/SKILL.md

@@ -27,14 +27,42 @@ The CLI binary is `harper` (v5; older installs use `harperdb`). Key commands:
 In this project, dev typically runs against the component dir, e.g.
 `harper dev harper-app` (use the project's documented run command if it wraps this).
 
-## The build step (TypeScript → generated artifacts)
+## The build step (TypeScript -> generated artifacts)
 
 Harper loads JavaScript (`resources.js`) and serves static files (`web/**`). In this
-project those are **generated**, not authored:
-
-- **TypeScript under `src/` is source.** `bun run build` compiles it into
-  `harper-app/resources.js` and `harper-app/web/**`.
-- **Never edit `resources.js` or `web/**` directly** — change the TypeScript and
+project those are **generated**, not authored.
+
+What the build actually does:
+
+1. Compiles the TypeScript source under `src/` into deployable JavaScript.
+2. Emits `harper-app/resources.js`, the aggregate resource module loaded by the
+   `jsResource` extension.
+3. Emits per-resource modules such as `harper-app/resource-*.js` when the project
+   build splits resources for Harper's runtime loader.
+4. Copies browser/static output into `harper-app/web/**` for the `static`
+   extension to serve.
+5. Mirrors shared library output into `harper-app/lib/**` and rewrites imports
+   such as `../lib/foo.js` to `./lib/foo.js`. Fabric packages the component root
+   as a flat deploy unit, and Node resolves real paths at runtime, so imports must
+   point at files that exist inside the packaged `harper-app/` root.
+6. Adds cache-busting `?v=` query parameters to browser-module imports when the
+   project build owns web asset versioning.
+
+Generated Harper deploy artifacts usually include:
+
+- `harper-app/resources.js`
+- `harper-app/resource-*.js`
+- `harper-app/web/**`
+- `harper-app/lib/**`
+
+Every lint, format, dead-code, search, or generated-artifact guard must ignore
+those generated paths unless it is explicitly validating the build output itself.
+When a new generated path appears, add it to every relevant ignore surface in the
+same change; partial ignores fail later gates in non-obvious ways.
+
+- **TypeScript under `src/` is source.** `bun run build` produces the deployable
+  Harper assets from it.
+- **Never edit generated Harper assets directly** — change the TypeScript and
   rebuild. See [[harper-resources]] and [[harper-component-model]].
 - **Build before symlinking, packaging, or deploying `harper-app/`.** Deploying
   stale artifacts ships code that does not match `src/`.
@@ -86,11 +114,45 @@ harper deploy_component \
 
 - Omitting `package` deploys the current directory.
 - `restart=true` restarts threads after deploy so new code loads.
-- `replicated=true` replicates the deploy across all nodes in a cluster — include it
-  when targeting Fabric/a cluster.
+- `replicated=true` asks Harper/Fabric to apply the component deploy across the
+  cluster rather than only the node receiving the deploy request. Include it when
+  targeting Fabric or any clustered deployment.
 - Credentials can come from `CLI_TARGET_USERNAME` / `CLI_TARGET_PASSWORD` instead of
   inline flags — prefer that so secrets never land in shell history or tracked files.
 
+## Replication and topology
+
+Fabric is a distributed runtime: a project can run on one or more Harper nodes,
+often grouped by region or environment. Your application code is packaged as a
+component, and the data layer is replicated through Harper's database and
+clustering model.
+
+Keep these semantics separate:
+
+- **Component code replication** is controlled by deploy behavior. With
+  `replicated=true`, the deployed component package should reach the cluster nodes
+  that serve the application. Without it, you may update only the target node and
+  leave other nodes running older code.
+- **Data replication** is runtime/database behavior. Deploying code does not by
+  itself prove that existing rows, schema changes, caches, or realtime state are
+  consistent across regions or nodes.
+- **Thread restart** is local process behavior. `restart=true` reloads code after
+  the package lands; it is not a substitute for checking every node or region that
+  receives traffic.
+
+After a replicated deploy, verify from the topology the app actually uses:
+
+1. Confirm the deploy command or workflow used `replicated=true` for Fabric/cluster
+   targets.
+2. Read `harper status` or the project's Fabric status command to see the expected
+   nodes/regions.
+3. Hit the public smoke endpoint through the production route, then hit a direct
+   node or region endpoint when the project exposes one.
+4. For schema or data changes, verify a write/read path that proves the expected
+   data is visible where traffic can land.
+5. If one node serves old assets or resources, treat the deploy as incomplete even
+   when the initial target node passed smoke.
+
 ## Secrets
 
 Keep runtime secrets out of tracked files. Use environment variables, the

package/plugins/lisa-harper-fabric-copilot/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-cursor/.claude-plugin/plugin.json

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

package/plugins/lisa-harper-fabric-cursor/skills/harper-build-and-deploy/SKILL.md

@@ -27,14 +27,42 @@ The CLI binary is `harper` (v5; older installs use `harperdb`). Key commands:
 In this project, dev typically runs against the component dir, e.g.
 `harper dev harper-app` (use the project's documented run command if it wraps this).
 
-## The build step (TypeScript → generated artifacts)
+## The build step (TypeScript -> generated artifacts)
 
 Harper loads JavaScript (`resources.js`) and serves static files (`web/**`). In this
-project those are **generated**, not authored:
-
-- **TypeScript under `src/` is source.** `bun run build` compiles it into
-  `harper-app/resources.js` and `harper-app/web/**`.
-- **Never edit `resources.js` or `web/**` directly** — change the TypeScript and
+project those are **generated**, not authored.
+
+What the build actually does:
+
+1. Compiles the TypeScript source under `src/` into deployable JavaScript.
+2. Emits `harper-app/resources.js`, the aggregate resource module loaded by the
+   `jsResource` extension.
+3. Emits per-resource modules such as `harper-app/resource-*.js` when the project
+   build splits resources for Harper's runtime loader.
+4. Copies browser/static output into `harper-app/web/**` for the `static`
+   extension to serve.
+5. Mirrors shared library output into `harper-app/lib/**` and rewrites imports
+   such as `../lib/foo.js` to `./lib/foo.js`. Fabric packages the component root
+   as a flat deploy unit, and Node resolves real paths at runtime, so imports must
+   point at files that exist inside the packaged `harper-app/` root.
+6. Adds cache-busting `?v=` query parameters to browser-module imports when the
+   project build owns web asset versioning.
+
+Generated Harper deploy artifacts usually include:
+
+- `harper-app/resources.js`
+- `harper-app/resource-*.js`
+- `harper-app/web/**`
+- `harper-app/lib/**`
+
+Every lint, format, dead-code, search, or generated-artifact guard must ignore
+those generated paths unless it is explicitly validating the build output itself.
+When a new generated path appears, add it to every relevant ignore surface in the
+same change; partial ignores fail later gates in non-obvious ways.
+
+- **TypeScript under `src/` is source.** `bun run build` produces the deployable
+  Harper assets from it.
+- **Never edit generated Harper assets directly** — change the TypeScript and
   rebuild. See [[harper-resources]] and [[harper-component-model]].
 - **Build before symlinking, packaging, or deploying `harper-app/`.** Deploying
   stale artifacts ships code that does not match `src/`.
@@ -86,11 +114,45 @@ harper deploy_component \
 
 - Omitting `package` deploys the current directory.
 - `restart=true` restarts threads after deploy so new code loads.
-- `replicated=true` replicates the deploy across all nodes in a cluster — include it
-  when targeting Fabric/a cluster.
+- `replicated=true` asks Harper/Fabric to apply the component deploy across the
+  cluster rather than only the node receiving the deploy request. Include it when
+  targeting Fabric or any clustered deployment.
 - Credentials can come from `CLI_TARGET_USERNAME` / `CLI_TARGET_PASSWORD` instead of
   inline flags — prefer that so secrets never land in shell history or tracked files.
 
+## Replication and topology
+
+Fabric is a distributed runtime: a project can run on one or more Harper nodes,
+often grouped by region or environment. Your application code is packaged as a
+component, and the data layer is replicated through Harper's database and
+clustering model.
+
+Keep these semantics separate:
+
+- **Component code replication** is controlled by deploy behavior. With
+  `replicated=true`, the deployed component package should reach the cluster nodes
+  that serve the application. Without it, you may update only the target node and
+  leave other nodes running older code.
+- **Data replication** is runtime/database behavior. Deploying code does not by
+  itself prove that existing rows, schema changes, caches, or realtime state are
+  consistent across regions or nodes.
+- **Thread restart** is local process behavior. `restart=true` reloads code after
+  the package lands; it is not a substitute for checking every node or region that
+  receives traffic.
+
+After a replicated deploy, verify from the topology the app actually uses:
+
+1. Confirm the deploy command or workflow used `replicated=true` for Fabric/cluster
+   targets.
+2. Read `harper status` or the project's Fabric status command to see the expected
+   nodes/regions.
+3. Hit the public smoke endpoint through the production route, then hit a direct
+   node or region endpoint when the project exposes one.
+4. For schema or data changes, verify a write/read path that proves the expected
+   data is visible where traffic can land.
+5. If one node serves old assets or resources, treat the deploy as incomplete even
+   when the initial target node passed smoke.
+
 ## Secrets
 
 Keep runtime secrets out of tracked files. Use environment variables, the