@harperfast/template-react-ts-studio 1.11.2 → 1.11.4

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

@@ -8,28 +8,32 @@ metadata:
     - >-
       fabric/cluster-creation-management.md#Connecting the Harper CLI to a
       Cluster
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: ccdefbbf8f3b8657
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: 39faf283b6964e93
 ---
 
 # Deploying to Harper Fabric
 
-Instructions for the agent to follow when deploying a Harper application to the Harper Fabric cloud using the Harper CLI.
+Instructions for the agent to follow when deploying a Harper application to a remote Harper Fabric cloud instance.
 
 ## 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.
+Apply this rule when deploying a Harper application to a remote Harper Fabric cluster or any remote Harper instance. Use it when setting up CI/CD pipelines that push application packages to a target environment, or when deploying from a local directory or external package source to a remote cluster.
 
 ## 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)).
+1. **Obtain the target URL**: Get the cluster's **Application URL** from the cluster's **Config → Overview** page. This is the hostname passed to all CLI commands as `target`.
+
+2. **Authenticate with `harper login`**: Run `harper login` once to store an authentication token locally. The CLI also writes `HARPER_CLI_TARGET` to a local `.env` for subsequent commands.
 
    ```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.
+   See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) for setting up a cluster before this step.
+
+3. **Deploy with `harper deploy`**: After logging in, deploy without repeating credentials.
 
    ```bash
    harper deploy \
@@ -40,83 +44,93 @@ Apply this rule when deploying a Harper application to a remote Harper instance
      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:
+4. **Use environment variables for CI/CD**: Instead of `harper login`, export credentials as environment variables before running `harper deploy`.
 
-   ```
-   HarperDB/application-template#semver:v1.0.0
+   ```bash
+   export HARPER_CLI_USERNAME=<username>
+   export HARPER_CLI_PASSWORD=<password>
+   harper deploy \
+     project=<name> \
+     package=<package> \
+     target=<remote> \
+     restart=true \
+     replicated=true
    ```
 
-4. **Authenticate for CI/CD pipelines**: Use environment variables instead of interactive login. Set credentials before running `harper deploy`.
+5. **Use inline auth parameters for one-off commands**: Pass `auth_username` and `auth_password` directly. These take precedence over environment variables and saved login tokens. Not recommended for production.
 
    ```bash
-   export HARPER_CLI_USERNAME=<username>
-   export HARPER_CLI_PASSWORD=<password>
    harper deploy \
      project=<name> \
      package=<package> \
+     auth_username=<username> \
+     auth_password=<password> \
      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.
+6. **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                                                | Meaning                                        |
+   | ---------------------------------------------------- | ---------------------------------------------- |
+   | _(omitted)_                                          | Package and deploy the current local directory |
+   | `"@harperdb/status-check"`                           | npm package                                    |
+   | `"HarperDB/status-check"`                            | GitHub shorthand                               |
+   | `"https://github.com/HarperDB/status-check"`         | GitHub full URL                                |
+   | `"git+ssh://git@github.com:HarperDB/secret-app.git"` | Private repo via SSH                           |
+   | `"https://example.com/application.tar.gz"`           | Remote tarball                                 |
+
+   For pinned git tags, use the `semver` directive:
+
+   ```
+   HarperDB/application-template#semver:v1.0.0
+   ```
+
+   For SSH-based private repos, register keys with the `Add SSH Key` operation before deploying.
 
 ## Examples
 
-**Interactive login then deploy (recommended):**
+**Interactive login then deploy:**
 
 ```bash
-# Log in once
-harper login <remote>
-# Provide your username and password when prompted
+harper login https://my-cluster.harperdbcloud.com
+# Enter username and password when prompted
 
-# Subsequently deploy without credentials
 harper deploy \
-  project=<name> \
-  package=<package> \
-  target=<remote> \
+  project=my-app \
+  package="HarperDB/application-template#semver:v1.0.0" \
+  target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
-**Deploy with inline credentials (not recommended for production):**
+**CI/CD pipeline deploy using environment variables:**
 
 ```bash
+export HARPER_CLI_USERNAME=admin
+export HARPER_CLI_PASSWORD=secret
 harper deploy \
