@acsetra/runner 0.1.26 → 0.1.29

package/README.md

@@ -16,8 +16,11 @@ npm install -g @acsetra/runner
 runner app create crm --label "CRM"
 runner set put crm contacts ada --json '{"role":"eng"}'
 runner doctor <workspace>.crm && runner compile <workspace>.crm
-runner auth crm                  # gate the app behind pen.acsetra.com sign-in
+runner auth crm                  # gate the app behind home.acsetra.com sign-in
 runner dev <workspace>.crm
+runner open <workspace>.crm      # reuse/create its paired Chrome tab
+runner notify <workspace>.crm --title Ready
+runner tabs
 ```
 
 Exposes `runner` and `acsetra` binaries. The token is cached at

package/bin/runner.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import * as config from "../lib/config.js";
 import * as api from "../lib/api.js";
+import * as browser from "../lib/browser.js";
 import { toOp, VerbError } from "../lib/verbs.js";
 import { dispatchHelp, renderTop } from "../lib/help.js";
 
@@ -136,7 +137,7 @@ async function main() {
   const argv = process.argv.slice(2);
   if (!argv.length || ["-h", "--help"].includes(argv[0])) { console.log(renderTop()); return 0; }
   const [cmd, ...rest] = argv;
-  if (["version", "--version", "-V"].includes(cmd)) { console.log("runner (@acsetra/runner) 0.1.26"); return 0; }
+  if (["version", "--version", "-V"].includes(cmd)) { console.log("runner (@acsetra/runner) 0.1.29"); return 0; }
 
   // help — top-level, `help <topic>`, and per-verb `<cmd> … --help` (lexical, before toOp)
   if (cmd === "help") {
@@ -163,6 +164,34 @@ async function main() {
       if (rest[0] === "revoke" && rest[1]) return emit(await api.del("/api/v1/tokens/" + rest[1]));
       return emit(await api.get("/api/v1/tokens"));
     }
+    if (cmd === "open" || cmd === "focus") {
+      const scope = browser.firstPositional(
+        rest, new Set(["--device", "--dedupe-key"]));
+      if (!scope) return fail(`usage: runner ${cmd} <scope> [--new|--reuse|--background]`, 2);
+      const disposition = rest.includes("--new") ? "new" :
+        rest.includes("--background") ? "background" : "reuse";
+      return emit(await browser.openScope(scope, {
+        disposition,
+        activation: rest.includes("--silent") ? "silent" : "focus",
+        device: opt(rest, "--device"),
+        dedupeKey: opt(rest, "--dedupe-key"),
+        fallback: !rest.includes("--no-fallback"),
+      }));
+    }
+    if (cmd === "notify") {
+      const scope = browser.firstPositional(
+        rest, new Set(["--title", "--message", "--device", "--dedupe-key"]));
+      if (!scope) return fail("usage: runner notify <scope> [--title T] [--message M]", 2);
+      return emit(await browser.notifyScope(scope, {
+        title: opt(rest, "--title"),
+        message: opt(rest, "--message"),
+        disposition: rest.includes("--new") ? "new" : "reuse",
+        device: opt(rest, "--device"),
+        dedupeKey: opt(rest, "--dedupe-key"),
+      }));
+    }
+    if (cmd === "tabs") return emit(await browser.tabs({ device: opt(rest, "--device") }));
+    if (cmd === "devices") return emit(await browser.devices());
     const [op, args] = toOp(cmd, rest);
     emit(await api.postOp(op, args));
     return 0;

package/lib/browser.js

@@ -0,0 +1,69 @@
+// Browser-native Runner commands. The server is the intent bus; paired Chrome
+// is the executor. OS URL opening remains a duplicate-safe cold fallback.
+import { setTimeout as sleep } from "node:timers/promises";
+import * as api from "./api.js";
+
+const intentOf = (out) => (out && out.intent) || {};
+
+export function firstPositional(args, valueFlags) {
+  for (let i = 0; i < args.length; i++) {
+    if (valueFlags.has(args[i])) { i++; continue; }
+    if (!args[i].startsWith("-")) return args[i];
+  }
+  return null;
+}
+
+async function waitIntent(intentId, seconds = 8) {
+  const deadline = Date.now() + Math.max(0, seconds) * 1000;
+  let intent = {};
+  while (Date.now() < deadline) {
+    intent = (await api.get(`/api/v1/browser/intents/${intentId}`)).intent || {};
+    if (!["pending", "claimed"].includes(intent.status)) return intent;
+    await sleep(350);
+  }
+  return intent;
+}
+
+function openUrl(url) {
+  const cmd = process.platform === "darwin" ? "open" :
+    process.platform === "win32" ? "start" : "xdg-open";
+  import("node:child_process").then(cp => {
+    try { cp.spawn(cmd, [url], { stdio: "ignore", detached: true }).unref(); } catch {}
+  });
+}
+
+export async function openScope(scope, {
+  disposition = "reuse", activation = "focus", device = null,
+  dedupeKey = null, fallback = true,
+} = {}) {
+  const out = await api.post("/api/v1/browser/intents", {
+    kind: "navigate", scope, disposition, activation, device, dedupe_key: dedupeKey,
+  });
+  const intent = intentOf(out);
+  if ((intent.delivery || {}).available || !fallback) return out;
+  if (intent.id) await api.del(`/api/v1/browser/intents/${intent.id}`);
+  if (out.open_url) openUrl(out.open_url);
+  out.intent = { ...intent, status: "cold_url" };
+  out.delivery = { mode: "system_browser", available: Boolean(out.open_url) };
+  return out;
+}
+
+export const notifyScope = (scope, {
+  title = null, message = null, disposition = "reuse", device = null, dedupeKey = null,
+} = {}) => api.post("/api/v1/browser/intents", {
+  kind: "notify", scope, title, message, disposition, device, dedupe_key: dedupeKey,
+});
+
+export async function tabs({ device = null, waitSeconds = 8 } = {}) {
+  const out = await api.post("/api/v1/browser/intents", {
+    kind: "inspect", device, ttl_seconds: Math.max(10, waitSeconds + 5),
+  });
+  const intent = intentOf(out);
+  if (!(intent.delivery || {}).available) {
+    return { tabs: [], intent, error: "no paired Runner Chrome device is currently active" };
+  }
+  const settled = await waitIntent(intent.id, waitSeconds);
+  return { tabs: (settled.result || {}).tabs || [], intent: settled };
+}
+
+export const devices = () => api.get("/api/v1/browser/devices");

package/lib/config.js

@@ -5,7 +5,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-export const DEFAULT_API_BASE = "https://pen.acsetra.com";
+export const DEFAULT_API_BASE = "https://home.acsetra.com";
 const USER_DIR = process.env.ACSETRA_HOME || path.join(os.homedir(), ".config", "acsetra");
 const CRED = path.join(USER_DIR, "credentials");
 const PROJ_DIR = ".runner";

package/lib/help.js

@@ -11,6 +11,7 @@ export const GROUPS = {
   set: [["create", "set.create"], ["put", "set.put"],
         ["declare_schema", "set.declare_schema"], ["fetch_url", "set.fetch_url"],
         ["remove_row", "set.remove_row"], ["drop", "set.drop"],
+        ["link", "set.link"], ["sources", "set.sources"],
         ["list", "set.list"], ["describe", "set.describe"],
         ["rows", "set.rows"], ["validate", "set.validate"]],
   css: [["init", "css.init"], ["set_class", "css.set_class"],
@@ -93,7 +94,7 @@ export const OPS_DOC = {
   "component.init": { desc: "bootstrap the component+route plane", kw: [] },
   "component.set": { desc: "author a component's node tree (--json is the tree)", kw: ["parts", "label", "ordinal"] },
   "component.remove": { desc: "remove a component", kw: [] },
-  "component.set_route": { desc: "mount a component on a page (--json is route props)", kw: ["instance", "label", "ordinal"] },
+  "component.set_route": { desc: "mount a component on a page (--json is route props); --page => page-scoped visibility wrapper (navigation shows/hides; without it extra routes STACK); --pattern => path pattern 'watch/{id}' mapping a served path onto the page (effective page defaults to the route code for patterned routes)", kw: ["instance", "page", "pattern", "label", "ordinal"] },
   "component.remove_route": { desc: "remove a route", kw: [] },
   "component.list": { desc: "list components", kw: [] },
   "component.list_routes": { desc: "list routes (pages)", kw: [] },
@@ -117,10 +118,15 @@ export const VERBS_DOC = {
   tokens: { usage: "tokens [new [--name N] | list | revoke <id>]", desc: "manage API tokens" },
   docs: { usage: "docs pull [-S scope]", desc: "refresh CLAUDE.md + .runner/docs/* (this app's context)" },
   dev: { usage: "dev <app> [--no-browser]", desc: "open your app's hosted surface in the browser" },
+  open: { usage: "open <scope> [--reuse|--new|--background] [--device ID] [--no-fallback]", desc: "open or reuse a scope in paired Runner Chrome; falls back to a cold browser URL" },
+  focus: { usage: "focus <scope> [--device ID]", desc: "move to an existing scope tab, creating it when needed" },
+  notify: { usage: "notify <scope> [--title T] [--message M] [--new] [--device ID]", desc: "raise a native notification whose click opens or reuses the scope" },
+  tabs: { usage: "tabs [--device ID]", desc: "list open Runner scope tabs from the paired browser only" },
+  devices: { usage: "devices", desc: "list paired browser devices and live status" },
   checkout: { usage: "checkout <app> [-o dir] [--force]", desc: "materialize a scope subtree as local files in .tmp/ (read-only; grep/edit, write back with the typed verbs)" },
   app: { usage: "app create <name> [--label L]  |  app list", desc: "create / list app scopes" },
   apps: { usage: "apps", desc: "list app scopes (alias of `app list`)" },
-  auth: { usage: "auth <app> [--off]  |  auth list [scope]", desc: "gate an app behind pen.acsetra.com sign-in — signed-in visitors are enrolled as members on first visit; --off lifts the gate (no secrets, reuses the main-site realm)" },
+  auth: { usage: "auth <app> [--off]  |  auth list [scope]", desc: "gate an app behind home.acsetra.com sign-in — signed-in visitors are enrolled as members on first visit; --off lifts the gate (no secrets, reuses the main-site realm)" },
   ls: { usage: "ls [-S scope]", desc: "list value sets" },
   inspect: { usage: "inspect [<set>] [-S scope]", desc: "read a set's rows (alias: i); no set => list" },
   read: { usage: "read <code> [-S scope]", desc: "read a value set (me_* = your own per-user zone)" },
@@ -247,11 +253,14 @@ export function renderTop() {
            "  r signin / whoami / workspaces / use <slug> / logout / usage / tokens",
            "  r docs pull            refresh CLAUDE.md + .runner/docs/*",
            "  r dev <app>            open your app's hosted surface in the browser",
+           "  r open / focus <scope> paired Chrome scope navigation",
+           "  r notify <scope>       native notification → scope tab",
+           "  r tabs / devices       inspect Runner tabs and paired browsers",
            "  r checkout <app>       materialize the app as local files in .tmp/",
            "");
   out.push("Authoring (planes — run `r <group> --help` for subcommands)",
            "  r app create <name> ; r apps",
-           "  r auth <app>           require pen.acsetra.com sign-in to use an app",
+           "  r auth <app>           require home.acsetra.com sign-in to use an app",
            "  r set | css | asset | behavior | component | head  <subverb> …",
            "  r pipe <code> -S <scope> -w c:l ; r w <code> <tier> …",
            "  r ls | inspect <set> | read <code> | show <pipe>",

package/lib/verbs.js

@@ -15,6 +15,7 @@ export const POS = {
   "set.create": ["code"], "set.put": ["set_code", "row_code"], "set.declare_schema": ["code"],
   "set.fetch_url": ["set_code", "row_code", "url"], "set.remove_row": ["set_code", "row_code"],
   "set.drop": ["set_code"], "set.describe": ["set_code"], "set.rows": ["set_code"],
+  "set.link": ["alias", "source"], "set.sources": ["scope"],
   "pipe.set": ["code"], "pipe.show": ["code"], "pipe.remove": ["code"],
   "css.set_class": ["code"], "css.set_rule": ["class_code", "variant"], "css.clear_rule": ["class_code"],
   "css.attach": ["class_code", "target"], "css.detach": ["code"], "css.describe": ["class_code"], "css.resolve": ["page"],
@@ -158,7 +159,7 @@ export function toOp(verb, rest) {
   }
   if (verb === "apps") return ["app.list", {}];
   if (verb === "auth") {
-    // Hosted "auth block": gate an app behind pen.acsetra.com sign-in. No secrets —
+    // Hosted "auth block": gate an app behind home.acsetra.com sign-in. No secrets —
     // the server reuses its own Keycloak realm; `--off` lifts the gate.
     //   runner auth <app> [--off]      |      runner auth list [scope]
     if (rest[0] === "list" || rest[0] === "ls") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acsetra/runner",
-  "version": "0.1.26",
+  "version": "0.1.29",
   "description": "Runner CLI — author and run hosted Runner apps from your terminal (the `runner` command).",
   "keywords": ["runner", "acsetra", "cli", "agent", "low-code"],
   "license": "MIT",