@simpleapps-com/augur-config 2.4.0 → 2026.11.1

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 (49) hide show
  1. package/EXPORTS.md +43 -44
  2. package/README.md +41 -29
  3. package/dist/augur-doctor.d.ts +13 -0
  4. package/dist/augur-doctor.d.ts.map +1 -0
  5. package/dist/augur-doctor.js +742 -0
  6. package/dist/augur-doctor.js.map +1 -0
  7. package/dist/chunk-RY3GDLDS.js +26 -0
  8. package/dist/chunk-RY3GDLDS.js.map +1 -0
  9. package/dist/chunk-ZV56KMH3.js +172 -0
  10. package/dist/chunk-ZV56KMH3.js.map +1 -0
  11. package/dist/doctor/checks.d.ts +34 -0
  12. package/dist/doctor/checks.d.ts.map +1 -0
  13. package/dist/doctor/cli.d.ts +11 -0
  14. package/dist/doctor/cli.d.ts.map +1 -0
  15. package/dist/doctor/node-reader.d.ts +7 -0
  16. package/dist/doctor/node-reader.d.ts.map +1 -0
  17. package/dist/doctor/report.d.ts +5 -0
  18. package/dist/doctor/report.d.ts.map +1 -0
  19. package/dist/doctor/rules.d.ts +227 -0
  20. package/dist/doctor/rules.d.ts.map +1 -0
  21. package/dist/eslint-next.d.ts +9 -0
  22. package/dist/eslint-next.d.ts.map +1 -0
  23. package/dist/eslint-next.js +35 -0
  24. package/dist/eslint-next.js.map +1 -0
  25. package/dist/eslint-shared.d.ts +36 -0
  26. package/dist/eslint-shared.d.ts.map +1 -0
  27. package/dist/eslint.d.ts +6 -0
  28. package/dist/eslint.d.ts.map +1 -0
  29. package/dist/eslint.js +30 -0
  30. package/dist/eslint.js.map +1 -0
  31. package/dist/lighthouse.d.ts +62 -0
  32. package/dist/lighthouse.d.ts.map +1 -0
  33. package/dist/lighthouse.js +68 -0
  34. package/dist/lighthouse.js.map +1 -0
  35. package/dist/prettier-next.d.ts +5 -0
  36. package/dist/prettier-next.d.ts.map +1 -0
  37. package/{src → dist}/prettier-next.js +9 -7
  38. package/dist/prettier-next.js.map +1 -0
  39. package/dist/prettier.d.ts +5 -0
  40. package/dist/prettier.d.ts.map +1 -0
  41. package/dist/prettier.js +17 -0
  42. package/dist/prettier.js.map +1 -0
  43. package/llms.txt +40 -20
  44. package/package.json +49 -12
  45. package/bin/augur-doctor.mjs +0 -1038
  46. package/src/eslint-next.js +0 -40
  47. package/src/eslint.js +0 -35
  48. package/src/lighthouse.js +0 -108
  49. package/src/prettier.js +0 -12
