pikasTech-HWLAB/tools/src/device-pod-cli-lib.ts

import { request as httpRequest } from "node:http";
import { request as httpsRequest } from "node:https";
import { readFile } from "node:fs/promises";
import path from "node:path";

import { resolveRuntimeEndpoint, runtimeEndpointVisibility, sameRuntimeEndpointScope } from "./runtime-endpoint-resolver.ts";

const VERSION = "0.2.0-rest";
const CLI_NAME = "device-pod-cli";
const DEFAULT_TIMEOUT_MS = 30000;
const BOOLEAN_OPTIONS = new Set(["dryRun", "full", "help", "h"]);

type FetchLike = typeof fetch;
type EnvLike = Record<string, string | undefined>;
type ParsedArgs = Record<string, unknown> & { _: string[] };

export async function main(argv = process.argv.slice(2), options: { env?: EnvLike; fetchImpl?: FetchLike; stdinText?: string; now?: () => string } = {}) {
  const result = await runDevicePodCli(argv, options);
  console.log(JSON.stringify(result.payload, null, 2));
  process.exitCode = result.exitCode;
}

export async function runDevicePodCli(argv: string[], options: { env?: EnvLike; fetchImpl?: FetchLike; stdinText?: string; now?: () => string } = {}) {
  const env = options.env ?? process.env;
  const fetchImpl = options.fetchImpl;
  const now = options.now ?? (() => new Date().toISOString());
  try {
    const parsed = parseOptions(argv);
    const target = parsed._[0] || "help";
    const rest = parsed._.slice(1);
    const context = { parsed, rest, env, fetchImpl, stdinText: options.stdinText, now };
    const payload = await dispatch(target, context);
    return { exitCode: payload.ok === false ? 1 : 0, payload: withMeta(payload, now) };
  } catch (error) {
    return { exitCode: 1, payload: withMeta(failure("device-pod-cli", error), now) };
  }
}

async function dispatch(target: string, context: any) {
  if (["help", "--help", "-h"].includes(target)) return help();
  if (target === "setup") return setupCommand(context);
  if (target === "admin") return adminCommand(context);
  if (target === "login") return login(context);
  if (target === "doctor") return doctor(context);
  if (target === "health") return health(context);
  if (target === "bootsharp") return bootsharpCommand(context);
  if (target === "profile") return profileCommand(context);
  if (target === "lease" || target === "leases") return removedStandaloneLeaseCommand();
  if (target === "job" || target === "jobs") return jobCommand(context);
  const selector = parseSelector(target);
  if (!selector) throw cliError("invalid_target_selector", `invalid target selector: ${target}`);
  return invokeSelector(selector, context);
}

function help() {
  return ok("help", {
    version: VERSION,
    contractVersion: "device-pod-rest-cli-v1",
    profileAuthority: "hwlab-cloud-api",
    localProfileAuthority: false,
    configuration: {
      apiBaseUrl: "auto-located from assembled HWLAB_RUNTIME_* / HWLAB_DEVICE_POD_* env; manual endpoint arguments are rejected when HWLAB_RUNTIME_ENDPOINT_LOCKED=1",
      auth: "assembled HWLAB_DEVICE_POD_API_KEY for AgentRun; browser cookie or explicit user session for local debug"
    },
    usage: [
      "hwpod profile list",
      "hwpod profile show --pod-id device-pod-71-freq",
      "hwpod bootsharp --pod-id D601-F103-V2",
      "hwpod D601-F103-V2:workspace:/ bootsharp",
      "hwpod device-pod-71-freq:workspace:/ ls",
      "hwpod device-pod-71-freq:workspace:/ put User/new.c --reason TEXT < file",
      "hwpod device-pod-71-freq:workspace:/ rmdir User/empty --reason TEXT",
      "hwpod device-pod-71-freq:workspace:/ keil add-source User/new.c --group User --reason TEXT",
      "hwpod device-pod-71-freq:workspace:/ build start --reason TEXT",
      "hwpod device-pod-71-freq:workspace:/ build evidence [jobId] [--tail N] [--full]",
      "hwpod device-pod-71-freq:debug-probe download evidence [jobId] [--tail N] [--full]",
      "hwpod device-pod-71-freq:io-probe:/uart/1 jsonrpc gpio.read --params-json '{\"pin\":\"PB5\"}' --reason TEXT",
      "hwpod job output --pod-id device-pod-71-freq <jobId>"
    ],
    startupProbe: "Run bootsharp first after selecting a Device Pod or resuming context; it returns workspace tree and AGENTS.md hints through the formal REST job path.",
    selectorCheatSheet: [
      "workspace:  ls | cat | rg | bootsharp | apply-patch | put | rm | rmdir | keil {add-source,remove-source} | build {start,status,output,cancel,wait,evidence}",
      "debug-probe: status | chip-id | download {start,status,output,cancel,wait,evidence} | reset    (no flash op; firmware flash = download)",
      "evidence:    <pod>:workspace:/ build evidence [jobId] and <pod>:debug-probe download evidence [jobId] are read-only; no --reason; tail defaults to 200 lines, --full for entire log",
      "io-probe:    ports | read | write | jsonrpc | read-after-launch-flash    (path = /uart/<n>)",
      "common mistakes: workspace keil download/flash and debug-probe flash are not SOP; use <pod>:debug-probe download start; build status/output/wait/cancel/evidence do NOT need --reason (read-only)",
      "full table: skills/device-pod-cli/SKILL.md Selector Cheat Sheet"
    ]
  });
}

