@vetala/vetala 0.1.0-beta

package/skill/composition-patterns/rules/state-decouple-implementation.md

@@ -0,0 +1,113 @@
+---
+title: Decouple State Management from UI
+impact: MEDIUM
+impactDescription: enables swapping state implementations without changing UI
+tags: composition, state, architecture
+---
+
+## Decouple State Management from UI
+
+The provider component should be the only place that knows how state is managed.
+UI components consume the context interface—they don't know if state comes from
+useState, Zustand, or a server sync.
+
+**Incorrect (UI coupled to state implementation):**
+
+```tsx
+function ChannelComposer({ channelId }: { channelId: string }) {
+  // UI component knows about global state implementation
+  const state = useGlobalChannelState(channelId)
+  const { submit, updateInput } = useChannelSync(channelId)
+
+  return (
+    <Composer.Frame>
+      <Composer.Input
+        value={state.input}
+        onChange={(text) => sync.updateInput(text)}
+      />
+      <Composer.Submit onPress={() => sync.submit()} />
+    </Composer.Frame>
+  )
+}
+```
+
+**Correct (state management isolated in provider):**
+
+```tsx
+// Provider handles all state management details
+function ChannelProvider({
+  channelId,
+  children,
+}: {
+  channelId: string
+  children: React.ReactNode
+}) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update, submit }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+// UI component only knows about the context interface
+function ChannelComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Usage
+function Channel({ channelId }: { channelId: string }) {
+  return (
+    <ChannelProvider channelId={channelId}>
+      <ChannelComposer />
+    </ChannelProvider>
+  )
+}
+```
+
+**Different providers, same UI:**
+
+```tsx
+// Local state for ephemeral forms
+function ForwardMessageProvider({ children }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+// Global synced state for channels
+function ChannelProvider({ channelId, children }) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+
+  return (
+    <Composer.Provider state={state} actions={{ update, submit }}>
+      {children}
+    </Composer.Provider>
+  )
+}
+```
+
+The same `Composer.Input` component works with both providers because it only
+depends on the context interface, not the implementation.

package/skill/composition-patterns/rules/state-lift-state.md

@@ -0,0 +1,125 @@
+---
+title: Lift State into Provider Components
+impact: HIGH
+impactDescription: enables state sharing outside component boundaries
+tags: composition, state, context, providers
+---
+
+## Lift State into Provider Components
+
+Move state management into dedicated provider components. This allows sibling
+components outside the main UI to access and modify state without prop drilling
+or awkward refs.
+
+**Incorrect (state trapped inside component):**
+
+```tsx
+function ForwardMessageComposer() {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer />
+    </Composer.Frame>
+  )
+}
+
+// Problem: How does this button access composer state?
+function ForwardMessageDialog() {
+  return (
+    <Dialog>
+      <ForwardMessageComposer />
+      <MessagePreview /> {/* Needs composer state */}
+      <DialogActions>
+        <CancelButton />
+        <ForwardButton /> {/* Needs to call submit */}
+      </DialogActions>
+    </Dialog>
+  )
+}
+```
+
+**Incorrect (useEffect to sync state up):**
+
+```tsx
+function ForwardMessageDialog() {
+  const [input, setInput] = useState('')
+  return (
+    <Dialog>
+      <ForwardMessageComposer onInputChange={setInput} />
+      <MessagePreview input={input} />
+    </Dialog>
+  )
+}
+
+function ForwardMessageComposer({ onInputChange }) {
+  const [state, setState] = useState(initialState)
+  useEffect(() => {
+    onInputChange(state.input) // Sync on every change 😬
+  }, [state.input])
+}
+```
+
+**Incorrect (reading state from ref on submit):**
+
+```tsx
+function ForwardMessageDialog() {
+  const stateRef = useRef(null)
+  return (
+    <Dialog>
+      <ForwardMessageComposer stateRef={stateRef} />
+      <ForwardButton onPress={() => submit(stateRef.current)} />
+    </Dialog>
+  )
+}
+```
+
+**Correct (state lifted to provider):**
+
+```tsx
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        <ForwardMessageComposer />
+        <MessagePreview /> {/* Custom components can access state and actions */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton /> {/* Custom components can access state and actions */}
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  )
+}
+
+function ForwardButton() {
+  const { actions } = use(Composer.Context)
+  return <Button onPress={actions.submit}>Forward</Button>
+}
+```
+
+The ForwardButton lives outside the Composer.Frame but still has access to the
+submit action because it's within the provider. Even though it's a one-off
+component, it can still access the composer's state and actions from outside the
+UI itself.
+
+**Key insight:** Components that need shared state don't have to be visually
+nested inside each other—they just need to be within the same provider.

