@tinycloud/cli 1.2.0-beta.1 → 1.2.0-beta.3

package/dist/index.js

@@ -8,6 +8,114 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/lib/replication-registry.ts
+function stopForSignal(signal) {
+  void closeReplication().finally(() => {
+    process.exit(signal === "SIGINT" ? 130 : 143);
+  });
+}
+function installSignalHandlers() {
+  if (state.installedSignalHandlers) return;
+  state.installedSignalHandlers = true;
+  state.sigintHandler = () => stopForSignal("SIGINT");
+  state.sigtermHandler = () => stopForSignal("SIGTERM");
+  process.once("SIGINT", state.sigintHandler);
+  process.once("SIGTERM", state.sigtermHandler);
+}
+function removeSignalHandlers() {
+  if (!state.installedSignalHandlers) return;
+  state.installedSignalHandlers = false;
+  if (state.sigintHandler) process.removeListener("SIGINT", state.sigintHandler);
+  if (state.sigtermHandler) process.removeListener("SIGTERM", state.sigtermHandler);
+  state.sigintHandler = void 0;
+  state.sigtermHandler = void 0;
+}
+function registerReplication(profile, control) {
+  state.controls.set(profile, control);
+  state.allControls.add(control);
+  state.generation += 1;
+  installSignalHandlers();
+}
+function replicationForProfile(profile) {
+  return state.controls.get(profile);
+}
+function registeredReplications() {
+  return state.controls;
+}
+function closeReplication(schedule = scheduleTimeout) {
+  if (state.closing) return state.closing;
+  removeSignalHandlers();
+  let resolveClosing;
+  let rejectClosing;
+  const closing = new Promise((resolve2, reject) => {
+    resolveClosing = resolve2;
+    rejectClosing = reject;
+  });
+  state.closing = closing;
+  void (async () => {
+    let timeout;
+    const deadline = new Promise((resolve2) => {
+      timeout = schedule(() => resolve2(true), CLOSE_TIMEOUT_MS);
+    });
+    let timedOut = false;
+    const abandonQueuedControls = () => {
+      for (const control of state.allControls) {
+        void Promise.resolve().then(() => control.close()).catch(() => void 0);
+      }
+      state.controls.clear();
+      state.allControls.clear();
+    };
+    try {
+      while (!timedOut) {
+        while (state.allControls.size > 0) {
+          const generation = state.generation;
+          const pending = [...state.allControls];
+          state.controls.clear();
+          state.allControls.clear();
+          const drained = Promise.allSettled(pending.map((control) => Promise.resolve().then(() => control.close()))).then(() => false);
+          timedOut ||= await Promise.race([drained, deadline]);
+          if (timedOut) {
+            abandonQueuedControls();
+            break;
+          }
+          if (state.generation === generation && state.allControls.size === 0) break;
+        }
+        if (timedOut) break;
+        const turn = new Promise((resolve2) => setImmediate(() => resolve2(false)));
+        timedOut ||= await Promise.race([turn, deadline]);
+        if (timedOut) abandonQueuedControls();
+        else if (state.allControls.size === 0) break;
+      }
+      state.closing = void 0;
+      if (state.allControls.size === 0) removeSignalHandlers();
+      resolveClosing(timedOut);
+    } catch (error) {
+      state.closing = void 0;
+      if (state.allControls.size === 0) removeSignalHandlers();
+      rejectClosing(error);
+    } finally {
+      clearTimeout(timeout);
+    }
+  })();
+  return closing;
+}
+var registryKey, globalState, state, CLOSE_TIMEOUT_MS, scheduleTimeout;
+var init_replication_registry = __esm({
+  "src/lib/replication-registry.ts"() {
+    "use strict";
+    registryKey = /* @__PURE__ */ Symbol.for("@tinycloud/cli/replication-registry");
+    globalState = globalThis;
+    state = globalState[registryKey] ??= {
+      controls: /* @__PURE__ */ new Map(),
+      allControls: /* @__PURE__ */ new Set(),
+      installedSignalHandlers: false,
+      generation: 0
+    };
+    CLOSE_TIMEOUT_MS = 3e3;
+    scheduleTimeout = (callback, delayMs) => setTimeout(callback, delayMs);
+  }
+});
+
 // src/config/constants.ts
 import {
   profilesPath,
@@ -33,8 +141,12 @@ var init_constants = __esm({
       PERMISSION_DENIED: 5,
       NETWORK_ERROR: 6,
       NODE_ERROR: 7,
+      /** `tc secrets wait` only: the deadline passed while a secret was still missing. */
+      PENDING: 8,
       /** A write was refused because the owner's TinyCloud storage is full. */
-      STORAGE_FULL: 10
+      STORAGE_FULL: 10,
+      /** Interrupted by SIGINT/SIGTERM (`CANCELLED`). */
+      CANCELLED: 130
     };
   }
 });
