@gobius/t3ctl 0.2.1 → 0.3.0

package/README.md

@@ -19,8 +19,8 @@ npm i -g @gobius/t3ctl
 # 2. mint a token — run this on the machine hosting T3 Code
 npx t3 auth session issue --label t3ctl --ttl 30d --token-only
 
-# 3. register that host under a short name of your choosing
-t3ctl host add laptop http://localhost:3773 eyJ2Ijox...
+# 3. register that host — t3ctl probes it and names it after the machine
+t3ctl host add http://localhost:3773 eyJ2Ijox...
 
 # 4. see everything
 t3ctl ls
@@ -81,15 +81,41 @@ t3ctl ls --json | jq -r '.projects[].threads[] | select(.status=="running") | .t
 The JSON shape is `{projects: [{host, id, title, workspaceRoot, threads: [{id,
 title, branch, status, provider, updatedAt}]}], unreachable: [{host, error}]}`.
 
-### `t3ctl host add <name> <origin> <token>`
+### `t3ctl host add <origin> [token] [--name <name>]`
 
-Register (or overwrite) a host. `<name>` is whatever you want to call it locally;
-`<origin>` is a scheme + host + optional port, with any trailing slash trimmed.
+Register (or update) a host. `<origin>` is a scheme + host + optional port, with
+any trailing slash trimmed — the scheme is required.
+
+Before writing anything, t3ctl fetches the host's environment descriptor from
+`/.well-known/t3/environment`. That endpoint is unauthenticated, so it confirms
+you are pointed at a real T3 Code server *before* a token is involved: a wrong
+origin fails with `not a T3 Code server` instead of a confusing 401 on your first
+`ls`. The descriptor's `environmentId`, `label` and `serverVersion` are stored
+alongside the token.
 
 ```sh
-t3ctl host add desktop https://studio.tailnet-1234.ts.net eyJ2Ijox...
+t3ctl host add https://studio.tailnet-1234.ts.net eyJ2Ijox...
 ```
 
+The host is named after the machine's own label (`SPR-Gobius-D` becomes
+`spr-gobius-d`); pass `--name` to choose your own. Re-running `host add` for an
+origin you already have updates that entry in place and keeps the stored token if
+you don't pass a new one.
+
+t3ctl warns you when:
+
+- the new host's `serverVersion` differs from your other hosts — the API is not a
+  stable public interface, so a version split is worth knowing about
+- an origin you already registered now reports a **different `environmentId`**,
+  meaning it points at a different machine than it used to and the stored token
+  belongs to the old one
+
+The token is optional so you can register a host before minting one, but reads
+will fail until you add it.
+
+The older `t3ctl host add <name> <origin> <token>` form still works and prints a
+deprecation notice.
+
 ### `t3ctl host rm <name>`
 
 ```sh
@@ -98,7 +124,8 @@ t3ctl host rm desktop
 
 ### `t3ctl hosts`
 
-List registered hosts with truncated tokens. `t3ctl host` with no subcommand does
+List registered hosts, probing each one in parallel for its label, environment id
+(shortened), server version and reachability. `t3ctl host` with no subcommand does
 the same thing.
 
 ```sh
@@ -106,10 +133,13 @@ t3ctl hosts
 ```
 
 ```
-laptop           http://localhost:3773  token:eyJ2Ijox…
-desktop          https://studio.tailnet-1234.ts.net  token:eyJ2Ijox…
+● laptop         SPR-Gobius-D       9d9d9921  0.0.38-nightly.20260901.1250  http://localhost:3773
+✕ desktop        Desktop            11111111  0.0.31-nightly.20260801.0900  https://studio.tailnet-1234.ts.net  cannot reach …
 ```
 
+Unreachable hosts are dimmed and show the values last recorded, not live ones.
+`ls` deliberately does *not* probe — it stays a single request per host.
+
 ### `t3ctl project create <title> <workspace-root>`
 
 Register an existing directory on the host as a project. The path is resolved
@@ -264,9 +294,9 @@ reachable URL works.** There's nothing to configure beyond `host add`.
 and give each host its own short name:
 
 ```sh
