@metagptx/deepflow-cli 0.1.0

package/src/client.js

@@ -0,0 +1,318 @@
+import { randomUUID } from "node:crypto";
+
+import { DEFAULT_BASE_URL, normalizeBaseUrl } from "./config.js";
+import { CliError, exitCodeForHttpStatus } from "./errors.js";
+import { VERSION as CLI_VERSION } from "./version.js";
+
+const DEFAULT_TIMEOUT_MS = 600_000;
+const DEFAULT_FAST_TIMEOUT_MS = 15_000;
+
+function parseJson(text) {
+  if (!text.trim()) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function summarizePayload(payload) {
+  if (!payload || typeof payload !== "object") {
+    return payload ? String(payload) : "";
+  }
+
+  return [
+    typeof payload.error_code === "string" ? payload.error_code : "",
+    typeof payload.summary === "string" ? payload.summary : "",
+    payload.context &&
+    typeof payload.context === "object" &&
+    typeof payload.context.reason === "string"
+      ? payload.context.reason
+      : "",
+  ]
+    .filter(Boolean)
+    .join(" - ");
+}
+
+function isAbortError(error) {
+  return error?.name === "AbortError" || error?.name === "TimeoutError";
+}
+
+export class DeepFlowClient {
+  constructor({
+    baseUrl = DEFAULT_BASE_URL,
+    token = null,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    fastTimeoutMs = DEFAULT_FAST_TIMEOUT_MS,
+    cliVersion = CLI_VERSION,
+  } = {}) {
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+    this.token = token;
+    this.timeoutMs = timeoutMs;
+    this.fastTimeoutMs = fastTimeoutMs;
+    this.cliVersion = cliVersion;
+  }
+
+  withBaseUrl(baseUrl) {
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+    return this;
+  }
+
+  buildHeaders(body, { auditMethod } = {}) {
+    const headers = new Headers();
+
+    headers.set("accept", "application/json");
+
+    if (this.cliVersion) {
+      headers.set("x-deepflow-cli-version", this.cliVersion);
+    }
+
+    if (auditMethod) {
+      headers.set("x-deepflow-cli-method", auditMethod);
+    }
+
+    if (body !== undefined) {
+      headers.set("content-type", "application/json");
+    }
+
+    if (this.token) {
+      headers.set("authorization", `Bearer ${this.token}`);
+    }
+
+    return headers;
+  }
+
+  async request(path, {
+    method = "GET",
+    body,
+    signal,
+    timeoutMs = this.timeoutMs,
+    auditMethod,
+  } = {}) {
+    const url = new URL(path, this.baseUrl);
+    const requestBody = body === undefined ? undefined : JSON.stringify(body);
+    let response;
+
+    try {
+      response = await fetch(url, {
+        method,
+        body: requestBody,
+        headers: this.buildHeaders(requestBody, { auditMethod }),
+        signal: signal
+          ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])
+          : AbortSignal.timeout(timeoutMs),
+      });
+    } catch (error) {
+      if (isAbortError(error)) {
+        throw new CliError(`DeepFlow Web did not respond at ${url.toString()} within ${timeoutMs}ms.`, {
+          code: "web_timeout",
+          exitCode: 5,
+        });
+      }
+
+      throw new CliError(`Failed to connect to DeepFlow Web at ${url.toString()}: ${error.message}`, {
+        code: "web_unreachable",
+        exitCode: 5,
+      });
+    }
+
+    const text = await response.text();
+    const payload = parseJson(text);
+
+    if (!response.ok) {
+      const details = summarizePayload(payload);
+
+      throw new CliError(
+        `${method} ${url.pathname}${url.search} failed with HTTP ${response.status}${
+          details ? `: ${details}` : ""
+        }`,
+        {
+          code: payload?.error_code || "http_error",
+          exitCode: exitCodeForHttpStatus(response.status, payload),
+          status: response.status,
+          payload,
+        },
+      );
+    }
+
+    return payload;
+  }
+
+  async authConfig(options = {}) {
+    return this.request("/api/auth/config", {
+      timeoutMs: this.fastTimeoutMs,
+      ...options,
+    });
+  }
+
+  async verifyToken(auditMethod = "auth.verify") {
+    return this.request("/api/auth/token/verify", {
+      timeoutMs: this.fastTimeoutMs,
+      auditMethod,
+    });
+  }
+
+  async listApps() {
+    const payload = await this.request("/api/local/apps", {
+      timeoutMs: this.fastTimeoutMs,
+      auditMethod: "apps.list",
+    });
+
+    return Array.isArray(payload?.items) ? payload.items : [];
+  }
+
+  async createIteration(input) {
+    return this.request("/api/local/iterations", {
+      method: "POST",
+      body: input,
+      auditMethod: "plan.run",
+    });
+  }
+
+  async createPlanSession(input) {
+    return this.request("/api/local/sessions", {
+      method: "POST",
+      body: {
+        ...input,
+        stage: "plan",
+      },
+      auditMethod: "plan.run",
+    });
+  }
+
+  async sendPlanMessage({
+    localIterationId,
+    sessionId,
+    prompt,
+  }) {
+    return this.request(
+      `/api/local/sessions/${encodeURIComponent(sessionId)}/messages?iterationId=${encodeURIComponent(localIterationId)}`,
+      {
+        method: "POST",
+        body: {
+          message_id: `cli-${Date.now()}-${randomUUID()}`,
+          mode: "plan",
+          content: prompt,
+        },
+        auditMethod: "plan.run",
+      },
+    );
+  }
+
+  async getLocalSession({
+    localIterationId,
+    sessionId,
+  }) {
+    return this.request(
+      `/api/local/sessions/${encodeURIComponent(sessionId)}?iterationId=${encodeURIComponent(localIterationId)}`,
+      {
+        timeoutMs: this.fastTimeoutMs,
+        auditMethod: "plan.status",
+      },
+    );
+  }
+
+  async listMessages({
+    backendIterationId,
+    sessionId,
+  }) {
+    return this.request(
+      `/api/sessions/${encodeURIComponent(sessionId)}/messages?iteration_id=${encodeURIComponent(backendIterationId)}`,
+      {
+        timeoutMs: this.fastTimeoutMs,
+        auditMethod: "session.messages",
+      },
+    );
+  }
+
+  async stopSession({
+    backendIterationId,
+    sessionId,
+  }) {
+    return this.request(
+      `/api/sessions/${encodeURIComponent(sessionId)}/stop?iteration_id=${encodeURIComponent(backendIterationId)}`,
+      {
+        method: "POST",
+        timeoutMs: this.fastTimeoutMs,
+        auditMethod: "session.stop",
+      },
+    );
+  }
+}
+
+export function buildPlanStatusUrl(baseUrl, {
+  localIterationId,
+  sessionId,
+}) {
+  return new URL(
+    `/api/local/sessions/${encodeURIComponent(sessionId)}?iterationId=${encodeURIComponent(localIterationId)}`,
+    baseUrl,
+  ).toString();
+}
+
+export function buildSessionMessagesUrl(baseUrl, {
+  backendIterationId,
+  sessionId,
+}) {
+  return new URL(
+    `/api/sessions/${encodeURIComponent(sessionId)}/messages?iteration_id=${encodeURIComponent(backendIterationId)}`,
+    baseUrl,
+  ).toString();
+}
+
+export function buildSessionStopUrl(baseUrl, {
+  backendIterationId,
+  sessionId,
+}) {
+  return new URL(
+    `/api/sessions/${encodeURIComponent(sessionId)}/stop?iteration_id=${encodeURIComponent(backendIterationId)}`,
+    baseUrl,
+  ).toString();
+}
+
+export async function resolveReachableBaseUrl(client) {
+  const parsed = new URL(client.baseUrl);
+
+  if (parsed.hostname === "127.0.0.1") {
+    parsed.hostname = "localhost";
+    const fallbackBaseUrl = normalizeBaseUrl(parsed.toString());
+    const fallbackClient = new DeepFlowClient({
+      baseUrl: fallbackBaseUrl,
+      token: client.token,
+      timeoutMs: client.timeoutMs,
+      fastTimeoutMs: client.fastTimeoutMs,
+      cliVersion: client.cliVersion,
+    });
+    const primaryController = new AbortController();
+    const fallbackController = new AbortController();
+
+    const reachableBaseUrl = await Promise.any([
+      client.authConfig({ signal: primaryController.signal }).then(() => client.baseUrl),
+      fallbackClient.authConfig({ signal: fallbackController.signal }).then(() => fallbackBaseUrl),
+    ])
+      .catch((error) => {
+        throw error.errors?.[0] ?? error;
+      })
+      .finally(() => {
+        primaryController.abort();
+        fallbackController.abort();
+      });
+
+    client.withBaseUrl(reachableBaseUrl);
+    return reachableBaseUrl;
+  }
+
+  await client.authConfig();
+  return client.baseUrl;
+}
+
+export function parseTimeoutMs(value, fallback) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export { DEFAULT_FAST_TIMEOUT_MS, DEFAULT_TIMEOUT_MS };

