@harperfast/template-react-ts-ssr-studio 1.13.3 → 1.13.5

package/.agents/skills/harper-best-practices/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: harper-best-practices
-description: Best practices for building Harper applications, covering schema definition,
-  automatic APIs, authentication, custom resources, and data handling.
-  Triggers on tasks involving Harper database design, API implementation,
-  and deployment.
+description: How to implement a specific Harper feature correctly, with one rule per feature
+  (tables and schemas, relationships, automatic REST and WebSocket APIs, extending tables,
+  custom resources, caching, real-time, auth, blobs, vector indexes, static and Vite web serving,
+  logging, env loading, and deploying to Harper Fabric). Use when building or changing one of
+  these features. For deciding which services an app needs, read harper-architecture first.
 license: Apache-2.0
 metadata:
   author: harper
@@ -12,6 +13,8 @@ metadata:
 
 # Harper Best Practices
 
+> Deciding what to build or which services an app needs? Read the `harper-architecture` skill first. This skill covers how to implement each Harper feature once that decision is made.
+
 Guidelines for building scalable, secure, and performant applications on Harper. These practices cover everything from initial schema design to advanced deployment strategies.
 
 ## When to Use
@@ -53,37 +56,37 @@ See the concrete examples embedded in each rule subsection below (GraphQL schema
 
 ### 1. Schema & Data Design (HIGH)
 
-- `adding-tables-with-schemas` — Guidelines for adding tables to a Harper database using GraphQL schemas.
+- `adding-tables-with-schemas` — Guidelines for adding tables to a Harper database using GraphQL schemas. (instead of: Postgres, MySQL, MongoDB, DynamoDB, Supabase, Firebase)
 - `schema-design-tooling` — Best practices for Harper schema design, including core directives and GraphQL tooling configuration.
-- `defining-relationships` — How to define and use relationships between tables in Harper using GraphQL.
-- `vector-indexing` — How to enable and query vector indexes for similarity search in Harper.
-- `using-blob-datatype` — How to use the Blob data type for efficient binary storage in Harper.
-- `handling-binary-data` — How to store and serve binary data like images or audio in Harper.
+- `defining-relationships` — How to define and use relationships between tables in Harper using GraphQL. (instead of: ORM relations and join tables (Prisma, Drizzle, Sequelize))
+- `vector-indexing` — How to enable and query vector indexes for similarity search in Harper. (instead of: Pinecone, Weaviate, pgvector)
+- `using-blob-datatype` — How to use the Blob data type for efficient binary storage in Harper. (instead of: S3 or GCS buckets for app-managed files)
+- `handling-binary-data` — How to store and serve binary data like images or audio in Harper. (instead of: S3 or GCS buckets for app-managed files)
 
 ### 2. API & Communication (HIGH)
 
-- `automatic-apis` — How to use Harper's automatically generated REST and WebSocket APIs.
+- `automatic-apis` — How to use Harper's automatically generated REST and WebSocket APIs. (instead of: Hand-written CRUD routes (Express, Fastify, Next.js API routes))
 - `querying-rest-apis` — How to use query parameters to filter, sort, and paginate Harper REST APIs.
-- `real-time-apps` — How to build real-time features in Harper using WebSockets and Pub/Sub.
-- `checking-authentication` — How to handle user authentication and sessions in Harper Resources.
+- `real-time-apps` — How to build real-time features in Harper using WebSockets and Pub/Sub. (instead of: Socket.io, `ws`, Pusher, Ably, Redis pub/sub, a separate MQTT broker)
+- `checking-authentication` — How to handle user authentication and sessions in Harper Resources. (instead of: Hand-rolled sessions, `passport`, `jsonwebtoken`, `bcrypt`)
 
 ### 3. Logic & Extension (MEDIUM)
 
-- `custom-resources` — How to define custom REST endpoints with JavaScript or TypeScript in Harper.
-- `extending-tables` — How to add custom logic to automatically generated table resources in Harper.
-- `programmatic-table-requests` — How to interact with Harper tables programmatically using the `tables` object.
-- `typescript-type-stripping` — How to run TypeScript files directly in Harper without a build step.
-- `caching` — How to implement integrated data caching in Harper from external sources.
+- `custom-resources` — How to define custom REST endpoints with JavaScript or TypeScript in Harper. (instead of: Express, Fastify, or Koa route handlers; serverless functions)
+- `extending-tables` — How to add custom logic to automatically generated table resources in Harper. (instead of: Middleware and controllers wrapped around CRUD routes)
+- `programmatic-table-requests` — How to interact with Harper tables programmatically using the `tables` object. (instead of: ORM and query-builder clients (Prisma, Drizzle, Knex))
+- `typescript-type-stripping` — How to run TypeScript files directly in Harper without a build step. (instead of: `tsc` or `ts-node` build steps for server code)
+- `caching` — How to implement integrated data caching in Harper from external sources. (instead of: Redis or Memcached cache-aside layers)
 
 ### 4. Infrastructure & Ops (MEDIUM)
 
-- `deploying-to-harper-fabric` — How to deploy a Harper application to Harper Fabric with the CLI, check that the release was certified, and roll back by activating a previous release's `deployment_id`.
+- `deploying-to-harper-fabric` — How to deploy a Harper application to Harper Fabric with the CLI, check that the release was certified, and roll back by activating a previous release's `deployment_id`. (instead of: Docker Compose stacks; deploying several services separately)
 - `deploying-from-ci` — How to deploy a Harper application from GitHub Actions with OIDC trusted publishing, so CI stores no Harper credential, including the one-command setup with `harper deploy setup=true provider=github-actions`.
 - `creating-a-fabric-account-and-cluster` — How to create a Harper Fabric account, organization, and cluster.
 - `creating-harper-apps` — How to initialize a new Harper application using the CLI.
-- `serving-web-content` — How to serve static files and integrated Vite/React applications in Harper.
-- `logging` — Best practices for logging in Harper, including console capture, the granular logger interface, and programmatic log retrieval.
-- `load-env` — How to load environment variables from .env files into a Harper application using the loadEnv plugin.
+- `serving-web-content` — How to serve static files and integrated Vite/React applications in Harper. (instead of: Nginx, Vercel, or Netlify for the frontend; a separate Vite dev server)
+- `logging` — Best practices for logging in Harper, including console capture, the granular logger interface, and programmatic log retrieval. (instead of: Separate log shippers for app logs (pino or winston transports))
+- `load-env` — How to load environment variables from .env files into a Harper application using the loadEnv plugin. (instead of: `dotenv`)
 - `v5-upgrade` — Breaking changes and recommended updates when migrating a Harper application to v5.
 - `delegating-to-the-built-in-agent` — How to delegate tasks to Harper's built-in agent via the CLI and the agent operations API.
 

package/.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md

@@ -9,6 +9,8 @@ metadata:
 
 Instructions for the agent to follow when adding tables to a Harper database.
 
+**Instead of:** Postgres, MySQL, MongoDB, DynamoDB, Supabase, Firebase. Use this rule rather than adding that service. See `harper-architecture`.
+
 ## When to Use
 
 Use this skill when you need to define new data structures or modify existing ones in a Harper database.

package/.agents/skills/harper-best-practices/rules/automatic-apis.md

@@ -20,6 +20,8 @@ metadata:
 
 Instructions for the agent to follow when using Harper's automatically generated REST and WebSocket APIs for exported tables and resources.
 
+**Instead of:** Hand-written CRUD routes (Express, Fastify, Next.js API routes). Use this rule rather than adding that service. See `harper-architecture`.
+
 ## When to Use
 
 Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for Harper tables and custom resources. Use it whenever you need to configure the REST plugin, understand the auto-generated endpoint surface, or wire up real-time WebSocket connections. See [querying-rest-apis.md](querying-rest-apis.md) for query syntax and [real-time-apps.md](real-time-apps.md) for real-time patterns.

package/.agents/skills/harper-best-practices/rules/caching.md

@@ -13,6 +13,8 @@ metadata:
 
 Instructions for the agent to implement integrated data caching from external sources using Harper's cache table directives and `sourcedFrom` API.
 
+**Instead of:** Redis or Memcached cache-aside layers. Use this rule rather than adding that service. See `harper-architecture`.
+
 ## When to Use
 
 Apply this rule when an application needs to wrap an external API, microservice, or database with a fast local cache. Use it when you need to define TTL-based cache expiration, connect an upstream data source to a Harper table, or implement on-demand cache invalidation.

package/.agents/skills/harper-best-practices/rules/checking-authentication.md

@@ -27,6 +27,8 @@ metadata:
 
 Instructions for the agent to handle user authentication, sessions, and JWT token issuance in Harper Resources.
 
+**Instead of:** Hand-rolled sessions, `passport`, `jsonwebtoken`, `bcrypt`. Use this rule rather than adding that service. See `harper-architecture`.
+
 ## When to Use
 
 Apply this rule when implementing login/logout flows, reading the current authenticated user, issuing or refreshing JWT tokens, or minting scoped tokens from a custom Resource. Use it whenever a Resource must gate behavior on identity or credentials. See [custom-resources.md](custom-resources.md) for the broader Resource authoring model.

package/.agents/skills/harper-best-practices/rules/custom-resources.md

@@ -15,6 +15,8 @@ metadata:
 
 Instructions for the agent to follow when defining custom REST endpoints with JavaScript or TypeScript in Harper.
 
+**Instead of:** Express, Fastify, or Koa route handlers; serverless functions. Use this rule rather than adding that service. See `harper-architecture`.
+
 ## When to Use
 
 Apply this rule when you need to create custom HTTP endpoints, wrap external APIs, or register routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed schema, or when you need fine-grained control over URL shape and path parameters.

package/.agents/skills/harper-best-practices/rules/defining-relationships.md

@@ -6,21 +6,23 @@ metadata:
   sources:
     - reference/v5/database/schema.md#Relationships
     - reference/v5/rest/querying.md#Relationships and Joins
-  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
-  inputHash: fd399fd81a88f13e
+  sourceCommit: bea4e62cb7efd809bb67e00cbda01a410c1177b1
+  inputHash: 58ffc789fa71ffe6
 ---
 
 # Defining Relationships Between Tables in Harper
 
-Instructions for the agent to follow when defining and querying relationships between tables in Harper using the `@relationship` directive.
+Instructions for the agent to define and query relationships between Harper tables using the `@relationship` directive in GraphQL schemas.
+
+**Instead of:** ORM relations and join tables (Prisma, Drizzle, Sequelize). Use this rule rather than adding that service. See `harper-architecture`.
 
 ## When to Use
 
-Apply this rule when adding foreign key relationships between schema tables, enabling join queries, or returning nested related records in query results. Use it any time a schema type needs to reference records in another table via a foreign key attribute.
+Apply this rule when writing Harper schemas that require join queries across tables, or when query results must include related records as nested properties. Use it whenever a foreign key exists in one table that references another, or when modeling one-to-many, many-to-one, or many-to-many associations.
 
 ## How It Works
 
-1. **Use `@relationship(from: attribute)` for many-to-one or many-to-many**: Place this on the field in the table that holds the foreign key. The `from` parameter names the attribute on this table that stores the foreign key referencing the target table's primary key.
+1. **Declare a many-to-one relationship with `from`**: Place `@relationship(from: attribute)` on a field when the foreign key lives in the current table and references the primary key of the target table. The result type is a single object.
 
    ```graphql
    type RealityShow @table @export {
@@ -36,17 +38,7 @@ Apply this rule when adding foreign key relationships between schema tables, ena
    }
    ```
 
-   If the foreign key attribute is an array, the relationship becomes many-to-many:
-
-   ```graphql
-   type RealityShow @table @export {
-   	id: Long @primaryKey
-   	networkIds: [Long] @indexed
-   	networks: [Network] @relationship(from: networkIds)
-   }
-   ```
-
-2. **Use `@relationship(to: attribute)` for one-to-many or many-to-many**: Place this on the table whose primary key is referenced by the foreign key in the target table. The `to` parameter names the attribute on the target table that holds the foreign key. The result type **must** be an array.
+2. **Declare a one-to-many relationship with `to`**: Place `@relationship(to: attribute)` on a field when the foreign key lives in the target table and references the primary key of the current table. The result type **must** be an array.
 
    ```graphql
    type Network @table @export {
@@ -56,14 +48,14 @@ Apply this rule when adding foreign key relationships between schema tables, ena
    }
    ```
 
-3. **Use `@relationship(from: attribute, to: attribute)` for foreign key to foreign key joins**: Specify both `from` and `to` when neither side uses the primary key. Harper resolves the relationship by searching the target table's `to` attribute for matches using this record's `from` attribute value. The result type must be an array.
+3. **Declare a foreign-key-to-foreign-key relationship with `@relationship(from: attribute, to: attribute)`**: Specify both `from` and `to` when neither side uses the primary key. Harper resolves the relationship by searching the target table's `to` attribute for matches using the current record's `from` attribute value. The result type must be an array.
 
    ```graphql
    type OrderItem @table @export {
    	id: Long @primaryKey
    	orderId: Long @indexed
    	productSku: Long @indexed
-   	products: [Product] @relationship(from: productSku, to: sku)
+   	products: [Product] @relationship(from: productSku, to: sku) # matches products by sku, not primary key
    }
 
    type Product @table @export {
@@ -73,14 +65,25 @@ Apply this rule when adding foreign key relationships between schema tables, ena
    }
    ```
 
-4. **Query across relationships using dot-syntax**: Filter records by related table attributes using chained dot notation. This behaves as an INNER JOIN — only records with a matching related record are returned.
+4. **Declare a many-to-many relationship using an array foreign key with `from`**: When the foreign key field is an array, `@relationship(from: attribute)` establishes a many-to-many relationship. The result type must be an array.
+
+   ```graphql
+   type RealityShow @table @export {
+   	id: Long @primaryKey
+   	networkIds: [Long] @indexed
+   	networks: [Network] @relationship(from: networkIds)
+   }
+   ```
+
+5. **Query across relationships using dot-syntax**: Filter records by related table attributes using dot-chained attribute names. This behaves as an INNER JOIN — only parents with a qualifying related record are returned.
 
    ```
+   GET /RealityShow?network.name=Bravo
    GET /Product/?brand.name=Microsoft
    GET /Brand/?products.name=Keyboard
    ```
 
-5. **Include relationship fields in results using `select()`**: Relationship attributes are not returned by default. Use `select()` to include them, optionally specifying nested fields with `{}`.
+6. **Include relationship fields in results using `select()`**: Relationship attributes are not included by default. Use `select()` to project them, optionally with a nested field list using `{}`.
 
    ```
    GET /Product/?brand.name=Microsoft&select(name,brand)
@@ -88,24 +91,27 @@ Apply this rule when adding foreign key relationships between schema tables, ena
    GET /Product/?name=Keyboard&select(name,brand{name,id})
    ```
 
-   When selecting a relationship without filtering on it, Harper performs a LEFT JOIN — the relationship property is omitted if the foreign key is null or references a non-existent record.
+   Selecting a relationship without an outer dot-syntax filter on it behaves as a LEFT JOIN: parents remain even when there are no related records.
 
-6. **Model many-to-many without a junction table**: Store an array of foreign key values and use `@relationship(from: ...)` pointing to that array attribute. The array order of the foreign key values is preserved when resolving the relationship.
+7. **Filter and page nested relationship results using `[]` inside `select()`**: Apply conditions, sort, and pagination to each parent's related records by placing them inside square brackets in the `select()` expression.
 
-   ```graphql
-   type Product @table @export {
-   	id: Long @primaryKey
-   	name: String
-   	resellerIds: [Long] @indexed
-   	resellers: [Reseller] @relationship(from: "resellerIds")
-   }
    ```
+   GET /Brand/?select(id,name,products[price=ge=number:30&sort(price)&limit(1)&select(id,name,price)])
+   ```
+
+   An outer relationship filter (e.g., `products.price=ge=number:30`) removes parents without a qualifying child **and** narrows the nested candidates. A filter inside `products[...]` only narrows projected children without removing their parent.
 
-7. **Define self-referential relationships** for parent-child hierarchies by pointing `@relationship` back at the same table type.
+   | Nested option      | Behavior                                                                   |
+   | ------------------ | -------------------------------------------------------------------------- |
+   | Conditions         | Qualify children; combine with `&` (AND), `\|` (OR), and groups.           |
+   | `sort(price)`      | Order eligible children before pagination.                                 |
+   | `limit(end)`       | Return at most `end` children per parent.                                  |
+   | `limit(start,end)` | Skip `start` eligible children and return at most `end - start`.           |
+   | `select(id,price)` | Project fields from returned children; omit to return whole child records. |
 
 ## Examples
 
-**Full schema with bidirectional relationships:**
+### Schema with bidirectional relationships
 
 ```graphql
 type Product @table @export {
@@ -122,22 +128,78 @@ type Brand @table @export {
 }
 ```
 
-**Querying with joins and nested select:**
+### Many-to-many without a junction table
+
+```graphql
+type Product @table @export {
+	id: Long @primaryKey
+	name: String
+	resellerIds: [Long] @indexed
+	resellers: [Reseller] @relationship(from: "resellerIds")
+}
+```
+
+```
+GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
+```
+
+The array order of `resellerIds` is preserved when resolving the relationship.
+
+### Nested filtering and pagination scenarios
+
+Schema for the following examples:
+
+```graphql
+type Brand @table @export {
+	id: Int @primaryKey
+	name: String @indexed
+	products: [Product] @relationship(to: "brandId")
+}
+
+type Product @table @export {
+	id: ID @primaryKey
+	brandId: Int @indexed
+	name: String
+	price: Int @indexed
+}
+```
+
+**Keep every brand; show its cheapest product costing at least 30** (LEFT JOIN behavior — Budget Basics returns with an empty product list):
 
 ```
-GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
-GET /Brand/?products.name=Keyboard
+GET /Brand/?select(id,name,products[price=ge=number:30&sort(price)&limit(1)&select(id,name,price)])
 ```
 
-**Many-to-many query with nested select:**
+**Return only qualifying brands; inherit the outer price filter** (INNER JOIN behavior — Budget Basics is removed):
 
 ```
-GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
+GET /Brand/?products.price=ge=number:30&select(id,name,products[sort(price)&limit(1)&select(id,name,price)])
+```
+
+**Page through each brand's qualifying products** (offset applies independently per brand):
+
+```
+GET /Brand/?products.price=ge=number:30&select(id,name,products[sort(price)&limit(1,2)&select(id,name,price)])
+```
+
+**Bound parent pages with stable sorting**:
+
+```
+GET /Brand/?products.price=ge=number:30&sort(name,id)&limit(0,20)&select(id,name,products[sort(price,id)&limit(1)&select(id,name,price)])
+```
+
+**Combine OR filters with child sorting and pagination**:
+
+```
+GET /Brand/?sort(name,id)&limit(0,20)&select(id,name,products[[price=lt=number:30|price=ge=number:60]&sort(-price,id)&limit(1,2)&select(id,name,price)])
 ```
 
 ## Notes
 
-- Every attribute named in `from` or `to` must exist on the respective table and be annotated with `@indexed` to support join queries.
-- The `to`-only and `from`+`to` forms both require the result field type to be an array (e.g., `[RealityShow]`).
-- The `from`-only form on a non-array attribute produces a many-to-one relationship; on an array attribute it produces many-to-many.
-- Self-referential relationships are supported for hierarchical data within a single table.
+- Index all foreign key fields (e.g., `brandId`, `price`) and outer filter fields to support efficient join queries.
+- Use a unique field as the final sort key (e.g., `sort(price,id)`) to ensure deterministic ordering when values are equal.
+- A nested `limit()` bounds children per parent, not the number of parents. Apply a separate outer `limit()` to bound the parent result set.
+- Nested filters require a table-backed relationship. Filters on plain JSON projections or full-text predicates inside a relationship selection return HTTP 400.
+- Invalid `limit()` bounds (negative or fractional values) return HTTP 400. `limit(0)` returns no children without reading them.
+- A condition traversing another relationship qualifies the immediate child only; it does not narrow that child's projected descendants. Place grandchild constraints in the grandchild's own bracket selection.
+- Schemas can define self-referential relationships to enable parent-child hierarchies within a single table.