@amanm/openpaw 0.1.0

package/bin/openpaw.cjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+/**
+ * Node launcher shim for OpenPaw.
+ *
+ * Purpose:
+ * - Keep npm global install UX (`npm i -g openpaw`) simple.
+ * - Ensure Bun is available before running the Bun-native TypeScript CLI.
+ * - Offer interactive Bun install on macOS/Linux when missing.
+ */
+
+const { spawn, spawnSync } = require("node:child_process");
+const { existsSync } = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const readline = require("node:readline");
+
+/** Absolute CLI entrypoint shipped in the npm package. */
+const CLI_ENTRY = path.resolve(__dirname, "..", "cli", "openpaw.tsx");
+
+/** Home-local Bun binary path used by official installer on Unix systems. */
+const HOME_BUN_BIN = path.join(os.homedir(), ".bun", "bin", "bun");
+
+/**
+ * Returns a PATH string that includes default Bun install directory if present.
+ */
+function pathWithHomeBun(envPath) {
+  if (!existsSync(HOME_BUN_BIN)) {
+    return envPath || "";
+  }
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  const segments = (envPath || "").split(delimiter).filter(Boolean);
+  const homeBunDir = path.dirname(HOME_BUN_BIN);
+  if (!segments.includes(homeBunDir)) {
+    segments.unshift(homeBunDir);
+  }
+  return segments.join(delimiter);
+}
+
+/**
+ * Resolves Bun binary by trying PATH (and `~/.bun/bin`) with lightweight version checks.
+ */
+function resolveBunBinary() {
+  const env = { ...process.env, PATH: pathWithHomeBun(process.env.PATH) };
+  const checkPath = spawnSync("bun", ["--version"], {
+    env,
+    stdio: "ignore",
+  });
+  if (checkPath.status === 0) {
+    return { bun: "bun", env };
+  }
+
+  if (existsSync(HOME_BUN_BIN)) {
+    const checkHome = spawnSync(HOME_BUN_BIN, ["--version"], {
+      env,
+      stdio: "ignore",
+    });
+    if (checkHome.status === 0) {
+      return { bun: HOME_BUN_BIN, env };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Prompts the user for a yes/no choice and resolves `true` only for affirmative answers.
+ */
+function promptYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(question, (answer) => {
+      rl.close();
+      const value = String(answer || "").trim().toLowerCase();
+      resolve(value === "" || value === "y" || value === "yes");
+    });
+  });
+}
+
+/**
+ * Runs official Bun installer on Unix (`curl ... | bash`) and returns success flag.
+ */
+function installBunUnix() {
+  const cmd = "curl -fsSL https://bun.sh/install | bash";
+  const result = spawnSync("bash", ["-lc", cmd], { stdio: "inherit" });
+  return result.status === 0;
+}
+
+/**
+ * Prints manual Bun install guidance and exits with failure.
+ */
+function failWithBunInstructions() {
+  if (process.platform === "win32") {
+    console.error("Bun is required to run OpenPaw.");
+    console.error("Install Bun from https://bun.sh/docs/installation and rerun `openpaw`.");
+    process.exit(1);
+  }
+
+  console.error("Bun is required to run OpenPaw.");
+  console.error("Install with: curl -fsSL https://bun.sh/install | bash");
+  console.error("Then restart your shell and rerun `openpaw`.");
+  process.exit(1);
+}
+
+/**
+ * Ensures Bun is present. When missing on macOS/Linux, asks permission to install it.
+ */
+async function ensureBun() {
+  const resolved = resolveBunBinary();
+  if (resolved) {
+    return resolved;
+  }
+
+  if (process.platform === "win32") {
+    failWithBunInstructions();
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    failWithBunInstructions();
+  }
+
+  const consent = await promptYesNo("Bun is required but not found. Install Bun now? [Y/n] ");
+  if (!consent) {
+    failWithBunInstructions();
+  }
+
+  const installed = installBunUnix();
+  if (!installed) {
+    console.error("Bun install failed.");
+    failWithBunInstructions();
+  }
+
+  const after = resolveBunBinary();
+  if (!after) {
+    console.error("Bun installed but not detected in PATH.");
+    failWithBunInstructions();
+  }
+
+  return after;
+}
+
+/**
+ * Executes Bun CLI (`bun run <entry> ...args`) with inherited stdio and signal forwarding.
+ */
+function runBunCli(bun, env) {
+  const args = ["run", CLI_ENTRY, ...process.argv.slice(2)];
+  const child = spawn(bun, args, {
+    stdio: "inherit",
+    env,
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}
+
+/**
+ * Launcher entrypoint.
+ */
+async function main() {
+  const { bun, env } = await ensureBun();
+  runBunCli(bun, env);
+}
+
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`OpenPaw launcher error: ${message}`);
+  process.exit(1);
+});

