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

package/agent/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/agent/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/agent/skills/harper-best-practices/rules/programmatic-table-requests.md

@@ -2,133 +2,185 @@
 name: programmatic-table-requests
 description: How to interact with Harper tables programmatically using the `tables` object.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - reference/v5/database/api.md#`tables`
+    - reference/v5/resources/resource-api.md#Query Object
+    - 'reference/v5/database/api.md#`transaction(context?, callback)`'
+    - >-
+      reference/v5/resources/resource-api.md#`update(target: RequestTarget | Id,
+      updates?: object): Promise<Resource>`
+    - >-
+      reference/v5/resources/resource-api.md#`addTo(property: string, value:
+      number)`
+    - reference/v5/components/javascript-environment.md#Module Loading
+  sourceCommit: be709f9978319dcdb669c05d794effc82bcda8b7
+  inputHash: 3d2417fbff687c42
 ---
 
 # Programmatic Table Requests
 
-Instructions for the agent to follow when interacting with Harper tables via code.
+Instructions for the agent to interact with Harper tables programmatically using the `tables` object and its query API.
 
 ## When to Use
 
-Use this skill when you need to perform database operations (CRUD, search, subscribe) from within Harper Resources or scripts.
+Apply this rule when writing server-side Harper code that reads from or writes to tables directly — for example, in request handlers, background jobs, or SSR entry points — instead of going through the REST API. Use it whenever you need to construct queries with `conditions`, paginate results, select specific fields, or perform CRDT-safe mutations with `addTo`.
 
 ## How It Works
 
-1. **Access the Table**: Use the global `tables` object followed by your table name (e.g., `tables.MyTable`).
-2. **Perform CRUD Operations**:
-   - **Get**: `await tables.MyTable.get(id)` for a single record or `await tables.MyTable.get({ conditions: [...] })` for multiple.
-   - **Create**: `await tables.MyTable.post(record)` (auto-generates ID) or `await tables.MyTable.put(id, record)`.
-   - **Update**: `await tables.MyTable.patch(id, partialRecord)` for partial updates.
-   - **Delete**: `await tables.MyTable.delete(id)`.
-3. **Use Updatable Records for Atomic Ops**: Call `update(id)` to get a reference, then use `addTo` or `subtractFrom` for atomic increments/decrements:
-   ```typescript
-   const stats = await tables.Stats.update('daily');
-   stats.addTo('viewCount', 1);
-   ```
-4. **Search and Stream**: Use `search(query)` for efficient streaming of large result sets:
-   ```typescript
-   for await (const record of tables.MyTable.search({ conditions: [...] })) {
-     // process record
-   }
+1. **Import `tables`**: Import from the `harper` package. Each table defined in `schema.graphql` with `@table` is available as a named property.
+
+   ```javascript
+   import { tables } from 'harper';
+   const { Product } = tables;
+   // same as: databases.data.Product
    ```