async function setupCommand({ parsed, rest, env, fetchImpl }: any) {
  const subcommand = rest[0] || "first-admin";
  if (subcommand !== "first-admin") throw cliError("unsupported_setup_command", `unsupported setup command: ${subcommand}`);
  const devicePod = devicePodSeedFromOptions(parsed, { required: false });
  const body = clean({
    username: requiredOption(parsed, env, "username", "HWLAB_USERNAME"),
    password: requiredOption(parsed, env, "password", "HWLAB_PASSWORD"),
    displayName: text(parsed.displayName),
    ...(devicePod ? { devicePod } : {})
  });
  const response = await requestJson({ parsed, env, fetchImpl, method: "POST", path: "/v1/setup/first-admin", body, auth: false });
  return responsePayload("setup.first-admin", response, { setCookie: response.headers.get("set-cookie") ?? null, devicePodSeedProvided: Boolean(devicePod), localProfileAuthority: false });
}

async function adminCommand(context: any) {
  const subcommand = context.rest[0] || "help";
  if (subcommand === "device-pod" || subcommand === "profile") return adminDevicePodCommand({ ...context, rest: context.rest.slice(1) });
  if (subcommand === "grant" || subcommand === "device-pod-grant") return adminGrantCommand({ ...context, rest: context.rest.slice(1) });
  throw cliError("unsupported_admin_command", `unsupported admin command: ${subcommand}`);
}

async function adminDevicePodCommand({ parsed, rest, env, fetchImpl }: any) {
  const subcommand = rest[0] || "upsert";
  if (!["create", "upsert", "update", "put"].includes(subcommand)) throw cliError("unsupported_admin_device_pod_command", `unsupported admin device-pod command: ${subcommand}`);
  const devicePod = devicePodSeedFromOptions(parsed, { required: true });
  const method = subcommand === "update" || subcommand === "put" ? "PUT" : "POST";
  const path = method === "PUT" ? `/v1/admin/device-pods/${encodeURIComponent(devicePod.devicePodId)}` : "/v1/admin/device-pods";
  const response = await requestJson({ parsed, env, fetchImpl, method, path, body: devicePod });
  return responsePayload(`admin.device-pod.${subcommand}`, response, { route: { method, path }, devicePodId: devicePod.devicePodId, localProfileAuthority: false });
}

async function adminGrantCommand({ parsed, rest, env, fetchImpl }: any) {
  const podId = requiredText(parsed.podId ?? parsed.devicePodId ?? rest[0], "podId");
  const userId = requiredText(parsed.userId ?? rest[1], "userId");
  const body = { devicePodId: podId, userId };
  const response = await requestJson({ parsed, env, fetchImpl, method: "POST", path: "/v1/admin/device-pod-grants", body });
  return responsePayload("admin.device-pod-grant", response, { devicePodId: podId, userId });
}

async function login({ parsed, env, fetchImpl }: any) {
  const response = await requestJson({ parsed, env, fetchImpl, method: "POST", path: "/auth/login", body: { username: requiredOption(parsed, env, "username", "HWLAB_USERNAME"), password: requiredOption(parsed, env, "password", "HWLAB_PASSWORD") }, auth: false });
  return responsePayload("login", response, { setCookie: response.headers.get("set-cookie") ?? null });
}

async function doctor({ parsed, env, fetchImpl }: any) {
  const podId = text(parsed.podId ?? parsed._[1]);
  const probes = [];
  for (const path of ["/v1/access/status", "/auth/session", "/v1/device-pods", podId ? `/v1/device-pods/${encodeURIComponent(podId)}/status` : ""].filter(Boolean)) {
    try {
      const response = await requestJson({ parsed, env, fetchImpl, method: "GET", path });
      probes.push({ path, httpStatus: response.status, ok: response.status < 400, body: compactBody(response.body) });
    } catch (error) {
      probes.push({ path, ok: false, blocker: errorSummary(error) });
    }
  }
  const hardFailed = probes.some((probe) => probe.ok === false && Number(probe.httpStatus ?? 0) >= 500);
  return ok("doctor", { status: hardFailed ? "degraded" : "succeeded", profileAuthority: "hwlab-cloud-api", localProfileAuthority: false, localProfileRead: false, devicePodId: podId || null, probes }, hardFailed ? "degraded" : "succeeded");
}

async function health({ parsed, rest, env, fetchImpl }: any) {
  const podId = text(parsed.podId ?? rest[0]);
  const path = podId ? `/v1/device-pods/${encodeURIComponent(podId)}/status` : "/health/live";
  const response = await requestJson({ parsed, env, fetchImpl, method: "GET", path, auth: Boolean(podId) });
  return responsePayload("health", response, { route: { method: "GET", path }, devicePodId: podId || null, localProfileAuthority: false });
}

async function bootsharpCommand(context: any) {
  const podId = requiredText(context.parsed.podId ?? context.rest[0], "podId");
  const path = text(context.parsed.path ?? context.rest[1] ?? "/") || "/";
  const selector = { podId, surface: "workspace", path };
  return invokeSelector(selector, { ...context, rest: ["bootsharp"] });
}

