feat: dynamic create-commandkit

Author: twlite

.gitignore

@@ -1,5 +1,4 @@
 node_modules
 dist
 .DS_Store
-.vscode
 .turbo

.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "files.readonlyInclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "files.watcherExclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "search.exclude": {
+    "**/routeTree.gen.ts": true
+  }
+}

examples/without-cli/pnpm-lock.yaml

@@ -14,19 +14,85 @@ create-commandkit is a CLI utility to quickly instantiate a Discord bot with Com
 
 - Interactive, beautiful command-line interface 🖥️
 - Supports CommonJS and ES Modules 📦
+- Dynamic template system with examples from GitHub 🚀
+- Support for all major package managers (npm, pnpm, yarn, bun, deno) 📦
+- TypeScript and JavaScript support 🔧
 
 ## Documentation
 
 You can find the full documentation [here](https://commandkit.dev).
 
 ## Usage
 
-Run the following command in your terminal:
+### Basic Usage
 
 ```sh
 npx create-commandkit@latest
 ```
 
+### With Project Name
+
+```sh
+npx create-commandkit@latest my-bot
+```
+
+### Using Examples
+
+```sh
+# Use a curated example
+npx create-commandkit@latest --example with-database
+
+# Use a custom GitHub repository
+npx create-commandkit@latest --example "https://github.com/user/repo"
+
+# Use a specific path within a repository
+npx create-commandkit@latest --example "https://github.com/user/repo" --example-path "examples/bot"
+```
+
+### CLI Options
+
+- `-h, --help` - Show all available options
+- `-v, --version` - Output the version number
+- `-e, --example <name-or-url>` - An example to bootstrap the app with
+- `--example-path <path>` - Specify the path to the example separately
+- `--use-npm` - Use npm as package manager
+- `--use-pnpm` - Use pnpm as package manager
+- `--use-yarn` - Use yarn as package manager
+- `--use-bun` - Use bun as package manager
+- `--use-deno` - Use deno as package manager
+- `--skip-install` - Skip installing packages
+- `--no-git` - Skip git initialization
+- `--yes` - Use defaults for all options
+- `--list-examples` - List all available examples from the official repository
+
+### Available Examples
+
+<!-- BEGIN_AVAILABLE_EXAMPLES -->
+- `basic-js` - [examples/basic-js](https://github.com/underctrl-io/commandkit/tree/main/examples/basic-js)
+- `basic-ts` - [examples/basic-ts](https://github.com/underctrl-io/commandkit/tree/main/examples/basic-ts)
+- `deno-ts` - [examples/deno-ts](https://github.com/underctrl-io/commandkit/tree/main/examples/deno-ts)
+- `without-cli` - [examples/without-cli](https://github.com/underctrl-io/commandkit/tree/main/examples/without-cli)
+<!-- END_AVAILABLE_EXAMPLES -->
+
+### Examples
+
+```sh
+# Create a bot with database example, skip installation
+npx create-commandkit@latest --example with-database --skip-install
+
+# Create a bot with all defaults (no prompts)
+npx create-commandkit@latest --yes
+
+# Create a bot from custom repository
+npx create-commandkit@latest --example "https://github.com/username/my-commandkit-template"
+
+# Create a bot with pnpm
+npx create-commandkit@latest --use-pnpm
+
+# List all available examples
+npx create-commandkit@latest --list-examples
+```
+
 ## Support and Suggestions
 
 Submit any queries or suggestions in our [Discord community](https://ctrl.lol/discord).

packages/create-commandkit/README.md

@@ -30,20 +30,25 @@
   "scripts": {
     "check-types": "tsc --noEmit",
     "dev": "tsc --watch",
-    "build": "tsc"
+    "build": "tsc && tsx scripts/sync-available-examples.ts"
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
+    "commander": "^14.0.1",
     "fs-extra": "^11.1.1",
     "gradient-string": "^3.0.0",
     "ora": "^8.0.1",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "tiged": "^2.12.7",
+    "validate-npm-package-name": "^6.0.2"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
     "@types/gradient-string": "^1.1.5",
     "@types/node": "^22.0.0",
+    "@types/validate-npm-package-name": "^4.0.2",
     "tsconfig": "workspace:*",
+    "tsx": "^4.20.6",
     "typescript": "catalog:build"
   }
-}
+}

packages/create-commandkit/package.json

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+const BEGIN_MARKER = '<!-- BEGIN_AVAILABLE_EXAMPLES -->';
+const END_MARKER = '<!-- END_AVAILABLE_EXAMPLES -->';
+
+const README_PATH = path.join(import.meta.dirname, '..', 'README.md');
+const README_CONTENT = fs.readFileSync(README_PATH, 'utf8');
+
+function insertBetween(content: string) {
+  const availableExamples = fs.readdirSync(
+    path.join(import.meta.dirname, '..', '..', '..', 'examples'),
+  );
+
+  const examples = availableExamples
+    .map(
+      (example) =>
+        `- \`${example}\` - [examples/${example}](https://github.com/underctrl-io/commandkit/tree/main/examples/${example})`,
+    )
+    .join('\n');
+
+  const between = `${BEGIN_MARKER}\n${examples}\n${END_MARKER}`;
+  const newContent = [
+    content.split(BEGIN_MARKER)[0],
+    between,
+    content.split(END_MARKER)[1],
+  ].join('');
+
+  return newContent;
+}
+
+const newContent = insertBetween(README_CONTENT);
+
+fs.writeFileSync(README_PATH, newContent);

packages/create-commandkit/scripts/sync-available-examples.ts

@@ -0,0 +1,59 @@
+import { Command } from 'commander';
+import type { CLIOptions } from './types.js';
+
+export function parseCLI(): CLIOptions {
+  const program = new Command();
+
+  program
+    .name('create-commandkit')
+    .description('Effortlessly create a CommandKit project')
+    .version(process.env.npm_package_version || '1.0.0')
+    .argument('[project-directory]', 'Project directory name')
+    .option('-h, --help', 'Show all available options')
+    .option('-v, --version', 'Output the version number')
+    .option(
+      '-e, --example <name-or-url>',
+      'An example to bootstrap the app with',
+    )
+    .option(
+      '--example-path <path>',
+      'Specify the path to the example separately',
+    )
+    .option('--use-npm', 'Explicitly tell the CLI to bootstrap using npm')
+    .option('--use-pnpm', 'Explicitly tell the CLI to bootstrap using pnpm')
+    .option('--use-yarn', 'Explicitly tell the CLI to bootstrap using yarn')
+    .option('--use-bun', 'Explicitly tell the CLI to bootstrap using bun')
+    .option('--use-deno', 'Explicitly tell the CLI to bootstrap using deno')
+    .option(
+      '--skip-install',
+      'Explicitly tell the CLI to skip installing packages',
+    )
+    .option('--no-git', 'Explicitly tell the CLI to disable git initialization')
+    .option('--yes', 'Use previous preferences or defaults for all options')
+    .option(
+      '--list-examples',
+      'List all available examples from the official repository',
+    );
+
+  program.parse();
+
+  const options = program.opts();
+  const args = program.args;
+
+  return {
+    help: options.help,
+    version: options.version,
+    example: options.example,
+    examplePath: options.examplePath,
+    useNpm: options.useNpm,
+    usePnpm: options.usePnpm,
+    useYarn: options.useYarn,
+    useBun: options.useBun,
+    useDeno: options.useDeno,
+    skipInstall: options.skipInstall,
+    noGit: options.noGit,
+    yes: options.yes,
+    listExamples: options.listExamples,
+    projectDirectory: args[0],
+  };
+}

packages/create-commandkit/src/cli.ts

@@ -0,0 +1,90 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+// @ts-ignore
+import { tiged } from 'tiged';
+import { validateExampleName } from './validate.js';
+
+export interface FetchExampleOptions {
+  example: string;
+  examplePath?: string;
+  targetDir: string;
+}
+
+export async function fetchExample({
+  example,
+  examplePath,
+  targetDir,
+}: FetchExampleOptions): Promise<void> {
+  const validation = validateExampleName(example);
+  if (!validation.valid) {
+    throw new Error(validation.error);
+  }
+
+  let sourceUrl: string;
+
+  // Check if it's a GitHub URL
+  if (example.startsWith('http://') || example.startsWith('https://')) {
+    sourceUrl = example;
+  } else {
+    // Construct URL for curated examples
+    sourceUrl = `underctrl-io/commandkit/examples/${example}`;
+  }
+
+  // Create temporary directory for download
+  const tempDir = path.join(targetDir, '.temp-example');
+
+  try {
+    // Download the example
+    const emitter = tiged(sourceUrl, {
+      mode: 'tar',
+      disableCache: true,
+    });
+
+    await emitter.clone(tempDir);
+
+    // If examplePath is specified, navigate to that subdirectory
+    const sourceDir = examplePath ? path.join(tempDir, examplePath) : tempDir;
+
+    if (examplePath && !fs.existsSync(sourceDir)) {
+      throw new Error(
+        `Example path '${examplePath}' not found in the repository`,
+      );
+    }
+
+    // Copy contents to target directory
+    const contents = fs.readdirSync(sourceDir);
+
+    for (const item of contents) {
+      const srcPath = path.join(sourceDir, item);
+      const destPath = path.join(targetDir, item);
+
+      if (fs.statSync(srcPath).isDirectory()) {
+        await fs.copy(srcPath, destPath);
+      } else {
+        await fs.copy(srcPath, destPath);
+      }
+    }
+
+    // Clean up temporary directory
+    await fs.remove(tempDir);
+  } catch (error) {
+    // Clean up on error
+    if (fs.existsSync(tempDir)) {
+      await fs.remove(tempDir);
+    }
+
+    if (error instanceof Error) {
+      if (
+        error.message.includes('not found') ||
+        error.message.includes('404')
+      ) {
+        throw new Error(
+          `Example '${example}' not found. Available examples: basic-ts, basic-js, with-database, with-i18n`,
+        );
+      }
+      throw new Error(`Failed to fetch example: ${error.message}`);
+    }
+
+    throw new Error('Failed to fetch example due to an unknown error');
+  }
+}