skillsforest 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# skillsforest-cli
+
+Install and manage agent skills from [SkillsForest](https://skillsforest.ai).
+
+## Install
+
+```bash
+npx skillsforest add <slug>
+```
+
+Or install globally:
+
+```bash
+npm install -g skillsforest
+skillsforest add <slug>
+```
+
+## Commands
+
+- **`add <slug>`** – Install a skill by slug. Auto-detects agent (Cursor, Claude Code, Codex) from your project, or use `--agent cursor|claude|codex|generic` and optional `--path ./custom`.
+- **`search <query>`** – Search the registry.
+- **`login`** – Store your API token for private skill access.
+- **`logout`** – Remove stored token.
+- **`list`** – List installed skills in the current project.
+
+## Private skills
+
+Create a token with `skill:read` at your SkillsForest API Tokens page, then:
+
+```bash
+skillsforest login
+# paste token when prompted
+skillsforest add my-private-skill
+```
+
+Or set `SKILLSFOREST_TOKEN` in the environment.
+
+## Development
+
+- `SKILLSFOREST_API_URL` – Registry base URL (default: `https://skillsforest.ai/api/v1/registry`).
+- E2E: run the Laravel app with a public skill, then:
+
+  ```bash
+  SKILLSFOREST_API_URL=http://skillsforest.test/api/v1/registry E2E_SLUG=your-slug ./scripts/e2e.sh
+  ```

package/bin/skillsforest.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { addCommand } = require('../src/commands/add');
+const { searchCommand } = require('../src/commands/search');
+const { loginCommand } = require('../src/commands/login');
+const { logoutCommand } = require('../src/commands/logout');
+const { listCommand } = require('../src/commands/list');
+
+program
+  .name('skillsforest')
+  .description('Install and manage agent skills from SkillsForest')
+  .version('0.1.0');
+
+program
+  .command('add <slug>')
+  .description('Install a skill by slug from the registry')
+  .option('--agent <type>', 'Agent type: cursor, claude, codex, generic')
+  .option('--path <dir>', 'Custom install path (relative to cwd)')
+  .action(addCommand);
+
+program
+  .command('search <query>')
+  .description('Search the registry for skills')
+  .action(searchCommand);
+
+program
+  .command('login')
+  .description('Store your API token for private skill access')
+  .action(loginCommand);
+
+program
+  .command('logout')
+  .description('Remove stored API token')
+  .action(logoutCommand);
+
+program
+  .command('list')
+  .description('List installed skills in the current project')
+  .action(listCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "skillsforest",
+  "version": "0.1.0",
+  "description": "Install agent skills from SkillsForest",
+  "main": "src/index.js",
+  "bin": {
+    "skillsforest": "bin/skillsforest.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "skills",
+    "cursor",
+    "claude",
+    "codex"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,55 @@
+const readline = require('readline');
+const { download } = require('../lib/registry');
+const { detectAgent, getSkillsDir } = require('../lib/detector');
+const { install } = require('../lib/installer');
+
+function promptAgent() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question('No agent directory found. Choose agent (cursor/claude/codex/generic) [cursor]: ', (answer) => {
+      rl.close();
+      const v = (answer || 'cursor').trim().toLowerCase();
+      resolve(['cursor', 'claude', 'codex', 'generic'].includes(v) ? v : 'cursor');
+    });
+  });
+}
+
+async function addCommand(slug, opts) {
+  let agent = opts.agent;
+  const cwd = process.cwd();
+
+  if (!agent) {
+    agent = detectAgent(cwd);
+    if (!agent) {
+      agent = await promptAgent();
+    }
+  } else {
+    agent = agent.toLowerCase();
+    if (!['cursor', 'claude', 'codex', 'generic'].includes(agent)) {
+      console.error('Invalid --agent. Use: cursor, claude, codex, generic');
+      process.exit(1);
+    }
+  }
+
+  const targetDir = opts.path ? require('path').resolve(cwd, opts.path) : null;
+
+  try {
+    const data = await download(slug);
+    if (!data.files || !Array.isArray(data.files)) {
+      throw new Error('Invalid response: missing files');
+    }
+    const skillDir = install(slug, data.files, agent, targetDir);
+    console.log(`Installed "${data.skill}" (v${data.version || '1.0.0'}) to ${skillDir}`);
+  } catch (err) {
+    if (err.status === 404) {
+      console.error(`Skill "${slug}" not found. It may be private (use "skillsforest login") or the slug may be wrong.`);
+    } else if (err.status === 403) {
+      console.error('Access denied. Token may be missing or invalid (try "skillsforest login").');
+    } else {
+      console.error(err.message || err);
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = { addCommand };

package/src/commands/list.js

@@ -0,0 +1,36 @@
+const fs = require('fs');
+const path = require('path');
+const { getSkillsDir, AGENT_DIRS } = require('../lib/detector');
+
+function listCommand() {
+  const cwd = process.cwd();
+  const found = [];
+
+  for (const [agent, dirName] of Object.entries(AGENT_DIRS)) {
+    const skillsDir = path.join(cwd, dirName, 'skills');
+    if (!fs.existsSync(skillsDir)) continue;
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        const skillPath = path.join(skillsDir, e.name);
+        const hasSkillMd = fs.existsSync(path.join(skillPath, 'SKILL.md'));
+        if (hasSkillMd) {
+          found.push({ agent, slug: e.name });
+        }
+      }
+    }
+  }
+
+  if (found.length === 0) {
+    console.log('No installed skills found in this project.');
+    return;
+  }
+
+  console.log('AGENT'.padEnd(12) + 'SLUG');
+  console.log('-'.repeat(40));
+  for (const { agent, slug } of found) {
+    console.log(agent.padEnd(12) + slug);
+  }
+}
+
+module.exports = { listCommand };

package/src/commands/login.js

@@ -0,0 +1,29 @@
+const readline = require('readline');
+const { saveToken } = require('../lib/auth');
+const { getRegistryBaseUrl } = require('../lib/config');
+
+async function loginCommand() {
+  const base = getRegistryBaseUrl();
+  const baseUrl = base.replace(/\/api\/v1\/registry\/?$/, '');
+  const tokenUrl = baseUrl ? `${baseUrl}/user/api-tokens` : 'https://skillsforest.ai/user/api-tokens';
+  console.log(`Create a token at: ${tokenUrl}`);
+  console.log('Paste your token (with skill:read for private skills):');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const token = await new Promise((resolve) => {
+    rl.question('Token: ', (answer) => {
+      rl.close();
+      resolve((answer || '').trim());
+    });
+  });
+
+  if (!token) {
+    console.error('No token provided.');
+    process.exit(1);
+  }
+
+  saveToken(token);
+  console.log('Token saved. You can now install private skills.');
+}
+
+module.exports = { loginCommand };

package/src/commands/logout.js

@@ -0,0 +1,11 @@
+const { removeCredentials } = require('../lib/auth');
+
+function logoutCommand() {
+  if (removeCredentials()) {
+    console.log('Logged out. Stored token removed.');
+  } else {
+    console.log('No stored token found.');
+  }
+}
+
+module.exports = { logoutCommand };

package/src/commands/search.js

@@ -0,0 +1,31 @@
+const { search } = require('../lib/registry');
+
+function formatRow(name, description, author, maxDesc = 60) {
+  const desc = (description || '').slice(0, maxDesc) + ((description || '').length > maxDesc ? '…' : '');
+  return `${name.padEnd(24)} ${desc.padEnd(maxDesc + 1)} ${(author || '').padEnd(16)}`;
+}
+
+async function searchCommand(query) {
+  try {
+    const data = await search(query);
+    const items = data.data || [];
+    if (items.length === 0) {
+      console.log('No skills found.');
+      return;
+    }
+    console.log(formatRow('NAME', 'DESCRIPTION', 'AUTHOR'));
+    console.log('-'.repeat(24 + 62 + 17));
+    for (const s of items) {
+      console.log(formatRow(s.slug || s.name, s.description, s.author));
+    }
+    const total = data.meta?.total ?? items.length;
+    if (total > items.length) {
+      console.log(`\n... and ${total - items.length} more.`);
+    }
+  } catch (err) {
+    console.error(err.message || err);
+    process.exit(1);
+  }
+}
+
+module.exports = { searchCommand };

package/src/lib/auth.js

@@ -0,0 +1,56 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CREDENTIALS_DIR = path.join(os.homedir(), '.skillsforest');
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, 'credentials');
+
+function getToken() {
+  if (process.env.SKILLSFOREST_TOKEN) {
+    return process.env.SKILLSFOREST_TOKEN.trim();
+  }
+  try {
+    if (fs.existsSync(CREDENTIALS_FILE)) {
+      const data = JSON.parse(fs.readFileSync(CREDENTIALS_FILE, 'utf8'));
+      return data.token || null;
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function saveToken(token) {
+  if (!fs.existsSync(CREDENTIALS_DIR)) {
+    fs.mkdirSync(CREDENTIALS_DIR, { mode: 0o700 });
+  }
+  fs.writeFileSync(
+    CREDENTIALS_FILE,
+    JSON.stringify({ token: token.trim() }, null, 2),
+    { mode: 0o600 }
+  );
+}
+
+function removeCredentials() {
+  try {
+    if (fs.existsSync(CREDENTIALS_FILE)) {
+      fs.unlinkSync(CREDENTIALS_FILE);
+      return true;
+    }
+  } catch {
+    // ignore
+  }
+  return false;
+}
+
+function isLoggedIn() {
+  return !!getToken();
+}
+
+module.exports = {
+  getToken,
+  saveToken,
+  removeCredentials,
+  isLoggedIn,
+  CREDENTIALS_FILE,
+};

package/src/lib/config.js

@@ -0,0 +1,10 @@
+const DEFAULT_REGISTRY_URL = 'https://skillsforest.ai/api/v1/registry';
+
+function getRegistryBaseUrl() {
+  return process.env.SKILLSFOREST_API_URL || DEFAULT_REGISTRY_URL;
+}
+
+module.exports = {
+  DEFAULT_REGISTRY_URL,
+  getRegistryBaseUrl,
+};

package/src/lib/detector.js

@@ -0,0 +1,28 @@
+const fs = require('fs');
+const path = require('path');
+
+const AGENT_DIRS = {
+  cursor: '.cursor',
+  claude: '.claude',
+  codex: '.codex',
+  generic: '.agent',
+};
+
+function detectAgent(cwd = process.cwd()) {
+  if (fs.existsSync(path.join(cwd, '.cursor'))) return 'cursor';
+  if (fs.existsSync(path.join(cwd, '.claude'))) return 'claude';
+  if (fs.existsSync(path.join(cwd, '.codex'))) return 'codex';
+  if (fs.existsSync(path.join(cwd, 'AGENTS.md'))) return 'codex';
+  return null;
+}
+
+function getSkillsDir(agent, cwd = process.cwd()) {
+  const dir = AGENT_DIRS[agent] || AGENT_DIRS.generic;
+  return path.join(cwd, dir, 'skills');
+}
+
+module.exports = {
+  detectAgent,
+  getSkillsDir,
+  AGENT_DIRS,
+};

package/src/lib/installer.js

@@ -0,0 +1,27 @@
+const fs = require('fs');
+const path = require('path');
+const { getSkillsDir } = require('./detector');
+
+function install(slug, files, agent, targetDir) {
+  const baseDir = targetDir || getSkillsDir(agent);
+  const skillDir = path.join(baseDir, slug);
+  if (!fs.existsSync(baseDir)) {
+    fs.mkdirSync(baseDir, { recursive: true });
+  }
+  if (!fs.existsSync(skillDir)) {
+    fs.mkdirSync(skillDir, { recursive: true });
+  }
+  for (const { path: filePath, content } of files) {
+    const fullPath = path.join(skillDir, filePath);
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(fullPath, content, 'utf8');
+  }
+  return skillDir;
+}
+
+module.exports = {
+  install,
+};

package/src/lib/registry.js

@@ -0,0 +1,63 @@
+const { getRegistryBaseUrl } = require('./config');
+const { getToken } = require('./auth');
+
+async function fetchRegistry(pathname, options = {}) {
+  const base = getRegistryBaseUrl().replace(/\/$/, '');
+  const url = `${base}${pathname.startsWith('/') ? pathname : `/${pathname}`}`;
+  const headers = { Accept: 'application/json', ...options.headers };
+  const token = getToken();
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  const res = await fetch(url, { ...options, headers });
+  const body = await res.text();
+
+  if (!res.ok) {
+    let msg = `Registry request failed: ${res.status} ${res.statusText}`;
+    try {
+      const j = JSON.parse(body);
+      if (j.message) msg = j.message;
+    } catch {
+      if (body) msg = body;
+    }
+    const err = new Error(msg);
+    err.status = res.status;
+    throw err;
+  }
+
+  const contentType = res.headers.get('content-type') || '';
+  if (!contentType.includes('application/json')) {
+    const preview = body.trimStart().slice(0, 80);
+    throw new Error(
+      `Registry returned non-JSON (${contentType || 'unknown type'}). ` +
+        (body.trimStart().startsWith('<')
+          ? 'Got HTML — the API URL may be wrong or the service may be returning an error page.'
+          : `Body preview: ${preview}`)
+    );
+  }
+  try {
+    return JSON.parse(body);
+  } catch (e) {
+    const preview = body.trimStart().slice(0, 80);
+    throw new Error(`Invalid JSON from registry. Body preview: ${preview}`);
+  }
+}
+
+async function search(query, params = {}) {
+  const sp = new URLSearchParams({ q: query, ...params });
+  return fetchRegistry(`/?${sp}`);
+}
+
+async function show(slug) {
+  return fetchRegistry(`/${encodeURIComponent(slug)}`);
+}
+
+async function download(slug) {
+  return fetchRegistry(`/${encodeURIComponent(slug)}/download`);
+}
+
+module.exports = {
+  search,
+  show,
+  download,
+};