@harperfast/template-vue-studio 1.13.6 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/.agents/skills/harper-best-practices/AGENTS.md +1260 -1113
  2. package/.agents/skills/harper-best-practices/rules/automatic-apis.md +118 -83
  3. package/.agents/skills/harper-best-practices/rules/checking-authentication.md +244 -256
  4. package/.agents/skills/harper-best-practices/rules/custom-resources.md +37 -42
  5. package/.agents/skills/harper-best-practices/rules/defining-relationships.md +86 -49
  6. package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
  7. package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
  8. package/.agents/skills/harper-best-practices/rules/load-env.md +27 -30
  9. package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
  10. package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
  11. package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
  12. package/.agents/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
  13. package/.agents/skills/harper-best-practices/rules/vector-indexing.md +77 -68
  14. package/.agents/skills/harper-mcp/AGENTS.md +228 -155
  15. package/.agents/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
  16. package/.agents/skills/harper-mcp/rules/enabling-mcp.md +104 -92
  17. package/.agents/skills/harper-mcp/rules/rate-limiting.md +95 -28
  18. package/agent/skills/harper-best-practices/AGENTS.md +1260 -1113
  19. package/agent/skills/harper-best-practices/rules/automatic-apis.md +118 -83
  20. package/agent/skills/harper-best-practices/rules/checking-authentication.md +244 -256
  21. package/agent/skills/harper-best-practices/rules/custom-resources.md +37 -42
  22. package/agent/skills/harper-best-practices/rules/defining-relationships.md +86 -49
  23. package/agent/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
  24. package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
  25. package/agent/skills/harper-best-practices/rules/load-env.md +27 -30
  26. package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
  27. package/agent/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
  28. package/agent/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
  29. package/agent/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
  30. package/agent/skills/harper-best-practices/rules/vector-indexing.md +77 -68
  31. package/agent/skills/harper-mcp/AGENTS.md +228 -155
  32. package/agent/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
  33. package/agent/skills/harper-mcp/rules/enabling-mcp.md +104 -92
  34. package/agent/skills/harper-mcp/rules/rate-limiting.md +95 -28
  35. package/package.json +1 -1
  36. package/skills-lock.json +7 -7
@@ -23,8 +23,8 @@ metadata:
23
23
  - reference/v5/operations-api/operations.md#Retrying an activation
24
24
  - reference/v5/operations-api/operations.md#`list_deployments`
25
25
  - reference/v5/operations-api/operations.md#`get_job`
26
- sourceCommit: e69702c99845f2dd810cb32652d1a9e6b58c538b
27
- inputHash: 44ee050eac4a5056
26
+ sourceCommit: 489477b2259ba148f4e526ea4b5cd24041ceec03
27
+ inputHash: 53279ae8c94cde2b
28
28
  ---
29
29
 
30
30
  # Deploying to Harper Fabric
@@ -39,148 +39,186 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
39
39
 
40
40
  ## How It Works
41
41
 
42
- 1. **Log in to the cluster once**: Pass the cluster's **Application URL**, from its **Config → Overview** page, to `harper login`. The CLI stores the token, so later commands don't repeat credentials. If the current directory already has a `.env` file that sets no target, it also appends `HARPER_CLI_TARGET` to it.
42
+ 1. **Authenticate against the cluster**: Run `harper login` once, pointing at the cluster's Application URL (found on **Config → Overview**). The CLI stores the token and sets the URL as the default target. If the current directory has a `.env` file, and neither that file nor your environment sets `HARPER_CLI_TARGET` or `CLI_TARGET`, login appends `HARPER_CLI_TARGET` to it.
43
43
 
44
44
  ```bash
45
45
  harper login <Application URL>
46
46
  # Provide cluster username and password when prompted
47
47
  ```
48
48
 
49
- For CI/CD pipelines, use workload identity (OIDC) or a refresh token from `harper login --for-ci` instead of a password. See [deploying-from-ci.md](deploying-from-ci.md) for a complete GitHub Actions workflow. For a one-off command, `auth_username=` and `auth_password=` also work, and take precedence over environment variables and saved login tokens. Don't use them in production.
49
+ For CI/CD pipelines, use workload identity (OIDC) or a refresh token from `harper login --for-ci` instead of a password. See [deploying-from-ci.md](deploying-from-ci.md) for a complete GitHub Actions workflow. For a one-off command, `auth_username=` and `auth_password=` are available but not recommended for production.
50
50
 
