@darkhorseprojects/circuitry 0.2.33 → 0.2.99

package/dist/graph.d.ts

@@ -1,5 +1,5 @@
-export declare const CIRCUITRY_SPEC_VERSION: "0.2";
-export type CircuitrySpecVersion = typeof CIRCUITRY_SPEC_VERSION;
+export declare const CIRCUITRY_SPEC_VERSION: "0.2.99";
+export type CircuitrySpecVersion = typeof CIRCUITRY_SPEC_VERSION | "0.2";
 export type CircuitryNodeKind = "agent" | "input" | "tool" | "output" | string;
 export type CircuitryEdgeKind = "context" | "dependency" | "message" | "control" | string;
 export type CircuitryInputKind = "text" | "file" | "url" | "image" | "uri" | "canvas" | "mcp" | string;
@@ -170,12 +170,20 @@ export type CircuitryRuntimeInputs = Record<string, unknown>;
  * graph source stable and catches misspelled input names before execution.
  */
 export declare const applyCircuitryRuntimeInputs: (graph: CircuitryGraph, inputs?: CircuitryRuntimeInputs) => CircuitryGraph;
+export type CircuitryGraphLink = string | {
+    /** Path to another .circuitry.yaml/.json file, resolved relative to this file. */
+    path: string;
+    /** Optional id prefix applied to imported resources. */
+    prefix?: string;
+};
 export type CircuitryGraph = {
-    /** Spec version. Use "0.2" for new graphs. */
+    /** Spec version. Use "0.2.99" for linked graph files. */
     circuitry: CircuitrySpecVersion | string;
     id?: string;
     title?: string;
     description?: string;
+    /** Files whose resources are merged into this graph before validation/execution. */
+    links?: CircuitryGraphLink[];
     resources?: Record<string, CircuitryResourceEntry>;
     /** Internal normalized execution nodes. Authored graph files must not set this. */
     nodes?: CircuitryNode[];
@@ -215,7 +223,7 @@ export type CircuitryValidationResult = {
 };
 export declare const DEFAULT_CIRCUITRY_VALIDATION_RULES: CircuitryValidationRuleEntry[];
 export declare const DEFAULT_CIRCUITRY_VALIDATION_STANDARD: {
-    readonly version: "0.2";
+    readonly version: "0.2.99";
     readonly requireSpecVersion: true;
     readonly rules: CircuitryValidationRuleEntry[];
     readonly executableKinds: ["agent", "tool", "output"];

package/dist/index.js

@@ -27,7 +27,7 @@ var isNodeElement = (element) => {
 };
 
 // src/graph.ts
-var CIRCUITRY_SPEC_VERSION = "0.2";
+var CIRCUITRY_SPEC_VERSION = "0.2.99";
 var runtimeInputToText = (value) => {
   if (typeof value === "string") return value;
   if (value === void 0) return "";
@@ -136,7 +136,7 @@ var normalizeCircuitryGraph = (graph) => {
   const { nodes, edges } = expandResources(graph.resources);
   return { ...graph, nodes, edges };
 };
-var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set([CIRCUITRY_SPEC_VERSION]);
+var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set(["0.2", CIRCUITRY_SPEC_VERSION]);
 var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   const resolvedStandard = createCircuitryValidationStandard(
     standard,

package/dist/node.d.ts

@@ -8,6 +8,12 @@ export declare class NodeCircuitryHost implements CircuitryHost {
     private exists;
     private parseIssue;
     private parseGraphForValidation;
+    private linkPath;
+    private linkPrefix;
+    private prefixResourceIds;
+    private mergeResources;
+    private resolveGraphLinks;
+    private parseAndResolveGraph;
     private readGraphFile;
     readGraph(input?: {
         filename?: string;

package/dist/node.js

@@ -8,7 +8,7 @@ import os from "node:os";
 import YAML from "yaml";
 
 // src/graph.ts
-var CIRCUITRY_SPEC_VERSION = "0.2";
+var CIRCUITRY_SPEC_VERSION = "0.2.99";
 var runtimeInputToText = (value) => {
   if (typeof value === "string") return value;
   if (value === void 0) return "";
@@ -117,7 +117,7 @@ var normalizeCircuitryGraph = (graph) => {
   const { nodes, edges } = expandResources(graph.resources);
   return { ...graph, nodes, edges };
 };
-var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set([CIRCUITRY_SPEC_VERSION]);
+var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set(["0.2", CIRCUITRY_SPEC_VERSION]);
 var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   const resolvedStandard = createCircuitryValidationStandard(
     standard,
@@ -837,11 +837,84 @@ var NodeCircuitryHost = class {
       return { error: this.parseIssue(error, filename) };
     }
   }
+  linkPath(link) {
+    return typeof link === "string" ? link : link.path;
+  }
+  linkPrefix(link) {
+    return typeof link === "string" ? "" : link.prefix || "";
+  }
+  prefixResourceIds(resources, prefix) {
+    if (!prefix) return resources;
+    const ids = new Set(Object.keys(resources));
+    const prefixed = {};
+    for (const [id, resource] of Object.entries(resources)) {
+      const next = { ...resource };
+      if ((next.type === "agent" || next.type === "tool") && next.inputs) {
+        next.inputs = next.inputs.map((input) => ids.has(input) ? `${prefix}${input}` : input);
+      }
+      prefixed[`${prefix}${id}`] = next;
+    }
+    return prefixed;
+  }
+  mergeResources(target, source, fromFile) {
+    for (const [id, resource] of Object.entries(source)) {
+      if (target[id]) {
+        throw new Error(`Linked Circuitry resource id collision: ${id} from ${fromFile}`);
+      }
+      target[id] = resource;
+    }
+  }
+  async resolveGraphLinks(graph, filename, standard, stack = []) {
+    const graphFile = path.resolve(filename);
+    if (stack.includes(graphFile)) {
+      throw new Error(`Circuitry graph link cycle: ${[...stack, graphFile].join(" -> ")}`);
+    }
+    const linkedResources = {};
+    const nextStack = [...stack, graphFile];
+    for (const link of graph.links || []) {
+      const rawPath = this.linkPath(link);
+      if (!rawPath) throw new Error(`Circuitry graph link is missing path in ${graphFile}`);
+      const linkedFile = path.resolve(path.dirname(graphFile), rawPath);
+      const linkedText = await readFile(linkedFile, "utf8");
+      const parsed = parseCircuitryText(linkedText, linkedFile, standard, { validate: false });
+      const resolved = await this.resolveGraphLinks(parsed, linkedFile, standard, nextStack);
+      this.mergeResources(
+        linkedResources,
+        this.prefixResourceIds(resolved.resources || {}, this.linkPrefix(link)),
+        linkedFile
+      );
+    }
+    return {
+      ...graph,
+      resources: {
+        ...linkedResources,
+        ...graph.resources || {}
+      }
+    };
+  }
+  async parseAndResolveGraph(text, filename, standard) {
+    const parsed = this.parseGraphForValidation(text, filename, standard);
+    if (!parsed.graph) return parsed;
+    try {
+      return { graph: await this.resolveGraphLinks(parsed.graph, filename, standard) };
+    } catch (error) {
+      return { error: this.parseIssue(error, filename) };
+    }
+  }
   async readGraphFile(filename) {
     const graphFile = this.resolveGraphFile(filename);
     const text = await readFile(graphFile, "utf8");
-    const graph = parseCircuitryText(text, graphFile);
-    return { graphFile, text, graph };
+    const parsed = await this.parseAndResolveGraph(text, graphFile);
+    if (!parsed.graph) throw new Error(`Invalid Circuitry graph:
+${parsed.error?.message}`);
+    const validation = validateCircuitryGraphWithStandard(parsed.graph);
+    if (validation.errors.length) {
+      throw new Error(
+        `Invalid Circuitry graph:
+${validation.errors.map((e) => e.message).join("\n")}`
+      );
+    }
+    return { graphFile, text, graph: normalizeCircuitryGraph(parsed.graph) };
   }
   async readGraph(input = {}) {
     const { graphFile, text, graph } = await this.readGraphFile(input.filename);
@@ -853,8 +926,8 @@ var NodeCircuitryHost = class {
     if (input.graph)
       return validateCircuitryGraphWithStandard(input.graph, input.standard);
     const filename = input.filename || defaultFilename;
-    const parsed = this.parseGraphForValidation(input.text, filename, input.standard);
-    if (parsed.error) {
+    const parsed = await this.parseAndResolveGraph(input.text, filename, input.standard);
+    if ("error" in parsed) {
       return {
         ok: false,
         errors: [parsed.error],
@@ -865,7 +938,7 @@ var NodeCircuitryHost = class {
   }
   async writeGraph(input) {
     const graphFile = this.resolveGraphFile(input.filename);
-    const parsed = input.graph ? { graph: input.graph } : this.parseGraphForValidation(
+    const parsed = input.graph ? { graph: input.graph } : await this.parseAndResolveGraph(
       input.text,
       input.filename || graphFile,
       input.standard
@@ -896,7 +969,7 @@ ${validation.errors.map((e) => e.message).join("\n")}`
   async runGraph(input = {}) {
     const source = input.source || (input.text ? "text" : "current");
     const graphFile = this.resolveGraphFile(input.filename);
-    const parsed = source === "text" ? this.parseGraphForValidation(
+    const parsed = source === "text" ? await this.parseAndResolveGraph(
       input.text,
       input.filename || graphFile,
       input.standard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darkhorseprojects/circuitry",
-  "version": "0.2.33",
+  "version": "0.2.99",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",