@tscomfy/cli 0.0.0-stage → 0.1.0

package/src/report.ts

@@ -0,0 +1,73 @@
+import { type Diagnostic, parse, type Schema } from "@tscomfy/core";
+import { isRecord } from "./util.ts";
+
+/** How many diagnostics a pack shows before the rest are summarized, unless verbose. */
+const SHOWN_PER_PACK = 5;
+
+/**
+ * Diagnostics grouped by node pack (`python_module`; docs/plan.md §9), errors and warnings
+ * counted, at most a few lines per pack unless `verbose`.
+ */
+export function reportDiagnostics(
+  diagnostics: readonly Diagnostic[],
+  schema: Schema,
+  objectInfo: string,
+  verbose: boolean,
+): string {
+  if (diagnostics.length === 0) return "";
+  const packs = packsOf(schema, objectInfo);
+  const groups = new Map<string, Diagnostic[]>();
+  for (const diagnostic of diagnostics) {
+    const classType = String(diagnostic.path[0] ?? "");
+    const pack = packs.get(classType) ?? "(no pack)";
+    groups.set(pack, [...(groups.get(pack) ?? []), diagnostic]);
+  }
+  const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
+  const lines = [
+    `${count(errors, "error")} and ${count(diagnostics.length - errors, "warning")} in the node definitions:`,
+  ];
+  for (const pack of [...groups.keys()].toSorted()) {
+    const group = groups.get(pack) ?? [];
+    lines.push(`  ${pack}: ${String(group.length)}`);
+    const shown = verbose ? group : group.slice(0, SHOWN_PER_PACK);
+    for (const diagnostic of shown) lines.push(`    ${formatDiagnostic(diagnostic)}`);
+    if (shown.length < group.length) {
+      lines.push(`    … and ${String(group.length - shown.length)} more (--verbose shows all)`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** One line for a diagnostic: its code, where, and what. */
+export function formatDiagnostic(diagnostic: Diagnostic): string {
+  return `${diagnostic.code} ${diagnostic.path.join(" › ")}: ${diagnostic.message}`;
+}
+
+/** `1 warning`, `3 errors`. */
+export function count(amount: number, noun: string): string {
+  return `${String(amount)} ${noun}${amount === 1 ? "" : "s"}`;
+}
+
+/** A byte size for humans. */
+export function size(bytes: number): string {
+  if (bytes < 1024) return `${String(bytes)} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+/**
+ * Each class type's pack: from the schema, or from the raw response for nodes the normalizer
+ * dropped.
+ */
+function packsOf(schema: Schema, objectInfo: string): Map<string, string> {
+  const packs = new Map<string, string>();
+  const raw = parse(objectInfo).value;
+  if (raw !== undefined && isRecord(raw)) {
+    for (const [classType, node] of Object.entries(raw)) {
+      const module = isRecord(node) ? node["python_module"] : undefined;
+      if (typeof module === "string") packs.set(classType, module);
+    }
+  }
+  for (const node of Object.values(schema.nodes)) packs.set(node.classType, node.pythonModule);
+  return packs;
+}

package/src/run.ts

@@ -0,0 +1,90 @@
+import { CHECK_USAGE, checkCommand } from "./check.ts";
+import { GENERATE_USAGE, generateCommand } from "./generate.ts";
+import { CliError, type Io } from "./io.ts";
+import { TRANSPILE_USAGE, transpileCommand } from "./transpile.ts";
+
+/** The CLI's version. A test keeps it equal to package.json. */
+export const CLI_VERSION = "0.1.0";
+
+/** `tscomfy --help`. */
+const USAGE = `Usage: tscomfy <command> [options]
+
+Commands:
+  generate   Generate typed node definitions from a ComfyUI server
+  check      Check that the generated types still match the server
+  transpile  Turn an API-format prompt or a UI workflow into TypeScript over the generated types
+  help       Show this help, or a command's: tscomfy help <command>
+
+Options:
+  -h, --help     Show this help.
+  -v, --version  Print the version.
+
+Run tscomfy <command> --help for a command's options.
+`;
+
+const USAGES: ReadonlyMap<string, string> = new Map([
+  ["generate", GENERATE_USAGE],
+  ["check", CHECK_USAGE],
+  ["transpile", TRANSPILE_USAGE],
+]);
+
+/**
+ * Runs the CLI with `args` (without the program name) and returns the exit code: 0 on success,
+ * 1 on a failure or detected drift, 2 on a usage error.
+ */
+export async function run(args: readonly string[], io: Io): Promise<number> {
+  const [command, ...rest] = args;
+  try {
+    switch (command) {
+      case "generate":
+        return await generateCommand(io, rest);
+      case "check":
+        return await checkCommand(io, rest);
+      case "transpile":
+        return await transpileCommand(io, rest);
+      case "-v":
+      case "--version":
+        noArguments(rest);
+        io.out(`${CLI_VERSION}\n`);
+        return 0;
+      case "-h":
+      case "--help":
+        noArguments(rest);
+        io.out(USAGE);
+        return 0;
+      case "help":
+        return help(io, rest);
+      case undefined:
+        io.err(USAGE);
+        return 2;
+      default:
+        throw new CliError(`Unknown command ${JSON.stringify(command)}.`, 2);
+    }
+  } catch (error) {
+    if (!(error instanceof CliError)) throw error;
+    io.err(`tscomfy: ${error.message}\n`);
+    if (error.exitCode === 2) {
+      io.err(`\n${USAGES.get(command ?? "") ?? USAGE}`);
+    }
+    return error.exitCode;
+  }
+}
+
+/** `tscomfy help [<command>]`: the usage, or a command's. */
+function help(io: Io, args: readonly string[]): number {
+  const [topic, ...rest] = args;
+  noArguments(rest);
+  if (topic === undefined) {
+    io.out(USAGE);
+    return 0;
+  }
+  const usage = USAGES.get(topic);
+  if (usage === undefined) throw new CliError(`Unknown command ${JSON.stringify(topic)}.`, 2);
+  io.out(usage);
+  return 0;
+}
+
+function noArguments(args: readonly string[]): void {
+  const [extra] = args;
+  if (extra !== undefined) throw new CliError(`Unexpected argument ${JSON.stringify(extra)}.`, 2);
+}

package/src/source.ts

@@ -0,0 +1,114 @@
+import { type Diagnostic, normalizeObjectInfo, type Schema } from "@tscomfy/core";
+import { type Flags, value } from "./args.ts";
+import { type Io, CliError } from "./io.ts";
+import { errorBodyMessage, flagWords, redactUrl } from "./util.ts";
+
+/** Where node definitions come from: a server, or a saved `/object_info` response. */
+export interface Source {
+  /** The `/object_info` text, exactly as served or saved. */
+  readonly text: string;
+  readonly comfyVersion?: string;
+  /** For messages: the server or the file. */
+  readonly label: string;
+  /** For the regenerate command in headers: `--url <server>` or `--from <file>`. */
+  readonly flag: string;
+}
+
+/**
+ * Reads `--url` (GET `/object_info`, and `/system_stats` for the version) or `--from`. Exactly
+ * one must be given. Only read-only GETs: tscomfy never queues anything.
+ */
+export async function readSource(io: Io, flags: Flags): Promise<Source> {
+  const url = value(flags, "url");
+  const from = value(flags, "from");
+  if ((url === undefined) === (from === undefined)) {
+    throw new CliError("Give either --url <server> or --from <object_info.json>.", 2);
+  }
+  if (from !== undefined) {
+    const text = await io.readText(from);
+    if (text === undefined) throw new CliError(`There is no file at ${from}.`);
+    const comfyVersion = value(flags, "comfy-version");
+    return {
+      text,
+      ...(comfyVersion === undefined ? {} : { comfyVersion }),
+      label: from,
+      flag: flagWords("from", from),
+    };
+  }
+  const base = serverBase(url ?? "");
+  const shown = redactUrl(base).replace(/\/+$/, "");
+  const text = await io.fetchText(endpoint(base, "object_info"));
+  const comfyVersion = await readComfyVersion(io, endpoint(base, "system_stats"));
+  return {
+    text,
+    ...(comfyVersion === undefined ? {} : { comfyVersion }),
+    label: shown,
+    flag: flagWords("url", shown),
+  };
+}
+
+/**
+ * The server URL. Credentials and the query (which often carries a token) are sent with each
+ * request but never shown: messages and generated headers use {@link redactUrl}.
+ */
+function serverBase(url: string): URL {
+  // Not echoed: an unparseable URL may still hold a password.
+  if (!URL.canParse(url)) throw new CliError("--url is not a valid URL.", 2);
+  const parsed = new URL(url);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new CliError(`${redactUrl(parsed)} is not an http(s) URL.`, 2);
+  }
+  if (parsed.hash !== "") {
+    throw new CliError("--url can't have a #fragment: it never reaches the server.", 2);
+  }
+  return parsed;
+}
+
+/** An endpoint under the server's path, keeping its query: `http://h/api/?t=1` → `…/api/x?t=1`. */
+function endpoint(base: URL, name: string): string {
+  const url = new URL(base.href);
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}/${name}`;
+  return url.href;
+}
+
+/** The ComfyUI version from `/system_stats`; optional, so a failure only loses the version. */
+async function readComfyVersion(io: Io, url: string): Promise<string | undefined> {
+  try {
+    const stats: unknown = JSON.parse(await io.fetchText(url));
+    const system: unknown =
+      typeof stats === "object" && stats !== null ? Reflect.get(stats, "system") : undefined;
+    const version: unknown =
+      typeof system === "object" && system !== null
+        ? Reflect.get(system, "comfyui_version")
+        : undefined;
+    return typeof version === "string" ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The normalized schema of a source. A response that holds no usable node at all (not JSON, not
+ * an object, an error body such as `{"detail": "Not authenticated"}`, or `{}`) is fatal, so it
+ * can't replace good types; anything less is reported and the rest generated.
+ */
+export function loadSchema(source: Source): {
+  readonly schema: Schema;
+  readonly diagnostics: readonly Diagnostic[];
+} {
+  const result = normalizeObjectInfo(
+    source.text,
+    source.comfyVersion === undefined ? {} : { comfyVersion: source.comfyVersion },
+  );
+  if (Object.keys(result.schema.nodes).length === 0) {
+    const detail = errorBodyMessage(source.text);
+    if (detail !== undefined) {
+      throw new CliError(`${source.label} is an error response, not node definitions: ${detail}.`);
+    }
+    const error = result.diagnostics.find((diagnostic) => diagnostic.severity === "error");
+    throw new CliError(
+      `${source.label} doesn't hold node definitions${error === undefined ? "" : `: ${error.message}`}`,
+    );
+  }
+  return result;
+}

package/src/transpile.ts

@@ -0,0 +1,201 @@
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import {
+  CODEGEN_VERSION,
+  exportNameProblem,
+  transpile,
+  transpileNameProblem,
+} from "@tscomfy/codegen";
+import { hashSchema, importApi, importUi, type JsonValue, parse, typedSchema } from "@tscomfy/core";
+import { type Flags, HELP, parseFlags, required, value } from "./args.ts";
+import { CliError, type Io } from "./io.ts";
+import { MANIFEST, readGenerated, SNAPSHOT } from "./manifest.ts";
+import { count, formatDiagnostic } from "./report.ts";
+import { camelName, flagWords, isRecord } from "./util.ts";
+
+/** `tscomfy transpile --help`. */
+export const TRANSPILE_USAGE: string = `Usage: tscomfy transpile (--prompt <prompt.json> | --workflow <workflow.json>) --schema <dir> [options]
+
+Turns an API-format prompt (the frontend's "Export (API)"), or a UI workflow (its "Save" or
+"Export"), into TypeScript that builds it with the types \`tscomfy generate\` wrote into <dir>.
+Running the code and exporting gives the prompt back: for a UI workflow, the prompt the frontend
+would queue for it, with Reroutes, PrimitiveNodes and subgraphs resolved. Nodes the types can't
+express are written as raw(…), with a warning.
+
+Options:
+  --prompt <file>      The prompt to transpile.
+  --workflow <file>    The UI workflow to transpile, instead of a prompt.
+  --schema <dir>       The directory \`tscomfy generate\` wrote (it reads ${SNAPSHOT} and ${MANIFEST}).
+  --out <file>         Where to write the module. Default: standard output, importing the
+                       schema relative to the current directory.
+  --name <identifier>  The exported constant. Default: from the file name, camelCased
+                       (My Txt2Img.json → myTxt2Img).
+  --no-inline          Give every node a variable, rather than inlining those used once.
+  -h, --help           Show this help.
+
+The header records the command that transpiles the file again, for a POSIX shell in the
+directory transpile ran in. A value that starts with - is written --flag=<value>.
+`;
+
+const FLAGS = [
+  { name: "prompt", takesValue: true },
+  { name: "workflow", takesValue: true },
+  { name: "schema", takesValue: true },
+  { name: "out", takesValue: true },
+  { name: "name", takesValue: true },
+  { name: "no-inline", takesValue: false },
+  HELP,
+] as const;
+
+/** `tscomfy transpile`. */
+export async function transpileCommand(io: Io, args: readonly string[]): Promise<number> {
+  const flags = parseFlags(args, FLAGS);
+  if (flags.has("help")) {
+    io.out(TRANSPILE_USAGE);
+    return 0;
+  }
+  if (flags.has("prompt") && flags.has("workflow")) {
+    throw new CliError("Pass --prompt or --workflow, not both.", 2);
+  }
+  if (!flags.has("prompt") && !flags.has("workflow")) {
+    throw new CliError("--prompt or --workflow is required.", 2);
+  }
+  const kind = flags.has("workflow") ? "workflow" : "prompt";
+  const promptPath = required(flags, kind);
+  const schemaDir = required(flags, "schema");
+  const out = value(flags, "out");
+  const { manifest, schema } = await readGenerated(io, schemaDir);
+  const name = readName(flags, promptPath, manifest.exportName);
+  const text = await io.readText(promptPath);
+  if (text === undefined) throw new CliError(`There is no file at ${promptPath}.`);
+
+  // The types in <dir> must be the ones this version would write, or the code won't fit them.
+  if (manifest.codegen !== CODEGEN_VERSION || manifest.schema !== hashSchema(schema)) {
+    throw new CliError(
+      `${schemaDir} was generated by another version of tscomfy; run tscomfy generate again first.`,
+    );
+  }
+  const what = kind === "prompt" ? "a prompt" : "a UI workflow";
+  const mixUp = kind === "prompt" ? notAPrompt(text) : notAWorkflow(text);
+  if (mixUp !== undefined) throw new CliError(`${promptPath} isn't ${what}: ${mixUp}`);
+  const typed = typedSchema(schema);
+  const imported = kind === "prompt" ? importApi(text, typed) : importUi(text, typed);
+  const fatal = imported.diagnostics.find(
+    (diagnostic) =>
+      diagnostic.path.length === 0 &&
+      (diagnostic.code === "E_INVALID_JSON" ||
+        diagnostic.code === "E_INVALID_PROMPT" ||
+        diagnostic.code === "E_INVALID_WORKFLOW"),
+  );
+  if (fatal !== undefined) {
+    throw new CliError(`${promptPath} isn't ${what}: ${fatal.message}`);
+  }
+  if (imported.workflow.graph.nodes.size === 0) {
+    throw new CliError(`${promptPath} isn't ${what}: it has no node that can be read.`);
+  }
+  const command = [
+    "tscomfy transpile",
+    flagWords(kind, promptPath),
+    flagWords("schema", schemaDir),
+    ...(out === undefined ? [] : [flagWords("out", out)]),
+    ...(flags.has("name") ? [flagWords("name", name)] : []),
+    ...(flags.has("no-inline") ? ["--no-inline"] : []),
+  ].join(" ");
+  const result = transpile(imported.workflow, {
+    name,
+    schemaModule: moduleSpecifier(out, schemaDir, manifest.importExtension),
+    schemaName: manifest.exportName,
+    inline: !flags.has("no-inline"),
+    header: [`Regenerate with: ${command}`],
+  });
+
+  for (const diagnostic of [...imported.diagnostics, ...result.diagnostics]) {
+    io.err(`${formatDiagnostic(diagnostic)}\n`);
+  }
+  if (out === undefined) {
+    io.out(result.code);
+    return 0;
+  }
+  await io.writeText(out, result.code);
+  io.out(
+    `Transpiled ${count(imported.workflow.graph.nodes.size, "node")} from ${promptPath} into ${out}.\n`,
+  );
+  return 0;
+}
+
+/**
+ * What a file that isn't a prompt looks like instead, when it is a common mix-up: the frontend's
+ * UI workflow (`nodes` and `links`), or a `POST /prompt` body (`{ "prompt": … }`).
+ */
+function notAPrompt(text: string): string | undefined {
+  const parsed = parse(text).value;
+  if (parsed === undefined || !isRecord(parsed)) return undefined;
+  if (isUiWorkflow(parsed)) return "it is a UI workflow; pass it with --workflow instead.";
+  // A node with the id "prompt" has a class_type; a POST /prompt body's prompt doesn't.
+  const prompt = parsed["prompt"];
+  if (prompt !== undefined && isRecord(prompt) && !Object.hasOwn(prompt, "class_type")) {
+    return "it is a POST /prompt body; save its prompt on its own.";
+  }
+  return undefined;
+}
+
+/** What a file passed as a UI workflow looks like instead: a prompt, or a `POST /prompt` body. */
+function notAWorkflow(text: string): string | undefined {
+  const parsed = parse(text).value;
+  if (parsed === undefined || !isRecord(parsed) || isUiWorkflow(parsed)) return undefined;
+  const nodes = Object.values(parsed);
+  if (nodes.length > 0 && nodes.every((node) => isRecord(node) && "class_type" in node)) {
+    return "it is an API prompt; pass it with --prompt instead.";
+  }
+  if (Object.hasOwn(parsed, "prompt")) {
+    return "it is a POST /prompt body; save its prompt on its own and pass it with --prompt.";
+  }
+  return undefined;
+}
+
+function isUiWorkflow(parsed: { readonly [key: string]: JsonValue }): boolean {
+  return Array.isArray(parsed["nodes"]) && Array.isArray(parsed["links"]);
+}
+
+/**
+ * How the module imports the schema: relative to where it is written (the current directory
+ * without --out), with POSIX separators.
+ */
+function moduleSpecifier(out: string | undefined, schemaDir: string, extension: string): string {
+  const from = out === undefined ? "." : dirname(out);
+  const target = relative(from, join(schemaDir, `index${extension}`));
+  // On another drive (Windows) there is no relative path.
+  if (isAbsolute(target)) {
+    throw new CliError(
+      "--schema and --out are on different drives; no relative import joins them.",
+    );
+  }
+  const posix = target.split(sep).join("/");
+  return posix.startsWith("./") || posix.startsWith("../") ? posix : `./${posix}`;
+}
+
+/**
+ * The export name: `--name`, or from the file name (`Anima-API.json` → `animaApi`, see
+ * `camelName`). The schema's name and this one must both be usable by `transpile`, by the rule
+ * `generate` checked the schema's with.
+ */
+function readName(flags: Flags, promptPath: string, schemaName: string): string {
+  const schemaProblem = exportNameProblem(schemaName);
+  if (schemaProblem !== undefined) {
+    // Generated before generate checked this.
+    throw new CliError(
+      `The schema's export name, ${schemaName}, won't do: ${schemaProblem}. Run tscomfy generate again with another --name.`,
+    );
+  }
+  const given = value(flags, "name");
+  const name = given ?? camelName(basename(promptPath).replace(/\.[^.]*$/, ""));
+  const problem = exportNameProblem(name) ?? transpileNameProblem({ name, schemaName });
+  if (problem !== undefined) {
+    throw new CliError(
+      given === undefined
+        ? `Can't name the export ${JSON.stringify(name)}, after ${JSON.stringify(promptPath)}: ${problem}; pass --name.`
+        : `--name ${JSON.stringify(given)} isn't usable: ${problem}.`,
+      2,
+    );
+  }
+  return name;
+}

package/src/util.ts

@@ -0,0 +1,87 @@
+import { type JsonValue, parse, stringify } from "@tscomfy/core";
+
+/** Whether a JSON value is an object (not null, not an array). */
+export function isRecord(value: JsonValue): value is { readonly [key: string]: JsonValue } {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A word for a POSIX shell, quoted only when it has to be: `out dir` → `'out dir'`. */
+export function shellQuote(word: string): string {
+  return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * `--name value` for a POSIX shell, as the CLI reads it back: `--name=value` when the value
+ * starts with `-`, which the separate form would take for a flag (`--out=--weird`).
+ */
+export function flagWords(name: string, value: string): string {
+  return value.startsWith("-")
+    ? `--${name}=${shellQuote(value)}`
+    : `--${name} ${shellQuote(value)}`;
+}
+
+/**
+ * An export name from a file or directory name, the same rule for `generate --out` and
+ * `transpile --prompt`: camelCase from the runs of ASCII letters and digits, a word in capitals
+ * lowercased, the first word starting lowercase and the others uppercase
+ * (`src/comfy/local` → `local`, `my-server` → `myServer`, `Anima-API.json` → `animaApi`).
+ * May be empty or start with a digit: callers check the result.
+ */
+export function camelName(text: string): string {
+  const words = text.match(/[A-Za-z0-9]+/g) ?? [];
+  return words
+    .map((word, index) => {
+      const lower = word === word.toUpperCase() ? word.toLowerCase() : word;
+      return index === 0
+        ? lower.charAt(0).toLowerCase() + lower.slice(1)
+        : lower.charAt(0).toUpperCase() + lower.slice(1);
+    })
+    .join("");
+}
+
+/** How much of an error body's message a message shows. */
+const SHOWN_DETAIL = 200;
+
+/**
+ * The message of an error body, when `text` is one rather than an answer: an object with a lone
+ * `detail`, `error` or `message` (`{"detail": "Not authenticated"}`, as auth proxies in front of
+ * ComfyUI send), whose value isn't a node definition. Shown as compact JSON, at most 200
+ * characters, with every control character escaped, so none reaches the terminal.
+ */
+export function errorBodyMessage(text: string): string | undefined {
+  const value = parse(text).value;
+  if (value === undefined || !isRecord(value)) return undefined;
+  const keys = Object.keys(value);
+  const [key] = keys;
+  if (keys.length !== 1 || (key !== "detail" && key !== "error" && key !== "message")) {
+    return undefined;
+  }
+  const message = value[key];
+  if (message === undefined || message === null) return undefined;
+  // A node class named `error` is an object with its inputs and outputs.
+  if (isRecord(message) && (Object.hasOwn(message, "input") || Object.hasOwn(message, "output"))) {
+    return undefined;
+  }
+  // `stringify` escapes C0 controls; DEL and C1 controls (a CSI is U+009B) are escaped here.
+  const shown = stringify(message).replaceAll(
+    /[\u007f-\u009f]/g,
+    (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+  if (shown.length <= SHOWN_DETAIL) return shown;
+  const cut = shown.slice(0, SHOWN_DETAIL);
+  // Not half a surrogate pair.
+  return `${/[\ud800-\udbff]$/.test(cut) ? cut.slice(0, -1) : cut}…`;
+}
+
+/**
+ * A URL fit for messages and generated files: without credentials, query or fragment, which is
+ * where servers expect passwords and tokens. `http://user:pw@host/api?token=t` → `http://host/api`.
+ */
+export function redactUrl(url: URL): string {
+  const shown = new URL(url.href);
+  shown.username = "";
+  shown.password = "";
+  shown.search = "";
+  shown.hash = "";
+  return shown.href;
+}