@harperfast/template-vue-ts-studio 1.9.1 → 1.10.0

package/.agents/skills/harper-best-practices/rules/extending-tables.md

@@ -2,45 +2,114 @@
 name: extending-tables
 description: How to add custom logic to automatically generated table resources in Harper.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - reference/v5/resources/overview.md#Extending a Table
+    - reference/v5/resources/resource-api.md#Throwing Errors
+  sourceCommit: ce0ab713d918d789bc1c9f22e461e963ccc1dff1
+  inputHash: 19738fbc732e0a1a
 ---
 
 # Extending Tables
 
-Instructions for the agent to follow when extending table resources in Harper.
+Instructions for the agent to follow when adding custom logic to automatically generated table resources in Harper.
 
 ## When to Use
 
-Use this skill when you need to add custom validation, side effects (like webhooks), data transformation, or custom access control to the standard CRUD operations of a Harper table.
+Apply this rule when you need to add computed properties, intercept writes, enforce validation, or otherwise customize the behavior of a Harper table resource beyond what the default generated endpoints provide. Use it any time a `@table` type needs server-side logic attached to its REST handlers.
 
 ## How It Works
 
-1. **Define the Table in GraphQL**: In your `.graphql` schema, define the table using the `@table` directive. **Do not** use `@export` if you plan to extend it.
+1. **Define the schema without `@export`**: Declare the table type in `schema.graphql` and omit the `@export` directive. Leaving `@export` on the schema while also exporting a subclass with the same name produces conflicting endpoints. Let the JavaScript class own the URL instead.
+
    ```graphql
+   # Omit the `@export` directive
    type MyTable @table {
-   	id: ID @primaryKey
-   	name: String
+   	id: Long @primaryKey
+   	# ...
    }
    ```
-2. **Create the Extension File**: Create a `.ts` file in your `resources/` directory.
-3. **Extend the Table Resource**: Export a class that extends `tables.YourTableName` and override the relevant **static** methods. In Harper 5 resource handlers are static and map 1:1 to HTTP verbs: `get(target)`, `post(target, data)`, `put(target, data)`, `patch(target, data)`, `delete(target)`. `target` is a pre-parsed `RequestTarget`; for writes, `data` is the request body and is **awaitable** (`await data`). Delegate to `super` to keep Harper's default behavior — a collection create passes just the record (`super.post(record)`), updates pass the target (`super.put(target, data)` / `super.patch(target, data)`), and reads/deletes pass the target (`super.get(target)`). To return a specific HTTP status from a thrown error, set **`.statusCode`** (e.g. `400`) on the error — a plain `.status` property is ignored.
 
