@networkpro/web 1.1.3 → 1.4.2

package/_redirects

@@ -0,0 +1 @@
+https://www.netwk.pro/*  https://netwk.pro/:splat  301

package/eslint.config.mjs

@@ -75,6 +75,17 @@ export default [
       "jsdoc/check-types": "warn", // Checks if types in JSDoc are defined correctly
       "jsdoc/require-param": "warn", // Requires @param in JSDoc
       "jsdoc/require-returns": "warn", // Requires @returns in JSDoc
+      "jsdoc/require-jsdoc": [
+        "warn",
+        {
+          publicOnly: true,
+          require: {
+            FunctionDeclaration: true,
+            MethodDefinition: true,
+            ClassDeclaration: true,
+          },
+        },
+      ],
     },
   },
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@networkpro/web",
   "private": false,
   "sideEffects": false,
-  "version": "1.1.3",
+  "version": "1.4.2",
   "description": "Locking Down Networks, Unlocking Confidence | Security, Networking, Privacy — Network Pro Strategies",
   "keywords": [
     "security",
@@ -30,37 +30,61 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.0.0 <25",
+    "npm": ">=11.0.0 <12"
   },
-  "main": "src/app.html",
   "style": "src/lib/styles/global.min.css",
-  "scripts": {
-    "upgrade": "npx npm-check-updates -u",
-    "dev": "vite dev",
-    "build": "vite build",
-    "build:netlify": "netlify build",
-    "preview": "vite preview",
-    "prepare": "svelte-kit sync || echo ''",
-    "check": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json",
-    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json --watch",
-    "clean": "rm -rf build/* node_modules package-lock.json && npm install",
-    "format": "prettier --check .",
-    "format:fix": "prettier --write .",
-    "lint": "eslint --ext .mjs,.js,.svelte --config eslint.config.mjs .",
-    "lint:fix": "eslint --ext .mjs,.js,.svelte --config eslint.config.mjs . --fix",
-    "lint:md": "npx markdownlint-cli2 \"**/*.{md,markdown}\" \"#node_modules/**\" \"#build/**\"",
-    "lint:css": "stylelint \"**/*.{css,svelte}\" --ignore-path .stylelintignore",
-    "lint:all": "npm run lint && npm run lint:md && npm run lint:css && npm run format",
-    "test": "npm run test:all",
-    "test:all": "npm run test:client -- --run && npm run test:server -- --run",
-    "test:client": "vitest --config vitest.config.client.js",
-    "test:server": "vitest --config vitest.config.server.js",
-    "test:watch": "vitest --config vitest.config.client.js --watch",
-    "test:coverage": "npm run test:client -- --run --coverage && npm run test:server -- --run --coverage",
-    "css:bundle": "node scripts/bundleCss.js",
-    "head:flatten": "node scripts/flattenHeaders.js",
-    "head:validate": "node scripts/validateHeaders.js",
-    "checkout": "npm run test:all && npm run lint:all && npm run check"
+"scripts": {
+  "dev": "vite dev",
+  "preview": "vite preview",
+  "start": "npm run dev",
+
+  "build": "vite build",
+  "build:netlify": "netlify build",
+  "css:bundle": "node scripts/bundleCss.js",
+
+  "prepare": "svelte-kit sync || echo ''",
+  "check": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json",
+  "check:watch": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json --watch",
+  "check:env": "node scripts/checkEnv.js",
+  "check:node": "node scripts/checkNode.js",
+
+  "checkout": "npm run check:node && npm run test:all && npm run lint:all && npm run check && npm run audit:scripts",
+  "verify": "npm run checkout",
+
+  "delete": "rm -rf build .svelte-kit node_modules package-lock.json",
+  "clean": "npm run delete && npm cache clean --force && npm install",
+  "upgrade": "npx npm-check-updates -u",
+
+  "test": "npm run test:all",
+  "test:all": "npm run test:client -- --run && npm run test:server -- --run",
+  "test:client": "vitest --config vitest.config.client.js",
+  "test:server": "vitest --config vitest.config.server.js",
+  "test:watch": "vitest --config vitest.config.client.js --watch",
+  "test:coverage": "npm run test:client -- --run --coverage && npm run test:server -- --run --coverage",
+
+  "lint": "eslint . --ext .mjs,.js,.svelte",
+  "lint:fix": "eslint . --ext .mjs,.js,.svelte --fix",
+  "lint:jsdoc": "eslint . --ext .js,.mjs,.svelte --max-warnings=0",
+  "lint:css": "stylelint \"**/*.{css,svelte}\" --ignore-path .stylelintignore",
+  "lint:md": "npx markdownlint-cli2 \"**/*.{md,markdown}\" \"#node_modules/**\" \"#build/**\"",
+  "lint:all": "npm run lint && npm run lint:md && npm run lint:css && npm run format",
+  "format": "prettier --check .",
+  "format:fix": "prettier --write .",
+
+  "lhci": "lhci",
+  "lighthouse": "npm run lighthouse:local",
+  "lighthouse:local": "npm run build && npm run preview & wait-on http://localhost:4173 && npm run lhci:run",
+  "lhci:run": "lhci autorun --config=.lighthouserc.cjs",
+
+  "audit:scripts": "node scripts/auditScripts.js",
+  "head:flatten": "node scripts/flattenHeaders.js",
+  "head:validate": "node scripts/validateHeaders.js",
+
+  "postinstall": "npm run check:node"
+},
+  "dependencies": {
+    "svelte": "5.31.1"
   },
   "devDependencies": {
     "@eslint/compat": "^1.2.9",
@@ -68,21 +92,20 @@
     "@netlify/plugin-sitemap": "^0.8.1",
     "@playwright/test": "^1.52.0",
     "@sveltejs/adapter-netlify": "^5.0.2",
-    "@sveltejs/kit": "^2.21.1",
-    "@sveltejs/vite-plugin-svelte": "^5.0.3",
+    "@sveltejs/kit": "2.21.1",
+    "@sveltejs/vite-plugin-svelte": "5.0.3",
     "@testing-library/jest-dom": "^6.6.3",
-    "@testing-library/svelte": "^5.2.7",
-    "@vitest/coverage-v8": "^3.1.3",
+    "@testing-library/svelte": "^5.2.8",
+    "@vitest/coverage-v8": "^3.1.4",
     "autoprefixer": "^10.4.21",
     "browserslist": "^4.24.5",
     "eslint": "^9.27.0",
     "eslint-config-prettier": "^10.1.5",
     "eslint-plugin-jsdoc": "^50.6.17",
-    "eslint-plugin-svelte": "^3.8.1",
+    "eslint-plugin-svelte": "^3.8.2",
     "globals": "^16.1.0",
     "jsdom": "^26.1.0",
     "lightningcss": "^1.30.1",
-    "lightningcss-cli": "^1.30.1",
     "markdownlint": "^0.38.0",
     "markdownlint-cli2": "^0.18.1",
     "mdsvex": "^0.12.6",
@@ -91,18 +114,18 @@
     "postcss-html": "^1.8.0",
     "prettier": "^3.5.3",
     "prettier-plugin-svelte": "^3.4.0",
+    "semver": "^7.7.2",
     "stylelint": "^16.19.1",
     "stylelint-config-html": "^1.1.0",
     "stylelint-config-recommended": "^16.0.0",
     "stylelint-order": "^7.0.0",
-    "svelte": "^5.30.2",
     "svelte-check": "^4.2.1",
     "svelte-eslint-parser": "^1.2.0",
     "svelte-preprocess": "^6.0.3",
     "typescript": "^5.8.3",
     "vite": "^6.3.5",
     "vite-plugin-lightningcss": "^0.0.5",
-    "vitest": "^3.1.3"
+    "vitest": "^3.1.4"
   },
   "overrides": {
     "@sveltejs/kit": {

package/playwright.config.js

@@ -1,3 +1,10 @@
+/* ==========================================================================
+playwright.config.js
+
+SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
+This file is part of Network Pro.
+========================================================================== */
+
 // @ts-check
 import { defineConfig, devices } from "@playwright/test";
 
@@ -5,7 +12,8 @@ import { defineConfig, devices } from "@playwright/test";
  * @see https://playwright.dev/docs/test-configuration
  */
 export default defineConfig({
-  testDir: "./tests",
+  testDir: "./tests/e2e",
+  testMatch: "*.spec.js",
 
   /* Run tests in files in parallel */
   fullyParallel: true,

package/scripts/auditScripts.js

@@ -0,0 +1,94 @@
+/* ==========================================================================
+scripts/auditScripts.js
+
+SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
+This file is part of Network Pro.
+========================================================================== */
+
+/**
+ * Audit for untested script modules in scripts/
+ * Looks for any .js/.mjs files without a matching test in tests/
+ *
+ * @module scripts/
+ * @author SunDevil311
+ * @updated 2025-05-21
+ */
+
+import fs from "fs";
+import path from "path";
+
+const scriptsDir = path.resolve("./scripts");
+const testsDir = path.resolve("./tests");
+
+// Scripts intentionally excluded from test coverage
+const allowList = new Set([
+  "checkNode.js",
+  "auditScripts.js", // itself
+]);
+
+// Recursively gather all test files
+function getAllTestFiles(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...getAllTestFiles(fullPath));
+    } else if (
+      entry.isFile() &&
+      (entry.name.endsWith(".test.js") ||
+        entry.name.endsWith(".spec.js") ||
+        entry.name.endsWith(".test.mjs") ||
+        entry.name.endsWith(".spec.mjs"))
+    ) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+// Get base names of tested modules (no extension or test specifier)
+const testFiles = getAllTestFiles(testsDir);
+const testedModules = new Set(
+  testFiles.map((filePath) =>
+    path
+      .basename(filePath)
+      .replace(/\.test\.js$|\.spec\.js$|\.test\.mjs$|\.spec\.mjs$/, ""),
+  ),
+);
+
+// Gather all scripts (.js and .mjs)
+const scriptFiles = fs
+  .readdirSync(scriptsDir)
+  .filter((file) => file.endsWith(".js") || file.endsWith(".mjs"));
+
+const untested = scriptFiles.filter((file) => {
+  const base = file.replace(/\.(js|mjs)$/, "");
+  return !allowList.has(file) && !testedModules.has(base);
+});
+
+const pathRelative = (file) =>
+  path.relative(process.cwd(), path.join(scriptsDir, file));
+
+// Output results
+if (untested.length) {
+  console.warn("\n⚠ Untested script files detected:\n");
+
+  untested.forEach((file) => {
+    const filePath = pathRelative(file);
+    console.warn(
+      `::warning file=${filePath},line=1,col=1::Missing test file for ${file}`,
+    );
+  });
+
+  console.warn(
+    `\nAdd a corresponding test file in /tests (e.g., ${untested[0].replace(
+      /\.(js|mjs)$/,
+      ".test.js",
+    )})`,
+  );
+} else {
+  console.log("✅ All script files have corresponding tests.");
+}

package/scripts/checkEnv.js

@@ -0,0 +1,66 @@
+/* ==========================================================================
+scripts/checkEnv.js
+
+SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
+This file is part of Network Pro.
+========================================================================== */
+
+/**
+ * Utility to validate execution environment
+ * Ensures `ENV_MODE` is defined and matches allowed environments
+ *
+ * @module scripts/
+ * @author SunDevil311
+ * @updated 2025-05-21
+ */
+
+import { basename } from "path";
+import { fileURLToPath } from "url";
+
+const validEnvs = new Set(["dev", "test", "ci", "prod", "preview"]);
+
+/**
+ * Checks and returns validation for ENV_MODE
+ * @returns {{
+ *   mode: string,
+ *   valid: boolean,
+ *   wasDefaulted: boolean,
+ *   allowed: string[]
+ * }}
+ */
+export function checkEnv() {
+  const current = process.env.ENV_MODE;
+  let mode = current;
+  let valid = false;
+  let wasDefaulted = false;
+
+  if (!mode) {
+    mode = "dev";
+    process.env.ENV_MODE = mode;
+    wasDefaulted = true;
+    console.warn("⚠️ ENV_MODE not set. Defaulting to 'dev'.");
+  }
+
+  valid = validEnvs.has(mode);
+
+  if (valid) {
+    const tag = wasDefaulted ? "[info]" : "[ok]";
+    console.log(`${tag} ENV_MODE is set to: "${mode}"`);
+  } else {
+    console.error(
+      `❌ Invalid ENV_MODE "${mode}". Must be one of: ${[...validEnvs].join(", ")}`,
+    );
+  }
+
+  return {
+    mode,
+    valid,
+    wasDefaulted,
+    allowed: [...validEnvs].sort(),
+  };
+}
+
+// ✅ Run only if called directly via CLI
+if (basename(fileURLToPath(import.meta.url)) === basename(process.argv[1])) {
+  checkEnv();
+}

package/scripts/checkNode.js

@@ -0,0 +1,54 @@
+/* ==========================================================================
+scripts/checkNode.js
+
+SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
+This file is part of Network Pro.
+========================================================================== */
+
+/**
+ * Utility to check Node.js and NPM version
+ * Ensures the current environment matches the required versions from package.json
+ *
+ * @module scripts/
+ * @author SunDevil311
+ * @updated 2025-05-20
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import semver from "semver";
+
+// Load engines from package.json
+const pkg = JSON.parse(fs.readFileSync(path.resolve("./package.json"), "utf8"));
+const { node: nodeRange, npm: npmRange } = pkg.engines;
+
+// Check Node version
+if (!semver.satisfies(process.version, nodeRange)) {
+  console.error(
+    `⚠️ Node version ${process.version} does not match required range: ${nodeRange}`,
+  );
+  process.exit(1);
+}
+
+// Check NPM version
+let npmVersion;
+
+try {
+  npmVersion = execSync("npm --version").toString().trim();
+  if (!semver.satisfies(npmVersion, npmRange)) {
+    console.error(
+      `⚠️ NPM version ${npmVersion} does not match required range: ${npmRange}`,
+    );
+    process.exit(1);
+  }
+} catch (err) {
+  console.error("❌ Failed to check NPM version:", err.message);
+  process.exit(1);
+}
+
+if (!process.env.CI || process.env.VERBOSE === "true") {
+  console.log(
+    `✅ Node (${process.version}) matches ${nodeRange}, and NPM (${npmVersion}) matches ${npmRange}`,
+  );
+}

package/scripts/checkVersions.js

@@ -0,0 +1,58 @@
+/* ==========================================================================
+scripts/checkVersions.js
+
+SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
+This file is part of Network Pro.
+========================================================================== */
+
+/**
+ * Utility to check Node.js and NPM version (non-blocking)
+ * Returns version info, can be unit tested, and doesn't kill process during
+ * test runs
+ *
+ * @module scripts/
+ * @author SunDevil311
+ * @updated 2025-05-20
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import semver from "semver";
+
+/**
+ * @typedef {object} VersionCheckResult
+ * @property {string} nodeVersion
+ * @property {string} npmVersion
+ * @property {string} nodeRange
+ * @property {string} npmRange
+ * @property {boolean} nodeValid
+ * @property {boolean} npmValid
+ */
+
+/**
+ * Returns an object with validation results for Node and NPM versions.
+ *
+ * @returns {VersionCheckResult}
+ */
+export function checkVersions() {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.resolve("./package.json"), "utf8"),
+  );
+  const { node: nodeRange, npm: npmRange } = pkg.engines;
+
+  const nodeVersion = process.version;
+  const npmVersion = execSync("npm --version").toString().trim();
+
+  const nodeValid = semver.satisfies(nodeVersion, nodeRange);
+  const npmValid = semver.satisfies(npmVersion, npmRange);
+
+  return {
+    nodeVersion,
+    npmVersion,
+    nodeRange,
+    npmRange,
+    nodeValid,
+    npmValid,
+  };
+}

package/src/global.d.ts

@@ -0,0 +1,15 @@
+/* ==========================================================================
+src/global.d.ts
+
+SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
+This file is part of Network Pro.
+========================================================================== */
+
+interface BeforeInstallPromptEvent extends Event {
+  readonly platforms: string[];
+  readonly userChoice: Promise<{
+    outcome: 'accepted' | 'dismissed';
+    platform: string;
+  }>;
+  prompt(): Promise<void>;
+}

package/src/lib/components/PWAInstallButton.svelte

@@ -0,0 +1,93 @@
+<!-- ==========================================================================
+src/lib/components/PWAInstallButton.svelte
+
+SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
+This file is part of Network Pro.
+========================================================================== -->
+
+<script>
+  import { onMount } from "svelte";
+  import { fade } from "svelte/transition";
+
+  let show = false;
+
+  /** @type {BeforeInstallPromptEvent | null} */
+  let deferredPrompt = null;
+
+  /**
+   * @typedef {CustomEvent<BeforeInstallPromptEvent>} PWAInstallAvailableEvent
+   */
+
+  onMount(() => {
+    /**
+     * Listen for the custom event fired by registerServiceWorker.js
+     * to enable a custom install experience.
+     *
+     * TypeScript / svelte-check does not recognize custom events by default,
+     * so we cast the base Event to CustomEvent manually.
+     */
+    window.addEventListener(
+      "pwa-install-available",
+      (/** @type {Event} */ e) => {
+        const customEvent = /** @type {PWAInstallAvailableEvent} */ (e);
+        deferredPrompt = customEvent.detail;
+        show = true;
+      },
+    );
+  });
+
+  /**
+   * Trigger the native install prompt and handle user response
+   */
+  async function promptInstall() {
+    if (!deferredPrompt) return;
+
+    deferredPrompt.prompt();
+
+    const { outcome } = await deferredPrompt.userChoice;
+    console.log(`User response to PWA install prompt: ${outcome}`);
+
+    // Always hide the button after interaction
+    show = false;
+    deferredPrompt = null;
+  }
+</script>
+
+{#if show}
+  <button
+    id="pwa-install"
+    class="install-button"
+    on:click={promptInstall}
+    transition:fade={{ duration: 600 }}>
+    Install App
+  </button>
+{/if}
+
+<style>
+  .install-button {
+    display: block;
+    padding: 0.5rem 1rem;
+    border: none;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
+    font-size: 1rem;
+    font-weight: bold;
+    color: #000;
+    background-color: #ffc627;
+    transition: background-color 0.2s ease-in-out;
+    border-radius: 6px;
+    cursor: pointer;
+    font-family: inherit;
+    margin-left: auto;
+    margin-right: auto;
+    margin-top: 1rem;
+  }
+
+  .install-button:hover {
+    background-color: #e6b300;
+  }
+
+  .install-button:focus {
+    outline: 2px solid #000;
+    outline-offset: 2px;
+  }
+</style>

package/src/lib/components/foss/FossItemContent.svelte

@@ -6,6 +6,8 @@ This file is part of Network Pro.
 ========================================================================== -->
 
 <script>
+  /* eslint-disable svelte/no-at-html-tags */
+
   import FossFeatures from "$lib/components/foss/FossFeatures.svelte";
   // Import directly from $lib by way of image utility
   import { obtainiumPng, obtainiumWbp } from "$lib";
@@ -85,14 +87,17 @@ This file is part of Network Pro.
 
   <h3>{fossItem.headline}</h3>
 
-  {@html fossItem.headlineDescription}
+  <!-- Trusted input, from internal CMS -->
+  {@html fossItem.detailsDescription}
 
   <FossFeatures features={fossItem.features} />
 
+  <!-- Trusted input, from internal CMS -->
   {@html fossItem.detailsDescription}
 
   {#each fossItem.notes as note}
     <blockquote class="bquote">
+      <!-- Trusted input, from internal CMS -->
       {@html note}
     </blockquote>
   {/each}

package/src/lib/registerServiceWorker.js

@@ -5,25 +5,31 @@ SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
 This file is part of Network Pro.
 ========================================================================== */
 
+/**
+ * Registers the service worker and handles update lifecycle, install prompt, and
+ * browser/environment compatibility checks. This supports offline usage and PWA behavior.
+ */
 export function registerServiceWorker() {
   if ('serviceWorker' in navigator) {
     // Skip registration in Firefox during development
-    const isFirefox = navigator.userAgent.indexOf('Firefox') !== -1;
-    const isDevelopment = window.location.hostname === 'localhost' ||
-                         window.location.hostname === '127.0.0.1';
+    const isFirefox = navigator.userAgent.includes('Firefox');
+    const isDevelopment =
+      window.location.hostname === 'localhost' ||
+      window.location.hostname === '127.0.0.1';
 
     if (isFirefox && isDevelopment) {
       console.log('Service Worker registration skipped in Firefox development mode');
       return;
     }
 
-    // Wait until after the page fully loads for better performance
+    // Wait until after full page load for performance optimization
     window.addEventListener('load', () => {
-      navigator.serviceWorker.register('service-worker.js')
+      navigator.serviceWorker
+        .register('service-worker.js')
         .then((registration) => {
           console.log('Service Worker registered with scope:', registration.scope);
 
-          // Track installation of new service worker
+          // Track installation of a new service worker
           registration.addEventListener('updatefound', () => {
             const newWorker = registration.installing;
             console.log('New service worker installing...');
@@ -40,7 +46,7 @@ export function registerServiceWorker() {
               ) {
                 updatePrompted = true;
 
-                // Custom prompt: reload to update
+                // Custom prompt: ask user to reload for latest content
                 if (confirm('New content is available. Reload to update?')) {
                   window.location.reload();
                 }
@@ -52,7 +58,7 @@ export function registerServiceWorker() {
           console.error('Service Worker registration failed:', error);
         });
 
-      // Ensure page reloads when new service worker takes control
+      // Ensure the page reloads automatically when the new service worker takes control
       let refreshing = false;
       navigator.serviceWorker.addEventListener('controllerchange', () => {
         if (!refreshing) {
@@ -60,6 +66,14 @@ export function registerServiceWorker() {
           window.location.reload();
         }
       });
+
+      // Optional PWA install prompt logic
+      window.addEventListener('beforeinstallprompt', (e) => {
+        e.preventDefault();
+        window.dispatchEvent(new CustomEvent('pwa-install-available', {
+          detail: /** @type {BeforeInstallPromptEvent} */ (e)
+        }));
+      });
     });
   }
 }