@simpleapps-com/augur-config 2.0.11 → 2.0.12

package/bin/augur-doctor.mjs

@@ -0,0 +1,621 @@
+#!/usr/bin/env node
+
+/**
+ * augur-doctor -- Site health check against the Augur platform standard.
+ *
+ * Usage:
+ *   npx augur-doctor            (runs against current directory)
+ *   npx augur-doctor /path/to/site
+ *
+ * Checks a consumer site for alignment with the reference implementation
+ * (ampro-online). Outputs a pass/fail/warn scorecard.
+ *
+ * See: https://github.com/simpleapps-com/augur-packages/wiki/guide-site-assessment
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, basename } from "node:path";
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+const sitePath = process.argv[2] || ".";
+const siteDir = resolve(sitePath);
+
+if (!existsSync(siteDir)) {
+  console.error(`Site directory not found: ${siteDir}`);
+  process.exit(1);
+}
+
+// Verify this looks like a site (has package.json)
+if (!existsSync(resolve(siteDir, "package.json"))) {
+  console.error(`No package.json found in: ${siteDir}`);
+  console.error("");
+  console.error("Usage: augur-doctor [/path/to/site]");
+  console.error("");
+  console.error("Run from a site directory, or pass the path as an argument.");
+  console.error("Examples:");
+  console.error("  npx augur-doctor");
+  console.error("  npx augur-doctor ./sites/pyebarker_store");
+  process.exit(1);
+}
+
+const siteName = basename(siteDir);
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function fileExists(relPath) {
+  return existsSync(resolve(siteDir, relPath));
+}
+
+function readFile(relPath) {
+  const fullPath = resolve(siteDir, relPath);
+  if (!existsSync(fullPath)) return null;
+  return readFileSync(fullPath, "utf-8");
+}
+
+function readJson(relPath) {
+  const content = readFile(relPath);
+  if (!content) return null;
+  try {
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/** Find a file matching any of the given relative paths. */
+function findFile(...candidates) {
+  for (const c of candidates) {
+    if (fileExists(c)) return c;
+  }
+  return null;
+}
+
+/** Check if file content contains a pattern. */
+function fileContains(relPath, pattern) {
+  const content = readFile(relPath);
+  if (!content) return false;
+  if (typeof pattern === "string") return content.includes(pattern);
+  return pattern.test(content);
+}
+
+// ── Results ──────────────────────────────────────────────────────────────────
+
+const results = [];
+
+function pass(id, label, detail) {
+  results.push({ status: "PASS", id, label, detail });
+}
+
+function fail(id, label, detail) {
+  results.push({ status: "FAIL", id, label, detail });
+}
+
+function warn(id, label, detail) {
+  results.push({ status: "WARN", id, label, detail });
+}
+
+function skip(id, label, detail) {
+  results.push({ status: "SKIP", id, label, detail });
+}
+
+// ── Checks ───────────────────────────────────────────────────────────────────
+
+// 1. Site config with defineSite()
+const configFile = findFile(
+  "lib/augur-config.ts",
+  "src/lib/augur-config.ts",
+  "config/augur-config.ts"
+);
+if (configFile && fileContains(configFile, "defineSite")) {
+  pass("site-config", "augur-config.ts with defineSite()", configFile);
+} else if (configFile) {
+  warn(
+    "site-config",
+    "augur-config.ts exists but does not use defineSite()",
+    configFile
+  );
+} else {
+  fail(
+    "site-config",
+    "augur-config.ts with defineSite()",
+    "Expected lib/augur-config.ts"
+  );
+}
+
+// 2. Server site with createServerSite()
+const siteFile = findFile(
+  "lib/augur-site.ts",
+  "src/lib/augur-site.ts",
+  "config/augur-site.ts"
+);
+if (siteFile && fileContains(siteFile, "createServerSite")) {
+  pass("server-site", "augur-site.ts using createServerSite()", siteFile);
+} else if (siteFile) {
+  warn(
+    "server-site",
+    "augur-site.ts exists but does not use createServerSite()",
+    siteFile
+  );
+} else {
+  fail(
+    "server-site",
+    "augur-site.ts using createServerSite()",
+    "Expected lib/augur-site.ts"
+  );
+}
+
+// 3. Actions re-export
+const actionsFile = findFile(
+  "lib/augur-actions.ts",
+  "src/lib/augur-actions.ts",
+  "lib/actions.ts"
+);
+if (actionsFile && fileContains(actionsFile, /site\.actions|actions\./)) {
+  pass("actions", "augur-actions.ts re-exporting site.actions", actionsFile);
+} else if (actionsFile) {
+  warn(
+    "actions",
+    "augur-actions.ts exists but may not re-export site.actions",
+    actionsFile
+  );
+} else {
+  fail(
+    "actions",
+    "augur-actions.ts re-exporting site.actions.*",
+    "Expected lib/augur-actions.ts"
+  );
+}
+
+// 4. Client hooks with createSiteHooks()
+const hooksFile = findFile(
+  "lib/augur.ts",
+  "src/lib/augur.ts",
+  "lib/augur-hooks.ts",
+  "src/lib/augur-hooks.ts"
+);
+if (hooksFile && fileContains(hooksFile, "createSiteHooks")) {
+  pass("site-hooks", "augur.ts with createSiteHooks()", hooksFile);
+} else if (
+  hooksFile &&
+  fileContains(hooksFile, /AugurHooksProvider|augur-hooks/)
+) {
+  pass(
+    "site-hooks",
+    "augur.ts with hooks setup",
+    hooksFile
+  );
+} else if (hooksFile) {
+  warn(
+    "site-hooks",
+    "augur.ts exists but does not use createSiteHooks()",
+    hooksFile
+  );
+} else {
+  fail(
+    "site-hooks",
+    "augur.ts with createSiteHooks()",
+    "Expected lib/augur.ts"
+  );
+}
+
+// 5. SSR prefetch options
+const optionsFile = findFile(
+  "lib/augur-options.ts",
+  "src/lib/augur-options.ts"
+);
+if (optionsFile && fileContains(optionsFile, /Options/)) {
+  pass("ssr-options", "augur-options.ts for SSR prefetching", optionsFile);
+} else if (optionsFile) {
+  warn(
+    "ssr-options",
+    "augur-options.ts exists but may not export options",
+    optionsFile
+  );
+} else {
+  fail(
+    "ssr-options",
+    "augur-options.ts for SSR prefetching",
+    "Expected lib/augur-options.ts"
+  );
+}
+
+// 6. tsconfig extends augur-config
+const tsconfig = readJson("tsconfig.json");
+if (tsconfig) {
+  const extendsVal = tsconfig.extends || "";
+  if (extendsVal.includes("augur-config/tsconfig/next")) {
+    pass(
+      "tsconfig",
+      "tsconfig.json extends augur-config/tsconfig/next",
+      ""
+    );
+  } else if (extendsVal.includes("augur-config")) {
+    warn(
+      "tsconfig",
+      "tsconfig.json extends augur-config but not /tsconfig/next",
+      `extends: ${extendsVal}`
+    );
+  } else {
+    fail(
+      "tsconfig",
+      "tsconfig.json extends augur-config/tsconfig/next",
+      extendsVal ? `extends: ${extendsVal}` : "No extends field"
+    );
+  }
+} else {
+  fail("tsconfig", "tsconfig.json exists", "File not found");
+}
+
+// 7. ESLint uses shared config
+const eslintFile = findFile("eslint.config.mjs", "eslint.config.js");
+if (eslintFile && fileContains(eslintFile, "augur-config/eslint")) {
+  pass("eslint", "eslint.config.mjs uses augur-config/eslint/next", eslintFile);
+} else if (eslintFile) {
+  fail(
+    "eslint",
+    "eslint.config.mjs uses augur-config/eslint/next",
+    "Config exists but does not import augur-config/eslint"
+  );
+} else if (
+  findFile(".eslintrc.json", ".eslintrc.js", ".eslintrc", ".eslintrc.cjs")
+) {
+  fail(
+    "eslint",
+    "eslint.config.mjs uses augur-config/eslint/next",
+    "Site uses legacy .eslintrc format -- migrate to eslint.config.mjs"
+  );
+} else {
+  fail("eslint", "eslint.config.mjs exists", "No ESLint config found");
+}
+
+// 8-12. next.config checks
+const nextConfigFile = findFile(
+  "next.config.ts",
+  "next.config.mjs",
+  "next.config.js"
+);
+if (nextConfigFile) {
+  const nextConfig = readFile(nextConfigFile);
+
+  // 8. serverExternalPackages: no augur-server
+  if (nextConfig.includes("serverExternalPackages")) {
+    if (nextConfig.includes("augur-server")) {
+      fail(
+        "next-external",
+        "next.config: augur-server NOT in serverExternalPackages",
+        "augur-server must be bundled, not externalized"
+      );
+    } else {
+      pass(
+        "next-external",
+        "next.config: serverExternalPackages correct",
+        ""
+      );
+    }
+
+    // Check for ioredis (if site uses Redis)
+    const pkg = readJson("package.json");
+    const hasIoredis =
+      pkg?.dependencies?.ioredis || pkg?.devDependencies?.ioredis;
+    if (hasIoredis && !nextConfig.includes("ioredis")) {
+      warn(
+        "next-ioredis",
+        "next.config: ioredis should be in serverExternalPackages",
+        "Site uses ioredis but it is not externalized"
+      );
+    } else if (hasIoredis) {
+      pass("next-ioredis", "next.config: ioredis in serverExternalPackages", "");
+    } else {
+      skip("next-ioredis", "next.config: ioredis check", "Site does not use ioredis");
+    }
+  } else {
+    warn(
+      "next-external",
+      "next.config: no serverExternalPackages found",
+      "Add serverExternalPackages for native Node modules"
+    );
+    skip("next-ioredis", "next.config: ioredis check", "No serverExternalPackages");
+  }
+
+  // 9. Security headers
+  if (
+    nextConfig.includes("Strict-Transport-Security") &&
+    nextConfig.includes("X-Content-Type-Options") &&
+    nextConfig.includes("Permissions-Policy")
+  ) {
+    pass("next-headers", "next.config: security headers", "");
+  } else if (nextConfig.includes("headers")) {
+    warn(
+      "next-headers",
+      "next.config: security headers incomplete",
+      "Missing HSTS, X-Content-Type-Options, or Permissions-Policy"
+    );
+  } else {
+    fail(
+      "next-headers",
+      "next.config: security headers",
+      "No headers() function found"
+    );
+  }
+
+  // 10. optimizePackageImports
+  if (nextConfig.includes("optimizePackageImports")) {
+    pass("next-optimize", "next.config: optimizePackageImports", "");
+  } else {
+    fail(
+      "next-optimize",
+      "next.config: optimizePackageImports",
+      "Add experimental.optimizePackageImports for augur packages"
+    );
+  }
+
+  // 11. reactStrictMode
+  if (nextConfig.includes("reactStrictMode")) {
+    pass("next-strict", "next.config: reactStrictMode", "");
+  } else {
+    warn(
+      "next-strict",
+      "next.config: reactStrictMode not set",
+      "Recommended for development error detection"
+    );
+  }
+} else {
+  fail("next-external", "next.config exists", "No next.config found");
+  skip("next-ioredis", "next.config: ioredis check", "No next.config");
+  fail("next-headers", "next.config: security headers", "No next.config");
+  fail("next-optimize", "next.config: optimizePackageImports", "No next.config");
+  skip("next-strict", "next.config: reactStrictMode", "No next.config");
+}
+
+// 12. SDK contract tests
+const hasContractTests =
+  fileExists("__tests__/sdk-contracts") ||
+  fileExists("src/__tests__/sdk-contracts") ||
+  fileExists("__tests__/sdk-contract.test.ts") ||
+  fileExists("src/__tests__/sdk-contract.test.ts");
+if (hasContractTests) {
+  pass("contract-tests", "SDK contract tests present", "");
+} else {
+  fail(
+    "contract-tests",
+    "SDK contract tests in __tests__/sdk-contracts/",
+    "No contract tests found"
+  );
+}
+
+// 13. No custom AugurClient wrapper
+const libDir = findFile("lib", "src/lib");
+if (libDir) {
+  const augurClientFile = findFile(
+    "lib/augur-client.ts",
+    "src/lib/augur-client.ts",
+    "lib/augurClient.ts",
+    "src/lib/augurClient.ts"
+  );
+  if (augurClientFile) {
+    const content = readFile(augurClientFile);
+    // Check for wrapper patterns that suggest custom SDK wrapping
+    if (
+      content &&
+      (content.includes("class AugurClient") ||
+        content.includes("extends AugurAPI"))
+    ) {
+      fail(
+        "no-wrapper",
+        "No custom AugurClient wrapper",
+        `${augurClientFile} wraps AugurAPI -- use augur-api directly`
+      );
+    } else {
+      pass(
+        "no-wrapper",
+        "No custom AugurClient wrapper",
+        augurClientFile ? "Uses augur-api directly" : ""
+      );
+    }
+  } else {
+    pass("no-wrapper", "No custom AugurClient wrapper", "");
+  }
+} else {
+  skip("no-wrapper", "No custom AugurClient wrapper", "No lib/ directory");
+}
+
+// 14. Auth uses site.auth or createAuthConfig
+const authFile = findFile(
+  "auth.ts",
+  "lib/auth.ts",
+  "src/lib/auth.ts",
+  "src/auth.ts"
+);
+if (authFile) {
+  const authContent = readFile(authFile);
+  if (
+    authContent &&
+    (authContent.includes("site.auth") ||
+      authContent.includes("createAuthConfig") ||
+      authContent.includes("createServerSite"))
+  ) {
+    pass(
+      "auth",
+      "Auth uses createAuthConfig or site.auth",
+      authFile
+    );
+  } else if (authContent && authContent.includes("NextAuth")) {
+    fail(
+      "auth",
+      "Auth uses createAuthConfig or site.auth",
+      `${authFile} uses raw NextAuth -- migrate to createAuthConfig()`
+    );
+  } else {
+    warn("auth", "Auth pattern unclear", authFile);
+  }
+} else {
+  warn("auth", "No auth.ts found", "Expected auth.ts or lib/auth.ts");
+}
+
+// 15. Image loader for agr.media CDN
+if (nextConfigFile) {
+  const nextConfig = readFile(nextConfigFile);
+  if (nextConfig.includes("agr.media") || nextConfig.includes("agrMedia")) {
+    pass("image-loader", "Image loader for agr.media CDN", "");
+  } else if (nextConfig.includes("images")) {
+    warn(
+      "image-loader",
+      "next.config has images config but no agr.media",
+      "Add agr.media to remotePatterns if site has product images"
+    );
+  } else {
+    warn(
+      "image-loader",
+      "No image configuration found",
+      "Add agr.media CDN to next.config images.remotePatterns"
+    );
+  }
+} else {
+  skip("image-loader", "Image loader check", "No next.config");
+}
+
+// 16. Quality script
+const pkg = readJson("package.json");
+if (pkg?.scripts?.quality) {
+  const quality = pkg.scripts.quality;
+  if (
+    quality.includes("typecheck") &&
+    quality.includes("lint") &&
+    quality.includes("test")
+  ) {
+    pass("quality-script", "quality script: typecheck + lint + test", "");
+  } else {
+    warn(
+      "quality-script",
+      "quality script exists but may be incomplete",
+      `"quality": "${quality}"`
+    );
+  }
+} else {
+  fail(
+    "quality-script",
+    "quality script in package.json",
+    'Add "quality": "pnpm typecheck && pnpm lint && pnpm test"'
+  );
+}
+
+// 17. Icons: react-icons (not heroicons or lucide-react)
+if (pkg) {
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const hasReactIcons = !!allDeps["react-icons"];
+  const hasHeroicons = !!allDeps["@heroicons/react"];
+  const hasLucide = !!allDeps["lucide-react"];
+
+  if (hasReactIcons && !hasHeroicons && !hasLucide) {
+    pass("icons", "Uses react-icons (platform standard)", "");
+  } else if (hasHeroicons) {
+    fail(
+      "icons",
+      "Uses react-icons (platform standard)",
+      "Site uses @heroicons/react -- migrate to react-icons/lu"
+    );
+  } else if (hasLucide) {
+    fail(
+      "icons",
+      "Uses react-icons (platform standard)",
+      "Site uses lucide-react -- migrate to react-icons/lu"
+    );
+  } else if (!hasReactIcons) {
+    warn("icons", "No icon library found", "Expected react-icons");
+  }
+}
+
+// 18. Tailwind v3.4 (not v4)
+if (pkg) {
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const tailwindVersion = allDeps["tailwindcss"] || "";
+  if (tailwindVersion.startsWith("^4") || tailwindVersion.startsWith("4")) {
+    fail(
+      "tailwind",
+      "Tailwind v3.4 (not v4)",
+      `Found tailwindcss: ${tailwindVersion} -- downgrade to ^3.4`
+    );
+  } else if (
+    tailwindVersion.startsWith("^3") ||
+    tailwindVersion.startsWith("3")
+  ) {
+    pass("tailwind", "Tailwind v3.4 (platform standard)", "");
+  } else if (tailwindVersion) {
+    warn("tailwind", "Tailwind version unclear", `tailwindcss: ${tailwindVersion}`);
+  } else {
+    warn("tailwind", "No tailwindcss dependency found", "");
+  }
+}
+
+// ── Output ───────────────────────────────────────────────────────────────────
+
+const ICONS = {
+  PASS: "\x1b[32m[PASS]\x1b[0m",
+  FAIL: "\x1b[31m[FAIL]\x1b[0m",
+  WARN: "\x1b[33m[WARN]\x1b[0m",
+  SKIP: "\x1b[90m[SKIP]\x1b[0m",
+};
+
+console.log("");
+console.log(`\x1b[1mAugur Doctor: ${siteName}\x1b[0m`);
+console.log(`Path: ${siteDir}`);
+console.log("");
+
+const groups = {
+  "Site Architecture": [
+    "site-config",
+    "server-site",
+    "actions",
+    "site-hooks",
+    "ssr-options",
+  ],
+  "Config Alignment": ["tsconfig", "eslint", "tailwind", "icons"],
+  "Next.js Config": [
+    "next-external",
+    "next-ioredis",
+    "next-headers",
+    "next-optimize",
+    "next-strict",
+  ],
+  "Testing & Quality": ["contract-tests", "quality-script"],
+  "Patterns": ["no-wrapper", "auth", "image-loader"],
+};
+
+for (const [groupName, ids] of Object.entries(groups)) {
+  console.log(`\x1b[1m${groupName}\x1b[0m`);
+  for (const id of ids) {
+    const result = results.find((r) => r.id === id);
+    if (!result) continue;
+    const icon = ICONS[result.status];
+    const detail = result.detail ? `  \x1b[90m${result.detail}\x1b[0m` : "";
+    console.log(`  ${icon} ${result.label}${detail}`);
+  }
+  console.log("");
+}
+
+// Summary
+const passing = results.filter((r) => r.status === "PASS").length;
+const failing = results.filter((r) => r.status === "FAIL").length;
+const warnings = results.filter((r) => r.status === "WARN").length;
+const skipped = results.filter((r) => r.status === "SKIP").length;
+const total = results.length - skipped;
+
+console.log(
+  `\x1b[1mScore: ${passing}/${total}\x1b[0m` +
+    (failing > 0 ? ` \x1b[31m(${failing} failing)\x1b[0m` : "") +
+    (warnings > 0 ? ` \x1b[33m(${warnings} warnings)\x1b[0m` : "")
+);
+console.log("");
+
+if (failing > 0) {
+  console.log(
+    "See the migration runbook for fixes:"
+  );
+  console.log(
+    "https://github.com/simpleapps-com/augur-packages/wiki/guide-migration-runbook"
+  );
+  console.log("");
+}
+
+process.exit(failing > 0 ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-config",
-  "version": "2.0.11",
+  "version": "2.0.12",
   "description": "Shared tooling configuration presets for Augur ecommerce sites",
   "license": "MIT",
   "repository": {
@@ -9,6 +9,9 @@
     "directory": "packages/augur-config"
   },
   "type": "module",
+  "bin": {
+    "augur-doctor": "./bin/augur-doctor.mjs"
+  },
   "exports": {
     "./eslint": "./src/eslint.js",
     "./eslint/next": "./src/eslint-next.js",
@@ -22,6 +25,7 @@
   },
   "files": [
     "src",
+    "bin",
     "EXPORTS.md",
     "llms.txt"
   ],