@todoforai/tfa-surface 0.1.0

package/dist/cli.js

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+
+// ../tfa-subagent/dist/auth.js
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir, platform } from "node:os";
+var DEFAULT_API_URL = "https://api.todofor.ai";
+function normalizeApiUrl(url) {
+  if (url.startsWith("localhost"))
+    return `http://${url}`;
+  if (!url.startsWith("http://") && !url.startsWith("https://"))
+    return `https://${url}`;
+  return url.replace(/\/+$/, "");
+}
+function credentialsPath() {
+  return platform() === "win32" ? join(homedir(), "AppData", "Roaming", "todoforai", "credentials.json") : platform() === "darwin" ? join(homedir(), "Library", "Application Support", "todoforai", "credentials.json") : join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "todoforai", "credentials.json");
+}
+function credentialsPaths() {
+  return [credentialsPath()];
+}
+function writeSecure(p, data) {
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 384 });
+  try {
+    chmodSync(p, 384);
+  } catch {}
+}
+function readStoredAuth(apiUrl) {
+  for (const p of credentialsPaths()) {
+    try {
+      const c = JSON.parse(readFileSync(p, "utf-8"));
+      const apiToken = c[apiUrl] || c.apiToken || c.apiKey || "";
+      const host = c.backendHost || "";
+      const storedApiUrl = typeof c.apiUrl === "string" && c.apiUrl ? c.apiUrl : host ? `${host === "localhost" || host === "127.0.0.1" ? "http" : "https"}://${host}` : undefined;
+      return {
+        apiToken,
+        apiUrl: storedApiUrl,
+        deviceId: typeof c.deviceId === "string" ? c.deviceId : undefined,
+        deviceSecret: typeof c.deviceSecret === "string" ? c.deviceSecret : undefined
+      };
+    } catch {}
+  }
+  return { apiToken: "" };
+}
+function persistApiToken(token) {
+  for (const p of credentialsPaths()) {
+    try {
+      const c = JSON.parse(readFileSync(p, "utf-8"));
+      c.apiToken = token;
+      writeSecure(p, c);
+      return;
+    } catch {}
+  }
+}
+async function refreshDeviceToken(opts = {}) {
+  const envUrl = process.env.TODOFORAI_API_URL || process.env.API_URL;
+  const initialApiUrl = normalizeApiUrl(opts.apiUrl || envUrl || DEFAULT_API_URL);
+  const stored = readStoredAuth(initialApiUrl);
+  const apiUrl = normalizeApiUrl(opts.apiUrl || envUrl || stored.apiUrl || DEFAULT_API_URL);
+  if (!stored.deviceId || !stored.deviceSecret)
+    return "";
+  try {
+    const res = await fetch(`${apiUrl}/api/v1/cli/device/token`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ deviceId: stored.deviceId, secret: stored.deviceSecret })
+    });
+    if (!res.ok)
+      return "";
+    const data = await res.json();
+    if (!data.token)
+      return "";
+    persistApiToken(data.token);
+    return data.token;
+  } catch {
+    return "";
+  }
+}
+async function fetchWithRenew(url, init, opts) {
+  const header = opts.header ?? "x-api-key";
+  const renewOn = opts.renewOn ?? [401];
+  const send = (token) => fetch(url, { ...init, headers: { ...init.headers, [header]: token } });
+  let res = await send(opts.token);
+  if (renewOn.includes(res.status) && opts.token.startsWith("dst_")) {
+    const fresh = await refreshDeviceToken({ apiUrl: opts.apiUrl });
+    if (fresh && fresh !== opts.token)
+      return { res: await send(fresh), token: fresh };
+  }
+  return { res, token: opts.token };
+}
+function resolveToken(opts = {}) {
+  const envUrl = process.env.TODOFORAI_API_URL || process.env.API_URL;
+  const initialApiUrl = normalizeApiUrl(opts.apiUrl || envUrl || DEFAULT_API_URL);
+  const stored = readStoredAuth(initialApiUrl);
+  const apiUrl = normalizeApiUrl(opts.apiUrl || envUrl || stored.apiUrl || DEFAULT_API_URL);
+  const apiToken = opts.apiToken || process.env.TODOFORAI_API_TOKEN || stored.apiToken || "";
+  if (!apiToken)
+    throw new Error("TODOFORAI_API_TOKEN not set and no apiToken found in ~/.config/todoforai/credentials.json (run `<cli> login` or `todoforai-bridge login`, or pass --api-token)");
+  return { apiUrl, apiToken };
+}
+// package.json
+var package_default = {
+  name: "@todoforai/tfa-surface",
+  version: "0.1.0",
+  description: "TODOforAI surface CLI — see and drive what is shown in the user's live UI (describe, todo/panel views, surface render, controls). Replaces tfa-frontend. Reuses bridge credentials.",
+  type: "module",
+  bin: {
+    "tfa-surface": "dist/cli.js"
+  },
+  scripts: {
+    build: "bun build src/cli.ts --outdir dist --target node --format esm",
+    dev: "bun run src/cli.ts"
+  },
+  devDependencies: {
+    "@todoforai/tfa-subagent": "^0.1.9",
+    "@types/node": "^20.11.0"
+  },
+  keywords: ["cli", "frontend", "surfaces", "ui-control", "todoforai"],
+  author: "TODO for AI",
+  license: "MIT",
+  files: ["dist"]
+};
+
+// src/cli.ts
+var VERSION = package_default.version;
+function printHelp() {
+  console.log(`tfa-surface — see and drive what is shown in the user's live TODOforAI UI.
+
+Target frontend: $TODOFORAI_FRONTEND_ID (a tabId). Override per call:
+  TODOFORAI_FRONTEND_ID=<tabId> tfa-surface describe
+
+Usage:
+  tfa-surface <command> [args...]
+
+Discovery:
+  describe                              What's open in the target frontend:
+                                        todos, focus, panel surfaces, sidebar,
+                                        embedded-browser CDP URL. YAML; --json
+                                        for the raw structure.
+
+Todos (views):
+  todo open  <todoId> [--popout]        Open a todo (full-page overlay); --popout
+                                        forces a floating preview window.
+  todo focus <todoId>                   Focus an open todo's window.
+  todo close <todoId>                   Close an open todo view.
+
+Panels (surfaces inside a todo; --todo defaults to $TODOFORAI_TODO_ID):
+  panel open <surface> [--todo <id>] [--url <url>]
+                                        surface: changes|preview|browser|terminal
+  panel close [--todo <id>]
+
+Content (inherited from tfa-frontend, broadcast to all tabs):
+  show  <surface> <target> [markdown]   Render markdown (stdin when omitted).
+  clear <surface> <target>              Clear a surface.
+  get   <control> <target>              Read a control's value.
+  set   <control> <target> <json>       Set a control (JSON value).
+  catalog                               Print the capability catalog (JSON).
+  whoami                                Check auth.
+
+Options:
+  --frontend <tabId>  Target frontend (overrides $TODOFORAI_FRONTEND_ID)
+  --api-url <url>     Backend URL (default: env/credentials)
+  --api-token <tok>   Token (default: env/credentials)
+  --json              Machine-readable output
+  -h, --help          This help
+  --version           Version
+
+Examples:
+  tfa-surface describe
+  tfa-surface todo open 3f2a91... --popout
+  tfa-surface panel open browser --url https://example.com
+  agent-browser connect "$(tfa-surface describe --json | jq -r '.todos[0].browser.cdp')"
+  git diff --stat | tfa-surface show chat.panel $TODOFORAI_TODO_ID
+
+Exit codes: 0 ok · 1 error · 2 frontend not reachable / no frontend id`);
+}
+function die(msg, code = 1) {
+  console.error(`Error: ${msg}`);
+  process.exit(code);
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+async function call(ctx, path, body, method = "POST") {
+  const init = {
+    method,
+    headers: body !== undefined ? { "content-type": "application/json" } : {},
+    body: body !== undefined ? JSON.stringify(body) : undefined
+  };
+  const { res, token } = await fetchWithRenew(`${ctx.apiUrl}/dst/v1${path}`, init, {
+    apiUrl: ctx.apiUrl,
+    token: ctx.token,
+    renewOn: [401, 403]
+  });
+  ctx.token = token;
+  const data = await res.json().catch(() => ({}));
+  if (res.status === 412)
+    die(`${data?.message ?? "frontend not connected"}`, 2);
+  if (res.status === 408 || data?.message?.includes("did not respond")) {
+    die(`frontend not reachable — is a browser tab or the desktop app open? (${data?.message ?? res.status})`, 2);
+  }
+  if (res.status >= 400)
+    die(`HTTP ${res.status}: ${JSON.stringify(data)}`);
+  return data;
+}
+async function uiCall(ctx, method, params = {}) {
+  if (!ctx.frontendId) {
+    die("no target frontend — set TODOFORAI_FRONTEND_ID or pass --frontend <tabId> (run inside an agent shell, or copy the id from `describe` on another window)", 2);
+  }
+  const data = await call(ctx, "/frontend/call", {
+    functionName: "ui_call",
+    args: { method, params },
+    targetFrontendId: ctx.frontendId
+  });
+  if (data.error)
+    die(data.error);
+  return data.result;
+}
+function printResult(ctx, data) {
+  if (data.error)
+    die(data.error);
+  if (ctx.json) {
+    console.log(JSON.stringify(data.result ?? { ok: true }));
+    return;
+  }
+  if (data.result && "value" in data.result) {
+    const v = data.result.value;
+    console.log(typeof v === "string" ? v : JSON.stringify(v));
+  } else {
+    console.log("ok");
+  }
+}
+function printDescribe(d) {
+  console.log(`frontend: ${d.frontendId}   (${d.platform}, ${d.kind})`);
+  console.log(`sidebar: ${d.sidebar}`);
+  console.log(d.todos.length ? "todos:" : "todos: []");
+  for (const t of d.todos) {
+    const flags = [t.mode === "window" ? "window" : "", t.focused ? "focused" : ""].filter(Boolean).join(", ");
+    console.log(`  ${t.todoId}:${flags ? `   ${flags}` : ""}${t.title ? `   # ${t.title}` : ""}`);
+    if (t.panel && t.panel !== "browser")
+      console.log(`    ${t.panel}`);
+    if (t.browser)
+      console.log(`    browser: ${t.browser.url}   cdp: ${t.browser.cdp ?? "(connecting)"}`);
+  }
+}
+async function main() {
+  const { values, positionals } = parseArgs({
+    options: {
+      frontend: { type: "string" },
+      todo: { type: "string" },
+      url: { type: "string" },
+      popout: { type: "boolean", default: false },
+      "api-url": { type: "string" },
+      "api-token": { type: "string" },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", default: false }
+    },
+    allowPositionals: true
+  });
+  if (values.version) {
+    console.log(VERSION);
+    return;
+  }
+  if (values.help || positionals.length === 0) {
+    printHelp();
+    return;
+  }
+  const { apiUrl, apiToken } = resolveToken({
+    apiUrl: values["api-url"],
+    apiToken: values["api-token"]
+  });
+  const ctx = {
+    apiUrl,
+    token: apiToken,
+    json: !!values.json,
+    frontendId: values.frontend || process.env.TODOFORAI_FRONTEND_ID || undefined
+  };
+  const todoArg = () => values.todo || process.env.TODOFORAI_TODO_ID || die("no todo — pass --todo <todoId> or set TODOFORAI_TODO_ID");
+  const [cmd, ...args] = positionals;
+  switch (cmd) {
+    case "describe": {
+      const result = await uiCall(ctx, "ui.describe");
+      if (ctx.json)
+        console.log(JSON.stringify(result));
+      else
+        printDescribe(result);
+      break;
+    }
+    case "todo": {
+      const [verb, todoId] = args;
+      if (!verb || !todoId)
+        die("usage: tfa-surface todo open|focus|close <todoId>");
+      if (verb === "open") {
+        const result = await uiCall(ctx, "todo.open", { todoId, ...values.popout ? { mode: "window" } : {} });
+        console.log(ctx.json ? JSON.stringify(result) : `${result.created ? "opened" : "already open"} (${result.mode})`);
+      } else if (verb === "focus" || verb === "close") {
+        await uiCall(ctx, `todo.${verb}`, { todoId });
+        console.log(ctx.json ? '{"ok":true}' : "ok");
+      } else {
+        die(`unknown todo verb: ${verb}`);
+      }
+      break;
+    }
+    case "panel": {
+      const [verb, surface] = args;
+      if (verb === "open") {
+        if (!surface)
+          die("usage: tfa-surface panel open changes|preview|browser|terminal [--todo <id>] [--url <url>]");
+        await uiCall(ctx, "panel.open", { todoId: todoArg(), surface, ...values.url ? { url: values.url } : {} });
+        console.log(ctx.json ? '{"ok":true}' : "ok");
+      } else if (verb === "close") {
+        await uiCall(ctx, "panel.close", { todoId: todoArg() });
+        console.log(ctx.json ? '{"ok":true}' : "ok");
+      } else {
+        die("usage: tfa-surface panel open|close ...");
+      }
+      break;
+    }
+    case "show": {
+      const [surface, target] = args;
+      if (!surface || !target)
+        die("usage: tfa-surface show <surface> <target> [markdown]");
+      const content = args[2] ?? (process.stdin.isTTY ? die("no markdown given and stdin is a TTY") : await readStdin());
+      if (!content.trim())
+        die("empty content — use `clear` to clear a surface");
+      printResult(ctx, await call(ctx, "/frontend/call", { functionName: "surface_render", args: { surface, target, content } }));
+      break;
+    }
+    case "clear": {
+      const [surface, target] = args;
+      if (!surface || !target)
+        die("usage: tfa-surface clear <surface> <target>");
+      printResult(ctx, await call(ctx, "/frontend/call", { functionName: "surface_clear", args: { surface, target } }));
+      break;
+    }
+    case "get": {
+      const [control, target] = args;
+      if (!control || !target)
+        die("usage: tfa-surface get <control> <target>");
+      printResult(ctx, await call(ctx, "/frontend/call", { functionName: "control_get", args: { control, target } }));
+      break;
+    }
+    case "set": {
+      const [control, target, value] = args;
+      if (!control || !target || value === undefined)
+        die("usage: tfa-surface set <control> <target> <json-value>");
+      printResult(ctx, await call(ctx, "/frontend/call", { functionName: "control_set", args: { control, target, value } }));
+      break;
+    }
+    case "catalog": {
+      const data = await call(ctx, "/frontend/catalog", undefined, "GET");
+      console.log(JSON.stringify(data, null, 2));
+      break;
+    }
+    case "whoami": {
+      await call(ctx, "/frontend/catalog", undefined, "GET");
+      console.log(`tfa-surface: authenticated (${ctx.apiUrl})`);
+      break;
+    }
+    default:
+      die(`unknown command: ${cmd} (see tfa-surface --help)`);
+  }
+}
+main().catch((e) => die(e instanceof Error ? e.message : String(e)));

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@todoforai/tfa-surface",
+  "version": "0.1.0",
+  "description": "TODOforAI surface CLI — see and drive what is shown in the user's live UI (describe, todo/panel views, surface render, controls). Replaces tfa-frontend. Reuses bridge credentials.",
+  "type": "module",
+  "bin": {
+    "tfa-surface": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "bun build src/cli.ts --outdir dist --target node --format esm",
+    "dev": "bun run src/cli.ts"
+  },
+  "devDependencies": {
+    "@todoforai/tfa-subagent": "^0.1.9",
+    "@types/node": "^20.11.0"
+  },
+  "keywords": ["cli", "frontend", "surfaces", "ui-control", "todoforai"],
+  "author": "TODO for AI",
+  "license": "MIT",
+  "files": ["dist"]
+}