package/bundled-skills/find-skills/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: find-skills
+description: 'Discover and install specialized agent skills from the open ecosystem (skills.sh, npx skills). Use when users ask "how do I do X", "find a skill for X", whether a capability exists, want to extend the agent, search tools/templates/workflows, or install community skills. Source: https://skills.sh/vercel-labs/skills/find-skills'
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` — Search for skills interactively or by keyword
+- `npx skills add <package>` — Install a skill from GitHub or other sources
+- `npx skills check` — Check for skill updates
+- `npx skills update` — Update all installed skills
+
+**Browse skills at:** [skills.sh](https://skills.sh/)
+
+## OpenPaw: workspace, shell, and where skills live
+
+- **Default bundle:** A fresh OpenPaw workspace only includes **find-skills** under `workspace/.agents/skills/find-skills/`. Anything else is installed later.
+- **`bash` tool:** Commands run with **cwd = the OpenPaw workspace root** (e.g. `~/.openpaw/workspace`) when the filesystem sandbox is on — so paths like `.agents/skills` are relative to that directory.
+- **Install new skills into this workspace:** Use **project** scope (do **not** use `-g` / `--global` for OpenPaw’s copy). The Skills CLI maps the **`universal`** agent to project-local **`./.agents/skills/`**. Prefer:
+
+```bash
+npx skills add <owner/repo> --skill <skill-name> -a universal -y
+```
+
+Examples:
+
+```bash
+npx skills find "ascii art"
+npx skills add some-org/some-skills-repo --skill ascii-art -a universal -y
+```
+
+After installing, OpenPaw rescans skill directories automatically before each model step and when using `load_skill`, `file_editor`, or `list_dir`—no restart required.
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Check the Leaderboard First
+
+Before running a CLI search, check the [skills.sh](https://skills.sh/) leaderboard to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
+
+For example, top skills for web development include:
+
+- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
+- `anthropics/skills` — Frontend design, document processing (100K+ installs)
+
+### Step 3: Search for Skills
+
+If the leaderboard doesn't cover the user's need, run the find command:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+### Step 4: Verify Quality Before Recommending
+
+**Do not recommend a skill based solely on search results.** Always verify:
+
+1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
+2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
+3. **GitHub stars** — Check the source repository. A skill from a repo with fewer than 100 stars should be treated with skepticism.
+
+### Step 5: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install count and source
+3. The install command they can run
+4. A link to learn more at skills.sh
+
+Example response:
+
+```text
+I found a skill that might help! The "react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+(185K installs)
+
+To install it:
+npx skills add vercel-labs/agent-skills@react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+```
+
+### Step 6: Offer to Install
+
+If the user wants to proceed, run install from the **workspace root** (OpenPaw `bash` already uses it as cwd). For OpenPaw, use **project** install into `./.agents/skills` via the **`universal`** agent target:
+
+```bash
+npx skills add <owner/repo> --skill <skill-name> -a universal -y
+```
+
+- **Do not** use `-g` for OpenPaw’s workspace skills — that targets the user-level agent dirs instead of this workspace.
+- `-y` skips confirmation when appropriate.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd          |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices     |
+| Design          | ui, ux, design-system, accessibility       |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```text
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```