-  project=<name> \
-  package=<package> \
-  username=<username> \
-  password=<password> \
-  target=<remote> \
+  project=my-app \
+  package="@harperdb/status-check" \
+  target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
-**Deploy a specific GitHub release by semver tag:**
+**Deploy current local directory:**
 
 ```bash
 harper deploy \
   project=my-app \
-  package="HarperDB/application-template#semver:v1.0.0" \
-  target=<remote> \
+  target=https://my-cluster.harperdbcloud.com \
   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.
+- Authentication precedence (highest to lowest): inline `auth_username`/`auth_password` parameters → environment variables (`HARPER_CLI_USERNAME`/`HARPER_CLI_PASSWORD`) → saved login token from `harper login`.
+- `harper login` writes `HARPER_CLI_TARGET` to a local `.env`, so subsequent commands do not need `target` repeated if that file is present.
+- Harper generates a `package.json` from component configurations and resolves packages via `npm install`. A local file path creates a symlink, so changes are picked up between restarts without redeploying.
+- For SSH-based private repos, register the SSH key with the `Add SSH Key` operation before running `harper deploy`.

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

@@ -7,8 +7,8 @@ metadata:
   mode: generate
   sources:
     - reference/v5/environment-variables/overview.md
-  sourceCommit: 42231db17c025a4a455e3d91875fad4084a01cb5
-  inputHash: fe610fc245226357
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: b4db5ede6b93d426
 ---
 
 # Load Environment Variables with loadEnv
@@ -17,18 +17,18 @@ Instructions for the agent to follow when loading environment variables from `.e
 
 ## 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.
+Apply this rule when a Harper application needs to supply secrets, API endpoints, or other configuration values to component code via `process.env` without hardcoding them. Use `loadEnv` any time you need to load one or more `.env` files at application startup.
 
 ## 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.
+1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` as the first entry in `config.yaml`. 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.
+2. **Place `loadEnv` first**: Harper is a single-process application. List `loadEnv` before all other components so that environment variables are available on `process.env` before dependent components start.
 
    ```yaml
    # config.yaml — loadEnv must come first
@@ -41,9 +41,9 @@ Apply this rule when a Harper application needs to load secrets or configuration
      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.
+3. **Access loaded values in component code**: After `loadEnv` runs, all loaded values are available on `process.env` and shared across all components.
 
-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.
+4. **Control override behavior**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to make loaded values win instead.
 
    ```yaml
    loadEnv:
@@ -51,14 +51,17 @@ Apply this rule when a Harper application needs to load secrets or configuration
      override: true
    ```
 
-5. **Load multiple files when required**: Supply a list of files or a glob pattern. Files are loaded in the order specified.
+5. **Load multiple files**: Pass an array of paths or a glob pattern to `files`. Files are loaded in the order specified.
+
    ```yaml
    loadEnv:
      files:
        - '.env'
        - '.env.local'
    ```
-   or
+
+   or with a glob:
+
    ```yaml
    loadEnv:
      files: 'env-vars/*'
@@ -73,17 +76,23 @@ Apply this rule when a Harper application needs to load secrets or configuration
 
 ## Examples
 
-**Minimal setup — single `.env` file:**
+**Single file, default behavior:**
 
 ```yaml
+# config.yaml
 loadEnv:
   files: '.env'
+
+rest: true
+
+myApp:
+  files: './src/*.js'
 ```
 
-**Full `config.yaml` with load order, multiple files, and override:**
+**Multiple files with override:**
 
 ```yaml
-# config.yaml — loadEnv must come first
+# config.yaml
 loadEnv:
   files:
     - '.env'
@@ -96,16 +105,8 @@ 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.
+- `loadEnv` loads values into `process.env` for **application** code only — it does not configure Harper itself.
+- Harper's own instance-wide configuration is composed at startup **before** any component's `loadEnv` runs. Variables such as `HARPER_CONFIG`, `HARPER_SET_CONFIG`, and `HARPER_DEFAULT_CONFIG` delivered through a `.env` file are read too late and are ignored. Set Harper configuration directly in the configuration file or export variables in the real process/container environment before Harper starts.
+- For production credentials, prefer the encrypted secrets store over a committed `.env` file. Secrets are also delivered to components via `process.env`.

package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md

