@harperfast/template-react-ts-studio 1.12.1 → 1.12.3

package/.agents/skills/harper-best-practices/rules/v5-upgrade.md

@@ -7,8 +7,8 @@ metadata:
   mode: generate
   sources:
     - release-notes/v5-lincoln/v5-migration.md
-  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
-  inputHash: 5ee6407370219136
+  sourceCommit: 677ad213d67822e109c83619e181ca23a59823db
+  inputHash: 01c0fafb9afa68a0
 ---
 
 # v5 Upgrade: Breaking Changes and Migration Guide
@@ -17,60 +17,53 @@ Instructions for the agent to apply when migrating a Harper application to v5, c
 
 ## 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 when upgrading an existing Harper application to v5, when encountering runtime errors related to renamed packages, changed APIs, or security restrictions after a v5 upgrade, or when scaffolding new v5-compatible application code.
 
 ## 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';
    ```
 
-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.
+2. **Enable `allowInstallScripts` if packages require install scripts**: Harper v5 uses `--ignore-scripts` by default when installing packages. If a package requires execution of install scripts (e.g., to install native 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.
-   - Replace `wasLoadedFromSource()` with `target.loadedFromSource`:
+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 add or mutate properties directly.
+   - Replace direct property mutation:
 
      ```javascript
-     // Old — remove this pattern:
-     const record = await Table.get(id);
-     if (record.wasLoadedFromSource()) { ... }
+     let record = await Table.get(id);
+     record = { ...record, property: 'changed' };
+     ```
 
-     // New — use loadedFromSource on the target:
+   - Replace `wasLoadedFromSource()` with `loadedFromSource` on the `target` object:
+
+     ```javascript
      const target = new RequestTarget();
      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 objects still expose `getUpdatedTime` and `getExpiresAt` methods.
 
-     ```javascript
-     // Old — throws in v5:
-     const record = await Table.get(id);
-     record.property = 'changed';
+4. **Update transaction and context handling using `getContext`**: Harper v5 uses asynchronous context tracking. Context and the current transaction are automatically carried to all downstream calls — you no longer pass context explicitly. Import `getContext` and `transaction` from `harper`:
 
-     // New — copy instead of mutate:
-     let record = await Table.get(id);
-     record = { ...record, property: 'changed' };
-     ```
-
-   - `getUpdatedTime` and `getExpiresAt` methods remain available on the record object.
+   ```javascript
+   import { getContext, 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.
+   If your code previously omitted context to escape a transaction (e.g., to poll for updated data), explicitly commit the transaction and/or wrap each read in a new `transaction()` call:
 
    ```javascript
    import { setTimeout as delay } from 'node:timers/promises';
    import { getContext, transaction } from 'harper';
-
    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);
    		}
@@ -79,24 +72,90 @@ Apply this rule when upgrading an existing Harper application to v5, when encoun
    }
    ```
 
-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`**: `spawn` and `execFile` may only launch executables listed in `applications.allowedSpawnCommands` in `harperdb-config.yaml`. Only the first token of the command is matched. `exec` is not usable through the substituted module; `execSync` always throws.
+
+   ```yaml
+   applications:
+     allowedSpawnCommands:
+       - npm
+       - node
+   ```
+
+   Additionally, `spawn`, `execFile`, and `fork` now require a `name` property in the `options` argument to prevent process multiplication across threads.
+
+6. **Use `saveBeforeCommit` instead of `blob.save()`**: The `blob.save()` method has been removed. Pass the `saveBeforeCommit` flag in the options to the `Blob` constructor instead.
+
+7. **Handle `headers` on returned response objects**: If you return an object from a REST method with a `headers` property, Harper v5 will use it as the response headers.
+
+8. **Configure the VM module loader and `lockdown` in `harperdb-config.yaml`**: v5 loads application modules through Node.js's VM module API. Control all behavior under the `applications` key:
+
+   ```yaml
+   applications:
+     lockdown: freeze-after-load
+     moduleLoader: vm-current-context
+     dependencyLoader: auto
+     allowedDirectory: app
+     allowedSpawnCommands:
+       - npm
+       - node
+   ```
+
+   **`moduleLoader` options:**
+
+   | Value                | Behavior                                                                                                                         |
+   | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+   | `vm-current-context` | Default. VM loader in Harper's own context; shares intrinsics with Harper. Best compatibility.                                   |
+   | `vm`                 | VM loader in a separate per-application context with its own intrinsics. Stronger isolation but may cause `instanceof` failures. |
+   | `native`             | Standard Node.js `import()`. No VM loader; application-specific context (`logger`, `config`) unavailable.                        |
+   | `compartment`        | SES Compartment-based loading. For specialized sandboxing only.                                                                  |
+
+   **`lockdown` options:**
 
