claude-mpm 5.4.59__py3-none-any.whl → 5.4.64__py3-none-any.whl

claude_mpm/skills/bundled/infrastructure/env-manager/references/validation.md

@@ -0,0 +1,420 @@
+# Environment Validation Workflows
+
+> **Part of**: [env-manager](../SKILL.md)
+> **Category**: infrastructure
+> **Reading Level**: Intermediate
+
+## Purpose
+
+Complete validation workflows for environment variables: structure checks, completeness verification, naming conventions, and framework-specific validation patterns.
+
+## Validation Hierarchy
+
+### Level 1: Structure Validation (Basic)
+Validates file format and syntax.
+
+### Level 2: Semantic Validation (Intermediate)
+Validates naming, completeness, framework conventions.
+
+### Level 3: Integration Validation (Advanced)
+Validates across environments, platforms, and services.
+
+## Structure Validation
+
+### Check 1: Valid Key-Value Format
+
+**What to Check:**
+```bash
+# Valid formats:
+KEY=value
+KEY="value with spaces"
+KEY='single quoted'
+KEY=
+
+# Invalid formats:
+key=value              # lowercase
+KEY = value            # spaces around =
+KEY=value # comment    # inline comments (parser-dependent)
+=value                 # missing key
+KEY                    # missing =
+```
+
+**Validation Script:**
+```python
+import re
+from pathlib import Path
+
+def validate_structure(env_file: Path) -> list[str]:
+    """Validate .env file structure."""
+    errors = []
+    valid_line_pattern = re.compile(r'^[A-Z_][A-Z0-9_]*=.*$')
+
+    with open(env_file) as f:
+        for line_num, line in enumerate(f, 1):
+            line = line.strip()
+
+            # Skip empty lines and comments
+            if not line or line.startswith('#'):
+                continue
+
+            # Check format
+            if not valid_line_pattern.match(line):
+                errors.append(f"Line {line_num}: Invalid format: {line}")
+
+            # Check for inline comments (warning)
+            if '#' in line and not line.startswith('#'):
+                # Check if # is inside quotes
+                key, value = line.split('=', 1)
+                if '#' in value and not (value.startswith('"') or value.startswith("'")):
+                    errors.append(f"Line {line_num}: WARNING: Possible inline comment: {line}")
+
+    return errors
+```
+
+### Check 2: No Duplicate Keys
+
+**Issue:**
+```bash
+# .env file
+DATABASE_URL=postgres://local
+DATABASE_URL=postgres://production  # Duplicate! Which wins?
+```
+
+**Validation:**
+```python
+def check_duplicates(env_file: Path) -> dict[str, list[int]]:
+    """Find duplicate keys and their line numbers."""
+    keys = {}
+
+    with open(env_file) as f:
+        for line_num, line in enumerate(f, 1):
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+
+            if '=' in line:
+                key = line.split('=', 1)[0]
+                if key in keys:
+                    keys[key].append(line_num)
+                else:
+                    keys[key] = [line_num]
+
+    # Return only duplicates
+    return {k: v for k, v in keys.items() if len(v) > 1}
+```
+
+### Check 3: Proper Quoting
+
+**Valid Quoting Patterns:**
+```bash
+# No quotes needed
+SIMPLE_VALUE=hello
+
+# Quotes required for spaces
+WITH_SPACES="hello world"
+
+# Quotes required for special chars
+SPECIAL_CHARS="value with = or # chars"
+
+# Escape quotes inside quotes
+ESCAPED="He said \"hello\""
+ESCAPED_SINGLE='It'\''s working'
+```
+
+**Validation:**
+```python
+def validate_quoting(env_file: Path) -> list[str]:
+    """Check for proper quoting."""
+    warnings = []
+
+    with open(env_file) as f:
+        for line_num, line in enumerate(f, 1):
+            line = line.strip()
+            if not line or line.startswith('#') or '=' not in line:
+                continue
+
+            key, value = line.split('=', 1)
+
+            # Check for spaces without quotes
+            if ' ' in value and not (value.startswith('"') or value.startswith("'")):
+                warnings.append(f"Line {line_num}: Value with spaces should be quoted: {key}")
+
+            # Check for special chars without quotes
+            if any(char in value for char in ['#', '=', '$']) and not value.startswith(('"', "'")):
+                warnings.append(f"Line {line_num}: Value with special chars should be quoted: {key}")
+
+    return warnings
+```
+
+## Completeness Validation
+
+### Compare Against .env.example
+
+**Workflow:**
+```python
+def compare_env_files(env_file: Path, example_file: Path) -> dict:
+    """Compare .env against .env.example."""
+
+    def parse_keys(file_path: Path) -> set[str]:
+        keys = set()
+        with open(file_path) as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith('#') and '=' in line:
+                    key = line.split('=', 1)[0]
+                    keys.add(key)
+        return keys
+
+    env_keys = parse_keys(env_file)
+    example_keys = parse_keys(example_file)
+
+    return {
+        'missing': example_keys - env_keys,  # Required but missing
+        'extra': env_keys - example_keys,    # Present but not documented
+        'common': env_keys & example_keys    # Properly documented
+    }
+```
+
+**Usage:**
+```bash
+# Find missing required variables
+python validate_env.py .env --compare .env.example
+
+# Output:
+# Missing variables (in .env.example but not .env):
+#   - DATABASE_URL
+#   - JWT_SECRET
+#   - SMTP_HOST
+#
+# Extra variables (in .env but not documented):
+#   - DEBUG_MODE
+#   - TEMP_API_KEY
+```
+
+### Check Required Variables by Environment
+
+**Pattern:**
+```python
+REQUIRED_VARS = {
+    'development': [
+        'NODE_ENV',
+        'DATABASE_URL',
+        'PORT'
+    ],
+    'production': [
+        'NODE_ENV',
+        'DATABASE_URL',
+        'PORT',
+        'JWT_SECRET',
+        'API_KEY',
+        'REDIS_URL'
+    ],
+    'test': [
+        'NODE_ENV',
+        'TEST_DATABASE_URL'
+    ]
+}
+
+def validate_required_vars(env_file: Path, environment: str) -> list[str]:
+    """Check if all required variables are present."""
+    required = REQUIRED_VARS.get(environment, [])
+    present = parse_keys(env_file)
+
+    missing = [var for var in required if var not in present]
+    return missing
+```
+
+## Naming Convention Validation
+
+### Standard Conventions
+
+**Valid Names:**
+```bash
+# Standard format: UPPERCASE_WITH_UNDERSCORES
+DATABASE_URL=value
+API_KEY=value
+MAX_CONNECTIONS=10
+
+# Framework-specific prefixes
+NEXT_PUBLIC_API_URL=value       # Next.js client-side
+VITE_API_URL=value              # Vite client-side
+REACT_APP_API_URL=value         # Create React App
+```
+
+**Invalid Names:**
+```bash
+# Bad patterns
+databaseUrl=value          # camelCase
+database-url=value         # kebab-case
+database.url=value         # dots
+123_KEY=value              # starts with number
+_PRIVATE_KEY=value         # leading underscore (convention warning)
+```
+
+**Validation:**
+```python
+import re
+
+def validate_naming_conventions(env_file: Path, framework: str = None) -> list[str]:
+    """Validate variable naming conventions."""
+    errors = []
+
+    # Standard pattern
+    standard_pattern = re.compile(r'^[A-Z][A-Z0-9_]*$')
+
+    # Framework-specific patterns
+    framework_patterns = {
+        'nextjs': re.compile(r'^(NEXT_PUBLIC_|NEXT_)[A-Z0-9_]+$'),
+        'vite': re.compile(r'^(VITE_)?[A-Z0-9_]+$'),
+        'react': re.compile(r'^(REACT_APP_)?[A-Z0-9_]+$'),
+    }
+
+    with open(env_file) as f:
+        for line_num, line in enumerate(f, 1):
+            line = line.strip()
+            if not line or line.startswith('#') or '=' not in line:
+                continue
+
+            key = line.split('=', 1)[0]
+
+            # Check standard pattern
+            if not standard_pattern.match(key):
+                errors.append(f"Line {line_num}: Invalid naming: {key} (use UPPERCASE_WITH_UNDERSCORES)")
+
+            # Check framework-specific patterns
+            if framework and framework in framework_patterns:
+                pattern = framework_patterns[framework]
+                if not pattern.match(key):
+                    errors.append(f"Line {line_num}: {framework} convention violation: {key}")
+
+    return errors
+```
+
+## Framework-Specific Validation
+
+### Next.js Validation
+
+**Rules:**
+```python
+def validate_nextjs_env(env_file: Path) -> list[str]:
+    """Validate Next.js environment variables."""
+    errors = []
+    warnings = []
+
+    with open(env_file) as f:
+        for line_num, line in enumerate(f, 1):
+            line = line.strip()
+            if not line or line.startswith('#') or '=' not in line:
+                continue
+
+            key, value = line.split('=', 1)
+
+            # Check NEXT_PUBLIC_ prefix rules
+            if key.startswith('NEXT_PUBLIC_'):
+                # Warn about secrets in public vars
+                if any(secret in key.lower() for secret in ['secret', 'key', 'password', 'token']):
+                    errors.append(f"Line {line_num}: SECURITY: Secret in NEXT_PUBLIC_ var: {key}")
+
+            # Check for client-side vars without NEXT_PUBLIC_
+            if any(client in key.lower() for client in ['api_url', 'api_endpoint']):
+                if not key.startswith('NEXT_PUBLIC_'):
+                    warnings.append(f"Line {line_num}: Client-side var without NEXT_PUBLIC_: {key}")
+
+    return errors, warnings
+```
+
+**File Precedence Check:**
+```python
+def check_nextjs_file_precedence(project_dir: Path) -> dict:
+    """Check Next.js .env file precedence."""
+    env_files = [
+        '.env.local',
+        '.env.development.local',
+        '.env.production.local',
+        '.env.development',
+        '.env.production',
+        '.env'
+    ]
+
+    found_files = []
+    for env_file in env_files:
+        if (project_dir / env_file).exists():
+            found_files.append(env_file)
+
+    # Parse and check for conflicts
+    all_vars = {}
+    for env_file in found_files:
+        vars_in_file = parse_env_file(project_dir / env_file)
+        for key, value in vars_in_file.items():
+            if key in all_vars:
+                all_vars[key].append((env_file, value))
+            else:
+                all_vars[key] = [(env_file, value)]
+
+    # Find variables defined in multiple files
+    conflicts = {k: v for k, v in all_vars.items() if len(v) > 1}
+
+    return {
+        'files_found': found_files,
+        'conflicts': conflicts,
+        'precedence_order': env_files
+    }
+```
+
+### Express/Node.js Validation
+
+**Standard Variables:**
+```python
+NODE_STANDARD_VARS = {
+    'NODE_ENV': ['development', 'production', 'test'],
+    'PORT': r'^\d+$',  # Must be a number
+    'DATABASE_URL': r'^postgres://|mysql://|mongodb://',  # Must be valid connection string
+}
+
+def validate_nodejs_env(env_file: Path) -> list[str]:
+    """Validate Node.js environment variables."""
+    errors = []
+    vars_dict = parse_env_file(env_file)
+
+    for key, value in vars_dict.items():
+        if key in NODE_STANDARD_VARS:
+            expected = NODE_STANDARD_VARS[key]
+
+            if isinstance(expected, list):
+                # Check enumeration
+                if value not in expected:
+                    errors.append(f"{key}: Invalid value '{value}', expected one of {expected}")
+            elif isinstance(expected, str):
+                # Check regex pattern
+                if not re.match(expected, value):
+                    errors.append(f"{key}: Value doesn't match expected format")
+
+    return errors
+```
+
+## Summary
+
+**Validation Workflow:**
+1. **Structure**: Valid format, no duplicates, proper quoting
+2. **Completeness**: All required vars present, compare with .env.example
+3. **Naming**: UPPERCASE_WITH_UNDERSCORES, framework prefixes
+4. **Framework**: Next.js NEXT_PUBLIC_, file precedence
+5. **Platform**: Vercel/Railway/Heroku conventions
+
+**Key Validations:**
+- ✅ Valid key-value format
+- ✅ No duplicate keys
+- ✅ Proper quoting for spaces/special chars
+- ✅ All required variables present
+- ✅ Consistent naming conventions
+- ✅ Framework-specific rules followed
+- ✅ No secrets in client-side vars (NEXT_PUBLIC_)
+
+## Related References
+
+- [Security](security.md): Secret scanning and exposure detection
+- [Synchronization](synchronization.md): Platform sync validation
+- [Frameworks](frameworks.md): Complete framework patterns
+
+---
+**Lines**: 285 ✓ 150-300 range

