kadai 0.2.0 → 0.4.0

package/README.md

@@ -1,4 +1,4 @@
-<img width="1024" height="1024" alt="image" src="https://github.com/user-attachments/assets/daa548e6-5984-4cde-93d3-7c4684de639a" />
+<img width="919" height="228" alt="image" src="https://github.com/user-attachments/assets/2c1fca9f-3484-409f-b3b4-214edc0387a4" />
 
 # kadai
 
@@ -6,8 +6,6 @@ A terminal UI for discovering and running project scripts. Drop scripts into `.k
 
 ## Getting Started
 
-<img width="950" height="205" alt="image" src="https://github.com/user-attachments/assets/b694bfaa-146b-41c7-a44c-d197c7cea08e" />
-
 ```bash
 bunx kadai
 # OR
@@ -33,11 +31,12 @@ On first run, kadai creates a `.kadai/` directory with a sample action and confi
 
 ### Supported Runtimes
 
-| Extension          | Runtime  |
-|--------------------|----------|
-| `.sh`, `.bash`     | bash     |
-| `.ts`, `.js`, `.mjs` | bun   |
-| `.py`              | python   |
+| Extension            | Runtime |
+|----------------------|---------|
+| `.sh`, `.bash`       | bash    |
+| `.ts`, `.js`, `.mjs` | bun     |
+| `.py`                | python  |
+| `.tsx`               | ink     |
 
 Shebangs are respected — if your script has `#!/usr/bin/env python3`, kadai uses that directly. Otherwise it finds the best available interpreter automatically (e.g. `uv run` before `python3` for `.py` files).
 
@@ -68,15 +67,59 @@ For JS/TS, use `//` comments:
 | `description` | string  | Short description                          |
 | `confirm`     | boolean | Require confirmation before running        |
 | `hidden`      | boolean | Hide from menu (still runnable via CLI)    |
-| `interactive` | boolean | Hand over the full terminal to the script  |
+| `fullscreen`  | boolean | Use alternate screen buffer (`.tsx` only)  |
+
+### Ink TUI Actions
+
+`.tsx` files let you build interactive terminal UIs that render directly inside kadai. Export a default React component that receives `InkActionProps`:
+
+```tsx
+// kadai:name Todo List
+// kadai:emoji ✅
+// kadai:description Manage project tasks
+import { Box, Text, useInput } from "ink";
+import { useState } from "react";
+import type { InkActionProps } from "kadai/types";
+
+export default function TodoList({ onExit }: InkActionProps) {
+  const [items] = useState(["Buy groceries", "Write code"]);
+  const [cursor, setCursor] = useState(0);
+
+  useInput((input, key) => {
+    if (key.upArrow) setCursor((c) => Math.max(0, c - 1));
+    if (key.downArrow) setCursor((c) => Math.min(items.length - 1, c + 1));
+    if (input === "q") onExit();
+  });
+
+  return (
+    <Box flexDirection="column">
+      {items.map((item, i) => (
+        <Text key={item} color={i === cursor ? "cyan" : undefined}>
+          {i === cursor ? "❯ " : "  "}{item}
+        </Text>
+      ))}
+      <Text dimColor>↑↓ navigate  q quit</Text>
+    </Box>
+  );
+}
+```
+
+Your component receives these props:
 
-### Interactive Scripts
+| Prop    | Type                       | Description                              |
+|---------|----------------------------|------------------------------------------|
+| `cwd`   | `string`                   | Working directory kadai was launched from |
+| `env`   | `Record<string, string>`   | Environment variables from kadai config  |
+| `args`  | `string[]`                 | Additional arguments passed to the action |
+| `onExit`| `() => void`               | Call this to return to the kadai menu     |
 
-Scripts marked `interactive` get full terminal control — kadai exits its UI, runs the script with inherited stdio, then returns to the menu. Use this for scripts that need user input (readline prompts, password entry, etc.).
+By default, ink actions render inline within kadai's UI. Add `kadai:fullscreen true` to use the terminal's alternate screen buffer — the action takes over the full screen and restores the previous view on exit:
 
-### Ink UI Actions (Planned)
+```tsx
+// kadai:fullscreen true
+```
 
-`.tsx` files will be able to export an Ink component that renders directly inside kadai's UI, enabling rich interactive interfaces (forms, progress bars, tables) without spawning a subprocess.
+See `.kadai/actions/` in this repo for working examples.
 
 ### Config
 
@@ -98,13 +141,29 @@ kadai                    # Interactive menu
 kadai list --json        # List actions as JSON
 kadai list --json --all  # Include hidden actions
 kadai run <action-id>    # Run an action directly
+kadai mcp                # Start MCP server (creates .mcp.json)
 ```
 
 ## AI
 
 kadai is designed to work well with AI coding agents like Claude Code.
 
-### How It Works
+### MCP Server
+
+kadai includes a built-in [MCP](https://modelcontextprotocol.io/) server that exposes your actions as tools. Any MCP-compatible client (Claude Code, Claude Desktop, etc.) can auto-discover and run your project's actions.
+
+kadai will automatically configure a `.mcp.json` file in your project root so Claude can automatically discover any `kadai` actions you define.
+
+```bash
+kadai mcp
+```
+
+This creates the `.mcp.json` in your project root if it doesn't already exist (so `claude` will autodiscover it.)
+It then starts the `mcp` server (this is the command `claude` uses to invoke `kadai` MCP.)
+
+Each action becomes an MCP tool. Nested action IDs use `--` as a separator (e.g. `database/reset` becomes the tool `database--reset`) since MCP tool names don't allow slashes.
+
+### JSON API
 
 - `kadai list --json` gives agents a machine-readable list of available project actions
 - `kadai run <action-id>` runs actions non-interactively (confirmation prompts auto-skip in non-TTY)