-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.
+   | Value               | Behavior                                                |
+   | ------------------- | ------------------------------------------------------- |
+   | `freeze-after-load` | Default. Freezes intrinsics after all components load.  |
+   | `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.        |
 
-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.
+   To disable the VM loader entirely and restore pre-v5 behavior:
 
-   | 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:
+     moduleLoader: native
+   ```
 
 ## Examples
 
-### Full `harperdb-config.yaml` `applications` block
+**Full transaction polling pattern (v5):**
+
+```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);
+	}
+}
+```
+
+**Checking `loadedFromSource` after `Table.get`:**
+
+```javascript
+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:
@@ -109,7 +168,7 @@ applications:
     - node
 ```
 
-### Restricting allowed built-in modules
+**Restricting allowed built-in modules:**
 
 ```yaml
 applications:
@@ -119,25 +178,14 @@ applications:
     - 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.
+- Always import Harper APIs from `'harper'`, not from global variables or `'harperdb'`.
+- `getContext` is exported from `'harper'` and provides access to the current transaction without passing context explicitly.
+- Record objects returned by `Table.get` are frozen — spread into a new object before modifying.
+- `loadedFromSource` is a property on the `target` object, replacing the removed `wasLoadedFromSource()` instance method.
+- `saveBeforeCommit` replaces the removed `blob.save()` method.
+- The `headers` property on a returned REST response object is used as response headers.
+- Under `lockdown: ses`, the constrained `fetch` applies 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; modules outside the application directory tree will throw. Set `allowedDirectory: any` only if legitimately required.
+- `dependencyLoader: native` is a narrower option than `moduleLoader: native` — it uses native loading only for npm packages while keeping the VM loader for first-party application source files.

package/.agents/skills/harper-best-practices/rules.manifest.yaml

@@ -149,14 +149,61 @@ rules:
     order: 1
     mode: generate
     sources:
+      # overview.md is sourced section-by-section rather than whole-file: at
+      # ~15KB it was the largest single input in the skill, and the compression
+      # dropped conditional requests, content negotiation, and the `GET`
+      # caveats outright. Listing sections narrows the input and makes a docs
+      # rename fail loudly in sliceSection. The dropped headings are the
+      # `# REST Overview` preamble (marketing + a version badge) and
+      # `## See Also` (link list); `## OpenAPI` is kept because the rule
+      # documents `GET /openapi`.
       - path: reference/v5/rest/overview.md
+        section: 'How the REST Interface Works'
         role: primary
+      - path: reference/v5/rest/overview.md
+        section: 'Configuration'
+        role: primary
+      - path: reference/v5/rest/overview.md
+        section: 'Tables and Their Automatic Endpoints'
+        role: primary
+      - path: reference/v5/rest/overview.md
+        section: 'URL Structure'
+        role: primary
+      - path: reference/v5/rest/overview.md
+        section: 'HTTP Methods'
+        role: primary
+      - path: reference/v5/rest/overview.md
+        section: 'Content Types'
+        role: primary
+      - path: reference/v5/rest/overview.md
+        section: 'OpenAPI'
+        role: supplemental
       - path: reference/v5/rest/websockets.md
         role: supplemental
     must_cover:
       - 'rest: true'
       - '@export'
       - 'WebSocket'
+      # Each of the following occurs exactly once across the sourced sections,
+      # so each pins one previously-dropped section:
+      #   If-None-Match / 304 Not Modified → `#### Conditional Requests and Caching`
+      #   `Accept`                         → `## Content Types` (bare `Accept`
+      #     would be satisfied by the SSE `Accept: text/event-stream` mention
+      #     under `## Tables and Their Automatic Endpoints`, which gates nothing)
+      #   .msgpack                         → the reserved content-type selector
+      #     suffixes and the undeclared-property caveat in `### GET`
+      - 'If-None-Match'
+      - '304 Not Modified'
+      - 'ETag'
+      - '`Accept`'
+      - '.msgpack'
+      # Pinned after the first regen dropped them while restoring the three
+      # sections above — an unanchored fact is only ever one regen from being
+      # compressed away, whichever fact it is:
+      #   Location (2×)     → the primary key POST returns in that header
+      #   @updatedTime (1×) → the three exceptions PUT always applies
+      - 'Location'
+      - '@updatedTime'
     cross_links:
       - querying-rest-apis
       - real-time-apps
@@ -207,13 +254,123 @@ rules:
       - path: reference/v5/resources/resource-api.md
         section: 'Session and Login from a Resource'
         role: primary
