create-leaderboard-plugin 0.1.0

package/dist/index.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * Create Leaderboard Plugin CLI Tool
+ *
+ * Generates a new leaderboard plugin project structure
+ */
+import { readFile } from "fs/promises";
+import { join, resolve } from "path";
+import { existsSync, mkdirSync, writeFileSync, readdirSync } from "fs";
+import prompts from "prompts";
+import { generatePackageJson } from "./templates/package-json";
+import { generateTsConfig } from "./templates/tsconfig";
+import { generateVitestConfig } from "./templates/vitest-config";
+import { generateIndexTs } from "./templates/index-ts";
+import { generateTestTs } from "./templates/test-ts";
+import { generateReadme } from "./templates/readme";
+/**
+ * Validate plugin name format (alphanumeric + hyphens, no spaces)
+ */
+function validatePluginName(name) {
+    return /^[a-z0-9-]+$/.test(name) && name.length > 0;
+}
+/**
+ * Get default author from root package.json or environment
+ */
+async function getDefaultAuthor() {
+    try {
+        const rootPackageJsonPath = resolve(process.cwd(), "package.json");
+        if (existsSync(rootPackageJsonPath)) {
+            const content = await readFile(rootPackageJsonPath, "utf-8");
+            const pkg = JSON.parse(content);
+            if (pkg.author) {
+                return pkg.author;
+            }
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return "Open Healthcare Network";
+}
+/**
+ * Prompt user for plugin information
+ */
+async function promptUser() {
+    const defaultAuthor = await getDefaultAuthor();
+    const response = await prompts([
+        {
+            type: "text",
+            name: "pluginName",
+            message: "Plugin name (e.g., 'github', 'slack'):",
+            validate: (value) => {
+                if (!value)
+                    return "Plugin name is required";
+                if (!validatePluginName(value)) {
+                    return "Plugin name must contain only lowercase letters, numbers, and hyphens";
+                }
+                return true;
+            },
+        },
+        {
+            type: "text",
+            name: "description",
+            message: "Plugin description:",
+            validate: (value) => {
+                if (!value)
+                    return "Description is required";
+                return true;
+            },
+        },
+        {
+            type: "text",
+            name: "author",
+            message: "Author:",
+            initial: defaultAuthor,
+            validate: (value) => {
+                if (!value)
+                    return "Author is required";
+                return true;
+            },
+        },
+    ]);
+    if (!response.pluginName || !response.description || !response.author) {
+        console.error("Creation cancelled.");
+        process.exit(1);
+    }
+    return {
+        pluginName: response.pluginName,
+        description: response.description,
+        author: response.author,
+        packageName: `@leaderboard/plugin-${response.pluginName}`,
+    };
+}
+/**
+ * Create directory structure
+ */
+function createDirectoryStructure(pluginDir) {
+    const dirs = [
+        pluginDir,
+        join(pluginDir, "src"),
+        join(pluginDir, "src", "__tests__"),
+    ];
+    for (const dir of dirs) {
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+}
+/**
+ * Generate plugin files
+ */
+function generateFiles(pluginDir, options) {
+    // package.json
+    writeFileSync(join(pluginDir, "package.json"), generatePackageJson(options), "utf-8");
+    // tsconfig.json
+    writeFileSync(join(pluginDir, "tsconfig.json"), generateTsConfig(), "utf-8");
+    // vitest.config.ts
+    writeFileSync(join(pluginDir, "vitest.config.ts"), generateVitestConfig(), "utf-8");
+    // src/index.ts
+    writeFileSync(join(pluginDir, "src", "index.ts"), generateIndexTs(options), "utf-8");
+    // src/__tests__/plugin.test.ts
+    writeFileSync(join(pluginDir, "src", "__tests__", "plugin.test.ts"), generateTestTs(options), "utf-8");
+    // README.md
+    writeFileSync(join(pluginDir, "README.md"), generateReadme(options), "utf-8");
+}
+/**
+ * Main function
+ */
+async function main() {
+    console.log("Create Leaderboard Plugin\n");
+    // Show usage if help flag is provided
+    if (process.argv.includes("--help") || process.argv.includes("-h")) {
+        console.log("Usage: pnpm create-leaderboard-plugin [target-directory]");
+        console.log("\nArguments:");
+        console.log("  target-directory  Directory where the plugin will be created (default: current directory)");
+        console.log("\nExamples:");
+        console.log("  pnpm create-leaderboard-plugin .");
+        console.log("  pnpm create-leaderboard-plugin ../../plugins/slack");
+        console.log("  pnpm create-leaderboard-plugin my-plugin");
+        process.exit(0);
+    }
+    // Get target directory from command line args (default to current directory)
+    const targetArg = process.argv[2] || ".";
+    const targetDir = resolve(process.cwd(), targetArg);
+    // Check if target directory exists and is not empty
+    if (existsSync(targetDir)) {
+        const files = readdirSync(targetDir);
+        if (files.length > 0) {
+            console.error(`Error: Directory "${targetArg}" is not empty.`);
+            console.error("Please specify an empty directory or a new directory path.");
+            process.exit(1);
+        }
+    }
+    // Prompt for information
+    const options = await promptUser();
+    try {
+        // Create directory structure
+        console.log(`Creating plugin in: ${targetDir}`);
+        createDirectoryStructure(targetDir);
+        // Generate files
+        console.log("Generating plugin files...");
+        generateFiles(targetDir, options);
+        console.log(`\n✓ Plugin "${options.packageName}" created successfully!`);
+        console.log(`\nNext steps:`);
+        if (targetArg !== ".") {
+            console.log(`  1. cd ${targetArg}`);
+            console.log(`  2. pnpm install`);
+        }
+        else {
+            console.log(`  1. pnpm install`);
+        }
+        console.log(`  ${targetArg !== "." ? "3" : "2"}. Implement your plugin logic in src/index.ts`);
+        console.log(`  ${targetArg !== "." ? "4" : "3"}. pnpm build`);
+        console.log(`  ${targetArg !== "." ? "5" : "4"}. Add the plugin to your config.yaml`);
+    }
+    catch (error) {
+        console.error("Error creating plugin:", error);
+        process.exit(1);
+    }
+}
+// Run main function
+main().catch((error) => {
+    console.error("Unhandled error:", error);
+    process.exit(1);
+});

package/dist/templates/index-ts.js

@@ -0,0 +1,137 @@
+/**
+ * Generate src/index.ts template
+ */
+export function generateIndexTs(options) {
+    return `/**
+ * ${options.description}
+ */
+
+import {
+  activityDefinitionQueries,
+  activityQueries,
+  contributorQueries,
+  contributorAggregateDefinitionQueries,
+  contributorAggregateQueries,
+  badgeDefinitionQueries,
+  contributorBadgeQueries,
+  type Plugin,
+  type PluginContext,
+} from "@ohcnetwork/leaderboard-api";
+
+const plugin: Plugin = {
+  name: "${options.packageName}",
+  version: "0.1.0",
+  
+  async setup(ctx: PluginContext) {
+    ctx.logger.info("Setting up ${options.pluginName} plugin...");
+    
+    // TODO: Define activity types here
+    // Example:
+    // await activityDefinitionQueries.insertOrIgnore(ctx.db, {
+    //   slug: "activity_slug",
+    //   name: "Activity Name",
+    //   description: "Activity description",
+    //   points: 10,
+    //   icon: "icon-name",
+    // });
+    
+    // TODO: Define contributor aggregate definitions (optional)
+    // Example:
+    // await contributorAggregateDefinitionQueries.upsert(ctx.db, {
+    //   slug: "custom_metric",
+    //   name: "Custom Metric",
+    //   description: "Example custom metric",
+    // });
+    
+    // TODO: Define badge definitions (optional)
+    // Example:
+    // await badgeDefinitionQueries.upsert(ctx.db, {
+    //   slug: "example_badge",
+    //   name: "Example Badge",
+    //   description: "Achievement badge for custom criteria",
+    //   variants: {
+    //     bronze: {
+    //       description: "Level 1",
+    //       svg_url: "https://example.com/bronze.svg",
+    //     },
+    //     silver: {
+    //       description: "Level 2",
+    //       svg_url: "https://example.com/silver.svg",
+    //     },
+    //     gold: {
+    //       description: "Level 3",
+    //       svg_url: "https://example.com/gold.svg",
+    //     },
+    //   },
+    // });
+    
+    ctx.logger.info("Setup complete");
+  },
+  
+  async scrape(ctx: PluginContext) {
+    ctx.logger.info("Starting ${options.pluginName} data scraping...");
+    
+    // TODO: Implement your scraping logic here
+    // Example:
+    // const data = await fetchDataFromSource(ctx.config);
+    // 
+    // for (const item of data) {
+    //   // Ensure contributor exists
+    //   await contributorQueries.upsert(ctx.db, {
+    //     username: item.user.username,
+    //     name: item.user.name,
+    //     role: null,
+    //     title: null,
+    //     avatar_url: item.user.avatar_url,
+    //     bio: null,
+    //     social_profiles: null,
+    //     joining_date: null,
+    //     meta: null,
+    //   });
+    //
+    //   // Insert activity
+    //   await activityQueries.upsert(ctx.db, {
+    //     slug: \`activity-\${item.id}\`,
+    //     contributor: item.user.username,
+    //     activity_definition: "activity_slug",
+    //     title: item.title,
+    //     occured_at: new Date(item.timestamp).toISOString(),
+    //     link: item.url,
+    //     text: item.description,
+    //     points: null, // Uses default from activity_definition
+    //     meta: null,
+    //   });
+    // }
+    
+    // TODO: Set custom aggregates (optional)
+    // Example:
+    // await contributorAggregateQueries.upsert(ctx.db, {
+    //   aggregate: "custom_metric",
+    //   contributor: "username",
+    //   value: {
+    //     type: "number",
+    //     value: 42,
+    //     unit: "items",
+    //     format: "integer",
+    //   },
+    //   meta: { source: "external_api" },
+    // });
+    
+    // TODO: Award custom badges (optional)
+    // Example:
+    // await contributorBadgeQueries.award(ctx.db, {
+    //   slug: \`example_badge__username__bronze\`,
+    //   badge: "example_badge",
+    //   contributor: "username",
+    //   variant: "bronze",
+    //   achieved_on: new Date().toISOString().split("T")[0],
+    //   meta: { reason: "Custom criteria met" },
+    // });
+    
+    ctx.logger.info("Scraping complete");
+  },
+};
+
+export default plugin;
+`;
+}

package/dist/templates/package-json.js

@@ -0,0 +1,31 @@
+/**
+ * Generate package.json template
+ */
+export function generatePackageJson(options) {
+    // Use JSON.stringify to safely escape strings
+    const pkg = {
+        name: options.packageName,
+        version: "0.1.0",
+        description: options.description,
+        type: "module",
+        main: "dist/index.js",
+        types: "dist/index.d.ts",
+        scripts: {
+            build: "tsc",
+            test: "vitest run",
+            "test:watch": "vitest",
+        },
+        keywords: ["leaderboard", "plugin"],
+        dependencies: {
+            "@ohcnetwork/leaderboard-api": "^0.1.0",
+        },
+        devDependencies: {
+            "@types/node": "^20.19.27",
+            typescript: "^5.7.3",
+            vitest: "^4.0.16",
+        },
+        author: options.author,
+        license: "MIT",
+    };
+    return JSON.stringify(pkg, null, 2) + "\n";
+}

package/dist/templates/readme.js

@@ -0,0 +1,59 @@
+/**
+ * Generate README.md template
+ */
+export function generateReadme(options) {
+    const displayName = options.pluginName
+        .split("-")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+    return `# ${options.packageName}
+
+${options.description}
+
+## Configuration
+
+Add the plugin to your \`config.yaml\`:
+
+\`\`\`yaml
+leaderboard:
+  plugins:
+    ${options.pluginName}:
+      source: "${options.packageName}"
+      config:
+        # TODO: Add your plugin configuration options here
+\`\`\`
+
+## Usage
+
+1. Build the plugin:
+
+\`\`\`bash
+pnpm build
+\`\`\`
+
+2. Add the plugin to your \`config.yaml\` (see Configuration above)
+
+3. Run the plugin runner:
+
+\`\`\`bash
+pnpm data:scrape
+\`\`\`
+
+## Development
+
+\`\`\`bash
+# Build the plugin
+pnpm build
+
+# Run tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+\`\`\`
+
+## License
+
+MIT
+`;
+}

package/dist/templates/test-ts.js

@@ -0,0 +1,97 @@
+/**
+ * Generate src/__tests__/plugin.test.ts template
+ */
+export function generateTestTs(options) {
+    return `/**
+ * Tests for ${options.pluginName} plugin
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createDatabase, initializeSchema } from "@ohcnetwork/leaderboard-api";
+import type { Database } from "@ohcnetwork/leaderboard-api";
+import plugin from "../index";
+
+describe("${options.pluginName.charAt(0).toUpperCase() + options.pluginName.slice(1)} Plugin", () => {
+  let db: Database;
+
+  beforeEach(async () => {
+    db = createDatabase(":memory:");
+    await initializeSchema(db);
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  it("should have correct plugin metadata", () => {
+    expect(plugin.name).toBe("${options.packageName}");
+    expect(plugin.version).toBeTruthy();
+    expect(plugin.scrape).toBeDefined();
+  });
+
+  it("should setup activity definitions", async () => {
+    const logger = {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    };
+
+    if (plugin.setup) {
+      await plugin.setup({
+        db,
+        config: {},
+        orgConfig: {
+          name: "Test Org",
+          description: "Test",
+          url: "https://test.com",
+          logo_url: "https://test.com/logo.png",
+        },
+        logger,
+      });
+    }
+
+    // TODO: Add assertions for your activity definitions
+  });
+
+  it("should scrape data", async () => {
+    const logger = {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    };
+
+    // Setup first if needed
+    if (plugin.setup) {
+      await plugin.setup({
+        db,
+        config: {},
+        orgConfig: {
+          name: "Test Org",
+          description: "Test",
+          url: "https://test.com",
+          logo_url: "https://test.com/logo.png",
+        },
+        logger,
+      });
+    }
+
+    // Then scrape
+    await plugin.scrape({
+      db,
+      config: {},
+      orgConfig: {
+        name: "Test Org",
+        description: "Test",
+        url: "https://test.com",
+        logo_url: "https://test.com/logo.png",
+      },
+      logger,
+    });
+
+    // TODO: Add assertions for scraped data
+  });
+});
+`;
+}

package/dist/templates/tsconfig.js

@@ -0,0 +1,31 @@
+/**
+ * Generate tsconfig.json template
+ */
+export function generateTsConfig() {
+    return `{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "incremental": true,
+    "paths": {
+      "@/*": ["./*"]
+    },
+    "noUncheckedIndexedAccess": true,
+    "strictNullChecks": true
+  },
+  "include": ["**/*.ts", "**/*.mts"],
+  "exclude": ["node_modules"]
+}
+
+`;
+}

package/dist/templates/vitest-config.js

@@ -0,0 +1,14 @@
+/**
+ * Generate vitest.config.ts template
+ */
+export function generateVitestConfig() {
+    return `import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+  },
+});
+`;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for the create-plugin tool
+ */
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "create-leaderboard-plugin",
+  "version": "0.1.0",
+  "description": "CLI tool to generate leaderboard plugin projects",
+  "type": "module",
+  "main": "dist/index.js",
+  "private": false,
+  "bin": {
+    "create-leaderboard-plugin": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "leaderboard",
+    "plugin",
+    "generator",
+    "cli"
+  ],
+  "author": "Open Healthcare Network",
+  "license": "MIT",
+  "dependencies": {
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.27",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5.7.3"
+  }
+}