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

package/.agents/skills/harper-best-practices/AGENTS.md

@@ -1988,26 +1988,22 @@ await fetch('http://localhost:9926/JokeCache/1', {
 
 ### 4.1 Deploying to Harper Fabric
 
-Instructions for the agent to follow when deploying a Harper application to a remote Harper Fabric cloud instance.
+Instructions for the agent to follow when deploying a Harper application to a remote Harper Fabric cluster.
 
 #### When to Use
 
-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.
+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.
 
 #### How It Works
 
-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.
+1. **Authenticate against the remote cluster**: Run `harper login` once, pointing at the cluster's Application URL (found on the cluster's **Config → Overview** page). The CLI stores the token and writes `HARPER_CLI_TARGET` to a local `.env`.
 
    ```bash
    harper login <Application URL>
    # Provide cluster username and password when prompted
    ```
 
-   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.
+2. **Deploy the application**: Run `harper deploy` with the required parameters. After logging in, no credentials need to be repeated.
 
    ```bash
    harper deploy \
@@ -2018,7 +2014,50 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
      replicated=true
    ```
 
-4. **Use environment variables for CI/CD**: Instead of `harper login`, export credentials as environment variables before running `harper deploy`.
+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.
+
+   | 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                                      |
+
+   For git tags, use the `semver` directive:
+
+   ```
+   HarperDB/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.
+
+   ```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):
+
+   ```bash
+   # Deploy a specific tag
+   harper deploy ref=v1.2.0 restart=true replicated=true
+
+   # Roll back by deploying an older commit
+   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.
+
+5. **Authenticate for CI/CD**: Use environment variables instead of `harper login` for automated pipelines.
 
    ```bash
    export HARPER_CLI_USERNAME=<username>
@@ -2031,7 +2070,19 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
      replicated=true
    ```
 
-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.
+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.
+
+   ```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.
 
    ```bash
    harper deploy \
@@ -2044,59 +2095,56 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
      replicated=true
    ```
 
-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:**
+**Standard deploy after login:**
 
 ```bash
 harper login https://my-cluster.harperdbcloud.com
-# Enter username and password when prompted
-
 harper deploy \
   project=my-app \
-  package="HarperDB/application-template#semver:v1.0.0" \
+  package="@myorg/my-app" \
   target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
-**CI/CD pipeline deploy using environment variables:**
+**Deploy current directory as a snapshot:**
 
 ```bash
-export HARPER_CLI_USERNAME=admin
-export HARPER_CLI_PASSWORD=secret
 harper deploy \
   project=my-app \
-  package="@harperdb/status-check" \
   target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
-**Deploy current local directory:**
+**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:**
+
+```bash
+harper deploy ref=${{ github.event.pull_request.head.sha }} restart=true replicated=true
+```
+
+**CI/CD deploy using environment variables:**
+
+```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
@@ -2104,10 +2152,14 @@ harper deploy \
 
 #### Notes
 
-- 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`.
+- `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.
 
 ### 4.2 Creating a Harper Fabric Account and Cluster
 
@@ -2546,15 +2598,15 @@ myApp:
 
 ### 4.7 v5 Upgrade: Breaking Changes and Migration Guide
 
-Instructions for the agent to apply when migrating a Harper application to v5, covering all breaking changes and required code updates.
+Instructions for the agent to apply all required breaking-change fixes and recommended updates when migrating a Harper application to v5.
 
 #### When to Use
 
-Apply this rule when upgrading an existing Harper application to v5, when encountering runtime errors related to renamed packages, changed APIs, or security restrictions introduced in v5, or when reviewing application code for v5 compatibility before deployment.
+Apply this rule whenever upgrading an existing Harper application to v5, encountering v5 runtime errors related to module imports, `Table.get` return values, transaction context, process spawning, or VM module loading. Also apply when configuring `harperdb-config.yaml` for a v5 deployment.
 
 #### How It Works
 
-1. **Update the package import from `harperdb` to `harper`**: All application code must import from `harper` instead of `harperdb`.
+1. **Update the package import from `harperdb` to `harper`**: All application code must import from `harper`, not `harperdb`.
 
    ```javascript
    import { tables } from 'harper';
@@ -2562,74 +2614,160 @@ Apply this rule when upgrading an existing Harper application to v5, when encoun
 
 2. **Enable `allowInstallScripts` if packages require install scripts**: Harper v5 uses `--ignore-scripts` by default when installing packages. If your application requires installation scripts (e.g., to install additional binaries), set the `allowInstallScripts` option when deploying.
 
-3. **Update `Table.get` usage — return value is now a frozen record object**: `Table.get` now returns a plain record object, not a table class instance. The record is frozen; you cannot mutate it directly.
+3. **Update `Table.get` usage — return value is now a plain frozen record object**: `Table.get` no longer returns an instance of the table class. The returned object is frozen and does not have table instance methods.
    - Replace `wasLoadedFromSource()` with `target.loadedFromSource`:
 
      ```javascript
-     // Old — remove this pattern:
+     // OLD — no longer works
      const record = await Table.get(id);
-     if (record.wasLoadedFromSource()) { ... }
+     if (record.wasLoadedFromSource()) {
+     	// record was loaded from origin (not cache)
+     }
+     ```
 