+      # JWT half. Sectioned *and* anchored deliberately.
+      #
+      # The generator concatenates every resolved source into one unlabeled
+      # blob (lib/sources.mjs `resolveSources`) and the system prompt tells the
+      # model to "keep it tight" and omit tangential detail. So whatever no
+      # `must_cover` anchor requires is exactly what gets compressed away —
+      # anchor starvation, not source ordering or size. As a whole-file source
+      # with no JWT anchors, this half collapsed to a single "use JWT instead"
+      # pointer and lost the token issue/refresh flow entirely.
+      #
+      # `must_cover` is the actual gate: it is enforced verbatim
+      # (validate-generated.mjs, `body.includes(must)`) and is echoed to the
+      # model as a hard requirement. `section:` only narrows what gets fed in —
+      # it helps because it tends to come with anchors, not on its own. Prefer
+      # identifier-shaped anchors that occur in exactly one sourced section; an
+      # anchor matching many sections gates nothing in particular.
+      #
+      # `role:` is a human-facing annotation only — the generator never reads
+      # it (it is enum-checked by the validator and otherwise unused).
+      - path: reference/v5/security/jwt-authentication.md
+        section: 'Create Authentication Tokens'
+        role: primary
       - path: reference/v5/security/jwt-authentication.md
+        section: 'Using the Operation Token'
+        role: supplemental
+      - path: reference/v5/security/jwt-authentication.md
+        section: 'Refreshing the Operation Token'
+        role: primary
+      - path: reference/v5/security/jwt-authentication.md
+        section: 'Scoped Tokens (Inline Role)'
+        role: primary
+      - path: reference/v5/security/jwt-authentication.md
+        section: 'Issuing Tokens from a Custom Resource'
+        role: primary
+      - path: reference/v5/security/jwt-authentication.md
+        section: 'Token Expiry Configuration'
+        role: supplemental
+      # Sourced so the rule carries the *negative* recommendation too. Without
+      # it the generated body pushed JWT at every non-browser client, while the
+      # source actually points simple and server-to-server callers at Basic
+      # Authentication — i.e. the rule was inviting token lifecycle complexity
+      # the docs tell you to avoid.
+      - path: reference/v5/security/jwt-authentication.md
+        section: 'When to Use JWT Auth'
+        role: primary
+      - path: reference/v5/security/jwt-authentication.md
+        section: 'Security Notes'
         role: supplemental
     must_cover:
+      # Session half.
       - 'getCurrentUser()'
       - 'getContext()'
       - 'context.login'
       - 'enableSessions'
+      # JWT half. One anchor per sourced section wherever an identifier is
+      # unique to it: `server.operation` pins the custom-resource section,
+      # `add_role`/`expires_in` the scoped-token section, `HTTPS` the security
+      # notes (`operationTokenTimeout` alone no longer distinguishes those two,
+      # since it occurs in both). `create_authentication_tokens` is the one
+      # unavoidably broad anchor — it is the subject of its own section but is
+      # back-referenced by three others, so it gates presence, not depth.
+      - 'create_authentication_tokens'
+      - 'refresh_operation_token'
+      - 'server.operation'
+      - 'add_role'
+      - 'expires_in'
+      - 'operationTokenTimeout'
+      - 'HTTPS'
+      # Scoped tokens are rejected with a 401 by nodes too old to understand
+      # them. Unanchored, that bullet was dropped the first time this rule was
+      # regenerated after the section was added — a rollout hazard, so it gets
+      # its own anchor rather than relying on the section being sourced.
+      - 'mixed-version'
+      # Operation names alone gate vocabulary, not mechanics: a regeneration
+      # could keep `create_authentication_tokens`/`refresh_operation_token` and
+      # still drop the token exchange, the refresh timeout, or what the third
+      # `server.operation` argument does. The anchors below pin those specific
+      # semantics. Each occurs exactly once in the doc and in exactly one
+      # sourced section, so it forces depth in that section rather than a
+      # passing mention anywhere.
+      #
+      # Two caveats this list is deliberately built around:
+      #
+      # 1. `must_cover` is a substring test (`body.includes(must)`), so an
+      #    anchor contained in another anchor gates nothing extra.
+      #    `operation_token` is already implied by `refresh_operation_token`,
+      #    and `refresh_token` by `Bearer <refresh_token>` — listing either
+      #    separately would be noise, not coverage.
+      # 2. A bare-fragment anchor invites literal satisfaction. Anchoring the
+      #    exchange as `Bearer <refresh_token>` — rather than `refresh_token`,
+      #    which occurs in three sourced sections — requires the body to show
+      #    the refresh token actually being presented as the Bearer credential.
+      #
+      # `third argument` + `current authenticated user` pin the authorize
+      # behavior together. `authorize: true` is the doc's prose name for it but
+      # is rejected as an anchor: the code passes `true` positionally, so
+      # forcing that string risks a body an agent transcribes as an options
+      # object.
+      - 'Bearer <refresh_token>'
+      - 'refreshTokenTimeout'
+      - 'third argument'
+      - 'current authenticated user'
+      # When to Use JWT Auth. `Basic Authentication` is a superstring of the
+      # plain `Basic Auth` the section also contains — which is the better
+      # anchor, since `Basic Auth` additionally appears in a code comment in
+      # the custom-resource section and could be satisfied from there while the
+      # recommendation itself stayed compressed away. `server-to-server` pins
+      # the scenario the source actually steers away from JWT.
+      #
+      # `preferred over Basic Auth` carries the source's *conditional* framing.
+      # It is anchored because sourcing the section alone was not enough: the
+      # body kept a flat "for non-browser clients, use JWT" directive and filed
+      # the Basic Auth alternative under Notes, which reads as a contradiction.
+      # Anchoring the conditional forces the choice to be stated as a tradeoff.
+      - 'Basic Authentication'
+      - 'server-to-server'
+      - 'preferred over Basic Auth'
     cross_links:
       - custom-resources
 
