camouflage-tui 1.0.0-beta.1

package/README.md

@@ -0,0 +1,142 @@
+# camouflage-tui
+
+Node SDK for [Camouflage](https://github.com/sinameraji/camouflage) — a high-performance terminal renderer for AI agent applications.
+
+If you're building an LLM-powered CLI tool and need streaming chat UI, tool execution display, permission modals, forms, and more — without fighting React Ink's re-render performance — this is for you.
+
+```bash
+npm install camouflage-tui
+```
+
+The `postinstall` script downloads a pre-built native binary for your platform (macOS, Linux). No Rust toolchain required.
+
+## Quick start
+
+```js
+import { mount } from "camouflage-tui";
+
+const cam = await mount();
+
+cam.send("SessionStarted", {});
+cam.send("UserMessageCreated", { text: "investigate failing test" });
+cam.send("AssistantStreamStarted", { stream_id: "s1" });
+cam.send("AssistantTokenDelta", { stream_id: "s1", token: "Looking " });
+cam.send("AssistantTokenDelta", { stream_id: "s1", token: "into it..." });
+cam.send("AssistantMessageCompleted", { stream_id: "s1" });
+
+// Listen for user input typed into the renderer
+cam.on("userInput", (text) => {
+  console.log("user said:", text);
+});
+
+// Listen for permission responses
+cam.on("permissionResponse", ({ request_id, choice, feedback }) => {
+  console.log(`${request_id} → ${choice}`);
+});
+
+await cam.close();
+```
+
+## API
+
+### `mount(opts?) => Promise<CamouflageHandle>`
+
+Spawns the renderer and resolves once the child has spawned. Rejects with
+a friendly error if the binary can't be found.
+
+```ts
+interface MountOptions {
+  bin?: string;              // default: bundled binary, then PATH lookup
+  args?: string[];           // extra args after --stdin-events --emit-responses
+  env?: NodeJS.ProcessEnv;   // merged with process.env
+  inheritStderr?: boolean;   // default true; false → "stderr" event
+  renderToTerminal?: boolean; // true → stdout goes to terminal, responses on fd 3
+}
+```
+
+### `CamouflageHandle`
+
+Extends `EventEmitter`. Send events with `send()`; subscribe to outbound events with `on()`.
+
+| Method                          | What                                            |
+|---------------------------------|-------------------------------------------------|
+| `send(event_type, payload?)`    | Write one event into the renderer.              |
+| `sendEvent({ event_type, payload? })` | Write a pre-built `Event`.                |
+| `close()` → `Promise<number>`   | Graceful shutdown; resolves with exit code.     |
+| `kill(signal?)`                 | Forceful — only if `close()` is wedged.         |
+
+| Event                | Payload                                           |
+|----------------------|---------------------------------------------------|
+| `"userInput"`        | `string` — user typed into the input box         |
+| `"permissionResponse"` | `{ request_id, choice, feedback? }`             |
+| `"selectListResponse"` | `{ id, value?, cancelled }`                     |
+| `"confirmResponse"`   | `{ id, value?, cancelled }`                     |
+| `"formResponse"`      | `{ id, values?, cancelled }`                    |
+| `"wizardCompleted"`   | `{ id, results }`                               |
+| `"wizardCancelled"`   | `{ id, at_step }`                               |
+| `"cancelRequested"`   | `{}` — user pressed Esc                          |
+| `"event"`            | any outbound `Event` (raw)                        |
+| `"exit"`             | `{ code, signal }` — renderer exited             |
+
+### Convenience helpers
+
+```js
+import { mount, selectList, confirm, toast, table, form, wizard } from "camouflage-tui";
+
+const cam = await mount();
+
+// Show a filterable list picker
+const choice = await selectList(cam, {
+  id: "model",
+  prompt: "Choose a model",
+  options: [
+    { value: "gpt-4", label: "GPT-4" },
+    { value: "claude", label: "Claude" },
+  ],
+});
+
+// Show a yes/no confirmation
+const ok = await confirm(cam, { id: "deploy", prompt: "Deploy to production?" });
+
+// Show a brief notification
+toast(cam, "Build succeeded");
+
+// Show a multi-field form
+const creds = await form(cam, {
+  id: "login",
+  title: "API credentials",
+  fields: [
+    { name: "key", label: "API Key", kind: "text" },
+    { name: "secret", label: "Secret", kind: "password" },
+  ],
+});
+```
+
+### Types-only import
+
+Don't need the runtime binding? Import just the protocol types and the
+NDJSON parser helpers — zero subprocess overhead:
+
+```ts
+import { Event, reader, validate, encode } from "camouflage-tui/types";
+```
+
+## Migration from Ink
+
+If you're replacing a React/Ink TUI:
+
+1. **Mount Camouflage** instead of `render(<App/>)`.
+2. **Replace state setters** (`setEvents([...e, newEv])`, `setTurnPhase("thinking")`, etc.) with `cam.send(...)` calls.
+3. **Replace `<TextInput onSubmit>`** with `cam.on("userInput", ...)`.
+4. **Replace permission UI state** with `cam.on("permissionResponse", ...)`.
+5. **Delete `<App/>`, the Ink dependency, and any per-component layout code** — the renderer owns layout.
+
+## Versioning
+
+Versions track the main Camouflage workspace. Within `SCHEMA_VERSION: 1`,
+payload fields only grow — never renamed, never semantically changed — so a
+newer renderer is always backward compatible with an older SDK.
+
+## License
+
+Apache-2.0.

package/bin/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "camouflage-tui",
+  "version": "1.0.0-beta.1",
+  "description": "High-performance terminal renderer for AI agent applications. A React Ink alternative built for streaming, persistence, and replay.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./types": {
+      "types": "./src/types.d.ts",
+      "import": "./src/types.js"
+    }
+  },
+  "bin": {
+    "camouflage-tui": "./bin/camouflage-tui"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "test": "node --test src/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["camouflage", "tui", "terminal", "agent", "ai", "rendering", "ink", "cli", "llm", "streaming"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sinameraji/camouflage.git",
+    "directory": "sdk/node"
+  },
+  "homepage": "https://github.com/sinameraji/camouflage",
+  "bugs": "https://github.com/sinameraji/camouflage/issues"
+}