-   ```typescript
-   import { tables } from 'harper';
+2. **Extend the generated table class**: In `resources.js`, extend from the `tables.<TypeName>` global. The class name you export becomes the URL path. The exported class extends tables.
 
+   ```javascript
    export class MyTable extends tables.MyTable {
-   	// Static handler; receives (target, data) — data is awaitable.
-   	static async post(target: any, data: any) {
-   		const record = await data;
-   		if (!record?.name) {
-   			const error: any = new Error('Name is required');
-   			error.statusCode = 400; // HTTP status (use statusCode, NOT status)
-   			throw error;
-   		}
-   		return super.post(record); // create delegates with the record (no id)
+   	static async get(target) {
+   		const record = await super.get(target);
+   		return { ...record, computedField: 'value' };
+   	}
+
+   	static async post(target, data) {
+   		this.create({ ...(await data), status: 'pending' });
    	}
    }
    ```
 
-4. **Override Methods**: Override the static `get`, `post`, `put`, `patch`, or `delete` as needed, delegating to `super.<method>` (see the argument forms above) to preserve Harper's default behavior unless you intend to replace it entirely.
-5. **Implement Logic**: Use overrides for validation, side effects, or transforming data before/after database operations.
+3. **Call `super` to preserve default behavior**: When delegating to `super`, match the argument form to the operation:
+   - Reads/deletes: `super.get(target)` / `super.delete(target)`
+   - Collection create: `super.post(target, record)` — target carries no id
+   - Updates: `super.put(target, data)` / `super.patch(target, data)`
+
+   Omit the `super` call only if you intend to replace the default behavior entirely.
+
+4. **Set `statusCode` on thrown errors to control HTTP responses**: Uncaught errors are caught by the protocol handler and produce error responses for REST. Use `.statusCode` — a plain `.status` property is ignored.
+
+   ```javascript
+   const error = new Error('Name is required');
+   error.statusCode = 400; // use statusCode, NOT status
+   throw error;
+   ```
+
+5. **Configure Harper to load both files**: Ensure your configuration references the schema and resource files.
+
+   ```yaml
+   rest: true
+   graphqlSchema:
+     files: schema.graphql
+   jsResource:
+     files: resources.js
+   ```
+
+## Examples
+
+Full end-to-end example — schema, resource class, and error handling:
+
+```graphql
+# schema.graphql — omit @export so the JS class owns the endpoint
+type MyTable @table {
+	id: Long @primaryKey
+}
+```
+
+```javascript
+// resources.js
+export class MyTable extends tables.MyTable {
+	static async get(target) {
+		// get the record from the database
+		const record = await super.get(target);
+		// add a computed property before returning
+		return { ...record, computedField: 'value' };
+	}
+
+	static async post(target, data) {
+		// custom action on POST
+		this.create({ ...(await data), status: 'pending' });
+	}
+}
+```
+
+Throwing a controlled HTTP error:
+
+```javascript
+if (!authorized) {
+	const error = new Error('Forbidden');
+	error.statusCode = 403;
+	throw error;
+}
+```
+
+## Notes
+
+- Always omit `@export` from the schema type when a JavaScript subclass is exporting the same name. The two registrations conflict.
+- `super` must be called with the correct arguments for each operation type — mismatched arguments will not behave as expected.
+- `statusCode` is the only recognized property for controlling HTTP status on thrown errors; `.status` is ignored.

package/.agents/skills/harper-best-practices/rules/handling-binary-data.md

@@ -2,44 +2,124 @@
 name: handling-binary-data
 description: How to store and serve binary data like images or audio in Harper.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - reference/v5/database/api.md#Accepting Binary in JSON Requests
+    - reference/v5/database/api.md#Serving Binary from a Resource
+    - reference/v5/rest/content-types.md#Storing Arbitrary Content Types
+  sourceCommit: ce0ab713d918d789bc1c9f22e461e963ccc1dff1
+  inputHash: fa06480e6fae7614
 ---
 
 # Handling Binary Data
 
-Instructions for the agent to follow when handling binary data in Harper.
+Instructions for the agent to follow when storing and serving binary data (images, audio, arbitrary content types) in Harper.
 
 ## When to Use
 
-Use this skill when you need to store binary files (images, audio, etc.) in the database or serve them back to clients via REST endpoints.
+Apply this rule when a Harper resource needs to accept, store, or serve binary payloads such as images, audio files, or calendar data. Use it when REST clients send `base64`-encoded data inside JSON, when raw binary is uploaded via `PUT`/`POST`, or when a resource must stream binary back to the client with the correct `Content-Type`.
 
 ## How It Works
 
-1. **Store Binary Data**: In your resource's `post` or `put` method, convert incoming data to Buffers and then to Blobs using `createBlob` from Harper's globals. Include the MIME type if available:
+1. **Accept base64-encoded binary from JSON clients**: Decode the incoming `base64` string with `Buffer.from` and wrap it using `createBlob`, recording the MIME type. Override `post` in your resource class:
 
    ```typescript
-   async post(target, record) {
-     if (record.data) {
-       record.data = createBlob(Buffer.from(record.data, record.encoding || 'base64'), {
-         type: record.contentType || 'application/octet-stream',
-       });
-     }
-     return super.post(target, record);
+   import { type RequestTargetOrId, tables, createBlob } from 'harper';
+
+   export class Photo extends tables.Photo {
+   	static async post(target: RequestTargetOrId, record: any) {
+   		if (record.data) {
+   			record.data = createBlob(Buffer.from(record.data, record.encoding || 'base64'), {
+   				type: record.contentType || 'application/octet-stream',
+   			});
+   		}
+   		return super.post(target, record);
+   	}
    }
    ```
 
-2. **Serve Binary Data**: In your resource's `get` method, return a response object with the appropriate `Content-Type` and the binary data in the `body`:
+2. **Serve binary from a resource**: Override `get` to return a response object with the blob's MIME type in the `Content-Type` header and the blob as the body. Harper streams it to the client:
+
    ```typescript
-   async get(target) {
-    const record = await super.get(target);
-    if (record?.data) {
-      return {
-        status: 200,
-        headers: { 'Content-Type': record.data.type || 'application/octet-stream' },
-        body: record.data,
-      };
-    }
-    return record;
+   export class Photo extends tables.Photo {
+   	static async get(target: RequestTargetOrId) {
+   		const record = await super.get(target);
+   		if (record?.data) {
+   			return {
+   				status: 200,
+   				headers: { 'Content-Type': record.data.type || 'application/octet-stream' },
+   				body: record.data,
+   			};
+   		}
+   		return record;
+   	}
    }
    ```
-3. **Use the Blob Type**: Ensure your GraphQL schema uses the `Blob` scalar for binary fields.
+
+3. **Upload raw binary with a non-standard content type**: Make a `PUT` or `POST` with any non-standard `Content-Type` header. Harper automatically stores the body as a record with `contentType` and `data` properties:
+
+   ```http
+   PUT /my-resource/33
+   Content-Type: text/calendar
+
+   BEGIN:VCALENDAR
+   VERSION:2.0
+   ...
+   ```
+
+   Harper stores this as:
+
+   ```json
+   { "contentType": "text/calendar", "data": "BEGIN:VCALENDAR\nVERSION:2.0\n..." }
+   ```
+
+   Retrieving that record returns the response with the stored `Content-Type` and body. If the content type is not from the `text` family, the data is treated as binary (a Node.js `Buffer`).
+
+4. **Upload binary to a specific property**: Use `application/octet-stream` (or any image/binary MIME type) and target a sub-path to store binary directly on a property:
+
+   ```http
+   PUT /my-resource/33/image
+   Content-Type: image/gif
+
+   ...image data...
+   ```
+
+## Examples
+
+**End-to-end: accept base64 JSON, store as blob, serve as binary**
+
+```typescript
+import { type RequestTargetOrId, tables, createBlob } from 'harper';
+
+export class Photo extends tables.Photo {
+	// Accept base64-encoded uploads in JSON
+	static async post(target: RequestTargetOrId, record: any) {
+		if (record.data) {
+			record.data = createBlob(Buffer.from(record.data, record.encoding || 'base64'), {
+				type: record.contentType || 'application/octet-stream',
+			});
+		}
+		return super.post(target, record);
+	}
+
+	// Stream the blob back with the correct Content-Type
+	static async get(target: RequestTargetOrId) {
+		const record = await super.get(target);
+		if (record?.data) {
+			return {
+				status: 200,
+				headers: { 'Content-Type': record.data.type || 'application/octet-stream' },
+				body: record.data,
+			};
+		}
+		return record;
+	}
+}
+```
+
+## Notes
+
+- `createBlob` takes a `Buffer` as its first argument and an options object with a `type` property for the MIME type. See [using-blob-datatype.md](using-blob-datatype.md) for full details on the blob data type.
+- Always fall back to `application/octet-stream` when no MIME type is known, both when creating and when serving blobs.
+- When Harper retrieves a record that has both `contentType` and `data` properties, it automatically sets the response `Content-Type` and body — no custom `get` override is required for that case unless you need additional logic.
+- Non-`text` content types cause `data` to be stored and returned as a Node.js `Buffer`.

package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md

@@ -74,13 +74,13 @@ Use these exact strings — incorrect comparator names will silently fail or err
 
 ### Query Object Parameters
 
-| Property     | Description                                                                          |
-| ------------ | ------------------------------------------------------------------------------------ |
-| `conditions` | Array of condition objects                                                           |
-| `limit`      | Maximum number of records to return                                                  |
-| `offset`     | Number of records to skip (for pagination)                                           |
-| `select`     | Array of attribute names to return; supports `$id` and `$updatedtime`                |
-| `sort`       | Object with `attribute`, `descending` (bool), and optional `next` for secondary sort |
+| Property     | Description                                                                                                                                                                                                     |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `conditions` | Array of condition objects                                                                                                                                                                                      |
+| `limit`      | Maximum number of records to return                                                                                                                                                                             |
+| `offset`     | Number of records to skip (for pagination)                                                                                                                                                                      |
+| `select`     | Array of fields to return: attribute names (supports `$id` and `$updatedtime`), or an object `{ name, select }` to include fields from a related record — see [Selecting Related Data](#selecting-related-data) |
+| `sort`       | Object with `attribute`, `descending` (bool), and optional `next` for secondary sort                                                                                                                            |
 
 ### Examples
 
@@ -129,6 +129,50 @@ for await (const record of tables.Product.search({
 })) { ... }
 ```
 
+## Selecting Related Data
+
+When a field is defined as a relationship (via `@relationship` — see [Defining Relationships](defining-relationships.md)), `select` can pull the related record(s) into your results as nested properties. This is the programmatic equivalent of the REST `select(name,author{name})` syntax (see [Querying REST APIs](querying-rest-apis.md)).
+
+**Whole related record** — list the relationship field by name. The related record (or an array of records for a to-many relationship) is attached as a nested property:
+
+```javascript
+for await (const book of tables.Book.search({
+	conditions: [{ attribute: 'id', value: 42 }],
+	select: ['id', 'title', 'author'], // `author` is a relationship field
+})) {
+	console.log(book.author.name); // the full related Author record
+}
+```
+
+**Partial related record** — use an object `{ name, select }` to choose which fields of the related record to return. Unselected fields are omitted:
+
+```javascript
+for await (const book of tables.Book.search({
+	conditions: [{ attribute: ['author', 'name'], comparator: 'equals', value: 'Harper' }],
+	select: ['id', 'title', { name: 'author', select: ['name'] }],
+})) {
+	// book.author.name is present; other Author fields are undefined
+}
+```
+
+**Nesting** — a `select` inside an object entry may itself contain more `{ name, select }` objects, traversing multiple relationships in one query:
+
+```javascript
+select: [
+  'id',
+  'name',
+  {
+    name: 'segments',
+    select: ['id', 'name', { name: 'client', select: ['id', 'name'] }],
+  },
+],
+```
+
+Notes:
+
+- A to-many relationship resolves to an array of records; depending on access pattern you may need to `await` the property before iterating it.
+- Selecting a relationship without filtering on it produces LEFT JOIN behavior (records with no related row are still returned); adding a condition on a related attribute (e.g. `attribute: ['author', 'name']`) produces INNER JOIN behavior.
+
 ## Cautions
 
 Be very careful when performing updates and deletions! You may be dealing with live production data. The wrong request to delete, without approval from a human, could be devastating to a business. Always use the proper approval process.

package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md

@@ -9,11 +9,11 @@ metadata:
     - reference/v5/database/schema.md#Overview
     - reference/v5/database/schema.md#Type Directives
     - reference/v5/database/schema.md#Field Directives
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: 4faa3baed7cfa854
+  sourceCommit: 4fe4c9c95e0974eaa77032f6f10e36fbd8ec64ac
+  inputHash: 15b9c72decc1f05d
 ---
 
-# Schema Design and Tooling
+# Schema Design and GraphQL Tooling
 
 Instructions for the agent to follow when designing Harper schemas, applying core directives, and configuring GraphQL tooling.
 
@@ -23,7 +23,18 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
 
 ## How It Works
 
-1. **Create a GraphQL schema file** with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.
+1. **Create a schema file** using standard GraphQL type definitions with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.
+
+2. **Register the schema** in the component's `config.yaml` using the `graphqlSchema` plugin:
+
+   ```yaml
+   graphqlSchema:
+     files: 'schema.graphql'
+   ```
+
+   Both plugins and applications can specify schemas.
+
+3. **Mark types as tables** with `@table`. The type name becomes the table name by default:
 
    ```graphql
    type Dog @table {
@@ -32,23 +43,36 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
    	breed: String
    	age: Int
    }
+   ```
 
+4. **Designate a primary key** with `@primaryKey` on exactly one field per type. Primary keys must be unique; duplicate-key inserts are rejected. If no primary key is provided on insert, Harper auto-generates one:
+   - `String` or `ID` → UUID string
+   - `Int`, `Long`, or `Any` → auto-incrementing integer
+
+   Use `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
+
+5. **Add secondary indexes** with `@indexed` on any field that will be used for filtering in REST queries, SQL, or NoSQL operations:
+
+   ```graphql
    type Breed @table {
    	id: Long @primaryKey
    	name: String @indexed
    }
    ```
 
-2. **Register the schema in `config.yaml`** using the `graphqlSchema` plugin key:
+   If the field value is an array, each element is individually indexed. Null values are indexed by default.
 
-   ```yaml
-   graphqlSchema:
-     files: 'schema.graphql'
+6. **Expose a table as an external endpoint** with `@export`. The optional `name` parameter sets the URL path segment:
+
+   ```graphql
+   type MyTable @table @export(name: "my-table") {
+   	id: Long @primaryKey
+   }
    ```
 
-   Both plugins and applications can specify schemas this way.
+   Without `name`, the type name is used as the path segment.
 
-3. **Mark every table type with `@table`**. The type name becomes the table name by default. Use optional arguments to override behavior:
+7. **Configure `@table` arguments** as needed for database placement, expiration, eviction, and replication:
 
    | Argument       | Type      | Default                       | Description                                                   |
    | -------------- | --------- | ----------------------------- | ------------------------------------------------------------- |
@@ -59,32 +83,13 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
    | `scanInterval` | `Int`     | `(expiration + eviction) / 4` | Seconds between eviction scans                                |
    | `replicate`    | `Boolean` | `true`                        | Enable replication of this table                              |
 
-4. **Designate a primary key on every table** using `@primaryKey`. Primary keys must be unique; duplicate-key inserts are rejected. If no key is provided on insert, Harper auto-generates one:
-   - `String` or `ID` → UUID string
-   - `Int`, `Long`, or `Any` → auto-incrementing integer
-
-   Prefer `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
-
-5. **Index fields that need fast querying** with `@indexed`. This is required for filtering by that attribute in REST queries, SQL, or NoSQL operations. If the field value is an array, each element is individually indexed.
-
-   ```graphql
-   type Product @table {
-   	id: Long @primaryKey
-   	category: String @indexed
-   	price: Float @indexed
-   }
-   ```
-
-6. **Expose a table as an external resource endpoint** with `@export`. This makes the table accessible via REST, MQTT, and other interfaces. The optional `name` parameter sets the URL path segment; without it, the type name is used.
-
-   ```graphql
-   type MyTable @table @export(name: "my-table") {
-   	id: Long @primaryKey
-   }
-   ```
-
-7. **Restrict extra properties** with `@sealed` when records must not include attributes beyond those declared. By default, Harper allows additional properties.
+8. **Apply additional field directives** where needed:
+   - `@createdTime` — auto-assigns Unix epoch milliseconds on record creation
+   - `@updatedTime` — auto-assigns Unix epoch milliseconds on each update
+   - `@embed(source: "fieldName", model: "modelName")` — computes an embedding vector on write; attribute type must be `[Float]`
+   - `@hidden` — suppresses the field from MCP tool descriptors and OpenAPI documents (not an access-control mechanism)
 
+9. **Restrict extra properties** with `@sealed` if records must not include properties beyond those declared:
    ```graphql
    type StrictRecord @table @sealed {
    	id: Long @primaryKey
@@ -92,70 +97,88 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
    }
    ```
 
-8. **Configure expiration, eviction, and scan behavior** together when building caching tables. These three arguments control the full record lifecycle:
-   - `expiration` — record becomes stale; next request triggers a source fetch
-   - `eviction` — additional time after `expiration` before physical removal
-   - `scanInterval` — how often Harper scans for records to evict; clock-aligned, not startup-aligned
-
 ## Examples
 
-**Caching table with tuned expiration:**
+**Minimal two-table schema:**
 
 ```graphql
-# Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
-type WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {
-	id: ID @primaryKey
-	temperature: Float
+type Dog @table {
+	id: Long @primaryKey
+	name: String
+	breed: String
+	age: Int
 }
-```
-
-**Table in a named database with expiration and an indexed field:**
 
-```graphql
-type Event @table(database: "analytics", expiration: 86400) {
+type Breed @table {
 	id: Long @primaryKey
 	name: String @indexed
 }
 ```
 
-**Session cache with auto-expiry:**
+**Table with expiration, eviction, and custom scan interval:**
 
 ```graphql
-type Session @table(expiration: 3600) {
-	id: Long @primaryKey
-	userId: String
+# Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
+type WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {
+	id: ID @primaryKey
+	temperature: Float
 }
 ```
 
-**Table with audit timestamps:**
+**Exported table with timestamps and a hidden field:**
 
 ```graphql
-type Order @table @export(name: "orders") {
+type Customer @table @export(name: "customers") {
 	id: Long @primaryKey
+	name: String @indexed
 	createdAt: Long @createdTime
 	updatedAt: Long @updatedTime
-	status: String @indexed
+
+	"""
+	Internal — do not surface to external consumers.
+	"""
+	creditScore: Int @hidden
 }
 ```
 
-**Overriding the table name and disabling replication:**
+**Multiple `@table` argument combinations:**
 
 ```graphql
+# Override table name
 type Product @table(table: "products") {
 	id: Long @primaryKey
-	name: String
 }
 
+# Place in a specific database
+type Order @table(database: "commerce") {
+	id: Long @primaryKey
+}
+
+# Auto-expire records after 1 hour
+type Session @table(expiration: 3600) {
+	id: Long @primaryKey
+	userId: String
+}
+
+# Disable replication
 type LocalRecord @table(replicate: false) {
 	id: Long @primaryKey
 	value: String
 }
+
+# Combine multiple arguments
+type Event @table(database: "analytics", expiration: 86400) {
+	id: Long @primaryKey
+	name: String @indexed
+}
 ```
 
 ## Notes
 
-- Use unique `database` names in plugins and applications to avoid table naming collisions, since all tables default to the `"data"` database.
-- Eviction removes non-indexed record data but does **not** remove a record from its secondary indexes. Indexes remain functional for evicted records; Harper fetches the full record from the source on demand when a query matches an evicted record.
-- `scanInterval` is clock-aligned to the server's local timezone. The server's startup time does not affect when eviction runs.
-- If replication is disabled on a table and later re-enabled, it will not catch up on writes made while replication was disabled.
-- Null values are indexed by `@indexed` fields, enabling queries such as `GET /Product/?category=null`.
+- All tables default to the `"data"` database. When designing plugins or applications, use unique database names to avoid table naming collisions.
+- Schemas are flexible by default — records may include properties beyond those declared. Use `@sealed` to prevent this.
+- `expiration` marks a record stale; `eviction` controls how long after expiration the record is physically removed. Eviction does not remove records from secondary indexes — Harper fetches the full record on demand if an evicted record matches a query.
+- `scanInterval` is clock-aligned to the server's local timezone, not startup-aligned. The eviction schedule is deterministic across restarts.
+- If replication is disabled on a table and later re-enabled, writes made during the disabled period are not replicated retroactively.
+- `@hidden` (on types or fields) is a metadata-visibility directive only. Use `attribute_permissions` on roles to enforce data access control.
+- Disabling replication (`replicate: false`) and re-enabling it later will not catch up on writes made while replication was disabled.