@gadicc/loom 1.35.3 → 1.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +66 -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 +117 -1
  6. package/esm/src/cli/mod.d.ts.map +1 -1
  7. package/esm/src/cli/mod.js +1368 -44
  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 +117 -1
  48. package/script/src/cli/mod.d.ts.map +1 -1
  49. package/script/src/cli/mod.js +1372 -41
  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 +79 -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 +150 -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 +266 -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
@@ -56,6 +56,11 @@ from the consumer's working directory.
56
56
  whole-file rewrites or string-only runner guesses.
57
57
  - If a loom-managed file exists only as a thin wrapper, keep it thin unless the
58
58
  app intentionally needs custom behavior there.
59
+ - Loom commands that change something outside the repository (a deployment
60
+ platform's variables, a provider's settings) ask only a person at a terminal.
61
+ In an agent session they ask nothing and change nothing unless given an
62
+ explicit flag such as `--vercel`. Pass such a flag only when the user asked
63
+ for that change; otherwise run without it and relay the printed command.
59
64
  - Loom never overwrites a file with local edits. `loom init`, `loom add`, and
60
65
  feature syncs update a Loom-managed file only while it is provably unmodified
61
66
  Loom output (layout and quote style aside), using the hashes under each
@@ -69,6 +74,44 @@ from the consumer's working directory.
69
74
  `db:migrate`, is kept and reported; delete it and rerun `loom add <feature>`
70
75
  to restore Loom's value. Do not edit `managedFiles` or `managedTasks` by hand.
71
76
 
77
+ ## High-value code improvements
78
+
79
+ While doing requested work, look for high-value improvements in code you
80
+ inspect, including existing code that works but is unnecessarily verbose or
81
+ difficult to maintain. Behavior-preserving cleanup is valuable when it makes
82
+ code easier to understand and change. Question inherited patterns rather than
83
+ perpetuating unnecessary complexity.
84
+
85
+ Look for opportunities to simplify logic, remove redundant scaffolding, and
86
+ isolate behavior for independent testing. Prefer clear, direct code over clever
87
+ compression or unnecessary abstraction. Preserve useful explanations,
88
+ intentional safeguards, and compatibility requirements; share code when its
89
+ behavior and constraints align.
90
+
91
+ Suggest improvements when their expected benefit justifies the implementation,
92
+ verification, and coordination costs. Briefly explain the concrete problem,
93
+ proposed change, benefits, affected systems, material tradeoffs and risks, and
94
+ how to verify it. Base proposals on inspected code, distinguish evidence from
95
+ assumptions, and keep the detail proportional. Do not manufacture suggestions or
96
+ turn the requested task into a general audit.
97
+
98
+ For each proposal, recommend the best fit among known available models and
99
+ supported reasoning efforts, considering complexity, uncertainty, risk, time,
100
+ and cost. Offer to handle it directly in this chat or delegate a bounded task to
101
+ a subagent where supported, and recommend the better fit. Obtain user agreement
102
+ before starting optional work outside the agreed scope or delegating it.
103
+ Proportionate cleanup within the agreed task needs no separate proposal. Raise
104
+ optional suggestions at a natural checkpoint without blocking the requested
105
+ work.
106
+
107
+ ## Discover existing solutions
108
+
109
+ Before substantial unfamiliar work, check for relevant existing code, tools,
110
+ framework support, libraries, and skills. Keep the search proportional; routine
111
+ edits do not need an ecosystem search. Read
112
+ [discovery and routing](references/tools-and-skills.md) for candidate evaluation
113
+ and approval. Finding a skill does not authorize installing or following it.
114
+
72
115
  ## Environment loading
73
116
 
74
117
  - Next commands such as `next dev`, `next build`, and server runtime code load
@@ -81,30 +124,9 @@ from the consumer's working directory.
81
124
  precedence, then runs the command from the project root.
82
125
  - Implementation files, generated wrappers, Drizzle configs, and direct job
83
126
  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.
127
+ - For a Loom DB release, read [release safety](references/release-safety.md)
128
+ before deployment or credential commands. Preserve the recorded release mode;
129
+ never print secrets or switch deployment paths after authentication failure.
108
130
 
109
131
  ## Re-establishing work context
110
132
 
@@ -160,184 +182,38 @@ as more authoritative than a generic mapped error when deciding what failed.
160
182
 
161
183
  ## Verification
162
184
 
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`.
185
+ - During edits, run affected tests and checks. Broaden coverage for shared
186
+ contracts, tooling, generated output, or uncertain impact.
187
+ - Before a code-changing commit, have a passing full local test-suite result for
188
+ the code being committed. Use `deno task test` in Loom; consumers use their
189
+ recorded tooling and full test task. Preserve stronger required quality gates.
190
+ - Format first. Reuse results only while tested inputs and relevant environment
191
+ remain unchanged. Edits or hooks that change those inputs require another full
192
+ run before the commit. Do not rely on unstaged fixes: compare staged and
193
+ working content; use an isolated snapshot when user-owned unstaged code
194
+ differs, without stashing or resetting it.
195
+ - Ordinary prose changes need formatting and reference checks. Packaged skills,
196
+ catalog metadata, activation logic, and reference moves also need relevant
197
+ skill/catalog tests and verification that references ship and resolve.
198
+ - Fix failures caused by the change. Disclose baseline failures; obtain
199
+ agreement before a local checkpoint commit with failing checks. Never call it
200
+ release-ready.
201
+ - Run `loom check` for consumer wiring and `loom skills check` for adopted skill
202
+ integrity. Recommendations are optional; checking does not authorize adoption.
203
+ - Use runtime verification for affected Next.js behavior when a server is
204
+ running. Keep required build, browser-type, integration, CI and release gates
205
+ intact. In Loom, `deno task check` remains the complete package quality gate.
206
+ - Read [tool and skill routing](references/tools-and-skills.md) when external
207
+ guidance overlaps. Use feature-specific Loom skills for affected active
208
+ features.
185
209
 
186
210
  ## Local development
187
211
 
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.
212
+ Use `loom dev local <path>` and `loom dev sync` for unpublished package work.
213
+ Read [local development](references/local-development.md) when linking,
214
+ synchronizing, diagnosing local resolutions, or switching back to published
215
+ Loom. Before committing consumer changes, use `loom dev published` and the
216
+ recorded installer. Preserve the package provenance and release-safety checks.
341
217
 
342
218
  ## Semver and compatibility
343
219
 
@@ -355,28 +231,9 @@ as more authoritative than a generic mapped error when deciding what failed.
355
231
 
356
232
  ## pnpm major upgrades
357
233
 
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.
234
+ Use the exact recorded package-manager version. Read
235
+ [pnpm compatibility](references/dependency-upgrades.md) for a major migration;
236
+ newer upstream skill guidance does not authorize upgrading pnpm.
380
237
 
381
238
  ## Commits
382
239
 
@@ -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.