package/scripts/install.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * postinstall script — downloads the pre-built camouflage-tui binary
+ * for the current platform from GitHub Releases.
+ *
+ * Falls back gracefully: if the download fails (e.g. no internet, unsupported
+ * platform, CI without GitHub access), prints instructions to build from source.
+ */
+
+import { createWriteStream, mkdirSync, chmodSync, existsSync, unlinkSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { get as httpsGet } from "node:https";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BIN_DIR = join(__dirname, "..", "bin");
+const BIN_PATH = join(BIN_DIR, "camouflage-tui");
+
+const PLATFORM_MAP = {
+  "darwin-x64": "x86_64-apple-darwin",
+  "darwin-arm64": "aarch64-apple-darwin",
+  "linux-x64": "x86_64-unknown-linux-gnu",
+  "linux-arm64": "aarch64-unknown-linux-gnu",
+};
+
+const REPO = "sinameraji/camouflage";
+
+async function main() {
+  // Skip if binary already exists (e.g. user built from source)
+  if (existsSync(BIN_PATH)) {
+    return;
+  }
+
+  const key = `${process.platform}-${process.arch}`;
+  const target = PLATFORM_MAP[key];
+  if (!target) {
+    warn(`Unsupported platform: ${key}`);
+    return;
+  }
+
+  // Read version from package.json
+  const { default: pkg } = await import("../package.json", { with: { type: "json" } });
+  const version = pkg.version;
+  const tag = `v${version}`;
+  const archive = `camouflage-tui-${target}.tar.gz`;
+  const url = `https://github.com/${REPO}/releases/download/${tag}/${archive}`;
+
+  mkdirSync(BIN_DIR, { recursive: true });
+
+  const tmpPath = `${BIN_PATH}.tmp`;
+
+  try {
+    process.stdout.write(`camouflage-tui: downloading ${target} binary...\n`);
+    await download(url, tmpPath);
+
+    // Extract the binary from the tarball
+    execSync(`tar xzf "${tmpPath}" -C "${BIN_DIR}"`, { stdio: "pipe" });
+    unlinkSync(tmpPath);
+
+    chmodSync(BIN_PATH, 0o755);
+    process.stdout.write(`camouflage-tui: installed to ${BIN_PATH}\n`);
+  } catch (err) {
+    // Clean up partial downloads
+    try { unlinkSync(tmpPath); } catch {}
+    try { unlinkSync(BIN_PATH); } catch {}
+    warn(`Download failed: ${err.message}`);
+  }
+}
+
+function download(url, dest, redirects = 0) {
+  if (redirects > 5) return Promise.reject(new Error("Too many redirects"));
+
+  return new Promise((resolve, reject) => {
+    httpsGet(url, { headers: { "User-Agent": "camouflage-tui-postinstall" } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        return resolve(download(res.headers.location, dest, redirects + 1));
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
+      }
+      const file = createWriteStream(dest);
+      res.pipe(file);
+      file.on("finish", () => { file.close(); resolve(); });
+      file.on("error", reject);
+      res.on("error", reject);
+    }).on("error", reject);
+  });
+}
+
+function warn(msg) {
+  process.stdout.write(
+    `\ncamouflage-tui: ${msg}\n` +
+    `\nTo install manually, build from source:\n` +
+    `  cargo install --path crates/tui --root ~/.local\n` +
+    `  # or: cargo install --git https://github.com/${REPO} camouflage-tui\n\n`,
+  );
+}
+
+main().catch((err) => {
+  warn(err.message);
+});

