@harperfast/template-vue-ts-studio 1.12.12 → 1.13.1

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

@@ -14,31 +14,37 @@ metadata:
       reference/v5/resources/resource-api.md#`addTo(property: string, value:
       number)`
     - reference/v5/components/javascript-environment.md#Module Formats
-  sourceCommit: 9e6ecf87dd25bb488ad44dc2876ca6439ccd682e
-  inputHash: f5629f73cde74764
+  sourceCommit: e73e5efb2823cc52caf7a6458d67fbcff3bbff2c
+  inputHash: bb360b0d6c0a7bd4
 ---
 
 # Programmatic Table Requests
 
-Instructions for the agent to interact with Harper tables programmatically using the `tables` object, the Query API, and transactions.
+Instructions for the agent to follow when interacting with Harper tables programmatically using the `tables` object.
 
 ## When to Use
 
-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()`.
+Apply this rule when writing server-side Harper component code that reads from or writes to tables using the programmatic API — for example, in HTTP handlers, background jobs, timers, or SSR entry points. Use it whenever you need to construct queries with `conditions`, `sort`, `select`, pagination, or transactions outside of the REST layer.
 
 ## How It Works
 
-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.
+1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a property of `tables`. Each property is the table class implementing the Resource API.
 
    ```javascript
    import { tables, transaction } from 'harper';
    const { Product } = tables;
-   // equivalent to: databases.data.Product
+   // same as: databases.data.Product
    ```
 
-   For standalone components, run `npm link harper` so imports resolve to the live runtime.
+   For components in their own directory, run:
 
-2. **Define your schema with `@table`**: Tables must be declared in `schema.graphql`. Mark attributes you intend to sort or filter on with `@indexed`.
+   ```bash
+   npm link harper
+   ```
+
+   All installed components have `harper` automatically linked.
+
+2. **Define your schema with `@table`**: Every type you want to access via `tables` must carry the `@table` directive. Mark queryable fields with `@indexed`.
 
    ```graphql
    type Product @table {
@@ -48,7 +54,7 @@ Apply this rule when writing server-side Harper component code that reads from o
    }
    ```
 
-3. **Query records with `search(`**: Pass a Query object to `search(`. Iterate results with `for await`.
+3. **Query records using `search(`**: Pass a Query object to `search()`. The query is an async iterable.
 
    ```javascript
    const query = {
@@ -59,7 +65,7 @@ Apply this rule when writing server-side Harper component code that reads from o
    }
    ```
 
-4. **Build `conditions`**: Each condition object supports these properties:
+4. **Build `conditions`**: Each condition object supports the following properties:
 
    | Property     | Description                                                                                                                                              |
    | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -69,53 +75,60 @@ Apply this rule when writing server-side Harper component code that reads from o
    | `conditions` | Nested conditions array                                                                                                                                  |
    | `operator`   | `and` (default) or `or` for the nested `conditions`                                                                                                      |
 
-5. **Control result shape with `select`**: Pass an array of property names, a single string, or nested objects for relationships.
+5. **Apply `select` to shape results**: Pass an array of property names, a string for a single property, or nested objects for relationships.
 
    ```javascript
-   // Scalar fields only
+   // Flat select
    Product.search({ select: ['name', 'price'] });
 
-   // Partial related record
+   // Nested relationship select
    Book.get({ id: 42, select: ['id', 'title', { name: 'author', select: ['name'] }] });
    ```
 
    Special `select` values: `$id`, `$updatedtime`, `$distance`.
 
-6. **Paginate with `limit` and `offset`**:
-
-   ```javascript
-   Product.search({ conditions: [...], limit: 20, offset: 40 });
-   ```
+6. **Apply `sort`**: Harper uses an index to provide sort order.
 
-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.
+   | 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)            |
+   - If the sort `attribute` is `@indexed`, no condition is required.
+   - If the sort `attribute` is not indexed, at least one entry in `conditions` (on **any** attribute) is required.
+   - Sorting by a non-indexed attribute with zero conditions raises:
+     > `HdbError: <attribute> is not indexed and not combined with any other conditions`
+   - The bare `@primaryKey` is treated as not indexed for sort purposes. To iterate in primary-key order, add an open-ended condition:
 
