@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.
Files changed (103) hide show
  1. package/README.md +56 -0
  2. package/THIRD_PARTY_NOTICES.md +12 -9
  3. package/esm/src/cli/externalSkills.d.ts.map +1 -1
  4. package/esm/src/cli/externalSkills.js +25 -20
  5. package/esm/src/cli/mod.d.ts +72 -1
  6. package/esm/src/cli/mod.d.ts.map +1 -1
  7. package/esm/src/cli/mod.js +771 -36
  8. package/esm/src/cli/projectSkills.d.ts +10 -3
  9. package/esm/src/cli/projectSkills.d.ts.map +1 -1
  10. package/esm/src/cli/projectSkills.js +173 -49
  11. package/esm/src/cli/vercelBuildEnv.d.ts +28 -0
  12. package/esm/src/cli/vercelBuildEnv.d.ts.map +1 -1
  13. package/esm/src/cli/vercelBuildEnv.js +120 -30
  14. package/esm/src/next/secrets/mod.d.ts +108 -0
  15. package/esm/src/next/secrets/mod.d.ts.map +1 -0
  16. package/esm/src/next/secrets/mod.js +176 -0
  17. package/esm/src/secrets/encoding.d.ts +32 -0
  18. package/esm/src/secrets/encoding.d.ts.map +1 -0
  19. package/esm/src/secrets/encoding.js +87 -0
  20. package/esm/src/secrets/errors.d.ts +45 -0
  21. package/esm/src/secrets/errors.d.ts.map +1 -0
  22. package/esm/src/secrets/errors.js +39 -0
  23. package/esm/src/secrets/fingerprint.d.ts +43 -0
  24. package/esm/src/secrets/fingerprint.d.ts.map +1 -0
  25. package/esm/src/secrets/fingerprint.js +87 -0
  26. package/esm/src/secrets/frame.d.ts +34 -0
  27. package/esm/src/secrets/frame.d.ts.map +1 -0
  28. package/esm/src/secrets/frame.js +86 -0
  29. package/esm/src/secrets/keyring.d.ts +62 -0
  30. package/esm/src/secrets/keyring.d.ts.map +1 -0
  31. package/esm/src/secrets/keyring.js +160 -0
  32. package/esm/src/secrets/legacy.d.ts +60 -0
  33. package/esm/src/secrets/legacy.d.ts.map +1 -0
  34. package/esm/src/secrets/legacy.js +147 -0
  35. package/esm/src/secrets/maintenance.d.ts +173 -0
  36. package/esm/src/secrets/maintenance.d.ts.map +1 -0
  37. package/esm/src/secrets/maintenance.js +315 -0
  38. package/esm/src/secrets/mod.d.ts +6 -0
  39. package/esm/src/secrets/mod.d.ts.map +1 -0
  40. package/esm/src/secrets/mod.js +5 -0
  41. package/esm/src/secrets/secrets.d.ts +192 -0
  42. package/esm/src/secrets/secrets.d.ts.map +1 -0
  43. package/esm/src/secrets/secrets.js +528 -0
  44. package/package.json +50 -2
  45. package/script/src/cli/externalSkills.d.ts.map +1 -1
  46. package/script/src/cli/externalSkills.js +25 -20
  47. package/script/src/cli/mod.d.ts +72 -1
  48. package/script/src/cli/mod.d.ts.map +1 -1
  49. package/script/src/cli/mod.js +772 -33
  50. package/script/src/cli/projectSkills.d.ts +10 -3
  51. package/script/src/cli/projectSkills.d.ts.map +1 -1
  52. package/script/src/cli/projectSkills.js +173 -49
  53. package/script/src/cli/vercelBuildEnv.d.ts +28 -0
  54. package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
  55. package/script/src/cli/vercelBuildEnv.js +121 -30
  56. package/script/src/next/secrets/mod.d.ts +108 -0
  57. package/script/src/next/secrets/mod.d.ts.map +1 -0
  58. package/script/src/next/secrets/mod.js +218 -0
  59. package/script/src/secrets/encoding.d.ts +32 -0
  60. package/script/src/secrets/encoding.d.ts.map +1 -0
  61. package/script/src/secrets/encoding.js +95 -0
  62. package/script/src/secrets/errors.d.ts +45 -0
  63. package/script/src/secrets/errors.d.ts.map +1 -0
  64. package/script/src/secrets/errors.js +45 -0
  65. package/script/src/secrets/fingerprint.d.ts +43 -0
  66. package/script/src/secrets/fingerprint.d.ts.map +1 -0
  67. package/script/src/secrets/fingerprint.js +92 -0
  68. package/script/src/secrets/frame.d.ts +34 -0
  69. package/script/src/secrets/frame.d.ts.map +1 -0
  70. package/script/src/secrets/frame.js +91 -0
  71. package/script/src/secrets/keyring.d.ts +62 -0
  72. package/script/src/secrets/keyring.d.ts.map +1 -0
  73. package/script/src/secrets/keyring.js +202 -0
  74. package/script/src/secrets/legacy.d.ts +60 -0
  75. package/script/src/secrets/legacy.d.ts.map +1 -0
  76. package/script/src/secrets/legacy.js +186 -0
  77. package/script/src/secrets/maintenance.d.ts +173 -0
  78. package/script/src/secrets/maintenance.d.ts.map +1 -0
  79. package/script/src/secrets/maintenance.js +323 -0
  80. package/script/src/secrets/mod.d.ts +6 -0
  81. package/script/src/secrets/mod.d.ts.map +1 -0
  82. package/script/src/secrets/mod.js +24 -0
  83. package/script/src/secrets/secrets.d.ts +192 -0
  84. package/script/src/secrets/secrets.d.ts.map +1 -0
  85. package/script/src/secrets/secrets.js +532 -0
  86. package/skills/loom/SKILL.md +74 -222
  87. package/skills/loom/references/dependency-upgrades.md +26 -0
  88. package/skills/loom/references/local-development.md +157 -0
  89. package/skills/loom/references/release-safety.md +118 -0
  90. package/skills/loom/references/release-trusted-sources.md +55 -0
  91. package/skills/loom/references/tools-and-skills.md +83 -0
  92. package/skills/loom-api-keys/SKILL.md +1 -1
  93. package/skills/loom-auth/SKILL.md +7 -60
  94. package/skills/loom-auth/references/secrets-and-rotation.md +61 -0
  95. package/skills/loom-db/SKILL.md +4 -79
  96. package/skills/loom-files/SKILL.md +4 -2
  97. package/skills/loom-files/references/provider-configuration.md +142 -0
  98. package/skills/loom-jobs/SKILL.md +9 -8
  99. package/skills/loom-lingui/SKILL.md +5 -3
  100. package/skills/loom-secrets/SKILL.md +252 -0
  101. package/skills/loom-torvalds-review/SKILL.md +9 -6
  102. package/skills/loom-torvalds-review/references/context-profiles.md +2 -1
  103. package/skills/upgrade-deps/SKILL.md +15 -7
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: loom
3
- description: Use when working in an app that consumes @gadicc/loom or when the task mentions loom.json, loom init/check/add, shared loom feature adoption, thin wrapper files, or deciding whether behavior belongs in the shared loom package versus the local app.
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
- - After `vercel pull`, or after project-scoped preparation with
85
- `loom db release prepare-vercel-project production`, treat
86
- `.vercel/.env.<target>.local` as a plaintext secret file. Mask usable pulled
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
- - Run `loom check` when validating a consuming app.
164
- - Run `loom add` to list CLI-activatable shared features and `loom status` to
165
- inspect which features and project skills are currently wired in.
166
- - Use `loom skills check` to validate locked external skills and package skill
167
- activations, and `loom skills update` to adopt reviewed catalog revisions.
168
- - Third-party skills must remain consumer-installed; never copy their content
169
- into the Loom package. Missing upstream licenses require explicit consumer
170
- acknowledgement.
171
- - In the Loom package source checkout, treat `"use client"` and `"use server"`
172
- as emitted-package contracts. Run `deno task build` after changes that may
173
- affect `dnt`: syntax anywhere in an entrypoint graph can cause a polyfill
174
- import to be emitted before a framework directive. Prefer a portable
175
- equivalent or adjust the build; never edit generated `npm/` output by hand.
176
- The package build rejects generated ESM with code before either directive.
177
- - After loom-related changes, also run the repo's normal verification commands
178
- before handoff.
179
- - If the task touches Next.js routes, confirm the wrapper paths still point at
180
- real files and that App Router conventions are still respected.
181
- - If Loom-managed Next.js routes or wrappers were changed and runtime tooling is
182
- available, prefer runtime verification in addition to static checks.
183
- - If the task affects an active feature, prefer feature-specific loom skills
184
- such as `loom-jobs` or `loom-api-keys`.
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
- - For a Loom DB consumer, prefer an existing machine PostgreSQL service with one
189
- restricted database and role per project. Use `loom db local setup|check` and
190
- the `loom-db` skill for the local database boundary. Containers remain useful
191
- for incompatible server versions or extensions.
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
- - Treat the exact `packageManager` pin as the consumer contract. Do not move all
359
- apps to a new pnpm major merely because a newer release exists.
360
- - Before pnpm 11, move pnpm settings from `package.json#pnpm` into
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.