tuya-platform-cli 0.1.0

package/src/lib/config.js

@@ -0,0 +1,204 @@
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import { expandHome, timestampForFile } from "./util.js";
+
+const DEFAULT_BASE_URL = "https://platform.tuya.com/ai/workflow";
+
+function getDefaultChromePath() {
+  switch (process.platform) {
+    case "darwin":
+      return "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+    case "win32":
+      return "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe";
+    default:
+      return "/usr/bin/google-chrome";
+  }
+}
+
+function getDefaultChromeProfileRoot() {
+  switch (process.platform) {
+    case "darwin":
+      return path.join(os.homedir(), "Library/Application Support/Google/Chrome");
+    case "win32":
+      return path.join(process.env.LOCALAPPDATA ?? os.homedir(), "Google/Chrome/User Data");
+    default:
+      return path.join(os.homedir(), ".config/google-chrome");
+  }
+}
+
+function buildDefaultOutputDir(command) {
+  const segment = command === "manual" ? "tuya-platform-cli" : "live-run";
+  return path.join(process.cwd(), "artifacts", segment, timestampForFile());
+}
+
+function requireArgValue(flag, next) {
+  if (next === undefined || next.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return next;
+}
+
+export function parseCliArgs(argv) {
+  const command =
+    argv[0] && !argv[0].startsWith("-")
+      ? argv[0]
+      : "manual";
+  const tokens = command === "manual" ? argv : argv.slice(1);
+
+  const args = {
+    command,
+    baseUrl: DEFAULT_BASE_URL,
+    chromePath: getDefaultChromePath(),
+    chromeProfileRoot: getDefaultChromeProfileRoot(),
+    chromeProfileName: "Default",
+    remoteDebuggingPort: command === "manual" ? 9222 : 9440,
+    headless: false,
+    help: false,
+    redactAuth: false,
+    workflowName: null,
+    workflowId: null,
+    region: "AZ",
+    imagePath: null,
+    definitionFile: null,
+    projectCode: null,
+  };
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    const next = tokens[index + 1];
+
+    switch (token) {
+      case "--base-url":
+        args.baseUrl = requireArgValue("--base-url", next);
+        index += 1;
+        break;
+      case "--chrome-path":
+        args.chromePath = expandHome(requireArgValue("--chrome-path", next));
+        index += 1;
+        break;
+      case "--chrome-profile-root":
+        args.chromeProfileRoot = expandHome(requireArgValue("--chrome-profile-root", next));
+        index += 1;
+        break;
+      case "--chrome-profile-name":
+        args.chromeProfileName = requireArgValue("--chrome-profile-name", next);
+        index += 1;
+        break;
+      case "--output-dir":
+        args.outputDir = expandHome(requireArgValue("--output-dir", next));
+        index += 1;
+        break;
+      case "--remote-debugging-port":
+        args.remoteDebuggingPort = Number(requireArgValue("--remote-debugging-port", next));
+        index += 1;
+        break;
+      case "--workflow-name":
+        args.workflowName = requireArgValue("--workflow-name", next);
+        index += 1;
+        break;
+      case "--workflow-id":
+        args.workflowId = requireArgValue("--workflow-id", next);
+        index += 1;
+        break;
+      case "--region":
+        args.region = requireArgValue("--region", next);
+        index += 1;
+        break;
+      case "--image-path":
+        args.imagePath = expandHome(requireArgValue("--image-path", next));
+        index += 1;
+        break;
+      case "--definition-file":
+        args.definitionFile = expandHome(requireArgValue("--definition-file", next));
+        index += 1;
+        break;
+      case "--project-code":
+        args.projectCode = requireArgValue("--project-code", next);
+        index += 1;
+        break;
+      case "--headless":
+        args.headless = true;
+        break;
+      case "--redact-auth":
+        args.redactAuth = true;
+        break;
+      case "--help":
+      case "-h":
+        args.help = true;
+        break;
+      default:
+        if (token.startsWith("--")) {
+          throw new Error(`Unknown argument: ${token}`);
+        }
+    }
+  }
+
+  const outputDir = args.outputDir ?? buildDefaultOutputDir(command);
+
+  const resolvedChromePath = path.resolve(args.chromePath);
+  if (!fs.existsSync(resolvedChromePath)) {
+    console.error(
+      `Warning: Chrome not found at ${resolvedChromePath}. Use --chrome-path to specify.`,
+    );
+  }
+
+  return {
+    ...args,
+    outputDir,
+    chromeProfileRoot: path.resolve(args.chromeProfileRoot),
+    chromePath: resolvedChromePath,
+  };
+}
+
+export function buildHelpText() {
+  return [
+    "Usage:",
+    "  tuya-platform-cli <command> [options]",
+    "  npm run tuya -- [options]",
+    "",
+    "Commands:",
+    "  doctor              Validate CDP, login state, workflow access, and trial-run preconditions",
+    "  manual              Launch isolated Chrome and record the 8 manual steps",
+    "  auto-basic          Attach to an existing Chrome CDP session and run the basic 8-step flow",
+    "  sample-extra-nodes  Attach to an existing Chrome CDP session and capture Loop/Monitor node samples",
+    "  sample-branch-edges Attach to an existing Chrome CDP session and create a selector branch sample",
+    "  sample-trial-inputs Attach to an existing Chrome CDP session and capture trial-run input samples",
+    "  configure           Read a JSON definition file and create/update a workflow via API",
+    "  publish             Publish a workflow's agent to the specified region",
+    "  list-libraries      List available knowledge libraries (returns libCode for SearchKnowledge nodes)",
+    "",
+    "Options:",
+    "  --base-url <url>                Target page URL",
+    "  --chrome-path <path>            Chrome binary path",
+    "  --chrome-profile-root <path>    Chrome user data root",
+    "  --chrome-profile-name <name>    Profile directory name (default: Default)",
+    "  --output-dir <path>             Artifact output directory",
+    "  --remote-debugging-port <port>  Chrome remote debugging port",
+    "  --workflow-name <name>          Workflow name prefix for sample commands",
+    "  --workflow-id <id>              Existing workflow ID for workflow-specific commands",
+    "  --region <region>               Workflow region for sample commands (default: AZ)",
+    "  --image-path <path>             Local image path for sample-trial-inputs",
+    "  --definition-file <path>        JSON workflow definition file for configure command",
+    "  --project-code <code>           Agent project code for publish command",
+    "  --headless                      Run Chrome headless (manual only)",
+    "  --redact-auth                   Redact auth headers (authorization, cookie) in output files",
+    "  --help, -h                      Show this help",
+    "",
+    "Defaults:",
+    `  base-url: ${DEFAULT_BASE_URL}`,
+    `  chrome-path: ${getDefaultChromePath()}`,
+    `  chrome-profile-root: ${getDefaultChromeProfileRoot()}`,
+    "",
+    "Examples:",
+    "  node src/cli.js doctor --remote-debugging-port 9440 --workflow-id 5883 --region AZ",
+    "  npm run tuya --",
+    "  node src/cli.js auto-basic --remote-debugging-port 9440",
+    "  node src/cli.js sample-extra-nodes --remote-debugging-port 9440 --region AZ",
+    "  node src/cli.js sample-branch-edges --remote-debugging-port 9440 --region AZ",
+    "  node src/cli.js sample-trial-inputs --remote-debugging-port 9440 --workflow-id 5883 --region AZ",
+    "  node src/cli.js configure --definition-file workflow.json --remote-debugging-port 9440 --region AZ",
+    "  node src/cli.js publish --workflow-id 5883 --region AZ --remote-debugging-port 9440",
+    "  node src/cli.js list-libraries --remote-debugging-port 9440",
+  ].join("\n");
+}

package/src/lib/recorder.js

@@ -0,0 +1,316 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { chromium } from "playwright";
+import { BrowserCdpClient, getBrowserWebSocketUrl } from "./cdp-client.js";
+import { ensureDir, safeJsonParse, slugify, trimBody, writeJson, writeText } from "./util.js";
+
+function buildAuthHeaders(headers = {}) {
+  const allowed = [
+    "authorization",
+    "cookie",
+    "x-auth-token",
+    "x-csrf-token",
+    "x-xsrf-token",
+    "x-requested-with",
+    "x-device-id",
+  ];
+
+  return Object.fromEntries(
+    Object.entries(headers).filter(([key]) =>
+      allowed.includes(String(key).toLowerCase()),
+    ),
+  );
+}
+
+const SENSITIVE_HEADERS = ["authorization", "cookie", "x-auth-token"];
+
+function redactHeaders(headers) {
+  const result = { ...headers };
+  for (const key of Object.keys(result)) {
+    if (SENSITIVE_HEADERS.includes(key.toLowerCase())) {
+      result[key] = "***REDACTED***";
+    }
+  }
+  return result;
+}
+
+function looksLikeBundle(url, mimeType) {
+  return (
+    mimeType?.includes("javascript") ||
+    /\.js(\?|$)/i.test(url) ||
+    url.includes("/assets/")
+  );
+}
+
+const BINARY_CONTENT_TYPES = /^(image|font|video|audio)\//i;
+
+let authWarningShown = false;
+
+export class StepRecorder {
+  constructor({ outputDir, remoteDebuggingPort, pageUrlIncludes = "platform.tuya.com/ai/workflow", redactAuth = false }) {
+    this.outputDir = outputDir;
+    this.remoteDebuggingPort = remoteDebuggingPort;
+    this.pageUrlIncludes = pageUrlIncludes;
+    this.redactAuth = redactAuth;
+    this.requests = new Map();
+    this.currentStep = null;
+    this.browser = null;
+    this.context = null;
+    this.page = null;
+    this.cdp = null;
+    this.sessions = new Set();
+  }
+
+  async initialize() {
+    const browserWsUrl = await getBrowserWebSocketUrl(this.remoteDebuggingPort);
+    this.cdp = new BrowserCdpClient(browserWsUrl);
+    await this.cdp.connect();
+    await this.bootstrapCdp();
+
+    this.browser = await chromium.connectOverCDP(
+      `http://127.0.0.1:${this.remoteDebuggingPort}`,
+    );
+    this.context =
+      this.browser.contexts()[0] ?? (await this.browser.newContext());
+    this.page =
+      this.context
+        .pages()
+        .find((page) => page.url().includes(this.pageUrlIncludes)) ??
+      this.context.pages().find((page) => page.url().startsWith("http")) ??
+      (await this.context.newPage());
+  }
+
+  async bootstrapCdp() {
+    this.cdp.on("Target.attachedToTarget", async (params, sessionId) => {
+      if (!sessionId) {
+        return;
+      }
+
+      this.sessions.add(sessionId);
+
+      await Promise.allSettled([
+        this.cdp.send("Network.enable", {}, sessionId),
+        this.cdp.send("Page.enable", {}, sessionId),
+        this.cdp.send("Runtime.enable", {}, sessionId),
+      ]);
+    });
+
+    this.cdp.on("Network.requestWillBeSent", (params, sessionId) => {
+      if (!this.currentStep) {
+        return;
+      }
+
+      const existing = this.requests.get(params.requestId) ?? {
+        requestId: params.requestId,
+        stepId: this.currentStep.id,
+        targetSessionId: sessionId,
+      };
+
+      existing.url = params.request.url;
+      existing.method = params.request.method;
+      existing.requestHeaders = params.request.headers ?? {};
+      const authHeaders = buildAuthHeaders(params.request.headers);
+      if (Object.keys(authHeaders).length > 0 && !authWarningShown) {
+        console.error("Warning: auth headers (authorization, cookie, etc.) are being captured. Use --redact-auth to redact them.");
+        authWarningShown = true;
+      }
+      existing.authHeaders = this.redactAuth ? redactHeaders(authHeaders) : authHeaders;
+      existing.requestTimestamp = params.timestamp;
+      existing.resourceType = params.type ?? existing.resourceType ?? null;
+      existing.documentUrl = params.documentURL ?? null;
+      existing.initiator = params.initiator ?? null;
+
+      this.requests.set(params.requestId, existing);
+      this.capturePostData(params.requestId, sessionId).catch(() => {});
+    });
+
+    this.cdp.on("Network.responseReceived", (params) => {
+      const existing = this.requests.get(params.requestId);
+      if (!existing || !this.currentStep) {
+        return;
+      }
+
+      existing.responseStatus = params.response.status;
+      existing.responseHeaders = params.response.headers ?? {};
+      existing.mimeType = params.response.mimeType ?? null;
+      existing.protocol = params.response.protocol ?? null;
+      existing.remoteIPAddress = params.response.remoteIPAddress ?? null;
+      existing.responseTimestamp = params.timestamp;
+      existing.responseUrl = params.response.url;
+      this.requests.set(params.requestId, existing);
+    });
+
+    this.cdp.on("Network.webSocketCreated", (params) => {
+      if (!this.currentStep) {
+        return;
+      }
+
+      this.requests.set(params.requestId, {
+        requestId: params.requestId,
+        stepId: this.currentStep.id,
+        url: params.url,
+        method: "WEBSOCKET",
+        resourceType: "WebSocket",
+        authHeaders: {},
+        frames: [],
+      });
+    });
+
+    this.cdp.on("Network.webSocketFrameReceived", (params) => {
+      const existing = this.requests.get(params.requestId);
+      if (!existing) {
+        return;
+      }
+
+      existing.frames ??= [];
+      existing.frames.push({
+        direction: "received",
+        opcode: params.response.opcode,
+        payloadData: trimBody(params.response.payloadData, 20_000),
+      });
+      this.requests.set(params.requestId, existing);
+    });
+
+    this.cdp.on("Network.webSocketFrameSent", (params) => {
+      const existing = this.requests.get(params.requestId);
+      if (!existing) {
+        return;
+      }
+
+      existing.frames ??= [];
+      existing.frames.push({
+        direction: "sent",
+        opcode: params.response.opcode,
+        payloadData: trimBody(params.response.payloadData, 20_000),
+      });
+      this.requests.set(params.requestId, existing);
+    });
+
+    this.cdp.on("Network.loadingFinished", (params, sessionId) => {
+      if (!this.currentStep) {
+        return;
+      }
+
+      this.captureResponseBody(params.requestId, sessionId).catch(() => {});
+    });
+
+    await this.cdp.send("Target.setDiscoverTargets", { discover: true });
+    await this.cdp.send("Target.setAutoAttach", {
+      autoAttach: true,
+      waitForDebuggerOnStart: false,
+      flatten: true,
+    });
+  }
+
+  async capturePostData(requestId, sessionId) {
+    if (!sessionId) {
+      return;
+    }
+
+    const existing = this.requests.get(requestId);
+    if (!existing || existing.requestBody) {
+      return;
+    }
+
+    try {
+      const response = await this.cdp.send(
+        "Network.getRequestPostData",
+        { requestId },
+        sessionId,
+      );
+      existing.requestBody = trimBody(response.postData, 200_000);
+      this.requests.set(requestId, existing);
+    } catch {
+      // Some requests do not expose post data.
+    }
+  }
+
+  async captureResponseBody(requestId, sessionId) {
+    if (!sessionId) {
+      return;
+    }
+
+    const existing = this.requests.get(requestId);
+    if (!existing || existing.responseBody !== undefined) {
+      return;
+    }
+
+    if (BINARY_CONTENT_TYPES.test(existing.mimeType ?? "")) {
+      existing.responseBody = null;
+      existing.skippedBinaryBody = true;
+      this.requests.set(requestId, existing);
+      return;
+    }
+
+    try {
+      const response = await this.cdp.send(
+        "Network.getResponseBody",
+        { requestId },
+        sessionId,
+      );
+      existing.responseBody = trimBody(
+        response.base64Encoded
+          ? Buffer.from(response.body, "base64").toString("utf8")
+          : response.body,
+        500_000,
+      );
+      existing.responseBodyJson = safeJsonParse(existing.responseBody);
+      this.requests.set(requestId, existing);
+    } catch {
+      // Some response bodies are unavailable for streaming or preflight requests.
+    }
+  }
+
+  async startStep(step) {
+    this.currentStep = step;
+    this.requests.clear();
+  }
+
+  async finishStep(step) {
+    const stepDir = path.join(this.outputDir, step.id);
+    const requestsDir = path.join(stepDir, "requests");
+    const bundlesDir = path.join(this.outputDir, "bundles");
+    const network = Array.from(this.requests.values()).sort((left, right) => {
+      return (left.requestTimestamp ?? 0) - (right.requestTimestamp ?? 0);
+    });
+
+    await ensureDir(requestsDir);
+    await ensureDir(bundlesDir);
+
+    for (const [index, request] of network.entries()) {
+      const fileName = `${String(index + 1).padStart(3, "0")}-${slugify(
+        request.method || "request",
+      )}-${slugify(request.url || request.requestId)}.json`;
+
+      await writeJson(path.join(requestsDir, fileName), request);
+
+      if (looksLikeBundle(request.url ?? "", request.mimeType) && request.responseBody) {
+        const bundleName = `${slugify(request.url)}.js`;
+        await writeText(path.join(bundlesDir, bundleName), request.responseBody);
+      }
+    }
+
+    await writeJson(path.join(stepDir, "network.json"), network);
+
+    if (this.page) {
+      try {
+        await this.page.screenshot({
+          path: path.join(stepDir, "screenshot.png"),
+          fullPage: true,
+        });
+      } catch {
+        // Screenshots are best-effort only.
+      }
+    }
+
+    this.currentStep = null;
+    return network;
+  }
+
+  async close() {
+    await Promise.allSettled([
+      this.browser?.close(),
+      this.cdp?.close(),
+    ]);
+  }
+}