@rigxyz/tapd 0.1.0 → 0.4.0

package/dist/bin.js

@@ -2,33 +2,99 @@
 import {
   AlreadyInitializedError,
   AlreadyJoinedError,
+  ImportTokenScopeError,
+  ImportValidationFailed,
   InvalidInviteUrlError,
   NotInitializedError,
   RelayClient,
   STATE_KEY_CONFLICT_COUNT,
+  addImport,
   bindingConfigFile,
   computeLocalDiff,
   findConflictSidecars,
+  importStateDbPath,
   init,
   join,
   list,
   loadIgnore,
+  loadImportMounts,
   mint,
   openStateDb,
   readBindingConfig,
+  removeImport,
   revoke,
   start
-} from "./chunk-RQC73B5Y.js";
+} from "./chunk-YPZ2UNI5.js";
 
 // src/bin.ts
-import { join as pathJoin, resolve } from "path";
+import { join as pathJoin, resolve as resolve2 } from "path";
 import kleur from "kleur";
 
+// src/defaults.ts
+var DEFAULT_RELAY_URL = "https://tap-relay.fly.dev";
+
+// src/hub-token.ts
+import { readFileSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+function rigConfigPath() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.trim() !== "" ? xdg : join2(homedir(), ".config");
+  return join2(base, "rig", "config.json");
+}
+var HubTokenMissingError = class extends Error {
+  constructor() {
+    super(
+      "no hub token \u2014 run `rig login` first, or set RIG_HUB_TOKEN. tapd needs an authenticated session to create/join bindings."
+    );
+    this.name = "HubTokenMissingError";
+  }
+};
+function readHubToken(opts = {}) {
+  const fromEnv = process.env.RIG_HUB_TOKEN?.trim();
+  if (fromEnv) return fromEnv;
+  const path = opts.configPath ?? rigConfigPath();
+  if (!existsSync(path)) throw new HubTokenMissingError();
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    throw new HubTokenMissingError();
+  }
+  if (parsed && typeof parsed === "object" && "hub_token" in parsed) {
+    const t = parsed.hub_token;
+    if (typeof t === "string" && t.trim() !== "") return t.trim();
+  }
+  throw new HubTokenMissingError();
+}
+
+// src/members.ts
+function clientFor(rootDir, fetchImpl) {
+  const cfg = readBindingConfig(rootDir);
+  if (!cfg) throw new NotInitializedError(rootDir);
+  return new RelayClient({
+    baseUrl: cfg.relayUrl,
+    bindingId: cfg.bindingId,
+    token: cfg.token,
+    fetch: fetchImpl
+  });
+}
+async function list2(opts) {
+  const res = await clientFor(opts.rootDir, opts.fetch).listMembers();
+  return res.members;
+}
+async function remove(opts) {
+  return clientFor(opts.rootDir, opts.fetch).removeMember(opts.userId);
+}
+async function setRole(opts) {
+  return clientFor(opts.rootDir, opts.fetch).setMemberRole(opts.userId, opts.role);
+}
+
 // src/pidfile.ts
 import {
-  existsSync,
+  existsSync as existsSync2,
   mkdirSync,
-  readFileSync,
+  readFileSync as readFileSync2,
   unlinkSync,
   writeFileSync
 } from "fs";