package/src/config.js

@@ -0,0 +1,156 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { CliError } from "./errors.js";
+
+export const DEFAULT_BASE_URL = "http://localhost:3100";
+export const DEFAULT_PROFILE = "default";
+
+export function resolveConfigPath(env = process.env) {
+  if (env.DEEPFLOW_CONFIG) {
+    return path.resolve(env.DEEPFLOW_CONFIG);
+  }
+
+  const configDir = env.DEEPFLOW_CONFIG_DIR
+    ? path.resolve(env.DEEPFLOW_CONFIG_DIR)
+    : path.join(os.homedir(), ".deepflow");
+
+  return path.join(configDir, "config.json");
+}
+
+function emptyConfig() {
+  return {
+    profile: DEFAULT_PROFILE,
+    profiles: {},
+  };
+}
+
+export async function readConfig(env = process.env) {
+  const configPath = resolveConfigPath(env);
+
+  try {
+    const raw = await readFile(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+
+    if (!parsed || typeof parsed !== "object") {
+      throw new Error("config is not an object");
+    }
+
+    return {
+      path: configPath,
+      data: {
+        ...emptyConfig(),
+        ...parsed,
+        profiles:
+          parsed.profiles && typeof parsed.profiles === "object"
+            ? parsed.profiles
+            : {},
+      },
+    };
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return {
+        path: configPath,
+        data: emptyConfig(),
+      };
+    }
+
+    throw new CliError(`Failed to read config: ${error.message}`, {
+      code: "config_read_failed",
+      exitCode: 1,
+    });
+  }
+}
+
+export async function writeConfig(data, env = process.env) {
+  const configPath = resolveConfigPath(env);
+  await mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
+  await writeFile(configPath, `${JSON.stringify(data, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  await chmod(configPath, 0o600);
+
+  return configPath;
+}
+
+export async function resolveRuntimeConfig(flags = {}, env = process.env) {
+  const config = await readConfig(env);
+  const profile = flags.profile || env.DEEPFLOW_PROFILE || config.data.profile || DEFAULT_PROFILE;
+  const profileConfig = config.data.profiles?.[profile] ?? {};
+  const token = flags.token || env.DEEPFLOW_TOKEN || profileConfig.token || config.data.token || null;
+  const baseUrl =
+    flags.baseUrl ||
+    env.DEEPFLOW_BASE_URL ||
+    profileConfig.baseUrl ||
+    config.data.baseUrl ||
+    DEFAULT_BASE_URL;
+
+  return {
+    configPath: config.path,
+    profile,
+    baseUrl: normalizeBaseUrl(baseUrl),
+    token,
+  };
+}
+
+export async function saveAuthConfig({
+  baseUrl,
+  token,
+  profile = DEFAULT_PROFILE,
+}, env = process.env) {
+  const config = await readConfig(env);
+  const next = {
+    ...config.data,
+    profile,
+    baseUrl: normalizeBaseUrl(baseUrl),
+    token,
+    profiles: {
+      ...(config.data.profiles ?? {}),
+      [profile]: {
+        ...(config.data.profiles?.[profile] ?? {}),
+        baseUrl: normalizeBaseUrl(baseUrl),
+        token,
+      },
+    },
+  };
+
+  const configPath = await writeConfig(next, env);
+
+  return {
+    configPath,
+    data: next,
+  };
+}
+
+export async function clearAuthConfig(profile = DEFAULT_PROFILE, env = process.env) {
+  const config = await readConfig(env);
+  const nextProfiles = {
+    ...(config.data.profiles ?? {}),
+  };
+
+  if (nextProfiles[profile]) {
+    const { token: _token, ...rest } = nextProfiles[profile];
+    nextProfiles[profile] = rest;
+  }
+
+  const next = {
+    ...config.data,
+    profiles: nextProfiles,
+  };
+
+  if ((next.profile || DEFAULT_PROFILE) === profile) {
+    delete next.token;
+  }
+
+  const configPath = await writeConfig(next, env);
+
+  return {
+    configPath,
+    data: next,
+  };
+}
+
+export function normalizeBaseUrl(value) {
+  return String(value || DEFAULT_BASE_URL).trim().replace(/\/+$/, "");
+}

package/src/errors.js

@@ -0,0 +1,55 @@
+export class CliError extends Error {
+  constructor(message, {
+    code = "error",
+    exitCode = 1,
+    status = null,
+    payload = null,
+  } = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exitCode = exitCode;
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+export function exitCodeForHttpStatus(status, payload = null) {
+  if (status === 401) {
+    return 3;
+  }
+
+  if (status === 403) {
+    return 4;
+  }
+
+  if (
+    status === 502 ||
+    payload?.error_type === "proxy_error" ||
+    payload?.error_code === "bad_gateway"
+  ) {
+    return 6;
+  }
+
+  return 1;
+}
+
+export function redactToken(value) {
+  if (typeof value !== "string" || !value) {
+    return "";
+  }
+
+  if (value.length <= 12) {
+    return `${value.slice(0, 4)}...`;
+  }
+
+  return `${value.slice(0, 8)}...${value.slice(-4)}`;
+}
+
+export function normalizeError(error) {
+  if (error instanceof CliError) {
+    return error;
+  }
+
+  return new CliError(error instanceof Error ? error.message : String(error));
+}

package/src/output.js

@@ -0,0 +1,87 @@
+import { normalizeError } from "./errors.js";
+
+export function writeJson(io, value, stream = "stdout") {
+  io[stream].write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function writeResult(io, result, { json = false } = {}) {
+  if (json) {
+    writeJson(io, result);
+    return;
+  }
+
+  switch (result.method) {
+    case "auth.login":
+      io.stdout.write(`Authenticated: ${result.baseUrl}\n`);
+      io.stdout.write(`Config: ${result.configPath}\n`);
+      break;
+    case "auth.logout":
+      io.stdout.write(`Logged out profile "${result.profile}".\n`);
+      break;
+    case "auth.status":
+      io.stdout.write(`Authenticated: ${result.authenticated ? "yes" : "no"}\n`);
+      io.stdout.write(`Base URL: ${result.baseUrl}\n`);
+      if (result.tokenPrefix) {
+        io.stdout.write(`Token: ${result.tokenPrefix}...\n`);
+      }
+      if (result.status) {
+        io.stdout.write(`Status: ${result.status}\n`);
+      }
+      break;
+    case "apps.list":
+      if (result.items.length === 0) {
+        io.stdout.write("No apps found.\n");
+        break;
+      }
+      for (const app of result.items) {
+        io.stdout.write(`${app.id}\t${app.appCode ?? ""}\t${app.name}\t${app.repositoryUrl}\n`);
+      }
+      break;
+    case "plan.run":
+      io.stdout.write("Plan run started.\n");
+      io.stdout.write(`Iteration: ${result.iterationId}\n`);
+      io.stdout.write(`Backend iteration: ${result.backendIterationId}\n`);
+      io.stdout.write(`Plan session: ${result.planSessionId}\n`);
+      if (result.runId) {
+        io.stdout.write(`Run: ${result.runId}\n`);
+      }
+      io.stdout.write(`URL: ${result.uiUrl}\n`);
+      io.stdout.write(`Status: ${result.statusUrl}\n`);
+      io.stdout.write(`Messages: ${result.messagesUrl}\n`);
+      io.stdout.write(`Stop: ${result.stopUrl}\n`);
+      break;
+    case "plan.status":
+      io.stdout.write(`Session: ${result.sessionId}\n`);
+      io.stdout.write(`Status: ${result.status ?? "unknown"}\n`);
+      break;
+    case "session.messages":
+      io.stdout.write(JSON.stringify(result.messages, null, 2));
+      io.stdout.write("\n");
+      break;
+    case "session.stop":
+      io.stdout.write(`Stop requested for session ${result.sessionId}.\n`);
+      break;
+    default:
+      io.stdout.write(JSON.stringify(result, null, 2));
+      io.stdout.write("\n");
+      break;
+  }
+}
+
+export function writeError(io, error, { json = false } = {}) {
+  const normalized = normalizeError(error);
+  const payload = {
+    ok: false,
+    errorCode: normalized.code,
+    message: normalized.message,
+    status: normalized.status,
+  };
+
+  if (json) {
+    writeJson(io, payload, "stderr");
+    return normalized.exitCode;
+  }
+
+  io.stderr.write(`Error: ${normalized.message}\n`);
+  return normalized.exitCode;
+}

package/src/version.js

@@ -0,0 +1,7 @@
+import { readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+export const VERSION = packageJson.version;