invoket 0.1.0

package/README.md

@@ -0,0 +1,208 @@
+# invoket
+
+A TypeScript task runner for Bun that uses type annotations to parse CLI arguments.
+
+## Features
+
+- **Type-safe CLI parsing** — TypeScript types determine how arguments are parsed
+- **Zero configuration** — Just write a `Tasks` class with typed methods
+- **JSON support** — Object and array parameters are automatically parsed from JSON
+- **Namespace support** — Organize tasks with `db:migrate` style namespaces
+- **Rest parameters** — Support for `...args` variadic parameters
+- **Auto-generated help** — JSDoc descriptions become CLI help text
+
+## Installation
+
+```bash
+bun link invoket
+```
+
+## Quick Start
+
+```bash
+invt                    # Show help
+invt hello World 3      # Run task with args
+invt db:migrate up      # Run namespaced task
+invt --version          # Show version
+```
+
+## Writing Tasks
+
+Create a `tasks.ts` file with a `Tasks` class:
+
+```typescript
+import { Context } from "invoket/context";
+
+interface SearchParams {
+  query: string;
+  limit?: number;
+}
+
+/**
+ * Project build and deployment tasks
+ */
+export class Tasks {
+  /** Say hello with a name and repeat count */
+  async hello(c: Context, name: string, count: number) {
+    for (let i = 0; i < count; i++) {
+      console.log(`Hello, ${name}!`);
+    }
+  }
+
+  /** Search with JSON parameters */
+  async search(c: Context, entity: string, params: SearchParams) {
+    console.log(`Searching ${entity}: ${params.query}`);
+  }
+
+  /** Install packages (rest params) */
+  async install(c: Context, ...packages: string[]) {
+    for (const pkg of packages) {
+      await c.run(`npm install ${pkg}`);
+    }
+  }
+}
+```
+
+## Namespaces
+
+Organize related tasks into namespaces:
+
+```typescript
+class DbNamespace {
+  /** Run database migrations */
+  async migrate(c: Context, direction: string = "up") {
+    await c.run(`prisma migrate ${direction}`);
+  }
+
+  /** Seed the database */
+  async seed(c: Context) {
+    await c.run("prisma db seed");
+  }
+}
+
+export class Tasks {
+  db = new DbNamespace();
+}
+```
+
+Call with `invt db:migrate up` or `invt db.seed`.
+
+## Type Mapping
+
+| TypeScript | CLI Display | Example Input |
+|------------|-------------|---------------|
+| `name: string` | `<name>` | `hello` |
+| `name: string = "default"` | `[name]` | `hello` (optional) |
+| `count: number` | `<count>` | `42` |
+| `force: boolean` | `<force>` | `true` or `1` |
+| `params: SomeInterface` | `<params>` | `'{"key": "value"}'` |
+| `items: string[]` | `<items>` | `'["a", "b", "c"]'` |
+| `...args: string[]` | `[args...]` | `a b c` (variadic) |
+
+## CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `-h`, `--help` | Show help with all tasks |
+| `<task> -h` | Show help for a specific task |
+| `-l`, `--list` | List available tasks |
+| `--version` | Show version |
+
+### Task-Specific Help
+
+Get detailed help for any task:
+
+```bash
+invt hello -h
+# Usage: invt hello <name> <count>
+#
+# Say hello with a name and repeat count
+#
+# Arguments:
+#   name            string     (required)
+#   count           number     (required)
+
+invt db:migrate --help
+# Usage: invt db:migrate [direction]
+#
+# Run database migrations
+#
+# Arguments:
+#   direction       string     (optional)
+```
+
+## Context API
+
+Every task receives a `Context` object as the first parameter:
+
+```typescript
+async deploy(c: Context, env: string) {
+  // Run shell commands
+  await c.run("npm run build");
+  
+  // Capture output
+  const { stdout } = await c.run("git rev-parse HEAD", { hide: true });
+  
+  // Ignore errors
+  await c.run("rm -f temp.txt", { warn: true });
+  
+  // Echo command before running
+  await c.run("npm test", { echo: true });
+  
+  // Change directory temporarily
+  for await (const _ of c.cd("subdir")) {
+    await c.run("ls");
+  }
+  
+  // Sudo
+  await c.sudo("apt update");
+  
+  // Access config
+  console.log(c.config);  // { echo: false, warn: false, ... }
+  
+  // local() is alias for run()
+  await c.local("echo hello");
+}
+```
+
+### Context Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `echo` | boolean | false | Print command before execution |
+| `warn` | boolean | false | Don't throw on non-zero exit |
+| `hide` | boolean | false | Capture output instead of printing |
+| `cwd` | string | process.cwd() | Working directory |
+
+### RunResult
+
+```typescript
+interface RunResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+  ok: boolean;      // code === 0
+  failed: boolean;  // code !== 0
+}
+```
+
+## Private Methods
+
+Methods starting with `_` are private and won't appear in help or be callable:
+
+```typescript
+export class Tasks {
+  async publicTask(c: Context) { }
+  async _privateHelper(c: Context) { }  // Hidden
+}
+```
+
+## Testing
+
+```bash
+bun test
+```
+
+## Requirements
+
+- Bun >= 1.0.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "invoket",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "TypeScript task runner for Bun - uses type annotations to parse CLI arguments",
+  "bin": {
+    "invt": "./src/cli.ts"
+  },
+  "exports": {
+    "./context": "./src/context.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "task-runner",
+    "cli",
+    "bun",
+    "typescript",
+    "invoke"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blueshed/invoket"
+  },
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.5"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,483 @@
+#!/usr/bin/env bun
+import { Context } from "./context";
+
+// Supported parameter types
+type ParamType = "string" | "number" | "boolean" | "object" | "array";
+
+// Parameter metadata extracted from TypeScript
+interface ParamMeta {
+  name: string;
+  type: ParamType;
+  required: boolean;
+  isRest: boolean;
+}
+
+interface TaskMeta {
+  description: string;
+  params: ParamMeta[];
+}
+
+interface DiscoveredTasks {
+  root: Map<string, TaskMeta>;
+  namespaced: Map<string, Map<string, TaskMeta>>; // namespace -> method -> meta
+  classDoc: string | null;
+}
+
+// Extract class-level JSDoc for Tasks class
+function extractClassDoc(source: string): string | null {
+  const match = source.match(
+    /\/\*\*\s*([^*]*(?:\*(?!\/)[^*]*)*)\*\/\s*export\s+class\s+Tasks/,
+  );
+  if (!match) return null;
+
+  const lines = match[1]
+    .split("\n")
+    .map((line) => line.replace(/^\s*\*?\s*/, "").trim())
+    .filter((line) => line && !line.startsWith("@"));
+
+  return lines[0] || null;
+}
+
+// Parse command to extract namespace and method
+function parseCommand(command: string): {
+  namespace: string | null;
+  method: string;
+} {
+  const colonIdx = command.indexOf(":");
+  const dotIdx = command.indexOf(".");
+
+  let sepIdx = -1;
+  if (colonIdx !== -1 && dotIdx !== -1) {
+    sepIdx = Math.min(colonIdx, dotIdx);
+  } else if (colonIdx !== -1) {
+    sepIdx = colonIdx;
+  } else if (dotIdx !== -1) {
+    sepIdx = dotIdx;
+  }
+
+  if (sepIdx !== -1) {
+    return {
+      namespace: command.slice(0, sepIdx),
+      method: command.slice(sepIdx + 1),
+    };
+  }
+
+  return { namespace: null, method: command };
+}
+
+// Extract methods from a class definition in source
+function extractMethodsFromClass(
+  source: string,
+  className: string,
+): Map<string, TaskMeta> {
+  const methods = new Map<string, TaskMeta>();
+
+  // Find the class body
+  const classPattern = new RegExp(
+    `class\\s+${className}\\s*(?:extends\\s+\\w+)?\\s*\\{([\\s\\S]*?)\\n\\}`,
+  );
+  const classMatch = source.match(classPattern);
+  if (!classMatch) return methods;
+
+  const classBody = classMatch[1];
+
+  // Match method declarations with JSDoc
+  const methodPattern =
+    /\/\*\*\s*([^*]*(?:\*(?!\/)[^*]*)*)\*\/\s*async\s+(\w+)\s*\(\s*c\s*:\s*Context\s*(?:,\s*([^)]+))?\s*\)/g;
+
+  let match;
+  while ((match = methodPattern.exec(classBody)) !== null) {
+    const [, jsdoc, methodName, paramsStr] = match;
+
+    // Skip private methods and constructor
+    if (methodName.startsWith("_") || methodName === "constructor") {
+      continue;
+    }
+
+    const description =
+      jsdoc
+        .split("\n")
+        .map((line) => line.replace(/^\s*\*?\s*/, "").trim())
+        .filter((line) => line && !line.startsWith("@"))[0] || "";
+
+    const params = parseParams(paramsStr);
+    methods.set(methodName, { description, params });
+  }
+
+  return methods;
+}
+
+// Parse parameter string into ParamMeta array
+function parseParams(paramsStr: string | undefined): ParamMeta[] {
+  const params: ParamMeta[] = [];
+  if (!paramsStr) return params;
+
+  // Check for rest parameter first: ...name: type
+  const restMatch = paramsStr.match(/\.\.\.(\w+)\s*:\s*(\w+\[\]|\w+)/);
+  if (restMatch) {
+    const [, name, rawType] = restMatch;
+    params.push({
+      name,
+      type: rawType.endsWith("[]") ? "array" : "string",
+      required: false,
+      isRest: true,
+    });
+    return params;
+  }
+
+  const paramPattern =
+    /(\w+)\s*:\s*(\w+\[\]|Record<[^>]+>|\{[^}]*\}|string|number|boolean|\w+)(?:\s*=\s*[^,)]+)?/g;
+  let paramMatch;
+
+  while ((paramMatch = paramPattern.exec(paramsStr)) !== null) {
+    const [fullMatch, name, rawType] = paramMatch;
+    const hasDefault = fullMatch.includes("=");
+
+    let type: ParamType;
+    if (rawType === "string") {
+      type = "string";
+    } else if (rawType === "number") {
+      type = "number";
+    } else if (rawType === "boolean") {
+      type = "boolean";
+    } else if (rawType.endsWith("[]")) {
+      type = "array";
+    } else {
+      type = "object";
+    }
+
+    params.push({ name, type, required: !hasDefault, isRest: false });
+  }
+
+  return params;
+}
+
+// Discover all tasks including namespaced ones
+function discoverAllTasks(source: string): DiscoveredTasks {
+  const root = extractMethodsFromClass(source, "Tasks");
+  const namespaced = new Map<string, Map<string, TaskMeta>>();
+  const classDoc = extractClassDoc(source);
+
+  // Find namespace assignments in Tasks class: propertyName = new ClassName()
+  const nsPattern = /(\w+)\s*=\s*new\s+(\w+)\s*\(\s*\)/g;
+  let nsMatch;
+
+  while ((nsMatch = nsPattern.exec(source)) !== null) {
+    const [, propName, className] = nsMatch;
+
+    // Skip private namespaces
+    if (propName.startsWith("_")) continue;
+
+    const nsMethods = extractMethodsFromClass(source, className);
+    if (nsMethods.size > 0) {
+      namespaced.set(propName, nsMethods);
+    }
+  }
+
+  return { root, namespaced, classDoc };
+}
+
+// Parse TypeScript source to extract method signatures and types (legacy, for compatibility)
+async function extractTaskMeta(source: string): Promise<Map<string, TaskMeta>> {
+  const { root, namespaced } = discoverAllTasks(source);
+
+  // Combine root and namespaced for backward compat
+  const all = new Map(root);
+  for (const [ns, methods] of namespaced) {
+    for (const [method, meta] of methods) {
+      all.set(method, meta); // This flattens - we'll fix in main()
+    }
+  }
+
+  return all;
+}
+
+// Convert CLI arg to typed value
+function coerceArg(value: string, type: ParamType): unknown {
+  switch (type) {
+    case "number": {
+      if (value === "") {
+        throw new Error(`Expected number, got ""`);
+      }
+      const n = Number(value);
+      if (Number.isNaN(n)) {
+        throw new Error(`Expected number, got "${value}"`);
+      }
+      return n;
+    }
+    case "boolean":
+      if (value === "true" || value === "1") return true;
+      if (value === "false" || value === "0") return false;
+      throw new Error(`Expected boolean, got "${value}"`);
+    case "object":
+    case "array": {
+      try {
+        const parsed = JSON.parse(value);
+        if (type === "array" && !Array.isArray(parsed)) {
+          throw new Error(`Expected array, got ${typeof parsed}`);
+        }
+        if (
+          type === "object" &&
+          (typeof parsed !== "object" ||
+            Array.isArray(parsed) ||
+            parsed === null)
+        ) {
+          throw new Error(
+            `Expected object, got ${Array.isArray(parsed) ? "array" : typeof parsed}`,
+          );
+        }
+        return parsed;
+      } catch (e) {
+        if (e instanceof SyntaxError) {
+          throw new Error(`Invalid JSON: ${e.message}`);
+        }
+        throw e;
+      }
+    }
+    case "string":
+    default:
+      return value;
+  }
+}
+
+// Format param for help display
+function formatParam(param: ParamMeta): string {
+  if (param.isRest) {
+    return `[${param.name}...]`;
+  }
+  return param.required ? `<${param.name}>` : `[${param.name}]`;
+}
+
+// Display help for a specific task
+function showTaskHelp(command: string, meta: TaskMeta): void {
+  const paramStr = meta.params.map(formatParam).join(" ");
+  const signature = paramStr ? `${command} ${paramStr}` : command;
+
+  console.log(`Usage: invt ${signature}\n`);
+
+  if (meta.description) {
+    console.log(`${meta.description}\n`);
+  }
+
+  if (meta.params.length > 0) {
+    console.log("Arguments:");
+    for (const param of meta.params) {
+      const reqStr = param.required ? "(required)" : "(optional)";
+      const typeStr = param.isRest ? `${param.type}...` : param.type;
+      console.log(`  ${param.name.padEnd(15)} ${typeStr.padEnd(10)} ${reqStr}`);
+    }
+  }
+}
+
+// Main CLI entry point
+async function main() {
+  const args = Bun.argv.slice(2);
+
+  // --version flag
+  if (args[0] === "--version") {
+    const pkgPath = new URL("../package.json", import.meta.url).pathname;
+    const pkg = await Bun.file(pkgPath).json();
+    console.log(pkg.version);
+    return;
+  }
+
+  // Find tasks.ts
+  const tasksPath = Bun.resolveSync("./tasks.ts", process.cwd());
+  const source = await Bun.file(tasksPath).text();
+
+  // Discover all tasks including namespaced
+  const discovered = discoverAllTasks(source);
+
+  // Import and instantiate Tasks class
+  const { Tasks } = await import(tasksPath);
+  const instance = new Tasks();
+  const context = new Context();
+
+  // No args or just help flag -> show general help
+  if (
+    args.length === 0 ||
+    (args.length === 1 && (args[0] === "-h" || args[0] === "--help"))
+  ) {
+    console.log("invoket — TypeScript task runner\n");
+
+    if (discovered.classDoc) {
+      console.log(`${discovered.classDoc}\n`);
+    }
+
+    console.log("Available tasks:\n");
+
+    // Root tasks
+    for (const [name, meta] of discovered.root) {
+      const paramStr = meta.params.map(formatParam).join(" ");
+      const signature = paramStr ? `${name} ${paramStr}` : name;
+      console.log(`  ${signature}`);
+    }
+
+    // Namespaced tasks
+    for (const [ns, methods] of discovered.namespaced) {
+      console.log(`\n${ns}:`);
+      for (const [name, meta] of methods) {
+        const paramStr = meta.params.map(formatParam).join(" ");
+        const signature = paramStr
+          ? `${ns}:${name} ${paramStr}`
+          : `${ns}:${name}`;
+        console.log(`  ${signature}`);
+      }
+    }
+
+    console.log("\nUsage: invt <task> [args...]");
+    console.log("       invt <task> -h   Show help for a specific task");
+    return;
+  }
+
+  // List flag
+  if (args[0] === "-l" || args[0] === "--list") {
+    console.log("Available tasks:\n");
+
+    // Root tasks
+    for (const [name, meta] of discovered.root) {
+      const paramStr = meta.params.map(formatParam).join(" ");
+      const signature = paramStr ? `${name} ${paramStr}` : name;
+      console.log(`  ${signature}`);
+    }
+
+    // Namespaced tasks
+    for (const [ns, methods] of discovered.namespaced) {
+      console.log(`\n${ns}:`);
+      for (const [name, meta] of methods) {
+        const paramStr = meta.params.map(formatParam).join(" ");
+        const signature = paramStr
+          ? `${ns}:${name} ${paramStr}`
+          : `${ns}:${name}`;
+        console.log(`  ${signature}`);
+      }
+    }
+    return;
+  }
+
+  const command = args[0];
+  const taskArgs = args.slice(1);
+
+  // Check if asking for task-specific help: invt hello -h
+  const wantsTaskHelp = taskArgs.includes("-h") || taskArgs.includes("--help");
+
+  const { namespace, method: methodName } = parseCommand(command);
+
+  let meta: TaskMeta | undefined;
+  let method: Function | undefined;
+  let thisArg: any = instance;
+
+  if (namespace) {
+    // Validate namespace
+    if (namespace.startsWith("_")) {
+      console.error(`Cannot call private namespace "${namespace}"`);
+      process.exit(1);
+    }
+
+    // Validate method
+    if (methodName.startsWith("_")) {
+      console.error(`Cannot call private method "${methodName}"`);
+      process.exit(1);
+    }
+
+    const nsMethods = discovered.namespaced.get(namespace);
+    if (!nsMethods) {
+      console.error(`Unknown namespace: ${namespace}`);
+      process.exit(1);
+    }
+
+    meta = nsMethods.get(methodName);
+    if (!meta) {
+      console.error(`Unknown task: ${command}`);
+      console.error(
+        `Available in ${namespace}: ${[...nsMethods.keys()].join(", ")}`,
+      );
+      process.exit(1);
+    }
+
+    thisArg = instance[namespace];
+    method = thisArg[methodName];
+  } else {
+    // Root task
+    if (methodName.startsWith("_")) {
+      console.error(`Cannot call private method "${methodName}"`);
+      process.exit(1);
+    }
+
+    meta = discovered.root.get(methodName);
+    method = instance[methodName];
+
+    // If method exists at runtime but not in source (inherited), allow it
+    if (!meta && typeof method === "function") {
+      // Inherited method - no type info, treat all args as strings
+      meta = { description: "", params: [] };
+    } else if (!meta) {
+      console.error(`Unknown task: ${command}`);
+      const allTasks = [...discovered.root.keys()];
+      for (const [ns, methods] of discovered.namespaced) {
+        for (const m of methods.keys()) {
+          allTasks.push(`${ns}:${m}`);
+        }
+      }
+      console.error(`Available: ${allTasks.join(", ")}`);
+      process.exit(1);
+    }
+  }
+
+  if (typeof method !== "function") {
+    console.error(`Task "${command}" is not a function`);
+    process.exit(1);
+  }
+
+  // Show task-specific help if requested
+  if (wantsTaskHelp) {
+    showTaskHelp(command, meta);
+    return;
+  }
+
+  // Validate and coerce arguments
+  const coercedArgs: unknown[] = [];
+
+  for (let i = 0; i < meta.params.length; i++) {
+    const param = meta.params[i];
+
+    // Handle rest parameters - collect all remaining args and spread them
+    if (param.isRest) {
+      const restArgs = taskArgs.slice(i);
+      coercedArgs.push(...restArgs);
+      break;
+    }
+
+    const arg = taskArgs[i];
+
+    if (arg === undefined) {
+      if (param.required) {
+        console.error(
+          `Missing required argument: <${param.name}> (${param.type})`,
+        );
+        const paramStr = meta.params.map(formatParam).join(" ");
+        console.error(`Usage: ${command} ${paramStr}`);
+        process.exit(1);
+      }
+      // Optional param not provided, don't push (use default)
+      break;
+    }
+
+    try {
+      coercedArgs.push(coerceArg(arg, param.type));
+    } catch (e) {
+      console.error(`Argument "${param.name}": ${(e as Error).message}`);
+      process.exit(1);
+    }
+  }
+
+  // Execute task
+  try {
+    await method.call(thisArg, context, ...coercedArgs);
+  } catch (e) {
+    console.error(`Error running "${command}": ${(e as Error).message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/context.ts

@@ -0,0 +1,88 @@
+import { $ } from "bun";
+import { resolve } from "path";
+
+export interface RunResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+  ok: boolean;
+  failed: boolean;
+}
+
+export interface RunOptions {
+  echo?: boolean;
+  warn?: boolean;
+  hide?: boolean;
+  cwd?: string;
+}
+
+export class Context {
+  cwd: string;
+  private options: RunOptions;
+
+  constructor(options: RunOptions = {}) {
+    this.cwd = options.cwd ?? process.cwd();
+    this.options = options;
+  }
+
+  get pwd(): string {
+    return this.cwd;
+  }
+
+  get config(): RunOptions {
+    return { ...this.options };
+  }
+
+  // Alias for run() - explicit local execution
+  local = this.run.bind(this);
+
+  async run(command: string, options?: RunOptions): Promise<RunResult> {
+    const opts = { ...this.options, ...options };
+
+    if (opts.echo) {
+      console.log(`$ ${command}`);
+    }
+
+    const result = await $`sh -c ${command}`
+      .cwd(opts.cwd ?? this.cwd)
+      .nothrow()
+      .quiet();
+
+    const runResult: RunResult = {
+      stdout: result.stdout.toString(),
+      stderr: result.stderr.toString(),
+      code: result.exitCode,
+      ok: result.exitCode === 0,
+      failed: result.exitCode !== 0,
+    };
+
+    if (!opts.warn && runResult.failed) {
+      const error = new Error(
+        `Command failed with exit code ${runResult.code}: ${command}`,
+      );
+      (error as any).result = runResult;
+      throw error;
+    }
+
+    if (!opts.hide) {
+      if (runResult.stdout) process.stdout.write(runResult.stdout);
+      if (runResult.stderr) process.stderr.write(runResult.stderr);
+    }
+
+    return runResult;
+  }
+
+  async sudo(command: string, options?: RunOptions): Promise<RunResult> {
+    return this.run(`sudo ${command}`, options);
+  }
+
+  async *cd(directory: string): AsyncGenerator<void, void, unknown> {
+    const previous = this.cwd;
+    this.cwd = resolve(this.cwd, directory);
+    try {
+      yield;
+    } finally {
+      this.cwd = previous;
+    }
+  }
+}