@tscomfy/cli 0.0.0-stage → 0.1.0

package/src/check.ts

@@ -0,0 +1,224 @@
+import { join } from "node:path";
+import { CODEGEN_VERSION } from "@tscomfy/codegen";
+import {
+  diffSchemas,
+  hashSchema,
+  type InputChange,
+  type NodeChange,
+  type Schema,
+  type SchemaDiff,
+} from "@tscomfy/core";
+import { HELP, parseFlags, required } from "./args.ts";
+import { regenerateCommand } from "./generate.ts";
+import type { Io } from "./io.ts";
+import { contentHash, FILES, MANIFEST, readGenerated, SNAPSHOT } from "./manifest.ts";
+import { count } from "./report.ts";
+import { loadSchema, readSource } from "./source.ts";
+
+/** `tscomfy check --help`. */
+export const CHECK_USAGE: string = `Usage: tscomfy check (--url <server> | --from <object_info.json>) --out <dir>
+
+Compares the server's node definitions with the snapshot in <dir>/${SNAPSHOT}, and checks
+that the files in <dir> are exactly what \`tscomfy generate\` wrote (<dir>/${MANIFEST}). Exits
+with 1 when anything differs, so it can guard a build. New files in upload and remote combos
+(an uploaded image) are runtime state, not drift.
+
+Options:
+  --url <server>   A ComfyUI server, e.g. http://127.0.0.1:8188. Only GET requests.
+  --from <file>    A saved /object_info response instead of a server.
+  --out <dir>      The directory \`tscomfy generate\` wrote.
+  --verbose        List every changed node, input and combo option, rather than the first few.
+  -h, --help       Show this help.
+`;
+
+const FLAGS = [
+  { name: "url", takesValue: true },
+  { name: "from", takesValue: true },
+  { name: "out", takesValue: true },
+  { name: "verbose", takesValue: false },
+  HELP,
+] as const;
+
+/** How many node and input names a list shows before the rest are counted, unless verbose. */
+const SHOWN_NAMES = 10;
+
+/** How many combo options a change lists before the rest are counted, unless verbose. */
+const SHOWN_OPTIONS = 5;
+
+/** What follows a count of entries left out. */
+const MORE = " (--verbose shows all)";
+
+/** `tscomfy check`. */
+export async function checkCommand(io: Io, args: readonly string[]): Promise<number> {
+  const flags = parseFlags(args, FLAGS);
+  if (flags.has("help")) {
+    io.out(CHECK_USAGE);
+    return 0;
+  }
+  const out = required(flags, "out");
+  const verbose = flags.has("verbose");
+  const { manifest, snapshotPath, snapshotText, schema: snapshot } = await readGenerated(io, out);
+  const source = await readSource(io, flags);
+  const current = loadSchema(source).schema;
+
+  // Files that don't hash as recorded were edited, removed or left half-written.
+  const stale: string[] = [];
+  for (const file of FILES) {
+    const hash = manifest.files[file];
+    // Sequential: a few small reads, and a stable order for the message.
+    // oxlint-disable-next-line no-await-in-loop
+    const text = file === SNAPSHOT ? snapshotText : await io.readText(join(out, file));
+    if (text === undefined || contentHash(text) !== hash) stale.push(file);
+  }
+  // Another codegen, or another core normalizing the same snapshot differently.
+  const outdated = manifest.codegen !== CODEGEN_VERSION || manifest.schema !== hashSchema(snapshot);
+  const { diff, runtime } = withoutRuntimeOptions(diffSchemas(snapshot, current), current);
+  const drifted = diff.added.length + diff.removed.length + diff.changed.length > 0;
+
+  const ignored =
+    runtime.length === 0
+      ? ""
+      : ` (changed files in ${count(runtime.length, "upload or remote combo")} aren't drift: ${listed(runtime, verbose, SHOWN_NAMES)})`;
+  if (!drifted && stale.length === 0 && !outdated) {
+    const nodes = Object.keys(current.nodes).length;
+    io.out(
+      `Up to date: ${count(nodes, "node type")} ${nodes === 1 ? "matches" : "match"} ${snapshotPath}${ignored}.\n`,
+    );
+    return 0;
+  }
+  const lines: string[] = [];
+  if (stale.length > 0) {
+    lines.push(
+      `${list(stale)} in ${out} ${stale.length === 1 ? "isn't" : "aren't"} what tscomfy generate wrote: edited, missing, or from an interrupted run.`,
+    );
+  }
+  if (outdated) {
+    lines.push(
+      manifest.codegen === CODEGEN_VERSION
+        ? `${out} was generated by another version of tscomfy, which read the snapshot differently.`
+        : `${out} was generated by @tscomfy/codegen ${manifest.codegen}; this is ${CODEGEN_VERSION}.`,
+    );
+  }
+  if (drifted) {
+    lines.push(
+      `${source.label} differs from ${snapshotPath}${ignored}:`,
+      ...formatDiff(diff, verbose),
+    );
+  }
+  const command = regenerateCommand({
+    flag: source.flag,
+    out,
+    exportName: manifest.exportName,
+    importExtension: manifest.importExtension,
+    // With --url, the server says again.
+    ...(flags.has("from") && manifest.comfyVersion !== undefined
+      ? { comfyVersion: manifest.comfyVersion }
+      : {}),
+  });
+  lines.push(`Run ${command} to update.`);
+  io.out(`${lines.join("\n")}\n`);
+  return 1;
+}
+
+/**
+ * The diff without option changes of upload and remote combos (docs/plan.md §6.5): their options
+ * are the server's files, which change with every upload, and the types take any string there.
+ * Also returns those inputs, as `Class.input`.
+ */
+function withoutRuntimeOptions(
+  diff: SchemaDiff,
+  current: Schema,
+): { readonly diff: SchemaDiff; readonly runtime: readonly string[] } {
+  const runtime: string[] = [];
+  const changed: NodeChange[] = [];
+  for (const change of diff.changed) {
+    const inputs = current.nodes[change.classType]?.inputs ?? [];
+    const kept = change.inputsChanged.filter((input: InputChange) => {
+      const definition = inputs.find((each) => each.name === input.name);
+      const runtimeOnly =
+        !input.specChanged &&
+        definition?.kind === "combo" &&
+        (definition.upload || definition.remote);
+      if (runtimeOnly) runtime.push(`${change.classType}.${input.name}`);
+      return !runtimeOnly;
+    });
+    const rest = { ...change, inputsChanged: kept };
+    const empty =
+      kept.length === 0 &&
+      rest.inputsAdded.length === 0 &&
+      rest.inputsRemoved.length === 0 &&
+      !rest.outputsChanged &&
+      !rest.detailsChanged;
+    if (!empty) changed.push(rest);
+  }
+  return { diff: { ...diff, changed }, runtime };
+}
+
+/**
+ * The diff as indented lines: every list (nodes, inputs, options, changed nodes) cut to its
+ * first few entries unless `verbose`, so a server that differs a lot still gives short lines.
+ */
+function formatDiff(diff: SchemaDiff, verbose: boolean): string[] {
+  const lines: string[] = [];
+  if (diff.added.length > 0) {
+    lines.push(
+      `  + ${count(diff.added.length, "node")} added: ${listed(diff.added, verbose, SHOWN_NAMES)}`,
+    );
+  }
+  if (diff.removed.length > 0) {
+    lines.push(
+      `  - ${count(diff.removed.length, "node")} removed: ${listed(diff.removed, verbose, SHOWN_NAMES)}`,
+    );
+  }
+  if (diff.changed.length > 0) {
+    lines.push(`  ~ ${count(diff.changed.length, "node")} changed:`);
+    const shown = verbose ? diff.changed : diff.changed.slice(0, SHOWN_NAMES);
+    for (const change of shown) lines.push(...formatChange(change, verbose));
+    if (shown.length < diff.changed.length) {
+      lines.push(`    … and ${String(diff.changed.length - shown.length)} more${MORE}`);
+    }
+  }
+  return lines;
+}
+
+function formatChange(change: NodeChange, verbose: boolean): string[] {
+  const lines = [`    ${change.classType}`];
+  if (change.inputsAdded.length > 0) {
+    lines.push(`      inputs added: ${listed(change.inputsAdded, verbose, SHOWN_NAMES)}`);
+  }
+  if (change.inputsRemoved.length > 0) {
+    lines.push(`      inputs removed: ${listed(change.inputsRemoved, verbose, SHOWN_NAMES)}`);
+  }
+  for (const input of change.inputsChanged) {
+    const options = (values: readonly (string | number | boolean)[]): string =>
+      listed(
+        values.map((option) => JSON.stringify(option)),
+        verbose,
+        SHOWN_OPTIONS,
+      );
+    const parts = [
+      ...(input.optionsAdded.length > 0 ? [`+ ${options(input.optionsAdded)}`] : []),
+      ...(input.optionsRemoved.length > 0 ? [`- ${options(input.optionsRemoved)}`] : []),
+      ...(input.specChanged ? ["spec changed"] : []),
+    ];
+    lines.push(`      ${input.name}: ${parts.join("; ")}`);
+  }
+  if (change.outputsChanged) lines.push("      outputs changed");
+  if (change.detailsChanged)
+    lines.push("      details changed (name, category, description, flags or order)");
+  return lines;
+}
+
+/** `a, b, c`, or the first `limit` and `… and 4 more (--verbose shows all)` unless `verbose`. */
+function listed(items: readonly string[], verbose: boolean, limit: number): string {
+  const shown = verbose ? items : items.slice(0, limit);
+  const rest = items.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")}, … and ${String(rest)} more${MORE}` : shown.join(", ");
+}
+
+/** `a`, `a and b`, `a, b and c`. */
+function list(items: readonly string[]): string {
+  return items.length <= 1
+    ? items.join("")
+    : `${items.slice(0, -1).join(", ")} and ${items.at(-1) ?? ""}`;
+}