@@ -119,7 +231,7 @@ function warningLine(warnings) {
   return `${subject} not used (${which}). Approve access again when a command needs it; remove the old grant with tc auth grants remove <cid>.`;
 }
 function outputError(code3, message, hint, details = {}) {
-  const { meta, warnings = [] } = details;
+  const { meta, warnings = [], setup, recovery, progress } = details;
   if (!shouldOutputJson()) {
     process.stderr.write(
       `${theme.error("\u2717")} ${theme.label(code3)}: ${message}
@@ -138,6 +250,9 @@ function outputError(code3, message, hint, details = {}) {
       error: { code: code3, message }
     };
     if (hint) payload.error.hint = hint;
+    if (recovery) payload.error.recovery = recovery;
+    if (setup) payload.error.setup = setup;
+    if (progress) payload.error.progress = progress;
     if (meta) payload.error.meta = meta;
     if (warnings.length > 0) payload.error.warnings = warnings;
     process.stderr.write(JSON.stringify(payload, null, 2) + "\n");
@@ -267,6 +382,13 @@ var init_storage = __esm({
 import { readFileSync, readdirSync } from "fs";
 import { join } from "path";
 import { ProfileDeletedError, ProfileLockTimeoutError } from "@tinycloud/operations/state";
+import { isSafeRecovery } from "@tinycloud/operations/recovery";
+import {
+  buildSecretRequestUrl,
+  isSafeRequestAccessRecovery,
+  isValidSecretName,
+  SECRET_REQUEST_MAX_NAMES
+} from "@tinycloud/operations/secret-request";
 import { authorizationVerdictOf, parseCapabilityResource, SERVICE_LONG_TO_SHORT, validatedCapabilityOf } from "@tinycloud/sdk-core";
 function setActiveProfileName(name) {
   activeProfileName = name;
@@ -342,11 +464,64 @@ function handleError(error) {
     meta.resource = capability.resource;
     meta.requiredAction = capability.requiredAction;
   }
+  const deniedNames = cliError.metadata?.deniedNames;
+  const recovery = safeCliRecovery(cliError.metadata?.recovery, {
+    deniedNames: Array.isArray(deniedNames) && deniedNames.every((name) => typeof name === "string") ? deniedNames : []
+  });
+  const setup = cliError.code === "NOT_FOUND" || cliError.code === "PERMISSION_DENIED" ? safeCliSetup(cliError.metadata?.setup) : void 0;
+  const progress = cliError.code === "NETWORK_ERROR" || cliError.code === "CANCELLED" ? safeCliProgress(cliError.metadata?.progress) : void 0;
   outputError(cliError.code, cliError.message, hint, {
+    ...recovery ? { recovery } : {},
+    ...setup ? { setup } : {},
+    ...progress ? { progress } : {},
     ...Object.keys(meta).length ? { meta } : {},
     warnings: mergeWarnings(drainWarnings(), operationWarnings(cliError.metadata?.warnings))
   });
-  process.exit(cliError.exitCode);
+  if (registeredReplications().size === 0) return process.exit(cliError.exitCode);
+  return closeReplication().then(() => process.exit(cliError.exitCode));
+}
+function safeCliRecovery(value, context) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || !("action" in value)) return void 0;
+  const action = value.action;
+  switch (action) {
+    case "sign_in":
+    case "complete_migration":
+      return isSafeRecovery(value, action) ? { ...value } : void 0;
+    case "request_access":
+      return isSafeRequestAccessRecovery(value, context.deniedNames) ? { ...value, names: [...value.names] } : void 0;
+    default:
+      return void 0;
+  }
+}
+function safeCliSetup(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const setup = { ...value };
+  if (!Object.keys(setup).every((key) => SETUP_KEYS[key] === true)) return void 0;
+  const { url, names, scope, owner, action } = setup;
+  if (action !== "add_secret" || typeof url !== "string" || typeof owner !== "string") return void 0;
+  if (!Array.isArray(names) || !names.every((name) => typeof name === "string")) return void 0;
+  if (scope !== void 0 && typeof scope !== "string") return void 0;
+  try {
+    const link2 = buildSecretRequestUrl({ owner, names, ...scope !== void 0 ? { scope } : {} });
+    if (link2.url !== url || link2.owner !== owner || link2.names.length !== names.length) return void 0;
+  } catch {
+    return void 0;
+  }
+  return { url, names: [...names], ...scope !== void 0 ? { scope } : {}, owner, action };
+}
+function safeNameList(value) {
+  if (!Array.isArray(value) || value.length > SECRET_REQUEST_MAX_NAMES) return void 0;
+  if (!value.every((name) => typeof name === "string" && isValidSecretName(name))) return void 0;
+  if (new Set(value).size !== value.length) return void 0;
+  return [...value];
+}
+function safeCliProgress(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  if (!("present" in value) || !("pending" in value) || Object.keys(value).length !== 2) return void 0;
+  const present = safeNameList(value.present);
+  const pending = safeNameList(value.pending);
+  if (!present || !pending || present.some((name) => pending.includes(name))) return void 0;
+  return { present, pending };
 }
 function buildAuthHint(error) {
   const capability = validatedCapabilityOf({ meta: error.metadata });
@@ -409,10 +584,11 @@ function buildNetworkHint() {
   lines.push(`Or override per-command with --host or TC_HOST.`);
   return lines.join("\n");
 }
-var activeProfileName, CLIError;
+var activeProfileName, CLIError, SETUP_KEYS;
 var init_errors = __esm({
   "src/output/errors.ts"() {
     "use strict";
+    init_replication_registry();
     init_constants();
     init_formatter();
     init_storage();
@@ -428,6 +604,7 @@ var init_errors = __esm({
       }
       status;
     };
+    SETUP_KEYS = { url: true, names: true, scope: true, owner: true, action: true };
   }
 });
 
@@ -900,11 +1077,11 @@ var init_md = __esm({
         if (len % 4)
           throw new Error("_sha2: outputLen should be aligned to 32bit");
         const outLen = len / 4;
-        const state = this.get();
-        if (outLen > state.length)
+        const state2 = this.get();
+        if (outLen > state2.length)
           throw new Error("_sha2: outputLen bigger than state");
         for (let i = 0; i < outLen; i++)
-          oview.setUint32(4 * i, state[i], isLE2);
+          oview.setUint32(4 * i, state2[i], isLE2);
       }
       digest() {
         const { buffer, outputLen } = this;
@@ -5464,6 +5641,8 @@ import {
   buildPermissionRequestArtifact,
   isPermissionRequestArtifact
 } from "@tinycloud/operations/artifacts";
+import { isLocalOwnerProfile } from "@tinycloud/operations/profile";
+import { resolveSecretsOwner } from "@tinycloud/operations/secret-request";
 import {
   additionalDelegationsPath as sharedAdditionalDelegationsPath,
   authRequestsPath as sharedAuthRequestsPath,
@@ -5501,14 +5680,17 @@ var init_permissions = __esm({
 });
 
 // src/auth/session-expired.ts
+import { signInRecovery } from "@tinycloud/operations/recovery";
 function signInAgainHint(profileName, posture) {
-  if (posture === "local-owner-key") {
-    return `Sign in again with: tc --profile ${profileName} auth login --method local`;
-  }
-  if (posture === "delegate-session") {
-    return `Have the owner approve a new scoped login: tc --profile ${profileName} auth login --method openkey --paste --manifest <manifest.json>. Pass the owner's code on stdin, newline-terminated.`;
+  const delegate = posture === "delegate-session";
+  const { command } = signInRecovery(
+    profileName,
+    delegate ? "delegate-session" : posture === "local-owner-key" ? "local-owner-key" : "owner-openkey"
+  );
+  if (command === void 0) {
+    return delegate ? `Have the owner approve a new scoped login for profile ${JSON.stringify(profileName)} with tc auth login --method openkey --paste --manifest <manifest.json>.` : `Sign in again to profile ${JSON.stringify(profileName)} with tc auth login.`;
   }
-  return `Sign in again with: tc --profile ${profileName} auth login --method openkey`;
+  return delegate ? `Have the owner approve a new scoped login: ${command}. Pass the owner's code on stdin, newline-terminated.` : `Sign in again with: ${command}`;
 }
 function sessionExpiredError(profileName, posture) {
   return new CLIError(
@@ -5543,13 +5725,127 @@ var init_delegation_expiry = __esm({
   }
 });
 
+// src/lib/replication-log.ts
+import { appendFileSync, chmodSync, mkdirSync, renameSync, statSync, writeFileSync } from "fs";
+import { dirname as dirname2, join as join4 } from "path";
+function appendReplicationEvent(root, event) {
+  mkdirSync(root, { recursive: true, mode: DIR_MODE });
+  chmodSync(root, DIR_MODE);
+  const path = join4(root, "events.jsonl");
+  let size = 0;
+  try {
+    size = statSync(path).size;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const line = `${JSON.stringify(event)}
+`;
+  if (size + Buffer.byteLength(line) > MAX_LOG_BYTES) {
+    const rotated = join4(root, "events.jsonl.1");
+    try {
+      renameSync(path, rotated);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    writeFileSync(path, line, { mode: LOG_MODE });
+  } else {
+    appendFileSync(path, line, { mode: LOG_MODE });
+  }
+  chmodSync(path, LOG_MODE);
+}
+function replicationLogPath(profileRoot) {
+  return join4(profileRoot, "replication", "events.jsonl");
+}
+function createReplicationEventSink(profileRoot, options) {
+  const pinnedNotices = /* @__PURE__ */ new Set();
+  const missingGrantWarnings = /* @__PURE__ */ new Set();
+  return (event) => {
+    appendProfileReplicationEvent(profileRoot, event);
+    if (event.type === "replication.state" && event.state === "grant_missing") {
+      const prefix = event.replica ?? event.space ?? "configured prefix";
+      const key = `${event.space ?? ""}\0${event.replica ?? ""}`;
+      if (!missingGrantWarnings.has(key)) {
+        missingGrantWarnings.add(key);
+        process.stderr.write(`[replication] Warning: no usable kv/get+sync grant for ${prefix}; reads use the network (${event.code ?? "grant_missing"}).
+`);
+      }
+    }
+    if (options.debug) {
+      if (event.type === "replication.read") {
+        const detail = event.source === "replica" ? "replica hit" : `${event.source} ${event.reason}`;
+        const syncStatus = event.syncedBeforeRead === void 0 ? "" : ` syncedBeforeRead:${event.syncedBeforeRead}`;
+        const syncError = event.syncError === void 0 ? "" : ` syncError:${event.syncError}`;
+        process.stderr.write(`[replication] ${event.op} ${event.key} \u2190 ${detail} ${event.latencyMs}ms${syncStatus}${syncError}${event.stalenessMs === null ? "" : ` (synced ${Math.round(event.stalenessMs / 1e3)}s ago)`}
+`);
+      } else if (event.type === "replication.write") {
+        process.stderr.write(`[replication] ${event.op} ${event.keys.join(",")} ${event.outcome}${event.code ? ` ${event.code}` : ""}
+`);
+      } else if (event.type === "replication.sync") {
+        const pending = event.pendingCleared === void 0 ? "" : ` pendingCleared:${event.pendingCleared}`;
+        process.stderr.write(`[replication] sync ${event.replica} ${event.outcome}${event.code ? ` ${event.code}` : ""}${pending}
+`);
+      }
+    }
+    if (event.type === "replication.read" && (event.pendingState === "in_flight" || event.pendingState === "ambiguous") && !options.quiet && !pinnedNotices.has(event.key)) {
+      pinnedNotices.add(event.key);
+      process.stderr.write(`[replication] ${event.key} reads from the network: an earlier write's outcome is unknown (${event.pendingState}${event.code ? `, ${event.code}` : ""}). Review: tc replica report
+`);
+    }
+  };
+}
+function appendProfileReplicationEvent(profileRoot, event) {
+  appendReplicationEvent(dirname2(replicationLogPath(profileRoot)), event);
+}
+var MAX_LOG_BYTES, LOG_MODE, DIR_MODE;
+var init_replication_log = __esm({
+  "src/lib/replication-log.ts"() {
+    "use strict";
+    MAX_LOG_BYTES = 5 * 1024 * 1024;
+    LOG_MODE = 384;
+    DIR_MODE = 448;
+  }
+});
+
+// src/lib/replication-config.ts
+import { join as join5 } from "path";
+import { profilePath, withProfileLock as withProfileLock2 } from "@tinycloud/operations/state";
+import { sqliteReplicaStorage } from "@tinycloud/node-sdk";
+function createCliReplicationConfig(profile, settings, output, enabled) {
+  if (!enabled || !settings || settings.prefixes.length === 0) return void 0;
+  const root = profilePath(profile);
+  return {
+    enabled: true,
+    prefixes: settings.prefixes,
+    allowSecrets: settings.allowSecrets === true,
+    mode: "foreground",
+    verify: process.env.TC_REPLICATION_VERIFY === "1",
+    maxStalenessMs: Number(process.env.TC_REPLICATION_MAX_STALENESS_MS ?? 6e4),
+    staleSyncTimeoutMs: Number(process.env.TC_REPLICATION_SYNC_TIMEOUT_MS ?? 1e4),
+    storage: sqliteReplicaStorage({
+      dir: join5(root, "replication"),
+      guard: (section) => withProfileLock2(profile, section, { requireProfile: true, timeoutMs: 35e3 })
+    }),
+    onEvent: createReplicationEventSink(root, output)
+  };
+}
+var init_replication_config = __esm({
+  "src/lib/replication-config.ts"() {
+    "use strict";
+    init_replication_log();
+  }
+});
+
 // src/lib/sdk.ts
 var sdk_exports = {};
 __export(sdk_exports, {
   bootstrapDelegatedSession: () => bootstrapDelegatedSession,
+  closeReplication: () => closeReplication,
   createSDKInstance: () => createSDKInstance,
   ensureAuthenticated: () => ensureAuthenticated,
   jwkHasPrivateParameter: () => jwkHasPrivateParameter,
+  registerReplication: () => registerReplication,
+  registeredReplications: () => registeredReplications,
+  replicationForProfile: () => replicationForProfile,
   restoreProfileSessionNode: () => restoreProfileSessionNode,
   selectSignerJwk: () => selectSignerJwk,
   storedSessionVerifiesLocally: () => storedSessionVerifiesLocally
@@ -5664,10 +5960,21 @@ async function createSDKInstance(ctx, options) {
     );
   }
   if (profile?.authMethod === "local" && effectivePrivateKey) {
+    const replication2 = createCliReplicationConfig(
+      ctx.profile,
+      profile?.replication,
+      { debug: ctx.replicationDebug, quiet: ctx.quiet },
+      ctx.replication
+    );
+    if (ctx.replication && !replication2) {
+      process.stderr.write("[replication] Enabled, but this profile has no configured prefixes; reads use the network.\n");
+    }
     const node2 = new TinyCloudNode({
       host: ctx.host,
-      privateKey: effectivePrivateKey
+      privateKey: effectivePrivateKey,
+      ...replication2 ? { replication: replication2 } : {}
     });
+    if (node2.replication) registerReplication(ctx.profile, node2.replication);
     const restoredOwnSession = Boolean(session && session.delegationHeader && session.delegationCid && session.spaceId);
     if (restoredOwnSession) {
       await restoreProfileSession(node2, ctx.profile, profile, persistedSessionData(ctx.profile, profile, session, key));
@@ -5683,10 +5990,21 @@ async function createSDKInstance(ctx, options) {
     }
     return node2;
   }
+  const replication = createCliReplicationConfig(
+    ctx.profile,
+    profile?.replication,
+    { debug: ctx.replicationDebug, quiet: ctx.quiet },
+    ctx.replication
+  );
+  if (ctx.replication && !replication) {
+    process.stderr.write("[replication] Enabled, but this profile has no configured prefixes; reads use the network.\n");
+  }
   const node = new TinyCloudNode({
     host: ctx.host,
-    privateKey: options?.privateKey
+    privateKey: options?.privateKey,
+    ...replication ? { replication } : {}
   });
+  if (node.replication) registerReplication(ctx.profile, node.replication);
   if (options?.privateKey) {
     await node.signIn();
   } else if (session && session.delegationHeader && session.delegationCid && session.spaceId) {
@@ -5828,6 +6146,9 @@ var init_sdk = __esm({
     init_session_expired();
     init_warnings();
     init_delegation_expiry();
+    init_replication_config();
+    init_replication_registry();
+    init_replication_registry();
     BOOTSTRAP_PROFILE_FIELDS = ["sessionDid", "spaceId"];
   }
 });
@@ -5968,14 +6289,14 @@ var init_host = __esm({
 
 // src/config/profiles.ts
 import { chmod as chmod2, lstat, readdir as readdir2, rm as rm2, rmdir } from "fs/promises";
-import { join as join4 } from "path";
+import { join as join6 } from "path";
 import {
-  profilePath,
+  profilePath as profilePath2,
   readSession,
   recordProfileDeletion,
   refuseWriteToDeletedProfile as refuseWriteToDeletedProfile2,
   removeSession,
-  withProfileLock as withProfileLock2,
+  withProfileLock as withProfileLock3,
   writeSession
 } from "@tinycloud/operations/state";
 var ProfileManager;
@@ -5993,7 +6314,7 @@ var init_profiles = __esm({
        * it around a whole read-modify-write, not just each write.
        */
       static async withLock(name, action, options) {
-        return withProfileLock2(name, action, options);
+        return withProfileLock3(name, action, options);
       }
       /**
        * Read-modify-write of profile.json under the profile lock, so concurrent
@@ -6019,7 +6340,7 @@ var init_profiles = __esm({
       /** Owner-only profile directory (0700), created or tightened before any write into it. */
       static async ensureProfileDir(name) {
         await _ProfileManager.ensureConfigDir();
-        const profileDir = join4(PROFILES_DIR, name);
+        const profileDir = join6(PROFILES_DIR, name);
         await ensureDir(profileDir);
         await chmod2(profileDir, PRIVATE_DIR_MODE);
         return profileDir;
@@ -6048,8 +6369,8 @@ var init_profiles = __esm({
        * Throws CLIError if the profile doesn't exist.
        */
       static async getProfile(name) {
-        const profilePath2 = join4(PROFILES_DIR, name, "profile.json");
-        const profile = await readJson(profilePath2);
+        const profilePath3 = join6(PROFILES_DIR, name, "profile.json");
+        const profile = await readJson(profilePath3);
         if (!profile) {
           throw new CLIError(
             "PROFILE_NOT_FOUND",
@@ -6064,18 +6385,18 @@ var init_profiles = __esm({
        */
       static async setProfile(name, data) {
         await _ProfileManager.withLock(name, async () => {
-          await writeJson(join4(await _ProfileManager.ensureProfileDir(name), "profile.json"), data);
+          await writeJson(join6(await _ProfileManager.ensureProfileDir(name), "profile.json"), data);
         });
       }
       /** Removes profile.json under the profile lock (rollback of a profile a failed login created). */
       static async removeProfileConfig(name) {
-        await _ProfileManager.withLock(name, () => rm2(join4(PROFILES_DIR, name, "profile.json"), { force: true }));
+        await _ProfileManager.withLock(name, () => rm2(join6(PROFILES_DIR, name, "profile.json"), { force: true }));
       }
       /**
        * Returns true if a profile directory exists.
        */
       static async profileExists(name) {
-        return fileExists(join4(PROFILES_DIR, name, "profile.json"));
+        return fileExists(join6(PROFILES_DIR, name, "profile.json"));
       }
       /**
        * Returns an array of profile directory names.
@@ -6099,7 +6420,7 @@ var init_profiles = __esm({
       static async deleteProfile(name) {
         let profileDir;
         try {
-          profileDir = profilePath(name);
+          profileDir = profilePath2(name);
         } catch {
           throw new CLIError(
             "INVALID_PROFILE_NAME",
@@ -6124,11 +6445,11 @@ var init_profiles = __esm({
           return;
         }
         await _ProfileManager.withLock(name, async () => {
-          for (const file of ["session.json", "key.json"]) await rm2(join4(profileDir, file), { force: true });
+          for (const file of ["session.json", "key.json"]) await rm2(join6(profileDir, file), { force: true });
           for (const entry of await readdir2(profileDir)) {
-            if (entry !== ".lock" && entry !== "profile.json") await rm2(join4(profileDir, entry), { recursive: true, force: true });
+            if (entry !== ".lock" && entry !== "profile.json") await rm2(join6(profileDir, entry), { recursive: true, force: true });
           }
-          await rm2(join4(profileDir, "profile.json"), { force: true });
+          await rm2(join6(profileDir, "profile.json"), { force: true });
           await recordProfileDeletion(name);
         });
         await rmdir(profileDir).catch((error) => {
@@ -6140,7 +6461,7 @@ var init_profiles = __esm({
        * Returns the parsed JWK for a profile, or null if no key exists.
        */
       static async getKey(name) {
-        return readJson(join4(PROFILES_DIR, name, "key.json"));
+        return readJson(join6(PROFILES_DIR, name, "key.json"));
       }
       /**
        * Saves a JWK key under the profile lock (0600, in an owner-only profile
@@ -6150,12 +6471,12 @@ var init_profiles = __esm({
       static async setKey(name, jwk) {
         await _ProfileManager.withLock(name, async () => {
           await refuseWriteToDeletedProfile2(name);
-          await writeJson(join4(await _ProfileManager.ensureProfileDir(name), "key.json"), jwk);
+          await writeJson(join6(await _ProfileManager.ensureProfileDir(name), "key.json"), jwk);
         });
       }
       /** Removes key.json under the profile lock (rollback of a key a failed login created). */
       static async removeKey(name) {
-        await _ProfileManager.withLock(name, () => rm2(join4(PROFILES_DIR, name, "key.json"), { force: true }));
+        await _ProfileManager.withLock(name, () => rm2(join6(PROFILES_DIR, name, "key.json"), { force: true }));
       }
       // ── Session management ──────────────────────────────────────────────
       /**
@@ -6182,7 +6503,7 @@ var init_profiles = __esm({
        * created or tightened to 0700.
        */
       static async getCacheDir(name) {
-        const cacheDir = join4(await _ProfileManager.ensureProfileDir(name), "cache");
+        const cacheDir = join6(await _ProfileManager.ensureProfileDir(name), "cache");
         await ensureDir(cacheDir);
         await chmod2(cacheDir, PRIVATE_DIR_MODE);
         return cacheDir;
@@ -6205,11 +6526,20 @@ var init_profiles = __esm({
         const config = await _ProfileManager.getConfig();
         const profile = options.profile ?? process.env.TC_PROFILE ?? config.defaultProfile ?? DEFAULT_PROFILE;
         let profileHost;
+        let profileConfig;
         try {
-          const profileConfig = await _ProfileManager.getProfile(profile);
+          profileConfig = await _ProfileManager.getProfile(profile);
           profileHost = profileConfig.host;
         } catch {
         }
+        const envReplication = process.env.TC_REPLICATION?.toLowerCase();
+        const envEnabled = envReplication === "1" || envReplication === "true" || envReplication === "on";
+        const explicitEnvOff = envReplication === "0" || envReplication === "false" || envReplication === "off";
+        if (envReplication !== void 0 && !envEnabled && !explicitEnvOff) {
+          throw new CLIError("INVALID_ARGUMENT", "TC_REPLICATION must be one of 1, true, on, 0, false or off.", ExitCode.USAGE_ERROR);
+        }
+        const explicitOff = options.noReplication === true || options.replication === false;
+        const replication = options.replication === true ? true : explicitOff ? false : envEnabled;
         const explicitHost = options.host ?? process.env.TC_HOST;
         let host = explicitHost ?? profileHost ?? DEFAULT_HOST;
         let localDiscovery;
@@ -6229,6 +6559,8 @@ var init_profiles = __esm({
           verbose: options.verbose ?? false,
           noCache: options.noCache ?? false,
           quiet: options.quiet ?? false,
+          replication,
+          replicationDebug: options.replicationDebug === true || process.env.TC_REPLICATION_DEBUG === "1",
           ...localDiscovery === void 0 ? {} : { localDiscovery }
         };
       }
@@ -6337,6 +6669,7 @@ function emitBanner(version2) {
 }
 
 // src/index.ts
+init_replication_registry();
 init_theme();
 init_formatter();
 init_profiles();
@@ -8059,8 +8392,8 @@ var BLAKE3 = class _BLAKE3 extends BLAKE2 {
   }
   _cloneInto(to) {
     to = super._cloneInto(to);
-    const { IV, flags, state, chunkPos, posOut, chunkOut, stack, chunksDone } = this;
-    to.state.set(state.slice());
+    const { IV, flags, state: state2, chunkPos, posOut, chunkOut, stack, chunksDone } = this;
+    to.state.set(state2.slice());
     to.stack = stack.map((i) => Uint32Array.from(i));
     to.IV.set(IV);
     to.flags = flags;
@@ -15280,12 +15613,12 @@ async function notifyShare(input) {
     if (input.signal?.aborted) throw new ShareNotifyError("share delivery was cancelled");
     attempts += 1;
     try {
-      const state = await input.adapter.deliver({ shareId: input.shareId, recipient, idempotencyKey, ...input.record === void 0 ? {} : { record: input.record }, ...input.signal === void 0 ? {} : { signal: input.signal } });
+      const state2 = await input.adapter.deliver({ shareId: input.shareId, recipient, idempotencyKey, ...input.record === void 0 ? {} : { record: input.record }, ...input.signal === void 0 ? {} : { signal: input.signal } });
       return {
         protocol: "tinycloud-share",
         version: 1,
         shareId: input.shareId,
-        state: state === "delivered" && input.record?.deliveredRecipients?.includes(recipient) ? "already-delivered" : state,
+        state: state2 === "delivered" && input.record?.deliveredRecipients?.includes(recipient) ? "already-delivered" : state2,
         idempotencyKey,
         attempts
       };
@@ -16982,7 +17315,7 @@ function receiveJson(result, path) {
 import { constants } from "fs";
 import { lstat as lstat2, mkdir as mkdir2, mkdtemp, open as open2, readFile as readFile3, realpath, stat as stat2, link, rename as rename2, rm as rm3, unlink } from "fs/promises";
 import { randomBytes as randomBytes2 } from "crypto";
-import { basename as basename2, join as join5, resolve, sep } from "path";
+import { basename as basename2, join as join7, resolve, sep } from "path";
 init_errors();
 var MAX_SHARE_STDIN_BYTES = 100 * 1024 * 1024;
 var MAX_SHARE_URL_BYTES = 64 * 1024;
@@ -17036,7 +17369,7 @@ async function assertDirectory(path) {
   const segments = absolute.split(sep).filter(Boolean);
   let current = absolute.startsWith(sep) ? sep : "";
   for (const segment of segments) {
-    current = current === sep ? join5(current, segment) : join5(current, segment);
+    current = current === sep ? join7(current, segment) : join7(current, segment);
     try {
       const info = await lstat2(current);
       if (info.isSymbolicLink()) {
@@ -17058,17 +17391,17 @@ async function writeShareOutput(directory, filename, bytes, force) {
   const safeName = safeFilename(filename);
   const directoryHandle = await open2(outputDirectory, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0));
   const stableDirectory = await realpath(outputDirectory);
-  const outputPath = join5(stableDirectory, safeName);
+  const outputPath = join7(stableDirectory, safeName);
   const directoryIdentity = await directoryHandle.stat();
   const assertStableDirectory = async () => {
     const current = await stat2(stableDirectory);
     if (current.dev !== directoryIdentity.dev || current.ino !== directoryIdentity.ino) throw new Error("OUTPUT_EXISTS");
   };
   await assertStableDirectory();
-  const stagingDirectory = await mkdtemp(join5(stableDirectory, ".tinycloud-share-stage-"));
+  const stagingDirectory = await mkdtemp(join7(stableDirectory, ".tinycloud-share-stage-"));
   const stagingInfo = await lstat2(stagingDirectory);
   if (!stagingInfo.isDirectory() || (stagingInfo.mode & 511) !== 448) throw new Error("OUTPUT_EXISTS");
-  const stagingPath = join5(stagingDirectory, `.tinycloud-share-${randomBytes2(16).toString("hex")}.tmp`);
+  const stagingPath = join7(stagingDirectory, `.tinycloud-share-${randomBytes2(16).toString("hex")}.tmp`);
   let temporaryPath;
   let handle;
   try {
@@ -17105,7 +17438,7 @@ async function writeShareOutput(directory, filename, bytes, force) {
     await rm3(stagingDirectory, { recursive: true, force: true });
     await directoryHandle.close();
   }
-  return join5(outputDirectory, safeName);
+  return join7(outputDirectory, safeName);
 }
 
 // src/share/errors.ts
@@ -17391,7 +17724,7 @@ function registerShareCommand(program2) {
       if (json) writeJson2({ ...redactPublishedShare(result), expiryClamped: result.metadata.expiryClamped === true, ...notification === void 0 ? {} : { notification } });
       else publishHuman(result);
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
   share.command("inspect [url]").description("Verify a share link and print safe metadata").option("--stdin", "Read the complete URL from stdin").option("--json", "Print versioned redacted JSON").option("--viewer-origin <origin>", "Require this canonical Share origin", SHARE_ORIGIN).action(async (url, options, command) => {
@@ -17401,7 +17734,7 @@ function registerShareCommand(program2) {
       if (json) writeJson2(result);
       else inspectHuman(result);
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
   share.command("receive [url]").description("Verify and receive a share link").option("--stdin", "Read the complete URL from stdin").option("--output <directory>", "Create the file in this directory").option("--stdout", "Write verified plaintext bytes to stdout").option("--force", "Allow replacing an existing non-symlink output").option("--max-bytes <bytes>", "Bound received content bytes").option("--json", "Print versioned redacted JSON").option("--viewer-origin <origin>", "Require this canonical Share origin", SHARE_ORIGIN).action(async (url, options, command) => {
@@ -17449,7 +17782,7 @@ function registerShareCommand(program2) {
       if (json) receiveJson(result, output);
       else receiveHuman(output);
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
   share.command("list").description("List encrypted sender history without complete bearer URLs").option("--json", "Print versioned redacted JSON").action(async (options, command) => {
@@ -17460,7 +17793,7 @@ function registerShareCommand(program2) {
       if (json) writeJson2({ protocol: "tinycloud-share", version: 1, shares: result });
       else process.stdout.write(result.map((item) => `${item.shareId}	${item.target}	${item.expiresAt}`).join("\n") + (result.length ? "\n" : ""));
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
   share.command("show <id>").description("Show one redacted sender-history record").option("--reveal-link", "Explicitly include the complete link").option("--json", "Print versioned redacted JSON").action(async (id, options, command) => {
@@ -17472,7 +17805,7 @@ function registerShareCommand(program2) {
       if (json) writeJson2({ protocol: "tinycloud-share", version: 1, share: result });
       else writeJson2(result);
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
   share.command("notify <id>").description("Retry idempotent delivery within 5 minutes of publication; after that publish a new share").requiredOption("--to <address>", "Recipient email").option("--json", "Print versioned JSON").action(async (id, options, command) => {
@@ -17499,7 +17832,7 @@ function registerShareCommand(program2) {
       if (result.reason === "delivery-window-expired") process.stderr.write(NOTIFY_WINDOW_MESSAGE);
       if (result.state === "partial-failure") process.exitCode = 9;
     } catch (error) {
-      handleError(shareCliError(error, "notify"));
+      return handleError(shareCliError(error, "notify"));
     }
   });
   share.command("revoke <id>").description("Revoke addressed shares; report bearer retention honestly").option("--ancestor", "Revoke the owner delegation ancestry").option("--json", "Print versioned JSON").action(async (id, options, command) => {
@@ -17516,7 +17849,7 @@ function registerShareCommand(program2) {
       else process.stdout.write(`${result.state}
 `);
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
 }
@@ -17527,7 +17860,7 @@ init_profiles();
 init_constants();
 init_session_expired();
 import { readFile as readFile4 } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join8 } from "path";
 import { createHash } from "crypto";
 import { writeJsonAtomic as writeJsonAtomic2 } from "@tinycloud/operations/state";
 import { LocationRecordValidationError, LocationRegistryHttpError, revokePolicyRootV3 } from "@tinycloud/sdk-core";
@@ -17632,8 +17965,8 @@ function createEncryptedProfileHistory(profileName, sessionSigner) {
   const observedProfiles = /* @__PURE__ */ new Set();
   let preparedKeys;
   let preparedKey;
-  const path = async (profile) => join6(await ProfileManager.getCacheDir(profile), "share-history-v2.json");
-  const legacyPath = async (profile) => join6(await ProfileManager.getCacheDir(profile), "share-history-v1.bin");
+  const path = async (profile) => join8(await ProfileManager.getCacheDir(profile), "share-history-v2.json");
+  const legacyPath = async (profile) => join8(await ProfileManager.getCacheDir(profile), "share-history-v1.bin");
   const b64 = (value) => Buffer.from(value).toString("base64url");
   const unb64 = (value) => {
     if (typeof value !== "string" || !/^[A-Za-z0-9_-]+$/.test(value)) throw new Error("share history is unavailable");
@@ -18197,7 +18530,7 @@ function selectedShareProfile() {
   }
   return process.env.TC_PROFILE;
 }
-program.name("tc").description("TinyCloud CLI \u2014 self-sovereign storage from the terminal").version(version).option("-p, --profile <name>", "Profile to use").option("-H, --host <url>", "TinyCloud node URL").option("-v, --verbose", "Enable verbose output").option("--no-cache", "Disable caching").option("-q, --quiet", "Suppress non-essential output").option("--json", "Force JSON output");
+program.name("tc").description("TinyCloud CLI \u2014 self-sovereign storage from the terminal").version(version).option("-p, --profile <name>", "Profile to use").option("-H, --host <url>", "TinyCloud node URL").option("-v, --verbose", "Enable verbose output").option("--no-cache", "Disable caching").option("-q, --quiet", "Suppress non-essential output").option("--json", "Force JSON output").option("--replication", "Enable read-through replication for this invocation").option("--no-replication", "Disable read-through replication for this invocation").option("--replication-debug", "Write replication diagnostics to stderr");
 program.hook("preAction", async (thisCommand) => {
   const opts = thisCommand.optsWithGlobals();
   setJsonOutputRequested(opts.json === true);
@@ -18248,7 +18581,7 @@ function firstCommandToken(values) {
       continue;
     }
     if (value.startsWith("--profile=") || value.startsWith("--host=")) continue;
-    if (value === "--verbose" || value === "--no-cache" || value === "-q" || value === "--quiet" || value === "--json") continue;
+    if (value === "--verbose" || value === "--no-cache" || value === "-q" || value === "--quiet" || value === "--json" || value === "--replication" || value === "--no-replication" || value === "--replication-debug") continue;
     if (value.startsWith("-")) continue;
     return value;
   }
@@ -18283,8 +18616,18 @@ ${theme.muted("Repo:")} ${theme.accent("https://github.com/tinycloudlabs/web-sdk
 });
 try {
   await program.parseAsync(process.argv);
+  if (await closeReplication()) {
+    process.exitCode = 0;
+    const stdoutFlushed = Promise.withResolvers();
+    process.stdout.write("", () => stdoutFlushed.resolve());
+    await stdoutFlushed.promise;
+    const stderrFlushed = Promise.withResolvers();
+    process.stderr.write("", () => stderrFlushed.resolve());
+    await stderrFlushed.promise;
+    process.exit();
+  }
 } catch (error) {
-  handleError(error);
+  await handleError(error);
 }
 /*! Bundled license information: