@codyswann/lisa 2.20.0 → 2.21.0

package/package.json

@@ -81,7 +81,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "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.20.0",
+  "version": "2.21.0",
   "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.20.0",
+  "version": "2.21.0",
   "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.20.0",
+  "version": "2.21.0",
   "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.20.0",
+  "version": "2.21.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "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.20.0",
+  "version": "2.21.0",
   "description": "Expo and 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.20.0",
+  "version": "2.21.0",
   "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.20.0",
+  "version": "2.21.0",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"
@@ -14,6 +14,7 @@
   "dependencies": [
     "lisa-typescript"
   ],
+  "skills": "./skills/",
   "interface": {
     "displayName": "Lisa Harper/Fabric",
     "shortDescription": "Harper/Fabric workflow guidance",

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

@@ -0,0 +1,101 @@
+---
+name: harper-build-and-deploy
+description: This skill should be used when building, running locally, or deploying a Harper (HarperDB/Fabric) component — running harper dev/run, producing the generated resources.js and web/** from TypeScript via the project build, packaging the harper-app component, deploying to Harper Fabric, or handling deploy-time secrets. Use it for any change that affects the deployable surface or the dev loop. Pairs with harper-component-model, harper-config-yaml, and harper-resources.
+---
+
+# Harper Build and Deploy
+
+## Overview
+
+The Harper lifecycle is: **develop locally → build TypeScript into the deployable
+component → run/iterate → deploy to Fabric**. This skill covers the CLI, the
+project's build step, and the deploy surface so a change is provably finished, not
+just compiling.
+
+## Local dev and run (the CLI)
+
+The CLI binary is `harper` (v5; older installs use `harperdb`). Key commands:
+
+| Command | What it does |
+| --- | --- |
+| `harper dev <path/to/app>` | Dev mode: **watches files, single-threaded, auto-restarts worker threads** on change, with console logging. The fast iteration loop. Does **not** restart the main thread. |
+| `harper run <path/to/app>` | Run an app from any directory. Use when you need the main thread to (re)start; manage start/stop yourself. |
+| `harper start` / `stop` / `restart` | Background (daemon) lifecycle. |
+| `harper status` | Harper and clustering status. |
+| `harper get_components` | List installed components. |
+
+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)
+
+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
+  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/`.
+
+## The deployable surface
+
+A deployable Harper component must keep these at the component root Fabric packages:
+
+- `config.yaml` — active extensions ([[harper-config-yaml]])
+- `schema.graphql` — data model ([[harper-schema-graphql]])
+- `resources.js` — generated custom logic
+- `web/**` — generated static assets
+
+If a change touches this surface, it is not done until the local build and the
+relevant deployed or smoke path agree.
+
+## Deploying to Fabric
+
+Fabric is Harper's distributed deploy network. Deploy packages the component and
+sends it to a target instance:
+
+```bash
+harper deploy_component \
+  project=<app-name> \
+  package=<path-or-git-url> \
+  target=https://<instance>:9925 \
+  username=<user> \
+  password=<pass> \
+  restart=true \
+  replicated=true
+```
+
+- 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.
+- 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.
+
+## Secrets
+
+Keep runtime secrets out of tracked files. Use environment variables, the
+`loadEnv` extension, or an OS keychain helper. Document *where* secrets live (which
+env var, which store) without recording their values.
+
+## Verification (required before reporting done)
+
+1. `bun run build` — produces fresh `resources.js` / `web/**`.
+2. `bun run typecheck`.
+3. The smallest relevant test command.
+4. For deploy-affecting changes, the project **smoke command** against the local or
+   deployed Harper endpoint.
+
+If a verification command cannot run, report the exact command and the blocker —
+do not claim completion. When you hit a Harper/Fabric limitation or workaround,
+record the symptom, root cause, fix, and the tempting-but-broken alternatives in
+the project's Fabric runbook.
+
+## Sources
+
+- [Harper CLI overview](https://docs.harperdb.io/reference/v4/cli/overview)
+- [Harper CLI](https://docs.harperdb.io/docs/deployments/harper-cli)
+- [Plugin API](https://docs.harperdb.io/reference/v5/components/plugin-api)
+- [Harper Fabric](https://www.harper.fast/)

package/plugins/lisa-harper-fabric/skills/harper-component-model/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: harper-component-model
+description: This skill should be used when reasoning about how a Harper (formerly HarperDB) Fabric application is structured — what a component, application, extension, or plugin is, where code and assets belong, and how the pieces depend on each other. Use it before adding a new capability, wiring an extension, deciding where a file should live, or explaining the runtime to someone. Pairs with harper-config-yaml, harper-resources, harper-schema-graphql, and harper-build-and-deploy.
+---
+
+# Harper Component Model
+
+## Overview
+
+Harper (formerly HarperDB; the product and company now at harper.fast) is an
+open-source Node.js platform that fuses **database, cache, application logic, and
+messaging into a single in-memory process**. **Fabric** is Harper's distributed
+deploy network: you develop locally, then deploy the same component to Fabric.
+
+Everything you build is a **component**. Understanding the component hierarchy is
+the prerequisite for every other Harper decision — config, resources, schema, and
+deploy all hang off it.
+
+## The three tiers
+
+Harper organizes functionality into three tiers, top to bottom:
+
+1. **Applications** — the user-facing product. An application *is* a type of
+   component. It implements business logic (REST/GraphQL endpoints, web UI,
+   real-time) by depending on extensions/plugins. This is what this project is.
+2. **Plugins** (v5) / **Extensions** (deprecated) — the building blocks an
+   application depends on. A plugin exports a single `handleApplication(scope)`
+   method and always runs on worker threads. The deprecated Extension API used
+   `start`, `handleFile`, `handleDirectory`, and `setupDirectory` instead.
+   `handleApplication()` cannot coexist with Extension API methods — defining
+   both throws. Prefer the Plugin API for any custom building block.
+3. **Core services** — the high-performance database, networking middleware, and
+   the component manager. You configure these; you don't reimplement them.
+
+> An *application* is the component you ship. *Extensions/plugins* are the
+> capabilities it consumes. Built-in extensions (`graphqlSchema`, `jsResource`,
+> `rest`, `static`, …) are provided by core; you only *enable* them in
+> `config.yaml`. See [[harper-config-yaml]].
+
+## Built-in extensions an application typically uses
+
+These ship with Harper and are enabled (not installed) via `config.yaml`:
+
+- `graphqlSchema` — define database tables/types from GraphQL schema files. See [[harper-schema-graphql]].
+- `jsResource` — load custom JavaScript resources (`resources.js`). See [[harper-resources]].
+- `rest` — auto-generate REST endpoints for exported resources/tables.
+- `static` — serve static files (the `web/**` directory) over HTTP.
+- `roles` — role-based access control from `roles.yaml`.
+- `loadEnv` — load environment variables from `.env`.
+- `dataLoader` — seed Harper tables from JSON/YAML.
+- `fastifyRoutes` — custom Fastify route handlers.
+
+## Where things live in this project
+
+This project wraps Harper's native model with a fixed layout under `harper-app/`:
+
+| Path | Role | Source or generated |
+| --- | --- | --- |
+| `harper-app/config.yaml` | Component config — which extensions are active | **Source** |
+| `harper-app/schema.graphql` | Table/type definitions | **Source** |
+| `src/**` (TypeScript) | Resources, browser modules, shared libs, scripts | **Source** |
+| `harper-app/resources.js` | Loaded by `jsResource` | **Generated** — never edit; build from TS |
+| `harper-app/web/**` | Served by `static` | **Generated** — never edit; build from TS |
+
+The TypeScript under `src/` is the source of truth. `resources.js` and `web/**`
+are deploy artifacts produced by `bun run build`. Never hand-edit them — change
+the matching TypeScript and rebuild. See [[harper-build-and-deploy]].
+
+## Decision guide
+
+- **Adding a backend behavior?** It's almost always a *resource* (custom logic) or
+  a *schema* change (new table/field), enabled through `config.yaml`. Don't ship a
+  client-side workaround for missing backend behavior — make the Harper change.
+- **Adding a reusable building block / npm-publishable capability?** That's a
+  *plugin* (`pluginModule`), not application code.
+- **Adding static UI?** It belongs in `web/**` (generated from `src/` UI code), served
+  by the `static` extension.
+- **Not sure if it deploys?** A deployable Harper app must keep `config.yaml`,
+  `schema.graphql`, `resources.js`, and `web/**` at the component root that Fabric
+  packages. If your change touches that surface, build before packaging.
+
+## Sources
+
+- [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
+- [Plugin API](https://docs.harperdb.io/reference/v5/components/plugin-api)
+- [Applications](https://docs.harperdb.io/docs/developers/applications)
+- [Harper platform](https://www.harper.fast/)

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

@@ -0,0 +1,107 @@
+---
+name: harper-config-yaml
+description: This skill should be used when creating or editing a Harper (HarperDB/Fabric) component's config.yaml — enabling a built-in extension (graphqlSchema, jsResource, rest, static, roles, loadEnv, dataLoader, fastifyRoutes), wiring an external component, or troubleshooting why an extension is not loading. Critical: it documents the no-merge footgun where a custom config.yaml replaces Harper's default config entirely. Pairs with harper-component-model, harper-resources, and harper-schema-graphql.
+---
+
+# Harper config.yaml
+
+## Overview
+
+A Harper component is configured by a single `config.yaml` at the component root
+(`harper-app/config.yaml` in this project). It declares **which extensions are
+active** and which files each extension reads. Extensions are *enabled* here, not
+installed — the built-ins ship with Harper.
+
+The structure is a map of extension name to its options:
+
+```yaml
+extensionName:
+  option-1: value
+  option-2: value
+```
+
+## ⚠️ The no-merge footgun
+
+If a component has **no** `config.yaml`, Harper applies this default automatically:
+
+```yaml
+rest: true
+graphqlSchema:
+  files: '*.graphql'
+roles:
+  files: 'roles.yaml'
+jsResource:
+  files: 'resources.js'
+fastifyRoutes:
+  files: 'routes/*.js'
+  urlPath: '.'
+static:
+  files: 'web/**'
+```
+
+The moment you add a **custom `config.yaml`, it replaces this default entirely —
+Harper does not merge your file with the defaults.** If you write a `config.yaml`
+that only enables `static`, you have silently turned off `rest`, `graphqlSchema`,
+`jsResource`, and `roles`. This is the most common Harper config mistake.
+
+**Rule:** when you add or edit `config.yaml`, re-declare every extension the app
+actually needs — start from the default block above and add to it. Do not assume
+unmentioned extensions stay on.
+
+## Built-in extensions
+
+| Key | Purpose | Common options |
+| --- | --- | --- |
+| `rest` | Auto REST endpoints for exported resources/tables | `true`, or an object with options |
+| `graphqlSchema` | Define tables/types from GraphQL files | `files: '*.graphql'` — see [[harper-schema-graphql]] |
+| `jsResource` | Load custom JS resources | `files: 'resources.js'` — see [[harper-resources]] |
+| `static` | Serve static files over HTTP | `files: 'web/**'`, `urlPath` |
+| `roles` | Role-based access control | `files: 'roles.yaml'` |
+| `loadEnv` | Load env vars from `.env` | `files` |
+| `dataLoader` | Seed tables from JSON/YAML | `files` |
+| `fastifyRoutes` | Custom Fastify routes | `files: 'routes/*.js'`, `urlPath` |
+
+## External components and custom plugins
+
+A component you depend on from npm needs a `package:` directive matching a
+`package.json` dependency:
+
+```yaml
+'@harperdb/nextjs':
+  package: '@harperdb/nextjs'
+  files: './'
+```
+
+A custom plugin you author is wired with `pluginModule` (point at the built JS, not
+TypeScript source):
+
+```yaml
+pluginModule: ./dist/index.js
+```
+
+The deprecated Extension API used `extensionModule` instead. Prefer `pluginModule`.
+See [[harper-component-model]] for the plugin-vs-extension distinction.
+
+## Project conventions
+
+- `config.yaml` is **source** and lives at `harper-app/config.yaml`. It is part of
+  the deployable surface Fabric packages — keep it at the component root.
+- The files `config.yaml` points to (`resources.js`, `web/**`) are **generated** by
+  `bun run build` from TypeScript under `src/`. Editing `config.yaml` to point at a
+  new file means the build must produce that file. See [[harper-build-and-deploy]].
+- A `config.yaml` change is a deploy-shape change: update the matching project doc
+  (the Fabric runbook) in the same change, and re-run the smoke command.
+- Keep secrets out of `config.yaml`. Use `loadEnv` / environment variables and
+  document *where* secrets live without recording their values.
+
+## Verification
+
+After editing `config.yaml`, confirm the app still boots and the expected surface
+is live: run `harper dev harper-app` (or the project's run command) and check that
+the REST/GraphQL/static endpoints you rely on respond. A config that silently
+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)

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

@@ -0,0 +1,106 @@
+---
+name: harper-resources
+description: This skill should be used when writing or editing Harper (HarperDB/Fabric) resources — the classes in resources.js (built from TypeScript under src/) that expose custom data logic over REST and GraphQL. Use it when adding an endpoint, overriding table behavior, wrapping an external API, or wiring real-time subscriptions. Covers the Resource method-to-HTTP mapping and the TS-is-source build convention. Pairs with harper-schema-graphql, harper-config-yaml, and harper-build-and-deploy.
+---
+
+# 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 and [[harper-schema-graphql]]
+for how the schema defines the tables resources extend.
+
+## 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/skills/harper-schema-graphql/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: harper-schema-graphql
+description: This skill should be used when editing a Harper (HarperDB/Fabric) schema.graphql — defining or changing database tables, types, fields, relationships, or indexes that the graphqlSchema extension turns into Harper tables and API surface. Use it when adding a table, changing the data model, or when a resource/verify path depends on schema shape. Pairs with harper-resources, harper-config-yaml, and harper-component-model.
+---
+
+# Harper schema.graphql
+
+## Overview
+
+Harper defines its database tables and types from **GraphQL schema files**, loaded
+by the `graphqlSchema` extension (default `*.graphql`; this project uses
+`harper-app/schema.graphql`). The schema is the source of truth for the data model:
+the tables it declares are what resources extend ([[harper-resources]]) and what
+the REST/GraphQL surface exposes.
+
+## Defining tables
+
+A table is a GraphQL type. Harper-specific directives mark a type as a persisted
+table and control exposure, primary keys, and indexes. The exact directive set
+depends on the Harper version in use — confirm against the live `schema.graphql`
+in this project and the Harper schema docs before adding new syntax. Common shape:
+
+```graphql
+type Dog @table {
+  id: ID @primaryKey
+  name: String @indexed
+  breed: String
+  owner: String
+}
+```
+
+- `@table` marks the type as a persisted Harper table.
+- `@primaryKey` marks the primary key field.
+- `@indexed` adds a secondary index for query/`search`.
+- Exposure of a type as an API endpoint is controlled by the schema/`rest`
+  configuration — see [[harper-config-yaml]].
+
+> Treat the directive names above as a starting point, not gospel — verify against
+> the project's existing schema and current Harper docs, since directive syntax has
+> evolved across versions.
+
+## How the schema drives the app
+
+- The `graphqlSchema` extension creates/migrates tables from the schema on load.
+- `rest: true` exposes exported tables/resources as REST endpoints; the GraphQL
+  surface is generated from the same schema.
+- Resources that `extends tables.X` depend on `X` existing in the schema. A rename
+  or removal in the schema is a breaking change for every resource and verify path
+  that references it.
+
+## Project conventions
+
+- `schema.graphql` is **source** and lives at the component root that Fabric
+  packages (`harper-app/schema.graphql`). Keep it there.
+- A schema change is a data-model change. In the **same change**:
+  - Update the conceptual schema docs.
+  - Update any verify/smoke paths that assert joins, relationships, or row counts —
+    those assertions encode the data model and must track it.
+  - Update resources and seed/data-loader paths that reference changed tables.
+- Document deploy-affecting consequences (new tables, migrations) in the Fabric
+  runbook. See [[harper-build-and-deploy]].
+
+## Verification
+
+After a schema change, boot the app (`harper dev harper-app` or the project run
+command) and confirm tables migrate cleanly and the dependent endpoints respond.
+Run any verify path that asserts row counts or joins against the changed model.
+
+## Sources
+
+- [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
+- [Applications](https://docs.harperdb.io/docs/developers/applications)

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

@@ -0,0 +1,101 @@
+---
+name: harper-build-and-deploy
+description: This skill should be used when building, running locally, or deploying a Harper (HarperDB/Fabric) component — running harper dev/run, producing the generated resources.js and web/** from TypeScript via the project build, packaging the harper-app component, deploying to Harper Fabric, or handling deploy-time secrets. Use it for any change that affects the deployable surface or the dev loop. Pairs with harper-component-model, harper-config-yaml, and harper-resources.
+---
+
+# Harper Build and Deploy
+
+## Overview
+
+The Harper lifecycle is: **develop locally → build TypeScript into the deployable
+component → run/iterate → deploy to Fabric**. This skill covers the CLI, the
+project's build step, and the deploy surface so a change is provably finished, not
+just compiling.
+
+## Local dev and run (the CLI)
+
+The CLI binary is `harper` (v5; older installs use `harperdb`). Key commands:
+
+| Command | What it does |
+| --- | --- |
+| `harper dev <path/to/app>` | Dev mode: **watches files, single-threaded, auto-restarts worker threads** on change, with console logging. The fast iteration loop. Does **not** restart the main thread. |
+| `harper run <path/to/app>` | Run an app from any directory. Use when you need the main thread to (re)start; manage start/stop yourself. |
+| `harper start` / `stop` / `restart` | Background (daemon) lifecycle. |
+| `harper status` | Harper and clustering status. |
+| `harper get_components` | List installed components. |
+
+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)
+
+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
+  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/`.
+
+## The deployable surface
+
+A deployable Harper component must keep these at the component root Fabric packages:
+
+- `config.yaml` — active extensions ([[harper-config-yaml]])
+- `schema.graphql` — data model ([[harper-schema-graphql]])
+- `resources.js` — generated custom logic
+- `web/**` — generated static assets
+
+If a change touches this surface, it is not done until the local build and the
+relevant deployed or smoke path agree.
+
+## Deploying to Fabric
+
+Fabric is Harper's distributed deploy network. Deploy packages the component and
+sends it to a target instance:
+
+```bash
+harper deploy_component \
+  project=<app-name> \
+  package=<path-or-git-url> \
+  target=https://<instance>:9925 \
+  username=<user> \
+  password=<pass> \
+  restart=true \
+  replicated=true
+```
+
+- 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.
+- 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.
+
+## Secrets
+
+Keep runtime secrets out of tracked files. Use environment variables, the
+`loadEnv` extension, or an OS keychain helper. Document *where* secrets live (which
+env var, which store) without recording their values.
+
+## Verification (required before reporting done)
+
+1. `bun run build` — produces fresh `resources.js` / `web/**`.
+2. `bun run typecheck`.
+3. The smallest relevant test command.
+4. For deploy-affecting changes, the project **smoke command** against the local or
+   deployed Harper endpoint.
+
+If a verification command cannot run, report the exact command and the blocker —
+do not claim completion. When you hit a Harper/Fabric limitation or workaround,
+record the symptom, root cause, fix, and the tempting-but-broken alternatives in
+the project's Fabric runbook.
+
+## Sources
+
+- [Harper CLI overview](https://docs.harperdb.io/reference/v4/cli/overview)
+- [Harper CLI](https://docs.harperdb.io/docs/deployments/harper-cli)
+- [Plugin API](https://docs.harperdb.io/reference/v5/components/plugin-api)
+- [Harper Fabric](https://www.harper.fast/)

package/plugins/src/harper-fabric/skills/harper-component-model/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: harper-component-model
+description: This skill should be used when reasoning about how a Harper (formerly HarperDB) Fabric application is structured — what a component, application, extension, or plugin is, where code and assets belong, and how the pieces depend on each other. Use it before adding a new capability, wiring an extension, deciding where a file should live, or explaining the runtime to someone. Pairs with harper-config-yaml, harper-resources, harper-schema-graphql, and harper-build-and-deploy.
+---
+
+# Harper Component Model
+
+## Overview
+
+Harper (formerly HarperDB; the product and company now at harper.fast) is an
+open-source Node.js platform that fuses **database, cache, application logic, and
+messaging into a single in-memory process**. **Fabric** is Harper's distributed
+deploy network: you develop locally, then deploy the same component to Fabric.
+
+Everything you build is a **component**. Understanding the component hierarchy is
+the prerequisite for every other Harper decision — config, resources, schema, and
+deploy all hang off it.
+
+## The three tiers
+
+Harper organizes functionality into three tiers, top to bottom:
+
+1. **Applications** — the user-facing product. An application *is* a type of
+   component. It implements business logic (REST/GraphQL endpoints, web UI,
+   real-time) by depending on extensions/plugins. This is what this project is.
+2. **Plugins** (v5) / **Extensions** (deprecated) — the building blocks an
+   application depends on. A plugin exports a single `handleApplication(scope)`
+   method and always runs on worker threads. The deprecated Extension API used
+   `start`, `handleFile`, `handleDirectory`, and `setupDirectory` instead.
+   `handleApplication()` cannot coexist with Extension API methods — defining
+   both throws. Prefer the Plugin API for any custom building block.
+3. **Core services** — the high-performance database, networking middleware, and
+   the component manager. You configure these; you don't reimplement them.
+
+> An *application* is the component you ship. *Extensions/plugins* are the
+> capabilities it consumes. Built-in extensions (`graphqlSchema`, `jsResource`,
+> `rest`, `static`, …) are provided by core; you only *enable* them in
+> `config.yaml`. See [[harper-config-yaml]].
+
+## Built-in extensions an application typically uses
+
+These ship with Harper and are enabled (not installed) via `config.yaml`:
+
+- `graphqlSchema` — define database tables/types from GraphQL schema files. See [[harper-schema-graphql]].
+- `jsResource` — load custom JavaScript resources (`resources.js`). See [[harper-resources]].
+- `rest` — auto-generate REST endpoints for exported resources/tables.
+- `static` — serve static files (the `web/**` directory) over HTTP.
+- `roles` — role-based access control from `roles.yaml`.
+- `loadEnv` — load environment variables from `.env`.
+- `dataLoader` — seed Harper tables from JSON/YAML.
+- `fastifyRoutes` — custom Fastify route handlers.
+
+## Where things live in this project
+
+This project wraps Harper's native model with a fixed layout under `harper-app/`:
+
+| Path | Role | Source or generated |
+| --- | --- | --- |
+| `harper-app/config.yaml` | Component config — which extensions are active | **Source** |
+| `harper-app/schema.graphql` | Table/type definitions | **Source** |
+| `src/**` (TypeScript) | Resources, browser modules, shared libs, scripts | **Source** |
+| `harper-app/resources.js` | Loaded by `jsResource` | **Generated** — never edit; build from TS |
+| `harper-app/web/**` | Served by `static` | **Generated** — never edit; build from TS |
+
+The TypeScript under `src/` is the source of truth. `resources.js` and `web/**`
+are deploy artifacts produced by `bun run build`. Never hand-edit them — change
+the matching TypeScript and rebuild. See [[harper-build-and-deploy]].
+
+## Decision guide
+
+- **Adding a backend behavior?** It's almost always a *resource* (custom logic) or
+  a *schema* change (new table/field), enabled through `config.yaml`. Don't ship a
+  client-side workaround for missing backend behavior — make the Harper change.
+- **Adding a reusable building block / npm-publishable capability?** That's a
+  *plugin* (`pluginModule`), not application code.
+- **Adding static UI?** It belongs in `web/**` (generated from `src/` UI code), served
+  by the `static` extension.
+- **Not sure if it deploys?** A deployable Harper app must keep `config.yaml`,
+  `schema.graphql`, `resources.js`, and `web/**` at the component root that Fabric
+  packages. If your change touches that surface, build before packaging.
+
+## Sources
+
+- [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
+- [Plugin API](https://docs.harperdb.io/reference/v5/components/plugin-api)
+- [Applications](https://docs.harperdb.io/docs/developers/applications)
+- [Harper platform](https://www.harper.fast/)

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

@@ -0,0 +1,107 @@
+---
+name: harper-config-yaml
+description: This skill should be used when creating or editing a Harper (HarperDB/Fabric) component's config.yaml — enabling a built-in extension (graphqlSchema, jsResource, rest, static, roles, loadEnv, dataLoader, fastifyRoutes), wiring an external component, or troubleshooting why an extension is not loading. Critical: it documents the no-merge footgun where a custom config.yaml replaces Harper's default config entirely. Pairs with harper-component-model, harper-resources, and harper-schema-graphql.
+---
+
+# Harper config.yaml
+
+## Overview
+
+A Harper component is configured by a single `config.yaml` at the component root
+(`harper-app/config.yaml` in this project). It declares **which extensions are
+active** and which files each extension reads. Extensions are *enabled* here, not
+installed — the built-ins ship with Harper.
+
+The structure is a map of extension name to its options:
+
+```yaml
+extensionName:
+  option-1: value
+  option-2: value
+```
+
+## ⚠️ The no-merge footgun
+
+If a component has **no** `config.yaml`, Harper applies this default automatically:
+
+```yaml
+rest: true
+graphqlSchema:
+  files: '*.graphql'
+roles:
+  files: 'roles.yaml'
+jsResource:
+  files: 'resources.js'
+fastifyRoutes:
+  files: 'routes/*.js'
+  urlPath: '.'
+static:
+  files: 'web/**'
+```
+
+The moment you add a **custom `config.yaml`, it replaces this default entirely —
+Harper does not merge your file with the defaults.** If you write a `config.yaml`
+that only enables `static`, you have silently turned off `rest`, `graphqlSchema`,
+`jsResource`, and `roles`. This is the most common Harper config mistake.
+
+**Rule:** when you add or edit `config.yaml`, re-declare every extension the app
+actually needs — start from the default block above and add to it. Do not assume
+unmentioned extensions stay on.
+
+## Built-in extensions
+
+| Key | Purpose | Common options |
+| --- | --- | --- |
+| `rest` | Auto REST endpoints for exported resources/tables | `true`, or an object with options |
+| `graphqlSchema` | Define tables/types from GraphQL files | `files: '*.graphql'` — see [[harper-schema-graphql]] |
+| `jsResource` | Load custom JS resources | `files: 'resources.js'` — see [[harper-resources]] |
+| `static` | Serve static files over HTTP | `files: 'web/**'`, `urlPath` |
+| `roles` | Role-based access control | `files: 'roles.yaml'` |
+| `loadEnv` | Load env vars from `.env` | `files` |
+| `dataLoader` | Seed tables from JSON/YAML | `files` |
+| `fastifyRoutes` | Custom Fastify routes | `files: 'routes/*.js'`, `urlPath` |
+
+## External components and custom plugins
+
+A component you depend on from npm needs a `package:` directive matching a
+`package.json` dependency:
+
+```yaml
+'@harperdb/nextjs':
+  package: '@harperdb/nextjs'
+  files: './'
+```
+
+A custom plugin you author is wired with `pluginModule` (point at the built JS, not
+TypeScript source):
+
+```yaml
+pluginModule: ./dist/index.js
+```
+
+The deprecated Extension API used `extensionModule` instead. Prefer `pluginModule`.
+See [[harper-component-model]] for the plugin-vs-extension distinction.
+
+## Project conventions
+
+- `config.yaml` is **source** and lives at `harper-app/config.yaml`. It is part of
+  the deployable surface Fabric packages — keep it at the component root.
+- The files `config.yaml` points to (`resources.js`, `web/**`) are **generated** by
+  `bun run build` from TypeScript under `src/`. Editing `config.yaml` to point at a
+  new file means the build must produce that file. See [[harper-build-and-deploy]].
+- A `config.yaml` change is a deploy-shape change: update the matching project doc
+  (the Fabric runbook) in the same change, and re-run the smoke command.
+- Keep secrets out of `config.yaml`. Use `loadEnv` / environment variables and
+  document *where* secrets live without recording their values.
+
+## Verification
+
+After editing `config.yaml`, confirm the app still boots and the expected surface
+is live: run `harper dev harper-app` (or the project's run command) and check that
+the REST/GraphQL/static endpoints you rely on respond. A config that silently
+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)

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

@@ -0,0 +1,106 @@
+---
+name: harper-resources
+description: This skill should be used when writing or editing Harper (HarperDB/Fabric) resources — the classes in resources.js (built from TypeScript under src/) that expose custom data logic over REST and GraphQL. Use it when adding an endpoint, overriding table behavior, wrapping an external API, or wiring real-time subscriptions. Covers the Resource method-to-HTTP mapping and the TS-is-source build convention. Pairs with harper-schema-graphql, harper-config-yaml, and harper-build-and-deploy.
+---
+
+# 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 and [[harper-schema-graphql]]
+for how the schema defines the tables resources extend.
+
+## 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/src/harper-fabric/skills/harper-schema-graphql/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: harper-schema-graphql
+description: This skill should be used when editing a Harper (HarperDB/Fabric) schema.graphql — defining or changing database tables, types, fields, relationships, or indexes that the graphqlSchema extension turns into Harper tables and API surface. Use it when adding a table, changing the data model, or when a resource/verify path depends on schema shape. Pairs with harper-resources, harper-config-yaml, and harper-component-model.
+---
+
+# Harper schema.graphql
+
+## Overview
+
+Harper defines its database tables and types from **GraphQL schema files**, loaded
+by the `graphqlSchema` extension (default `*.graphql`; this project uses
+`harper-app/schema.graphql`). The schema is the source of truth for the data model:
+the tables it declares are what resources extend ([[harper-resources]]) and what
+the REST/GraphQL surface exposes.
+
+## Defining tables
+
+A table is a GraphQL type. Harper-specific directives mark a type as a persisted
+table and control exposure, primary keys, and indexes. The exact directive set
+depends on the Harper version in use — confirm against the live `schema.graphql`
+in this project and the Harper schema docs before adding new syntax. Common shape:
+
+```graphql
+type Dog @table {
+  id: ID @primaryKey
+  name: String @indexed
+  breed: String
+  owner: String
+}
+```
+
+- `@table` marks the type as a persisted Harper table.
+- `@primaryKey` marks the primary key field.
+- `@indexed` adds a secondary index for query/`search`.
+- Exposure of a type as an API endpoint is controlled by the schema/`rest`
+  configuration — see [[harper-config-yaml]].
+
+> Treat the directive names above as a starting point, not gospel — verify against
+> the project's existing schema and current Harper docs, since directive syntax has
+> evolved across versions.
+
+## How the schema drives the app
+
+- The `graphqlSchema` extension creates/migrates tables from the schema on load.
+- `rest: true` exposes exported tables/resources as REST endpoints; the GraphQL
+  surface is generated from the same schema.
+- Resources that `extends tables.X` depend on `X` existing in the schema. A rename
+  or removal in the schema is a breaking change for every resource and verify path
+  that references it.
+
+## Project conventions
+
+- `schema.graphql` is **source** and lives at the component root that Fabric
+  packages (`harper-app/schema.graphql`). Keep it there.
+- A schema change is a data-model change. In the **same change**:
+  - Update the conceptual schema docs.
+  - Update any verify/smoke paths that assert joins, relationships, or row counts —
+    those assertions encode the data model and must track it.
+  - Update resources and seed/data-loader paths that reference changed tables.
+- Document deploy-affecting consequences (new tables, migrations) in the Fabric
+  runbook. See [[harper-build-and-deploy]].
+
+## Verification
+
+After a schema change, boot the app (`harper dev harper-app` or the project run
+command) and confirm tables migrate cleanly and the dependent endpoints respond.
+Run any verify path that asserts row counts or joins against the changed model.
+
+## Sources
+
+- [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
+- [Applications](https://docs.harperdb.io/docs/developers/applications)