-     // New — use loadedFromSource on the target:
-     const target = new RequestTarget();
+     ```javascript
+     // NEW
+     const target = new RequestTarget(); // note that this is passed in if you are overriding the `get` method
      target.id = id;
      const record = await Table.get(target);
      if (target.loadedFromSource) {
-       // record was loaded from origin (not cache)
+     	// record was loaded from origin (not cache)
      }
      ```
 
-   - Replace in-place mutation with object spread, since records are frozen:
+   - The record object still has `getUpdatedTime` and `getExpiresAt` methods available.
+
+   - **Handle frozen records**: The record object is frozen — you cannot add or remove properties directly. Copy and spread instead:
 
      ```javascript
-     // Old — throws in v5:
+     // OLD — throws in v5
      const record = await Table.get(id);
      record.property = 'changed';
+     ```
 
-     // New — copy instead of mutate:
+     ```javascript
+     // NEW
      let record = await Table.get(id);
      record = { ...record, property: 'changed' };
      ```
 
-   - `getUpdatedTime` and `getExpiresAt` methods remain available on the record object.
+4. **Update transaction and context handling**: Harper v5 uses asynchronous context tracking. Context and the current transaction are automatically carried to all calls, including `Table.get`. Code that previously omitted context to escape a transaction must now explicitly commit or start a new transaction.
+   - Import `getContext` and `transaction` from `harper`:
 
-4. **Update transaction and context handling**: Harper v5 uses asynchronous context tracking. `Table.get` and other table calls now automatically inherit the current transaction context. Code that previously omitted context to bypass a transaction will no longer work as expected. Use `getContext` (imported from `harper`) to access and commit the current transaction explicitly when you need to see updated data.
+     ```javascript
+     import { getContext, transaction } from 'harper';
+     ```
 
-   ```javascript
-   import { setTimeout as delay } from 'node:timers/promises';
-   import { getContext, transaction } from 'harper';
+   - Explicitly commit the current transaction before reading updated data:
 
-   class MyResource {
-   	static async get(target) {
-   		// Commit the current transaction to read latest data:
-   		await getContext().transaction.commit();
-   		// Optionally wrap each poll in a new transaction:
-   		while ((await transaction(() => Table.get(target))).status !== 'ready') {
-   			await delay(100);
-   		}
-   		return Table.get(target);
-   	}
-   }
-   ```
+     ```javascript
+     import { setTimeout as delay } from 'node:timers/promises';
+     import { getContext, transaction } from 'harper';
+     class MyResource {
+     	static async get(target) {
+     		await getContext().transaction.commit();
+     		while ((await transaction(() => Table.get(target))).status !== 'ready') {
+     			await delay(100);
+     		}
+     		return Table.get(target);
+     	}
+     }
+     ```
 
-5. **Register allowed spawn commands via `allowedSpawnCommands`**: Any use of `spawn`, `exec`, or `execFile` from `node:child_process` must reference executables listed in `applications.allowedSpawnCommands` in `harperdb-config.yaml`. Provide a `name` property in the options argument to ensure only a single named process is started across threads.
+5. **Register allowed spawn commands via `allowedSpawnCommands`**: Any `spawn` or `execFile` call may only launch executables listed in `applications.allowedSpawnCommands` in `harperdb-config.yaml`. The `exec` function is not usable through the substituted module, and `execSync` always throws. The `spawn`, `execFile`, and `fork` functions also require a `name` property in the `options` argument to prevent process multiplication across threads.
 
 6. **Replace `blob.save()` with `saveBeforeCommit`**: The `blob.save()` method has been removed. Use the `saveBeforeCommit` flag in the options passed to the `Blob` constructor instead.
 
-7. **Configure the `moduleLoader` and `lockdown` settings**: Harper v5 loads application modules through Node.js's VM module API. Control this behavior in `harperdb-config.yaml` under the `applications` key.
+7. **Configure the `moduleLoader` and `lockdown` settings**: Harper v5 loads application modules through Node.js's VM module API. Control all behavior in the `applications` section of `harperdb-config.yaml`:
 