async function profileCommand({ parsed, rest, env, fetchImpl }: any) {
  const subcommand = rest[0] || "list";
  if (subcommand === "create") {
    throw cliError("legacy_profile_create_removed", "local device-pod profile creation is removed from v0.2 formal mode; use cloud-api admin device-pod APIs", { next: ["POST /v1/admin/device-pods", "POST /v1/admin/device-pod-grants"] });
  }
  if (subcommand === "list") {
    const response = await requestJson({ parsed, env, fetchImpl, method: "GET", path: "/v1/device-pods" });
    return responsePayload("profile.list", response, { localProfileAuthority: false, localProfileRead: false });
  }
  if (subcommand === "show") {
    const podId = requiredText(parsed.podId ?? rest[1], "podId");
    const path = `/v1/device-pods/${encodeURIComponent(podId)}/status`;
    const response = await requestJson({ parsed, env, fetchImpl, method: "GET", path });
    return responsePayload("profile.show", response, { route: { method: "GET", path }, devicePodId: podId, localProfileAuthority: false, localProfileRead: false });
  }
  throw cliError("unsupported_profile_command", `unsupported profile command: ${subcommand}`);
}

function removedStandaloneLeaseCommand() {
  throw cliError(
    "standalone_lease_command_removed",
    "standalone hwpod lease commands are not part of the v0.2 standard path; send named Device Pod jobs through cloud-api with --reason and, only when cloud-api requires it, --lease-token",
    {
      next: [
        "Run hwpod bootsharp --pod-id <devicePodId> before operating a pod.",
        "Run the actual Device Pod job, for example hwpod <devicePodId>:workspace:/ build start --reason TEXT.",
        "Do not call hwpod lease acquire/current/release or switch to a generic gateway shell."
      ]
    }
  );
}

async function jobCommand({ parsed, rest, env, fetchImpl }: any) {
  const subcommand = rest[0] || "status";
  const podId = requiredText(parsed.podId, "podId");
  const jobId = requiredText(rest[1] ?? parsed.jobId, "jobId");
  const suffix = subcommand === "output" ? "/output" : subcommand === "cancel" ? "/cancel" : "";
  const method = subcommand === "cancel" ? "POST" : "GET";
  const path = `/v1/device-pods/${encodeURIComponent(podId)}/jobs/${encodeURIComponent(jobId)}${suffix}`;
  const response = await requestJson({ parsed, env, fetchImpl, method, path });
  return responsePayload(`job.${subcommand}`, response, { route: { method, path }, devicePodId: podId, jobId, compactKind: subcommand === "output" ? "device-job-output" : null }, parsed);
}

async function invokeSelector(selector: any, context: any) {
  const { parsed, rest } = context;
  const operation = rest[0] || defaultOperation(selector.surface);
  const jobRoute = jobRouteFromSelector(selector, operation, rest, parsed);
  if (jobRoute) return jobCommand({ ...context, parsed: { ...parsed, podId: selector.podId }, rest: jobRoute });
  if (selector.surface === "debug-probe" && operation === "status") return probeGet("debug.status", selector, "/status", context);
  const job = await buildJob(selector, operation, rest, parsed, context.stdinText);
  if (parsed.dryRun === true) return ok("device-pod.plan", { route: { method: "POST", path: `/v1/device-pods/${encodeURIComponent(selector.podId)}/jobs` }, request: redactJobRequest(job), selector, localProfileAuthority: false, localProfileRead: false });
  const response = await requestJson({ parsed, env: context.env, fetchImpl: context.fetchImpl, method: "POST", path: `/v1/device-pods/${encodeURIComponent(selector.podId)}/jobs`, body: job });
  return responsePayload("device-pod.invoke", response, { selector, intent: job.intent, mutating: MUTATING_INTENTS.has(job.intent), localProfileAuthority: false, localProfileRead: false });
}

async function probeGet(action: string, selector: any, suffix: string, { parsed, env, fetchImpl }: any) {
  const path = `/v1/device-pods/${encodeURIComponent(selector.podId)}${suffix}`;
  const response = await requestJson({ parsed, env, fetchImpl, method: "GET", path });
  return responsePayload(action, response, { route: { method: "GET", path }, selector, localProfileAuthority: false });
}

