@harperfast/template-vue-ts-studio 1.9.2 → 1.10.1

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

@@ -5,21 +5,21 @@ metadata:
   mode: generate
   sources:
     - learn/developers/caching-with-harper.md
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: 8212a7d7dbbd2b18
+  sourceCommit: 4fe4c9c95e0974eaa77032f6f10e36fbd8ec64ac
+  inputHash: 60ad55fa37b5eec5
 ---
 
 # Caching External Data Sources in Harper
 
-Instructions for the agent to implement integrated data caching in Harper by wrapping external sources with a cache table and `sourcedFrom`.
+Instructions for the agent to implement integrated data caching from external sources using Harper's cache table directives and `sourcedFrom` API.
 
 ## When to Use
 
-Apply this rule when a Harper application needs to cache responses from an external API, microservice, or database to avoid repeated slow or expensive upstream calls. Use it whenever you need to define TTL-based cache expiration, observe ETag-based conditional responses, or manually invalidate cached entries.
+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.
 
 ## How It Works
 
-1. **Define a cache table with `expiration`**: In `schema.graphql`, add the `expiration` argument to `@table`. The value is in seconds. Any record older than this threshold is considered stale and will be re-fetched on next access.
+1. **Define a cache table with `expiration`**: Add the `expiration` argument to the `@table` directive in `schema.graphql`. The value is in seconds. When a record becomes stale, the next request fetches a fresh copy from the upstream source.
 
    ```graphql
    type JokeCache @table(expiration: 60) @export {
@@ -29,7 +29,7 @@ Apply this rule when a Harper application needs to cache responses from an exter
    }
    ```
 
-2. **Wrap the external source in `resources.js`**: Create an object with a `get(id)` method that fetches from the upstream source. Then call `sourcedFrom` on the table to register it.
+2. **Implement an upstream source object**: In `resources.js`, create an object with a `get(id)` method that fetches data from the external API.
 
    ```javascript
    const jokeAPI = {
@@ -38,18 +38,22 @@ Apply this rule when a Harper application needs to cache responses from an exter
    		return response.json();
    	},
    };
+   ```
+
+3. **Connect the source with `sourcedFrom`**: Call `sourcedFrom` on the table to register the upstream source. Harper will call `jokeAPI.get()` automatically when a record is missing or stale.
 
+   ```javascript
    tables.JokeCache.sourcedFrom(jokeAPI);
    ```
 
-   Harper's caching behavior after `sourcedFrom` is registered:
-   - A request arrives for `/JokeCache/1`.
-   - Harper checks if the record with id `1` exists in `JokeCache` and is not stale.
+   Harper's request flow after `sourcedFrom` is registered:
+   - Request arrives for `/JokeCache/1`.
+   - Harper checks if the record exists and is not stale.
    - If fresh, Harper returns it immediately.
    - If missing or stale, Harper calls `jokeAPI.get()`, stores the result in `JokeCache`, and returns it.
    - Multiple simultaneous requests for the same missing or stale record wait on a single upstream call — Harper prevents cache stampedes automatically.
 
-3. **Configure plugins in `config.yaml`**: Enable the schema, REST API, and JS resource plugins.
+4. **Configure plugins in `config.yaml`**: Enable `graphqlSchema`, `rest`, and `jsResource`.
 
    ```yaml
    graphqlSchema:
@@ -59,29 +63,7 @@ Apply this rule when a Harper application needs to cache responses from an exter
      files: 'resources.js'
    ```
 
-4. **Observe caching via ETags**: Harper automatically computes an ETag from the record's last-modified timestamp. On the first request you receive a `200` with an `etag` header. Pass that value back in `If-None-Match` on subsequent requests; Harper returns `304 Not Modified` with an empty body if the record is unchanged.
-
-   ```bash
-   curl -i 'http://localhost:9926/JokeCache/1' \
-     -H 'If-None-Match: "abCDefGHij"'
-   ```
-
-5. **Force a cache bypass**: Send `Cache-Control: no-cache` to make Harper skip the local cache and always call the upstream source, regardless of TTL.
-
-   ```bash
-   curl -i 'http://localhost:9926/JokeCache/1' \
-     -H 'Cache-Control: no-cache'
-   ```
-
-6. **Invalidate a cache entry on demand**: Remove `@export` from the schema type, then export a class of the same name in `resources.js` that extends the table and implements a `post` handler calling `this.invalidate(target)`.
-
-   ```graphql
-   type JokeCache @table(expiration: 60) {
-   	id: ID @primaryKey
-   	setup: String
-   	punchline: String
-   }
-   ```
+5. **Implement on-demand invalidation**: To invalidate a cache entry before its TTL expires, export a class extending the table and call `this.invalidate(target)` in a `post` handler. Remove `@export` from the schema when using this pattern — the exported class provides the endpoint.
 
    ```javascript
    export class JokeCache extends tables.JokeCache {
@@ -95,34 +77,25 @@ Apply this rule when a Harper application needs to cache responses from an exter
    }
    ```
 