@@ -293,6 +450,36 @@ rules:
       - 'search('
       - 'addTo'
       - 'select'
+      # Query Object options that were covered before the transaction material
+      # was pinned, and that the regen then compressed out to make room. They
+      # are anchored now rather than left to survive on luck; each occurs only
+      # in § Query Object. `sort` also carries the `@indexed`-or-`conditions`
+      # requirement and `allowFullScan`, which have no meaning without it.
+      - 'sort'
+      - '@indexed'
+      - 'explain'
+      - 'enforceExecutionOrder'
+      # The `transaction(context?, callback)` source was already declared with a
+      # `section:` and was still dropped in full — proof that sectioning narrows
+      # the input but does not hold content in. Only an anchor does. Each of
+      # these occurs in exactly one sourced section:
+      #   transaction() (2×)     → § `transaction(context?, callback)`
+      #   resetReadSnapshot() (1×) → its `### Transaction Object` member table
+      #   atomicity (1×)         → `### Transaction Scope and Atomicity`
+      #   limit / offset (1× each) → § Query Object, the pagination pair
+      # Balanced parens deliberately: anchoring the bare `transaction(` also
+      # gates the section, but the model satisfies it literally and writes
+      # prose like "wrap background work in `transaction(`". `transaction()`
+      # contains `transaction(`, so it is the stricter anchor as well.
+      - 'transaction()'
+      - 'resetReadSnapshot()'
+      - 'atomicity'
+      - 'limit'
+      - 'offset'
+      # § Module Loading's one piece of actionable build guidance: keep `harper`
+      # external when bundling for SSR, or it is bundled instead of resolving
+      # to the runtime. Only occurrence of `vite.config` in the sources.
+      - 'vite.config'
 
   - rule: typescript-type-stripping
     description: How to run TypeScript files directly in Harper without a build step.
@@ -347,6 +534,28 @@ rules:
     must_cover:
       - 'harper deploy'
       - 'harper login'
+      # `### Provisioning a Deploy Credential` is already inside the sourced
+      # `## Remote Management` slice, and its security guidance was compressed
+      # away anyway. These anchors pin it; each occurs only in that slice:
+      #   fine-grained (2×) → prefer a fine-grained PAT over the `gh` CLI token
+      #   read:org (1×)     → the account-wide scopes the `gh` token carries
+      #   enc:v1: (1×)      → the client-side-encryption envelope
+      # They double as the rename detector for that subheading: if it is
+      # retitled or removed, the content goes and these anchors fail.
+      - 'fine-grained'
+      - 'Contents: Read-only'
+      - 'read:org'
+      - 'enc:v1:'
+      # Pinned after the first regen dropped it while restoring the credential
+      # guidance: `refs/heads/*` and `refs/tags/*` (or a bare branch/tag) are
+      # the only refs a `by_ref` deploy can fetch.
+      - 'refs/tags'
+      # Also pinned after a regen dropped it: `setup=true` calls
+      # `get_secrets_public_key` / `set_secret` / `grant_secret`, so it must be
+      # run with an administrative credential, not the CI identity it
+      # provisions for. The source escapes it as `super\_user`; every generated
+      # body so far unescapes, so the anchor is the unescaped form.
+      - 'super_user'
     cross_links:
       - creating-a-fabric-account-and-cluster
 
@@ -422,6 +631,9 @@ rules:
       - 'moduleLoader'
       - 'lockdown'
       - 'Table.get'
+      # `## Response Objects` had no anchor and was dropped in full. Every
+      # occurrence of `headers` in the whole-file source is in that section.
+      - 'headers'
 
   - rule: delegating-to-the-built-in-agent
     description: How to delegate tasks to Harper's built-in agent via the CLI and the agent operations API.