@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/netlify-deploy/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: netlify-deploy
+description: Deploy web projects to Netlify using the Netlify CLI (`npx netlify`). Use when the user asks to deploy, host, publish, or link a site/repo on Netlify, including preview and production deploys.
+---
+
+# Netlify Deployment Skill
+
+Deploy web projects to Netlify using the Netlify CLI with intelligent detection of project configuration and deployment context.
+
+## Overview
+
+This skill automates Netlify deployments by:
+- Verifying Netlify CLI authentication
+- Detecting project configuration and framework
+- Linking to existing sites or creating new ones
+- Deploying to production or preview environments
+
+## Prerequisites
+
+- **Netlify CLI**: Installed via npx (no global install required)
+- **Authentication**: Netlify account with active login session
+- **Project**: Valid web project in current directory
+- Respect the current runtime permission and network policy. If deployment network calls are blocked, stop and report the blocker; ask the user to run in an environment where they have explicitly allowed Netlify network access.
+- The deployment might take a few minutes. Use appropriate timeout values.
+
+## Authentication Pattern
+
+The skill uses the **pre-authenticated Netlify CLI** approach:
+
+1. Check authentication status with `npx netlify status`
+2. If not authenticated, guide user through `npx netlify login`
+3. Fail gracefully if authentication cannot be established
+
+Authentication uses either:
+- **Browser-based OAuth** (primary): `netlify login` opens browser for authentication
+- **API Key** (alternative): Set `NETLIFY_AUTH_TOKEN` environment variable
+
+## Workflow
+
+### 1. Verify Netlify CLI Authentication
+
+Check if the user is logged into Netlify:
+
+```bash
+npx netlify status
+```
+
+**Expected output patterns**:
+- ✅ Authenticated: Shows logged-in user email and site link status
+- ❌ Not authenticated: "Not logged into any site" or authentication error
+
+**If not authenticated**, guide the user:
+
+```bash
+npx netlify login
+```
+
+This opens a browser window for OAuth authentication. Wait for user to complete login, then verify with `netlify status` again.
+
+**Alternative: API Key authentication**
+
+If browser authentication isn't available, users can set:
+
+```bash
+export NETLIFY_AUTH_TOKEN=your_token_here
+```
+
+Tokens can be generated at: https://app.netlify.com/user/applications#personal-access-tokens
+
+### 2. Detect Site Link Status
+
+From `netlify status` output, determine:
+- **Linked**: Site already connected to Netlify (shows site name/URL)
+- **Not linked**: Need to link or create site
+
+### 3. Link to Existing Site or Create New
+
+**If already linked** → Skip to step 4
+
+**If not linked**, attempt to link by Git remote:
+
+```bash
+# Check if project is Git-based
+git remote show origin
+
+# If Git-based, extract remote URL
+# Format: https://github.com/username/repo or git@github.com:username/repo.git
+
+# Try to link by Git remote
+npx netlify link --git-remote-url <REMOTE_URL>
+```
+
+**If link fails** (site doesn't exist on Netlify):
+
+```bash
+# Create new site interactively
+npx netlify init
+```
+
+This guides user through:
+1. Choosing team/account
+2. Setting site name
+3. Configuring build settings
+4. Creating netlify.toml if needed
+
+### 4. Verify Dependencies
+
+Before deploying, ensure project dependencies are installed:
+
+```bash
+# For npm projects
+npm install
+
+# For other package managers, detect and use appropriate command
+# yarn install, pnpm install, etc.
+```
+
+### 5. Deploy to Netlify
+
+Choose deployment type based on context:
+
+**Preview/Draft Deploy** (default for existing sites):
+
+```bash
+npx netlify deploy
+```
+
+This creates a deploy preview with a unique URL for testing.
+
+**Production Deploy** (for new sites or explicit production deployments):
+
+```bash
+npx netlify deploy --prod
+```
+
+This deploys to the live production URL.
+
+**Deployment process**:
+1. CLI detects build settings (from netlify.toml or prompts user)
+2. Builds the project locally
+3. Uploads built assets to Netlify
+4. Returns deployment URL
+
+### 6. Report Results
+
+After deployment, report to user:
+- **Deploy URL**: Unique URL for this deployment
+- **Site URL**: Production URL (if production deploy)
+- **Deploy logs**: Link to Netlify dashboard for logs
+- **Next steps**: Suggest `netlify open` to view site or dashboard
+
+## Handling netlify.toml
+
+If a `netlify.toml` file exists, the CLI uses it automatically. If not, the CLI will prompt for:
+- **Build command**: e.g., `npm run build`, `next build`
+- **Publish directory**: e.g., `dist`, `build`, `.next`
+
+Common framework defaults:
+- **Next.js**: build command `npm run build`, publish `.next`
+- **React (Vite)**: build command `npm run build`, publish `dist`
+- **Static HTML**: no build command, publish current directory
+
+The skill should detect framework from `package.json` if possible and suggest appropriate settings.
+
+## Example Full Workflow
+
+```bash
+# 1. Check authentication
+npx netlify status
+
+# If not authenticated:
+npx netlify login
+
+# 2. Link site (if needed)
+# Try Git-based linking first
+git remote show origin
+npx netlify link --git-remote-url https://github.com/user/repo
+
+# If no site exists, create new one:
+npx netlify init
+
+# 3. Install dependencies
+npm install
+
+# 4. Deploy (preview for testing)
+npx netlify deploy
+
+# 5. Deploy to production (when ready)
+npx netlify deploy --prod
+```
+
+## Error Handling
+
+Common issues and solutions:
+
+**"Not logged in"**
+→ Run `npx netlify login`
+
+**"No site linked"**
+→ Run `npx netlify link` or `npx netlify init`
+
+**"Build failed"**
+→ Check build command and publish directory in netlify.toml or CLI prompts
+→ Verify dependencies are installed
+→ Review build logs for specific errors
+
+**"Publish directory not found"**
+→ Verify build command ran successfully
+→ Check publish directory path is correct
+
+## Troubleshooting
+
+### Escalated Network Access
+
+If deployment fails due to network issues (timeouts, DNS errors, connection resets), first distinguish provider/network failure from runtime policy blocking. When runtime policy blocks outbound deployment calls, do not weaken the policy from inside the skill; stop and ask the user to explicitly approve or run from an environment with Netlify network access.
+
+Example guidance to the user:
+
+```
+The deploy needs Netlify network access, but the current runtime policy blocked it. Please approve network access or run this deploy from an environment where Netlify access is allowed.
+```
+
+## Environment Variables
+
+For secrets and configuration:
+
+1. Never commit secrets to Git
+2. Set in Netlify dashboard: Site Settings → Environment Variables
+3. Access in builds via `process.env.VARIABLE_NAME`
+
+## Tips
+
+- Use `netlify deploy` (no `--prod`) first to test before production
+- Run `netlify open` to view site in Netlify dashboard
+- Run `netlify logs` to view function logs (if using Netlify Functions)
+- Use `netlify dev` for local development with Netlify Functions
+
+## Reference
+
+- Netlify CLI Docs: https://docs.netlify.com/cli/get-started/
+- netlify.toml Reference: https://docs.netlify.com/configure-builds/file-based-configuration/
+
+## Bundled References (Load As Needed)
+
+- [CLI commands](references/cli-commands.md)
+- [Deployment patterns](references/deployment-patterns.md)
+- [netlify.toml guide](references/netlify-toml.md)

package/skills/netlify-deploy/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Netlify Deploy"
+  short_description: "Deploy web projects to Netlify with the Netlify CLI"
+  icon_small: "./assets/netlify-small.svg"
+  icon_large: "./assets/netlify.png"
+  default_prompt: "Deploy this project to Netlify and return the preview URL, build settings, and any required fixes."

package/skills/netlify-deploy/assets/netlify-small.svg

@@ -0,0 +1,11 @@
+<svg width="16" height="16" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+  <g transform="translate(0 7.6825)" fill="currentColor">
+    <path d="M34.593 94.2052H33.3844L27.3514 88.1722V86.9637L36.5743 77.7409H42.9639L43.8158 78.5928V84.9824L34.593 94.2052Z" />
+    <path d="M27.3514 25.9703V24.7617L33.3844 18.7287H34.593L43.8158 27.9515V34.3411L42.9639 35.1931H36.5743L27.3514 25.9703Z" />
+    <path d="M80.4594 74.759H71.6824L70.9493 74.026V53.4802C70.9493 49.8248 69.5129 46.9915 65.1046 46.8925C62.836 46.833 60.2405 46.8925 57.4668 47.0014L57.0507 47.4274V74.0161L56.3176 74.7491H47.5406L46.8075 74.0161V38.9179L47.5406 38.1848H67.2939C74.9713 38.1848 81.1925 44.406 81.1925 52.0834V74.026L80.4594 74.759Z" />
+    <path d="M35.8412 61.6034H0.73307L0 60.8703V52.0735L0.73307 51.3404H35.8412L36.5743 52.0735V60.8703L35.8412 61.6034Z" />
+    <path d="M127.277 61.6034H92.1687L91.4356 60.8703V52.0735L92.1687 51.3404H127.277L128.01 52.0735V60.8703L127.277 61.6034Z" />
+    <path d="M58.9428 27.2185V0.887367L59.6759 0.154297H68.4727L69.2058 0.887367V27.2185L68.4727 27.9515H59.6759L58.9428 27.2185Z" />
+    <path d="M58.9428 112.056V85.7254L59.6759 84.9923H68.4727L69.2058 85.7254V112.056L68.4727 112.79H59.6759L58.9428 112.056Z" />
+  </g>
+</svg>

package/skills/netlify-deploy/references/cli-commands.md

@@ -0,0 +1,162 @@
+# Netlify CLI Commands Reference
+
+Quick reference for common Netlify CLI commands used in deployments.
+
+## Authentication
+
+```bash
+# Login via browser OAuth
+npx netlify login
+
+# Check authentication status and site link
+npx netlify status
+
+# Logout
+npx netlify logout
+```
+
+## Site Management
+
+```bash
+# Link current directory to existing site
+npx netlify link
+
+# Link by Git remote URL
+npx netlify link --git-remote-url <url>
+
+# Create and link new site
+npx netlify init
+
+# Unlink from current site
+npx netlify unlink
+
+# Open site in Netlify dashboard
+npx netlify open
+
+# Open site admin panel
+npx netlify open:admin
+
+# Open site in browser
+npx netlify open:site
+```
+
+## Deployment
+
+```bash
+# Deploy preview/draft (safe for testing)
+npx netlify deploy
+
+# Deploy to production
+npx netlify deploy --prod
+
+# Deploy with specific directory
+npx netlify deploy --dir=dist
+
+# Deploy with message
+npx netlify deploy --message="Deploy message"
+
+# List all deploys
+npx netlify deploy:list
+```
+
+## Development
+
+```bash
+# Run local dev server with Netlify features
+npx netlify dev
+
+# Run local dev server on specific port
+npx netlify dev --port 3000
+```
+
+## Site Information
+
+```bash
+# Get site info
+npx netlify sites:list
+
+# Get current site info
+npx netlify api getSite --data '{"site_id": "YOUR_SITE_ID"}'
+```
+
+## Environment Variables
+
+```bash
+# List environment variables
+npx netlify env:list
+
+# Set environment variable
+npx netlify env:set KEY value
+
+# Get environment variable value
+npx netlify env:get KEY
+
+# Import env vars from file
+npx netlify env:import .env
+```
+
+## Build
+
+```bash
+# Show build settings
+npx netlify build --dry
+
+# Run build locally
+npx netlify build
+```
+
+## Functions (Serverless)
+
+```bash
+# List functions
+npx netlify functions:list
+
+# Invoke function locally
+npx netlify functions:invoke FUNCTION_NAME
+
+# Create new function
+npx netlify functions:create FUNCTION_NAME
+```
+
+## Logs
+
+```bash
+# Stream function logs
+npx netlify logs
+
+# View logs for specific function
+npx netlify logs:function FUNCTION_NAME
+```
+
+## Troubleshooting Commands
+
+```bash
+# Check CLI version
+npx netlify --version
+
+# Get help for any command
+npx netlify help [command]
+
+# Check status with verbose output
+npx netlify status --verbose
+```
+
+## Exit Codes
+
+- `0` - Success
+- `1` - General error
+- `2` - Authentication error
+- `3` - Site not found
+- `4` - Build failed
+
+## Common Flags
+
+- `--json` - Output as JSON
+- `--silent` - Suppress output
+- `--debug` - Show debug information
+- `--force` - Skip confirmation prompts
+
+## Resources
+
+- Full CLI documentation: https://docs.netlify.com/cli/get-started/
+- CLI GitHub repository: https://github.com/netlify/cli