@todoforai/tfa-surface 0.1.2 → 0.1.4

package/dist/cli.js

@@ -116,7 +116,7 @@ function resolveToken(opts = {}) {
 // package.json
 var package_default = {
   name: "@todoforai/tfa-surface",
-  version: "0.1.2",
+  version: "0.1.4",
   description: "TODOforAI surface CLI — see and drive what is shown in the user's live UI (describe, todo/panel views, renderer cards, surface render, controls). Replaces tfa-frontend. Reuses bridge credentials.",
   type: "module",
   bin: {
@@ -156,22 +156,24 @@ Usage:
   tfa-surface <command> [args...]
 
 Discovery:
-  describe                              What's open in the target frontend:
-                                        todos, focus, panel surfaces, sidebar,
-                                        embedded-browser CDP URL, show/card
-                                        instances in loaded chats. YAML; --json
-                                        for the raw structure.
+  describe                              Every surface in the target frontend — kind, id,
+                                        ref, focus; plus sidebar, embedded-browser CDP
+                                        URL and the show instances loaded in each todo.
+                                        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|agents|preview|browser|terminal
-  panel close [--todo <id>]
+Surfaces — a ref is a todo id, <todoId>:<alias> (a shown artifact, live) or an http(s) url:
+  open overlay <todoId>                 The full-page todo (todos only).
+  open window  <ref> [--detached]       A floating preview window (any ref); --detached: out of
+                                        the grid, own size, resizable. connect:/stream: refs always are.
+  open panel   <view> [--todo <id>] [--url <url>]
+                                        A todo's side panel: changes|agents|preview|browser|terminal
+                                        (--todo defaults to $TODOFORAI_TODO_ID).
+  open card    <ref> [--id <id>] [--title <t>] [--group <slug>]
+                                        A card on the project board, for every member —
+                                        its own card, or a tile inside a group's card.
+                                        Persisted; the same --id updates in place.
+  close  <kind> <id>                    overlay: no id · window: the ref · panel: the todo · card: its id
+  focus  window <ref>                   Bring a window (or its docked tab) to front.
 
 Renderer cards (data plane — works headless, no frontend needed;
 --project defaults to $TODOFORAI_PROJECT_ID):
@@ -193,6 +195,7 @@ Content (inherited from tfa-frontend, broadcast to all tabs):
 
 Options:
   --frontend <tabId>  Target frontend (overrides $TODOFORAI_FRONTEND_ID)
+  --id <surfaceId>    Card id (open card); --group <slug> files it into a group card
   --api-url <url>     Backend URL (default: env/credentials)
   --api-token <tok>   Token (default: env/credentials)
   --json              Machine-readable output
@@ -202,9 +205,13 @@ Options:
 Examples:
   tfa-surface describe
   tfa-surface card add kpi-tile dashboards/kpi.html --title "KPI tile"
-  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')"
+  tfa-surface open window 3f2a91...
+  tfa-surface open window $TODOFORAI_TODO_ID:kpi     # a shown artifact, in its own window
+  tfa-surface open window connect:<deviceId>/zele   # a sign-in card for the user
+  tfa-surface open card   $TODOFORAI_TODO_ID:kpi --title "Weekly KPIs" --group marketing
+  tfa-surface open panel browser --url https://example.com
+  tfa-surface close card weekly-kpis
+  agent-browser connect "$(tfa-surface describe --json | jq -r '.surfaces[] | select(.browser) | .browser.cdp' | head -1)"
   git diff --stat | tfa-surface show chat.panel $TODOFORAI_TODO_ID
 
 Exit codes: 0 ok · 1 error · 2 frontend not reachable / no frontend id`);
@@ -284,24 +291,18 @@ function printResult(ctx, data) {
 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.open ? t.browser.url : "(idle)"}   cdp: ${t.browser.cdp}`);
-    if (t.shows?.length) {
+  console.log(d.surfaces.length ? "surfaces:" : "surfaces: []");
+  for (const s of d.surfaces) {
+    const flags = [s.focused ? "focused" : "", s.docked ? "docked" : "", s.size ? `detached ${s.size.w}x${s.size.h}` : "", s.view ?? "", s.group ? `in ${s.group}` : ""].filter(Boolean).join(", ");
+    const id = s.kind === "overlay" || s.id === s.ref ? "" : ` ${s.id}`;
+    console.log(`  ${s.kind}${id}: ${s.ref}${flags ? `   ${flags}` : ""}${s.title ? `   # ${s.title}` : ""}`);
+    if (s.browser)
+      console.log(`    browser: ${s.browser.open ? s.browser.url : "(idle)"}   cdp: ${s.browser.cdp}`);
+    if (s.shows?.length) {
       console.log("    shows:");
-      for (const s of t.shows) {
-        const bits = [
-          s.card ? `card=${s.card}` : "",
-          s.mime || "",
-          s.url ? `url ${s.url}` : "",
-          s.title || ""
-        ].filter(Boolean);
-        console.log(`      ${s.ref}${bits.length ? `  ${bits.join("  ")}` : ""}`);
+      for (const x of s.shows) {
+        const bits = [x.card ? `card=${x.card}` : "", x.mime || "", x.url ? `url ${x.url}` : "", x.title || ""].filter(Boolean);
+        console.log(`      ${x.ref}${bits.length ? `  ${bits.join("  ")}` : ""}`);
       }
     }
   }
@@ -315,10 +316,12 @@ async function main() {
       project: { type: "string" },
       title: { type: "string" },
       description: { type: "string" },
-      popout: { type: "boolean", default: false },
+      id: { type: "string" },
+      group: { type: "string" },
       "api-url": { type: "string" },
       "api-token": { type: "string" },
       json: { type: "boolean", default: false },
+      detached: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false },
       version: { type: "boolean", default: false }
     },
@@ -354,37 +357,46 @@ async function main() {
         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|agents|preview|browser|terminal [--todo <id>] [--url <url>]");
-        const result = await uiCall(ctx, "panel.open", { todoId: todoArg(), surface, ...values.url ? { url: values.url } : {} });
+    case "open": {
+      const [kind, arg] = args;
+      const usage = "usage: tfa-surface open overlay <todoId> | window <ref> [--detached] | panel <view> [--todo <id>] [--url <url>] | card <ref> [--id <id>] [--title <t>] [--group <slug>]";
+      if (kind === "overlay" || kind === "window") {
+        if (!arg)
+          die(usage);
+        const result = await uiCall(ctx, "surface.open", { kind, ref: arg, ...values.detached && { detached: true } });
+        console.log(ctx.json ? JSON.stringify(result) : `${result.created ? "opened" : "already open"} (${kind})`);
+      } else if (kind === "panel") {
+        if (!arg)
+          die(usage);
+        const result = await uiCall(ctx, "surface.open", { kind, id: todoArg(), view: arg, ref: values.url ?? arg });
         const pending = result?.browserReady === false;
         console.log(ctx.json ? JSON.stringify(result ?? { ok: true }) : pending ? "ok (browser opening — its CDP url appears in `device_list` shortly)" : "ok");
-      } else if (verb === "close") {
-        await uiCall(ctx, "panel.close", { todoId: todoArg() });
-        console.log(ctx.json ? '{"ok":true}' : "ok");
+      } else if (kind === "card") {
+        if (!arg)
+          die(usage);
+        const result = await uiCall(ctx, "surface.open", {
+          kind,
+          ref: arg,
+          ...values.id ? { id: values.id } : {},
+          ...values.title !== undefined ? { title: values.title } : {},
+          ...values.group !== undefined ? { group: values.group } : {}
+        });
+        console.log(ctx.json ? JSON.stringify(result) : `card ${result.id} ${result.created ? "added to" : "updated on"} the board`);
       } else {
-        die("usage: tfa-surface panel open|close ...");
+        die(usage);
       }
       break;
     }
+    case "close":
+    case "focus": {
+      const [kind, arg] = args;
+      const id = kind === "overlay" ? "" : kind === "panel" ? arg || todoArg() : arg;
+      if (!kind || kind !== "overlay" && !id)
+        die(`usage: tfa-surface ${cmd} overlay | window <ref> | panel [<todoId>] | card <id>`);
+      await uiCall(ctx, `surface.${cmd}`, { kind, id });
+      console.log(ctx.json ? '{"ok":true}' : "ok");
+      break;
+    }
     case "card": {
       const [verb, name] = args;
       const cardPath = (n) => `/resources/cards/${projectArg()}/${encodeURIComponent(n)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@todoforai/tfa-surface",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "TODOforAI surface CLI — see and drive what is shown in the user's live UI (describe, todo/panel views, renderer cards, surface render, controls). Replaces tfa-frontend. Reuses bridge credentials.",
   "type": "module",
   "bin": {