diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..eb40842d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,121 @@ +# AGENTS.md + +This file is the operational guide for coding agents working in the +CommandKit monorepo. + +## Repository layout + +- Monorepo managed with `pnpm` workspaces + Turborepo. +- Workspace roots: + - `packages/*` - published/core packages + - `apps/*` - first-party apps (docs site, test bot, etc.) +- Key project used as real-world reference: + - `apps/test-bot` - practical CommandKit usage patterns (plugins, + JSX components, tasks, workflow, ratelimit, i18n, sharding manager + pattern) + +## First source of truth for agents + +Use the skills in `skills/` first, then confirm with code and docs. + +- Skills index: `skills/README.md` +- Core framework skill: `skills/commandkit/SKILL.md` +- Plugin development skill: + `skills/commandkit-plugin-development/SKILL.md` + +Each skill includes: + +- `SKILL.md` with activation guidance and reference/tool tables +- `references/*.md` with implementation details and best practices +- optional `tools/*.mjs` helper generators/validators + +## CommandKit conventions to preserve + +When editing CommandKit projects (especially `apps/test-bot`), +preserve convention-based discovery: + +- Config file at root: `commandkit.config.ts` (or `.js`) +- App entrypoint: `src/app.ts` (exports discord.js client) +- Commands: `src/app/commands/**` +- Events: `src/app/events/**` +- Optional feature paths: + - i18n: `src/app/locales/**` + - tasks: `src/app/tasks/**` + - workflow: `src/workflows/**` + - ratelimit runtime config: `ratelimit.ts` + - sharding manager: `src/sharding-manager.ts` + +Important middleware naming conventions: + +- `+global-middleware.ts` +- `+middleware.ts` +- `+.middleware.ts` + +## Preferred implementation workflow + +1. Identify the target package/app and relevant skill in `skills/`. +2. Read the corresponding `references/*.md` for exact patterns. +3. Mirror existing local conventions (from nearby files) before + introducing new structures. +4. Make minimal, focused changes. +5. Validate with the appropriate command(s). + +## Validation commands + +From repo root: + +- Install deps: `pnpm install` +- Build packages: `pnpm build` +- Type-check packages: `pnpm check-types` +- Format codebase: `pnpm format` +- Check formatting only: `pnpm prettier:check` + +For app-level verification (example test bot): + +- `pnpm --filter test-bot dev` +- `pnpm --filter test-bot build` +- `pnpm --filter test-bot start` + +## Documentation and guide alignment + +When adding or changing behavior, keep docs alignment in mind: + +- Guide docs: `apps/website/docs/guide/**` +- API reference docs: `apps/website/docs/api-reference/**` + +If you add new user-facing behavior in packages, update the relevant +guide and/or API reference pages. + +## Plugin development guidance + +For creating CommandKit plugins: + +- Runtime plugin patterns: + `skills/commandkit-plugin-development/references/01-runtime-plugin-basics.md` +- Runtime hook mapping: + `skills/commandkit-plugin-development/references/02-runtime-hooks-reference.md` +- Compiler transforms: + `skills/commandkit-plugin-development/references/03-compiler-plugin-transform.md` +- Template extension hooks: + `skills/commandkit-plugin-development/references/04-template-registration.md` +- Rolldown integration: + `skills/commandkit-plugin-development/references/05-rolldown-plugins.md` + +## Safety and quality rules + +- Do not introduce APIs that are not already present in the + codebase/docs unless explicitly asked. +- Do not break convention-based file discovery paths. +- Keep changes backward-compatible unless the task explicitly requires + a breaking change. +- Prefer explicit error handling in runtime hooks and long-running + workflows. +- For interactive JSX components, use valid interaction patterns + (`onClick` for interactive buttons, link buttons with `url` + + `ButtonStyle.Link`). + +## Git hygiene + +- Do not revert unrelated user changes. +- Keep commits scoped and descriptive when asked to commit. +- Avoid destructive git operations unless explicitly requested. diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 00000000..c8ee76fe --- /dev/null +++ b/skills/README.md @@ -0,0 +1,44 @@ +# CommandKit Skills Index + +This directory contains self-contained skills for public CommandKit +packages and development workflows. + +Each skill folder includes: + +- `SKILL.md` for activation and execution behavior +- `README.md` for human-facing scope and usage notes +- `references/*.md` for feature-specific snippets, filesystem + expectations, important details, and best practices +- optional `tools/*.mjs` JavaScript helpers with shebang for + repeatable utility tasks + +`SKILL.md` files include tabular indexes for references and tools, +with name + description columns. + +## Included skills + +- `skills/commandkit` +- `skills/create-commandkit` +- `skills/commandkit-ai` +- `skills/commandkit-analytics` +- `skills/commandkit-cache` +- `skills/commandkit-devtools` +- `skills/commandkit-i18n` +- `skills/commandkit-legacy-migration` +- `skills/commandkit-queue` +- `skills/commandkit-ratelimit` +- `skills/commandkit-redis` +- `skills/commandkit-tasks` +- `skills/commandkit-workflow` +- `skills/commandkit-plugin-development` + +## Excluded internal packages + +- `@commandkit/devtools-ui` (private internal UI package) +- `tsconfig` (private internal tooling package) + +## Legacy policy + +`@commandkit/legacy` is represented only by a migration-focused skill. +It should be used to move existing projects to modern CommandKit +patterns, not to encourage new legacy adoption. diff --git a/skills/commandkit-ai/README.md b/skills/commandkit-ai/README.md new file mode 100644 index 00000000..dc5fe0a2 --- /dev/null +++ b/skills/commandkit-ai/README.md @@ -0,0 +1,22 @@ +# commandkit-ai skill + +Specialized skill for implementing AI features with `@commandkit/ai`. + +## Use this skill when + +- enabling AI plugin support in CommandKit +- building natural language command flows +- registering/executing AI tools +- debugging AI response or execution behavior + +## Typical inputs + +- target AI behavior +- model/provider constraints +- desired tool integration + +## Expected outputs + +- plugin/config updates +- command-level implementation changes +- practical error handling and fallback strategy diff --git a/skills/commandkit-ai/SKILL.md b/skills/commandkit-ai/SKILL.md new file mode 100644 index 00000000..f01eba89 --- /dev/null +++ b/skills/commandkit-ai/SKILL.md @@ -0,0 +1,58 @@ +--- +name: commandkit-ai +version: 1.2.0 +author: neplextech +emoji: '🤖' +tags: + - commandkit + - ai + - tools + - llm +description: > + Build AI-powered command flows with @commandkit/ai. Use for model + selection, message filtering, schema-backed AI commands, and safe + tool-calling behavior. +--- + +# CommandKit AI Plugin + +## Activation guidance + +Use when implementing natural-language command execution or AI tool +orchestration. + +## Required filesystem expectations + +- plugin registration in `commandkit.config.ts` +- AI runtime config in `src/ai.ts` or `src/ai.js` +- AI-enabled command files in `src/app/commands/**` + +## Execution workflow + +1. Register `ai()` plugin. +2. Configure `configureAI()` in `src/ai.*`. +3. Implement `aiConfig` schema and `ai` command handlers. +4. Add tool registration and robust error handling. +5. Validate trigger filter, permissions, and response safety. + +## Guardrails + +- Never hardcode API keys. +- Treat AI output as untrusted input for sensitive operations. +- Keep tool descriptions explicit and narrow. + +## Reference index + +| Name | Description | +| --------------------------------------- | -------------------------------------------------------------- | +| `references/00-filesystem-structure.md` | File layout and export expectations for AI-enabled projects. | +| `references/01-plugin-setup.md` | Minimal plugin wiring in config. | +| `references/02-configure-ai-model.md` | Model selection, message filters, and runtime option patterns. | +| `references/03-ai-command-schema.md` | Typed schema + AI command implementation pattern. | +| `references/04-custom-tools.md` | Tool creation and safe exposure patterns. | + +## Tool index + +| Name | Description | +| ---------------------------------------- | --------------------------------------------------------------------- | +| `tools/generate-ai-command-template.mjs` | Prints a starter AI command template with schema and handler exports. | diff --git a/skills/commandkit-ai/references/00-filesystem-structure.md b/skills/commandkit-ai/references/00-filesystem-structure.md new file mode 100644 index 00000000..e471b3b9 --- /dev/null +++ b/skills/commandkit-ai/references/00-filesystem-structure.md @@ -0,0 +1,49 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + ai.ts + app/ + commands/ +``` + +## Example + +```txt +project/ + commandkit.config.ts + src/ + ai.ts + app/ + commands/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-ai/references/01-plugin-setup.md b/skills/commandkit-ai/references/01-plugin-setup.md new file mode 100644 index 00000000..af5665e6 --- /dev/null +++ b/skills/commandkit-ai/references/01-plugin-setup.md @@ -0,0 +1,49 @@ +# 01 plugin setup + +## Purpose + +Show minimal plugin registration pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + ai.ts + app/ + commands/ +``` + +## Example + +```ts +import { defineConfig } from 'commandkit'; +import { ai } from '@commandkit/ai'; + +export default defineConfig({ + plugins: [ai()], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-ai/references/02-configure-ai-model.md b/skills/commandkit-ai/references/02-configure-ai-model.md new file mode 100644 index 00000000..aff64bad --- /dev/null +++ b/skills/commandkit-ai/references/02-configure-ai-model.md @@ -0,0 +1,59 @@ +# 02 configure ai model + +## Purpose + +Show model selection and message filter configuration for AI runtime. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + ai.ts + app/ + commands/ +``` + +## Example + +```ts +import { createGoogleGenerativeAI } from '@ai-sdk/google'; +import { configureAI } from '@commandkit/ai'; + +const google = createGoogleGenerativeAI({ + apiKey: process.env.GOOGLE_API_KEY, +}); + +configureAI({ + selectAiModel: async () => ({ + model: google.languageModel('gemini-2.0-flash'), + maxSteps: 5, + temperature: 0.7, + }), + messageFilter: async (_commandkit, message) => + message.mentions.users.has(message.client.user.id), +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-ai/references/03-ai-command-schema.md b/skills/commandkit-ai/references/03-ai-command-schema.md new file mode 100644 index 00000000..658f255d --- /dev/null +++ b/skills/commandkit-ai/references/03-ai-command-schema.md @@ -0,0 +1,58 @@ +# 03 ai command schema + +## Purpose + +Show schema-backed AI command exports to reduce parameter hallucination. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + ai.ts + app/ + commands/ +``` + +## Example + +```ts +import type { AiConfig, AiCommand } from '@commandkit/ai'; +import { z } from 'zod'; + +export const aiConfig: AiConfig = { + inputSchema: z.object({ + username: z.string(), + message: z.string().optional(), + }), +}; + +export const ai: AiCommand = async (ctx) => { + const { username, message } = ctx.ai.params; + await ctx.message.reply(message || `Hello, ${username}!`); + return { username }; +}; +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-ai/references/04-custom-tools.md b/skills/commandkit-ai/references/04-custom-tools.md new file mode 100644 index 00000000..1a6c08f2 --- /dev/null +++ b/skills/commandkit-ai/references/04-custom-tools.md @@ -0,0 +1,65 @@ +# 04 custom tools + +## Purpose + +Show custom AI tool definitions and registration patterns. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + ai.ts + app/ + commands/ +``` + +## Example + +```ts +import { createTool } from '@commandkit/ai'; +import { z } from 'zod'; + +export const getWeather = createTool({ + name: 'getWeather', + description: 'Get weather information', + inputSchema: z.object({ location: z.string() }), + async execute(_ctx, params) { + return { location: params.location, status: 'sunny' }; + }, +}); +``` + +```ts +import { configureAI } from '@commandkit/ai'; + +configureAI({ + selectAiModel: async () => ({ + model: someModel, + tools: { getWeather }, + }), +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-ai/tools/generate-ai-command-template.mjs b/skills/commandkit-ai/tools/generate-ai-command-template.mjs new file mode 100644 index 00000000..fdcd1e8f --- /dev/null +++ b/skills/commandkit-ai/tools/generate-ai-command-template.mjs @@ -0,0 +1,16 @@ +#!/usr/bin/env node + +console.log(`import type { AiConfig, AiCommand } from '@commandkit/ai'; +import { z } from 'zod'; + +export const aiConfig: AiConfig = { + inputSchema: z.object({ + prompt: z.string().describe('User request prompt'), + }), +}; + +export const ai: AiCommand = async (ctx) => { + const { prompt } = ctx.ai.params; + await ctx.message.reply(prompt); + return { ok: true }; +};`); diff --git a/skills/commandkit-analytics/README.md b/skills/commandkit-analytics/README.md new file mode 100644 index 00000000..d2df2ff1 --- /dev/null +++ b/skills/commandkit-analytics/README.md @@ -0,0 +1,21 @@ +# commandkit-analytics skill + +This skill covers analytics integration for CommandKit via PostHog and Umami providers. + +## Use this skill when + +- adding analytics to a bot +- instrumenting command or plugin events +- reducing/no-op telemetry for specific operations + +## Typical inputs + +- analytics provider choice +- event naming/measurement goals +- privacy constraints + +## Expected outputs + +- provider wiring in config +- event instrumentation strategy +- safe payload guidance diff --git a/skills/commandkit-analytics/SKILL.md b/skills/commandkit-analytics/SKILL.md new file mode 100644 index 00000000..3615d95d --- /dev/null +++ b/skills/commandkit-analytics/SKILL.md @@ -0,0 +1,55 @@ +--- +name: commandkit-analytics +version: 1.2.0 +author: neplextech +emoji: '📈' +tags: + - commandkit + - analytics + - posthog + - umami +description: > + Instrument CommandKit bots with @commandkit/analytics. Use for + provider setup, event taxonomy, runtime telemetry controls, and + privacy-aware analytics design. +--- + +# CommandKit Analytics Plugin + +## Activation guidance + +Use for analytics provider setup and event instrumentation strategy. + +## Required filesystem expectations + +- provider plugin registration in `commandkit.config.ts` +- tracking calls in commands/events/middleware where business events + occur + +## Execution workflow + +1. Choose provider (`posthog` or `umami`). +2. Define stable event names and payload fields. +3. Instrument meaningful lifecycle events. +4. Apply selective suppression with `noAnalytics()` where needed. + +## Guardrails + +- Do not collect secrets or unnecessary personal data. +- Keep event schemas stable to preserve reporting quality. + +## Reference index + +| Name | Description | +| --------------------------------------- | ------------------------------------------------------------ | +| `references/00-filesystem-structure.md` | Integration locations and analytics architecture boundaries. | +| `references/01-posthog-setup.md` | PostHog provider setup pattern. | +| `references/02-umami-setup.md` | Umami provider setup pattern. | +| `references/03-track-events.md` | Event tracking conventions and examples. | +| `references/04-no-analytics-scope.md` | Request-level telemetry suppression pattern. | + +## Tool index + +| Name | Description | +| ----- | ------------------------------------------------ | +| `N/A` | This skill currently has no helper tool scripts. | diff --git a/skills/commandkit-analytics/references/00-filesystem-structure.md b/skills/commandkit-analytics/references/00-filesystem-structure.md new file mode 100644 index 00000000..3e8651c2 --- /dev/null +++ b/skills/commandkit-analytics/references/00-filesystem-structure.md @@ -0,0 +1,49 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-analytics/references/01-posthog-setup.md b/skills/commandkit-analytics/references/01-posthog-setup.md new file mode 100644 index 00000000..bc5d5812 --- /dev/null +++ b/skills/commandkit-analytics/references/01-posthog-setup.md @@ -0,0 +1,55 @@ +# 01 posthog setup + +## Purpose + +Show PostHog analytics provider setup. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```ts +import { defineConfig } from 'commandkit'; +import { posthog } from '@commandkit/analytics/posthog'; + +export default defineConfig({ + plugins: [ + posthog({ + posthogOptions: { + apiKey: process.env.POSTHOG_API_KEY, + }, + }), + ], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-analytics/references/02-umami-setup.md b/skills/commandkit-analytics/references/02-umami-setup.md new file mode 100644 index 00000000..f5d23629 --- /dev/null +++ b/skills/commandkit-analytics/references/02-umami-setup.md @@ -0,0 +1,56 @@ +# 02 umami setup + +## Purpose + +Show Umami analytics provider setup. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```ts +import { defineConfig } from 'commandkit'; +import { umami } from '@commandkit/analytics/umami'; + +export default defineConfig({ + plugins: [ + umami({ + umamiOptions: { + hostUrl: process.env.UMAMI_HOST_URL, + websiteId: process.env.UMAMI_WEBSITE_ID, + }, + }), + ], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-analytics/references/03-track-events.md b/skills/commandkit-analytics/references/03-track-events.md new file mode 100644 index 00000000..6864440c --- /dev/null +++ b/skills/commandkit-analytics/references/03-track-events.md @@ -0,0 +1,52 @@ +# 03 track events + +## Purpose + +Show event tracking patterns and payload discipline. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```ts +import { track } from 'commandkit/analytics'; + +await track({ + name: 'command_executed', + data: { + commandName: 'ping', + guildId: interaction.guildId, + }, +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-analytics/references/04-no-analytics-scope.md b/skills/commandkit-analytics/references/04-no-analytics-scope.md new file mode 100644 index 00000000..0326ae4e --- /dev/null +++ b/skills/commandkit-analytics/references/04-no-analytics-scope.md @@ -0,0 +1,52 @@ +# 04 no analytics scope + +## Purpose + +Show per-request telemetry suppression pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```ts +import { noAnalytics } from 'commandkit/analytics'; + +export const chatInput = async (ctx) => { + if (ctx.interaction.user.bot) { + noAnalytics(); + } + + await ctx.interaction.reply('done'); +}; +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-cache/README.md b/skills/commandkit-cache/README.md new file mode 100644 index 00000000..ee84fea2 --- /dev/null +++ b/skills/commandkit-cache/README.md @@ -0,0 +1,22 @@ +# commandkit-cache skill + +Skill for caching architecture and implementation with `@commandkit/cache`. + +## Use this skill when + +- adding cache to expensive data fetches +- setting cache lifetime policies +- implementing tag-based invalidation +- configuring Redis-backed cache provider + +## Typical inputs + +- target function(s) to cache +- freshness requirements +- deployment mode (single instance vs distributed) + +## Expected outputs + +- `'use cache'` integration +- clear `cacheLife` and `cacheTag` decisions +- safe invalidation flow using `revalidateTag` diff --git a/skills/commandkit-cache/SKILL.md b/skills/commandkit-cache/SKILL.md new file mode 100644 index 00000000..92c9a4a3 --- /dev/null +++ b/skills/commandkit-cache/SKILL.md @@ -0,0 +1,58 @@ +--- +name: commandkit-cache +version: 1.2.0 +author: neplextech +emoji: '🗄️' +tags: + - commandkit + - cache + - performance + - redis +description: > + Implement deterministic caching with @commandkit/cache. Use for 'use + cache' directives, cacheTag/cacheLife strategy, revalidateTag + invalidation, and provider setup for memory or Redis deployments. +--- + +# CommandKit Cache Plugin + +## Activation guidance + +Use for read-heavy deterministic workloads and explicit invalidation +design. + +## Required filesystem expectations + +- plugin registration in `commandkit.config.ts` +- cacheable functions in commands/services/helpers +- optional provider bootstrap module for Redis setup + +## Execution workflow + +1. Register `cache()` plugin. +2. Add `'use cache'` to deterministic async functions. +3. Design tags and TTLs with clear resource boundaries. +4. Pair writes with `revalidateTag`. +5. Choose memory vs Redis based on deployment topology. + +## Guardrails + +- Do not cache mutation paths. +- Do not cache sensitive user-specific results without strict key + design. + +## Reference index + +| Name | Description | +| --------------------------------------- | ------------------------------------------------------------ | +| `references/00-filesystem-structure.md` | Cache integration locations and bootstrap placement. | +| `references/01-directive-use-cache.md` | Correct directive usage and deterministic function criteria. | +| `references/02-cachetag-cachelife.md` | Tag strategy, TTL strategy, and invalidation planning. | +| `references/03-revalidate-tag.md` | Mutation-side invalidation patterns. | +| `references/04-provider-setup.md` | Memory/Redis provider setup and topology guidance. | + +## Tool index + +| Name | Description | +| ----- | ------------------------------------------------ | +| `N/A` | This skill currently has no helper tool scripts. | diff --git a/skills/commandkit-cache/references/00-filesystem-structure.md b/skills/commandkit-cache/references/00-filesystem-structure.md new file mode 100644 index 00000000..7396e31c --- /dev/null +++ b/skills/commandkit-cache/references/00-filesystem-structure.md @@ -0,0 +1,49 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + services/ +``` + +## Example + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + services/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-cache/references/01-directive-use-cache.md b/skills/commandkit-cache/references/01-directive-use-cache.md new file mode 100644 index 00000000..c3b303c3 --- /dev/null +++ b/skills/commandkit-cache/references/01-directive-use-cache.md @@ -0,0 +1,54 @@ +# 01 directive use cache + +## Purpose + +Show valid cache directive usage in deterministic functions. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + services/ +``` + +## Example + +```ts +import { cacheLife, cacheTag } from '@commandkit/cache'; + +async function fetchDogs() { + 'use cache'; + + cacheTag('dogs'); + cacheLife('1h'); + + const dogs = await fetch('https://example.com/dogs'); + return dogs.json(); +} +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-cache/references/02-cachetag-cachelife.md b/skills/commandkit-cache/references/02-cachetag-cachelife.md new file mode 100644 index 00000000..cfa5a26e --- /dev/null +++ b/skills/commandkit-cache/references/02-cachetag-cachelife.md @@ -0,0 +1,54 @@ +# 02 cachetag cachelife + +## Purpose + +Explain cache tag taxonomy and TTL strategy. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + services/ +``` + +## Example + +```ts +import { cacheTag, cacheLife } from '@commandkit/cache'; + +async function fetchGuildSettings(guildId: string) { + 'use cache'; + + cacheTag(`guild:${guildId}`); + cacheTag('settings'); + cacheLife('1h'); + + return await db.guilds.findOne(guildId); +} +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-cache/references/03-revalidate-tag.md b/skills/commandkit-cache/references/03-revalidate-tag.md new file mode 100644 index 00000000..b4c5ee30 --- /dev/null +++ b/skills/commandkit-cache/references/03-revalidate-tag.md @@ -0,0 +1,49 @@ +# 03 revalidate tag + +## Purpose + +Show write-path invalidation patterns. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + services/ +``` + +## Example + +```ts +import { revalidateTag } from '@commandkit/cache'; + +async function updateGuildSettings(guildId: string, settings: unknown) { + await db.guilds.update(guildId, settings); + await revalidateTag(`guild:${guildId}`); +} +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-cache/references/04-provider-setup.md b/skills/commandkit-cache/references/04-provider-setup.md new file mode 100644 index 00000000..dd1bb852 --- /dev/null +++ b/skills/commandkit-cache/references/04-provider-setup.md @@ -0,0 +1,53 @@ +# 04 provider setup + +## Purpose + +Show cache provider setup for memory/Redis topologies. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + services/ +``` + +## Example + +```ts +// commandkit.config.ts +import { defineConfig } from 'commandkit'; +import { cache, setCacheProvider } from '@commandkit/cache'; +import { RedisCache } from '@commandkit/cache/providers/redis'; + +setCacheProvider(new RedisCache({ host: 'localhost', port: 6379 })); + +export default defineConfig({ + plugins: [cache()], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-devtools/README.md b/skills/commandkit-devtools/README.md new file mode 100644 index 00000000..bc1598c7 --- /dev/null +++ b/skills/commandkit-devtools/README.md @@ -0,0 +1,21 @@ +# commandkit-devtools skill + +Skill for local development debugging using `@commandkit/devtools`. + +## Use this skill when + +- enabling devtools in a CommandKit bot +- troubleshooting command/event behavior in development +- validating local diagnostics setup + +## Typical inputs + +- local dev environment details +- symptoms/bugs seen during runtime +- current plugin configuration + +## Expected outputs + +- correct plugin wiring +- diagnosis-oriented adjustments +- practical local verification steps diff --git a/skills/commandkit-devtools/SKILL.md b/skills/commandkit-devtools/SKILL.md new file mode 100644 index 00000000..47eee6f4 --- /dev/null +++ b/skills/commandkit-devtools/SKILL.md @@ -0,0 +1,52 @@ +--- +name: commandkit-devtools +version: 1.2.0 +author: neplextech +emoji: '🛠️' +tags: + - commandkit + - devtools + - debugging + - local-development +description: > + Configure and use @commandkit/devtools for local debugging, command + inspection, and runtime diagnostics during development. +--- + +# CommandKit Devtools Plugin + +## Activation guidance + +Use for development-time diagnostics and command/runtime +introspection. + +## Required filesystem expectations + +- plugin setup in `commandkit.config.ts` +- environment-aware plugin loading logic + +## Execution workflow + +1. Enable devtools only for development. +2. Configure port/features as needed. +3. Use dashboard findings to target command/event fixes. + +## Guardrails + +- Never ship devtools enabled in production. +- Keep feature toggles focused to reduce diagnostic noise. + +## Reference index + +| Name | Description | +| --------------------------------------- | -------------------------------------------- | +| `references/00-filesystem-structure.md` | Placement and environment gate expectations. | +| `references/01-plugin-setup.md` | Base plugin wiring. | +| `references/02-config-options.md` | Feature and port configuration patterns. | +| `references/03-dev-only-loading.md` | Development-only loading pattern. | + +## Tool index + +| Name | Description | +| ----- | ------------------------------------------------ | +| `N/A` | This skill currently has no helper tool scripts. | diff --git a/skills/commandkit-devtools/references/00-filesystem-structure.md b/skills/commandkit-devtools/references/00-filesystem-structure.md new file mode 100644 index 00000000..7fb282c6 --- /dev/null +++ b/skills/commandkit-devtools/references/00-filesystem-structure.md @@ -0,0 +1,41 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts +``` + +## Example + +```txt +project/ + commandkit.config.ts +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-devtools/references/01-plugin-setup.md b/skills/commandkit-devtools/references/01-plugin-setup.md new file mode 100644 index 00000000..09197910 --- /dev/null +++ b/skills/commandkit-devtools/references/01-plugin-setup.md @@ -0,0 +1,45 @@ +# 01 plugin setup + +## Purpose + +Show minimal plugin registration pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts +``` + +## Example + +```ts +import { defineConfig } from 'commandkit'; +import { devtools } from '@commandkit/devtools'; + +export default defineConfig({ + plugins: [devtools()], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-devtools/references/02-config-options.md b/skills/commandkit-devtools/references/02-config-options.md new file mode 100644 index 00000000..75ece02b --- /dev/null +++ b/skills/commandkit-devtools/references/02-config-options.md @@ -0,0 +1,55 @@ +# 02 config options + +## Purpose + +Show devtools feature/port configuration patterns. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts +``` + +## Example + +```ts +import { defineConfig } from 'commandkit'; +import { devtools } from '@commandkit/devtools'; + +export default defineConfig({ + plugins: [ + devtools({ + port: 4356, + features: { + commandInspection: true, + performanceMonitoring: true, + debugging: true, + }, + enableLogging: true, + }), + ], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-devtools/references/03-dev-only-loading.md b/skills/commandkit-devtools/references/03-dev-only-loading.md new file mode 100644 index 00000000..0be5c4d1 --- /dev/null +++ b/skills/commandkit-devtools/references/03-dev-only-loading.md @@ -0,0 +1,45 @@ +# 03 dev only loading + +## Purpose + +Show environment-gated devtools loading. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts +``` + +## Example + +```ts +import { defineConfig } from 'commandkit'; +import { devtools } from '@commandkit/devtools'; + +export default defineConfig({ + plugins: [...(process.env.NODE_ENV === 'development' ? [devtools()] : [])], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-i18n/README.md b/skills/commandkit-i18n/README.md new file mode 100644 index 00000000..5a431e56 --- /dev/null +++ b/skills/commandkit-i18n/README.md @@ -0,0 +1,21 @@ +# commandkit-i18n skill + +Skill for localization and translation workflows with `@commandkit/i18n`. + +## Use this skill when + +- localizing command metadata and responses +- implementing locale detection/fallback strategy +- integrating i18next resources in CommandKit + +## Typical inputs + +- target locales +- translation key structure +- desired fallback behavior + +## Expected outputs + +- `i18n()` setup changes +- command localization wiring +- locale-safe response implementation diff --git a/skills/commandkit-i18n/SKILL.md b/skills/commandkit-i18n/SKILL.md new file mode 100644 index 00000000..fc4f76b8 --- /dev/null +++ b/skills/commandkit-i18n/SKILL.md @@ -0,0 +1,58 @@ +--- +name: commandkit-i18n +version: 1.2.0 +author: neplextech +emoji: '🌍' +tags: + - commandkit + - i18n + - localization + - i18next +description: > + Implement localization with @commandkit/i18n and i18next. Use for + locale resources, command metadata translations, and locale-aware + runtime helpers. +--- + +# CommandKit i18n Plugin + +## Activation guidance + +Use for multilingual command metadata and translated runtime +responses. + +## Required filesystem expectations + +- plugin registration in `commandkit.config.ts` +- locale files under `src/app/locales//*.json` +- command/event handlers in `src/app/commands/**` and + `src/app/events/**` + +## Execution workflow + +1. Register `i18n()` plugin. +2. Build locale directory and translation files. +3. Add `$command` keys for metadata localization. +4. Use `ctx.locale()` in commands and `locale()` in events/utilities. +5. Validate missing-key and fallback behavior. + +## Guardrails + +- Keep translation keys stable across locales. +- Ensure all required keys exist in baseline locale. + +## Reference index + +| Name | Description | +| ------------------------------------------------ | --------------------------------------------------------- | +| `references/00-filesystem-structure.md` | Locale folder layout and naming expectations. | +| `references/01-plugin-setup.md` | Plugin setup baseline. | +| `references/02-locales-structure.md` | Locale file placement and organization details. | +| `references/03-command-metadata-localization.md` | `$command` and context menu metadata localization format. | +| `references/04-locale-helpers.md` | Runtime locale helper usage in commands/events. | + +## Tool index + +| Name | Description | +| -------------------------------- | -------------------------------------------------------------------- | +| `tools/generate-locale-file.mjs` | Prints a locale JSON starter template for a command and locale code. | diff --git a/skills/commandkit-i18n/references/00-filesystem-structure.md b/skills/commandkit-i18n/references/00-filesystem-structure.md new file mode 100644 index 00000000..9ef5b925 --- /dev/null +++ b/skills/commandkit-i18n/references/00-filesystem-structure.md @@ -0,0 +1,55 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + locales/ + en-US/ + command.json + commands/ + events/ +``` + +## Example + +```txt +project/ + commandkit.config.ts + src/ + app/ + locales/ + en-US/ + ping.json + commands/ + events/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-i18n/references/01-plugin-setup.md b/skills/commandkit-i18n/references/01-plugin-setup.md new file mode 100644 index 00000000..36fc57d3 --- /dev/null +++ b/skills/commandkit-i18n/references/01-plugin-setup.md @@ -0,0 +1,52 @@ +# 01 plugin setup + +## Purpose + +Show minimal plugin registration pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + locales/ + en-US/ + command.json + commands/ + events/ +``` + +## Example + +```ts +import { defineConfig } from 'commandkit'; +import { i18n } from '@commandkit/i18n'; + +export default defineConfig({ + plugins: [i18n()], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-i18n/references/02-locales-structure.md b/skills/commandkit-i18n/references/02-locales-structure.md new file mode 100644 index 00000000..922f0b8a --- /dev/null +++ b/skills/commandkit-i18n/references/02-locales-structure.md @@ -0,0 +1,55 @@ +# 02 locales structure + +## Purpose + +Define locale file organization for command/event translations. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + locales/ + en-US/ + command.json + commands/ + events/ +``` + +## Example + +```txt +src/ + app/ + locales/ + en-US/ + ping.json + fr/ + ping.json + commands/ + ping.ts +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-i18n/references/03-command-metadata-localization.md b/skills/commandkit-i18n/references/03-command-metadata-localization.md new file mode 100644 index 00000000..63868630 --- /dev/null +++ b/skills/commandkit-i18n/references/03-command-metadata-localization.md @@ -0,0 +1,59 @@ +# 03 command metadata localization + +## Purpose + +Show metadata localization keys and structure. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + locales/ + en-US/ + command.json + commands/ + events/ +``` + +## Example + +```json +{ + "$command": { + "name": "ping", + "description": "Check the bot latency" + }, + "$command:user-ctx": { + "name": "Ping" + }, + "$command:message-ctx": { + "name": "Ping" + }, + "response": "Pong! {{latency}}ms" +} +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-i18n/references/04-locale-helpers.md b/skills/commandkit-i18n/references/04-locale-helpers.md new file mode 100644 index 00000000..ba338024 --- /dev/null +++ b/skills/commandkit-i18n/references/04-locale-helpers.md @@ -0,0 +1,58 @@ +# 04 locale helpers + +## Purpose + +Show locale helpers in command and event contexts. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + locales/ + en-US/ + command.json + commands/ + events/ +``` + +## Example + +```ts +// command context +export const chatInput = async (ctx) => { + const { t } = ctx.locale(); + await ctx.interaction.reply(t('response', { latency: ctx.client.ws.ping })); +}; +``` + +```ts +// event or utility usage +import { locale } from '@commandkit/i18n'; + +const { t } = locale('fr'); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-i18n/tools/generate-locale-file.mjs b/skills/commandkit-i18n/tools/generate-locale-file.mjs new file mode 100644 index 00000000..8b5a11a4 --- /dev/null +++ b/skills/commandkit-i18n/tools/generate-locale-file.mjs @@ -0,0 +1,15 @@ +#!/usr/bin/env node + +const locale = process.argv[2] ?? 'en-US'; +const command = process.argv[3] ?? 'ping'; + +const template = { + $command: { + name: command, + description: `Description for ${command}`, + }, + response: 'Localized response text', +}; + +console.log(`// Save as src/app/locales/${locale}/${command}.json`); +console.log(JSON.stringify(template, null, 2)); diff --git a/skills/commandkit-legacy-migration/README.md b/skills/commandkit-legacy-migration/README.md new file mode 100644 index 00000000..2a5b52c8 --- /dev/null +++ b/skills/commandkit-legacy-migration/README.md @@ -0,0 +1,26 @@ +# commandkit-legacy-migration skill + +Migration-only skill for projects currently using `@commandkit/legacy`. + +## Use this skill when + +- a project already depends on legacy handlers +- you need a controlled migration to modern CommandKit +- you want to deprecate and remove legacy plugin usage + +## Do not use this skill for + +- greenfield projects +- recommending new legacy adoption + +## Typical inputs + +- current legacy file layout +- migration risk tolerance and rollout constraints +- parity requirements + +## Expected outputs + +- phased migration plan +- concrete code updates per phase +- explicit criteria for removing `legacy()` diff --git a/skills/commandkit-legacy-migration/SKILL.md b/skills/commandkit-legacy-migration/SKILL.md new file mode 100644 index 00000000..68ee0b6c --- /dev/null +++ b/skills/commandkit-legacy-migration/SKILL.md @@ -0,0 +1,52 @@ +--- +name: commandkit-legacy-migration +version: 1.2.0 +author: neplextech +emoji: '♻️' +tags: + - commandkit + - legacy + - migration + - deprecation +description: > + Migrate existing projects off @commandkit/legacy to modern + CommandKit patterns. This skill is migration-only and must not + promote new legacy adoption. +--- + +# CommandKit Legacy Migration + +## Activation guidance + +Use only when legacy plugin usage already exists. + +## Required filesystem expectations + +- legacy and modern structures may coexist during phased migration +- target end state uses `src/app/commands/**` and `src/app/events/**` + +## Execution workflow + +1. Detect legacy dependencies and plugin usage. +2. Inventory parity requirements. +3. Migrate incrementally by domain/feature slices. +4. Remove `legacy()` only after parity validation. + +## Guardrails + +- Never recommend new legacy adoption. +- Keep migration commits small and verifiable. + +## Reference index + +| Name | Description | +| ------------------------------------------ | ------------------------------------------------------- | +| `references/00-filesystem-structure.md` | Coexistence strategy and target modern structure. | +| `references/01-legacy-plugin-detection.md` | How to identify legacy plugin and handler usage points. | +| `references/02-migration-plan-template.md` | Stepwise migration plan template with safety checks. | + +## Tool index + +| Name | Description | +| ----- | ------------------------------------------------ | +| `N/A` | This skill currently has no helper tool scripts. | diff --git a/skills/commandkit-legacy-migration/references/00-filesystem-structure.md b/skills/commandkit-legacy-migration/references/00-filesystem-structure.md new file mode 100644 index 00000000..3e8651c2 --- /dev/null +++ b/skills/commandkit-legacy-migration/references/00-filesystem-structure.md @@ -0,0 +1,49 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-legacy-migration/references/01-legacy-plugin-detection.md b/skills/commandkit-legacy-migration/references/01-legacy-plugin-detection.md new file mode 100644 index 00000000..ea3632be --- /dev/null +++ b/skills/commandkit-legacy-migration/references/01-legacy-plugin-detection.md @@ -0,0 +1,48 @@ +# 01 legacy plugin detection + +## Purpose + +Identify legacy plugin usage and migration entrypoints. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```ts +import { legacy } from '@commandkit/legacy'; + +export default defineConfig({ + plugins: [legacy()], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-legacy-migration/references/02-migration-plan-template.md b/skills/commandkit-legacy-migration/references/02-migration-plan-template.md new file mode 100644 index 00000000..3e2af566 --- /dev/null +++ b/skills/commandkit-legacy-migration/references/02-migration-plan-template.md @@ -0,0 +1,44 @@ +# 02 migration plan template + +## Purpose + +Provide a phased migration template with parity checks. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```txt +Follow the patterns in this reference and adapt names/options to project context. +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-plugin-development/README.md b/skills/commandkit-plugin-development/README.md new file mode 100644 index 00000000..6242971d --- /dev/null +++ b/skills/commandkit-plugin-development/README.md @@ -0,0 +1,11 @@ +# commandkit-plugin-development skill + +Self-contained skill for creating CommandKit runtime and compiler plugins. + +Use this skill when: +- implementing `RuntimePlugin` hooks +- implementing `CompilerPlugin` transforms +- extending `commandkit create` templates +- wiring `rolldownPlugins` for compile-time customization + +The skill includes detailed references and template generator tools for both plugin classes. diff --git a/skills/commandkit-plugin-development/SKILL.md b/skills/commandkit-plugin-development/SKILL.md new file mode 100644 index 00000000..7f291f36 --- /dev/null +++ b/skills/commandkit-plugin-development/SKILL.md @@ -0,0 +1,63 @@ +--- +name: commandkit-plugin-development +version: 1.0.0 +author: neplextech +emoji: '🧩' +tags: + - commandkit + - plugins + - runtime-plugin + - compiler-plugin + - rolldown +description: > + Create CommandKit plugins for runtime and compiler extension points. + Use when implementing RuntimePlugin hooks, CompilerPlugin + transforms, template registration, or rolldownPlugins-based compiler + customization. +--- + +# CommandKit Plugin Development + +## Activation guidance + +Use when building custom plugins that modify CommandKit runtime +behavior, command registration flow, or source compilation. + +## Required filesystem expectations + +- plugin source files in project plugin directory (for example + `src/plugins/**`) +- plugin wiring in `commandkit.config.ts` +- optional template output targets under application source tree + +## Execution workflow + +1. Decide plugin type: runtime vs compiler. +2. Implement focused plugin class with explicit hook usage. +3. Register plugin in config and validate lifecycle behavior. +4. Add logging/tests for hook behavior and failure modes. + +## Guardrails + +- Keep plugin scope narrow and explicit. +- Avoid heavy side effects in hot hooks. +- For compiler plugins, preserve code correctness and source maps when + transforming. + +## Reference index + +| Name | Description | +| -------------------------------------------- | ---------------------------------------------------------------------------- | +| `references/00-filesystem-structure.md` | Plugin folder layout and config wiring expectations. | +| `references/01-runtime-plugin-basics.md` | RuntimePlugin class setup and minimal lifecycle hook usage. | +| `references/02-runtime-hooks-reference.md` | Practical mapping of major runtime hooks and when to use each. | +| `references/03-compiler-plugin-transform.md` | CompilerPlugin transform pipeline and safe transform patterns. | +| `references/04-template-registration.md` | Registering/unregistering `commandkit create` templates in compiler plugins. | +| `references/05-rolldown-plugins.md` | Using `rolldownPlugins` in config for compiler-time extension. | + +## Tool index + +| Name | Description | +| --------------------------------------------- | ----------------------------------------------------------------------------- | +| `tools/generate-runtime-plugin-template.mjs` | Prints a minimal RuntimePlugin template with typed hook signatures. | +| `tools/generate-compiler-plugin-template.mjs` | Prints a minimal CompilerPlugin template including transform method skeleton. | diff --git a/skills/commandkit-plugin-development/references/00-filesystem-structure.md b/skills/commandkit-plugin-development/references/00-filesystem-structure.md new file mode 100644 index 00000000..340a1b03 --- /dev/null +++ b/skills/commandkit-plugin-development/references/00-filesystem-structure.md @@ -0,0 +1,63 @@ +# 00 filesystem structure + +## Purpose + +Define a maintainable plugin project layout for runtime and compiler +plugin development. + +## When to use + +Use when creating plugin source folders, deciding where to register +plugins, or structuring template outputs. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + plugins/ + my-runtime-plugin.ts + my-compiler-plugin.ts + app/ + commands/ + events/ +``` + +## Example + +```ts +// commandkit.config.ts +import { defineConfig } from 'commandkit'; + +export default defineConfig({ + plugins: [ + // runtime plugin instances or plugin wrappers + ], + rolldownPlugins: [ + // optional compiler-time rolldown plugins + ], +}); +``` + +## Important details + +- Keep plugin classes in dedicated plugin directories to avoid mixing + with app command logic. +- Wire plugins centrally in config for easier auditability. +- Compiler plugin template generation should target valid app source + paths. + +## Best practices + +- Keep one plugin class per file. +- Name plugins clearly by behavior (for example + `logging-runtime-plugin`). +- Keep plugin setup deterministic and side effects explicit. + +## Common mistakes + +- Spreading plugin registration across multiple unrelated startup + files. +- Mixing runtime and compiler concerns in a single class. +- Generating templates into non-discovered directories. diff --git a/skills/commandkit-plugin-development/references/01-runtime-plugin-basics.md b/skills/commandkit-plugin-development/references/01-runtime-plugin-basics.md new file mode 100644 index 00000000..0b955480 --- /dev/null +++ b/skills/commandkit-plugin-development/references/01-runtime-plugin-basics.md @@ -0,0 +1,51 @@ +# 01 runtime plugin basics + +## Purpose + +Provide a baseline RuntimePlugin implementation and registration +pattern. + +## When to use + +Use when adding behavior around command/event lifecycle, registration +flow, interaction handling, or post-command telemetry. + +## Filesystem + +```txt +src/ + plugins/ + my-runtime-plugin.ts +commandkit.config.ts +``` + +## Example + +```ts +import { type CommandKitPluginRuntime, RuntimePlugin } from 'commandkit'; + +export class MyRuntimePlugin extends RuntimePlugin { + async onAfterClientLogin(ctx: CommandKitPluginRuntime): Promise { + console.log(`Bot logged in as ${ctx.client.user?.tag}`); + } +} +``` + +## Important details + +- Runtime plugins extend `RuntimePlugin`. +- Hooks receive `CommandKitPluginRuntime` and can access + client/commands/events context. +- Keep hook code non-blocking where possible. + +## Best practices + +- Start with one hook, then add only hooks you truly need. +- Add try/catch around external I/O in hooks. +- Keep plugin responsibilities focused. + +## Common mistakes + +- Implementing many hooks without clear need. +- Throwing uncaught errors from hot hooks. +- Embedding unrelated business logic inside plugin hooks. diff --git a/skills/commandkit-plugin-development/references/02-runtime-hooks-reference.md b/skills/commandkit-plugin-development/references/02-runtime-hooks-reference.md new file mode 100644 index 00000000..bb80de08 --- /dev/null +++ b/skills/commandkit-plugin-development/references/02-runtime-hooks-reference.md @@ -0,0 +1,65 @@ +# 02 runtime hooks reference + +## Purpose + +Summarize major runtime hooks and practical usage boundaries for safe +plugin behavior. + +## When to use + +Use when deciding where to place plugin logic in lifecycle, routing, +command registration, and interaction execution stages. + +## Filesystem + +```txt +src/ + plugins/ + runtime-hooks-plugin.ts +``` + +## Example + +```ts +import { + RuntimePlugin, + type CommandKitPluginRuntime, + type CommandBuilderLike, +} from 'commandkit'; + +export class HooksPlugin extends RuntimePlugin { + async onBeforeCommandsLoad(_ctx: CommandKitPluginRuntime): Promise {} + + async onAfterCommandsLoad(ctx: CommandKitPluginRuntime): Promise { + console.log(`Loaded ${ctx.commands.size} commands`); + } + + async prepareCommand( + _ctx: CommandKitPluginRuntime, + command: CommandBuilderLike, + ): Promise { + return command; + } +} +``` + +## Important details + +- Initialization hooks: before/after commands/events/client login. +- Router hooks: commands router init and events router init. +- Registration hooks: `prepareCommand` and pre-register command hooks. +- Execution hooks: interaction/message pre-hooks, `executeCommand`, + `onAfterCommand`. + +## Best practices + +- Keep `executeCommand` behavior explicit: return whether execution + was handled. +- Prefer lightweight hooks for high-frequency paths. +- Log enough metadata for debugging without noisy spam. + +## Common mistakes + +- Returning wrong control-flow values from `executeCommand`. +- Mutating command metadata without deterministic rules. +- Performing expensive work in pre-interaction hooks. diff --git a/skills/commandkit-plugin-development/references/03-compiler-plugin-transform.md b/skills/commandkit-plugin-development/references/03-compiler-plugin-transform.md new file mode 100644 index 00000000..c675a36f --- /dev/null +++ b/skills/commandkit-plugin-development/references/03-compiler-plugin-transform.md @@ -0,0 +1,71 @@ +# 03 compiler plugin transform + +## Purpose + +Show how to build compiler plugins that transform source code safely. + +## When to use + +Use when implementing directive transforms, compile-time rewrites, or +custom compile behavior. + +## Filesystem + +```txt +src/ + plugins/ + my-compiler-plugin.ts +``` + +## Example + +```ts +import { + type CompilerPluginRuntime, + CompilerPlugin, + MaybeFalsey, + PluginTransformParameters, + TransformedResult, +} from 'commandkit'; + +export class MyCompilerPlugin extends CompilerPlugin { + public readonly name = 'my-compiler-plugin'; + + public async activate(_ctx: CompilerPluginRuntime): Promise {} + + public async deactivate(_ctx: CompilerPluginRuntime): Promise {} + + public async transform( + params: PluginTransformParameters, + ): Promise> { + const transformed = params.contents.replace( + /console\.log/g, + 'console.warn', + ); + + return { + code: transformed, + map: null, + }; + } +} +``` + +## Important details + +- Compiler plugins extend `CompilerPlugin` and implement `transform`. +- Return transformed code and optional source map. +- Activation/deactivation hooks are available for setup/cleanup. + +## Best practices + +- Keep transforms deterministic and easy to reason about. +- Preserve source-map quality when doing non-trivial rewrites. +- Scope transforms by file/path patterns to avoid accidental global + rewrites. + +## Common mistakes + +- Rewriting code without preserving semantics. +- Applying broad regex transforms across all files unintentionally. +- Ignoring source maps for complex transformations. diff --git a/skills/commandkit-plugin-development/references/04-template-registration.md b/skills/commandkit-plugin-development/references/04-template-registration.md new file mode 100644 index 00000000..379934a6 --- /dev/null +++ b/skills/commandkit-plugin-development/references/04-template-registration.md @@ -0,0 +1,62 @@ +# 04 template registration + +## Purpose + +Show how compiler plugins can extend `commandkit create` with custom +templates. + +## When to use + +Use when your plugin needs to scaffold new file types or override +default templates. + +## Filesystem + +```txt +src/ + plugins/ + templates-plugin.ts +``` + +## Example + +```ts +import { CompilerPlugin, type CompilerPluginRuntime } from 'commandkit'; +import { writeFile } from 'node:fs/promises'; +import { join } from 'node:path'; + +export class TemplatesPlugin extends CompilerPlugin { + public readonly name = 'templates-plugin'; + + public async activate(ctx: CompilerPluginRuntime): Promise { + ctx.registerTemplate('event', async (args: string[]) => { + const [name, targetPath] = args; + const file = `export default async function on${name[0].toUpperCase() + name.slice(1)}() {\n console.log('${name}');\n}`; + await writeFile(join(targetPath, 'event.ts'), file); + }); + } + + public async deactivate(ctx: CompilerPluginRuntime): Promise { + ctx.unregisterTemplate('event'); + } +} +``` + +## Important details + +- `registerTemplate` must be called in `activate`. +- `unregisterTemplate` must be called in `deactivate`. +- Templates can intentionally override defaults by reusing template + names. + +## Best practices + +- Validate template args before writing files. +- Keep generated output minimal and convention-aligned. +- Add cleanup logic to avoid stale template registrations. + +## Common mistakes + +- Registering templates outside lifecycle hooks. +- Not unregistering templates on plugin deactivation. +- Writing templates to invalid paths. diff --git a/skills/commandkit-plugin-development/references/05-rolldown-plugins.md b/skills/commandkit-plugin-development/references/05-rolldown-plugins.md new file mode 100644 index 00000000..e190fd67 --- /dev/null +++ b/skills/commandkit-plugin-development/references/05-rolldown-plugins.md @@ -0,0 +1,51 @@ +# 05 rolldown plugins + +## Purpose + +Show how to integrate rolldown plugins through CommandKit config for +compiler-time extension. + +## When to use + +Use when you already have a rolldown plugin or need bundler-level +compile customization. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ +``` + +## Example + +```ts +import { defineConfig } from 'commandkit'; +import { someRolldownPlugin } from 'some-rolldown-plugin'; + +export default defineConfig({ + rolldownPlugins: [someRolldownPlugin()], +}); +``` + +## Important details + +- `rolldownPlugins` runs in compile pipeline, not runtime command + execution. +- Keep plugin ordering intentional if using multiple rolldown plugins. +- Confirm plugin compatibility with your module format and target + runtime. + +## Best practices + +- Start with one plugin and verify build output before stacking + plugins. +- Keep build-specific behavior isolated from runtime logic. +- Add CI build verification for plugin-based transformations. + +## Common mistakes + +- Expecting rolldown plugin behavior to affect runtime-only hooks. +- Adding incompatible plugins without testing output. +- Ignoring plugin ordering side effects. diff --git a/skills/commandkit-plugin-development/tools/generate-compiler-plugin-template.mjs b/skills/commandkit-plugin-development/tools/generate-compiler-plugin-template.mjs new file mode 100644 index 00000000..7daa3ed5 --- /dev/null +++ b/skills/commandkit-plugin-development/tools/generate-compiler-plugin-template.mjs @@ -0,0 +1,26 @@ +#!/usr/bin/env node + +console.log(`import { + CompilerPlugin, + type CompilerPluginRuntime, + type PluginTransformParameters, + type MaybeFalsey, + type TransformedResult, +} from 'commandkit'; + +export class MyCompilerPlugin extends CompilerPlugin { + public readonly name = 'my-compiler-plugin'; + + public async activate(_ctx: CompilerPluginRuntime): Promise {} + + public async deactivate(_ctx: CompilerPluginRuntime): Promise {} + + public async transform( + params: PluginTransformParameters, + ): Promise> { + return { + code: params.contents, + map: null, + }; + } +}`); diff --git a/skills/commandkit-plugin-development/tools/generate-runtime-plugin-template.mjs b/skills/commandkit-plugin-development/tools/generate-runtime-plugin-template.mjs new file mode 100644 index 00000000..2f72dada --- /dev/null +++ b/skills/commandkit-plugin-development/tools/generate-runtime-plugin-template.mjs @@ -0,0 +1,9 @@ +#!/usr/bin/env node + +console.log(`import { RuntimePlugin, type CommandKitPluginRuntime } from 'commandkit'; + +export class MyRuntimePlugin extends RuntimePlugin { + async onAfterClientLogin(ctx: CommandKitPluginRuntime): Promise { + console.log(\`Logged in as \${ctx.client.user?.tag}\`); + } +}`); diff --git a/skills/commandkit-queue/README.md b/skills/commandkit-queue/README.md new file mode 100644 index 00000000..8a5f76ff --- /dev/null +++ b/skills/commandkit-queue/README.md @@ -0,0 +1,21 @@ +# commandkit-queue skill + +Skill for queue architecture with `@commandkit/queue`. + +## Use this skill when + +- implementing publish/subscribe bot workflows +- configuring queue drivers (e.g., Redis-backed) +- decoupling message processing from command execution + +## Typical inputs + +- producer/consumer flow +- transport/driver constraints +- delivery reliability requirements + +## Expected outputs + +- driver setup +- channel/message contract strategy +- robust send/receive integration diff --git a/skills/commandkit-queue/SKILL.md b/skills/commandkit-queue/SKILL.md new file mode 100644 index 00000000..3dd371b9 --- /dev/null +++ b/skills/commandkit-queue/SKILL.md @@ -0,0 +1,55 @@ +--- +name: commandkit-queue +version: 1.2.0 +author: neplextech +emoji: '📬' +tags: + - commandkit + - queue + - messaging + - redis +description: > + Build queue-based messaging workflows with @commandkit/queue. Use + for driver bootstrap, topic/payload contracts, send/receive + patterns, and resilient consumer handling. +--- + +# CommandKit Queue Plugin + +## Activation guidance + +Use for decoupled async communication between bot components/services. + +## Required filesystem expectations + +- queue bootstrap module (for example `src/bootstrap/queue.ts`) +- producers/consumers in command/event/service layers +- shared payload type module for typed contracts + +## Execution workflow + +1. Register queue driver once at startup. +2. Define topic naming and payload contracts. +3. Implement send/receive handlers with error strategy. +4. Ensure idempotent consumption behavior. + +## Guardrails + +- Avoid unstructured payloads. +- Avoid side-effect-heavy consumers without retry/idempotency + planning. + +## Reference index + +| Name | Description | +| --------------------------------------- | ---------------------------------------------------------- | +| `references/00-filesystem-structure.md` | Queue bootstrap placement and typed contract organization. | +| `references/01-driver-setup.md` | Driver setup with Redis PubSub integration. | +| `references/02-send-and-receive.md` | Publish/subscribe usage patterns. | +| `references/03-typed-events.md` | Typed message contract approach. | + +## Tool index + +| Name | Description | +| ----- | ------------------------------------------------ | +| `N/A` | This skill currently has no helper tool scripts. | diff --git a/skills/commandkit-queue/references/00-filesystem-structure.md b/skills/commandkit-queue/references/00-filesystem-structure.md new file mode 100644 index 00000000..344fa139 --- /dev/null +++ b/skills/commandkit-queue/references/00-filesystem-structure.md @@ -0,0 +1,51 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + src/ + bootstrap/ + queue.ts + app/ + commands/ + events/ +``` + +## Example + +```txt +project/ + src/ + bootstrap/ + queue.ts + app/ + commands/ + events/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-queue/references/01-driver-setup.md b/skills/commandkit-queue/references/01-driver-setup.md new file mode 100644 index 00000000..d1259804 --- /dev/null +++ b/skills/commandkit-queue/references/01-driver-setup.md @@ -0,0 +1,52 @@ +# 01 driver setup + +## Purpose + +Show queue driver bootstrap and one-time initialization. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + src/ + bootstrap/ + queue.ts + app/ + commands/ + events/ +``` + +## Example + +```ts +import Redis from 'ioredis'; +import { PubSubRedisBroker } from '@discordjs/brokers'; +import { RedisPubSubDriver } from '@commandkit/queue/discordjs'; +import { setDriver } from '@commandkit/queue'; + +const broker = new PubSubRedisBroker(new Redis()); +const driver = new RedisPubSubDriver(broker); +setDriver(driver); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-queue/references/02-send-and-receive.md b/skills/commandkit-queue/references/02-send-and-receive.md new file mode 100644 index 00000000..2a84f064 --- /dev/null +++ b/skills/commandkit-queue/references/02-send-and-receive.md @@ -0,0 +1,51 @@ +# 02 send and receive + +## Purpose + +Show publish/subscribe message handling patterns. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + src/ + bootstrap/ + queue.ts + app/ + commands/ + events/ +``` + +## Example + +```ts +import { send, receive } from '@commandkit/queue'; + +await send('user-events', { userId: '123', action: 'login' }); + +await receive('user-events', async (message) => { + await processUserEvent(message); +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-queue/references/03-typed-events.md b/skills/commandkit-queue/references/03-typed-events.md new file mode 100644 index 00000000..a639c37f --- /dev/null +++ b/skills/commandkit-queue/references/03-typed-events.md @@ -0,0 +1,54 @@ +# 03 typed events + +## Purpose + +Show typed queue contract patterns. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + src/ + bootstrap/ + queue.ts + app/ + commands/ + events/ +``` + +## Example + +```ts +interface QueueEvents { + 'user-updates': { + userId: string; + action: 'login' | 'logout' | 'register'; + timestamp: number; + }; +} + +const driver = new RedisPubSubDriver(broker); +setDriver(driver); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-ratelimit/README.md b/skills/commandkit-ratelimit/README.md new file mode 100644 index 00000000..7f253298 --- /dev/null +++ b/skills/commandkit-ratelimit/README.md @@ -0,0 +1,21 @@ +# commandkit-ratelimit skill + +Skill for designing and implementing command rate limiting with `@commandkit/ratelimit`. + +## Use this skill when + +- adding anti-abuse protections +- defining scoped limits and windows +- switching to Redis/fallback storage for shared deployments + +## Typical inputs + +- command usage profile +- acceptable burst/sustained behavior +- storage and deployment topology + +## Expected outputs + +- ratelimit configuration +- directive usage in command handlers +- clear violation behavior and user messaging diff --git a/skills/commandkit-ratelimit/SKILL.md b/skills/commandkit-ratelimit/SKILL.md new file mode 100644 index 00000000..f6148350 --- /dev/null +++ b/skills/commandkit-ratelimit/SKILL.md @@ -0,0 +1,58 @@ +--- +name: commandkit-ratelimit +version: 1.2.0 +author: neplextech +emoji: '🚦' +tags: + - commandkit + - ratelimit + - abuse-prevention + - redis +description: > + Configure advanced abuse protection with @commandkit/ratelimit. Use + for runtime defaults, command-level policy, directive usage, storage + strategy, and user-facing cooldown behavior. +--- + +# CommandKit Ratelimit Plugin + +## Activation guidance + +Use when protecting commands from abuse while keeping user UX +predictable. + +## Required filesystem expectations + +- plugin registration in `commandkit.config.ts` +- runtime config bootstrap in `ratelimit.ts` or `ratelimit.js` +- optional per-command metadata in command files + +## Execution workflow + +1. Define runtime defaults with `configureRatelimit`. +2. Register plugin in config. +3. Apply command-level overrides or directive-based limits. +4. Configure memory/redis/fallback storage based on deployment. +5. Validate limited responses and retry timing. + +## Guardrails + +- Balance burst and sustained limits. +- Avoid policy that blocks legitimate normal usage. + +## Reference index + +| Name | Description | +| --------------------------------------------- | --------------------------------------------------- | +| `references/00-filesystem-structure.md` | Required ratelimit bootstrap/config file placement. | +| `references/01-runtime-config.md` | Runtime defaults and initialization pattern. | +| `references/02-plugin-setup.md` | Plugin wiring and startup ordering expectations. | +| `references/03-command-metadata-ratelimit.md` | Command-level metadata policy examples. | +| `references/04-use-ratelimit-directive.md` | Function directive usage and error handling. | +| `references/05-storage-options.md` | Memory/Redis storage strategy and deployment fit. | + +## Tool index + +| Name | Description | +| ------------------------------------- | ----------------------------------------------------------------- | +| `tools/generate-ratelimit-config.mjs` | Prints a baseline `configureRatelimit()` runtime config template. | diff --git a/skills/commandkit-ratelimit/references/00-filesystem-structure.md b/skills/commandkit-ratelimit/references/00-filesystem-structure.md new file mode 100644 index 00000000..a47bb24f --- /dev/null +++ b/skills/commandkit-ratelimit/references/00-filesystem-structure.md @@ -0,0 +1,49 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts + ratelimit.ts + src/ + app/ + commands/ +``` + +## Example + +```txt +project/ + commandkit.config.ts + ratelimit.ts + src/ + app/ + commands/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-ratelimit/references/01-runtime-config.md b/skills/commandkit-ratelimit/references/01-runtime-config.md new file mode 100644 index 00000000..cdc5812d --- /dev/null +++ b/skills/commandkit-ratelimit/references/01-runtime-config.md @@ -0,0 +1,53 @@ +# 01 runtime config + +## Purpose + +Show ratelimit runtime bootstrap config pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + ratelimit.ts + src/ + app/ + commands/ +``` + +## Example + +```ts +import { configureRatelimit } from '@commandkit/ratelimit'; + +configureRatelimit({ + defaultLimiter: { + maxRequests: 5, + interval: '1m', + scope: 'user', + algorithm: 'fixed-window', + }, +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-ratelimit/references/02-plugin-setup.md b/skills/commandkit-ratelimit/references/02-plugin-setup.md new file mode 100644 index 00000000..d8a57837 --- /dev/null +++ b/skills/commandkit-ratelimit/references/02-plugin-setup.md @@ -0,0 +1,49 @@ +# 02 plugin setup + +## Purpose + +Show plugin registration and startup ordering expectations. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + ratelimit.ts + src/ + app/ + commands/ +``` + +## Example + +```ts +import { defineConfig } from 'commandkit'; +import { ratelimit } from '@commandkit/ratelimit'; + +export default defineConfig({ + plugins: [ratelimit()], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-ratelimit/references/03-command-metadata-ratelimit.md b/skills/commandkit-ratelimit/references/03-command-metadata-ratelimit.md new file mode 100644 index 00000000..969cee23 --- /dev/null +++ b/skills/commandkit-ratelimit/references/03-command-metadata-ratelimit.md @@ -0,0 +1,51 @@ +# 03 command metadata ratelimit + +## Purpose + +Show per-command policy overrides through metadata. + +## When to use + +Use when specific commands need tighter or looser limits than global defaults. + +## Filesystem + +```txt +project/ + commandkit.config.ts + ratelimit.ts + src/ + app/ + commands/ +``` + +## Example + +```ts +export const metadata = { + ratelimit: { + maxRequests: 3, + interval: '10s', + scope: 'user', + algorithm: 'sliding-window', + }, +}; +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-ratelimit/references/04-use-ratelimit-directive.md b/skills/commandkit-ratelimit/references/04-use-ratelimit-directive.md new file mode 100644 index 00000000..c8944408 --- /dev/null +++ b/skills/commandkit-ratelimit/references/04-use-ratelimit-directive.md @@ -0,0 +1,57 @@ +# 04 use ratelimit directive + +## Purpose + +Show function-level directive usage and error handling. + +## When to use + +Use when throttling a hot async function outside command metadata policy. + +## Filesystem + +```txt +project/ + commandkit.config.ts + ratelimit.ts + src/ + app/ + commands/ +``` + +## Example + +```ts +import { RateLimitError } from '@commandkit/ratelimit'; + +const heavy = async () => { + 'use ratelimit'; + return 'ok'; +}; + +try { + await heavy(); +} catch (error) { + if (error instanceof RateLimitError) { + console.log(error.result.retryAfter); + } +} +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-ratelimit/references/05-storage-options.md b/skills/commandkit-ratelimit/references/05-storage-options.md new file mode 100644 index 00000000..e72ab6a6 --- /dev/null +++ b/skills/commandkit-ratelimit/references/05-storage-options.md @@ -0,0 +1,58 @@ +# 05 storage options + +## Purpose + +Show storage strategy tradeoffs and setup snippets. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + ratelimit.ts + src/ + app/ + commands/ +``` + +## Example + +```ts +import { + MemoryRateLimitStorage, + setRateLimitStorage, +} from '@commandkit/ratelimit'; + +setRateLimitStorage(new MemoryRateLimitStorage()); +``` + +```ts +import { RedisRateLimitStorage } from '@commandkit/ratelimit/redis'; +import { setRateLimitStorage } from '@commandkit/ratelimit'; + +setRateLimitStorage( + new RedisRateLimitStorage({ host: 'localhost', port: 6379 }), +); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-ratelimit/tools/generate-ratelimit-config.mjs b/skills/commandkit-ratelimit/tools/generate-ratelimit-config.mjs new file mode 100644 index 00000000..7b7ec2fe --- /dev/null +++ b/skills/commandkit-ratelimit/tools/generate-ratelimit-config.mjs @@ -0,0 +1,12 @@ +#!/usr/bin/env node + +console.log(`import { configureRatelimit } from '@commandkit/ratelimit'; + +configureRatelimit({ + defaultLimiter: { + maxRequests: 5, + interval: '1m', + scope: 'user', + algorithm: 'fixed-window', + }, +});`); diff --git a/skills/commandkit-redis/README.md b/skills/commandkit-redis/README.md new file mode 100644 index 00000000..cb2ce666 --- /dev/null +++ b/skills/commandkit-redis/README.md @@ -0,0 +1,21 @@ +# commandkit-redis skill + +Skill for Redis-backed distributed infrastructure in CommandKit ecosystems. + +## Use this skill when + +- scaling beyond a single process +- sharing cache/locks/rate-limit state across instances +- integrating Redis providers with CommandKit plugins/utilities + +## Typical inputs + +- deployment topology +- required shared capabilities (cache, limits, locks) +- reliability constraints + +## Expected outputs + +- Redis integration wiring +- provider/storage selection guidance +- operational guardrails for distributed behavior diff --git a/skills/commandkit-redis/SKILL.md b/skills/commandkit-redis/SKILL.md new file mode 100644 index 00000000..61ae6cde --- /dev/null +++ b/skills/commandkit-redis/SKILL.md @@ -0,0 +1,53 @@ +--- +name: commandkit-redis +version: 1.2.0 +author: neplextech +emoji: '🧠' +tags: + - commandkit + - redis + - cache + - distributed-systems +description: > + Add Redis-backed shared infrastructure with @commandkit/redis for + cache, mutex, semaphore, and distributed state patterns. +--- + +# CommandKit Redis Integrations + +## Activation guidance + +Use for multi-instance or distributed coordination scenarios. + +## Required filesystem expectations + +- central Redis bootstrap module (for example + `src/bootstrap/redis.ts`) +- plugin/provider wiring in startup or config layer + +## Execution workflow + +1. Initialize Redis client with env-based config. +2. Wire cache provider and/or synchronization storages. +3. Validate behavior across multiple runtime instances. + +## Guardrails + +- Keep credentials out of source control. +- Keep key naming/TTL conventions explicit and documented. + +## Reference index + +| Name | Description | +| ------------------------------------------ | ------------------------------------------------------------- | +| `references/00-filesystem-structure.md` | Redis bootstrap and integration layout strategy. | +| `references/01-plugin-setup.md` | Plugin-based Redis cache integration. | +| `references/02-manual-cache-provider.md` | Manual cache provider wiring with custom Redis client. | +| `references/03-redis-mutex-storage.md` | Distributed lock patterns with Redis mutex storage. | +| `references/04-redis-semaphore-storage.md` | Distributed concurrency control with Redis semaphore storage. | + +## Tool index + +| Name | Description | +| ----- | ------------------------------------------------ | +| `N/A` | This skill currently has no helper tool scripts. | diff --git a/skills/commandkit-redis/references/00-filesystem-structure.md b/skills/commandkit-redis/references/00-filesystem-structure.md new file mode 100644 index 00000000..22fb5558 --- /dev/null +++ b/skills/commandkit-redis/references/00-filesystem-structure.md @@ -0,0 +1,47 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + redis.ts +``` + +## Example + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + redis.ts +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-redis/references/01-plugin-setup.md b/skills/commandkit-redis/references/01-plugin-setup.md new file mode 100644 index 00000000..f178c50c --- /dev/null +++ b/skills/commandkit-redis/references/01-plugin-setup.md @@ -0,0 +1,48 @@ +# 01 plugin setup + +## Purpose + +Show minimal plugin registration pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + redis.ts +``` + +## Example + +```ts +import { defineConfig } from 'commandkit'; +import { redis } from '@commandkit/redis'; + +export default defineConfig({ + plugins: [redis()], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-redis/references/02-manual-cache-provider.md b/skills/commandkit-redis/references/02-manual-cache-provider.md new file mode 100644 index 00000000..10545db4 --- /dev/null +++ b/skills/commandkit-redis/references/02-manual-cache-provider.md @@ -0,0 +1,48 @@ +# 02 manual cache provider + +## Purpose + +Show manual Redis provider wiring for custom clients. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + redis.ts +``` + +## Example + +```ts +import { setCacheProvider } from '@commandkit/cache'; +import { RedisCacheProvider } from '@commandkit/redis'; +import { Redis } from 'ioredis'; + +const redis = new Redis(); +setCacheProvider(new RedisCacheProvider(redis)); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-redis/references/03-redis-mutex-storage.md b/skills/commandkit-redis/references/03-redis-mutex-storage.md new file mode 100644 index 00000000..aa59d659 --- /dev/null +++ b/skills/commandkit-redis/references/03-redis-mutex-storage.md @@ -0,0 +1,55 @@ +# 03 redis mutex storage + +## Purpose + +Show distributed mutex integration pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + redis.ts +``` + +## Example + +```ts +import { createMutex } from 'commandkit/mutex'; +import { RedisMutexStorage } from '@commandkit/redis'; +import { Redis } from 'ioredis'; + +const redis = new Redis(); +const mutex = createMutex({ + timeout: 30000, + storage: new RedisMutexStorage(redis), +}); + +await mutex.withLock('shared-resource', async () => { + await updateSharedResource(); +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-redis/references/04-redis-semaphore-storage.md b/skills/commandkit-redis/references/04-redis-semaphore-storage.md new file mode 100644 index 00000000..29cc4831 --- /dev/null +++ b/skills/commandkit-redis/references/04-redis-semaphore-storage.md @@ -0,0 +1,56 @@ +# 04 redis semaphore storage + +## Purpose + +Show distributed semaphore integration pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + redis.ts +``` + +## Example + +```ts +import { createSemaphore } from 'commandkit/semaphore'; +import { RedisSemaphoreStorage } from '@commandkit/redis'; +import { Redis } from 'ioredis'; + +const redis = new Redis(); +const semaphore = createSemaphore({ + permits: 5, + timeout: 30000, + storage: new RedisSemaphoreStorage(redis), +}); + +await semaphore.withPermit('database-connection', async () => { + await executeDatabaseQuery(); +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-tasks/README.md b/skills/commandkit-tasks/README.md new file mode 100644 index 00000000..a35b652c --- /dev/null +++ b/skills/commandkit-tasks/README.md @@ -0,0 +1,21 @@ +# commandkit-tasks skill + +Skill for scheduled/background job systems using `@commandkit/tasks`. + +## Use this skill when + +- creating scheduled command-adjacent jobs +- choosing and configuring task drivers +- implementing robust dynamic task workflows + +## Typical inputs + +- task schedule and cadence +- persistence and retry requirements +- runtime constraints + +## Expected outputs + +- plugin/driver setup +- task definitions and scheduling logic +- reliability and operational recommendations diff --git a/skills/commandkit-tasks/SKILL.md b/skills/commandkit-tasks/SKILL.md new file mode 100644 index 00000000..b49131fc --- /dev/null +++ b/skills/commandkit-tasks/SKILL.md @@ -0,0 +1,56 @@ +--- +name: commandkit-tasks +version: 1.2.0 +author: neplextech +emoji: '⏱️' +tags: + - commandkit + - tasks + - scheduler + - cron +description: > + Implement scheduled and dynamic jobs with @commandkit/tasks. Use for + static task definitions, dynamic task creation, driver setup, and + resilient job execution patterns. +--- + +# CommandKit Tasks Plugin + +## Activation guidance + +Use for recurring jobs, delayed reminders, and background processing +flows. + +## Required filesystem expectations + +- plugin registration in `commandkit.config.ts` +- static tasks in `src/app/tasks/**` +- driver bootstrap module (for example `src/bootstrap/tasks.ts`) + +## Execution workflow + +1. Register tasks plugin. +2. Configure and initialize driver. +3. Add static tasks and optional dynamic creation APIs. +4. Add idempotency, error handling, and cancellation support. + +## Guardrails + +- Keep tasks idempotent where retries are possible. +- Validate dynamic task payload and schedule inputs. + +## Reference index + +| Name | Description | +| ------------------------------------------ | ----------------------------------------------------- | +| `references/00-filesystem-structure.md` | Task folder and bootstrap layout expectations. | +| `references/01-plugin-and-driver-setup.md` | Plugin + driver setup patterns. | +| `references/02-static-task.md` | Static task definition pattern and lifecycle notes. | +| `references/03-dynamic-task.md` | Dynamic task scheduling pattern and payload guidance. | +| `references/04-delete-task.md` | Task cancellation/deletion pattern and safeguards. | + +## Tool index + +| Name | Description | +| ---------------------------------- | -------------------------------------------- | +| `tools/generate-task-template.mjs` | Prints static or dynamic task template code. | diff --git a/skills/commandkit-tasks/references/00-filesystem-structure.md b/skills/commandkit-tasks/references/00-filesystem-structure.md new file mode 100644 index 00000000..52abdac2 --- /dev/null +++ b/skills/commandkit-tasks/references/00-filesystem-structure.md @@ -0,0 +1,51 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + tasks.ts + app/ + tasks/ +``` + +## Example + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + tasks.ts + app/ + tasks/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-tasks/references/01-plugin-and-driver-setup.md b/skills/commandkit-tasks/references/01-plugin-and-driver-setup.md new file mode 100644 index 00000000..4986b4a0 --- /dev/null +++ b/skills/commandkit-tasks/references/01-plugin-and-driver-setup.md @@ -0,0 +1,53 @@ +# 01 plugin and driver setup + +## Purpose + +Show tasks plugin + driver startup setup. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + tasks.ts + app/ + tasks/ +``` + +## Example + +```ts +import { defineConfig } from 'commandkit/config'; +import { tasks, setDriver } from '@commandkit/tasks'; +import { SQLiteDriver } from '@commandkit/tasks/sqlite'; + +setDriver(new SQLiteDriver('./tasks.db')); + +export default defineConfig({ + plugins: [tasks()], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-tasks/references/02-static-task.md b/skills/commandkit-tasks/references/02-static-task.md new file mode 100644 index 00000000..08a0b9ea --- /dev/null +++ b/skills/commandkit-tasks/references/02-static-task.md @@ -0,0 +1,53 @@ +# 02 static task + +## Purpose + +Show static task definition pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + tasks.ts + app/ + tasks/ +``` + +## Example + +```ts +import { task } from '@commandkit/tasks'; + +export default task({ + name: 'daily-backup', + schedule: '0 0 * * *', + async execute() { + await performBackup(); + }, +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-tasks/references/03-dynamic-task.md b/skills/commandkit-tasks/references/03-dynamic-task.md new file mode 100644 index 00000000..3171bed4 --- /dev/null +++ b/skills/commandkit-tasks/references/03-dynamic-task.md @@ -0,0 +1,51 @@ +# 03 dynamic task + +## Purpose + +Show dynamic task scheduling pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + tasks.ts + app/ + tasks/ +``` + +## Example + +```ts +import { createTask } from '@commandkit/tasks'; + +await createTask({ + name: 'reminder', + data: { userId: '123', message: 'meeting' }, + schedule: Date.now() + 5 * 60 * 1000, +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-tasks/references/04-delete-task.md b/skills/commandkit-tasks/references/04-delete-task.md new file mode 100644 index 00000000..65658952 --- /dev/null +++ b/skills/commandkit-tasks/references/04-delete-task.md @@ -0,0 +1,47 @@ +# 04 delete task + +## Purpose + +Show scheduled task cancellation pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + bootstrap/ + tasks.ts + app/ + tasks/ +``` + +## Example + +```ts +import { deleteTask } from '@commandkit/tasks'; + +await deleteTask(taskId); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-tasks/tools/generate-task-template.mjs b/skills/commandkit-tasks/tools/generate-task-template.mjs new file mode 100644 index 00000000..083c6828 --- /dev/null +++ b/skills/commandkit-tasks/tools/generate-task-template.mjs @@ -0,0 +1,23 @@ +#!/usr/bin/env node + +const mode = process.argv[2] ?? 'static'; + +if (mode === 'dynamic') { + console.log(`import { createTask } from '@commandkit/tasks'; + +await createTask({ + name: 'reminder', + data: { userId: '123', message: 'hello' }, + schedule: Date.now() + 60000, +});`); +} else { + console.log(`import { task } from '@commandkit/tasks'; + +export default task({ + name: 'daily-job', + schedule: '0 0 * * *', + async execute() { + // do work + }, +});`); +} diff --git a/skills/commandkit-workflow/README.md b/skills/commandkit-workflow/README.md new file mode 100644 index 00000000..35c8177c --- /dev/null +++ b/skills/commandkit-workflow/README.md @@ -0,0 +1,21 @@ +# commandkit-workflow skill + +Skill for workflow orchestration patterns with `@commandkit/workflow`. + +## Use this skill when + +- implementing durable long-running bot flows +- decomposing logic into workflow steps +- wiring workflow runtime and triggers + +## Typical inputs + +- target multi-step process +- durability and restart expectations +- integration points with commands/events + +## Expected outputs + +- workflow plugin integration +- step structure and orchestration code +- reliability-oriented implementation guidance diff --git a/skills/commandkit-workflow/SKILL.md b/skills/commandkit-workflow/SKILL.md new file mode 100644 index 00000000..967d23b0 --- /dev/null +++ b/skills/commandkit-workflow/SKILL.md @@ -0,0 +1,55 @@ +--- +name: commandkit-workflow +version: 1.2.0 +author: neplextech +emoji: '🧭' +tags: + - commandkit + - workflow + - orchestration + - durability +description: > + Build durable workflow orchestration with @commandkit/workflow. Use + for workflow entrypoints, step design, command-triggered workflow + starts, and long-running stateful process handling. +--- + +# CommandKit Workflow Plugin + +## Activation guidance + +Use for multi-step processes that should survive restart and run +reliably. + +## Required filesystem expectations + +- plugin registration in `commandkit.config.ts` +- workflow files in `src/workflows/**` +- trigger commands/events in `src/app/**` + +## Execution workflow + +1. Register workflow plugin. +2. Create workflow entrypoint using `'use workflow'`. +3. Create step functions using `'use step'`. +4. Start workflows from commands/events. + +## Guardrails + +- Keep step boundaries explicit and side effects controlled. +- Keep workflow inputs deterministic and serializable. + +## Reference index + +| Name | Description | +| --------------------------------------- | ------------------------------------------------------------ | +| `references/00-filesystem-structure.md` | Workflow/trigger file placement and project layout guidance. | +| `references/01-plugin-setup.md` | Plugin wiring baseline. | +| `references/02-workflow-and-step.md` | Entry/step design pattern and best practices. | +| `references/03-start-workflow.md` | Starting workflows from command handlers. | + +## Tool index + +| Name | Description | +| ----- | ------------------------------------------------ | +| `N/A` | This skill currently has no helper tool scripts. | diff --git a/skills/commandkit-workflow/references/00-filesystem-structure.md b/skills/commandkit-workflow/references/00-filesystem-structure.md new file mode 100644 index 00000000..cfc229f1 --- /dev/null +++ b/skills/commandkit-workflow/references/00-filesystem-structure.md @@ -0,0 +1,49 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + workflows/ + app/ + commands/ +``` + +## Example + +```txt +project/ + commandkit.config.ts + src/ + workflows/ + app/ + commands/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit-workflow/references/01-plugin-setup.md b/skills/commandkit-workflow/references/01-plugin-setup.md new file mode 100644 index 00000000..49f90c0c --- /dev/null +++ b/skills/commandkit-workflow/references/01-plugin-setup.md @@ -0,0 +1,49 @@ +# 01 plugin setup + +## Purpose + +Show minimal plugin registration pattern. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + workflows/ + app/ + commands/ +``` + +## Example + +```ts +import { defineConfig } from 'commandkit/config'; +import { workflow } from '@commandkit/workflow'; + +export default defineConfig({ + plugins: [workflow()], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-workflow/references/02-workflow-and-step.md b/skills/commandkit-workflow/references/02-workflow-and-step.md new file mode 100644 index 00000000..2c58ba5c --- /dev/null +++ b/skills/commandkit-workflow/references/02-workflow-and-step.md @@ -0,0 +1,60 @@ +# 02 workflow and step + +## Purpose + +Show workflow entrypoint and step boundaries. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + workflows/ + app/ + commands/ +``` + +## Example + +```ts +import { sleep } from 'workflow'; +import { useClient } from 'commandkit/hooks'; + +export async function greetUserWorkflow(userId: string) { + 'use workflow'; + + await greetUser(userId); + await sleep('5 seconds'); + await greetUser(userId, true); +} + +async function greetUser(userId: string, again = false) { + 'use step'; + const client = useClient(); + const user = await client.users.fetch(userId); + await user.send(again ? 'Hello again!' : 'Hello!'); +} +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit-workflow/references/03-start-workflow.md b/skills/commandkit-workflow/references/03-start-workflow.md new file mode 100644 index 00000000..f1e5f943 --- /dev/null +++ b/skills/commandkit-workflow/references/03-start-workflow.md @@ -0,0 +1,50 @@ +# 03 start workflow + +## Purpose + +Show triggering workflows from commands/events. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + workflows/ + app/ + commands/ +``` + +## Example + +```ts +import { start } from 'workflow/api'; +import { greetUserWorkflow } from '@/workflows/greet'; + +export const chatInput = async (ctx) => { + await ctx.interaction.reply("I'm gonna greet you"); + await start(greetUserWorkflow, [ctx.interaction.user.id]); +}; +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit/README.md b/skills/commandkit/README.md new file mode 100644 index 00000000..7c692c32 --- /dev/null +++ b/skills/commandkit/README.md @@ -0,0 +1,28 @@ +# commandkit skill + +This skill is the primary operational guide for working with the `commandkit` core package. + +## Use this skill when + +- creating or refactoring command files +- adding Discord event handlers +- wiring middleware, categories, metadata, or context patterns +- working on JSX-based message/component responses +- setting up or debugging `commandkit.config.*` + +## Typical inputs + +- target behavior and command/event requirements +- current project structure +- existing conventions and plugin usage + +## Expected outputs + +- concrete code changes aligned with CommandKit conventions +- minimal, clear explanation of architecture decisions +- references to relevant docs for maintainability + +## Notes + +- Prefer existing codebase conventions over generic templates. +- Keep framework-specific behavior in CommandKit-native patterns. diff --git a/skills/commandkit/SKILL.md b/skills/commandkit/SKILL.md new file mode 100644 index 00000000..938084d6 --- /dev/null +++ b/skills/commandkit/SKILL.md @@ -0,0 +1,83 @@ +--- +name: commandkit +version: 1.2.0 +author: neplextech +emoji: '🧰' +tags: + - commandkit + - discordjs + - framework + - commands + - events +description: > + Build and maintain Discord bots with CommandKit core conventions. + Use when implementing command/event architecture, middleware chains, + JSX components, and commandkit.config setup for plugin-based + features. +--- + +# CommandKit Core + +## Activation guidance + +Use this skill for framework-level architecture and implementation: + +- command and event file placement +- commandkit.config strategy and plugin wiring +- middleware lifecycle behavior +- JSX interaction components and handlers +- project structure validation and migration to convention-based + layouts + +## Required filesystem expectations + +- `commandkit.config.ts` (or `.js`) at project root +- `src/app/commands/**` for commands +- `src/app/events/**` for events +- optional plugin-specific folders (`src/app/locales`, + `src/app/tasks`, `src/workflows`) when those plugins are enabled + +## Configuration expectations + +- Use `defineConfig` from `commandkit/config`. +- Register plugins explicitly in `plugins: []`. +- Use startup guards like `noBuildOnly()` for runtime-only setup (for + example task/driver init). +- Keep environment-sensitive plugin toggles explicit (for example + devtools in development only). + +## Execution workflow + +1. Validate structure and baseline config first. +2. Place command/event files in convention paths. +3. Implement command logic with typed context and metadata. +4. Add middleware only for cross-cutting concerns. +5. Verify runtime behavior with local dev command. + +## Guardrails + +- Do not invent CommandKit APIs. +- Avoid registration-heavy patterns that bypass convention discovery. +- Keep handlers small and move reusable logic to helpers/services. + +## Reference index + +| Name | Description | +| ------------------------------------------ | ------------------------------------------------------------------------------------------- | +| `references/00-filesystem-structure.md` | Canonical project layout, required paths, and structure validation guidance. | +| `references/01-config-and-structure.md` | Detailed config patterns, plugin wiring strategies, and config recipes by task. | +| `references/02-chat-input-command.md` | Baseline slash command pattern with metadata and response handling. | +| `references/03-event-handler.md` | Event listener conventions and lifecycle best practices. | +| `references/04-jsx-components.md` | Valid JSX component patterns (including interactive handlers) based on real project usage. | +| `references/05-middlewares.md` | Global, directory, and command-specific middleware patterns and ordering. | +| `references/06-config-recipes.md` | Task-oriented config recipes for common bot setups (core only, AI, cache, tasks, workflow). | +| `references/07-sharding-your-bot.md` | Sharding manager setup, entrypoint behavior, and scale-related shard planning. | +| `references/08-file-naming-conventions.md` | Special filenames/directories CommandKit auto-discovers and how they affect runtime. | +| `references/09-manual-setup.md` | Full manual setup flow for config, app entrypoint, commands, events, and run/build/start. | +| `references/10-cli-api.md` | Advanced programmatic CLI API usage patterns and constraints. | + +## Tool index + +| Name | Description | +| --------------------------- | --------------------------------------------------------------------------- | +| `tools/check-structure.mjs` | Checks whether required core CommandKit paths exist in the current project. | diff --git a/skills/commandkit/references/00-filesystem-structure.md b/skills/commandkit/references/00-filesystem-structure.md new file mode 100644 index 00000000..41f082af --- /dev/null +++ b/skills/commandkit/references/00-filesystem-structure.md @@ -0,0 +1,66 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime +bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why +files are not discovered. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +```txt +src/ + app/ + components/ + utils/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature + expectations. +- Preserve deterministic behavior and explicit error handling in + implementation code. +- CommandKit supports both JavaScript and TypeScript projects and a + mix of both ESM and CJS module formats. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command + names and data models. +- Validate external inputs and permission boundaries before side + effects. +- Keep setup deterministic so startup behavior is stable across + environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by + CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/commandkit/references/01-config-and-structure.md b/skills/commandkit/references/01-config-and-structure.md new file mode 100644 index 00000000..a2be9b6a --- /dev/null +++ b/skills/commandkit/references/01-config-and-structure.md @@ -0,0 +1,91 @@ +# 01 config and structure + +## Purpose + +Explain CommandKit configuration model and how plugin setup maps to +concrete project tasks. + +## When to use + +Use when editing commandkit.config or deciding which plugins/files are +required for a capability. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```ts +import { defineConfig } from 'commandkit/config'; + +export default defineConfig({ + plugins: [], +}); +``` + +```ts +import { defineConfig, noBuildOnly } from 'commandkit/config'; +import { i18n } from '@commandkit/i18n'; +import { devtools } from '@commandkit/devtools'; +import { cache } from '@commandkit/cache'; +import { ai } from '@commandkit/ai'; +import { tasks, setDriver } from '@commandkit/tasks'; +import { SQLiteDriver } from '@commandkit/tasks/sqlite'; +import { workflow } from '@commandkit/workflow'; +import { ratelimit } from '@commandkit/ratelimit'; + +noBuildOnly(() => { + // runs only if this code is being executed outside of a build process + // this prevents issues such as: + // - build command hangs due to long-running driver initialization + // - build-time errors from missing environment variables used in driver setup + // - unintended side effects from running driver code during build + // The opposite behavior can be achieved with `buildOnly()` function. + setDriver(new SQLiteDriver()); +})(); + +export default defineConfig({ + plugins: [ + i18n(), + devtools(), + cache(), + ratelimit(), + ai(), + tasks({ initializeDefaultDriver: false }), + workflow(), + ], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature + expectations. +- Preserve deterministic behavior and explicit error handling in + implementation code. +- CommandKit config file can be in both JavaScript and TypeScript + formats, and supports both ESM and CJS module formats. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command + names and data models. +- Validate external inputs and permission boundaries before side + effects. +- Keep setup deterministic so startup behavior is stable across + environments. + +## Common mistakes + +- Enabling plugins without creating required companion files. +- Running runtime-only setup during build. +- Putting commands/events outside discovery paths. diff --git a/skills/commandkit/references/02-chat-input-command.md b/skills/commandkit/references/02-chat-input-command.md new file mode 100644 index 00000000..7ac5016c --- /dev/null +++ b/skills/commandkit/references/02-chat-input-command.md @@ -0,0 +1,53 @@ +# 02 chat input command + +## Purpose + +Provide a safe baseline for implementing slash commands with CommandKit conventions. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```ts +import type { ChatInputCommand, CommandData } from 'commandkit'; + +export const command: CommandData = { + name: 'ping', + description: 'Ping command', +}; + +export const chatInput: ChatInputCommand = async (ctx) => { + await ctx.interaction.reply('Pong!'); +}; +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit/references/03-event-handler.md b/skills/commandkit/references/03-event-handler.md new file mode 100644 index 00000000..815186be --- /dev/null +++ b/skills/commandkit/references/03-event-handler.md @@ -0,0 +1,52 @@ +# 03 event handler + +## Purpose + +Provide a baseline event handler pattern with clear lifecycle behavior. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```ts +import type { DiscordJSEvent } from 'commandkit'; + +export const event: DiscordJSEvent = { + name: 'ready', + once: true, + execute: (client) => { + console.log(`Logged in as ${client.user?.tag}`); + }, +}; +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit/references/04-jsx-components.md b/skills/commandkit/references/04-jsx-components.md new file mode 100644 index 00000000..f7a17a78 --- /dev/null +++ b/skills/commandkit/references/04-jsx-components.md @@ -0,0 +1,119 @@ +# 04 jsx components + +## Purpose + +Provide valid JSX component patterns for interactive and display use +cases without invalid handler assumptions. + +## When to use + +Use when building Discord UI with JSX components, especially +interactive flows with buttons/selects/modals. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```tsx +import { + ActionRow, + Button, + OnButtonKitClick, + ChatInputCommand, + CommandData, +} from 'commandkit'; +import { ButtonStyle, MessageFlags } from 'discord.js'; + +export const command: CommandData = { + name: 'confirmation', + description: 'Confirm an action with buttons', +}; + +const handleConfirm: OnButtonKitClick = async (interaction, context) => { + await interaction.reply({ + content: 'Confirmed.', + flags: MessageFlags.Ephemeral, + }); + context.dispose(); // clean up the listener +}; + +export const chatInput: ChatInputCommand = async ({ interaction }) => { + const row = ( + + {/* commandkit auto assigns customId for JSX components by default */} + + + ); + + await interaction.reply({ + content: 'Proceed?', + components: [row], + }); +}; +``` + +```tsx +import { ActionRow, Button } from 'commandkit'; +import { ButtonStyle } from 'discord.js'; + +const row = ( + + + +); +``` + +```tsx +import { Container, TextDisplay, ChatInputCommand } from 'commandkit'; +import { Colors, MessageFlags } from 'discord.js'; + +export const chatInput: ChatInputCommand = async (ctx) => { + const container = ( + + + + ); + + await ctx.interaction.reply({ + components: [container], + flags: MessageFlags.IsComponentsV2, + }); +}; +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature + expectations. +- Preserve deterministic behavior and explicit error handling in + implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command + names and data models. +- Validate external inputs and permission boundaries before side + effects. +- Keep setup deterministic so startup behavior is stable across + environments. + +## Common mistakes + +- Using non-link buttons without onClick handlers. +- Forgetting MessageFlags.IsComponentsV2 when sending v2 container + payloads. +- Mixing interactive and link button patterns incorrectly. diff --git a/skills/commandkit/references/05-middlewares.md b/skills/commandkit/references/05-middlewares.md new file mode 100644 index 00000000..222b3db0 --- /dev/null +++ b/skills/commandkit/references/05-middlewares.md @@ -0,0 +1,54 @@ +# 05 middlewares + +## Purpose + +Describe middleware scopes, ordering, and safe cross-cutting usage patterns. + +## When to use + +Use when you need auth/logging/validation before or after command execution. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```ts +import type { MiddlewareContext } from 'commandkit'; + +export function beforeExecute(ctx: MiddlewareContext) { + console.log(`User ${ctx.interaction.user.id} is about to execute a command`); +} + +export function afterExecute(ctx: MiddlewareContext) { + console.log( + `Command execution completed for user ${ctx.interaction.user.id}`, + ); +} +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit/references/06-config-recipes.md b/skills/commandkit/references/06-config-recipes.md new file mode 100644 index 00000000..7ecc7a1b --- /dev/null +++ b/skills/commandkit/references/06-config-recipes.md @@ -0,0 +1,58 @@ +# 06 config recipes + +## Purpose + +Provide ready-to-adapt config recipes for common plugin combinations. + +## When to use + +Use when you need a known-good config starting point for a specific feature combination. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```ts +import { defineConfig } from 'commandkit/config'; + +export default defineConfig({ + plugins: [], +}); +``` + +```ts +import { defineConfig } from 'commandkit/config'; +import { i18n } from '@commandkit/i18n'; +import { cache } from '@commandkit/cache'; + +export default defineConfig({ + plugins: [i18n(), cache()], +}); +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/commandkit/references/07-sharding-your-bot.md b/skills/commandkit/references/07-sharding-your-bot.md new file mode 100644 index 00000000..0a5c449e --- /dev/null +++ b/skills/commandkit/references/07-sharding-your-bot.md @@ -0,0 +1,67 @@ +# 07 sharding your bot + +## Purpose + +Provide a safe, practical sharding setup for large Discord bots using +CommandKit + discord.js sharding manager conventions. + +## When to use + +Use when the bot is approaching high guild counts, has single-process +memory pressure, or needs multi-process scaling. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app.ts + sharding-manager.ts +``` + +## Example + +```ts +// src/sharding-manager.ts +import { ShardingManager } from 'discord.js'; +import { join } from 'node:path'; + +process.loadEnvFile('./.env'); + +const manager = new ShardingManager(join(import.meta.dirname, 'index.js'), { + token: process.env.DISCORD_TOKEN, + totalShards: 2, + mode: 'worker', +}); + +manager.on('shardCreate', (shard) => { + console.log(`Launched shard ${shard.id}`); +}); + +await manager.spawn(); +``` + +## Important details + +- `src/sharding-manager.ts` is auto-detected by CommandKit and used as + shard manager entrypoint. +- `index.js` refers to the generated runtime entrypoint used by + CommandKit in dev/start flows. +- Sharding behavior follows discord.js semantics; CommandKit does not + redefine core sharding model. + +## Best practices + +- Keep shard count configurable via environment for deploy + flexibility. +- Add startup logging for shard creation and failures. +- Centralize shared-state dependencies (cache/queue/ratelimit storage) + for multi-shard consistency. + +## Common mistakes + +- Hardcoding shard settings without environment-based overrides. +- Forgetting to load token environment variables before manager + creation. +- Assuming single-process in-memory state is shared across shards. diff --git a/skills/commandkit/references/08-file-naming-conventions.md b/skills/commandkit/references/08-file-naming-conventions.md new file mode 100644 index 00000000..4353ce8a --- /dev/null +++ b/skills/commandkit/references/08-file-naming-conventions.md @@ -0,0 +1,68 @@ +# 08 file naming conventions + +## Purpose + +Document CommandKit special filenames and directory conventions that +control discovery and execution behavior. + +## When to use + +Use when creating new files, reorganizing command/event trees, or +debugging why handlers are not being discovered. + +## Filesystem + +```txt +src/ + app.ts + app/ + commands/ + +global-middleware.ts + +middleware.ts + +.middleware.ts + events/ + / + .ts +``` + +## Example + +```ts +// src/app.ts +import { Client } from 'discord.js'; + +const client = new Client({ intents: ['Guilds'] }); +export default client; +``` + +```ts +// src/app/commands/+middleware.ts +import type { MiddlewareContext } from 'commandkit'; + +export function beforeExecute(ctx: MiddlewareContext) { + console.log(`before ${ctx.command.name}`); +} +``` + +## Important details + +- `src/app.ts` must export the discord.js client instance. +- Command categories use parenthesized directories (for example + `(Moderation)`) for organization. +- Middleware filename variants define global, directory-scoped, and + command-scoped behavior. + +## Best practices + +- Use descriptive, stable command filenames and folder categories. +- Keep middleware naming exact (`+middleware`, `+global-middleware`, + `+.middleware`). +- Keep event handlers inside event-name folders to preserve discovery + consistency. + +## Common mistakes + +- Placing handlers in custom paths not recognized by convention + discovery. +- Misspelling middleware filename prefixes/signatures. +- Forgetting to export default client from `src/app.ts`. diff --git a/skills/commandkit/references/09-manual-setup.md b/skills/commandkit/references/09-manual-setup.md new file mode 100644 index 00000000..218eeb18 --- /dev/null +++ b/skills/commandkit/references/09-manual-setup.md @@ -0,0 +1,80 @@ +# 09 manual setup + +## Purpose + +Provide a full manual setup blueprint for CommandKit projects without +using scaffolding CLI. + +## When to use + +Use when integrating CommandKit into an existing repo or when custom +project bootstrap is required. + +## Filesystem + +```txt +project/ + commandkit.config.ts + src/ + app.ts + app/ + commands/ + events/ +``` + +## Example + +```ts +// commandkit.config.ts +import { defineConfig } from 'commandkit'; + +export default defineConfig({}); +``` + +```ts +// src/app.ts +import { Client } from 'discord.js'; + +const client = new Client({ intents: ['Guilds'] }); +export default client; +``` + +```ts +// src/app/commands/ping.ts +import type { CommandData, ChatInputCommand, MessageCommand } from 'commandkit'; + +export const command: CommandData = { + name: 'ping', + description: 'Pong!', +}; + +export const chatInput: ChatInputCommand = async ({ interaction }) => { + await interaction.reply('Pong!'); +}; + +export const message: MessageCommand = async ({ message }) => { + await message.reply('Pong!'); +}; +``` + +## Important details + +- Do not call `client.login()` manually; CommandKit handles login. +- Bot token should come from `DISCORD_TOKEN` or `TOKEN`, or be + assigned to `client.token` explicitly. +- Development/build artifacts (`.commandkit`, `dist`) should be + ignored by version control. + +## Best practices + +- Verify manual setup with `commandkit dev` before adding plugins. +- Add one command and one event first to validate discovery. +- Keep env handling explicit and consistent across local/CI/prod. + +## Common mistakes + +- Creating config and entrypoint but missing `src/app/commands` or + `src/app/events`. +- Trying to log in client manually and conflicting with CommandKit + lifecycle. +- Committing generated build/dev folders. diff --git a/skills/commandkit/references/10-cli-api.md b/skills/commandkit/references/10-cli-api.md new file mode 100644 index 00000000..b75c7b3a --- /dev/null +++ b/skills/commandkit/references/10-cli-api.md @@ -0,0 +1,69 @@ +# 10 cli api + +## Purpose + +Document advanced programmatic use of `commandkit/cli` modules for +custom tooling and build workflows. + +## When to use + +Use when standard CLI commands are insufficient and custom automation +requires invoking CommandKit internals programmatically. + +## Filesystem + +```txt +project/ + commandkit.config.ts + scripts/ + custom-build.ts + custom-dev.ts + src/ +``` + +## Example + +```ts +import { production, typeChecker } from 'commandkit/cli'; + +async function customBuild() { + const configPath = './commandkit.config.ts'; + + await typeChecker.performTypeCheck('./src'); + await production.createProductionBuild(configPath); +} + +await customBuild(); +``` + +```ts +import { development } from 'commandkit/cli'; + +const devServer = await development.bootstrapDevelopmentServer( + './commandkit.config.ts', +); +devServer.watcher.on('change', (path) => { + console.log(`changed: ${path}`); +}); +``` + +## Important details + +- CLI API is an advanced/internal-style surface and may change faster + than high-level CLI commands. +- Wrap CLI API usage in explicit error handling. +- Prefer `commandkit dev/build/start` unless integration requirements + truly demand programmatic control. + +## Best practices + +- Isolate custom CLI API usage in dedicated scripts. +- Keep config path explicit in automation scripts. +- Fail fast with clear error output in CI. + +## Common mistakes + +- Overusing CLI API when regular CLI commands are sufficient. +- Missing try/catch around long-running build/dev bootstraps. +- Assuming internal API stability across versions without + compatibility checks. diff --git a/skills/commandkit/tools/check-structure.mjs b/skills/commandkit/tools/check-structure.mjs new file mode 100644 index 00000000..3c6c11ab --- /dev/null +++ b/skills/commandkit/tools/check-structure.mjs @@ -0,0 +1,13 @@ +#!/usr/bin/env node +import { existsSync } from 'node:fs'; + +const required = ['commandkit.config.ts', 'src/app/commands', 'src/app/events']; +const missing = required.filter((p) => !existsSync(p)); + +if (missing.length > 0) { + console.error('Missing expected CommandKit paths:'); + for (const m of missing) console.error(`- ${m}`); + process.exit(1); +} + +console.log('Core CommandKit structure looks valid.'); diff --git a/skills/create-commandkit/README.md b/skills/create-commandkit/README.md new file mode 100644 index 00000000..fdc10e26 --- /dev/null +++ b/skills/create-commandkit/README.md @@ -0,0 +1,22 @@ +# create-commandkit skill + +This skill covers the official scaffolding CLI for new CommandKit projects. + +## Use this skill when + +- starting a new CommandKit bot +- choosing TypeScript vs JavaScript starters +- choosing ESM vs CommonJS modules +- generating a baseline structure before custom features + +## Typical inputs + +- preferred language and module system +- package manager +- starter scope (minimal, plugin-ready, example-driven) + +## Expected outputs + +- exact scaffold command(s) +- concise rationale for selected options +- immediate next steps after project creation diff --git a/skills/create-commandkit/SKILL.md b/skills/create-commandkit/SKILL.md new file mode 100644 index 00000000..7e077bef --- /dev/null +++ b/skills/create-commandkit/SKILL.md @@ -0,0 +1,55 @@ +--- +name: create-commandkit +version: 1.2.0 +author: neplextech +emoji: '🚀' +tags: + - commandkit + - scaffolding + - cli + - bootstrap +description: > + Scaffold CommandKit projects with create-commandkit. Use when + generating a new bot, selecting example templates, package manager + flags, and reproducible initialization commands. +--- + +# Create CommandKit CLI + +## Activation guidance + +Use for greenfield setup, template selection, and first-run onboarding +commands. + +## Required filesystem expectations + +- generated project root with `package.json` +- `commandkit.config.ts` or `.js` +- `src/app/commands/**` and `src/app/events/**` + +## Execution workflow + +1. Select bootstrap mode (interactive, defaults, or example). +2. Select package manager and installation flags. +3. Produce copy-paste command and next steps. +4. Verify generated structure before adding features. + +## Guardrails + +- Prefer official examples for reliable baseline behavior. +- Keep generated instructions deterministic and shell-ready. + +## Reference index + +| Name | Description | +| ---------------------------------------- | ------------------------------------------------------------------- | +| `references/00-filesystem-structure.md` | Expected post-scaffold structure and immediate verification checks. | +| `references/01-bootstrap-commands.md` | Standard initialization command variants. | +| `references/02-example-templates.md` | Using curated and custom example sources. | +| `references/03-package-manager-flags.md` | Package manager and setup flags with selection guidance. | + +## Tool index + +| Name | Description | +| ----------------------------- | --------------------------------------------------------------- | +| `tools/recommend-command.mjs` | Generates a recommended scaffold command from simple CLI hints. | diff --git a/skills/create-commandkit/references/00-filesystem-structure.md b/skills/create-commandkit/references/00-filesystem-structure.md new file mode 100644 index 00000000..ee44e52e --- /dev/null +++ b/skills/create-commandkit/references/00-filesystem-structure.md @@ -0,0 +1,51 @@ +# 00 filesystem structure + +## Purpose + +Define required filesystem layout so feature discovery and runtime bootstrapping work reliably. + +## When to use + +Use when creating a new project, enabling a plugin, or debugging why files are not discovered. + +## Filesystem + +```txt +new-project/ + package.json + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```txt +my-bot/ + package.json + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Creating feature files in arbitrary folders not discovered by CommandKit. +- Renaming key directories without matching framework conventions. +- Missing root config file while expecting auto-discovery to work. diff --git a/skills/create-commandkit/references/01-bootstrap-commands.md b/skills/create-commandkit/references/01-bootstrap-commands.md new file mode 100644 index 00000000..2c289f9c --- /dev/null +++ b/skills/create-commandkit/references/01-bootstrap-commands.md @@ -0,0 +1,49 @@ +# 01 bootstrap commands + +## Purpose + +Show reliable project bootstrap command variants. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +new-project/ + package.json + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```sh +npx create-commandkit@latest +``` + +```sh +npx create-commandkit@latest my-bot +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/create-commandkit/references/02-example-templates.md b/skills/create-commandkit/references/02-example-templates.md new file mode 100644 index 00000000..6ef62a9e --- /dev/null +++ b/skills/create-commandkit/references/02-example-templates.md @@ -0,0 +1,52 @@ +# 02 example templates + +## Purpose + +Show how to scaffold from official or custom examples. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +new-project/ + package.json + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```sh +# curated +npx create-commandkit@latest --example basic-ts + +# custom repository +npx create-commandkit@latest --example "https://github.com/user/repo" + +# custom path within repository +npx create-commandkit@latest --example "https://github.com/user/repo" --example-path "examples/bot" +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/create-commandkit/references/03-package-manager-flags.md b/skills/create-commandkit/references/03-package-manager-flags.md new file mode 100644 index 00000000..e0461031 --- /dev/null +++ b/skills/create-commandkit/references/03-package-manager-flags.md @@ -0,0 +1,45 @@ +# 03 package manager flags + +## Purpose + +Document package-manager and setup flags for reproducible scaffolds. + +## When to use + +Use when implementing or reviewing this feature in a CommandKit-based project. + +## Filesystem + +```txt +new-project/ + package.json + commandkit.config.ts + src/ + app/ + commands/ + events/ +``` + +## Example + +```sh +npx create-commandkit@latest --use-pnpm --skip-install --no-git +``` + +## Important details + +- Use exact API/export names shown in the example. +- Keep filesystem placement aligned with enabled plugins and feature expectations. +- Preserve deterministic behavior and explicit error handling in implementation code. + +## Best practices + +- Keep snippets as baseline patterns and adapt them to real command names and data models. +- Validate external inputs and permission boundaries before side effects. +- Keep setup deterministic so startup behavior is stable across environments. + +## Common mistakes + +- Skipping validation for user-provided inputs before side effects. +- Changing structure/config without verifying companion files. +- Copying snippets without adapting identifiers and environment values. diff --git a/skills/create-commandkit/tools/recommend-command.mjs b/skills/create-commandkit/tools/recommend-command.mjs new file mode 100644 index 00000000..9794416b --- /dev/null +++ b/skills/create-commandkit/tools/recommend-command.mjs @@ -0,0 +1,12 @@ +#!/usr/bin/env node + +const args = process.argv.slice(2); +const name = args.find((a) => !a.startsWith('--')) ?? 'my-bot'; +const pm = args.includes('--pnpm') + ? '--use-pnpm' + : args.includes('--yarn') + ? '--use-yarn' + : '--use-npm'; +const fast = args.includes('--yes') ? '--yes' : ''; + +console.log(`npx create-commandkit@latest ${name} ${pm} ${fast}`.trim());