@fishawack/lab-env 4.44.1 → 4.45.0-beta.2

package/_Ai/vue-3.md

@@ -75,12 +75,13 @@ fw npm -v
 
 ## Project Structure Context
 
-- **Vue Components**: Main app component at [`_Build/vue/app.vue`](_Build/vue/app.vue)
-- **Routes**: Page components in [`_Build/vue/routes/`](_Build/vue/routes/) directory
-- **Global Components**: Reusable components in [`_Build/vue/globals/`](_Build/vue/globals/) directory
-- **JavaScript**: Main script at [`_Build/js/script.js`](_Build/js/script.js), utilities in [`_Build/js/libs/`](_Build/js/libs/) directory
-- **Styles**: SASS files in [`_Build/sass/`](_Build/sass/) directory
-- **Templates**: Handlebars templates in [`_Build/handlebars/`](_Build/handlebars/) directory
+- **Vue Components**: Main app component at [`resources/vue/app.vue`](resources/vue/app.vue)
+- **Vue Components**: Reusable components in [`resources/vue/components/`](resources/vue/components/) directory
+- **Vue Routes**: Page components in [`resources/vue/routes/`](resources/vue/routes/) directory
+- **Vue Stories**: Component documentation in [`resources/vue/stories/`](resources/vue/stories/) directory
+- **JavaScript**: Main script at [`resources/js/script.js`](resources/js/script.js), utilities in [`resources/js/libs/`](resources/js/libs/) directory
+- **Styles**: SASS files in [`resources/sass/`](resources/sass/) directory
+- **Templates**: Handlebars templates in [`resources/handlebars/`](resources/handlebars/) directory
 - **Tests**: Unit tests in [`_Test/unit/`](_Test/unit/), UI tests in [`_Test/ui/`](_Test/ui/)
 
 ## Technology Stack
@@ -144,22 +145,85 @@ The project uses Fishawack's custom build system (`@fishawack/core`):
 
 ## Styling Architecture
 
+### Critical Styling Philosophy
+
+**NEVER use `<style>` blocks in Vue components** - All styling is managed through the structured SASS architecture. This enforces separation of concerns and maintains optimal build performance.
+
 ### SASS Structure
 
-- [`_Build/sass/vendor.scss`](_Build/sass/vendor.scss): Third-party imports and lab-ui components
-- [`_Build/sass/general.scss`](_Build/sass/general.scss): Project-specific styles
-- [`_Build/sass/_variables.scss`](_Build/sass/_variables.scss): SASS variables
-- [`_Build/sass/_defaults.scss`](_Build/sass/_defaults.scss): Default overrides
+- [`resources/sass/vendor.scss`](resources/sass/vendor.scss): Third-party imports and lab-ui components (cached for performance)
+- [`resources/sass/general.scss`](resources/sass/general.scss): Project-specific component imports (fast-reloading)
+- [`resources/sass/_variables.scss`](resources/sass/_variables.scss): Project color overrides and custom variables
+- [`resources/sass/_defaults.scss`](resources/sass/_defaults.scss): Lab-UI component setting overrides
+- [`resources/sass/components/`](resources/sass/components/): Individual component style files using BEM methodology
+
+### BEM Methodology
+
+All component styling follows BEM (Block Element Modifier) methodology:
+
+```scss
+// Block: Base component
+.card {
+}
+
+// Element: Component part
+.card__header {
+}
+.card__body {
+}
+.card__footer {
+}
+
+// Modifier: Variant or state
+.card--featured {
+}
+.card--compact {
+}
+.card__header--sticky {
+}
+```
+
+**Vue Template Example:**
+
+```vue
+<template>
+    <article class="card card--featured">
+        <header class="card__header card__header--sticky">
+            <h2 class="card__title">{{ title }}</h2>
+        </header>
+        <div class="card__body">
+            <p>{{ content }}</p>
+        </div>
+    </article>
+</template>
+```
 
 ### UI Library Integration
 
-Uses `@fishawack/lab-ui` for:
+Uses `@fishawack/lab-ui` utility-first framework providing:
+
+#### Utility Classes (Tailwind-like system):
 
