create-harper 1.2.1 → 1.3.0

package/lib/install.js

@@ -20,4 +20,9 @@ export function install(root, agent) {
 		stdio: 'inherit',
 		cwd: root,
 	});
+	prompts.log.step('Installing Harper skills...');
+	run('npx -y skills add harperfast/skills --all --yes', {
+		stdio: 'inherit',
+		cwd: root,
+	});
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "create-harper",
 	"description": "Scaffold a new Harper project in JavaScript or TypeScript.",
-	"version": "1.2.1",
+	"version": "1.3.0",
 	"type": "module",
 	"author": {
 		"name": "HarperDB",

package/template-react/README.md

@@ -26,7 +26,7 @@ npm run dev
 2. Craft your schema by hand.
 3. Save your changes.
 
-These schemas are the heart of a great Harper app, specifying which tables you want and what attributes/fields they should have. Any table you `@export` stands up [REST endpoints automatically](./skills/automatic-rest-apis.md).
+These schemas are the heart of a great Harper app, specifying which tables you want and what attributes/fields they should have. Any table you `@export` stands up [endpoints automatically](./.agents/skills/harper-best-practices/rules/automatic-apis.md).
 
 ### Add Custom Endpoints
 

package/template-react/package.json

@@ -4,6 +4,8 @@
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {
+		"agent:run": "npx -y @harperfast/agent@latest",
+		"agent:skills:update": "npx -y skills@latest add harperfast/skills --all --yes",
 		"dev": "harper run .",
 		"test": "echo 'No tests implemented yet'",
 		"lint": "echo 'No lint implemented yet'",

package/template-react/resources/README.md

@@ -1,11 +1,11 @@
 # Resources
 
-The [schemas you define in .GraphQL files](../skills/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../skills/automatic-apis.md).
+The [schemas you define in .GraphQL files](../.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../.agents/skills/harper-best-practices/rules/automatic-apis.md).
 
-But you can [extend your tables with custom logic](../skills/extending-tables.md) and [create your own resources](../skills/custom-resources.md) in this directory.
+But you can [extend your tables with custom logic](../.agents/skills/harper-best-practices/rules/extending-tables.md) and [create your own resources](../.agents/skills/harper-best-practices/rules/custom-resources.md) in this directory.
 
 ## Want to read more?
 
 Check out the rest of the "skills" documentation!
 
-[AGENTS.md](../AGENTS.md)
+[Harper Best Practices Skill](../.agents/skills/harper-best-practices/SKILL.md)

package/template-react/schemas/README.md

@@ -2,10 +2,10 @@
 
 Your schemas are defined in `.graphql` files within this `schemas` directory. These files contain the structure and types for your database tables, allowing Harper to automatically generate REST APIs for CRUD operations.
 
-Take a look at the [Adding Tables with Schemas](../skills/adding-tables-with-schemas.md) to learn more!
+Take a look at the [Adding Tables with Schemas](../.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md) to learn more!
 
 ## Want to read more?
 
 Check out the rest of the "skills" documentation!
 
-[AGENTS.md](../AGENTS.md)
+[Harper Best Practices Skill](../.agents/skills/harper-best-practices/SKILL.md)

package/template-react-ts/README.md

@@ -28,7 +28,7 @@ TypeScript is supported at runtime in Node.js through [type stripping](https://n
 2. Craft your schema by hand.
 3. Save your changes.
 
-These schemas are the heart of a great Harper app, specifying which tables you want and what attributes/fields they should have. Any table you `@export` stands up [REST endpoints automatically](./skills/automatic-rest-apis.md).
+These schemas are the heart of a great Harper app, specifying which tables you want and what attributes/fields they should have. Any table you `@export` stands up [endpoints automatically](./.agents/skills/harper-best-practices/rules/automatic-apis.md).
 
 ### Add Custom Endpoints
 

package/template-react-ts/package.json

@@ -4,6 +4,8 @@
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {
+		"agent:run": "npx -y @harperfast/agent@latest",
+		"agent:skills:update": "npx -y skills@latest add harperfast/skills --all --yes",
 		"dev": "harper run .",
 		"test": "echo 'No tests implemented yet'",
 		"lint": "echo 'No lint implemented yet'",

package/template-react-ts/resources/README.md

@@ -1,11 +1,11 @@
 # Resources
 
-The [schemas you define in .GraphQL files](../skills/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../skills/automatic-apis.md).
+The [schemas you define in .GraphQL files](../.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../.agents/skills/harper-best-practices/rules/automatic-apis.md).
 
-But you can [extend your tables with custom logic](../skills/extending-tables.md) and [create your own resources](../skills/custom-resources.md) in this directory.
+But you can [extend your tables with custom logic](../.agents/skills/harper-best-practices/rules/extending-tables.md) and [create your own resources](../.agents/skills/harper-best-practices/rules/custom-resources.md) in this directory.
 
 ## Want to read more?
 
 Check out the rest of the "skills" documentation!
 
-[AGENTS.md](../AGENTS.md)
+[Harper Best Practices Skill](../.agents/skills/harper-best-practices/SKILL.md)

package/template-react-ts/schemas/README.md

@@ -2,10 +2,10 @@
 
 Your schemas are defined in `.graphql` files within this `schemas` directory. These files contain the structure and types for your database tables, allowing Harper to automatically generate REST APIs for CRUD operations.
 
-Take a look at the [Adding Tables with Schemas](../skills/adding-tables-with-schemas.md) to learn more!
+Take a look at the [Adding Tables with Schemas](../.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md) to learn more!
 
 ## Want to read more?
 
 Check out the rest of the "skills" documentation!
 
-[AGENTS.md](../AGENTS.md)
+[Harper Best Practices Skill](../.agents/skills/harper-best-practices/SKILL.md)

package/template-vanilla/README.md

@@ -26,7 +26,7 @@ npm run dev
 2. Craft your schema by hand.
 3. Save your changes.
 
-These schemas are the heart of a great Harper app, specifying which tables you want and what attributes/fields they should have. Any table you `@export` stands up [REST endpoints automatically](./skills/automatic-rest-apis.md).
+These schemas are the heart of a great Harper app, specifying which tables you want and what attributes/fields they should have. Any table you `@export` stands up [endpoints automatically](./.agents/skills/harper-best-practices/rules/automatic-apis.md).
 
 ### Add Custom Endpoints
 

package/template-vanilla/package.json

@@ -4,6 +4,8 @@
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {
+		"agent:run": "npx -y @harperfast/agent@latest",
+		"agent:skills:update": "npx -y skills@latest add harperfast/skills --all --yes",
 		"start": "harperdb run .",
 		"dev": "harperdb dev .",
 		"deploy": "dotenv -- npm run deploy:component",

package/template-vanilla/resources/README.md

@@ -1,11 +1,11 @@
 # Resources
 
-The [schemas you define in .GraphQL files](../skills/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../skills/automatic-apis.md).
+The [schemas you define in .GraphQL files](../.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../.agents/skills/harper-best-practices/rules/automatic-apis.md).
 
-But you can [extend your tables with custom logic](../skills/extending-tables.md) and [create your own resources](../skills/custom-resources.md) in this directory.
+But you can [extend your tables with custom logic](../.agents/skills/harper-best-practices/rules/extending-tables.md) and [create your own resources](../.agents/skills/harper-best-practices/rules/custom-resources.md) in this directory.
 
 ## Want to read more?
 
 Check out the rest of the "skills" documentation!
 
-[AGENTS.md](../AGENTS.md)
+[Harper Best Practices Skill](../.agents/skills/harper-best-practices/SKILL.md)

package/template-vanilla/schemas/README.md

@@ -2,10 +2,10 @@
 
 Your schemas are defined in `.graphql` files within this `schemas` directory. These files contain the structure and types for your database tables, allowing Harper to automatically generate REST APIs for CRUD operations.
 
-Take a look at the [Adding Tables with Schemas](../skills/adding-tables-with-schemas.md) to learn more!
+Take a look at the [Adding Tables with Schemas](../.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md) to learn more!
 
 ## Want to read more?
 
 Check out the rest of the "skills" documentation!
 
-[AGENTS.md](../AGENTS.md)
+[Harper Best Practices Skill](../.agents/skills/harper-best-practices/SKILL.md)

package/template-vanilla-ts/README.md

@@ -28,7 +28,7 @@ TypeScript is supported at runtime in Node.js through [type stripping](https://n
 2. Craft your schema by hand.
 3. Save your changes.
 
-These schemas are the heart of a great Harper app, specifying which tables you want and what attributes/fields they should have. Any table you `@export` stands up [REST endpoints automatically](./skills/automatic-rest-apis.md).
+These schemas are the heart of a great Harper app, specifying which tables you want and what attributes/fields they should have. Any table you `@export` stands up [endpoints automatically](./.agents/skills/harper-best-practices/rules/automatic-apis.md).
 
 ### Add Custom Endpoints
 

package/template-vanilla-ts/package.json

@@ -4,6 +4,8 @@
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {
+		"agent:run": "npx -y @harperfast/agent@latest",
+		"agent:skills:update": "npx -y skills@latest add harperfast/skills --all --yes",
 		"start": "harperdb run .",
 		"dev": "harperdb dev .",
 		"deploy": "dotenv -- npm run deploy:component",

package/template-vanilla-ts/resources/README.md

@@ -1,11 +1,11 @@
 # Resources
 
-The [schemas you define in .GraphQL files](../skills/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../skills/automatic-apis.md).
+The [schemas you define in .GraphQL files](../.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../.agents/skills/harper-best-practices/rules/automatic-apis.md).
 
-But you can [extend your tables with custom logic](../skills/extending-tables.md) and [create your own resources](../skills/custom-resources.md) in this directory.
+But you can [extend your tables with custom logic](../.agents/skills/harper-best-practices/rules/extending-tables.md) and [create your own resources](../.agents/skills/harper-best-practices/rules/custom-resources.md) in this directory.
 
 ## Want to read more?
 
 Check out the rest of the "skills" documentation!
 
-[AGENTS.md](../AGENTS.md)
+[Harper Best Practices Skill](../.agents/skills/harper-best-practices/SKILL.md)

package/template-vanilla-ts/schemas/README.md

@@ -2,10 +2,10 @@
 
 Your schemas are defined in `.graphql` files within this `schemas` directory. These files contain the structure and types for your database tables, allowing Harper to automatically generate REST APIs for CRUD operations.
 
-Take a look at the [Adding Tables with Schemas](../skills/adding-tables-with-schemas.md) to learn more!
+Take a look at the [Adding Tables with Schemas](../.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md) to learn more!
 
 ## Want to read more?
 
 Check out the rest of the "skills" documentation!
 
-[AGENTS.md](../AGENTS.md)
+[Harper Best Practices Skill](../.agents/skills/harper-best-practices/SKILL.md)

package/template-react/AGENTS.md

@@ -1,22 +0,0 @@
-# Harper Agent Skills
-
-This repository contains "skills" that guide AI agents in developing Harper applications.
-
-## Available Skills
-
-- [Adding Tables with Schemas](skills/adding-tables-with-schemas.md): Learn how to define schemas and enable automatic REST APIs for your database tables with schema .graphql files in Harper.
-- [Automatic APIs](skills/automatic-apis.md): Details on the CRUD endpoints automatically generated for exported tables with REST and WebSockets.
-- [Caching](skills/caching.md): How caching is defined and implemented in Harper applications.
-- [Checking Authentication](skills/checking-authentication.md): How to use sessions to verify user identity and roles.
-- [Custom Resources](skills/custom-resources.md): How to define custom REST endpoints using JavaScript or TypeScript (Note: Paths are case-sensitive).
-- [Defining Relationships](skills/defining-relationships.md): Using the `@relationship` directive to link tables.
-- [Deploying to Harper Fabric](skills/deploying-to-harper-fabric.md): Globally scaling your Harper application with our generous Free tier and beyond.
-- [Extending Table Resources](skills/extending-tables.md): Adding custom logic to automatically generated table resources.
-- [Handling Binary Data](skills/handling-binary-data.md): How to store and serve binary data like images or MP3s.
-- [Programmatic Table Requests](skills/programmatic-table-requests.md): How to use filters, operators, sorting, and pagination in programmatic table requests.
-- [Querying REST APIs](skills/querying-rest-apis.md): How to use filters, operators, sorting, and pagination in REST requests.
-- [Real-time Applications](skills/real-time-apps.md): Implementing WebSockets and Pub/Sub for live data updates.
-- [Serving Web Content](skills/serving-web-content): Two ways to serve web content from a Harper application.
-- [TypeScript Type Stripping](skills/typescript-type-stripping.md): Using TypeScript directly without build tools via Node.js Type Stripping.
-- [Using Blobs](skills/using-blob-datatype.md): How to store and retrieve large data in HarperDB.
-- [Vector Indexing](skills/vector-indexing.md): How to define and use vector indexes for efficient similarity search.

package/template-react/skills/adding-tables-with-schemas.md

@@ -1,34 +0,0 @@
-# Adding Tables to Harper
-
-To add tables to a Harper database, follow these guidelines:
-
-1. **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. **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. **Defining Relationships**: You can link tables together using the `@relationship` directive. For more details, see the [Defining Relationships](defining-relationships.md) skill.
-
-4. **Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill.
-
-   - `GET /{TableName}`: Describes the schema itself.
-   - `GET /{TableName}/`: Lists all records (supports filtering, sorting, and pagination via query parameters). See the [Querying REST APIs](querying-rest-apis.md) skill for details.
-   - `GET /{TableName}/{id}`: Retrieves a single record by its ID.
-   - `POST /{TableName}/`: Creates a new record.
-   - `PUT /{TableName}/{id}`: Updates an existing record.
-   - `PATCH /{TableName}/{id}`: Performs a partial update on a record.
-   - `DELETE /{TableName}/`: Deletes all records or filtered records.
-   - `DELETE /{TableName}/{id}`: Deletes a single record by its ID.
-
-### Example
-
-In `schemas/ExamplePerson.graphql`:
-
-```graphql
-type ExamplePerson @table @export {
-	id: ID @primaryKey
-	name: String
-	tag: String @indexed
-}
-```
-
-Tip: if you are going to [extend the table](./extending-tables.md) in your resources, then do not `@export` the table from the schema.

package/template-react/skills/automatic-apis.md

@@ -1,53 +0,0 @@
-# Automatic APIs in Harper
-
-When you define a GraphQL type with the `@table` and `@export` directives, Harper automatically generates a fully-functional REST API and WebSocket interface for that table. This allows for immediate CRUD (Create, Read, Update, Delete) operations and real-time updates without writing any additional code.
-
-## Enabling Automatic APIs
-
-To enable the automatic REST and WebSocket APIs for a table, ensure your GraphQL schema includes the `@export` directive:
-
-```graphql
-type MyTable @table @export {
-	id: ID @primaryKey
-	# ... other fields
-}
-```
-
-## Available REST Endpoints
-
-The following endpoints are automatically created for a table named `TableName` (Note: Paths are **case-sensitive**, so `GET /TableName/` is valid while `GET /tablename/` is not):
-
-- **Describe Schema**: `GET /{TableName}`
-  Returns the schema definition and metadata for the table.
-- **List Records**: `GET /{TableName}/`
-  Lists all records in the table. This endpoint supports advanced filtering, sorting, and pagination. For more details, see the [Querying REST APIs](querying-rest-apis.md) skill.
-- **Get Single Record**: `GET /{TableName}/{id}`
-  Retrieves a single record by its primary key (`id`).
-- **Create Record**: `POST /{TableName}/`
-  Creates a new record. The request body should be a JSON object containing the record data.
-- **Update Record (Full)**: `PUT /{TableName}/{id}`
-  Replaces the entire record at the specified `id` with the provided JSON data.
-- **Update Record (Partial)**: `PATCH /{TableName}/{id}`
-  Updates only the specified fields of the record at the given `id`.
-- **Delete All/Filtered Records**: `DELETE /{TableName}/`
-  Deletes all records in the table, or a subset of records if filtering parameters are provided.
-- **Delete Single Record**: `DELETE /{TableName}/{id}`
-  Deletes the record with the specified `id`.
-
-## Automatic WebSockets
-
-In addition to REST endpoints, Harper also stands up WebSocket interfaces for exported tables. When you connect to the table's endpoint via WebSocket, you will automatically receive events whenever updates are made to that table.
-
-- **WebSocket Endpoint**: `ws://your-harper-instance/{TableName}`
-
-This is the easiest way to add real-time capabilities to your application. For more complex real-time needs, see the [Real-time Applications](real-time-apps.md) skill.
-
-## Filtering and Querying
-
-The `GET /{TableName}/` and `DELETE /{TableName}/` endpoints can be filtered using query parameters. While basic equality filters are straightforward, Harper supports a rich set of operators, sorting, and pagination.
-
-For a comprehensive guide on advanced querying, see the [Querying REST APIs](querying-rest-apis.md) skill.
-
-## Customizing Resources
-
-If the automatic APIs don't behave how you need, then you can look to [customize the resources](./custom-resources.md).

package/template-react/skills/automatic-rest-apis.md

@@ -1,41 +0,0 @@
-# Automatic REST APIs in HarperDB
-
-When you define a GraphQL type with the `@table` and `@export` directives, HarperDB automatically generates a fully-functional REST API for that table. This allows for immediate CRUD (Create, Read, Update, Delete) operations without writing any additional code.
-
-## Enabling REST APIs
-
-To enable the automatic REST API for a table, ensure your GraphQL schema includes the `@export` directive:
-
-```graphql
-type MyTable @table @export {
-	id: ID @primaryKey
-	# ... other fields
-}
-```
-
-## Available Endpoints
-
-The following endpoints are automatically created for a table named `TableName` (Note: Paths are **case-sensitive**, so `GET /TableName/` is valid while `GET /tablename/` is not):
-
-- **Describe Schema**: `GET /{TableName}`
-  Returns the schema definition and metadata for the table.
-- **List Records**: `GET /{TableName}/`
-  Lists all records in the table. This endpoint supports advanced filtering, sorting, and pagination. For more details, see the [Querying REST APIs](querying-rest-apis.md) skill.
-- **Get Single Record**: `GET /{TableName}/{id}`
-  Retrieves a single record by its primary key (`id`).
-- **Create Record**: `POST /{TableName}/`
-  Creates a new record. The request body should be a JSON object containing the record data.
-- **Update Record (Full)**: `PUT /{TableName}/{id}`
-  Replaces the entire record at the specified `id` with the provided JSON data.
-- **Update Record (Partial)**: `PATCH /{TableName}/{id}`
-  Updates only the specified fields of the record at the given `id`.
-- **Delete All/Filtered Records**: `DELETE /{TableName}/`
-  Deletes all records in the table, or a subset of records if filtering parameters are provided.
-- **Delete Single Record**: `DELETE /{TableName}/{id}`
-  Deletes the record with the specified `id`.
-
-## Filtering and Querying
-
-The `GET /{TableName}/` and `DELETE /{TableName}/` endpoints can be filtered using query parameters. While basic equality filters are straightforward, HarperDB supports a rich set of operators, sorting, and pagination.
-
-For a comprehensive guide on advanced querying, see the [Querying REST APIs](querying-rest-apis.md) skill.

package/template-react/skills/caching.md

@@ -1,113 +0,0 @@
-# Harper Caching
-
-Harper includes integrated support for **caching data from external sources**, enabling high-performance, low-latency cache storage that is fully queryable and interoperable with your applications. With built-in caching capabilities and distributed responsiveness, Harper makes an ideal **data caching server** for both edge and centralized use cases.
-
----
-
-## What is Harper Caching?
-
-Harper caching lets you store **cached content** in standard tables, enabling you to:
-
-- Expose cached entries as **queryable structured data** (e.g., JSON or CSV)
-- Serve data to clients with **flexible formats and custom querying**
-- Manage cache control with **timestamps and ETags** for downstream caching layers
-- Implement **active or passive caching** patterns depending on your source and invalidation strategy
-
----
-
-## Configuring a Cache Table
-
-Define a cache table in your `schema.graphql`:
-
-```graphql
-type MyCache @table(expiration: 3600) @export {
-	id: ID @primaryKey
-}
-```
-
-- `expiration` is defined in seconds
-- Expired records are refreshed on access
-- Evicted records are removed after expiration
-
----
-
-## Connecting an External Source
-
-Create a resource:
-
-```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();
-	}
-}
-```
-
-Attach it to your table:
-
-```js
-import { tables } from 'harperdb';
-import { ThirdPartyAPI } from './ThirdPartyAPI.js';
-
-const { MyCache } = tables;
-MyCache.sourcedFrom(ThirdPartyAPI);
-```
-
----
-
-## Cache Behavior
-
-1. Fresh data is returned immediately
-2. Missing or stale data triggers a fetch
-3. Concurrent misses are deduplicated
-
----
-
-## Active Caching
-
-Use `subscribe()` to proactively update or invalidate cache entries:
-
-```js
-class MyAPI extends Resource {
-	async *subscribe() {
-		// stream updates
-	}
-}
-```
-
-See [Real Time Apps](real-time-apps.md) for more details.
-
----
-
-## Write-Through Caching
-
-Propagate updates upstream:
-
-```js
-class ThirdPartyAPI extends Resource {
-	async put(data) {
-		await fetch(`https://some-api.com/${this.getId()}`, {
-			method: 'PUT',
-			body: JSON.stringify(data),
-		});
-	}
-}
-```
-
----
-
-## Summary
-
-Harper Caching allows you to:
-
-- Cache external APIs efficiently
-- Query cached data like native tables
-- Prevent cache stampedes
-- Build real-time or write-through caches