@codigodoleo/wp-kit 3.1.1 → 3.3.0

package/modules/plugin/templates/.lando.yml.hbs

@@ -0,0 +1,15 @@
+tooling:
+{{#if enable_lint}}
+  plugin-pint:
+    service: appserver
+    description: Lint PHP in the plugin
+    dir: /app/content/plugins/{{plugin_name}}
+    cmd: ./vendor/bin/pint
+{{#if plugin_lint_eslint}}
+  plugin-eslint:
+    service: build
+    description: Lint JS/TS in the plugin
+    dir: /app/content/plugins/{{plugin_name}}
+    cmd: npx eslint --fix resources/
+{{/if}}
+{{/if}}

package/modules/plugin/templates/composer.json.hbs

@@ -0,0 +1,14 @@
+{
+  "description": "{{projectDescription}} — Plugin",
+  "autoload": {
+    "psr-4": {
+      "App\\Plugins\\": "src/"
+    }
+  },
+  "require-dev": {
+    "laravel/pint": "^1.21"
+  },
+  "scripts": {
+    "lint": ["./vendor/bin/pint --test"]
+  }
+}

package/modules/plugin/templates/plugin.php.hbs

@@ -0,0 +1,15 @@
+<?php
+/**
+ * Plugin Name: {{plugin_name}}
+ * Description: {{projectDescription}}
+ * Version:     {{projectVersion}}
+ */
+
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+// Autoload via Composer
+if (file_exists(__DIR__ . '/vendor/autoload.php')) {
+    require_once __DIR__ . '/vendor/autoload.php';
+}

package/modules/sage/index.js

@@ -16,6 +16,7 @@ import { VERSION_REGISTRY, validateVersionCompatibility } from '../../lib/config
 export async function setupModule(context, generator) {
   const themeDir = path.join(context.cwd, 'content', 'themes', context.projectName);
   const relativeThemeDir = `content/themes/${context.projectName}`;
+  const relativeDevcontainerDir = '.devcontainer';
 
   try {
     // 1. Validate version compatibility
@@ -46,11 +47,17 @@ export async function setupModule(context, generator) {
     // 3. Prepare and validate directory
     await fs.ensureDir(themeDir);
     const files = await fs.readdir(themeDir);
+    let shouldInstallSage = true;
+
     if (files.length > 0) {
-      log(
-        color.orange,
-        `⚠️  Warning: ${themeDir} is not empty. Existing files may be overwritten.`
-      );
+      const alreadyInstalled = await isSageThemeInstalled(themeDir);
+      if (alreadyInstalled) {
+        shouldInstallSage = false;
+        log(color.blue, '[sage] ♻️ Existing Sage theme detected. Reusing installation.');
+      } else {
+        log(color.orange, `⚠️  ${themeDir} has stale files. Cleaning before installation.`);
+        await fs.emptyDir(themeDir);
+      }
     }
 
     // 4. Build composer command with proper error handling
@@ -63,32 +70,139 @@ export async function setupModule(context, generator) {
       '--ignore-platform-reqs',
     ].join(' ');
 
-    log(color.blue, `[sage] 📦 Installing Sage ${context.sageVersion} (${sageConfig.tag})...`);
-    log(color.blue, `[sage] 📍 Location: ${relativeThemeDir}`);
-
-    // 5. Execute installation
-    execSync(cmd, { stdio: 'inherit', cwd: context.cwd });
+    if (shouldInstallSage) {
+      log(color.blue, `[sage] 📦 Installing Sage ${context.sageVersion} (${sageConfig.tag})...`);
+      log(color.blue, `[sage] 📍 Location: ${relativeThemeDir}`);
+      execSync(cmd, { stdio: 'inherit', cwd: context.cwd });
+    }
 
     // 6. Validate theme installation
     await validateThemeInstallation(themeDir, sageConfig);
     log(color.green, `[sage] ✅ Theme installation verified`);
 
     // 7. Generate customizations
-    log(color.blue, `[sage] 📝 Generating theme customizations...`);
+    log(color.blue, '[sage] 🛠️ Applying advanced Sage DX customizations...');
+    if (context.sageVersion === '11') {
+      await generator.generateFile(
+        'theme/vite.config.js',
+        context,
+        'sage',
+        `${relativeThemeDir}/vite.config.js`
+      );
+    } else {
+      log(color.blue, '[sage] ℹ️ Keeping default Vite config for Sage 10 compatibility.');
+    }
     await generator.generateFile(
-      'theme/vite.config.js',
+      'theme/style.css',
       context,
       'sage',
-      `${relativeThemeDir}/vite.config.js`
+      `${relativeThemeDir}/style.css`
     );
+
     await generator.generateFile(
-      'theme/style.css',
+      'theme/app/Blocks/.gitkeep',
       context,
       'sage',
-      `${relativeThemeDir}/style.css`
+      `${relativeThemeDir}/app/Blocks/.gitkeep`
+    );
+    await generator.generateFile(
+      'theme/app/Fields/.gitkeep',
+      context,
+      'sage',
+      `${relativeThemeDir}/app/Fields/.gitkeep`
     );
+    await generator.generateFile(
+      'theme/resources/views/blocks/.gitkeep',
+      context,
+      'sage',
+      `${relativeThemeDir}/resources/views/blocks/.gitkeep`
+    );
+
+    await generator.mergeWithExistingFile({
+      existingFile: `${relativeThemeDir}/package.json`,
+      moduleTemplatePath: 'theme/package.json',
+      context,
+      format: 'json',
+      moduleName: 'sage',
+      mergeStrategy: 'replace',
+    });
+
+    await generator.mergeWithExistingFile({
+      existingFile: `${relativeThemeDir}/composer.json`,
+      moduleTemplatePath: 'theme/composer.json',
+      context,
+      format: 'json',
+      moduleName: 'sage',
+      mergeStrategy: 'replace',
+    });
 
-    log(color.green, `[sage] ✅ Sage theme setup completed successfully`);
+    await generator.generateFile(
+      '.devcontainer/docker-compose.override.yml',
+      context,
+      'sage',
+      `${relativeDevcontainerDir}/docker-compose.override.yml`
+    );
+    await generator.generateFile(
+      '.devcontainer/post-create.sh',
+      context,
+      'sage',
+      `${relativeDevcontainerDir}/post-create.sh`
+    );
+    await fs.chmod(path.join(context.cwd, relativeDevcontainerDir, 'post-create.sh'), 0o755);
+
+    // Unified setup scripts for Sage — shared between Lando, devcontainer and CI/CD
+    await generator.generateFile(
+      'server/cmd/setup-sage-php.sh',
+      context,
+      'sage',
+      'server/cmd/setup-sage-php.sh'
+    );
+    await generator.generateFile(
+      'server/cmd/setup-sage-node.sh',
+      context,
+      'sage',
+      'server/cmd/setup-sage-node.sh'
+    );
+    await fs.chmod(path.join(context.cwd, 'server/cmd/setup-sage-php.sh'), 0o755);
+    await fs.chmod(path.join(context.cwd, 'server/cmd/setup-sage-node.sh'), 0o755);
+
+    await generator.mergeWithExistingFile({
+      existingFile: `${relativeDevcontainerDir}/devcontainer.json`,
+      moduleTemplatePath: '.devcontainer/devcontainer.json',
+      context,
+      format: 'json',
+      moduleName: 'sage',
+      mergeStrategy: 'replace',
+    });
+
+    // 8. Lint configs co-located in theme — always installed (IDE/editor support)
+    log(color.blue, '[sage] 🔧 Installing lint configurations...');
+    await generator.copyFile(
+      'lint/.prettierrc.json',
+      'sage',
+      `${relativeThemeDir}/.prettierrc.json`
+    );
+    if (context.sage_lint_eslint !== false) {
+      await generator.copyFile(
+        'lint/eslint.config.mjs',
+        'sage',
+        `${relativeThemeDir}/eslint.config.mjs`
+      );
+    }
+    if (context.sage_lint_pint !== false) {
+      await generator.copyFile('lint/pint.json', 'sage', `${relativeThemeDir}/pint.json`);
+    }
+    if (context.sage_lint_stylelint !== false) {
+      await generator.copyFile(
+        'lint/.stylelintrc.json',
+        'sage',
+        `${relativeThemeDir}/.stylelintrc.json`
+      );
+    }
+
+    log(color.green, '[sage] ✅ Advanced Sage setup completed successfully');
+    log(color.green, `[sage] ✅ Theme directory: ${relativeThemeDir}`);
+    log(color.green, '[sage] ✅ Lando + Devcontainer command parity enabled');
   } catch (error) {
     log(color.red, `[sage] ❌ Installation failed: ${error.message}`);
     throw error;
@@ -126,3 +240,13 @@ async function validateThemeInstallation(themeDir, sageConfig) {
 
   log(color.blue, `[sage] ℹ️  Theme info: ${packageJson.name} v${packageJson.version || '1.0.0'}`);
 }
+
+async function isSageThemeInstalled(themeDir) {
+  const requiredFiles = ['package.json', 'composer.json', 'theme.json'];
+  for (const file of requiredFiles) {
+    if (!(await fs.pathExists(path.join(themeDir, file)))) {
+      return false;
+    }
+  }
+  return true;
+}

package/modules/sage/lint/.prettierrc.json

@@ -0,0 +1,12 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "overrides": [
+    { "files": "*.blade.php", "options": { "parser": "html" } },
+    { "files": "*.vue", "options": { "parser": "vue" } },
+    { "files": "*.scss", "options": { "singleQuote": false } }
+  ]
+}

package/modules/sage/lint/.stylelintrc.json

@@ -0,0 +1,7 @@
+{
+  "extends": ["stylelint-config-standard-scss"],
+  "rules": {
+    "color-hex-length": "short",
+    "string-quotes": "double"
+  }
+}

package/modules/sage/lint/eslint.config.mjs

@@ -0,0 +1,30 @@
+import js from '@eslint/js';
+import eslintConfigPrettier from 'eslint-config-prettier/flat';
+import prettierPlugin from 'eslint-plugin-prettier';
+import globals from 'globals';
+
+export default [
+  {
+    ignores: ['node_modules/**', 'vendor/**', 'public/build/**'],
+  },
+  js.configs.recommended,
+  {
+    files: ['resources/**/*.{js,mjs,ts,vue}'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+    plugins: {
+      prettier: prettierPlugin,
+    },
+    rules: {
+      'prettier/prettier': 'error',
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+    },
+  },
+  eslintConfigPrettier,
+];

package/modules/sage/lint/pint.json

@@ -0,0 +1,11 @@
+{
+  "preset": "psr12",
+  "rules": {
+    "array_syntax": {
+      "syntax": "short"
+    },
+    "binary_operator_spaces": {
+      "default": "single_space"
+    }
+  }
+}

package/modules/sage/prompts.js

@@ -2,7 +2,7 @@ export default [
   {
     type: 'confirm',
     name: 'enable_sage',
-    message: 'Enable Sage theme?',
+    message: 'Enable Sage theme (advanced setup is automatic)?',
     default: true,
   },
   {
@@ -13,4 +13,25 @@ export default [
     default: '11',
     when: (answers) => answers.enable_sage,
   },
+  {
+    type: 'confirm',
+    name: 'sage_lint_eslint',
+    message: 'Sage: enable ESLint for JS/TS/Vue?',
+    default: true,
+    when: (answers) => answers.enable_sage && answers.enable_lint,
+  },
+  {
+    type: 'confirm',
+    name: 'sage_lint_stylelint',
+    message: 'Sage: enable Stylelint for CSS/SCSS?',
+    default: true,
+    when: (answers) => answers.enable_sage && answers.enable_lint,
+  },
+  {
+    type: 'confirm',
+    name: 'sage_lint_pint',
+    message: 'Sage: enable Pint for PHP?',
+    default: true,
+    when: (answers) => answers.enable_sage && answers.enable_lint,
+  },
 ];

package/modules/sage/templates/.devcontainer/devcontainer.json.hbs

@@ -0,0 +1,7 @@
+{
+  "dockerComposeFile": [
+    "docker-compose.yml",
+    "docker-compose.override.yml"
+  ],
+  "postCreateCommand": "bash .devcontainer/setup.sh && bash .devcontainer/post-create.sh"
+}

package/modules/sage/templates/.devcontainer/docker-compose.override.yml.hbs

@@ -0,0 +1,6 @@
+services:
+  wordpress:
+    environment:
+      SAGE_THEME_DIR: /workspace/content/themes/{{projectName}}
+    ports:
+      - "3009:3009"

package/modules/sage/templates/.devcontainer/post-create.sh.hbs

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Sage devcontainer post-create — delegates to unified setup scripts.
+# Invoked from: devcontainer.json postCreateCommand.
+set -euo pipefail
+
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.."; pwd)"
+
+bash "${PROJECT_ROOT}/server/cmd/setup-sage-php.sh"
+bash "${PROJECT_ROOT}/server/cmd/setup-sage-node.sh"
+
+echo "Sage post-create bootstrap completed."

package/modules/sage/templates/.lando.yml.hbs

@@ -1,63 +1,61 @@
+services:
+  build:
+    type: node:24
+    ssl: true
+    build:
+      - bash /app/server/cmd/setup-sage-node.sh
+    scanner: false
 events:
   post-start:
-    - cd /app/content/themes/{{projectName}} && composer install --no-interaction --no-progress --optimize-autoloader
-    - cd /app/content/themes/{{projectName}} && yarn install && yarn build
+    - bash ./server/cmd/setup-sage-php.sh
+    - bash ./server/cmd/setup-sage-node.sh
     - wp theme activate {{projectName}}
-    - cd /app/content/themes/{{projectName}} && wp acorn optimize:clear && wp acorn optimize
+    - cd /app/content/themes/{{projectName}} && wp acorn optimize:clear
 tooling:
-  theme-build:
+  dev:
+    service: build
+    description: Run the Sage/Vite development server
+    cmd: npm run dev --prefix /app/content/themes/{{projectName}}
+  theme-bootstrap:
     service: appserver
-    description: "Build the Sage theme"
+    description: Install theme dependencies
     dir: /app/content/themes/{{projectName}}
     cmd:
-      - composer install --no-interaction --no-progress --optimize-autoloader
-      - yarn install
-      - yarn build
+      - appserver: bash /app/server/cmd/setup-sage-php.sh
+      - build: bash /app/server/cmd/setup-sage-node.sh
+  theme-build:
+    service: build
+    description: Build the Sage theme
+    cmd: npm run build --prefix /app/content/themes/{{projectName}}
   theme-lint:
+    service: build
+    description: Lint the Sage theme (JS/TS/Vue)
+    cmd: npm run lint --prefix /app/content/themes/{{projectName}}
+{{#if enable_lint}}
+  pint:
     service: appserver
-    description: "Lint the Sage theme"
+    description: Lint PHP in the Sage theme
     dir: /app/content/themes/{{projectName}}
-    cmd:
-      - yarn lint
-      - pint --test
-  theme-dev:
-    service: appserver
-    description: "Dev the Sage theme"
+    cmd: ./vendor/bin/pint
+  stylelint:
+    service: build
+    description: Lint CSS/SCSS in the Sage theme
+    cmd: npx stylelint --fix "resources/**/*.{css,scss}" --config /app/content/themes/{{projectName}}/.stylelintrc.json
     dir: /app/content/themes/{{projectName}}
-    cmd:
-      - yarn dev
-  acorn-make:
+{{/if}}
+  acorn:
     service: appserver
-    description: Create new Acorn classes interactively
+    description: Run Acorn artisan commands
     dir: /app/content/themes/{{projectName}}
-    cmd: wp acorn make:$ACORN_TYPE $ACORN_NAME
+    cmd: wp acorn $ACORN_COMMAND
     options:
-      type:
+      command:
         passthrough: true
         alias:
-          - t
-        describe: Type of class to create
-        interactive:
-          type: list
-          message: What type of class would you like to create?
-          choices:
-            - name: Command (Artisan command)
-              value: command
-            - name: Component (View component class)
-              value: component
-            - name: Composer (View composer class)
-              value: composer
-            - name: Provider (Service provider class)
-              value: provider
-          weight: 100
-        env: ACORN_TYPE
-      filename:
-        passthrough: true
-        alias:
-          - n
-        describe: Name of the class to create
+          - c
+        describe: Acorn command to execute
         interactive:
           type: input
-          message: What is the name of the class?
-          weight: 200
-        env: ACORN_NAME
+          message: "Acorn command (example: make:component Hero)"
+          weight: 100
+        env: ACORN_COMMAND

package/modules/sage/templates/server/cmd/setup-sage-node.sh.hbs

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Installs and builds Sage theme Node.js dependencies.
+# Invoked from: Lando (build service build step + post-start), Devcontainer (post-create.sh), CI/CD.
+set -euo pipefail
+
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+THEME_DIR="${PROJECT_ROOT}/content/themes/{{projectName}}"
+
+if [ ! -d "${THEME_DIR}" ]; then
+	echo "Theme directory not found: ${THEME_DIR}" && exit 0
+fi
+
+if [ ! -d "${THEME_DIR}/node_modules" ]; then
+	echo "Installing Sage theme Node.js dependencies..."
+	npm install --prefix "${THEME_DIR}"
+fi
+
+if [ ! -f "${THEME_DIR}/public/build/manifest.json" ]; then
+	echo "Building Sage theme..."
+	npm run build --prefix "${THEME_DIR}"
+fi
+
+echo "Sage theme Node.js setup complete."

package/modules/sage/templates/server/cmd/setup-sage-php.sh.hbs

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Installs Sage theme PHP dependencies via Composer.
+# Invoked from: Lando (post-start), Devcontainer (post-create.sh), CI/CD.
+set -euo pipefail
+
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+THEME_DIR="${PROJECT_ROOT}/content/themes/{{projectName}}"
+
+if [ ! -d "${THEME_DIR}" ]; then
+	echo "Theme directory not found: ${THEME_DIR}" && exit 0
+fi
+
+if [ -f "${THEME_DIR}/vendor/autoload.php" ]; then
+	echo "Sage PHP dependencies already installed, skipping."
+	exit 0
+fi
+
+echo "Installing Sage theme PHP dependencies..."
+composer install \
+	--working-dir="${THEME_DIR}" \
+	--no-interaction \
+	--no-progress \
+	--optimize-autoloader
+echo "Sage PHP dependencies installed."

package/modules/sage/templates/theme/composer.json.hbs

@@ -1,3 +1,25 @@
-{ "name": "{{projectName}}/wordpress", "type": "wordpress-theme", "license": "MIT", "description": "{{projectDescription}}",
-"authors": [ { "name": "{{author}}", "email": "{{authorEmail}}" } ], "support": { }, "require": {
-"php": ">={{phpVersion}}", "roots/acorn": "^5.0", "log1x/sage-directives": "^2.0" } }
+{
+	"description": "{{projectDescription}}",
+	"authors": [
+		{
+			"name": "{{author}}",
+			"email": "{{authorEmail}}"
+		}
+	],
+	"require": {
+		"php": ">={{phpVersion}}",
+		"log1x/sage-directives": "^2.0",
+		"log1x/acf-composer": "^2.0 || ^3.0"
+	},
+	"require-dev": {
+		"laravel/pint": "^1.21"
+	},
+	"scripts": {
+		"lint": [
+			"./vendor/bin/pint --test"
+		],
+		"acorn:optimize": [
+			"wp acorn optimize"
+		]
+	}
+}

package/modules/sage/templates/theme/package.json.hbs

@@ -1,3 +1,15 @@
-{ "name": "{{projectName}}", "author": "{{author}}", "description": "{{projectDescription}}",
-"version": "{{projectVersion}}", "license": "MIT", "repository": { "type": "git", "url": "{{gitRepository}}"
-} }
+{
+	"author": "{{author}}",
+	"description": "{{projectDescription}}",
+	"version": "{{projectVersion}}",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "{{gitRepository}}"
+	},
+	"scripts": {
+		"dev": "vite",
+		"build": "vite build",
+		"lint": "eslint resources --ext .js,.ts,.vue"
+	}
+}

package/modules/sage/templates/theme/vite.config.js.hbs

@@ -1,13 +1,55 @@
-import fs from 'fs'; import { defineConfig } from 'vite'; import tailwindcss from
-'@tailwindcss/vite'; import laravel from 'laravel-vite-plugin'; import { wordpressPlugin,
-wordpressThemeJson } from '@roots/vite-plugin'; export default defineConfig({ base:
-'/app/content/themes/{{projectName}}/', plugins: [ tailwindcss(), laravel({ input: [
-'resources/css/app.css', 'resources/js/app.js', 'resources/css/editor.css',
-'resources/js/editor.js', ], refresh: true, watch: { usePolling: true, interval: 1000, ignored:
-['node_modules', 'public/build/hot'], }, }), wordpressPlugin(), // Generate the theme.json file in
-the public/build/assets directory // based on the Tailwind config and the theme.json file from base
-theme folder wordpressThemeJson({ disableTailwindColors: false, disableTailwindFonts: false,
-disableTailwindFontSizes: false, }), ], resolve: { alias: { '@scripts': '/resources/js', '@styles':
-'/resources/css', '@fonts': '/resources/fonts', '@images': '/resources/images', }, }, server: {
-https: { key: fs.readFileSync('/certs/cert.key'), cert: fs.readFileSync('/certs/cert.crt'), }, host:
-true, port: 3009, hmr: { host: 'localhost', protocol: 'wss' }, }, });
+import { wordpressPlugin, wordpressThemeJson } from '@roots/vite-plugin';
+import tailwindcss from '@tailwindcss/vite';
+import fs from 'fs';
+import laravel from 'laravel-vite-plugin';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	base: '/app/content/themes/{{projectName}}/',
+	plugins: [
+		tailwindcss(),
+		laravel({
+			input: [
+				'resources/css/app.css',
+				'resources/js/app.js',
+				'resources/css/editor.css',
+				'resources/js/editor.js',
+			],
+			refresh: true,
+			watch: {
+				usePolling: true,
+				interval: 1000,
+				ignored: ['node_modules', 'public/build/hot'],
+			},
+		}),
+		wordpressPlugin(),
+		wordpressThemeJson({
+			disableTailwindColors: false,
+			disableTailwindFonts: false,
+			disableTailwindFontSizes: false,
+		}),
+	],
+	resolve: {
+		alias: {
+			'@scripts': '/resources/js',
+			'@styles': '/resources/css',
+			'@fonts': '/resources/fonts',
+			'@images': '/resources/images',
+			'@blocks': '/app/Blocks',
+			'@fields': '/app/Fields',
+		},
+	},
+	server: {
+		https: {
+			key: fs.readFileSync('/certs/cert.key'),
+			cert: fs.readFileSync('/certs/cert.crt'),
+		},
+		host: true,
+		port: 5173,
+		strictPort: true,
+		hmr: {
+			host: 'localhost',
+			protocol: 'wss',
+		},
+	},
+});