@harperfast/template-react-ts-studio 1.12.2 → 1.12.4

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

@@ -8,17 +8,17 @@ metadata:
     - >-
       fabric/cluster-creation-management.md#Connecting the Harper CLI to a
       Cluster
-  sourceCommit: 6bf676d4bde158fcd08a81565556a0ee91768274
-  inputHash: 8c8b2fabac08a561
+  sourceCommit: 677ad213d67822e109c83619e181ca23a59823db
+  inputHash: e5586ad2bcc7c12a
 ---
 
 # Deploying to Harper Fabric
 
-Instructions for the agent to follow when deploying a Harper application to a remote Harper Fabric cluster.
+Instructions for the agent to follow when deploying a Harper application to a remote Harper Fabric cloud cluster.
 
 ## When to Use
 
-Apply this rule when deploying a Harper application to a remote Harper Fabric cluster or any remote Harper instance. This includes first-time deploys, redeployments, rollbacks, and CI/CD pipeline deployments. See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) to set up a cluster before deploying.
+Apply this rule when deploying a Harper application to a remote Harper Fabric cluster or any remote Harper instance. This includes first-time deploys, redeployments, rollbacks, CI/CD pipeline deploys, and provisioning credentials for private repositories. See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) for setting up the cluster before deploying.
 
 ## How It Works
 
@@ -29,7 +29,7 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
    # Provide cluster username and password when prompted
    ```
 
-2. **Deploy the application**: Run `harper deploy` with the required parameters. After logging in, no credentials need to be repeated.
+2. **Deploy the application**: After login, run `harper deploy` without repeating credentials. Set `restart=true` and `replicated=true` for a production deploy.
 
    ```bash
    harper deploy \
@@ -40,30 +40,42 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
      replicated=true
    ```
 
-3. **Choose a package source**: Set the `package` parameter to any valid npm dependency value, or omit it to package and upload the current local directory.
+3. **Use environment variables for CI/CD**: Instead of `harper login`, export credentials as environment variables before calling `harper deploy`.
 
-   | Value                                                | Effect                                           |
-   | ---------------------------------------------------- | ------------------------------------------------ |
-   | _(omitted)_                                          | Packages and deploys the current local directory |
-   | `"@harperdb/status-check"`                           | npm package                                      |
-   | `"HarperDB/status-check"`                            | GitHub shorthand                                 |
-   | `"https://github.com/HarperDB/status-check"`         | GitHub URL                                       |
-   | `"git+ssh://git@github.com:HarperDB/secret-app.git"` | Private repo via SSH                             |
-   | `"https://example.com/application.tar.gz"`           | Tarball URL                                      |
+   ```bash
+   export HARPER_CLI_USERNAME=<username>
+   export HARPER_CLI_PASSWORD=<password>
+   harper deploy \
+     project=<name> \
+     package=<package> \
+     target=<remote> \
+     restart=true \
+     replicated=true
+   ```
+
+4. **Choose a package source**: The `package` field accepts any valid npm dependency value. Select the form that matches your source:
+
+   | Source                  | `package` value                                      |
+   | ----------------------- | ---------------------------------------------------- |
+   | Current local directory | Omit `package`                                       |
+   | npm package             | `"@harperdb/status-check"`                           |
+   | GitHub (public)         | `"HarperFast/status-check"` or full URL              |
+   | Private repo (SSH)      | `"git+ssh://git@github.com:HarperDB/secret-app.git"` |
+   | Tarball                 | `"https://example.com/application.tar.gz"`           |
 
    For git tags, use the `semver` directive:
 
    ```
-   HarperDB/application-template#semver:v1.0.0
+   HarperFast/application-template#semver:v1.0.0
    ```
 
-4. **Deploy by reference (optional)**: Instead of uploading a snapshot, send a pinned git reference so the cluster fetches and builds that exact commit. Use `by_ref=true` to resolve the current commit from the local repository automatically.
+5. **Deploy by reference for reproducible deploys**: Pass `by_ref=true` to send a pinned git SHA instead of uploading a snapshot. The cluster fetches and builds from that exact commit.
 
    ```bash
    harper deploy by_ref=true restart=true replicated=true
    ```
 
-   Use `ref` to deploy a specific commit, tag, or branch (resolved to a full SHA before sending):
+   Use `ref` to target a specific commit, tag, or branch (resolved to a full SHA before sending):
 
    ```bash
    # Deploy a specific tag
