invoket 0.1.7 → 0.1.9

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,349 @@ 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
+```
+
+## Arguments
 
-## Type Mapping
+### Type Mapping
 
-| TypeScript | CLI Display | Example Input |
-|------------|-------------|---------------|
-| `name: string` | `<name>` | `hello` |
-| `name: string = "default"` | `[name]` | `hello` (optional) |
+| 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) |
+| `items: string[]` | `<items>` | `'["a", "b"]'` |
+| `...args: string[]` | `[args...]` (variadic) | `a b c` |
 
-## CLI Flags
+### 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
+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
+}
+```
+
+## 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!");
 }
 ```
 
-## Testing
+### 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
+
+AI agents like Claude Code have built-in tools for searching files, reading code, and running commands. What they lack is **project context** — the state of migrations, the history of decisions, the shape of your API, which tests are flaky and why. That knowledge lives in developers' heads, scattered across commits, issues, and Slack threads.
+
+invoket lets you build a **structured, queryable project knowledge base** that agents can read and write through the same CLI interface humans use. Bun's built-in SQLite makes this trivial — no external database, no setup, just a `.ctx.db` file that travels with the project.
+
+### Project context — a SQLite-backed knowledge base
+
+```typescript
+import { Context } from "invoket/context";
+import { Database } from "bun:sqlite";
+
+class Ctx {
+  private db: Database;
+
+  constructor() {
+    this.db = new Database(".ctx.db", { create: true });
+    this.db.run(`CREATE TABLE IF NOT EXISTS context (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updated_at TEXT DEFAULT (datetime('now'))
+    )`);
+    this.db.run(`CREATE TABLE IF NOT EXISTS decisions (
+      id INTEGER PRIMARY KEY,
+      subject TEXT NOT NULL,
+      decision TEXT NOT NULL,
+      rationale TEXT,
+      status TEXT DEFAULT 'active',
+      created_at TEXT DEFAULT (datetime('now'))
+    )`);
+  }
+
+  /** Store a key-value fact about the project */
+  async set(c: Context, key: string, ...value: string[]) {
+    this.db.run(
+      `INSERT OR REPLACE INTO context (key, value, updated_at)
+       VALUES (?, ?, datetime('now'))`,
+      [key, value.join(" ")]
+    );
+    console.log(`Set: ${key}`);
+  }
+
+  /** Retrieve a fact */
+  async get(c: Context, key: string) {
+    const row = this.db.query("SELECT value, updated_at FROM context WHERE key = ?").get(key) as any;
+    if (!row) { console.log(`Not found: ${key}`); return; }
+    console.log(`${row.value}  (${row.updated_at})`);
+  }
+
+  /** Search facts by keyword */
+  async search(c: Context, ...terms: string[]) {
+    const pattern = `%${terms.join(" ")}%`;
+    const rows = this.db.query(
+      "SELECT key, value FROM context WHERE key LIKE ? OR value LIKE ?"
+    ).all(pattern, pattern) as any[];
+    for (const r of rows) console.log(`${r.key}: ${r.value}`);
+  }
+
+  /** Record an architectural decision */
+  async decide(c: Context, subject: string, decision: string, ...rationale: string[]) {
+    this.db.run(
+      "INSERT INTO decisions (subject, decision, rationale) VALUES (?, ?, ?)",
+      [subject, decision, rationale.join(" ")]
+    );
+    console.log(`Recorded: ${subject}`);
+  }
+
+  /** List active decisions */
+  async decisions(c: Context) {
+    const rows = this.db.query(
+      "SELECT id, subject, decision, rationale FROM decisions WHERE status = 'active' ORDER BY created_at DESC"
+    ).all() as any[];
+    for (const r of rows) {
+      console.log(`#${r.id} ${r.subject}: ${r.decision}`);
+      if (r.rationale) console.log(`   ${r.rationale}`);
+    }
+  }
+
+  /** Dump all context as JSON */
+  async dump(c: Context) {
+    const facts = this.db.query("SELECT key, value FROM context ORDER BY key").all();
+    const decisions = this.db.query("SELECT * FROM decisions WHERE status = 'active'").all();
+    console.log(JSON.stringify({ facts, decisions }, null, 2));
+  }
+}
+
+export class Tasks {
+  ctx = new Ctx();
+}
+```
 
 ```bash
-bun test
+# Store project facts
+invt ctx:set db "Postgres 16 on Supabase, migrations in prisma/"
+invt ctx:set api "REST with /api/v2 prefix, auth via JWT middleware"
+invt ctx:set deploy "Fly.io, auto-deploy on push to main"
+
+# Record decisions with rationale
+invt ctx:decide auth "JWT in httpOnly cookies" "Chose over localStorage for XSS protection"
+invt ctx:decide orm "Prisma over Drizzle" "Team familiarity, existing migrations"
+
+# Query context
+invt ctx:get db
+invt ctx:search auth
+invt ctx:decisions
+
+# Dump everything for agent context
+invt ctx:dump
+```
+
+An agent starts a session with `invt ctx:dump` and immediately has structured project knowledge — not flat markdown, not grep results, but queryable facts and decisions with timestamps.
+
+### Why SQLite?
+
+Bun bundles SQLite natively — `import { Database } from "bun:sqlite"` just works. No dependencies, no server, no config. The `.ctx.db` file is a single file you can `.gitignore` or commit. You can extend the schema as the project grows: add tables for endpoints, test history, deployment logs, whatever your project needs.
+
+### Growing the schema
+
+The example above is a starting point. A real project might track more:
+
+```typescript
+// Track API endpoints and their status
+this.db.run(`CREATE TABLE IF NOT EXISTS endpoints (
+  path TEXT PRIMARY KEY,
+  method TEXT,
+  handler TEXT,
+  auth TEXT DEFAULT 'required',
+  status TEXT DEFAULT 'active'
+)`);
+
+// Track test health
+this.db.run(`CREATE TABLE IF NOT EXISTS test_runs (
+  id INTEGER PRIMARY KEY,
+  suite TEXT,
+  passed INTEGER,
+  failed INTEGER,
+  skipped INTEGER,
+  ran_at TEXT DEFAULT (datetime('now'))
+)`);
 ```
 
+The namespace class is the interface. The schema is yours to shape around what your project actually needs to remember.
+
 ## Requirements
 
 - Bun >= 1.0.0

package/package.json

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