-   Trigger invalidation with a `POST`:
+   Update the schema to remove `@export`:
 
-   ```bash
-   curl -X POST 'http://localhost:9926/JokeCache/1' \
-     -H 'Content-Type: application/json' \
-     -d '{"action": "invalidate"}'
+   ```graphql
+   type JokeCache @table(expiration: 60) {
+   	id: ID @primaryKey
+   	setup: String
+   	punchline: String
+   }
    ```
 
-   The next `GET /JokeCache/1` will fetch fresh data from the upstream source regardless of TTL.
-
 ## Examples
 
-Complete `schema.graphql` and `resources.js` for a cached external API with on-demand invalidation:
-
-```graphql
-type JokeCache @table(expiration: 60) {
-	id: ID @primaryKey
-	setup: String
-	punchline: String
-}
-```
+**Complete `resources.js`**:
 
 ```javascript
 // resources.js
 
 const jokeAPI = {
-	async get() {
-		const id = this.getId();
+	async get(id) {
 		const response = await fetch(`https://official-joke-api.appspot.com/jokes/${id}`);
 		return response.json();
 	},
@@ -141,23 +114,56 @@ export class JokeCache extends tables.JokeCache {
 }
 ```
 
-First request — cache miss, upstream is called, `200` returned:
+**Complete `schema.graphql`**:
 
-```bash
-curl -i 'http://localhost:9926/JokeCache/1'
+```graphql
+type JokeCache @table(expiration: 60) {
+	id: ID @primaryKey
+	setup: String
+	punchline: String
+}
 ```
 
-Second request with ETag — cache hit, `304 Not Modified`:
+**Fetch a cached record**:
 
-```bash
-curl -i 'http://localhost:9926/JokeCache/1' \
-  -H 'If-None-Match: "abCDefGHij"'
+```javascript
+const response = await fetch('http://localhost:9926/JokeCache/1');
+console.log(response.status); // 200
+const etag = response.headers.get('etag'); // e.g. "abCDefGHij"
+const joke = await response.json();
+```
+
+**Use ETag for conditional requests** (returns `304 Not Modified` if unchanged):
+
+```javascript
+const second = await fetch('http://localhost:9926/JokeCache/1', {
+	headers: { 'If-None-Match': etag },
+});
+console.log(second.status); // 304
+```
+
+**Bypass the cache with `Cache-Control: no-cache`**:
+
+```javascript
+const response = await fetch('http://localhost:9926/JokeCache/1', {
+	headers: { 'Cache-Control': 'no-cache' },
+});
+```
+
+**Trigger invalidation via POST**:
+
+```javascript
+await fetch('http://localhost:9926/JokeCache/1', {
+	method: 'POST',
+	headers: { 'Content-Type': 'application/json' },
+	body: JSON.stringify({ action: 'invalidate' }),
+});
 ```
 
 ## Notes
 
 - `expiration` is measured in seconds. Harper also supports separate `eviction` and `scanInterval` arguments on `@table` for fine-grained control over physical record removal.
-- The `@export` directive on the schema type is not required when you export a Resource class of the same name from `resources.js` — the class export serves as the endpoint registration. See [custom-resources.md](custom-resources.md) for details on building Resource classes.
-- Harper's REST layer automatically exposes `@export`-ed tables and Resource classes as HTTP endpoints. See [automatic-apis.md](automatic-apis.md) for how endpoints are structured and named.
-- ETag values include their double quotes as part of the value — include them verbatim when passing the value in `If-None-Match`.
-- `sourcedFrom` must be called after the table reference (`tables.JokeCache`) is available, which is guaranteed when the call is at the top level of `resources.js`.
+- ETags are automatically computed from a record's last-modified timestamp. Include the double quotes when passing an ETag back in `If-None-Match` — they are part of the value.
+- Exporting a class with the same name as a table (e.g., `export class JokeCache extends tables.JokeCache`) registers it as the HTTP endpoint for that table; `@export` in the schema is not required separately.
+- For defining custom upstream source behavior beyond a simple `get`, see [custom-resources.md](custom-resources.md).
+- For details on how `@table` and `@export` expose REST endpoints automatically, see [automatic-apis.md](automatic-apis.md).

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

@@ -2,43 +2,164 @@
 name: custom-resources
 description: How to define custom REST endpoints with JavaScript or TypeScript in Harper.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - reference/v5/resources/overview.md#Custom External Data Source
+    - reference/v5/resources/overview.md#Exporting Resources as Endpoints
+    - reference/v5/components/javascript-environment.md#Module Loading
+  sourceCommit: f37a8c4021e20d5c74c1d339a6b6c8c196b5603e
+  inputHash: df69870433c0b3e5
 ---
 
 # Custom Resources
 
-Instructions for the agent to follow when creating custom resources in Harper.
+Instructions for the agent to follow when defining custom REST endpoints with JavaScript or TypeScript in Harper.
 
 ## When to Use
 
-Use this skill when the automatic CRUD operations provided by `@table @export` are insufficient, and you need custom logic, third-party API integration, or specialized data handling for your REST endpoints.
+Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or registering routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed schema, or when a specific URL shape is required.
 
 ## How It Works
 
-1. **Check if a Custom Resource is Necessary**: Verify if [Automatic APIs](./automatic-apis.md) or [Extending Tables](./extending-tables.md) can satisfy the requirement first.
-2. **Create the Resource File**: Create a `.ts` or `.js` file in the directory specified by `jsResource` in `config.yaml` (typically `resources/`).
-3. **Define the Resource Class**: Export a class extending `Resource` from `harper` and define **static** methods for the HTTP verbs you handle. In Harper 5 the static methods are the HTTP handlers (mapped 1:1 to verbs); they receive a pre-parsed `RequestTarget`, and write handlers also receive the request body as an awaitable `data` argument:
+1. **Import `Resource` from `harper`**: Always import from the `harper` package rather than relying on globals.
 
-   ```typescript
-   import { Resource } from 'harper';
+   ```javascript
+   import { tables, Resource } from 'harper';
+   ```
+
+2. **Define a class that `extends Resource`**: Implement HTTP methods as `static` methods. Each method receives a `target` object.
+
+   ```javascript
+   export class CustomEndpoint extends Resource {
+   	static get(target) {
+   		return {
+   			data: doSomething(),
+   		};
+   	}
+   }
+   ```
+
+3. **Use `async` static methods for external calls**: Await fetch or other async operations inside `static` handlers.
 
-   export class MyResource extends Resource {
-   	// v5 handlers are static and map 1:1 to HTTP verbs.
-   	static async get(target: any) {
-   		return { message: 'Hello from custom GET!' };
+   ```javascript
+   export class MyExternalData extends Resource {
+   	static async get(target) {
+   		const response = await fetch(`https://api.example.com/${target.id}`);
+   		return response.json();
+   	}
+
+   	static async put(target, data) {
+   		return fetch(`https://api.example.com/${target.id}`, {
+   			method: 'PUT',
+   			body: JSON.stringify(await data),
+   		});
    	}
    }
    ```
 
-4. **Implement HTTP Methods**: Add static methods (`get`, `post`, `put`, `patch`, or `delete`) to handle the corresponding requests. Read/delete handlers receive `(target)`; write handlers receive `(target, data)` where `data` is awaitable.
-5. **Route Nesting and Naming**: You can control the URL structure by how you export your resources:
-   - **Direct Class Export**: `export class Foo extends Resource` creates endpoints at `/Foo/`. Class names are case-sensitive in the URL.
-   - **Nested Objects**: `export const Bar = { Foo };` creates endpoints at `/Bar/Foo/`.
-   - **Lowercase and Hyphens**: Use object keys to define custom paths: `export const bar = { 'foo-baz': Foo };` exposes endpoints at `/bar/foo-baz/`.
-6. **Access Tables (Optional)**: Import and use the `tables` object to interact with your data:
-   ```typescript
-   import { tables } from 'harper';
-   // ... inside a method
-   const results = await tables.MyTable.list();
+4. **Export the class to create an endpoint**: The export form controls the resulting URL. Choose the form that matches the URL shape you need.
+
+   | Export form                                 | URL             | Notes                                                           |
+   | ------------------------------------------- | --------------- | --------------------------------------------------------------- |
+   | `export class Foo extends Resource {}`      | `/Foo/`         | Class name becomes the path segment. Case-sensitive.            |
+   | `export const Bar = { Foo };`               | `/Bar/Foo/`     | Nest under an object to add a path prefix.                      |
+   | `export const bar = { 'foo-baz': Foo };`    | `/bar/foo-baz/` | Use object keys for lowercase, hyphens, or non-identifier URLs. |
+   | `export { Foo as '/widget/:id' }`           | `/widget/:id`   | Rename the export to set the path directly.                     |
+   | `static path = '/widget/:id'` (class field) | `/widget/:id`   | Declare path on the class; overrides the export name.           |
+   | `server.resources.set('my-path', Foo);`     | `/my-path/`     | Programmatic registration for dynamic paths.                    |
+
+   URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
+
+5. **Declare path parameters with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
+
+   ```javascript
+   export class Widget extends Resource {
+   	static path = '/widget/:id/action/:action';
+   	static get(target) {
+   		return { id: target.id, action: target.action };
+   	}
+   }
+   ```
+
+   A `static path` takes precedence over the export name. A leading `/` makes the path root-relative (top-level). A leading `./` or bare name resolves relative to the component directory.
+
+6. **Register programmatically when the path is dynamic**: Use `server.resources.set(` when the path cannot be known at export time.
+
+   ```javascript
+   server.resources.set('my-path', Foo);
    ```
-7. **Configure Loading**: Ensure `config.yaml` points to your resource files (e.g., `jsResource: { files: 'resources/*.ts' }`).
+
+7. **Optionally source a table from a custom resource**: Use the resource as a caching layer for a local table.
+   ```javascript
+   tables.MyCache.sourcedFrom(MyExternalData);
+   ```
+
+## Examples
+
+### External API wrapper with GET and PUT
+
+```javascript
+import { tables, Resource } from 'harper';
+
+export class MyExternalData extends Resource {
+	static async get(target) {
+		const response = await fetch(`https://api.example.com/${target.id}`);
+		return response.json();
+	}
+
+	static async put(target, data) {
+		return fetch(`https://api.example.com/${target.id}`, {
+			method: 'PUT',
+			body: JSON.stringify(await data),
+		});
+	}
+}
+
+// Use as a cache source for a local table
+tables.MyCache.sourcedFrom(MyExternalData);
+```
+
+### Path parameters with `static path`
+
+```javascript
+import { Resource } from 'harper';
+
+export class Widget extends Resource {
+	// GET /widget/10/action/jump  ->  target.id === '10', target.action === 'jump'
+	static path = '/widget/:id/action/:action';
+	static get(target) {
+		return { id: target.id, action: target.action };
+	}
+}
+
+export class Files extends Resource {
+	// GET /files/a/b/c.txt  ->  target.rest === 'a/b/c.txt'
+	static path = '/files/*rest';
+	static get(target) {
+		return { path: target.rest };
+	}
+}
+```
+
+### Programmatic registration
+
+```javascript
+import { Resource } from 'harper';
+
+export class Foo extends Resource {
+	static get(target) {
+		return { data: doSomething() };
+	}
+}
+
+server.resources.set('my-path', Foo);
+```
+
+## Notes
+
+- A bare `*` wildcard (no name) binds under `target.wildcard`. A wildcard must be the final segment of the path.
+- Resolution order: exact/static paths always win over parameterized ones. Among parameterized routes, more specific paths win — a literal segment beats `:param`, which beats `*`, compared left to right.
+- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as `{param}` URI templates.
+- If a resource `extends` an existing table, avoid conflicting exports between the schema and the JavaScript implementation.
+- Link the `harper` package in your component directory to ensure correct typings: `npm link harper`. All installed components have `harper` automatically linked.
+- Harper runs as a single process — `tables`, `databases`, and other APIs are the same live, process-wide objects regardless of which component accesses them.

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

@@ -2,34 +2,164 @@
 name: defining-relationships
 description: How to define and use relationships between tables in Harper using GraphQL.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - reference/v5/database/schema.md#Relationships
+    - reference/v5/rest/querying.md#Relationships and Joins
+  sourceCommit: 4fe4c9c95e0974eaa77032f6f10e36fbd8ec64ac
+  inputHash: 6953f507f0cde0f7
 ---
 
-# Defining Relationships
+# Defining Relationships Between Tables in Harper
 
-Instructions for the agent to follow when defining relationships between Harper tables.
+Instructions for the agent to follow when defining and querying relationships between tables in Harper using the `@relationship` directive.
 
 ## When to Use
 
-Use this skill when you need to link data across different tables, enabling automatic joins and efficient related-data fetching via REST APIs.
+Apply this rule whenever a schema requires linking two tables via a foreign key — for example, modeling shows and networks, products and brands, or orders and items. Use it when queries need to filter or select nested related records using dot-syntax.
 
 ## How It Works
 
-1. **Identify the Relationship Type**: Determine if it's one-to-one, many-to-one, or one-to-many.
-2. **Use the `@relationship` Directive**: Apply it to a field in your GraphQL schema.
-   - **Many-to-One (Current table holds FK)**: Use `from`.
-     ```graphql
-     type Book @table @export {
-     	authorId: ID
-     	author: Author @relationship(from: "authorId")
-     }
-     ```
-   - **One-to-Many (Related table holds FK)**: Use `to` and an array type.
-     ```graphql
-     type Author @table @export {
-     	books: [Book] @relationship(to: "authorId")
-     }
-     ```
-3. **Query with Relationships**: Use dot syntax in REST API calls for filtering or the `select()` operator for including related data.
-   - Example Filter: `GET /Book/?author.name=Harper`
-   - Example Select: `GET /Author/?select(name,books(title))`
+1. **Use `@relationship(from: attribute)` for many-to-one or many-to-many**: Place this on a field in the current table when the foreign key lives in this table and references the primary key of the target table.
+
+   ```graphql
+   type RealityShow @table @export {
+   	id: Long @primaryKey
+   	networkId: Long @indexed
+   	network: Network @relationship(from: networkId)
+   	title: String @indexed
+   }
+
+   type Network @table @export {
+   	id: Long @primaryKey
+   	name: String @indexed
+   }
+   ```
+
+   For a many-to-many relationship, make the foreign key an array:
+
+   ```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 a field in the current table when the foreign key lives in the target table and references the primary key of this table. The result type must be an array.
+
+   ```graphql
+   type Network @table @export {
+   	id: Long @primaryKey
+   	name: String @indexed
+   	shows: [RealityShow] @relationship(to: networkId)
+   }
+   ```
+
+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. This is useful for joining on non-primary-key attributes.
+
+   ```graphql
+   type OrderItem @table @export {
+   	id: Long @primaryKey
+   	orderId: Long @indexed
+   	productSku: Long @indexed
+   	product: Product @relationship(from: productSku, to: sku)
+   }
+
+   type Product @table @export {
+   	id: Long @primaryKey
+   	sku: Long @indexed
+   	name: String
+   }
+   ```
+
+4. **Query across relationships using dot-syntax**: Filter by related table attributes using chained dot notation. This behaves as an INNER JOIN.
+
+   ```
+   GET /RealityShow?network.name=Bravo
+   GET /Product/?brand.name=Microsoft
+   GET /Brand/?products.name=Keyboard
+   ```
+
+5. **Select nested relationship fields with `select()`**: Relationship attributes are not included by default. Use `select()` to include them in results. When selecting without a filter on the related table, this acts as a LEFT JOIN — the relationship property is omitted if the foreign key is null or references a non-existent record.
+
+   ```
+   GET /Product/?brand.name=Microsoft&select(name,brand)
+   GET /Product/?brand.name=Microsoft&select(name,brand{name})
+   GET /Product/?name=Keyboard&select(name,brand{name,id})
+   ```
+
+## Examples
+
+**Many-to-one relationship** — a show belongs to a network:
+
+```graphql
+type RealityShow @table @export {
+	id: Long @primaryKey
+	networkId: Long @indexed
+	network: Network @relationship(from: networkId)
+	title: String @indexed
+}
+
+type Network @table @export {
+	id: Long @primaryKey
+	name: String @indexed
+}
+```
+
+Query:
+
+```
+GET /RealityShow?network.name=Bravo
+```
+
+**One-to-many relationship** — a network has many shows:
+
+```graphql
+type Network @table @export {
+	id: Long @primaryKey
+	name: String @indexed
+	shows: [RealityShow] @relationship(to: networkId)
+}
+```
+
+**Many-to-many with array foreign keys** — a product has multiple resellers:
+
+```graphql
+type Product @table @export {
+	id: Long @primaryKey
+	name: String
+	resellerIds: [Long] @indexed
+	resellers: [Reseller] @relationship(from: resellerIds)
+}
+```
+
+Query with nested select:
+
+```
+GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
+```
+
+**Foreign key to foreign key join** — order item joined on SKU:
+
+```graphql
+type OrderItem @table @export {
+	id: Long @primaryKey
+	orderId: Long @indexed
+	productSku: Long @indexed
+	product: Product @relationship(from: productSku, to: sku)
+}
+
+type Product @table @export {
+	id: Long @primaryKey
+	sku: Long @indexed
+	name: String
+}
+```
+
+## Notes
+
+- The `@relationship` directive requires the referenced attribute to be `@indexed` on the foreign key side.
+- Self-referential relationships are supported, enabling parent-child hierarchies within a single table.
+- The array order of foreign key values (e.g., `resellerIds`) is preserved when resolving many-to-many relationships.
+- When using `select()` without a filter on the related table, the join behaves as a LEFT JOIN — missing or null foreign keys result in the relationship property being omitted rather than causing an error.