-t3ctl host add laptop  http://localhost:3773                  eyJ2Ijox...
-t3ctl host add desktop https://studio.tailnet-1234.ts.net     eyJ2Ijox...
-t3ctl host add builder http://10.0.0.42:3773                  eyJ2Ijox...
+t3ctl host add http://localhost:3773               eyJ2Ijox...
+t3ctl host add https://studio.tailnet-1234.ts.net  eyJ2Ijox...
+t3ctl host add http://10.0.0.42:3773               eyJ2Ijox...
 t3ctl ls -t
 ```
 
@@ -274,8 +304,10 @@ t3ctl ls -t
 up as `unreachable` and don't block the rest.
 
 T3 Code's own **T3 Connect relay** (what the mobile app uses when you're off your
-tailnet) is **not implemented in t3ctl** — the transports above are the options
-today.
+tailnet) is **not planned**: the relay's `dpop-token` exchange only accepts a
+Clerk *session* JWT carrying the relay audience, and its allowed scopes are keyed
+by `client_id`, which is pinned to `t3-mobile` and `t3-web`. A third-party CLI has
+no way to present either. The transports above are the options.
 
 ## Limitations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gobius/t3ctl",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Controller CLI for T3 Code hosts — list and drive threads across machines",
   "keywords": [

package/t3ctl.mjs

@@ -22,7 +22,7 @@ const writeHosts = (hosts) => {
 
 const snapshot = async (host) => {
   const res = await fetch(`${host.origin}/api/orchestration/snapshot`, {
-    headers: { authorization: `Bearer ${host.token}` },
+    headers: host.token ? { authorization: `Bearer ${host.token}` } : {},
     signal: AbortSignal.timeout(host.timeoutMs ?? 15000),
   });
   if (!res.ok) throw new Error(`${host.name}: HTTP ${res.status} ${await res.text().catch(() => '')}`.trim());
@@ -67,7 +67,7 @@ const cmdLs = async (args) => {
   const showAll = args.includes('--all') || args.includes('-a');
   const asJson = args.includes('--json');
   const hosts = readHosts();
-  if (!hosts.length) return console.error('No hosts registered. Run: t3ctl host add <name> <origin> <token>');
+  if (!hosts.length) return console.error('No hosts registered. Run: t3ctl host add <origin> <token>');
 
   const { ok, failed } = await collect(hosts);
 
@@ -111,22 +111,135 @@ const cmdLs = async (args) => {
   for (const f of failed) console.error(`\n\x1b[31munreachable\x1b[0m ${f.host.name}: ${f.error}`);
 };
 
-const cmdHost = (args) => {
+// ---- host registry ------------------------------------------------------
+// The descriptor at /.well-known/t3/environment is UNAUTHENTICATED, so probing
+// it answers "is anyone home, and is it T3 Code?" without a token — a wrong
+// origin fails here instead of as a baffling 401 on the first real call.
+// Schema: ExecutionEnvironmentDescriptor in packages/contracts/src/environment.ts.
+
+const DESCRIPTOR_PATH = '/.well-known/t3/environment';
+
+const probe = async (origin, timeoutMs = 5000) => {
+  let res;
+  try {
+    res = await fetch(`${origin}${DESCRIPTOR_PATH}`, { signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    // Node's fetch reports a bare "fetch failed"; the cause carries the real reason.
+    const why = error.name === 'TimeoutError' ? `no response in ${timeoutMs}ms`
+      : (error.cause?.message ?? error.message);
+    throw new Error(`cannot reach ${origin}: ${why}`);
+  }
+  const notT3 = (why) => new Error(`not a T3 Code server (${DESCRIPTOR_PATH} ${why})`);
+  if (!res.ok) throw notT3(`returned HTTP ${res.status}`);
+  let d;
+  try { d = await res.json(); } catch { throw notT3('is not JSON'); }
+  const missing = ['environmentId', 'label', 'serverVersion'].filter((k) => typeof d?.[k] !== 'string' || !d[k]);
+  if (missing.length) throw notT3(`is missing ${missing.join(', ')}`);
+  return { environmentId: d.environmentId, label: d.label, serverVersion: d.serverVersion };
+};
+
+const shortId = (id) => (id ? id.slice(0, 8) : '-');
+const warn = (message) => console.error(`\x1b[33mwarning\x1b[0m ${message}`);
+
+// The name is what you type in --host, so derive a typeable slug from the label
+// rather than using the label verbatim.
+const slugify = (label) => label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'host';
+
+const uniqueName = (base, hosts) => {
+  if (!hosts.some((h) => h.name === base)) return base;
+  for (let n = 2; ; n++) if (!hosts.some((h) => h.name === `${base}-${n}`)) return `${base}-${n}`;
+};
+
+const isOrigin = (value) => /^https?:\/\//i.test(value ?? '');
+
+// Two accepted shapes, told apart by the scheme:
+//   host add <origin> [token] [--name <n>]     current
+//   host add <name> <origin> <token>           legacy, still works
+const parseHostAdd = (pos) => {
+  if (isOrigin(pos[0])) return { origin: pos[0], token: pos[1] ?? null, legacy: false };
+  if (isOrigin(pos[1])) return { name: pos[0], origin: pos[1], token: pos[2] ?? null, legacy: true };
+  return null;
+};
+
+const HOST_ADD_USAGE = 'usage: t3ctl host add <origin> [token] [--name <name>]\n' +
+  '       an origin needs a scheme, e.g. http://localhost:3773';
+
+const cmdHostAdd = async (pos, flags, hosts) => {
+  // Validate before any network or registry work so a bare `host add` prints
+  // usage instead of stalling on a probe.
+  const parsed = parseHostAdd(pos);
+  if (!parsed) return usage(HOST_ADD_USAGE);
+  if ('name' in flags && !flags.name) return usage(HOST_ADD_USAGE);
+  if (parsed.legacy) warn('"host add <name> <origin> <token>" is deprecated — use: t3ctl host add <origin> [token] [--name <name>]');
+
+  const origin = parsed.origin.replace(/\/$/, '');
+  const descriptor = await probe(origin);
+  const existing = hosts.find((h) => h.origin === origin);
+
+  // A changed environmentId on a known origin means the origin now points at a
+  // different machine — the stored token almost certainly belongs to the old one.
+  if (existing?.environmentId && existing.environmentId !== descriptor.environmentId) {
+    warn(`${origin} is now a DIFFERENT environment\n` +
+      `  was ${existing.environmentId} (${existing.label ?? 'unknown'})\n` +
+      `  now ${descriptor.environmentId} (${descriptor.label})\n` +
+      `  the token stored for "${existing.name}" was issued by the old one and will likely fail`);
+  }
+
+  const name = flags.name ?? parsed.name ?? existing?.name ??
+    uniqueName(slugify(descriptor.label), hosts);
+  const token = parsed.token ?? existing?.token ?? null;
+
+  const others = hosts.filter((h) => h.name !== name && h.origin !== origin && h.serverVersion);
+  const skewed = [...new Set(others.map((h) => h.serverVersion))].filter((v) => v !== descriptor.serverVersion);
+  if (skewed.length) warn(`serverVersion ${descriptor.serverVersion} differs from other hosts: ${skewed.join(', ')}`);
+
+  writeHosts(hosts.filter((h) => h.name !== name && h.origin !== origin).concat({
+    name, origin, token,
+    environmentId: descriptor.environmentId,
+    label: descriptor.label,
+    serverVersion: descriptor.serverVersion,
+  }));
+  console.log(`added ${bold(name)} -> ${origin}\n  label   ${descriptor.label}\n` +
+    `  env     ${descriptor.environmentId}\n  version ${descriptor.serverVersion}`);
+  if (!token) warn(`no token stored for ${name} — reads will fail until you run: t3ctl host add ${origin} <token>`);
+};
+
+const cmdHostsList = async (hosts) => {
+  if (!hosts.length) return console.log('(no hosts)');
+  const probes = await Promise.allSettled(hosts.map((h) => probe(h.origin)));
+  const drifted = [];
+  hosts.forEach((h, i) => {
+    const p = probes[i];
+    const live = p.status === 'fulfilled' ? p.value : null;
+    if (live && h.environmentId && h.environmentId !== live.environmentId) drifted.push({ h, live });
+    const icon = live ? ICON.running : ICON.error;
+    const label = live?.label ?? h.label ?? '-';
+    const env = shortId(live?.environmentId ?? h.environmentId);
+    const version = live?.serverVersion ?? h.serverVersion ?? '-';
+    // Values for an unreachable host are whatever was last stored, so dim the
+    // whole row to keep remembered data visually distinct from probed data.
+    const cell = (text, width) => (live ? text.padEnd(width) : dim(text.padEnd(width)));
+    console.log(`${icon} ${live ? bold(h.name.padEnd(14)) : dim(h.name.padEnd(14))} ${cell(label, 18)} ${dim(env.padEnd(9))} ${cell(version, 28)} ${dim(h.origin)}` +
+      (live ? '' : ` ${dim(p.reason.message)}`));
+  });
+  for (const { h, live } of drifted) {
+    warn(`${h.name} (${h.origin}) is now a DIFFERENT environment\n` +
+      `  was ${h.environmentId} (${h.label ?? 'unknown'})\n  now ${live.environmentId} (${live.label})`);
+  }
+};
+
+const cmdHost = async (args) => {
   const [sub, ...rest] = args;
+  const { flags, pos } = parseArgs(rest);
   const hosts = readHosts();
-  if (sub === 'add') {
-    const [name, origin, token] = rest;
-    if (!name || !origin || !token) return usage('usage: t3ctl host add <name> <origin> <token>');
-    const next = hosts.filter((h) => h.name !== name).concat({ name, origin: origin.replace(/\/$/, ''), token });
-    writeHosts(next);
-    console.log(`added ${name} -> ${origin}`);
-  } else if (sub === 'rm') {
-    writeHosts(hosts.filter((h) => h.name !== rest[0]));
-    console.log(`removed ${rest[0]}`);
-  } else {
-    if (!hosts.length) return console.log('(no hosts)');
-    for (const h of hosts) console.log(`${h.name.padEnd(16)} ${h.origin}  ${dim('token:' + h.token.slice(0, 8) + '…')}`);
+  if (sub === 'add') return cmdHostAdd(pos, flags, hosts);
+  if (sub === 'rm') {
+    if (!pos[0]) return usage('usage: t3ctl host rm <name>');
+    writeHosts(hosts.filter((h) => h.name !== pos[0]));
+    console.log(`removed ${pos[0]}`);
+    return;
   }
+  return cmdHostsList(hosts);
 };
 
 
@@ -135,7 +248,7 @@ const cmdHost = (args) => {
 // commandId is the idempotency key, so retries are safe.
 // Schemas: packages/contracts/src/orchestration.ts in pingdotgg/t3code.
 
-const VALUE_FLAGS = ['host', 'model', 'branch', 'runtime-mode', 'interaction-mode', 'worktree'];
+const VALUE_FLAGS = ['host', 'model', 'branch', 'runtime-mode', 'interaction-mode', 'worktree', 'name'];
 
 const parseArgs = (argv) => {
   const flags = {}, pos = [];
@@ -155,7 +268,7 @@ const pickHost = (flags) => {
     if (!h) throw new Error(`no such host: ${flags.host}`);
     return h;
   }
-  if (!hosts.length) throw new Error('no hosts registered — run: t3ctl host add <name> <origin> <token>');
+  if (!hosts.length) throw new Error('no hosts registered — run: t3ctl host add <origin> <token>');
   if (hosts.length > 1) throw new Error(`multiple hosts; pass --host <${hosts.map((h) => h.name).join('|')}>`);
   return hosts[0];
 };
@@ -163,7 +276,7 @@ const pickHost = (flags) => {
 const dispatch = async (host, command) => {
   const res = await fetch(`${host.origin}/api/orchestration/dispatch`, {
     method: 'POST',
-    headers: { authorization: `Bearer ${host.token}`, 'content-type': 'application/json' },
+    headers: { ...(host.token ? { authorization: `Bearer ${host.token}` } : {}), 'content-type': 'application/json' },
     body: JSON.stringify(command),
     signal: AbortSignal.timeout(host.timeoutMs ?? 15000),
   });
@@ -309,9 +422,9 @@ if (!commands[cmd]) {
   console.log(`t3ctl — control T3 Code hosts
 
   t3ctl ls [-t|--threads] [-a|--all] [--json]   list projects and threads across hosts
-  t3ctl host add <name> <origin> <token>        register a host
+  t3ctl host add <origin> [token] [--name <n>]  register a host (probes it first)
   t3ctl host rm <name>                          remove a host
-  t3ctl hosts                                   list registered hosts
+  t3ctl hosts                                   list hosts and probe each one
 
   t3ctl project create <title> <root>           create a project for an existing dir
   t3ctl thread create <project> <title>         start a thread (--model inst/model,