diff --git a/.github/workflows/validate-skills.yml b/.github/workflows/validate-skills.yml index 7a2e54b..fb60d18 100644 --- a/.github/workflows/validate-skills.yml +++ b/.github/workflows/validate-skills.yml @@ -2,9 +2,9 @@ name: Validate Skills Schema on: push: - branches: [ main ] + branches: [main] pull_request: - branches: [ main ] + branches: [main] jobs: validate: diff --git a/.oxfmtrc.json b/.oxfmtrc.json new file mode 100644 index 0000000..70a38e3 --- /dev/null +++ b/.oxfmtrc.json @@ -0,0 +1,6 @@ +{ + "$schema": "./node_modules/oxfmt/configuration_schema.json", + "ignorePatterns": [], + "singleQuote": true, + "useTabs": true +} diff --git a/.releaserc.json b/.releaserc.json index 57ad559..3f1bb97 100644 --- a/.releaserc.json +++ b/.releaserc.json @@ -1,7 +1,5 @@ { - "branches": [ - "main" - ], + "branches": ["main"], "plugins": [ [ "@semantic-release/commit-analyzer", @@ -22,10 +20,7 @@ } ], "parserOpts": { - "noteKeywords": [ - "BREAKING CHANGE", - "BREAKING CHANGES" - ] + "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"] } } ], @@ -39,10 +34,7 @@ [ "@semantic-release/git", { - "assets": [ - "package.json", - "package-lock.json" - ] + "assets": ["package.json", "package-lock.json"] } ], "@semantic-release/github" diff --git a/README.md b/README.md index 8ab41c5..5a7629f 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,9 @@ Re-run this command later if you want to get the latest updates from us. ## Available Skills ### [Harper Best Practices](harper-best-practices/SKILL.md) + Comprehensive guidelines for building, extending, and deploying Harper applications. Covers: + - Schema design and relationships. - Automatic REST and WebSocket APIs. - Custom resources and table extensions. diff --git a/commitlint.config.cjs b/commitlint.config.cjs index 7ba2a99..0327923 100644 --- a/commitlint.config.cjs +++ b/commitlint.config.cjs @@ -1,17 +1,8 @@ module.exports = { extends: ['@commitlint/config-conventional'], rules: { - 'subject-case': [ - 0, - 'never', - ], - 'body-max-line-length': [ - 0, - 'never', - ], - 'footer-max-line-length': [ - 0, - 'never', - ], + 'subject-case': [0, 'never'], + 'body-max-line-length': [0, 'never'], + 'footer-max-line-length': [0, 'never'], }, }; diff --git a/harper-best-practices/AGENTS.md b/harper-best-practices/AGENTS.md index d87c251..dc89333 100644 --- a/harper-best-practices/AGENTS.md +++ b/harper-best-practices/AGENTS.md @@ -40,16 +40,19 @@ Guidelines for building scalable, secure, and performant applications on Harper. Instructions for the agent to follow when adding tables to a Harper database. #### When to Use + Use this skill when you need to define new data structures or modify existing ones in a Harper database. -#### Steps +#### 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`. -3. **Define Relationships**: Link tables together using the `@relationship` directive. -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. +3. **Define Relationships**: Link tables together using the `@relationship` directive. +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. 5. **Consider Table Extensions**: If you are going to extend the table in your resources, then do not `@export` the table from the schema. #### Example + ```graphql type ExamplePerson @table @export { id: ID @primaryKey @@ -63,29 +66,42 @@ type ExamplePerson @table @export { Using the `@relationship` directive to link tables. #### When to Use + Use this when you have two or more tables that need to be logically linked (e.g., a "Product" table and a "Category" table). -#### Steps -1. **Identify the Relationship**: Determine which table should "own" the relationship. This is typically the table that will hold the foreign key. +#### How It Works + +1. **Identify the Relationship Type**: Determine if it's one-to-one, many-to-one, or one-to-many. 2. **Apply the `@relationship` Directive**: In your GraphQL schema, use the `@relationship` directive on the field that links to another table. -3. **Specify the `name` and `path` Arguments**: - - `name`: A unique name for the relationship. - - `path`: The field name in the current table that holds the value to match in the related table. -4. **Define the Inverse Relationship (Optional but Recommended)**: For better queryability, define the relationship in the related table as well. + - **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 + ```graphql type Product @table @export { - id: ID @primaryKey - name: String - category: Category @relationship(name: "product_category", path: "category_id") - category_id: ID + id: ID @primaryKey + name: String + categoryId: ID + category: Category @relationship(from: "categoryId") } type Category @table @export { - id: ID @primaryKey - name: String - products: [Product] @relationship(name: "product_category", path: "id") + id: ID @primaryKey + name: String + products: [Product] @relationship(to: "categoryId") } ``` @@ -94,31 +110,36 @@ type Category @table @export { How to define and use vector indexes for efficient similarity search. #### When to Use + Use this when you need to perform similarity searches on high-dimensional data, such as image embeddings, text embeddings, or any other numeric vectors. -#### Steps +#### How It Works + 1. **Define the Vector Field**: In your GraphQL schema, define a field with a list of floats (e.g., `[Float]`). 2. **Apply the `@indexed` Directive**: Use the `@indexed` directive on the vector field and specify the index type as `vector`. 3. **Configure the Index (Optional)**: You can provide additional configuration for the vector index, such as the distance metric (e.g., `cosine`, `euclidean`). 4. **Querying**: Use the `vector` operator in your REST or programmatic requests to perform similarity searches. #### Example + ```graphql type Document @table @export { - id: ID @primaryKey - content: String - embedding: [Float] @indexed(type: "vector", options: { dims: 1536, metric: "cosine" }) + id: ID @primaryKey + content: String + embedding: [Float] @indexed(type: "vector", options: { dims: 1536, metric: "cosine" }) } ``` ### 1.4 Using Blobs -How to store and retrieve large data in HarperDB. +How to store and retrieve large data in Harper. #### When to Use + Use this when you need to store large, unstructured data such as files, images, or large text documents that exceed the typical size of a standard database field. -#### Steps +#### How It Works + 1. **Define the Blob Field**: Use the `Blob` scalar type in your GraphQL schema. 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. @@ -128,10 +149,12 @@ Use this when you need to store large, unstructured data such as files, images, How to store and serve binary data like images or MP3s. #### When to Use + Use this when your application needs to handle binary files, particularly for storage and retrieval. -#### Steps -1. **Use the `Blob` type**: As with general large data, the `Blob` type is best for binary files. +#### How It Works + +1. **Use the `Blob` type**: As with general large data, the `Blob` type is best for binary files. Ensure you store and retrieve the appropriate MIME type (e.g., `image/jpeg`, `audio/mpeg`) for the data. 2. **Streaming**: For large files, use streaming to minimize memory usage during upload and download. 3. **MIME Types**: Store the MIME type alongside the binary data to ensure it is served correctly by your application logic. @@ -146,6 +169,7 @@ Use this when your application needs to handle binary files, particularly for st Details on the CRUD endpoints automatically generated for exported tables. #### Endpoints + - `GET /{TableName}`: Describes the schema. - `GET /{TableName}/`: Lists records (supports filtering/sorting). - `GET /{TableName}/{id}`: Gets a record by ID. @@ -160,6 +184,7 @@ Details on the CRUD endpoints automatically generated for exported tables. 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. @@ -171,10 +196,12 @@ How to use filters, operators, sorting, and pagination in REST requests. Implementing WebSockets and Pub/Sub for live data updates. #### When to Use + Use this for applications that require live updates, such as chat apps, live dashboards, or collaborative tools. -#### Steps -1. **WebSocket Connection**: Connect to the Harper WebSocket endpoint. +#### How It Works + +1. **WebSocket Connection**: Connect to the Harper WebSocket endpoint. Use `wss://` for secure connections over HTTPS, or `ws://` for local development. 2. **Subscribing**: Subscribe to table updates or specific records. 3. **Pub/Sub**: Use the internal bus to publish and subscribe to custom events. @@ -183,9 +210,11 @@ Use this for applications that require live updates, such as chat apps, live das How to use sessions to verify user identity and roles. #### When to Use + Use this to secure your application by ensuring that only authorized users can access certain resources or perform specific actions. -#### Steps +#### How It Works + 1. **Session Handling**: Access the session object from the request context. 2. **Identity Verification**: Check for the presence of a user ID or token. 3. **Role Checks**: Verify if the user has the required roles for the action. @@ -200,7 +229,8 @@ Use this to secure your application by ensuring that only authorized users can a How to define custom REST endpoints using JavaScript or TypeScript. -#### Steps +#### 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. @@ -209,7 +239,8 @@ How to define custom REST endpoints using JavaScript or TypeScript. Adding custom logic to automatically generated table resources. -#### Steps +#### How It Works + 1. **Define Extension**: Create a resource file that targets an existing table. 2. **Intercept Requests**: Use handlers to add custom validation or data transformation. 3. **No `@export`**: If extending, remember not to `@export` the table in the schema. @@ -219,6 +250,7 @@ Adding custom logic to automatically generated table resources. How to use filters, operators, sorting, and pagination in programmatic table requests. #### Usage + When writing custom resources, use the internal API to query tables with full support for advanced filtering and sorting. ### 3.4 TypeScript Type Stripping @@ -226,6 +258,7 @@ When writing custom resources, use the internal API to query tables with full su Using TypeScript directly without build tools via Node.js Type Stripping. #### Configuration + Harper supports native TypeScript type stripping, allowing you to run `.ts` files directly. Ensure your environment is configured to take advantage of this for faster development cycles. ### 3.5 Caching @@ -233,6 +266,7 @@ Harper supports native TypeScript type stripping, allowing you to run `.ts` file How caching is defined and implemented in Harper applications. #### Strategies + - **In-memory**: For fast access to frequently used data. - **Distributed**: For scaling across multiple nodes in Harper Fabric. @@ -247,22 +281,27 @@ How caching is defined and implemented in Harper applications. The fastest way to start a new Harper project is using the `create-harper` CLI tool. This command initializes a project with a standard folder structure, essential configuration files, and basic schema definitions. #### When to Use + Use this command when starting a new Harper application or adding a new Harper microservice to an existing architecture. #### Commands + Initialize a project using your preferred package manager: **NPM** + ```bash npm create harper@latest ``` **PNPM** + ```bash pnpm create harper@latest ``` **Bun** + ```bash bun create harper@latest ``` @@ -271,7 +310,7 @@ bun create harper@latest Follow these steps to set up your Harper Fabric environment for deployment. -#### Steps +#### How It Works 1. **Sign Up/In**: Go to [https://fabric.harper.fast/](https://fabric.harper.fast/) and sign up or sign in. 2. **Create an Organization**: Create an organization (org) to manage your projects. @@ -290,11 +329,13 @@ Follow these steps to set up your Harper Fabric environment for deployment. Globally scaling your Harper application. #### Benefits + - **Global Distribution**: Low latency for users everywhere. - **Automatic Sync**: Data is synced across the fabric automatically. - **Free Tier**: Start for free and scale as you grow. -#### Steps +#### How It Works + 1. **Sign up**: Follow the [Creating a Fabric Account and Cluster](#42-creating-a-fabric-account-and-cluster) steps to create a Harper Fabric account, organization, and cluster. 2. **Configure Environment**: Add your cluster credentials and cluster application URL to `.env`: ```bash @@ -309,33 +350,33 @@ Globally scaling your Harper application. If your application was not created with `npm create harper`, you'll need to manually configure the deployment scripts and CI/CD workflow. -##### 1. Update `package.json` +#### 1. Update `package.json` Add the following scripts and dependencies to your `package.json`: ```json { - "scripts": { - "deploy": "dotenv -- npm run deploy:component", - "deploy:component": "harperdb deploy_component . restart=rolling replicated=true" - }, - "devDependencies": { - "dotenv-cli": "^11.0.0", - "harperdb": "^4.7.20" - } + "scripts": { + "deploy": "dotenv -- npm run deploy:component", + "deploy:component": "harperdb deploy_component . restart=rolling replicated=true" + }, + "devDependencies": { + "dotenv-cli": "^11.0.0", + "harperdb": "^4.7.20" + } } ``` -###### Why split the scripts? +#### Why split the scripts? -The `deploy` script is separated from `deploy:component` to ensure environment variables from your `.env` file are properly loaded and passed to the Harper CLI. +The `deploy` script is separated from `deploy:component` to ensure environment variables from your `.env` file are properly loaded and passed to the Harper CLI. - `deploy`: Uses `dotenv-cli` to load environment variables (like `CLI_TARGET`, `CLI_TARGET_USERNAME`, and `CLI_TARGET_PASSWORD`) before executing the next command. -- `deploy:component`: The actual command that performs the deployment. +- `deploy:component`: The actual command that performs the deployment. By using `dotenv -- npm run deploy:component`, the environment variables are correctly set in the shell session before `harperdb deploy_component` is called, allowing it to authenticate with your cluster. -##### 2. Configure GitHub Actions +#### 2. Configure GitHub Actions Create a `.github/workflows/deploy.yaml` file with the following content: @@ -368,9 +409,14 @@ jobs: run: npm run lint - name: Deploy run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + CLI_TARGET_USERNAME: ${{ secrets.CLI_TARGET_USERNAME }} + CLI_TARGET_PASSWORD: ${{ secrets.CLI_TARGET_PASSWORD }} ``` Be sure to set the following repository secrets in your GitHub repository: + - `CLI_TARGET` - `CLI_TARGET_USERNAME` - `CLI_TARGET_PASSWORD` @@ -380,5 +426,6 @@ Be sure to set the following repository secrets in your GitHub repository: Two ways to serve web content from a Harper application. #### Methods -1. **Static Serving**: Serve HTML, CSS, and JS files directly. + +1. **Static Serving**: Serve HTML, CSS, and JS files directly. If using the Vite plugin for development, ensure Harper is running (e.g., `harperdb run .`) to allow for Hot Module Replacement (HMR). 2. **Dynamic Rendering**: Use custom resources to render content on the fly. diff --git a/harper-best-practices/SKILL.md b/harper-best-practices/SKILL.md index 4c1be3d..e0e9b14 100644 --- a/harper-best-practices/SKILL.md +++ b/harper-best-practices/SKILL.md @@ -1,7 +1,6 @@ --- name: harper-best-practices -description: - Best practices for building Harper applications, covering schema definition, +description: Best practices for building Harper applications, covering schema definition, automatic APIs, authentication, custom resources, and data handling. Triggers on tasks involving Harper database design, API implementation, and deployment. @@ -26,7 +25,7 @@ Reference these guidelines when: - Optimizing data storage and retrieval (Blobs, Vector Indexing) - Deploying applications to Harper Fabric -## Steps +## How It Works 1. Review the requirements for the task (schema design, API needs, or infrastructure setup). 2. Consult the relevant category under "Rule Categories by Priority" to understand the impact of your decisions. @@ -35,14 +34,18 @@ Reference these guidelines when: 5. If you're extending functionality, consult the `logic-` and `api-` rules. 6. Validate your implementation against the `ops-` rules before deployment. +## Examples + +See the concrete examples embedded in each rule subsection below (GraphQL schemas, REST query patterns, and deployment workflow snippets). + ## Rule Categories by Priority -| Priority | Category | Impact | Prefix | -| -------- | ----------------------- | ------ | --------------- | -| 1 | Schema & Data Design | HIGH | `schema-` | -| 2 | API & Communication | HIGH | `api-` | -| 3 | Logic & Extension | MEDIUM | `logic-` | -| 4 | Infrastructure & Ops | MEDIUM | `ops-` | +| Priority | Category | Impact | Prefix | +| -------- | -------------------- | ------ | --------- | +| 1 | Schema & Data Design | HIGH | `schema-` | +| 2 | API & Communication | HIGH | `api-` | +| 3 | Logic & Extension | MEDIUM | `logic-` | +| 4 | Infrastructure & Ops | MEDIUM | `ops-` | ## Quick Reference @@ -58,7 +61,7 @@ Reference these guidelines when: - `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 live data updates +- `real-time-apps` - WebSockets and Pub/Sub for Real-Time Apps - `checking-authentication` - Secure apps with session-based identity verification ### 3. Logic & Extension (MEDIUM) diff --git a/harper-best-practices/rules/adding-tables-with-schemas.md b/harper-best-practices/rules/adding-tables-with-schemas.md index 99081ee..3849850 100644 --- a/harper-best-practices/rules/adding-tables-with-schemas.md +++ b/harper-best-practices/rules/adding-tables-with-schemas.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when adding tables to a Harper database. Use this skill when you need to define new data structures or modify existing ones in a Harper database. -## Steps +## 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`. @@ -27,7 +27,7 @@ Use this skill when you need to define new data structures or modify existing on - `DELETE /{TableName}/{id}`: Deletes a single record by its ID. 5. **Consider Table Extensions**: If you are going to [extend the table](./extending-tables.md) in your resources, then do not `@export` the table from the schema. -### Example +## Examples In a hypothetical `schemas/ExamplePerson.graphql`: diff --git a/harper-best-practices/rules/automatic-apis.md b/harper-best-practices/rules/automatic-apis.md index 09b9f7e..a737877 100644 --- a/harper-best-practices/rules/automatic-apis.md +++ b/harper-best-practices/rules/automatic-apis.md @@ -11,24 +11,27 @@ Instructions for the agent to follow when utilizing Harper's automatic APIs. 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. -## Steps - -1. **Enable Automatic APIs**: Ensure your GraphQL schema includes the `@export` directive for the table: - ```graphql - type MyTable @table @export { - id: ID @primaryKey - # ... other fields - } - ``` -2. **Access REST Endpoints**: Use the following endpoints for a table named `TableName` (Note: Paths are **case-sensitive**): - - **Describe Schema**: `GET /{TableName}` - - **List Records**: `GET /{TableName}/` (Supports filtering, sorting, and pagination. See [Querying REST APIs](querying-rest-apis.md)). - - **Get Single Record**: `GET /{TableName}/{id}` - - **Create Record**: `POST /{TableName}/` (Request body should be JSON). - - **Update Record (Full)**: `PUT /{TableName}/{id}` - - **Update Record (Partial)**: `PATCH /{TableName}/{id}` - - **Delete All/Filtered Records**: `DELETE /{TableName}/` - - **Delete Single Record**: `DELETE /{TableName}/{id}` -3. **Use Automatic WebSockets**: Connect to `ws://your-harper-instance/{TableName}` to receive events whenever updates are made to that table. This is the easiest way to add real-time capabilities. For more complex needs, see [Real-time Applications](real-time-apps.md). +## 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). + +## Examples + +### Schema Configuration + +```graphql +type MyTable @table @export { + id: ID @primaryKey + name: String +} +``` + +### Common REST Operations + +- **List Records**: `GET /MyTable/` +- **Create Record**: `POST /MyTable/` +- **Update Record**: `PATCH /MyTable/{id}` diff --git a/harper-best-practices/rules/caching.md b/harper-best-practices/rules/caching.md index d441f75..88ebe8e 100644 --- a/harper-best-practices/rules/caching.md +++ b/harper-best-practices/rules/caching.md @@ -11,36 +11,40 @@ Instructions for the agent to follow when implementing caching in Harper. 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. -## Steps - -1. **Configure a Cache Table**: Define a table in your `schema.graphql` with an `expiration` (in seconds): - ```graphql - type MyCache @table(expiration: 3600) @export { - id: ID @primaryKey - } - ``` -2. **Define an External Source**: Create a Resource class that fetches the data: - ```js - import { Resource } from 'harperdb'; - - export class ThirdPartyAPI extends Resource { - 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'); - } - return await response.json(); - } - } - ``` -3. **Attach Source to Table**: Use `sourcedFrom` to link your resource to the table: - ```js - import { tables } from 'harperdb'; - import { ThirdPartyAPI } from './ThirdPartyAPI.js'; - - const { MyCache } = tables; - MyCache.sourcedFrom(ThirdPartyAPI); - ``` -4. **Implement Active Caching (Optional)**: Use `subscribe()` for proactive updates. See [Real Time Apps](real-time-apps.md). +## 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. + +## Examples + +### Schema Configuration + +```graphql +type MyCache @table(expiration: 3600) @export { + id: ID @primaryKey +} +``` + +### Resource Implementation + +```js +import { Resource, tables } from 'harperdb'; + +export class ThirdPartyAPI extends Resource { + 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'); + } + return await response.json(); + } +} + +// Attach source to table +tables.MyCache.sourcedFrom(ThirdPartyAPI); +``` diff --git a/harper-best-practices/rules/checking-authentication.md b/harper-best-practices/rules/checking-authentication.md index fafd213..1898181 100644 --- a/harper-best-practices/rules/checking-authentication.md +++ b/harper-best-practices/rules/checking-authentication.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when handling authentication and sessions. Use this skill when you need to implement sign-in/sign-out functionality, protect specific resource endpoints, or identify the currently logged-in user in a Harper application. -## Steps +## How It Works 1. **Configure Harper for Sessions**: Ensure `harperdb-config.yaml` has sessions enabled and local auto-authorization disabled for testing: ```yaml @@ -20,19 +20,19 @@ Use this skill when you need to implement sign-in/sign-out functionality, protec enableSessions: true ``` 2. **Implement Sign In**: Use `this.getContext().login(username, password)` to create a session: - ```ts + ```typescript async post(_target, data) { - const context = this.getContext(); - try { - await context.login(data.username, data.password); - } catch { - return new Response('Invalid credentials', { status: 403 }); - } - return new Response('Logged in', { status: 200 }); + const context = this.getContext(); + try { + await context.login(data.username, data.password); + } catch { + return new Response('Invalid credentials', { status: 403 }); + } + return new Response('Logged in', { status: 200 }); } ``` 3. **Identify Current User**: Use `this.getCurrentUser()` to access session data: - ```ts + ```typescript async get() { const user = this.getCurrentUser?.(); if (!user) return new Response(null, { status: 401 }); @@ -40,7 +40,7 @@ Use this skill when you need to implement sign-in/sign-out functionality, protec } ``` 4. **Implement Sign Out**: Use `this.getContext().logout()` or delete the session from context: - ```ts + ```typescript async post() { const context = this.getContext(); await context.session?.delete?.(context.session.id); @@ -49,6 +49,42 @@ Use this skill when you need to implement sign-in/sign-out functionality, protec ``` 5. **Protect Routes**: In your Resource, use `allowRead()`, `allowUpdate()`, etc., to enforce authorization logic based on `this.getCurrentUser()`. For privileged actions, verify `user.role.permission.super_user`. +## Examples + +### Sign In Implementation + +```typescript +async post(_target, data) { + const context = this.getContext(); + try { + await context.login(data.username, data.password); + } catch { + return new Response('Invalid credentials', { status: 403 }); + } + return new Response('Logged in', { status: 200 }); +} +``` + +### Identify Current User + +```typescript +async get() { + const user = this.getCurrentUser?.(); + if (!user) return new Response(null, { status: 401 }); + return { username: user.username, role: user.role }; +} +``` + +### Sign Out Implementation + +```typescript +async post() { + const context = this.getContext(); + await context.session?.delete?.(context.session.id); + return new Response('Logged out', { status: 200 }); +} +``` + ## Status code conventions used here - 200: Successful operation. For `GET /me`, a `200` with empty body means “not signed in”. @@ -77,9 +113,9 @@ This project includes two Resource patterns for that flow: - with an existing Authorization token (either Basic Auth or a JWT) and you want to issue new tokens, or - from an explicit `{ username, password }` payload (useful for direct “login” from a CLI/mobile client). -```js +```javascript export class IssueTokens extends Resource { -static loadAsInstance = false; + static loadAsInstance = false; async get(target) { const { refresh_token: refreshToken, operation_token: jwt } = @@ -118,9 +154,9 @@ static loadAsInstance = false; **Description / use case:** When the JWT expires, the client uses the refresh token to get a new JWT without re-supplying username/password. -```js +```javascript export class RefreshJWT extends Resource { -static loadAsInstance = false; + static loadAsInstance = false; async post(target, data) { if (!data.refreshToken) { diff --git a/harper-best-practices/rules/creating-a-fabric-account-and-cluster.md b/harper-best-practices/rules/creating-a-fabric-account-and-cluster.md index 2a2a1da..0c5bf61 100644 --- a/harper-best-practices/rules/creating-a-fabric-account-and-cluster.md +++ b/harper-best-practices/rules/creating-a-fabric-account-and-cluster.md @@ -7,17 +7,22 @@ description: How to create a Harper Fabric account, organization, and cluster. Follow these steps to set up your Harper Fabric environment for deployment. -## Steps +## How It Works 1. **Sign Up/In**: Go to [https://fabric.harper.fast/](https://fabric.harper.fast/) and sign up or sign in. 2. **Create an Organization**: Create an organization (org) to manage your projects. 3. **Create a Cluster**: Create a new cluster. This can be on the free tier, no credit card required. 4. **Set Credentials**: During setup, set the cluster username and password to finish configuring it. 5. **Get Application URL**: Navigate to the **Config** tab and copy the **Application URL**. -6. **Configure Environment**: Update your `.env` file or GitHub Actions secrets with these cluster-specific credentials: - ```bash - CLI_TARGET_USERNAME='YOUR_CLUSTER_USERNAME' - CLI_TARGET_PASSWORD='YOUR_CLUSTER_PASSWORD' - CLI_TARGET='YOUR_CLUSTER_URL' - ``` +6. **Configure Environment**: Update your `.env` file or GitHub Actions secrets with cluster-specific credentials. 7. **Next Steps**: See the [deploying-to-harper-fabric](deploying-to-harper-fabric.md) rule for detailed instructions on deploying your application successfully. + +## Examples + +### Environment Configuration + +```bash +CLI_TARGET_USERNAME='YOUR_CLUSTER_USERNAME' +CLI_TARGET_PASSWORD='YOUR_CLUSTER_PASSWORD' +CLI_TARGET='YOUR_CLUSTER_URL' +``` diff --git a/harper-best-practices/rules/creating-harper-apps.md b/harper-best-practices/rules/creating-harper-apps.md index 2daf45c..d9cd55f 100644 --- a/harper-best-practices/rules/creating-harper-apps.md +++ b/harper-best-practices/rules/creating-harper-apps.md @@ -16,16 +16,19 @@ Use this command when starting a new Harper application or adding a new Harper m Initialize a project using your preferred package manager: ### NPM + ```bash npm create harper@latest ``` ### PNPM + ```bash pnpm create harper@latest ``` ### Bun + ```bash bun create harper@latest ``` diff --git a/harper-best-practices/rules/custom-resources.md b/harper-best-practices/rules/custom-resources.md index 79b9f04..7082321 100644 --- a/harper-best-practices/rules/custom-resources.md +++ b/harper-best-practices/rules/custom-resources.md @@ -11,11 +11,12 @@ Instructions for the agent to follow when creating custom resources in Harper. 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. -## Steps +## 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 `harperdb`: + ```typescript import { type RequestTargetOrId, Resource } from 'harperdb'; @@ -25,6 +26,7 @@ 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: ```typescript diff --git a/harper-best-practices/rules/defining-relationships.md b/harper-best-practices/rules/defining-relationships.md index 6cc4911..5471faa 100644 --- a/harper-best-practices/rules/defining-relationships.md +++ b/harper-best-practices/rules/defining-relationships.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when defining relationships between Harper Use this skill when you need to link data across different tables, enabling automatic joins and efficient related-data fetching via REST APIs. -## Steps +## 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. diff --git a/harper-best-practices/rules/deploying-to-harper-fabric.md b/harper-best-practices/rules/deploying-to-harper-fabric.md index 2e65a6b..6a1f2f9 100644 --- a/harper-best-practices/rules/deploying-to-harper-fabric.md +++ b/harper-best-practices/rules/deploying-to-harper-fabric.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when deploying to Harper Fabric. Use this skill when you are ready to move your Harper application from local development to a cloud-hosted environment. -## Steps +## How It Works 1. **Sign up**: Follow the [creating-a-fabric-account-and-cluster](creating-a-fabric-account-and-cluster.md) rule to create a Harper Fabric account, organization, and cluster. 2. **Configure Environment**: Add your cluster credentials and cluster application URL to `.env`: @@ -33,23 +33,23 @@ Add the following scripts and dependencies to your `package.json`: ```json { - "scripts": { - "deploy": "dotenv -- npm run deploy:component", - "deploy:component": "harperdb deploy_component . restart=rolling replicated=true" - }, - "devDependencies": { - "dotenv-cli": "^11.0.0", - "harperdb": "^4.7.20" - } + "scripts": { + "deploy": "dotenv -- npm run deploy:component", + "deploy:component": "harperdb deploy_component . restart=rolling replicated=true" + }, + "devDependencies": { + "dotenv-cli": "^11.0.0", + "harperdb": "^4.7.20" + } } ``` #### Why split the scripts? -The `deploy` script is separated from `deploy:component` to ensure environment variables from your `.env` file are properly loaded and passed to the Harper CLI. +The `deploy` script is separated from `deploy:component` to ensure environment variables from your `.env` file are properly loaded and passed to the Harper CLI. - `deploy`: Uses `dotenv-cli` to load environment variables (like `CLI_TARGET`, `CLI_TARGET_USERNAME`, and `CLI_TARGET_PASSWORD`) before executing the next command. -- `deploy:component`: The actual command that performs the deployment. +- `deploy:component`: The actual command that performs the deployment. By using `dotenv -- npm run deploy:component`, the environment variables are correctly set in the shell session before `harperdb deploy_component` is called, allowing it to authenticate with your cluster. @@ -89,9 +89,14 @@ jobs: run: npm run lint - name: Deploy run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + CLI_TARGET_USERNAME: ${{ secrets.CLI_TARGET_USERNAME }} + CLI_TARGET_PASSWORD: ${{ secrets.CLI_TARGET_PASSWORD }} ``` Be sure to set the following repository secrets in your GitHub repository's /settings/secrets/actions: + - `CLI_TARGET` - `CLI_TARGET_USERNAME` - `CLI_TARGET_PASSWORD` diff --git a/harper-best-practices/rules/extending-tables.md b/harper-best-practices/rules/extending-tables.md index d2cff81..a0597c1 100644 --- a/harper-best-practices/rules/extending-tables.md +++ b/harper-best-practices/rules/extending-tables.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when extending table resources in Harper. 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. -## Steps +## 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. ```graphql @@ -22,16 +22,20 @@ Use this skill when you need to add custom validation, side effects (like webhoo ``` 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`: + ```typescript import { type RequestTargetOrId, tables } from 'harperdb'; export class MyTable extends tables.MyTable { async post(target: RequestTargetOrId, record: any) { // Custom logic here - if (!record.name) { throw new Error('Name required'); } + if (!record.name) { + throw new Error('Name required'); + } return super.post(target, record); } } ``` + 4. **Override Methods**: Override `get`, `post`, `put`, `patch`, or `delete` as needed. Always call `super[method]` to maintain default Harper functionality unless you intend to replace it entirely. 5. **Implement Logic**: Use overrides for validation, side effects, or transforming data before/after database operations. diff --git a/harper-best-practices/rules/handling-binary-data.md b/harper-best-practices/rules/handling-binary-data.md index 630d924..0b536d1 100644 --- a/harper-best-practices/rules/handling-binary-data.md +++ b/harper-best-practices/rules/handling-binary-data.md @@ -11,33 +11,35 @@ Instructions for the agent to follow when handling binary data in Harper. 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. -## Steps +## 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`. Include the MIME type if available: -1. **Store Base64 as Blobs**: In your resource's `post` or `put` method, convert incoming base64 strings to Buffers and then to Blobs using `createBlob`: ```typescript import { createBlob } from 'harperdb'; async post(target, record) { if (record.data) { - record.data = createBlob(Buffer.from(record.data, 'base64'), { - type: 'image/jpeg', + 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`: ```typescript async get(target) { - const record = await super.get(target); - if (record?.data) { - return { - status: 200, - headers: { 'Content-Type': 'image/jpeg' }, - body: record.data, - }; - } - return record; + 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. diff --git a/harper-best-practices/rules/programmatic-table-requests.md b/harper-best-practices/rules/programmatic-table-requests.md index 4518125..70a8a3f 100644 --- a/harper-best-practices/rules/programmatic-table-requests.md +++ b/harper-best-practices/rules/programmatic-table-requests.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when interacting with Harper tables via cod Use this skill when you need to perform database operations (CRUD, search, subscribe) from within Harper Resources or scripts. -## Steps +## 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**: diff --git a/harper-best-practices/rules/querying-rest-apis.md b/harper-best-practices/rules/querying-rest-apis.md index 18a5c8e..70c9e39 100644 --- a/harper-best-practices/rules/querying-rest-apis.md +++ b/harper-best-practices/rules/querying-rest-apis.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when querying Harper's REST APIs. Use this skill when you need to perform advanced data retrieval (filtering, sorting, pagination, joins) using Harper's automatic REST endpoints. -## Steps +## How It Works 1. **Basic Filtering**: Use attribute names as query parameters: `GET /Table/?key=value`. 2. **Use Comparison Operators**: Append operators like `gt`, `ge`, `lt`, `le`, `ne` using FIQL-style syntax: `GET /Table/?price=gt=100`. diff --git a/harper-best-practices/rules/real-time-apps.md b/harper-best-practices/rules/real-time-apps.md index 2ba897e..13d028b 100644 --- a/harper-best-practices/rules/real-time-apps.md +++ b/harper-best-practices/rules/real-time-apps.md @@ -11,27 +11,33 @@ Instructions for the agent to follow when building real-time applications in Har Use this skill when you need to stream live updates to clients, implement chat features, or provide real-time data synchronization between the database and a frontend. -## Steps +## How It Works 1. **Check Automatic WebSockets**: If you only need to stream table changes, use [Automatic APIs](automatic-apis.md) which provide a WebSocket endpoint for every `@export`ed table. -2. **Implement `connect` in a Resource**: For custom bi-directional logic, implement the `connect` method: - ```typescript - import { Resource, tables } from 'harperdb'; - - export class MySocket extends Resource { - async *connect(target, incomingMessages) { - // Subscribe to table changes - const subscription = await tables.MyTable.subscribe(target); - if (!incomingMessages) { return subscription; // SSE mode - } - - // Handle incoming client messages - for await (let message of incomingMessages) { - yield { received: message }; - } - } - } - ``` +2. **Implement `connect` in a Resource**: For custom bi-directional logic, implement the `connect` method. 3. **Use Pub/Sub**: Use `tables.TableName.subscribe(query)` to listen for specific data changes and stream them to the client. 4. **Handle SSE**: Ensure your `connect` method gracefully handles cases where `incomingMessages` is null (Server-Sent Events). -5. **Connect from Client**: Use standard WebSockets (`new WebSocket('ws://...')`) to connect to your resource endpoint. +5. **Connect from Client**: Use standard WebSockets (`new WebSocket('wss://...')`) to connect to your resource endpoint. Ensure you use the appropriate scheme (`ws://` for HTTP, `wss://` for HTTPS). + +## Examples + +### Bi-directional WebSocket Resource + +```typescript +import { Resource, tables } from 'harperdb'; + +export class MySocket extends Resource { + async *connect(target, incomingMessages) { + // Subscribe to table changes + const subscription = await tables.MyTable.subscribe(target); + if (!incomingMessages) { + return subscription; // SSE mode + } + + // Handle incoming client messages + for await (let message of incomingMessages) { + yield { received: message }; + } + } +} +``` diff --git a/harper-best-practices/rules/serving-web-content.md b/harper-best-practices/rules/serving-web-content.md index 714612a..f11d3dd 100644 --- a/harper-best-practices/rules/serving-web-content.md +++ b/harper-best-practices/rules/serving-web-content.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when serving web content from Harper. Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React app) directly from your Harper instance. -## Steps +## How It Works 1. **Choose a Method**: Decide between the simple Static Plugin or the integrated Vite Plugin. 2. **Option A: Static Plugin (Simple)**: @@ -29,6 +29,37 @@ Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React app) package: '@harperfast/vite-plugin' ``` - Ensure `vite.config.ts` and `index.html` are in the project root. + + ```javascript + import vue from '@vitejs/plugin-vue'; + import path from 'node:path'; + import { defineConfig } from 'vite'; + + // https://vite.dev/config/ + export default defineConfig({ + plugins: [vue()], + resolve: { + alias: { + '@': path.resolve(import.meta.dirname, './src'), + }, + }, + build: { + outDir: 'web', + emptyOutDir: true, + rolldownOptions: { + external: ['**/*.test.*', '**/*.spec.*'], + }, + }, + }); + ``` + - Install dependencies: `npm install --save-dev vite @harperfast/vite-plugin`. - - Use `npm run dev` for development with HMR. -4. **Deploy for Production**: For Vite apps, use a build script to generate static files into a `web/` folder and deploy them using the static handler pattern. + - Then `harper run .` will start up Harper and Vite with HMR. Vite does _not_ need to be executed separately. + +4. **Deploy for Production**: For Vite apps, use a build script to generate static files into a `web/` folder and deploy them using the static handler pattern. For example, these scripts in a package.json can perform the necessary steps: + ```json + "build": "vite build", + "deploy": "rm -Rf deploy && npm run build && mkdir deploy && mv web deploy/ && cp -R deploy-template/* deploy/ && cp -R schemas resources deploy/ && dotenv -- npm run deploy:component && rm -Rf deploy", + "deploy:component": "(cd deploy && harper deploy_component . project=web restart=rolling replicated=true)" + ``` + Then in production, the "Static Plugin" option will performantly and securely serve your assets. `npm create harper@latest` scaffolds all of this for you. diff --git a/harper-best-practices/rules/typescript-type-stripping.md b/harper-best-practices/rules/typescript-type-stripping.md index db94801..9b09e50 100644 --- a/harper-best-practices/rules/typescript-type-stripping.md +++ b/harper-best-practices/rules/typescript-type-stripping.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when using TypeScript in Harper. Use this skill when you want to write Harper Resources in TypeScript and have them execute directly in Node.js without an intermediate build or compilation step. -## Steps +## How It Works 1. **Verify Node.js Version**: Ensure you are using Node.js v22.6.0 or higher. 2. **Name Files with `.ts`**: Create your resource files in the `resources/` directory with a `.ts` extension. diff --git a/harper-best-practices/rules/using-blob-datatype.md b/harper-best-practices/rules/using-blob-datatype.md index b9f2195..b980af2 100644 --- a/harper-best-practices/rules/using-blob-datatype.md +++ b/harper-best-practices/rules/using-blob-datatype.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when working with the Blob data type in Har Use this skill when you need to store unstructured or large binary data (media, documents) that is too large for standard JSON fields. Blobs provide efficient storage and integrated streaming support. -## Steps +## How It Works 1. **Define Blob Fields**: In your GraphQL schema, use the `Blob` type: ```graphql diff --git a/harper-best-practices/rules/vector-indexing.md b/harper-best-practices/rules/vector-indexing.md index 197093e..b0d16df 100644 --- a/harper-best-practices/rules/vector-indexing.md +++ b/harper-best-practices/rules/vector-indexing.md @@ -11,7 +11,7 @@ Instructions for the agent to follow when implementing vector search in Harper. Use this skill when you need to perform similarity searches on high-dimensional data, such as AI embeddings for semantic search, recommendations, or image retrieval. -## Steps +## How It Works 1. **Enable Vector Indexing**: In your GraphQL schema, add `@indexed(type: "HNSW")` to a numeric array field: ```graphql @@ -46,88 +46,93 @@ Use this skill when you need to perform similarity searches on high-dimensional 5. **Generate Embeddings**: Use external services (OpenAI, Ollama) to generate the numeric vectors before storing or searching them in Harper. ```typescript -const { Product } = tables; - import OpenAI from 'openai'; +import ollama from 'ollama'; + +const { Product } = tables; const openai = new OpenAI(); // the name of the OpenAI embedding model const OPENAI_EMBEDDING_MODEL = 'text-embedding-3-small'; +// the name of the Ollama embedding model +const OLLAMA_EMBEDDING_MODEL = 'llama3'; + const SIMILARITY_THRESHOLD = 0.5; export class ProductSearch extends Resource { -// based on env variable we choose the appropriate embedding generator -generateEmbedding = process.env.EMBEDDING_GENERATOR === 'ollama' -? this._generateOllamaEmbedding -: this._generateOpenAIEmbedding; - - /** - * Executes a search query using a generated text embedding and returns the matching products. - * - * @param {Object} data - The input data for the request. - * @param {string} data.prompt - The prompt to generate the text embedding from. - * @return {Promise} Returns a promise that resolves to an array of products matching the conditions, - * including fields: name, description, price, and $distance. - */ - async post(data) { - const embedding = await this.generateEmbedding(data.prompt); - - return await Product.search({ - select: ['name', 'description', 'price', '$distance'], - conditions: { - attribute: 'textEmbeddings', - comparator: 'lt', - value: SIMILARITY_THRESHOLD, - target: embedding[0], - }, - limit: 5, - }); - } - - /** - * Generates an embedding using the Ollama API. - * - * @param {string} promptData - The input data for which the embedding is to be generated. - * @return {Promise} A promise that resolves to the generated embedding as an array of numbers. - */ - async _generateOllamaEmbedding(promptData) { - const embedding = await ollama.embed({ - model: OLLAMA_EMBEDDING_MODEL, - input: promptData, - }); - return embedding?.embeddings; - } - - /** - * Generates OpenAI embeddings based on the given prompt data. - * - * @param {string} promptData - The input data used for generating the embedding. - * @return {Promise} A promise that resolves to an array of embeddings, where each embedding is an array of floats. - */ - async _generateOpenAIEmbedding(promptData) { - const embedding = await openai.embeddings.create({ - model: OPENAI_EMBEDDING_MODEL, - input: promptData, - encoding_format: 'float', - }); - - let embeddings = []; - embedding.data.forEach((embeddingData) => { - embeddings.push(embeddingData.embedding); - }); - - return embeddings; - } - + // based on env variable we choose the appropriate embedding generator + generateEmbedding = + process.env.EMBEDDING_GENERATOR === 'ollama' + ? this._generateOllamaEmbedding + : this._generateOpenAIEmbedding; + + /** + * Executes a search query using a generated text embedding and returns the matching products. + * + * @param {Object} data - The input data for the request. + * @param {string} data.prompt - The prompt to generate the text embedding from. + * @return {Promise} Returns a promise that resolves to an array of products matching the conditions, + * including fields: name, description, price, and $distance. + */ + async post(data) { + const embedding = await this.generateEmbedding(data.prompt); + + return await Product.search({ + select: ['name', 'description', 'price', '$distance'], + conditions: { + attribute: 'textEmbeddings', + comparator: 'lt', + value: SIMILARITY_THRESHOLD, + target: embedding[0], + }, + limit: 5, + }); + } + + /** + * Generates an embedding using the Ollama API. + * + * @param {string} promptData - The input data for which the embedding is to be generated. + * @return {Promise} A promise that resolves to the generated embedding as an array of numbers. + */ + async _generateOllamaEmbedding(promptData) { + const embedding = await ollama.embed({ + model: OLLAMA_EMBEDDING_MODEL, + input: promptData, + }); + return embedding?.embeddings; + } + + /** + * Generates OpenAI embeddings based on the given prompt data. + * + * @param {string} promptData - The input data used for generating the embedding. + * @return {Promise} A promise that resolves to an array of embeddings, where each embedding is an array of floats. + */ + async _generateOpenAIEmbedding(promptData) { + const embedding = await openai.embeddings.create({ + model: OPENAI_EMBEDDING_MODEL, + input: promptData, + encoding_format: 'float', + }); + + let embeddings = []; + embedding.data.forEach((embeddingData) => { + embeddings.push(embeddingData.embedding); + }); + + return embeddings; + } } - ``` +## Examples + Sample request to the `ProductSearch` resource which prompts to find "shorts for the gym": ```bash curl -X POST "http://localhost:9926/ProductSearch/" \ --H "accept: application/json \ +-H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Basic " \ -d '{"prompt": "shorts for the gym"}' diff --git a/package-lock.json b/package-lock.json index cf75240..a0a5714 100644 --- a/package-lock.json +++ b/package-lock.json @@ -20,6 +20,7 @@ "conventional-changelog-conventionalcommits": "^9.1.0", "dprint": "^0.51.1", "gray-matter": "^4.0.3", + "oxfmt": "^0.41.0", "semantic-release": "^25.0.3" } }, @@ -675,6 +676,329 @@ "@octokit/openapi-types": "^27.0.0" } }, + "node_modules/@oxfmt/binding-android-arm-eabi": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-android-arm-eabi/-/binding-android-arm-eabi-0.41.0.tgz", + "integrity": "sha512-REfrqeMKGkfMP+m/ScX4f5jJBSmVNYcpoDF8vP8f8eYPDuPGZmzp56NIUsYmx3h7f6NzC6cE3gqh8GDWrJHCKw==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-android-arm64": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-android-arm64/-/binding-android-arm64-0.41.0.tgz", + "integrity": "sha512-s0b1dxNgb2KomspFV2LfogC2XtSJB42POXF4bMCLJyvQmAGos4ZtjGPfQreToQEaY0FQFjz3030ggI36rF1q5g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-darwin-arm64": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-darwin-arm64/-/binding-darwin-arm64-0.41.0.tgz", + "integrity": "sha512-EGXGualADbv/ZmamE7/2DbsrYmjoPlAmHEpTL4vapLF4EfVD6fr8/uQDFnPJkUBjiSWFJZtFNsGeN1B6V3owmA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-darwin-x64": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-darwin-x64/-/binding-darwin-x64-0.41.0.tgz", + "integrity": "sha512-WxySJEvdQQYMmyvISH3qDpTvoS0ebnIP63IMxLLWowJyPp/AAH0hdWtlo+iGNK5y3eVfa5jZguwNaQkDKWpGSw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-freebsd-x64": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-freebsd-x64/-/binding-freebsd-x64-0.41.0.tgz", + "integrity": "sha512-Y2kzMkv3U3oyuYaR4wTfGjOTYTXiFC/hXmG0yVASKkbh02BJkvD98Ij8bIevr45hNZ0DmZEgqiXF+9buD4yMYQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-linux-arm-gnueabihf": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-0.41.0.tgz", + "integrity": "sha512-ptazDjdUyhket01IjPTT6ULS1KFuBfTUU97osTP96X5y/0oso+AgAaJzuH81oP0+XXyrWIHbRzozSAuQm4p48g==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-linux-arm-musleabihf": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm-musleabihf/-/binding-linux-arm-musleabihf-0.41.0.tgz", + "integrity": "sha512-UkoL2OKxFD+56bPEBcdGn+4juTW4HRv/T6w1dIDLnvKKWr6DbarB/mtHXlADKlFiJubJz8pRkttOR7qjYR6lTA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-linux-arm64-gnu": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-0.41.0.tgz", + "integrity": "sha512-gofu0PuumSOHYczD8p62CPY4UF6ee+rSLZJdUXkpwxg6pILiwSDBIouPskjF/5nF3A7QZTz2O9KFNkNxxFN9tA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-linux-arm64-musl": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm64-musl/-/binding-linux-arm64-musl-0.41.0.tgz", + "integrity": "sha512-VfVZxL0+6RU86T8F8vKiDBa+iHsr8PAjQmKGBzSCAX70b6x+UOMFl+2dNihmKmUwqkCazCPfYjt6SuAPOeQJ3g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-linux-ppc64-gnu": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-0.41.0.tgz", + "integrity": "sha512-bwzokz2eGvdfJbc0i+zXMJ4BBjQPqg13jyWpEEZDOrBCQ91r8KeY2Mi2kUeuMTZNFXju+jcAbAbpyJxRGla0eg==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-linux-riscv64-gnu": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-0.41.0.tgz", + "integrity": "sha512-POLM//PCH9uqDeNDwWL3b3DkMmI3oI2cU6hwc2lnztD1o7dzrQs3R9nq555BZ6wI7t2lyhT9CS+CRaz5X0XqLA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-linux-riscv64-musl": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-0.41.0.tgz", + "integrity": "sha512-NNK7PzhFqLUwx/G12Xtm6scGv7UITvyGdAR5Y+TlqsG+essnuRWR4jRNODWRjzLZod0T3SayRbnkSIWMBov33w==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-linux-s390x-gnu": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-0.41.0.tgz", + "integrity": "sha512-qVf/zDC5cN9eKe4qI/O/m445er1IRl6swsSl7jHkqmOSVfknwCe5JXitYjZca+V/cNJSU/xPlC5EFMabMMFDpw==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-linux-x64-gnu": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-x64-gnu/-/binding-linux-x64-gnu-0.41.0.tgz", + "integrity": "sha512-ojxYWu7vUb6ysYqVCPHuAPVZHAI40gfZ0PDtZAMwVmh2f0V8ExpPIKoAKr7/8sNbAXJBBpZhs2coypIo2jJX4w==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-linux-x64-musl": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-x64-musl/-/binding-linux-x64-musl-0.41.0.tgz", + "integrity": "sha512-O2exZLBxoCMIv2vlvcbkdedazJPTdG0VSup+0QUCfYQtx751zCZNboX2ZUOiQ/gDTdhtXvSiot0h6GEGkOyalA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-openharmony-arm64": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-openharmony-arm64/-/binding-openharmony-arm64-0.41.0.tgz", + "integrity": "sha512-N+31/VoL+z+NNBt8viy3I4NaIdPbiYeOnB884LKqvXldaE2dRztdPv3q5ipfZYv0RwFp7JfqS4I27K/DSHCakg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-win32-arm64-msvc": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-0.41.0.tgz", + "integrity": "sha512-Z7NAtu/RN8kjCQ1y5oDD0nTAeRswh3GJ93qwcW51srmidP7XPBmZbLlwERu1W5veCevQJtPS9xmkpcDTYsGIwQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-win32-ia32-msvc": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-0.41.0.tgz", + "integrity": "sha512-uNxxP3l4bJ6VyzIeRqCmBU2Q0SkCFgIhvx9/9dJ9V8t/v+jP1IBsuaLwCXGR8JPHtkj4tFp+RHtUmU2ZYAUpMA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@oxfmt/binding-win32-x64-msvc": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@oxfmt/binding-win32-x64-msvc/-/binding-win32-x64-msvc-0.41.0.tgz", + "integrity": "sha512-49ZSpbZ1noozyPapE8SUOSm3IN0Ze4b5nkO+4+7fq6oEYQQJFhE0saj5k/Gg4oewVPdjn0L3ZFeWk2Vehjcw7A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, "node_modules/@pnpm/config.env-replace": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/@pnpm/config.env-replace/-/config.env-replace-1.1.0.tgz", @@ -5189,6 +5513,46 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/oxfmt": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/oxfmt/-/oxfmt-0.41.0.tgz", + "integrity": "sha512-sKLdJZdQ3bw6x9qKiT7+eID4MNEXlDHf5ZacfIircrq6Qwjk0L6t2/JQlZZrVHTXJawK3KaMuBoJnEJPcqCEdg==", + "dev": true, + "license": "MIT", + "dependencies": { + "tinypool": "2.1.0" + }, + "bin": { + "oxfmt": "bin/oxfmt" + }, + "engines": { + "node": "^20.19.0 || >=22.12.0" + }, + "funding": { + "url": "https://github.com/sponsors/Boshen" + }, + "optionalDependencies": { + "@oxfmt/binding-android-arm-eabi": "0.41.0", + "@oxfmt/binding-android-arm64": "0.41.0", + "@oxfmt/binding-darwin-arm64": "0.41.0", + "@oxfmt/binding-darwin-x64": "0.41.0", + "@oxfmt/binding-freebsd-x64": "0.41.0", + "@oxfmt/binding-linux-arm-gnueabihf": "0.41.0", + "@oxfmt/binding-linux-arm-musleabihf": "0.41.0", + "@oxfmt/binding-linux-arm64-gnu": "0.41.0", + "@oxfmt/binding-linux-arm64-musl": "0.41.0", + "@oxfmt/binding-linux-ppc64-gnu": "0.41.0", + "@oxfmt/binding-linux-riscv64-gnu": "0.41.0", + "@oxfmt/binding-linux-riscv64-musl": "0.41.0", + "@oxfmt/binding-linux-s390x-gnu": "0.41.0", + "@oxfmt/binding-linux-x64-gnu": "0.41.0", + "@oxfmt/binding-linux-x64-musl": "0.41.0", + "@oxfmt/binding-openharmony-arm64": "0.41.0", + "@oxfmt/binding-win32-arm64-msvc": "0.41.0", + "@oxfmt/binding-win32-ia32-msvc": "0.41.0", + "@oxfmt/binding-win32-x64-msvc": "0.41.0" + } + }, "node_modules/p-each-series": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/p-each-series/-/p-each-series-3.0.0.tgz", @@ -6741,6 +7105,16 @@ "url": "https://github.com/sponsors/jonschlinkert" } }, + "node_modules/tinypool": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-2.1.0.tgz", + "integrity": "sha512-Pugqs6M0m7Lv1I7FtxN4aoyToKg1C4tu+/381vH35y8oENM/Ai7f7C4StcoK4/+BSw9ebcS8jRiVrORFKCALLw==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^20.0.0 || >=22.0.0" + } + }, "node_modules/to-regex-range": { "version": "5.0.1", "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", diff --git a/package.json b/package.json index 0335235..66837bd 100644 --- a/package.json +++ b/package.json @@ -1,34 +1,36 @@ { - "name": "@harperfast/skills", - "version": "1.1.1", - "description": "Best practices for making awesome Harper apps with your favorite Agent", - "repository": "github:HarperFast/skills", - "bugs": { - "url": "https://github.com/harperfast/skills/issues" - }, - "homepage": "https://github.com/harperfast", - "author": { - "name": "Harper", - "email": "support@harperdb.io" - }, - "license": "Apache License 2.0", - "keywords": [], - "type": "module", - "scripts": { - "validate": "node scripts/validate-skills.mjs" - }, - "devDependencies": { - "@commitlint/cli": "^20.4.1", - "@commitlint/config-conventional": "^20.4.1", - "@semantic-release/commit-analyzer": "^13.0.1", - "@semantic-release/git": "^10.0.1", - "@semantic-release/github": "^12.0.3", - "@semantic-release/npm": "^13.1.3", - "@semantic-release/release-notes-generator": "^14.1.0", - "@types/node": "^25.2.0", - "conventional-changelog-conventionalcommits": "^9.1.0", - "dprint": "^0.51.1", - "gray-matter": "^4.0.3", - "semantic-release": "^25.0.3" - } + "name": "@harperfast/skills", + "version": "1.1.1", + "description": "Best practices for making awesome Harper apps with your favorite Agent", + "keywords": [], + "homepage": "https://github.com/harperfast", + "bugs": { + "url": "https://github.com/harperfast/skills/issues" + }, + "license": "Apache License 2.0", + "author": { + "name": "Harper", + "email": "support@harperdb.io" + }, + "repository": "github:HarperFast/skills", + "type": "module", + "scripts": { + "format": "oxfmt", + "validate": "oxfmt --check && node scripts/validate-skills.mjs" + }, + "devDependencies": { + "@commitlint/cli": "^20.4.1", + "@commitlint/config-conventional": "^20.4.1", + "@semantic-release/commit-analyzer": "^13.0.1", + "@semantic-release/git": "^10.0.1", + "@semantic-release/github": "^12.0.3", + "@semantic-release/npm": "^13.1.3", + "@semantic-release/release-notes-generator": "^14.1.0", + "@types/node": "^25.2.0", + "conventional-changelog-conventionalcommits": "^9.1.0", + "dprint": "^0.51.1", + "gray-matter": "^4.0.3", + "oxfmt": "^0.41.0", + "semantic-release": "^25.0.3" + } } diff --git a/release.config.js b/release.config.js index 04f65fa..265ebbc 100644 --- a/release.config.js +++ b/release.config.js @@ -23,8 +23,8 @@ module.exports = { [ '@semantic-release/git', { - 'assets': ['package.json'], - 'message': 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}', + assets: ['package.json'], + message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}', }, ], '@semantic-release/github', diff --git a/renovate.json b/renovate.json index 2dcc30a..17690cf 100644 --- a/renovate.json +++ b/renovate.json @@ -1,12 +1,8 @@ { "$schema": "https://docs.renovatebot.com/renovate-schema.json", - "extends": [ - "config:recommended" - ], + "extends": ["config:recommended"], "timezone": "America/New_York", - "schedule": [ - "before 9am on Monday" - ], + "schedule": ["before 9am on Monday"], "semanticCommits": "enabled", "minimumReleaseAge": "3 days", "internalChecksFilter": "strict", @@ -15,18 +11,13 @@ { "groupName": "pin digests", "groupSlug": "all-digests", - "matchDepTypes": [ - "action" - ], + "matchDepTypes": ["action"], "pinDigests": true }, { "groupName": "all non-major dependencies", "groupSlug": "all-minor-patch", - "matchUpdateTypes": [ - "minor", - "patch" - ], + "matchUpdateTypes": ["minor", "patch"], "matchCurrentVersion": "!/^0/", "automerge": true } diff --git a/scripts/validate-skills.mjs b/scripts/validate-skills.mjs index 342ea1d..cd5fc4e 100644 --- a/scripts/validate-skills.mjs +++ b/scripts/validate-skills.mjs @@ -6,120 +6,123 @@ const SKILL_FILE = 'SKILL.md'; const AGENTS_FILE = 'AGENTS.md'; function getAllFiles(dir) { - let results = []; - const list = fs.readdirSync(dir); - list.forEach((file) => { - if (file === 'node_modules' || file === '.git') return; - const filePath = path.join(dir, file); - const stat = fs.statSync(filePath); - if (stat && stat.isDirectory()) { - results = results.concat(getAllFiles(filePath)); - } else if (file.endsWith('.md')) { - results.push(filePath); - } - }); - return results; + let results = []; + const list = fs.readdirSync(dir); + list.forEach((file) => { + if (file === 'node_modules' || file === '.git') return; + const filePath = path.join(dir, file); + const stat = fs.statSync(filePath); + if (stat && stat.isDirectory()) { + results = results.concat(getAllFiles(filePath)); + } else if (file.endsWith('.md')) { + results.push(filePath); + } + }); + return results; } function validateSkillFile(filePath, data) { - const errors = []; - - if (!data.name) { - errors.push('Missing "name" in frontmatter'); - } else if (typeof data.name !== 'string') { - errors.push('"name" must be a string'); - } else if (!/^[a-z0-9-]+$/.test(data.name)) { - errors.push('"name" must be lowercase and only contain letters, numbers, and hyphens'); - } - - if (!data.description) { - errors.push('Missing "description" in frontmatter'); - } else if (typeof data.description !== 'string') { - errors.push('"description" must be a string'); - } - - if (data.metadata) { - if (typeof data.metadata !== 'object') { - errors.push('"metadata" must be an object'); - } else { - if (data.metadata.version && typeof data.metadata.version !== 'string') { - errors.push('"metadata.version" must be a string'); - } - if (data.metadata.internal !== undefined && typeof data.metadata.internal !== 'boolean') { - errors.push('"metadata.internal" must be a boolean'); - } - } - } - - return errors; + const errors = []; + + if (!data.name) { + errors.push('Missing "name" in frontmatter'); + } else if (typeof data.name !== 'string') { + errors.push('"name" must be a string'); + } else if (!/^[a-z0-9-]+$/.test(data.name)) { + errors.push('"name" must be lowercase and only contain letters, numbers, and hyphens'); + } + + if (!data.description) { + errors.push('Missing "description" in frontmatter'); + } else if (typeof data.description !== 'string') { + errors.push('"description" must be a string'); + } + + if (data.metadata) { + if (typeof data.metadata !== 'object') { + errors.push('"metadata" must be an object'); + } else { + if (data.metadata.version && typeof data.metadata.version !== 'string') { + errors.push('"metadata.version" must be a string'); + } + if (data.metadata.internal !== undefined && typeof data.metadata.internal !== 'boolean') { + errors.push('"metadata.internal" must be a boolean'); + } + } + } + + return errors; } function validateRuleFile(filePath, data) { - const errors = []; + const errors = []; - if (!data.name) { - errors.push('Missing "name" in frontmatter'); - } else if (typeof data.name !== 'string') { - errors.push('"name" must be a string'); - } + if (!data.name) { + errors.push('Missing "name" in frontmatter'); + } else if (typeof data.name !== 'string') { + errors.push('"name" must be a string'); + } - if (!data.description) { - errors.push('Missing "description" in frontmatter'); - } else if (typeof data.description !== 'string') { - errors.push('"description" must be a string'); - } + if (!data.description) { + errors.push('Missing "description" in frontmatter'); + } else if (typeof data.description !== 'string') { + errors.push('"description" must be a string'); + } - return errors; + return errors; } function validateAgentsFile(filePath, content) { - const errors = []; - if (!content.trim().startsWith('# ')) { - errors.push('Should start with a top-level heading (H1)'); - } - return errors; + const errors = []; + if (!content.trim().startsWith('# ')) { + errors.push('Should start with a top-level heading (H1)'); + } + return errors; } const allFiles = getAllFiles('.'); let hasError = false; allFiles.forEach((file) => { - const content = fs.readFileSync(file, 'utf8'); - let errors = []; - - if (file.endsWith(SKILL_FILE)) { - const { data, content: body } = matter(content); - errors = validateSkillFile(file, data); - if (!body.includes('## When to Use')) { - errors.push('Missing "## When to Use" section'); - } - if (!body.includes('## Steps')) { - errors.push('Missing "## Steps" section'); - } - } else if (file.includes(path.sep + 'rules' + path.sep)) { - const { data, content: body } = matter(content); - errors = validateRuleFile(file, data); - if (!body.trim().startsWith('# ')) { - errors.push('Rule file should start with a top-level heading (H1)'); - } - } else if (file.endsWith(AGENTS_FILE)) { - errors = validateAgentsFile(file, content); - } else { - // Other markdown files (like README.md) - no specific validation for now - return; - } - - if (errors.length > 0) { - console.error(`Validation failed for ${file}:`); - errors.forEach((err) => console.error(` - ${err}`)); - hasError = true; - } else { - // console.log(`✓ ${file} is valid`); - } + const content = fs.readFileSync(file, 'utf8'); + let errors = []; + + if (file.endsWith(SKILL_FILE)) { + const { data, content: body } = matter(content); + errors = validateSkillFile(file, data); + if (!body.includes('## When to Use')) { + errors.push('Missing "## When to Use" section'); + } + if (!body.includes('## How It Works')) { + errors.push('Missing "## How It Works" section'); + } + if (!body.includes('## Examples')) { + errors.push('Missing "## Examples" section'); + } + } else if (file.includes(path.sep + 'rules' + path.sep)) { + const { data, content: body } = matter(content); + errors = validateRuleFile(file, data); + if (!body.trim().startsWith('# ')) { + errors.push('Rule file should start with a top-level heading (H1)'); + } + } else if (file.endsWith(AGENTS_FILE)) { + errors = validateAgentsFile(file, content); + } else { + // Other markdown files (like README.md) - no specific validation for now + return; + } + + if (errors.length > 0) { + console.error(`Validation failed for ${file}:`); + errors.forEach((err) => console.error(` - ${err}`)); + hasError = true; + } else { + // console.log(`✓ ${file} is valid`); + } }); if (hasError) { - process.exit(1); + process.exit(1); } else { - console.log('✓ All skills and rules validated successfully'); + console.log('✓ All skills and rules validated successfully'); }