@hanamorilabs/tab 0.1.0

package/dist/proxy-bin.js

@@ -0,0 +1,216 @@
+/**
+ * The self-hosted proxy is one static binary (`flocktab-proxy`, Rust, see
+ * apps/proxy-rs). It arrives with `npm i -g @hanamorilabs/tab` as the
+ * platform package for this machine (an optional dependency); when that is
+ * missing, `tab up` fetches the build from the GitHub release into
+ * ~/.flocktab/bin. Either way it runs as a background process with the
+ * provider keys from ~/.flocktab/proxy.env. No Docker, no checkout, no
+ * runtime beyond the binary itself.
+ */
+import { spawn } from "node:child_process";
+import { chmod, mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { configDir } from "./config.js";
+/** The proxy release `tab up` fetches. Bump with each proxy tag. */
+export const PROXY_VERSION = "0.1.1";
+export const RELEASES = "https://github.com/joseairosa/flocktab/releases/download";
+export function targetFor(platform = process.platform, arch = process.arch) {
+    if (platform === "darwin")
+        return arch === "arm64" ? "darwin-arm64" : arch === "x64" ? "darwin-x64" : undefined;
+    if (platform === "linux")
+        return arch === "x64" ? "linux-x64" : arch === "arm64" ? "linux-arm64" : undefined;
+    if (platform === "win32")
+        return arch === "x64" ? "win-x64" : undefined;
+    return undefined;
+}
+export function assetUrl(version, target) {
+    const ext = target === "win-x64" ? ".exe" : "";
+    return `${RELEASES}/proxy-v${version}/flocktab-proxy-${target}${ext}`;
+}
+/** Where a download lands when no platform package is installed. */
+export function downloadedBinPath(env = process.env) {
+    return path.join(configDir(env), "bin", process.platform === "win32" ? "flocktab-proxy.exe" : "flocktab-proxy");
+}
+/**
+ * The binary that ships with `npm i -g @hanamorilabs/tab`: the platform
+ * package listed as an optional dependency. Resolved from this module, so
+ * a global install finds it beside `tab` in the global node_modules.
+ */
+export function packagedBinPath(target = targetFor()) {
+    if (!target)
+        return undefined;
+    const bin = target === "win-x64" ? "flocktab-proxy.exe" : "flocktab-proxy";
+    try {
+        return createRequire(import.meta.url).resolve(`@hanamorilabs/flocktab-proxy-${target}/${bin}`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** FLOCKTAB_PROXY_BIN, else the packaged binary, else a download under ~/.flocktab/bin. */
+export function proxyBinPath(env = process.env) {
+    const override = env.FLOCKTAB_PROXY_BIN?.trim();
+    if (override)
+        return override;
+    return packagedBinPath() ?? downloadedBinPath(env);
+}
+export function proxyEnvPath(env = process.env) {
+    return path.join(configDir(env), "proxy.env");
+}
+export function proxyLogPath(env = process.env) {
+    return path.join(configDir(env), "proxy.log");
+}
+function pidPath(env) {
+    return path.join(configDir(env), "proxy.pid");
+}
+async function exists(file) {
+    try {
+        await stat(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function hasProxyEnv(env = process.env) {
+    return exists(proxyEnvPath(env));
+}
+/** KEY=VALUE lines; comments and blanks skipped; no shell quoting. */
+export function parseEnvFile(text) {
+    const out = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        out[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+    }
+    return out;
+}
+export async function readProxyEnv(env = process.env) {
+    try {
+        return parseEnvFile(await readFile(proxyEnvPath(env), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The provider keys the proxy spends: plaintext on purpose, this is the
+ * operator's own machine, the same trade as any `.env`. Owner-only.
+ */
+export async function writeProxyEnv(input, env = process.env) {
+    const dir = configDir(env);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const lines = [
+        `# FlockTab self-hosted proxy. Keys stay here; the ledger is ${input.control}.`,
+        `FLOCKTAB_CONTROL_URL=${input.control}`,
+        ...Object.entries(input.keys)
+            .filter(([, v]) => v.trim())
+            .map(([id, v]) => `FLOCKTAB_PROVIDER_KEY_${id.toUpperCase()}=${v.trim()}`),
+        "",
+    ];
+    const file = proxyEnvPath(env);
+    await writeFile(file, lines.join("\n"), { mode: 0o600 });
+    await chmod(file, 0o600);
+    return file;
+}
+/** Fetch this machine's build of the proxy from the release. */
+export async function downloadProxy(log, env = process.env, fetchImpl = fetch) {
+    const target = targetFor();
+    if (!target)
+        return { ok: false, message: `no proxy build for ${process.platform}/${process.arch}` };
+    const url = assetUrl(PROXY_VERSION, target);
+    const file = downloadedBinPath(env);
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    log(`Fetching flocktab-proxy ${PROXY_VERSION} for ${target}`);
+    let res;
+    try {
+        res = await fetchImpl(url);
+    }
+    catch (err) {
+        return { ok: false, message: `could not download ${url}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!res.ok || !res.body)
+        return { ok: false, message: `download of ${url} answered ${res.status}` };
+    const tmp = `${file}.part`;
+    await writeFile(tmp, Buffer.from(await res.arrayBuffer()), { mode: 0o755 });
+    await chmod(tmp, 0o755);
+    await rename(tmp, file);
+    return { ok: true, file };
+}
+export async function proxyInstalled(env = process.env) {
+    return exists(proxyBinPath(env));
+}
+async function readPid(env) {
+    try {
+        const pid = Number.parseInt(await readFile(pidPath(env), "utf8"), 10);
+        return Number.isFinite(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Start the proxy in the background: keys from proxy.env, output to proxy.log, pid file kept. */
+export async function startProxy(log, env = process.env) {
+    const existing = await readPid(env);
+    if (existing && alive(existing))
+        return { ok: true, pid: existing };
+    if (!(await proxyInstalled(env))) {
+        log("No proxy package for this machine came with tab; fetching the release build.");
+        const fetched = await downloadProxy(log, env);
+        if (!fetched.ok)
+            return fetched;
+    }
+    const fileEnv = await readProxyEnv(env);
+    if (!fileEnv.FLOCKTAB_CONTROL_URL) {
+        return { ok: false, message: `no ${proxyEnvPath(env)}: run tab up to save your provider keys` };
+    }
+    const logFile = await open(proxyLogPath(env), "a", 0o600);
+    const child = spawn(proxyBinPath(env), [], {
+        detached: true,
+        stdio: ["ignore", logFile.fd, logFile.fd],
+        env: { ...env, ...fileEnv, HOST: fileEnv.HOST ?? "127.0.0.1", PORT: fileEnv.PORT ?? "8787" },
+    });
+    await logFile.close();
+    if (!child.pid)
+        return { ok: false, message: "the proxy did not start" };
+    child.unref();
+    await writeFile(pidPath(env), `${child.pid}\n`, { mode: 0o600 });
+    return { ok: true, pid: child.pid };
+}
+export async function stopProxy(env = process.env) {
+    const pid = await readPid(env);
+    await rm(pidPath(env), { force: true });
+    if (!pid || !alive(pid))
+        return false;
+    try {
+        process.kill(pid, "SIGTERM");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The last lines of the proxy log, for a failed start. */
+export async function tailProxyLog(lines = 8, env = process.env) {
+    try {
+        const text = await readFile(proxyLogPath(env), "utf8");
+        return text.trimEnd().split("\n").slice(-lines);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/selfhost.js

@@ -0,0 +1,33 @@
+/**
+ * Is the local proxy answering, and wait for it after a start. The proxy
+ * itself is the `flocktab-proxy` binary (see proxy-bin.ts).
+ */
+export async function proxyHealth(proxyUrl, timeoutMs = 3_000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(`${proxyUrl}/health`, { signal: controller.signal });
+        if (!response.ok)
+            return { ok: false, reason: `health returned ${response.status}` };
+        const body = (await response.json().catch(() => ({})));
+        return body.ok === true ? { ok: true } : { ok: false, reason: "ledger unavailable" };
+    }
+    catch {
+        return { ok: false, reason: "not running" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Wait for health after a start, bounded. */
+export async function waitHealthy(proxyUrl, totalMs = 60_000) {
+    const deadline = Date.now() + totalMs;
+    let last = { ok: false, reason: "not running" };
+    while (Date.now() < deadline) {
+        last = await proxyHealth(proxyUrl);
+        if (last.ok)
+            return last;
+        await new Promise((r) => setTimeout(r, 1_500));
+    }
+    return last;
+}

package/dist/ui.js

@@ -0,0 +1,99 @@
+/**
+ * Terminal styling for `tab`: a few colours, a box, aligned rows. No
+ * dependency. Colour follows the usual rules: NO_COLOR wins, FORCE_COLOR
+ * forces, otherwise only a real terminal gets escapes.
+ */
+const ESC = "\u001b[";
+const CODES = {
+    reset: "0",
+    bold: "1",
+    dim: "2",
+    underline: "4",
+    red: "31",
+    green: "32",
+    yellow: "33",
+    blue: "34",
+    magenta: "35",
+    cyan: "36",
+};
+export function colorEnabled(env = process.env, isTTY = Boolean(process.stderr.isTTY)) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "")
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0")
+        return true;
+    if (env.TERM === "dumb")
+        return false;
+    return isTTY;
+}
+let enabled = colorEnabled();
+/** Tests and callers with their own detection can flip it. */
+export function setColor(on) {
+    enabled = on;
+}
+function wrap(code, text) {
+    if (!enabled || text === "")
+        return text;
+    return `${ESC}${CODES[code]}m${text}${ESC}${CODES.reset}m`;
+}
+export const bold = (t) => wrap("bold", t);
+export const dim = (t) => wrap("dim", t);
+export const underline = (t) => wrap("underline", t);
+export const red = (t) => wrap("red", t);
+export const green = (t) => wrap("green", t);
+export const yellow = (t) => wrap("yellow", t);
+export const cyan = (t) => wrap("cyan", t);
+export const magenta = (t) => wrap("magenta", t);
+/** Visible width: escapes do not take columns. */
+export function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\u001b\[[0-9;]*m/g, "");
+}
+export function width(text) {
+    return [...stripAnsi(text)].length;
+}
+const GLYPH = {
+    ok: "✓",
+    warn: "!",
+    fail: "✗",
+    info: "›",
+    plain: " ",
+};
+const TONE_PAINT = {
+    ok: green,
+    warn: yellow,
+    fail: red,
+    info: cyan,
+    plain: (t) => t,
+};
+/** "✓ Approved as Codex", glyph coloured, text plain. */
+export function line(tone, text) {
+    return `${TONE_PAINT[tone](GLYPH[tone])} ${text}`;
+}
+/** A framed block, the way release notes and confirmations read at a glance. */
+export function box(lines, options = {}) {
+    const pad = options.pad ?? 2;
+    const paint = TONE_PAINT[options.tone ?? "info"];
+    const title = options.title ? ` ${bold(options.title)} ` : "";
+    const inner = Math.max(width(title), ...lines.map(width)) + pad * 2;
+    const top = `╭${title ? "─" + title : ""}${"─".repeat(Math.max(0, inner - width(title) - (title ? 1 : 0)))}╮`;
+    const body = lines.map((l) => {
+        const fill = " ".repeat(Math.max(0, inner - pad - width(l)));
+        return `${paint("│")}${" ".repeat(pad)}${l}${fill}${paint("│")}`;
+    });
+    const bottom = `╰${"─".repeat(inner)}╯`;
+    return [paint(top), ...body, paint(bottom)].join("\n");
+}
+/** Aligned label/value rows: plain labels are dimmed, painted ones kept; padding counts visible width. */
+export function rows(pairs, indent = 2) {
+    const w = Math.max(0, ...pairs.map(([k]) => width(k)));
+    return pairs
+        .map(([k, v]) => {
+        const pad = " ".repeat(w - width(k));
+        const label = k.includes(ESC) ? `${k}${pad}` : dim(`${k}${pad}`);
+        return `${" ".repeat(indent)}${label}  ${v}`;
+    })
+        .join("\n");
+}
+export function heading(text) {
+    return bold(text);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@hanamorilabs/tab",
+  "version": "0.1.0",
+  "description": "Run any AI agent on a FlockTab tab: tab claude, tab codex, tab <command>.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "tab": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "optionalDependencies": {
+    "@hanamorilabs/flocktab-proxy-darwin-arm64": "0.1.1",
+    "@hanamorilabs/flocktab-proxy-darwin-x64": "0.1.1",
+    "@hanamorilabs/flocktab-proxy-linux-x64": "0.1.1",
+    "@hanamorilabs/flocktab-proxy-linux-arm64": "0.1.1",
+    "@hanamorilabs/flocktab-proxy-win-x64": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.6",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joseairosa/flocktab.git",
+    "directory": "apps/tab"
+  },
+  "homepage": "https://flocktab.com",
+  "keywords": [
+    "flocktab",
+    "claude",
+    "codex",
+    "agent",
+    "budget",
+    "proxy"
+  ]
+}