@el-j/magic-helix-plugins 4.0.0-beta.2 → 4.0.0-beta.4

package/dist/patterns/tool-guidelines/usage-policies.md

@@ -0,0 +1,105 @@
+# Usage Policies Pattern
+
+## Purpose
+Define when and how to use tools, including restrictions. From **Cline** and **ChatGPT** patterns.
+
+## Template
+
+```markdown
+## {TOOL_NAME} Usage Policy
+
+### When to Use
+- {USE_CASE_1}
+- {USE_CASE_2}
+- {USE_CASE_3}
+
+### When NOT to Use
+- {ANTI_PATTERN_1}
+- {ANTI_PATTERN_2}
+- {ANTI_PATTERN_3}
+
+### Restrictions
+- {RESTRICTION_1}
+- {RESTRICTION_2}
+- {RESTRICTION_3}
+
+### Preferred Alternatives
+If {CONDITION}, use {ALTERNATIVE_TOOL} instead because {REASON}.
+```
+
+## Examples
+
+### Cline (Terminal Commands)
+```markdown
+## run_in_terminal Usage Policy
+
+### When to Use
+- Installing packages (npm, pip, brew)
+- Running build commands (npm run build)
+- Git operations (commit, push, pull)
+- Executing test suites
+
+### When NOT to Use
+- Running Python code snippets (use pylance_runCodeSnippet instead)
+- Reading file contents (use read_file instead)
+- Making file edits (use replace_string_in_file instead)
+- Parallel execution (terminal doesn't support concurrent commands)
+
+### Restrictions
+- Run one command at a time (wait for output before next)
+- Use absolute paths to avoid navigation issues
+- Disable paging (--no-pager, | cat) to prevent truncation
+- Filter output with grep/awk for large results (>1000 lines)
+
+### Preferred Alternatives
+If running Python code, use `pylance_runCodeSnippet` instead because it:
+- Uses correct workspace interpreter automatically
+- Avoids shell escaping/quoting problems
+- Provides clean, formatted output
+```
+
+### ChatGPT (Image Generation)
+```markdown
+## generate_image Usage Policy
+
+### When to Use
+- User explicitly requests an image
+- Visual aid would enhance understanding
+- Demonstrating design concepts
+- Creating illustrations for explanations
+
+### When NOT to Use
+- User asked for text description only
+- Depicting real people (use generic descriptions)
+- Generating logos/brands (copyright concerns)
+- Creating images of copyrighted characters
+
+### Restrictions
+- NEVER generate images of named real people (living or deceased)
+- NEVER create content that is harmful, hateful, or violent
+- NEVER generate trademarked characters or logos
+- NEVER include recognizable brand names or products
+
+### Preferred Alternatives
+If user wants a person, describe generic attributes instead:
+❌ "Generate an image of Taylor Swift"
+✅ "Generate an image of a young woman with curly blonde hair performing on stage"
+```
+
+## Variables
+- `{TOOL_NAME}`: Tool/function name
+- `{USE_CASE_X}`: Appropriate scenarios
+- `{ANTI_PATTERN_X}`: Inappropriate scenarios
+- `{RESTRICTION_X}`: Hard constraints
+- `{CONDITION}`: Circumstance triggering alternative
+- `{ALTERNATIVE_TOOL}`: Better tool for scenario
+- `{REASON}`: Why alternative is better
+
+## Best Practices
+1. Start with positive use cases (what to do)
+2. Follow with anti-patterns (what not to do)
+3. Use concrete examples (✅/❌ pairs)
+4. Explain reasoning behind restrictions
+5. Suggest alternatives when rejecting patterns
+6. Include edge cases and gotchas
+7. Benefits: Prevents misuse, improves efficiency, reduces errors

