@codyswann/lisa 2.195.4 → 2.195.6

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

@@ -0,0 +1,368 @@
+---
+name: harper-auth
+description: "adding or debugging Harper…"
+---
+
+# Harper Auth
+
+## Overview
+
+Harper uses role-based access control. Every user has one role, and that role
+decides which databases, tables, attributes, and operations the user can access.
+Use declarative `roles.yaml` for application-owned roles and the Operations API
+for environment-owned users, password changes, role audits, and token issuance.
+
+Cross-check extension wiring in [[harper-config-yaml]] before editing roles:
+custom `config.yaml` files replace Harper's default config, so `roles` must be
+re-declared alongside `rest`, `graphqlSchema`, and `jsResource` when the app needs
+all of them. Cross-check endpoint/resource behavior in [[harper-resources]] and
+query filters in [[harper-rest-queries]].
+
+## Role model
+
+Harper has built-in roles and custom roles:
+
+| Role type | Use it for | Notes |
+| --- | --- | --- |
+| `super_user` | Operators, deploy automation, emergency admin work | Full access to operations and data. Do not use for app clients. |
+| `structure_user` | Schema/database administration without full data access | Scope narrowly when used; normal app users usually should not need it. |
+| Custom role | Application clients, readers, editors, service accounts | Permissions are explicit. Missing database/table entries mean no access. |
+
+Prefer least-privilege custom roles for application traffic. A public read client,
+an editor/admin client, and a deploy/operator client should normally be separate
+users with separate roles.
+
+## Enable role files
+
+Keep roles in the component root, typically `harper-app/roles.yaml`, and enable
+the built-in `roles` extension in `harper-app/config.yaml`:
+
+```yaml
+rest: true
+graphqlSchema:
+  files: 'schema.graphql'
+roles:
+  files: 'roles.yaml'
+jsResource:
+  files: 'resources.js'
+```
+
+Because `config.yaml` is not merged with Harper's defaults, keep every extension
+the component needs in this file. Removing `roles` silently stops role-file
+reconciliation; removing `rest` or `jsResource` can make the secured endpoint
+disappear while the role still exists.
+
+## Declare roles in `roles.yaml`
+
+Use `roles.yaml` for roles that should be versioned with the app. On startup,
+Harper creates missing declared roles and updates existing declared roles to match
+the file.
+
+Example: public readers can read orders, but only admins can write:
+
+```yaml
+public_reader:
+  super_user: false
+  app:
+    Orders:
+      read: true
+      insert: false
+      update: false
+      delete: false
+      attributes:
+        id:
+          read: true
+        status:
+          read: true
+        publicTotal:
+          read: true
+
+order_admin:
+  super_user: false
+  app:
+    Orders:
+      read: true
+      insert: true
+      update: true
+      delete: false
+      attributes:
+        internalNotes:
+          read: true
+          insert: true
+          update: true
+```
+
+Rules:
+
+- Database keys such as `app` must match the database names in `schema.graphql`.
+- Table keys such as `Orders` must match the table type names, not necessarily the
+  exported REST path.
+- Table-level `read`, `insert`, `update`, and `delete` are the outer gate.
+- Attribute permissions narrow field-level access. They cannot grant a capability
+  that the table-level permission denies.
+- If a database or table is omitted from the role, that role has no access to it.
+
+Use role files for stable app permissions. Use Operations API calls when changing
+users, rotating credentials, or inspecting what the deployed system actually has.
+
+## Manage users and roles with Operations API
+
+User and role mutations require a `super_user` caller. Send JSON `POST` requests
+to the Operations API, usually port `9925` locally:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"operation":"list_roles"}'
+```
+
+Create a user for a declared role:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "operation": "add_user",
+    "username": "public-client",
+    "password": "replace-with-generated-secret",
+    "role": "public_reader",
+    "active": true
+  }'
+```
+
+Change a user's role or password:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "operation": "alter_user",
+    "username": "public-client",
+    "role": "order_admin",
+    "active": true
+  }'
+```
+
+Remove a user before removing a role:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"operation":"drop_user","username":"public-client"}'
+```
+
+Avoid committing real passwords, tokens, or generated secrets. For local examples,
+use environment variables or throwaway development credentials.
+
+## Basic auth and JWT operation tokens
+
+Harper accepts Basic auth for Operations API and secured REST calls:
+
+```bash
+curl -i http://localhost:9926/app/orders/ \
+  -u "$PUBLIC_USERNAME:$PUBLIC_PASSWORD"
+```
+
+For clients that should not send Basic auth on every request, create JWT tokens
+with `create_authentication_tokens`. This operation is intentionally unauthenticated
+but requires the target username and password:
+
+```bash
+tokens="$(
+  curl -sS http://localhost:9925/ \
+    -H 'Content-Type: application/json' \
+    --data '{
+      "operation": "create_authentication_tokens",
+      "username": "'"$PUBLIC_USERNAME"'",
+      "password": "'"$PUBLIC_PASSWORD"'"
+    }'
+)"
+
+operation_token="$(jq -r '.operation_token' <<<"$tokens")"
+refresh_token="$(jq -r '.refresh_token' <<<"$tokens")"
+```
+
+Use the operation token as a bearer token:
+
+```bash
+curl -i http://localhost:9926/app/orders/ \
+  -H "Authorization: Bearer $operation_token"
+```
+
+Refresh an expired operation token with the refresh token:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -H 'Content-Type: application/json' \
+  -H "Authorization: Bearer $refresh_token" \
+  --data '{"operation": "refresh_operation_token"}'
+```
+
+Treat operation tokens and refresh tokens as credentials. Never log them, commit
+them, paste them into tickets, or store them in browser-accessible app config.
+
+## Exported resources and `context.user`
+
+Exported tables and custom Resources inherit the caller's role permissions.
+If a role cannot read or write the underlying table, Harper should deny the REST
+or GraphQL request before app logic treats it as successful.
+
+Use custom Resource checks when the rule depends on request identity, tenant
+ownership, or business state that is not expressible in `roles.yaml`:
+
+```javascript
+export class Orders extends tables.Orders {
+  static async post(target, data, context) {
+    const user = context.user;
+    if (!user) {
+      const error = new Error('Authentication required');
+      error.statusCode = 401;
+      throw error;
+    }
+
+    if (user.role !== 'order_admin') {
+      const error = new Error('Forbidden');
+      error.statusCode = 403;
+      throw error;
+    }
+
+    return super.post(target, await data, context);
+  }
+}
+```
+
+Pass `context` through when delegating to tables or other resources:
+
+```javascript
+await tables.OrderEvents.post(
+  target,
+  {
+    orderId,
+    type: 'created',
+    createdBy: context.user?.username,
+  },
+  context,
+);
+```
+
+Guidance:
+
+- Use `roles.yaml` for coarse table/attribute access and Resource logic for
+  request-specific policy.
+- Do not trust client-provided role, user id, tenant id, or permission claims.
+  Read identity from `context.user`.
+- Do not put `context` in module-level state; it belongs to one request.
+- Do not use `requestWithoutAuthentication` for normal application routes. If a
+  webhook must bypass Harper auth, verify its signature first and keep its table
+  writes narrowly scoped.
+
+## Session cookies are `SameSite=None` — guard state-changing POSTs
+
+Harper hardcodes the session cookie's `SameSite=None` attribute on HTTPS. The
+browser therefore attaches the session cookie to **cross-site** requests, so a
+same-origin app cannot rely on `SameSite` to block CSRF on cookie-authenticated,
+state-changing routes (`POST`/`PUT`/`PATCH`/`DELETE`).
+
+Add an app-side origin check in the resource before mutating. Reject requests
+whose `Origin` (or `Referer` fallback) is not an allowed origin:
+
+```javascript
+const ALLOWED_ORIGINS = new Set([
+  'https://app.example.com',
+]);
+
+function requireSameOrigin(context) {
+  const headers = context.requestContext?.headers ?? context.headers;
+  const origin =
+    headers?.get?.('origin') ??
+    headers?.get?.('referer');
+  const ok =
+    typeof origin === 'string' &&
+    [...ALLOWED_ORIGINS].some((allowed) => origin.startsWith(allowed));
+  if (!ok) {
+    const error = new Error('Cross-origin request rejected');
+    error.statusCode = 403; // Harper reads statusCode, not status
+    throw error;
+  }
+}
+
+export class Watchlists extends tables.Watchlists {
+  static async post(target, data, context) {
+    requireSameOrigin(context);
+    // ...authorization and write
+    return super.post(target, await data, context);
+  }
+}
+```
+
+Guidance:
+
+- Call the check on every cookie-authenticated state-changing route. Read-only
+  `GET` handlers and token/`Authorization: Bearer` APIs (not cookie-driven) do
+  not need it.
+- Prefer an allowlist of exact origins over substring matching that a lookalike
+  host could satisfy.
+- This is defense the app owns; Harper will not add it for you.
+
+## Verification matrix
+
+Run the local app, create the test users, and check unauthenticated, reader, and
+admin behavior against the same endpoint:
+
+```bash
+harper dev harper-app
+
+# Unauthenticated request should be denied.
+curl -i http://localhost:9926/app/orders/
+
+# Reader can read.
+curl -i http://localhost:9926/app/orders/ \
+  -u "$PUBLIC_USERNAME:$PUBLIC_PASSWORD"
+
+# Reader cannot write.
+curl -i -X POST http://localhost:9926/app/orders/ \
+  -u "$PUBLIC_USERNAME:$PUBLIC_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"id":"ord_1","status":"new"}'
+
+# Admin can write.
+curl -i -X POST http://localhost:9926/app/orders/ \
+  -u "$ADMIN_USERNAME:$ADMIN_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"id":"ord_1","status":"new"}'
+```
+
+Expected results:
+
+| Caller | Read | Write |
+| --- | --- | --- |
+| No credentials | `401` or auth denial | `401` or auth denial |
+| `public_reader` | `200` | `403` or permission denial |
+| `order_admin` | `200` | `200` or expected validation response |
+
+Also verify metadata with a restricted user when debugging permissions:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$PUBLIC_USERNAME:$PUBLIC_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"operation":"user_info"}'
+```
+
+If the status code is unexpected, check in this order:
+
+1. `config.yaml` still enables `roles`, `rest`, `graphqlSchema`, and `jsResource`.
+2. `roles.yaml` database/table names match the schema.
+3. The user is active and assigned to the intended role.
+4. The route being tested is the exported table/resource path you meant to secure.
+5. Resource code passes `context` through to `super` and nested table calls.
+
+## Sources
+
+- [Users & Roles Configuration](https://docs.harperdb.io/reference/v5/users-and-roles/configuration)
+- [Operations Reference](https://docs.harperdb.io/reference/v5/operations-api/operations)
+- [Components Overview](https://docs.harperdb.io/reference/v5/components/overview)

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

@@ -0,0 +1,4 @@
+display_name: "Harper Auth"
+short_description: "adding or debugging Harper…"
+default_prompt:
+  - "Use $harper-auth: adding or debugging Harper…."

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

@@ -0,0 +1,198 @@
+---
+name: harper-build-and-deploy
+description: "building, running locally, or…"
+---
+
+# 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.
+
+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/*.js` — every compiled module the build emits to the harper-app
+  root (`resources.js`, `resource-*.js`, and any other output such as a route
+  negotiation module). The single-star does **not** cross a directory separator,
+  so it does not match hand-written shims one level down.
+- `harper-app/web/**`
+- `harper-app/lib/**`
+
+The guard surfaces (`generated-artifact-globs.txt` for the PreToolUse block hook,
+`.gitignore`, `.prettierignore`, the ESLint/oxlint/knip ignores, and
+`tsconfig.eslint.json`) all key off `harper-app/*.js` so a newly-named compiled
+module is protected automatically. **Name compiled resource modules
+`resource-*.ts`** so their JS output is unambiguously generated.
+
+If you keep a *hand-written* `.js` at the harper-app root (e.g. an SEO shell),
+the root-level rule would otherwise treat it as generated: re-include it with a
+`!harper-app/<file>.js` line below the managed gitignore block, and add it to
+`.lisa/harper-generated-artifact-allowlist.txt` so the block hook lets you edit
+it. Hand-written shims nested under `harper-app/<route>/index.js` need no
+exemption — the root-level rule never matches them.
+
+Every lint, format, dead-code, search, or generated-artifact guard must ignore
+generated paths unless it is explicitly validating the build output itself. When
+a new generated *directory* 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/`.
+
+## 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. Lisa ships a create-only GitHub
+Actions workflow at `.github/workflows/deploy.yml` for Harper/Fabric projects. Use
+that workflow as the canonical deployment path for repositories that have adopted
+the template: it builds the project, runs `harper deploy_component` against the
+configured Fabric target, and then runs the project's smoke verification script.
+
+Required GitHub secrets:
+
+- `CLI_TARGET` or `HARPER_FABRIC_TARGET` — Fabric target URL.
+- `CLI_TARGET_USERNAME` — deploy username.
+- `CLI_TARGET_PASSWORD` — deploy password.
+
+Optional GitHub variables:
+
+- `HARPER_PROJECT` — Fabric project name; defaults to the repository name.
+- `HARPER_PACKAGE` — package path; defaults to `harper-app`.
+
+For local debugging or one-off deploys, the equivalent CLI command 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` 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
+`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, run the create-only GitHub deploy workflow when
+   available, or manually run `harper deploy_component` plus the project **smoke
+   command** against the local or deployed Harper endpoint.
+5. For public HTTP surfaces, run the create-only ZAP baseline workflow or
+   `bash scripts/zap-baseline.sh` with `ZAP_TARGET_URL` set to the deployed app.
+
+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/.codex-plugin/skills/harper-build-and-deploy/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Harper Build And Deploy"
+short_description: "building, running locally, or…"
+default_prompt:
+  - "Use $harper-build-and-deploy: building, running locally, or…."