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

package/agent/skills/harper-best-practices/rules/creating-harper-apps.md

@@ -0,0 +1,54 @@
+---
+name: creating-harper-apps
+description: How to initialize a new Harper application using the CLI.
+metadata:
+  mode: synthesized
+---
+
+# Creating 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
+```
+
+## Options
+
+You can specify the project name and template directly:
+
+```bash
+npm create harper@latest my-app --template default
+```
+
+## Next Steps
+
+1. **Configure Environment**: Set up your `.env` file with local or cloud credentials.
+2. **Define Schema**: Modify `schema.graphql` to fit your application's data model.
+3. **Start Development**: Run `npm run dev` to start the local Harper instance.
+4. **Deploy**: Use `npm run deploy` to push your application to Harper Fabric.

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

@@ -0,0 +1,44 @@
+---
+name: custom-resources
+description: How to define custom REST endpoints with JavaScript or TypeScript in Harper.
+metadata:
+  mode: synthesized
+---
+
+# Custom Resources
+
+Instructions for the agent to follow when creating custom resources in Harper.
+
+## When to Use
+
+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.
+
+## 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 `harper` and define **static** methods for the HTTP verbs you handle. In Harper 5 the static methods are the HTTP handlers (mapped 1:1 to verbs); they receive a pre-parsed `RequestTarget`, and write handlers also receive the request body as an awaitable `data` argument:
+
+   ```typescript
+   import { Resource } from 'harper';
+
+   export class MyResource extends Resource {
+   	// v5 handlers are static and map 1:1 to HTTP verbs.
+   	static async get(target: any) {
+   		return { message: 'Hello from custom GET!' };
+   	}
+   }
+   ```
+
+4. **Implement HTTP Methods**: Add static methods (`get`, `post`, `put`, `patch`, or `delete`) to handle the corresponding requests. Read/delete handlers receive `(target)`; write handlers receive `(target, data)` where `data` is awaitable.
+5. **Route Nesting and Naming**: You can control the URL structure by how you export your resources:
+   - **Direct Class Export**: `export class Foo extends Resource` creates endpoints at `/Foo/`. Class names are case-sensitive in the URL.
+   - **Nested Objects**: `export const Bar = { Foo };` creates endpoints at `/Bar/Foo/`.
+   - **Lowercase and Hyphens**: Use object keys to define custom paths: `export const bar = { 'foo-baz': Foo };` exposes endpoints at `/bar/foo-baz/`.
+6. **Access Tables (Optional)**: Import and use the `tables` object to interact with your data:
+   ```typescript
+   import { tables } from 'harper';
+   // ... inside a method
+   const results = await tables.MyTable.list();
+   ```
+7. **Configure Loading**: Ensure `config.yaml` points to your resource files (e.g., `jsResource: { files: 'resources/*.ts' }`).

package/agent/skills/harper-best-practices/rules/defining-relationships.md

@@ -0,0 +1,35 @@
+---
+name: defining-relationships
+description: How to define and use relationships between tables in Harper using GraphQL.
+metadata:
+  mode: synthesized
+---
+
+# Defining Relationships
+
+Instructions for the agent to follow when defining relationships between Harper tables.
+
+## When to Use
+
+Use this skill when you need to link data across different tables, enabling automatic joins and efficient related-data fetching via REST APIs.
+
+## 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.
+   - **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 Filter: `GET /Book/?author.name=Harper`
+   - Example Select: `GET /Author/?select(name,books(title))`

package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md

@@ -0,0 +1,122 @@
+---
+name: deploying-to-harper-fabric
+description: How to deploy a Harper application to the Harper Fabric cloud.
+metadata:
+  mode: generate
+  sources:
+    - reference/v5/components/applications.md#Remote Management
+    - >-
+      fabric/cluster-creation-management.md#Connecting the Harper CLI to a
+      Cluster
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: ccdefbbf8f3b8657
+---
+
+# Deploying to Harper Fabric
+
+Instructions for the agent to follow when deploying a Harper application to the Harper Fabric cloud using the Harper CLI.
+
+## When to Use
+
+Apply this rule when deploying a Harper application to a remote Harper instance or Harper Fabric cluster. This covers interactive deployments, CI/CD pipelines, and any scenario where the agent must push a local or remote package to a target environment.
+
+## How It Works
+
+1. **Authenticate with the remote target**: Run `harper login` once to store an authentication token. The CLI writes `HARPER_CLI_TARGET` to a local `.env` so subsequent commands do not need credentials repeated. Find the **Application URL** on the cluster's **Config → Overview** page (see [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md)).
+
+   ```bash
+   harper login <Application URL>
+   # Provide cluster username and password when prompted
+   ```
+
+2. **Deploy the application**: Run `harper deploy` with the required parameters. After logging in, no credentials are needed inline.
+
+   ```bash
+   harper deploy \
+     project=<name> \
+     package=<package> \
+     target=<remote> \
+     restart=true \
+     replicated=true
+   ```
+
+3. **Choose a package source**: Set the `package` parameter to any valid npm dependency value, or omit it to package and deploy the current local directory.
+
+   | Value                                                | Effect                                           |
+   | ---------------------------------------------------- | ------------------------------------------------ |
+   | _(omitted)_                                          | Packages and deploys the current local directory |
+   | `"@harperdb/status-check"`                           | npm package                                      |
+   | `"HarperDB/status-check"`                            | GitHub repo (short form)                         |
+   | `"https://github.com/HarperDB/status-check"`         | GitHub repo (full URL)                           |
+   | `"git+ssh://git@github.com:HarperDB/secret-app.git"` | Private repo via SSH                             |
+   | `"https://example.com/application.tar.gz"`           | Remote tarball                                   |
+
+   For git tags, use the `semver` directive for reliable versioning:
+
+   ```
+   HarperDB/application-template#semver:v1.0.0
+   ```
+
+4. **Authenticate for CI/CD pipelines**: Use environment variables instead of interactive login. Set credentials before running `harper deploy`.
+
+   ```bash
+   export HARPER_CLI_USERNAME=<username>
+   export HARPER_CLI_PASSWORD=<password>
+   harper deploy \
+     project=<name> \
+     package=<package> \
+     target=<remote> \
+     restart=true \
+     replicated=true
+   ```
+
+5. **Register SSH keys for private repos**: Before deploying from an SSH-based private repository, use the Add SSH Key operation to register the key with the remote instance.
+
+## Examples
+
+**Interactive login then deploy (recommended):**
+
+```bash
+# Log in once
+harper login <remote>
+# Provide your username and password when prompted
+
+# Subsequently deploy without credentials
+harper deploy \
+  project=<name> \
+  package=<package> \
+  target=<remote> \
+  restart=true \
+  replicated=true
+```
+
+**Deploy with inline credentials (not recommended for production):**
+
+```bash
+harper deploy \
+  project=<name> \
+  package=<package> \
+  username=<username> \
+  password=<password> \
+  target=<remote> \
+  restart=true \
+  replicated=true
+```
+
+**Deploy a specific GitHub release by semver tag:**
+
+```bash
+harper deploy \
+  project=my-app \
+  package="HarperDB/application-template#semver:v1.0.0" \
+  target=<remote> \
+  restart=true \
+  replicated=true
+```
+
+## Notes
+
+- Always prefer `harper login` for interactive use and environment variables (`HARPER_CLI_USERNAME`, `HARPER_CLI_PASSWORD`) for CI/CD. Avoid inline `username`/`password` parameters in production.
+- Omitting `package` causes the CLI to package the current local directory. Specifying a local file path creates a symlink, so changes are picked up between restarts without redeploying.
+- Harper generates a `package.json` from component configurations and resolves dependencies using a form of `npm install`.
+- For SSH-based private repos, register keys with the Add SSH Key operation before deploying.

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

@@ -0,0 +1,46 @@
+---
+name: extending-tables
+description: How to add custom logic to automatically generated table resources in Harper.
+metadata:
+  mode: synthesized
+---
+
+# Extending Tables
+
+Instructions for the agent to follow when extending table resources in Harper.
+
+## When to Use
+
+Use this skill when you need to add custom validation, side effects (like webhooks), data transformation, or custom access control to the standard CRUD operations of a Harper table.
+
+## 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
+   type MyTable @table {
+   	id: ID @primaryKey
+   	name: String
+   }
+   ```
+2. **Create the Extension File**: Create a `.ts` file in your `resources/` directory.
+3. **Extend the Table Resource**: Export a class that extends `tables.YourTableName` and override the relevant **static** methods. In Harper 5 resource handlers are static and map 1:1 to HTTP verbs: `get(target)`, `post(target, data)`, `put(target, data)`, `patch(target, data)`, `delete(target)`. `target` is a pre-parsed `RequestTarget`; for writes, `data` is the request body and is **awaitable** (`await data`). Delegate to `super` to keep Harper's default behavior — a collection create passes just the record (`super.post(record)`), updates pass the target (`super.put(target, data)` / `super.patch(target, data)`), and reads/deletes pass the target (`super.get(target)`). To return a specific HTTP status from a thrown error, set **`.statusCode`** (e.g. `400`) on the error — a plain `.status` property is ignored.
+
+   ```typescript
+   import { tables } from 'harper';
+
+   export class MyTable extends tables.MyTable {
+   	// Static handler; receives (target, data) — data is awaitable.
+   	static async post(target: any, data: any) {
+   		const record = await data;
+   		if (!record?.name) {
+   			const error: any = new Error('Name is required');
+   			error.statusCode = 400; // HTTP status (use statusCode, NOT status)
+   			throw error;
+   		}
+   		return super.post(record); // create delegates with the record (no id)
+   	}
+   }
+   ```
+
+4. **Override Methods**: Override the static `get`, `post`, `put`, `patch`, or `delete` as needed, delegating to `super.<method>` (see the argument forms above) to preserve Harper's default behavior unless you intend to replace it entirely.
+5. **Implement Logic**: Use overrides for validation, side effects, or transforming data before/after database operations.

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

