@gadicc/loom 1.35.3 → 1.36.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.
- package/README.md +56 -0
- package/THIRD_PARTY_NOTICES.md +12 -9
- package/esm/src/cli/externalSkills.d.ts.map +1 -1
- package/esm/src/cli/externalSkills.js +25 -20
- package/esm/src/cli/mod.d.ts +72 -1
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +771 -36
- package/esm/src/cli/projectSkills.d.ts +10 -3
- package/esm/src/cli/projectSkills.d.ts.map +1 -1
- package/esm/src/cli/projectSkills.js +173 -49
- package/esm/src/cli/vercelBuildEnv.d.ts +28 -0
- package/esm/src/cli/vercelBuildEnv.d.ts.map +1 -1
- package/esm/src/cli/vercelBuildEnv.js +120 -30
- package/esm/src/next/secrets/mod.d.ts +108 -0
- package/esm/src/next/secrets/mod.d.ts.map +1 -0
- package/esm/src/next/secrets/mod.js +176 -0
- package/esm/src/secrets/encoding.d.ts +32 -0
- package/esm/src/secrets/encoding.d.ts.map +1 -0
- package/esm/src/secrets/encoding.js +87 -0
- package/esm/src/secrets/errors.d.ts +45 -0
- package/esm/src/secrets/errors.d.ts.map +1 -0
- package/esm/src/secrets/errors.js +39 -0
- package/esm/src/secrets/fingerprint.d.ts +43 -0
- package/esm/src/secrets/fingerprint.d.ts.map +1 -0
- package/esm/src/secrets/fingerprint.js +87 -0
- package/esm/src/secrets/frame.d.ts +34 -0
- package/esm/src/secrets/frame.d.ts.map +1 -0
- package/esm/src/secrets/frame.js +86 -0
- package/esm/src/secrets/keyring.d.ts +62 -0
- package/esm/src/secrets/keyring.d.ts.map +1 -0
- package/esm/src/secrets/keyring.js +160 -0
- package/esm/src/secrets/legacy.d.ts +60 -0
- package/esm/src/secrets/legacy.d.ts.map +1 -0
- package/esm/src/secrets/legacy.js +147 -0
- package/esm/src/secrets/maintenance.d.ts +173 -0
- package/esm/src/secrets/maintenance.d.ts.map +1 -0
- package/esm/src/secrets/maintenance.js +315 -0
- package/esm/src/secrets/mod.d.ts +6 -0
- package/esm/src/secrets/mod.d.ts.map +1 -0
- package/esm/src/secrets/mod.js +5 -0
- package/esm/src/secrets/secrets.d.ts +192 -0
- package/esm/src/secrets/secrets.d.ts.map +1 -0
- package/esm/src/secrets/secrets.js +528 -0
- package/package.json +50 -2
- package/script/src/cli/externalSkills.d.ts.map +1 -1
- package/script/src/cli/externalSkills.js +25 -20
- package/script/src/cli/mod.d.ts +72 -1
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +772 -33
- package/script/src/cli/projectSkills.d.ts +10 -3
- package/script/src/cli/projectSkills.d.ts.map +1 -1
- package/script/src/cli/projectSkills.js +173 -49
- package/script/src/cli/vercelBuildEnv.d.ts +28 -0
- package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
- package/script/src/cli/vercelBuildEnv.js +121 -30
- package/script/src/next/secrets/mod.d.ts +108 -0
- package/script/src/next/secrets/mod.d.ts.map +1 -0
- package/script/src/next/secrets/mod.js +218 -0
- package/script/src/secrets/encoding.d.ts +32 -0
- package/script/src/secrets/encoding.d.ts.map +1 -0
- package/script/src/secrets/encoding.js +95 -0
- package/script/src/secrets/errors.d.ts +45 -0
- package/script/src/secrets/errors.d.ts.map +1 -0
- package/script/src/secrets/errors.js +45 -0
- package/script/src/secrets/fingerprint.d.ts +43 -0
- package/script/src/secrets/fingerprint.d.ts.map +1 -0
- package/script/src/secrets/fingerprint.js +92 -0
- package/script/src/secrets/frame.d.ts +34 -0
- package/script/src/secrets/frame.d.ts.map +1 -0
- package/script/src/secrets/frame.js +91 -0
- package/script/src/secrets/keyring.d.ts +62 -0
- package/script/src/secrets/keyring.d.ts.map +1 -0
- package/script/src/secrets/keyring.js +202 -0
- package/script/src/secrets/legacy.d.ts +60 -0
- package/script/src/secrets/legacy.d.ts.map +1 -0
- package/script/src/secrets/legacy.js +186 -0
- package/script/src/secrets/maintenance.d.ts +173 -0
- package/script/src/secrets/maintenance.d.ts.map +1 -0
- package/script/src/secrets/maintenance.js +323 -0
- package/script/src/secrets/mod.d.ts +6 -0
- package/script/src/secrets/mod.d.ts.map +1 -0
- package/script/src/secrets/mod.js +24 -0
- package/script/src/secrets/secrets.d.ts +192 -0
- package/script/src/secrets/secrets.d.ts.map +1 -0
- package/script/src/secrets/secrets.js +532 -0
- package/skills/loom/SKILL.md +74 -222
- package/skills/loom/references/dependency-upgrades.md +26 -0
- package/skills/loom/references/local-development.md +157 -0
- package/skills/loom/references/release-safety.md +118 -0
- package/skills/loom/references/release-trusted-sources.md +55 -0
- package/skills/loom/references/tools-and-skills.md +83 -0
- package/skills/loom-api-keys/SKILL.md +1 -1
- package/skills/loom-auth/SKILL.md +7 -60
- package/skills/loom-auth/references/secrets-and-rotation.md +61 -0
- package/skills/loom-db/SKILL.md +4 -79
- package/skills/loom-files/SKILL.md +4 -2
- package/skills/loom-files/references/provider-configuration.md +142 -0
- package/skills/loom-jobs/SKILL.md +9 -8
- package/skills/loom-lingui/SKILL.md +5 -3
- package/skills/loom-secrets/SKILL.md +252 -0
- package/skills/loom-torvalds-review/SKILL.md +9 -6
- package/skills/loom-torvalds-review/references/context-profiles.md +2 -1
- package/skills/upgrade-deps/SKILL.md +15 -7
package/skills/loom/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: loom
|
|
3
|
-
description:
|
|
3
|
+
description: Work in apps consuming @gadicc/loom. Use for shared feature adoption, loom.json, CLI workflows, and app versus package ownership.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Loom
|
|
@@ -69,6 +69,44 @@ from the consumer's working directory.
|
|
|
69
69
|
`db:migrate`, is kept and reported; delete it and rerun `loom add <feature>`
|
|
70
70
|
to restore Loom's value. Do not edit `managedFiles` or `managedTasks` by hand.
|
|
71
71
|
|
|
72
|
+
## High-value code improvements
|
|
73
|
+
|
|
74
|
+
While doing requested work, look for high-value improvements in code you
|
|
75
|
+
inspect, including existing code that works but is unnecessarily verbose or
|
|
76
|
+
difficult to maintain. Behavior-preserving cleanup is valuable when it makes
|
|
77
|
+
code easier to understand and change. Question inherited patterns rather than
|
|
78
|
+
perpetuating unnecessary complexity.
|
|
79
|
+
|
|
80
|
+
Look for opportunities to simplify logic, remove redundant scaffolding, and
|
|
81
|
+
isolate behavior for independent testing. Prefer clear, direct code over clever
|
|
82
|
+
compression or unnecessary abstraction. Preserve useful explanations,
|
|
83
|
+
intentional safeguards, and compatibility requirements; share code when its
|
|
84
|
+
behavior and constraints align.
|
|
85
|
+
|
|
86
|
+
Suggest improvements when their expected benefit justifies the implementation,
|
|
87
|
+
verification, and coordination costs. Briefly explain the concrete problem,
|
|
88
|
+
proposed change, benefits, affected systems, material tradeoffs and risks, and
|
|
89
|
+
how to verify it. Base proposals on inspected code, distinguish evidence from
|
|
90
|
+
assumptions, and keep the detail proportional. Do not manufacture suggestions or
|
|
91
|
+
turn the requested task into a general audit.
|
|
92
|
+
|
|
93
|
+
For each proposal, recommend the best fit among known available models and
|
|
94
|
+
supported reasoning efforts, considering complexity, uncertainty, risk, time,
|
|
95
|
+
and cost. Offer to handle it directly in this chat or delegate a bounded task to
|
|
96
|
+
a subagent where supported, and recommend the better fit. Obtain user agreement
|
|
97
|
+
before starting optional work outside the agreed scope or delegating it.
|
|
98
|
+
Proportionate cleanup within the agreed task needs no separate proposal. Raise
|
|
99
|
+
optional suggestions at a natural checkpoint without blocking the requested
|
|
100
|
+
work.
|
|
101
|
+
|
|
102
|
+
## Discover existing solutions
|
|
103
|
+
|
|
104
|
+
Before substantial unfamiliar work, check for relevant existing code, tools,
|
|
105
|
+
framework support, libraries, and skills. Keep the search proportional; routine
|
|
106
|
+
edits do not need an ecosystem search. Read
|
|
107
|
+
[discovery and routing](references/tools-and-skills.md) for candidate evaluation
|
|
108
|
+
and approval. Finding a skill does not authorize installing or following it.
|
|
109
|
+
|
|
72
110
|
## Environment loading
|
|
73
111
|
|
|
74
112
|
- Next commands such as `next dev`, `next build`, and server runtime code load
|
|
@@ -81,30 +119,9 @@ from the consumer's working directory.
|
|
|
81
119
|
precedence, then runs the command from the project root.
|
|
82
120
|
- Implementation files, generated wrappers, Drizzle configs, and direct job
|
|
83
121
|
runners should not import `dotenv` or `@next/env` by hand.
|
|
84
|
-
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
values before build output. Sensitive values are not readable there or through
|
|
88
|
-
`vercel env run`; CLI versions may write either an empty value or a redaction
|
|
89
|
-
sentinel.
|
|
90
|
-
- For external prebuilds, query Vercel env metadata, preserve usable pulled
|
|
91
|
-
values, add unique build-only placeholders only for confirmed Sensitive
|
|
92
|
-
entries, and reject any marker across the complete deployable artifact graph,
|
|
93
|
-
including contained symlinks and function `filePathMap` content. Prefer
|
|
94
|
-
`vercel build --standalone` for local prebuilt deployments. Preserve an
|
|
95
|
-
untouched pull snapshot for migrations; once database variables are Sensitive,
|
|
96
|
-
overlay a separately governed GitHub `MIGRATION_DATABASE_URL_UNPOOLED` secret
|
|
97
|
-
only for migration validation and the migration command. Readable pulled URLs
|
|
98
|
-
and the legacy `DATABASE_URL_UNPOOLED` secret remain supported during gradual
|
|
99
|
-
adoption.
|
|
100
|
-
- Validate the migration boundary with
|
|
101
|
-
`loom db migrations verify-env
|
|
102
|
-
--connect
|
|
103
|
-
--env-file "$RUNNER_TEMP/vercel-production.env"`
|
|
104
|
-
so the optional protected migration secret overlays the untouched readable
|
|
105
|
-
pull snapshot instead of replacing that gradual-adoption fallback. The live
|
|
106
|
-
probe must authenticate with the selected URL and confirm migration schema
|
|
107
|
-
access before a present override supersedes the fallback.
|
|
122
|
+
- For a Loom DB release, read [release safety](references/release-safety.md)
|
|
123
|
+
before deployment or credential commands. Preserve the recorded release mode;
|
|
124
|
+
never print secrets or switch deployment paths after authentication failure.
|
|
108
125
|
|
|
109
126
|
## Re-establishing work context
|
|
110
127
|
|
|
@@ -160,184 +177,38 @@ as more authoritative than a generic mapped error when deciding what failed.
|
|
|
160
177
|
|
|
161
178
|
## Verification
|
|
162
179
|
|
|
163
|
-
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
-
|
|
180
|
-
|
|
181
|
-
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
180
|
+
- During edits, run affected tests and checks. Broaden coverage for shared
|
|
181
|
+
contracts, tooling, generated output, or uncertain impact.
|
|
182
|
+
- Before a code-changing commit, have a passing full local test-suite result for
|
|
183
|
+
the code being committed. Use `deno task test` in Loom; consumers use their
|
|
184
|
+
recorded tooling and full test task. Preserve stronger required quality gates.
|
|
185
|
+
- Format first. Reuse results only while tested inputs and relevant environment
|
|
186
|
+
remain unchanged. Edits or hooks that change those inputs require another full
|
|
187
|
+
run before the commit. Do not rely on unstaged fixes: compare staged and
|
|
188
|
+
working content; use an isolated snapshot when user-owned unstaged code
|
|
189
|
+
differs, without stashing or resetting it.
|
|
190
|
+
- Ordinary prose changes need formatting and reference checks. Packaged skills,
|
|
191
|
+
catalog metadata, activation logic, and reference moves also need relevant
|
|
192
|
+
skill/catalog tests and verification that references ship and resolve.
|
|
193
|
+
- Fix failures caused by the change. Disclose baseline failures; obtain
|
|
194
|
+
agreement before a local checkpoint commit with failing checks. Never call it
|
|
195
|
+
release-ready.
|
|
196
|
+
- Run `loom check` for consumer wiring and `loom skills check` for adopted skill
|
|
197
|
+
integrity. Recommendations are optional; checking does not authorize adoption.
|
|
198
|
+
- Use runtime verification for affected Next.js behavior when a server is
|
|
199
|
+
running. Keep required build, browser-type, integration, CI and release gates
|
|
200
|
+
intact. In Loom, `deno task check` remains the complete package quality gate.
|
|
201
|
+
- Read [tool and skill routing](references/tools-and-skills.md) when external
|
|
202
|
+
guidance overlaps. Use feature-specific Loom skills for affected active
|
|
203
|
+
features.
|
|
185
204
|
|
|
186
205
|
## Local development
|
|
187
206
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
- For local unpublished Loom package development, use `loom dev local <path>`.
|
|
194
|
-
Loom uses a managed `file:` override for pnpm projects and a local `links`
|
|
195
|
-
entry in the authoritative Deno config for Deno projects.
|
|
196
|
-
- The pnpm override goes where the project's pnpm version applies it
|
|
197
|
-
(`packageManager`, else the `pnpm --version` of the pnpm Loom runs; not
|
|
198
|
-
`npm_config_user_agent`, which names the pnpm running the current script), as
|
|
199
|
-
verified with real pnpm 9.7.0 to 11.25.0:
|
|
200
|
-
- pnpm before 10.5.1 reads overrides only from package.json `resolutions` and
|
|
201
|
-
`pnpm.overrides`; Loom adds its entry there, creating `resolutions` when
|
|
202
|
-
neither exists. pnpm 9 also needs `packages:` in any `pnpm-workspace.yaml`.
|
|
203
|
-
- pnpm 10.5.1 to 10.x reads `pnpm-workspace.yaml` `overrides` only while both
|
|
204
|
-
package.json maps are empty; otherwise the package.json maps replace (not
|
|
205
|
-
merge with) the workspace map, so Loom uses the package.json map there.
|
|
206
|
-
- pnpm 11 reads only `pnpm-workspace.yaml` overrides.
|
|
207
|
-
- An unknown version is treated as pnpm 10.5.1 or newer; pnpm 8 and older are
|
|
208
|
-
untested.
|
|
209
|
-
- An ignored override shows up as pnpm reporting "Lockfile is up to date" while
|
|
210
|
-
the app keeps the published package; `pnpm config get overrides` does not
|
|
211
|
-
reveal this. `loom dev sync` moves an override that is in the wrong place, and
|
|
212
|
-
fails with the detected pnpm version if pnpm still does not apply it.
|
|
213
|
-
- The managed flow keeps the committed dependency/import on a published Loom
|
|
214
|
-
version. `loom dev sync` refreshes with a plain `pnpm install` (or
|
|
215
|
-
`deno install`, according to `project.tooling`), which keeps every other
|
|
216
|
-
locked version. Do not link or refresh Loom with `pnpm update`; it re-resolves
|
|
217
|
-
Loom's dependency subtree and can leave duplicate peer variants of packages
|
|
218
|
-
such as `@better-auth/core`. To move to another published Loom version, set
|
|
219
|
-
the exact version in package.json and run `pnpm install`, which keeps other
|
|
220
|
-
locked versions. `pnpm add --save-exact @gadicc/loom@<version>` (with `-w` at
|
|
221
|
-
a workspace root with packages) gives the same lockfile but may re-sort
|
|
222
|
-
package.json; it is only needed to replace a local resolution an older
|
|
223
|
-
`pnpm update --no-save` link left under an unchanged pin. The sync fails if
|
|
224
|
-
pnpm-lock.yaml does not record the override afterwards and warns when the
|
|
225
|
-
install added duplicate peer variants.
|
|
226
|
-
- `loom dev sync` decides freshness by content: it rebuilds when the Loom
|
|
227
|
-
sources differ from the fingerprint stamped into the `npm/` build and
|
|
228
|
-
reinstalls when the app's installed copy differs from `npm/` by file list or
|
|
229
|
-
content, including after a `deno task build` run outside the sync. Use
|
|
230
|
-
`--force` only to rebuild and reinstall unconditionally.
|
|
231
|
-
- Concurrent Loom commands take turns through `.loom/dev-sync.lock`, and
|
|
232
|
-
`loom dev local` and `loom dev published` take the same lock: a second command
|
|
233
|
-
waits for the running sync, then re-reads the link and re-checks freshness
|
|
234
|
-
instead of rebuilding again (or re-adding an override removed meanwhile). If
|
|
235
|
-
the Loom package it had loaded was replaced while it waited, it treats that as
|
|
236
|
-
a refresh: `loom env` continues, other commands exit 75. The holder refreshes
|
|
237
|
-
the lock every 5 seconds and removes it on Ctrl-C, SIGTERM, or SIGHUP. A lock
|
|
238
|
-
nobody refreshed for a minute (a crash, `kill -9`, another machine) is broken,
|
|
239
|
-
after about 12 seconds when its process is gone on this host or it was already
|
|
240
|
-
a minute old, and after five minutes when its process still exists on this
|
|
241
|
-
host (a paused command); one waiter breaks it at a time under a short
|
|
242
|
-
`.loom/dev-sync.lock.break` lock. A holder that lost its lock stops before its
|
|
243
|
-
next build, install, or state write. After 10 minutes of waiting the command
|
|
244
|
-
fails and names the lock holder.
|
|
245
|
-
- Other Loom commands run the sync automatically while linked. When it refreshes
|
|
246
|
-
the package, `loom env -- <command>` (and so scripts such as `pnpm test` that
|
|
247
|
-
wrap it) still runs its command, with the sync's output on stderr; other
|
|
248
|
-
commands exit with status 75 and must be rerun so they do not run stale Loom
|
|
249
|
-
code.
|
|
250
|
-
- This still avoids the peer-resolution problems we observed with `pnpm link`
|
|
251
|
-
when Loom is consumed by React apps.
|
|
252
|
-
- Treat this as a workaround for current pnpm behavior, not a permanent
|
|
253
|
-
preference. If pnpm's local-link behavior changes enough to preserve peer
|
|
254
|
-
resolution cleanly for Loom, this workaround can be revisited or removed.
|
|
255
|
-
- Before committing app changes or preparing a published build, switch back with
|
|
256
|
-
`loom dev published`, then run `pnpm install` or `deno install`. A lockfile
|
|
257
|
-
linked by an older Loom through `pnpm update --no-save` keeps its local
|
|
258
|
-
resolution through a plain install; restore that lockfile from git when it has
|
|
259
|
-
no other intended changes, as `loom dev published` explains.
|
|
260
|
-
- Each Loom build records its provenance in `npm/.loom-build.json` (kept out of
|
|
261
|
-
the packed package): the git commit it was built from, whether that checkout
|
|
262
|
-
was dirty, and a digest of the packed output. Dirty means tracked changes,
|
|
263
|
-
untracked files git does not ignore, files marked skip-worktree or
|
|
264
|
-
assume-unchanged, or a package-relevant file written while the build ran. The
|
|
265
|
-
last is judged by content, git state and modification times, so an edit
|
|
266
|
-
reverted before the build finished still counts; with whole-second timestamps
|
|
267
|
-
(FAT, HFS+), so does a file written a moment before the build started.
|
|
268
|
-
`loom dev sync` also records its sync in gitignored `.loom/dev-state.json` for
|
|
269
|
-
`loom status` and `loom check`; that record never gates a release. It stays
|
|
270
|
-
while local Loom may still be in use: any local Loom override, link or catalog
|
|
271
|
-
entry (any dangling Deno link counts as possibly Loom's), a local
|
|
272
|
-
`pnpm-lock.yaml` resolution or a Loom link in `deno.lock`, or an installed
|
|
273
|
-
copy that is not provably the published package. pnpm proves that through its
|
|
274
|
-
registry store entry; Deno through a `deno.lock` that records no Loom link and
|
|
275
|
-
resolves the pinned `npm:@gadicc/loom` version from the registry.
|
|
276
|
-
`loom dev published` deletes the record once none is left, which for pnpm
|
|
277
|
-
usually means rerunning it after the `pnpm install` it asks for. Otherwise
|
|
278
|
-
`loom check` treats the record as stale: it notes that it can be deleted and,
|
|
279
|
-
if the recorded checkout still exists, advises a newer pin when a newer
|
|
280
|
-
release covers the synced commit. What the record says fails a production
|
|
281
|
-
check only while a link, override or local lockfile points at local Loom; an
|
|
282
|
-
unproven installed copy alone, or a checkout that no longer exists, only
|
|
283
|
-
warns.
|
|
284
|
-
- `loom dev published` proves what is actually installed, from that build
|
|
285
|
-
provenance, before it switches back:
|
|
286
|
-
- It collects every local Loom target: the managed pnpm override, any
|
|
287
|
-
hand-written `file:`/`link:` Loom entry in the `pnpm-workspace.yaml`
|
|
288
|
-
`overrides:` map, and any `file:`/`link:` resolution in `pnpm-lock.yaml`, or
|
|
289
|
-
every Deno link to Loom. It refuses when they name more than one package.
|
|
290
|
-
- The target's build must record a clean commit, and its npm/ output must
|
|
291
|
-
still match the recorded digest. An older build, one made without git, one
|
|
292
|
-
made from uncommitted changes, or output edited after the build is refused;
|
|
293
|
-
run `loom dev sync`, or commit the Loom changes and run
|
|
294
|
-
`loom dev sync --force`. A checkout whose own build script predates
|
|
295
|
-
provenance (an older tag, say, while bisecting) is rebuilt once per source
|
|
296
|
-
change and then always refused; relink to a newer checkout to switch back
|
|
297
|
-
with proof.
|
|
298
|
-
- The installed copy must match that build (pnpm `node_modules`, and a Deno
|
|
299
|
-
`node_modules` copy unless `nodeModulesDir` is `"none"`), and for pnpm
|
|
300
|
-
`pnpm-lock.yaml` must resolve Loom to it. Otherwise run `loom dev sync`.
|
|
301
|
-
- The build's commit must be reachable from `origin/main` and either included
|
|
302
|
-
in a semver release tag or package-equivalent to the latest semver release
|
|
303
|
-
because only non-package files changed after that tag. The app then switches
|
|
304
|
-
to the exact published Loom version that covers it, unless it already pins a
|
|
305
|
-
newer exact version: Loom never moves a pin back, because a checkout without
|
|
306
|
-
the newest tags names an older covering release.
|
|
307
|
-
- The checkout's current commit and working tree do not matter: later work in
|
|
308
|
-
it neither blocks nor passes a build that is already installed.
|
|
309
|
-
- A pnpm link that was never installed needs no proof: when pnpm-lock.yaml and
|
|
310
|
-
pnpm's record of node_modules still hold the published Loom and
|
|
311
|
-
`node_modules/@gadicc/loom` links pnpm's store entry for that version, the
|
|
312
|
-
overrides are removed and the pin stays. Anything less certain gets the full
|
|
313
|
-
proof: an interrupted install, or a layout without a `node_modules/.pnpm`
|
|
314
|
-
store entry to check (`node-linker=hoisted`, `enableGlobalVirtualStore`, a
|
|
315
|
-
custom `virtual-store-dir`). Deno links are always proved: Deno reads the
|
|
316
|
-
linked directory, or copies it into node_modules on its next install or run,
|
|
317
|
-
so a Deno link has no lasting never-installed state.
|
|
318
|
-
- Apps may pin Loom through a pnpm catalog (`"@gadicc/loom": "catalog:"` or
|
|
319
|
-
`"catalog:<name>"` in package.json, with the version in `pnpm-workspace.yaml`
|
|
320
|
-
`catalog:` or `catalogs:`, as block maps or single-line flow maps). Loom reads
|
|
321
|
-
the version from the catalog, and `loom dev published` pins the covering
|
|
322
|
-
version in that catalog entry while package.json keeps its `catalog:`
|
|
323
|
-
reference. Do not use `pnpm add` to change such a pin; it replaces the
|
|
324
|
-
reference. Edit the catalog and run `pnpm install`.
|
|
325
|
-
- `loom dev published` also removes Deno links and package.json overrides and
|
|
326
|
-
notices stale `pnpm-lock.yaml` resolutions that still point at local Loom
|
|
327
|
-
after the override has been removed.
|
|
328
|
-
- `loom check` should warn during normal development if a Deno link or pnpm
|
|
329
|
-
lockfile still resolves Loom locally, if the synced Loom commit is
|
|
330
|
-
unpublished, or if it is covered by a newer exact version than the app
|
|
331
|
-
currently pins.
|
|
332
|
-
- If an older local-dev block has no recorded commit, switch back carefully and
|
|
333
|
-
run `loom dev sync` first whenever the app may depend on unpublished Loom
|
|
334
|
-
changes.
|
|
335
|
-
- Before app release or CD builds, run `loom check --production` so local Loom
|
|
336
|
-
overrides, local lockfile resolutions, and unresolved synced Loom commits fail
|
|
337
|
-
the build instead of remaining advisory warnings.
|
|
338
|
-
- Publishing Loom makes a version available, but it should not move unrelated
|
|
339
|
-
consumer apps; each app upgrades only through its own package and lockfile
|
|
340
|
-
changes.
|
|
207
|
+
Use `loom dev local <path>` and `loom dev sync` for unpublished package work.
|
|
208
|
+
Read [local development](references/local-development.md) when linking,
|
|
209
|
+
synchronizing, diagnosing local resolutions, or switching back to published
|
|
210
|
+
Loom. Before committing consumer changes, use `loom dev published` and the
|
|
211
|
+
recorded installer. Preserve the package provenance and release-safety checks.
|
|
341
212
|
|
|
342
213
|
## Semver and compatibility
|
|
343
214
|
|
|
@@ -355,28 +226,9 @@ as more authoritative than a generic mapped error when deciding what failed.
|
|
|
355
226
|
|
|
356
227
|
## pnpm major upgrades
|
|
357
228
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
`pnpm-workspace.yaml`; pnpm 11 no longer reads that package.json object.
|
|
362
|
-
- Keep only registry and authentication settings in `.npmrc`. Move pnpm options
|
|
363
|
-
such as `store-dir` and `strictDepBuilds` into `pnpm-workspace.yaml`.
|
|
364
|
-
- Replace `onlyBuiltDependencies`, `ignoredBuiltDependencies`, and related old
|
|
365
|
-
dependency-build settings with an explicit `allowBuilds` map before pnpm 11.
|
|
366
|
-
- For GitHub Actions on pnpm 11+, use the maintained `pnpm/setup` action rather
|
|
367
|
-
than `pnpm/action-setup`.
|
|
368
|
-
- Run `loom check` before changing the pin. Compatibility findings are warnings
|
|
369
|
-
while the app remains on pnpm 10 and issues once it declares pnpm 11 or newer.
|
|
370
|
-
- Keep `@gadicc/loom` in `minimumReleaseAgeExclude`. It is a first-party package
|
|
371
|
-
that consumers routinely need immediately; `loom init` adds the exception
|
|
372
|
-
without weakening pnpm's release-age policy for third-party dependencies.
|
|
373
|
-
- Canary a new pnpm major in one clean Vercel consumer before rolling it across
|
|
374
|
-
the fleet. Verify a frozen install, local tests/build, preview deployment, and
|
|
375
|
-
the production release workflow. Defer consumers with overlapping local config
|
|
376
|
-
edits or unrelated commits that would be pushed by the rollout.
|
|
377
|
-
- pnpm 12 is a separate migration even when it can consume the same lockfile.
|
|
378
|
-
Evaluate it independently after its new Rust CLI and stricter workspace
|
|
379
|
-
validation have matured in the actual deployment platform.
|
|
229
|
+
Use the exact recorded package-manager version. Read
|
|
230
|
+
[pnpm compatibility](references/dependency-upgrades.md) for a major migration;
|
|
231
|
+
newer upstream skill guidance does not authorize upgrading pnpm.
|
|
380
232
|
|
|
381
233
|
## Commits
|
|
382
234
|
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Loom pnpm compatibility
|
|
2
|
+
|
|
3
|
+
## pnpm major upgrades
|
|
4
|
+
|
|
5
|
+
- Treat the exact `packageManager` pin as the consumer contract. Do not move all
|
|
6
|
+
apps to a new pnpm major merely because a newer release exists.
|
|
7
|
+
- Before pnpm 11, move pnpm settings from `package.json#pnpm` into
|
|
8
|
+
`pnpm-workspace.yaml`; pnpm 11 no longer reads that package.json object.
|
|
9
|
+
- Keep only registry and authentication settings in `.npmrc`. Move pnpm options
|
|
10
|
+
such as `store-dir` and `strictDepBuilds` into `pnpm-workspace.yaml`.
|
|
11
|
+
- Replace `onlyBuiltDependencies`, `ignoredBuiltDependencies`, and related old
|
|
12
|
+
dependency-build settings with an explicit `allowBuilds` map before pnpm 11.
|
|
13
|
+
- For GitHub Actions on pnpm 11+, use the maintained `pnpm/setup` action rather
|
|
14
|
+
than `pnpm/action-setup`.
|
|
15
|
+
- Run `loom check` before changing the pin. Compatibility findings are warnings
|
|
16
|
+
while the app remains on pnpm 10 and issues once it declares pnpm 11 or newer.
|
|
17
|
+
- Keep `@gadicc/loom` in `minimumReleaseAgeExclude`. It is a first-party package
|
|
18
|
+
that consumers routinely need immediately; `loom init` adds the exception
|
|
19
|
+
without weakening pnpm's release-age policy for third-party dependencies.
|
|
20
|
+
- Canary a new pnpm major in one clean Vercel consumer before rolling it across
|
|
21
|
+
the fleet. Verify a frozen install, local tests/build, preview deployment, and
|
|
22
|
+
the production release workflow. Defer consumers with overlapping local config
|
|
23
|
+
edits or unrelated commits that would be pushed by the rollout.
|
|
24
|
+
- pnpm 12 is a separate migration even when it can consume the same lockfile.
|
|
25
|
+
Evaluate it independently after its new Rust CLI and stricter workspace
|
|
26
|
+
validation have matured in the actual deployment platform.
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# Loom local package development
|
|
2
|
+
|
|
3
|
+
## Local development
|
|
4
|
+
|
|
5
|
+
- For a Loom DB consumer, prefer an existing machine PostgreSQL service with one
|
|
6
|
+
restricted database and role per project. Use `loom db local setup|check` and
|
|
7
|
+
the `loom-db` skill for the local database boundary. Containers remain useful
|
|
8
|
+
for incompatible server versions or extensions.
|
|
9
|
+
|
|
10
|
+
- For local unpublished Loom package development, use `loom dev local <path>`.
|
|
11
|
+
Loom uses a managed `file:` override for pnpm projects and a local `links`
|
|
12
|
+
entry in the authoritative Deno config for Deno projects.
|
|
13
|
+
- The pnpm override goes where the project's pnpm version applies it
|
|
14
|
+
(`packageManager`, else the `pnpm --version` of the pnpm Loom runs; not
|
|
15
|
+
`npm_config_user_agent`, which names the pnpm running the current script), as
|
|
16
|
+
verified with real pnpm 9.7.0 to 11.25.0:
|
|
17
|
+
- pnpm before 10.5.1 reads overrides only from package.json `resolutions` and
|
|
18
|
+
`pnpm.overrides`; Loom adds its entry there, creating `resolutions` when
|
|
19
|
+
neither exists. pnpm 9 also needs `packages:` in any `pnpm-workspace.yaml`.
|
|
20
|
+
- pnpm 10.5.1 to 10.x reads `pnpm-workspace.yaml` `overrides` only while both
|
|
21
|
+
package.json maps are empty; otherwise the package.json maps replace (not
|
|
22
|
+
merge with) the workspace map, so Loom uses the package.json map there.
|
|
23
|
+
- pnpm 11 reads only `pnpm-workspace.yaml` overrides.
|
|
24
|
+
- An unknown version is treated as pnpm 10.5.1 or newer; pnpm 8 and older are
|
|
25
|
+
untested.
|
|
26
|
+
- An ignored override shows up as pnpm reporting "Lockfile is up to date" while
|
|
27
|
+
the app keeps the published package; `pnpm config get overrides` does not
|
|
28
|
+
reveal this. `loom dev sync` moves an override that is in the wrong place, and
|
|
29
|
+
fails with the detected pnpm version if pnpm still does not apply it.
|
|
30
|
+
- The managed flow keeps the committed dependency/import on a published Loom
|
|
31
|
+
version. `loom dev sync` refreshes with a plain `pnpm install` (or
|
|
32
|
+
`deno install`, according to `project.tooling`), which keeps every other
|
|
33
|
+
locked version. Do not link or refresh Loom with `pnpm update`; it re-resolves
|
|
34
|
+
Loom's dependency subtree and can leave duplicate peer variants of packages
|
|
35
|
+
such as `@better-auth/core`. To move to another published Loom version, set
|
|
36
|
+
the exact version in package.json and run `pnpm install`, which keeps other
|
|
37
|
+
locked versions. `pnpm add --save-exact @gadicc/loom@<version>` (with `-w` at
|
|
38
|
+
a workspace root with packages) gives the same lockfile but may re-sort
|
|
39
|
+
package.json; it is only needed to replace a local resolution an older
|
|
40
|
+
`pnpm update --no-save` link left under an unchanged pin. The sync fails if
|
|
41
|
+
pnpm-lock.yaml does not record the override afterwards and warns when the
|
|
42
|
+
install added duplicate peer variants.
|
|
43
|
+
- `loom dev sync` decides freshness by content: it rebuilds when the Loom
|
|
44
|
+
sources differ from the fingerprint stamped into the `npm/` build and
|
|
45
|
+
reinstalls when the app's installed copy differs from `npm/` by file list or
|
|
46
|
+
content, including after a `deno task build` run outside the sync. Use
|
|
47
|
+
`--force` only to rebuild and reinstall unconditionally.
|
|
48
|
+
- Concurrent Loom commands take turns through `.loom/dev-sync.lock`, and
|
|
49
|
+
`loom dev local` and `loom dev published` take the same lock: a second command
|
|
50
|
+
waits for the running sync, then re-reads the link and re-checks freshness
|
|
51
|
+
instead of rebuilding again (or re-adding an override removed meanwhile). If
|
|
52
|
+
the Loom package it had loaded was replaced while it waited, it treats that as
|
|
53
|
+
a refresh: `loom env` continues, other commands exit 75. The holder refreshes
|
|
54
|
+
the lock every 5 seconds and removes it on Ctrl-C, SIGTERM, or SIGHUP. A lock
|
|
55
|
+
nobody refreshed for a minute (a crash, `kill -9`, another machine) is broken,
|
|
56
|
+
after about 12 seconds when its process is gone on this host or it was already
|
|
57
|
+
a minute old, and after five minutes when its process still exists on this
|
|
58
|
+
host (a paused command); one waiter breaks it at a time under a short
|
|
59
|
+
`.loom/dev-sync.lock.break` lock. A holder that lost its lock stops before its
|
|
60
|
+
next build, install, or state write. After 10 minutes of waiting the command
|
|
61
|
+
fails and names the lock holder.
|
|
62
|
+
- Other Loom commands run the sync automatically while linked. When it refreshes
|
|
63
|
+
the package, `loom env -- <command>` (and so scripts such as `pnpm test` that
|
|
64
|
+
wrap it) still runs its command, with the sync's output on stderr; other
|
|
65
|
+
commands exit with status 75 and must be rerun so they do not run stale Loom
|
|
66
|
+
code.
|
|
67
|
+
- This still avoids the peer-resolution problems we observed with `pnpm link`
|
|
68
|
+
when Loom is consumed by React apps.
|
|
69
|
+
- Treat this as a workaround for current pnpm behavior, not a permanent
|
|
70
|
+
preference. If pnpm's local-link behavior changes enough to preserve peer
|
|
71
|
+
resolution cleanly for Loom, this workaround can be revisited or removed.
|
|
72
|
+
- Before committing app changes or preparing a published build, switch back with
|
|
73
|
+
`loom dev published`, then run `pnpm install` or `deno install`. A lockfile
|
|
74
|
+
linked by an older Loom through `pnpm update --no-save` keeps its local
|
|
75
|
+
resolution through a plain install; restore that lockfile from git when it has
|
|
76
|
+
no other intended changes, as `loom dev published` explains.
|
|
77
|
+
- Each Loom build records its provenance in `npm/.loom-build.json` (kept out of
|
|
78
|
+
the packed package): the git commit it was built from, whether that checkout
|
|
79
|
+
was dirty, and a digest of the packed output. Dirty means tracked changes,
|
|
80
|
+
untracked files git does not ignore, files marked skip-worktree or
|
|
81
|
+
assume-unchanged, or a package-relevant file written while the build ran. The
|
|
82
|
+
last is judged by content, git state and modification times, so an edit
|
|
83
|
+
reverted before the build finished still counts; with whole-second timestamps
|
|
84
|
+
(FAT, HFS+), so does a file written a moment before the build started.
|
|
85
|
+
`loom dev sync` also records its sync in gitignored `.loom/dev-state.json` for
|
|
86
|
+
`loom status` and `loom check`; that record never gates a release. It stays
|
|
87
|
+
while local Loom may still be in use: any local Loom override, link or catalog
|
|
88
|
+
entry (any dangling Deno link counts as possibly Loom's), a local
|
|
89
|
+
`pnpm-lock.yaml` resolution or a Loom link in `deno.lock`, or an installed
|
|
90
|
+
copy that is not provably the published package. pnpm proves that through its
|
|
91
|
+
registry store entry; Deno through a `deno.lock` that records no Loom link and
|
|
92
|
+
resolves the pinned `npm:@gadicc/loom` version from the registry.
|
|
93
|
+
`loom dev published` deletes the record once none is left, which for pnpm
|
|
94
|
+
usually means rerunning it after the `pnpm install` it asks for. Otherwise
|
|
95
|
+
`loom check` treats the record as stale: it notes that it can be deleted and,
|
|
96
|
+
if the recorded checkout still exists, advises a newer pin when a newer
|
|
97
|
+
release covers the synced commit. What the record says fails a production
|
|
98
|
+
check only while a link, override or local lockfile points at local Loom; an
|
|
99
|
+
unproven installed copy alone, or a checkout that no longer exists, only
|
|
100
|
+
warns.
|
|
101
|
+
- `loom dev published` proves what is actually installed, from that build
|
|
102
|
+
provenance, before it switches back:
|
|
103
|
+
- It collects every local Loom target: the managed pnpm override, any
|
|
104
|
+
hand-written `file:`/`link:` Loom entry in the `pnpm-workspace.yaml`
|
|
105
|
+
`overrides:` map, and any `file:`/`link:` resolution in `pnpm-lock.yaml`, or
|
|
106
|
+
every Deno link to Loom. It refuses when they name more than one package.
|
|
107
|
+
- The target's build must record a clean commit, and its npm/ output must
|
|
108
|
+
still match the recorded digest. An older build, one made without git, one
|
|
109
|
+
made from uncommitted changes, or output edited after the build is refused;
|
|
110
|
+
run `loom dev sync`, or commit the Loom changes and run
|
|
111
|
+
`loom dev sync --force`. A checkout whose own build script predates
|
|
112
|
+
provenance (an older tag, say, while bisecting) is rebuilt once per source
|
|
113
|
+
change and then always refused; relink to a newer checkout to switch back
|
|
114
|
+
with proof.
|
|
115
|
+
- The installed copy must match that build (pnpm `node_modules`, and a Deno
|
|
116
|
+
`node_modules` copy unless `nodeModulesDir` is `"none"`), and for pnpm
|
|
117
|
+
`pnpm-lock.yaml` must resolve Loom to it. Otherwise run `loom dev sync`.
|
|
118
|
+
- The build's commit must be reachable from `origin/main` and either included
|
|
119
|
+
in a semver release tag or package-equivalent to the latest semver release
|
|
120
|
+
because only non-package files changed after that tag. The app then switches
|
|
121
|
+
to the exact published Loom version that covers it, unless it already pins a
|
|
122
|
+
newer exact version: Loom never moves a pin back, because a checkout without
|
|
123
|
+
the newest tags names an older covering release.
|
|
124
|
+
- The checkout's current commit and working tree do not matter: later work in
|
|
125
|
+
it neither blocks nor passes a build that is already installed.
|
|
126
|
+
- A pnpm link that was never installed needs no proof: when pnpm-lock.yaml and
|
|
127
|
+
pnpm's record of node_modules still hold the published Loom and
|
|
128
|
+
`node_modules/@gadicc/loom` links pnpm's store entry for that version, the
|
|
129
|
+
overrides are removed and the pin stays. Anything less certain gets the full
|
|
130
|
+
proof: an interrupted install, or a layout without a `node_modules/.pnpm`
|
|
131
|
+
store entry to check (`node-linker=hoisted`, `enableGlobalVirtualStore`, a
|
|
132
|
+
custom `virtual-store-dir`). Deno links are always proved: Deno reads the
|
|
133
|
+
linked directory, or copies it into node_modules on its next install or run,
|
|
134
|
+
so a Deno link has no lasting never-installed state.
|
|
135
|
+
- Apps may pin Loom through a pnpm catalog (`"@gadicc/loom": "catalog:"` or
|
|
136
|
+
`"catalog:<name>"` in package.json, with the version in `pnpm-workspace.yaml`
|
|
137
|
+
`catalog:` or `catalogs:`, as block maps or single-line flow maps). Loom reads
|
|
138
|
+
the version from the catalog, and `loom dev published` pins the covering
|
|
139
|
+
version in that catalog entry while package.json keeps its `catalog:`
|
|
140
|
+
reference. Do not use `pnpm add` to change such a pin; it replaces the
|
|
141
|
+
reference. Edit the catalog and run `pnpm install`.
|
|
142
|
+
- `loom dev published` also removes Deno links and package.json overrides and
|
|
143
|
+
notices stale `pnpm-lock.yaml` resolutions that still point at local Loom
|
|
144
|
+
after the override has been removed.
|
|
145
|
+
- `loom check` should warn during normal development if a Deno link or pnpm
|
|
146
|
+
lockfile still resolves Loom locally, if the synced Loom commit is
|
|
147
|
+
unpublished, or if it is covered by a newer exact version than the app
|
|
148
|
+
currently pins.
|
|
149
|
+
- If an older local-dev block has no recorded commit, switch back carefully and
|
|
150
|
+
run `loom dev sync` first whenever the app may depend on unpublished Loom
|
|
151
|
+
changes.
|
|
152
|
+
- Before app release or CD builds, run `loom check --production` so local Loom
|
|
153
|
+
overrides, local lockfile resolutions, and unresolved synced Loom commits fail
|
|
154
|
+
the build instead of remaining advisory warnings.
|
|
155
|
+
- Publishing Loom makes a version available, but it should not move unrelated
|
|
156
|
+
consumer apps; each app upgrades only through its own package and lockfile
|
|
157
|
+
changes.
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Loom release safety
|
|
2
|
+
|
|
3
|
+
Read the active manifest and app-owned release workflow before deployment or
|
|
4
|
+
credential commands. Preparation alone does not authorize migrations, uploads,
|
|
5
|
+
promotion, pushes, or credential changes. Reuse the user's existing
|
|
6
|
+
authorization.
|
|
7
|
+
|
|
8
|
+
The global `deploy-to-vercel` git-push path and `vercel-cli-with-tokens`
|
|
9
|
+
`printenv`/`.env` grep examples do not override Loom release mode or secret
|
|
10
|
+
handling. Never print secrets, stage unrelated files with `git add .`,
|
|
11
|
+
substitute a no-auth deployment after authentication failure, or skip the
|
|
12
|
+
required smoke check. Preserve the configured project-token or team-token mode.
|
|
13
|
+
|
|
14
|
+
- After `vercel pull`, or after project-scoped preparation with
|
|
15
|
+
`loom db release prepare-vercel-project production`, treat
|
|
16
|
+
`.vercel/.env.<target>.local` as a plaintext secret file. Mask usable pulled
|
|
17
|
+
values before build output. Sensitive values are not readable there or through
|
|
18
|
+
`vercel env run`; CLI versions may write either an empty value or a redaction
|
|
19
|
+
sentinel.
|
|
20
|
+
- For external prebuilds, query Vercel env metadata, preserve usable pulled
|
|
21
|
+
values, add unique build-only placeholders only for confirmed Sensitive
|
|
22
|
+
entries, and reject any marker across the complete deployable artifact graph,
|
|
23
|
+
including contained symlinks and function `filePathMap` content. Prefer
|
|
24
|
+
`vercel build --standalone` for local prebuilt deployments. Preserve an
|
|
25
|
+
untouched pull snapshot for migrations; once database variables are Sensitive,
|
|
26
|
+
overlay a separately governed GitHub `MIGRATION_DATABASE_URL_UNPOOLED` secret
|
|
27
|
+
only for migration validation and the migration command. Readable pulled URLs
|
|
28
|
+
and the legacy `DATABASE_URL_UNPOOLED` secret remain supported during gradual
|
|
29
|
+
adoption.
|
|
30
|
+
- Validate the migration boundary with
|
|
31
|
+
`loom db migrations verify-env
|
|
32
|
+
--connect
|
|
33
|
+
--env-file "$RUNNER_TEMP/vercel-production.env"`
|
|
34
|
+
so the optional protected migration secret overlays the untouched readable
|
|
35
|
+
pull snapshot instead of replacing that gradual-adoption fallback. The live
|
|
36
|
+
probe must authenticate with the selected URL and confirm migration schema
|
|
37
|
+
access before a present override supersedes the fallback.
|
|
38
|
+
|
|
39
|
+
## Database release workflow
|
|
40
|
+
|
|
41
|
+
- For Vercel production releases, confirm `vercel.json` disables automatic
|
|
42
|
+
deployments for the configured production branch and GitHub Actions builds
|
|
43
|
+
with Vercel production settings. The branch defaults to `main`; apps using
|
|
44
|
+
another branch set `features.db.config.release.productionBranch` in
|
|
45
|
+
`loom.json` and match the Vercel project production branch, workflow trigger
|
|
46
|
+
and deployment fence. Workflows and `vercel.json` remain app-owned. The flow
|
|
47
|
+
uploads a staged production deployment with `--prebuilt --prod --skip-domain`,
|
|
48
|
+
runs `db:migrate`, and then promotes the staged deployment. Before adding
|
|
49
|
+
build-only placeholders, preserve an untouched copy of the pulled env file for
|
|
50
|
+
migrations. Before Vercel database variables become Sensitive, provide a
|
|
51
|
+
separately governed direct migration URL as the GitHub Environment secret
|
|
52
|
+
`MIGRATION_DATABASE_URL_UNPOOLED` and expose it only to validation and
|
|
53
|
+
migration steps. `vercel pull` and `vercel env run` cannot recover Sensitive
|
|
54
|
+
values. The pulled URL and legacy `DATABASE_URL_UNPOOLED` secret remain
|
|
55
|
+
supported during gradual adoption. Team-token workflows pass
|
|
56
|
+
`--scope "$VERCEL_ORG_ID"` to Vercel CLI release commands. Project-token
|
|
57
|
+
workflows instead run `loom db release prepare-vercel-project production` with
|
|
58
|
+
explicit private env, metadata, and project-link outputs, then build without
|
|
59
|
+
the token. Stage the materialized artifact with both `VERCEL_ORG_ID` and
|
|
60
|
+
`VERCEL_PROJECT_ID` removed from that process and promote it with
|
|
61
|
+
`loom db release promote-vercel`; do not mix these two release modes.
|
|
62
|
+
- Query Vercel Production variable metadata before an external build. Preserve
|
|
63
|
+
usable pulled values, insert unique placeholders only for confirmed unreadable
|
|
64
|
+
Sensitive values, and scan `.vercel/output` for those markers before uploading
|
|
65
|
+
the prebuilt artifact. Prefer `loom db release prepare-build-env` and
|
|
66
|
+
`loom db release verify-build-env`; keep only the declarative requirements
|
|
67
|
+
policy app-local. Prefer `vercel build --standalone` for local prebuilt
|
|
68
|
+
deployments so FileFsRef content is materialized inside the output. Loom also
|
|
69
|
+
scans contained symlinks and function `filePathMap` targets; pass the Vercel
|
|
70
|
+
deployment root as the optional third `verify-build-env` argument when a
|
|
71
|
+
monorepo's mappings are relative to a root above the app.
|
|
72
|
+
- Use
|
|
73
|
+
`loom db migrations verify-env --connect --env-file
|
|
74
|
+
"$RUNNER_TEMP/vercel-production.env"`
|
|
75
|
+
before a release migration. It validates the preserved pull snapshot plus any
|
|
76
|
+
process-level migration-secret overlay, including URL precedence, database
|
|
77
|
+
role, and direct-vs-pooled endpoint, then authenticates with the selected URL
|
|
78
|
+
and checks the target database and schema privileges without printing
|
|
79
|
+
credentials. A present but invalid override must fail instead of silently
|
|
80
|
+
falling back. `--connect` loads the app's `postgres` package, an optional Loom
|
|
81
|
+
peer that `loom add db` installs; without it the command says so instead of
|
|
82
|
+
reporting a connection failure.
|
|
83
|
+
- Once a dedicated direct URL has been provisioned, load it as
|
|
84
|
+
`MIGRATION_DATABASE_URL_UNPOOLED` in the local process and run
|
|
85
|
+
`loom db migrations setup-github`. Loom sends the value to GitHub over stdin,
|
|
86
|
+
records `LOOM_MIGRATION_DATABASE_ROLE`, and does not change Vercel variables.
|
|
87
|
+
- Use `loom check --network` after wiring a production release workflow so Loom
|
|
88
|
+
can verify the linked Vercel project plus GitHub's `VERCEL_TOKEN`,
|
|
89
|
+
`VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` release configuration.
|
|
90
|
+
- On fresh external CI runners, run `loom init` after dependency installation
|
|
91
|
+
and before `loom check --production` so the intentionally gitignored managed
|
|
92
|
+
skill links are hydrated. Initialization preserves an equivalent formatted
|
|
93
|
+
`loom.json` instead of creating formatting-only drift.
|
|
94
|
+
- Use `loom db release setup-github` to create/update that GitHub release
|
|
95
|
+
configuration from the linked Vercel project. A normal rerun preserves an
|
|
96
|
+
existing write-only GitHub `VERCEL_TOKEN` and refuses to associate it with a
|
|
97
|
+
different linked org or project. New credentials default to project scope and
|
|
98
|
+
expire after 90 days; use `--rotate-token` for explicit replacement,
|
|
99
|
+
`--token-expiry-days` for another bounded lifetime, or `--token-scope team`
|
|
100
|
+
only as an explicit compatibility option. Keep the previous token active until
|
|
101
|
+
a full release succeeds with its replacement. If the current Vercel login
|
|
102
|
+
cannot mint tokens, create a bounded project token in Vercel and install it
|
|
103
|
+
through GitHub's hidden environment-secret input rather than broadening its
|
|
104
|
+
scope.
|
|
105
|
+
- Smoke check the staged deployment URL after promotion with normal `curl`.
|
|
106
|
+
Existing workflows may continue to create a short-lived Vercel Protection
|
|
107
|
+
Bypass for Automation secret through the Vercel API, send it as the
|
|
108
|
+
`x-vercel-protection-bypass` header, and revoke it in the same step. Apps may
|
|
109
|
+
instead adopt the reviewed GitHub OIDC Trusted Sources flow with
|
|
110
|
+
`loom db release trust-plan`, `trust-apply`, and `trust-check`; see
|
|
111
|
+
[trusted-source setup](release-trusted-sources.md). Keep either change
|
|
112
|
+
app-owned and deliberate. Avoid the beta `vercel curl` command in CI.
|
|
113
|
+
- Production migrations must remain backward-compatible with the currently live
|
|
114
|
+
app because old code continues serving traffic until the staged deployment is
|
|
115
|
+
promoted. Use expand/contract migrations for destructive schema changes.
|
|
116
|
+
- Keep `VERCEL_TOKEN` in a protected GitHub Environment, limit that environment
|
|
117
|
+
to release branches, and expose the token only on steps that call Vercel. Pin
|
|
118
|
+
third-party Actions to full commit SHAs and let Dependabot maintain them.
|