-- Typography system
-- Grid system
-- Button components
-- Utility classes
-- Color system
+- **Spacing**: `m-0`, `m-0.5`, `m-1.5`, `p-2`, `p-3`, `p-4`
+- **Colors**: `bg-1` through `bg-6`, `color-1` through `color-6`
+- **Grid**: `grid__6/12`, `mobile:grid__12/12`, `grid--gutters`
+- **Flexbox**: `flex`, `justify-center`, `items-center`, `flex-column`
+- **Typography**: `text-center`, `font-600`, `uppercase`
+- **Display**: `block`, `hidden`, `mobile:hidden`, `tablet:block`
+
+#### Responsive Breakpoints:
+
+- `mobile:` - 767px and below
+- `tablet:` - 1023px and below
+- `desktop:` - 1299px and below
+
+#### Base Components:
+
+- Typography system with semantic font weights
+- 12-column flexbox grid system
+- Button component base with extensive customization
+- Form components with validation states
+- Utility classes for spacing, colors, and layout
 
 ## Testing Guidelines
 
@@ -187,17 +251,241 @@ fw npm run test
 
 ## Development Guidelines
 
+### Vue Component Styling Rules
+
+**CRITICAL**: Never use `<style>` or `<style scoped>` blocks in Vue components. All styling must be managed through the SASS architecture.
+
+#### Correct Approach:
+
+```vue
+<!-- MyComponent.vue -->
+<template>
+    <div class="my-component my-component--featured">
+        <header class="my-component__header">
+            <h2 class="my-component__title">{{ title }}</h2>
+        </header>
+        <div class="my-component__body">
+            <p>{{ content }}</p>
+        </div>
+    </div>
+</template>
+
+<script>
+export default {
+    name: "MyComponent",
+    props: ["title", "content"],
+};
+</script>
+
+<!-- NO <style> block - styles are in resources/sass/components/_my-component.scss -->
+```
+
+#### Corresponding SASS File (`resources/sass/components/_my-component.scss`):
+
+```scss
+.my-component {
+    // Use lab-ui utilities when possible
+    @apply bg-0 p-2 grid--gutters;
+
+    border: 1px solid $color6;
+    border-radius: 4px;
+
+    &__header {
+        @apply border-color-6 pb-1;
+        border-bottom: 1px solid;
+    }
+
+    &__title {
+        @apply font-600 color-4;
+        margin: 0;
+    }
+
+    &__body {
+        @apply pt-1;
+    }
+
+    // Modifier for featured variant
+    &--featured {
+        border-color: $color1;
+        box-shadow: 0 4px 8px rgba($color1, 0.1);
+    }
+}
+```
+
+### BEM Methodology Implementation
+
+Use BEM (Block Element Modifier) consistently for all component styling:
+
+- **Block**: `.component-name` - The standalone component
+- **Element**: `.component-name__element` - A part of the component
+- **Modifier**: `.component-name--modifier` or `.component-name__element--modifier` - A variant or state
+
+#### Vue Template BEM Patterns:
+
+```vue
+<template>
+    <!-- Block with modifier -->
+    <article class="card card--featured">
+        <!-- Elements -->
+        <header class="card__header card__header--sticky">
+            <h2 class="card__title">{{ title }}</h2>
+            <button class="card__action card__action--primary">Action</button>
+        </header>
+
+        <div class="card__body">
+            <!-- Combine BEM with lab-ui utilities -->
+            <p class="card__text color-4 font-400">{{ content }}</p>
+        </div>
+
+        <!-- Conditional modifiers -->
+        <footer
+            class="card__footer"
+            :class="{ 'card__footer--expanded': isExpanded }"
+        >
+            <slot name="footer" />
+        </footer>
+    </article>
+</template>
+```
+
+### Lab-UI Utility Integration
+
+Combine BEM component styles with lab-ui utilities for optimal performance:
+
+#### Layout Utilities:
+
+```vue
+<template>
+    <div class="dashboard-grid grid grid--gutters">
+        <div class="dashboard-card grid__6/12 tablet:grid__12/12">
+            <!-- Card content -->
+        </div>
+        <div class="dashboard-card grid__6/12 tablet:grid__12/12">
+            <!-- Card content -->
+        </div>
+    </div>
+</template>
+```
+
+#### Responsive Design:
+
+```vue
+<template>
+    <nav class="main-nav flex justify-between items-center p-2">
+        <div class="main-nav__brand">
+            <img
+                src="logo.svg"
+                alt="Brand"
+                class="logo--small tablet:logo--medium"
+            />
+        </div>
+
+        <div class="main-nav__menu hidden tablet:block">
+            <!-- Desktop menu -->
+        </div>
+
+        <button class="main-nav__toggle block tablet:hidden">
+            <!-- Mobile menu toggle -->
+        </button>
+    </nav>
+</template>
+```
+
+### Component Development Workflow
+
+1. **Create Vue Component**: Focus on structure and behavior only
+2. **Define BEM Classes**: Use semantic class names following BEM methodology
+3. **Create SASS File**: Add corresponding file in `resources/sass/components/`
+4. **Import in General**: Add new component to `resources/sass/general.scss`
+5. **Use Lab-UI Utilities**: Leverage existing utilities before writing custom CSS
+6. **Test Responsively**: Verify component works across all breakpoints
+
 ### Vue Component Patterns
 
 - Use Vue 3 Composition API when appropriate
 - Follow Single File Component (SFC) structure
 - Utilize global components (`GIcon`, `GSvg`) for consistent UI