51
- 2. **Deploy the application**: Run `harper deploy` with the required parameters. Omit `package` to upload the current directory; supply a reference for npm, GitHub, or tarball sources.
51
+ 2. **Deploy the application**: Run `harper deploy` with the required parameters. A bare `target` host defaults to `https://<host>:9925`. Use `restart=rolling` for a staggered, zero-downtime restart across the cluster. Pass `replicated=false` to restrict the deploy to the single node you called; on Harper Fabric, omit it to reach every node.
52
52
 
53
53
  ```bash
54
54
  harper deploy \
55
55
  project=<name> \
56
56
  package=<package> \
57
57
  target=<remote> \
58
- restart=true \
58
+ restart=rolling \
59
59
  replicated=true
60
60
  ```
61
61
 
62
- A bare `target` host defaults to `https://<host>:9925`. Use `restart=rolling` for a staggered, zero-downtime restart across the cluster. Pass `replicated=false` to deploy only to the node you called. Pass `json=true` to print the result as JSON instead of YAML.
62
+ Key parameters:
63
+
64
+ | Parameter | Description |
65
+ | --------------------- | ------------------------------------------------------------------------------------- |
66
+ | `package=<reference>` | npm, GitHub, or tarball reference. Omit to deploy current directory. |
67
+ | `target=<url>` | Remote Harper instance URL. Bare host defaults to `https://<host>:9925`. |
68
+ | `restart=rolling` | Restart nodes one at a time; each stays in rotation while it restarts. |
69
+ | `replicated=false` | Deploy to the called node only. |
70
+ | `wait=false` | With `restart=rolling`, exit after the called node takes the release. |
71
+ | `wait_timeout=<ms>` | With `restart=rolling`, maximum wait time per node. Default: ten minutes per node. |
72
+ | `activate=false` | Build and install without making the release live. Cannot be combined with `restart`. |
73
+ | `ref=<committish>` | Branch, tag, or commit SHA to deploy. Resolved to SHA. Implies `by_ref`. |
74
+ | `json=true` | Print output as JSON instead of YAML. |
63
75
 
64
76
  3. **Choose a package source**: The `package` field accepts any valid npm dependency value.
65
77
 
66
- | Source | Value |
67
- | ------------------ | --------------------------------------------------------------------------------------------- |
68
- | npm package | `package="@harperdb/status-check"` |
69
- | GitHub (public) | `package="HarperFast/status-check"` or `package="https://github.com/HarperFast/status-check"` |
70
- | Private repo (SSH) | `package="git+ssh://git@github.com:HarperDB/secret-app.git"` |
71
- | Tarball | `package="https://example.com/application.tar.gz"` |
78
+ | Format | Example |
79
+ | ----------------------- | --------------------------------------------------------------------------------------------- |
80
+ | Current local directory | Omit `package` |
81
+ | npm package | `package="@harperdb/status-check"` |
82
+ | GitHub (public) | `package="HarperFast/status-check"` or `package="https://github.com/HarperFast/status-check"` |
83
+ | Private repo (SSH) | `package="git+ssh://git@github.com:HarperDB/secret-app.git"` |
84
+ | Tarball | `package="https://example.com/application.tar.gz"` |
72
85
 
73
86
  For git tags, use the `semver` directive: `HarperFast/application-template#semver:v1.0.0`. For an SSH-based private repo, register the key with `add_ssh_key` first.
74
87
 
75
- 4. **Provision credentials for private repositories**: Run `harper deploy setup=true` once per component and source. (With `provider=github-actions`, it sets up GitHub Actions OIDC deploys instead.) This requires `super_user` privileges and is interactive. It calls `get_secrets_public_key`, `set_secret`, and `grant_secret`. Run it with an administrative credential rather than the CI identity it provisions for:
88
+ 4. **Provision credentials for private repositories**: Run `harper deploy setup=true` once per component and source. (With `provider=github-actions`, it sets up GitHub Actions OIDC deploys instead.) This requires `super_user` privileges — run it with an administrative credential, not the CI identity it provisions for.
76
89
 
