@harperfast/template-vue-studio 1.5.21 → 1.5.23

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

@@ -8,10 +8,11 @@ Guidelines for building scalable, secure, and performant applications on Harper.
 
 1. [Schema & Data Design](#1-schema--data-design) — **HIGH**
    - 1.1 [Adding Tables with Schemas](#11-adding-tables-with-schemas)
-   - 1.2 [Defining Relationships](#12-defining-relationships)
-   - 1.3 [Vector Indexing](#13-vector-indexing)
-   - 1.4 [Using Blobs](#14-using-blobs)
-   - 1.5 [Handling Binary Data](#15-handling-binary-data)
+   - 1.2 [Schema Design & Tooling](#12-schema-design--tooling)
+   - 1.3 [Defining Relationships](#13-defining-relationships)
+   - 1.4 [Vector Indexing](#14-vector-indexing)
+   - 1.5 [Using Blobs](#15-using-blobs)
+   - 1.6 [Handling Binary Data](#16-handling-binary-data)
 2. [API & Communication](#2-api--communication) — **HIGH**
    - 2.1 [Automatic REST APIs](#21-automatic-rest-apis)
    - 2.2 [Querying REST APIs](#22-querying-rest-apis)
@@ -61,7 +62,66 @@ type ExamplePerson @table @export {
 }
 ```
 
-### 1.2 Defining Relationships
+### 1.2 Schema Design & Tooling
+
+Harper uses GraphQL schemas to define database tables, relationships, and APIs. To ensure the best development experience for both humans and AI agents, it's important to understand the core directives and configure your project tooling correctly.
+
+#### Core Harper Directives
+
+Harper extends GraphQL with custom directives that define database behavior. These are typically defined in `node_modules/harperdb/schema.graphql`. If you don't have access to that file, here is a reference of the most important ones:
+
+##### Table Definition
+- `@table`: Marks a GraphQL type as a Harper database table.
+- `@export`: Automatically generates REST and WebSocket APIs for the table.
+- `@table(expiration: Int)`: Configures a time-to-expire for records in the table (useful for caching).
+
+##### Attribute Constraints & Indexing
+- `@primaryKey`: Specifies the unique identifier for the table.
+- `@indexed`: Creates a standard index on the field for faster lookups.
+- `@indexed(type: "HNSW", distance: "cosine" | "euclidean" | "dot")`: Creates a vector index for similarity search.
+
+##### Relationships
+- `@relationship(from: String)`: Defines a relationship to another table. `from` specifies the local field holding the foreign key.
+
+##### Authentication & Authorization
+- `@auth(role: String)`: Restricts access to a table or field based on user roles.
+
+#### Configuring GraphQL Tooling
+
+To get the best IDE support (autocompletion, validation) and to help AI agents understand your schema context, you should create a `graphql.config.yml` file in your project root.
+
+This file tells GraphQL tools where to find Harper's built-in types and directives alongside your own schema files.
+
+##### Creating `graphql.config.yml`
+
+Create a file named `graphql.config.yml` in your project root with the following content:
+
+```yaml
+schema:
+  - "node_modules/harperdb/schema.graphql"
+  - "schema.graphql"
+  - "schemas/*.graphql"
+```
+
+##### Why this is important:
+1. **Shared Directives**: It includes `@table`, `@primaryKey`, etc., so they aren't marked as "unknown directives".
+2. **Context for Agents**: When an agent reads your project, seeing this config helps it locate the core Harper definitions, leading to more accurate code generation.
+3. **Consistency**: The `npm create harper@latest` command includes this by default. Manually adding it to existing projects ensures they follow the same standards.
+
+#### Example Project Structure
+
+A typical Harper project with proper schema tooling:
+
+```text
+my-harper-app/
+├── config.yaml
+├── graphql.config.yml
+├── package.json
+├── schema.graphql
+└── resources.js
+```
+
+### 1.3 Defining Relationships
 
 Using the `@relationship` directive to link tables.
 
@@ -105,7 +165,7 @@ type Category @table @export {
 }
 ```
 
-### 1.3 Vector Indexing
+### 1.4 Vector Indexing
 
 How to define and use vector indexes for efficient similarity search.
 
@@ -130,7 +190,7 @@ type Document @table @export {
 }
 ```
 
-### 1.4 Using Blobs
+### 1.5 Using Blobs
 
 How to store and retrieve large data in Harper.
 
@@ -144,7 +204,7 @@ Use this when you need to store large, unstructured data such as files, images,
 2. **Storing Data**: Send the data as a buffer or a stream when creating or updating a record.
 3. **Retrieving Data**: Access the blob field, which will return the data as a stream or buffer.
 
-### 1.5 Handling Binary Data
+### 1.6 Handling Binary Data
 
 How to store and serve binary data like images or MP3s.
 
@@ -185,11 +245,12 @@ How to use filters, operators, sorting, and pagination in REST requests.
 
 #### Query Parameters
 
-- `limit`: Number of records to return.
-- `offset`: Number of records to skip.
-- `sort`: Field to sort by.
-- `order`: `asc` or `desc`.
-- `filter`: JSON object for filtering.
+- `limit(count)` or `limit(offset, count)`: Number of records to return and optional skip. Example: `?limit(10)`, `?limit(10, 20)`.
+- `sort(+field1, -field2)`: Fields to sort by. Use `+` for ascending and `-` for descending. Example: `?sort(+name)`, `?sort(-price, +name)`.
+- `select(field1, field2)`: Specific fields to return. Example: `?select(id, name)`.
+- `filter`: Advanced filtering using comparison operators and logic.
+  - Operators: `gt`, `ge`, `lt`, `le`, `ne`. Example: `?price=gt=100`.
+  - Logic: `&` (AND), `|` (OR), `()` (grouping). Example: `?(category=electronics|category=books)&price=lt=500`.
 
 ### 2.3 Real-time Applications
 
@@ -232,8 +293,13 @@ How to define custom REST endpoints using JavaScript or TypeScript.
 #### How It Works
 
 1. **Create Resource File**: Define your logic in a JS or TS file.
-2. **Export Handlers**: Export functions like `GET`, `POST`, etc.
-3. **Registration**: Ensure the resource is correctly registered in your application configuration.
+2. **Define Resource Class**: Export a class extending `Resource` from `harperdb`.
+3. **Implement HTTP Methods**: Add methods like `get`, `post`, `put`, `patch`, or `delete` to handle corresponding requests.
+4. **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/`.
+5. **Registration**: Ensure the resource is correctly registered in your application configuration.
 
 ### 3.2 Extending Table Resources
 

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

@@ -52,6 +52,7 @@ 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)
@@ -85,6 +86,7 @@ Read individual rule files for detailed explanations and code examples:
 
 ```
 rules/adding-tables-with-schemas.md
+rules/schema-design-tooling.md
 rules/automatic-apis.md
 rules/creating-harper-apps.md
 ```

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

@@ -27,11 +27,15 @@ Use this skill when the automatic CRUD operations provided by `@table @export` a
    }
    ```
 
-4. **Implement HTTP Methods**: Add methods like `get`, `post`, `put`, `patch`, or `delete` to handle corresponding requests. Note that paths are **case-sensitive** and match the class name.
-5. **Access Tables (Optional)**: Import and use the `tables` object to interact with your data:
+4. **Implement HTTP Methods**: Add methods like `get`, `post`, `put`, `patch`, or `delete` to handle corresponding requests.
+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 'harperdb';
    // ... inside a method
    const results = await tables.MyTable.list();
    ```
-6. **Configure Loading**: Ensure `config.yaml` points to your resource files (e.g., `jsResource: { files: 'resources/*.ts' }`).
+7. **Configure Loading**: Ensure `config.yaml` points to your resource files (e.g., `jsResource: { files: 'resources/*.ts' }`).

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

@@ -17,6 +17,11 @@ Use this skill when you need to perform advanced data retrieval (filtering, sort
 2. **Use Comparison Operators**: Append operators like `gt`, `ge`, `lt`, `le`, `ne` using FIQL-style syntax: `GET /Table/?price=gt=100`.
 3. **Apply Logic and Grouping**: Use `&` for AND, `|` for OR, and `()` for grouping: `GET /Table/?(rating=5|featured=true)&price=lt=50`.
 4. **Select Specific Fields**: Use `select()` to limit returned attributes: `GET /Table/?select(name,price)`.
-5. **Paginate Results**: Use `limit(count)` or `limit(offset, count)`: `GET /Table/?limit(20, 10)`.
-6. **Sort Results**: Use `sort()` with `+` (asc) or `-` (desc): `GET /Table/?sort(-price,+name)`.
+5. **Paginate Results**: Use `limit(count)` or `limit(offset, count)` to set the number of records to return and skip.
+   - Example (first 10): `GET /Table/?limit(10)`
+   - Example (skip 20, return 10): `GET /Table/?limit(20, 10)`
+6. **Sort Results**: Use `sort()` with `+` (asc) or `-` (desc) before the field name. Avoid `sort=field` format.
+   - Example (asc): `GET /Table/?sort(+name)`
+   - Example (desc): `GET /Table/?sort(-price)`
+   - Example (combined): `GET /Table/?sort(-price,+name)`
 7. **Query Relationships**: Use dot syntax for tables linked with `@relationship`: `GET /Book/?author.name=Harper`.

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

@@ -0,0 +1,63 @@
+---
+name: schema-design-tooling
+description: Best practices for Harper schema design, including core directives and GraphQL tooling configuration.
+---
+
+# Schema Design & Tooling
+
+Harper uses GraphQL schemas to define database tables, relationships, and APIs. To ensure the best development experience for both humans and AI agents, it's important to understand the core directives and configure your project tooling correctly.
+
+## Core Harper Directives
+
+Harper extends GraphQL with custom directives that define database behavior. These are typically defined in `node_modules/harperdb/schema.graphql`. If you don't have access to that file, here is a reference of the most important ones:
+
+### Table Definition
+- `@table`: Marks a GraphQL type as a Harper database table.
+- `@export`: Automatically generates REST and WebSocket APIs for the table.
+- `@table(expiration: Int)`: Configures a time-to-expire for records in the table (useful for caching).
+
+### Attribute Constraints & Indexing
+- `@primaryKey`: Specifies the unique identifier for the table.
+- `@indexed`: Creates a standard index on the field for faster lookups.
+- `@indexed(type: "HNSW", distance: "cosine" | "euclidean" | "dot")`: Creates a vector index for similarity search.
+
+### Relationships
+- `@relationship(from: String)`: Defines a relationship to another table. `from` specifies the local field holding the foreign key.
+
+### Authentication & Authorization
+- `@auth(role: String)`: Restricts access to a table or field based on user roles.
+
+## Configuring GraphQL Tooling
+
+To get the best IDE support (autocompletion, validation) and to help AI agents understand your schema context, you should create a `graphql.config.yml` file in your project root.
+
+This file tells GraphQL tools where to find Harper's built-in types and directives alongside your own schema files.
+
+### Creating `graphql.config.yml`
+
+Create a file named `graphql.config.yml` in your project root with the following content:
+
+```yaml
+schema:
+  - "node_modules/harperdb/schema.graphql"
+  - "schema.graphql"
+  - "schemas/*.graphql"
+```
+
+### Why this is important:
+1. **Shared Directives**: It includes `@table`, `@primaryKey`, etc., so they aren't marked as "unknown directives".
+2. **Context for Agents**: When an agent reads your project, seeing this config helps it locate the core Harper definitions, leading to more accurate code generation.
+3. **Consistency**: The `npm create harper@latest` command includes this by default. Manually adding it to existing projects ensures they follow the same standards.
+
+## Example Project Structure
+
+A typical Harper project with proper schema tooling:
+
+```text
+my-harper-app/
+├── config.yaml
+├── graphql.config.yml
+├── package.json
+├── schema.graphql
+└── resources.js
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/template-vue-studio",
-	"version": "1.5.21",
+	"version": "1.5.23",
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {},

package/skills-lock.json

@@ -4,7 +4,7 @@
     "harper-best-practices": {
       "source": "harperfast/skills",
       "sourceType": "github",
-      "computedHash": "52d86f4580839d4d0badcebeeda01d2aee288f2ab180260c66ae67c55b47b76f"
+      "computedHash": "dc6edafe30ac9800fb009d9ac48b73206e9ba9efc6b9a49268aeb1bb7e8c1b8c"
     }
   }
 }