aiden-runtime 3.19.5 → 3.19.7

package/workspace-templates/skills/explainshell/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: explainshell
+description: Break down shell commands and one-liners into plain-English explanations — powered by explainshell.com
+category: developer
+version: 1.0.0
+license: Apache-2.0
+origin: aiden
+tags: shell, bash, linux, commands, explainer, learning, devops, documentation, scripting
+---
+
+# ExplainShell — Shell Command Explainer
+
+Paste any shell command or one-liner and get a plain-English breakdown of every flag, argument, and pipe stage. Powered by explainshell.com, which maps commands to their man-page descriptions.
+
+**No API key required.** Works immediately for any user.
+
+## When to Use
+
+- User pastes a cryptic command and asks "what does this do?"
+- Reviewing an unfamiliar bash script or automation pipeline
+- Learning: user wants to understand each part of a complex one-liner
+- Documentation: need to annotate shell commands in runbooks
+- User asks "explain this command", "what does this flag mean?", "break this down"
+
+## How to Use
+
+### Explain a single command (browser link)
+
+```powershell
+# The simplest approach — open the explanation in the browser
+$command = "tar -xzf archive.tar.gz -C /tmp"
+$encoded = [Uri]::EscapeDataString($command)
+Start-Process "https://explainshell.com/explain?cmd=$encoded"
+Write-Host "Opened: https://explainshell.com/explain?cmd=$encoded"
+```
+
+### Fetch explanation text directly (PowerShell)
+
+```powershell
+$command = "find . -type f -name '*.log' -mtime +7 -exec rm {} \;"
+$encoded = [Uri]::EscapeDataString($command)
+$url     = "https://explainshell.com/explain?cmd=$encoded"
+
+$html    = Invoke-WebRequest -Uri $url -UseBasicParsing
+# Extract helptext spans (plain text explanations)
+$pattern = '<span class="helptext">(.*?)</span>'
+$matches = [regex]::Matches($html.Content, $pattern, 'Singleline')
+
+Write-Host "Command: $command"
+Write-Host ""
+$matches | ForEach-Object {
+    $text = $_.Groups[1].Value -replace '<[^>]+>', '' -replace '&amp;', '&' -replace '&lt;', '<' -replace '&gt;', '>'
+    if ($text.Trim()) { Write-Host "  • $($text.Trim())" }
+}
+Write-Host ""
+Write-Host "Full explanation: $url"
+```
+
+### Explain a piped one-liner
+
+```powershell
+$command = "ps aux | awk '{print \$2, \$11}' | sort -k2 | uniq -c | sort -rn | head -10"
+$encoded = [Uri]::EscapeDataString($command)
+Write-Host "ExplainShell link:"
+Write-Host "  https://explainshell.com/explain?cmd=$encoded"
+```
+
+## Examples
+
+**"Explain: tar -xzf file.tar.gz"**
+→ `tar`: archive utility; `-x`: extract; `-z`: filter through gzip; `-f`: use archive file.
+
+**"What does find . -type f -exec rm {} \\; do?"**
+→ `find`: search; `.`: starting directory; `-type f`: only files; `-exec rm {} ;`: run rm on each result.
+
+**"Break down: awk '{print $2}' | sort | uniq -c"**
+→ `awk`: text processor prints second field; `sort`: lexicographic sort; `uniq -c`: count consecutive duplicates.
+
+**"What is 2>&1 in a command?"**
+→ Redirects stderr (fd 2) to the same destination as stdout (fd 1) — merges error output.
+
+## Cautions
+
+- explainshell.com covers most standard POSIX and GNU commands — may not know custom scripts or aliases
+- Very long one-liners (> 200 chars) may produce incomplete explanations
+- Some compound expressions (e.g. complex `awk` programs) parse partially
+- Rate-limit: be polite — avoid bulk automated requests to a free community service
+- The HTML structure may change; if parsing fails, the URL is always valid as a fallback
+
+## Requirements
+
+- None — no API key needed
+- Works with any POSIX/GNU shell command or pipeline

package/workspace-templates/skills/explainshell/index.ts