@@ -14,8 +14,8 @@ metadata:
       reference/v5/resources/resource-api.md#`addTo(property: string, value:
       number)`
     - reference/v5/components/javascript-environment.md#Module Loading
-  sourceCommit: be709f9978319dcdb669c05d794effc82bcda8b7
-  inputHash: 3d2417fbff687c42
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: ace5c3f4a0ad4519
 ---
 
 # Programmatic Table Requests
@@ -24,11 +24,11 @@ Instructions for the agent to interact with Harper tables programmatically using
 
 ## When to Use
 
-Apply this rule when writing server-side Harper code that reads from or writes to tables directly — for example, in request handlers, background jobs, or SSR entry points — instead of going through the REST API. Use it whenever you need to construct queries with `conditions`, paginate results, select specific fields, or perform CRDT-safe mutations with `addTo`.
+Apply this rule when writing server-side code that reads from or writes to Harper tables directly — for example, in request handlers, background jobs, or SSR rendering — without going through the REST API. Use it whenever you need to construct queries with `conditions`, `select`, `sort`, or `search(`.
 
 ## How It Works
 
-1. **Import `tables`**: Import from the `harper` package. Each table defined in `schema.graphql` with `@table` is available as a named property.
+1. **Import `tables`**: Pull `tables` from the `harper` package. Each property on `tables` corresponds to a table defined in `schema.graphql`.
 
    ```javascript
    import { tables } from 'harper';
@@ -36,10 +36,9 @@ Apply this rule when writing server-side Harper code that reads from or writes t
    // same as: databases.data.Product
    ```
 
-2. **Define your schema**: Declare tables in `schema.graphql` using `@table` and `@primaryKey`.
+2. **Define your schema**: Declare tables with `@table` in `schema.graphql`. Each type becomes a property on `tables`.
 
    ```graphql
-   # schema.graphql
    type Product @table {
    	id: Long @primaryKey
    	name: String
@@ -47,57 +46,75 @@ Apply this rule when writing server-side Harper code that reads from or writes t
    }
    ```
 
-3. **Create and mutate records**: Use `create`, `patch`, `get`, and `update` on the table class.
+3. **Create and modify records**: Use `create`, `patch`, and `get` for basic CRUD.
 
    ```javascript
-   // Create a new record (id auto-generated)
    const created = await Product.create({ name: 'Shirt', price: 9.5 });
-
-   // Modify the record
    await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
-
-   // Retrieve by primary key
    const record = await Product.get(created.id);
    ```
 
-4. **Query with `search(` and `conditions`**: Pass a query object to `search()` to filter records. Iterate the async result.
+4. **Query with `search(`**: Pass a query object to `Product.search(query)`. It returns an async iterable.
 
    ```javascript
    const query = {
    	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
    };
    for await (const record of Product.search(query)) {
-   	// ...
+   	// process record
    }
    ```
 
-5. **Use `select` to shape results**: Pass a `select` array to return only specific properties, including nested relationship fields.
+5. **Build `conditions`**: Each condition object filters records. Nest conditions with `operator` for boolean logic.
+
+   | Property     | Description                                                                                                                                              |
+   | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `attribute`  | Property name, or array for chained/joined properties (e.g. `['brand', 'name']`)                                                                         |
+   | `value`      | The value to match                                                                                                                                       |
+   | `comparator` | `equals` (default), `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `starts_with`, `contains`, `ends_with`, `between`, `not_equal` |
+   | `conditions` | Nested conditions array                                                                                                                                  |
+   | `operator`   | `and` (default) or `or` for the nested `conditions`                                                                                                      |
+
+6. **Use `select`** to control which properties are returned. Accepts an array of property names, a string for a single property, or nested objects for relationships.
 
    ```javascript
-   const book = await Book.get({ id: 42, select: ['id', 'title', 'author'] });
-   book.author.name; // full related Author record
+   // Array of names
+   Product.search({ select: ['name', 'price'] });
 
-   // Partial related record
-   const book = await Book.get({
-   	id: 42,
-   	select: ['id', 'title', { name: 'author', select: ['name'] }],
-   });
+   // Nested relationship select
+   Book.get({ id: 42, select: ['id', 'title', { name: 'author', select: ['name'] }] });
    ```
 
-6. **Use `addTo` for concurrent-safe increments**: Call `addTo` on a mutable resource instance obtained via `update()`. This uses CRDT incrementation, safe across threads and nodes.
+   Special `select` values:
+   - `$id` — returns the primary key regardless of its name
+   - `$updatedtime` — returns the last-updated timestamp
+   - `$distance` — returns the computed distance when querying a vector index
+
+7. **Use `addTo`** for concurrent-safe numeric increments (CRDT incrementation, safe across threads and nodes).
 
    ```javascript
-   static async post(target, data) {
-     const record = await this.update(target.id);
-     record.addTo('quantity', -1); // decrement safely across nodes
-   }
+   const record = await Product.update(target.id);
+   record.addTo('quantity', -1);
    ```
 
-7. **Scope destructive operations carefully**: `update`, `patch`, and `delete` operate directly on stored data. Always use specific `conditions`, validate the affected set before writing, and gate behind authorization controls.
+8. **Apply `sort`, `limit`, and `offset`** for ordering and pagination. A `sort` attribute must be `@indexed`, or at least one `conditions` entry must be present. Pass `allowFullScan: true` to permit an unconditional ordered scan.
+
+   ```javascript
+   Product.search({
+   	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
+   	sort: { attribute: 'id' },
+   });
+   ```
+
+   | Sort property | Description                                                |
+   | ------------- | ---------------------------------------------------------- |
+   | `attribute`   | Property name (or array for chained relationship property) |
+   | `descending`  | Sort descending if `true` (default: `false`)               |
+   | `next`        | Secondary sort to resolve ties (same structure)            |
 
 ## Examples
 
-### Nested conditions query
+**Nested conditions with `or`:**
 
 ```javascript
 Product.search({
@@ -114,23 +131,25 @@ Product.search({
 });
 ```
 
-### Chained attribute reference (relationship join)
+**Chained attribute reference (relationship join):**
 
 ```javascript
 Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-### Deep nested `select`
+**Deep nested `select` across multiple relationships:**
 
 ```javascript
-select: [
-	'id',
-	'name',
-	{ name: 'segments', select: ['id', 'name', { name: 'client', select: ['id', 'name'] }] },
-];
+Product.search({
+	select: [
+		'id',
+		'name',
+		{ name: 'segments', select: ['id', 'name', { name: 'client', select: ['id', 'name'] }] },
+	],
+});
 ```
 
-### SSR usage
+**SSR usage — read directly from `tables` in a render function:**
 
 ```typescript
 import { tables } from 'harper';
@@ -143,44 +162,9 @@ export async function render(url: string): Promise<string> {
 
 ## Notes
 
-### `conditions` comparator values
-
-| Comparator           | Description            |
-| -------------------- | ---------------------- |
-| `equals`             | Default equality match |
-| `greater_than`       | Strictly greater       |
-| `greater_than_equal` | Greater than or equal  |
-| `less_than`          | Strictly less          |
-| `less_than_equal`    | Less than or equal     |
-| `starts_with`        | String prefix match    |
-| `contains`           | String contains        |
-| `ends_with`          | String suffix match    |
-| `between`            | Range match            |
-| `not_equal`          | Inequality match       |
-
-### Query object options
-
-| Property                | Description                                                             |
-| ----------------------- | ----------------------------------------------------------------------- |
-| `conditions`            | Array of condition objects to filter records                            |
-| `operator`              | Top-level `and` (default) or `or` for the `conditions` array            |
-| `limit`                 | Maximum number of records to return                                     |
-| `offset`                | Number of records to skip (for pagination)                              |
-| `select`                | Properties to include in each returned record                           |
-| `sort`                  | Sort order object with `attribute`, `descending`, and `next` properties |
-| `explain`               | If `true`, returns conditions reordered as Harper will execute them     |
-| `enforceExecutionOrder` | If `true`, forces conditions to execute in the order supplied           |
-
-### `select` special properties
-
-- `$id` — Returns the primary key regardless of its name
-- `$updatedtime` — Returns the last-updated timestamp
-- `$distance` — Returns the computed distance from the target vector when the query uses a vector index
-
-### Relationship join behavior
-
-- Selecting a relationship **without** filtering on it behaves as a **LEFT JOIN** — records with no related row are still returned.
-- Adding a `conditions` entry on a related attribute (e.g. `attribute: ['author', 'name']`) behaves as an **INNER JOIN** — only records with a matching related row are returned.
-
-- Keep `harper` external when bundling for SSR (e.g. `ssr: { external: ['harper'] }` in `vite.config`) so it resolves to the runtime instead of being bundled.
-- `tables`, `databases`, and other Harper APIs are the same live, process-wide objects regardless of whether accessed as globals or via `import { tables } from 'harper'`.
+- Scope destructive operations (`update`, `patch`, `delete`) with specific `conditions` and validate the affected set before writing. These operate on live data and are not easily reversible.
+- Sorting by a bare `@primaryKey` with no conditions raises `HdbError: <attribute> is not indexed and not combined with any other conditions`. Add an open-ended condition or pass `allowFullScan: true`.
+- Selecting a relationship field without filtering on it behaves as a **LEFT JOIN**. Adding a condition on a related attribute (e.g. `attribute: ['author', 'name']`) behaves as an **INNER JOIN**.
+- A to-many relationship resolves to an array; `await` the property before iterating when needed.
+- `tables` and `databases.data` reference the same live objects — a record written through one component is immediately visible to all others.
+- Keep `harper` external when bundling for SSR (e.g. `ssr: { external: ['harper'] }` in `vite.config`) so it resolves to the runtime.