@gadicc/loom 1.36.0 → 1.37.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.
@@ -56,6 +56,11 @@ from the consumer's working directory.
56
56
  whole-file rewrites or string-only runner guesses.
57
57
  - If a loom-managed file exists only as a thin wrapper, keep it thin unless the
58
58
  app intentionally needs custom behavior there.
59
+ - Loom commands that change something outside the repository (a deployment
60
+ platform's variables, a provider's settings) ask only a person at a terminal.
61
+ In an agent session they ask nothing and change nothing unless given an
62
+ explicit flag such as `--vercel`. Pass such a flag only when the user asked
63
+ for that change; otherwise run without it and relay the printed command.
59
64
  - Loom never overwrites a file with local edits. `loom init`, `loom add`, and
60
65
  feature syncs update a Loom-managed file only while it is provably unmodified
61
66
  Loom output (layout and quote style aside), using the hashes under each
@@ -68,6 +68,14 @@ names:
68
68
  - `FILES_S3_REGION=auto`
69
69
  - `FILES_STORAGE_PROVIDER=cloudflare-r2`
70
70
 
71
+ Setup adds missing non-secret values with `--no-sensitive` (Vercel CLI 54 or
72
+ newer), because the CLI otherwise stores a Production or Preview value as a
73
+ Secret, which `loom files r2 check` and release env policies cannot read back.
74
+ `--repair` updates drifted values in place and keeps their Vercel type, so it
75
+ cannot fix a value an earlier setup stored as a Secret. Setup and
76
+ `loom check --network` name any such values instead of suggesting `--repair`;
77
+ remove them in Vercel, then rerun setup to add them back as readable values.
78
+
71
79
  The sensitive variables are `FILES_S3_ACCESS_KEY_ID` and
72
80
  `FILES_S3_SECRET_ACCESS_KEY`. Rerun setup to repair missing non-secret values or
73
81
  prompt only for missing secrets. Run `loom files r2 check` or
@@ -40,10 +40,10 @@ Do not describe it as more than this in an app's docs or UI.
40
40
  password manager and the deployment platform. An agent's transcript is a
41
41
  third. Ask the operator to run it in their own terminal, then continue from
42
42
  the fingerprint, which is not secret. The same goes for
43
- `loom secrets fingerprint`, which prompts for a key. Both commands refuse to
44
- run when they detect a CI or agent session or a missing terminal. That is a
45
- guardrail, not a guarantee: do not look for a way to satisfy it. The rule
46
- holds whether or not the command would run.
43
+ `loom secrets fingerprint` and `loom secrets push`, which prompt for a key.
44
+ All three refuse to run when they detect a CI or agent session or a missing
45
+ terminal. That is a guardrail, not a guarantee: do not look for a way to
46
+ satisfy it. The rule holds whether or not the command would run.
47
47
  - **Never pass a key as a command-line argument**, to `fingerprint` or anything
48
48
  else. A key typed there is in shell history: treat it as exposed and rotate.
49
49
  - **Never read, print, log or commit a key**: not `.env.local`, not a
@@ -160,6 +160,17 @@ LOOM_SECRETS_ACTIVE_KEY=1 # readable
160
160
  - Production fingerprints are recorded in `loom.json` with a state: `active`,
161
161
  `decrypt-only` or `retired`. Use `loom secrets activate` and
162
162
  `loom secrets retire` to change states rather than editing by hand.
163
+ - On a project linked to Vercel (`.vercel/project.json`), `keygen` offers to add
164
+ the new key to Vercel Production as a Secret, and the pointer when the key is
165
+ the active one. It first has the operator paste the key back from their
166
+ password manager and checks it against the recorded fingerprint, so the saved
167
+ copy is proven before Vercel has one. `loom secrets push <id>` does the same
168
+ later for a recorded key, and `loom secrets activate <id>` offers to move the
169
+ Vercel pointer before it changes `loom.json`. `--vercel` does it without the
170
+ first question and `--no-vercel` never. When telling an operator to run
171
+ `keygen`, mention the offer. An agent may run `activate --vercel` only when
172
+ the user asked for that production change; without the flag, an agent session
173
+ changes nothing on Vercel.
163
174
  - Development keys are written to `.env.local` by `loom add secrets` and are not
164
175
  recorded. `vercel env pull` rewrites `.env.local` and can drop them; run
165
176
  `loom add secrets` again. Locally sealed rows are then unreadable, which is
@@ -170,16 +181,19 @@ LOOM_SECRETS_ACTIVE_KEY=1 # readable
170
181
  1. Operator: `loom secrets keygen`, which records the new key as `decrypt-only`.
171
182
  Save the key and fingerprint in the password manager.
172
183
  2. Operator: add `LOOM_SECRETS_KEY_<n+1>` to the platform from the
173
- password-manager copy, as a write-only secret for Production only. Deploy.
174
- The health check must pass.
184
+ password-manager copy, as a write-only secret for Production only (on Vercel,
185
+ accept `keygen`'s offer or run `loom secrets push <n+1>`). Deploy. The health
186
+ check must pass.
175
187
  3. Move the pointer, in this order. Operator: set
176
- `LOOM_SECRETS_ACTIVE_KEY=<n+1>` on the platform **first**. Then
177
- `loom secrets activate <n+1>`, run `loom check --production`, and push the
178
- `loom.json` change, so the deployment that carries the new list is built with
179
- the new pointer. In the other order, a deployment with the new list and the
180
- old pointer fails every `seal`, `reseal` and `mac` (opens still work). Then
181
- delete deployments built before step 2: an older deployment keeps the
182
- environment it was built with and cannot read the new rows.
188
+ `LOOM_SECRETS_ACTIVE_KEY=<n+1>` on the platform **first** (on Vercel,
189
+ `loom secrets activate <n+1>` offers to do this before it changes
190
+ `loom.json`). Then `loom secrets activate <n+1>`, run
191
+ `loom check --production`, and push the `loom.json` change, so the deployment
192
+ that carries the new list is built with the new pointer. In the other order,
193
+ a deployment with the new list and the old pointer fails every `seal`,
194
+ `reseal` and `mac` (opens still work). Then delete deployments built before
195
+ step 2: an older deployment keeps the environment it was built with and
196
+ cannot read the new rows.
183
197
  4. Run `reseal` (a real run needs `dryRun: false`), then `report`, then
184
198
  `verify`.
185
199
  5. Retiring the old key is a separate decision. It is safe only when: