mage-obsidian 1.1.2 → 2.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+    push:
+    pull_request:
+
+jobs:
+    unit:
+        name: Unit tests (Node ${{ matrix.node }})
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                node: ["20", "22"]
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: ${{ matrix.node }}
+            - run: npm install
+            - run: npm test
+
+    lint:
+        name: Lint & format
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: "22"
+            - run: npm install
+            - name: Typecheck
+              run: npm run typecheck
+            - name: Oxlint (fast pre-filter)
+              run: npm run lint:fast
+            - name: ESLint
+              run: npm run lint
+            - name: Prettier format check
+              run: npm run format:check

package/.github/workflows/publish.yml

@@ -1,35 +1,36 @@
 name: Publish to npm
 
 on:
-  push:
-    branches:
-      - master
+    push:
+        branches:
+            - master
 
 jobs:
-  publish:
-    runs-on: ubuntu-latest
+    publish:
+        runs-on: ubuntu-latest
+        permissions:
+            id-token: write
+            contents: read
 
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
 
-      - uses: pnpm/action-setup@v4
-        name: Install pnpm
-        with:
-          version: 9
-          run_install: false
+            - uses: pnpm/action-setup@v4
+              name: Install pnpm
+              with:
+                  version: 11
+                  run_install: false
 
-      - name: Install Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: 'pnpm'
-          registry-url: 'https://registry.npmjs.org'
+            - name: Install Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 22
+                  cache: "pnpm"
+                  registry-url: "https://registry.npmjs.org"
 
-      - name: Install dependencies
-        run: pnpm install
+            - name: Install dependencies
+              run: pnpm install
 
-      - name: Publish to npm
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: pnpm publish --no-git-checks
+            - name: Publish to npm
+              run: pnpm publish --no-git-checks

package/.oxlintrc.json

@@ -0,0 +1,19 @@
+{
+    "$schema": "./node_modules/oxlint/configuration_schema.json",
+    "ignorePatterns": [
+        "node_modules",
+        ".precompiled",
+        "src/__tests__/magento_scenarios",
+        "src/__tests__/fixtures",
+        "src/__tests__/__mocks__",
+        "src/templates"
+    ],
+    "categories": {
+        "correctness": "error"
+    },
+    "env": {
+        "node": true,
+        "browser": true,
+        "es2024": true
+    }
+}

package/.prettierignore

@@ -0,0 +1,7 @@
+node_modules
+.precompiled
+pnpm-lock.yaml
+src/__tests__/magento_scenarios
+src/__tests__/fixtures
+src/__tests__/__mocks__
+src/templates

package/.prettierrc.json

@@ -0,0 +1,7 @@
+{
+    "tabWidth": 4,
+    "printWidth": 100,
+    "semi": true,
+    "singleQuote": false,
+    "trailingComma": "all"
+}

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Jeanmarcos
+Copyright (c) 2024 Jeanmarcos Juarez
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,4 +1,5 @@
 [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/Q5Q816Z9WN)
+
 # MageObsidian JS Utils
 
 [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)

package/eslint.config.js

@@ -0,0 +1,24 @@
+import globals from "globals";
+import preset from "./src/config/eslint.js";
+
+// The build engine itself: ESM, Node runtime. Data trees under __tests__ and
+// generated/template files are not linted.
+export default [
+    {
+        ignores: [
+            "node_modules/**",
+            ".precompiled/**",
+            "src/__tests__/magento_scenarios/**",
+            "src/__tests__/fixtures/**",
+            "src/__tests__/__mocks__/**",
+            "src/templates/**",
+        ],
+    },
+    ...preset,
+    {
+        files: ["**/*.test.{js,ts}", "src/__tests__/**"],
+        languageOptions: {
+            globals: { ...globals.vitest },
+        },
+    },
+];

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "mage-obsidian",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "description": "Mage Obsidian Ultis",
-  "main": "./src/scripts/buildThemes.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mage-obsidian/js-package-utils.git"
+  },
+  "main": "./src/cli/buildThemes.ts",
   "keywords": [
     "Magento",
     "MageObsidian"
@@ -11,31 +15,53 @@
   "license": "MIT",
   "type": "module",
   "bin": {
-    "mage-obsidian:build-themes": "./src/scripts/buildThemes.js"
+    "mage-obsidian:build-themes": "./src/cli/buildThemes.ts"
   },
   "imports": {
+    "#core/*": "./src/core/*",
+    "#vite/*": "./src/vite/*",
+    "#runtime/*": "./src/runtime/*",
+    "#cli/*": "./src/cli/*",
     "#utils/*": "./src/utils/*",
-    "#config/*": "./src/config/*",
-    "#service/*": "./src/service/*"
+    "#config/*": "./src/config/*"
   },
   "exports": {
-    ".": "./src/scripts/buildThemes.js",
-    "./service/": "./src/service/",
-    "./utils/": "./src/utils/",
-    "./config/": "./src/config/",
-    "./service/*": "./src/service/*"
+    ".": "./src/cli/buildThemes.ts",
+    "./core/*": "./src/core/*",
+    "./vite/*": "./src/vite/*",
+    "./runtime/*": "./src/runtime/*",
+    "./cli/*": "./src/cli/*",
+    "./utils/*": "./src/utils/*",
+    "./config/*": "./src/config/*"
   },
   "dependencies": {
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "deepmerge": "^4.3.1",
+    "dotenv": "^16.6.1",
     "readline-sync": "^1.4.10"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
-    "jest-environment-node": "^29.7.0"
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.19.21",
+    "eslint": "^10.5.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-vue": "^10.9.2",
+    "globals": "^17.6.0",
+    "oxlint": "^1.70.0",
+    "prettier": "^3.8.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.61.1",
+    "vitest": "^3.2.6"
   },
   "scripts": {
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "lint:fast": "oxlint",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   }
 }

package/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+# esbuild (pulled in by Vitest) ships its binary via the platform-specific
+# @esbuild/<platform> package, so its postinstall script is not required.
+allowBuilds:
+    esbuild: false

package/src/cli/buildThemes.ts

@@ -0,0 +1,263 @@
+#! /usr/bin/env node
+import { Command } from "commander";
+import { execSync, spawn } from "child_process";
+import os from "os";
+import readlineSync from "readline-sync";
+import fs from "fs";
+import path from "path";
+import chalk from "chalk";
+import configResolver from "../core/configResolver.ts";
+import preCompileMagentoFiles from "../core/preCompileMagentoFiles.ts";
+import runWithConcurrency from "../utils/runWithConcurrency.ts";
+import dotenv from "dotenv";
+dotenv.config();
+
+const program = new Command();
+
+program
+    .option("--theme <theme>", "Specify the active theme")
+    .option("--dev-server", "Run the development server for a specific theme")
+    .option("--typecheck", "Type-check theme sources with vue-tsc instead of building");
+
+program.parse(process.argv);
+
+const options = program.opts();
+const themesConfig = configResolver.getMagentoConfig().themes;
+
+if (options.devServer && !options.theme) {
+    console.error(chalk.red("Error: The --theme option is required when using --dev-server."));
+    process.exit(1);
+}
+
+const theme = options.theme || "all";
+
+const executeCommand = (command) => {
+    try {
+        execSync(command, { stdio: "inherit" });
+    } catch (error) {
+        console.error(chalk.red(`Command failed: ${command}`), error);
+        process.exit(1);
+    }
+};
+
+function tryCreateEnvFile() {
+    const defaultEnvVars = {
+        VITE_SERVER_HOST: "phpfpm",
+        VITE_SERVER_PORT: "5173",
+        VITE_SERVER_SECURE: "true",
+        VITE_HMR_PATH: "/__vite_ping",
+        MAGENTO_HOST: "magento.test",
+        VITE_SERVER_ALLOWED_HOSTS: "magento.test,localhost",
+    };
+
+    console.log(chalk.blue("Creating `.env` file with default or user-provided values..."));
+
+    const envFilePath = path.resolve(process.cwd(), ".env");
+    if (fs.existsSync(envFilePath)) {
+        console.log(chalk.green(".env file already exists."));
+        return;
+    }
+
+    let envContent = "";
+    for (const [key, defaultValue] of Object.entries(defaultEnvVars)) {
+        const userInput = readlineSync.question(
+            chalk.yellow(`Enter value for ${key} (default: ${defaultValue}): `),
+            {
+                defaultInput: defaultValue,
+            },
+        );
+        envContent += `${key}=${userInput || defaultValue}\n`;
+    }
+
+    fs.writeFileSync(envFilePath, envContent);
+    console.log(chalk.green(".env file created successfully."));
+}
+
+function validateEnv() {
+    const requiredEnvVars = [
+        "VITE_SERVER_HOST",
+        "VITE_SERVER_PORT",
+        "VITE_SERVER_SECURE",
+        "VITE_HMR_PATH",
+        "MAGENTO_HOST",
+        "VITE_SERVER_ALLOWED_HOSTS",
+    ];
+    const missingEnvVars = [];
+    for (const envVar of requiredEnvVars) {
+        if (!process.env[envVar]) {
+            missingEnvVars.push(envVar);
+        }
+    }
+    if (missingEnvVars.length > 0) {
+        console.error(
+            chalk.red(`Missing required environment variables: ${missingEnvVars.join(", ")}`),
+        );
+        tryCreateEnvFile();
+        console.log(chalk.green("Please restart the script after setting up the .env file."));
+        process.exit(1);
+    }
+}
+
+/**
+ * Build a single theme in its own child process. Each child gets its own
+ * CURRENT_THEME env so several themes can build concurrently without sharing
+ * in-process state. Output is buffered and printed as a labeled block on exit
+ * to keep parallel logs readable. Never rejects — failures surface via the
+ * returned exit code so sibling builds aren't aborted.
+ *
+ * @param {string} themeName
+ * @returns {Promise<{ themeName: string, code: number }>}
+ */
+const spawnBuild = (themeName) =>
+    new Promise<{ themeName: string; code: number }>((resolve) => {
+        const child = spawn("vite build", {
+            shell: true,
+            env: { ...process.env, CURRENT_THEME: themeName },
+        });
+        const chunks = [];
+        child.stdout.on("data", (data) => chunks.push(data));
+        child.stderr.on("data", (data) => chunks.push(data));
+        const finish = (code) => {
+            console.log(chalk.cyan(`\n=== ${themeName} ===`));
+            process.stdout.write(Buffer.concat(chunks).toString());
+            if (code === 0) {
+                console.log(chalk.green(`✓ ${themeName} built`));
+            } else {
+                console.error(chalk.red(`✗ ${themeName} failed (exit ${code})`));
+            }
+            resolve({ themeName, code });
+        };
+        child.on("close", finish);
+        child.on("error", (error) => {
+            chunks.push(Buffer.from(String(error?.stack ?? error)));
+            finish(1);
+        });
+    });
+
+const buildThemes = async (themeNames) => {
+    const cores = os.cpus()?.length ?? 2;
+    const limit = Math.max(1, Math.min(themeNames.length, cores - 1));
+    console.log(
+        chalk.cyan(
+            `Building ${themeNames.length} theme(s) (concurrency ${limit}): ${themeNames.join(", ")}`,
+        ),
+    );
+
+    const results = await runWithConcurrency(
+        themeNames,
+        (themeName) => spawnBuild(themeName),
+        limit,
+    );
+
+    const failed = results.filter((result) => result.code !== 0);
+    if (failed.length > 0) {
+        console.error(
+            chalk.red(`Build failed for: ${failed.map((result) => result.themeName).join(", ")}`),
+        );
+        process.exit(1);
+    }
+};
+
+/**
+ * Type-check one assembled theme with vue-tsc. The theme's generated
+ * tsconfig.typecheck.json (materialized by precompile) carries the full
+ * `Vendor_Module::` paths, so every cross-module seam resolves. vue-tsc (not
+ * plain tsc) is required to check inside `<script setup lang="ts">` SFCs. Output
+ * is buffered and printed as a labeled block; never rejects — failures surface
+ * via the exit code so sibling themes still run.
+ *
+ * @param {string} themeName
+ * @returns {Promise<{ themeName: string, code: number }>}
+ */
+const spawnTypecheck = (themeName) =>
+    new Promise<{ themeName: string; code: number }>((resolve) => {
+        const themeDefinition = configResolver.getThemeDefinition(themeName);
+        const tsconfigPath = path.join(themeDefinition.src, "tsconfig.typecheck.json");
+        const child = spawn(`vue-tsc --noEmit -p "${tsconfigPath}"`, {
+            shell: true,
+            env: { ...process.env, CURRENT_THEME: themeName },
+        });
+        const chunks = [];
+        child.stdout.on("data", (data) => chunks.push(data));
+        child.stderr.on("data", (data) => chunks.push(data));
+        const finish = (code) => {
+            console.log(chalk.cyan(`\n=== ${themeName} (typecheck) ===`));
+            process.stdout.write(Buffer.concat(chunks).toString());
+            if (code === 0) {
+                console.log(chalk.green(`✓ ${themeName} type-checks`));
+            } else {
+                console.error(chalk.red(`✗ ${themeName} has type errors (exit ${code})`));
+            }
+            resolve({ themeName, code });
+        };
+        child.on("close", finish);
+        child.on("error", (error) => {
+            chunks.push(Buffer.from(String(error?.stack ?? error)));
+            finish(1);
+        });
+    });
+
+const typecheckThemes = async (themeNames) => {
+    // Materialize each theme's tsconfig.typecheck.json + inheritance map in-process
+    // (idempotent, cached by contract hash) before spawning vue-tsc against it.
+    for (const themeName of themeNames) {
+        await preCompileMagentoFiles(themeName);
+    }
+    console.log(
+        chalk.cyan(`Type-checking ${themeNames.length} theme(s): ${themeNames.join(", ")}`),
+    );
+
+    const results = await runWithConcurrency(
+        themeNames,
+        (themeName) => spawnTypecheck(themeName),
+        1,
+    );
+
+    const failed = results.filter((result) => result.code !== 0);
+    if (failed.length > 0) {
+        console.error(
+            chalk.red(`Type check failed for: ${failed.map((r) => r.themeName).join(", ")}`),
+        );
+        process.exit(1);
+    }
+};
+
+const runDevServer = (themeName) => {
+    console.log(chalk.cyan(`Starting development server for theme: ${themeName}`));
+    try {
+        const theme = themesConfig[themeName];
+        if (!theme) {
+            console.error(chalk.red(`Theme "${themeName}" does not exist.`));
+            process.exit(1);
+        }
+
+        process.env.CURRENT_THEME = themeName;
+        executeCommand("vite");
+    } catch (error) {
+        console.error(
+            chalk.red(`Failed to start development server for theme "${themeName}":`),
+            error,
+        );
+    }
+};
+
+validateEnv();
+
+if (options.devServer) {
+    runDevServer(theme);
+} else {
+    let themeNames;
+    if (theme === "all") {
+        themeNames = Object.keys(themesConfig);
+    } else if (themesConfig[theme]) {
+        themeNames = [theme];
+    } else {
+        console.error(chalk.red(`Theme "${theme}" does not exist.`));
+        process.exit(1);
+    }
+    if (options.typecheck) {
+        await typecheckThemes(themeNames);
+    } else {
+        await buildThemes(themeNames);
+    }
+}

package/src/config/default.ts

@@ -0,0 +1,31 @@
+import path from "node:path";
+
+// The Vite harness runs from the `vite/` dir one level below the Magento root.
+// Allow an explicit root override so the engine is not tied to that cwd layout
+// (e.g. when invoked from elsewhere or in tests).
+export const MAGENTO_ROOT = process.env.MAGE_OBSIDIAN_MAGENTO_ROOT
+    ? path.resolve(process.env.MAGE_OBSIDIAN_MAGENTO_ROOT)
+    : path.resolve(process.cwd(), "..");
+
+export const DEPENDENCY_CONFIG_FILENAME = "mage_obsidian_frontend_modules.json";
+export const MAGENTO_CONFIG_RELATIVE_PATH = "app/etc/";
+export const DEPENDENCY_CONFIG_FILE_PATH = path.resolve(
+    MAGENTO_ROOT,
+    MAGENTO_CONFIG_RELATIVE_PATH,
+    DEPENDENCY_CONFIG_FILENAME,
+);
+
+export const MODULE_WEB_PATH = "view/frontend/web/";
+export const MODULE_TEMPLATES_PATH = "view/frontend/templates";
+export const THEME_MODULE_WEB_PATH = "web/";
+export const MODULE_CSS_FOLDER = "css";
+
+export const THEME_CSS_FOLDER = "css";
+
+export const OUTPUT_THEME_DIR = "web/generated";
+export const OUTPUT_JS_DIR = "js/";
+export const OUTPUT_CSS_DIR = "css/";
+export const PRECOMPILED_FOLDER = ".precompiled";
+export const INTERCEPTORS_FOLDER = "interceptors";
+
+export const ALL_JS_VUE_FILES_WITH_INHERITANCE_FILE_NAME = "allJsVueFilesWithInheritance.json";

