invoket 0.1.8 → 0.1.10

package/CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+Add reusable commands to `tasks.ts`. invoket gives them typed args, `--help`, and error handling.
+
+Use invoket when a command will be reused. Write a raw script for throwaway one-offs.
+
+## Task skeleton
+
+```typescript
+import { Context } from "invoket/context";
+
+export class Tasks {
+  /** Description (required — no JSDoc = not discovered) */
+  async taskName(c: Context, required: string, optional: number = 1) {}
+}
+```
+
+`async` + JSDoc + `c: Context` first param. `_prefix` = private.
+
+## Types → CLI
+
+`string` as-is, `number` rejects NaN, `boolean` accepts `true/false/1/0/--flag/--no-flag`, `Interface` and `Record` expect JSON string, `type[]` expects JSON array, `...args: string[]` collects remaining, `= default` and `| null` make optional.
+
+## Flags
+
+Auto: `--paramName`. For short flags add `@flag` in JSDoc:
+
+```typescript
+/** @flag env -e --environment */
+async deploy(c: Context, env: string) {}
+```
+
+## Namespaces
+
+```typescript
+class Db {
+  /** Migrate */
+  async migrate(c: Context, direction: string = "up") {}
+}
+export class Tasks {
+  db = new Db();  // invt db:migrate up
+}
+```
+
+## Context
+
+```typescript
+await c.run(cmd);                        // throw on failure
+await c.run(cmd, { warn: true });        // don't throw
+const { stdout } = await c.run(cmd, { hide: true }); // capture
+await c.run(cmd, { stream: true });      // real-time output
+await c.run(cmd, { echo: true });        // print command first
+await c.sudo(cmd);                       // sudo prefix
+for await (const _ of c.cd(dir)) { }    // temp cd
+```
+
+Result: `{ stdout, stderr, code, ok, failed }`. Failure throws `CommandError` with `.result`.

package/README.md

@@ -28,13 +28,21 @@ One script solves one problem. A `tasks.ts` file is a project's command centre.
 ## Installation
 
 ```bash
-bun add -d invoket    # Add to project
-bun link invoket      # Or link globally for development
+bun add -d invoket     # Add to project (use bunx invt to run)
+bun add -g invoket     # Or install globally (invt available on PATH)
 ```
 
+Then scaffold your project:
+
+```bash
+bunx invt --init       # Creates tasks.ts and CLAUDE.md
+```
+
+`--init` creates a starter `tasks.ts` and copies the `CLAUDE.md` reference card into your project so AI agents know how to write tasks.
+
 ## Quick Start
 
-Create `tasks.ts`:
+Edit `tasks.ts`:
 
 ```typescript
 import { Context } from "invoket/context";
@@ -153,6 +161,7 @@ Flags and positional args can be freely mixed in any order.
 | `<task> -h` | Help for a specific task |
 | `-l`, `--list` | List tasks |
 | `--version` | Show version |
+| `--init` | Scaffold `tasks.ts` and `CLAUDE.md` |
 
 ## Context API
 
@@ -300,180 +309,146 @@ EOF`);
 
 ## 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"));
-  }
+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.
 
-  /** 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)");
-  }
-}
+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.
 
-export class Tasks {
-  memory = new Memory();
-}
-```
-
-```bash
-invt memory:store arch "Monorepo with packages/api and packages/web"
-invt memory:recall arch
-invt memory:list
-```
-
-### Task planning — break work into steps
+### Project context — a SQLite-backed knowledge base
 
 ```typescript
-import { existsSync, readFileSync, writeFileSync } from "fs";
-
-class Plan {
-  private file = ".plan.json";
+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'))
+    )`);
+  }
 
-  private load(): { task: string; done: boolean }[] {
-    if (!existsSync(this.file)) return [];
-    return JSON.parse(readFileSync(this.file, "utf-8"));
+  /** 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}`);
   }
 
-  private save(tasks: { task: string; done: boolean }[]) {
-    writeFileSync(this.file, JSON.stringify(tasks, null, 2));
+  /** 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})`);
   }
 
-  /** 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(" ")}`);
+  /** 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}`);
   }
 
-  /** 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}`);
+  /** 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}`);
   }
 
-  /** 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}`);
+  /** 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}`);
     }
   }
 
-  /** Clear the plan */
-  async clear(c: Context) {
-    this.save([]);
-    console.log("Plan cleared.");
+  /** 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 {
-  plan = new Plan();
+  ctx = new Ctx();
 }
 ```
 
 ```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
+# 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
 ```
 
-### Session journal — log decisions
-
-```typescript
-import { appendFileSync, existsSync, readFileSync } from "fs";
+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.
 
-class Journal {
-  private file = ".journal.md";
+### Why SQLite?
 
-  /** 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"));
-  }
-}
+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.
 
-export class Tasks {
-  journal = new Journal();
-}
-```
-
-```bash
-invt journal:log "Chose Postgres over SQLite for concurrent writes"
-invt journal:show
-```
+### Growing the schema
 
-### Codebase search — structured context gathering
+The example above is a starting point. A real project might track more:
 
 ```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
+// 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'))
+)`);
 ```
 
-These tasks persist in the project. Every session, the agent starts with `invt --help` and has its full toolbox ready.
+The namespace class is the interface. The schema is yours to shape around what your project actually needs to remember.
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "invoket",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "description": "TypeScript task runner for Bun - uses type annotations to parse CLI arguments",
   "bin": {
@@ -10,7 +10,8 @@
     "./context": "./src/context.ts"
   },
   "files": [
-    "src"
+    "src",
+    "CLAUDE.md"
   ],
   "keywords": [
     "task-runner",

package/src/cli.ts

@@ -1,8 +1,12 @@
 #!/usr/bin/env bun
 import { Context } from "./context";
+import { dirname } from "path";
 import {
   discoverAllTasks,
   discoverRuntimeNamespaces,
+  extractImports,
+  extractMethodsFromClass,
+  findUnresolvedNamespaces,
   parseCommand,
   parseCliArgs,
   resolveArgs,
@@ -23,13 +27,18 @@ async function main() {
     return;
   }
 
-  // Find tasks.ts
-  let tasksPath: string;
-  try {
-    tasksPath = Bun.resolveSync("./tasks.ts", process.cwd());
-  } catch {
-    console.log("No tasks.ts found. Create one to get started:\n");
-    console.log(`import { Context } from "invoket/context";
+  // --init flag: scaffold tasks.ts and CLAUDE.md
+  if (args[0] === "--init") {
+    const { existsSync } = await import("fs");
+    const cwd = process.cwd();
+
+    const tasksFile = `${cwd}/tasks.ts`;
+    if (existsSync(tasksFile)) {
+      console.log("tasks.ts already exists, skipping.");
+    } else {
+      await Bun.write(
+        tasksFile,
+        `import { Context } from "invoket/context";
 
 export class Tasks {
   /** Say hello */
@@ -37,7 +46,36 @@ export class Tasks {
     console.log("Hello, World!");
   }
 }
