@kommander/broski 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# broski
+
+Private text conversations with your msg-bot agents, in an OpenTUI/Solid terminal.
+
+```sh
+bun x @kommander/broski --gateway URL
+npx @kommander/broski --gateway URL
+```
+
+Replace `URL` with the HTTPS origin supplied by your gateway operator. A gateway
+is mandatory; this package contains no service address or credentials. HTTPS is
+required, including local testing. The npm package is `@kommander/broski`;
+the installed executable is `broski`.
+
+## Login And Keys
+
+Press Enter in the Console OAuth dialog. Open the displayed verification URL in
+your browser and enter the displayed code. Your Console user must already be
+linked to your msg-bot account. Login requires a configured gateway; no model API
+key or administrator token can substitute for Console messaging authorization.
+
+- Tab switches between the bot sidebar and message input.
+- Up/Down selects a bot; Enter returns to its input.
+- Enter sends a text message.
+- Ctrl+N creates a bot, subject to the gateway's fleet quotas.
+- Ctrl+L signs out and opens login; Ctrl+R refreshes bot status.
+- Escape closes a dialog; Ctrl+Q or Ctrl+C exits.
+
+Use a terminal at least 50 columns by 16 rows. Tokens stay in process memory and
+are not written to disk. Local transcripts are plaintext private files under
+`~/.local/state/console-chat/`, separated by gateway and authenticated account,
+limited to 2,000 entries and 8 MB per account. Protect your local account and backups.
+
+The configured HTTPS gateway is your trust root. Its discovery response identifies
+one Console authority; device/token URLs are derived from that authority, and
+verification URLs must stay on its HTTPS origin. Redirects are rejected. The client
+uses Console's public JSON device grant and holds its own access token, not the
+manager's account credentials. Expiry requires login again. Ctrl+L clears the local
+token and closes the stream; it does not revoke the token at Console or delete local history.
+
+The gateway retains only bounded in-memory pending replies, with an initial
+delivery plus at most three retries. Reconnect does not recover a server history;
+gateway restart loses pending replies. Messages are deduplicated locally before
+REST ACK. An uncertain send keeps its message ID for an explicit retry.
+
+## Runtime
+
+Supported package targets: Linux and macOS, x64 and arm64. Node >=22.18 can launch
+the package; Bun >=1.3 can run it directly. OpenTUI 0.5.3's Node FFI is not yet
+implemented, so the Node launcher uses a pinned, package-local optional Bun binary.
+It never downloads code itself, shells out to a global `bun`, or needs Bun on PATH.
+Do not omit optional dependencies. Linux x64 Node and Bun terminal paths have been
+smoke-tested; other declared native targets require platform release checks.
+
+No token, private text, or backend error body is intentionally logged. Terminal
+control sequences are stripped before rendering. This is a text-only DM client,
+not an agent administration console.

package/bin/broski.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+if (process.versions.bun) {
+  try { await import("../dist/main.js"); }
+  catch { process.stderr.write("broski could not start. Check terminal and native optional dependencies.\n"); process.exitCode = 1; }
+} else {
+  // OpenTUI 0.5.3's Node FFI is a placeholder. Never assume a global Bun executable.
+  try {
+    const platform = process.platform;
+    if (!["linux", "darwin"].includes(platform) || !["x64", "arm64"].includes(process.arch)) throw new Error("Unsupported platform");
+    const arch = process.arch === "arm64" ? "aarch64" : "x64";
+    const musl = platform === "linux" && !process.report.getReport().header.glibcVersionRuntime ? "-musl" : "";
+    const baseline = arch === "x64" ? "-baseline" : "";
+    const executable = createRequire(import.meta.url).resolve(`@oven/bun-${platform}-${arch}${musl}${baseline}/bin/bun`);
+    const child = spawn(executable, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], { stdio: "inherit" });
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, () => child.kill(signal));
+    child.on("error", () => { process.stderr.write("Packaged terminal runtime could not start.\n"); process.exitCode = 1; });
+    child.on("exit", (code, signal) => { process.exitCode = code ?? (signal ? 1 : 0); });
+  } catch {
+    process.stderr.write("broski needs its native optional dependencies. Install without --omit=optional on Linux or macOS x64/arm64.\n");
+    process.exitCode = 1;
+  }
+}