async function buildJob(selector: any, operation: string, rest: string[], parsed: ParsedArgs, stdinText?: string) {
  const args = clean({});
  let intent = "";
  if (selector.surface === "workspace") {
    const basePath = selector.path || ".";
    if (operation === "bootsharp") {
      intent = "workspace.bootsharp";
      args.path = joinPath(basePath, rest[1] || "");
      Object.assign(args, passthroughOptions(parsed, ["depth", "limit", "agentsLimit"]));
    }
    else if (operation === "ls") {
      intent = "workspace.ls";
      args.path = joinPath(basePath, rest[1] || "");
    }
    else if (operation === "cat") {
      intent = "workspace.cat";
      args.path = joinPath(basePath, rest[1] || "");
      args.maxBytes = numberOption(parsed.maxBytes ?? parsed.limit);
    }
    else if (operation === "rg") {
      intent = "workspace.rg";
      args.pattern = workspaceRgPattern(parsed, rest[1]);
      args.path = joinPath(basePath, text(parsed.path) || rest[2] || "");
      Object.assign(args, passthroughOptions(parsed, [
        "glob",
        "g",
        "filesWithMatches",
        "l",
        "ignoreCase",
        "i",
        "maxCount"
      ]));
    }
    else if (operation === "put") {
      intent = "workspace.put";
      args.path = joinPath(basePath, requiredText(rest[1] ?? parsed.path, "path"));
      Object.assign(
        args,
        await contentPayload(parsed, stdinText),
        passthroughOptions(parsed, ["encoding", "charset", "createOnly", "createDirs", "updateOnly"])
      );
    }
    else if (operation === "rm") {
      intent = "workspace.rm";
      args.path = joinPath(basePath, requiredText(rest[1] ?? parsed.path, "path"));
      Object.assign(args, passthroughOptions(parsed, ["missingOk"]));
    }
    else if (operation === "rmdir") {
      intent = "workspace.rmdir";
      args.path = joinPath(basePath, requiredText(rest[1] ?? parsed.path, "path"));
    }
    else if (operation === "keil") {
      const keilAction = String(rest[1] ?? "").trim();
      if (keilAction && !["add-source", "remove-source"].includes(keilAction)) {
        throw cliError(
          "unsupported_workspace_keil_action",
          `unsupported workspace.keil action: ${keilAction}. workspace.keil only supports add-source and remove-source (Keil project-file maintenance). Firmware flashing goes through "<devicePodId>:debug-probe download start"; see SKILL.md Selector Cheat Sheet.`,
          { gotAction: keilAction, allowed: ["add-source", "remove-source"], hint: "<devicePodId>:debug-probe download start --reason <text>" }
        );
      }
      intent = "workspace.keil";
      args.action = requiredText(rest[1], "keil action");
      args.base = basePath;
      args.path = text(rest[2] ?? parsed.path ?? parsed.source ?? parsed.file ?? parsed.src);
      Object.assign(args, passthroughOptions(parsed, ["group", "groupName", "target", "timeoutMs"]));
    }
    else if (operation === "apply-patch") {
      intent = "workspace.apply-patch";
      args.base = joinPath(basePath, rest[1] || "");
      args.patch = await patchText(parsed, stdinText);
      Object.assign(args, passthroughOptions(parsed, ["encoding", "charset", "createDirs"]));
    }
    else if (operation === "build") {
      if (text(rest[1]) === "evidence") {
        intent = "workspace.evidence";
        args.kind = "build";
        args.jobId = text(rest[2] ?? parsed.jobId);
        Object.assign(args, passthroughOptions(parsed, ["tail", "full", "target"]));
      } else {
        intent = "workspace.build";
        args.action = rest[1] || "start";
        if (["status", "wait"].includes(String(args.action))) args.jobId = text(rest[2] ?? parsed.jobId);
        Object.assign(args, passthroughOptions(parsed, ["target", "timeoutMs", "clean", "dryRun"]));
      }
    }
    else throw cliError("unsupported_workspace_operation", `unsupported workspace operation: ${operation}`);
  } else if (selector.surface === "debug-probe") {
    if (operation === "chip-id") intent = "debug.chip-id";
    else if (operation === "flash") {
      throw cliError(
        "unsupported_debug_operation",
        `unsupported debug-probe operation: flash. The correct selector for firmware flashing is "<devicePodId>:debug-probe download start". Allowed debug-probe operations: status, chip-id, download, reset; see SKILL.md Selector Cheat Sheet.`,
        { gotOperation: operation, allowed: ["status", "chip-id", "download", "reset"], hint: "<devicePodId>:debug-probe download start --reason <text>" }
      );
    }
    else if (operation === "download") {
      if (text(rest[1]) === "evidence") {
        intent = "debug.evidence";
        args.kind = "download";
        args.jobId = text(rest[2] ?? parsed.jobId);
        Object.assign(args, passthroughOptions(parsed, ["tail", "full", "target"]));
      } else {
        intent = "debug.download";
        args.action = rest[1] || "start";
        if (["status", "wait"].includes(String(args.action))) args.jobId = text(rest[2] ?? parsed.jobId);
        Object.assign(args, passthroughOptions(parsed, [
          "target",
          "timeoutMs",
          "captureUart",
          "captureDurationMs",
          "durationMs",
          "port",
          "baudRate"
        ]));
      }
    }
    else if (operation === "reset") intent = "debug.reset";
    else throw cliError(
      "unsupported_debug_operation",
      `unsupported debug-probe operation: ${operation}. Allowed debug-probe operations: status, chip-id, download, reset; see SKILL.md Selector Cheat Sheet.`,
      { gotOperation: operation, allowed: ["status", "chip-id", "download", "reset"] }
    );
  } else if (selector.surface === "io-probe") {
    const uartId = normalizeProbePath(selector.path || "uart/1");
    if (operation === "ports") { intent = "io.ports"; args.uartId = uartId; }
    else if (operation === "read") {
      intent = "io.uart.read";
      args.uartId = uartId;
      Object.assign(args, passthroughOptions(parsed, ["durationMs", "port", "baudRate"]));
    }
    else if (operation === "read-after-launch-flash") {
      intent = "io.uart.read-after-launch-flash";
      args.uartId = uartId;
      Object.assign(args, passthroughOptions(parsed, [
        "durationMs",
        "port",
        "baudRate",
        "flashBase",
        "skipHardwareReset",
        "connectMode",
        "timeoutMs"
      ]));
    }
    else if (operation === "write") {
      intent = "io.uart.write";
      args.uartId = uartId;
      args.message = text(rest[1] ?? parsed.message ?? parsed.text ?? parsed.data);
      args.hex = parsed.hex === true;
      Object.assign(args, passthroughOptions(parsed, ["port", "baudRate"]));
    }
    else if (operation === "jsonrpc") {
      intent = "io.uart.jsonrpc";
      args.uartId = uartId;
      args.method = text(rest[1] ?? parsed.method);
      Object.assign(args, jsonRpcArgs(parsed), passthroughOptions(parsed, uartJsonRpcOptionKeys));
    }
    else throw cliError("unsupported_io_operation", `unsupported io-probe operation: ${operation}`);
  }
  return clean({ intent, args: clean(args), reason: text(parsed.reason) });
}