claude_mpm/skills/bundled/main/artifacts-builder/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: artifacts-builder
+description: Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
+license: Complete terms in LICENSE.txt
+progressive_disclosure:
+  entry_point:
+    summary: "Build complex React + TypeScript + shadcn/ui artifacts bundled to single HTML files"
+    when_to_use: "Complex artifacts requiring state management, routing, or shadcn/ui components (not simple HTML/JSX)"
+    quick_start: |
+      1. Initialize: bash scripts/init-artifact.sh <project-name>
+      2. Develop: Edit generated React/TypeScript files
+      3. Bundle: bash scripts/bundle-artifact.sh → creates bundle.html
+      4. Share bundled HTML as artifact with user
+      Stack: React 18 + TypeScript + Vite + Tailwind CSS + shadcn/ui
+    note: "Already optimal at 73 lines - scripts/ directory provides implementation details, no fragmentation needed"
+  references: []
+---
+
+# Artifacts Builder
+
+To build powerful frontend claude.ai artifacts, follow these steps:
+1. Initialize the frontend repo using `scripts/init-artifact.sh`
+2. Develop your artifact by editing the generated code
+3. Bundle all code into a single HTML file using `scripts/bundle-artifact.sh`
+4. Display artifact to user
+5. (Optional) Test the artifact
+
+**Stack**: React 18 + TypeScript + Vite + Parcel (bundling) + Tailwind CSS + shadcn/ui
+
+## Design & Style Guidelines
+
+VERY IMPORTANT: To avoid what is often referred to as "AI slop", avoid using excessive centered layouts, purple gradients, uniform rounded corners, and Inter font.
+
+## Quick Start
+
+### Step 1: Initialize Project
+
+Run the initialization script to create a new React project:
+```bash
+bash scripts/init-artifact.sh <project-name>
+cd <project-name>
+```
+
+This creates a fully configured project with:
+- ✅ React + TypeScript (via Vite)
+- ✅ Tailwind CSS 3.4.1 with shadcn/ui theming system
+- ✅ Path aliases (`@/`) configured
+- ✅ 40+ shadcn/ui components pre-installed
+- ✅ All Radix UI dependencies included
+- ✅ Parcel configured for bundling (via .parcelrc)
+- ✅ Node 18+ compatibility (auto-detects and pins Vite version)
+
+### Step 2: Develop Your Artifact
+
+To build the artifact, edit the generated files. See **Common Development Tasks** below for guidance.
+
+### Step 3: Bundle to Single HTML File
+
+To bundle the React app into a single HTML artifact:
+```bash
+bash scripts/bundle-artifact.sh
+```
+
+This creates `bundle.html` - a self-contained artifact with all JavaScript, CSS, and dependencies inlined. This file can be directly shared in Claude conversations as an artifact.
+
+**Requirements**: Your project must have an `index.html` in the root directory.
+
+**What the script does**:
+- Installs bundling dependencies (parcel, @parcel/config-default, parcel-resolver-tspaths, html-inline)
+- Creates `.parcelrc` config with path alias support
+- Builds with Parcel (no source maps)
+- Inlines all assets into single HTML using html-inline
+
+### Step 4: Share Artifact with User
+
+Finally, share the bundled HTML file in conversation with the user so they can view it as an artifact.
+
+### Step 5: Testing/Visualizing the Artifact (Optional)
+
+Note: This is a completely optional step. Only perform if necessary or requested.
+
+To test/visualize the artifact, use available tools (including other Skills or built-in tools like Playwright or Puppeteer). In general, avoid testing the artifact upfront as it adds latency between the request and when the finished artifact can be seen. Test later, after presenting the artifact, if requested or if issues arise.
+
+## Reference
+
+- **shadcn/ui components**: https://ui.shadcn.com/docs/components