-   | Setting            | Default              | Options                                             |
-   | ------------------ | -------------------- | --------------------------------------------------- |
-   | `moduleLoader`     | `vm-current-context` | `vm-current-context`, `vm`, `native`, `compartment` |
-   | `lockdown`         | `freeze-after-load`  | `freeze-after-load`, `freeze`, `ses`, `none`        |
-   | `dependencyLoader` | `auto`               | `auto`, `app`, `native`                             |
-   | `allowedDirectory` | `app`                | `app`, `any`                                        |
-   - Use `moduleLoader: native` to disable the VM loader entirely and restore pre-v5 behavior (application-specific context such as tagged logging and per-app `config` will not be available).
-   - Use `lockdown: none` as a temporary workaround if a dependency modifies intrinsic prototypes at runtime and throws a `TypeError`.
+   ```yaml
+   applications:
+     lockdown: freeze-after-load # default; see below
+     moduleLoader: vm-current-context # vm-current-context (default) | vm | native | compartment
+     dependencyLoader: auto # auto (default) | app | native
+     allowedDirectory: app # app (default) | any
+     allowedSpawnCommands: # see "Spawning new processes" above
+       - npm
+       - node
+     # allowedBuiltinModules: [] # if omitted, all Node.js built-ins are allowed
+   ```
+
+   **`moduleLoader` options:**
+
+   | Value                | Behavior                                                                                                                         |
+   | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+   | `vm-current-context` | Default. VM loader in Harper's own context; shares intrinsics with Harper for best compatibility.                                |
+   | `vm`                 | VM loader in a separate per-application context with its own intrinsics; stronger isolation but can cause `instanceof` failures. |
+   | `native`             | Standard Node.js `import()` with no VM loader; application-specific context (tagged logging, per-app `config`) not available.    |
+   | `compartment`        | SES Compartment-based loading; for specialized sandboxing only.                                                                  |
+
+   **`lockdown` options:**
+
+   | Value               | Behavior                                                      |
+   | ------------------- | ------------------------------------------------------------- |
+   | `freeze-after-load` | Default. Freezes intrinsics after all components have loaded. |
+   | `freeze`            | Freezes intrinsics before loading any application code.       |
+   | `ses`               | Full SES lockdown via the `ses` package; strictest.           |
+   | `none`              | No lockdown. Use as a temporary workaround only.              |
+   - To disable the VM loader entirely and restore pre-v5 behavior:
+
+     ```yaml
+     applications:
+       moduleLoader: native
+     ```
+
+   - To restrict which Node.js built-ins are accessible:
+
+     ```yaml
+     applications:
+       allowedBuiltinModules:
+         - fs
+         - path
+         - http
+     ```
+
+   - To allow loading modules from outside the application directory:
+
+     ```yaml
+     applications:
+       allowedDirectory: any
+     ```
 
 #### Examples
 
-##### Full `harperdb-config.yaml` `applications` block
+**Full transaction context migration:**
+
+```javascript
+import { setTimeout as delay } from 'node:timers/promises';
+import { getContext, transaction } from 'harper';
+
+class MyResource {
+	static async get(target) {
+		// Explicitly commit the transaction to see updated data
+		await getContext().transaction.commit();
+		// Start a new transaction for each get to see the latest data
+		while ((await transaction(() => Table.get(target))).status !== 'ready') {
+			await delay(100);
+		}
+		return Table.get(target);
+	}
+}
+```
+
+**`Table.get` with `loadedFromSource` check:**
+
+```javascript
+import { tables } from 'harper';
+
+const target = new RequestTarget();
+target.id = id;
+const record = await Table.get(target);
+if (target.loadedFromSource) {
+	// record was loaded from origin (not cache)
+}
+```
+
+**Full `harperdb-config.yaml` `applications` block:**
 
 ```yaml
 applications:
@@ -2642,38 +2780,14 @@ applications:
     - node
 ```
 
-##### Restricting allowed built-in modules
-
-```yaml
-applications:
-  allowedBuiltinModules:
-    - fs
-    - path
-    - http
-```
-
-##### Disabling the VM loader for package compatibility
-
-```yaml
-applications:
-  moduleLoader: native
-```
-
-##### Accessing context and committing a transaction
-
-```javascript
-import { getContext } from 'harper';
-
-await getContext().transaction.commit();
-```
-
 #### Notes
 
-- The `lockdown: freeze-after-load` default freezes `Object`, `Array`, `Promise`, `Map`, `Set`, and other intrinsics after all application code loads. Any code or dependency that mutates intrinsic prototypes after startup will throw a `TypeError`.
-- Under `lockdown: ses`, the constrained `fetch` (https-only) is applied only in `vm` mode. In `vm-current-context` and `native` modes, application code uses the standard global `fetch`.
-- In production, `allowedDirectory: app` prevents loading modules from outside the application's own directory tree. Set `allowedDirectory: any` only if your application legitimately requires it.
-- `dependencyLoader: native` is a narrower alternative to `moduleLoader: native` — it uses native loading only for npm packages while keeping the VM loader for first-party application source files.
-- Access Harper functions and APIs through the `harper` package rather than through global variables. Use `getContext` from `harper` to access request context without passing it explicitly through every call.
+- Use `getContext` (imported from `harper`) to access the current transaction anywhere in application code without passing context explicitly through every call.
+- Harper functions and APIs should be accessed through the `harper` package rather than through global variables.
+- Use `static` methods on Resources/Tables to implement endpoints, and access request information from the request `target` argument or via `getContext`.
+- `lockdown: none` is only a temporary workaround for dependencies that mutate intrinsic prototypes at runtime; do not leave it set in production.
+- Under `lockdown: ses`, the constrained (https-only) `fetch` is applied only in `vm` mode. In `vm-current-context` and `native` modes, application code uses the standard global `fetch`.
+- In production, `allowedDirectory: app` is the default; dev mode installs default to `allowedDirectory: any`.
 
 ### 4.8 Delegating to the Built-in Agent