@@ -73,53 +85,32 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
    harper deploy ref=9f8c2a1 restart=true replicated=true
    ```
 
-   **Key `by_ref` parameters:**
-
-   | Parameter    | Required | Description                                                                                                                 |
-   | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
-   | `by_ref`     | —        | Build the package reference from the local repository                                                                       |
-   | `ref`        | optional | Deploy a specific commit, tag, or branch instead of `HEAD`. Implies `by_ref`.                                               |
-   | `credential` | optional | Set to `true` to authenticate the clone with the stored credential for the repository's host. Omit for public repositories. |
-
-   > Commit and push before deploying by reference. The cluster clones from the remote and only sees pushed commits. Run `git fetch` if the unpushed-commit check fires for a commit you know you pushed.
+   **Key constraints for `ref` values:**
+   - Must name something a clone can fetch: `refs/heads/*` and `refs/tags/*`, or a bare branch or tag name.
+   - Anything else (e.g., `refs/pull/123/head`) is rejected up front.
+   - If a ref can't be resolved, the deploy stops — run `git fetch` and retry, or pass a full commit SHA.
+   - Commit and push before deploying: the cluster clones from the remote and only sees pushed commits.
 
-5. **Authenticate for CI/CD**: Use environment variables instead of `harper login` for automated pipelines.
+6. **Deploy private repositories by reference**: Pass `credential=true` alongside `by_ref=true`. The CLI attaches a credentials reference; the cluster resolves the secret in memory at clone time — no token travels in the operation body or lands on disk.
 
    ```bash
-   export HARPER_CLI_USERNAME=<username>
-   export HARPER_CLI_PASSWORD=<password>
-   harper deploy \
-     project=<name> \
-     package=<package> \
-     target=<remote> \
-     restart=true \
-     replicated=true
+   harper deploy by_ref=true credential=true restart=true replicated=true
    ```
 
-6. **Provision credentials for private repositories**: Run `harper deploy setup=true` once per component and source to provision a deploy credential. Run this with an administrative credential, not the CI identity.
+7. **Provision a deploy credential for private sources**: Run `harper deploy setup=true` once per component and source. This is interactive and requires **super_user** — run it with an administrative credential, not the CI identity.
 
    ```bash
    harper deploy setup=true
    ```
 
-   Then pass `credential=true` on subsequent deploys:
-
-   ```bash
-   harper deploy by_ref=true credential=true restart=true replicated=true
-   ```
-
-7. **Use inline auth for one-off commands (not recommended for production)**: Pass `auth_username` and `auth_password` directly. These take precedence over environment variables and saved login tokens.
+   This command:
+   1. Fetches the cluster's public key with `get_secrets_public_key`.
+   2. Encrypts the token locally into an `enc:v1:` envelope.
+   3. Stores only the ciphertext with `set_secret`, in the component-scoped tier.
+   4. Grants the component permission to resolve it with `grant_secret`.
+   5. Prints the `credentials` reference for the deploy to use.
 
-   ```bash
-   harper deploy \
-     project=<name> \
-     package=<package> \
-     auth_username=<username> \
-     auth_password=<password> \
-     target=<remote> \
-     restart=true \
-     replicated=true
-   ```
+   Use a **fine-grained** personal access token (PAT) scoped to **Contents: Read-only** on the specific repository. Avoid session tokens from `gh` CLI — they typically carry `repo`, `read:org`, `gist`, and `workflow` scopes across your whole account.
 
 ## Examples
 
@@ -129,60 +120,47 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
 harper login https://my-cluster.harperdbcloud.com
 harper deploy \
   project=my-app \
-  package="@myorg/my-app" \
+  package="HarperFast/my-app" \
   target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
-**Deploy current directory as a snapshot:**
+**CI/CD deploy using environment variables:**
 
 ```bash
+export HARPER_CLI_USERNAME=admin
+export HARPER_CLI_PASSWORD=secret
 harper deploy \
   project=my-app \
+  package="HarperFast/my-app" \
   target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
-**Deploy a pinned tag by reference:**
-
-```bash
-harper deploy ref=v1.2.0 restart=true replicated=true
-```
-
-**Deploy a private repository by reference with a stored credential:**
-
-```bash
-harper deploy by_ref=true credential=true restart=true replicated=true
-```
-
-**GitHub Actions — deploy the pull request head commit explicitly:**
+**Deploy by reference in GitHub Actions (pull request):**
 
 ```bash
 harper deploy ref=${{ github.event.pull_request.head.sha }} restart=true replicated=true
 ```
 
-**CI/CD deploy using environment variables:**
+**Deploy a private repo by reference with a provisioned credential:**
 
 ```bash
-export HARPER_CLI_USERNAME=<username>
-export HARPER_CLI_PASSWORD=<password>
-harper deploy \
-  project=my-app \
-  package="HarperDB/my-app#semver:v1.0.0" \
-  target=https://my-cluster.harperdbcloud.com \
-  restart=true \
-  replicated=true
+# Provision once (run as super_user)
+harper deploy setup=true
+
+# Deploy subsequently
+harper deploy by_ref=true credential=true restart=true replicated=true
 ```
 
 ## Notes
 
-- `harper login` stores an authentication token so subsequent `harper deploy` commands do not require credentials to be repeated.
-- Inline `auth_username`/`auth_password` parameters take precedence over environment variables, which take precedence over saved login tokens.
-- For SSH-based private repos, register keys with the `add_ssh_key` operation before deploying.
-- `by_ref` deploys build from source on each cluster node. If your application requires a build step that cannot run on the node, deploy a built payload (omit `by_ref`) instead.
-- `harper deploy setup=true` requires **super_user** privileges. Provision credentials with an administrative account, not the CI identity.
-- Tags and branches passed to `ref` are resolved to a full commit SHA locally before the deploy is sent. If resolution fails, run `git fetch` and retry, or pass a full commit SHA directly.
-- The `refs/pull/<n>/head` style refs are rejected; use `ref=${{ github.event.pull_request.head.sha }}` in GitHub Actions pull request workflows instead.
-- Deploy credentials provisioned via `harper deploy setup=true` are stored scoped to the component and reused on every subsequent deploy, including rollbacks.
+- `auth_username` and `auth_password` can be passed directly as deploy parameters for one-off commands, but this is not recommended for production. Dedicated authentication parameters take precedence over environment variables and saved login tokens.
+- The `enc:v1:` envelope means the plaintext token never leaves your machine — only ciphertext is stored and replicated.
+- Deploy credentials are stored scoped to the component, never in the global `processEnv` tier. If a global secret exists at the derived name, it is converted to the component-scoped tier automatically.
+- Because stored credentials are durable, later deploys and rollbacks reuse them without re-entering anything.
+- The unpushed-commit check is skipped under GitHub Actions; the dirty-tree warning still applies.
+- Deploying by reference means the cluster installs and builds from source. If your application requires a build step that cannot run on the node, deploy the built output as a payload deploy instead.
+- For SSH-based private repos, use the `add_ssh_key` operation to register keys before deploying.

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

@@ -13,30 +13,32 @@ metadata:
     - >-
       reference/v5/resources/resource-api.md#`addTo(property: string, value:
       number)`
-    - reference/v5/components/javascript-environment.md#Module Loading
-  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
-  inputHash: ace5c3f4a0ad4519
+    - reference/v5/components/javascript-environment.md#Module Formats
+  sourceCommit: 9e6ecf87dd25bb488ad44dc2876ca6439ccd682e
+  inputHash: f5629f73cde74764
 ---
 
 # Programmatic Table Requests
 
-Instructions for the agent to interact with Harper tables programmatically using the `tables` object and its query API.
+Instructions for the agent to interact with Harper tables programmatically using the `tables` object, the Query API, and transactions.
 
 ## When to Use
 
-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(`.
+Apply this rule when writing server-side Harper component code that reads from or writes to tables directly — for example, in HTTP handlers, background jobs, timers, or SSR render functions. Use it whenever you need to construct queries with `conditions`, `sort`, `select`, `limit`, or `offset`, or when you need explicit transaction control via `transaction()`.
 
 ## How It Works
 
-1. **Import `tables`**: Pull `tables` from the `harper` package. Each property on `tables` corresponds to a table defined in `schema.graphql`.
+1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a named property of `tables`. Each property is the table class implementing the Resource API.
 
    ```javascript
-   import { tables } from 'harper';
+   import { tables, transaction } from 'harper';
    const { Product } = tables;
-   // same as: databases.data.Product
+   // equivalent to: databases.data.Product
    ```
 
-2. **Define your schema**: Declare tables with `@table` in `schema.graphql`. Each type becomes a property on `tables`.
+   For standalone components, run `npm link harper` so imports resolve to the live runtime.
+
+2. **Define your schema with `@table`**: Tables must be declared in `schema.graphql`. Mark attributes you intend to sort or filter on with `@indexed`.
 
    ```graphql
    type Product @table {
@@ -46,15 +48,7 @@ Apply this rule when writing server-side code that reads from or writes to Harpe
    }
    ```
 
-3. **Create and modify records**: Use `create`, `patch`, and `get` for basic CRUD.
-
-   ```javascript
-   const created = await Product.create({ name: 'Shirt', price: 9.5 });
-   await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
-   const record = await Product.get(created.id);
-   ```
-
-4. **Query with `search(`**: Pass a query object to `Product.search(query)`. It returns an async iterable.
+3. **Query records with `search(`**: Pass a Query object to `search(`. Iterate results with `for await`.
 
    ```javascript
    const query = {
@@ -65,7 +59,7 @@ Apply this rule when writing server-side code that reads from or writes to Harpe
    }
    ```
 
-5. **Build `conditions`**: Each condition object filters records. Nest conditions with `operator` for boolean logic.
+4. **Build `conditions`**: Each condition object supports these properties:
 
    | Property     | Description                                                                                                                                              |
    | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -75,29 +69,31 @@ Apply this rule when writing server-side code that reads from or writes to Harpe
    | `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.
+5. **Control result shape with `select`**: Pass an array of property names, a single string, or nested objects for relationships.
 
    ```javascript
-   // Array of names
+   // Scalar fields only
    Product.search({ select: ['name', 'price'] });
 
-   // Nested relationship select
+   // Partial related record
    Book.get({ id: 42, select: ['id', 'title', { name: 'author', select: ['name'] }] });
    ```
 
-   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
+   Special `select` values: `$id`, `$updatedtime`, `$distance`.
 
-7. **Use `addTo`** for concurrent-safe numeric increments (CRDT incrementation, safe across threads and nodes).
+6. **Paginate with `limit` and `offset`**:
 
    ```javascript
-   const record = await Product.update(target.id);
-   record.addTo('quantity', -1);
+   Product.search({ conditions: [...], limit: 20, offset: 40 });
    ```
 
-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.
+7. **Sort with `sort`**: The `sort` object accepts `attribute`, `descending` (default `false`), and `next` for tie-breaking. Harper uses an index for sort order — the sort `attribute` must be `@indexed`, **or** at least one entry in `conditions` must be present.
+
+   Sorting by a non-indexed attribute with zero conditions raises:
+
+   > `HdbError: <attribute> is not indexed and not combined with any other conditions`
+
+   Note: `@primaryKey` alone is treated as not indexed for sort purposes. To scan the whole table in primary-key order, add an open-ended condition:
 
    ```javascript
    Product.search({
@@ -106,15 +102,78 @@ Apply this rule when writing server-side code that reads from or writes to Harpe
    });
    ```
 
-   | 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)            |
+   Alternatively, pass `allowFullScan: true` to permit an unconditional ordered scan, or omit `sort` entirely to iterate without an index requirement.
+
+8. **Debug query planning with `explain` and `enforceExecutionOrder`**:
+   - `explain: true` — returns conditions reordered as Harper will execute them.
+   - `enforceExecutionOrder: true` — forces conditions to execute in the order supplied, disabling automatic re-ordering.
+
+9. **Use `addTo` for concurrent-safe numeric updates**: `addTo` uses CRDT incrementation, safe across threads and nodes.
+
+   ```javascript
+   const record = await Product.update(32);
+   record.addTo('quantity', -1);
+   ```
+
+10. **Wrap background work in `transaction()`**: HTTP handlers get a transaction automatically. Use `transaction()` explicitly for timers, background jobs, or any code outside a request context. Always `await` the call and `catch` errors.
+
+    ```javascript
+    await transaction(async (txn) => {
+    	for (let item of data) {
+    		await MyTable.put(item, txn);
+    	}
+    });
+    ```
+
+    The `txn` object exposes:
+
+    | Member                | Description                                            |
+    | --------------------- | ------------------------------------------------------ |
+    | `commit()`            | Commits the current transaction                        |
+    | `abort()`             | Aborts and resets the transaction                      |
+    | `resetReadSnapshot()` | Resets the read snapshot to the latest committed state |
+    | `timestamp`           | Timestamp associated with the current transaction      |
+
+    **Atomicity**: all tables in the same database share one transactional context — writes across multiple tables commit atomically. Tables in different databases each get their own transaction with no cross-database atomicity guarantee.
+
+    If `transaction()` is called with a context that already has an active transaction, it reuses that transaction — safe to call defensively.
+
+11. **Keep `harper` external when bundling for SSR**: In `vite.config`, mark `harper` as external so it resolves to the runtime rather than being bundled.
+
+    ```javascript
+    // vite.config
+    ssr: {
+    	external: ['harper'];
+    }
+    ```
 
 ## Examples
 
-**Nested conditions with `or`:**
+### Full CRUD sequence
+
+```javascript
+import { tables } from 'harper';
+const { Product } = tables;
+
+// Create
+const created = await Product.create({ name: 'Shirt', price: 9.5 });
+
+// Patch
+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);
+
+// Query with conditions
+const query = {
+	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
+};
+for await (const record of Product.search(query)) {
+	// process record
+}
+```
+
+### Nested conditions with `or`
 
 ```javascript
 Product.search({
@@ -131,25 +190,41 @@ Product.search({
 });
 ```
 
-**Chained attribute reference (relationship join):**
+### Chained attribute reference (join/relationship)
 
 ```javascript
 Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-**Deep nested `select` across multiple relationships:**
+### Background job with `transaction()`
 
 ```javascript
-Product.search({
-	select: [
-		'id',
-		'name',
-		{ name: 'segments', select: ['id', 'name', { name: 'client', select: ['id', 'name'] }] },
-	],
-});
+import { isMainThread } from 'node:worker_threads';
+import { tables, transaction } from 'harper';
+const { MyTable } = tables;
+
+if (isMainThread) {
+	let running = false;
+	setInterval(async () => {
+		if (running) return;
+		running = true;
+		try {
+			let data = await (await fetch('https://example.com/data')).json();
+			await transaction(async (txn) => {
+				for (let item of data) {
+					await MyTable.put(item, txn);
+				}
+			});
+		} catch (error) {
+			logger.error('hourly import failed', error);
+		} finally {
+			running = false;
+		}
+	}, 3600000);
+}
 ```
 
-**SSR usage — read directly from `tables` in a render function:**
+### SSR render with `tables`
 
 ```typescript
 import { tables } from 'harper';
@@ -162,9 +237,7 @@ export async function render(url: string): Promise<string> {
 
 ## Notes
 
-- 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.
+- `tables` and `databases` do **not** automatically apply role permissions — calls run in a trusted server-side context. Apply your own authorization controls before exposing results.
+- Destructive operations (`update`, `patch`, `delete`) act on live data and are not easily reversible. Scope them with specific `conditions` and validate the affected set before writing.
+- `tables` is the same live, process-wide object whether accessed as a global or via `import { tables } from 'harper'`. A record written through one component is immediately visible to every other.
+- Run `npm link harper` for components in their own directory to ensure typings match the running installation.