claude_mpm/skills/bundled/main/internal-comms/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: internal-comms
+description: A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).
+license: Complete terms in LICENSE.txt
+progressive_disclosure:
+  entry_point:
+    summary: "Write internal communications using company-specific formats and guidelines"
+    when_to_use: "Writing 3P updates, newsletters, FAQs, status reports, leadership updates, project updates, or incident reports"
+    quick_start: |
+      1. Identify communication type (3P update, newsletter, FAQ, etc.)
+      2. Load appropriate guideline from examples/ directory
+      3. Follow specific instructions for formatting, tone, and content
+      Available: examples/3p-updates.md, examples/company-newsletter.md, examples/faq-answers.md, examples/general-comms.md
+    note: "Already optimal at 32 lines - examples/ directory provides all format guidelines, no fragmentation needed"
+  references: []
+---
+
+## When to use this skill
+To write internal communications, use this skill for:
+- 3P updates (Progress, Plans, Problems)
+- Company newsletters
+- FAQ responses
+- Status reports
+- Leadership updates
+- Project updates
+- Incident reports
+
+## How to use this skill
+
+To write any internal communication:
+
+1. **Identify the communication type** from the request
+2. **Load the appropriate guideline file** from the `examples/` directory:
+    - `examples/3p-updates.md` - For Progress/Plans/Problems team updates
+    - `examples/company-newsletter.md` - For company-wide newsletters
+    - `examples/faq-answers.md` - For answering frequently asked questions
+    - `examples/general-comms.md` - For anything else that doesn't explicitly match one of the above
+3. **Follow the specific instructions** in that file for formatting, tone, and content gathering
+
+If the communication type doesn't match any existing guideline, ask for clarification or more context about the desired format.
+
+## Keywords
+3P updates, company newsletter, company comms, weekly update, faqs, common questions, updates, internal comms

