@harperfast/template-vue-ts-studio 1.6.2 → 1.6.4

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

@@ -38,6 +38,8 @@ Reference these guidelines when:
 
 See the concrete examples embedded in each rule subsection below (GraphQL schemas, REST query patterns, and deployment workflow snippets).
 
+<!-- BEGIN GENERATED INDEX -->
+
 ## Rule Categories by Priority
 
 | Priority | Category             | Impact | Prefix    |
@@ -51,35 +53,37 @@ See the concrete examples embedded in each rule subsection below (GraphQL schema
 
 ### 1. Schema & Data Design (HIGH)
 
-- `adding-tables-with-schemas` - Define tables using GraphQL schemas and directives
-- `schema-design-tooling` - Core directives and GraphQL IDE/agent configuration
-- `defining-relationships` - Link tables using the `@relationship` directive
-- `vector-indexing` - Efficient similarity search with vector indexes
-- `using-blob-datatype` - Store and retrieve large data (Blobs)
-- `handling-binary-data` - Manage binary data like images or MP3s
+- `adding-tables-with-schemas` — Guidelines for adding tables to a Harper database using GraphQL schemas.
+- `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.
 
 ### 2. API & Communication (HIGH)
 
-- `automatic-apis` - Leverage automatically generated CRUD endpoints
-- `querying-rest-apis` - Filters, sorting, and pagination in REST requests
-- `real-time-apps` - WebSockets and Pub/Sub for Real-Time Apps
-- `checking-authentication` - Secure apps with session-based identity verification
+- `automatic-apis` — How to use Harper's automatically generated REST and WebSocket APIs.
+- `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.
 
 ### 3. Logic & Extension (MEDIUM)
 
-- `custom-resources` - Define custom REST endpoints using JS/TS
-- `extending-tables` - Add custom logic to generated table resources
-- `programmatic-table-requests` - Advanced filtering and sorting in code
-- `typescript-type-stripping` - Use TypeScript without build tools
-- `caching` - Implement and define caching for performance
+- `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.
 
 ### 4. Infrastructure & Ops (MEDIUM)
 
-- `deploying-to-harper-fabric` - Scale globally with Harper Fabric
-- `creating-a-fabric-account-and-cluster` - Setting up your Harper Fabric cloud infrastructure
-- `creating-harper-apps` - Quickstart with `npm create harper@latest`
-- `serving-web-content` - Ways to serve web content from Harper
-- `logging` - Use standard console and Harper's granular logger
+- `deploying-to-harper-fabric` — How to deploy a Harper application to the Harper Fabric cloud.
+- `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.
+
+<!-- END GENERATED INDEX -->
 
 ## How to Use
 

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

@@ -1,6 +1,8 @@
 ---
 name: adding-tables-with-schemas
 description: Guidelines for adding tables to a Harper database using GraphQL schemas.
+metadata:
+  mode: synthesized
 ---
 
 # Adding Tables with Schemas
@@ -14,9 +16,9 @@ Use this skill when you need to define new data structures or modify existing on
 ## How It Works
 
 1. **Create Dedicated Schema Files**: Prefer having a dedicated schema `.graphql` file for each table. Check the `config.yaml` file under `graphqlSchema.files` to see how it's configured. It typically accepts wildcards (e.g., `schemas/*.graphql`), but may be configured to point at a single file.
-2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harperdb/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
+2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harper/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
 3. **Define Relationships**: Link tables together using the `@relationship` directive. For more details, see the [Defining Relationships](defining-relationships.md) skill.
-4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill.
+4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. **Important**: REST endpoints also require `rest: true` in `config.yaml` — without it, `@export`ed tables will not respond to HTTP requests. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill.
    - `GET /{TableName}`: Describes the schema itself.
    - `GET /{TableName}/`: Lists all records (supports filtering, sorting, and pagination via query parameters). See the [Querying REST APIs](querying-rest-apis.md) skill for details.
    - `GET /{TableName}/{id}`: Retrieves a single record by its ID.

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

@@ -1,37 +1,165 @@
 ---
 name: automatic-apis
 description: How to use Harper's automatically generated REST and WebSocket APIs.
+metadata:
+  mode: generate
+  sources:
+    - reference/v5/rest/overview.md
+    - reference/v5/rest/websockets.md
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: 8fcf0cfe190e013e
 ---
 
 # Automatic APIs
 
-Instructions for the agent to follow when utilizing Harper's automatic APIs.
+Instructions for the agent to follow when enabling and using Harper's automatically generated REST and WebSocket APIs.
 
 ## When to Use
 
-Use this skill when you want to interact with Harper tables via REST or WebSockets without writing custom resource logic. This is ideal for basic CRUD operations and real-time updates.
+Apply this rule when adding REST or WebSocket API access to Harper tables or custom resources. Use it when configuring `config.yaml` to expose endpoints, mapping HTTP methods to resource operations, or implementing real-time WebSocket connections on a resource class.
 
 ## How It Works
 
-1. **Enable Automatic APIs**: Ensure your GraphQL schema includes the `@export` directive for the table.
-2. **Access REST Endpoints**: Use the standard endpoints for your table (Note: Paths are case-sensitive).
-3. **Use Automatic WebSockets**: Connect to `wss://your-harper-instance/{TableName}` to receive events whenever updates are made to that table. This is the easiest way to add real-time capabilities. (Use `ws://` for local development without SSL). For more complex needs, see [Real-time Apps](real-time-apps.md).
-4. **Apply Filtering and Querying**: Use query parameters with `GET /{TableName}/` and `DELETE /{TableName}/`. See the [Querying REST APIs](querying-rest-apis.md) skill for advanced details.
-5. **Customize if Needed**: If the automatic APIs don't meet your requirements, [customize the resources](./custom-resources.md).
+1. **Enable the REST plugin**: Add `rest: true` to your application's `config.yaml`. This activates the HTTP REST interface and enables WebSocket support by default.
+
+   ```yaml
+   rest: true
+   ```
+
+   To configure optional behavior:
+
+   ```yaml
+   rest:
+     lastModified: true # enables Last-Modified response header support
+     webSocket: false # disables automatic WebSocket support (enabled by default)
+   ```
+
+2. **Export your resource in the schema**: Tables are not exposed by default. Use the `@export` directive in your schema definition to make a table available as a REST endpoint. The exported name defines the base URL path, served on the application HTTP server port (default `9926`).
+
+3. **Use the correct URL structure**: The REST interface follows a consistent path convention.
+
+   | Path                                         | Description                                                                        |
+   | -------------------------------------------- | ---------------------------------------------------------------------------------- |
+   | `/my-resource`                               | Returns a description of the resource (e.g., table metadata)                       |
+   | `/my-resource/`                              | Trailing slash — represents the full collection; append query parameters to search |
+   | `/my-resource/record-id`                     | A specific record identified by its primary key                                    |
+   | `/my-resource/record-id/`                    | Trailing slash — collection of records with the given id prefix                    |
+   | `/my-resource/record-id/with/multiple/parts` | Record id with multiple path segments                                              |
+
+4. **Map HTTP methods to operations**: Each HTTP method maps to a resource method and operation.
+   - **GET** — Retrieve a record or search. Calls `get()`.
+
+     ```
+     GET /MyTable/123
+     GET /MyTable/?name=Harper
+     GET /MyTable/123.propertyName
+     ```
+
+     Responses include an `ETag` header. Clients may send `If-None-Match` to receive `304 Not Modified` when the record is unchanged.
+
+   - **PUT** — Create or replace a record (upsert). Calls `put(record)`. Properties not in the body are removed.
+
+     ```
+     PUT /MyTable/123
+     Content-Type: application/json
+
+     { "name": "some data" }
+     ```
+
+   - **POST** — Create a new record without specifying a primary key. Calls `post(data)`. The assigned key is returned in the `Location` response header.
+
+     ```
+     POST /MyTable/
+     Content-Type: application/json
+
+     { "name": "some data" }
+     ```
+
+   - **PATCH** — Partially update a record, merging only provided properties. Unspecified properties are preserved.
+
+     ```
+     PATCH /MyTable/123
+     Content-Type: application/json
+
+     { "status": "active" }
+     ```
+
+   - **DELETE** — Delete a record or all records matching a query.
+     ```
+     DELETE /MyTable/123
+     DELETE /MyTable/?status=archived
+     ```
+
+5. **Access the auto-generated OpenAPI spec**: Harper generates an OpenAPI specification for all exported resources. Retrieve it at:
+
+   ```
+   GET /openapi
+   ```
+
+6. **Connect via WebSocket**: When `rest` is enabled, WebSocket support is on by default. Connect to a resource URL to subscribe to change events for that resource.
+
+   ```javascript
+   let ws = new WebSocket('wss://server/my-resource/341');
+   ws.onmessage = (event) => {
+   	let data = JSON.parse(event.data);
+   };
+   ```
+
+   Connecting to `wss://server/my-resource/341` accesses the `my-resource` resource with record id `341` and subscribes to it. When the record changes or a message is published to it, the WebSocket connection receives the update.
+
+7. **Implement a custom `connect()` handler**: Override `connect(incomingMessages)` on a resource class to control WebSocket behavior. The method must return an async iterable or generator that produces messages to send to the client.
 
 ## Examples
 
-### Schema Configuration
+**Simple echo server using an async generator**:
+
+```javascript
+export class Echo extends Resource {
+	async *connect(incomingMessages) {
+		for await (let message of incomingMessages) {
+			yield message; // echo each message back
+		}
+	}
+}
+```
+
+**Using the default `connect()` with event-style access and a timer**:
+
+```javascript
+export class Example extends Resource {
+	connect(incomingMessages) {
+		let outgoingMessages = super.connect();
+
+		let timer = setInterval(() => {
+			outgoingMessages.send({ greeting: 'hi again!' });
+		}, 1000);
+
+		incomingMessages.on('data', (message) => {
+			outgoingMessages.send(message); // echo incoming messages
+		});
 
-```graphql
-type MyTable @table @export {
-	id: ID @primaryKey
-	name: String
+		outgoingMessages.on('close', () => {
+			clearInterval(timer);
+		});
+
+		return outgoingMessages;
+	}
 }
 ```
 
-### Common REST Operations
+**Minimal `config.yaml` enabling REST with WebSocket disabled**:
+
+```yaml
+rest:
+  webSocket: false
+```
+
+## Notes
 
-- **List Records**: `GET /MyTable/`
-- **Create Record**: `POST /MyTable/`
-- **Update Record**: `PATCH /MyTable/{id}`
+- Tables must be explicitly exported using `@export` in the schema — they are not exposed by default.
+- `rest: true` is the minimal configuration to enable both REST and WebSocket support. See [real-time-apps.md](real-time-apps.md) for patterns around real-time WebSocket usage.
+- For full query syntax on `GET` and `DELETE` with query parameters, see [querying-rest-apis.md](querying-rest-apis.md).
+- The default `connect()` returns an iterable with a `send(message)` method and a `close` event for cleanup on disconnect.
+- For MQTT over WebSockets, set the sub-protocol header `Sec-WebSocket-Protocol: mqtt`.
+- In distributed environments, non-retained messages are delivered in the order received per node; retained messages (PUT/updated records) keep only the latest-timestamp version as the winning record across the cluster.
+- Use the `Content-Type` request header to specify body format and the `Accept` header to request a specific response format.

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

@@ -1,50 +1,163 @@
 ---
 name: caching
 description: How to implement integrated data caching in Harper from external sources.
+metadata:
+  mode: generate
+  sources:
+    - learn/developers/caching-with-harper.md
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: 8212a7d7dbbd2b18
 ---
 
-# Caching
+# Caching External Data Sources in Harper
 
-Instructions for the agent to follow when implementing caching in Harper.
+Instructions for the agent to implement integrated data caching in Harper by wrapping external sources with a cache table and `sourcedFrom`.
 
 ## When to Use
 
-Use this skill when you need high-performance, low-latency storage for data from external sources. It's ideal for reducing API calls to third-party services, preventing cache stampedes, and making external data queryable as if it were native Harper tables.
+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.
 
 ## How It Works
 
-1. **Configure a Cache Table**: Define a table in your `schema.graphql` with an `expiration` (in seconds).
-2. **Define an External Source**: Create a Resource class that fetches the data from your source.
-3. **Attach Source to Table**: Use `sourcedFrom` to link your resource to the table.
-4. **Implement Active Caching (Optional)**: Use `subscribe()` for proactive updates. See [Real-Time Apps](real-time-apps.md).
-5. **Implement Write-Through Caching (Optional)**: Define `put` or `post` in your resource to propagate updates upstream.
+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.
+
+   ```graphql
+   type JokeCache @table(expiration: 60) @export {
+   	id: ID @primaryKey
+   	setup: String
+   	punchline: String
+   }
+   ```
+
+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.
+
+   ```javascript
+   const jokeAPI = {
+   	async get(id) {
+   		const response = await fetch(`https://official-joke-api.appspot.com/jokes/${id}`);
+   		return response.json();
+   	},
+   };
+
+   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.
+   - 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.
+
+   ```yaml
+   graphqlSchema:
+     files: 'schema.graphql'
+   rest: true
+   jsResource:
+     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
+   }
+   ```
+
+   ```javascript
+   export class JokeCache extends tables.JokeCache {
+   	static async post(target, data) {
+   		const body = await data;
+   		if (body?.action === 'invalidate') {
+   			this.invalidate(target);
+   			return { status: 200, data: { message: 'invalidated' } };
+   		}
+   	}
+   }
+   ```
+
+   Trigger invalidation with a `POST`:
+
+   ```bash
+   curl -X POST 'http://localhost:9926/JokeCache/1' \
+     -H 'Content-Type: application/json' \
+     -d '{"action": "invalidate"}'
+   ```
+
+   The next `GET /JokeCache/1` will fetch fresh data from the upstream source regardless of TTL.
 
 ## Examples
 