-   See the [Query Conditions](#query-conditions) section below for the full query object reference.
-5. **Real-time Subscriptions**: Use `subscribe(query)` to listen for changes:
-   ```typescript
-   for await (const event of tables.MyTable.subscribe(query)) {
-   	// handle event
+
+2. **Define your schema**: Declare tables in `schema.graphql` using `@table` and `@primaryKey`.
+
+   ```graphql
+   # schema.graphql
+   type Product @table {
+   	id: Long @primaryKey
+   	name: String
+   	price: Float
    }
    ```
-6. **Publish Events**: Use `publish(id, message)` to trigger subscriptions without necessarily persisting data.
 
-## Query Conditions
+3. **Create and mutate records**: Use `create`, `patch`, `get`, and `update` on the table class.
 
-When passing a query to `search()`, `get()`, or `subscribe()`, use a query object with a `conditions` array.
+   ```javascript
+   // Create a new record (id auto-generated)
+   const created = await Product.create({ name: 'Shirt', price: 9.5 });
 
-### Condition Object Shape
+   // Modify the record
+   await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
 
-| Property     | Description                                                                                |
-| ------------ | ------------------------------------------------------------------------------------------ |
-| `attribute`  | Field name, or array of field names to traverse a relationship (e.g., `['brand', 'name']`) |
-| `value`      | The value to compare against                                                               |
-| `comparator` | One of the comparator strings below (default: `equals`)                                    |
-| `operator`   | `and` (default) or `or` — applies to a nested `conditions` block                           |
-| `conditions` | Nested array of condition objects for complex AND/OR logic                                 |
+   // Retrieve by primary key
+   const record = await Product.get(created.id);
+   ```
 
-### Comparator Values
+4. **Query with `search(` and `conditions`**: Pass a query object to `search()` to filter records. Iterate the async result.
 
-Use these exact strings — incorrect comparator names will silently fail or error:
+   ```javascript
+   const query = {
+   	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
+   };
+   for await (const record of Product.search(query)) {
+   	// ...
+   }
+   ```
 
-| Comparator           | Meaning                                                    |
-| -------------------- | ---------------------------------------------------------- |
-| `equals`             | Exact match (default)                                      |
-| `not_equal`          | Not equal                                                  |
-| `greater_than`       | `>`                                                        |
-| `greater_than_equal` | `>=`                                                       |
-| `less_than`          | `<`                                                        |
-| `less_than_equal`    | `<=`                                                       |
-| `starts_with`        | String starts with value                                   |
-| `contains`           | String contains value                                      |
-| `ends_with`          | String ends with value                                     |
-| `between`            | Value is between two bounds (pass `value` as `[min, max]`) |
+5. **Use `select` to shape results**: Pass a `select` array to return only specific properties, including nested relationship fields.
 
-### Query Object Parameters
+   ```javascript
+   const book = await Book.get({ id: 42, select: ['id', 'title', 'author'] });
+   book.author.name; // full related Author record
 
-| 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 |
+   // Partial related record
+   const book = await Book.get({
+   	id: 42,
+   	select: ['id', 'title', { name: 'author', select: ['name'] }],
+   });
+   ```
 
-### Examples
+6. **Use `addTo` for concurrent-safe increments**: Call `addTo` on a mutable resource instance obtained via `update()`. This uses CRDT incrementation, safe across threads and nodes.
 
-**Simple filter:**
+   ```javascript
+   static async post(target, data) {
+     const record = await this.update(target.id);
+     record.addTo('quantity', -1); // decrement safely across nodes
+   }
+   ```
 
-```javascript
-for await (const record of tables.Product.search({
-  conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],
-  limit: 20,
-})) { ... }
-```
+7. **Scope destructive operations carefully**: `update`, `patch`, and `delete` operate directly on stored data. Always use specific `conditions`, validate the affected set before writing, and gate behind authorization controls.
 
-**AND + nested OR:**
+## Examples
+
+### Nested conditions query
 
 ```javascript
-for await (const record of tables.Product.search({
-  conditions: [
-    { attribute: 'price', comparator: 'less_than', value: 100 },
-    {
-      operator: 'or',
-      conditions: [
-        { attribute: 'rating', comparator: 'greater_than', value: 4 },
-        { attribute: 'featured', value: true },
-      ],
-    },
-  ],
-})) { ... }
+Product.search({
+	conditions: [
+		{ attribute: 'price', comparator: 'less_than', value: 100 },
+		{
+			operator: 'or',
+			conditions: [
+				{ attribute: 'rating', comparator: 'greater_than', value: 4 },
+				{ attribute: 'featured', value: true },
+			],
+		},
+	],
+});
 ```
 
-**Relationship traversal:**
+### Chained attribute reference (relationship join)
 
 ```javascript
-for await (const record of tables.Book.search({
-  conditions: [{ attribute: ['brand', 'name'], comparator: 'equals', value: 'Harper' }],
-})) { ... }
+Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-**Sort and paginate:**
+### Deep nested `select`
 
 ```javascript
-for await (const record of tables.Product.search({
-  conditions: [{ attribute: 'inStock', value: true }],
-  sort: { attribute: 'price', descending: false },
-  limit: 10,
-  offset: 20,
-})) { ... }
+select: [
+	'id',
+	'name',
+	{ name: 'segments', select: ['id', 'name', { name: 'client', select: ['id', 'name'] }] },
+];
 ```
 
-## Cautions
+### SSR usage
+
+```typescript
+import { tables } from 'harper';
+
+export async function render(url: string): Promise<string> {
+	const product = await tables.Product.get(idFromUrl(url));
+	return renderToString(/* <App product={product} /> */);
+}
+```
 
-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.
+## Notes
+
+### `conditions` comparator values
+
+| Comparator           | Description            |
+| -------------------- | ---------------------- |
+| `equals`             | Default equality match |
+| `greater_than`       | Strictly greater       |
+| `greater_than_equal` | Greater than or equal  |
+| `less_than`          | Strictly less          |
+| `less_than_equal`    | Less than or equal     |
+| `starts_with`        | String prefix match    |
+| `contains`           | String contains        |
+| `ends_with`          | String suffix match    |
+| `between`            | Range match            |
+| `not_equal`          | Inequality match       |
+
+### Query object options
+
+| Property                | Description                                                             |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `conditions`            | Array of condition objects to filter records                            |
+| `operator`              | Top-level `and` (default) or `or` for the `conditions` array            |
+| `limit`                 | Maximum number of records to return                                     |
+| `offset`                | Number of records to skip (for pagination)                              |
+| `select`                | Properties to include in each returned record                           |
+| `sort`                  | Sort order object with `attribute`, `descending`, and `next` properties |
+| `explain`               | If `true`, returns conditions reordered as Harper will execute them     |
+| `enforceExecutionOrder` | If `true`, forces conditions to execute in the order supplied           |
+
+### `select` special properties
+
+- `$id` — Returns the primary key regardless of its name
+- `$updatedtime` — Returns the last-updated timestamp
+- `$distance` — Returns the computed distance from the target vector when the query uses a vector index
+
+### Relationship join behavior
+
+- Selecting a relationship **without** filtering on it behaves as a **LEFT JOIN** — records with no related row are still returned.
+- Adding a `conditions` entry on a related attribute (e.g. `attribute: ['author', 'name']`) behaves as an **INNER JOIN** — only records with a matching related row are returned.
+
+- Keep `harper` external when bundling for SSR (e.g. `ssr: { external: ['harper'] }` in `vite.config`) so it resolves to the runtime instead of being bundled.
+- `tables`, `databases`, and other Harper APIs are the same live, process-wide objects regardless of whether accessed as globals or via `import { tables } from 'harper'`.