claude_mpm/skills/bundled/main/internal-comms/examples/3p-updates.md

@@ -0,0 +1,47 @@
+## Instructions
+You are being asked to write a 3P update. 3P updates stand for "Progress, Plans, Problems." The main audience is for executives, leadership, other teammates, etc. They're meant to be very succinct and to-the-point: think something you can read in 30-60sec or less. They're also for people with some, but not a lot of context on what the team does.
+
+3Ps can cover a team of any size, ranging all the way up to the entire company. The bigger the team, the less granular the tasks should be. For example, "mobile team" might have "shipped feature" or "fixed bugs," whereas the company might have really meaty 3Ps, like "hired 20 new people" or "closed 10 new deals." 
+
+They represent the work of the team across a time period, almost always one week. They include three sections:
+1) Progress: what the team has accomplished over the next time period. Focus mainly on things shipped, milestones achieved, tasks created, etc.
+2) Plans: what the team plans to do over the next time period. Focus on what things are top-of-mind, really high priority, etc. for the team.
+3) Problems: anything that is slowing the team down. This could be things like too few people, bugs or blockers that are preventing the team from moving forward, some deal that fell through, etc.
+
+Before writing them, make sure that you know the team name. If it's not specified, you can ask explicitly what the team name you're writing for is.
+
+
+## Tools Available
+Whenever possible, try to pull from available sources to get the information you need:
+- Slack: posts from team members with their updates - ideally look for posts in large channels with lots of reactions
+- Google Drive: docs written from critical team members with lots of views
+- Email: emails with lots of responses of lots of content that seems relevant
+- Calendar: non-recurring meetings that have a lot of importance, like product reviews, etc.
+
+
+Try to gather as much context as you can, focusing on the things that covered the time period you're writing for:
+- Progress: anything between a week ago and today
+- Plans: anything from today to the next week
+- Problems: anything between a week ago and today
+
+
+If you don't have access, you can ask the user for things they want to cover. They might also include these things to you directly, in which case you're mostly just formatting for this particular format.
+
+## Workflow
+
+1. **Clarify scope**: Confirm the team name and time period (usually past week for Progress/Problems, next
+week for Plans)
+2. **Gather information**: Use available tools or ask the user directly
+3. **Draft the update**: Follow the strict formatting guidelines
+4. **Review**: Ensure it's concise (30-60 seconds to read) and data-driven
+
+## Formatting
+
+The format is always the same, very strict formatting. Never use any formatting other than this. Pick an emoji that is fun and captures the vibe of the team and update.
+
+[pick an emoji] [Team Name] (Dates Covered, usually a week)
+Progress: [1-3 sentences of content]
+Plans: [1-3 sentences of content]
+Problems: [1-3 sentences of content]
+
+Each section should be no more than 1-3 sentences: clear, to the point. It should be data-driven, and generally include metrics where possible. The tone should be very matter-of-fact, not super prose-heavy.

