@phcdevworks/spectre-shell-wordpress 1.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,194 @@
+# Contributing to Spectre Shell WordPress
+
+Thanks for helping improve Spectre Shell! This package is a reusable template for building modern WordPress themes with Vite, TypeScript, and Tailwind CSS 4.
+
+## Development Philosophy
+
+This template follows a **build tool first** approach:
+
+### 1. Build Configuration (Vite + Tailwind)
+
+**Purpose**: Single source of truth for asset compilation and optimization
+
+**Exports**: Compiled CSS and JavaScript to `spectre-theme/dist/` with manifest
+
+**Rules**:
+
+- Vite config defines asset pipeline and WordPress integration
+- Tailwind config defines design utilities and theme
+- All source files compile through Vite
+
+**Status**: v1.0.0 with stable dev/prod mode detection and HMR support
+
+### 2. Source Assets (src/)
+
+**Purpose**: Development files for TypeScript and CSS
+
+**Ships**:
+
+- `main.ts` (JavaScript entry point)
+- `main.css` (CSS entry with Tailwind)
+- Optional token/component organization
+
+**Rules**:
+
+- Keep source minimal and well-documented
+- Import Tailwind via `@import` syntax
+- Use TypeScript for type safety
+
+**Status**: Basic structure ready for customization
+
+### 3. WordPress Theme (spectre-theme/)
+
+**Purpose**: WordPress templates and PHP functions that load Vite assets
+
+**Key mechanism**:
+
+- `functions.php` detects `WP_ENV` to switch dev/prod modes
+- Dev mode loads from Vite server with HMR
+- Prod mode loads manifest-based compiled assets
+
+**Rules**:
+
+- PHP never defines styles or scripts inline
+- All assets load through Vite's manifest or dev server
+- Follow WordPress coding standards
+
+**Status**: Basic templates with asset loading ready
+
+### Golden Rule (Non-Negotiable)
+
+**Vite builds. WordPress loads. Source never ships.**
+
+WordPress themes never ship raw source files—only compiled assets from `dist/`.
+
+- If it's a build config → belongs in `vite.config.ts` or `tailwind.config.ts`
+- If it's source code → belongs in `src/`
+- If it's WordPress PHP → belongs in `spectre-theme/`
+
+## Development Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/phcdevworks/spectre-shell-wordpress.git
+cd spectre-shell-wordpress
+```
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Build the package (compiles TypeScript and generates CSS):
+
+```bash
+npm run build
+# or for development with watch mode:
+npm run dev
+```
+
+## Project Structure
+
+```
+spectre-shell-wordpress/
+├── src/
+│   ├── js/
+│   │   └── main.ts          # JavaScript entry point
+│   └── styles/
+│       └── main.css         # CSS entry with Tailwind
+├── spectre-theme/
+│   ├── dist/                # Built assets (generated)
+│   ├── functions.php        # Theme functions & asset loading
+│   ├── header.php           # Header template
+│   ├── footer.php           # Footer template
+│   ├── index.php            # Main template
+│   └── style.css            # WordPress theme metadata
+├── vite.config.ts           # Vite configuration
+├── tailwind.config.ts       # Tailwind configuration
+└── package.json
+```
+
+**Responsibilities**:
+
+- **Theme developers**: Edit `spectre-theme/` templates and `src/` assets
+- **Config maintainers**: Update Vite and Tailwind configs
+- **Build engineers**: Update build pipeline when structure changes
+
+## Contribution Guidelines
+
+### Configuration Development
+
+1. **Never hardcode paths** – Use Node.js path resolution
+2. **Test both modes** – Verify dev server and production builds
+3. **Document changes** – Update README when config changes
+4. **Keep it minimal** – Only include necessary options
+
+### Source File Development
+
+- Use TypeScript for type safety
+- Follow modern ES module patterns
+- Add comments for complex logic
+- Import Tailwind properly with `@import 'tailwindcss'`
+- Test in dev mode with HMR
+
+### WordPress Theme Development
+
+- Follow WordPress coding standards for PHP
+- Never inline styles or scripts
+- Use proper escaping and sanitization
+- Test theme activation and asset loading
+- Ensure compatibility with latest WordPress version
+
+### Code Quality
+
+- Use modern TypeScript + ES modules
+- Follow WordPress PHP standards
+- Add comments for complex logic
+- Run `npm run build` before committing
+- Test changes in both dev and prod modes
+
+### Documentation
+
+- Update README.md when adding features
+- Include code examples for new features
+- Document breaking changes in commit messages
+- Keep inline comments clear and concise
+
+## Pull Request Process
+
+1. **Branch from `main`**
+2. **Make your changes** and test locally (`npm run build` and verify in WordPress)
+3. **Run build** to ensure compilation works (`npm run build`)
+4. **Update documentation** (README.md, comments) to reflect changes
+5. **Open a PR** describing:
+   - The motivation for the change
+   - What was changed
+   - Testing notes (WordPress version, dev/prod modes tested)
+6. **Respond to feedback** and make requested changes
+
+## Known Gaps (Not Done Yet)
+
+- Additional WordPress template files (single.php, page.php, archive.php)
+- WordPress block editor (Gutenberg) styles and support
+- Image optimization pipeline
+- Multi-language/i18n setup examples
+- Custom post type examples
+- WooCommerce integration example
+
+## Questions or Issues?
+
+Please open an issue or discussion on GitHub if you're unsure about the best approach for a change. Coordinating early avoids conflicts with:
+
+- Build configuration
+- WordPress compatibility
+- Template structure
+
+## Code of Conduct
+
+This project adheres to the [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PHCDevworks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+# @phcdevworks/spectre-shell-wordpress
+
+A reusable template for building modern WordPress themes with Vite, TypeScript, and Tailwind CSS 4. Features HMR, manifest-based asset loading, and seamless dev/prod mode switching for rapid WordPress theme development.
+
+🤝 **[Contributing Guide](CONTRIBUTING.md)** | 📝 **[Changelog](CHANGELOG.md)**
+
+## Overview
+
+`@phcdevworks/spectre-shell-wordpress` is a starter template that brings modern frontend tooling to WordPress theme development. It uses Vite for fast builds and HMR, TypeScript for type safety, and Tailwind CSS 4 for utility-first styling.
+
+- ✅ Vite-powered development with instant HMR
+- ✅ TypeScript for type-safe theme development
+- ✅ Tailwind CSS 4 with modern `@import` syntax
+- ✅ Automatic dev/prod mode detection via `WP_ENV`
+- ✅ Manifest-based asset loading with cache-busting
+- ✅ WordPress-optimized build output to `spectre-theme/dist/`
+
+## Installation
+
+```bash
+# Clone or use this template
+git clone https://github.com/phcdevworks/spectre-shell-wordpress.git
+cd spectre-shell-wordpress
+
+# Install dependencies
+npm install
+```
+
+## Usage
+
+### 1. Configure WordPress Environment
+
+Set up your WordPress installation to work with the Vite dev server:
+
+```php
+// wp-config.php
+define('WP_ENV', 'development'); // Enable dev mode
+```
+
+**How it works:**
+
+- **Development mode**: Assets load from Vite dev server (http://localhost:5173) with HMR
+- **Production mode**: Assets load from `spectre-theme/dist/` with manifest-based cache-busting
+
+### 2. Start Development Server
+
+```bash
+npm run dev
+```
+
+This starts the Vite dev server on http://localhost:5173 with HMR enabled. Edit files in `src/` and see changes instantly in your browser.
+
+### 3. Activate Theme in WordPress
+
+```bash
+# Copy or symlink theme folder to WordPress
+cp -r spectre-theme /path/to/wordpress/wp-content/themes/spectre-shell
+# Or create a symlink for development
+ln -s $(pwd)/spectre-theme /path/to/wordpress/wp-content/themes/spectre-shell
+```
+
+Then activate the theme in WordPress admin.
+
+### 4. Build for Production
+
+```bash
+npm run build
+```
+
+This compiles TypeScript, processes CSS with Tailwind, and outputs optimized assets to `spectre-theme/dist/` with a manifest for cache-busting.
+
+**Deploy:** Upload the `spectre-theme/` folder to your WordPress installation.
+
+
+## Theme Customization
+
+### Update Theme Metadata
+
+Edit `spectre-theme/style.css` with your theme details:
+
+```css
+/*
+Theme Name: Your Theme Name
+Theme URI: https://yoursite.com
+Author: Your Name
+Description: Your amazing WordPress theme
+Text Domain: your-theme-slug
+*/
+```
+
+### Replace Function Prefixes
+
+Find and replace in `spectre-theme/functions.php`:
+
+- `spectre_shell` → `your_theme_slug`
+- Function names (e.g., `spectre_shell_setup` → `yourtheme_setup`)
+
+### Customize Styles
+
+Edit `src/styles/main.css`:
+
+```css
+@import "tailwindcss";
+
+/* Your custom styles */
+:root {
+  --font-sans: system-ui, sans-serif;
+}
+
+body {
+  @apply antialiased;
+}
+
+/* WordPress alignment classes */
+.alignleft {
+  @apply float-left mr-4;
+}
+```
+
+### Add JavaScript
+
+Edit `src/js/main.ts`:
+
+```typescript
+import "../styles/main.css";
+
+// Your TypeScript code
+document.addEventListener("DOMContentLoaded", () => {
+  console.log("Theme loaded!");
+});
+```
+
+### Tailwind Configuration
+
+Customize `tailwind.config.ts`:
+
+```typescript
+import type { Config } from "tailwindcss";
+
+export default {
+  content: ["./spectre-theme/**/*.php", "./src/**/*.{js,ts,jsx,tsx}"],
+  theme: {
+    extend: {
+      colors: {
+        primary: "#your-color",
+      },
+    },
+  },
+} satisfies Config;
+```
+
+## Project Structure
+
+| Folder        | Responsibility                                                       |
+| ------------- | -------------------------------------------------------------------- |
+| `src/`        | TypeScript and CSS source files compiled by Vite                     |
+| `src/js/`     | JavaScript/TypeScript entry points                                   |
+| `src/styles/` | CSS files with Tailwind imports                                      |
+| `spectre-theme/`      | WordPress theme files (PHP templates, functions.php, style.css)      |
+| `spectre-theme/dist/` | Generated build artifacts (CSS, JS, manifest) - auto-created by Vite |
+
+**Source files** live in `src/` and compile to `spectre-theme/dist/`. Only the `spectre-theme/` folder gets deployed to WordPress.
+
+## Asset Loading
+
+### Development Mode
+
+When `WP_ENV` is set to `development`, `spectre-theme/functions.php` loads assets from the Vite dev server:
+
+```php
+wp_enqueue_script(
+    'vite-client',
+    'http://localhost:5173/@vite/client',
+    array(),
+    null,
+    false
+);
+```
+
+Changes to source files trigger instant browser updates via HMR.
+
+### Production Mode
+
+In production, assets load from the manifest file at `spectre-theme/dist/.vite/manifest.json`:
+
+```php
+$manifest = json_decode(file_get_contents(get_template_directory() . '/dist/.vite/manifest.json'), true);
+
+if (isset($manifest['src/styles/main.css'])) {
+    $css_file = $manifest['src/styles/main.css']['file'];
+    wp_enqueue_style('theme-style', get_template_directory_uri() . '/dist/' . $css_file);
+}
+```
+
+Hashed filenames ensure cache-busting on updates.
+
+## WordPress Theme Templates
+
+Add standard WordPress templates to the `spectre-theme/` folder:
+
+```
+spectre-theme/
+├── single.php       # Single post template
+├── page.php         # Page template
+├── archive.php      # Archive template
+├── 404.php          # 404 error page
+├── search.php       # Search results
+└── sidebar.php      # Sidebar
+```
+
+All templates have access to enqueued Vite assets automatically.
+
+## Build & Release
+
+```bash
+npm run build
+```
+
+The build process:
+
+1. **TypeScript compilation** - Compiles `src/js/` to optimized JavaScript
+2. **CSS processing** - Processes `src/styles/` with Tailwind and PostCSS
+3. **Asset optimization** - Minifies and generates hashed filenames
+4. **Manifest generation** - Creates `.vite/manifest.json` for asset lookup
+
+Output goes to `spectre-theme/dist/` and is ready for WordPress deployment.
+
+For release history and version notes, see the **[Changelog](CHANGELOG.md)**.
+
+## Development Philosophy
+
+This template follows a **build tool first** approach:
+
+### 1. Build Configuration (Vite + Tailwind)
+
+**Purpose**: Asset compilation pipeline for WordPress themes
+
+**Outputs**: Compiled CSS and JavaScript to `spectre-theme/dist/` with manifest
+
+**Rules**:
+
+- Vite handles all asset compilation and HMR
+- Tailwind provides utility-first CSS framework
+- All source files must go through Vite
+
+### 2. Source Assets (src/)
+
+**Purpose**: Development files for TypeScript and CSS
+
+**Contains**:
+
+- `main.ts` - JavaScript entry point
+- `main.css` - CSS entry with Tailwind imports
+- Optional component organization
+
+**Rules**:
+
+- Use TypeScript for type safety
+- Import Tailwind via `@import 'tailwindcss'`
+- Never ship raw source to production
+
+### 3. WordPress Theme (spectre-theme/)
+
+**Purpose**: WordPress templates and functions that load Vite assets
+
+**Key mechanism**:
+
+- `functions.php` detects `WP_ENV` and switches between dev/prod
+- Dev mode loads from Vite server with HMR
+- Prod mode loads from manifest
+
+**Rules**:
+
+- PHP never defines inline styles or scripts
+- All assets load through Vite's build system
+- Follow WordPress coding standards
+
+### Golden Rule (Non-Negotiable)
+
+**Vite builds. WordPress loads. Source never ships.**
+
+WordPress themes ship only compiled assets from `dist/`, never raw source files.
+
+- If it's a build config → belongs in `vite.config.ts` or `tailwind.config.ts`
+- If it's source code → belongs in `src/`
+- If it's WordPress PHP → belongs in `spectre-theme/`
+
+## Design Principles
+
+1. **Fast development** - HMR and Vite dev server for instant feedback
+2. **Type-safe** - TypeScript catches errors before runtime
+3. **Modern CSS** - Tailwind CSS 4 with utility-first approach
+4. **WordPress-native** - Standard WordPress functions and hooks
+5. **Production-ready** - Optimized builds with cache-busting
+
+## TypeScript Support
+
+Type definitions are included for Vite and WordPress globals:
+
+```typescript
+// vite-env.d.ts
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_SOME_KEY: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+```
+
+## Part of the Spectre Suite
+
+- **Spectre Tokens** - Design token foundation
+- **Spectre UI** - Core styling layer
+- **Spectre Shell WordPress** - WordPress theme template (this package)
+- **Spectre Blocks** - WordPress block library
+- **Spectre Astro** - Astro integration
+
+## Contributing
+
+Issues and pull requests are welcome. For theme template improvements, test both dev and production modes.
+
+For detailed contribution guidelines, see **[CONTRIBUTING.md](CONTRIBUTING.md)**.
+
+## License
+
+MIT © PHCDevworks — See **[LICENSE](LICENSE)** for details.
+
+---
+
+## ❤️ Support Spectre
+
+If Spectre Shell WordPress helps your workflow, consider sponsoring:
+
+- [GitHub Sponsors](https://github.com/sponsors/phcdevworks)
+- [Buy Me a Coffee](https://buymeacoffee.com/phcdevworks)

package/SECURITY.md

@@ -0,0 +1,94 @@
+# Security Policy
+
+## Supported Versions
+
+We aim to support the latest published version of Spectre Shell WordPress. Security updates are applied to the current major version only.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+**Please ensure you are using the most recent version** of both:
+
+- This template
+- `vite` and other dependencies (updated in `package.json`)
+
+Older releases may not receive security fixes.
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please **DO NOT** open a public issue. Security issues should be reported privately to protect users.
+
+### How to Report
+
+**Preferred method**: Use [GitHub Security Advisories](https://github.com/phcdevworks/spectre-shell-wordpress/security/advisories/new) to privately report vulnerabilities
+
+**Alternative methods**:
+
+- Email the maintainers at [security contact - see repository]
+- Direct message maintainers through GitHub
+
+### What to Include
+
+Please provide as much detail as possible to help us reproduce and assess impact:
+
+1. **Description of the vulnerability** and potential impact
+2. **Steps to reproduce** or proof-of-concept code
+3. **Affected versions** (if known)
+4. **Potential attack scenarios**
+5. **Suggested mitigation** (if you have ideas)
+
+### What to Expect
+
+1. **Acknowledgment**: We will acknowledge receipt within **48 hours**
+2. **Assessment**: We will investigate and provide an initial assessment within **5 business days**
+3. **Updates**: We will keep you informed of the fix status throughout the process
+4. **Resolution**: We will work on a fix and coordinate disclosure timing with you
+5. **Credit**: We will credit you in the security advisory (unless you prefer to remain anonymous)
+
+## Responsible Disclosure
+
+We appreciate responsible disclosure and will work with you to:
+
+- Understand the scope and severity of the issue
+- Develop and test a fix
+- Coordinate public disclosure timing
+- Credit your contribution (if desired)
+
+**Please allow us reasonable time to address the issue before public disclosure.**
+
+## Security Best Practices
+
+When using Spectre Shell WordPress:
+
+1. **Keep dependencies updated** to the latest versions
+2. **Monitor dependencies** for known vulnerabilities (`npm audit`)
+3. **Use HTTPS** for all production sites
+4. **Follow WordPress security best practices** for theme development
+5. **Sanitize user input** in WordPress templates
+
+## Scope
+
+This security policy covers:
+
+- The Spectre Shell WordPress template code
+- Build configuration and compilation
+- WordPress theme asset loading
+- TypeScript source files
+
+This policy does **NOT** cover:
+
+- Vulnerabilities in WordPress core (report to [WordPress HackerOne](https://hackerone.com/wordpress))
+- Issues in Vite, Tailwind, or other dependencies (report to their maintainers)
+- WordPress plugin vulnerabilities
+- Server configuration issues
+
+## Contact
+
+For security-related questions that aren't vulnerabilities:
+
+- Open a [GitHub Discussion](https://github.com/phcdevworks/spectre-shell-wordpress/discussions)
+- Tag maintainers in relevant issues
+
+Thank you for helping keep this template and our community safe!

package/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>spectre-shell-wordpress</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>