opencode-swarm-plugin 0.44.2 → 0.45.1

package/global-skills/cli-builder/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: cli-builder
+description: Guide for building TypeScript CLIs with Bun. Use when creating command-line tools, adding subcommands to existing CLIs, or building developer tooling. Covers argument parsing, subcommand patterns, output formatting, and distribution.
+tags:
+  - cli
+  - typescript
+  - bun
+  - tooling
+---
+
+# CLI Builder
+
+Build TypeScript command-line tools with Bun.
+
+## When to Build a CLI
+
+CLIs are ideal for:
+- Developer tools and automation
+- Project-specific commands (`swarm`, `bd`, etc.)
+- Scripts that need arguments/flags
+- Tools that compose with shell pipelines
+
+## Quick Start
+
+### Minimal CLI
+
+```typescript
+#!/usr/bin/env bun
+// scripts/my-tool.ts
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === "help") {
+  console.log(`
+Usage: my-tool <command>
+
+Commands:
+  hello    Say hello
+  help     Show this message
+`);
+  process.exit(0);
+}
+
+if (command === "hello") {
+  console.log("Hello, world!");
+}
+```
+
+Run with: `bun scripts/my-tool.ts hello`
+
+### With Argument Parsing
+
+Use `parseArgs` from Node's `util` module (works in Bun):
+
+```typescript
+#!/usr/bin/env bun
+import { parseArgs } from "util";
+
+const { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    name: { type: "string", short: "n" },
+    verbose: { type: "boolean", short: "v", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  },
+  allowPositionals: true,
+});
+
+if (values.help) {
+  console.log(`
+Usage: greet [options] <message>
+
+Options:
+  -n, --name <name>   Name to greet
+  -v, --verbose       Verbose output
+  -h, --help          Show help
+`);
+  process.exit(0);
+}
+
+const message = positionals[0] || "Hello";
+const name = values.name || "World";
+
+console.log(`${message}, ${name}!`);
+if (values.verbose) {
+  console.log(`  (greeted at ${new Date().toISOString()})`);
+}
+```
+
+## Subcommand Pattern
+
+For CLIs with multiple commands, use a command registry:
+
+```typescript
+#!/usr/bin/env bun
+import { parseArgs } from "util";
+
+type Command = {
+  description: string;
+  run: (args: string[]) => Promise<void>;
+};
+
+const commands: Record<string, Command> = {
+  init: {
+    description: "Initialize a new project",
+    run: async (args) => {
+      const { values } = parseArgs({
+        args,
+        options: {
+          template: { type: "string", short: "t", default: "default" },
+        },
+      });
+      console.log(`Initializing with template: ${values.template}`);
+    },
+  },
+
+  build: {
+    description: "Build the project",
+    run: async (args) => {
+      const { values } = parseArgs({
+        args,
+        options: {
+          watch: { type: "boolean", short: "w", default: false },
+        },
+      });
+      console.log(`Building...${values.watch ? " (watch mode)" : ""}`);
+    },
+  },
+};
+
+function showHelp() {
+  console.log(`
+Usage: mytool <command> [options]
+
+Commands:`);
+  for (const [name, cmd] of Object.entries(commands)) {
+    console.log(`  ${name.padEnd(12)} ${cmd.description}`);
+  }
+  console.log(`
+Run 'mytool <command> --help' for command-specific help.
+`);
+}
+
+// Main
+const [command, ...args] = process.argv.slice(2);
+
+if (!command || command === "help" || command === "--help") {
+  showHelp();
+  process.exit(0);
+}
+
+const cmd = commands[command];
+if (!cmd) {
+  console.error(`Unknown command: ${command}`);
+  showHelp();
+  process.exit(1);
+}
+
+await cmd.run(args);
+```
+
+## Output Formatting
+
+### Colors (without dependencies)
+
+```typescript
+const colors = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+};
+
+function success(msg: string) {
+  console.log(`${colors.green}✓${colors.reset} ${msg}`);
+}
+
+function error(msg: string) {
+  console.error(`${colors.red}✗${colors.reset} ${msg}`);
+}
+
+function warn(msg: string) {
+  console.log(`${colors.yellow}⚠${colors.reset} ${msg}`);
+}
+
+function info(msg: string) {
+  console.log(`${colors.blue}ℹ${colors.reset} ${msg}`);
+}
+```
+
+### JSON Output Mode
+
+Support `--json` for scriptable output:
+
+```typescript
+const { values } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    json: { type: "boolean", default: false },
+  },
+  allowPositionals: true,
+});
+
+const result = { status: "ok", items: ["a", "b", "c"] };
+
+if (values.json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log("Status:", result.status);
+  console.log("Items:", result.items.join(", "));
+}
+```
+
+### Progress Indicators
+
+```typescript
+function spinner(message: string) {
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let i = 0;
+
+  const id = setInterval(() => {
+    process.stdout.write(`\r${frames[i++ % frames.length]} ${message}`);
+  }, 80);
+
+  return {
+    stop: (finalMessage?: string) => {
+      clearInterval(id);
+      process.stdout.write(`\r${finalMessage || message}\n`);
+    },
+  };
+}
+
+// Usage
+const spin = spinner("Loading...");
+await someAsyncWork();
+spin.stop("✓ Done!");
+```
+
+## File System Operations
+
+```typescript
+import { readFile, writeFile, mkdir, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+
+// Ensure directory exists before writing
+async function writeFileWithDir(path: string, content: string) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content);
+}
+
+// Read JSON with defaults
+async function readJsonFile<T>(path: string, defaults: T): Promise<T> {
+  if (!existsSync(path)) return defaults;
+  const content = await readFile(path, "utf-8");
+  return { ...defaults, ...JSON.parse(content) };
+}
+```
+
+## Shell Execution
+
+```typescript
+import { $ } from "bun";
+
+// Simple command
+const result = await $`git status`.text();
+
+// With error handling
+try {
+  await $`npm test`.quiet();
+  console.log("Tests passed!");
+} catch (error) {
+  console.error("Tests failed");
+  process.exit(1);
+}
+
+// Capture output
+const branch = await $`git branch --show-current`.text();
+console.log(`Current branch: ${branch.trim()}`);
+```
+
+## Error Handling
+
+```typescript
+class CLIError extends Error {
+  constructor(message: string, public exitCode = 1) {
+    super(message);
+    this.name = "CLIError";
+  }
+}
+
+async function main() {
+  try {
+    await runCommand();
+  } catch (error) {
+    if (error instanceof CLIError) {
+      console.error(`Error: ${error.message}`);
+      process.exit(error.exitCode);
+    }
+    throw error; // Re-throw unexpected errors
+  }
+}
+
+main();
+```
+
+## Distribution
+
+### package.json bin field
+
+```json
+{
+  "name": "my-cli",
+  "bin": {
+    "mycli": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "bun build ./src/cli.ts --outfile ./dist/cli.js --target node"
+  }
+}
+```
+
+### Shebang for direct execution
+
+```typescript
+#!/usr/bin/env bun
+// First line of your CLI script
+```
+
+Make executable: `chmod +x scripts/my-cli.ts`
+
+## Best Practices
+
+1. **Always provide --help** - Users expect it
+2. **Exit codes matter** - 0 for success, non-zero for errors
+3. **Support --json** - For scriptability and piping
+4. **Fail fast** - Validate inputs early
+5. **Be quiet by default** - Use --verbose for noise
+6. **Respect NO_COLOR** - Check `process.env.NO_COLOR`
+7. **Stream large output** - Don't buffer everything in memory