function jobRouteFromSelector(selector: any, operation: string, rest: string[], parsed: ParsedArgs) {
  if (selector.surface === "workspace" && (operation === "status" || operation === "output" || operation === "cancel")) return [operation, requiredText(rest[1] ?? parsed.jobId, "jobId")];
  if (selector.surface === "workspace" && operation === "build" && isSelectorCloudJobAlias(rest[1], rest[2] ?? parsed.jobId)) return [String(rest[1]), requiredText(rest[2] ?? parsed.jobId, "jobId")];
  if (selector.surface === "debug-probe" && operation === "download" && isSelectorCloudJobAlias(rest[1], rest[2] ?? parsed.jobId)) return [String(rest[1]), requiredText(rest[2] ?? parsed.jobId, "jobId")];
  return null;
}

function isSelectorCloudJobAlias(subcommand: unknown, candidateJobId: unknown) {
  const subcommandText = String(subcommand ?? "");
  if (!["status", "output", "cancel"].includes(subcommandText)) return false;
  if (subcommandText === "output" || subcommandText === "cancel") return true;
  return /^job(?:_|-)/u.test(text(candidateJobId));
}

function workspaceRgPattern(parsed: ParsedArgs, positional: unknown) {
  const encoded = text(parsed.patternB64);
  if (encoded) return Buffer.from(encoded, "base64").toString("utf8");
  return requiredText(parsed.pattern ?? parsed.query ?? positional, "pattern");
}

async function requestJson({ parsed, env, fetchImpl, method, path, body, auth = true, extraHeaders = {} }: any) {
  const endpoint = resolveRuntimeEndpoint({ kind: "api", parsed, env });
  const baseUrl = endpoint.baseUrl;
  const url = `${baseUrl}${path}`;
  const authHeaderValues = auth ? await authHeaders(parsed, env, endpoint) : {};
  const requestBody = body ? JSON.stringify(body) : undefined;
  const headers = clean({
    accept: "application/json",
    ...(requestBody ? { "content-type": "application/json", "content-length": Buffer.byteLength(requestBody) } : {}),
    ...authHeaderValues,
    ...extraHeaders
  });
  const timeoutMs = numberOption(parsed.timeoutMs) ?? DEFAULT_TIMEOUT_MS;
  if (fetchImpl) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), timeoutMs);
    try {
      const response = await fetchImpl(`${baseUrl}${path}`, {
        method,
        headers,
        body: requestBody,
        signal: controller.signal
      });
      const textBody = await response.text();
      return { status: response.status, headers: response.headers, body: parseJson(textBody), url, method, path, runtimeEndpoint: endpoint };
    } finally {
      clearTimeout(timeout);
    }
  }
  return requestJsonWithNodeHttp({ url, method, path, headers, body: requestBody, timeoutMs, runtimeEndpoint: endpoint });
}

function requestJsonWithNodeHttp({ url, method, path, headers, body, timeoutMs, runtimeEndpoint }: any): Promise<any> {
  return new Promise((resolve, reject) => {
    const target = new URL(url);
    const requestImpl = target.protocol === "https:" ? httpsRequest : httpRequest;
    const request = requestImpl(target, { method, headers: nodeHttpHeaders(headers) }, (response) => {
      const chunks: Buffer[] = [];
      response.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
      response.on("end", () => {
        const textBody = Buffer.concat(chunks).toString("utf8");
        resolve({
          status: response.statusCode ?? 0,
          headers: nodeResponseHeaders(response.headers),
          body: parseJson(textBody),
          url,
          method,
          path,
          runtimeEndpoint
        });
      });
    });
    request.setTimeout(timeoutMs, () => request.destroy(cliError("request_timeout", `request timed out after ${timeoutMs}ms`)));
    request.on("error", reject);
    if (body) request.write(body);
    request.end();
  });
}

function nodeHttpHeaders(headers: Record<string, unknown>) {
  const out: Record<string, string> = {};
  for (const [key, value] of Object.entries(headers)) {
    if (value === undefined || value === null) continue;
    out[key] = String(value);
  }
  return out;
}

function nodeResponseHeaders(headers: Record<string, unknown>) {
  return {
    get(name: string) {
      const value = headers[String(name || "").toLowerCase()];
      if (Array.isArray(value)) return value.join("; ");
      return value === undefined || value === null ? null : String(value);
    }
  };
}