@@ -53,10 +119,10 @@ function isProcessAlive(pid) {
   }
 }
 function readLivePid(path) {
-  if (!existsSync(path)) return null;
+  if (!existsSync2(path)) return null;
   let raw;
   try {
-    raw = readFileSync(path, "utf8").trim();
+    raw = readFileSync2(path, "utf8").trim();
   } catch {
     return null;
   }
@@ -73,10 +139,10 @@ function acquire(path) {
   writeFileSync(path, String(process.pid), { mode: 384 });
 }
 function release(path) {
-  if (!existsSync(path)) return;
+  if (!existsSync2(path)) return;
   let raw;
   try {
-    raw = readFileSync(path, "utf8").trim();
+    raw = readFileSync2(path, "utf8").trim();
   } catch {
     return;
   }
@@ -88,12 +154,131 @@ function release(path) {
   }
 }
 
+// src/history.ts
+var PAGE_LIMIT = 500;
+function clientFor2(rootDir, fetchImpl) {
+  const cfg = readBindingConfig(rootDir);
+  if (!cfg) throw new NotInitializedError(rootDir);
+  return new RelayClient({
+    baseUrl: cfg.relayUrl,
+    bindingId: cfg.bindingId,
+    token: cfg.token,
+    fetch: fetchImpl
+  });
+}
+async function history(opts) {
+  const client = clientFor2(opts.rootDir, opts.fetch);
+  const events = [];
+  let after = void 0;
+  while (true) {
+    const page = await client.listChanges({
+      after,
+      limit: PAGE_LIMIT,
+      path: opts.path,
+      ...opts.untilInclusive ? { untilInclusive: opts.untilInclusive } : {}
+    });
+    events.push(...page.events);
+    if (page.events.length < PAGE_LIMIT) break;
+    after = page.cursor;
+  }
+  return events.reverse();
+}
+
+// src/restore.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, renameSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join3, resolve } from "path";
+var PathNeverExistedError = class extends Error {
+  constructor(path) {
+    super(`No events for path "${path}" \u2014 never written through this binding.`);
+    this.path = path;
+    this.name = "PathNeverExistedError";
+  }
+  path;
+};
+var PathCurrentlyDeletedError = class extends Error {
+  constructor(path, lastCursor) {
+    super(
+      `Path "${path}" is currently deleted (last event: ${lastCursor}). Pass --as-of <cursor> with a cursor before the delete to restore an earlier version.`
+    );
+    this.path = path;
+    this.lastCursor = lastCursor;
+    this.name = "PathCurrentlyDeletedError";
+  }
+  path;
+  lastCursor;
+};
+var HashMismatchError = class extends Error {
+  constructor(path, expected, actual) {
+    super(`Hash mismatch restoring "${path}": expected ${expected}, got ${actual}`);
+    this.path = path;
+    this.expected = expected;
+    this.actual = actual;
+    this.name = "HashMismatchError";
+  }
+  path;
+  expected;
+  actual;
+};
+function clientFor3(rootDir, fetchImpl) {
+  const cfg = readBindingConfig(rootDir);
+  if (!cfg) throw new NotInitializedError(rootDir);
+  return new RelayClient({
+    baseUrl: cfg.relayUrl,
+    bindingId: cfg.bindingId,
+    token: cfg.token,
+    fetch: fetchImpl
+  });
+}
+function sha256Hex(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+async function restore(opts) {
+  const events = await history({
+    rootDir: opts.rootDir,
+    path: opts.path,
+    ...opts.asOf ? { untilInclusive: opts.asOf } : {},
+    ...opts.fetch ? { fetch: opts.fetch } : {}
+  });
+  if (events.length === 0) {
+    throw new PathNeverExistedError(opts.path);
+  }
+  if (!opts.asOf && events[0].op === "delete") {
+    throw new PathCurrentlyDeletedError(opts.path, events[0].id);
+  }
+  const writeEvent = events.find((e) => e.op === "write" && e.hash != null);
+  if (!writeEvent || !writeEvent.hash) {
+    throw new PathNeverExistedError(opts.path);
+  }
+  const client = clientFor3(opts.rootDir, opts.fetch);
+  const dl = await client.downloadUrl(writeEvent.hash);
+  const bytes = await client.getObjectBytes(dl.downloadUrl);
+  const actualHash = `sha256:${sha256Hex(bytes)}`;
+  if (actualHash !== writeEvent.hash) {
+    throw new HashMismatchError(opts.path, writeEvent.hash, actualHash);
+  }
+  const targetAbs = resolve(opts.rootDir, opts.path);
+  const overwrote = existsSync3(targetAbs);
+  mkdirSync2(dirname2(targetAbs), { recursive: true });
+  const tmp = `${targetAbs}.tap-restore-tmp.${Date.now().toString(36)}`;
+  const mode = writeEvent.executable ? 493 : 420;
+  writeFileSync2(tmp, bytes, { mode });
+  renameSync(tmp, targetAbs);
+  return {
+    path: opts.path,
+    restoredFromCursor: writeEvent.id,
+    hash: writeEvent.hash,
+    size: bytes.length,
+    overwrote
+  };
+}
+
 // src/status.ts
-import { existsSync as existsSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { join as join4 } from "path";
 
 // src/version.ts
-var TAPD_VERSION = "0.1.0";
+var TAPD_VERSION = "0.4.0";
 
 // src/status.ts
 var STATE_KEY_LAST_APPLY_ERROR = "last_apply_error";
@@ -105,9 +290,9 @@ function statusToJson(report) {
   return {
     protocolVersion: STATUS_PROTOCOL_VERSION,
     version: TAPD_VERSION,
-    bindingId: report.config.bindingId,
-    relayUrl: report.config.relayUrl,
-    deviceId: report.config.deviceId,
+    bindingId: report.config?.bindingId ?? null,
+    relayUrl: report.config?.relayUrl ?? null,
+    deviceId: report.config?.deviceId ?? null,
     daemon: report.daemon,
     cursor: report.cursor,
     remoteCursor: report.remoteCursor,
@@ -116,15 +301,67 @@ function statusToJson(report) {
     pendingUploads: report.pendingUploads,
     conflicts: report.conflicts,
     lastApplyError: report.lastApplyError,
-    offline: report.offline
+    offline: report.offline,
+    mounts: report.mounts
   };
 }
+function readMounts(rootDir) {
+  const loaded = loadImportMounts(rootDir);
+  const mounts = [];
+  const readyPaths = [];
+  for (const spec of loaded.ready) {
+    let cursor;
+    const dbPath = importStateDbPath(rootDir, spec.name);
+    if (existsSync4(dbPath)) {
+      const db = openStateDb(dbPath);
+      try {
+        cursor = db.getCursor();
+      } finally {
+        db.close();
+      }
+    }
+    mounts.push({
+      name: spec.name,
+      path: spec.path,
+      state: "ok",
+      bindingId: spec.bindingId,
+      ...cursor ? { cursor } : {}
+    });
+    readyPaths.push(spec.path);
+  }
+  for (const b of loaded.broken) {
+    mounts.push({ name: b.name, path: b.path, state: "misconfigured", reason: b.reason });
+  }
+  mounts.sort((a, b) => a.name.localeCompare(b.name));
+  return { mounts, readyPaths };
+}
 async function status(opts) {
   const config = readBindingConfig(opts.rootDir);
+  const { mounts, readyPaths } = readMounts(opts.rootDir);
+  const pidfilePath = join4(opts.rootDir, DAEMON_PIDFILE_REL);
+  const livePid = readLivePid(pidfilePath);
+  const daemon = livePid !== null ? { running: true, pid: livePid } : { running: false };
   if (!config) {
-    throw new NotInitializedError(opts.rootDir);
+    if (mounts.length === 0) {
+      throw new NotInitializedError(opts.rootDir);
+    }
+    return {
+      config: null,
+      cursor: "chg_0",
+      remoteCursor: "chg_0",
+      trackedPaths: 0,
+      pendingPeek: [],
+      pendingApplies: 0,
+      pendingUploads: 0,
+      conflicts: [],
+      conflictCount: 0,
+      lastApplyError: null,
+      daemon,
+      offline: false,
+      mounts
+    };
   }
-  const db = openStateDb(join2(opts.rootDir, ".rig", "tap", "state.local.db"));
+  const db = openStateDb(join4(opts.rootDir, ".rig", "tap", "state.local.db"));
   try {
     const cursor = db.getCursor();
     const tracked = db.listPaths().length;
@@ -135,9 +372,6 @@ async function status(opts) {
     const lastErrJson = db.getMeta(STATE_KEY_LAST_APPLY_ERROR);
     const lastErrAt = db.getMeta(STATE_KEY_LAST_APPLY_ERROR_AT);
     const lastApplyError = lastErrJson ? safeParseLastError(lastErrJson, lastErrAt) : null;
-    const pidfilePath = join2(opts.rootDir, DAEMON_PIDFILE_REL);
-    const livePid = readLivePid(pidfilePath);
-    const daemon = livePid !== null ? { running: true, pid: livePid } : { running: false };
     const client = new RelayClient({
       baseUrl: config.relayUrl,
       bindingId: config.bindingId,
@@ -160,9 +394,14 @@ async function status(opts) {
     const pendingApplies = remoteEvents.length;
     const remoteCursor = remoteEvents.length > 0 ? remoteEvents[remoteEvents.length - 1].id : cursor;
     let pendingUploads = 0;
-    if (existsSync2(opts.rootDir)) {
+    if (existsSync4(opts.rootDir)) {
       const ignore = loadIgnore(opts.rootDir);
-      const diff = await computeLocalDiff({ rootDir: opts.rootDir, stateDb: db, ignore });
+      const diff = await computeLocalDiff({
+        rootDir: opts.rootDir,
+        stateDb: db,
+        ignore,
+        excludePaths: readyPaths
+      });
       pendingUploads = diff.writes.length + diff.deletes.length + diff.mkdirs.length + diff.rmdirs.length;
     }
     const conflicts = findConflictSidecars(opts.rootDir);
@@ -178,7 +417,8 @@ async function status(opts) {
       conflictCount,
       lastApplyError,
       daemon,
-      offline
+      offline,
+      mounts
     };
   } finally {
     db.close();
@@ -204,13 +444,13 @@ function safeParseLastError(json, at) {
 
 // src/uninit.ts
 import {
-  existsSync as existsSync3,
+  existsSync as existsSync5,
   rmSync,
   rmdirSync,
   statSync,
   unlinkSync as unlinkSync2
 } from "fs";
-import { join as join3 } from "path";
+import { join as join5 } from "path";
 var DAEMON_PIDFILE_REL2 = ".rig/tap/daemon.pid";
 var STATE_DIR_REL = ".rig/tap";
 var DaemonStillRunningError = class extends Error {
@@ -226,14 +466,14 @@ function uninit(opts) {
   if (!config) {
     throw new NotInitializedError(opts.rootDir);
   }
-  const pidfilePath = join3(opts.rootDir, DAEMON_PIDFILE_REL2);
+  const pidfilePath = join5(opts.rootDir, DAEMON_PIDFILE_REL2);
   const livePid = readLivePid(pidfilePath);
   if (livePid !== null) {
     throw new DaemonStillRunningError(livePid);
   }
-  const stateDbPath = join3(opts.rootDir, ".rig", "tap", "state.local.db");
+  const stateDbPath = join5(opts.rootDir, ".rig", "tap", "state.local.db");
   const tracked = [];
-  if (existsSync3(stateDbPath)) {
+  if (existsSync5(stateDbPath)) {
     const db = openStateDb(stateDbPath);
     try {
       for (const p of db.listPaths()) {
@@ -253,7 +493,7 @@ function uninit(opts) {
     const files = tracked.filter((t) => !t.isDir);
     const dirs = tracked.filter((t) => t.isDir).sort((a, b) => b.path.split("/").length - a.path.split("/").length);
     for (const f of files) {
-      const abs = join3(opts.rootDir, f.path);
+      const abs = join5(opts.rootDir, f.path);
       try {
         const st = statSync(abs);
         if (st.isFile()) {
@@ -271,7 +511,7 @@ function uninit(opts) {
       }
     }
     for (const d of dirs) {
-      const abs = join3(opts.rootDir, d.path);
+      const abs = join5(opts.rootDir, d.path);
       try {
         rmdirSync(abs);
         dirsRemoved += 1;
@@ -288,15 +528,15 @@ function uninit(opts) {
     }
   }
   const cfgPath = bindingConfigFile(opts.rootDir);
-  if (existsSync3(cfgPath)) {
+  if (existsSync5(cfgPath)) {
     try {
       unlinkSync2(cfgPath);
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
     }
   }
-  const stateDir = join3(opts.rootDir, STATE_DIR_REL);
-  if (existsSync3(stateDir)) {
+  const stateDir = join5(opts.rootDir, STATE_DIR_REL);
+  if (existsSync5(stateDir)) {
     rmSync(stateDir, { recursive: true, force: true });
   }
   return {
@@ -325,32 +565,43 @@ function help() {
 ${C.bold().cyan("COMMANDS")}
   ${C.green("tapd init")}    bootstrap a binding in the current directory
   ${C.green("tapd invite")}  mint / list / revoke invite URLs (owner only)
+  ${C.green("tapd members")} list / remove / set-role for binding members (owner only for write ops)
   ${C.green("tapd join")}    accept an invite URL into the current directory
+  ${C.green("tapd import")}  mount another binding read-only into a subdir (meta-rig)
   ${C.green("tapd start")}   run the watch + apply daemon (foreground)
   ${C.green("tapd status")}  show binding + cursor + pending remote events
+  ${C.green("tapd history")} list ChangeEvents for a single path (recovery)
+  ${C.green("tapd restore")} bring a file back from the relay's event log
   ${C.green("tapd uninit")}  disconnect this checkout (optionally --purge tracked files)
   ${C.green("tapd help")}    this message
 
+${C.dim("Identity:")} tapd doesn't manage its own credentials \u2014 init/join
+read a Clerk JWT from RIG_HUB_TOKEN (set by rig when shelling out) or
+from ~/.config/rig/config.json (set by ${C.green("rig login")}).
+
 ${C.dim("--version / -v")} print the tapd binary version on stdout and exit.
 ${C.dim("--json")} on init / invite / join / status / uninit emits a versioned
 JSON payload to stdout (protocolVersion: 1) for programmatic consumers (rig).
 
 ${C.bold().cyan("tapd init OPTIONS")}
   ${C.dim("--name <n>")}              binding display name (required)
-  ${C.dim("--owner-user-id <u>")}     placeholder user id (Phase 3 sources from Clerk)
-  ${C.dim("--relay <url>")}           default http://127.0.0.1:4030
+  ${C.dim("--relay <url>")}           override (defaults to the logged-in relay)
   ${C.dim("--device-label <l>")}      default 'owner'
   ${C.dim("--dir <path>")}            default cwd
 
 ${C.bold().cyan("tapd join OPTIONS")}
   ${C.dim("<invite-url>")}            positional \u2014 full URL from \`rig invite\` /
-                                relay (.../v1/invites/<secret>/accept)
-  ${C.dim("--user-id <u>")}           Phase 3 placeholder until Clerk
-  ${C.dim("--email <e>")}             optional; required if the invite has
-                                an emailConstraint
+                                relay or dashboard
+  ${C.dim("--anonymous")}             accept a pure-capability invite without an account
   ${C.dim("--device-label <l>")}      default 'device'
   ${C.dim("--dir <path>")}            default cwd
 
+${C.bold().cyan("tapd members SUBCOMMANDS")}
+  ${C.green("tapd members list")}                     list members (any active member can read)
+  ${C.green("tapd members remove <userId>")}          remove + cascade-revoke their tokens (owner)
+  ${C.green("tapd members set-role <userId> <role>")} change role: owner | editor | viewer (owner)
+    ${C.dim("--dir <path>")}                          default cwd
+
 ${C.bold().cyan("tapd invite SUBCOMMANDS")}
   ${C.green("tapd invite create")}    mint a new invite + print the URL once
     ${C.dim("--ops <read,write,subscribe>")}    default read,write,subscribe
@@ -409,10 +660,106 @@ function collectPathGlobs(flags2) {
   const parts = raw.split(",").map((s) => s.trim()).filter(Boolean);
   return parts.length > 0 ? parts : void 0;
 }
+async function runMembers(positional2, flags2) {
+  const json = flags2.get("json") === true;
+  const sub = positional2[0];
+  const rootDir = resolve2(flags2.get("dir") ?? process.cwd());
+  const VALID_ROLES2 = /* @__PURE__ */ new Set(["owner", "editor", "viewer"]);
+  try {
+    if (sub === void 0 || sub === "list") {
+      const members = await list2({ rootDir });
+      if (json) {
+        printJson({ protocolVersion: PROTOCOL_VERSION, members });
+        return;
+      }
+      const C = kleur;
+      if (members.length === 0) {
+        console.log(C.dim("no members"));
+        return;
+      }
+      console.log(C.bold().cyan("tapd members"));
+      for (const m of members) {
+        const roleColor = m.role === "owner" ? C.yellow : m.role === "editor" ? C.green : C.dim;
+        const emailSuffix = m.email ? `  ${C.dim(m.email)}` : "";
+        console.log(
+          `  ${C.bold(m.userId)}  ${roleColor(m.role.padEnd(7))}${emailSuffix}  ${C.dim(`joined ${m.joinedAt}`)}`
+        );
+      }
+      return;
+    }
+    if (sub === "remove") {
+      const userId = positional2[1];
+      if (!userId) {
+        if (json) printJsonError("missing_argument", "usage: tapd members remove <userId>");
+        else console.error(kleur.red("error:"), "usage: tapd members remove <userId>");
+        process.exit(2);
+      }
+      const result = await remove({ rootDir, userId });
+      if (json) {
+        printJson({
+          protocolVersion: PROTOCOL_VERSION,
+          userId,
+          removed: result.removed,
+          tokensRevoked: result.tokensRevoked
+        });
+        return;
+      }
+      const C = kleur;
+      console.log(
+        `${C.green("\u2713")} removed ${C.bold(userId)}  ${C.dim(`(${result.tokensRevoked} token${result.tokensRevoked === 1 ? "" : "s"} revoked)`)}`
+      );
+      return;
+    }
+    if (sub === "set-role") {
+      const userId = positional2[1];
+      const role = positional2[2];
+      if (!userId || !role) {
+        if (json) printJsonError("missing_argument", "usage: tapd members set-role <userId> <owner|editor|viewer>");
+        else console.error(kleur.red("error:"), "usage: tapd members set-role <userId> <owner|editor|viewer>");
+        process.exit(2);
+      }
+      if (!VALID_ROLES2.has(role)) {
+        if (json) printJsonError("invalid_role", `invalid role '${role}' (allowed: owner|editor|viewer)`);
+        else console.error(kleur.red("error:"), `invalid role '${role}' (allowed: owner|editor|viewer)`);
+        process.exit(2);
+      }
+      const result = await setRole({
+        rootDir,
+        userId,
+        role
+      });
+      if (json) {
+        printJson({
+          protocolVersion: PROTOCOL_VERSION,
+          userId,
+          role: result.role,
+          changed: result.changed
+        });
+        return;
+      }
+      const C = kleur;
+      console.log(`${C.green("\u2713")} ${C.bold(userId)} \u2192 ${C.bold(role)}`);
+      return;
+    }
+    if (json) printJsonError("unknown_subcommand", `unknown subcommand: tapd members ${sub}`);
+    else {
+      console.error(kleur.red("error:"), `unknown subcommand: tapd members ${sub}`);
+      console.error("  see `tapd help`");
+    }
+    process.exit(2);
+  } catch (err) {
+    if (err instanceof NotInitializedError) {
+      if (json) printJsonError("not_initialized", err.message);
+      else console.error(kleur.red("error:"), err.message);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
 async function runInvite(positional2, flags2) {
   const json = flags2.get("json") === true;
   const sub = positional2[0];
-  const rootDir = resolve(flags2.get("dir") ?? process.cwd());
+  const rootDir = resolve2(flags2.get("dir") ?? process.cwd());
   try {
     if (sub === void 0 || sub === "create") {
       const ops = parseOps(flags2.get("ops"));
@@ -543,22 +890,32 @@ async function runJoin(positional2, flags2) {
     if (json) printJsonError("missing_argument", "missing invite URL");
     else {
       console.error(kleur.red("error:"), "missing invite URL");
-      console.error("  usage: tapd join <invite-url> --user-id <u>");
+      console.error("  usage: tapd join <invite-url>");
     }
     process.exit(2);
   }
-  const userId = flags2.get("user-id");
-  if (!userId) {
-    if (json) printJsonError("missing_flag", "--user-id is required (placeholder until Clerk)");
-    else console.error(kleur.red("error:"), "--user-id is required (Phase 3 placeholder until Clerk)");
-    process.exit(2);
+  const anonymous = flags2.get("anonymous") === true;
+  let accessToken = null;
+  if (!anonymous) {
+    try {
+      accessToken = readHubToken();
+    } catch (err) {
+      if (err instanceof HubTokenMissingError) {
+        if (json) printJsonError("not_logged_in", err.message);
+        else {
+          console.error(kleur.red("error:"), err.message);
+          console.error(kleur.dim("  pass --anonymous for a pure-capability invite, or run `rig login`."));
+        }
+        process.exit(1);
+      }
+      throw err;
+    }
   }
-  const rootDir = resolve(flags2.get("dir") ?? process.cwd());
-  const email = flags2.get("email");
+  const rootDir = resolve2(flags2.get("dir") ?? process.cwd());
   const deviceLabel = flags2.get("device-label");
   let result;
   try {
-    result = await join({ rootDir, inviteUrl, userId, email, deviceLabel });
+    result = await join({ rootDir, inviteUrl, accessToken, deviceLabel });
   } catch (err) {
     if (err instanceof AlreadyJoinedError) {
       if (json) printJsonError("already_joined", err.message);
@@ -597,9 +954,132 @@ async function runJoin(positional2, flags2) {
   console.log("");
   console.log(C.dim("  Next: `tapd start` (initial apply pulls the remote manifest)."));
 }
+async function runImport(positional2, flags2) {
+  const json = flags2.get("json") === true;
+  const rootDir = resolve2(flags2.get("dir") ?? process.cwd());
+  const sub = positional2[0];
+  if (sub === "remove") {
+    const name = positional2[1];
+    if (!name) {
+      if (json) printJsonError("missing_argument", "usage: tapd import remove <name>");
+      else console.error(kleur.red("error:"), "usage: tapd import remove <name>");
+      process.exit(2);
+    }
+    let accessToken2 = null;
+    try {
+      accessToken2 = readHubToken();
+    } catch {
+      accessToken2 = null;
+    }
+    const result2 = await removeImport({
+      rootDir,
+      name,
+      purge: flags2.get("purge") === true,
+      accessToken: accessToken2
+    });
+    if (json) {
+      printJson({ protocolVersion: PROTOCOL_VERSION, ...result2, name });
+      return;
+    }
+    const C2 = kleur;
+    if (!result2.removed) {
+      console.log(C2.dim(`no import named "${name}"`));
+      return;
+    }
+    console.log(`${C2.green("\u2713")} removed import ${C2.bold(name)}${result2.purged ? C2.dim(" (purged files)") : ""}`);
+    switch (result2.revoke) {
+      case "revoked":
+        console.log(C2.dim("  grant relinquished on the relay."));
+        break;
+      case "not-creator":
+        console.log(
+          C2.yellow("  note:") + " the grant belongs to another user and remains active \u2014 only its owner can revoke it."
+        );
+        break;
+      case "no-token":
+        console.log(C2.yellow("  note:") + " not signed in \u2014 the grant was not revoked. Run `rig login`, then re-remove, to relinquish it.");
+        break;
+      case "offline":
+        console.log(C2.yellow("  note:") + " relay unreachable \u2014 local mount removed, grant not yet revoked.");
+        break;
+    }
+    console.log(C2.dim("  restart the daemon to apply: `tapd start`"));
+    return;
+  }
+  const inviteUrl = sub;
+  const mountPath = flags2.get("path");
+  if (!inviteUrl || !mountPath) {
+    const msg = "usage: tapd import <invite-url> --path <subdir> [--name <name>]";
+    if (json) printJsonError("missing_argument", msg);
+    else console.error(kleur.red("error:"), msg);
+    process.exit(2);
+  }
+  const anonymous = flags2.get("anonymous") === true;
+  let accessToken = null;
+  if (!anonymous) {
+    try {
+      accessToken = readHubToken();
+    } catch (err) {
+      if (err instanceof HubTokenMissingError) {
+        if (json) printJsonError("not_logged_in", err.message);
+        else {
+          console.error(kleur.red("error:"), err.message);
+          console.error(kleur.dim("  pass --anonymous for a pure-capability invite, or run `rig login`."));
+        }
+        process.exit(1);
+      }
+      throw err;
+    }
+  }
+  let result;
+  try {
+    result = await addImport({
+      rootDir,
+      inviteUrl,
+      path: mountPath,
+      name: flags2.get("name"),
+      accessToken,
+      deviceLabel: flags2.get("device-label")
+    });
+  } catch (err) {
+    if (err instanceof ImportValidationFailed) {
+      if (json) printJsonError("import_invalid", err.message);
+      else console.error(kleur.red("error:"), err.message);
+      process.exit(2);
+    }
+    if (err instanceof ImportTokenScopeError) {
+      if (json) printJsonError("insufficient_ops", err.message);
+      else console.error(kleur.red("error:"), err.message);
+      process.exit(1);
+    }
+    if (err instanceof InvalidInviteUrlError) {
+      if (json) printJsonError("invalid_invite_url", err.message);
+      else console.error(kleur.red("error:"), err.message);
+      process.exit(2);
+    }
+    throw err;
+  }
+  if (json) {
+    printJson({ protocolVersion: PROTOCOL_VERSION, ...result });
+    return;
+  }
+  const C = kleur;
+  console.log(C.bold().cyan("tapd import"));
+  console.log(`  name:     ${C.bold(result.name)}`);
+  console.log(`  mount:    ${result.path}  ${C.dim("(read-only mirror)")}`);
+  console.log(`  binding:  ${result.bindingId}`);
+  console.log(`  ops:      ${result.ops.join(", ")}`);
+  console.log(C.dim(`    Token stored in ${rootDir}/.rig/tap/imports/${result.name}.local.json (mode 0600).`));
+  if (result.importerBindingVerified === false) {
+    console.log(
+      C.yellow("  note:") + " recorded as a personal import (you \u2192 source); the rig-level edge needs membership in this meta-rig."
+    );
+  }
+  console.log(C.dim("  Next: (re)start the daemon to begin mirroring \u2014 `tapd start`."));
+}
 async function runStatus(flags2) {
   const json = flags2.get("json") === true;
-  const rootDir = resolve(flags2.get("dir") ?? process.cwd());
+  const rootDir = resolve2(flags2.get("dir") ?? process.cwd());
   let report;
   try {
     report = await status({ rootDir });
@@ -619,37 +1099,51 @@ async function runStatus(flags2) {
   }
   const C = kleur;
   console.log(C.bold().cyan("tapd status"));
-  console.log(`  binding:  ${C.bold(report.config.bindingId)}`);
-  console.log(`  relay:    ${report.config.relayUrl}`);
-  console.log(`  device:   ${C.bold(report.config.deviceId)}`);
-  console.log(`  cursor:   ${report.cursor}`);
-  console.log(`  tracked:  ${report.trackedPaths} paths`);
-  if (report.pendingPeek.length === 0) {
-    console.log(`  pending:  ${C.green("up to date")}`);
-  } else {
-    console.log(`  pending:  ${C.yellow(`${report.pendingPeek.length}+ events behind`)}`);
-    for (const ev of report.pendingPeek) {
-      console.log(C.dim(`    ${ev.op.padEnd(6)} ${ev.path}  (${ev.id})`));
+  if (report.config) {
+    console.log(`  binding:  ${C.bold(report.config.bindingId)}`);
+    console.log(`  relay:    ${report.config.relayUrl}`);
+    console.log(`  device:   ${C.bold(report.config.deviceId)}`);
+    console.log(`  cursor:   ${report.cursor}`);
+    console.log(`  tracked:  ${report.trackedPaths} paths`);
+    if (report.pendingPeek.length === 0) {
+      console.log(`  pending:  ${C.green("up to date")}`);
+    } else {
+      console.log(`  pending:  ${C.yellow(`${report.pendingPeek.length}+ events behind`)}`);
+      for (const ev of report.pendingPeek) {
+        console.log(C.dim(`    ${ev.op.padEnd(6)} ${ev.path}  (${ev.id})`));
+      }
+    }
+    if (report.conflictCount > 0) {
+      console.log(
+        `  conflicts: ${C.yellow(String(report.conflictCount))} ${C.dim("(sidecars at *.conflict-from.*)")}`
+      );
+    } else {
+      console.log(`  conflicts: ${C.dim("none")}`);
+    }
+    if (report.lastApplyError) {
+      const e = report.lastApplyError;
+      console.log(
+        `  last err: ${C.red(e.reason)} ${C.dim(`(${e.op} ${e.path} @ ${e.eventId}${e.at ? `, ${e.at}` : ""})`)}`
+      );
     }
-  }
-  if (report.conflictCount > 0) {
-    console.log(
-      `  conflicts: ${C.yellow(String(report.conflictCount))} ${C.dim("(sidecars at *.conflict-from.*)")}`
-    );
   } else {
-    console.log(`  conflicts: ${C.dim("none")}`);
+    console.log(C.dim("  (import-only meta-rig \u2014 no primary binding)"));
   }
-  if (report.lastApplyError) {
-    const e = report.lastApplyError;
-    console.log(
-      `  last err: ${C.red(e.reason)} ${C.dim(`(${e.op} ${e.path} @ ${e.eventId}${e.at ? `, ${e.at}` : ""})`)}`
-    );
+  if (report.mounts.length > 0) {
+    console.log(`  imports:`);
+    for (const m of report.mounts) {
+      if (m.state === "ok") {
+        console.log(`    ${C.green("\u25CF")} ${C.bold(m.name)} \u2192 ${m.path}${m.cursor ? C.dim(`  (${m.cursor})`) : ""}`);
+      } else {
+        console.log(`    ${C.yellow("\u25CB")} ${C.bold(m.name)} ${C.yellow("misconfigured")} ${C.dim(`(${m.reason ?? "unknown"})`)}`);
+      }
+    }
   }
 }
 async function runUninit(flags2) {
   const json = flags2.get("json") === true;
   const purge = flags2.get("purge") === true;
-  const rootDir = resolve(flags2.get("dir") ?? process.cwd());
+  const rootDir = resolve2(flags2.get("dir") ?? process.cwd());
   let result;
   try {
     result = uninit({ rootDir, purge });
@@ -706,7 +1200,7 @@ async function runUninit(flags2) {
   }
 }
 async function runStart(flags2) {
-  const rootDir = resolve(flags2.get("dir") ?? process.cwd());
+  const rootDir = resolve2(flags2.get("dir") ?? process.cwd());
   const pollSeconds = flags2.has("poll-seconds") ? Number(flags2.get("poll-seconds")) : void 0;
   const pidfilePath = flags2.get("no-pidfile") === true ? null : pathJoin(rootDir, DAEMON_PIDFILE_REL3);
   let handle = null;
@@ -750,26 +1244,136 @@ async function runStart(flags2) {
   if (pidfilePath) console.log(`  pid:    ${process.pid}  ${kleur.dim(`(${pidfilePath})`)}`);
   console.log(kleur.dim("  press ctrl+c to stop"));
 }
+async function runHistory(flags2) {
+  const json = flags2.get("json") === true;
+  const rootDir = resolve2(flags2.get("dir") ?? process.cwd());
+  const path = flags2.get("path");
+  const asOf = flags2.get("as-of");
+  if (!path) {
+    if (json) printJsonError("missing_flag", "--path is required");
+    else console.error(kleur.red("error:"), "--path is required (e.g. theses/foo.md)");
+    process.exit(2);
+  }
+  let events;
+  try {
+    events = await history({
+      rootDir,
+      path,
+      ...asOf ? { untilInclusive: asOf } : {}
+    });
+  } catch (err) {
+    if (err instanceof NotInitializedError) {
+      if (json) printJsonError("not_initialized", err.message);
+      else console.error(kleur.red("error:"), err.message);
+      process.exit(1);
+    }
+    if (json) printJsonError("history_failed", err.message);
+    else console.error(kleur.red("error:"), err.message);
+    process.exit(1);
+  }
+  if (json) {
+    printJson({
+      protocolVersion: PROTOCOL_VERSION,
+      path,
+      events
+    });
+    return;
+  }
+  const C = kleur;
+  console.log(C.bold().cyan("tapd history") + " " + C.dim(path));
+  if (events.length === 0) {
+    console.log(C.dim("  (no events \u2014 never written through this binding)"));
+    return;
+  }
+  for (const ev of events) {
+    const dot = ev.op === "delete" ? C.red("\u2022") : ev.op === "write" ? C.green("\u2022") : C.dim("\u2022");
+    const sizeStr = ev.size != null ? `${ev.size}B` : "";
+    const actor = ev.actorUserId ? C.dim(`by ${ev.actorUserId}`) : "";
+    console.log(`  ${dot} ${C.bold(ev.id.padEnd(10))} ${ev.op.padEnd(6)} ${C.dim(ev.createdAt)}  ${sizeStr.padEnd(8)} ${actor}`);
+  }
+}
+async function runRestore(flags2) {
+  const json = flags2.get("json") === true;
+  const rootDir = resolve2(flags2.get("dir") ?? process.cwd());
+  const path = flags2.get("path");
+  const asOf = flags2.get("as-of");
+  if (!path) {
+    if (json) printJsonError("missing_flag", "--path is required");
+    else console.error(kleur.red("error:"), "--path is required");
+    process.exit(2);
+  }
+  let result;
+  try {
+    result = await restore({
+      rootDir,
+      path,
+      ...asOf ? { asOf } : {}
+    });
+  } catch (err) {
+    if (err instanceof NotInitializedError) {
+      if (json) printJsonError("not_initialized", err.message);
+      else console.error(kleur.red("error:"), err.message);
+      process.exit(1);
+    }
+    if (err instanceof PathNeverExistedError) {
+      if (json) printJsonError("path_never_existed", err.message);
+      else console.error(kleur.red("error:"), err.message);
+      process.exit(1);
+    }
+    if (err instanceof PathCurrentlyDeletedError) {
+      if (json) printJsonError("path_currently_deleted", err.message);
+      else console.error(kleur.red("error:"), err.message);
+      process.exit(1);
+    }
+    if (err instanceof HashMismatchError) {
+      if (json) printJsonError("hash_mismatch", err.message);
+      else console.error(kleur.red("error:"), err.message);
+      process.exit(1);
+    }
+    if (json) printJsonError("restore_failed", err.message);
+    else console.error(kleur.red("error:"), err.message);
+    process.exit(1);
+  }
+  if (json) {
+    printJson({
+      protocolVersion: PROTOCOL_VERSION,
+      ...result
+    });
+    return;
+  }
+  const C = kleur;
+  console.log(
+    C.green("\u2713 ") + `restored ${C.bold(path)} from ${C.bold(result.restoredFromCursor)} ` + C.dim(`(${result.size}B, hash ${result.hash.slice(0, 16)}\u2026)`)
+  );
+  if (result.overwrote) {
+    console.log(C.dim("  (overwrote local file; daemon will resync to other devices)"));
+  }
+}
 async function runInit(flags2) {
   const json = flags2.get("json") === true;
   const name = flags2.get("name");
-  const ownerUserId = flags2.get("owner-user-id");
   if (!name) {
     if (json) printJsonError("missing_flag", "--name is required");
     else console.error(kleur.red("error:"), "--name is required");
     process.exit(2);
   }
-  if (!ownerUserId) {
-    if (json) printJsonError("missing_flag", "--owner-user-id is required (placeholder until Clerk)");
-    else console.error(kleur.red("error:"), "--owner-user-id is required (placeholder until Phase 3 / Clerk)");
-    process.exit(2);
+  let accessToken;
+  try {
+    accessToken = readHubToken();
+  } catch (err) {
+    if (err instanceof HubTokenMissingError) {
+      if (json) printJsonError("not_logged_in", err.message);
+      else console.error(kleur.red("error:"), err.message);
+      process.exit(1);
+    }
+    throw err;
   }
-  const rootDir = resolve(flags2.get("dir") ?? process.cwd());
-  const relayUrl = flags2.get("relay") ?? "http://127.0.0.1:4030";
+  const relayUrl = flags2.get("relay") ?? process.env.RIG_RELAY_URL ?? DEFAULT_RELAY_URL;
+  const rootDir = resolve2(flags2.get("dir") ?? process.cwd());
   const deviceLabel = flags2.get("device-label");
   let result;
   try {
-    result = await init({ rootDir, relayUrl, ownerUserId, bindingName: name, deviceLabel });
+    result = await init({ rootDir, relayUrl, accessToken, bindingName: name, deviceLabel });
   } catch (err) {
     if (err instanceof AlreadyInitializedError) {
       if (json) printJsonError("already_initialized", err.message);
@@ -858,15 +1462,27 @@ if (flags.get("version") === true || command === "-v") {
     case "invite":
       await runInvite(positional, flags);
       return;
+    case "members":
+      await runMembers(positional, flags);
+      return;
     case "join":
       await runJoin(positional, flags);
       return;
+    case "import":
+      await runImport(positional, flags);
+      return;
     case "start":
       await runStart(flags);
       return;
     case "status":
       await runStatus(flags);
       return;
+    case "history":
+      await runHistory(flags);
+      return;
+    case "restore":
+      await runRestore(flags);
+      return;
     case "uninit":
       await runUninit(flags);
       return;