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

package/dist/default_templates/patterns/domain-expertise/server-components.md

@@ -1,212 +0,0 @@
-# Server Components Pattern
-
-## Purpose
-Guide usage of React Server Components (RSC) in Next.js. From **v0** pattern.
-
-## Template
-
-```markdown
-## React Server Components (RSC)
-
-### When to Use Server Components
-- {SCENARIO_1_FOR_SERVER}
-- {SCENARIO_2_FOR_SERVER}
-- {SCENARIO_3_FOR_SERVER}
-
-### When to Use Client Components
-- {SCENARIO_1_FOR_CLIENT}
-- {SCENARIO_2_FOR_CLIENT}
-- {SCENARIO_3_FOR_CLIENT}
-
-### Composition Patterns
-- {HOW_TO_MIX_SERVER_AND_CLIENT}
-- {PASSING_PROPS_BETWEEN_TYPES}
-- {HANDLING_SERIALIZATION}
-```
-
-## Examples
-
-### v0 (Next.js App Router RSC Guidelines)
-```markdown
-## React Server Components (RSC) in Next.js
-
-### When to Use Server Components (Default)
-- **Data Fetching**: When you need to fetch data from APIs or databases
-  ```typescript
-  // ✅ Server Component - fetch directly
-  export default async function BlogPost({ params }: { params: { id: string } }) {
-    const post = await fetch(`https://api.example.com/posts/${params.id}`)
-      .then(r => r.json());
-    return <article>{post.content}</article>;
-  }
-  ```
-
-- **Static Content**: Components that don't need interactivity
-  ```typescript
-  // ✅ Server Component - no hooks or events
-  export function Footer() {
-    return (
-      <footer>
-        <p>&copy; 2024 Company Name</p>
-        <nav>
-          <a href="/about">About</a>
-          <a href="/contact">Contact</a>
-        </nav>
-      </footer>
-    );
-  }
-  ```
-
-- **Sensitive Operations**: Backend logic that shouldn't be exposed to client
-  ```typescript
-  // ✅ Server Component - API key stays on server
-  async function fetchData() {
-    return await fetch('https://api.example.com/data', {
-      headers: { 'Authorization': `Bearer ${process.env.API_KEY}` }
-    }).then(r => r.json());
-  }
-  ```
-
-### When to Use Client Components ('use client')
-- **Interactivity**: Components with event handlers or React hooks
-  ```typescript
-  'use client';
-  import { useState } from 'react';
-  
-  export function Counter() {
-    const [count, setCount] = useState(0);
-    return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
-  }
-  ```
-
-- **Browser APIs**: Components using window, document, localStorage, etc.
-  ```typescript
-  'use client';
-  import { useEffect } from 'react';
-  
-  export function Tracker() {
-    useEffect(() => {
-      console.log('Page viewed:', window.location.href);
-    }, []);
-    return null;
-  }
-  ```
-
-- **Third-Party Libraries**: Components using client-only libraries
-  ```typescript
-  'use client';
-  import { useFormik } from 'formik'; // Client-side form library
-  
-  export function SignupForm() {
-    const formik = useFormik({ /* ... */ });
-    return <form onSubmit={formik.handleSubmit}>...</form>;
-  }
-  ```
-
-### Composition Patterns
-- **Server Component as Parent**: Client components can be children
-  ```typescript
-  // ✅ Server Component
-  export default async function Page() {
-    const data = await fetchData();
-    
-    return (
-      <div>
-        <h1>{data.title}</h1>
-        <InteractiveWidget data={data} /> {/* Client Component */}
-      </div>
-    );
-  }
-  ```
-
-- **Pass Serializable Props**: Only JSON-serializable data between boundaries
-  ```typescript
-  // ✅ Serializable props (string, number, plain object)
-  <ClientComponent title="Hello" count={5} data={{ id: 1 }} />
-  
-  // ❌ Non-serializable props (functions, class instances)
-  <ClientComponent onClick={() => {}} instance={new Date()} />
-  ```
-
-- **Workaround for Non-Serializable**: Use Server Actions or move logic to client
-  ```typescript
-  // ✅ Server Action (async function from server)
-  async function updateData(formData: FormData) {
-    'use server';
-    // Server-side logic
-  }
-  
-  // Pass action to client component
-  <ClientForm action={updateData} />
-  ```
-
-- **Client Component as Wrapper**: Server components can be passed as children
-  ```typescript
-  // ✅ Client Component wrapper
-  'use client';
-  export function AnimatedContainer({ children }: { children: React.ReactNode }) {
-    return <motion.div>{children}</motion.div>;
-  }
-  
-  // Usage: Server Component as child
-  <AnimatedContainer>
-    <ServerRenderedContent /> {/* Still a Server Component */}
-  </AnimatedContainer>
-  ```
-
-### Performance Considerations
-- **Minimize Client Bundles**: Keep 'use client' boundary as low as possible
-  ```typescript
-  // ❌ Entire page is client component (large bundle)
-  'use client';
-  export default function Page() {
-    const [state, setState] = useState();
-    return <div>...</div>;
-  }
-  
-  // ✅ Only interactive part is client component
-  export default function Page() {
-    return (
-      <div>
-        <StaticHeader /> {/* Server Component */}
-        <InteractiveWidget /> {/* Client Component - small bundle */}
-        <StaticFooter /> {/* Server Component */}
-      </div>
-    );
-  }
-  ```
-
-- **Data Fetching Location**: Fetch in Server Component, not Client Component
-  ```typescript
-  // ✅ Fetch in Server Component (faster, no loading state)
-  export default async function Page() {
-    const data = await fetchData();
-    return <ClientDisplay data={data} />;
-  }
-  
-  // ❌ Fetch in Client Component (slower, needs loading state)
-  'use client';
-  export default function Page() {
-    const [data, setData] = useState(null);
-    useEffect(() => { fetchData().then(setData); }, []);
-    if (!data) return <Spinner />;
-    return <div>{data}</div>;
-  }
-  ```
-```
-
-## Variables
-- `{SCENARIO_X_FOR_SERVER}`: When to use Server Component
-- `{SCENARIO_X_FOR_CLIENT}`: When to use Client Component
-- `{HOW_TO_MIX_SERVER_AND_CLIENT}`: Composition strategies
-- `{PASSING_PROPS_BETWEEN_TYPES}`: Serialization rules
-- `{HANDLING_SERIALIZATION}`: Workarounds for non-serializable data
-
-## Best Practices
-1. Default to Server Components (add 'use client' only when needed)
-2. Explain serialization boundaries (common source of bugs)
-3. Show composition patterns (client wrapping server, server wrapping client)
-4. Highlight performance benefits (smaller bundles, faster data fetching)
-5. Provide migration guide (Pages Router → App Router)
-6. Address common mistakes ('use client' on entire page)
-7. Benefits: Optimal performance, secure API calls, smaller JS bundles