function parseOptions(argv: string[]): ParsedArgs {
  const out: ParsedArgs = { _: [] };
  for (let i = 0; i < argv.length; i += 1) {
    const item = argv[i] ?? "";
    if (/^-[A-Za-z]$/u.test(item)) {
      const key = item.slice(1);
      const next = argv[i + 1];
      if (next && !next.startsWith("-")) { setOption(out, key, next); i += 1; }
      else setOption(out, key, true);
      continue;
    }
    if (!item.startsWith("--")) { out._.push(item); continue; }
    const eq = item.indexOf("=");
    const rawKey = eq >= 0 ? item.slice(2, eq) : item.slice(2);
    const key = rawKey.replace(/-([a-z])/gu, (_, c) => String(c).toUpperCase());
    if (eq >= 0) { setOption(out, key, item.slice(eq + 1)); continue; }
    if (BOOLEAN_OPTIONS.has(key)) { setOption(out, key, true); continue; }
    const next = argv[i + 1];
    if (next && !next.startsWith("--")) { setOption(out, key, next); i += 1; }
    else setOption(out, key, true);
  }
  return out;
}

function setOption(out: ParsedArgs, key: string, value: unknown) {
  if (out[key] === undefined) out[key] = value;
  else if (Array.isArray(out[key])) (out[key] as unknown[]).push(value);
  else out[key] = [out[key], value];
}

function parseSelector(raw: string) {
  const match = raw.match(/^([^:]+):(workspace|debug-probe|io-probe)(?::(.*))?$/u);
  return match ? { podId: match[1], surface: match[2], path: match[2] === "io-probe" ? normalizeProbePath(match[3] || "") : normalizePath(match[3] || ".") } : null;
}

function passthroughOptions(parsed: ParsedArgs, keys: string[]) {
  const out: Record<string, unknown> = {};
  for (const key of keys) {
    const value = parsed[key];
    if (value === undefined || value === false || value === "") continue;
    out[key] = typeof value === "string" && /^\d+$/u.test(value) ? Number.parseInt(value, 10) : value;
  }
  return out;
}

const MUTATING_INTENTS = new Set([
  "workspace.apply-patch",
  "workspace.build",
  "workspace.put",
  "workspace.rm",
  "workspace.rmdir",
  "workspace.keil",
  "debug.download",
  "debug.reset",
  "io.uart.read-after-launch-flash",
  "io.uart.write",
  "io.uart.jsonrpc"
]);
const uartJsonRpcOptionKeys = [
  "id",
  "request",
  "requestB64",
  "params",
  "paramsB64",
  "responseTimeoutMs",
  "durationMs",
  "retry",
  "retries",
  "retryDelayMs",
  "lineEnding",
  "noNewline",
  "lineDelimited",
  "discardBefore",
  "requireResponse",
  "requireJson",
  "requireJsonrpc",
  "requireJsonrpcResult",
  "allowIdMismatch",
  "port",
  "baudRate"
];
function defaultOperation(surface: string) { return surface === "workspace" ? "ls" : surface === "debug-probe" ? "status" : "read"; }
async function authHeaders(parsed: ParsedArgs, env: EnvLike, endpoint: any) {
  const apiKey = text(parsed.devicePodApiKey ?? env.HWLAB_DEVICE_POD_API_KEY);
  const explicitCookie = text(parsed.cookie ?? env.HWLAB_SESSION_COOKIE);
  const sessionToken = text(parsed.sessionToken ?? env.HWLAB_CLOUD_API_SESSION_TOKEN ?? env.HWLAB_SESSION_TOKEN);
  const bearer = text(parsed.bearerToken ?? env.HWLAB_BEARER_TOKEN);
  const stateCookie = !apiKey && !explicitCookie && !sessionToken && !bearer ? await savedHwlabCliCookie(parsed, env, endpoint) : "";
  const cookie = explicitCookie || stateCookie;
  return clean({
    ...(apiKey ? { "x-hwlab-device-pod-api-key": apiKey } : {}),
    ...(cookie ? { cookie: cookie.includes("=") ? cookie : `hwlab_session=${encodeURIComponent(cookie)}` } : {}),
    ...(sessionToken ? { "x-hwlab-session-token": sessionToken } : {}),
    ...(bearer ? { authorization: `Bearer ${bearer}` } : {})
  });
}

async function savedHwlabCliCookie(parsed: ParsedArgs, env: EnvLike, endpoint: any) {
  const file = hwlabCliSessionFile(parsed, env);
  let stored: any;
  try {
    stored = JSON.parse(await readFile(file, "utf8"));
  } catch {
    return "";
  }
  const cookie = text(stored?.cookie);
  const storedBaseUrl = text(stored?.baseUrl);
  if (!cookie || !storedBaseUrl) return "";
  return storedBaseUrl === endpoint?.baseUrl || sameRuntimeEndpointScope(storedBaseUrl, endpoint?.baseUrl) ? cookie : "";
}