-### Schema Configuration
+Complete `schema.graphql` and `resources.js` for a cached external API with on-demand invalidation:
 
 ```graphql
-type MyCache @table(expiration: 3600) @export {
+type JokeCache @table(expiration: 60) {
 	id: ID @primaryKey
+	setup: String
+	punchline: String
 }
 ```
 
-### Resource Implementation
-
-```js
-import { Resource, tables } from 'harperdb';
+```javascript
+// resources.js
 
-export class ThirdPartyAPI extends Resource {
+const jokeAPI = {
 	async get() {
 		const id = this.getId();
-		const response = await fetch(`https://api.example.com/items/${id}`);
-		if (!response.ok) {
-			throw new Error('Source fetch failed');
+		const response = await fetch(`https://official-joke-api.appspot.com/jokes/${id}`);
+		return response.json();
+	},
+};
+
+tables.JokeCache.sourcedFrom(jokeAPI);
+
+export class JokeCache extends tables.JokeCache {
+	static async post(target, data) {
+		const body = await data;
+		if (body?.action === 'invalidate') {
+			this.invalidate(target);
+			return { status: 200, data: { message: 'invalidated' } };
 		}
-		return await response.json();
 	}
 }
+```
 
-// Attach source to table
-tables.MyCache.sourcedFrom(ThirdPartyAPI);
+First request — cache miss, upstream is called, `200` returned:
+
+```bash
+curl -i 'http://localhost:9926/JokeCache/1'
+```
+
+Second request with ETag — cache hit, `304 Not Modified`:
+
+```bash
+curl -i 'http://localhost:9926/JokeCache/1' \
+  -H 'If-None-Match: "abCDefGHij"'
 ```
+
+## 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`.