appduct 0.10.0 → 0.11.1

package/dist/cli/routes/tools.js

@@ -0,0 +1,1860 @@
+// src/cli/routes/tools.ts
+import { isValidToolGroup } from "@appduct/shared";
+
+// src/commands/tools.ts
+import { RPC_METHODS as RPC_METHODS2 } from "@appduct/shared";
+
+// src/rpc/client.ts
+import { connect as connect2 } from "node:net";
+import { spawn as spawnChildProcess } from "node:child_process";
+import { open as open2, readFile as readFile3, rm as rm2, stat as stat2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+import { RPC_METHODS } from "@appduct/shared";
+
+// src/daemon/log-rotation.ts
+import { chmod as chmod2, rename, stat } from "node:fs/promises";
+
+// src/daemon/config.ts
+import { readFile } from "node:fs/promises";
+var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
+  "wssPort",
+  "keyPath",
+  "graceSeconds",
+  "linkTtlSeconds",
+  "keepaliveIntervalSeconds",
+  "eventBufferSize",
+  "auditRetentionDays",
+  "daemonLogMaxBytes",
+  "policy",
+  "advertisedIp",
+  "scheme",
+  "restartDaemonOnVersionMismatch"
+]);
+var KNOWN_POLICY_KEYS = /* @__PURE__ */ new Set(["default", "destructive", "tools"]);
+var POLICY_DECISIONS = /* @__PURE__ */ new Set(["allow", "deny", "prompt"]);
+var DEFAULT_AUDIT_RETENTION_DAYS = 30;
+var DEFAULT_DAEMON_LOG_MAX_BYTES = 10 * 1024 * 1024;
+var AppductConfigError = class extends Error {
+  constructor(key, message) {
+    super(message);
+    this.key = key;
+    this.name = "AppductConfigError";
+  }
+};
+var configError = (key, message) => {
+  return new AppductConfigError(key, `Invalid Appduct config value for "${key}": ${message}`);
+};
+var requireWssPort = (value, key) => {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 65535) {
+    throw configError(key, "must be a port number between 0 and 65535 (0 binds an OS-assigned port).");
+  }
+  return value;
+};
+var requirePositiveInteger = (value, key) => {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw configError(key, "must be a positive integer.");
+  }
+  return value;
+};
+var requireNonEmptyString = (value, key) => {
+  if (typeof value !== "string" || value.length === 0) {
+    throw configError(key, "must be a non-empty string.");
+  }
+  return value;
+};
+var requireBoolean = (value, key) => {
+  if (typeof value !== "boolean") {
+    throw configError(key, "must be a boolean.");
+  }
+  return value;
+};
+var requirePolicyDecision = (value, key) => {
+  if (typeof value !== "string" || !POLICY_DECISIONS.has(value)) {
+    throw configError(key, 'must be "allow", "deny", or "prompt".');
+  }
+  return value;
+};
+var defaultConfig = (paths) => {
+  return {
+    wssPort: 8443,
+    keyPath: paths.keyPath,
+    graceSeconds: 600,
+    linkTtlSeconds: 300,
+    keepaliveIntervalSeconds: 15,
+    eventBufferSize: 256,
+    auditRetentionDays: DEFAULT_AUDIT_RETENTION_DAYS,
+    daemonLogMaxBytes: DEFAULT_DAEMON_LOG_MAX_BYTES,
+    restartDaemonOnVersionMismatch: false,
+    policy: {
+      default: "allow",
+      destructive: "allow"
+    }
+  };
+};
+var loadConfig = async (paths, options = {}) => {
+  const warn = options.warn ?? (() => {
+  });
+  const config = defaultConfig(paths);
+  let raw;
+  try {
+    raw = JSON.parse(await readFile(paths.configPath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return config;
+    }
+    throw configError("config.json", `could not be read/parsed (${error.message}).`);
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw configError("config.json", "must be a JSON object.");
+  }
+  const parsed = raw;
+  for (const key of Object.keys(parsed)) {
+    if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
+      warn(`Unknown Appduct config key "${key}" is ignored.`);
+    }
+  }
+  if (parsed.wssPort !== void 0) {
+    config.wssPort = requireWssPort(parsed.wssPort, "wssPort");
+  }
+  if (parsed.keyPath !== void 0) {
+    config.keyPath = requireNonEmptyString(parsed.keyPath, "keyPath");
+  }
+  if (parsed.advertisedIp !== void 0) {
+    config.advertisedIp = requireNonEmptyString(parsed.advertisedIp, "advertisedIp");
+  }
+  if (parsed.scheme !== void 0) {
+    config.scheme = requireNonEmptyString(parsed.scheme, "scheme");
+  }
+  if (parsed.graceSeconds !== void 0) {
+    config.graceSeconds = requirePositiveInteger(parsed.graceSeconds, "graceSeconds");
+  }
+  if (parsed.linkTtlSeconds !== void 0) {
+    config.linkTtlSeconds = requirePositiveInteger(parsed.linkTtlSeconds, "linkTtlSeconds");
+  }
+  if (parsed.keepaliveIntervalSeconds !== void 0) {
+    config.keepaliveIntervalSeconds = requirePositiveInteger(
+      parsed.keepaliveIntervalSeconds,
+      "keepaliveIntervalSeconds"
+    );
+  }
+  if (parsed.eventBufferSize !== void 0) {
+    config.eventBufferSize = requirePositiveInteger(parsed.eventBufferSize, "eventBufferSize");
+  }
+  if (parsed.auditRetentionDays !== void 0) {
+    config.auditRetentionDays = requirePositiveInteger(parsed.auditRetentionDays, "auditRetentionDays");
+  }
+  if (parsed.daemonLogMaxBytes !== void 0) {
+    config.daemonLogMaxBytes = requirePositiveInteger(parsed.daemonLogMaxBytes, "daemonLogMaxBytes");
+  }
+  if (parsed.restartDaemonOnVersionMismatch !== void 0) {
+    config.restartDaemonOnVersionMismatch = requireBoolean(
+      parsed.restartDaemonOnVersionMismatch,
+      "restartDaemonOnVersionMismatch"
+    );
+  }
+  if (parsed.policy !== void 0) {
+    if (typeof parsed.policy !== "object" || parsed.policy === null || Array.isArray(parsed.policy)) {
+      throw configError("policy", "must be an object.");
+    }
+    const policy = parsed.policy;
+    for (const key of Object.keys(policy)) {
+      if (!KNOWN_POLICY_KEYS.has(key)) {
+        warn(`Unknown Appduct config key "policy.${key}" is ignored.`);
+      }
+    }
+    if (policy.default !== void 0) {
+      config.policy.default = requirePolicyDecision(policy.default, "policy.default");
+    }
+    if (policy.destructive !== void 0) {
+      config.policy.destructive = requirePolicyDecision(policy.destructive, "policy.destructive");
+    }
+    if (policy.tools !== void 0) {
+      if (typeof policy.tools !== "object" || policy.tools === null || Array.isArray(policy.tools)) {
+        throw configError("policy.tools", "must be an object.");
+      }
+      const tools = {};
+      for (const [toolKey, toolValue] of Object.entries(policy.tools)) {
+        tools[toolKey] = requirePolicyDecision(toolValue, `policy.tools["${toolKey}"]`);
+      }
+      config.policy.tools = tools;
+    }
+  }
+  return config;
+};
+
+// src/daemon/pidfile.ts
+import { readFileSync } from "node:fs";
+import { open, readFile as readFile2, rm } from "node:fs/promises";
+var readProcStatus = (pid) => {
+  try {
+    return readFileSync(`/proc/${pid}/status`, "utf8");
+  } catch {
+    return void 0;
+  }
+};
+var isZombie = (pid, readStatus) => {
+  const status = readStatus(pid);
+  if (status === void 0) {
+    return false;
+  }
+  return /^State:\s*Z\b/mu.test(status);
+};
+var isProcessAlive = (pid, readStatus = readProcStatus) => {
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+  return !isZombie(pid, readStatus);
+};
+var readPidFromFile = async (pidFilePath) => {
+  let contents;
+  try {
+    contents = await readFile2(pidFilePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+  const pid = Number.parseInt(contents.trim(), 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+};
+
+// src/daemon/socket-probe.ts
+import { connect } from "node:net";
+var isSocketConnectable = (socketPath) => {
+  return new Promise((resolve) => {
+    const socket = connect(socketPath);
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+};
+
+// src/daemon/state-dir.ts
+import { join } from "node:path";
+import { mkdir, chmod } from "node:fs/promises";
+var getStateDirPaths = (stateDir) => {
+  return {
+    root: stateDir,
+    socketPath: join(stateDir, "daemon.sock"),
+    pidFilePath: join(stateDir, "daemon.pid"),
+    logFilePath: join(stateDir, "daemon.log"),
+    keyPath: join(stateDir, "key.pem"),
+    configPath: join(stateDir, "config.json"),
+    auditDir: join(stateDir, "audit"),
+    spawnLockPath: join(stateDir, "daemon.spawn.lock")
+  };
+};
+var ensureStateDir = async (stateDir) => {
+  const paths = getStateDirPaths(stateDir);
+  await mkdir(paths.auditDir, { recursive: true });
+  await chmod(paths.root, 448);
+  await chmod(paths.auditDir, 448);
+  return paths;
+};
+
+// src/daemon/log-rotation.ts
+var STATE_FILE_MODE = 384;
+var daemonLogBackupPath = (logFilePath) => `${logFilePath}.1`;
+var isDaemonHoldingLog = async (pidFilePath) => {
+  try {
+    const pid = await readPidFromFile(pidFilePath);
+    return pid !== void 0 && isProcessAlive(pid);
+  } catch {
+    return false;
+  }
+};
+var rotateDaemonLogIfNeeded = async (options) => {
+  const warn = options.warn ?? ((message) => {
+    process.stderr.write(`${message}
+`);
+  });
+  try {
+    const stats = await stat(options.logFilePath);
+    if (!stats.isFile() || stats.size <= options.maxBytes) {
+      return { rotated: false };
+    }
+    const held = options.pidFilePath !== void 0 && await isDaemonHoldingLog(options.pidFilePath) || options.socketPath !== void 0 && await isSocketConnectable(options.socketPath);
+    if (held) {
+      warn(
+        `appduct: "${options.logFilePath}" is over its size cap but a daemon still holds it; leaving it in place.`
+      );
+      return { rotated: false, skipped: "daemon_running" };
+    }
+    const backupPath = daemonLogBackupPath(options.logFilePath);
+    await rename(options.logFilePath, backupPath);
+    try {
+      await chmod2(backupPath, STATE_FILE_MODE);
+    } catch (error) {
+      warn(`appduct: rotated "${options.logFilePath}" but could not set 0600 on "${backupPath}": ${error.message}`);
+    }
+    return { rotated: true, rotatedBytes: stats.size };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { rotated: false };
+    }
+    warn(`appduct: failed to rotate "${options.logFilePath}": ${error.message}`);
+    return { rotated: false };
+  }
+};
+var ensureDaemonLogMode = async (logFilePath, warn = (message) => process.stderr.write(`${message}
+`)) => {
+  try {
+    await chmod2(logFilePath, STATE_FILE_MODE);
+    return true;
+  } catch (error) {
+    warn(`appduct: could not set 0600 on "${logFilePath}": ${error.message}`);
+    return false;
+  }
+};
+var resolveDaemonLogMaxBytes = async (stateDir) => {
+  try {
+    return (await loadConfig(getStateDirPaths(stateDir))).daemonLogMaxBytes;
+  } catch {
+    return DEFAULT_DAEMON_LOG_MAX_BYTES;
+  }
+};
+
+// src/package-root.ts
+import { existsSync, readFileSync as readFileSync2 } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_NAME = "appduct";
+var cached;
+var getPackageRoot = () => {
+  if (cached !== void 0) {
+    return cached;
+  }
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (; ; ) {
+    const candidate = join2(dir, "package.json");
+    if (existsSync(candidate)) {
+      let name;
+      try {
+        name = JSON.parse(readFileSync2(candidate, "utf8")).name;
+      } catch {
+      }
+      if (name === PACKAGE_NAME) {
+        cached = dir;
+        return dir;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error(`Could not locate the "${PACKAGE_NAME}" package root above ${import.meta.url}.`);
+    }
+    dir = parent;
+  }
+};
+
+// src/package-version.ts
+var DAEMON_VERSION_OVERRIDE_ENV = "APPDUCT_DAEMON_VERSION_OVERRIDE";
+
+// src/rpc/client.ts
+var defaultBinPath = join3(getPackageRoot(), "bin.js");
+var DaemonRpcError = class extends Error {
+  constructor(code, message, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+    this.name = "DaemonRpcError";
+  }
+};
+var DaemonUnavailableError = class extends Error {
+  constructor(message, reason = "unreachable") {
+    super(message);
+    this.reason = reason;
+    this.name = "DaemonUnavailableError";
+  }
+};
+var isRequestTimeoutError = (error) => {
+  return error instanceof DaemonUnavailableError && error.reason === "timeout";
+};
+var describeLiveState = (state) => {
+  const parts = [];
+  if (state.sessions > 0) {
+    parts.push(`${state.sessions} connected session(s)`);
+  }
+  if (state.pendingLinks > 0) {
+    parts.push(`${state.pendingLinks} unclaimed link(s)`);
+  }
+  return parts.join(" and ");
+};
+var DaemonVersionMismatchError = class extends Error {
+  constructor(daemonVersion, clientVersion, live, message) {
+    super(
+      message ?? `The running Appduct daemon is version ${daemonVersion}, but this client is version ${clientVersion}. It was not restarted automatically because ${describeLiveState(live)} would be lost. Run "appduct daemon stop" once that state is expendable, or force it with "--daemon-restart".`
+    );
+    this.daemonVersion = daemonVersion;
+    this.clientVersion = clientVersion;
+    this.name = "DaemonVersionMismatchError";
+    this.sessionCount = live.sessions;
+    this.pendingLinkCount = live.pendingLinks;
+  }
+  sessionCount;
+  pendingLinkCount;
+};
+var DaemonVersionRestartIneffectiveError = class extends DaemonVersionMismatchError {
+  constructor(daemonVersion, clientVersion, live) {
+    super(
+      daemonVersion,
+      clientVersion,
+      live,
+      `The Appduct daemon was restarted to match this client (version ${clientVersion}), but the daemon now answering still reports version ${daemonVersion}. Either the old daemon never exited (compare "daemon.pid" with what "appduct daemon status" reports), or another process spawned an older daemon in the meantime. Run "appduct daemon stop", then retry.`
+    );
+    this.name = "DaemonVersionRestartIneffectiveError";
+  }
+};
+var parseVersion = (value) => {
+  const match = /^(\d+(?:\.\d+)*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(value.trim());
+  if (!match) {
+    return void 0;
+  }
+  return {
+    numbers: match[1].split(".").map(Number),
+    // Build metadata (`+…`) is dropped, per semver: it never affects precedence, so two versions
+    // differing only there are the same version and neither restarts nor warns about the other.
+    prerelease: match[2]?.split(".")
+  };
+};
+var isNumericIdentifier = (identifier) => /^\d+$/u.test(identifier);
+var comparePrerelease = (left, right) => {
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const a = left[index];
+    const b = right[index];
+    if (a === void 0) {
+      return -1;
+    }
+    if (b === void 0) {
+      return 1;
+    }
+    if (a === b) {
+      continue;
+    }
+    const aNumeric = isNumericIdentifier(a);
+    const bNumeric = isNumericIdentifier(b);
+    if (aNumeric && bNumeric) {
+      return Number(a) < Number(b) ? -1 : 1;
+    }
+    if (aNumeric !== bNumeric) {
+      return aNumeric ? -1 : 1;
+    }
+    return a < b ? -1 : 1;
+  }
+  return 0;
+};
+var compareVersions = (a, b) => {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) {
+    return void 0;
+  }
+  const length = Math.max(left.numbers.length, right.numbers.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (left.numbers[index] ?? 0) - (right.numbers[index] ?? 0);
+    if (difference !== 0) {
+      return difference < 0 ? -1 : 1;
+    }
+  }
+  if (left.prerelease === void 0 && right.prerelease === void 0) {
+    return 0;
+  }
+  if (left.prerelease === void 0) {
+    return 1;
+  }
+  if (right.prerelease === void 0) {
+    return -1;
+  }
+  return comparePrerelease(left.prerelease, right.prerelease);
+};
+var isSameVersion = (a, b) => {
+  return a === b || compareVersions(a, b) === 0;
+};
+var isConnectionMissingError = (error) => {
+  const code = error.code;
+  return code === "ENOENT" || code === "ECONNREFUSED";
+};
+var isDaemonUnreachableError = (error) => {
+  return error instanceof DaemonUnavailableError || isConnectionMissingError(error);
+};
+var nextRequestId = 1;
+var sendRequest = (socketPath, method, params, timeoutMs) => {
+  return new Promise((resolve, reject) => {
+    const id = nextRequestId;
+    nextRequestId += 1;
+    let socket;
+    let settled = false;
+    let buffer = "";
+    const finish = (fn) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      socket.destroy();
+      fn();
+    };
+    const timeout = setTimeout(() => {
+      finish(
+        () => reject(new DaemonUnavailableError(`Timed out waiting for a response to "${method}".`, "timeout"))
+      );
+    }, timeoutMs);
+    socket = connect2(socketPath);
+    socket.on("error", (error) => {
+      finish(() => reject(error));
+    });
+    socket.on("connect", () => {
+      socket.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}
+`);
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      let newlineIndex = buffer.indexOf("\n");
+      while (newlineIndex !== -1) {
+        const line = buffer.slice(0, newlineIndex);
+        buffer = buffer.slice(newlineIndex + 1);
+        newlineIndex = buffer.indexOf("\n");
+        if (line.length === 0) {
+          continue;
+        }
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (message.id !== id) {
+          continue;
+        }
+        if (message.error) {
+          finish(
+            () => reject(new DaemonRpcError(message.error.code, message.error.message, message.error.data))
+          );
+          return;
+        }
+        finish(() => resolve(message.result));
+        return;
+      }
+    });
+    socket.on("close", () => {
+      finish(
+        () => reject(new DaemonUnavailableError("Connection to the Appduct daemon closed.", "closed"))
+      );
+    });
+  });
+};
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var pollForSocket = async (socketPath, timeoutMs, pollIntervalMs) => {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isSocketConnectable(socketPath)) {
+      return true;
+    }
+    await sleep(pollIntervalMs);
+  }
+  return isSocketConnectable(socketPath);
+};
+var unlinkStaleSocketIfDaemonDead = async (paths) => {
+  let pid;
+  try {
+    pid = Number.parseInt((await readFile3(paths.pidFilePath, "utf8")).trim(), 10);
+  } catch {
+    pid = void 0;
+  }
+  if (pid === void 0 || Number.isNaN(pid) || !isProcessAlive(pid)) {
+    await rm2(paths.socketPath, { force: true });
+  }
+};
+var defaultSpawn = async (args, context) => {
+  const paths = getStateDirPaths(context.stateDir);
+  await rotateDaemonLogIfNeeded({
+    logFilePath: context.logFilePath,
+    maxBytes: await resolveDaemonLogMaxBytes(context.stateDir),
+    pidFilePath: paths.pidFilePath,
+    socketPath: paths.socketPath
+  });
+  const logFd = await open2(context.logFilePath, "a", 384);
+  try {
+    await ensureDaemonLogMode(context.logFilePath);
+    const childEnv = { ...process.env, APPDUCT_STATE_DIR: context.stateDir };
+    delete childEnv[DAEMON_VERSION_OVERRIDE_ENV];
+    const child = spawnChildProcess(process.execPath, [defaultBinPath, ...args], {
+      detached: true,
+      stdio: ["ignore", logFd.fd, logFd.fd],
+      env: childEnv
+    });
+    child.unref();
+  } finally {
+    await logFd.close();
+  }
+};
+var SPAWN_LOCK_STALE_MS = 3e4;
+var pollUntilLockReleased = async (lockPath, timeoutMs, pollIntervalMs) => {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!await pathExists(lockPath)) {
+      return true;
+    }
+    await sleep(pollIntervalMs);
+  }
+  return !await pathExists(lockPath);
+};
+var readPidfilePid = async (paths) => {
+  try {
+    const pid = Number.parseInt((await readFile3(paths.pidFilePath, "utf8")).trim(), 10);
+    return Number.isNaN(pid) ? void 0 : pid;
+  } catch {
+    return void 0;
+  }
+};
+var pathExists = async (target) => {
+  try {
+    await stat2(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var acquireSpawnLock = async (lockPath) => {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const lockHandle = await open2(lockPath, "wx", 384);
+      await lockHandle.close();
+      return true;
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+    }
+    let heldForMs;
+    try {
+      heldForMs = Date.now() - (await stat2(lockPath)).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (heldForMs < SPAWN_LOCK_STALE_MS) {
+      return false;
+    }
+    await rm2(lockPath, { force: true });
+  }
+  return false;
+};
+var spawnDaemonAndWait = async (paths, spawn, waitTimeoutMs, pollIntervalMs, options = {}) => {
+  await ensureStateDir(paths.root);
+  const acquiredLock = await acquireSpawnLock(paths.spawnLockPath);
+  let lockWaitTimedOut = false;
+  if (acquiredLock) {
+    try {
+      const shouldSpawn = options.beforeSpawn ? await options.beforeSpawn() : true;
+      if (shouldSpawn) {
+        await unlinkStaleSocketIfDaemonDead(paths);
+        await spawn(["daemon", "run"], { stateDir: paths.root, logFilePath: paths.logFilePath });
+      }
+    } finally {
+      await rm2(paths.spawnLockPath, { force: true });
+    }
+  } else if (options.awaitLockRelease) {
+    lockWaitTimedOut = !await pollUntilLockReleased(paths.spawnLockPath, waitTimeoutMs, pollIntervalMs);
+  }
+  const ready = await pollForSocket(paths.socketPath, waitTimeoutMs, pollIntervalMs);
+  if (!ready) {
+    const lockHint = await pathExists(paths.spawnLockPath) ? ` Another process holds the spawn-lock at "${paths.spawnLockPath}"; if no "appduct daemon" is starting, delete it and retry.` : "";
+    throw new DaemonUnavailableError(
+      `Timed out waiting for the Appduct daemon socket at "${paths.socketPath}".${lockHint}`
+    );
+  }
+  return { ownedLock: acquiredLock, lockWaitTimedOut };
+};
+var versionChecks = /* @__PURE__ */ new Map();
+var RESTART_REQUEST_TIMEOUT_MS = 3e3;
+var readStatusSpawningIfNeeded = async (context) => {
+  try {
+    return await sendRequest(
+      context.paths.socketPath,
+      RPC_METHODS.daemonStatus,
+      {},
+      context.requestTimeoutMs
+    );
+  } catch (error) {
+    if (!isConnectionMissingError(error)) {
+      throw error;
+    }
+    if (!context.autoSpawn) {
+      return void 0;
+    }
+    await spawnDaemonAndWait(context.paths, context.spawn, context.waitTimeoutMs, context.pollIntervalMs);
+    return sendRequest(
+      context.paths.socketPath,
+      RPC_METHODS.daemonStatus,
+      {},
+      context.requestTimeoutMs
+    );
+  }
+};
+var readStatusIfReachable = async (context) => {
+  try {
+    return await sendRequest(
+      context.paths.socketPath,
+      RPC_METHODS.daemonStatus,
+      {},
+      RESTART_REQUEST_TIMEOUT_MS
+    );
+  } catch (error) {
+    if (isConnectionMissingError(error)) {
+      return void 0;
+    }
+    if (isRequestTimeoutError(error)) {
+      throw new DaemonUnavailableError(
+        `The Appduct daemon at "${context.paths.socketPath}" did not answer "daemon.status" within ${RESTART_REQUEST_TIMEOUT_MS}ms, so it was not replaced. It is running but unresponsive \u2014 run "appduct daemon stop" and retry.`,
+        "timeout"
+      );
+    }
+    throw error;
+  }
+};
+var isDaemonGone = async (paths) => {
+  if (await isSocketConnectable(paths.socketPath)) {
+    return false;
+  }
+  let pid;
+  try {
+    pid = Number.parseInt((await readFile3(paths.pidFilePath, "utf8")).trim(), 10);
+  } catch {
+    return true;
+  }
+  return pid === void 0 || Number.isNaN(pid) || !isProcessAlive(pid);
+};
+var readLiveState = (status) => {
+  return {
+    sessions: Array.isArray(status.sessions) ? status.sessions.length : 0,
+    pendingLinks: typeof status.pendingLinks === "number" ? status.pendingLinks : 0
+  };
+};
+var isSafeToRestart = (live) => {
+  return live.sessions === 0 && live.pendingLinks === 0;
+};
+var pollUntilDaemonGone = async (paths, timeoutMs, pollIntervalMs) => {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isDaemonGone(paths)) {
+      return true;
+    }
+    await sleep(pollIntervalMs);
+  }
+  return isDaemonGone(paths);
+};
+var restartDaemon = async (context) => {
+  const pidBefore = await readPidfilePid(context.paths);
+  const outcome = await spawnDaemonAndWait(
+    context.paths,
+    context.spawn,
+    context.waitTimeoutMs,
+    context.pollIntervalMs,
+    {
+      awaitLockRelease: true,
+      beforeSpawn: async () => {
+        const status = await readStatusIfReachable(context);
+        if (status === void 0) {
+          return true;
+        }
+        if (isSameVersion(status.version, context.check.clientVersion)) {
+          return false;
+        }
+        const live = readLiveState(status);
+        if (!isSafeToRestart(live) && !context.check.forceRestart) {
+          throw new DaemonVersionMismatchError(status.version, context.check.clientVersion, live);
+        }
+        try {
+          await sendRequest(
+            context.paths.socketPath,
+            RPC_METHODS.daemonShutdown,
+            {},
+            RESTART_REQUEST_TIMEOUT_MS
+          );
+        } catch (error) {
+          if (isRequestTimeoutError(error)) {
+            throw new DaemonUnavailableError(
+              `The Appduct daemon at "${context.paths.socketPath}" did not acknowledge "daemon.shutdown" within ${RESTART_REQUEST_TIMEOUT_MS}ms, so it was left running. Run "appduct daemon stop" and retry.`,
+              "timeout"
+            );
+          }
+          if (!isDaemonUnreachableError(error)) {
+            throw error;
+          }
+        }
+        if (!await pollUntilDaemonGone(context.paths, context.waitTimeoutMs, context.pollIntervalMs)) {
+          throw new DaemonUnavailableError(
+            `The Appduct daemon at "${context.paths.socketPath}" did not shut down in time; run "appduct daemon stop" and retry.`
+          );
+        }
+        return true;
+      }
+    }
+  );
+  if (!outcome.ownedLock && outcome.lockWaitTimedOut && await readPidfilePid(context.paths) === pidBefore) {
+    throw new DaemonUnavailableError(
+      `The Appduct daemon at "${context.paths.socketPath}" did not shut down in time: another process has held the spawn-lock at "${context.paths.spawnLockPath}" for longer than this command waited. Retry, or run "appduct daemon stop" if nothing is starting a daemon.`
+    );
+  }
+};
+var warnOlderClient = (context, daemonVersion) => {
+  const message = `appduct: the running daemon is version ${daemonVersion}, newer than this client (${context.check.clientVersion}). Continuing without restarting it \u2014 a newer daemon serves an older client, and replacing it would downgrade whatever started it. Run "appduct daemon stop" if you want this client's daemon instead.
+`;
+  const warn = context.check.onWarning ?? ((text) => void process.stderr.write(text));
+  warn(message);
+};
+var runVersionCheck = async (context) => {
+  const status = await readStatusSpawningIfNeeded(context);
+  if (status === void 0) {
+    return;
+  }
+  if (isSameVersion(status.version, context.check.clientVersion)) {
+    return;
+  }
+  if ((compareVersions(context.check.clientVersion, status.version) ?? -1) <= 0) {
+    warnOlderClient(context, status.version);
+    return;
+  }
+  const live = readLiveState(status);
+  if (!isSafeToRestart(live) && !context.check.forceRestart) {
+    throw new DaemonVersionMismatchError(status.version, context.check.clientVersion, live);
+  }
+  await restartDaemon(context);
+  const replacement = await readStatusIfReachable(context);
+  if (replacement === void 0) {
+    throw new DaemonUnavailableError(
+      `The Appduct daemon was restarted but nothing is listening at "${context.paths.socketPath}"; check "${context.paths.logFilePath}".`
+    );
+  }
+  if (isSameVersion(replacement.version, context.check.clientVersion)) {
+    return;
+  }
+  if ((compareVersions(context.check.clientVersion, replacement.version) ?? -1) <= 0) {
+    warnOlderClient(context, replacement.version);
+    return;
+  }
+  throw new DaemonVersionRestartIneffectiveError(
+    replacement.version,
+    context.check.clientVersion,
+    readLiveState(replacement)
+  );
+};
+var ensureDaemonVersion = async (paths, options, spawn) => {
+  const check = options.checkVersion;
+  if (!check) {
+    return;
+  }
+  const cached2 = versionChecks.get(paths.socketPath);
+  if (cached2) {
+    return cached2;
+  }
+  const pending = runVersionCheck({
+    paths,
+    spawn,
+    autoSpawn: options.autoSpawn ?? true,
+    requestTimeoutMs: options.requestTimeoutMs ?? 1e4,
+    waitTimeoutMs: options.spawnWaitTimeoutMs ?? 5e3,
+    pollIntervalMs: options.spawnPollIntervalMs ?? 100,
+    check
+  }).catch((error) => {
+    if (!(error instanceof DaemonVersionMismatchError)) {
+      versionChecks.delete(paths.socketPath);
+    }
+    throw error;
+  });
+  versionChecks.set(paths.socketPath, pending);
+  return pending;
+};
+var ensureDaemonVersionMatches = async (options) => {
+  const paths = getStateDirPaths(options.stateDir);
+  await ensureDaemonVersion(
+    paths,
+    { ...options, autoSpawn: options.autoSpawn ?? false },
+    options.spawn ?? defaultSpawn
+  );
+};
+var callDaemon = async (method, params, options) => {
+  const paths = getStateDirPaths(options.stateDir);
+  const autoSpawn = options.autoSpawn ?? true;
+  const spawn = options.spawn ?? defaultSpawn;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 1e4;
+  await ensureDaemonVersion(paths, options, spawn);
+  try {
+    return await sendRequest(paths.socketPath, method, params, requestTimeoutMs);
+  } catch (error) {
+    if (!autoSpawn || !isConnectionMissingError(error)) {
+      throw error;
+    }
+    await spawnDaemonAndWait(
+      paths,
+      spawn,
+      options.spawnWaitTimeoutMs ?? 5e3,
+      options.spawnPollIntervalMs ?? 100
+    );
+    return sendRequest(paths.socketPath, method, params, requestTimeoutMs);
+  }
+};
+
+// src/errors.ts
+var EXIT_CODE_BY_ERROR_TYPE = {
+  usage_error: 64,
+  validation_error: 65,
+  // EX_NOINPUT (66): "an input file did not exist or was not readable" — `doctor` throws this for a
+  // missing external tool or an unreadable/corrupt artifact, deliberately distinct from every other
+  // code here so a release pipeline can't mistake "we couldn't tell" for either a clean pass or an
+  // assertion failure (docs/tasks/08-appduct-doctor.md).
+  inspection_error: 66,
+  connection_error: 70,
+  session_error: 71,
+  tool_error: 72,
+  permission_error: 77,
+  internal_error: 1,
+  // `doctor --assert-present`/`--assert-absent`: the artifact was inspected successfully and the
+  // assertion did not hold. Distinct from `inspection_error` (66) — this means the answer is known
+  // and it's "no", not "couldn't tell" — and distinct from `internal_error` (1) so a caller can't
+  // conflate a normal assertion failure with an unexpected crash.
+  assertion_error: 3
+};
+var RPC_ERROR_EXIT_CLASS = {
+  no_session: "session_error",
+  ambiguous_session: "session_error",
+  unknown_session: "session_error",
+  session_not_active: "session_error",
+  session_suspended: "session_error",
+  tool_not_found: "tool_error",
+  tool_input_validation_error: "tool_error",
+  tool_output_validation_error: "tool_error",
+  tool_execution_error: "tool_error",
+  tool_serialization_error: "tool_error",
+  tool_timeout: "tool_error",
+  tool_cancelled: "tool_error",
+  policy_denied: "permission_error",
+  invalid_request: "validation_error"
+};
+var AppductCliError = class extends Error {
+  type;
+  details;
+  constructor(type, message, details) {
+    super(message);
+    this.name = "AppductCliError";
+    this.type = type;
+    this.details = details;
+  }
+};
+var usageError = (message, details) => {
+  return new AppductCliError("usage_error", message, details);
+};
+var connectionError = (message, details) => {
+  return new AppductCliError("connection_error", message, details);
+};
+var isAppductCliError = (value) => {
+  return value instanceof AppductCliError;
+};
+var rpcErrorClass = (error) => {
+  const type = error.data?.type;
+  return type ? RPC_ERROR_EXIT_CLASS[type] : void 0;
+};
+var toCliError = (error) => {
+  if (isAppductCliError(error)) {
+    return {
+      type: error.type,
+      message: error.message,
+      details: error.details
+    };
+  }
+  if (error instanceof DaemonVersionMismatchError) {
+    return {
+      type: "connection_error",
+      message: error.message,
+      details: {
+        daemon_version: error.daemonVersion,
+        client_version: error.clientVersion,
+        session_count: error.sessionCount,
+        pending_link_count: error.pendingLinkCount
+      }
+    };
+  }
+  if (error instanceof DaemonRpcError && error.data?.type) {
+    return {
+      type: error.data.type,
+      message: error.message,
+      details: error.data.details
+    };
+  }
+  if (isDaemonUnreachableError(error)) {
+    return {
+      type: "connection_error",
+      message: error instanceof Error ? error.message : "The Appduct daemon is unreachable."
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      type: "internal_error",
+      message: error.message
+    };
+  }
+  return {
+    type: "internal_error",
+    message: "An unexpected error occurred.",
+    details: error
+  };
+};
+var getExitCodeForError = (error) => {
+  if (isAppductCliError(error)) {
+    return EXIT_CODE_BY_ERROR_TYPE[error.type];
+  }
+  if (error instanceof DaemonVersionMismatchError) {
+    return EXIT_CODE_BY_ERROR_TYPE.connection_error;
+  }
+  if (error instanceof DaemonRpcError) {
+    const cliErrorClass = rpcErrorClass(error);
+    return EXIT_CODE_BY_ERROR_TYPE[cliErrorClass ?? "internal_error"];
+  }
+  if (isDaemonUnreachableError(error)) {
+    return EXIT_CODE_BY_ERROR_TYPE.connection_error;
+  }
+  return EXIT_CODE_BY_ERROR_TYPE.internal_error;
+};
+
+// src/commands/tools.ts
+var listTools = (selector, context, params = {}) => {
+  return callDaemon(
+    RPC_METHODS2.toolsList,
+    { selector, ...params },
+    { stateDir: context.stateDir, spawn: context.spawn }
+  );
+};
+var findTool = (tools, name) => {
+  return tools.find((tool) => tool.name === name);
+};
+var hasPagingOptions = (options) => {
+  return options.group !== void 0 || options.filter !== void 0 || options.limit !== void 0 || options.offset !== void 0;
+};
+var hasListingOnlyOptions = (options) => {
+  return hasPagingOptions(options) || options.groups === true;
+};
+var toListParams = (options) => {
+  return { group: options.group, filter: options.filter, limit: options.limit, offset: options.offset };
+};
+var toListing = (result, params) => {
+  return {
+    ...result,
+    ...params.group !== void 0 ? { group: params.group } : {},
+    ...params.filter !== void 0 ? { filter: params.filter } : {},
+    ...params.limit !== void 0 ? { limit: params.limit } : {},
+    ...params.offset !== void 0 ? { offset: params.offset } : {}
+  };
+};
+var listingOnlyError = () => {
+  return usageError(
+    '"--group", "--groups", "--filter", "--limit", and "--offset" only apply to a tools listing, not a single tool lookup.'
+  );
+};
+var listGroups = async (selector, context) => {
+  const result = await listTools(selector, context, { limit: 1 });
+  return { groups: requireGroupSupport(result), total: result.total };
+};
+var requireGroupSupport = (result) => {
+  if (!Array.isArray(result.groups)) {
+    throw connectionError(
+      'The running Appduct daemon does not support tool groups ("--group"/"--groups"). Restart it with a newer version: `appduct daemon stop`, or pass `--daemon-restart`.'
+    );
+  }
+  return result.groups;
+};
+var listOrGroups = async (selector, options, context) => {
+  if (options.groups === true) {
+    try {
+      return await listGroups(selector, context);
+    } catch (error) {
+      if (selector !== void 0 && error instanceof DaemonRpcError && error.data?.type === "unknown_session") {
+        throw usageError(
+          `No session matches "${selector}". "--groups" takes no value; to list one group's tools, use "--group ${selector}".`
+        );
+      }
+      throw error;
+    }
+  }
+  const params = toListParams(options);
+  const result = await listTools(selector, context, params);
+  if (params.group !== void 0) {
+    requireGroupSupport(result);
+  }
+  return toListing(result, params);
+};
+var handleToolsCommand = async (options, context) => {
+  if (options.groups === true && hasPagingOptions(options)) {
+    throw usageError(
+      '"--groups" lists every group in the session and cannot be combined with "--group", "--filter", "--limit", or "--offset".'
+    );
+  }
+  if (options.name !== void 0 && hasListingOnlyOptions(options)) {
+    throw listingOnlyError();
+  }
+  if (options.selector !== void 0 && options.name !== void 0) {
+    const result = await listTools(options.selector, context);
+    const tool = findTool(result.tools, options.name);
+    if (!tool) {
+      throw usageError(
+        `Tool "${options.name}" is not registered on session "${options.selector}".`,
+        { available: result.tools.map((entry) => entry.name) }
+      );
+    }
+    return { ok: true, data: tool };
+  }
+  if (options.selector !== void 0) {
+    let implicitTools;
+    try {
+      implicitTools = await listTools(void 0, context);
+    } catch (error) {
+      if (!(error instanceof DaemonRpcError)) {
+        throw error;
+      }
+    }
+    if (implicitTools) {
+      const tool = findTool(implicitTools.tools, options.selector);
+      if (tool) {
+        if (hasListingOnlyOptions(options)) {
+          throw listingOnlyError();
+        }
+        return { ok: true, data: tool };
+      }
+    }
+    return { ok: true, data: await listOrGroups(options.selector, options, context) };
+  }
+  return { ok: true, data: await listOrGroups(void 0, options, context) };
+};
+
+// src/cli/command-options.ts
+var parsePositiveIntegerOption = (value, flagName) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) {
+    throw usageError(`"${flagName}" must be a positive integer.`);
+  }
+  return parsed;
+};
+var parseNonNegativeIntegerOption = (value, flagName) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 0) {
+    throw usageError(`"${flagName}" must be a non-negative integer.`);
+  }
+  return parsed;
+};
+var readTextOption = (argv, value, flagName) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value === "boolean") {
+    throw usageError(`"${flagName}" requires a value.`);
+  }
+  let raw;
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--") {
+      break;
+    }
+    if (token === flagName && index + 1 < argv.length) {
+      raw = argv[index + 1];
+      index += 1;
+    } else if (token.startsWith(`${flagName}=`)) {
+      raw = token.slice(flagName.length + 1);
+    }
+  }
+  return raw ?? String(Array.isArray(value) ? value.at(-1) : value);
+};
+var splitOptionalSelectorAndTarget = (args, commandUsage) => {
+  if (args.length > 2) {
+    throw usageError(`Usage: ${commandUsage} (too many arguments).`);
+  }
+  if (args.length === 2) {
+    return { selector: args[0], target: args[1] };
+  }
+  if (args.length === 1) {
+    return { selectorOrTarget: args[0] };
+  }
+  return {};
+};
+
+// src/cli/global-flags.ts
+var formatJson = (value, flags) => {
+  return flags.pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+};
+
+// src/output.ts
+import pc from "picocolors";
+import {
+  formatAgentWebSocketUrl,
+  renderToolSignature,
+  summarizeToolDescription
+} from "@appduct/shared";
+
+// src/qr-terminal.ts
+import { toQR } from "toqr";
+var HALF_UPPER = "\u2580";
+var HALF_LOWER = "\u2584";
+var FULL = "\u2588";
+var renderQrToTerminal = (content, options) => {
+  const margin = options?.margin ?? 0;
+  const ecLevel = options?.ecLevel ?? 1;
+  const modules = toQR(content, ecLevel);
+  const side = Math.sqrt(modules.length);
+  if (!Number.isInteger(side)) {
+    throw new Error("Invalid QR matrix size");
+  }
+  const dim = side + 2 * margin;
+  const isDark = (row, col) => {
+    if (row < margin || col < margin || row >= margin + side || col >= margin + side) {
+      return false;
+    }
+    const mr = row - margin;
+    const mc = col - margin;
+    return modules[mr * side + mc] === 1;
+  };
+  const lines = [];
+  for (let row = 0; row < dim; row += 2) {
+    let line = "";
+    for (let col = 0; col < dim; col++) {
+      const top = isDark(row, col);
+      const bottom = row + 1 < dim ? isDark(row + 1, col) : false;
+      line += top ? bottom ? FULL : HALF_UPPER : bottom ? HALF_LOWER : " ";
+    }
+    lines.push(line);
+  }
+  return lines.join("\n");
+};
+
+// src/output.ts
+var renderMetaLines = (meta) => {
+  if (!meta) {
+    return [];
+  }
+  return [
+    "Meta",
+    `  Command: ${meta.command}`,
+    `  Timestamp: ${meta.timestamp}`,
+    ...typeof meta.duration_ms === "number" ? [`  Duration: ${meta.duration_ms} ms`] : []
+  ];
+};
+var formatScalar = (value, flags) => {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  return formatJson(value, flags);
+};
+var renderFields = (title, fields, flags) => {
+  const visibleFields = fields.filter(([, value]) => value !== void 0);
+  if (visibleFields.length === 0) {
+    return [];
+  }
+  const width = Math.max(...visibleFields.map(([label]) => label.length));
+  return [
+    title,
+    ...visibleFields.map(([label, value]) => `  ${label.padEnd(width)}  ${formatScalar(value, flags)}`)
+  ];
+};
+var formatAge = (fromIso, toIso) => {
+  const elapsedMs = Math.max(0, new Date(toIso).getTime() - new Date(fromIso).getTime());
+  const elapsedSeconds = Math.floor(elapsedMs / 1e3);
+  if (elapsedSeconds < 60) {
+    return `${elapsedSeconds}s`;
+  }
+  const elapsedMinutes = Math.floor(elapsedSeconds / 60);
+  if (elapsedMinutes < 60) {
+    return `${elapsedMinutes}m`;
+  }
+  const elapsedHours = Math.floor(elapsedMinutes / 60);
+  if (elapsedHours < 24) {
+    return `${elapsedHours}h`;
+  }
+  return `${Math.floor(elapsedHours / 24)}d`;
+};
+var formatDevice = (device) => {
+  const parts = [device.manufacturer, device.model].filter((part) => Boolean(part));
+  const label = parts.length > 0 ? parts.join(" ") : "unknown device";
+  return device.os ? `${label} (${device.os})` : label;
+};
+var renderLsData = (colors, data, now) => {
+  if (data.length === 0) {
+    return [colors.dim("Sessions"), "  No Appduct sessions are registered."];
+  }
+  const nowIso = now.toISOString();
+  const headers = ["Alias", "State", "Device", "Tools", "Age"];
+  const rows = data.map((session) => [
+    session.alias,
+    session.state,
+    formatDevice(session.device),
+    String(session.toolCount),
+    formatAge(session.claimedAt ?? session.createdAt, nowIso)
+  ]);
+  const widths = headers.map(
+    (header, index) => Math.max(header.length, ...rows.map((row) => row[index].length))
+  );
+  return [
+    colors.green("Sessions"),
+    `  ${headers.map((header, index) => header.padEnd(widths[index])).join("  ")}`,
+    ...rows.map((row) => `  ${row.map((cell, index) => cell.padEnd(widths[index])).join("  ")}`)
+  ];
+};
+var isToolsListing = (data) => {
+  return typeof data === "object" && data !== null && Array.isArray(data.tools);
+};
+var isToolGroupsListing = (data) => {
+  return typeof data === "object" && data !== null && Array.isArray(data.groups) && !Array.isArray(data.tools);
+};
+var UNGROUPED_LABEL = "(ungrouped)";
+var MAX_FOOTER_GROUPS = 10;
+var hasAnyGroup = (groups) => {
+  return (groups ?? []).some((entry) => entry.group !== null);
+};
+var topLevelGroups = (groups) => {
+  return (groups ?? []).filter((entry) => entry.group !== null && !entry.group.includes("/"));
+};
+var renderEmptyToolsLine = (data) => {
+  if (data.total > 0) {
+    return `  No tools at offset ${data.offset ?? 0}; ${data.total} matching tool${data.total === 1 ? "" : "s"} in total.`;
+  }
+  if (data.group !== void 0) {
+    const match = data.filter === void 0 ? "" : ` match ${JSON.stringify(data.filter)}`;
+    return `  No tools in group ${JSON.stringify(data.group)}${match}. Run \`appduct tools --groups\` to see the session's groups.`;
+  }
+  return data.filter === void 0 ? "  No tools registered." : `  No tools match ${JSON.stringify(data.filter)}.`;
+};
+var renderGroupHint = (data) => {
+  if (data.group !== void 0 || !hasAnyGroup(data.groups)) {
+    return void 0;
+  }
+  const top = topLevelGroups(data.groups);
+  const named = top.slice(0, MAX_FOOTER_GROUPS).map((entry) => `${entry.group} ${entry.total}`);
+  const more = top.length > MAX_FOOTER_GROUPS ? `, ... ${top.length - MAX_FOOTER_GROUPS} more; see --groups` : "";
+  return `--group <name> (groups: ${named.join(", ")}${more})`;
+};
+var renderTruncationLine = (data) => {
+  if (data.tools.length >= data.total) {
+    return [];
+  }
+  const groupHint = renderGroupHint(data);
+  const narrow = groupHint === void 0 ? "--filter <text> or" : `${groupHint} or --filter <text>, or`;
+  return [
+    "",
+    `Showing ${data.tools.length} of ${data.total} tools (offset ${data.offset ?? 0}). Narrow with ${narrow} page with --offset <n>.`
+  ];
+};
+var renderToolSummaryLines = (tool, indent) => {
+  const tag = tool.policy === "allow" ? "" : `  [${tool.policy}]`;
+  return [`${indent}${renderToolSignature(tool)}${tag}`, `${indent}  ${summarizeToolDescription(tool.description)}`];
+};
+var renderGroupedToolLines = (colors, tools) => {
+  const byGroup = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    const key = tool.group ?? null;
+    const bucket = byGroup.get(key);
+    if (bucket) {
+      bucket.push(tool);
+    } else {
+      byGroup.set(key, [tool]);
+    }
+  }
+  const tops = /* @__PURE__ */ new Map();
+  for (const key of byGroup.keys()) {
+    if (key === null) {
+      continue;
+    }
+    const slash = key.indexOf("/");
+    const top = slash === -1 ? key : key.slice(0, slash);
+    const subs = tops.get(top) ?? [];
+    if (slash !== -1) {
+      subs.push(key);
+    }
+    tops.set(top, subs);
+  }
+  const byCodePoint = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+  const lines = [];
+  for (const top of [...tops.keys()].sort(byCodePoint)) {
+    lines.push(`  ${colors.cyan(top)}`);
+    lines.push(...(byGroup.get(top) ?? []).flatMap((tool) => renderToolSummaryLines(tool, "    ")));
+    for (const sub of tops.get(top).sort(byCodePoint)) {
+      lines.push(`    ${colors.cyan(sub)}`);
+      lines.push(...byGroup.get(sub).flatMap((tool) => renderToolSummaryLines(tool, "      ")));
+    }
+  }
+  const ungrouped = byGroup.get(null);
+  if (ungrouped) {
+    lines.push(`  ${colors.cyan(UNGROUPED_LABEL)}`);
+    lines.push(...ungrouped.flatMap((tool) => renderToolSummaryLines(tool, "    ")));
+  }
+  return lines;
+};
+var renderToolsTitle = (colors, data) => {
+  return colors.green(data.group === void 0 ? "Tools" : `Tools in group ${data.group}`);
+};
+var renderToolSummaryTable = (colors, data) => {
+  if (data.tools.length === 0) {
+    return [renderToolsTitle(colors, data), renderEmptyToolsLine(data)];
+  }
+  const grouped = data.group === void 0 && hasAnyGroup(data.groups);
+  return [
+    renderToolsTitle(colors, data),
+    ...grouped ? renderGroupedToolLines(colors, data.tools) : data.tools.flatMap((tool) => renderToolSummaryLines(tool, "  ")),
+    ...renderTruncationLine(data),
+    "",
+    "Run `appduct tools <name>` for a tool's full schema."
+  ];
+};
+var renderToolDetail = (colors, tool, flags) => {
+  return renderFields(
+    colors.green(`Tool: ${tool.name}`),
+    [
+      ["Signature", renderToolSignature(tool)],
+      ["Description", tool.description],
+      ["Input schema", tool.input_schema],
+      ["Output schema", tool.output_schema],
+      // `?? undefined` keeps an ungrouped tool's row hidden rather than printing a bare "null":
+      // `renderFields` drops undefined rows, and the machine form's `null` is for consumers, not
+      // for a human scanning one tool's schema.
+      ["Group", tool.group ?? void 0],
+      ["Annotations", tool.annotations],
+      // Only rendered for a tool that declares one; `renderFields` drops undefined rows, so a
+      // tool on the daemon's default deadline shows no line at all rather than a misleading
+      // "10000".
+      ["Timeout (ms)", tool.timeout_ms]
+    ],
+    flags
+  );
+};
+var renderToolsFullListing = (colors, data, flags) => {
+  if (data.tools.length === 0) {
+    return [renderToolsTitle(colors, data), renderEmptyToolsLine(data)];
+  }
+  return [
+    ...data.tools.flatMap((tool, index) => [
+      ...index > 0 ? [""] : [],
+      ...renderToolDetail(colors, tool, flags)
+    ]),
+    ...renderTruncationLine(data)
+  ];
+};
+var renderToolGroups = (colors, data) => {
+  if (data.groups.length === 0) {
+    return [colors.green("Groups"), "  No tools registered."];
+  }
+  const label = (entry) => {
+    if (entry.group === null) {
+      return UNGROUPED_LABEL;
+    }
+    return entry.group.includes("/") ? `  ${entry.group}` : entry.group;
+  };
+  const width = Math.max(...data.groups.map((entry) => label(entry).length));
+  const countWidth = Math.max(...data.groups.map((entry) => String(entry.total).length));
+  return [
+    colors.green("Groups"),
+    ...data.groups.map((entry) => `  ${label(entry).padEnd(width)}  ${String(entry.total).padStart(countWidth)}`),
+    "",
+    `${data.total} tool${data.total === 1 ? "" : "s"} in total. ` + (hasAnyGroup(data.groups) ? "Run `appduct tools --group <name>` to list one group's tools." : "No tool declares a group.")
+  ];
+};
+var renderToolsData = (colors, data, flags, full) => {
+  if (isToolGroupsListing(data)) {
+    return renderToolGroups(colors, data);
+  }
+  if (!isToolsListing(data)) {
+    return renderToolDetail(colors, data, flags);
+  }
+  return full ? renderToolsFullListing(colors, data, flags) : renderToolSummaryTable(colors, data);
+};
+var renderInvokeData = (colors, data, flags) => {
+  return [colors.green("Result"), formatScalar(data, flags)];
+};
+var renderLinkData = (colors, data, flags, qr) => {
+  const lines = [
+    colors.green("Link Created"),
+    ...renderFields(
+      "Link",
+      [
+        ["Session", data.sessionId],
+        ["Deep link", data.deepLink],
+        ["Endpoint", formatAgentWebSocketUrl(data.endpoint)],
+        ["Pin", data.pin],
+        ["Expires", new Date(data.expiresAt * 1e3).toISOString()],
+        ["Delivered", data.delivered ? `yes (${data.target})` : void 0]
+      ],
+      flags
+    )
+  ];
+  if (qr) {
+    lines.push("", "QR", renderQrToTerminal(data.deepLink));
+  }
+  return lines;
+};
+var renderRevokeData = (colors, _data) => {
+  return [colors.green("Session Revoked")];
+};
+var renderKeygenData = (colors, data, flags) => {
+  return [
+    colors.green("Key Ready"),
+    ...renderFields(
+      "Key",
+      [
+        ["Path", data.path],
+        ["Fingerprint", data.pin]
+      ],
+      flags
+    )
+  ];
+};
+var renderInitData = (colors, data, flags) => {
+  const snippet = JSON.stringify(
+    { mcpServers: { appduct: data.mcpServerEntry } },
+    null,
+    2
+  );
+  return [
+    colors.green(data.changed ? "Project Initialized" : "Project Already Initialized"),
+    ...renderFields(
+      "Config",
+      [
+        ["Path", data.path],
+        ["Scheme", data.scheme],
+        ["Source", data.source],
+        // Only present for a scheme discovery read off a static project file (app.json, or one of
+        // the native Android/iOS probes) — names the exact file/key, not just which platform.
+        ["Read from", data.origin],
+        ["Written", data.changed ? data.created ? "created" : "updated" : "unchanged"]
+      ],
+      flags
+    ),
+    ...data.note === void 0 ? [] : ["", colors.yellow(`Note: ${data.note}`)],
+    "",
+    "MCP server entry",
+    ...snippet.split("\n").map((line) => `  ${line}`),
+    "",
+    "Next",
+    ...data.nextSteps.map((step, index) => `  ${index + 1}. ${step}`)
+  ];
+};
+var renderDaemonRunData = (colors, data, flags) => {
+  return [
+    colors.green("Daemon Running"),
+    ...renderFields(
+      "Daemon",
+      [
+        ["PID", data.daemon.pid],
+        ["State dir", data.daemon.state_dir],
+        ["Socket", data.daemon.socket_path]
+      ],
+      flags
+    )
+  ];
+};
+var renderDaemonStartData = (colors, data, flags) => {
+  return [
+    colors.green("Daemon Started"),
+    ...renderFields(
+      "Daemon",
+      [
+        ["PID", data.daemon.pid],
+        ["WSS port", data.daemon.wss_port],
+        ["Started at", data.daemon.started_at]
+      ],
+      flags
+    )
+  ];
+};
+var renderDaemonStopData = (colors, data, flags) => {
+  return [
+    colors.green("Daemon Stopped"),
+    ...renderFields("Daemon", [["Method", data.daemon.method]], flags)
+  ];
+};
+var formatByteSize = (bytes) => {
+  const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${unit === 0 ? value : value.toFixed(1)} ${units[unit]}`;
+};
+var renderDaemonStatusData = (colors, data, flags) => {
+  return [
+    colors.green("Daemon Status"),
+    ...renderFields(
+      "Daemon",
+      [
+        ["Version", data.daemon.version],
+        ["PID", data.daemon.pid],
+        ["Started at", data.daemon.started_at],
+        ["WSS port", data.daemon.wss_port],
+        ["Pinned keys", data.daemon.pinned_keys.length],
+        ["Sessions", data.daemon.session_count]
+      ],
+      flags
+    ),
+    "",
+    ...renderFields(
+      "Policy",
+      [
+        ["Default", data.policy.default],
+        ["Destructive", data.policy.destructive],
+        ["Overrides", data.policy.tools ? Object.keys(data.policy.tools).length : 0]
+      ],
+      flags
+    ),
+    "",
+    // The retention rows drop out entirely against a daemon that predates them (`renderFields`
+    // skips `undefined`), rather than printing "undefined" or an invented zero.
+    ...renderFields(
+      "Audit",
+      [
+        ["Path", data.audit.path],
+        ["Retention", data.audit.retention_days === void 0 ? void 0 : `${data.audit.retention_days} days`],
+        ["Files", data.audit.files],
+        ["Size", data.audit.bytes === void 0 ? void 0 : formatByteSize(data.audit.bytes)],
+        ["Failed writes", data.audit.failed_writes],
+        ["Failed prunes", data.audit.failed_prunes]
+      ],
+      flags
+    ),
+    // Version drift (issue #30) is the one thing here an operator has to act on, so it goes last
+    // — the line still on screen after the block scrolls — and in yellow, not a quiet field row.
+    ...data.warning ? ["", colors.yellow(`Warning: ${data.warning}`)] : []
+  ];
+};
+var renderDoctorData = (colors, data, flags) => {
+  return [
+    data.present ? colors.green("Appduct Present") : colors.yellow("Appduct Absent"),
+    ...renderFields(
+      "Artifact",
+      [
+        ["Path", data.artifact],
+        ["Platform", data.platform],
+        ["Format", data.format],
+        ["Present", data.present],
+        ["Signals", data.signals.length > 0 ? data.signals.join(", ") : "none"],
+        ["Assertion", data.assertion ? `${data.assertion.expected} (holds)` : void 0]
+      ],
+      flags
+    )
+  ];
+};
+var renderSuccessData = (colors, command, data, options) => {
+  const flags = options.flags;
+  switch (command) {
+    case "init":
+      return renderInitData(colors, data, flags);
+    case "keygen":
+      return renderKeygenData(colors, data, flags);
+    case "link":
+      return renderLinkData(colors, data, flags, options.qr);
+    case "ls":
+      return renderLsData(colors, data, options.now ?? /* @__PURE__ */ new Date());
+    case "tools":
+      return renderToolsData(colors, data, flags, options.full);
+    case "invoke":
+      return renderInvokeData(colors, data, flags);
+    case "revoke":
+      return renderRevokeData(colors, data);
+    case "daemon run":
+      return renderDaemonRunData(colors, data, flags);
+    case "daemon start":
+      return renderDaemonStartData(colors, data, flags);
+    case "daemon stop":
+      return renderDaemonStopData(colors, data, flags);
+    case "daemon status":
+      return renderDaemonStatusData(colors, data, flags);
+    case "doctor":
+      return renderDoctorData(colors, data, flags);
+    default:
+      return [colors.green("Command Complete"), formatJson(data, flags)];
+  }
+};
+var renderHumanError = (colors, error, flags, meta) => {
+  return [
+    colors.red("Command Failed"),
+    ...renderFields(
+      "Error",
+      [
+        ["Type", error.type],
+        ["Message", error.message],
+        ["Details", error.details]
+      ],
+      flags
+    ),
+    ...meta ? ["", ...renderMetaLines(meta)] : []
+  ].join("\n");
+};
+var renderResult = (result, options) => {
+  if (options.flags.json) {
+    return {
+      stdout: `${formatJson(result, options.flags)}
+`
+    };
+  }
+  const colors = pc.createColors(options.flags.color);
+  if (!result.ok) {
+    return {
+      stderr: `${renderHumanError(colors, result.error, options.flags, result.meta)}
+`
+    };
+  }
+  const lines = [
+    ...renderSuccessData(colors, options.command, result.data, options),
+    "",
+    ...renderMetaLines(result.meta)
+  ].filter((line, index, collection) => {
+    if (line !== "") {
+      return true;
+    }
+    return index > 0 && collection[index - 1] !== "" && index < collection.length - 1;
+  });
+  return {
+    stdout: `${lines.join("\n")}
+`
+  };
+};
+
+// src/cli/envelope.ts
+var createCommandMeta = (command, startedAt, finishedAt) => {
+  return {
+    command,
+    timestamp: finishedAt.toISOString(),
+    duration_ms: finishedAt.getTime() - startedAt.getTime()
+  };
+};
+var finalizeResult = (result, timing, flags) => {
+  if (!flags.verbose) {
+    return result;
+  }
+  return {
+    ...result,
+    meta: createCommandMeta(timing.command, timing.startedAt, timing.finishedAt)
+  };
+};
+
+// src/cli/runner.ts
+var writeRenderedOutput = (rendered, writers) => {
+  if (rendered.stdout) {
+    writers.stdout.write(rendered.stdout);
+  }
+  if (rendered.stderr) {
+    writers.stderr.write(rendered.stderr);
+  }
+};
+var executeCommand = async (command, handler, env, render = {}) => {
+  const startedAt = env.clock.now();
+  try {
+    const result = await handler();
+    const finishedAt = env.clock.now();
+    const finalized = finalizeResult(result, { command, startedAt, finishedAt }, env.flags);
+    const renderOptions = {
+      command,
+      flags: env.flags,
+      now: finishedAt,
+      qr: render.qr,
+      full: render.full
+    };
+    writeRenderedOutput(renderResult(finalized, renderOptions), env);
+    return 0;
+  } catch (error) {
+    const finishedAt = env.clock.now();
+    const cliError = toCliError(error);
+    const result = { ok: false, error: cliError };
+    const finalized = finalizeResult(result, { command, startedAt, finishedAt }, env.flags);
+    const renderOptions = {
+      command,
+      flags: env.flags,
+      now: finishedAt,
+      qr: render.qr,
+      full: render.full
+    };
+    writeRenderedOutput(renderResult(finalized, renderOptions), env);
+    return getExitCodeForError(error);
+  }
+};
+
+// src/cli/router.ts
+var commandName = (context) => {
+  return context.path.join(" ");
+};
+
+// src/cli/version-guard.ts
+var versionCheckOptions = async (context, onWarning = context.versionCheck.warn) => {
+  return {
+    clientVersion: context.versionCheck.clientVersion,
+    forceRestart: await context.versionCheck.forceRestart(),
+    onWarning
+  };
+};
+var guarded = (context) => {
+  return (handler) => {
+    return async () => {
+      await ensureDaemonVersionMatches({
+        stateDir: context.stateDir,
+        autoSpawn: false,
+        checkVersion: await versionCheckOptions(context)
+      });
+      return handler();
+    };
+  };
+};
+
+// src/cli/routes/tools.ts
+var route = async (context) => {
+  const { options, stateDir } = context;
+  return executeCommand(
+    commandName(context),
+    // Argument parsing runs inside the handler so a usage error renders through the runner (exit
+    // 64, `--json` envelope) instead of escaping the route as an uncaught rejection, and before
+    // the version check so a typo never waits on (or restarts) the daemon.
+    () => {
+      const { selector, target, selectorOrTarget } = splitOptionalSelectorAndTarget(
+        context.args,
+        "tools [selector] [name]"
+      );
+      const limit = parsePositiveIntegerOption(options.limit, "--limit");
+      const offset = parseNonNegativeIntegerOption(options.offset, "--offset");
+      const filter = readTextOption(context.argv, options.filter, "--filter");
+      const group = readTextOption(context.argv, options.group, "--group");
+      if (group !== void 0 && !isValidToolGroup(group)) {
+        throw usageError(
+          `"--group" must be a group name like "checkout" or "checkout/payment" (one or two "/"-separated segments of [a-zA-Z0-9_-], at most 64 characters each); got ${JSON.stringify(group)}.`
+        );
+      }
+      const groups = options.groups === void 0 ? void 0 : Boolean(options.groups);
+      if (groups && options.full) {
+        throw usageError('"--groups" lists groups only and cannot be combined with "--full".');
+      }
+      return guarded(context)(
+        () => handleToolsCommand(
+          { selector: selector ?? selectorOrTarget, name: target, group, groups, filter, limit, offset },
+          { stateDir }
+        )
+      )();
+    },
+    context.env,
+    { full: Boolean(options.full) }
+  );
+};
+export {
+  route
+};