@gadicc/loom 1.22.1 → 1.24.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -1
- package/esm/src/cli/mod.d.ts +11 -0
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +236 -54
- package/esm/src/cli/releaseConfig.d.ts +10 -0
- package/esm/src/cli/releaseConfig.d.ts.map +1 -0
- package/esm/src/cli/releaseConfig.js +22 -0
- package/esm/src/next/pwa/mod.d.ts +10 -2
- package/esm/src/next/pwa/mod.d.ts.map +1 -1
- package/esm/src/next/pwa/mod.js +142 -31
- package/package.json +2 -2
- package/script/src/cli/mod.d.ts +11 -0
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +237 -54
- package/script/src/cli/releaseConfig.d.ts +10 -0
- package/script/src/cli/releaseConfig.d.ts.map +1 -0
- package/script/src/cli/releaseConfig.js +26 -0
- package/script/src/next/pwa/mod.d.ts +10 -2
- package/script/src/next/pwa/mod.d.ts.map +1 -1
- package/script/src/next/pwa/mod.js +142 -31
- package/skills/loom/SKILL.md +25 -0
- package/skills/loom-db/SKILL.md +5 -1
- package/skills/loom-jobs/SKILL.md +18 -0
- package/skills/loom-scaffold/SKILL.md +69 -0
- package/skills/loom-scaffold/agents/openai.yaml +4 -0
- package/skills/loom-scaffold/references/greenfield-workflow.md +248 -0
|
@@ -51,13 +51,24 @@ function reportError(error, onError, logger) {
|
|
|
51
51
|
(logger ?? console).error("[PWA] Service worker lifecycle error", error);
|
|
52
52
|
}
|
|
53
53
|
}
|
|
54
|
-
|
|
55
|
-
|
|
54
|
+
const registrations = new WeakMap();
|
|
55
|
+
function registerOnce(serwist) {
|
|
56
|
+
let pending = registrations.get(serwist);
|
|
57
|
+
if (!pending) {
|
|
58
|
+
// React effects can remount while registration is still waiting for load.
|
|
59
|
+
pending = Promise.resolve().then(() => serwist.register());
|
|
60
|
+
registrations.set(serwist, pending);
|
|
61
|
+
void pending.catch(() => registrations.delete(serwist));
|
|
62
|
+
}
|
|
63
|
+
return pending;
|
|
56
64
|
}
|
|
57
65
|
/**
|
|
58
66
|
* Registers Loom's Serwist lifecycle listeners and optional update polling.
|
|
59
67
|
*
|
|
60
|
-
*
|
|
68
|
+
* Cleanup removes this observer's listeners and polling without unregistering
|
|
69
|
+
* the worker or removing offline caches. Pending callbacks cannot activate or
|
|
70
|
+
* reload after cleanup. Registration is shared across effect remounts.
|
|
71
|
+
*
|
|
61
72
|
* In `prompt` mode, a waiting worker is activated only after `canReloadNow` and
|
|
62
73
|
* `confirmUpdate` both allow it; in `manual` mode Loom reports availability but
|
|
63
74
|
* never activates the worker for the app.
|
|
@@ -71,8 +82,19 @@ function setupLoomPwaLifecycle(options = {}) {
|
|
|
71
82
|
const logger = options.logger === false ? false : options.logger ?? console;
|
|
72
83
|
const reload = options.reload ?? defaultReload;
|
|
73
84
|
let disposed = false;
|
|
74
|
-
let
|
|
85
|
+
let reloaded = false;
|
|
86
|
+
let reloadPending = false;
|
|
87
|
+
let approvedWorker;
|
|
88
|
+
let legacyApproval = false;
|
|
89
|
+
let registration;
|
|
75
90
|
let updateInterval;
|
|
91
|
+
let updatePending = false;
|
|
92
|
+
let promptQueue = Promise.resolve();
|
|
93
|
+
const pendingWaiting = new WeakSet();
|
|
94
|
+
const decidedWaiting = new WeakSet();
|
|
95
|
+
const controller = () => navigator.serviceWorker.controller;
|
|
96
|
+
let previousController = controller();
|
|
97
|
+
let latestControl;
|
|
76
98
|
const makeContext = (reason, event) => ({
|
|
77
99
|
event,
|
|
78
100
|
isUpdate: event.isUpdate ?? reason === "waiting",
|
|
@@ -80,77 +102,166 @@ function setupLoomPwaLifecycle(options = {}) {
|
|
|
80
102
|
serwist,
|
|
81
103
|
wasWaitingBeforeRegister: event.wasWaitingBeforeRegister,
|
|
82
104
|
});
|
|
105
|
+
const failed = (error) => {
|
|
106
|
+
if (!disposed)
|
|
107
|
+
reportError(error, options.onError, options.logger);
|
|
108
|
+
};
|
|
83
109
|
const deferUpdate = (context) => {
|
|
110
|
+
if (disposed)
|
|
111
|
+
return;
|
|
84
112
|
options.onUpdateDeferred?.(context);
|
|
85
113
|
logger && logger.info("[PWA] Update deferred.");
|
|
86
114
|
};
|
|
115
|
+
const isCurrent = (worker) => !worker || controller() === worker ||
|
|
116
|
+
worker.state === "activating" || worker.state === "activated" ||
|
|
117
|
+
(worker.state !== "redundant" &&
|
|
118
|
+
(!registration || registration.waiting === worker));
|
|
119
|
+
const applyControl = async (context) => {
|
|
120
|
+
const current = controller();
|
|
121
|
+
const approved = approvedWorker
|
|
122
|
+
? current === approvedWorker
|
|
123
|
+
: legacyApproval;
|
|
124
|
+
if (disposed || reloaded || reloadPending ||
|
|
125
|
+
(!approved && (updateMode !== "auto" || !context.isUpdate)))
|
|
126
|
+
return;
|
|
127
|
+
// Reserve before awaiting the app's guard; controller events can overlap.
|
|
128
|
+
reloadPending = true;
|
|
129
|
+
try {
|
|
130
|
+
const allowed = await (options.canReloadNow?.(context) ?? true);
|
|
131
|
+
if (disposed || reloaded || current !== controller())
|
|
132
|
+
return;
|
|
133
|
+
if (!allowed) {
|
|
134
|
+
deferUpdate(context);
|
|
135
|
+
return;
|
|
136
|
+
}
|
|
137
|
+
reloaded = true;
|
|
138
|
+
options.onUpdateActivated?.(context);
|
|
139
|
+
if (!disposed)
|
|
140
|
+
reload();
|
|
141
|
+
}
|
|
142
|
+
finally {
|
|
143
|
+
reloadPending = false;
|
|
144
|
+
}
|
|
145
|
+
};
|
|
87
146
|
const handleWaiting = async (event) => {
|
|
147
|
+
const key = event.sw ?? event;
|
|
148
|
+
if (disposed || reloaded || decidedWaiting.has(key))
|
|
149
|
+
return;
|
|
88
150
|
const context = makeContext("waiting", event);
|
|
89
151
|
options.onUpdateAvailable?.(context);
|
|
152
|
+
if (disposed)
|
|
153
|
+
return;
|
|
90
154
|
if (updateMode === "manual") {
|
|
91
155
|
deferUpdate(context);
|
|
92
156
|
return;
|
|
93
157
|
}
|
|
94
|
-
|
|
158
|
+
const allowed = await (options.canReloadNow?.(context) ?? true);
|
|
159
|
+
if (disposed || reloaded)
|
|
160
|
+
return;
|
|
161
|
+
if (!allowed || !isCurrent(event.sw)) {
|
|
95
162
|
deferUpdate(context);
|
|
96
163
|
return;
|
|
97
164
|
}
|
|
98
165
|
const accepted = updateMode === "auto"
|
|
99
166
|
? true
|
|
100
167
|
: await (options.confirmUpdate?.(context) ?? defaultConfirmUpdate());
|
|
101
|
-
if (
|
|
168
|
+
if (disposed || reloaded)
|
|
169
|
+
return;
|
|
170
|
+
decidedWaiting.add(key);
|
|
171
|
+
if (!accepted || !isCurrent(event.sw)) {
|
|
102
172
|
deferUpdate(context);
|
|
103
173
|
return;
|
|
104
174
|
}
|
|
105
|
-
|
|
175
|
+
approvedWorker = event.sw;
|
|
176
|
+
legacyApproval = !event.sw;
|
|
106
177
|
options.onUpdateAccepted?.(context);
|
|
107
|
-
|
|
108
|
-
};
|
|
109
|
-
const handleControlling = async (event) => {
|
|
110
|
-
const context = makeContext("controlling", event);
|
|
111
|
-
if (!context.isUpdate || (!reloadOnNextControl && updateMode !== "auto")) {
|
|
178
|
+
if (disposed || reloaded)
|
|
112
179
|
return;
|
|
180
|
+
if (event.sw && controller() === event.sw) {
|
|
181
|
+
// Another tab may have activated the accepted worker during the prompt.
|
|
182
|
+
await applyControl(latestControl ?? makeContext("controlling", {
|
|
183
|
+
type: "controlling",
|
|
184
|
+
isUpdate: true,
|
|
185
|
+
sw: event.sw,
|
|
186
|
+
}));
|
|
113
187
|
}
|
|
114
|
-
if (
|
|
115
|
-
|
|
116
|
-
|
|
188
|
+
else if (event.sw) {
|
|
189
|
+
// Serwist's messageSkipWaiting selects whichever worker is waiting now.
|
|
190
|
+
// Address the approved identity so a replacement cannot inherit consent.
|
|
191
|
+
if (event.sw.state !== "activating" && event.sw.state !== "activated") {
|
|
192
|
+
event.sw.postMessage({ type: "SKIP_WAITING" });
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
else {
|
|
196
|
+
// Preserve integrations that implement the original identity-free API.
|
|
197
|
+
await serwist.messageSkipWaiting();
|
|
117
198
|
}
|
|
118
|
-
options.onUpdateActivated?.(context);
|
|
119
|
-
reload();
|
|
120
199
|
};
|
|
121
200
|
const waitingListener = (event) => {
|
|
122
|
-
|
|
201
|
+
const key = event.sw ?? event;
|
|
202
|
+
if (disposed || reloaded || pendingWaiting.has(key))
|
|
203
|
+
return;
|
|
204
|
+
pendingWaiting.add(key);
|
|
205
|
+
// The shared confirmation UI has one dialog. Serialize different workers.
|
|
206
|
+
promptQueue = promptQueue.then(() => handleWaiting(event)).catch(failed)
|
|
207
|
+
.finally(() => pendingWaiting.delete(key));
|
|
123
208
|
};
|
|
124
209
|
const controllingListener = (event) => {
|
|
125
|
-
|
|
210
|
+
if (disposed)
|
|
211
|
+
return;
|
|
212
|
+
const current = controller();
|
|
213
|
+
const context = makeContext("controlling", event);
|
|
214
|
+
// Serwist snapshots isUpdate at registration, even on a first-install page
|
|
215
|
+
// that later receives updates. Its external event.sw can also be outdated.
|
|
216
|
+
context.isUpdate ||= Boolean(previousController && current !== previousController);
|
|
217
|
+
previousController = current;
|
|
218
|
+
latestControl = context;
|
|
219
|
+
void applyControl(context).catch(failed);
|
|
126
220
|
};
|
|
127
221
|
serwist.addEventListener("waiting", waitingListener);
|
|
128
222
|
serwist.addEventListener("controlling", controllingListener);
|
|
223
|
+
const observeRegistration = (value) => {
|
|
224
|
+
if (disposed || !value)
|
|
225
|
+
return;
|
|
226
|
+
registration = value;
|
|
227
|
+
// Cached registration does not emit waiting again when an effect remounts.
|
|
228
|
+
if (value.waiting) {
|
|
229
|
+
waitingListener({
|
|
230
|
+
type: "waiting",
|
|
231
|
+
sw: value.waiting,
|
|
232
|
+
wasWaitingBeforeRegister: true,
|
|
233
|
+
});
|
|
234
|
+
}
|
|
235
|
+
};
|
|
129
236
|
if (options.register ?? true) {
|
|
130
|
-
serwist.
|
|
237
|
+
void registerOnce(serwist).then(observeRegistration).catch(failed);
|
|
131
238
|
}
|
|
132
239
|
if (options.updateCheckIntervalMs !== undefined &&
|
|
133
240
|
options.updateCheckIntervalMs > 0) {
|
|
134
|
-
navigator.serviceWorker.ready
|
|
135
|
-
|
|
136
|
-
if (disposed) {
|
|
241
|
+
void navigator.serviceWorker.ready.then((value) => {
|
|
242
|
+
if (disposed)
|
|
137
243
|
return;
|
|
138
|
-
|
|
139
|
-
logger &&
|
|
140
|
-
logger.info(`[PWA] Will check for updates every ${options.updateCheckIntervalMs / 1000} seconds.`);
|
|
244
|
+
registration = value;
|
|
245
|
+
logger && logger.info(`[PWA] Will check for updates every ${options.updateCheckIntervalMs / 1000} seconds.`);
|
|
141
246
|
updateInterval = setInterval(() => {
|
|
142
|
-
|
|
247
|
+
if (disposed || updatePending)
|
|
248
|
+
return;
|
|
249
|
+
updatePending = true;
|
|
250
|
+
void Promise.resolve().then(() => {
|
|
251
|
+
if (!disposed)
|
|
252
|
+
return value.update();
|
|
253
|
+
}).catch(failed).finally(() => {
|
|
254
|
+
updatePending = false;
|
|
255
|
+
});
|
|
143
256
|
}, options.updateCheckIntervalMs);
|
|
144
|
-
})
|
|
145
|
-
.catch((error) => reportError(error, options.onError, options.logger));
|
|
257
|
+
}).catch(failed);
|
|
146
258
|
}
|
|
147
259
|
return () => {
|
|
148
260
|
disposed = true;
|
|
149
261
|
serwist.removeEventListener("waiting", waitingListener);
|
|
150
262
|
serwist.removeEventListener("controlling", controllingListener);
|
|
151
|
-
if (updateInterval !== undefined)
|
|
263
|
+
if (updateInterval !== undefined)
|
|
152
264
|
clearInterval(updateInterval);
|
|
153
|
-
}
|
|
154
265
|
};
|
|
155
266
|
}
|
|
156
267
|
/**
|
package/skills/loom/SKILL.md
CHANGED
|
@@ -223,6 +223,31 @@ as more authoritative than a generic mapped error when deciding what failed.
|
|
|
223
223
|
Loom version, preserve the older behavior and add an explicit new path for the
|
|
224
224
|
changed behavior.
|
|
225
225
|
|
|
226
|
+
## pnpm major upgrades
|
|
227
|
+
|
|
228
|
+
- Treat the exact `packageManager` pin as the consumer contract. Do not move all
|
|
229
|
+
apps to a new pnpm major merely because a newer release exists.
|
|
230
|
+
- Before pnpm 11, move pnpm settings from `package.json#pnpm` into
|
|
231
|
+
`pnpm-workspace.yaml`; pnpm 11 no longer reads that package.json object.
|
|
232
|
+
- Keep only registry and authentication settings in `.npmrc`. Move pnpm options
|
|
233
|
+
such as `store-dir` and `strictDepBuilds` into `pnpm-workspace.yaml`.
|
|
234
|
+
- Replace `onlyBuiltDependencies`, `ignoredBuiltDependencies`, and related old
|
|
235
|
+
dependency-build settings with an explicit `allowBuilds` map before pnpm 11.
|
|
236
|
+
- For GitHub Actions on pnpm 11+, use the maintained `pnpm/setup` action rather
|
|
237
|
+
than `pnpm/action-setup`.
|
|
238
|
+
- Run `loom check` before changing the pin. Compatibility findings are warnings
|
|
239
|
+
while the app remains on pnpm 10 and issues once it declares pnpm 11 or newer.
|
|
240
|
+
- Keep `@gadicc/loom` in `minimumReleaseAgeExclude`. It is a first-party package
|
|
241
|
+
that consumers routinely need immediately; `loom init` adds the exception
|
|
242
|
+
without weakening pnpm's release-age policy for third-party dependencies.
|
|
243
|
+
- Canary a new pnpm major in one clean Vercel consumer before rolling it across
|
|
244
|
+
the fleet. Verify a frozen install, local tests/build, preview deployment, and
|
|
245
|
+
the production release workflow. Defer consumers with overlapping local config
|
|
246
|
+
edits or unrelated commits that would be pushed by the rollout.
|
|
247
|
+
- pnpm 12 is a separate migration even when it can consume the same lockfile.
|
|
248
|
+
Evaluate it independently after its new Rust CLI and stricter workspace
|
|
249
|
+
validation have matured in the actual deployment platform.
|
|
250
|
+
|
|
226
251
|
## Commits
|
|
227
252
|
|
|
228
253
|
- Use conventional commits with scopes for the title. Limit the subject line to
|
package/skills/loom-db/SKILL.md
CHANGED
|
@@ -71,7 +71,11 @@ Use this skill when working on the shared DB stack from a consuming app.
|
|
|
71
71
|
- Confirm active Loom-managed feature schemas match their recorded hash in
|
|
72
72
|
`loom.json` and are exported from the app-local schema barrel.
|
|
73
73
|
- For Vercel production releases, confirm `vercel.json` disables automatic
|
|
74
|
-
|
|
74
|
+
deployments for the configured production branch and GitHub Actions builds
|
|
75
|
+
with Vercel production settings. The branch defaults to `main`; apps using
|
|
76
|
+
another branch set `features.db.config.release.productionBranch` in
|
|
77
|
+
`loom.json` and match the Vercel project production branch, workflow trigger
|
|
78
|
+
and deployment fence. Workflows and `vercel.json` remain app-owned. The flow
|
|
75
79
|
uploads a staged production deployment with `--prebuilt --prod --skip-domain`,
|
|
76
80
|
runs `db:migrate`, and then promotes the staged deployment. Before adding
|
|
77
81
|
build-only placeholders, preserve an untouched copy of the pulled env file for
|
|
@@ -39,6 +39,24 @@ Use this skill when working on the shared jobs feature from a consuming app.
|
|
|
39
39
|
task. Keep env loading in tasks such as `job` via `loom env --`, not in
|
|
40
40
|
`scripts/jobDirect.ts`.
|
|
41
41
|
|
|
42
|
+
## Invocation policy
|
|
43
|
+
|
|
44
|
+
- Treat a direct runner as one job transport, not as a separate job class and
|
|
45
|
+
not as evidence that the handler requires shell APIs. The app's script/job
|
|
46
|
+
boundary should instead follow capabilities: database and external-service
|
|
47
|
+
operations belong in jobs even when they are also HTTP-accessible.
|
|
48
|
+
- In server-deployed apps, production-capable operator jobs should normally have
|
|
49
|
+
an authenticated HTTP route and appear in the admin catalog. Retain the direct
|
|
50
|
+
runner as a local development and emergency-operator convenience.
|
|
51
|
+
- Keep a job out of HTTP only when it is deliberately local-only, requires a
|
|
52
|
+
runtime unavailable to the web deployment, or has another reviewed production
|
|
53
|
+
control plane. Document both the reason and the actual production execution
|
|
54
|
+
path.
|
|
55
|
+
- Sensitivity alone is not a reason for CLI-only obscurity. Protect sensitive
|
|
56
|
+
HTTP jobs with fresh-admin or scoped API-key authorization, bounded typed
|
|
57
|
+
parameters, explicit confirmation for consequential actions, sanitized output,
|
|
58
|
+
and durable audit records.
|
|
59
|
+
|
|
42
60
|
## Catalog runtime boundaries
|
|
43
61
|
|
|
44
62
|
- Keep the configured metadata catalog dependency-free. Define job metadata in a
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: loom-scaffold
|
|
3
|
+
description: Scaffold a brand-new small site, demo, or prototype with @gadicc/loom and the standard Next.js, MUI, Better Auth, Neon, Drizzle, Vitest, Biome, pnpm, GitHub, and Vercel stack. Use for empty or nearly empty repositories; use the loom skill for adoption into an existing application.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Loom Scaffold
|
|
7
|
+
|
|
8
|
+
Create a small but production-capable greenfield application without copying an
|
|
9
|
+
older app wholesale. Use current compatible packages, let Loom own its shared
|
|
10
|
+
feature wiring, and leave product-specific UI and behavior in the new app.
|
|
11
|
+
|
|
12
|
+
This is an orchestration skill, not a frozen source template. Read
|
|
13
|
+
[the greenfield workflow](references/greenfield-workflow.md) completely before
|
|
14
|
+
changing the target repository.
|
|
15
|
+
|
|
16
|
+
## Applicability
|
|
17
|
+
|
|
18
|
+
- Use this skill when the target is empty or contains only bootstrap state such
|
|
19
|
+
as `.git`, `.vercel`, and a local environment file.
|
|
20
|
+
- If meaningful application code already exists, switch to the `loom` skill and
|
|
21
|
+
adopt features incrementally instead.
|
|
22
|
+
- The standard profile is Next.js App Router with `src/`, TypeScript, MUI,
|
|
23
|
+
Better Auth with Google OAuth, Neon/Drizzle, Vitest, Biome, Node 24, the
|
|
24
|
+
current compatible pnpm 11 release, GitHub, and Vercel.
|
|
25
|
+
- Treat DB, auth, mail, files, jobs, PWA, and localization as selectable Loom
|
|
26
|
+
features. Do not add optional features merely because another app uses them.
|
|
27
|
+
|
|
28
|
+
## Start here
|
|
29
|
+
|
|
30
|
+
1. Inspect git status, remotes, the linked Vercel project, and existing files.
|
|
31
|
+
Preserve all pre-existing bootstrap state and never display local secrets.
|
|
32
|
+
2. Resolve the app name, display title, canonical domain, desired features, and
|
|
33
|
+
deployment region. Database placement is expensive to change, so require an
|
|
34
|
+
explicit region before provisioning it; match Vercel functions unless the
|
|
35
|
+
user chooses otherwise.
|
|
36
|
+
3. Confirm which external actions are in scope. Scaffolding does not by itself
|
|
37
|
+
authorize deleting/recreating resources, pushing commits, changing OAuth
|
|
38
|
+
clients, or deploying production.
|
|
39
|
+
4. After installing Next.js, read the relevant version-matched documentation in
|
|
40
|
+
`node_modules/next/dist/docs/` before making framework-specific choices.
|
|
41
|
+
5. Install the published Loom package, run `loom init`, read the resulting
|
|
42
|
+
`loom.json`, and use `loom add <feature>` rather than hand-creating shared
|
|
43
|
+
feature wiring.
|
|
44
|
+
|
|
45
|
+
## Non-negotiable invariants
|
|
46
|
+
|
|
47
|
+
- Keep `loom.json` and `project.tooling` authoritative after initialization.
|
|
48
|
+
- Pin Node and the package manager reproducibly. Keep pnpm settings in
|
|
49
|
+
`pnpm-workspace.yaml`, exempt the first-party `@gadicc/loom` package from the
|
|
50
|
+
release-age delay, and explicitly review every dependency build script.
|
|
51
|
+
- Use Loom's loopback-only Better Auth development helper when `vercel dev`
|
|
52
|
+
proxies Next.js on an internal port. OAuth callbacks must use the public
|
|
53
|
+
localhost port, never the internal framework port.
|
|
54
|
+
- Generate Drizzle migrations and generated schemas through the declared app
|
|
55
|
+
tasks. Do not hand-edit migration journals or generated validation files.
|
|
56
|
+
- For a DB-backed production app, stage the exact Vercel artifact, run verified
|
|
57
|
+
migrations, smoke-test it, and only then promote it. Keep automatic preview
|
|
58
|
+
deployments, but disable automatic `main` production deployments once that
|
|
59
|
+
release workflow is ready.
|
|
60
|
+
- Keep secrets out of commits, command arguments, logs, caches, and uploaded
|
|
61
|
+
artifacts. Document variable names in `.env.example`.
|
|
62
|
+
|
|
63
|
+
## Finish
|
|
64
|
+
|
|
65
|
+
Run the frozen install, project quality gate, production build, `loom check`,
|
|
66
|
+
and relevant network/preview checks. Report created resources and regions,
|
|
67
|
+
features, generated migration state, OAuth callback requirements, verification
|
|
68
|
+
results, deployment URLs, commits, and every remaining manual or unauthorized
|
|
69
|
+
step.
|
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
# Greenfield Loom application workflow
|
|
2
|
+
|
|
3
|
+
Use this workflow end to end for an empty or nearly empty repository. Adapt the
|
|
4
|
+
product surface, but preserve the operational boundaries below.
|
|
5
|
+
|
|
6
|
+
## Reference provenance
|
|
7
|
+
|
|
8
|
+
This skill records the reusable decisions from a reviewed Own the Gate
|
|
9
|
+
greenfield build; it does not treat that application's moving working tree as a
|
|
10
|
+
template. Loom's `docs/reference-projects.yaml` registry pins the named
|
|
11
|
+
`greenfieldScaffold` snapshot from the initial app revision through the exact
|
|
12
|
+
revision reviewed when this workflow was extracted.
|
|
13
|
+
|
|
14
|
+
Use the skill itself as the normal source of truth. If Loom maintainers need to
|
|
15
|
+
inspect a raw reference artifact and both repositories are available locally,
|
|
16
|
+
read it from `capturedThroughRevision` without checking out or modifying the
|
|
17
|
+
live app. Current framework, provider, and Loom documentation overrides package
|
|
18
|
+
versions captured by the snapshot. Advance the snapshot only after deciding that
|
|
19
|
+
later app work is a reusable scaffold improvement rather than Own the Gate
|
|
20
|
+
product behavior.
|
|
21
|
+
|
|
22
|
+
## 1. Intake and preflight
|
|
23
|
+
|
|
24
|
+
Inspect before asking questions:
|
|
25
|
+
|
|
26
|
+
- current path and existing non-generated files;
|
|
27
|
+
- `git status --short --branch` and configured remotes;
|
|
28
|
+
- `.vercel/project.json` or `.vercel/repo.json` without relinking;
|
|
29
|
+
- available Node, Corepack/pnpm, Vercel, GitHub, and provider CLIs;
|
|
30
|
+
- whether `.env.local` exists, without printing its values.
|
|
31
|
+
|
|
32
|
+
Resolve only material missing choices:
|
|
33
|
+
|
|
34
|
+
- package/directory slug and human-facing title;
|
|
35
|
+
- canonical domain and public localhost port;
|
|
36
|
+
- Vercel team/project and whether it is already linked;
|
|
37
|
+
- database and Vercel function region;
|
|
38
|
+
- required Loom features, with DB and Better Auth as the standard profile;
|
|
39
|
+
- OAuth providers and whether local/production credentials already exist;
|
|
40
|
+
- whether the user requested local scaffolding only, a pushed preview, or a
|
|
41
|
+
complete production release.
|
|
42
|
+
|
|
43
|
+
Do not infer permission to replace an existing resource. Before deleting or
|
|
44
|
+
recreating a database, deployment, branch, or credential, identify the exact
|
|
45
|
+
target, prove why replacement is needed, and obtain explicit authorization.
|
|
46
|
+
|
|
47
|
+
## 2. Establish the application baseline
|
|
48
|
+
|
|
49
|
+
Preserve `.git`, `.vercel`, `.env.local`, and any user-owned files. If a
|
|
50
|
+
generator rejects the bootstrap files in the target directory, generate into a
|
|
51
|
+
temporary directory, review its output, and move only the intended scaffold
|
|
52
|
+
files. Never copy a temporary `.git`, `.vercel`, environment file, or lockfile
|
|
53
|
+
over existing state blindly.
|
|
54
|
+
|
|
55
|
+
Create the smallest useful baseline:
|
|
56
|
+
|
|
57
|
+
- current compatible Next.js and React with App Router, `src/`, TypeScript, and
|
|
58
|
+
the `@/*` alias;
|
|
59
|
+
- React Server Components by default, with narrow client providers;
|
|
60
|
+
- MUI, Emotion, the version-appropriate MUI Next.js cache provider, one shared
|
|
61
|
+
theme, and an intentional first page rather than generator demo content;
|
|
62
|
+
- site metadata in one typed app-local config used by layout, sitemap, robots,
|
|
63
|
+
and tests;
|
|
64
|
+
- Biome checks/fixes, Vitest, typecheck, build, and a full local gate;
|
|
65
|
+
- `.gitignore`, `.env.example`, `.node-version`, `.nvmrc`, and a concise README;
|
|
66
|
+
- Dependabot and CODEOWNERS when GitHub maintenance is in scope.
|
|
67
|
+
|
|
68
|
+
After `loom init`, keep project-specific AGENTS guidance outside Loom's managed
|
|
69
|
+
blocks. Add only useful local context such as the project overview, runtime and
|
|
70
|
+
UI choices, authoritative commands, environment/data rules, and verification
|
|
71
|
+
gate; do not duplicate the shared Loom skill.
|
|
72
|
+
|
|
73
|
+
Use current mutually compatible releases rather than copying versions from a
|
|
74
|
+
reference app. Pin framework/tooling versions where reproducibility matters.
|
|
75
|
+
|
|
76
|
+
## 3. Configure pnpm 11 deliberately
|
|
77
|
+
|
|
78
|
+
Record an exact current pnpm 11 version in `packageManager` and target Node 24.
|
|
79
|
+
Do not move a new scaffold to pnpm 12 as part of ordinary creation; evaluate it
|
|
80
|
+
as a separate canary when explicitly requested.
|
|
81
|
+
|
|
82
|
+
Keep non-registry pnpm settings in `pnpm-workspace.yaml`, using pnpm 11 names:
|
|
83
|
+
|
|
84
|
+
- add `@gadicc/loom` to `minimumReleaseAgeExclude`, because it is first-party
|
|
85
|
+
development infrastructure;
|
|
86
|
+
- set `minimumReleaseAgeExcludePrune: true`;
|
|
87
|
+
- enable `strictDepBuilds`;
|
|
88
|
+
- use `allowBuilds` only for build scripts observed and reviewed during the
|
|
89
|
+
actual install.
|
|
90
|
+
|
|
91
|
+
If an already-reviewed dependency is younger than pnpm's release-age window, add
|
|
92
|
+
only its exact package/version exception. Do not disable the policy or add broad
|
|
93
|
+
third-party patterns. Let Loom remain the sole broad first-party exception.
|
|
94
|
+
|
|
95
|
+
In GitHub Actions, use the maintained `pnpm/setup` action pinned to a reviewed
|
|
96
|
+
full commit SHA. Let `package.json#packageManager` select pnpm; do not also pass
|
|
97
|
+
a duplicate version input. The cache input is `cache-dependency-path` with a
|
|
98
|
+
hyphen. Include both lockfile and workspace configuration in the cache key.
|
|
99
|
+
|
|
100
|
+
## 4. Initialize Loom and select features
|
|
101
|
+
|
|
102
|
+
Install the current published `@gadicc/loom`, then run:
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
pnpm exec loom init
|
|
106
|
+
pnpm exec loom status
|
|
107
|
+
pnpm exec loom add db
|
|
108
|
+
pnpm exec loom add auth
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Only run the feature commands the app needs. Re-read `loom.json` after each
|
|
112
|
+
activation and treat recorded paths and `project.tooling` as authoritative. Keep
|
|
113
|
+
generated Loom wrappers thin. Let `loom init` manage the AGENTS bootstrap,
|
|
114
|
+
package skills, task wiring, and the pnpm release-age exception.
|
|
115
|
+
|
|
116
|
+
For DB work, read the `loom-db` skill. For Better Auth work, read the
|
|
117
|
+
`loom-auth` skill. Use the matching feature skill for every additional active
|
|
118
|
+
feature.
|
|
119
|
+
|
|
120
|
+
## 5. Provision and initialize Neon
|
|
121
|
+
|
|
122
|
+
Select the region before provisioning. For the Vercel Marketplace path, use the
|
|
123
|
+
explicit region and resource name:
|
|
124
|
+
|
|
125
|
+
```text
|
|
126
|
+
pnpm exec loom db neon setup --name <resource-name> --region <region>
|
|
127
|
+
pnpm exec loom db neon check
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Use Better Auth rather than Neon Auth unless the user explicitly chooses the
|
|
131
|
+
latter. Verify the connected provider, Production/Preview environment scopes,
|
|
132
|
+
and recorded region in `loom.json`; do not assume that project-level Preview
|
|
133
|
+
variables imply an isolated local-development database.
|
|
134
|
+
|
|
135
|
+
Keep app schemas in the configured schema directory. For the standard auth
|
|
136
|
+
baseline:
|
|
137
|
+
|
|
138
|
+
1. create the app-owned Better Auth options and generator config;
|
|
139
|
+
2. generate the Better Auth Drizzle schema;
|
|
140
|
+
3. export it from the app schema barrel;
|
|
141
|
+
4. generate and review the initial Drizzle migration;
|
|
142
|
+
5. regenerate Loom's Valibot schemas;
|
|
143
|
+
6. verify the PGlite harness and tests;
|
|
144
|
+
7. apply migrations only through the authoritative env-aware task and only to
|
|
145
|
+
the intended database.
|
|
146
|
+
|
|
147
|
+
Never hand-edit Drizzle journal/snapshot state or generated Valibot output.
|
|
148
|
+
|
|
149
|
+
## 6. Configure Better Auth and Google OAuth
|
|
150
|
+
|
|
151
|
+
Keep providers, the Drizzle adapter, plugins, redirect behavior, and session
|
|
152
|
+
enrichment app-local. Use Loom helpers for the stable secret, session, and
|
|
153
|
+
server-reader boundaries.
|
|
154
|
+
|
|
155
|
+
For local development through `vercel dev`, spread
|
|
156
|
+
`createBetterAuthLocalDevelopmentConfig()` only in the non-production branch. It
|
|
157
|
+
trusts the loopback proxy boundary so Better Auth derives callbacks from the
|
|
158
|
+
public localhost port rather than Next.js's internal port.
|
|
159
|
+
|
|
160
|
+
Document and verify these callbacks:
|
|
161
|
+
|
|
162
|
+
- local origin: `http://localhost:<public-port>`;
|
|
163
|
+
- local redirect: `http://localhost:<public-port>/api/auth/callback/google`;
|
|
164
|
+
- production origin: `https://<canonical-domain>`;
|
|
165
|
+
- production redirect: `https://<canonical-domain>/api/auth/callback/google`.
|
|
166
|
+
|
|
167
|
+
Treat Google OAuth client creation and redirect editing as manual/external
|
|
168
|
+
unless an authenticated, supported API or CLI path has been confirmed. Vercel
|
|
169
|
+
environment variables can be configured from its CLI without placing secret
|
|
170
|
+
values in command arguments or shell history.
|
|
171
|
+
|
|
172
|
+
When local credentials are available, run the app through the public
|
|
173
|
+
`vercel dev` URL and initiate sign-in. Inspect the actual Google authorization
|
|
174
|
+
request and compare its `redirect_uri` exactly with the configured public
|
|
175
|
+
callback before declaring local OAuth complete.
|
|
176
|
+
|
|
177
|
+
At minimum document these environment names:
|
|
178
|
+
|
|
179
|
+
- `NEXT_PUBLIC_SITE_URL` and `BETTER_AUTH_URL`;
|
|
180
|
+
- `BETTER_AUTH_SECRET` or a deliberate versioned rotation configuration;
|
|
181
|
+
- provider client ID and client secret;
|
|
182
|
+
- pooled and direct database URLs supplied by the integration.
|
|
183
|
+
|
|
184
|
+
## 7. Build the safe production release path
|
|
185
|
+
|
|
186
|
+
Set the chosen Vercel function region in `vercel.json`. For a DB-backed app,
|
|
187
|
+
build the GitHub-to-Vercel staged release before disabling Vercel's automatic
|
|
188
|
+
production deployment for `main`.
|
|
189
|
+
|
|
190
|
+
Use Loom's setup commands where applicable:
|
|
191
|
+
|
|
192
|
+
```text
|
|
193
|
+
pnpm exec loom db release setup-github
|
|
194
|
+
pnpm exec loom db migrations setup-github
|
|
195
|
+
pnpm exec loom check --production --network
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
The app-local workflow must:
|
|
199
|
+
|
|
200
|
+
1. install frozen dependencies and hydrate Loom's ignored skill links;
|
|
201
|
+
2. run typecheck, Biome, tests, and `loom check --production`;
|
|
202
|
+
3. pull Vercel Production settings and mask readable secrets;
|
|
203
|
+
4. prepare metadata-backed placeholders only for unreadable Sensitive values;
|
|
204
|
+
5. validate the preserved migration environment with `--connect`;
|
|
205
|
+
6. build and scan the exact prebuilt artifact;
|
|
206
|
+
7. upload it with `--prebuilt --prod --skip-domain`;
|
|
207
|
+
8. run the backward-compatible Drizzle migration;
|
|
208
|
+
9. smoke-test the staged deployment through a short-lived protection bypass;
|
|
209
|
+
10. promote that exact deployment and revoke the bypass even on failure.
|
|
210
|
+
|
|
211
|
+
Keep preview deployments automatic. Pin third-party Actions to reviewed full
|
|
212
|
+
commit SHAs and let Dependabot maintain them.
|
|
213
|
+
|
|
214
|
+
## 8. Verification and release
|
|
215
|
+
|
|
216
|
+
Before the first commit, run at least:
|
|
217
|
+
|
|
218
|
+
```text
|
|
219
|
+
pnpm install --frozen-lockfile
|
|
220
|
+
pnpm pre-commit
|
|
221
|
+
pnpm build
|
|
222
|
+
pnpm exec loom check
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Run provider/network checks when external setup is in scope. If push/deployment
|
|
226
|
+
was authorized, use a non-production branch first, wait for Vercel to reach a
|
|
227
|
+
terminal state, and smoke-test meaningful routes such as the homepage, auth
|
|
228
|
+
session endpoint, and a DB readiness endpoint. Promote the exact verified
|
|
229
|
+
commit, follow CI/CD to completion, and fix/retry failures within the authorized
|
|
230
|
+
scope.
|
|
231
|
+
|
|
232
|
+
Do not upload a directory that contains unreviewed private data or local secret
|
|
233
|
+
files merely to obtain a preview. Use Git integration or establish an explicit
|
|
234
|
+
safe packaging/ignore boundary first.
|
|
235
|
+
|
|
236
|
+
## 9. Handoff
|
|
237
|
+
|
|
238
|
+
Report:
|
|
239
|
+
|
|
240
|
+
- application URL, package name, title, and selected regions;
|
|
241
|
+
- installed stack and active Loom features;
|
|
242
|
+
- database resource, environment scoping, migration state, and whether live
|
|
243
|
+
connectivity was verified;
|
|
244
|
+
- OAuth origins/redirects and any console-only work remaining;
|
|
245
|
+
- local commands and every verification result;
|
|
246
|
+
- preview/production deployment and workflow URLs when created;
|
|
247
|
+
- commits and whether they were pushed;
|
|
248
|
+
- every incomplete, manual, deferred, or unauthorized step.
|