package/src/generate.ts

@@ -0,0 +1,198 @@
+import { basename, dirname, join } from "node:path";
+import { CODEGEN_VERSION, exportNameProblem, generate } from "@tscomfy/codegen";
+import { hashSchema } from "@tscomfy/core";
+import { type Flags, HELP, parseFlags, required, value } from "./args.ts";
+import { CliError, type Io } from "./io.ts";
+import {
+  contentHash,
+  formatManifest,
+  MANIFEST,
+  type Manifest,
+  readManifest,
+  SNAPSHOT,
+} from "./manifest.ts";
+import { count, formatDiagnostic, reportDiagnostics, size } from "./report.ts";
+import { loadSchema, readSource, type Source } from "./source.ts";
+import { camelName, flagWords } from "./util.ts";
+
+/** `tscomfy generate --help`. */
+export const GENERATE_USAGE: string = `Usage: tscomfy generate (--url <server> | --from <object_info.json>) --out <dir> [options]
+
+Writes <dir>/nodes.ts (types), <dir>/index.ts (the typed schema), <dir>/${SNAPSHOT}
+(the raw response, for regenerating offline and for \`tscomfy check\`) and <dir>/${MANIFEST}
+(what was generated, for \`tscomfy check\` and \`tscomfy transpile\`).
+
+Options:
+  --url <server>             A ComfyUI server, e.g. http://127.0.0.1:8188. Only GET requests.
+                             Credentials and the query are sent, never written or shown.
+  --from <file>              A saved /object_info response instead of a server.
+  --out <dir>                The directory to write into.
+  --name <identifier>        The exported schema constant. Default: from the directory name,
+                             camelCased (my-server → myServer).
+  --import-extension <ext>   How index.ts imports nodes.ts: .js (default) or .ts.
+  --comfy-version <version>  The ComfyUI version to record, with --from. Default: the one
+                             recorded next to <file> when it is a snapshot generate wrote.
+  --verbose                  List every diagnostic.
+  --quiet                    Print errors only.
+  -h, --help                 Show this help.
+
+The headers record the command that regenerates the files, for a POSIX shell in the directory
+generate ran in. A value that starts with - is written --flag=<value>.
+`;
+
+const FLAGS = [
+  { name: "url", takesValue: true },
+  { name: "from", takesValue: true },
+  { name: "out", takesValue: true },
+  { name: "name", takesValue: true },
+  { name: "import-extension", takesValue: true },
+  { name: "comfy-version", takesValue: true },
+  { name: "verbose", takesValue: false },
+  { name: "quiet", takesValue: false },
+  HELP,
+] as const;
+
+/** `tscomfy generate`. */
+export async function generateCommand(io: Io, args: readonly string[]): Promise<number> {
+  const flags = parseFlags(args, FLAGS);
+  if (flags.has("help")) {
+    io.out(GENERATE_USAGE);
+    return 0;
+  }
+  const out = required(flags, "out");
+  const exportName = readName(flags, out);
+  const importExtension = readExtension(flags);
+  if (flags.has("comfy-version") && !flags.has("from")) {
+    throw new CliError("--comfy-version goes with --from; with --url it comes from the server.", 2);
+  }
+  if (flags.has("verbose") && flags.has("quiet")) {
+    throw new CliError("--verbose and --quiet don't go together.", 2);
+  }
+  const read = await readSource(io, flags);
+  const source = await withSnapshotVersion(io, flags, read);
+  const schema = loadSchema(source);
+
+  const command = regenerateCommand({
+    flag: source.flag,
+    out,
+    exportName,
+    importExtension,
+    // With --url, the server says again.
+    ...(flags.has("from") && source.comfyVersion !== undefined
+      ? { comfyVersion: source.comfyVersion }
+      : {}),
+  });
+  const result = generate(schema.schema, { exportName, importExtension, command });
+  const files = [...result.files, { path: SNAPSHOT, contents: source.text }];
+  await Promise.all(files.map((file) => io.writeText(join(out, file.path), file.contents)));
+  // Last: a run interrupted before this leaves a manifest that doesn't match the files.
+  const manifest: Manifest = {
+    codegen: CODEGEN_VERSION,
+    schema: hashSchema(schema.schema),
+    exportName,
+    importExtension,
+    ...(source.comfyVersion === undefined ? {} : { comfyVersion: source.comfyVersion }),
+    files: Object.fromEntries(files.map((file) => [file.path, contentHash(file.contents)])),
+  };
+  await io.writeText(join(out, MANIFEST), formatManifest(manifest));
+
+  const diagnostics = [...schema.diagnostics, ...result.diagnostics];
+  if (!flags.has("quiet")) {
+    const version =
+      schema.schema.comfyVersion === undefined ? "" : ` (ComfyUI ${schema.schema.comfyVersion})`;
+    io.out(
+      `Generated ${count(Object.keys(schema.schema.nodes).length, "node type")} from ${source.label}${version} into ${out}:\n` +
+        `  ${files.map((file) => `${file.path} ${size(byteLength(file.contents))}`).join(" · ")}\n`,
+    );
+    io.out(reportDiagnostics(diagnostics, schema.schema, source.text, flags.has("verbose")));
+  } else {
+    const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    for (const diagnostic of errors) io.err(`${formatDiagnostic(diagnostic)}\n`);
+  }
+  return 0;
+}
+
+/**
+ * `--from` a snapshot generate wrote, without `--comfy-version`: the version its manifest
+ * records, when the file is exactly the one recorded. Regenerating offline then keeps the
+ * version a `--url` run fetched. Anything else (another file, an edited snapshot, no manifest,
+ * or one that isn't ours) leaves the version unknown, as for any saved response.
+ */
+async function withSnapshotVersion(io: Io, flags: Flags, source: Source): Promise<Source> {
+  const from = value(flags, "from");
+  if (from === undefined || source.comfyVersion !== undefined || basename(from) !== SNAPSHOT) {
+    return source;
+  }
+  const manifest = await readManifest(io, dirname(from)).catch(() => undefined);
+  const recorded = manifest?.comfyVersion;
+  if (recorded === undefined || manifest?.files[SNAPSHOT] !== contentHash(source.text)) {
+    return source;
+  }
+  return { ...source, comfyVersion: recorded };
+}
+
+/** What regenerates a directory: the recorded options, from a given source. */
+export interface Regenerate {
+  /** `--url <server>` or `--from <file>`, as shell words. */
+  readonly flag: string;
+  readonly out: string;
+  readonly exportName: string;
+  readonly importExtension: ".js" | ".ts";
+  readonly comfyVersion?: string;
+}
+
+/** The `tscomfy generate` command for a POSIX shell; options at their defaults are left out. */
+export function regenerateCommand(options: Regenerate): string {
+  return [
+    "tscomfy generate",
+    options.flag,
+    flagWords("out", options.out),
+    ...(options.exportName === defaultName(options.out)
+      ? []
+      : [flagWords("name", options.exportName)]),
+    ...(options.importExtension === ".js" ? [] : [`--import-extension ${options.importExtension}`]),
+    ...(options.comfyVersion === undefined
+      ? []
+      : [flagWords("comfy-version", options.comfyVersion)]),
+  ].join(" ");
+}
+
+/** The export name from the output directory (see {@link camelName}), if it can be one. */
+function defaultName(out: string): string | undefined {
+  const name = camelName(basename(out));
+  return exportNameProblem(name) === undefined ? name : undefined;
+}
+
+function readName(flags: Flags, out: string): string {
+  const given = value(flags, "name");
+  if (given === undefined) {
+    const derived = defaultName(out);
+    if (derived === undefined) {
+      const name = camelName(basename(out));
+      const why =
+        name === "" ? "" : `: ${JSON.stringify(name)} won't do, ${exportNameProblem(name) ?? ""}`;
+      throw new CliError(
+        `Can't make an export name from ${JSON.stringify(out)}${why}; pass --name.`,
+        2,
+      );
+    }
+    return derived;
+  }
+  const problem = exportNameProblem(given);
+  if (problem !== undefined) {
+    throw new CliError(`--name ${JSON.stringify(given)} isn't usable: ${problem}.`, 2);
+  }
+  return given;
+}
+
+function readExtension(flags: Flags): ".js" | ".ts" {
+  const extension = value(flags, "import-extension") ?? ".js";
+  if (extension !== ".js" && extension !== ".ts") {
+    throw new CliError("--import-extension is .js or .ts.", 2);
+  }
+  return extension;
+}
+
+function byteLength(text: string): number {
+  return new TextEncoder().encode(text).length;
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @module @tscomfy/cli
+ *
+ * The `tscomfy` command: generate types from a ComfyUI server, check them for drift against a
+ * snapshot, and transpile API prompts and UI workflows to code. The only package with I/O,
+ * through `node:fs`, `node:crypto` and `fetch`, so it runs on Node and Bun.
+ * Exported for running the CLI in-process: `run(args, systemIo())`, or with an {@link Io} of
+ * your own, which reports failures as {@link CliError}s.
+ */
+
+export { CliError, type Io, systemIo } from "./io.ts";
+export { CLI_VERSION, run } from "./run.ts";

package/src/io.ts

@@ -0,0 +1,99 @@
+import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { errorBodyMessage, redactUrl } from "./util.ts";
+
+/** Everything the CLI does to the outside world, so commands can be tested without it. */
+export interface Io {
+  /** Writes to standard output. */
+  readonly out: (text: string) => void;
+  /** Writes to standard error. */
+  readonly err: (text: string) => void;
+  /**
+   * GETs a URL's body; throws a {@link CliError} for a network error or a non-2xx status (with
+   * the message of an error body, such as `{"detail": "Not authenticated"}`).
+   */
+  readonly fetchText: (url: string) => Promise<string>;
+  /** A file's text (UTF-8, without a byte order mark), or `undefined` when it doesn't exist. */
+  readonly readText: (path: string) => Promise<string | undefined>;
+  /** Replaces a file's contents in one step, creating its directory. */
+  readonly writeText: (path: string, text: string) => Promise<void>;
+}
+
+/** A failure to report to the user: a message, and the exit code to end with. */
+export class CliError extends Error {
+  /** 1 for a failure, 2 for a usage error. */
+  readonly exitCode: number;
+
+  /** A failure with `message`, ending the process with `exitCode`. */
+  constructor(message: string, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+const FETCH_TIMEOUT_MS = 60_000;
+
+/** The real world: the process's streams, `fetch` and `node:fs`, which Node and Bun both have. */
+export function systemIo(): Io {
+  return {
+    out: (text) => {
+      process.stdout.write(text);
+    },
+    err: (text) => {
+      process.stderr.write(text);
+    },
+    fetchText: async (url) => {
+      const shown = redactUrl(new URL(url));
+      try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (!response.ok) {
+          const answer = `${String(response.status)} ${response.statusText}`.trimEnd();
+          // Best effort: the status says what went wrong; the body may say why.
+          const body = await response.text().catch(() => "");
+          const detail = errorBodyMessage(body);
+          throw new CliError(
+            `${shown} answered ${answer}${detail === undefined ? "" : `: ${detail}`}`,
+          );
+        }
+        return await response.text();
+      } catch (error) {
+        if (error instanceof CliError) throw error;
+        throw new CliError(`Could not reach ${shown}: ${reason(error)}`);
+      }
+    },
+    readText: async (path) => {
+      try {
+        // TextDecoder drops a byte order mark, as editors that save one expect.
+        return new TextDecoder().decode(await readFile(path));
+      } catch (error) {
+        if (codeOf(error) === "ENOENT") return undefined;
+        throw new CliError(`Could not read ${path}: ${reason(error)}`);
+      }
+    },
+    writeText: async (path, text) => {
+      // Through a temporary file, so an interrupted run never leaves a file half written. One
+      // name per file, so a run that was killed leaves nothing a later run doesn't replace; and
+      // a symlink is followed, so the file it points to is the one replaced.
+      const target = await realpath(path).catch(() => path);
+      const temporary = `${target}.tmp`;
+      try {
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(temporary, text);
+        await rename(temporary, target);
+      } catch (error) {
+        // Best effort: when the directory can't be made, there is nothing to remove.
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw new CliError(`Could not write ${path}: ${reason(error)}`);
+      }
+    },
+  };
+}
+
+function reason(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function codeOf(error: unknown): unknown {
+  return typeof error === "object" && error !== null ? Reflect.get(error, "code") : undefined;
+}

package/src/main.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The `tscomfy` executable.
+
+import { systemIo } from "./io.ts";
+import { run } from "./run.ts";
+
+process.exitCode = await run(process.argv.slice(2), systemIo());

package/src/manifest.ts

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type { Schema } from "@tscomfy/core";
+import { CliError, type Io } from "./io.ts";
+import { loadSchema } from "./source.ts";
+
+/** The record `generate` writes last, next to the files, for `check` and `transpile`. */
+export const MANIFEST = "tscomfy.json";
+
+/** The raw snapshot written next to the generated files, for `--from` and `check`. */
+export const SNAPSHOT = "object_info.json";
+
+/**
+ * What one `generate` run wrote: the codegen version, the schema hash, the options needed to
+ * regenerate, and a content hash of every file, so `check` notices an edited, missing or
+ * half-written file and output from another version.
+ */
+export interface Manifest {
+  readonly codegen: string;
+  /** `hashSchema` of the snapshot (D15). */
+  readonly schema: string;
+  readonly exportName: string;
+  readonly importExtension: ".js" | ".ts";
+  /**
+   * The ComfyUI version of the snapshot, when known: the server's with `--url`, the
+   * `--comfy-version` given with `--from`. For regenerating from the snapshot, and for the
+   * command `check` suggests with `--from`.
+   */
+  readonly comfyVersion?: string;
+  /** `sha256:<hex>` of each file, by its name in the output directory: exactly {@link FILES}. */
+  readonly files: { readonly [file: string]: string };
+}
+
+/** The files a manifest covers, in the order `check` reports them. */
+export const FILES: readonly string[] = ["nodes.ts", "index.ts", SNAPSHOT];
+
+/** `sha256:<hex>` of a text's UTF-8 bytes. */
+export function contentHash(text: string): string {
+  return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+}
+
+/** The manifest's file contents: stable key order, one trailing newline. */
+export function formatManifest(manifest: Manifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/** The manifest in `out`, or `undefined` when there is none. Throws for one that isn't ours. */
+export async function readManifest(io: Io, out: string): Promise<Manifest | undefined> {
+  const path = join(out, MANIFEST);
+  const text = await io.readText(path);
+  if (text === undefined) return undefined;
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new CliError(`${path} is not JSON; run tscomfy generate again.`);
+  }
+  if (!isManifest(value)) {
+    throw new CliError(`${path} is not a tscomfy manifest; run tscomfy generate again.`);
+  }
+  return value;
+}
+
+function isManifest(value: unknown): value is Manifest {
+  if (typeof value !== "object" || value === null) return false;
+  const field = (name: string): unknown => Reflect.get(value, name);
+  const files = field("files");
+  const extension = field("importExtension");
+  const comfyVersion = field("comfyVersion");
+  return (
+    typeof field("codegen") === "string" &&
+    typeof field("schema") === "string" &&
+    typeof field("exportName") === "string" &&
+    (extension === ".js" || extension === ".ts") &&
+    (comfyVersion === undefined || typeof comfyVersion === "string") &&
+    typeof files === "object" &&
+    files !== null &&
+    // Exactly our files: a hand-edited list must not hide one, or name a path outside `out`.
+    Object.keys(files).toSorted().join("\n") === FILES.toSorted().join("\n") &&
+    Object.values(files).every((hash) => typeof hash === "string")
+  );
+}
+
+/** A directory `tscomfy generate` wrote: its manifest, and the snapshot normalized. */
+export interface Generated {
+  readonly manifest: Manifest;
+  readonly snapshotPath: string;
+  /** The snapshot's text, exactly as written. */
+  readonly snapshotText: string;
+  readonly schema: Schema;
+}
+
+/** The manifest and snapshot in `dir`; fails when either is missing, or isn't ours. */
+export async function readGenerated(io: Io, dir: string): Promise<Generated> {
+  const manifest = await readManifest(io, dir);
+  const snapshotPath = join(dir, SNAPSHOT);
+  const snapshotText = await io.readText(snapshotPath);
+  if (manifest === undefined || snapshotText === undefined) {
+    throw new CliError(
+      `There is no ${manifest === undefined ? MANIFEST : SNAPSHOT} in ${dir}; run tscomfy generate first.`,
+    );
+  }
+  const { schema } = loadSchema({ text: snapshotText, label: snapshotPath, flag: "" });
+  return { manifest, snapshotPath, snapshotText, schema };
+}