-   Sorting by a non-indexed attribute with zero conditions raises:
+     ```javascript
+     Product.search({
+     	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
+     	sort: { attribute: 'id' },
+     });
+     ```
 
-   > `HdbError: <attribute> is not indexed and not combined with any other conditions`
+   - Pass `allowFullScan: true` to permit an unconditional ordered scan, or omit `sort` entirely to iterate without an index requirement.
 
-   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:
+7. **Paginate with `limit` and `offset`**:
 
    ```javascript
-   Product.search({
-   	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
-   	sort: { attribute: 'id' },
-   });
+   Product.search({ conditions: [...], limit: 20, offset: 40 });
    ```
 
-   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`**:
+8. **Debug 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.
+   - `enforceExecutionOrder: true` — forces conditions to execute in the order supplied, disabling Harper's automatic re-ordering.
 
-9. **Use `addTo` for concurrent-safe numeric updates**: `addTo` uses CRDT incrementation, safe across threads and nodes.
+9. **Use `addTo` for concurrent-safe increments**: `addTo(property, value)` uses CRDT incrementation, safe across threads and nodes.
 
    ```javascript
-   const record = await Product.update(32);
-   record.addTo('quantity', -1);
+   static async post(target, data) {
+     const record = await this.update(target.id);
+     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.
+10. **Wrap background work in `transaction()`**: Harper auto-starts transactions for HTTP handlers. Use `transaction()` explicitly for timers, background jobs, or any code outside a natural transaction context.
 
     ```javascript
     await transaction(async (txn) => {
@@ -127,18 +140,18 @@ Apply this rule when writing server-side Harper component code that reads from o
 
     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      |
+    | Member                | Type            | Description                                            |
+    | --------------------- | --------------- | ------------------------------------------------------ |
+    | `commit()`            | `() => Promise` | Commits the current transaction                        |
+    | `abort()`             | `() => void`    | Aborts the transaction and resets it                   |
+    | `resetReadSnapshot()` | `() => void`    | Resets the read snapshot to the latest committed state |
+    | `timestamp`           | `number`        | 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.
+    On normal callback completion the transaction commits automatically. If the callback throws, the transaction is aborted.
 
-    If `transaction()` is called with a context that already has an active transaction, it reuses that transaction — safe to call defensively.
+11. **Understand atomicity**: Transactions span a single database. All tables within the same database share one transactional context — reads return a consistent snapshot and writes across multiple tables commit atomically. Cross-database operations get separate transactions with no cross-database atomicity guarantee.
 
-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.
+12. **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
@@ -149,7 +162,7 @@ Apply this rule when writing server-side Harper component code that reads from o
 
 ## Examples
 
-### Full CRUD sequence
+**Full CRUD flow:**
 
 ```javascript
 import { tables } from 'harper';
@@ -161,19 +174,18 @@ 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
+// Get by primary key
 const record = await Product.get(created.id);
 
-// Query with conditions
-const query = {
+// Search with conditions
+for await (const record of Product.search({
 	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
-};
-for await (const record of Product.search(query)) {
+})) {
 	// process record
 }
 ```
 
-### Nested conditions with `or`
+**Nested conditions with `or`:**
 
 ```javascript
 Product.search({
@@ -190,13 +202,13 @@ Product.search({
 });
 ```
 
-### Chained attribute reference (join/relationship)
+**Chained attribute reference (join):**
 
 ```javascript
 Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-### Background job with `transaction()`
+**Background job with `transaction()`:**
 
 ```javascript
 import { isMainThread } from 'node:worker_threads';
@@ -224,7 +236,7 @@ if (isMainThread) {
 }
 ```
 
-### SSR render with `tables`
+**SSR with Harper data:**
 
 ```typescript
 import { tables } from 'harper';
@@ -237,7 +249,9 @@ export async function render(url: string): Promise<string> {
 
 ## Notes
 
-- `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.
+- `tables` and `databases` calls run in a trusted server-side context and do **not** automatically apply the target table's role permissions.
+- Programmatic `update`, `patch`, and `delete` calls operate directly on stored data. Scope destructive operations with specific `conditions`, validate the affected set before writing, and gate them behind authorization controls.
+- If `transaction()` is called with a context that already has an active transaction, it reuses that transaction — making it safe to call defensively.
+- Always `await` the `transaction()` call and `catch` errors when outside a request context; an unawaited call means a failed write is never observed.
+- Guard against timer overlap: if a job can outlast its interval, use a `running` flag to skip a tick rather than opening two transactions over the same rows.
+- CommonJS is also supported: `const { tables, Resource } = require('harper');`

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

@@ -595,8 +595,12 @@ rules:
   # Infrastructure & Ops (priority 4 — MEDIUM)
   # ===========================================================================
 
+  # Deploying is split across two rules: as one, its sources would come to
+  # ~57KB, well over any other rule's input, and the larger the input, the more
+  # facts regeneration compresses away. This rule covers a CLI deploy and what
+  # happens to a release afterwards; deploying-from-ci covers OIDC in CI.
   - rule: deploying-to-harper-fabric
-    description: How to deploy a Harper application to the Harper Fabric cloud.
+    description: How to deploy a Harper application to Harper Fabric with the CLI, check that the release was certified, and roll back by activating a previous release's `deployment_id`.
     category: ops
     priority: 4
     order: 1
@@ -608,6 +612,41 @@ rules:
       - path: fabric/cluster-creation-management.md
         section: 'Connecting the Harper CLI to a Cluster'
         role: supplemental
+      # The CLI forms of `restart=rolling`, `replicated=false`, `activate=false`
+      # and `deployment_id=`. Matched by heading text, so the
+      # `restart=rolling` anchor also fails if commands.md ever gains an
+      # earlier `Parameters` heading.
+      - path: reference/v5/cli/commands.md
+        section: 'Parameters'
+        role: supplemental
+      # How `list_deployments` and `get_job` are run from the CLI.
+      - path: reference/v5/cli/operations-api-commands.md
+        section: 'General Syntax'
+        role: supplemental
+      # `deploy_component` is sourced by subsection: the whole section is
+      # ~30KB, mostly detail that does not change what an agent does.
+      # `Restarting` is left out: Parameters and the canary section carry
+      # what an agent needs from it.
+      - path: reference/v5/operations-api/operations.md
+        section: 'Certifying a release in a canary worker'
+        role: primary
+      - path: reference/v5/operations-api/operations.md
+        section: 'Staging a build and activating it later'
+        role: primary
+      - path: reference/v5/operations-api/operations.md
+        section: 'Going back to a previous release'
+        role: primary
+      # What a retried activation does on each node, and that a retry with
+      # `restart` restarts every worker even where the release is live.
+      - path: reference/v5/operations-api/operations.md
+        section: 'Retrying an activation'
+        role: supplemental
+      - path: reference/v5/operations-api/operations.md
+        section: '`list_deployments`'
+        role: supplemental
+      - path: reference/v5/operations-api/operations.md
+        section: '`get_job`'
+        role: supplemental
     must_cover:
       - 'harper deploy'
       - 'harper login'
@@ -619,6 +658,10 @@ rules:
       #   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.
+      #
+      # Deploying by reference is no longer the CI default, but a private
+      # repository is still deployed that way. If the docs move this guidance
+      # out of `## Remote Management`, re-point the source; don't drop these.
       - 'fine-grained'
       - 'Contents: Read-only'
       - 'read:org'
@@ -633,35 +676,168 @@ rules:
       # provisions for. The source escapes it as `super\_user`; every generated
       # body so far unescapes, so the anchor is the unescaped form.
       - 'super_user'
+      # Going back: activating a kept release rebuilds nothing, where
+      # redeploying an older commit installs it again from source.
+      # `stagingRetention` holds how many releases a node keeps.
+      - 'deployment_id'
+      - 'list_deployments'
+      - 'stagingRetention'
+      - 'activate: false'
+      # On Pro and Fabric a deploy replicates unless `replicated=false`.
+      - 'replicated=false'
+      # `not-requested` occurs only in the `certification` table, so it holds
+      # the table, not a passing mention of the field. `restartJobId`, `get_job`
+      # and `COMPLETE` hold the wait: a rolling deploy responds once its job
+      # starts, and its record says `success` even if the job then fails.
+      - 'restart=rolling'
+      - 'certification'
+      - 'not-requested'
+      - 'fails closed'
+      - 'restartJobId'
+      - 'get_job'
+      - 'COMPLETE'
     cross_links:
       - creating-a-fabric-account-and-cluster
+      - deploying-from-ci
+
+  - rule: deploying-from-ci
+    description: How to deploy a Harper application from GitHub Actions with OIDC trusted publishing, so CI stores no Harper credential, including the one-command setup with `harper deploy setup=true provider=github-actions`.
+    category: ops
+    priority: 4
+    order: 2
+    mode: generate
+    # The guide's isolated-worker and per-PR preview sections are left out:
+    # ~18KB on their own, and a different task from deploying a release.
+    sources:
+      # The one-command setup (v5.4.0) for a workflow that deploys when changes
+      # merge to a branch, which create-harper projects scaffold. The guide's
+      # hand-written policy is still what a tag-triggered release needs.
+      - path: reference/v5/cli/commands.md
+        section: 'GitHub Actions deploys (OIDC)'
+        role: primary
+      - path: learn/developers/deploying-from-ci.md
+        section: 'Let the workflow authenticate with OIDC'
+        role: primary
+      - path: learn/developers/deploying-from-ci.md
+        section: 'Path A: deploy a tagged release from your repository'
+        role: primary
+      - path: learn/developers/deploying-from-ci.md
+        section: 'Give Harper a durable credential for a private source'
+        role: supplemental
+      - path: learn/developers/deploying-from-ci.md
+        section: 'Path B: build in CI, publish to GitHub Packages, deploy the artifact'
+        role: supplemental
+      - path: learn/developers/deploying-from-ci.md
+        section: 'Check the deployment record'
+        role: supplemental
+      - path: learn/developers/deploying-from-ci.md
+        section: 'Operational notes'
+        role: supplemental
+      # Where the exchange sits in credential precedence, and how to diagnose
+      # a refused one.
+      - path: reference/v5/cli/authentication.md
+        section: 'Workload identity (OIDC)'
+        role: supplemental
+      - path: reference/v5/operations-api/operations.md
+        section: 'Policy specificity for GitHub Actions'
+        role: supplemental
+      - path: reference/v5/operations-api/operations.md
+        section: '`list_oidc_trust`'
+        role: supplemental
+      - path: reference/v5/operations-api/operations.md
+        section: '`drop_oidc_trust`'
+        role: supplemental
+    must_cover:
+      # The one-command setup: `workflow=` holds the default-file rule (a
+      # `deploy.yml` workflow can't match a policy pinned to `deploy.yaml`),
+      # and `github-actions-<project>` the policy name a revocation drops.
+      - 'provider=github-actions'
+      - 'workflow='
+      - 'github-actions-<project>'
+      # The version check `harper deploy` makes before it uploads; a role
+      # without it logs a refused operation on every run.
+      - 'registration_info'
+      - 'id-token: write'
+      - 'vars.HARPER_CLI_TARGET'
+      # A configured credential outranks the exchange, so a pipeline that
+      # keeps its refresh token never uses OIDC.
+      - 'HARPER_CLI_REFRESH_TOKEN'
+      # The workflow as written: without a checkout and the CLI, a clean
+      # runner has nothing to deploy and nothing to deploy it with. Fact
+      # retention can't see inside a fence, and step 2's single job also has
+      # `runs-on: ubuntu-latest` and `actions/checkout`, so Path A's complete
+      # workflow is held by what only it has: its trigger (`push:` and
+      # `tags: ['v*']`), its `jobs:` wrapper, and the wait loop's
+      # `.[0].status`. The CLI install is held with its pin: an unpinned one
+      # would change under a rerun of an old tag after a new major release.
+      - 'actions/checkout'
+      - 'npm install --global harper@^5.3'
+      - 'runs-on: ubuntu-latest'
+      - 'push:'
+      - "tags: ['v*']"
+      - 'jobs:'
+      - '.[0].status'
+      # `workflow_path` is what a tag-triggered release pins instead of
+      # `workflow_ref`. `trailing slash` holds the audience rule, without which
+      # a policy never matches. The environment is the ref gate, and only as
+      # strong as its deployment branch and tag rules.
+      - 'add_oidc_trust'
+      - 'super_user'
+      - 'token.actions.githubusercontent.com'
+      - 'repository_id'
+      - 'workflow_ref'
+      - 'workflow_path'
+      - 'environment: production'
+      - 'Deployment branches and tags'
+      - 'trailing slash'
+      # An `operations` allowlist refuses what it doesn't list, so the wait
+      # step needs `get_job`. A job lives only on the node that received the
+      # deploy, so polls through a load-balanced URL have to reach it.
+      - 'deploy_component'
+      - 'get_job'
+      - 'get_deployment'
+      - 'restartJobId'
+      - 'load-balanced'
+      - 'credential=true'
+      # A rejected exchange never says which check failed; `invalid_reason`
+      # and the `oidc-trust` log do. Dropping a policy leaves an issued token
+      # valid for its hour; `alter_user` stops it.
+      - 'list_oidc_trust'
+      - 'invalid_reason'
+      - 'oidc-trust'
+      - 'drop_oidc_trust'
+      - 'alter_user'
+      # The user setup creates, which an incident revocation deactivates.
+      - '<project>-ci-deploy'
+    cross_links:
+      - deploying-to-harper-fabric
 
   - rule: creating-a-fabric-account-and-cluster
     description: How to create a Harper Fabric account, organization, and cluster.
     category: ops
     priority: 4
-    order: 2
+    order: 3
     mode: synthesized
 
   - rule: creating-harper-apps
     description: How to initialize a new Harper application using the CLI.
     category: ops
     priority: 4
-    order: 3
+    order: 4
     mode: synthesized
 
   - rule: serving-web-content
     description: How to serve static files and integrated Vite/React applications in Harper.
     category: ops
     priority: 4
-    order: 4
+    order: 5
     mode: synthesized
 
   - rule: logging
     description: Best practices for logging in Harper, including console capture, the granular logger interface, and programmatic log retrieval.
     category: ops
     priority: 4
-    order: 5
+    order: 6
     mode: generate
     sources:
       - path: reference/v5/logging/overview.md
@@ -677,7 +853,7 @@ rules:
     description: How to load environment variables from .env files into a Harper application using the loadEnv plugin.
     category: ops
     priority: 4
-    order: 6
+    order: 7
     mode: generate
     sources:
       - path: reference/v5/environment-variables/overview.md
@@ -693,7 +869,7 @@ rules:
     description: Breaking changes and recommended updates when migrating a Harper application to v5.
     category: ops
     priority: 4
-    order: 7
+    order: 8
     mode: generate
     sources:
       - path: release-notes/v5-lincoln/v5-migration.md
@@ -723,7 +899,7 @@ rules:
     description: How to delegate tasks to Harper's built-in agent via the CLI and the agent operations API.
     category: ops
     priority: 4
-    order: 8
+    order: 9
     mode: synthesized
     cross_links:
       - deploying-to-harper-fabric

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/template-vue-ts-studio",
-	"version": "1.12.12",
+	"version": "1.13.1",
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {},

package/skills-lock.json

@@ -5,7 +5,7 @@
       "source": "harperfast/skills",
       "sourceType": "github",
       "skillPath": "harper-best-practices/SKILL.md",
-      "computedHash": "b157e80968413da12ccbbe21f4b64eb0d1bcfc7c0f166b03f51a0013fe8901a0"
+      "computedHash": "b95b53d7d50d882d44b2f331fc45047e3caa8bd5140fbfb777aedd9b18eb451b"
     },
     "harper-local-dev": {
       "source": "harperfast/skills",