invoket 0.1.7 → 0.1.8

package/README.md

@@ -1,74 +1,91 @@
 # invoket
 
-A TypeScript task runner for Bun that uses type annotations to parse CLI arguments.
+TypeScript task runner for Bun. Write typed methods, get a CLI for free.
 
-## 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
+```typescript
+import { Context } from "invoket/context";
 
-## Installation
+export class Tasks {
+  /** Deploy to an environment */
+  async deploy(c: Context, env: string, force: boolean = false) {
+    await c.run(`deploy.sh ${env}${force ? " --force" : ""}`);
+  }
+}
+```
 
 ```bash
-bun link invoket
+$ invt deploy prod --force
 ```
 
-## Quick Start
+No config files. No argument parser boilerplate. Your TypeScript types *are* the CLI definition.
+
+## Why not just write a script?
+
+You could. But then you write arg parsing, help text, and error handling every time. With invoket, you write a method and get all three for free. Your `tasks.ts` becomes a growing toolbox — every task documented, discoverable via `invt --help`, and callable by name with typed arguments.
+
+One script solves one problem. A `tasks.ts` file is a project's command centre.
+
+## Installation
 
 ```bash
-invt                    # Show help
-invt hello World 3      # Run task with args
-invt db:migrate up      # Run namespaced task
-invt --version          # Show version
+bun add -d invoket    # Add to project
+bun link invoket      # Or link globally for development
 ```
 
-## Writing Tasks
+## Quick Start
 
-Create a `tasks.ts` file with a `Tasks` class:
+Create `tasks.ts`:
 
 ```typescript
 import { Context } from "invoket/context";
 
-interface SearchParams {
-  query: string;
-  limit?: number;
-}
-
 /**
- * Project build and deployment tasks
+ * My project tasks
  */
 export class Tasks {
-  /** Say hello with a name and repeat count */
-  async hello(c: Context, name: string, count: number) {
+  /**
+   * Say hello
+   * @flag name -n
+   * @flag count -c
+   */
+  async hello(c: Context, name: string, count: number = 1) {
     for (let i = 0; i < count; i++) {
       console.log(`Hello, ${name}!`);
     }
   }
 
   /** Search with JSON parameters */
-  async search(c: Context, entity: string, params: SearchParams) {
+  async search(c: Context, entity: string, params: { query: string; limit?: number }) {
     console.log(`Searching ${entity}: ${params.query}`);
   }
 
-  /** Install packages (rest params) */
+  /** Install packages */
   async install(c: Context, ...packages: string[]) {
     for (const pkg of packages) {
-      await c.run(`npm install ${pkg}`);
+      await c.run(`bun add ${pkg}`);
     }
   }
 }
 ```
 
+Run it:
+
+```bash
+invt                              # Show help
+invt hello World                  # Positional args
+invt hello -n World -c 3          # Short flags
+invt hello --name=World --count=3 # Long flags
+invt search users '{"query":"bob"}' # JSON params
+invt install react vue angular    # Rest params
+invt hello -h                     # Task-specific help
+```
+
 ## Namespaces
 
-Organize related tasks into namespaces:
+Group related tasks:
 
 ```typescript
-class DbNamespace {
+class Db {
   /** Run database migrations */
   async migrate(c: Context, direction: string = "up") {
     await c.run(`prisma migrate ${direction}`);
@@ -81,128 +98,383 @@ class DbNamespace {
 }
 
 export class Tasks {
-  db = new DbNamespace();
+  db = new Db();
 }
 ```
 
-Call with `invt db:migrate up` or `invt db.seed`.
+```bash
+invt db:migrate up    # colon separator
+invt db.seed          # dot separator also works
+```
 
-## Type Mapping
+## Arguments
 
-| TypeScript | CLI Display | Example Input |
-|------------|-------------|---------------|
-| `name: string` | `<name>` | `hello` |
-| `name: string = "default"` | `[name]` | `hello` (optional) |
+### Type Mapping
+
+| TypeScript | CLI | Example |
+|------------|-----|---------|
+| `name: string` | `<name>` (required) | `hello` |
+| `name: string = "default"` | `[name]` (optional) | `hello` |
 | `count: number` | `<count>` | `42` |
-| `force: boolean` | `<force>` | `true` or `1` |
+| `force: boolean` | `<force>` | `true`, `1`, `false`, `0` |
 | `params: SomeInterface` | `<params>` | `'{"key": "value"}'` |
-| `items: string[]` | `<items>` | `'["a", "b", "c"]'` |
-| `...args: string[]` | `[args...]` | `a b c` (variadic) |
-
-## CLI Flags
+| `items: string[]` | `<items>` | `'["a", "b"]'` |
+| `...args: string[]` | `[args...]` (variadic) | `a b c` |
 
-| 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 |
+### Flags
 
-### Task-Specific Help
+Every parameter automatically gets a `--long` flag. Add `@flag` annotations for short flags and aliases:
 
