popii-framework 0.6.1-beta.0

package/README.md

@@ -0,0 +1,159 @@
+<div align="center">
+  <h1>🥤 Popii</h1>
+  <p><b>A convention-first Discord bot framework built for the <a href="https://bun.sh/">Bun</a> runtime.</b></p>
+  <p>
+    <a href="https://npmjs.com/package/popii-framework">
+      <img src="https://img.shields.io/npm/v/popii-framework?color=F04F96&labelColor=0D0610&label=npm" alt="npm version">
+    </a>
+    <a href="https://npmjs.com/package/popii-framework">
+      <img src="https://img.shields.io/npm/v/popii-framework/beta?color=e879a0&labelColor=0D0610&label=beta" alt="npm beta version">
+    </a>
+    <a href="https://docs.loveyourmaid.moe">
+      <img src="https://img.shields.io/badge/docs-docs.loveyourmaid.moe-F04F96?labelColor=0D0610" alt="documentation">
+    </a>
+    <img src="https://img.shields.io/badge/bun-%3E%3D1.1.0-F04F96?labelColor=0D0610" alt="bun version">
+    <img src="https://img.shields.io/badge/discord.js-14-F04F96?labelColor=0D0610" alt="discord.js version">
+    <img src="https://img.shields.io/badge/license-MIT-F04F96?labelColor=0D0610" alt="license">
+  </p>
+</div>
+
+---
+
+Popii lets you build Discord bots the way modern web frameworks handle routing — drop a file, get a command. No boilerplate, no manual registration, no restarts during development.
+
+```ts
+// src/commands/ping.ts
+import { command } from "popii-framework";
+
+export default command({
+  name: "ping",
+  description: "Replies with pong!",
+  slash: true,
+  async do(pop) {
+    await pop.reply(`Pong! ${pop.client.discord.ws.ping}ms`);
+  }
+});
+```
+
+That's it. Popii finds the file, registers the slash command, and hot-reloads it on save.
+
+---
+
+## Features
+
+- **Folder-based routing** — `src/commands/config/set.ts` becomes `/config set` automatically
+- **Hot-module replacement** — edit commands, events, and middleware without disconnecting from Discord
+- **Plugin system** — extend the `pop` context with new methods and properties
+- **Plugin marketplace** — install community plugins with `popii add <name>`
+- **Built-in plugins** — SQLite, voice, AI, economy, web dashboard, and more out of the box
+- **Middleware** — Express-style middleware pipeline for commands and events
+- **Sharding** — first-class multi-shard support via `PopiiShardingManager`
+- **Type-safe** — full TypeScript support with augmentable context types
+
+---
+
+## Getting Started
+
+```bash
+bunx popii init
+```
+
+The setup wizard scaffolds a new project with your chosen plugins, folder structure, and `.env` in seconds. Open your browser, pick your plugins, paste your token, done.
+
+```bash
+cd my-bot
+bun run dev
+```
+
+Your bot is live with HMR enabled. Save any file and changes apply instantly.
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `popii init` | Scaffold a new bot project |
+| `popii dev` | Start the dev server with HMR |
+| `popii sync` | Manually sync slash commands to Discord |
+| `popii add <name>` | Install a plugin from the marketplace |
+| `popii remove <name>` | Uninstall a plugin |
+| `popii search <query>` | Search the plugin marketplace |
+| `popii list` | List installed plugins |
+| `popii g <type> <name>` | Generate a command, event, snap, middleware, task, or test |
+| `popii doctor` | Check your environment for common issues |
+| `popii deploy` | Generate deployment config for Railway, Fly.io, or VPS |
+| `popii migrate <create\|up>` | Run SQLite migrations |
+| `popii console` | Start an interactive REPL with the bot in scope |
+| `popii dashboard` | Print web dashboard setup instructions |
+
+---
+
+## Built-in Plugins
+
+| Plugin | Description |
+|--------|-------------|
+| `sqlitePlugin` | Bun SQLite database injected into every `pop` context |
+| `mongoosePlugin` | MongoDB via Mongoose ODM |
+| `voicePlugin` | Voice channel playback with queue, SponsorBlock, and now-playing cards |
+| `webPlugin` | HTTP server with health checks, metrics, and an optional web dashboard |
+| `deskPlugin` | Full support ticket system |
+| `popiiAiPlugin` | AI assistant via OpenAI, Gemini, or Anthropic |
+| `economyPlugin` | Virtual currency, inventory, and shop system |
+| `uiPlugin` | Pagination, forms, and interactive prompts |
+| `payPlugin` | Payment processing |
+| `autoModPlugin` | Automated moderation |
+| `giveawayPlugin` | Giveaway system |
+| `canvasPlugin` | Image generation and now-playing cards |
+| `lastFmPlugin` | Last.fm scrobbling and now-playing integration |
+| `captchaPlugin` | Verification captchas |
+| `activityRotatorPlugin` | Rotating bot status messages |
+| `telemetryPlugin` | Performance monitoring |
+| `commandLoggerPlugin` | Command execution logging |
+| `commandAnalyticPlugin` | Usage analytics |
+| `permissionGuardPlugin` | Automatic permission enforcement |
+| `errorHandlerPlugin` | Graceful error handling |
+| `reloadPlugin` | Adds a `/reload` slash command |
+
+---
+
+## Plugin Marketplace
+
+Install community plugins directly from the CLI:
+
+```bash
+bunx popii add economy        # installs popii-plugin-economy
+bunx popii search music       # search the registry
+bunx popii list               # show installed plugins
+```
+
+Plugins are discovered automatically on startup when `autoDiscover: true` is set:
+
+```ts
+const client = popiiClient({
+  token: process.env.DISCORD_TOKEN!,
+  autoDiscover: true,
+  pluginConfig: {
+    "popii-plugin-economy": { currencySymbol: "🪙" }
+  }
+});
+```
+
+Want to build a plugin? Use the [plugin template](https://github.com/popii-dev/plugin-template) to get started.
+
+---
+
+## Requirements
+
+- [Bun](https://bun.sh/) ≥ 1.1.0
+- `discord.js` ^14.0.0 (peer dependency, installed automatically by `popii init`)
+
+Optional peer dependencies installed as needed:
+- `ioredis` — for Redis-backed storage and multi-shard coordination
+- `@discordjs/voice` + `libsodium-wrappers` — for the voice plugin
+
+---
+
+## License
+
+MIT

package/dist/cli/commands.d.ts

@@ -0,0 +1,15 @@
+export declare function runDev(args: string[]): Promise<void>;
+export declare function runSync(args: string[]): Promise<void>;
+export declare function runConsole(args: string[]): Promise<void>;
+export declare function runMigrate(args: string[]): Promise<void>;
+export declare function runInstall(args: string[]): Promise<void>;
+export declare function runAdd(args: string[]): Promise<void>;
+export declare function runRemove(args: string[]): Promise<void>;
+export declare function runSearch(args: string[]): Promise<void>;
+export declare function runList(args: string[]): Promise<void>;
+export declare function runGenerate(args: string[]): Promise<void>;
+export declare function runDoctor(args: string[]): Promise<void>;
+export declare function runDeploy(args: string[]): Promise<void>;
+export declare function runDashboard(args: string[]): Promise<void>;
+export declare function runInit(args: string[]): Promise<void>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/cli/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"AAQA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,iBAwB1C;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,iBAO3C;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,iBAc9C;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,iBA2C9C;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,iBAuD9C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,iBAoF1C;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,iBAoB7C;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,iBA2C7C;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,iBA4C3C;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,iBA4F/C;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,iBA6E7C;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,iBAqF7C;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,iBAqDhD;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,iBAuF3C"}

package/dist/cli/pages.d.ts

@@ -0,0 +1,5 @@
+export declare function openBrowser(url: string): void;
+export declare function setupPageHtml(): string;
+export declare function donePageHtml(botName: string): string;
+export declare function initViaWeb(): Promise<void>;
+//# sourceMappingURL=pages.d.ts.map

package/dist/cli/pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/cli/pages.ts"],"names":[],"mappings":"AAEA,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,QAItC;AAED,wBAAgB,aAAa,IAAI,MAAM,CAqdtC;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA8BpD;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CA+BhD"}

package/dist/cli/scaffold.d.ts

@@ -0,0 +1,23 @@
+export type BuiltinFieldSpec = {
+    configKey: string;
+    envKey?: string;
+    type: "string" | "number" | "bool";
+    default?: string;
+    enabledBy?: string;
+};
+export declare const BUILTIN_PLUGIN_FIELDS: Record<string, BuiltinFieldSpec[]>;
+export declare function buildPluginOptionsStr(pluginName: string, cfg: Record<string, string>): string;
+export declare function scaffoldProject(opts: {
+    botName: string;
+    plugins: string[];
+    communityPlugins?: {
+        npmName: string;
+        exportName: string;
+    }[];
+    botToken: string;
+    installDeps: boolean;
+    genDocker: boolean;
+    pluginConfig?: Record<string, Record<string, string>>;
+    communityPluginConfig?: Record<string, Record<string, string>>;
+}): Promise<void>;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/cli/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/cli/scaffold.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,gBAAgB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhJ,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAuCpE,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CA+C7F;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gBAAgB,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChE,iBA+HA"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}