function hwlabCliSessionFile(parsed: ParsedArgs, env: EnvLike) {
  const explicit = text(parsed.stateFile ?? env.HWLAB_CLI_STATE_FILE ?? env.HWLAB_SESSION_STATE_FILE);
  return path.resolve(process.cwd(), explicit || ".state/hwlab-cli/session.json");
}
function responsePayload(action: string, response: any, extra: Record<string, unknown> = {}, parsed: ParsedArgs = { _: [] }) {
  const success = response.status >= 200 && response.status < 300 && response.body?.ok !== false;
  const full = parsed.full === true;
  const compactKind = text(extra.compactKind);
  const cleanExtra = { ...extra };
  delete cleanExtra.compactKind;
  const body = !full && compactKind === "device-job-output" ? compactJobOutputBody(response.body) : response.body;
  return {
    ok: success,
    action,
    status: success ? "succeeded" : "failed",
    apiBaseUrl: response.runtimeEndpoint?.baseUrl,
    runtimeEndpoint: runtimeEndpointVisibility(response.runtimeEndpoint),
    httpStatus: response.status,
    request: pruneUndefined({ method: response.method, path: response.path, url: response.url }),
    ...cleanExtra,
    body,
    ...(full ? { full: true } : {})
  };
}
function withMeta(payload: any, now: () => string) { return { generatedAt: now(), cli: CLI_NAME, version: VERSION, ...payload }; }
function ok(action: string, data: Record<string, unknown> = {}, status = "succeeded") { return { ok: true, action, status, ...data }; }
function failure(action: string, error: any) {
  const summary = errorSummary(error);
  return {
    ok: false,
    action,
    status: "failed",
    error: summary,
    ...patchHintForText(summary.message),
    ...(error?.details ? { details: error.details } : {})
  };
}
function cliError(code: string, message: string, details: Record<string, unknown> = {}) { return Object.assign(new Error(message), { code, details }); }
function errorSummary(error: any) { return { code: error?.code ?? "device_pod_cli_error", message: error?.message ?? String(error), ...(error?.details ? { details: error.details } : {}) }; }
function requiredOption(parsed: ParsedArgs, env: EnvLike, key: string, envKey: string) { return requiredText(parsed[key] ?? env[envKey], key); }
function requiredText(value: unknown, field: string) { const valueText = text(value); if (!valueText) throw cliError("missing_required_value", `${field} is required`, { field }); return valueText; }
function text(value: unknown) { return String(value ?? "").trim(); }
function numberOption(value: unknown) { const parsed = Number.parseInt(String(value ?? ""), 10); return Number.isFinite(parsed) ? parsed : undefined; }
function clean<T extends Record<string, any>>(value: T): T { return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined && item !== "" && item !== false)) as T; }
function pruneUndefined<T extends Record<string, unknown>>(value: T): T { return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined)) as T; }
function arrayOption(value: unknown) { return (Array.isArray(value) ? value : value === undefined ? [] : [value]).map((item) => text(item)).filter(Boolean); }
function devicePodSeedFromOptions(parsed: ParsedArgs, { required = false } = {}) {
  const devicePodText = text(parsed.devicePodJson ?? parsed.devicePod);
  if (devicePodText) return normalizeDevicePodSeed(parseJsonObjectOption(devicePodText, "devicePodJson"), "devicePodJson");
  const profileText = text(parsed.profileJson ?? parsed.profile);
  if (!profileText) {
    if (required) throw cliError("device_pod_profile_required", "--profile-json or --device-pod-json is required", { field: "profileJson" });
    return null;
  }
  return normalizeDevicePodSeed({
    devicePodId: parsed.podId ?? parsed.devicePodId,
    name: parsed.name,
    status: parsed.status,
    profile: parseJsonObjectOption(profileText, "profileJson")
  }, "devicePod");
}
function normalizeDevicePodSeed(value: any, field: string) {
  if (!value || typeof value !== "object" || Array.isArray(value)) throw cliError("invalid_device_pod_seed", `${field} must be a JSON object`, { field });
  const devicePodId = requiredText(value.devicePodId ?? value.id, `${field}.devicePodId`);
  const profile = value.profile ?? value.profileJson;
  if (!profile || typeof profile !== "object" || Array.isArray(profile)) throw cliError("invalid_device_pod_profile", `${field}.profile must be a JSON object`, { field: `${field}.profile` });
  return clean({ devicePodId, name: text(value.name), status: text(value.status), profile });
}
function parseJsonObjectOption(value: string, field: string) {
  try {
    const parsed = JSON.parse(value);
    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("not an object");
    return parsed;
  } catch (error: any) {
    throw cliError("invalid_json_option", `${field} must be a JSON object`, { field, reason: error?.message ?? String(error) });
  }
}
function normalizePath(value: string) { return String(value || ".").trim().replace(/\\/gu, "/").replace(/\s*\/\s*/gu, "/").replace(/\/+/gu, "/").replace(/^\/+|\/+$/gu, "") || "."; }
function normalizeProbePath(value: string) { const normalized = normalizePath(value); if (normalized === ".") return "uart/1"; if (normalized === "uart") throw cliError("invalid_io_probe_path", "io-probe path must be concrete, for example /uart/1"); return normalized; }
function joinPath(base: string, child: string) { const left = normalizePath(base); const right = normalizePath(child || "."); if (!right || right === ".") return left; if (child.startsWith("/")) return right; if (left === ".") return right; return normalizePath(`${left}/${right}`); }
async function patchText(parsed: ParsedArgs, stdinText?: string) { if (typeof parsed.patch === "string") return parsed.patch; if (typeof parsed.patchB64 === "string") return Buffer.from(parsed.patchB64, "base64").toString("utf8"); if (stdinText !== undefined) return stdinText; const chunks = []; for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk)); const textValue = Buffer.concat(chunks).toString("utf8"); if (!textValue.trim()) throw cliError("patch_text_required", "workspace apply-patch requires patch text on stdin or --patch/--patch-b64"); return textValue; }
async function contentPayload(parsed: ParsedArgs, stdinText?: string) {
  if (typeof parsed.contentB64 === "string") return { contentB64: parsed.contentB64 };
  if (typeof parsed.textB64 === "string") return { textB64: parsed.textB64 };
  if (typeof parsed.text === "string" || typeof parsed.content === "string") {
    return { text: String(parsed.text ?? parsed.content) };
  }
  const content = stdinText !== undefined ? stdinText : await readStdinText();
  if (!content) {
    throw cliError(
      "content_required",
      "workspace put requires stdin text or --content-b64/--text/--text-b64"
    );
  }
  return { contentB64: Buffer.from(content, "utf8").toString("base64") };
}
async function readStdinText() { const chunks = []; for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk)); return Buffer.concat(chunks).toString("utf8"); }
function jsonRpcArgs(parsed: ParsedArgs) {
  return clean({
    request: parsed.requestJson,
    params: parsed.paramsJson ?? parsed.params,
    expectResultField: arrayOption(parsed.expectResultField ?? parsed.resultField)
  });
}
function redactJobRequest(job: any) { return { ...job, args: redactArgs(job.args) }; }
function redactArgs(args: any = {}) {
  if (!args || typeof args !== "object") return args;
  const next = { ...args };
  if (typeof next.patch === "string") {
    next.patch = undefined;
    next.patchBytes = Buffer.byteLength(args.patch, "utf8");
  }
  if (typeof next.contentB64 === "string") {
    next.contentB64 = undefined;
    next.contentBytes = Buffer.from(args.contentB64, "base64").length;
  }
  if (typeof next.text === "string") {
    next.text = undefined;
    next.textBytes = Buffer.byteLength(args.text, "utf8");
  }
  return next;
}