+- Never include styling within component files
 
 ### Adding New Routes
 
-1. Create component in [`_Build/vue/routes/`](_Build/vue/routes/)
-2. Add route definition to [`_Build/js/libs/routes.js`](_Build/js/libs/routes.js)
+1. Create component in [`resources/vue/routes/`](resources/vue/routes/)
+2. Add route definition to [`resources/js/libs/routes.js`](resources/js/libs/routes.js)
 3. Set `prerender: false` if route shouldn't be pre-rendered
+4. Create corresponding SASS file in [`resources/sass/components/`](resources/sass/components/) if custom styling needed
+
+### Performance Considerations
+
+#### SASS Architecture Benefits:
+
+- **Vendor Caching**: Third-party libraries in `vendor.scss` are cached for faster rebuilds
+- **Fast Recompilation**: Project styles in `general.scss` recompile quickly during development
+- **PurgeCSS Optimization**: Unused CSS automatically removed in production builds
+- **No Style Duplication**: Global SASS architecture prevents style repetition across components
+
+#### PurgeCSS and Dynamic Classes:
+
+```javascript
+// If Vue components add classes dynamically via JavaScript:
+export default {
+    methods: {
+        highlightElement() {
+            // Ensure these classes are preserved in production
+            this.$el.classList.add("highlighted", "animated-in");
+        },
+    },
+};
+```
+
+Add protection in SASS file:
+
+```scss
+/* purgecss start ignore */
+.highlighted,
+.animated-in {
+    // These classes will be preserved in production builds
+}
+/* purgecss end ignore */
+```
+
+### Styling Anti-Patterns to Avoid
+
+❌ **Never do this:**
+
+```vue
+<template>
+    <div class="my-component">
+        <p :style="{ color: dynamicColor }">Text</p>
+    </div>
+</template>
+
+<style scoped>
+.my-component {
+    padding: 20px;
+}
+</style>
+```
+
+✅ **Do this instead:**
+
+```vue
+<template>
+    <div class="my-component" :class="colorClass">
+        <p class="my-component__text">Text</p>
+    </div>
+</template>
+
+<script>
+export default {
+    computed: {
+        colorClass() {
+            return `my-component--${this.variant}`;
+        },
+    },
+};
+</script>
+<!-- Styles in resources/sass/components/_my-component.scss -->
+```
 
 ### Adding Dependencies
 
@@ -230,10 +518,24 @@ The `fw` command is our container orchestration manager that:
 
 1. Always assume containerized environment with `fw` prefix
 2. Follow Vue.js 3 best practices and Composition API patterns
-3. Use existing global components and utilities from lab-ui
-4. Consider the Handlebars template system for static content
-5. Respect the existing SASS architecture and variable system
-6. Ensure new routes are properly configured for SPA routing
-7. Use the existing testing patterns for unit and integration tests
-
-Remember: This is a containerized Vue.js SPA with a custom build system - all operations must go through the `fw` container orchestration manager.
+3. **NEVER suggest `<style>` blocks in Vue components** - All styling goes in SASS files
+4. Use BEM methodology for component class naming (`.block__element--modifier`)
+5. Combine lab-ui utilities with custom component styles for optimal performance
+6. Create corresponding SASS files in `resources/sass/components/` for new components
+7. Import new component styles in `resources/sass/general.scss` for fast recompilation
+8. Use existing global components and utilities from lab-ui
+9. Consider the Handlebars template system for static content
+10. Respect the existing SASS architecture and variable system
+11. Ensure new routes are properly configured for SPA routing
+12. Use the existing testing patterns for unit and integration tests
+13. Always test production builds when adding JavaScript-generated CSS classes (PurgeCSS considerations)
+
+### Key Styling Principles:
+
+- **Separation of Concerns**: Vue handles logic/templates, SASS handles all styling
+- **Utility-First**: Use lab-ui utilities before writing custom CSS
+- **BEM Methodology**: Consistent class naming for maintainable styles
+- **Performance**: Leverage vendor/general file split for optimal build times
+- **Responsive**: Mobile-first design with lab-ui breakpoint system
+
+Remember: This is a containerized Vue.js SPA with structured SASS architecture - all operations must go through the `fw` container orchestration manager, and all styling must be managed through the SASS system using BEM methodology.

