@gadicc/loom 1.27.0 → 1.29.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 +7 -3
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +76 -13
- package/esm/src/next/auth/client.d.ts +28 -0
- package/esm/src/next/auth/client.d.ts.map +1 -0
- package/esm/src/next/auth/client.js +28 -0
- package/esm/src/next/auth/server.d.ts +16 -0
- package/esm/src/next/auth/server.d.ts.map +1 -1
- package/esm/src/next/auth/server.js +15 -3
- package/package.json +6 -2
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +76 -13
- package/script/src/next/auth/client.d.ts +28 -0
- package/script/src/next/auth/client.d.ts.map +1 -0
- package/script/src/next/auth/client.js +32 -0
- package/script/src/next/auth/server.d.ts +16 -0
- package/script/src/next/auth/server.d.ts.map +1 -1
- package/script/src/next/auth/server.js +15 -3
- package/skills/loom-auth/SKILL.md +65 -0
- package/skills/modernize-app/SKILL.md +90 -0
- package/skills/modernize-app/agents/openai.yaml +4 -0
- package/skills/modernize-app/references/architecture-and-characterization.md +205 -0
- package/skills/modernize-app/references/identity-and-data.md +251 -0
- package/skills/modernize-app/references/offline-and-media.md +403 -0
- package/skills/modernize-app/references/rollout-and-shared-work.md +400 -0
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import "../../../_dnt.polyfills.js";
|
|
2
|
+
/**
|
|
3
|
+
* Browser-side Better Auth helpers. This module imports nothing, so it adds no
|
|
4
|
+
* dependency and is safe to reach from a consumer's own client module. Read
|
|
5
|
+
* globals through `globalThis`: a bare `window` becomes a build shim that is
|
|
6
|
+
* always defined, and pulls Node polyfills into the browser bundle.
|
|
7
|
+
*/
|
|
8
|
+
type PendingSessionState = {
|
|
9
|
+
isPending: boolean;
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* Wraps Better Auth's `useSession` so a session reports pending only until the
|
|
13
|
+
* page's first answer.
|
|
14
|
+
*
|
|
15
|
+
* Better Auth marks a session with no data as pending again for every refetch,
|
|
16
|
+
* which it runs on focus, on reconnect and on a cross-tab session change. For a
|
|
17
|
+
* signed-out visitor that turns each of those into a pending state, so views
|
|
18
|
+
* waiting for the first answer unmount and re-check identity, and anything
|
|
19
|
+
* keyed on the session runs again. After the first answer this keeps the last
|
|
20
|
+
* settled state, which for a pending refetch is always "no session", until the
|
|
21
|
+
* new answer arrives.
|
|
22
|
+
*
|
|
23
|
+
* Server renders never settle, so hydration still starts from the pending
|
|
24
|
+
* state the server rendered.
|
|
25
|
+
*/
|
|
26
|
+
export declare function createSettledSessionHook<TState extends PendingSessionState>(useSession: () => TState): () => TState;
|
|
27
|
+
export {};
|
|
28
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/client.ts"],"names":[],"mappings":"AAAA,OAAO,4BAA4B,CAAC;AAGpC;;;;;GAKG;AAEH,KAAK,mBAAmB,GAAG;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,SAAS,mBAAmB,EACzE,UAAU,EAAE,MAAM,MAAM,GACvB,MAAM,MAAM,CAWd"}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.createSettledSessionHook = createSettledSessionHook;
|
|
4
|
+
require("../../../_dnt.polyfills.js");
|
|
5
|
+
"use client";
|
|
6
|
+
/**
|
|
7
|
+
* Wraps Better Auth's `useSession` so a session reports pending only until the
|
|
8
|
+
* page's first answer.
|
|
9
|
+
*
|
|
10
|
+
* Better Auth marks a session with no data as pending again for every refetch,
|
|
11
|
+
* which it runs on focus, on reconnect and on a cross-tab session change. For a
|
|
12
|
+
* signed-out visitor that turns each of those into a pending state, so views
|
|
13
|
+
* waiting for the first answer unmount and re-check identity, and anything
|
|
14
|
+
* keyed on the session runs again. After the first answer this keeps the last
|
|
15
|
+
* settled state, which for a pending refetch is always "no session", until the
|
|
16
|
+
* new answer arrives.
|
|
17
|
+
*
|
|
18
|
+
* Server renders never settle, so hydration still starts from the pending
|
|
19
|
+
* state the server rendered.
|
|
20
|
+
*/
|
|
21
|
+
function createSettledSessionHook(useSession) {
|
|
22
|
+
let settled = false;
|
|
23
|
+
return function useSettledSession() {
|
|
24
|
+
const session = useSession();
|
|
25
|
+
if (!session.isPending) {
|
|
26
|
+
if (typeof globalThis.document !== "undefined")
|
|
27
|
+
settled = true;
|
|
28
|
+
return session;
|
|
29
|
+
}
|
|
30
|
+
return settled ? { ...session, isPending: false } : session;
|
|
31
|
+
};
|
|
32
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
type SessionQuery = {
|
|
2
2
|
disableCookieCache?: boolean;
|
|
3
|
+
disableRefresh?: boolean;
|
|
3
4
|
};
|
|
4
5
|
type GetSessionArgs<THeaders> = {
|
|
5
6
|
headers: THeaders;
|
|
@@ -20,9 +21,24 @@ export type CreateRequestAuthSessionReadersOptions<THeaders, TAuth extends Bette
|
|
|
20
21
|
getHeaders: () => THeaders | Promise<THeaders>;
|
|
21
22
|
profileEnvVar?: string;
|
|
22
23
|
};
|
|
24
|
+
export type SessionReadOptions = {
|
|
25
|
+
disableCookieCache?: boolean;
|
|
26
|
+
/** Reads the session without extending it, for a check that only decides. */
|
|
27
|
+
disableRefresh?: boolean;
|
|
28
|
+
};
|
|
23
29
|
export declare function createRequestAuthSessionReaders<THeaders, TAuth extends BetterAuthLike<THeaders, unknown>>(options: CreateRequestAuthSessionReadersOptions<THeaders, TAuth>): {
|
|
24
30
|
getFreshSession: any;
|
|
25
31
|
getSession: any;
|
|
32
|
+
/**
|
|
33
|
+
* Reads the session again on every call, unlike the cached readers above.
|
|
34
|
+
* An authorization boundary that re-checks after awaited work needs this:
|
|
35
|
+
* a cached read can still answer from before a revocation. Pass
|
|
36
|
+
* `disableRefresh` for a check that only decides, so deciding does not
|
|
37
|
+
* extend the session.
|
|
38
|
+
*/
|
|
39
|
+
readSession: (readOptions?: SessionReadOptions) => Promise<InferAuthSession<TAuth, THeaders>>;
|
|
40
|
+
/** `readSession` with the cookie cache bypassed, and never cached. */
|
|
41
|
+
readFreshSession: (readOptions?: SessionReadOptions) => Promise<InferAuthSession<TAuth, THeaders>>;
|
|
26
42
|
};
|
|
27
43
|
export {};
|
|
28
44
|
//# sourceMappingURL=server.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/server.ts"],"names":[],"mappings":"AAEA,KAAK,YAAY,GAAG;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;
|
|
1
|
+
{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/server.ts"],"names":[],"mappings":"AAEA,KAAK,YAAY,GAAG;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,IAAI;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,EAAE,QAAQ,IAAI;IACxC,MAAM,EAAE;QACN,OAAO,EAAE,QAAQ,CAAC;KACnB,CAAC;IACF,GAAG,EAAE;QACH,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;KACtE,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAC1B,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC/C,QAAQ,IACN,KAAK,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;AAEtC,MAAM,MAAM,sCAAsC,CAChD,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,IAC7C;IACF,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,UAAU,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,wBAAgB,+BAA+B,CAC7C,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAE/C,OAAO,EAAE,sCAAsC,CAAC,QAAQ,EAAE,KAAK,CAAC;;;IAqC9D;;;;;;OAMG;gCAtCU,kBAAkB,KAC9B,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAuC3C,sEAAsE;qCACtC,kBAAkB;EAGrD"}
|
|
@@ -7,11 +7,13 @@ function createRequestAuthSessionReaders(options) {
|
|
|
7
7
|
async function readSession(readOptions = {}) {
|
|
8
8
|
const startedAt = Date.now();
|
|
9
9
|
const requestHeaders = await options.getHeaders();
|
|
10
|
+
const query = {
|
|
11
|
+
...(readOptions.disableCookieCache ? { disableCookieCache: true } : {}),
|
|
12
|
+
...(readOptions.disableRefresh ? { disableRefresh: true } : {}),
|
|
13
|
+
};
|
|
10
14
|
const session = await options.auth.api.getSession({
|
|
11
15
|
headers: requestHeaders,
|
|
12
|
-
query:
|
|
13
|
-
? { disableCookieCache: true }
|
|
14
|
-
: undefined,
|
|
16
|
+
query: Object.keys(query).length ? query : undefined,
|
|
15
17
|
});
|
|
16
18
|
if (options.env?.[profileEnvVar] === "1") {
|
|
17
19
|
console.info(`[perf:authSession] disableCookieCache=${readOptions.disableCookieCache ? 1 : 0} total=${Date.now() - startedAt}ms`);
|
|
@@ -23,5 +25,15 @@ function createRequestAuthSessionReaders(options) {
|
|
|
23
25
|
return {
|
|
24
26
|
getFreshSession,
|
|
25
27
|
getSession,
|
|
28
|
+
/**
|
|
29
|
+
* Reads the session again on every call, unlike the cached readers above.
|
|
30
|
+
* An authorization boundary that re-checks after awaited work needs this:
|
|
31
|
+
* a cached read can still answer from before a revocation. Pass
|
|
32
|
+
* `disableRefresh` for a check that only decides, so deciding does not
|
|
33
|
+
* extend the session.
|
|
34
|
+
*/
|
|
35
|
+
readSession,
|
|
36
|
+
/** `readSession` with the cookie cache bypassed, and never cached. */
|
|
37
|
+
readFreshSession: (readOptions = {}) => readSession({ ...readOptions, disableCookieCache: true }),
|
|
26
38
|
};
|
|
27
39
|
}
|
|
@@ -102,6 +102,71 @@ The helper accepts only loopback hosts and origins by default. Do not spread it
|
|
|
102
102
|
into production configuration or enable trusted proxy headers when requests can
|
|
103
103
|
bypass or spoof the intended proxy boundary.
|
|
104
104
|
|
|
105
|
+
## App layouts the manifest records
|
|
106
|
+
|
|
107
|
+
`loom.json` describes the app's shape; the checks follow it rather than one
|
|
108
|
+
layout. Record `modules.authRuntimeModule` when the Better Auth factory stays
|
|
109
|
+
free of environment reads and another module builds the instance: the shared
|
|
110
|
+
secret and session helpers may then live in either, and either may be the module
|
|
111
|
+
the client, route and server import. That module must import the configured auth
|
|
112
|
+
module, otherwise its text says nothing about the instance being checked.
|
|
113
|
+
|
|
114
|
+
The route may wrap its handlers, for example to fail closed while a migration
|
|
115
|
+
completes, as long as one `toNextJsHandler(<instance>)` call supplies every
|
|
116
|
+
exported `GET` and `POST`.
|
|
117
|
+
|
|
118
|
+
## Request-scoped sessions
|
|
119
|
+
|
|
120
|
+
`createRequestAuthSessionReaders` returns four readers. `getSession` and
|
|
121
|
+
`getFreshSession` are request-cached, so within one request each reads the
|
|
122
|
+
cookie once, which suits page and layout reads. `readSession` and
|
|
123
|
+
`readFreshSession` read again on every call.
|
|
124
|
+
|
|
125
|
+
An authorization boundary that re-checks after awaited work needs an uncached
|
|
126
|
+
read: a cached one can still answer from before a revocation. Use
|
|
127
|
+
`readFreshSession` there, and pass `disableRefresh` for a check that only
|
|
128
|
+
decides, so deciding does not extend the session. Validate identity and expiry
|
|
129
|
+
where you read.
|
|
130
|
+
|
|
131
|
+
An app may still own that reader, for example when it takes explicit headers so
|
|
132
|
+
tests and scripts can call it outside a request. Record
|
|
133
|
+
`requestSessionReaders: "app-owned"` then, so the check expects it.
|
|
134
|
+
|
|
135
|
+
## Browser session state
|
|
136
|
+
|
|
137
|
+
Better Auth marks a session with no data as pending again for every refetch, and
|
|
138
|
+
it refetches on focus, on reconnect and on a cross-tab change. For a signed-out
|
|
139
|
+
visitor each of those becomes a pending state, so views waiting for the first
|
|
140
|
+
answer unmount and re-check identity. Wrap the client's hook once:
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
"use client";
|
|
144
|
+
|
|
145
|
+
import { createSettledSessionHook } from "@gadicc/loom/next/auth/client";
|
|
146
|
+
|
|
147
|
+
export const authClient = createAuthClient({/* app plugins */});
|
|
148
|
+
export const useSession = createSettledSessionHook(authClient.useSession);
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
The wrapper reports pending only until the page's first answer, then keeps the
|
|
152
|
+
last settled state, which for a pending refetch is always "no session". Server
|
|
153
|
+
renders never settle it, so hydration still starts from the server's state.
|
|
154
|
+
|
|
155
|
+
That module imports nothing and reads globals through `globalThis`. A bare
|
|
156
|
+
`window` in package source becomes a build shim that is always defined, and
|
|
157
|
+
pulls Node polyfills into the browser bundle; `scripts/build_npm.ts` guards the
|
|
158
|
+
emitted browser entrypoints against both.
|
|
159
|
+
|
|
160
|
+
## Anonymous identity checks
|
|
161
|
+
|
|
162
|
+
An endpoint that answers "who is signed in" to a page should return 200 with a
|
|
163
|
+
null user for anonymous visitors, not 401. Anonymous pages ask on each load and
|
|
164
|
+
tab refocus, and browsers log every 401 as a failed request, which fills the
|
|
165
|
+
console during ordinary anonymous use. Keep 401 for endpoints that refuse to do
|
|
166
|
+
the work without a session. Clients cached before such a change must already
|
|
167
|
+
accept the new body: an old client that treats a null user as malformed shows an
|
|
168
|
+
error until it reloads.
|
|
169
|
+
|
|
105
170
|
## Local test login
|
|
106
171
|
|
|
107
172
|
Developer UI login is distinct from a production-build E2E auth harness. Use
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: modernize-app
|
|
3
|
+
description: Modernize an existing legacy web app toward Loom through staged tooling, framework, authentication, persistence and client-data migrations. Use for an app-wide modernization, especially Mongo/Gongo applications; use upgrade-deps alone for a dependency-only update and loom-scaffold for a new app.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Modernize an Existing App
|
|
7
|
+
|
|
8
|
+
Preserve the useful product and its data while replacing the underlying stack in
|
|
9
|
+
reviewable stages. Discover the actual starting point: recollection, old config
|
|
10
|
+
files and a dependency's presence do not establish which runtime paths are used.
|
|
11
|
+
Match the requested phase: for research-only work, inspect and design without
|
|
12
|
+
beginning application changes or provisioning resources. Treat the rollout
|
|
13
|
+
reference as acceptance criteria, not a ready-to-run recipe.
|
|
14
|
+
|
|
15
|
+
## Establish a plan that can survive implementation
|
|
16
|
+
|
|
17
|
+
Use `loom` first in a consumer, read `loom.json`, and follow its recorded
|
|
18
|
+
tooling and feature contracts. If `loom.json` is absent, including an older
|
|
19
|
+
partial Loom adoption, inspect the existing tooling, imports and wrappers before
|
|
20
|
+
using existing-app adoption; do not scaffold over them. Use the matching
|
|
21
|
+
installed feature skill when adopting or changing a Loom feature.
|
|
22
|
+
|
|
23
|
+
Record active routes, important user journeys, authoritative services, server
|
|
24
|
+
and browser data, deployed runtime/region, branch/worktree, verification
|
|
25
|
+
commands and independent backup coverage. Classify findings as observed,
|
|
26
|
+
operator-decided, locally verified, provider-verified or pending. Keep current
|
|
27
|
+
status separate from historical checkpoint notes.
|
|
28
|
+
|
|
29
|
+
Ask about ambiguous product behavior before encoding it: ownership versus
|
|
30
|
+
access, who can create or publish, anonymous adoption, required offline use,
|
|
31
|
+
supported devices, reauthentication and recovery expectations. Continue
|
|
32
|
+
independent work. Reuse explicit decisions and authorization; do not make users
|
|
33
|
+
approve the same choice after every resume or commit.
|
|
34
|
+
|
|
35
|
+
Read only the relevant reference:
|
|
36
|
+
|
|
37
|
+
- [Architecture and characterization](references/architecture-and-characterization.md)
|
|
38
|
+
for feature boundaries, tests, tooling upgrades and retained formats.
|
|
39
|
+
- [Identity and data](references/identity-and-data.md) for Gongo/internal-auth
|
|
40
|
+
or NextAuth bridges, canonical IDs, SQL constraints and import preservation.
|
|
41
|
+
- [Offline data and media](references/offline-and-media.md) for browser data,
|
|
42
|
+
queued work, private downloads, uploads and rendered resource dependencies.
|
|
43
|
+
- [Rollout and shared work](references/rollout-and-shared-work.md) for provider
|
|
44
|
+
placement, rehearsals, production activation and extracting Loom improvements.
|
|
45
|
+
|
|
46
|
+
## Order by dependencies, with useful intermediate behavior
|
|
47
|
+
|
|
48
|
+
Once implementation is authorized, establish reproducible checks and
|
|
49
|
+
characterize the next changing boundary. Run `upgrade-deps` for the dependency
|
|
50
|
+
campaign, grouping coupled packages and recording supported deferrals. Introduce
|
|
51
|
+
application services over the current authoritative store; port simpler features
|
|
52
|
+
first. Prepare SQL schemas and pure import planners locally, then exercise
|
|
53
|
+
protected real input without publishing private fixtures. Build browser recovery
|
|
54
|
+
before retiring any legacy store or protocol it depends on.
|
|
55
|
+
|
|
56
|
+
Choose authentication and persistence release boundaries from actual ID/session
|
|
57
|
+
dependencies. A verified NextAuth-to-Gongo bridge can allow staged replacement;
|
|
58
|
+
it is an option, not a mandatory intermediate destination. A database adapter is
|
|
59
|
+
useful only when its supported synchronization subset costs less than migrating
|
|
60
|
+
remaining features. Avoid implementing a generic Mongo emulator by accident.
|
|
61
|
+
|
|
62
|
+
Keep one authoritative writer at each stage. A passing schema, parser,
|
|
63
|
+
repository or provider probe is a completed foundation, not runtime activation.
|
|
64
|
+
Enable a feature only after its identity, permission, transport, persistence, UI
|
|
65
|
+
and recovery boundaries work together. Do not postpone integration tests that
|
|
66
|
+
could disprove the architecture until every foundation is finished.
|
|
67
|
+
|
|
68
|
+
## Review and leave usable checkpoints
|
|
69
|
+
|
|
70
|
+
Before a meaningful commit, use `loom-torvalds-review` with the relevant app or
|
|
71
|
+
shared-package profile. Challenge account switching, stale callbacks, retries,
|
|
72
|
+
concurrent changes, bypass paths, partial failure, existing clients and
|
|
73
|
+
recovery. Use an independent reviewer when delegation is authorized and
|
|
74
|
+
valuable; otherwise make the adversarial pass explicit. Tie findings to
|
|
75
|
+
reachable behavior and add meaningful regression checks. Review the final
|
|
76
|
+
integrated diff, not only a staged subagent patch, and rerun checks affected by
|
|
77
|
+
review fixes.
|
|
78
|
+
|
|
79
|
+
Respect the operator's model and usage budget. When delegated implementation is
|
|
80
|
+
authorized, give workers bounded tasks and only the context they need; retain
|
|
81
|
+
the requested orchestration and review ownership. Reuse established baseline and
|
|
82
|
+
identical-artifact evidence instead of repeating unchanged checks. Repeat checks
|
|
83
|
+
when edits, failures or unresolved concerns justify them.
|
|
84
|
+
|
|
85
|
+
When commits are authorized, commit each passing compatibility unit with a
|
|
86
|
+
consistent manifest/lockfile and the repository's attribution rules. Keep shared
|
|
87
|
+
configuration and integration under one owner when work runs in parallel. Record
|
|
88
|
+
what changed, exact verification scope, limitations, activation state and next
|
|
89
|
+
gate. Continue authorized work without routine confirmation; publishing,
|
|
90
|
+
provider changes and cutover remain bounded by the user's actual authorization.
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# Architecture and characterization
|
|
2
|
+
|
|
3
|
+
## Establish what exists before replacing it
|
|
4
|
+
|
|
5
|
+
Trace entry points to their actual reads, writes, identity and external effects.
|
|
6
|
+
An empty RPC router can be removed after usage/build checks; a populated one
|
|
7
|
+
needs a caller and behavior migration. Inspect route files before proposing a
|
|
8
|
+
Pages-to-App Router migration. Compare live deployment settings with local
|
|
9
|
+
configuration rather than assuming either mirrors the other.
|
|
10
|
+
|
|
11
|
+
Reference apps provide patterns, not a version set or universal product policy.
|
|
12
|
+
Compare richer behaviors and missing cases. A cache freshness TTL is not an
|
|
13
|
+
authorization lease; a whole-database cleanup helper may destroy an outbox in
|
|
14
|
+
another app. Use Loom's registries when doing shared extraction.
|
|
15
|
+
|
|
16
|
+
Make a small feature matrix with authority, read/write entry points,
|
|
17
|
+
permissions, offline necessity, unsynchronized state and intended replacement.
|
|
18
|
+
Trace code that bypasses a nominal data adapter: auth adapters, uploads, jobs
|
|
19
|
+
and integrations often use the database directly. Identify unused experiments
|
|
20
|
+
separately from active systems. An ingestion target and a retrieval target can
|
|
21
|
+
have drifted; moving the wrong one does not migrate the product.
|
|
22
|
+
|
|
23
|
+
## Pick the smallest useful service boundary
|
|
24
|
+
|
|
25
|
+
For online pages, Server Components can call server query services directly and
|
|
26
|
+
ordinary forms can use authenticated Server Actions. RSC does not provide
|
|
27
|
+
durable client state or replace every transport. Keep versioned callable
|
|
28
|
+
endpoints for offline outboxes, streaming, direct uploads and binary/rendered
|
|
29
|
+
responses. Do not persist deployment-specific Server Action references as
|
|
30
|
+
durable offline commands.
|
|
31
|
+
|
|
32
|
+
When consolidating generated-media routes, derive a closed registry and
|
|
33
|
+
parameter contract from actual callers. Keep old URLs as thin wrappers over the
|
|
34
|
+
shared service. Preserve genuine list-valued parameters, their order and
|
|
35
|
+
meaningful empty values; do not confuse them with repeated scalar keys. A widget
|
|
36
|
+
exporting live client state needs its own server-rendering contract before
|
|
37
|
+
adding its slug.
|
|
38
|
+
|
|
39
|
+
Reuse authorization and domain services across old and new entry points. A
|
|
40
|
+
database transition must not leave old generic mutation endpoints able to bypass
|
|
41
|
+
the new command. Constrain them or migrate coupled callers in the same unit. A
|
|
42
|
+
brief full-snapshot bridge can be simpler than preserving a flawed timestamp
|
|
43
|
+
delta protocol; measure its bounded data size and remember that an omitted item
|
|
44
|
+
does not automatically evict a legacy cache.
|
|
45
|
+
|
|
46
|
+
Separate an operation's protocol version, data schema version, concurrency
|
|
47
|
+
version, compiler identity and output compatibility profile. A compatible
|
|
48
|
+
compiler update should not make older stored output unreadable; a new renderer
|
|
49
|
+
profile requires explicit reader support.
|
|
50
|
+
|
|
51
|
+
## Characterize behavior that the migration could change
|
|
52
|
+
|
|
53
|
+
Prioritize permissions, exact source/data round trips, concurrency, uncertain
|
|
54
|
+
acknowledgements, scheduling boundaries, anonymous adoption, critical form
|
|
55
|
+
values, stream framing and actual rendering. Extract pure logic from
|
|
56
|
+
editor/framework side effects where practical. Do not turn legacy library method
|
|
57
|
+
names into the permanent test interface or preserve an obvious defect as
|
|
58
|
+
required behavior.
|
|
59
|
+
|
|
60
|
+
Use scoped coverage that includes unimported files in selected modules. Describe
|
|
61
|
+
its scope honestly; high coverage of extracted modules is not whole-app
|
|
62
|
+
coverage. Expand it as meaningful boundaries move. Do not weaken assertions or
|
|
63
|
+
thresholds merely to accommodate a dependency upgrade.
|
|
64
|
+
|
|
65
|
+
Use old/new comparisons for scheduling, astronomy, compiler/source maps and
|
|
66
|
+
serialization. Fix clocks/locales/timezones and preserve absent versus zero/null
|
|
67
|
+
states. Test actual controls for partial dates and clearing; a schema test alone
|
|
68
|
+
does not show what a third-party picker submits. Inspect package exports and
|
|
69
|
+
native binaries, not only version ranges.
|
|
70
|
+
|
|
71
|
+
Standalone harnesses should use the package instances and runtime realms of the
|
|
72
|
+
boundary they exercise. CJS/ESM entry points or duplicate installations can
|
|
73
|
+
create distinct class identities and fail `instanceof` for otherwise equivalent
|
|
74
|
+
values. Diagnose a harness mismatch before weakening validation. If mixed
|
|
75
|
+
instances occur in the supported runtime, treat that as a compatibility issue to
|
|
76
|
+
resolve and test; changing only the fixture would hide the problem. Check the
|
|
77
|
+
runtime export shape too: a standalone CJS loader can expose an ESM schema's
|
|
78
|
+
re-exports beneath a default namespace. Match the supported loader before
|
|
79
|
+
changing app exports to satisfy the harness.
|
|
80
|
+
|
|
81
|
+
Real browser checks matter for contenteditable/CodeMirror, hook-driven
|
|
82
|
+
rendering, selection, clipboard, service workers, IndexedDB and multi-tab
|
|
83
|
+
lifetimes. Keep known baseline failures identifiable, then compare old/new
|
|
84
|
+
behavior. A documented hook-order workaround may require retaining the current
|
|
85
|
+
renderer and disabling a new compiler optimization until its architecture is
|
|
86
|
+
deliberately changed.
|
|
87
|
+
|
|
88
|
+
Widget mocks must preserve lifecycle boundaries relevant to the failure. An
|
|
89
|
+
eager editor mock can hide a lost source update before the real view mounts.
|
|
90
|
+
Verify initial text and preview after delayed creation, and that a late view
|
|
91
|
+
cannot restore content after access is locked. Inspect whether controlled value
|
|
92
|
+
updates emit the same change callback as user input before relying on that
|
|
93
|
+
callback for compilation or draft persistence.
|
|
94
|
+
|
|
95
|
+
## Choose the acceptance environment early
|
|
96
|
+
|
|
97
|
+
Inspect Loom and the reference apps for developer test-user flows before asking
|
|
98
|
+
the operator to repeat long multi-account journeys on Preview. Automate ordinary
|
|
99
|
+
permissions, forms, account switching and offline behavior against isolated
|
|
100
|
+
local data. Keep a smaller deployed pass for actual OAuth callbacks, platform
|
|
101
|
+
packaging, database integration and object-storage behavior that local services
|
|
102
|
+
cannot prove. Synthetic sessions can prove the application's authorization and
|
|
103
|
+
lifecycle contracts, but they cannot prove provider consent, callback
|
|
104
|
+
registration, cookie behavior or account linking. Keep the real OAuth journey as
|
|
105
|
+
its own deployed gate.
|
|
106
|
+
|
|
107
|
+
Keep developer login and production-build test sessions separate. Shared
|
|
108
|
+
developer login can own explicit opt-in, local request checks, fixed identity
|
|
109
|
+
selection and cookie forwarding; the app owns identity persistence and
|
|
110
|
+
permission grants. An identity named "admin" must not silently bypass a separate
|
|
111
|
+
grant fixture. Follow the installed `loom-auth` guidance when its shared helper
|
|
112
|
+
is available.
|
|
113
|
+
|
|
114
|
+
For service-worker acceptance, use the app's production build when development
|
|
115
|
+
mode disables the worker. An auth library's official test helper can create real
|
|
116
|
+
sessions through a separate command without enabling a deployed test-login
|
|
117
|
+
route. Bind the command to synthetic targets, validate sessions with the actual
|
|
118
|
+
runtime auth configuration, and keep browser storage-state files private and
|
|
119
|
+
ignored.
|
|
120
|
+
|
|
121
|
+
Exercise real local storage protocols where practical, including conditional
|
|
122
|
+
write retries and subsequent reads. A passing local adapter does not prove cloud
|
|
123
|
+
CORS, credentials or exact provider behavior. Keep any local transport exception
|
|
124
|
+
explicit and scoped; preserve the cloud adapter's authorization and validation.
|
|
125
|
+
|
|
126
|
+
Test cold loading and reconnect separately from steady-state requests. A private
|
|
127
|
+
view can register while account verification is still in progress, miss its
|
|
128
|
+
first permission check, and later display a cached grant without checking
|
|
129
|
+
revocation. Coalesce readiness retries without looping on the state changes
|
|
130
|
+
caused by those same requests. Review every caller of shared identity
|
|
131
|
+
activation, since an older verification may change local authority before a
|
|
132
|
+
newer check rejects it as stale. Also interrupt an already-started permission
|
|
133
|
+
request with account activation: readiness gating alone does not repair a
|
|
134
|
+
cancelled request. Exercise registration of already-cached resources with the
|
|
135
|
+
real coordinator: asynchronous discovery can invalidate a request before its
|
|
136
|
+
first network call. A lock reason may be shared by that discovery and the
|
|
137
|
+
request's own successful cache update. Track whether the permission response was
|
|
138
|
+
accepted, and retry pre-acceptance cancellation without turning accepted cache
|
|
139
|
+
changes or ordinary network failures into a loop. When replacing awaited work
|
|
140
|
+
with queued callbacks, preserve ordering required by later save, publication or
|
|
141
|
+
cleanup operations. Update tests so their promises are actually in flight before
|
|
142
|
+
exercising cancellation or sign-out.
|
|
143
|
+
|
|
144
|
+
When a browser session closes without evidence, inspect driver stderr before
|
|
145
|
+
diagnosing an application crash or retrying. Restricted script contexts may omit
|
|
146
|
+
ordinary globals, and an uncaught event-listener error can terminate the driver.
|
|
147
|
+
|
|
148
|
+
## Upgrade tooling without bundling a product rewrite
|
|
149
|
+
|
|
150
|
+
Follow `upgrade-deps`; re-query supported versions and migration guidance when
|
|
151
|
+
the work happens. Align actual executing Node/Deno, package-manager pins, CI and
|
|
152
|
+
deployment targets. Preserve intentional loaders and build modes while moving
|
|
153
|
+
framework/runtime/adapter families. Read installed framework docs where
|
|
154
|
+
available. Migrate formatter defaults deliberately and separate broad formatting
|
|
155
|
+
from behavior changes; lint-driven React key changes can alter state.
|
|
156
|
+
|
|
157
|
+
After dependency patches or code generation, inspect the artifact actually
|
|
158
|
+
served. A package file can be correct while an incremental framework cache still
|
|
159
|
+
emits old code. Use clean generated output when evidence calls for it; do not
|
|
160
|
+
delete user data or lockfiles to make verification pass. Match source/artifact
|
|
161
|
+
identities between isolated tests and the integrated app.
|
|
162
|
+
|
|
163
|
+
A repository alert banner is not a dependency audit result: its count can differ
|
|
164
|
+
from the API and can outlive manifests removed from the default branch. Resolve
|
|
165
|
+
alerts against the current default-branch manifests and lockfile, then trace
|
|
166
|
+
each advisory through the installed dependency path to its actual input and
|
|
167
|
+
sink. An unreachable trigger can justify scheduling a patch after a release, but
|
|
168
|
+
it is not security clearance for the dependency or for unrelated alerts.
|
|
169
|
+
|
|
170
|
+
When diagnosing a Vercel prebuilt deployment mismatch, rebuild from a fresh real
|
|
171
|
+
dependency tree. Reused dependencies can conceal packages or files that the
|
|
172
|
+
declared install and deployment artifact do not contain. When the installed CLI
|
|
173
|
+
supports it, use `vercel build --standalone` to inline external file references,
|
|
174
|
+
then prove every packaged path remains inside the standalone output root.
|
|
175
|
+
Inspect the complete upload graph rather than only regular files: follow
|
|
176
|
+
symlinks and resolve `FileFsRef` and `filePathMap` entries to their final
|
|
177
|
+
packaged targets. A successful build or upload summary does not establish that
|
|
178
|
+
this graph is complete. Nor does enumerating every traced edge prove the tracer
|
|
179
|
+
discovered data loaded from a runtime-computed path. For dynamic fonts, native
|
|
180
|
+
data or similar resources, verify the physical packaged file and execute the
|
|
181
|
+
built route that opens it.
|
|
182
|
+
|
|
183
|
+
For native/WASM resources, exercise the built public route and inspect
|
|
184
|
+
deployment asset traces. A loader working in unit tests can be rewritten by the
|
|
185
|
+
bundler or retain a build-machine path. Verify every wrapper carries the
|
|
186
|
+
required server assets, and exercise repeated calls in one process: shared
|
|
187
|
+
initialization can fail even when each isolated test succeeds.
|
|
188
|
+
|
|
189
|
+
Next's NFT trace can name an asset through a pnpm package symlink while the
|
|
190
|
+
final standalone artifact omits its physical target. Check the actual packaged
|
|
191
|
+
and deployed file, then exercise native/WASM initialization; a trace entry alone
|
|
192
|
+
proves neither inclusion nor loadability.
|
|
193
|
+
|
|
194
|
+
An RSC page can carry a runtime exception with HTTP 200. Inspect the decoded RSC
|
|
195
|
+
result and runtime error. Under current Next, do not pass the Next `Link`
|
|
196
|
+
function through MUI's `component` prop across a server/client boundary;
|
|
197
|
+
instantiate that composition in a client component. Client-only usage remains
|
|
198
|
+
valid.
|
|
199
|
+
|
|
200
|
+
Keep stored content formats stable through persistence migration unless a change
|
|
201
|
+
is necessary. Evaluate replacement editors independently with real constructs,
|
|
202
|
+
round-trip conversion, diagnostics and the intended editor audience. Preserve
|
|
203
|
+
exact originals and distinguish semantic comparison rules from transformations
|
|
204
|
+
applied to stored data. Defer collaboration or other product work when outside
|
|
205
|
+
the agreed milestone.
|