@@ -1,1038 +0,0 @@
1
- #!/usr/bin/env node
2
-
3
- /**
4
- * augur-doctor -- Site health check against the Augur platform standard.
5
- *
6
- * Usage:
7
- * npx augur-doctor (runs against current directory)
8
- * npx augur-doctor /path/to/site
9
- *
10
- * Checks a consumer site for alignment with the reference implementation
11
- * (ampro-online). Outputs a pass/fail/warn scorecard.
12
- *
13
- * See: https://github.com/simpleapps-com/augur-packages/wiki/guide-site-assessment
14
- */
15
-
16
- import { readFileSync, existsSync } from "node:fs";
17
- import { resolve, basename, dirname } from "node:path";
18
-
19
- // ── CLI ──────────────────────────────────────────────────────────────────────
20
-
21
- const sitePath = process.argv[2] || ".";
22
- const siteDir = resolve(sitePath);
23
-
24
- if (!existsSync(siteDir)) {
25
- console.error(`Site directory not found: ${siteDir}`);
26
- process.exit(1);
27
- }
28
-
29
- // Verify this looks like a site (has package.json)
30
- if (!existsSync(resolve(siteDir, "package.json"))) {
31
- console.error(`No package.json found in: ${siteDir}`);
32
- console.error("");
33
- console.error("Usage: augur-doctor [/path/to/site]");
34
- console.error("");
35
- console.error("Run from a site directory, or pass the path as an argument.");
36
- console.error("Examples:");
37
- console.error(" npx augur-doctor");
38
- console.error(" npx augur-doctor ./sites/pyebarker_store");
39
- process.exit(1);
40
- }
41
-
42
- const siteName = basename(siteDir);
43
-
44
- // ── Helpers ──────────────────────────────────────────────────────────────────
45
-
46
- function fileExists(relPath) {
47
- return existsSync(resolve(siteDir, relPath));
48
- }
49
-
50
- function readFile(relPath) {
51
- const fullPath = resolve(siteDir, relPath);
52
- if (!existsSync(fullPath)) return null;
53
- return readFileSync(fullPath, "utf-8");
54
- }
55
-
56
- function readJson(relPath) {
57
- const content = readFile(relPath);
58
- if (!content) return null;
59
- try {
60
- return JSON.parse(content);
61
- } catch {
62
- return null;
63
- }
64
- }
65
-
66
- /** Find a file matching any of the given relative paths. */
67
- function findFile(...candidates) {
68
- for (const c of candidates) {
69
- if (fileExists(c)) return c;
70
- }
71
- return null;
72
- }
73
-
74
- /** Check if file content contains a pattern. */
75
- function fileContains(relPath, pattern) {
76
- const content = readFile(relPath);
77
- if (!content) return false;
78
- if (typeof pattern === "string") return content.includes(pattern);
79
- return pattern.test(content);
80
- }
81
-
82
- /**
83
- * Walk up from siteDir looking for a file, stopping at a .git boundary.
84
- * Returns the relative-to-siteDir path if found, or null.
85
- */
86
- function findFileUpward(...filenames) {
87
- let dir = siteDir;
88
- const root = resolve("/");
89
- while (dir !== root) {
90
- for (const name of filenames) {
91
- const candidate = resolve(dir, name);
92
- if (existsSync(candidate)) return candidate;
93
- }
94
- // Stop at git repo root
95
- if (existsSync(resolve(dir, ".git"))) break;
96
- dir = dirname(dir);
97
- }
98
- return null;
99
- }
100
-
101
- /** Files where proxy pattern wiring commonly lives across different site layouts. */
102
- const proxyDetectionFiles = [
103
- "lib/augur-query.ts", "src/lib/augur-query.ts",
104
- "lib/augur.ts", "src/lib/augur.ts",
105
- "lib/augur-options.ts", "src/lib/augur-options.ts",
106
- "app/providers.tsx", "src/app/providers.tsx",
107
- "app/context/ReactQueryProvider.tsx", "src/app/context/ReactQueryProvider.tsx",
108
- ];
109
-
110
- /** Regex matching proxy pattern imports/usage. */
111
- const proxyPatternRegex = /createServerQueryProxy|queryAction|createAugurOptions|registerQueryAction/;
112
-
113
- // ── Results ──────────────────────────────────────────────────────────────────
114
-
115
- const results = [];
116
-
117
- function pass(id, label, detail) {
118
- results.push({ status: "PASS", id, label, detail });
119
- }
120
-
121
- function fail(id, label, detail) {
122
- results.push({ status: "FAIL", id, label, detail });
123
- }
124
-
125
- function warn(id, label, detail) {
126
- results.push({ status: "WARN", id, label, detail });
127
- }
128
-
129
- function suggest(id, label, detail) {
130
- results.push({ status: "SUGGEST", id, label, detail });
131
- }
132
-
133
- function skip(id, label, detail) {
134
- results.push({ status: "SKIP", id, label, detail });
135
- }
136
-
137
- // ── Checks ───────────────────────────────────────────────────────────────────
138
-
139
- // 1. Site config with defineSite()
140
- const configFile = findFile(
141
- "lib/augur-config.ts",
142
- "src/lib/augur-config.ts",
143
- "config/augur-config.ts"
144
- );
145
- if (configFile && fileContains(configFile, "defineSite")) {
146
- pass("site-config", "augur-config.ts with defineSite()", configFile);
147
- } else if (configFile) {
148
- warn(
149
- "site-config",
150
- "augur-config.ts exists but does not use defineSite()",
151
- configFile
152
- );
153
- } else {
154
- fail(
155
- "site-config",
156
- "augur-config.ts with defineSite()",
157
- "Expected lib/augur-config.ts"
158
- );
159
- }
160
-
161
- // 2. Server site with createServerSite()
162
- const siteFile = findFile(
163
- "lib/augur-site.ts",
164
- "src/lib/augur-site.ts",
165
- "config/augur-site.ts"
166
- );
167
- if (siteFile && fileContains(siteFile, "createServerSite")) {
168
- pass("server-site", "augur-site.ts using createServerSite()", siteFile);
169
- } else if (siteFile) {
170
- warn(
171
- "server-site",
172
- "augur-site.ts exists but does not use createServerSite()",
173
- siteFile
174
- );
175
- } else {
176
- fail(
177
- "server-site",
178
- "augur-site.ts using createServerSite()",
179
- "Expected lib/augur-site.ts"
180
- );
181
- }
182
-
183
- // 3. Actions re-export
184
- const actionsFile = findFile(
185
- "lib/augur-actions.ts",
186
- "src/lib/augur-actions.ts",
187
- "lib/actions.ts"
188
- );
189
- if (actionsFile && fileContains(actionsFile, /site\.actions|actions\./)) {
190
- pass("actions", "augur-actions.ts re-exporting site.actions", actionsFile);
191
- } else if (actionsFile) {
192
- warn(
193
- "actions",
194
- "augur-actions.ts exists but may not re-export site.actions",
195
- actionsFile
196
- );
197
- } else {
198
- // Migrated sites using createServerQueryProxy don't need augur-actions.ts
199
- const usesProxyPattern = proxyDetectionFiles
200
- .some((f) => fileExists(f) && fileContains(f, proxyPatternRegex));
201
-
202
- if (usesProxyPattern) {
203
- pass("actions", "Using proxy pattern (augur-actions.ts not needed)", "");
204
- } else {
205
- fail(
206
- "actions",
207
- "augur-actions.ts re-exporting site.actions.*",
208
- "Expected lib/augur-actions.ts or createServerQueryProxy usage"
209
- );
210
- }
211
- }
212
-
213
- // 4. Client hooks with createSiteHooks()
214
- const hooksFile = findFile(
215
- "lib/augur.ts",
216
- "src/lib/augur.ts",
217
- "lib/augur-hooks.ts",
218
- "src/lib/augur-hooks.ts"
219
- );
220
- if (hooksFile && fileContains(hooksFile, "createSiteHooks")) {
221
- pass("site-hooks", "augur.ts with createSiteHooks()", hooksFile);
222
- } else if (
223
- hooksFile &&
224
- fileContains(hooksFile, /AugurHooksProvider|augur-hooks/)
225
- ) {
226
- pass(
227
- "site-hooks",
228
- "augur.ts with hooks setup",
229
- hooksFile
230
- );
231
- } else if (hooksFile) {
232
- warn(
233
- "site-hooks",
234
- "augur.ts exists but does not use createSiteHooks()",
235
- hooksFile
236
- );
237
- } else {
238
- fail(
239
- "site-hooks",
240
- "augur.ts with createSiteHooks()",
241
- "Expected lib/augur.ts"
242
- );
243
- }
244
-
245
- // 5. SSR prefetch options
246
- const optionsFile = findFile(
247
- "lib/augur-options.ts",
248
- "src/lib/augur-options.ts"
249
- );
250
- if (optionsFile && fileContains(optionsFile, /Options/)) {
251
- pass("ssr-options", "augur-options.ts for SSR prefetching", optionsFile);
252
- } else if (optionsFile) {
253
- warn(
254
- "ssr-options",
255
- "augur-options.ts exists but may not export options",
256
- optionsFile
257
- );
258
- } else {
259
- fail(
260
- "ssr-options",
261
- "augur-options.ts for SSR prefetching",
262
- "Expected lib/augur-options.ts"
263
- );
264
- }
265
-
266
- // 6. tsconfig extends augur-config
267
- const tsconfig = readJson("tsconfig.json");
268
- if (tsconfig) {
269
- const extendsVal = tsconfig.extends || "";
270
- if (extendsVal.includes("augur-config/tsconfig/next")) {
271
- pass(
272
- "tsconfig",
273
- "tsconfig.json extends augur-config/tsconfig/next",
274
- ""
275
- );
276
- } else if (extendsVal.includes("augur-config")) {
277
- warn(
278
- "tsconfig",
279
- "tsconfig.json extends augur-config but not /tsconfig/next",
280
- `extends: ${extendsVal}`
281
- );
282
- } else {
283
- fail(
284
- "tsconfig",
285
- "tsconfig.json extends augur-config/tsconfig/next",
286
- extendsVal ? `extends: ${extendsVal}` : "No extends field"
287
- );
288
- }
289
- } else {
290
- fail("tsconfig", "tsconfig.json exists", "File not found");
291
- }
292
-
293
- // 7. ESLint uses shared config
294
- const eslintFile = findFile("eslint.config.mjs", "eslint.config.js");
295
- if (eslintFile && fileContains(eslintFile, "augur-config/eslint")) {
296
- pass("eslint", "eslint.config.mjs uses augur-config/eslint/next", eslintFile);
297
- } else if (eslintFile) {
298
- fail(
299
- "eslint",
300
- "eslint.config.mjs uses augur-config/eslint/next",
301
- "Config exists but does not import augur-config/eslint"
302
- );
303
- } else if (
304
- findFile(".eslintrc.json", ".eslintrc.js", ".eslintrc", ".eslintrc.cjs")
305
- ) {
306
- fail(
307
- "eslint",
308
- "eslint.config.mjs uses augur-config/eslint/next",
309
- "Site uses legacy .eslintrc format -- migrate to eslint.config.mjs"
310
- );
311
- } else {
312
- fail("eslint", "eslint.config.mjs exists", "No ESLint config found");
313
- }
314
-
315
- // 7b. ESLint: no-deprecated rule
316
- if (eslintFile) {
317
- const eslintContent = readFile(eslintFile);
318
- if (eslintContent && /no-deprecated["']?\s*:\s*["'](error|warn)["']/.test(eslintContent)) {
319
- pass("eslint-deprecated", "ESLint: no-deprecated rule enabled", "");
320
- } else if (eslintContent && eslintContent.includes("no-deprecated")) {
321
- warn(
322
- "eslint-deprecated",
323
- "ESLint: no-deprecated found but may not be warn/error",
324
- "Set @typescript-eslint/no-deprecated to warn or error"
325
- );
326
- } else {
327
- fail(
328
- "eslint-deprecated",
329
- "ESLint: @typescript-eslint/no-deprecated rule",
330
- 'Add "@typescript-eslint/no-deprecated": "warn" to eslint.config.mjs rules'
331
- );
332
- }
333
- } else {
334
- skip("eslint-deprecated", "ESLint: no-deprecated rule", "No ESLint config found");
335
- }
336
-
337
- // Read package.json early — needed by prettier, icons, tailwind, and quality checks.
338
- const pkg = readJson("package.json");
339
-
340
- // 7c. Prettier uses shared config
341
- const prettierFile = findFile(
342
- "prettier.config.mjs",
343
- "prettier.config.js",
344
- ".prettierrc.mjs",
345
- ".prettierrc.js"
346
- );
347
- if (prettierFile && fileContains(prettierFile, "augur-config/prettier")) {
348
- pass("prettier", "Prettier uses augur-config/prettier preset", prettierFile);
349
- } else if (prettierFile) {
350
- fail(
351
- "prettier",
352
- "Prettier uses augur-config/prettier preset",
353
- "Config exists but does not import augur-config/prettier"
354
- );
355
- } else if (pkg?.prettier) {
356
- fail(
357
- "prettier",
358
- "Prettier uses augur-config/prettier preset",
359
- "Prettier config is inline in package.json -- move to prettier.config.mjs"
360
- );
361
- } else if (findFile(".prettierrc", ".prettierrc.json", ".prettierrc.yaml")) {
362
- fail(
363
- "prettier",
364
- "Prettier uses augur-config/prettier preset",
365
- "Site uses static prettier config -- migrate to prettier.config.mjs with augur-config/prettier"
366
- );
367
- } else {
368
- fail("prettier", "Prettier config exists", "No Prettier config found");
369
- }
370
-
371
- // 7d. Knip for dead code detection
372
- const knipConfigFile = findFile(
373
- "knip.json",
374
- "knip.jsonc",
375
- "knip.ts",
376
- "knip.config.ts",
377
- "knip.config.js"
378
- );
379
- const hasKnipDep = !!(pkg?.devDependencies?.knip || pkg?.dependencies?.knip);
380
- if (knipConfigFile && hasKnipDep) {
381
- pass("knip", "Knip configured for dead code detection", knipConfigFile);
382
- } else if (hasKnipDep && !knipConfigFile) {
383
- warn(
384
- "knip",
385
- "Knip installed but no config file found",
386
- "Add knip.json or knip.ts -- see https://knip.dev/overview/configuration"
387
- );
388
- } else if (knipConfigFile && !hasKnipDep) {
389
- fail(
390
- "knip",
391
- "Knip for dead code detection",
392
- "Config exists but knip not in devDependencies -- run pnpm add -D knip"
393
- );
394
- } else {
395
- fail(
396
- "knip",
397
- "Knip for dead code detection",
398
- "Add knip to devDependencies and create knip.json -- see https://knip.dev"
399
- );
400
- }
401
-
402
- // 8-12. next.config checks
403
- const nextConfigFile = findFile(
404
- "next.config.ts",
405
- "next.config.mjs",
406
- "next.config.js"
407
- );
408
- if (nextConfigFile) {
409
- const nextConfig = readFile(nextConfigFile);
410
-
411
- // 8. serverExternalPackages: no augur-server
412
- if (nextConfig.includes("serverExternalPackages")) {
413
- if (nextConfig.includes("augur-server")) {
414
- fail(
415
- "next-external",
416
- "next.config: augur-server NOT in serverExternalPackages",
417
- "augur-server must be bundled, not externalized"
418
- );
419
- } else {
420
- pass(
421
- "next-external",
422
- "next.config: serverExternalPackages correct",
423
- ""
424
- );
425
- }
426
-
427
- // Check for ioredis (if site uses Redis)
428
- const pkg = readJson("package.json");
429
- const hasIoredis =
430
- pkg?.dependencies?.ioredis || pkg?.devDependencies?.ioredis;
431
- if (hasIoredis && !nextConfig.includes("ioredis")) {
432
- warn(
433
- "next-ioredis",
434
- "next.config: ioredis should be in serverExternalPackages",
435
- "Site uses ioredis but it is not externalized"
436
- );
437
- } else if (hasIoredis) {
438
- pass("next-ioredis", "next.config: ioredis in serverExternalPackages", "");
439
- } else {
440
- skip("next-ioredis", "next.config: ioredis check", "Site does not use ioredis");
441
- }
442
- } else {
443
- warn(
444
- "next-external",
445
- "next.config: no serverExternalPackages found",
446
- "Add serverExternalPackages for native Node modules"
447
- );
448
- skip("next-ioredis", "next.config: ioredis check", "No serverExternalPackages");
449
- }
450
-
451
- // 9. Security headers
452
- if (
453
- nextConfig.includes("Strict-Transport-Security") &&
454
- nextConfig.includes("X-Content-Type-Options") &&
455
- nextConfig.includes("Permissions-Policy")
456
- ) {
457
- pass("next-headers", "next.config: security headers", "");
458
- } else if (nextConfig.includes("headers")) {
459
- warn(
460
- "next-headers",
461
- "next.config: security headers incomplete",
462
- "Missing HSTS, X-Content-Type-Options, or Permissions-Policy"
463
- );
464
- } else {
465
- fail(
466
- "next-headers",
467
- "next.config: security headers",
468
- "No headers() function found"
469
- );
470
- }
471
-
472
- // 10. optimizePackageImports
473
- if (nextConfig.includes("optimizePackageImports")) {
474
- pass("next-optimize", "next.config: optimizePackageImports", "");
475
- } else {
476
- fail(
477
- "next-optimize",
478
- "next.config: optimizePackageImports",
479
- "Add experimental.optimizePackageImports for augur packages"
480
- );
481
- }
482
-
483
- // 11. reactStrictMode
484
- if (nextConfig.includes("reactStrictMode")) {
485
- pass("next-strict", "next.config: reactStrictMode", "");
486
- } else {
487
- warn(
488
- "next-strict",
489
- "next.config: reactStrictMode not set",
490
- "Recommended for development error detection"
491
- );
492
- }
493
- } else {
494
- fail("next-external", "next.config exists", "No next.config found");
495
- skip("next-ioredis", "next.config: ioredis check", "No next.config");
496
- fail("next-headers", "next.config: security headers", "No next.config");
497
- fail("next-optimize", "next.config: optimizePackageImports", "No next.config");
498
- skip("next-strict", "next.config: reactStrictMode", "No next.config");
499
- }
500
-
501
- // 12. SDK contract tests
502
- const hasContractTests =
503
- fileExists("__tests__/sdk-contracts") ||
504
- fileExists("src/__tests__/sdk-contracts") ||
505
- fileExists("__tests__/sdk-contract.test.ts") ||
506
- fileExists("src/__tests__/sdk-contract.test.ts");
507
- if (hasContractTests) {
508
- pass("contract-tests", "SDK contract tests present", "");
509
- } else {
510
- fail(
511
- "contract-tests",
512
- "SDK contract tests in __tests__/sdk-contracts/",
513
- "No contract tests found"
514
- );
515
- }
516
-
517
- // 13. No custom AugurClient wrapper
518
- const libDir = findFile("lib", "src/lib");
519
- if (libDir) {
520
- const augurClientFile = findFile(
521
- "lib/augur-client.ts",
522
- "src/lib/augur-client.ts",
523
- "lib/augurClient.ts",
524
- "src/lib/augurClient.ts"
525
- );
526
- if (augurClientFile) {
527
- const content = readFile(augurClientFile);
528
- // Check for wrapper patterns that suggest custom SDK wrapping
529
- if (
530
- content &&
531
- (content.includes("class AugurClient") ||
532
- content.includes("extends AugurAPI"))
533
- ) {
534
- fail(
535
- "no-wrapper",
536
- "No custom AugurClient wrapper",
537
- `${augurClientFile} wraps AugurAPI -- use augur-api directly`
538
- );
539
- } else {
540
- pass(
541
- "no-wrapper",
542
- "No custom AugurClient wrapper",
543
- augurClientFile ? "Uses augur-api directly" : ""
544
- );
545
- }
546
- } else {
547
- pass("no-wrapper", "No custom AugurClient wrapper", "");
548
- }
549
- } else {
550
- skip("no-wrapper", "No custom AugurClient wrapper", "No lib/ directory");
551
- }
552
-
553
- // 14. Auth uses site.auth or createAuthConfig
554
- const authFile = findFile(
555
- "auth.ts",
556
- "lib/auth.ts",
557
- "src/lib/auth.ts",
558
- "src/auth.ts"
559
- );
560
- if (authFile) {
561
- const authContent = readFile(authFile);
562
- if (
563
- authContent &&
564
- (authContent.includes("site.auth") ||
565
- authContent.includes("createAuthConfig") ||
566
- authContent.includes("createServerSite"))
567
- ) {
568
- pass(
569
- "auth",
570
- "Auth uses createAuthConfig or site.auth",
571
- authFile
572
- );
573
- } else if (authContent && authContent.includes("NextAuth")) {
574
- fail(
575
- "auth",
576
- "Auth uses createAuthConfig or site.auth",
577
- `${authFile} uses raw NextAuth -- migrate to createAuthConfig()`
578
- );
579
- } else {
580
- warn("auth", "Auth pattern unclear", authFile);
581
- }
582
- } else {
583
- warn("auth", "No auth.ts found", "Expected auth.ts or lib/auth.ts");
584
- }
585
-
586
- // 15. Image loader for agr.media CDN
587
- if (nextConfigFile) {
588
- const nextConfig = readFile(nextConfigFile);
589
- if (nextConfig.includes("agr.media") || nextConfig.includes("agrMedia")) {
590
- pass("image-loader", "Image loader for agr.media CDN", "");
591
- } else if (nextConfig.includes("images")) {
592
- warn(
593
- "image-loader",
594
- "next.config has images config but no agr.media",
595
- "Add agr.media to remotePatterns if site has product images"
596
- );
597
- } else {
598
- warn(
599
- "image-loader",
600
- "No image configuration found",
601
- "Add agr.media CDN to next.config images.remotePatterns"
602
- );
603
- }
604
- } else {
605
- skip("image-loader", "Image loader check", "No next.config");
606
- }
607
-
608
- // 16. Quality script
609
- if (pkg?.scripts?.quality) {
610
- const quality = pkg.scripts.quality;
611
- if (
612
- quality.includes("typecheck") &&
613
- quality.includes("lint") &&
614
- quality.includes("test")
615
- ) {
616
- pass("quality-script", "quality script: typecheck + lint + test", "");
617
- } else {
618
- warn(
619
- "quality-script",
620
- "quality script exists but may be incomplete",
621
- `"quality": "${quality}"`
622
- );
623
- }
624
- } else {
625
- fail(
626
- "quality-script",
627
- "quality script in package.json",
628
- 'Add "quality": "pnpm typecheck && pnpm lint && pnpm test"'
629
- );
630
- }
631
-
632
- // 17. Icons: react-icons (not heroicons or lucide-react)
633
- if (pkg) {
634
- const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
635
- const hasReactIcons = !!allDeps["react-icons"];
636
- const hasHeroicons = !!allDeps["@heroicons/react"];
637
- const hasLucide = !!allDeps["lucide-react"];
638
-
639
- if (hasReactIcons && !hasHeroicons && !hasLucide) {
640
- pass("icons", "Uses react-icons (platform standard)", "");
641
- } else if (hasHeroicons) {
642
- fail(
643
- "icons",
644
- "Uses react-icons (platform standard)",
645
- "Site uses @heroicons/react -- migrate to react-icons/lu"
646
- );
647
- } else if (hasLucide) {
648
- fail(
649
- "icons",
650
- "Uses react-icons (platform standard)",
651
- "Site uses lucide-react -- migrate to react-icons/lu"
652
- );
653
- } else if (!hasReactIcons) {
654
- warn("icons", "No icon library found", "Expected react-icons");
655
- }
656
- }
657
-
658
- // 18. Tailwind v4
659
- if (pkg) {
660
- const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
661
- const tailwindVersion = allDeps["tailwindcss"] || "";
662
- if (tailwindVersion.startsWith("^4") || tailwindVersion.startsWith("4")) {
663
- pass("tailwind", "Tailwind v4 (platform standard)", "");
664
- } else if (
665
- tailwindVersion.startsWith("^3") ||
666
- tailwindVersion.startsWith("3")
667
- ) {
668
- fail(
669
- "tailwind",
670
- "Tailwind v4",
671
- `Found tailwindcss: ${tailwindVersion} -- upgrade to ^4.0.0`
672
- );
673
- } else if (tailwindVersion) {
674
- warn("tailwind", "Tailwind version unclear", `tailwindcss: ${tailwindVersion}`);
675
- } else {
676
- warn("tailwind", "No tailwindcss dependency found", "");
677
- }
678
- }
679
-
680
- // 19. Pre-commit hooks (lefthook + lint-staged)
681
- // Check site dir first, then walk up for monorepo layouts
682
- const lefthookFile = findFile("lefthook.yml", ".lefthook.yml")
683
- || findFileUpward("lefthook.yml", ".lefthook.yml");
684
- const hasLefthookDep = !!(pkg?.devDependencies?.lefthook || pkg?.dependencies?.lefthook);
685
- if (lefthookFile || hasLefthookDep) {
686
- // lefthookFile may be a relative path (from findFile) or absolute (from findFileUpward)
687
- const lefthookContent = lefthookFile
688
- ? (existsSync(resolve(siteDir, lefthookFile))
689
- ? readFile(lefthookFile)
690
- : (existsSync(lefthookFile) ? readFileSync(lefthookFile, "utf-8") : null))
691
- : null;
692
- const hasPreCommit = lefthookContent && lefthookContent.includes("pre-commit");
693
- const lintStagedConfig =
694
- pkg?.["lint-staged"] ||
695
- fileExists(".lintstagedrc") ||
696
- fileExists(".lintstagedrc.json") ||
697
- fileExists("lint-staged.config.js") ||
698
- fileExists("lint-staged.config.mjs");
699
-
700
- if (hasPreCommit && lintStagedConfig) {
701
- pass("pre-commit", "Pre-commit hooks: lefthook + lint-staged", lefthookFile || "package.json");
702
- } else if (hasPreCommit) {
703
- suggest(
704
- "pre-commit",
705
- "Pre-commit hooks: lefthook found but no lint-staged config",
706
- "See https://github.com/simpleapps-com/augur-packages/wiki/guide-migration-runbook#pre-commit-hooks"
707
- );
708
- } else if (lefthookFile) {
709
- suggest(
710
- "pre-commit",
711
- "Pre-commit hooks: lefthook found but no pre-commit section",
712
- "See https://github.com/simpleapps-com/augur-packages/wiki/guide-migration-runbook#pre-commit-hooks"
713
- );
714
- } else {
715
- suggest(
716
- "pre-commit",
717
- "Pre-commit hooks: lefthook in devDependencies but no config file",
718
- "Add lefthook.yml -- see https://github.com/simpleapps-com/augur-packages/wiki/guide-migration-runbook#pre-commit-hooks"
719
- );
720
- }
721
- } else if (findFile(".husky/pre-commit", ".husky/_/pre-commit")) {
722
- suggest(
723
- "pre-commit",
724
- "Pre-commit hooks: husky found -- consider switching to lefthook",
725
- "See https://github.com/simpleapps-com/augur-packages/wiki/guide-migration-runbook#pre-commit-hooks"
726
- );
727
- } else {
728
- suggest(
729
- "pre-commit",
730
- "No pre-commit hooks found -- recommended for code quality",
731
- "See https://github.com/simpleapps-com/augur-packages/wiki/guide-migration-runbook#pre-commit-hooks"
732
- );
733
- }
734
-
735
- // ---------------------------------------------------------------------------
736
- // 20-22. Proxy adoption checks
737
- // ---------------------------------------------------------------------------
738
-
739
- // 20. Local hooks that could be replaced by createServerQueryProxy
740
- const localHooksFile = findFile(
741
- "lib/augur.ts",
742
- "src/lib/augur.ts",
743
- "hooks/augur.ts"
744
- );
745
- if (localHooksFile) {
746
- const hooksContent = readFile(localHooksFile);
747
- const hasUseQuery =
748
- hooksContent &&
749
- (hooksContent.includes("useQuery") || hooksContent.includes("useInfiniteQuery"));
750
- const hasServerAction =
751
- hooksContent &&
752
- (hooksContent.includes("unwrap(") || hooksContent.includes("serverAction") ||
753
- hooksContent.includes("augur-server/actions"));
754
-
755
- if (hasUseQuery && hasServerAction) {
756
- suggest(
757
- "proxy-local-hooks",
758
- "Local hooks wrapping server actions -- replace with createServerQueryProxy",
759
- `${localHooksFile} -- see wiki/guide-migration-runbook#proxy-migration`
760
- );
761
- } else if (hasUseQuery) {
762
- suggest(
763
- "proxy-local-hooks",
764
- "Local hooks found -- check if createServerQueryProxy can replace them",
765
- localHooksFile
766
- );
767
- } else {
768
- pass("proxy-local-hooks", "No local hook wrappers detected", "");
769
- }
770
- } else {
771
- pass("proxy-local-hooks", "No local hook wrappers detected", "");
772
- }
773
-
774
- // 21. createServerQueryProxy usage
775
- const usesServerProxy = proxyDetectionFiles.some(
776
- (f) => fileExists(f) && fileContains(f, /createServerQueryProxy|createAugurOptions/)
777
- );
778
- const usesAugurOptions = proxyDetectionFiles.some(
779
- (f) => fileExists(f) && fileContains(f, /useAugurOptions|registerQueryAction/)
780
- );
781
- if (usesServerProxy) {
782
- pass("proxy-server-query", "Uses createServerQueryProxy for data fetching", "");
783
- } else if (usesAugurOptions) {
784
- pass("proxy-server-query", "Uses useAugurOptions for data fetching", "");
785
- } else {
786
- suggest(
787
- "proxy-server-query",
788
- "No proxy-based data fetching detected",
789
- "Consider createServerQueryProxy (augur-server/hooks) or useAugurOptions (augur-hooks)"
790
- );
791
- }
792
-
793
- // 21b. QueryClient memory safety on the server (#481)
794
- // A module-scope QueryClient is shared across every request on the server.
795
- // A finite gcTime in a provider's defaultOptions starts a GC timer during SSR
796
- // that pins the whole request cache until it fires. Both leak memory.
797
- const moduleScopeClientRegex = /^(?:export\s+)?(?:const|let|var)\s+\w+\s*=\s*new QueryClient\(/m;
798
- // Allowed: Infinity, resolveGcTime(...), 0 (fires next tick). Anything else is finite.
799
- const finiteGcTimeRegex = /gcTime\s*:\s*(?!Infinity\b|resolveGcTime\(|0\b)\S/;
800
-
801
- const moduleScopeClientFiles = proxyDetectionFiles.filter(
802
- (f) => fileExists(f) && fileContains(f, moduleScopeClientRegex)
803
- );
804
- if (moduleScopeClientFiles.length > 0) {
805
- fail(
806
- "query-client-scope",
807
- "QueryClient created at module scope (shared across server requests)",
808
- `${moduleScopeClientFiles.join(", ")}: create it per request (see wiki guide-getting-started#provider-setup)`
809
- );
810
- } else {
811
- pass("query-client-scope", "No module-scope QueryClient", "");
812
- }
813
-
814
- const finiteGcTimeFiles = proxyDetectionFiles.filter(
815
- (f) => fileExists(f) && fileContains(f, finiteGcTimeRegex)
816
- );
817
- if (finiteGcTimeFiles.length > 0) {
818
- fail(
819
- "query-gc-time",
820
- "Finite gcTime in provider/query setup (leaks memory during SSR)",
821
- `${finiteGcTimeFiles.join(", ")}: remove it, or wrap with resolveGcTime() from augur-core`
822
- );
823
- } else {
824
- pass("query-gc-time", "No finite gcTime in provider/query setup", "");
825
- }
826
-
827
- // 22. augur-api version
828
- if (pkg) {
829
- const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
830
- const apiVersion = allDeps["@simpleapps-com/augur-api"] || "";
831
-
832
- // Extract base version from range (strip ^, ~, >=, etc.)
833
- const versionMatch = apiVersion.match(/(\d{4})\.(\d+)\.(\d+)/);
834
-
835
- if (versionMatch) {
836
- const [, year, minor, patch] = versionMatch.map(Number);
837
- const isTypedProxy =
838
- year > 2026 ||
839
- (year === 2026 && minor > 3) ||
840
- (year === 2026 && minor === 3 && patch >= 7);
841
-
842
- if (isTypedProxy) {
843
- pass("api-version", "augur-api SDK version supports typed proxies", apiVersion);
844
- } else {
845
- warn(
846
- "api-version",
847
- "augur-api SDK may lack typed proxy support",
848
- `${apiVersion} -- upgrade to >= 2026.3.7 for typed responses`
849
- );
850
- }
851
- } else if (apiVersion) {
852
- warn("api-version", "augur-api version format not recognized", apiVersion);
853
- } else {
854
- warn("api-version", "No augur-api dependency found", "");
855
- }
856
- }
857
-
858
- // ---------------------------------------------------------------------------
859
- // 23-24. Augur package version checks
860
- // ---------------------------------------------------------------------------
861
-
862
- const augurPackageNames = [
863
- "@simpleapps-com/augur-config",
864
- "@simpleapps-com/augur-core",
865
- "@simpleapps-com/augur-hooks",
866
- "@simpleapps-com/augur-mobile",
867
- "@simpleapps-com/augur-server",
868
- "@simpleapps-com/augur-tailwind",
869
- "@simpleapps-com/augur-utils",
870
- "@simpleapps-com/augur-web",
871
- ];
872
-
873
- if (pkg) {
874
- const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
875
-
876
- // Collect installed augur packages and their version ranges
877
- const installedAugur = [];
878
- for (const name of augurPackageNames) {
879
- const version = allDeps[name];
880
- if (version) {
881
- installedAugur.push({ name, version });
882
- }
883
- }
884
-
885
- // 23. Version consistency -- all augur packages should be on the same version
886
- if (installedAugur.length >= 2) {
887
- const versions = new Set(installedAugur.map((p) => p.version));
888
- if (versions.size === 1) {
889
- pass(
890
- "augur-version-sync",
891
- "All augur packages on the same version",
892
- installedAugur[0].version
893
- );
894
- } else {
895
- const mismatchDetail = installedAugur
896
- .map((p) => `${p.name.replace("@simpleapps-com/", "")}: ${p.version}`)
897
- .join(", ");
898
- fail(
899
- "augur-version-sync",
900
- "All augur packages must be on the same version",
901
- mismatchDetail
902
- );
903
- }
904
- } else if (installedAugur.length === 1) {
905
- pass("augur-version-sync", "Single augur package installed", installedAugur[0].version);
906
- } else {
907
- skip("augur-version-sync", "Augur package version sync", "No augur packages found");
908
- }
909
-
910
- // 24. Latest version -- augur packages should be on the latest published version
911
- if (installedAugur.length > 0) {
912
- // Use augur-config as the reference (all packages share the same version)
913
- const refPkg = installedAugur[0];
914
- const refVersion = refPkg.version.replace(/^[\^~>=<\s]+/, "");
915
-
916
- try {
917
- const { execSync } = await import("node:child_process");
918
- const latestVersion = execSync(
919
- `npm view @simpleapps-com/augur-config version 2>/dev/null`,
920
- { encoding: "utf-8" }
921
- ).trim();
922
-
923
- if (latestVersion && refVersion === latestVersion) {
924
- pass(
925
- "augur-version-latest",
926
- "Augur packages on latest version",
927
- latestVersion
928
- );
929
- } else if (latestVersion) {
930
- fail(
931
- "augur-version-latest",
932
- "Augur packages should be on the latest version",
933
- `installed: ${refVersion}, latest: ${latestVersion} -- run: pnpm update ${augurPackageNames.map((n) => JSON.stringify(n)).join(" ")}`
934
- );
935
- } else {
936
- skip(
937
- "augur-version-latest",
938
- "Augur latest version check",
939
- "Could not fetch latest version from npm"
940
- );
941
- }
942
- } catch {
943
- skip(
944
- "augur-version-latest",
945
- "Augur latest version check",
946
- "Could not fetch latest version from npm (offline or not published)"
947
- );
948
- }
949
- } else {
950
- skip("augur-version-latest", "Augur latest version check", "No augur packages found");
951
- }
952
- } else {
953
- skip("augur-version-sync", "Augur package version sync", "No package.json");
954
- skip("augur-version-latest", "Augur latest version check", "No package.json");
955
- }
956
-
957
- // ── Output ───────────────────────────────────────────────────────────────────
958
-
959
- const ICONS = {
960
- PASS: "\x1b[32m[PASS]\x1b[0m",
961
- FAIL: "\x1b[31m[FAIL]\x1b[0m",
962
- WARN: "\x1b[33m[WARN]\x1b[0m",
963
- SUGGEST: "\x1b[36m[SUGGEST]\x1b[0m",
964
- SKIP: "\x1b[90m[SKIP]\x1b[0m",
965
- };
966
-
967
- console.log("");
968
- console.log(`\x1b[1mAugur Doctor: ${siteName}\x1b[0m`);
969
- console.log(`Path: ${siteDir}`);
970
- console.log("");
971
-
972
- const groups = {
973
- "Site Architecture": [
974
- "site-config",
975
- "server-site",
976
- "actions",
977
- "site-hooks",
978
- "ssr-options",
979
- ],
980
- "Config Alignment": ["tsconfig", "eslint", "eslint-deprecated", "prettier", "knip", "tailwind", "icons"],
981
- "Next.js Config": [
982
- "next-external",
983
- "next-ioredis",
984
- "next-headers",
985
- "next-optimize",
986
- "next-strict",
987
- ],
988
- "Testing & Quality": ["contract-tests", "quality-script", "pre-commit"],
989
- "Proxy Adoption": [
990
- "proxy-local-hooks",
991
- "proxy-server-query",
992
- "query-client-scope",
993
- "query-gc-time",
994
- "api-version",
995
- ],
996
- "Package Versions": ["augur-version-sync", "augur-version-latest"],
997
- "Patterns": ["no-wrapper", "auth", "image-loader"],
998
- };
999
-
1000
- for (const [groupName, ids] of Object.entries(groups)) {
1001
- console.log(`\x1b[1m${groupName}\x1b[0m`);
1002
- for (const id of ids) {
1003
- const result = results.find((r) => r.id === id);
1004
- if (!result) continue;
1005
- const icon = ICONS[result.status];
1006
- const detail = result.detail ? ` \x1b[90m${result.detail}\x1b[0m` : "";
1007
- console.log(` ${icon} ${result.label}${detail}`);
1008
- }
1009
- console.log("");
1010
- }
1011
-
1012
- // Summary
1013
- const passing = results.filter((r) => r.status === "PASS").length;
1014
- const failing = results.filter((r) => r.status === "FAIL").length;
1015
- const warnings = results.filter((r) => r.status === "WARN").length;
1016
- const suggestions = results.filter((r) => r.status === "SUGGEST").length;
1017
- const skipped = results.filter((r) => r.status === "SKIP").length;
1018
- const total = results.length - skipped - suggestions;
1019
-
1020
- console.log(
1021
- `\x1b[1mScore: ${passing}/${total}\x1b[0m` +
1022
- (failing > 0 ? ` \x1b[31m(${failing} failing)\x1b[0m` : "") +
1023
- (warnings > 0 ? ` \x1b[33m(${warnings} warnings)\x1b[0m` : "") +
1024
- (suggestions > 0 ? ` \x1b[36m(${suggestions} suggestions)\x1b[0m` : "")
1025
- );
1026
- console.log("");
1027
-
1028
- if (failing > 0) {
1029
- console.log(
1030
- "See the migration runbook for fixes:"
1031
- );
1032
- console.log(
1033
- "https://github.com/simpleapps-com/augur-packages/wiki/guide-migration-runbook"
1034
- );
1035
- console.log("");
1036
- }
1037
-
1038
- process.exit(failing > 0 ? 1 : 0);