@hanamorilabs/tab 0.1.1 → 0.1.3

package/README.md

@@ -59,6 +59,8 @@ Codex shows `FlockTab - Self-hosted` as its provider.
 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 setup <name>...   make plain `codex` run `tab codex` (shims in ~/.flocktab/bin)
+tab alias remove <name>...  undo that; `tab alias list` shows them
 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
@@ -67,6 +69,23 @@ tab logout           forget the session and keys on this machine
 tab help             this list
 ```
 
+## Aliases: plain `codex` on the tab
+
+```
+tab alias setup codex claude
+export PATH="$HOME/.flocktab/bin:$PATH"   # once, in your shell rc
+codex                                     # now runs: tab codex
+tab alias remove codex                    # back to the plain codex
+```
+
+`tab alias setup` 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 list` shows them; `tab alias remove <name>` deletes the shim, and
+the plain command is the real one again. 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,6 +7,8 @@
  *   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 setup codex  make plain `codex` run `tab codex` (shims in ~/.flocktab/bin)
+ *   tab alias remove codex undo that; `tab alias list` shows them
  *   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
@@ -28,6 +30,7 @@ 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, proxyInstalled, proxyLogPath, PROXY_VERSION, startProxy, stopProxy, tailProxyLog, writeProxyEnv, } from "./proxy-bin.js";
 import { proxyHealth, waitHealthy } from "./selfhost.js";
@@ -48,6 +51,8 @@ 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 setup <name>...", "make plain `codex` run `tab codex` (shims in ~/.flocktab/bin)"),
+        cmd("alias remove <name>...", "undo that; `tab alias list` shows them"),
         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)"),
@@ -487,6 +492,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(),
@@ -511,6 +518,59 @@ 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(args, removeFlag = false) {
+    // `tab alias setup codex`, `tab alias remove codex`, `tab alias list`;
+    // the bare `tab alias codex` and `tab unalias codex` mean the same.
+    const [first, ...rest] = args;
+    let names = args;
+    let remove = removeFlag;
+    if (first === "setup" || first === "add")
+        names = rest;
+    else if (first === "remove" || first === "rm") {
+        names = rest;
+        remove = true;
+    }
+    else if (first === "list" || first === "ls")
+        names = [];
+    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 alias remove needs a name, e.g. tab alias remove codex");
+        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();
@@ -605,6 +665,10 @@ 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":

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanamorilabs/tab",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Run any AI agent on a FlockTab tab: tab claude, tab codex, tab <command>.",
   "license": "MIT",
   "type": "module",