77
90
  ```bash
78
91
  harper deploy setup=true
79
92
  ```
80
93
 
81
- The command:
82
- 1. Fetches the cluster's public key with `get_secrets_public_key`.
83
- 2. Encrypts the token locally into an `enc:v1:` envelope.
84
- 3. Stores only the ciphertext with `set_secret`, scoped to the component, never in the global `processEnv` tier.
85
- 4. Grants the component permission to resolve it with `grant_secret`.
94
+ The setup flow:
95
+ - Fetches the cluster's public key with `get_secrets_public_key`.
96
+ - Encrypts the token locally into an `enc:v1:` envelope.
97
+ - Stores only the ciphertext with `set_secret` in the component-scoped tier — never in the global `processEnv` tier that every component and child process can read.
98
+ - Grants the component permission to resolve it with `grant_secret`.
99
+
100
+ Prefer a **fine-grained** personal access token scoped to **Contents: Read-only** on the target repository. Avoid the `gh` CLI session token, which carries `read:org`, `gist`, `workflow`, and `repo` scopes across your whole account. The encrypted token is durable and replayed on every cold deploy and rollback, so use the narrowest credential that does the job.
86
101
 
87
- Use a **fine-grained** personal access token with **Contents: Read-only** on the target repository. Avoid broad tokens: the `gh` CLI session token typically carries `read:org`, `gist`, and `workflow` scopes across your whole account. Then deploy with `credential=true`:
102
+ Then deploy with `credential=true`:
88
103
 
89
104
  ```bash
90
105
  harper deploy by_ref=true credential=true restart=true replicated=true
91
106
  ```
92
107
 
93
- 5. **Stage a release to make live later**: `activate=false` (`activate: false` in the operation) builds and installs the release on each node without making it live, so the slow, fallible part happens when you choose and the cut-over is quick. Cannot be combined with `restart`.
108
+ 5. **Deploy by reference for a reproducible source**: `by_ref=true` sends a pinned git reference instead of uploading the working directory, and the cluster fetches and builds that exact commit. It resolves the repository's `origin` remote and the current commit, then deploys `package=git+https://github.com/<owner>/<repo>.git#<full commit SHA>`.
94
109
 