package/dist/default_templates/patterns/domain-expertise/shadcn-ui.md

@@ -1,52 +0,0 @@
-# shadcn/ui Component Library Pattern
-
-## Purpose
-Guide usage of shadcn/ui components in Next.js/React projects. From **same.new**.
-
-## Installation Pattern
-```bash
-npx shadcn-ui@latest add button
-npx shadcn-ui@latest add card dialog input
-```
-
-## Component Usage
-```tsx
-import { Button } from "@/components/ui/button"
-import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
-
-export function ProductCard({ product }: Props) {
-  return (
-    <Card>
-      <CardHeader>
-        <CardTitle>{product.name}</CardTitle>
-      </CardHeader>
-      <CardContent>
-        <p>{product.description}</p>
-        <Button>Add to Cart</Button>
-      </CardContent>
-    </Card>
-  )
-}
-```
-
-## Customization
-```tsx
-// ✅ Extend with custom variants using cva
-import { cva } from "class-variance-authority"
-
-const buttonVariants = cva("base-classes", {
-  variants: {
-    variant: {
-      default: "bg-primary",
-      outline: "border border-input",
-      custom: "bg-gradient-to-r from-purple-500 to-pink-500"
-    }
-  }
-})
-```
-
-## Best Practices
-- Components are copied to your repo (not npm dependencies)
-- Customize in `components/ui/` as needed
-- Use Radix UI primitives for accessibility
-- Combine with Tailwind for styling