-Get detailed help for any task:
+```typescript
+/**
+ * @flag env -e --environment
+ * @flag force -f
+ */
+async deploy(c: Context, env: string, force: boolean = false) {}
+```
 
 ```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)
+invt deploy prod                       # positional
+invt deploy --env=prod --force         # long flags
+invt deploy -e prod -f                 # short flags
+invt deploy --environment=prod         # alias
+invt deploy --no-force                 # boolean negation
+invt deploy --force=false              # explicit boolean
+invt install -- --not-a-flag           # -- stops flag parsing
 ```
 
+Flags and positional args can be freely mixed in any order.
+
+### CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `-h`, `--help` | Show all tasks |
+| `<task> -h` | Help for a specific task |
+| `-l`, `--list` | List tasks |
+| `--version` | Show version |
+
 ## Context API
 
-Every task receives a `Context` object as the first parameter:
+Every task receives a `Context` for shell execution:
 
 ```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("npm run build");                          // run command
+  const { stdout } = await c.run("git rev-parse HEAD", { hide: true }); // capture output
+  await c.run("rm -f temp.txt", { warn: true });         // ignore errors
+  await c.run("npm test", { echo: true });                // echo before running
+  await c.run("make", { stream: true });                  // stream output in real-time
+
+  for await (const _ of c.cd("subdir")) {                 // temporary cd
     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");
+
+  await c.sudo("apt update");                             // sudo prefix
+  await c.local("echo hello");                            // alias for run()
 }
 ```
 
-### Context Options
+### 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 |
+| `stream` | boolean | false | Stream output in real-time |
+| `cwd` | string | `process.cwd()` | Working directory |
 
 ### RunResult
 
 ```typescript
 interface RunResult {
-  stdout: string;
+  stdout: string;    // captured output (empty when streaming)
   stderr: string;
   code: number;
-  ok: boolean;      // code === 0
-  failed: boolean;  // code !== 0
+  ok: boolean;       // code === 0
+  failed: boolean;   // code !== 0
+}
+```
+
+### Error Handling
+
+Failed commands throw `CommandError`:
+
+```typescript
+import { CommandError } from "invoket/context";
+
+try {
+  await c.run("exit 1");
+} catch (e) {
+  if (e instanceof CommandError) {
+    console.log(e.result.code);   // 1
+    console.log(e.result.stderr);
+  }
 }
 ```
 
+Use `{ warn: true }` to suppress throws and inspect the result instead.
+
 ## Private Methods
 
-Methods starting with `_` are private and won't appear in help or be callable:
+Prefix with `_` to hide from CLI:
 
 ```typescript
 export class Tasks {
-  async publicTask(c: Context) { }
-  async _privateHelper(c: Context) { }  // Hidden
+  async publicTask(c: Context) {
+    this._helper();
+  }
+  async _helper() { }  // not discoverable, not callable via CLI
 }
 ```
 
-## Testing
+## Patterns
+
+### Project setup
+
+```typescript
+/** Bootstrap dev environment */
+async setup(c: Context) {
+  await c.run("bun install");
+  await c.run("cp .env.example .env", { warn: true });
+  await c.run("bun run db:migrate");
+  console.log("Ready to go!");
+}
+```
+
+### Git workflow
+
+```typescript
+/**
+ * Commit and push current branch
+ * @flag message -m
+ */
+async ship(c: Context, message: string) {
+  const { stdout } = await c.run("git branch --show-current", { hide: true });
+  await c.run("git add -A");
+  await c.run(`git commit -m "${message}"`);
+  await c.run(`git push -u origin ${stdout.trim()}`);
+}
+```
+
+### Run with fallback
+
+```typescript
+/** Lint and fix */
+async lint(c: Context) {
+  const result = await c.run("eslint . --fix", { warn: true, hide: true });
+  if (result.failed) {
+    console.log("Lint errors remain:");
+    console.log(result.stdout);
+  }
+}
+```
+
+### Capture and transform
+
+```typescript
+/** Show outdated deps */
+async deps(c: Context) {
+  const { stdout } = await c.run("bun outdated --json", { hide: true, warn: true });
+  const deps = JSON.parse(stdout || "[]");
+  for (const d of deps) console.log(`${d.name}: ${d.current} → ${d.latest}`);
+}
+```
+
+### Scaffold files
+
+```typescript
+/** @flag name -n */
+async component(c: Context, name: string) {
+  const upper = name[0].toUpperCase() + name.slice(1);
+  await c.run(`mkdir -p src/components/${name}`);
+  await c.run(`cat > src/components/${name}/index.tsx << 'EOF'
+export function ${upper}() {
+  return <div>${upper}</div>;
+}
+EOF`);
+  console.log(`Created src/components/${name}/index.tsx`);
+}
+```
+
+## Agentic Tools
+
+invoket shines as a toolbox for AI agents. Instead of writing ad-hoc scripts each session, the agent adds methods to `tasks.ts` that persist across sessions. `invt --help` shows what tools are available. The file becomes the project's growing command centre.
+
+### Memory — persist context across sessions
+
+```typescript
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+
+class Memory {
+  private dir = ".memory";
+
+  private ensure() {
+    if (!existsSync(this.dir)) mkdirSync(this.dir, { recursive: true });
+  }
+
+  /** Store a value by key */
+  async store(c: Context, key: string, ...value: string[]) {
+    this.ensure();
+    writeFileSync(`${this.dir}/${key}.md`, value.join(" "));
+    console.log(`Stored: ${key}`);
+  }
+
+  /** Recall a value by key */
+  async recall(c: Context, key: string) {
+    const path = `${this.dir}/${key}.md`;
+    if (!existsSync(path)) { console.log(`Not found: ${key}`); return; }
+    console.log(readFileSync(path, "utf-8"));
+  }
+
+  /** List all stored keys */
+  async list(c: Context) {
+    this.ensure();
+    const { stdout } = await c.run(`ls ${this.dir}`, { hide: true, warn: true });
+    console.log(stdout || "(empty)");
+  }
+}
+
+export class Tasks {
+  memory = new Memory();
+}
+```
 
 ```bash
-bun test
+invt memory:store arch "Monorepo with packages/api and packages/web"
+invt memory:recall arch
+invt memory:list
 ```
 