package/src/config/eslint.js

@@ -0,0 +1,60 @@
+import js from "@eslint/js";
+import globals from "globals";
+import pluginVue from "eslint-plugin-vue";
+import tseslint from "typescript-eslint";
+import prettier from "eslint-config-prettier/flat";
+
+/**
+ * Shared flat ESLint preset for the MageObsidian stack. Consumers spread the
+ * default export and add their own `files`/`ignores`. Every plugin is imported
+ * here (inside the mage-obsidian package), so a consuming repo only needs
+ * `eslint` itself installed — the plugins resolve relative to this file.
+ *
+ * JS today, TypeScript after the engine migration: the TS rules are scoped to
+ * `*.ts*` and the Vue `<script>` parser is already the TS parser, so `.vue`
+ * files lint whether their script block is JS or TS.
+ */
+const unusedVarsOptions = {
+    argsIgnorePattern: "^_",
+    varsIgnorePattern: "^_",
+    caughtErrors: "none",
+};
+
+export default tseslint.config(
+    js.configs.recommended,
+    {
+        languageOptions: {
+            ecmaVersion: "latest",
+            sourceType: "module",
+            globals: { ...globals.node, ...globals.browser },
+        },
+    },
+    {
+        // Plain JS (author code, engine bits not yet migrated): the base rule.
+        files: ["**/*.{js,mjs,cjs}"],
+        rules: {
+            "no-unused-vars": ["error", unusedVarsOptions],
+        },
+    },
+    {
+        files: ["**/*.{ts,mts,cts,tsx}"],
+        extends: [tseslint.configs.recommended],
+        rules: {
+            // tseslint disables the base rule for TS; use the TS-aware one so
+            // labels in function-type annotations aren't flagged as unused.
+            "@typescript-eslint/no-unused-vars": ["error", unusedVarsOptions],
+            // Lenient migration baseline: the engine is typed progressively, so
+            // explicit `any` is allowed but surfaced as a warning (ratchet
+            // target, alongside tsconfig `strict`).
+            "@typescript-eslint/no-explicit-any": "warn",
+        },
+    },
+    {
+        files: ["**/*.vue"],
+        extends: [pluginVue.configs["flat/recommended"]],
+        languageOptions: {
+            parserOptions: { parser: tseslint.parser },
+        },
+    },
+    prettier,
+);