@tonyclaw/agent-inspector 3.0.43 → 3.0.45

package/src/cli/alias.ts

@@ -0,0 +1,440 @@
+import { normalizeBasePath } from "../lib/basePath";
+
+const DEFAULT_ALIAS_HOST = "localhost";
+const DEFAULT_ALIAS_PORT = 9527;
+const ALIAS_CONTROL_PATH = "/.agent-inspector/base-path-aliases";
+const REQUEST_TIMEOUT_MS = 5_000;
+
+export type AliasFetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+export type AliasIo = {
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+};
+
+type AliasAction =
+  | { kind: "add"; basePath: string }
+  | { kind: "list" }
+  | { kind: "remove"; basePath: string };
+
+type AliasOptions = {
+  action: AliasAction;
+  host: string;
+  port: number;
+  json: boolean;
+};
+
+type AliasParseResult =
+  | { kind: "help" }
+  | { kind: "ok"; options: AliasOptions }
+  | { kind: "error"; message: string };
+
+type AliasSnapshot = {
+  canonicalBasePath: string;
+  aliases: readonly string[];
+  runtimeScoped: true;
+};
+
+type AliasRequestResult =
+  | { kind: "success"; snapshot: AliasSnapshot }
+  | { kind: "http-error"; status: number; detail: string | null }
+  | { kind: "network-error"; timedOut: boolean }
+  | { kind: "invalid-response" };
+
+type AliasOutput = {
+  action: AliasAction["kind"];
+  canonicalBasePath: string;
+  canonicalUrl: string;
+  aliases: readonly string[];
+  aliasUrls: readonly string[];
+  runtimeScoped: true;
+};
+
+const processIo: AliasIo = {
+  stdout: (text) => {
+    process.stdout.write(text);
+  },
+  stderr: (text) => {
+    process.stderr.write(text);
+  },
+};
+
+function parsePort(raw: string | undefined): number | null {
+  if (raw === undefined || raw.trim() === "") return null;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) return null;
+  return port;
+}
+
+function normalizeAliasPath(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (
+    !trimmed.startsWith("/") ||
+    trimmed.includes("?") ||
+    trimmed.includes("#") ||
+    trimmed.includes("\\")
+  ) {
+    return null;
+  }
+  return normalizeBasePath(trimmed);
+}
+
+function isValidHost(host: string): boolean {
+  const trimmed = host.trim();
+  return (
+    trimmed.length > 0 &&
+    !trimmed.includes("://") &&
+    !trimmed.includes("/") &&
+    !trimmed.includes("?") &&
+    !trimmed.includes("#") &&
+    !/\s/u.test(trimmed)
+  );
+}
+
+function formatHostForUrl(host: string): string {
+  if (host.startsWith("[") && host.endsWith("]")) return host;
+  return host.includes(":") ? `[${host}]` : host;
+}
+
+export function parseAliasArgs(argv: readonly string[]): AliasParseResult {
+  let host = DEFAULT_ALIAS_HOST;
+  let port = DEFAULT_ALIAS_PORT;
+  let json = false;
+  let help = false;
+  const positional: string[] = [];
+
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    switch (arg) {
+      case undefined:
+        continue;
+      case "--help":
+      case "-h":
+        help = true;
+        break;
+      case "--host": {
+        const value = argv[index + 1];
+        if (value === undefined || !isValidHost(value)) {
+          return {
+            kind: "error",
+            message: "alias: --host requires a hostname or IP address without a protocol or path",
+          };
+        }
+        host = value.trim();
+        index++;
+        break;
+      }
+      case "--port":
+      case "-p": {
+        const value = parsePort(argv[index + 1]);
+        if (value === null) {
+          return {
+            kind: "error",
+            message: "alias: --port must be an integer from 1 to 65535",
+          };
+        }
+        port = value;
+        index++;
+        break;
+      }
+      case "--json":
+        json = true;
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          return { kind: "error", message: `alias: unknown option ${arg}` };
+        }
+        positional.push(arg);
+    }
+  }
+
+  if (help) return { kind: "help" };
+
+  const command = positional[0];
+  switch (command) {
+    case "list":
+      if (positional.length !== 1) {
+        return { kind: "error", message: "alias: list does not accept a base path" };
+      }
+      return { kind: "ok", options: { action: { kind: "list" }, host, port, json } };
+    case "add":
+    case "remove": {
+      const rawBasePath = positional[1];
+      if (rawBasePath === undefined || positional.length !== 2) {
+        return { kind: "error", message: `alias: ${command} requires exactly one base path` };
+      }
+      const basePath = normalizeAliasPath(rawBasePath);
+      if (basePath === null) {
+        return {
+          kind: "error",
+          message: `alias: ${command} base path must be an absolute URL path without a query or hash`,
+        };
+      }
+      const action: AliasAction = { kind: command, basePath };
+      return { kind: "ok", options: { action, host, port, json } };
+    }
+    case undefined:
+      return { kind: "error", message: "alias: expected add <path>, list, or remove <path>" };
+    default:
+      return { kind: "error", message: `alias: unknown command ${command}` };
+  }
+}
+
+function aliasHelp(): string {
+  return `agent-inspector alias - mount additional base paths on a running runtime
+
+Usage:
+  agent-inspector alias add <path> [--host <host>] [--port <port>] [--json]
+  agent-inspector alias list [--host <host>] [--port <port>] [--json]
+  agent-inspector alias remove <path> [--host <host>] [--port <port>] [--json]
+
+Options:
+  --host <host>  Running instance host (default: localhost)
+  --port <port>  Running instance port (default: 9527)
+  --json         Emit machine-readable output
+  --help, -h     Show this help
+
+Aliases are runtime-scoped. This command never starts another Agent Inspector runtime.
+`;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseAliasSnapshot(value: unknown): AliasSnapshot | null {
+  if (!isObject(value)) return null;
+  const canonicalBasePath = value["canonicalBasePath"];
+  const aliases = value["aliases"];
+  const runtimeScoped = value["runtimeScoped"];
+  if (
+    typeof canonicalBasePath !== "string" ||
+    !Array.isArray(aliases) ||
+    !aliases.every((alias) => typeof alias === "string") ||
+    runtimeScoped !== true
+  ) {
+    return null;
+  }
+  return {
+    canonicalBasePath: normalizeBasePath(canonicalBasePath),
+    aliases: aliases.map((alias) => normalizeBasePath(alias)),
+    runtimeScoped: true,
+  };
+}
+
+function readErrorDetail(value: unknown): string | null {
+  if (!isObject(value)) return null;
+  const error = value["error"];
+  if (typeof error === "string" && error.trim() !== "") return error;
+  const message = value["message"];
+  return typeof message === "string" && message.trim() !== "" ? message : null;
+}
+
+async function readJson(response: Response): Promise<unknown | null> {
+  try {
+    const value: unknown = await response.json();
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+async function requestAliases(
+  endpoint: string,
+  action: AliasAction,
+  fetchImpl: AliasFetch,
+): Promise<AliasRequestResult> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort();
+  }, REQUEST_TIMEOUT_MS);
+  const method = action.kind === "list" ? "GET" : action.kind === "add" ? "POST" : "DELETE";
+  const basePath = action.kind === "list" ? null : action.basePath;
+  const init: RequestInit = {
+    method,
+    headers:
+      action.kind === "list"
+        ? { accept: "application/json" }
+        : {
+            accept: "application/json",
+            "content-type": "application/json",
+            "x-agent-inspector-csrf": "1",
+          },
+    signal: controller.signal,
+  };
+  if (basePath !== null) init.body = JSON.stringify({ basePath });
+
+  try {
+    const response = await fetchImpl(endpoint, init);
+    const value = await readJson(response);
+    if (!response.ok) {
+      return { kind: "http-error", status: response.status, detail: readErrorDetail(value) };
+    }
+    const snapshot = parseAliasSnapshot(value);
+    return snapshot === null ? { kind: "invalid-response" } : { kind: "success", snapshot };
+  } catch (error) {
+    const timedOut =
+      controller.signal.aborted || (error instanceof Error && error.name === "AbortError");
+    return { kind: "network-error", timedOut };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function displayBasePath(basePath: string): string {
+  const normalized = normalizeBasePath(basePath);
+  return normalized === "" ? "/" : normalized;
+}
+
+function fullUrl(origin: string, basePath: string): string {
+  return `${origin}${normalizeBasePath(basePath)}`;
+}
+
+function buildOutput(origin: string, action: AliasAction, snapshot: AliasSnapshot): AliasOutput {
+  return {
+    action: action.kind,
+    canonicalBasePath: displayBasePath(snapshot.canonicalBasePath),
+    canonicalUrl: fullUrl(origin, snapshot.canonicalBasePath),
+    aliases: snapshot.aliases.map(displayBasePath),
+    aliasUrls: snapshot.aliases.map((alias) => fullUrl(origin, alias)),
+    runtimeScoped: true,
+  };
+}
+
+function formatHumanOutput(output: AliasOutput): string {
+  const heading =
+    output.action === "add"
+      ? "Base-path alias added."
+      : output.action === "remove"
+        ? "Base-path alias removed."
+        : "Base-path aliases for the running runtime:";
+  const aliasPaths = output.aliases.length === 0 ? "(none)" : output.aliases.join(", ");
+  const aliasUrls =
+    output.aliasUrls.length === 0
+      ? "  (none)"
+      : output.aliasUrls.map((url) => `  - ${url}`).join("\n");
+  return `${heading}
+Canonical base path: ${output.canonicalBasePath}
+Canonical URL: ${output.canonicalUrl}
+Alias base paths: ${aliasPaths}
+Alias URLs:
+${aliasUrls}
+Scope: current runtime only; no second runtime was started and aliases are not persisted.
+`;
+}
+
+function writeError(io: AliasIo, json: boolean, code: string, message: string): void {
+  if (json) {
+    io.stderr(`${JSON.stringify({ error: code, message, runtimeStarted: false })}\n`);
+    return;
+  }
+  io.stderr(`agent-inspector alias: ${message}\n`);
+}
+
+function oldRuntimeMessage(origin: string): string {
+  return `the runtime at ${origin} does not support base-path aliases. Upgrade Agent Inspector and restart that instance, then retry; this command did not start a runtime.`;
+}
+
+async function handleHttpError(
+  options: AliasOptions,
+  endpoint: string,
+  origin: string,
+  result: Extract<AliasRequestResult, { kind: "http-error" }>,
+  fetchImpl: AliasFetch,
+  io: AliasIo,
+): Promise<number> {
+  if (result.status === 404 && options.action.kind === "remove") {
+    const probe = await requestAliases(endpoint, { kind: "list" }, fetchImpl);
+    if (probe.kind === "success") {
+      writeError(
+        io,
+        options.json,
+        "alias_not_found",
+        `base path ${displayBasePath(options.action.basePath)} is not mounted. Run "agent-inspector alias list --host ${options.host} --port ${options.port}" to inspect the current runtime.`,
+      );
+      return 1;
+    }
+    if (probe.kind === "network-error") {
+      writeError(
+        io,
+        options.json,
+        probe.timedOut ? "request_timeout" : "runtime_unreachable",
+        `${probe.timedOut ? "timed out contacting" : "cannot reach"} ${origin}. Confirm the existing runtime is running and the --host/--port values are correct; no runtime was started.`,
+      );
+      return 1;
+    }
+    if (probe.kind === "http-error" && (probe.status === 404 || probe.status === 405)) {
+      writeError(io, options.json, "unsupported_runtime", oldRuntimeMessage(origin));
+      return 1;
+    }
+  }
+
+  if (result.status === 404 || result.status === 405) {
+    writeError(io, options.json, "unsupported_runtime", oldRuntimeMessage(origin));
+    return 1;
+  }
+  if (result.status === 409) {
+    writeError(
+      io,
+      options.json,
+      "alias_conflict",
+      `${result.detail ?? "the base path is already mounted or conflicts with another mount"}. Run "agent-inspector alias list --host ${options.host} --port ${options.port}" to inspect the current runtime.`,
+    );
+    return 1;
+  }
+
+  const detail = result.detail === null ? "the runtime rejected the request" : result.detail;
+  writeError(
+    io,
+    options.json,
+    "runtime_rejected_request",
+    `${detail} (HTTP ${result.status}). Check the running instance and retry; no runtime was started.`,
+  );
+  return 1;
+}
+
+export async function runAlias(
+  argv: readonly string[],
+  fetchImpl: AliasFetch = fetch,
+  io: AliasIo = processIo,
+): Promise<number> {
+  const parsed = parseAliasArgs(argv);
+  if (parsed.kind === "help") {
+    io.stdout(aliasHelp());
+    return 0;
+  }
+  if (parsed.kind === "error") {
+    io.stderr(`${parsed.message}\n\n${aliasHelp()}`);
+    return 2;
+  }
+
+  const { options } = parsed;
+  const origin = `http://${formatHostForUrl(options.host)}:${options.port}`;
+  const endpoint = `${origin}${ALIAS_CONTROL_PATH}`;
+  const result = await requestAliases(endpoint, options.action, fetchImpl);
+  switch (result.kind) {
+    case "success": {
+      const output = buildOutput(origin, options.action, result.snapshot);
+      io.stdout(options.json ? `${JSON.stringify(output, null, 2)}\n` : formatHumanOutput(output));
+      return 0;
+    }
+    case "network-error":
+      writeError(
+        io,
+        options.json,
+        result.timedOut ? "request_timeout" : "runtime_unreachable",
+        `${result.timedOut ? "timed out contacting" : "cannot reach"} ${origin}. Confirm the existing runtime is running and the --host/--port values are correct; no runtime was started.`,
+      );
+      return 1;
+    case "invalid-response":
+      writeError(
+        io,
+        options.json,
+        "invalid_runtime_response",
+        `the runtime at ${origin} returned an invalid alias response. Upgrade and restart that instance, then retry; no runtime was started.`,
+      );
+      return 1;
+    case "http-error":
+      return handleHttpError(options, endpoint, origin, result, fetchImpl, io);
+  }
+}