@@ -0,0 +1,45 @@
+---
+name: handling-binary-data
+description: How to store and serve binary data like images or audio in Harper.
+metadata:
+  mode: synthesized
+---
+
+# Handling Binary Data
+
+Instructions for the agent to follow when handling binary data in Harper.
+
+## When to Use
+
+Use this skill when you need to store binary files (images, audio, etc.) in the database or serve them back to clients via REST endpoints.
+
+## How It Works
+
+1. **Store Binary Data**: In your resource's `post` or `put` method, convert incoming data to Buffers and then to Blobs using `createBlob` from Harper's globals. Include the MIME type if available:
+
+   ```typescript
+   async post(target, record) {
+     if (record.data) {
+       record.data = createBlob(Buffer.from(record.data, record.encoding || 'base64'), {
+         type: record.contentType || 'application/octet-stream',
+       });
+     }
+     return super.post(target, record);
+   }
+   ```
+
+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': 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.

package/agent/skills/harper-best-practices/rules/load-env.md

@@ -0,0 +1,111 @@
+---
+name: load-env
+description: >-
+  How to load environment variables from .env files into a Harper application
+  using the loadEnv plugin.
+metadata:
+  mode: generate
+  sources:
+    - reference/v5/environment-variables/overview.md
+  sourceCommit: 42231db17c025a4a455e3d91875fad4084a01cb5
+  inputHash: fe610fc245226357
+---
+
+# Load Environment Variables with loadEnv
+
+Instructions for the agent to follow when loading environment variables from `.env` files into a Harper application using the `loadEnv` plugin.
+
+## When to Use
+
+Apply this rule when a Harper application needs to load secrets or configuration values from `.env` files into `process.env` at startup. Use it whenever hardcoding values must be avoided and environment-specific configuration must be supplied to Harper components.
+
+## How It Works
+
+1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` as a top-level key. It is built into Harper and requires no installation.
+
+   ```yaml
+   loadEnv:
+     files: '.env'
+   ```
+
+2. **Place `loadEnv` first**: Always list `loadEnv` before any other components in `config.yaml` so that environment variables are available on `process.env` before dependent components start.
+
+   ```yaml
+   # config.yaml — loadEnv must come first
+   loadEnv:
+     files: '.env'
+
+   rest: true
+
+   myApp:
+     files: './src/*.js'
+   ```
+
+3. **Configure the `files` option**: Provide one or more paths or glob patterns pointing to the env files to load. This option is required.
+
+4. **Set `override` if needed**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to reverse this and have loaded values win.
+
+   ```yaml
+   loadEnv:
+     files: '.env'
+     override: true
+   ```
+
+5. **Load multiple files when required**: Supply a list of files or a glob pattern. Files are loaded in the order specified.
+   ```yaml
+   loadEnv:
+     files:
+       - '.env'
+       - '.env.local'
+   ```
+   or
+   ```yaml
+   loadEnv:
+     files: 'env-vars/*'
+   ```
+
+### Configuration Options
+
+| Option     | Type                 | Required | Description                                                                            |
+| ---------- | -------------------- | -------- | -------------------------------------------------------------------------------------- |
+| `files`    | `string \| string[]` | **Yes**  | Path(s) or glob pattern(s) to the env file(s) to load.                                 |
+| `override` | `boolean`            | No       | If `true`, loaded values override existing environment variables. Defaults to `false`. |
+
+## Examples
+
+**Minimal setup — single `.env` file:**
+
+```yaml
+loadEnv:
+  files: '.env'
+```
+
+**Full `config.yaml` with load order, multiple files, and override:**
+
+```yaml
+# config.yaml — loadEnv must come first
+loadEnv:
+  files:
+    - '.env'
+    - '.env.local'
+  override: true
+
+rest: true
+
+myApp:
+  files: './src/*.js'
+```
+
+**Glob pattern:**
+
+```yaml
+loadEnv:
+  files: 'env-vars/*'
+```
+
+## Notes
+
+- `loadEnv` is built into Harper — do not install it separately; only declare it in `config.yaml`.
+- Because Harper is a single-process application, variables loaded onto `process.env` are shared across all components.
+- Without `override: true`, variables already set in the shell or container environment will not be overwritten by values in `.env` files.
+- `files` is the only required option; omitting it will produce an invalid configuration.

package/agent/skills/harper-best-practices/rules/logging.md

@@ -0,0 +1,169 @@
+---
+name: logging
+description: >-
+  Best practices for logging in Harper, including console capture, the granular
+  logger interface, and programmatic log retrieval.
+metadata:
+  mode: generate
+  sources:
+    - reference/v5/logging/overview.md
+    - reference/v5/logging/api.md
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: 46cd384598304e3b
+---
+
+# Harper Logging
+
+Instructions for the agent to follow when implementing logging in Harper applications, including direct logger usage, tagged loggers, and console capture behavior.
+
+## When to Use
+
+Apply this rule when writing any JavaScript component, plugin, or resource that needs to emit structured log entries, filter logs by component, or capture existing `console.log` output into Harper's log system. Use it whenever you need to understand log levels, log entry format, or the `logger` global API.
+
+## How It Works
+
+1. **Use the `logger` global directly** — `logger` is available in all JavaScript components without any imports. Call the method matching the desired severity level:
+
+   ```javascript
+   logger.trace('detailed trace message');
+   logger.debug('debug info', { someContext: 'value' });
+   logger.info('informational message');
+   logger.warn('potential issue');
+   logger.error('error occurred', error);
+   logger.fatal('fatal error');
+   logger.notify('server is ready');
+   ```
+
+   Only entries at or above the configured `logging.level` (or `logging.external.level`) are written to `hdb.log`.
+
+2. **Create a tagged logger with `withTag(`** — Call `logger.withTag(tag)` once per module or class to get a `TaggedLogger` scoped to that tag. This prefixes every log entry with the tag, making log output filterable by component.
+
+   ```javascript
+   const log = logger.withTag('my-resource');
+   ```
+
+   Because `TaggedLogger` methods for disabled levels are `null`, always use optional chaining (`?.`) when calling them:
+
+   ```javascript
+   log.debug?.('Fetching record', { id });
+   log.warn?.('Record not found', { id });
+   log.error?.('Failed to update record', err);
+   ```
+
+   `TaggedLogger` does not have a `withTag()` method.
+
+3. **Understand the interface contracts** — `MainLogger` always has all methods defined:
+
+   ```typescript
+   interface MainLogger {
+   	trace(...messages: any[]): void;
+   	debug(...messages: any[]): void;
+   	info(...messages: any[]): void;
+   	warn(...messages: any[]): void;
+   	error(...messages: any[]): void;
+   	fatal(...messages: any[]): void;
+   	notify(...messages: any[]): void;
+   	withTag(tag: string): TaggedLogger;
+   }
+   ```
+
+   `TaggedLogger` methods may be `null`:
+
+   ```typescript
+   interface TaggedLogger {
+   	trace: ((...messages: any[]) => void) | null;
+   	debug: ((...messages: any[]) => void) | null;
+   	info: ((...messages: any[]) => void) | null;
+   	warn: ((...messages: any[]) => void) | null;
+   	error: ((...messages: any[]) => void) | null;
+   	fatal: ((...messages: any[]) => void) | null;
+   	notify: ((...messages: any[]) => void) | null;
+   }
+   ```
+
+4. **Know the log levels** — From least to most severe:
+
+   | Level    | Description                                                          |
+   | -------- | -------------------------------------------------------------------- |
+   | `trace`  | Highly detailed internal execution tracing.                          |
+   | `debug`  | Diagnostic information useful during development.                    |
+   | `info`   | General operational events.                                          |
+   | `warn`   | Potential issues that don't prevent normal operation.                |
+   | `error`  | Errors that affect specific operations.                              |
+   | `fatal`  | Critical errors causing process termination.                         |
+   | `notify` | Important operational milestones. Always logged regardless of level. |
+
+   The default log level is `warn`. Setting a level includes that level and all more-severe levels.
+
+5. **Enable console capture when porting existing code** — When `logging.console: true` is set, writes via `console.log`, `console.warn`, `console.error`, etc. are appended verbatim to `hdb.log`. Captured lines do **not** pass through `logger`'s level filter. Prefer `logger` directly in production code so that level filtering and tagging apply. Console capture is intended as a convenience for porting existing code and for debugging.
+
+6. **Know where logs are written** — All standard log output goes to `<ROOTPATH>/log/hdb.log` (default: `~/hdb/log/hdb.log`). To also log to `stdout`/`stderr`, set `logging.stdStreams: true`.
+
+## Examples
+
+### Basic logging in a resource
+
+```javascript
+export class MyResource extends Resource {
+	async get(id) {
+		logger.debug('Fetching record', { id });
+		const record = await super.get(id);
+		if (!record) {
+			logger.warn('Record not found', { id });
+		}
+		return record;
+	}
+
+	async put(record) {
+		logger.info('Updating record', { id: record.id });
+		try {
+			return await super.put(record);
+		} catch (err) {
+			logger.error('Failed to update record', err);
+			throw err;
+		}
+	}
+}
+```
+
+### Tagged logging with `withTag()`
+
+```javascript
+const log = logger.withTag('my-resource');
+
+export class MyResource extends Resource {
+	async get(id) {
+		log.debug?.('Fetching record', { id });
+		const record = await super.get(id);
+		if (!record) {
+			log.warn?.('Record not found', { id });
+		}
+		return record;
+	}
+
+	async put(record) {
+		log.info?.('Updating record', { id: record.id });
+		try {
+			return await super.put(record);
+		} catch (err) {
+			log.error?.('Failed to update record', err);
+			throw err;
+		}
+	}
+}
+```
+
+Tagged entries appear in `hdb.log` with the tag in the header:
+
+```
+2023-03-09T14:25:05.269Z [info] [my-resource]: Updating record
+```
+
+## Notes
+
+- All log output is written to `<ROOTPATH>/log/hdb.log`. The `logger` global writes to this file at the configured `logging.external` level.
+- Log entry format for `logger`: `<timestamp> [<level>] [<thread>/<id>]: <message>`
+- Log entry format for `TaggedLogger`: `<timestamp> [<level>] [<tag>]: <message>`
+- `console.log` output is only forwarded to `hdb.log` when `logging.console: true` is explicitly set; it is not forwarded by default.
+- When logging to standard streams, run Harper in the foreground (`harper`, not `harper start`).
+- `TaggedLogger` is bound to the configured log level at creation time — always use `?.` on its methods.