package/global-skills/cli-builder/references/advanced-patterns.md

@@ -0,0 +1,244 @@
+# Advanced CLI Patterns
+
+## Interactive Prompts
+
+For interactive CLIs, use `@clack/prompts` (lightweight, pretty):
+
+```typescript
+import * as p from "@clack/prompts";
+
+async function setup() {
+  p.intro("Project Setup");
+
+  const name = await p.text({
+    message: "Project name?",
+    placeholder: "my-project",
+    validate: (v) => (v.length < 1 ? "Name required" : undefined),
+  });
+
+  const template = await p.select({
+    message: "Choose a template",
+    options: [
+      { value: "basic", label: "Basic" },
+      { value: "full", label: "Full Featured" },
+    ],
+  });
+
+  const features = await p.multiselect({
+    message: "Select features",
+    options: [
+      { value: "typescript", label: "TypeScript" },
+      { value: "testing", label: "Testing" },
+      { value: "linting", label: "Linting" },
+    ],
+  });
+
+  const confirmed = await p.confirm({
+    message: "Create project?",
+  });
+
+  if (p.isCancel(confirmed) || !confirmed) {
+    p.cancel("Cancelled");
+    process.exit(0);
+  }
+
+  const s = p.spinner();
+  s.start("Creating project...");
+  await createProject({ name, template, features });
+  s.stop("Project created!");
+
+  p.outro("Done! Run `cd ${name} && bun dev`");
+}
+```
+
+## Config File Loading
+
+Support multiple config formats:
+
+```typescript
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+
+interface Config {
+  name: string;
+  debug: boolean;
+}
+
+const CONFIG_FILES = [
+  "myapp.config.ts",
+  "myapp.config.js",
+  "myapp.config.json",
+  ".myapprc",
+  ".myapprc.json",
+];
+
+async function loadConfig(): Promise<Config> {
+  const defaults: Config = { name: "default", debug: false };
+
+  for (const file of CONFIG_FILES) {
+    if (!existsSync(file)) continue;
+
+    if (file.endsWith(".ts") || file.endsWith(".js")) {
+      const mod = await import(`./${file}`);
+      return { ...defaults, ...mod.default };
+    }
+
+    if (file.endsWith(".json") || file.startsWith(".")) {
+      const content = await readFile(file, "utf-8");
+      return { ...defaults, ...JSON.parse(content) };
+    }
+  }
+
+  return defaults;
+}
+```
+
+## Plugin System
+
+Allow extending CLI with plugins:
+
+```typescript
+interface Plugin {
+  name: string;
+  commands?: Record<string, Command>;
+  hooks?: {
+    beforeRun?: () => Promise<void>;
+    afterRun?: () => Promise<void>;
+  };
+}
+
+class CLI {
+  private plugins: Plugin[] = [];
+  private commands: Record<string, Command> = {};
+
+  use(plugin: Plugin) {
+    this.plugins.push(plugin);
+    if (plugin.commands) {
+      Object.assign(this.commands, plugin.commands);
+    }
+  }
+
+  async run(args: string[]) {
+    // Run beforeRun hooks
+    for (const p of this.plugins) {
+      await p.hooks?.beforeRun?.();
+    }
+
+    // Execute command
+    const [cmd, ...rest] = args;
+    await this.commands[cmd]?.run(rest);
+
+    // Run afterRun hooks
+    for (const p of this.plugins) {
+      await p.hooks?.afterRun?.();
+    }
+  }
+}
+```
+
+## Watching Files
+
+```typescript
+import { watch } from "fs";
+
+function watchFiles(
+  dir: string,
+  callback: (event: string, filename: string) => void
+) {
+  const watcher = watch(dir, { recursive: true }, (event, filename) => {
+    if (filename && !filename.includes("node_modules")) {
+      callback(event, filename);
+    }
+  });
+
+  // Cleanup on exit
+  process.on("SIGINT", () => {
+    watcher.close();
+    process.exit(0);
+  });
+
+  return watcher;
+}
+
+// Usage
+watchFiles("./src", (event, file) => {
+  console.log(`${event}: ${file}`);
+  // Trigger rebuild, restart, etc.
+});
+```
+
+## Parallel Execution
+
+```typescript
+async function runParallel<T>(
+  items: T[],
+  fn: (item: T) => Promise<void>,
+  concurrency = 4
+) {
+  const chunks = [];
+  for (let i = 0; i < items.length; i += concurrency) {
+    chunks.push(items.slice(i, i + concurrency));
+  }
+
+  for (const chunk of chunks) {
+    await Promise.all(chunk.map(fn));
+  }
+}
+
+// Usage
+await runParallel(files, async (file) => {
+  await processFile(file);
+}, 8);
+```
+
+## Testing CLIs
+
+```typescript
+import { describe, test, expect } from "bun:test";
+import { $ } from "bun";
+
+describe("mycli", () => {
+  test("--help shows usage", async () => {
+    const result = await $`bun ./src/cli.ts --help`.text();
+    expect(result).toContain("Usage:");
+  });
+
+  test("unknown command fails", async () => {
+    try {
+      await $`bun ./src/cli.ts unknown`.quiet();
+      expect(true).toBe(false); // Should not reach
+    } catch (error) {
+      expect(error.exitCode).toBe(1);
+    }
+  });
+
+  test("init creates files", async () => {
+    const tmpDir = await $`mktemp -d`.text();
+    await $`bun ./src/cli.ts init --path ${tmpDir.trim()}`;
+
+    const files = await $`ls ${tmpDir.trim()}`.text();
+    expect(files).toContain("package.json");
+  });
+});
+```
+
+## Graceful Shutdown
+
+```typescript
+let isShuttingDown = false;
+
+async function shutdown() {
+  if (isShuttingDown) return;
+  isShuttingDown = true;
+
+  console.log("\nShutting down...");
+
+  // Cleanup: close connections, save state, etc.
+  await cleanup();
+
+  process.exit(0);
+}
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+```