function patchHintForText(message: unknown) {
  const textValue = String(message ?? "");
  const patchLike = /apply-patch|patch|hunk|\*\*\* Begin Patch|\*\*\* End Patch|Update File|Add File|Delete File/iu;
  if (!patchLike.test(textValue)) return {};
  return {
    patchHint: {
      standardForm: [
        "*** Begin Patch",
        "*** Update File: path/to/file.c",
        "@@",
        " exact unchanged context line",
        "-old line",
        "+new line",
        "*** End Patch"
      ],
      next: patchHintNext(textValue)
    }
  };
}

function patchHintNext(message: string) {
  const next = [
    "Re-read the current target file with workspace cat/rg, then retry a smaller exact-context hunk patch."
  ];
  if (/end with \*\*\* End Patch/iu.test(message)) {
    next.unshift("Add a final exact `*** End Patch` line.");
  } else if (/start with \*\*\* Begin Patch/iu.test(message)) {
    next.unshift("Start the patch with an exact `*** Begin Patch` line.");
  } else if (/hunk did not match|must start with @@|invalid update line prefix|ellipsis/iu.test(message)) {
    next.unshift("Use exact current context; do not use ellipsis or line-number-only hunks.");
  } else if (/unsupported patch header|capitalization|New File/iu.test(message)) {
    next.unshift("Use exactly `*** Update File:`, `*** Add File:`, or `*** Delete File:` headers.");
  }
  next.push("Do not switch to workspace put for existing source unless a smaller hunk cannot safely express the edit.");
  return next;
}
function parseJson(value: string) { if (!value) return null; try { return JSON.parse(value); } catch { return { rawText: value.slice(0, 2000), parseError: true }; } }
function compactBody(body: any) { if (!body || typeof body !== "object") return body; return { ok: body.ok, status: body.status, authenticated: body.authenticated, actor: body.actor, contractVersion: body.contractVersion, devicePodCount: Array.isArray(body.devicePods) ? body.devicePods.length : undefined, selectedDevicePodId: body.selectedDevicePodId, error: body.error, summary: body.summary }; }
function compactJobOutputBody(body: any) {
  if (!body || typeof body !== "object") return body;
  const output = body.output && typeof body.output === "object" ? body.output : {};
  const textValue = typeof body.text === "string" ? body.text : typeof output.text === "string" ? output.text : "";
  const maxTextBytes = 4000;
  const textBuffer = Buffer.from(textValue, "utf8");
  const clippedText = textBuffer.length > maxTextBytes ? textBuffer.subarray(0, maxTextBytes).toString("utf8") : textValue;
  return clean({
    serviceId: body.serviceId,
    contractVersion: body.contractVersion,
    accepted: body.accepted,
    status: body.status,
    devicePodId: body.devicePodId,
    targetId: body.targetId,
    profileHash: body.profileHash,
    traceId: body.traceId,
    operationId: body.operationId,
    job: body.job,
    blocker: body.blocker,
    freshness: body.freshness,
    outputUrl: body.outputUrl,
    cancelUrl: body.cancelUrl,
    text: clippedText,
    bytes: body.bytes ?? output.bytes,
    truncation: body.truncation ?? output.truncation,
    outputSummary: output.summary,
    gateway: output.gateway,
    evidenceId: output.evidenceId,
    httpStatus: output.httpStatus,
    compacted: true,
    compactNote: "Use --full to print the complete device job output payload.",
    textTruncation: {
      maxBytes: maxTextBytes,
      originalBytes: textBuffer.length,
      truncated: textBuffer.length > maxTextBytes
    }
  });
}