@hanamorilabs/tab 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # tab
 
-Run any AI agent on a FlockTab tab.
+Run any AI agent on a FlockTab tab. Needs Node 22 or newer; nothing else.
 
 ```
 npm i -g @hanamorilabs/tab
@@ -46,11 +46,44 @@ for the keys once (typed without echo, saved owner-only to
 `~/.flocktab/proxy.env`), fetches `flocktab-proxy` for this machine into
 `~/.flocktab/bin`, and starts it in the background (log: `~/.flocktab/proxy.log`).
 `tab down` stops it; `tab update` fetches the newest proxy and restarts;
-`tab claude` starts it when it is down. No Docker, no checkout. Then
+`tab claude` starts it when it is down. No Docker, no Rust, no checkout: the
+binary comes with `tab` as the `@hanamorilabs/flocktab-proxy-<platform>`
+package for your machine. Then
 `tab login`, pick **2 Self-hosted**: the proxy says which console it settles
 through, so the device code lands on flocktab.com. No unlock in this mode;
 Codex shows `FlockTab - Self-hosted` as its provider.
 
+## Commands
+
+```
+tab login            approve this machine in the console, once
+tab <agent> [args]   claude, codex, grok, kimi, gemini, or any command, on the tab
+tab use              pick or change the Agent this folder runs as (.flocktab)
+tab alias <name>...  make plain `codex` run `tab codex` (shims in ~/.flocktab/bin)
+tab unalias <name>   remove such a shim
+tab status           flock, folder Agent, proxy health, provider key state
+tab version          tab and proxy versions
+tab up | down        self-hosted: start or stop the local proxy
+tab update           self-hosted: newest proxy (npm i -g @hanamorilabs/tab@latest)
+tab logout           forget the session and keys on this machine
+tab help             this list
+```
+
+## Aliases: plain `codex` on the tab
+
+```
+tab alias codex claude
+export PATH="$HOME/.flocktab/bin:$PATH"   # once, in your shell rc
+codex                                     # now runs: tab codex
+```
+
+`tab alias` writes a shim named after the command into `~/.flocktab/bin`
+(`codex.cmd` on Windows). With that folder first on `PATH`, the plain
+command runs on the tab. When `tab` spawns the real agent it removes its
+own shim folder from the child's `PATH`, so nothing loops. `tab alias` with
+no name lists them; `tab unalias codex` removes one. Prefer a shell alias?
+`alias codex='tab codex'` in your rc does the same for that shell only.
+
 ## Secrets and colour
 
 The unlock and provider keys are typed with echo off (raw mode); the unlock is checked against the proxy before saving; a wrong unlock is refused, and `tab status` says `unlock ok` or `unlock is WRONG`. The check is `GET /v1/whoami` with the unlock, which decrypts the envelope in memory and answers `ok`/`wrong`, never the key. Output is coloured on a terminal; `NO_COLOR` turns it off, `FORCE_COLOR` turns it on for pipes.

package/dist/alias.js

@@ -0,0 +1,79 @@
+/**
+ * `tab alias codex`: a shim named `codex` in ~/.flocktab/bin that runs
+ * `tab codex "$@"`. With that folder first on PATH, the plain command is on
+ * the tab. No shell rc is edited here: `tab alias` prints the one PATH line
+ * and the person adds it where they like.
+ *
+ * The shim shadows the real binary by name, so when `tab` spawns the agent
+ * it removes ~/.flocktab/bin from the child's PATH (`pathWithoutShims`);
+ * otherwise `codex` would resolve to the shim and loop forever.
+ */
+import { chmod, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { configDir } from "./config.js";
+export function shimDir(env = process.env) {
+    return path.join(configDir(env), "bin");
+}
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+export function validAliasName(name) {
+    return NAME.test(name) && !["tab", "flocktab-proxy"].includes(name.toLowerCase());
+}
+function shimBody(name, platform = process.platform) {
+    if (platform === "win32") {
+        return { file: `${name}.cmd`, body: `@echo off\r\ntab ${name} %*\r\n` };
+    }
+    return { file: name, body: `#!/bin/sh\nexec tab ${name} "$@"\n` };
+}
+export async function writeAlias(name, env = process.env, platform = process.platform) {
+    const dir = shimDir(env);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const { file, body } = shimBody(name, platform);
+    const target = path.join(dir, file);
+    await writeFile(target, body, { mode: 0o755 });
+    await chmod(target, 0o755);
+    return target;
+}
+export async function removeAlias(name, env = process.env, platform = process.platform) {
+    const { file } = shimBody(name, platform);
+    const target = path.join(shimDir(env), file);
+    try {
+        await rm(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Alias names present in the shim folder (the proxy binary is not one). */
+export async function listAliases(env = process.env) {
+    try {
+        return (await readdir(shimDir(env)))
+            .filter((f) => !f.startsWith("flocktab-proxy") && !f.endsWith(".part"))
+            .map((f) => f.replace(/\.cmd$/i, ""))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Whether the shim folder is on PATH, so an alias would actually be found. */
+export function shimDirOnPath(env = process.env, platform = process.platform) {
+    const sep = platform === "win32" ? ";" : ":";
+    const dir = path.resolve(shimDir(env));
+    return (env.PATH ?? "").split(sep).some((p) => p && path.resolve(p) === dir);
+}
+/** PATH for the child agent: everything except the shim folder. */
+export function pathWithoutShims(env = process.env, platform = process.platform) {
+    const sep = platform === "win32" ? ";" : ":";
+    const dir = path.resolve(shimDir(env));
+    return (env.PATH ?? "")
+        .split(sep)
+        .filter((p) => p && path.resolve(p) !== dir)
+        .join(sep);
+}
+/** The line to add to a shell rc so the shims win. */
+export function pathLine(platform = process.platform) {
+    return platform === "win32"
+        ? `setx PATH "%USERPROFILE%\\.flocktab\\bin;%PATH%"`
+        : `export PATH="$HOME/.flocktab/bin:$PATH"`;
+}

package/dist/cli.js

@@ -7,7 +7,9 @@
  *   tab codex  [...args]   Codex on the tab
  *   tab <cmd>  [...args]   anything else, both APIs pointed at the tab
  *   tab use                pick (or change) the Agent this folder runs as
+ *   tab alias codex ...    make plain `codex` run `tab codex` (shims in ~/.flocktab/bin)
  *   tab status             which flock, which Agent here, is the proxy up
+ *   tab version            tab and proxy versions
  *   tab up | down | update self-hosted: start, stop, or fetch the newest proxy
  *   tab logout             forget the session and keys
  *
@@ -27,9 +29,11 @@ import { ConsoleApiError, createAgent, issueAgentKey, listAgents } from "./conso
 import { consoleUrlFor, DeviceLoginError, startDeviceLogin, waitForApproval } from "./device-login.js";
 import { clearConfig, configDir, configPath, HOSTED_PROXY, isLocalProxy, loadConfig, LOCAL_PROXY, normalizeProxyUrl, presentedKey, saveConfig, } from "./config.js";
 import { reportFolder } from "./folder.js";
+import { listAliases, pathLine, pathWithoutShims, removeAlias, shimDir, shimDirOnPath, validAliasName, writeAlias } from "./alias.js";
 import { agentNameFor, projectRoot, readProject, writeProject } from "./project.js";
-import { downloadProxy, hasProxyEnv, packagedBinPath, proxyBinPath, proxyEnvPath, proxyLogPath, PROXY_VERSION, startProxy, stopProxy, tailProxyLog, writeProxyEnv, } from "./proxy-bin.js";
+import { downloadProxy, hasProxyEnv, packagedBinPath, proxyBinPath, proxyEnvPath, proxyInstalled, proxyLogPath, PROXY_VERSION, startProxy, stopProxy, tailProxyLog, writeProxyEnv, } from "./proxy-bin.js";
 import { proxyHealth, waitHealthy } from "./selfhost.js";
+import { TAB_VERSION } from "./version.js";
 const say = (text) => console.error(text);
 const ok = (text) => say(line("ok", text));
 const warn = (text) => say(line("warn", text));
@@ -46,7 +50,10 @@ function usage() {
         cmd(others.join(" | tab "), "the same, for those agents"),
         cmd("<command> [args]", "any other agent, both APIs pointed at the tab"),
         cmd("use", "pick or change the Agent this folder runs as (.flocktab)"),
+        cmd("alias <name>...", "make plain `codex` run `tab codex` (shims in ~/.flocktab/bin)"),
+        cmd("unalias <name>", "remove such a shim"),
         cmd("status", "which flock, which Agent here, is the proxy up"),
+        cmd("version", "tab and proxy versions"),
         cmd("up", "self-hosted: start the local proxy (fetches it the first time)"),
         cmd("down", "self-hosted: stop the local proxy"),
         cmd("update", "self-hosted: fetch the newest proxy and restart it"),
@@ -423,6 +430,15 @@ async function resolveAgent(config, opts = {}) {
     ok(`This folder runs as ${bold(issued.agent.name)} ${dim(`(${file})`)}`);
     return login;
 }
+/** `tab version`: this CLI, and the proxy it would run (packaged, downloaded, or neither). */
+async function version() {
+    const packaged = packagedBinPath();
+    const bin = proxyBinPath();
+    const installed = await proxyInstalled();
+    const where = packaged ? `packaged, ${packaged}` : installed ? `downloaded, ${bin}` : "not installed; tab up fetches it";
+    say(rows([["tab", TAB_VERSION], ["proxy", `${PROXY_VERSION}  ${dim(`(${where})`)}`]], 0));
+    return 0;
+}
 async function status() {
     const config = await loadConfig();
     if (!config) {
@@ -475,6 +491,8 @@ async function runAgent(name, args) {
     const key = presentedKey({ key: agent.key, unlock: config.unlock });
     reportFolder(config.proxyUrl, key);
     const { spec, env } = envFor({ name, proxyUrl: config.proxyUrl, presentedKey: key });
+    // An alias shim named like the agent must not be what we spawn.
+    env.PATH = pathWithoutShims();
     if (spec.isolatedHome === "codex") {
         env.CODEX_HOME = await prepareCodexHome({
             baseDir: configDir(),
@@ -488,6 +506,8 @@ async function runAgent(name, args) {
         child.on("error", (err) => {
             if (err.code === "ENOENT") {
                 fail(`${spec.label} is not installed (${spec.command} not on PATH). ${dim(spec.install)}`);
+                if (!knownClients().includes(name))
+                    say(dim(`Not a tab command either; see ${bold("tab help")}.`));
                 resolve(127);
                 return;
             }
@@ -497,6 +517,46 @@ async function runAgent(name, args) {
         child.on("close", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
     });
 }
+/**
+ * `tab alias codex claude`: shims so the plain commands run on the tab.
+ * `tab alias` alone lists them; `tab unalias codex` removes one.
+ */
+async function alias(names, remove = false) {
+    if (names.length === 0 && !remove) {
+        const existing = await listAliases();
+        if (existing.length === 0)
+            say(dim(`No aliases. Example: ${bold("tab alias codex claude")}`));
+        else
+            say(rows(existing.map((n) => [n, dim(`tab ${n}`)]), 0));
+        return pathHint();
+    }
+    if (names.length === 0) {
+        fail("tab unalias needs a name.");
+        return 2;
+    }
+    for (const name of names) {
+        if (!validAliasName(name)) {
+            fail(`${name} is not a usable alias name.`);
+            return 2;
+        }
+        if (remove) {
+            (await removeAlias(name)) ? ok(`Removed ${name}.`) : warn(`${name} was not an alias.`);
+        }
+        else {
+            const file = await writeAlias(name);
+            ok(`${bold(name)} now runs ${bold(`tab ${name}`)} ${dim(`(${file})`)}`);
+        }
+    }
+    return remove ? 0 : pathHint();
+}
+function pathHint() {
+    if (shimDirOnPath())
+        return 0;
+    say("");
+    say(`Put ${dim(shimDir())} first on your PATH so the aliases win. Add to your shell rc, then open a new terminal:`);
+    say(`  ${bold(pathLine())}`);
+    return 0;
+}
 /** `tab use`: pick or change the Agent for this folder. */
 async function use() {
     const config = await ensureLogin();
@@ -591,6 +651,14 @@ async function main(argv) {
             return 0;
         case "use":
             return use();
+        case "alias":
+            return alias(rest);
+        case "unalias":
+            return alias(rest, true);
+        case "version":
+        case "--version":
+        case "-v":
+            return version();
         case "status":
             return status();
         case "up":

package/dist/version.js

@@ -0,0 +1,2 @@
+/** Written by scripts/write-version.mjs from package.json at build; `tab version` prints it. */
+export const TAB_VERSION = "0.1.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanamorilabs/tab",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Run any AI agent on a FlockTab tab: tab claude, tab codex, tab <command>.",
   "license": "MIT",
   "type": "module",
@@ -15,7 +15,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "build": "node scripts/write-version.mjs && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",