@@ -0,0 +1,132 @@
+// skills/explainshell/index.ts
+// Programmatic handler — fetch and parse shell command explanations from explainshell.com.
+
+import { ApiSkill } from '../../core/apiSkillBase'
+
+const skill = new ApiSkill({
+  name:      'explainshell',
+  baseUrl:   'https://explainshell.com',
+  authType:  'none',
+  rateLimit: { requests: 5, windowMs: 1_000 },
+  timeout:   15_000,
+  retries:   2,
+})
+
+// ── HTML parsing helpers ──────────────────────────────────────
+
+/** Strip HTML tags from a string. */
+function stripTags(html: string): string {
+  return html
+    .replace(/<[^>]+>/g, '')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g,  '<')
+    .replace(/&gt;/g,  '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g,  "'")
+    .replace(/&nbsp;/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/**
+ * Extract explanation fragments from explainshell HTML.
+ *
+ * The page contains elements like:
+ *   <span class="helptext">explanation text...</span>
+ *   <div class="help-box">...</div>
+ * as well as argument tokens in <span class="arg">...</span>.
+ *
+ * We extract helptext spans and pair them with their nearest
+ * argument token for a readable breakdown.
+ */
+function parseExplainshellHtml(html: string): string[] {
+  const results: string[] = []
+
+  // Match each helptext block — may span multiple lines
+  const helptextRe = /<span[^>]*class="helptext"[^>]*>([\s\S]*?)<\/span>/gi
+  let match: RegExpExecArray | null
+
+  while ((match = helptextRe.exec(html)) !== null) {
+    const text = stripTags(match[1])
+    if (text.length > 2) results.push(text)
+  }
+
+  // If helptext approach yields nothing, try extracting from help-box divs
+  if (results.length === 0) {
+    const boxRe = /<div[^>]*class="[^"]*help-box[^"]*"[^>]*>([\s\S]*?)<\/div>/gi
+    while ((match = boxRe.exec(html)) !== null) {
+      const text = stripTags(match[1])
+      if (text.length > 5) results.push(text)
+    }
+  }
+
+  // Deduplicate while preserving order
+  const seen = new Set<string>()
+  return results.filter(r => {
+    const k = r.slice(0, 80)
+    if (seen.has(k)) return false
+    seen.add(k)
+    return true
+  })
+}
+
+/** Check if the HTML indicates the command was not found. */
+function isNotFound(html: string): boolean {
+  return /no match for/i.test(html) || /couldn.t parse/i.test(html)
+}
+
+// ── Public API ────────────────────────────────────────────────
+
+export interface ExplainResult {
+  command:   string
+  url:       string
+  breakdown: string[]   // plain-text explanations, one per flag/segment
+  parsed:    boolean    // false if HTML parsing yielded nothing (URL still valid)
+}
+
+/**
+ * Fetch a plain-English breakdown of a shell command.
+ *
+ * @param command  The shell command to explain (e.g. "tar -xzf file.tar.gz")
+ * @returns        ExplainResult with URL and parsed breakdown array
+ */
+export async function explain(command: string): Promise<ExplainResult> {
+  const cmd     = command.trim()
+  const encoded = encodeURIComponent(cmd)
+  const url     = `https://explainshell.com/explain?cmd=${encoded}`
+
+  let breakdown: string[] = []
+  let parsed               = false
+
+  try {
+    const html = await skill.get('/explain', { cmd })
+
+    if (typeof html === 'string') {
+      if (isNotFound(html)) {
+        breakdown = [`explainshell did not recognise "${cmd}" — try visiting the URL directly.`]
+      } else {
+        breakdown = parseExplainshellHtml(html)
+        parsed    = breakdown.length > 0
+        if (!parsed) {
+          breakdown = ['Explanation available at the URL below — could not parse the response automatically.']
+        }
+      }
+    }
+  } catch {
+    breakdown = ['Could not reach explainshell.com — visit the URL manually.']
+  }
+
+  return { command: cmd, url, breakdown, parsed }
+}
+
+/** Format an ExplainResult as a readable string. */
+export function formatExplanation(result: ExplainResult): string {
+  const lines = [`Command: ${result.command}`, '']
+
+  if (result.breakdown.length > 0) {
+    result.breakdown.forEach(b => lines.push(`  • ${b}`))
+  }
+
+  lines.push('', `Full explanation: ${result.url}`)
+  return lines.join('\n')
+}

package/workspace-templates/skills/explainshell/skill.json

@@ -0,0 +1,25 @@
+{
+  "name": "explainshell",
+  "version": "1.0.0",
+  "description": "Break down shell commands and one-liners into plain-English explanations — powered by explainshell.com",
+  "author": "aiden",
+  "license": "MIT",
+  "tools": [],
+  "trigger_phrases": [],
+  "compatible_agents": [
+    "aiden"
+  ],
+  "min_agent_version": "3.0.0",
+  "tags": [
+    "shell",
+    "bash",
+    "linux",
+    "commands",
+    "explainer",
+    "learning",
+    "devops",
+    "documentation",
+    "scripting"
+  ],
+  "created": "2026-04-27T17:11:39.556Z"
+}

package/workspace-templates/skills/financial_research/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: financial_research
+description: Research stocks, companies, and market data using real-time financial APIs
+version: 1.0.0
+tags: finance, stocks, market, investment, NSE, BSE, equity, company
+license: Apache-2.0
+---
+
+# Financial Research
+
+When performing financial research:
+1. Use get_market_data first to get the live price, change %, and volume for any symbol
+2. Use get_company_info to fetch sector, industry, P/E ratio, EPS, revenue, and profit margins
+3. Use web_search to find recent news, analyst upgrades/downgrades, and earnings updates
+4. Synthesise all three into a structured summary: price snapshot → company profile → recent news → outlook
+5. For NSE stocks: symbol is the ticker only (e.g. RELIANCE, TCS) — tool auto-appends .NS
+6. For BSE stocks: append .BO manually (e.g. RELIANCE.BO) if the user specifies BSE
+7. For US stocks: use the bare symbol (e.g. AAPL, TSLA, NVDA)
+8. Always state the data source and note that prices are delayed/indicative if market is closed
+9. When comparing multiple stocks: build a table with symbol, price, change%, P/E, sector
+10. Never give buy/sell advice — present data and let the user decide

package/workspace-templates/skills/financial_research/skill.json

@@ -0,0 +1,24 @@
+{
+  "name": "financial_research",
+  "version": "1.0.0",
+  "description": "Research stocks, companies, and market data using real-time financial APIs",
+  "author": "local",
+  "license": "MIT",
+  "tools": [],
+  "trigger_phrases": [],
+  "compatible_agents": [
+    "aiden"
+  ],
+  "min_agent_version": "3.0.0",
+  "tags": [
+    "finance",
+    "stocks",
+    "market",
+    "investment",
+    "NSE",
+    "BSE",
+    "equity",
+    "company"
+  ],
+  "created": "2026-04-27T17:11:39.591Z"
+}

package/workspace-templates/skills/gif-search/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: gif-search
+description: Search and fetch GIFs from Tenor using the public API with curl or PowerShell — requires a free Tenor API key
+category: media
+version: 1.0.1
+origin: aiden
+license: Apache-2.0
+tags: gif, tenor, giphy, search, media, animation, image, reaction, fun
+---
+
+# GIF Search via Tenor
+
+Search and fetch GIFs using the Tenor API. Obtain a free API key at
+https://developers.google.com/tenor/guides/quickstart (takes 2 minutes) and set it as
+the `TENOR_API_KEY` environment variable. All examples below use `$env:TENOR_API_KEY`
+(PowerShell) or `os.environ["TENOR_API_KEY"]` (Python).
+
+## When to Use
+
+- User wants to find a GIF for a given mood, reaction, or topic
+- User wants to share a GIF URL in a chat or document
+- User wants to download a GIF file locally
+- User wants to embed a GIF in a web page or email
+
+## How to Use
+
+### 1. Search GIFs with PowerShell (no API key needed)
+
+```powershell
+function Search-Gif($query, $limit = 5) {
+  $q    = [Uri]::EscapeDataString($query)
+  $url  = "https://tenor.googleapis.com/v2/search?q=$q&limit=$limit&key=$env:TENOR_API_KEY"
+  $resp = Invoke-RestMethod -Uri $url
+  $resp.results | ForEach-Object {
+    [PSCustomObject]@{
+      Title    = $_.title
+      GifUrl   = $_.media_formats.gif.url
+      PreviewUrl = $_.media_formats.tinygif.url
+    }
+  }
+}
+
+# Usage
+Search-Gif "excited celebration" | Format-Table -AutoSize
+```
+
+### 2. Search GIFs with Python
+
+```python
+import requests, urllib.parse
+
+def search_gif(query, limit=5, api_key=None):
+  api_key = api_key or os.environ.get("TENOR_API_KEY", "")
+  params = {"q": query, "limit": limit, "key": api_key}
+  resp   = requests.get("https://tenor.googleapis.com/v2/search", params=params)
+  resp.raise_for_status()
+  results = resp.json().get("results", [])
+  return [{"title": r["title"], "url": r["media_formats"]["gif"]["url"]} for r in results]
+
+gifs = search_gif("happy dancing")
+for g in gifs:
+  print(g["title"])
+  print(g["url"])
+  print()
+```
+
+### 3. Get trending GIFs
+
+```powershell
+$url  = "https://tenor.googleapis.com/v2/featured?limit=10&key=$env:TENOR_API_KEY"
+$resp = Invoke-RestMethod -Uri $url
+$resp.results | Select-Object title, @{N="url";E={$_.media_formats.gif.url}}
+```
+
+### 4. Download a GIF to disk
+
+```powershell
+$gifUrl   = "https://media.tenor.com/your-gif.gif"
+$outPath  = "C:\Users\shiva\Downloads\reaction.gif"
+Invoke-WebRequest -Uri $gifUrl -OutFile $outPath
+Write-Host "Downloaded: $outPath"
+```
+
+### 5. Get a GIF by category (reaction types)
+
+```powershell
+# Categories: happy, sad, angry, love, funny, wow, thumbsup, facepalm, etc.
+$category = "facepalm"
+Search-Gif $category -limit 3 | Select-Object GifUrl
+```
+
+### 6. Use your own Tenor API key (higher rate limits)
+
+Register at https://developers.google.com/tenor/guides/quickstart — free, takes 2 minutes.
+
+```powershell
+$env:TENOR_API_KEY = "your_api_key_here"
+
+function Search-Gif($query, $limit = 5) {
+  $q   = [Uri]::EscapeDataString($query)
+  $url = "https://tenor.googleapis.com/v2/search?q=$q&limit=$limit&key=$env:TENOR_API_KEY"
+  (Invoke-RestMethod -Uri $url).results | Select-Object title, @{N="url";E={$_.media_formats.gif.url}}
+}
+```
+
+## Examples
+
+**"Find me a GIF for when tests are passing"**
+→ Use step 2 with query `"success celebration cheering"` and return the top result URL.
+
+**"What are trending GIFs right now?"**
+→ Use step 3 to fetch featured/trending GIFs.
+
+**"Download the first result for 'thumbs up'"**
+→ Use step 1 to search, then step 4 to download the `GifUrl` of the first result.
+
+## Cautions
+
+- The demo API key used in examples has low rate limits — register your own free key for production use
+- Tenor GIF URLs are CDN links and may not be permanently stable — don't store them long-term
+- GIF files can be large (1-20 MB) — check size before downloading in bulk
+- Always attribute Tenor as the source when displaying GIFs publicly

package/workspace-templates/skills/gif-search/skill.json

@@ -0,0 +1,25 @@
+{
+  "name": "gif-search",
+  "version": "1.0.1",
+  "description": "Search and fetch GIFs from Tenor using the public API with curl or PowerShell — requires a free Tenor API key",
+  "author": "aiden",
+  "license": "MIT",
+  "tools": [],
+  "trigger_phrases": [],
+  "compatible_agents": [
+    "aiden"
+  ],
+  "min_agent_version": "3.0.0",
+  "tags": [
+    "gif",
+    "tenor",
+    "giphy",
+    "search",
+    "media",
+    "animation",
+    "image",
+    "reaction",
+    "fun"
+  ],
+  "created": "2026-04-27T17:11:39.623Z"
+}

package/workspace-templates/skills/github-auth/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: github-auth
+description: Set up GitHub authentication via gh CLI, SSH keys, and HTTPS personal access tokens
+category: developer
+version: 1.0.0
+origin: aiden
+license: Apache-2.0
+tags: github, auth, ssh, pat, token, credentials, gh-cli, authentication, git, https
+---
+
+# GitHub Authentication Setup
+
+Configure GitHub authentication for `git` and `gh` CLI operations using the GitHub CLI (`gh`), SSH keys, or HTTPS personal access tokens (PATs).
+
+## When to Use
+
+- User needs to authenticate with GitHub from a new machine
+- User is getting `Permission denied (publickey)` or `Authentication failed` errors
+- User wants to switch from HTTPS to SSH authentication
+- User wants to create or rotate a personal access token
+- User wants to verify their current GitHub credentials are working
+
+## How to Use
+
+### 1. Authenticate with gh CLI (recommended)
+
+```powershell
+# Interactive login — opens browser for OAuth
+gh auth login
+
+# Choose: GitHub.com → HTTPS → Authenticate with browser
+# Or choose SSH if preferred
+
+# Verify authentication
+gh auth status
+```
+
+### 2. Create an SSH key
+
+```powershell
+# Generate Ed25519 key (modern, secure)
+ssh-keygen -t ed25519 -C "your-email@example.com" -f "$env:USERPROFILE\.ssh\github_ed25519"
+
+# Start ssh-agent and add key
+Start-Service ssh-agent
+ssh-add "$env:USERPROFILE\.ssh\github_ed25519"
+
+# Display public key to copy to GitHub
+Get-Content "$env:USERPROFILE\.ssh\github_ed25519.pub"
+```
+
+After running step 2, the user must add the public key at https://github.com/settings/keys → New SSH key.
+
+### 3. Configure SSH to use the key for GitHub
+
+```powershell
+# Create or append to SSH config
+$config = @"
+
+Host github.com
+  HostName github.com
+  User git
+  IdentityFile ~/.ssh/github_ed25519
+"@
+Add-Content "$env:USERPROFILE\.ssh\config" $config
+
+# Test SSH connection
+ssh -T git@github.com
+```
+
+### 4. Create a Personal Access Token (HTTPS)
+
+Direct the user to: https://github.com/settings/tokens/new
+- Select scopes: `repo`, `read:org` (for org repos), `workflow` (for Actions)
+- Copy the token — it is shown only once
+
+```powershell
+# Configure git to cache HTTPS credentials
+git config --global credential.helper wincred
+
+# Test — will prompt for username + PAT as password
+git clone https://github.com/your-org/your-repo.git
+```
+
+### 5. Configure gh CLI with a PAT
+
+```powershell
+# Authenticate gh CLI with a PAT non-interactively
+$env:GH_TOKEN = "ghp_your_token_here"
+gh auth status
+```
+
+### 6. Verify and list configured credentials
+
+```powershell
+# Check gh auth
+gh auth status
+
+# Check git remote URL type
+git remote -v
+
+# Test SSH
+ssh -T git@github.com
+# Expected: "Hi username! You've successfully authenticated..."
+```
+
+### 7. Switch a repo from HTTPS to SSH
+
+```powershell
+# Show current remote
+git remote get-url origin
+
+# Change to SSH
+git remote set-url origin git@github.com:owner/repo.git
+git remote -v   # verify
+```
+
+## Examples
+
+**"I'm on a new machine and need to set up GitHub access"**
+→ Use step 1 (`gh auth login`) for the quickest setup. If SSH is preferred, use steps 2–3 then step 1 with SSH option.
+
+**"I'm getting Authentication failed when pushing to GitHub"**
+→ Use step 6 to diagnose. If HTTPS, rotate the PAT (step 4). If SSH, run `ssh -T git@github.com` to test.
+
+**"Generate a new SSH key and add it to GitHub"**
+→ Use steps 2–3 and instruct user to paste the public key at github.com/settings/keys.
+
+## Cautions
+
+- Never store PATs in code files or commit them to git — use environment variables or the system keychain
+- PATs shown on GitHub are one-time — copy immediately when created
+- SSH keys without passphrases are convenient but less secure — recommend a passphrase for shared machines
+- `gh auth login` stores credentials in the system keychain — do not use on untrusted machines

package/workspace-templates/skills/github-auth/skill.json

@@ -0,0 +1,26 @@
+{
+  "name": "github-auth",
+  "version": "1.0.0",
+  "description": "Set up GitHub authentication via gh CLI, SSH keys, and HTTPS personal access tokens",
+  "author": "aiden",
+  "license": "MIT",
+  "tools": [],
+  "trigger_phrases": [],
+  "compatible_agents": [
+    "aiden"
+  ],
+  "min_agent_version": "3.0.0",
+  "tags": [
+    "github",
+    "auth",
+    "ssh",
+    "pat",
+    "token",
+    "credentials",
+    "gh-cli",
+    "authentication",
+    "git",
+    "https"
+  ],
+  "created": "2026-04-27T17:11:39.656Z"
+}