package/dist/php/index.cjs

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("../BasePlugin-odQJAKA-.cjs");class t extends i.BasePlugin{constructor(){super(...arguments),this.name="php",this.displayName="PHP",this.version="3.0.0",this.priority=65}async detect(e){if(!this.fileExists(e,"composer.json"))return null;const s=this.readJSON(e,"composer.json");if(!s)return{language:"PHP",name:this.getProjectName(e),dependencies:{},manifestFile:"composer.json",projectPath:e};const n={...s.require,...s["require-dev"]};return{language:"PHP",name:s.name||this.getProjectName(e),description:s.description,dependencies:n,manifestFile:"composer.json",projectPath:e}}getTemplates(){return[{name:"php-core",tags:["php"],content:`# PHP Development Guidelines
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("node:path"),i=require("../BasePlugin-odQJAKA-.cjs");function o(n){const e=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(n){for(const t in n)if(t!=="default"){const s=Object.getOwnPropertyDescriptor(n,t);Object.defineProperty(e,t,s.get?s:{enumerable:!0,get:()=>n[t]})}}return e.default=n,Object.freeze(e)}const a=o(r);class p extends i.BasePlugin{constructor(){super(...arguments),this.name="php",this.displayName="PHP",this.version="3.0.0",this.priority=65}async detect(e){if(!this.fileExists(e,"composer.json"))return null;const t=this.readJSON(e,"composer.json");if(!t)return{language:"PHP",name:this.getProjectName(e),dependencies:{},manifestFile:"composer.json",projectPath:e};const s={...t.require,...t["require-dev"]};return{language:"PHP",name:t.name||this.getProjectName(e),description:t.description,dependencies:s,manifestFile:"composer.json",projectPath:e}}getTemplates(){return[{name:"php-core",tags:["php"],content:()=>this.loadTemplateFromFile(a.join(__dirname,"templates/lang-php.md")).then(e=>e||this.getPHPFallbackTemplate())}]}getPHPFallbackTemplate(){return`# PHP Development Guidelines
 
 This project uses PHP.
 
@@ -15,4 +15,4 @@ This project uses PHP.
 ## Testing
 - Write PHPUnit tests
 - Use proper assertions
-- Aim for good coverage`}]}getDependencyTagMap(){return{"laravel/framework":"laravel","symfony/symfony":"symfony","phpunit/phpunit":"phpunit"}}}exports.PHPPlugin=t;
+- Aim for good coverage`}getDependencyTagMap(){return{"laravel/framework":"laravel","symfony/symfony":"symfony","phpunit/phpunit":"phpunit"}}}exports.PHPPlugin=p;

package/dist/php/{index.js → index.mjs}

@@ -1,5 +1,6 @@
+import * as t from "node:path";
 import { B as i } from "../BasePlugin-6wv0hYJ9.js";
-class t extends i {
+class a extends i {
   constructor() {
     super(...arguments), this.name = "php", this.displayName = "PHP", this.version = "3.0.0", this.priority = 65;
   }
@@ -33,7 +34,14 @@ class t extends i {
       {
         name: "php-core",
         tags: ["php"],
-        content: `# PHP Development Guidelines
+        content: () => this.loadTemplateFromFile(
+          t.join(__dirname, "templates/lang-php.md")
+        ).then((e) => e || this.getPHPFallbackTemplate())
+      }
+    ];
+  }
+  getPHPFallbackTemplate() {
+    return `# PHP Development Guidelines
 
 This project uses PHP.
 
@@ -50,9 +58,7 @@ This project uses PHP.
 ## Testing
 - Write PHPUnit tests
 - Use proper assertions
-- Aim for good coverage`
-      }
-    ];
+- Aim for good coverage`;
   }
   getDependencyTagMap() {
     return {
@@ -63,5 +69,5 @@ This project uses PHP.
   }
 }
 export {
-  t as PHPPlugin
+  a as PHPPlugin
 };

package/dist/php/templates/framework-laravel.md

@@ -0,0 +1,112 @@
+# Laravel Framework Guidelines
+
+## Overview
+This project uses Laravel framework. Follow Laravel conventions and best practices.
+
+## Artisan Commands
+- Serve application: `php artisan serve`
+- Run migrations: `php artisan migrate`
+- Create migration: `php artisan make:migration <name>`
+- Create model: `php artisan make:model <name>`
+- Create controller: `php artisan make:controller <name>`
+- Clear cache: `php artisan cache:clear`
+- List routes: `php artisan route:list`
+
+## Directory Structure
+- `app/` - Application core code
+- `app/Http/Controllers/` - Controllers
+- `app/Models/` - Eloquent models
+- `app/Services/` - Business logic services
+- `routes/` - Route definitions
+- `database/migrations/` - Database migrations
+- `resources/views/` - Blade templates
+- `config/` - Configuration files
+
+## Eloquent ORM
+- Use Eloquent models for database interactions
+- Define relationships in models
+- Use query scopes for reusable queries
+- Use accessors and mutators for attribute transformation
+- Eager load relationships to avoid N+1 queries
+
+## Routing
+- Define routes in `routes/web.php` or `routes/api.php`
+- Use resource controllers: `Route::resource('posts', PostController::class)`
+- Use route model binding for automatic model injection
+- Group related routes with middleware
+- Name your routes for easier URL generation
+
+## Controllers
+- Keep controllers thin - delegate to services
+- Use single action controllers for simple endpoints
+- Return views or JSON responses appropriately
+- Use form requests for validation
+- Use resource controllers for CRUD operations
+
+## Blade Templates
+- Use Blade templating engine
+- Extend layouts: `@extends('layouts.app')`
+- Define sections: `@section('content') ... @endsection`
+- Include partials: `@include('partials.header')`
+- Use components for reusable UI elements
+- Escape output: `{{ $variable }}` (automatic)
+- Raw output (use cautiously): `{!! $html !!}`
+
+## Validation
+- Use Form Requests for complex validation
+- Define rules in controller or Form Request
+- Use built-in validation rules
+- Create custom validation rules when needed
+- Return validation errors automatically
+
+## Database
+- Use migrations for schema changes
+- Use seeders for test data
+- Use factories for model generation
+- Write raw queries only when necessary
+- Use database transactions for multiple operations
+
+## Authentication
+- Use Laravel Breeze or Jetstream for scaffolding
+- Use middleware for route protection: `auth`, `guest`
+- Use gates and policies for authorization
+- Hash passwords with `Hash::make()`
+- Use sanctum for API authentication
+
+## Testing
+- Write Feature tests in `tests/Feature/`
+- Write Unit tests in `tests/Unit/`
+- Use `php artisan test` to run tests
+- Use factories for test data generation
+- Use `RefreshDatabase` trait for database tests
+
+## Queues & Jobs
+- Use queues for slow operations
+- Create jobs: `php artisan make:job <name>`
+- Dispatch jobs: `dispatch(new JobName())`
+- Run queue worker: `php artisan queue:work`
+- Use different queues for priority
+
+## Events & Listeners
+- Use events for decoupled communication
+- Create events: `php artisan make:event <name>`
+- Create listeners: `php artisan make:listener <name>`
+- Register in `EventServiceProvider`
+- Dispatch events: `event(new EventName())`
+
+## API Development
+- Use API resources for JSON responses
+- Version your API routes
+- Use rate limiting middleware
+- Return proper HTTP status codes
+- Use Sanctum or Passport for authentication
+
+## Best Practices
+- Use dependency injection in constructors
+- Keep business logic in service classes
+- Use repository pattern for complex data access
+- Follow single responsibility principle
+- Write tests for all features
+- Use environment variables for configuration
+- Never commit `.env` file
+- Use Laravel's built-in features before third-party packages

package/dist/php/templates/lang-php.md

@@ -0,0 +1,94 @@
+# PHP Development Guidelines
+
+## Overview
+This project uses PHP. Follow modern PHP standards (PSR-12) and best practices.
+
+## Code Style
+- Follow PSR-12 coding standards
+- Use 4 spaces for indentation
+- Use `declare(strict_types=1);` at the top of files
+- Use type declarations for all parameters and return types
+- Use `final` for classes that shouldn't be extended
+
+## PHP Standards Recommendations (PSR)
+- PSR-1: Basic Coding Standard
+- PSR-4: Autoloading Standard
+- PSR-7: HTTP Message Interface
+- PSR-12: Extended Coding Style Guide
+- PSR-15: HTTP Handlers
+
+## Composer Commands
+- Install dependencies: `composer install`
+- Update dependencies: `composer update`
+- Autoload optimization: `composer dump-autoload -o`
+- Run scripts: `composer run-script <script-name>`
+- Validate composer.json: `composer validate`
+
+## Type Safety
+- Use strict types: `declare(strict_types=1);`
+- Add type hints to all parameters
+- Add return type declarations
+- Use union types in PHP 8+: `string|int`
+- Use nullable types: `?string`
+
+## Error Handling
+- Use exceptions for error handling
+- Create custom exception classes
+- Catch specific exceptions, not generic `\Exception`
+- Use `finally` blocks for cleanup
+- Log errors appropriately
+
+## Object-Oriented Programming
+- Follow SOLID principles
+- Use dependency injection
+- Favor composition over inheritance
+- Use interfaces for contracts
+- Use abstract classes for shared behavior
+
+## Modern PHP Features (8.x)
+- Named arguments: `function(param: $value)`
+- Constructor property promotion
+- Match expressions instead of switch
+- Nullsafe operator: `$obj?->method()`
+- Attributes instead of annotations
+
+## Security
+- Always validate and sanitize user input
+- Use prepared statements for database queries
+- Escape output to prevent XSS
+- Use CSRF tokens for forms
+- Keep dependencies updated
+- Use environment variables for sensitive data
+
+## Testing
+- Write PHPUnit tests for all classes
+- Aim for high code coverage
+- Use data providers for multiple test cases
+- Mock external dependencies
+- Run tests: `vendor/bin/phpunit`
+
+## Code Quality Tools
+- PHPStan: Static analysis - `vendor/bin/phpstan analyse`
+- Psalm: Static analysis - `vendor/bin/psalm`
+- PHP_CodeSniffer: Code style - `vendor/bin/phpcs`
+- PHP-CS-Fixer: Auto-fix style - `vendor/bin/php-cs-fixer fix`
+
+## Documentation
+- Use PHPDoc blocks for all classes, methods, and properties
+- Include `@param`, `@return`, and `@throws` tags
+- Document complex logic with inline comments
+- Keep documentation up-to-date
+
+## Performance
+- Use opcode caching (OPcache)
+- Profile with Xdebug or Blackfire
+- Optimize database queries
+- Use caching (Redis, Memcached)
+- Consider asynchronous processing for heavy tasks
+
+## Common Patterns
+- Repository pattern for data access
+- Service layer for business logic
+- Factory pattern for object creation
+- Observer pattern for events
+- Dependency injection containers

package/dist/python/index.cjs

@@ -1,6 +1,6 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("../BasePlugin-odQJAKA-.cjs");class l extends p.BasePlugin{constructor(){super(...arguments),this.name="python",this.displayName="Python",this.version="3.0.0",this.priority=85}async detect(e){return this.fileExists(e,"pyproject.toml")?this.detectFromPyproject(e):this.fileExists(e,"requirements.txt")?this.detectFromRequirements(e):this.fileExists(e,"setup.py")?{language:"Python",name:this.getProjectName(e),dependencies:{},manifestFile:"setup.py",projectPath:e}:null}getTemplates(){return[{name:"python-core",tags:["python"],content:this.getPythonTemplate()}]}getDependencyTagMap(){return{django:"django",flask:"flask",fastapi:"fastapi",pytest:"pytest",numpy:"numpy",pandas:"pandas"}}detectFromPyproject(e){const t=this.readFile(e,"pyproject.toml");if(!t)return{language:"Python",name:this.getProjectName(e),dependencies:{},manifestFile:"pyproject.toml",projectPath:e};const o=t.match(/name\s*=\s*["']([^"']+)["']/),n=t.match(/description\s*=\s*["']([^"']+)["']/),s={},i=t.match(/\[tool\.poetry\.dependencies\]([\s\S]*?)(?:\n\[|$)/);if(i){const a=i[1].split(`
-`);for(const c of a){const r=c.match(/^([a-zA-Z0-9_-]+)\s*=\s*["']([^"']+)["']/);r&&r[1]!=="python"&&(s[r[1]]=r[2])}}return{language:"Python",name:o?.[1]||this.getProjectName(e),description:n?.[1],dependencies:s,manifestFile:"pyproject.toml",projectPath:e}}detectFromRequirements(e){const t=this.readFile(e,"requirements.txt"),o={};if(t){for(const n of t.split(`
-`))if(n.trim()&&!n.startsWith("#")){const s=n.split(/[=<>]/),i=s[0].trim(),a=s[1]?.trim()||"*";i&&(o[i]=a)}}return{language:"Python",name:this.getProjectName(e),dependencies:o,manifestFile:"requirements.txt",projectPath:e}}getPythonTemplate(){return`# Python Development Guidelines
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("node:path"),m=require("../BasePlugin-odQJAKA-.cjs");function u(s){const e=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(s){for(const t in s)if(t!=="default"){const n=Object.getOwnPropertyDescriptor(s,t);Object.defineProperty(e,t,n.get?n:{enumerable:!0,get:()=>s[t]})}}return e.default=s,Object.freeze(e)}const d=u(p);class y extends m.BasePlugin{constructor(){super(...arguments),this.name="python",this.displayName="Python",this.version="3.0.0",this.priority=85}async detect(e){return this.fileExists(e,"pyproject.toml")?this.detectFromPyproject(e):this.fileExists(e,"requirements.txt")?this.detectFromRequirements(e):this.fileExists(e,"setup.py")?{language:"Python",name:this.getProjectName(e),dependencies:{},manifestFile:"setup.py",projectPath:e}:null}getTemplates(){return[{name:"python-core",tags:["python"],content:()=>this.loadTemplateFromFile(d.join(__dirname,"templates/lang-python.md")).then(e=>e||this.getPythonFallbackTemplate())}]}getDependencyTagMap(){return{django:"django",flask:"flask",fastapi:"fastapi",pytest:"pytest",numpy:"numpy",pandas:"pandas"}}detectFromPyproject(e){const t=this.readFile(e,"pyproject.toml");if(!t)return{language:"Python",name:this.getProjectName(e),dependencies:{},manifestFile:"pyproject.toml",projectPath:e};const n=t.match(/name\s*=\s*["']([^"']+)["']/),i=t.match(/description\s*=\s*["']([^"']+)["']/),o={},r=t.match(/\[tool\.poetry\.dependencies\]([\s\S]*?)(?:\n\[|$)/);if(r){const c=r[1].split(`
+`);for(const l of c){const a=l.match(/^([a-zA-Z0-9_-]+)\s*=\s*["']([^"']+)["']/);a&&a[1]!=="python"&&(o[a[1]]=a[2])}}return{language:"Python",name:n?.[1]||this.getProjectName(e),description:i?.[1],dependencies:o,manifestFile:"pyproject.toml",projectPath:e}}detectFromRequirements(e){const t=this.readFile(e,"requirements.txt"),n={};if(t){for(const i of t.split(`
+`))if(i.trim()&&!i.startsWith("#")){const o=i.split(/[=<>]/),r=o[0].trim(),c=o[1]?.trim()||"*";r&&(n[r]=c)}}return{language:"Python",name:this.getProjectName(e),dependencies:n,manifestFile:"requirements.txt",projectPath:e}}getPythonFallbackTemplate(){return`# Python Development Guidelines
 
 This project uses Python.
 
@@ -27,4 +27,4 @@ This project uses Python.
 ## Best Practices
 - Handle exceptions properly
 - Use context managers for resources
-- Follow Pythonic idioms`}}exports.PythonPlugin=l;
+- Follow Pythonic idioms`}}exports.PythonPlugin=y;

package/dist/python/{index.js → index.mjs}

@@ -1,5 +1,6 @@
-import { B as p } from "../BasePlugin-6wv0hYJ9.js";
-class d extends p {
+import * as c from "node:path";
+import { B as m } from "../BasePlugin-6wv0hYJ9.js";
+class u extends m {
   constructor() {
     super(...arguments), this.name = "python", this.displayName = "Python", this.version = "3.0.0", this.priority = 85;
   }
@@ -17,7 +18,9 @@ class d extends p {
       {
         name: "python-core",
         tags: ["python"],
-        content: this.getPythonTemplate()
+        content: () => this.loadTemplateFromFile(
+          c.join(__dirname, "templates/lang-python.md")
+        ).then((e) => e || this.getPythonFallbackTemplate())
       }
     ];
   }
@@ -48,8 +51,8 @@ class d extends p {
     if (i) {
       const a = i[1].split(`
 `);
-      for (const c of a) {
-        const r = c.match(/^([a-zA-Z0-9_-]+)\s*=\s*["']([^"']+)["']/);
+      for (const p of a) {
+        const r = p.match(/^([a-zA-Z0-9_-]+)\s*=\s*["']([^"']+)["']/);
         r && r[1] !== "python" && (s[r[1]] = r[2]);
       }
     }
@@ -80,7 +83,7 @@ class d extends p {
       projectPath: e
     };
   }
-  getPythonTemplate() {
+  getPythonFallbackTemplate() {
     return `# Python Development Guidelines
 
 This project uses Python.
@@ -112,5 +115,5 @@ This project uses Python.
   }
 }
 export {
-  d as PythonPlugin
+  u as PythonPlugin
 };