ocs-stats 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+# OpenCode Skills & Agents
+
+A collection of reusable skills and agents for [OpenCode](https://opencode.ai) - an AI-powered development assistant that runs in your terminal.
+
+## What This Does
+
+When you add these files to your project, OpenCode will:
+- Follow your coding conventions (formatting, patterns, etc.)
+- Write commit messages in your preferred format
+- Audit your code for security vulnerabilities
+- Use proper patterns for your tech stack
+
+## Installation
+
+### Method 1: NPX (Recommended)
+
+```bash
+cd /path/to/your/project
+npx ocs-stats
+```
+
+That's it! The `.opencode` folder will be created in your project.
+
+**Global install** (shared across all projects):
+```bash
+npx ocs-stats --global
+```
+
+### Method 2: Download ZIP
+
+1. Click the green **"Code"** button at the top of this page
+2. Select **"Download ZIP"**
+3. Extract the ZIP file
+4. Copy the `templates/.opencode` folder to your project root
+
+```
+your-project/
+├── .opencode/     ← Paste this folder here
+├── src/
+├── package.json
+└── ...
+```
+
+### Method 3: Clone & Copy
+
+```bash
+git clone https://github.com/Zen0space/opencode-skills.git
+cp -r opencode-skills/templates/.opencode /path/to/your/project/
+```
+
+## Verify Installation
+
+```bash
+cd /path/to/your/project
+opencode
+```
+
+OpenCode automatically loads any `.opencode` folder in your project root.
+
+## Check Your Progress
+
+Use the `stats` command to view your security agent's progress:
+
+```bash
+npx ocs-stats stats
+```
+
+Example output:
+```
+╔══════════════════════════════════════╗
+║        SECURITY AGENT                ║
+╠══════════════════════════════════════╣
+║  Level 1 - Novice                    ║
+║  XP: [█████████░░░░░░░░] 85/150       ║
+║  Progress: 57%                       ║
+║                                      ║
+║  Stats:                              ║
+║  * Issues Fixed:  4                  ║
+║  * Audits Done:   2                  ║
+║  * Patterns Added: 1                 ║
+║  * XP Penalties:  0                  ║
+╚══════════════════════════════════════╝
+```
+
+## Update Skills
+
+```bash
+npx ocs-stats update
+```
+
+## What's Included
+
+### Agents
+
+| Agent | Description |
+|-------|-------------|
+| `security` | Security expert with XP-based leveling system for auditing and fixing vulnerabilities |
+
+### Skills
+
+| Skill | Description |
+|-------|-------------|
+| `commit` | Commit message conventions (type(scope): description format) |
+| `memories` | Session memory for tracking work context and pending tasks |
+| `mobile` | Mobile development (React Native, Flutter, Swift) |
+| `security` | Security patterns, auth approach, and anti-patterns |
+| `webapp` | Web development (React, Vue, Svelte, Angular) |
+
+## Customization
+
+### Understand Session Memory
+
+The `memories` skill tracks your current work session:
+- **Current Focus:** What you're actively working on
+- **Recent Work:** Last changes made
+- **Pending Tasks:** TODOs to complete
+- **Context Notes:** Important decisions and gotchas
+
+The agent reads and updates this file automatically. You can also edit it manually.
+
+### Update Commit Conventions (Optional)
+
+Edit `.opencode/skills/commit/SKILL.md` if you use different commit formats.
+
+### Remove What You Don't Need
+
+```bash
+# Remove mobile skill if you're not building a mobile app
+rm -rf .opencode/skills/mobile
+
+# Remove security agent if you don't need security audits
+rm -rf .opencode/agents/security
+rm -rf .opencode/security
+```
+
+## Security Agent Features
+
+The security agent includes an XP-based leveling system that tracks your progress:
+
+| Level | Title | XP Required |
+|-------|-------|-------------|
+| 1 | Novice | 0 |
+| 2 | Apprentice | 150 |
+| 3 | Practitioner | 450 |
+| 4 | Expert | 900 |
+| 5 | Master | 1500 |
+| 6 | Grandmaster | 3,000 |
+
+### XP Awards (Fix-Only System)
+
+| Action | XP |
+|--------|-----|
+| Fix critical issue | +60 XP |
+| Fix high issue | +35 XP |
+| Fix medium issue | +15 XP |
+| Fix low issue | +10 XP |
+| Add security pattern | +30 XP |
+| Complete package audit | +75 XP |
+
+### Preflight Checklist
+
+Before risky operations (auth changes, DB schema, middleware), the agent:
+1. Shows a dry-run preview
+2. Confirms user permission
+3. Documents rollback plan
+
+## File Structure
+
+```
+.opencode/
+├── agents/
+│   └── security.md          # Security audit agent
+├── skills/
+│   ├── commit/SKILL.md      # Commit conventions
+│   ├── memories/SKILL.md    # Session memory (auto-updated)
+│   ├── mobile/SKILL.md      # Mobile patterns (RN, Flutter, Swift)
+│   ├── security/SKILL.md    # Security patterns
+│   └── webapp/SKILL.md      # Web patterns (React, Vue, Svelte, Angular)
+└── security/
+    ├── xp.json              # XP tracking (auto-updated)
+    └── knowledge.md         # Accumulated findings (auto-updated)
+```
+
+## For Contributors
+
+```
+opencode-skills/
+├── package.json             # npm package config
+├── bin/cli.js               # CLI entry point
+├── src/                     # Source files
+│   ├── init.js
+│   ├── display.js
+│   └── stats.js
+├── templates/               # Files copied to user projects
+│   ├── agents/
+│   ├── skills/
+│   └── security/
+├── README.md
+└── LICENSE
+```
+
+**Publishing to npm:**
+```bash
+npm login
+npm publish
+```
+
+## Troubleshooting
+
+### OpenCode not finding my skills
+
+- Make sure `.opencode` folder is in your **project root** (same level as `package.json`)
+- Check that skill files are named `SKILL.md` (uppercase)
+
+### Skills not working as expected
+
+- Open the `SKILL.md` file and verify the content
+- Make sure the frontmatter (between `---`) is valid YAML
+
+### Want to reset security XP?
+
+Delete the tracking files and OpenCode will recreate them:
+
+```bash
+rm .opencode/security/xp.json
+rm .opencode/security/knowledge.md
+```
+
+## Contributing
+
+Feel free to submit issues and pull requests to improve these skills and agents.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

package/bin/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { init, update } from '../src/init.js';
+import { stats, displayXp } from '../src/stats.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+const isGlobal = args.includes('--global') || args.includes('-g');
+const isHelp = args.includes('--help') || args.includes('-h');
+
+if (isHelp) {
+  console.log(`
+ocs-stats - Install OpenCode skills and agents
+
+Usage:
+  npx ocs-stats              Install to current project
+  npx ocs-stats --global     Install globally (~/.opencode)
+  npx ocs-stats update       Update skills (removes existing)
+  npx ocs-stats stats        Show security agent progress
+  npx ocs-stats display-xp <amount> "<reason>"
+                                          Display XP gain (used by agent)
+
+Options:
+  -g, --global    Install to user home directory
+  -h, --help      Show this help message
+
+Examples:
+  npx ocs-stats
+  npx ocs-stats update
+  npx ocs-stats stats
+  npx ocs-stats display-xp 35 "Fixed high issue"
+`);
+  process.exit(0);
+}
+
+if (command === 'update') {
+  update({ isGlobal }).catch((err) => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
+  process.exit(0);
+}
+
+if (command === 'stats') {
+  stats();
+  process.exit(0);
+}
+
+if (command === 'display-xp') {
+  const amount = args[1];
+  const reason = args[2];
+  displayXp(amount, reason);
+  process.exit(0);
+}
+
+init({ isGlobal }).catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "ocs-stats",
+  "version": "1.0.0",
+  "description": "OpenCode Skills - One-click installer with gamified XP stats",
+  "type": "module",
+  "bin": {
+    "ocs-stats": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "keywords": [
+    "opencode",
+    "ai",
+    "skills",
+    "agents",
+    "cli",
+    "stats"
+  ],
+  "author": "Zen0space",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zen0space/opencode-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Zen0space/opencode-skills/issues"
+  },
+  "homepage": "https://github.com/Zen0space/opencode-skills#readme",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/display.js

@@ -0,0 +1,119 @@
+const LEVEL_THRESHOLDS = [
+  { level: 1, title: 'Novice', xpRequired: 0 },
+  { level: 2, title: 'Apprentice', xpRequired: 150 },
+  { level: 3, title: 'Practitioner', xpRequired: 450 },
+  { level: 4, title: 'Expert', xpRequired: 900 },
+  { level: 5, title: 'Master', xpRequired: 1500 },
+  { level: 6, title: 'Grandmaster', xpRequired: 3000 }
+];
+
+const BOX_WIDTH = 40;
+const CONTENT_WIDTH = BOX_WIDTH - 2;
+
+export function progressBar(current, max, width = 16) {
+  const safeCurrent = Math.max(0, current);
+  const safeMax = Math.max(1, max);
+  const filled = Math.min(width, Math.round((safeCurrent / safeMax) * width));
+  const empty = width - filled;
+  return '█'.repeat(filled) + '░'.repeat(empty);
+}
+
+export function getNextLevelXp(currentLevel) {
+  const nextLevel = LEVEL_THRESHOLDS.find(t => t.level === currentLevel + 1);
+  return nextLevel ? nextLevel.xpRequired : null;
+}
+
+function line(content) {
+  const padding = CONTENT_WIDTH - content.length;
+  return '║' + content + ' '.repeat(Math.max(0, padding)) + '║';
+}
+
+function topBorder() {
+  return '╔' + '═'.repeat(CONTENT_WIDTH) + '╗';
+}
+
+function bottomBorder() {
+  return '╚' + '═'.repeat(CONTENT_WIDTH) + '╝';
+}
+
+function divider() {
+  return '╠' + '═'.repeat(CONTENT_WIDTH) + '╣';
+}
+
+function emptyLine() {
+  return '║' + ' '.repeat(CONTENT_WIDTH) + '║';
+}
+
+export function showXpGain(amount, reason, data) {
+  const { xp, level, title } = data;
+  const nextLevelXp = getNextLevelXp(level);
+  
+  const xpText = `+${amount} XP  ${reason.substring(0, 24)}`;
+  const levelText = `Level ${level} - ${title}`;
+  
+  console.log('');
+  console.log(topBorder());
+  console.log(line('  ' + xpText));
+  console.log(divider());
+  console.log(line('  ' + levelText));
+  
+  if (!nextLevelXp) {
+    console.log(line('  [████████████████] MAX LEVEL!'));
+  } else {
+    const bar = progressBar(xp, nextLevelXp);
+    const xpStr = `${xp}/${nextLevelXp}`;
+    console.log(line(`  [${bar}] ${xpStr}`));
+  }
+  
+  console.log(bottomBorder());
+  console.log('');
+}
+
+export function showStats(data) {
+  const { xp, level, title, issuesFixed, totalAudits, patternsAdded, mistakes } = data;
+  const nextLevelXp = getNextLevelXp(level);
+  
+  const totalFixed = (issuesFixed?.critical || 0) + 
+                     (issuesFixed?.high || 0) + 
+                     (issuesFixed?.medium || 0) + 
+                     (issuesFixed?.low || 0);
+  
+  const totalPenalty = mistakes?.totalPenaltyXP || 0;
+  
+  console.log('');
+  console.log(topBorder());
+  console.log(line('        SECURITY AGENT'));
+  console.log(divider());
+  console.log(line(`  Level ${level} - ${title}`));
+  
+  if (!nextLevelXp) {
+    console.log(line('  XP: [████████████████] MAX LEVEL!'));
+  } else {
+    const bar = progressBar(xp, nextLevelXp);
+    const xpStr = `${xp}/${nextLevelXp}`;
+    const percent = Math.round((xp / nextLevelXp) * 100);
+    console.log(line(`  XP: [${bar}] ${xpStr}`));
+    console.log(line(`  Progress: ${percent}%`));
+  }
+  
+  console.log(emptyLine());
+  console.log(line('  Stats:'));
+  console.log(line(`  * Issues Fixed:  ${totalFixed}`));
+  console.log(line(`  * Audits Done:   ${totalAudits || 0}`));
+  console.log(line(`  * Patterns Added: ${patternsAdded || 0}`));
+  console.log(line(`  * XP Penalties:  ${totalPenalty}`));
+  console.log(bottomBorder());
+  console.log('');
+}
+
+export function showLevelUp(newLevel, newTitle) {
+  console.log('');
+  console.log(topBorder());
+  console.log(emptyLine());
+  console.log(line('          LEVEL UP!'));
+  console.log(emptyLine());
+  console.log(line(`     Level ${newLevel} - ${newTitle}`));
+  console.log(emptyLine());
+  console.log(bottomBorder());
+  console.log('');
+}

package/src/init.js

@@ -0,0 +1,87 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+export async function init({ isGlobal = false } = {}) {
+  const targetDir = isGlobal 
+    ? path.join(process.env.HOME || process.env.USERPROFILE, '.opencode')
+    : path.join(process.cwd(), '.opencode');
+
+  const targetParent = path.dirname(targetDir);
+
+  console.log(`\nInstalling OpenCode skills to: ${targetDir}\n`);
+
+  if (fs.existsSync(targetDir)) {
+    console.log('.opencode folder already exists.');
+    console.log('   To update: npx ocs-stats update\n');
+    process.exit(0);
+  }
+
+  if (!fs.existsSync(targetParent)) {
+    fs.mkdirSync(targetParent, { recursive: true });
+  }
+
+  copyDir(TEMPLATES_DIR, targetDir);
+
+  console.log('Installed successfully!\n');
+  console.log('What was installed:');
+  console.log('  * Agents: security');
+  console.log('  * Skills: commit, memories, mobile, security, webapp');
+  console.log('  * Security: XP tracking, knowledge base\n');
+  
+  if (!isGlobal) {
+    console.log('Next steps:');
+    console.log('  1. Edit .opencode/skills/memories/SKILL.md to match your project');
+    console.log('  2. Run `opencode` in this directory to start using the skills\n');
+    console.log('Check progress: npx ocs-stats stats\n');
+  }
+}
+
+export async function update({ isGlobal = false } = {}) {
+  const targetDir = isGlobal 
+    ? path.join(process.env.HOME || process.env.USERPROFILE, '.opencode')
+    : path.join(process.cwd(), '.opencode');
+
+  console.log(`\nUpdating OpenCode skills at: ${targetDir}\n`);
+
+  if (!fs.existsSync(targetDir)) {
+    console.log('.opencode folder not found. Run `npx ocs-stats` first.\n');
+    process.exit(1);
+  }
+
+  // Remove existing
+  fs.rmSync(targetDir, { recursive: true, force: true });
+  console.log('  Removed existing .opencode folder');
+
+  // Reinstall
+  copyDir(TEMPLATES_DIR, targetDir);
+  console.log('  Installed fresh copy\n');
+
+  console.log('Updated successfully!\n');
+  console.log('What was installed:');
+  console.log('  * Agents: security');
+  console.log('  * Skills: commit, memories, mobile, security, webapp');
+  console.log('  * Security: XP tracking, knowledge base\n');
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}

package/src/stats.js

@@ -0,0 +1,48 @@
+import fs from 'fs';
+import path from 'path';
+import { showStats, showXpGain } from './display.js';
+
+function findXpJson() {
+  const cwdPath = path.join(process.cwd(), '.opencode', 'security', 'xp.json');
+  
+  if (fs.existsSync(cwdPath)) {
+    return cwdPath;
+  }
+  
+  return null;
+}
+
+export function stats() {
+  const xpPath = findXpJson();
+  
+  if (!xpPath) {
+    console.log('');
+    console.log('  No .opencode/security/xp.json found in this project.');
+    console.log('');
+    console.log('  Make sure you\'re in a project with opencode-skills installed.');
+    console.log('  Run: npx create-opencode-skills');
+    console.log('');
+    process.exit(1);
+  }
+  
+  const data = JSON.parse(fs.readFileSync(xpPath, 'utf-8'));
+  showStats(data);
+}
+
+export function displayXp(amount, reason) {
+  const xpPath = findXpJson();
+  
+  if (!xpPath) {
+    console.log('No xp.json found');
+    process.exit(1);
+  }
+  
+  if (!amount || isNaN(amount)) {
+    console.log('Invalid XP amount. Usage: display-xp <amount> "<reason>"');
+    process.exit(1);
+  }
+  
+  const data = JSON.parse(fs.readFileSync(xpPath, 'utf-8'));
+  const reasonText = reason || 'XP earned';
+  showXpGain(parseInt(amount, 10), reasonText, data);
+}