package/dist/default_templates/patterns/domain-expertise/tailwind-patterns.md

@@ -1,52 +0,0 @@
-# Tailwind CSS Patterns
-
-## Purpose
-Enforce Tailwind CSS best practices and utility patterns. From **same.new** and **Loveable**.
-
-## Key Patterns
-
-### Utility-First Approach
-```tsx
-// ✅ Use utility classes
-<button className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
-  Click me
-</button>
-
-// ❌ Avoid custom CSS
-<button className="custom-button">Click me</button>
-```
-
-### Responsive Design
-```tsx
-// ✅ Mobile-first responsive utilities
-<div className="w-full md:w-1/2 lg:w-1/3 xl:w-1/4">
-  Responsive width
-</div>
-```
-
-### Dark Mode
-```tsx
-// ✅ Dark mode variants
-<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
-  Content
-</div>
-```
-
-### Component Extraction
-```tsx
-// When utilities get too long (>5 classes), extract to component
-// ✅ Extract reusable pattern
-function Card({ children }: { children: React.ReactNode }) {
-  return (
-    <div className="rounded-lg shadow-md p-6 bg-white dark:bg-gray-800">
-      {children}
-    </div>
-  );
-}
-```
-
-## Best Practices
-- Use arbitrary values sparingly: `w-[137px]` (prefer standard scale)
-- Group related utilities: layout, spacing, typography, colors
-- Use @apply only for component styles (avoid in utility classes)
-- Configure theme in tailwind.config.js for brand colors

package/dist/default_templates/patterns/environment/container-awareness.md

@@ -1,17 +0,0 @@
-# $(basename "$file" .md | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') Pattern
-
-## Purpose
-[Pattern description from integration document]
-
-## Template
-```markdown
-[Key structure and variables]
-```
-
-## Examples
-[Concrete examples from v0, Claude, ChatGPT, Cline, etc.]
-
-## Best Practices
-1. [Guideline 1]
-2. [Guideline 2]
-3. Benefits: [Key advantages]

package/dist/default_templates/patterns/environment/ide-features.md

@@ -1,17 +0,0 @@
-# $(basename "$file" .md | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') Pattern
-
-## Purpose
-[Pattern description from integration document]
-
-## Template
-```markdown
-[Key structure and variables]
-```
-
-## Examples
-[Concrete examples from v0, Claude, ChatGPT, Cline, etc.]
-
-## Best Practices
-1. [Guideline 1]
-2. [Guideline 2]
-3. Benefits: [Key advantages]

package/dist/default_templates/patterns/environment/os-commands.md

@@ -1,17 +0,0 @@
-# $(basename "$file" .md | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') Pattern
-
-## Purpose
-[Pattern description from integration document]
-
-## Template
-```markdown
-[Key structure and variables]
-```
-
-## Examples
-[Concrete examples from v0, Claude, ChatGPT, Cline, etc.]
-
-## Best Practices
-1. [Guideline 1]
-2. [Guideline 2]
-3. Benefits: [Key advantages]

package/dist/default_templates/patterns/organization/heading-hierarchy.md