package/src/__fake-renderer.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Test harness only — stands in for `camouflage-tui` in binding tests.
+ *
+ * Behaviour: reads NDJSON lines from stdin and for each known event_type,
+ * echoes it back on stdout (simulating what camouflage-tui would emit as
+ * outbound traffic). This lets us validate that the Node binding's
+ * spawn → write → readline parse → typed-event pipeline works end-to-end
+ * without needing a real Rust binary or a TTY.
+ *
+ * The real binding does NOT echo inbound back — but for test purposes,
+ * any inbound event is "valid outbound" since both directions use the
+ * same NDJSON shape.
+ */
+import { createInterface } from "node:readline";
+
+const rl = createInterface({ input: process.stdin });
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  try {
+    JSON.parse(trimmed); // sanity check
+    process.stdout.write(trimmed + "\n");
+  } catch {
+    // skip malformed
+  }
+});
+rl.on("close", () => process.exit(0));

package/src/binding.d.ts

@@ -0,0 +1,237 @@
+import { EventEmitter } from "node:events";
+import type { Event } from "./types.js";
+
+export interface MountOptions {
+  /** Executable name or path. Defaults to "camouflage-tui" (PATH lookup). */
+  bin?: string;
+  /** Extra args to pass to the renderer. `--stdin-events --emit-responses`
+   *  are always appended by the binding. */
+  args?: string[];
+  /** Environment overrides for the child. Merged with process.env. */
+  env?: NodeJS.ProcessEnv;
+  /** If true (default), renderer stderr is forwarded to Node's stderr.
+   *  If false, captured and exposed via the "stderr" event. */
+  inheritStderr?: boolean;
+  /** When true, skip the default `--stdin-events --emit-responses` args.
+   *  Only used to point the binding at a non-Camouflage binary for tests
+   *  or specialised harnesses. */
+  skipDefaultArgs?: boolean;
+  /** When true, the renderer's stdout and stderr go directly to the user's
+   *  terminal (TUI rendering is visible to the user), and outbound
+   *  NDJSON arrives on fd 3 via the new --responses-fd path. Use this when
+   *  building a "host CLI that internally drives Camouflage" — e.g.
+   *  KimiFlare's eventual Ink replacement. Default false: backward-
+   *  compatible programmatic mode where both directions ride on the
+   *  pipes the binding manages. */
+  renderToTerminal?: boolean;
+}
+
+export interface PermissionResponseEvent {
+  request_id: string;
+  choice: "allow_once" | "allow_session" | "deny";
+  feedback?: string;
+}
+
+export interface SelectListResponseEvent {
+  id: string;
+  value?: string;
+  cancelled: boolean;
+}
+
+export interface ConfirmResponseEvent {
+  id: string;
+  value?: boolean;
+  cancelled: boolean;
+}
+
+/**
+ * Convenience helper: emit a ShowConfirm and resolve to the user's
+ * ConfirmResponse for that id.
+ */
+export function confirm(
+  cam: CamouflageHandle,
+  spec: {
+    id: string;
+    prompt: string;
+    yes_label?: string;
+    no_label?: string;
+    default?: "yes" | "no";
+    allow_cancel?: boolean;
+  },
+): Promise<ConfirmResponseEvent>;
+
+/**
+ * Convenience helper: show a brief inline toast. Display-only — no
+ * response.
+ */
+export function toast(
+  cam: CamouflageHandle,
+  spec: string | {
+    text: string;
+    kind?: "info" | "success" | "warn" | "error";
+    ttl_ms?: number;
+  },
+): void;
+
+/** Convenience helper: show a tabular data view. Display-only. */
+export function table(
+  cam: CamouflageHandle,
+  spec: {
+    id: string;
+    title?: string;
+    columns: {
+      name: string;
+      label?: string;
+      align?: "left" | "right" | "center";
+    }[];
+    rows: Record<string, unknown>[];
+  },
+): void;
+
+/** Convenience helper: show a label/value list. Display-only. */
+export function keyValueView(
+  cam: CamouflageHandle,
+  spec: {
+    id: string;
+    title?: string;
+    items: { label: string; value: string }[];
+  },
+): void;
+
+export interface FormResponseEvent {
+  id: string;
+  values?: Record<string, string>;
+  cancelled: boolean;
+}
+
+/**
+ * Convenience helper: show a multi-field form and resolve to the user's
+ * FormResponse for that id.
+ */
+export function form(
+  cam: CamouflageHandle,
+  spec: {
+    id: string;
+    title?: string;
+    fields: {
+      name: string;
+      label: string;
+      kind?: "text" | "password";
+      default?: string;
+      placeholder?: string;
+      required?: boolean;
+    }[];
+    allow_cancel?: boolean;
+  },
+): Promise<FormResponseEvent>;
+
+export interface WizardCompletedEvent {
+  id: string;
+  results: Record<string, unknown>;
+}
+
+export interface WizardCancelledEvent {
+  id: string;
+  at_step: number;
+}
+
+export type WizardResolved =
+  | (WizardCompletedEvent & { cancelled?: undefined })
+  | (WizardCancelledEvent & { cancelled: true });
+
+/**
+ * Convenience helper: show a multi-step wizard. Resolves to either
+ * `{ id, results }` (completion) or `{ id, cancelled: true, at_step }`
+ * (user cancelled).
+ */
+export function wizard(
+  cam: CamouflageHandle,
+  spec: {
+    id: string;
+    title?: string;
+    steps: (
+      | { kind: "select"; id: string; prompt: string; options: { value: string; label: string; description?: string }[]; default?: string }
+      | { kind: "confirm"; id: string; prompt: string; yes_label?: string; no_label?: string }
+      | { kind: "form"; id: string; title?: string; fields: { name: string; label: string; kind?: "text" | "password"; default?: string; placeholder?: string; required?: boolean }[] }
+    )[];
+    allow_cancel?: boolean;
+  },
+): Promise<WizardResolved>;
+
+/**
+ * Convenience helper: emit a `ShowSelectList` and return a Promise that
+ * resolves to the user's `SelectListResponseEvent` for that id. The host
+ * picks the id; the helper subscribes once, filters by id, and unsubscribes
+ * automatically.
+ *
+ * @example
+ *   const choice = await selectList(cam, {
+ *     id: "resume-picker",
+ *     prompt: "Resume which session?",
+ *     options: [{ value: "a", label: "Session A" }],
+ *   });
+ *   if (choice.cancelled) return;
+ *   console.log("user picked:", choice.value);
+ */
+export function selectList(
+  cam: CamouflageHandle,
+  spec: {
+    id: string;
+    prompt: string;
+    options: { value: string; label: string; description?: string }[];
+    default?: string;
+    allow_filter?: boolean;
+    allow_cancel?: boolean;
+  },
+): Promise<SelectListResponseEvent>;
+
+export interface InvalidEvent {
+  line: string;
+  error: string;
+}
+
+export interface ExitEvent {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+}
+
+export interface CamouflageHandle extends EventEmitter {
+  /** Send one event INTO the renderer. */
+  send(event_type: string, payload?: object): boolean;
+  /** Send a pre-built Event object. */
+  sendEvent(ev: { event_type: string; payload?: object }): boolean;
+  /** Gracefully close: end stdin, wait for child exit, resolve with code. */
+  close(): Promise<number>;
+  /** Force-kill the renderer. */
+  kill(signal?: NodeJS.Signals): void;
+
+  // Typed event subscriptions (EventEmitter overrides):
+  on(event: "userInput", listener: (text: string) => void): this;
+  on(event: "permissionResponse", listener: (resp: PermissionResponseEvent) => void): this;
+  on(event: "selectListResponse", listener: (resp: SelectListResponseEvent) => void): this;
+  on(event: "confirmResponse", listener: (resp: ConfirmResponseEvent) => void): this;
+  on(event: "formResponse", listener: (resp: FormResponseEvent) => void): this;
+  on(event: "wizardCompleted", listener: (resp: WizardCompletedEvent) => void): this;
+  on(event: "wizardCancelled", listener: (resp: WizardCancelledEvent) => void): this;
+  on(event: "modeChangeRequested", listener: (resp: { direction: "next" | "prev" }) => void): this;
+  on(event: "cancelRequested", listener: () => void): this;
+  on(event: "event", listener: (ev: Event) => void): this;
+  on(event: "invalid", listener: (info: InvalidEvent) => void): this;
+  on(event: "stderr", listener: (chunk: string) => void): this;
+  on(event: "exit", listener: (info: ExitEvent) => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+/**
+ * Spawn the Camouflage renderer and return a handle for emitting events
+ * and listening to renderer→host outbound events.
+ *
+ * @example
+ *   import { mount } from "camouflage";
+ *   const cam = await mount();
+ *   cam.send("SessionStarted", {});
+ *   cam.on("userInput", (text) => console.log("got input:", text));
+ *   // ... when done:
+ *   await cam.close();
+ */
+export function mount(opts?: MountOptions): Promise<CamouflageHandle>;