@field/cascade 0.10.0 → 0.11.0

package/dist/cli/graphFile-VPSQ6OF7.js

@@ -0,0 +1,286 @@
+import {
+  formatCompactJSON
+} from "./chunk-OWWBYLHC.js";
+import {
+  writeFileAtomic
+} from "./chunk-WPUDGEFY.js";
+import {
+  builtinModuleIds,
+  diagnoseGraph,
+  moduleDefinitions
+} from "./chunk-EUIAC3U3.js";
+import "./chunk-36P5K3SD.js";
+import "./chunk-D6BUOHUG.js";
+import "./chunk-RXDIMXN5.js";
+import "./chunk-QQPA2ZHH.js";
+import "./chunk-KH4MUBKF.js";
+import "./chunk-35D343DC.js";
+import "./chunk-DEQSEFFH.js";
+import "./chunk-HSNOBIVT.js";
+import "./chunk-ICH7N5PN.js";
+import "./chunk-GFS6W3C5.js";
+import "./chunk-HFHWYL55.js";
+import "./chunk-CO22XHNG.js";
+import "./chunk-RQZ4SX5R.js";
+import "./chunk-A4OAMOZH.js";
+import "./chunk-J7VK7MNF.js";
+import {
+  GraphEditError,
+  GraphEditor,
+  applyOperation
+} from "./chunk-XWDSKG7N.js";
+import "./chunk-BIJO5OFS.js";
+
+// src/cli/graphFile.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// src/cli/lineMerge.ts
+function matchLines(before, after, limit = 2e3) {
+  const n = before.length;
+  const m = after.length;
+  const max = Math.min(n + m, limit);
+  const offset = max + 1;
+  const frontier = new Int32Array(2 * max + 3);
+  const trace = [];
+  let found = false;
+  for (let d = 0; d <= max && !found; d += 1) {
+    trace.push(frontier.slice());
+    for (let k = -d; k <= d; k += 2) {
+      let x2 = k === -d || k !== d && frontier[offset + k - 1] < frontier[offset + k + 1] ? frontier[offset + k + 1] : frontier[offset + k - 1] + 1;
+      let y2 = x2 - k;
+      while (x2 < n && y2 < m && before[x2] === after[y2]) {
+        x2 += 1;
+        y2 += 1;
+      }
+      frontier[offset + k] = x2;
+      if (x2 >= n && y2 >= m) {
+        found = true;
+        break;
+      }
+    }
+  }
+  if (!found) return null;
+  const match = new Array(m).fill(-1);
+  let x = n;
+  let y = m;
+  for (let d = trace.length - 1; d >= 0 && (x > 0 || y > 0); d -= 1) {
+    const v = trace[d];
+    const k = x - y;
+    const down = k === -d || k !== d && v[offset + k - 1] < v[offset + k + 1];
+    const previousK = down ? k + 1 : k - 1;
+    const previousX = v[offset + previousK];
+    const previousY = previousX - previousK;
+    while (x > previousX && y > previousY) {
+      x -= 1;
+      y -= 1;
+      match[y] = x;
+    }
+    if (d > 0) {
+      x = previousX;
+      y = previousY;
+    }
+  }
+  return match;
+}
+function mergeLines(original, serializedBefore, after) {
+  let prefix = 0;
+  while (prefix < serializedBefore.length && prefix < after.length && serializedBefore[prefix] === after[prefix]) prefix += 1;
+  let suffix = 0;
+  while (suffix < serializedBefore.length - prefix && suffix < after.length - prefix && serializedBefore[serializedBefore.length - 1 - suffix] === after[after.length - 1 - suffix]) suffix += 1;
+  const middle = matchLines(
+    serializedBefore.slice(prefix, serializedBefore.length - suffix),
+    after.slice(prefix, after.length - suffix)
+  );
+  if (!middle) return null;
+  return after.map((line, index) => {
+    if (index < prefix) return original[index];
+    if (index >= after.length - suffix) return original[serializedBefore.length - (after.length - index)];
+    const matched = middle[index - prefix];
+    return matched >= 0 ? original[matched + prefix] : line;
+  });
+}
+
+// src/cli/graphFile.ts
+var STYLES = [
+  { name: "studio", asciiOnly: false, trailingNewline: false },
+  { name: "studio", asciiOnly: false, trailingNewline: true },
+  { name: "plain", asciiOnly: false, trailingNewline: false },
+  { name: "plain", asciiOnly: false, trailingNewline: true },
+  { name: "plain", asciiOnly: true, trailingNewline: false },
+  { name: "plain", asciiOnly: true, trailingNewline: true },
+  { name: "studio", asciiOnly: true, trailingNewline: false },
+  { name: "studio", asciiOnly: true, trailingNewline: true }
+];
+function serializeGraph(document, style) {
+  let text = JSON.stringify(document, null, 2);
+  if (style.name === "studio") text = formatCompactJSON(text, 2);
+  if (style.asciiOnly) text = text.replace(/[\u007f-￿]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+  return style.trailingNewline ? `${text}
+` : text;
+}
+function detectStyle(text, document) {
+  return STYLES.find((style) => serializeGraph(document, style) === text) ?? null;
+}
+function writeModeFor(text, document) {
+  const exact = detectStyle(text, document);
+  if (exact) return { kind: "exact", style: exact };
+  const lines = text.split("\n");
+  let best = null;
+  for (const style of STYLES) {
+    const candidate = serializeGraph(document, style).split("\n");
+    if (candidate.length !== lines.length) continue;
+    const differing = candidate.filter((line, index) => line !== lines[index]).length;
+    if (!best || differing < best.differing) best = { style, differing };
+  }
+  return best ? { kind: "aligned", style: best.style } : { kind: "rewrite", style: STYLES[1] };
+}
+var GraphFile = class _GraphFile {
+  constructor(file, original, document, mode) {
+    this.file = file;
+    this.original = original;
+    this.document = document;
+    this.mode = mode;
+    this.definitions = /* @__PURE__ */ new Map();
+    this.results = [];
+    this.warnings = [];
+    this.editor = new GraphEditor(document, { definitionOf: (id) => this.definitions.get(id) });
+  }
+  static async open(file) {
+    const resolved = path.resolve(file);
+    let text;
+    try {
+      text = await fs.readFile(resolved, "utf8");
+    } catch {
+      throw new GraphEditError(`No graph at ${resolved}; create one with "cascade graph create ${file}"`);
+    }
+    let document;
+    try {
+      document = JSON.parse(text);
+    } catch (error) {
+      throw new GraphEditError(`${resolved} is not valid JSON: ${error instanceof Error ? error.message : error}`);
+    }
+    const mode = writeModeFor(text, document);
+    const graph = new _GraphFile(resolved, text, document, mode);
+    if (mode.kind === "rewrite") {
+      graph.warnings.push(`${path.basename(resolved)} is not in a formatting the editor reproduces exactly; it will be rewritten in Studio's format on save`);
+    }
+    await graph.loadDefinitions(document.nodes.map((node) => String(node.module ?? node.type ?? "")));
+    return graph;
+  }
+  /** A new, empty graph file. Refuses to overwrite one that exists. */
+  static async create(file, options = {}) {
+    const resolved = path.resolve(file);
+    if (!resolved.endsWith(".cascade")) throw new GraphEditError(`A graph file ends in .cascade: ${file}`);
+    const document = {
+      version: "0.2",
+      metadata: { name: options.name ?? path.basename(resolved, ".cascade") },
+      nodes: []
+    };
+    await fs.mkdir(path.dirname(resolved), { recursive: true });
+    try {
+      await fs.writeFile(resolved, serializeGraph(document, STYLES[1]), { flag: "wx" });
+    } catch (error) {
+      if (error.code === "EEXIST") throw new GraphEditError(`${resolved} already exists`);
+      throw error;
+    }
+    return resolved;
+  }
+  /** Apply one operation. Nothing is written until `save`. */
+  async apply(operation) {
+    if (operation.op === "node.add") {
+      const module = await this.resolveModule(operation.module);
+      operation = { ...operation, module };
+    }
+    const before = this.editor.warnings.length;
+    const result = { op: operation.op, ...applyOperation(this.editor, operation) };
+    this.warnings.push(...this.editor.warnings.slice(before));
+    this.results.push(result);
+    return result;
+  }
+  /** Apply a batch. All or nothing: a failing operation leaves the file untouched. */
+  async applyAll(operations, options = {}) {
+    for (const [index, operation] of operations.entries()) {
+      try {
+        await this.apply(operation);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new GraphEditError(operations.length > 1 ? `Operation ${index + 1} (${operation.op}): ${message}` : message);
+      }
+    }
+    return this.save(options);
+  }
+  /**
+   * Validate and write. The edited graph is checked with the same code as
+   * `cascade check`, and refused if that finds a problem the original did not
+   * have — a graph that was already failing can still be repaired one edit at
+   * a time. The write is atomic, and refused if the file changed on disk since
+   * it was read (Studio saving, or another agent). `dryRun` validates and
+   * writes nothing.
+   */
+  async save(options = {}) {
+    const text = this.serialize();
+    const changed = text !== this.original;
+    if (changed) {
+      const [before, after] = await Promise.all([
+        diagnoseGraph(this.file, JSON.parse(this.original)),
+        diagnoseGraph(this.file, this.document)
+      ]);
+      const introduced = after.errors.filter((error) => !before.errors.includes(error));
+      if (introduced.length) {
+        throw new GraphEditError(`The edit was not saved; the graph would fail "cascade check":
+${introduced.map((error) => `  ${error}`).join("\n")}`);
+      }
+      this.warnings.push(...after.warnings.filter((warning) => !before.warnings.includes(warning)));
+      if (!options.dryRun) await this.writeAtomically(text);
+    }
+    return { results: this.results, warnings: [...new Set(this.warnings)], changed };
+  }
+  serialize() {
+    const text = serializeGraph(this.document, this.mode.style);
+    if (this.mode.kind !== "aligned") return text;
+    const before = serializeGraph(JSON.parse(this.original), this.mode.style).split("\n");
+    const merged = mergeLines(this.original.split("\n"), before, text.split("\n"));
+    return merged ? merged.join("\n") : text;
+  }
+  async writeAtomically(text) {
+    const current = await fs.readFile(this.file, "utf8");
+    if (current !== this.original) {
+      throw new GraphEditError(`${this.file} changed on disk while it was being edited; nothing was written. Run the command again.`);
+    }
+    const { mode } = await fs.stat(this.file);
+    await writeFileAtomic(this.file, text, { mode });
+  }
+  async loadDefinitions(ids) {
+    const missing = ids.filter((id) => id && !this.definitions.has(id));
+    if (!missing.length) return;
+    for (const [id, definition] of await moduleDefinitions(this.file, missing)) this.definitions.set(id, definition);
+  }
+  /**
+   * The module a `node add` names. A full id is used as given; a short name is
+   * looked up as a project node (`nodes/<Name>/`) first, then as a built-in
+   * (`Circle` is `cascade.geo.Circle`). A module with no static definition is
+   * refused, because the editor could not check a single port or parameter on it.
+   */
+  async resolveModule(name) {
+    const candidates = name.includes(".") ? [name] : [`project.${name}`, ...builtinModuleIds().filter((id) => id.slice(id.lastIndexOf(".") + 1).toLowerCase() === name.toLowerCase())];
+    await this.loadDefinitions(candidates);
+    const found = candidates.filter((id) => this.definitions.get(id));
+    if (found.length > 1 && !name.includes(".")) {
+      throw new GraphEditError(`"${name}" is ambiguous: ${found.join(", ")}`);
+    }
+    if (found[0]) return found[0];
+    const near = builtinModuleIds().filter((id) => id.toLowerCase().includes(name.toLowerCase().replace(/^.*\./, ""))).slice(0, 6);
+    throw new GraphEditError(
+      `No node type "${name}" with a static definition: not a built-in, and no nodes/${name.replace(/^project\./, "")}/index.ts exporting \`definition\` in ${path.dirname(this.file)}` + (near.length ? `. Similar: ${near.join(", ")}` : '. "cascade inspect" lists what a graph uses; doc/NODE_REFERENCE.md lists the built-ins')
+    );
+  }
+};
+var openGraph = (file) => GraphFile.open(file);
+export {
+  GraphFile,
+  detectStyle,
+  openGraph,
+  serializeGraph
+};
+//# sourceMappingURL=graphFile-VPSQ6OF7.js.map

package/dist/cli/headlessCanvas-5XLDZT7M.js

@@ -0,0 +1,15 @@
+import {
+  CANVAS_PACKAGE,
+  MISSING_CANVAS_MESSAGE,
+  MissingCanvasError,
+  canvasAvailable,
+  installHeadlessCanvas
+} from "./chunk-WIH4TEIS.js";
+export {
+  CANVAS_PACKAGE,
+  MISSING_CANVAS_MESSAGE,
+  MissingCanvasError,
+  canvasAvailable,
+  installHeadlessCanvas
+};
+//# sourceMappingURL=headlessCanvas-5XLDZT7M.js.map

package/dist/cli/helpCommand-3VRE3KVO.js

@@ -0,0 +1,155 @@
+import {
+  headlessBuiltin,
+  headlessBuiltinRegistrations
+} from "./chunk-36P5K3SD.js";
+import "./chunk-D6BUOHUG.js";
+import "./chunk-RXDIMXN5.js";
+import "./chunk-QQPA2ZHH.js";
+import "./chunk-KH4MUBKF.js";
+import "./chunk-35D343DC.js";
+import "./chunk-DEQSEFFH.js";
+import "./chunk-HSNOBIVT.js";
+import "./chunk-J7VK7MNF.js";
+
+// src/cli/helpCommand.ts
+import fs from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+var HELP_NODE_USAGE = "cascade help node [<type>] [--project <dir>] [--json]";
+async function runHelpCommand(args) {
+  const json = args.includes("--json");
+  const projectIndex = args.indexOf("--project");
+  const project = path.resolve(projectIndex === -1 ? "." : args[projectIndex + 1] ?? ".");
+  const operands = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--project") index += 1;
+    else if (!args[index].startsWith("-")) operands.push(args[index]);
+  }
+  const [, topic, type] = operands;
+  if (topic !== "node") {
+    const { mainHelp } = await import("./verbs-RCE3K4VQ.js");
+    console.log(mainHelp());
+    return;
+  }
+  if (!type) {
+    const nodes = await listNodes(project);
+    if (json) print({ nodes });
+    else console.log(nodes.map((node) => `  ${node.module.padEnd(28)}${node.summary}`).join("\n") + `
+
+${HELP_NODE_USAGE}`);
+    return;
+  }
+  const found = await findNode(type, project);
+  if (found) {
+    if (json) print(found);
+    else console.log(formatNode(found));
+    return;
+  }
+  const studio = studioNode(type);
+  if (studio) {
+    const message = `${type} is a class-based Studio node (${studio}): it has no static definition to print. Its ports are in Studio's Definition panel; doc/NODE_REFERENCE.md in this package lists it.`;
+    if (json) print({ module: type, source: "studio", message });
+    else console.log(message);
+    return;
+  }
+  const near = (await listNodes(project)).map((node) => node.module).filter((id) => id.toLowerCase().includes(type.toLowerCase().replace(/^.*\./, ""))).slice(0, 6);
+  throw new Error(`No node type "${type}".${near.length ? ` Did you mean ${near.join(", ")}?` : ""} cascade help node lists them all.`);
+}
+function print(data) {
+  process.stdout.write(`${JSON.stringify(data)}
+`);
+}
+async function findNode(type, project) {
+  const exact = headlessBuiltin(type);
+  if (exact) return { module: exact.moduleId, source: "builtin", definition: exact.definition };
+  const name = type.slice(type.lastIndexOf(".") + 1);
+  if (!type.includes(".") || type.startsWith("project.")) {
+    const local = await projectDefinition(project, name);
+    if (local) return { module: `project.${name}`, source: "project", definition: local };
+  }
+  if (type.includes(".")) return void 0;
+  const short = headlessBuiltinRegistrations.filter((registration) => registration.moduleId.slice(registration.moduleId.lastIndexOf(".") + 1).toLowerCase() === name.toLowerCase());
+  return short.length === 1 ? { module: short[0].moduleId, source: "builtin", definition: short[0].definition } : void 0;
+}
+async function projectDefinition(project, name) {
+  if (!existsSync(path.join(project, "nodes", name, "index.ts"))) return void 0;
+  const { moduleDefinitions } = await import("./projectRuntime-Z5PJOH47.js");
+  const definitions = await moduleDefinitions(path.join(project, "index.cascade"), [`project.${name}`]);
+  return definitions.get(`project.${name}`);
+}
+async function listNodes(project) {
+  const summary = (definition) => [definition.label, definition.description].filter(Boolean).join(" \u2014 ");
+  const builtins = headlessBuiltinRegistrations.map((registration) => ({ module: registration.moduleId, summary: summary(registration.definition) }));
+  let names = [];
+  try {
+    names = (await fs.readdir(path.join(project, "nodes"), { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  } catch {
+  }
+  const local = [];
+  for (const name of names) {
+    const definition = await projectDefinition(project, name).catch(() => void 0);
+    local.push({ module: `project.${name}`, summary: definition ? summary(definition) : "(dynamic or unreadable definition)" });
+  }
+  return [...builtins.sort((a, b) => a.module.localeCompare(b.module)), ...local];
+}
+function formatNode({ module, source, definition }) {
+  const lines = [`${module}${definition.label ? ` \u2014 ${definition.label}` : ""}${source === "project" ? " (project node)" : ""}`];
+  if (definition.description) lines.push(definition.description);
+  lines.push("", `Runs on ${definition.runsOn}.${definition.capabilities?.length ? ` Capabilities: ${definition.capabilities.join(", ")}.` : ""}`);
+  for (const [heading, group] of [["Inputs", definition.inputs], ["Props", definition.props], ["Outputs", definition.outputs]]) {
+    const entries = Object.entries(group ?? {});
+    if (!entries.length) continue;
+    lines.push("", `${heading}:`);
+    for (const [name, port] of entries) lines.push(`  ${describePort(name, port)}`);
+  }
+  const firstInput = Object.keys(definition.inputs ?? {})[0];
+  const firstOutput = Object.keys(definition.outputs ?? {})[0];
+  const firstProp = Object.keys(definition.props ?? {})[0];
+  lines.push("", "Use:", `  cascade node add <graph> ${module}`);
+  if (firstOutput) lines.push(`  cascade connect <graph> <node>.${firstOutput} <other>.<input>`);
+  if (firstInput) lines.push(`  cascade connect <graph> <other>.<output> <node>.${firstInput}`);
+  if (firstProp) lines.push(`  cascade set <graph> <node>.${firstProp} <value>`);
+  return lines.join("\n");
+}
+function describePort(name, port) {
+  if (port.kind === "trigger") return `${name}  trigger`;
+  const parts = [`${name}  ${String(port.type)}`];
+  if ("default" in port) parts.push(`default ${JSON.stringify(port.default)}`);
+  if (port.min !== void 0 || port.max !== void 0) parts.push(`range ${port.min ?? ""}\u2026${port.max ?? ""}`);
+  if (Array.isArray(port.options)) parts.push(`options ${port.options.map((option) => JSON.stringify(option?.value ?? option)).join(" | ")}`);
+  if (port.expression) parts.push(`expression ${String(port.expression)}`);
+  const line = parts.join(", ");
+  return port.description ? `${line}  \u2014 ${String(port.description)}` : line;
+}
+function studioNode(type) {
+  const reference = referenceFile();
+  if (!reference) return void 0;
+  const text = readFileSync(reference, "utf8");
+  const studio = text.slice(text.indexOf("## Studio node libraries"));
+  const name = type.slice(type.lastIndexOf(".") + 1);
+  const library = /^### (.+?) — `(cascade\.[a-z]+)\.\*`/gm;
+  let match;
+  const sections = [];
+  while (match = library.exec(studio)) sections.push({ label: match[1], namespace: match[2], at: match.index });
+  for (const [index, section] of sections.entries()) {
+    const body = studio.slice(section.at, sections[index + 1]?.at ?? studio.length);
+    if (type.includes(".") && !type.startsWith(`${section.namespace}.`)) continue;
+    if (body.includes(`\`${name}\``)) return `${section.namespace}.${name}, ${section.label} library`;
+  }
+  return void 0;
+}
+function referenceFile() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [path.resolve(here, "..", "..", "doc", "NODE_REFERENCE.md"), path.resolve(here, "..", "doc", "NODE_REFERENCE.md")]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return void 0;
+}
+export {
+  HELP_NODE_USAGE,
+  findNode,
+  formatNode,
+  runHelpCommand
+};
+//# sourceMappingURL=helpCommand-3VRE3KVO.js.map