95
- ```json
96
- {
97
- "operation": "deploy_component",
98
- "project": "my-app",
99
- "package": "npm:@my-org/my-app@1.2.3",
100
- "activate": false
101
- }
110
+ ```bash
111
+ harper deploy by_ref=true restart=true replicated=true
112
+ ```
113
+
114
+ Deploy a specific tag or commit with `ref`:
115
+
116
+ ```bash
117
+ harper deploy ref=v1.2.0 restart=true replicated=true
118
+ harper deploy ref=9f8c2a1 restart=true replicated=true
102
119
  ```
103
120
 
104
- The response names the artifact waiting to be activated:
121
+ Tags and branches are resolved to a full commit SHA before the deploy is sent. A `ref` that cannot be resolved stops the deploy — run `git fetch` and retry, or pass a full commit SHA. A full commit SHA is accepted directly with no resolution step. Valid refs must be in `refs/heads/*` or `refs/tags/*` if qualified; a ref like `refs/pull/123/head` is rejected up front even if your local checkout can resolve it. Commit and push before deploying — the cluster clones from the remote and only sees pushed commits.
122
+ - On a GitHub Actions `pull_request` run, `by_ref` deploys the pull request's head commit. If the event payload isn't readable, the deploy stops; pass the commit explicitly:
123
+
124
+ ```bash
125
+ harper deploy ref=${{ github.event.pull_request.head.sha }} restart=true replicated=true
126
+ ```
127
+
128
+ 6. **Activate a staged build**: Make a staged build live using its `deployment_id`. Pass `restart` here, not on the stage step. Takes no `package`, `payload`, `credentials`, install options, or `urlPath`/`host` — those are rejected rather than ignored.
105
129
 
106
130
  ```json
107
131
  {
108
- "deployment_id": "a3f8c2d1-...",
109
- "message": "Staged: my-app. Deploy it with deploy_component deployment_id=a3f8c2d1-..."
132
+ "operation": "deploy_component",
133
+ "project": "my-app",
134
+ "deployment_id": "a3f8c2d1-..."
110
135
  }
111
136
  ```
112
137
 
113
- Nothing about the running component changes, and `get_deployment` reports it as `staged`. Make it live by deploying that `deployment_id`, as in step 6. The activation takes no `package`, `payload`, `credentials`, install options, or `urlPath`/`host`. They are rejected, because the staged build already decided them.
114
-
115
- 6. **Activate a staged build or roll back**: Pass `deployment_id` with `restart` to make a staged build live, or to restore a release a later deploy replaced, with no rebuild or reinstall. Pass `restart` here rather than on the stage.
138
+ Or via the CLI:
116
139
 
117
140
  ```bash
118
141
  harper deploy project=<name> deployment_id=<id> restart=true
119
142
  ```
120
143
 
121
- Use `list_deployments` to find the `deployment_id` of the release to restore:
144
+ 7. **Stage a build for later activation**: Pass `activate=false` (`activate: false` in the operation) to build and install without making the release live. `activate: false` cannot be combined with `restart`.
122
145
 
123
146
  ```json
124
- { "operation": "list_deployments", "project": "my-app", "status": "success", "limit": 20 }
147
+ {
148
+ "operation": "deploy_component",
149
+ "project": "my-app",
150
+ "package": "npm:@my-org/my-app@1.2.3",
151
+ "activate": false
152
+ }
125
153
  ```
126
154
 
127
- - A `404` response means the id never existed on that node, was pruned, or the release was replaced and not kept. A `409` means the build exists but cannot be activated (e.g., belongs to another component, or files changed after staging).
128
- - Kept releases and staged builds count against `deployment.stagingRetention.maxCount` (`stagingRetention` default: `5`). Each kept release is a full installed copy of the component, `node_modules` included, so budget disk for it. `0` keeps no replaced releases.
129
-
130
- 7. **Deploy by reference for a reproducible source**: `by_ref=true` sends a pinned git reference instead of uploading the working directory, and the cluster fetches and builds that exact commit. It resolves the repository's `origin` remote and the current commit, then deploys `package=git+https://github.com/<owner>/<repo>.git#<full commit SHA>`. Defaults to `HEAD`.
155
+ The response names the artifact that is now waiting:
131
156
 
132
- ```bash
133
- harper deploy by_ref=true restart=true replicated=true
157
+ ```json
158
+ {
159
+ "deployment_id": "a3f8c2d1-...",
160
+ "message": "Staged: my-app. Deploy it with deploy_component deployment_id=a3f8c2d1-..."
161
+ }
134
162
  ```
135
163
 
136
- Deploy a specific tag or commit with `ref`:
164
+ The response includes a `deployment_id` naming the staged artifact. Staged builds and replaced releases together count against `deployment.stagingRetention.maxCount` (default `5`). Each kept release is a full installed copy of the component, `node_modules` included. The oldest are pruned at the next deploy or startup.
165
+ - `404` means the id never existed on that node, was pruned, or the release was replaced and not kept. A `409` means the build exists but cannot be activated (e.g., belongs to another component, or files changed after staging).
137
166
 
138
- ```bash
139
- harper deploy ref=v1.2.0 restart=true replicated=true
140
- harper deploy ref=9f8c2a1 restart=true replicated=true
141
- ```
167
+ 8. **Roll back to a previous release**: Use `list_deployments` to find the `deployment_id` of the release to restore. Then activate that id with `restart`. This swaps in the exact installed release with no fetch, rebuild, or reinstall. The release it replaces is kept in turn, so you can go forward again the same way.
142
168
 
143
- - Tags and branches are resolved to a full commit SHA before the deploy is sent. A `ref` that cannot be resolved stops the deploy — run `git fetch` and retry, or pass a full commit SHA.
144
- - Any other `ref` must name something a clone can fetch: `refs/heads/*` or `refs/tags/*`, or a bare branch or tag name. A qualified ref outside those, such as `refs/pull/123/head`, is rejected up front.
145
- - On a GitHub Actions `pull_request` run, `by_ref` deploys the pull request's head commit. If the event payload isn't readable, the deploy stops; pass the commit explicitly.
146
- - Commit and push first — the cluster clones from the remote and only sees pushed commits.
169
+ ```json
170
+ {
171
+ "operation": "deploy_component",
172
+ "project": "my-app",
173
+ "deployment_id": "<id of the deployment you want back>",
174
+ "restart": true
175
+ }
176
+ ```
147
177
 
148
- 8. **Check certification after a rolling deploy**: A deploy with `restart=rolling` certifies the release in a canary worker before rolling it out. The deploy response includes a `certification` field:
178
+ 9. **Check certification after a rolling deploy**: A deploy with `"restart": "rolling"` certifies the release on each node using a canary worker before rolling it out. The deploy response includes a `certification` field:
149
179
 
150
180
  | `certification` | Meaning |
151
181
  | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
152
182
  | `certified` | The canary loaded the release; rollout proceeded. |
153
183
  | `uncertified` | The rollout went on unchecked: the component ran nothing as it loaded (`loadComponent: dev-only`, an absent `if-installed` component, or safe mode), or no worker was replaced. |
154
- | `unavailable` | Deploy restarted unchecked (no worker loads the component, `isolated` setting changed, already live, or `file:` directory source). |
184
+ | `unavailable` | Deploy restarted unchecked (no worker loads the component, `isolated` setting changed, already live, or `package: file:<dir>` source). |
155
185
  | `not-requested` | The deploy did not restart. |
156
- - **A rejected release fails the deploy.** If the canary throws while loading the component, exits, or doesn't report within a minute, the deploy fails with `400`. The release it replaced is made live again, and nothing is replicated to other nodes. The error carries the decision as an object in `certification` with `status` set to `rejected`, or to `interrupted` for a restart that stopped before the canary decided.
157
- - **A release with nothing to go back to fails closed.** A rejected first deploy, or one whose previous release was not kept, stays on disk, but no worker on that node loads it, even after Harper restarts. `get_status` reports the component as failed and says why. Deploy a fix, or activate the same `deployment_id` again with `restart`.
186
+ - **A rejected release fails the deploy.** If the canary throws while loading the component, exits, or doesn't report within a minute, the deploy fails with `400`. The release it replaced is made live again, and nothing is replicated to other nodes. A restart that stops before the canary decides is reported with `status: "interrupted"`.
187
+ - **A release with nothing to go back to fails closed.** A rejected first deploy, or one whose previous release was not kept, stays on disk, but no worker on that node loads it, even after Harper restarts. `get_status` reports the component as failed and says why. Deploy a fixed release, or activate the same `deployment_id` again with `restart` once the cause is fixed.
158
188
  - Another deploy or `drop_component` of the component on that node is refused with `409` until the rollout has finished.
159
189
 
160
- 9. **Wait for a rolling deploy to finish**: A `deploy_component` with `"restart": "rolling"` returns a `restartJobId`. Poll it with `get_job` to learn whether every node took the release.
190
+ 10. **Check rolling deploy job status**: A `deploy_component` with `"restart": "rolling"` returns a `restartJobId`. Call `get_job` on the node that received the deploy — `system.hdb_job` is not replicated.
161
191
 
162
- ```json
163
- { "operation": "get_job", "id": "4a982782-929a-4507-8794-26dae1132def" }
164
- ```
192
+ ```json
193
+ { "operation": "get_job", "id": "<restartJobId>" }
194
+ ```
165
195
 
166
- `get_job` returns status `COMPLETE`, `IN_PROGRESS`, or `ERROR`. It answers only on the node that ran the job. A deploy-only role that waits for rolling deploys must include `get_job` in its operations allowlist.
167
- - `list_deployments` returns records newest first. Filter by `project` and `status`; omit `limit` to return every matching record. A deploy in progress reads `pending`, or `loading`, until its `completed_at` is set.
196
+ `get_job` returns status `COMPLETE`, `IN_PROGRESS`, or `ERROR`. It answers only on the node that ran the job — `system.hdb_job` is not replicated. For a rolling deploy, that is the node that received the deploy. A deploy-only role that polls for rolling deploys must include `get_job` in its operations allowlist. The job ends `COMPLETE` on success, or `ERROR` with a `message` listing each node's outcome under `activated`.
197
+
198
+ 11. **Monitor `list_deployments` correctly**: A deploy in progress reads `pending`, or `loading` once its release has started loading. A rolling deploy's record reads `rolling_out` until the job has visited every node; filter `list_deployments` without `status` and check each record's `status` is a finished one (`success`, `failed`, `staged`, or `partial`). `completed_at` alone does not indicate completion, since a `rolling_out` record already has it.
199
+
200
+ ```json
201
+ {
202
+ "operation": "list_deployments",
203
+ "project": "my-app",
204
+ "limit": 20
205
+ }
206
+ ```
207
+
208
+ - The `list_deployments` response strips `payload_blob` and replaces it with `payload_blob_present`; use `get_deployment_payload` to retrieve the tarball.
168
209
 
169
210
  ## Examples
170
211
 
171
- ### Full rolling deploy from a pinned tag
212
+ ### Full rolling deploy from a git tag
172
213
 
173
214
  ```bash
174
- # Authenticate once
175
215
  harper login https://my-cluster.harperdbcloud.com
176
-
177
- # Deploy a pinned release with rolling restart
178
216
  harper deploy \
179
217
  project=my-app \
180
218
  ref=v1.2.0 \
181
- target=https://my-cluster.harperdbcloud.com \
182
219
  restart=rolling \
183
- replicated=true
220
+ replicated=true \
221
+ credential=true
184
222
  ```
185
223
 
186
224
  ### Stage a build, then activate in a maintenance window
@@ -203,7 +241,7 @@ Response:
203
241
  }
204
242
  ```
205
243
 
206
- Activate later:
244
+ Activate later with restart:
207
245
 
208
246
  ```json
209
247
  {
@@ -214,27 +252,30 @@ Activate later:
214
252
  }
215
253
  ```
216
254
 
217
- ### Roll back to a previous release
255
+ ### Roll back using list_deployments
218
256
 
219
257
  ```json
220
- {
221
- "operation": "list_deployments",
222
- "project": "my-app"
223
- }
258
+ { "operation": "list_deployments", "project": "my-app", "limit": 10 }
224
259
  ```
225
260
 
226
- Then:
227
-
228
261
  ```json
229
262
  {
230
263
  "operation": "deploy_component",
231
264
  "project": "my-app",
232
- "deployment_id": "<id of the deployment you want back>",
265
+ "deployment_id": "<previous-deployment-id>",
233
266
  "restart": true
234
267
  }
235
268
  ```
236
269
 
237
- ### Rejected canary — error response shape
270
+ ### Check a rolling deploy job
271
+
272
+ ```json
273
+ { "operation": "get_job", "id": "4a982782-929a-4507-8794-26dae1132def" }
274
+ ```
275
+
276
+ The job ends `COMPLETE` when every node has taken the release, or `ERROR` with node-level detail if any node did not.
277
+
278
+ ### Certification rejection response
238
279
 
239
280
  ```json
240
281
  {
@@ -254,14 +295,13 @@ Then:
254
295
 
255
296
  ## Notes
256
297
 
257
- - `harper login` stores a token; subsequent `harper deploy` calls to the same target need no credentials. See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) for cluster setup.
258
- - For GitHub Actions, prefer OIDC workload identity over stored tokens. See [deploying-from-ci.md](deploying-from-ci.md).
259
- - `restart=rolling` and `activate=false` cannot be combined.
260
- - `deployment_id` activation takes no `package`, `payload`, `credentials`, install options, `urlPath`, or `host` — supplying them is rejected.
261
- - `file:` directory sources (`package: file:<dir>`) cannot be staged and are not kept as rollback targets.
262
- - `stagingRetention.maxCount` (default `5`) caps staged builds and kept replaced releases together per component.
263
- - `get_job` on a `restartJobId` answers only on the node that received the deploy; any other node returns an empty array.
264
- - A rolling deploy's record reads `rolling_out` until the job has visited every node; filter `list_deployments` without `status` and check each record's `status` for a finished value (`success`, `partial`, `failed`, `staged`). `completed_at` alone does not confirm a finished state, since a `rolling_out` record already has it.
265
- - `enc:v1:` envelopes store only ciphertext — plaintext never leaves your machine and never appears in operation logs or replication.
266
- - Tags used in `refs/tags` are resolved to a commit SHA before the deploy is sent; a tag that moves mid-deploy cannot cause nodes to run different code.
267
- - `super_user` is required to run `harper deploy setup=true`.
298
+ - `replicated=false` restricts a deploy to the single node you called. On Harper Fabric, omit this parameter to reach every node.
299
+ - `restart=rolling` cannot be combined with `activate=false`.
300
+ - `deployment_id` activation takes no `package`, `payload`, `credentials`, install options, or `urlPath`/`host` — supplying them is rejected.
301
+ - `file:` directory sources cannot be staged with `activate=false` and are not kept as rollback targets.
302
+ - `deployment.stagingRetention.maxCount` (default `5`) caps staged builds and kept replaced releases together per component. At the default, budget disk for up to five extra copies per component, `node_modules` included.
303
+ - A deploy-only role that waits for rolling deploys must include `get_job` in its operations allowlist.
304
+ - `get_job` answers only on the node that ran the job — `system.hdb_job` is not replicated.
305
+ - The `enc:v1:` envelope is the only form of the token that ever leaves your machine or appears in API logs.
306
+ - The secret provisioned by `harper deploy setup=true` is stored scoped to the component, never in the global `processEnv` tier.
307
+ - For creating the cluster itself, see [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md). For full CI/CD pipeline setup, see [deploying-from-ci.md](deploying-from-ci.md).
@@ -7,7 +7,7 @@ metadata:
7
7
  mode: generate
8
8
  sources:
9
9
  - reference/v5/environment-variables/overview.md
10
- sourceCommit: 2dde0597443a13af0c753f2adbe528e8442d8ee4
10
+ sourceCommit: 489477b2259ba148f4e526ea4b5cd24041ceec03
11
11
  inputHash: 51b7b4f21b275eec
12
12
  ---
13
13
 
@@ -19,11 +19,11 @@ Instructions for the agent to follow when loading environment variables from `.e
19
19
 
20
20
  ## When to Use
21
21
 
22
- Apply this rule when a Harper application needs to supply secrets, API endpoints, or other configuration values to component code via `process.env` without hardcoding them. Use this whenever a `.env` file must be loaded at application startup.
22
+ Apply this rule when a Harper application needs to supply secrets, API endpoints, or other configuration values to component code via `process.env` without hardcoding them. Use this whenever a `.env` file must be loaded at application startup before other components run.
23
23
 
24
24
  ## How It Works
25
25
 
26
- 1. **Declare `loadEnv` first in `config.yaml`**: Place `loadEnv` before all other components so environment variables are available when dependent components start.
26
+ 1. **Declare `loadEnv` first in `config.yaml`**: Place `loadEnv` before all other components so environment variables are available when dependent components start. Harper is single-process, so variables loaded onto `process.env` are shared across all components.
27
27
 
28
28
  ```yaml
29
29
  # config.yaml — loadEnv must come first
@@ -31,13 +31,11 @@ Apply this rule when a Harper application needs to supply secrets, API endpoints
31
31
  files: '.env'
32
32
  ```
33
33
 
34
- 2. **Set the `files` option**: Provide one or more paths or glob patterns pointing to the env file(s) to load. This option is required.
34
+ 2. **Specify files to load**: Set the `files` option to a path, glob pattern, or list of paths. This is the only required option.
35
35
 
36
- 3. **Access variables in component code**: After loading, all values from the specified files are available on `process.env` and shared across all components in the single Harper process.
36
+ 3. **Control override behavior**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to make loaded values overwrite existing environment variables.
37
37
 
38
- 4. **Control override behavior with `override`**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to reverse this — loaded values will overwrite variables already present in the shell or container environment.
39
-
40
- 5. **Load multiple files when needed**: Specify a list or a glob pattern under `files`. Files are loaded in the order specified.
38
+ 4. **Access values in component code**: After loading, all values from the specified files are available on `process.env` throughout your components.
41
39
 
42
40
  ### Configuration Options
43
41
 
@@ -48,26 +46,13 @@ Apply this rule when a Harper application needs to supply secrets, API endpoints
48
46
 
49
47
  ## Examples
50
48
 
51
- **Basic usage — load a single `.env` file:**
49
+ **Basic single file:**
52
50
 
53
51
  ```yaml
54
52
  loadEnv:
55
53
  files: '.env'
56
54
  ```
57
55
 
58
- **Full `config.yaml` with `loadEnv` declared first:**
59
-
60
- ```yaml
61
- # config.yaml — loadEnv must come first
62
- loadEnv:
63
- files: '.env'
64
-
65
- rest: true
66
-
67
- myApp:
68
- files: './src/*.js'
69
- ```
70
-
71
56
  **Override existing environment variables:**
72
57
 
73
58
  ```yaml
@@ -76,7 +61,7 @@ loadEnv:
76
61
  override: true
77
62
  ```
78
63
 
79
- **Load multiple files as a list:**
64
+ **Multiple explicit files** (loaded in order specified):
80
65
 
81
66
  ```yaml
82
67
  loadEnv:
@@ -85,18 +70,30 @@ loadEnv:
85
70
  - '.env.local'
86
71
  ```
87
72
 
88
- **Load multiple files using a glob pattern:**
73
+ **Glob pattern:**
89
74
 
90
75
  ```yaml
91
76
  loadEnv:
92
77
  files: 'env-vars/*'
93
78
  ```
94
79
 
80
+ **Full `config.yaml` with dependent components:**
81
+
82
+ ```yaml
83
+ # config.yaml — loadEnv must come first
84
+ loadEnv:
85
+ files: '.env'
86
+
87
+ rest: true
88
+
89
+ myApp:
90
+ files: './src/*.js'
91
+ ```
92
+
95
93
  ## Notes
96
94
 
97
- - `loadEnv` is built into Harper — it does not need to be installed, only declared in `config.yaml`.
98
- - Variables are loaded onto `process.env` and shared across all components. Declare `loadEnv` before any component that depends on those variables.
99
- - `loadEnv` supplies **application** environment variables only. It does **not** configure Harper itself. Harper's own configuration is composed at startup before any `loadEnv` runs, so variables such as `HARPER_CONFIG`, `HARPER_SET_CONFIG`, and `HARPER_DEFAULT_CONFIG` delivered through a `.env` file are read too late and are ignored.
100
- - To change Harper's own configuration, use the configuration file directly or export variables in the real process/container environment before Harper starts.
101
- - For production credentials, prefer the encrypted secrets store over a committed `.env` file. Secrets are delivered to components via `process.env` and never appear in operation logs or replication payloads.
102
- - Individual `.env` values can also be stored encrypted so plaintext never reaches the API, logs, or replication payload.
95
+ - `loadEnv` is built into Harper — do not install it separately. Only declare it in `config.yaml`.
96
+ - `loadEnv` supplies **application** environment variables for component code. It does **not** configure Harper itself.
97
+ - Harper's own configuration is composed at startup **before** any `loadEnv` runs. Variables such as `HARPER_CONFIG`, `HARPER_SET_CONFIG`, and `HARPER_DEFAULT_CONFIG` delivered through a `.env` file are read too late and are ignored. Set Harper configuration in the configuration file or export variables in the real process/container environment before Harper starts.
98
+ - A component's `.env` file can be managed remotely via the Operations API (`get_env_keys`, `set_env_value`, `delete_env_value`). Changes reach running code only after worker threads restart.
99
+ - For production credentials, prefer the encrypted secrets store over a committed `.env` file. Individual `.env` values can also be stored encrypted. See [Encrypted Environment Values](encrypted-values.md) and [Secrets](secrets.md).