@@ -1,103 +0,0 @@
-# Heading Hierarchy Pattern
-
-## Purpose
-Use Markdown headings to create scannable, nested instruction sections. From **v0**, **Claude**, and **Cline** patterns.
-
-## Template
-
-```markdown
-# {TOP_LEVEL_ROLE}
-
-## {SECTION_1}
-{Content}
-
-### {SUBSECTION_1_1}
-{Content}
-
-### {SUBSECTION_1_2}
-{Content}
-
-## {SECTION_2}
-{Content}
-
-### {SUBSECTION_2_1}
-{Content}
-
-## {SECTION_3}
-{Content}
-```
-
-## Examples
-
-### v0 (Code Generation Instructions)
-```markdown
-# v0 Code Generation Instructions
-
-## Code Style
-Write modern, idiomatic TypeScript with proper typing.
-
-### React Patterns
-- Use functional components with hooks
-- Prefer composition over inheritance
-- Extract reusable logic into custom hooks
-
-### Naming Conventions
-- Components: PascalCase (e.g., UserProfile)
-- Files: kebab-case (e.g., user-profile.tsx)
-- Functions: camelCase (e.g., handleSubmit)
-
-## Framework Requirements
-
-### Next.js App Router
-- Use Server Components by default
-- Add 'use client' only when necessary
-- Leverage React Server Components for data fetching
-
-### Routing
-- File-based routing in app/ directory
-- Use route groups (folders) for organization
-- Dynamic routes with [param] syntax
-```
-
-### Cline (Tool Usage Guidelines)
-```markdown
-# Cline Tool Usage Guidelines
-
-## File Operations
-
-### Reading Files
-- Use read_file for examining code
-- Read large sections to minimize API calls
-- Parallelize reads when possible
-
-### Writing Files
-- Show preview before making changes
-- Use replace_string_in_file for edits
-- Include 3-5 lines of context for accuracy
-
-## Terminal Commands
-
-### Command Execution
-- Run one command at a time (no parallel terminal calls)
-- Explain purpose of non-trivial commands
-- Use absolute paths to avoid navigation issues
-
-### Output Management
-- Filter output with grep/awk for large results
-- Use --no-pager for git commands
-- Disable paging to avoid truncation
-```
-
-## Variables
-- `{TOP_LEVEL_ROLE}`: Main purpose (H1 - appears once)
-- `{SECTION_X}`: Major category (H2 - primary divisions)
-- `{SUBSECTION_X_Y}`: Sub-category (H3 - detailed breakdowns)
-
-## Best Practices
-1. Use only one H1 (main title)
-2. H2 for major sections (5-10 max)
-3. H3 for subsections within H2
-4. Avoid going deeper than H3 (use lists instead)
-5. Keep headings concise (3-7 words)
-6. Use parallel structure (all H2s follow same pattern)
-7. Benefits: Easy to navigate, works in Markdown viewers, hierarchical structure

package/dist/default_templates/patterns/organization/sequential-workflows.md