-`);
+`,
+      );
+      console.log("Created tasks.ts");
+    }
+
+    const claudeFile = `${cwd}/CLAUDE.md`;
+    const claudeMdPath = new URL("../CLAUDE.md", import.meta.url).pathname;
+    const claudeMd = await Bun.file(claudeMdPath).text();
+    if (existsSync(claudeFile)) {
+      const existing = await Bun.file(claudeFile).text();
+      if (existing.includes("invoket")) {
+        console.log("CLAUDE.md already has invoket section, skipping.");
+      } else {
+        await Bun.write(claudeFile, existing.trimEnd() + "\n\n" + claudeMd);
+        console.log("Appended invoket guide to CLAUDE.md");
+      }
+    } else {
+      await Bun.write(claudeFile, claudeMd);
+      console.log("Created CLAUDE.md");
+    }
+
+    return;
+  }
+
+  // Find tasks.ts
+  let tasksPath: string;
+  try {
+    tasksPath = Bun.resolveSync("./tasks.ts", process.cwd());
+  } catch {
+    console.log("No tasks.ts found. Run 'invt --init' to get started.");
     process.exit(1);
   }
 
@@ -51,6 +89,24 @@ export class Tasks {
   // Discover all tasks including namespaced
   const discovered = discoverAllTasks(source);
 
+  // Resolve imported namespace classes from their source files
+  const imports = extractImports(source);
+  const unresolved = findUnresolvedNamespaces(source, discovered);
+  for (const [propName, className] of unresolved) {
+    const importPath = imports.get(className);
+    if (!importPath) continue;
+    try {
+      const resolvedPath = Bun.resolveSync(importPath, dirname(tasksPath));
+      const importedSource = await Bun.file(resolvedPath).text();
+      const methods = extractMethodsFromClass(importedSource, className);
+      if (methods.size > 0) {
+        discovered.namespaced.set(propName, methods);
+      }
+    } catch {
+      // Can't resolve import — runtime discovery will handle it
+    }
+  }
+
   // Also discover imported namespaces from runtime
   discoverRuntimeNamespaces(instance, discovered);
 

package/src/parser.ts

@@ -219,6 +219,47 @@ export function parseParams(
   return params;
 }
 
+// Extract import statements: maps imported identifiers to their module paths
+export function extractImports(
+  source: string,
+): Map<string, string> {
+  const imports = new Map<string, string>();
+  const pattern =
+    /import\s+(?!\s*type\s)(?:\{([^}]+)\}|(\w+))\s+from\s+["']([^"']+)["']/g;
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    const [, namedImports, defaultImport, importPath] = match;
+    if (namedImports) {
+      for (const spec of namedImports.split(",")) {
+        const parts = spec.trim().split(/\s+as\s+/);
+        const localName = parts[parts.length - 1].trim();
+        if (localName) imports.set(localName, importPath);
+      }
+    }
+    if (defaultImport) {
+      imports.set(defaultImport, importPath);
+    }
+  }
+  return imports;
+}
+
+// Find namespace assignments whose class wasn't found in the local source
+export function findUnresolvedNamespaces(
+  source: string,
+  discovered: DiscoveredTasks,
+): Map<string, string> {
+  const unresolved = new Map<string, string>(); // propName -> className
+  const nsPattern = /(\w+)\s*=\s*new\s+(\w+)\s*\(\s*\)/g;
+  let match;
+  while ((match = nsPattern.exec(source)) !== null) {
+    const [, propName, className] = match;
+    if (propName.startsWith("_")) continue;
+    if (discovered.namespaced.has(propName)) continue;
+    unresolved.set(propName, className);
+  }
+  return unresolved;
+}
+
 // Discover all tasks including namespaced ones (source parsing only)
 export function discoverAllTasks(source: string): DiscoveredTasks {
   const root = extractMethodsFromClass(source, "Tasks");