@olives/devos 2.1.0

package/.agents/skills/ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+       python search.py "<query>" --design-system --variance 8 --motion 9 --density 7
+
+Domains: style, prompt, color, chart, landing, product, ux, typography, google-fonts, gsap
+Stacks: react, nextjs, vue, svelte, astro, swiftui, react-native, flutter, nuxtjs, nuxt-ui, html-tailwind, shadcn, jetpack-compose, threejs, angular, laravel, javafx, wpf, winui, avalonia, uno, uwp
+
+Design dials (1-10, only with --design-system):
+  --variance   DESIGN_VARIANCE: 1=centered/minimal, 10=bold/asymmetric
+  --motion     MOTION_INTENSITY: 1=subtle, 10=complex; attaches a GSAP snippet from motion.csv
+  --density    VISUAL_DENSITY: 1=spacious, 10=dense/dashboard; overrides the spacing scale
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help=f"Stack-specific search. Available: {', '.join(AVAILABLE_STACKS)}")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+    # Design dials (1-10), only applied with --design-system
+    parser.add_argument("--variance", type=int, choices=range(1, 11), metavar="1-10", help="DESIGN_VARIANCE dial: 1=centered/minimal, 10=bold/asymmetric (only with --design-system)")
+    parser.add_argument("--motion", type=int, choices=range(1, 11), metavar="1-10", help="MOTION_INTENSITY dial: 1=subtle, 10=complex; pulls a matching GSAP snippet from motion.csv (only with --design-system)")
+    parser.add_argument("--density", type=int, choices=range(1, 11), metavar="1-10", help="VISUAL_DENSITY dial: 1=spacious, 10=dense/dashboard; overrides the spacing scale (only with --design-system)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query,
+            args.project_name,
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir,
+            variance=args.variance,
+            motion=args.motion,
+            density=args.density
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = (args.project_name or args.query).lower().replace(' ', '-')
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/.agents/skills/vercel-cli-with-tokens/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: vercel-cli-with-tokens
+description: Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login — e.g. "deploy to vercel", "set up vercel", "add environment variables to vercel".
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel CLI with Tokens
+
+Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on `vercel login`.
+
+## Step 1: Locate the Vercel Token
+
+Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:
+
+### A) `VERCEL_TOKEN` is already set in the environment
+
+```bash
+printenv VERCEL_TOKEN
+```
+
+If this returns a value, you're ready. Skip to Step 2.
+
+### B) Token is in a `.env` file under `VERCEL_TOKEN`
+
+```bash
+grep '^VERCEL_TOKEN=' .env 2>/dev/null
+```
+
+If found, export it:
+
+```bash
+export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
+```
+
+### C) Token is in a `.env` file under a different name
+
+Look for any variable that looks like a Vercel token (Vercel tokens typically start with `vca_`):
+
+```bash
+grep -i 'vercel' .env 2>/dev/null
+```
+
+Inspect the output to identify which variable holds the token, then export it as `VERCEL_TOKEN`:
+
+```bash
+export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
+```
+
+### D) No token found — ask the user
+
+If none of the above yield a token, ask the user to provide one. They can create a Vercel access token at vercel.com/account/tokens.
+
+---
+
+**Important:** Once `VERCEL_TOKEN` is exported as an environment variable, the Vercel CLI reads it natively — **do not pass it as a `--token` flag**. Putting secrets in command-line arguments exposes them in shell history and process listings.
+
+```bash
+# Bad — token visible in shell history and process listings
+vercel deploy --token "vca_abc123"
+
+# Good — CLI reads VERCEL_TOKEN from the environment
+export VERCEL_TOKEN="vca_abc123"
+vercel deploy
+```
+
+## Step 2: Locate the Project and Team
+
+Similarly, check for the project ID and team scope. These let the CLI target the right project without needing `vercel link`.
+
+```bash
+# Check environment
+printenv VERCEL_PROJECT_ID
+printenv VERCEL_ORG_ID
+
+# Or check .env
+grep -i 'vercel' .env 2>/dev/null
+```
+
+**If you have a project URL** (e.g. `https://vercel.com/my-team/my-project`), extract the team slug:
+
+```bash
+# e.g. "my-team" from "https://vercel.com/my-team/my-project"
+echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1
+```
+
+**If you have both `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` in your environment**, export them — the CLI will use these automatically and skip any `.vercel/` directory:
+
+```bash
+export VERCEL_ORG_ID="<org-id>"
+export VERCEL_PROJECT_ID="<project-id>"
+```
+
+Note: `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` must be set together — setting only one causes an error.
+
+## CLI Setup
+
+Ensure the Vercel CLI is installed and up to date:
+
+```bash
+npm install -g vercel
+vercel --version
+```
+
+## Deploying a Project
+
+Always deploy as **preview** unless the user explicitly requests production. Choose a method based on what you have available.
+
+### Quick Deploy (have project ID — no linking needed)
+
+When `VERCEL_TOKEN` and `VERCEL_PROJECT_ID` are set in the environment, deploy directly:
+
+```bash
+vercel deploy -y --no-wait
+```
+
+With a team scope (either via `VERCEL_ORG_ID` or `--scope`):
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Production (only when explicitly requested):
+
+```bash
+vercel deploy --prod --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Full Deploy Flow (no project ID — need to link)
+
+Use this when you have a token and team but no pre-existing project ID.
+
+#### Check project state first
+
+```bash
+# Does the project have a git remote?
+git remote get-url origin 2>/dev/null
+
+# Is it already linked to a Vercel project?
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+```
+
+#### Link the project
+
+**With git remote (preferred):**
+
+```bash
+vercel link --repo --scope <team-slug> -y
+```
+
+Reads the git remote and connects to the matching Vercel project. Creates `.vercel/repo.json`. More reliable than plain `vercel link`, which matches by directory name.
+
+**Without git remote:**
+
+```bash
+vercel link --scope <team-slug> -y
+```
+
+Creates `.vercel/project.json`.
+
+**Link to a specific project by name:**
+
+```bash
+vercel link --project <project-name> --scope <team-slug> -y
+```
+
+If the project is already linked, check `orgId` in `.vercel/project.json` or `.vercel/repo.json` to verify it matches the intended team.
+
+#### Deploy after linking
+
+**A) Git Push Deploy — has git remote (preferred)**
+
+Git pushes trigger automatic Vercel deployments.
+
+1. **Ask the user before pushing.** Never push without explicit approval.
+2. Commit and push:
+   ```bash
+   git add .
+   git commit -m "deploy: <description of changes>"
+   git push
+   ```
+3. Vercel builds automatically. Non-production branches get preview deployments.
+4. Retrieve the deployment URL:
+   ```bash
+   sleep 5
+   vercel ls --format json --scope <team-slug>
+   ```
+   Find the latest entry in the `deployments` array.
+
+**B) CLI Deploy — no git remote**
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Deploying from a Remote Repository (code not cloned locally)
+
+1. Clone the repository:
+   ```bash
+   git clone <repo-url>
+   cd <repo-name>
+   ```
+2. Link to Vercel:
+   ```bash
+   vercel link --repo --scope <team-slug> -y
+   ```
+3. Deploy via git push (if you have push access) or CLI deploy.
+
+### About `.vercel/` Directory
+
+A linked project has either:
+- `.vercel/project.json` — from `vercel link`. Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — from `vercel link --repo`. Contains `orgId`, `remoteName`, and a `projects` map.
+
+Not needed when `VERCEL_ORG_ID` + `VERCEL_PROJECT_ID` are both set in the environment.
+
+**Do NOT** run `vercel project inspect` or `vercel link` in an unlinked directory to detect state — they will interactively prompt or silently link as a side-effect. `vercel ls` is safe (in an unlinked directory it defaults to showing all deployments for the scope). `vercel whoami` is safe anywhere.
+
+## Managing Environment Variables
+
+```bash
+# Set for all environments
+echo "value" | vercel env add VAR_NAME --scope <team-slug>
+
+# Set for a specific environment (production, preview, development)
+echo "value" | vercel env add VAR_NAME production --scope <team-slug>
+
+# List environment variables
+vercel env ls --scope <team-slug>
+
+# Pull env vars to local .env.local file
+vercel env pull --scope <team-slug>
+
+# Remove a variable
+vercel env rm VAR_NAME --scope <team-slug> -y
+```
+
+## Inspecting Deployments
+
+```bash
+# List recent deployments
+vercel ls --format json --scope <team-slug>
+
+# Inspect a specific deployment
+vercel inspect <deployment-url>
+
+# View build logs (requires Vercel CLI v35+)
+vercel inspect <deployment-url> --logs
+
+# View runtime request logs (follows live by default; add --no-follow for a one-shot snapshot)
+vercel logs <deployment-url>
+```
+
+## Managing Domains
+
+```bash
+# List domains
+vercel domains ls --scope <team-slug>
+
+# Add a domain to the project — linked or env-linked directory (1 arg)
+vercel domains add <domain> --scope <team-slug>
+
+# Add a domain — unlinked directory (requires <project> positional)
+vercel domains add <domain> <project> --scope <team-slug>
+```
+
+## Stripe Projects Plan Changes
+
+If this project is managed by Stripe Projects. **Ask the user before running any paid or destructive plan change** — upgrades bill a real card, downgrades remove seats.
+
+First run `stripe projects status --json` to confirm the Vercel resource's local name. The examples below assume the default (`vercel-plan`); substitute the actual name if it was renamed at `stripe projects add` time.
+
+- **Upgrade to Pro:** `stripe projects add vercel/pro` (or `stripe projects upgrade vercel-plan pro`)
+- **Downgrade to Hobby:** `stripe projects downgrade vercel-plan hobby`
+
+### What Pro gives you
+
+- $20/month platform fee, includes $20/month of usage credit.
+- Turbo build machines (30 vCPUs, 60 GB memory) by default for new projects — significantly faster builds than Hobby.
+- 1 deploying seat + unlimited free Viewer seats (read-only collaborators, preview comments).
+- Higher included allocations (1 TB Fast Data Transfer, 10M Edge Requests per month).
+- Paid add-ons available: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.
+
+Full details: https://vercel.com/docs/plans/pro-plan
+
+## Working Agreement
+
+- **Never pass `VERCEL_TOKEN` as a `--token` flag.** Export it as an environment variable and let the CLI read it natively.
+- **Check the environment for tokens before asking the user.** Look in the current env and `.env` files first.
+- **Default to preview deployments.** Only deploy to production when explicitly asked.
+- **Ask before pushing to git.** Never push commits without the user's approval.
+- **Do not modify `.vercel/` files directly.** The CLI manages this directory. Reading them (e.g. to verify `orgId`) is fine.
+- **Do not curl/fetch deployed URLs to verify.** Just return the link to the user.
+- **Use `--format json`** when structured output will help with follow-up steps.
+- **Use `-y`** on commands that prompt for confirmation to avoid interactive blocking.
+
+## Troubleshooting
+
+### Token not found
+
+Check the environment and any `.env` files present:
+
+```bash
+printenv | grep -i vercel
+grep -i vercel .env 2>/dev/null
+```
+
+### Authentication error
+
+If the CLI fails with `Authentication required`:
+- The token may be expired or invalid.
+- Verify: `vercel whoami` (uses `VERCEL_TOKEN` from environment).
+- Ask the user for a fresh token.
+
+### Wrong team
+
+Verify the scope is correct:
+
+```bash
+vercel whoami --scope <team-slug>
+```
+
+### Build failure
+
+Check the build logs:
+
+```bash
+vercel inspect <deployment-url> --logs
+```
+
+Common causes:
+- Missing dependencies — ensure `package.json` is complete and committed.
+- Missing environment variables — add with `vercel env add`.
+- Framework misconfiguration — check `vercel.json`. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from `package.json`; override with `vercel.json` if detection is wrong.
+
+### CLI not installed
+
+```bash
+npm install -g vercel
+```