@@ -1,102 +0,0 @@
-# Sequential Workflows Pattern
-
-## Purpose
-Define step-by-step processes with clear ordering. From **Manus** agent loop pattern.
-
-## Template
-
-```markdown
-## {WORKFLOW_NAME}
-
-Follow these steps in order:
-
-1. **{STEP_1_NAME}**: {STEP_1_DESCRIPTION}
-   - {SUBSTEP_1_1}
-   - {SUBSTEP_1_2}
-
-2. **{STEP_2_NAME}**: {STEP_2_DESCRIPTION}
-   - {SUBSTEP_2_1}
-   - {SUBSTEP_2_2}
-
-3. **{STEP_3_NAME}**: {STEP_3_DESCRIPTION}
-   - {SUBSTEP_3_1}
-   - {SUBSTEP_3_2}
-
-Repeat until {COMPLETION_CONDITION}.
-```
-
-## Examples
-
-### Manus (Agent Execution Loop)
-```markdown
-## Agent Execution Loop
-
-Follow these steps in order:
-
-1. **Analyze Request**: Understand user intent and break down into subtasks
-   - Read the user's message carefully
-   - Identify required information and tools
-   - Determine if clarification is needed
-
-2. **Plan Actions**: Decide which tool(s) to use
-   - Select one tool per iteration (no parallel tool calls)
-   - Gather necessary parameters
-   - Anticipate potential errors
-
-3. **Execute Tool**: Call the selected tool and process results
-   - Invoke tool with validated parameters
-   - Parse output for relevant information
-   - Update internal state with findings
-
-4. **Reflect**: Evaluate progress and decide next action
-   - Compare current state to goal
-   - Identify remaining subtasks
-   - Determine if another iteration is needed
-
-Repeat until all subtasks are completed or user goal is achieved.
-```
-
-### v0 (Code Generation Workflow)
-```markdown
-## Code Generation Workflow
-
-Follow these steps in order:
-
-1. **Understand Requirements**: Parse user request for technical specs
-   - Identify framework (React, Vue, etc.)
-   - Determine styling approach (Tailwind, CSS modules)
-   - Note any specific libraries requested
-
-2. **Plan Structure**: Design component hierarchy
-   - Break UI into logical components
-   - Identify shared vs unique elements
-   - Map out data flow
-
-3. **Generate Code**: Write implementation
-   - Start with outer container/layout
-   - Add child components progressively
-   - Include proper TypeScript types
-
-4. **Verify Quality**: Check for common issues
-   - Ensure accessibility (ARIA labels, semantic HTML)
-   - Validate responsive design breakpoints
-   - Confirm proper error handling
-
-Repeat for each component in the hierarchy.
-```
-
-## Variables
-- `{WORKFLOW_NAME}`: Process title (e.g., "Request Processing", "Error Recovery")
-- `{STEP_X_NAME}`: Phase name (e.g., "Analyze", "Execute", "Verify")
-- `{STEP_X_DESCRIPTION}`: What happens in this phase
-- `{SUBSTEP_X_Y}`: Granular actions within phase
-- `{COMPLETION_CONDITION}`: When to stop iterating
-
-## Best Practices
-1. Number steps explicitly (1, 2, 3...) for clarity
-2. Use bold for step names to make them scannable
-3. Limit to 5-7 main steps (sub-steps for detail)
-4. Include decision points ("If X, then Y")
-5. State iteration/termination conditions clearly
-6. Use present tense imperative ("Analyze", not "You should analyze")
-7. Benefits: Reproducible process, clear sequencing, easy to debug

package/dist/default_templates/patterns/organization/xml-rule-groups.md

@@ -1,64 +0,0 @@
-# XML Rule Groups Pattern
-
-## Purpose
-Structure instructions using XML-like tags for hierarchical organization. From **same.new** pattern.
-
-## Template
-
-```xml
-<rules>
-  <category name="{CATEGORY_NAME}">
-    <rule>{RULE_1}</rule>
-    <rule>{RULE_2}</rule>
-    <rule>{RULE_3}</rule>
-  </category>
-  
-  <category name="{CATEGORY_NAME_2}">
-    <rule>{RULE_4}</rule>
-    <rule>{RULE_5}</rule>
-  </category>
-</rules>
-```
-
-## Examples
-
-### same.new (Code Generation Rules)
-```xml
-<rules>
-  <category name="Code Style">
-    <rule>Use functional components with hooks, not class components</rule>
-    <rule>Prefer const over let, never use var</rule>
-    <rule>Use descriptive variable names (e.g., userData not ud)</rule>
-  </category>
-  
-  <category name="File Operations">
-    <rule>Always show a preview before writing files</rule>
-    <rule>Ask for confirmation before deleting or overwriting</rule>
-    <rule>Use relative paths for imports within the project</rule>
-  </category>
-  
-  <category name="Error Handling">
-    <rule>Wrap async operations in try-catch blocks</rule>
-    <rule>Return user-friendly error messages, not stack traces</rule>
-    <rule>Log errors for debugging but don't expose internals</rule>
-  </category>
-</rules>
-```
-
-## Variables
-- `{CATEGORY_NAME}`: Logical grouping (e.g., "Code Style", "Security", "Performance")
-- `{RULE_X}`: Specific instruction within category
-
-## Best Practices
-1. Keep categories focused (5-10 rules max per category)
-2. Use parallel structure for rules within a category
-3. Order categories by importance (most critical first)
-4. Use nested tags for sub-categories if needed:
-   ```xml
-   <category name="React">
-     <subcategory name="Hooks">
-       <rule>Always declare hooks at top level</rule>
-     </subcategory>
-   </category>
-   ```
-5. Benefits: Easy to scan, clear hierarchy, simple to add/remove sections