package/bitbucket-pipelines.yml

@@ -127,7 +127,9 @@ pipelines:
             - production
           size: 4x
           script:
-            # Install deps
+            # Install lib deps
+            - git submodule init && git submodule update
+            # Install release deps
             - npm install -g semantic-release@24 @semantic-release/changelog@6 @semantic-release/git@10 conventional-changelog-conventionalcommits@8
             # Release version via node so can exit out when no release made
             - |

package/cli.js

@@ -33,73 +33,99 @@ const args = hideBin(process.argv);
                 description: `Continue past standard failure points (use at your own risk)`,
             });
 
-        // Repo commands
-        let commands = ["start", "watch", "setup"];
-
-        if (_.config.preset !== "external") {
-            commands.push("content");
-        }
-
-        commands.push("production", "test");
-
-        if (_.config.preset === "permanent") {
-            commands.push("deploy");
-        }
-
-        commands.push(
-            "reinstall",
-            "install",
-            "uninstall",
-            "run",
-            "check",
-            "clean",
-            "nuke",
-            "regenerate",
-            "connect",
-            "execute",
-            "lint",
-        );
-
-        if (_.config.preset === "permanent") {
-            commands.push("origin");
-        }
-
-        commands.push("npm", "script");
-
-        if (_.platform === "laravel") {
-            commands.push("artisan");
-        }
-
-        if (_.platform === "craftcms") {
-            commands.push("craft");
-        }
-
-        if (_.platform === "drupal") {
-            commands.push("drush");
-        }
-
-        if (_.platform === "wordpress") {
-            commands.push("wp");
-        }
+        // Platform command mapping
+        const platformCommands = {
+            // Base commands available to all platforms
+            base: ["start", "setup", "connect", "execute", "nuke", "lint"],
+
+            // Web development commands (for frameworks that build frontend assets)
+            webDev: [
+                "watch",
+                "run",
+                "check",
+                "npm",
+                "production",
+                "test",
+                "reinstall",
+                "install",
+                "uninstall",
+                "clean",
+                "regenerate",
+                "script",
+            ],
+
+            // Platform-specific commands
+            laravel: ["artisan", "composer", "php"],
+            craftcms: ["craft", "composer", "php"],
+            drupal: ["drush", "composer", "php"],
+            wordpress: ["wp", "composer", "php"],
+            adonis: ["ace", "node"],
+            php: ["composer", "php"],
+            python: ["python", "pip"],
+        };
+
+        // Define which platforms get which command groups
+        const platformGroups = {
+            laravel: ["base", "webDev"],
+            craftcms: ["base", "webDev"],
+            drupal: ["base", "webDev"],
+            wordpress: ["base", "webDev"],
+            adonis: ["base", "webDev"],
+            php: ["base", "webDev"],
+            core: ["base", "webDev"],
+            python: ["base"], // Python only gets base commands, no webDev
+        };
+
+        // Config-based command additions
+        const configCommands = {
+            content: _.config.preset !== "external",
+            deploy: _.config.preset === "permanent",
+            origin: _.config.preset === "permanent",
+        };
+
+        // Build commands array
+        let commands = [];
+
+        // Special handling for devops preset - only gets create commands and hidden docker commands
+        if (_.config.preset === "devops") {
+            // No platform or base commands for devops
+            commands = [];
+        } else {
+            // Normal command building for other presets
+            // Add command groups based on platform
+            const groups = platformGroups[_.platform] || ["base"];
+            groups.forEach((group) => {
+                if (platformCommands[group]) {
+                    commands.push(...platformCommands[group]);
+                }
+            });
 
-        if (_.platform === "adonis") {
-            commands.push("ace", "node");
-        }
+            // Add config-based commands
+            Object.entries(configCommands).forEach(([command, condition]) => {
+                if (condition) {
+                    commands.push(command);
+                }
+            });
 
-        if (
-            _.platform === "laravel" ||
-            (_.platform === "wordpress" &&
-                process.env.VERSION_WORDPRESS !== "0") ||
-            _.platform === "drupal" ||
-            _.platform === "craftcms" ||
-            _.platform === "php"
-        ) {
-            commands.push("composer", "php");
+            // Add platform-specific commands
+            if (platformCommands[_.platform]) {
+                commands.push(...platformCommands[_.platform]);
+            }
+
+            // Special case for WordPress version 0 (no composer/php)
+            if (
+                _.platform === "wordpress" &&
+                process.env.VERSION_WORDPRESS === "0"
+            ) {
+                commands = commands.filter(
+                    (cmd) => !["composer", "php"].includes(cmd),
+                );
+            }
         }
 
         commands.forEach((d) => cli.command(...require(`./commands/${d}.js`)));
 
-        // Docker commands
+        // Docker commands (hidden - available to all)
         [
             "build",
             "config",
@@ -111,8 +137,8 @@ const args = hideBin(process.argv);
             "compose",
         ].forEach((d) => cli.command(...require(`./commands/docker/${d}.js`)));
 
-        if (_.config.preset === "permanent") {
-            // Create commands
+        // Create commands
+        if (_.config.preset === "permanent" || _.config.preset === "devops") {
             [
                 "new",
                 "provision",

package/commands/connect.js

@@ -6,7 +6,7 @@ module.exports = [
     (yargs) => {
         yargs.positional("container", {
             describe: "container to connect to",
-            default: "core",
+            default: _.platform === "python" ? "python" : "core",
         });
     },
     (argv) => _.command(argv.container),

package/commands/create/cmds/dekey.js

@@ -4,7 +4,9 @@ const aws = require("../services/aws/index.js");
 
 module.exports = [
     "dekey",
-    false,
+    _.config.preset === "devops"
+        ? "Removes AWS access keys and credentials"
+        : false,
     () => {},
     async () => {
         let users = [];

package/commands/create/cmds/deprovision.js

@@ -6,7 +6,9 @@ const { stack, client } = require("../libs/prompts.js");
 
 module.exports = [
     ["deprovision", "deprov"],
-    false,
+    _.config.preset === "devops"
+        ? "Terminate the provisioned environment on AWS"
+        : false,
     (yargs) => {
         yargs.option("branch", {
             alias: "b",

package/commands/create/cmds/key.js

@@ -10,7 +10,9 @@ const htmlEmail = require("fs").readFileSync(
 
 module.exports = [
     "key",
-    false,
+    _.config.preset === "devops"
+        ? "Creates AWS access keys and credentials"
+        : false,
     () => {},
     async () => {
         let users = [];

package/commands/create/cmds/provision.js

@@ -9,7 +9,9 @@ const { frameworks } = require("../libs/vars");
 
 module.exports = [
     ["provision", "prov"],
-    "Provisions the deployment target",
+    _.config.preset === "devops"
+        ? "Provisions a static or fullstack env on AWS"
+        : false,
     (yargs) => {
         yargs.option("branch", {
             alias: "b",

package/commands/create/libs/vars.js

@@ -96,7 +96,7 @@ module.exports.globalModules = [
 ];
 
 // User presets
-module.exports.presets = ["permanent", "freelancer", "external"];
+module.exports.presets = ["permanent", "freelancer", "external", "devops"];
 
 module.exports.templates = [
     {

package/commands/create/services/aws/elasticbeanstalk.js

@@ -56,8 +56,8 @@ module.exports.createElasticBeanstalkEnvironment = async (
                     SolutionStackName: solutions.SolutionStacks.filter((d) => {
                         return language === "node"
                             ? d.includes("Node.js 20")
-                            : d.includes("PHP 8.1") &&
-                                  d.includes("Amazon Linux 2 ");
+                            : d.includes("PHP 8.2") &&
+                                  d.includes("Amazon Linux 2023");
                     })[0],
                     OptionSettings,
                     CNAMEPrefix,

package/commands/create/services/aws/iam.js

@@ -136,6 +136,14 @@ module.exports.syncFWIAMPolicies = async (
             "arn:aws:iam::aws:policy/AdministratorAccess-AWSElasticBeanstalk",
         );
     }
+
+    if (permissions.includes("manage-users")) {
+        await module.exports.attachIAMPolicy(
+            UserName,
+            account,
+            "arn:aws:iam::aws:policy/IAMFullAccess",
+        );
+    }
 };
 
 module.exports.removeIAMPolicy = async (UserName, account, policy) => {