package/skill/deploy-to-vercel/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: deploy-to-vercel
+description: Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".
+---
+
+# Deploy to Vercel
+
+Deploy any project to Vercel. **Always deploy as preview** (not production) unless the user explicitly asks for production.
+
+The goal is to get the user into the best long-term setup: their project linked to Vercel with git-push deploys. Every method below tries to move the user closer to that state.
+
+## Step 1: Gather Project State
+
+Run all four checks before deciding which method to use:
+
+```bash
+# 1. Check for a git remote
+git remote get-url origin 2>/dev/null
+
+# 2. Check if locally linked to a Vercel project (either file means linked)
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+
+# 3. Check if the Vercel CLI is installed and authenticated
+vercel whoami 2>/dev/null
+
+# 4. List available teams (if authenticated)
+vercel teams list --format json 2>/dev/null
+```
+
+### Team selection
+
+If the user belongs to multiple teams, present all available team slugs as a bulleted list and ask which one to deploy to. Once the user picks a team, proceed immediately to the next step — do not ask for additional confirmation.
+
+Pass the team slug via `--scope` on all subsequent CLI commands (`vercel deploy`, `vercel link`, `vercel inspect`, etc.):
+
+```bash
+vercel deploy [path] -y --no-wait --scope <team-slug>
+```
+
+If the project is already linked (`.vercel/project.json` or `.vercel/repo.json` exists), the `orgId` in those files determines the team — no need to ask again. If there is only one team (or just a personal account), skip the prompt and use it directly.
+
+**About the `.vercel/` directory:** A linked project has either:
+- `.vercel/project.json` — created by `vercel link` (single project linking). Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — created by `vercel link --repo` (repo-based linking). Contains `orgId`, `remoteName`, and a `projects` array mapping directories to Vercel project IDs.
+
+Either file means the project is linked. Check for both.
+
+**Do NOT** use `vercel project inspect`, `vercel ls`, or `vercel link` to detect state in an unlinked directory — without a `.vercel/` config, they will interactively prompt (or with `--yes`, silently link as a side-effect). Only `vercel whoami` is safe to run anywhere.
+
+## Step 2: Choose a Deploy Method
+
+### Linked (`.vercel/` exists) + has git remote → Git Push
+
+This is the ideal state. The project is linked and has git integration.
+
+1. **Ask the user before pushing.** Never push without explicit approval:
+   ```
+   This project is connected to Vercel via git. I can commit and push to
+   trigger a deployment. Want me to proceed?
+   ```
+
+2. **Commit and push:**
+   ```bash
+   git add .
+   git commit -m "deploy: <description of changes>"
+   git push
+   ```
+   Vercel automatically builds from the push. Non-production branches get preview deployments; the production branch (usually `main`) gets a production deployment.
+
+3. **Retrieve the preview URL.** If the CLI is authenticated:
+   ```bash
+   sleep 5
+   vercel ls --format json
+   ```
+   The JSON output has a `deployments` array. Find the latest entry — its `url` field is the preview URL.
+
+   If the CLI is not authenticated, tell the user to check the Vercel dashboard or the commit status checks on their git provider for the preview URL.
+
+---
+
+### Linked (`.vercel/` exists) + no git remote → `vercel deploy`
+
+The project is linked but there's no git repo. Deploy directly with the CLI.
+
+```bash
+vercel deploy [path] -y --no-wait
+```
+
+Use `--no-wait` so the CLI returns immediately with the deployment URL instead of blocking until the build finishes (builds can take a while). Then check on the deployment status with:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+For production deploys (only if user explicitly asks):
+```bash
+vercel deploy [path] --prod -y --no-wait
+```
+
+---
+
+### Not linked + CLI is authenticated → Link first, then deploy
+
+The CLI is working but the project isn't linked yet. This is the opportunity to get the user into the best state.
+
+1. **Ask the user which team to deploy to.** Present the team slugs from Step 1 as a bulleted list. If there's only one team (or just a personal account), skip this step.
+
+2. **Once a team is selected, proceed directly to linking.** Tell the user what will happen but do not ask for separate confirmation:
+   ```
+   Linking this project to <team name> on Vercel. This will create a Vercel
+   project to deploy to and enable automatic deployments on future git pushes.
+   ```
+
+3. **If a git remote exists**, use repo-based linking with the selected team scope:
+   ```bash
+   vercel link --repo --scope <team-slug>
+   ```
+   This reads the git remote URL and matches it to existing Vercel projects that deploy from that repo. It creates `.vercel/repo.json`. This is much more reliable than `vercel link` (without `--repo`), which tries to match by directory name and often fails when the local folder and Vercel project are named differently.
+
+   **If there is no git remote**, fall back to standard linking:
+   ```bash
+   vercel link --scope <team-slug>
+   ```
+   This prompts the user to select or create a project. It creates `.vercel/project.json`.
+
+4. **Then deploy using the best available method:**
+   - If a git remote exists → commit and push (see git push method above)
+   - If no git remote → `vercel deploy [path] -y --no-wait --scope <team-slug>`, then `vercel inspect <url>` to check status
+
+---
+
+### Not linked + CLI not authenticated → Install, auth, link, deploy
+
+The Vercel CLI isn't set up at all.
+
+1. **Install the CLI (if not already installed):**
+   ```bash
+   npm install -g vercel
+   ```
+
+2. **Authenticate:**
+   ```bash
+   vercel login
+   ```
+   The user completes auth in their browser. If running in a non-interactive environment where login is not possible, skip to the **no-auth fallback** below.
+
+3. **Ask which team to deploy to** — present team slugs from `vercel teams list --format json` as a bulleted list. If only one team / personal account, skip. Once selected, proceed immediately.
+
+4. **Link the project** with the selected team scope (use `--repo` if a git remote exists, plain `vercel link` otherwise):
+   ```bash
+   vercel link --repo --scope <team-slug>   # if git remote exists
+   vercel link --scope <team-slug>          # if no git remote
+   ```
+
+5. **Deploy** using the best available method (git push if remote exists, otherwise `vercel deploy -y --no-wait --scope <team-slug>`, then `vercel inspect <url>` to check status).
+
+---
+
+### No-Auth Fallback — Browserless sandbox
+
+**When to use:** Last resort when the CLI can't be installed or authenticated in a browserless sandbox. This requires no authentication — it returns a **Preview URL** (live site) and a **Claim URL** (transfer to your Vercel account).
+
+```bash
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
+```
+
+**Arguments:**
+- `path` - Directory to deploy, or a `.tgz` file (defaults to current directory)
+
+**Examples:**
+```bash
+# Deploy current directory
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
+
+# Deploy specific project
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
+
+# Deploy existing tarball
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
+```
+
+The script auto-detects the framework from `package.json`, packages the project (excluding `node_modules`, `.git`, `.env`), uploads it, and waits for the build to complete.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+---
+
+### No-Auth Fallback — Restricted CLI sandbox
+
+**When to use:** In a restricted CLI sandbox where the Vercel CLI may not be authenticated. Try the CLI first, and fall back to the deploy script if auth fails.
+
+1. **Check whether the Vercel CLI is installed** (no escalation needed for this check):
+   ```bash
+   command -v vercel
+   ```
+
+2. **If `vercel` is installed**, try deploying with the CLI:
+   ```bash
+   vercel deploy [path] -y --no-wait
+   ```
+
+3. **If `vercel` is not installed, or the CLI fails with "No existing credentials found"**, use the fallback script:
+   ```bash
+   skill_dir="<path-to-skill>"
+
+   # Deploy current directory
+   bash "$skill_dir/resources/deploy-sandbox.sh"
+
+   # Deploy specific project
+   bash "$skill_dir/resources/deploy-sandbox.sh" /path/to/project
+
+   # Deploy existing tarball
+   bash "$skill_dir/resources/deploy-sandbox.sh" /path/to/project.tgz
+   ```
+
+The script handles framework detection, packaging, and deployment. It waits for the build to complete and returns JSON with `previewUrl` and `claimUrl`.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+**Escalated network access:** Only escalate the actual deploy command if sandboxing blocks the network call (`sandbox_permissions=require_escalated`). Do **not** escalate the `command -v vercel` check.
+
+---
+
+## Environment Notes
+
+### Terminal-based agents
+
+You have full shell access. Do NOT use the `/mnt/skills/` path. Follow the decision flow above using the CLI directly.
+
+For the no-auth fallback, run the deploy script from the skill's installed location:
+```bash
+bash <installed-skill-path>/deploy-to-vercel/resources/deploy.sh [path]
+```
+The path may vary depending on where the user installed the skill.
+
+### Browser-only sandboxes
+
+You likely cannot run `vercel login` or `git push`. Go directly to the **no-auth fallback — Browserless sandbox**.
+
+### Restricted CLI sandboxes
+
+Check if the CLI is available first, then fall back to the deploy script. Go to the **no-auth fallback — Restricted CLI sandbox**.
+
+---
+
+## Output
+
+Always show the user the deployment URL.
+
+- **Git push:** Use `vercel ls --format json` to find the preview URL. If the CLI isn't authenticated, tell the user to check the Vercel dashboard or commit status checks.
+- **CLI deploy:** Show the URL returned by `vercel deploy --no-wait`. Use `vercel inspect <url>` to check build status and report it to the user.
+- **No-auth fallback:** Show both the preview URL and the claim URL:
+  ```
+  Deployment successful!
+
+  Preview URL: https://my-app-abc123.vercel.app
+  Claim URL:   https://vercel.com/claim-deployment?code=...
+
+  View your site at the Preview URL.
+  To transfer this deployment to your Vercel account, visit the Claim URL.
+  ```
+
+**Do not** curl or fetch the deployed URL to verify it works. Just return the link.
+
+---
+
+## Troubleshooting
+
+### Network Egress Error (sandboxed environments)
+
+If deployment fails due to network restrictions in the current environment, tell the user:
+
+```
+Deployment failed due to network restrictions. To fix this:
+
+1. Open the environment's network or capability settings
+2. Allow access to *.vercel.com
+3. Try deploying again
+```
+
+### Escalated Network Access (sandboxed environments)
+
+If deployment fails due to network issues (timeouts, DNS errors, connection resets) in a sandboxed environment, rerun with escalated permissions (`sandbox_permissions=require_escalated`). Do not escalate the initial CLI availability check — only escalate the actual deploy command.
+
+Example guidance to the user:
+```
+The deploy needs escalated network access to deploy to Vercel. I can rerun
+the command with escalated permissions — want me to proceed?
+```
+
+### CLI Auth Failure
+
+If `vercel login` or `vercel deploy` fails with authentication errors, fall back to the appropriate no-auth deploy script for the current environment.