claude_mpm/skills/bundled/main/internal-comms/examples/company-newsletter.md

@@ -0,0 +1,65 @@
+## Instructions
+You are being asked to write a company-wide newsletter update. You are meant to summarize the past week/month of a company in the form of a newsletter that the entire company will read. It should be maybe ~20-25 bullet points long. It will be sent via Slack and email, so make it consumable for that.
+
+Ideally it includes the following attributes:
+- Lots of links: pulling documents from Google Drive that are very relevant, linking to prominent Slack messages in announce channels and from executives, perhgaps referencing emails that went company-wide, highlighting significant things that have happened in the company.
+- Short and to-the-point: each bullet should probably be no longer than ~1-2 sentences
+- Use the "we" tense, as you are part of the company. Many of the bullets should say "we did this" or "we did that"
+
+## Tools to use
+If you have access to the following tools, please try to use them. If not, you can also let the user know directly that their responses would be better if they gave them access.
+
+- Slack: look for messages in channels with lots of people, with lots of reactions or lots of responses within the thread
+- Email: look for things from executives that discuss company-wide announcements
+- Calendar: if there were meetings with large attendee lists, particularly things like All-Hands meetings, big company announcements, etc. If there were documents attached to those meetings, those are great links to include.
+- Documents: if there were new docs published in the last week or two that got a lot of attention, you can link them. These should be things like company-wide vision docs, plans for the upcoming quarter or half, things authored by critical executives, etc.
+- External press: if you see references to articles or press we've received over the past week, that could be really cool too.
+
+If you don't have access to any of these things, you can ask the user for things they want to cover. In this case, you'll mostly just be polishing up and fitting to this format more directly.
+
+## Sections
+The company is pretty big: 1000+ people. There are a variety of different teams and initiatives going on across the company. To make sure the update works well, try breaking it into sections of similar things. You might break into clusters like {product development, go to market, finance} or {recruiting, execution, vision}, or {external news, internal news} etc. Try to make sure the different areas of the company are highlighted well.
+
+## Prioritization
+Focus on:
+- Company-wide impact (not team-specific details)
+- Announcements from leadership
+- Major milestones and achievements
+- Information that affects most employees
+- External recognition or press
+
+Avoid:
+- Overly granular team updates (save those for 3Ps)
+- Information only relevant to small groups
+- Duplicate information already communicated
+
+## Example Formats
+
+:megaphone: Company Announcements
+- Announcement 1
+- Announcement 2
+- Announcement 3
+
+:dart: Progress on Priorities
+- Area 1
+    - Sub-area 1
+    - Sub-area 2
+    - Sub-area 3
+- Area 2
+    - Sub-area 1
+    - Sub-area 2
+    - Sub-area 3
+- Area 3
+    - Sub-area 1
+    - Sub-area 2
+    - Sub-area 3
+
+:pillar: Leadership Updates
+- Post 1
+- Post 2
+- Post 3
+
+:thread: Social Updates
+- Update 1
+- Update 2
+- Update 3