invoket 0.1.9 → 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "invoket",
-  "version": "0.1.9",
+  "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

@@ -27,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 */
@@ -41,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);
   }