+### Task planning — break work into steps
+
+```typescript
+import { existsSync, readFileSync, writeFileSync } from "fs";
+
+class Plan {
+  private file = ".plan.json";
+
+  private load(): { task: string; done: boolean }[] {
+    if (!existsSync(this.file)) return [];
+    return JSON.parse(readFileSync(this.file, "utf-8"));
+  }
+
+  private save(tasks: { task: string; done: boolean }[]) {
+    writeFileSync(this.file, JSON.stringify(tasks, null, 2));
+  }
+
+  /** Add a step to the plan */
+  async add(c: Context, ...task: string[]) {
+    const tasks = this.load();
+    tasks.push({ task: task.join(" "), done: false });
+    this.save(tasks);
+    console.log(`Added step ${tasks.length}: ${task.join(" ")}`);
+  }
+
+  /** Mark step as done */
+  async done(c: Context, step: number) {
+    const tasks = this.load();
+    tasks[step - 1].done = true;
+    this.save(tasks);
+    console.log(`Done: ${tasks[step - 1].task}`);
+  }
+
+  /** Show the plan */
+  async show(c: Context) {
+    const tasks = this.load();
+    if (!tasks.length) { console.log("No plan yet."); return; }
+    for (const [i, t] of tasks.entries()) {
+      console.log(`${t.done ? "✓" : " "} ${i + 1}. ${t.task}`);
+    }
+  }
+
+  /** Clear the plan */
+  async clear(c: Context) {
+    this.save([]);
+    console.log("Plan cleared.");
+  }
+}
+
+export class Tasks {
+  plan = new Plan();
+}
+```
+
+```bash
+invt plan:add "Set up database schema"
+invt plan:add "Write API endpoints"
+invt plan:add "Add tests"
+invt plan:show
+invt plan:done 1
+```
+
+### Session journal — log decisions
+
+```typescript
+import { appendFileSync, existsSync, readFileSync } from "fs";
+
+class Journal {
+  private file = ".journal.md";
+
+  /** Log a decision or finding */
+  async log(c: Context, ...entry: string[]) {
+    const ts = new Date().toISOString().slice(0, 16);
+    appendFileSync(this.file, `\n## ${ts}\n\n${entry.join(" ")}\n`);
+    console.log("Logged.");
+  }
+
+  /** Show recent entries */
+  async show(c: Context) {
+    if (!existsSync(this.file)) { console.log("No journal yet."); return; }
+    console.log(readFileSync(this.file, "utf-8"));
+  }
+}
+
+export class Tasks {
+  journal = new Journal();
+}
+```
+
+```bash
+invt journal:log "Chose Postgres over SQLite for concurrent writes"
+invt journal:show
+```
+
+### Codebase search — structured context gathering
+
+```typescript
+class Search {
+  /** Find files matching a pattern */
+  async files(c: Context, pattern: string) {
+    await c.run(`find . -name "${pattern}" -not -path "*/node_modules/*"`, { stream: true });
+  }
+
+  /** Search code for a pattern */
+  async code(c: Context, pattern: string, ...glob: string[]) {
+    const g = glob.length ? `--glob '${glob.join("' --glob '")}'` : "";
+    await c.run(`rg "${pattern}" ${g} --type-not binary`, { stream: true, warn: true });
+  }
+
+  /** Summarise project structure */
+  async tree(c: Context) {
+    await c.run("find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | head -50", { stream: true });
+  }
+}
+
+export class Tasks {
+  search = new Search();
+}
+```
+
+```bash
+invt search:code "async.*Context" "*.ts"
+invt search:files "*.test.ts"
+invt search:tree
+```
+
+These tasks persist in the project. Every session, the agent starts with `invt --help` and has its full toolbox ready.
+
 ## Requirements
 
 - Bun >= 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "invoket",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "description": "TypeScript task runner for Bun - uses type annotations to parse CLI arguments",
   "bin": {