@dot-agent/compiler 0.1.0 → 0.5.0-alpha.1

package/dist/index.js

@@ -1,4 +1,5 @@
 import {
+  COMPILER_VERSION,
   aboutmeToJson,
   buildAboutme,
   buildId,
@@ -7,13 +8,15 @@ import {
   extractFiles,
   extractName,
   parseAboutme,
-  parseId
-} from "./chunk-IT25ILTQ.js";
+  parseId,
+  validateMagicBytes,
+  validateZipBomb
+} from "./chunk-JIYQMCQQ.js";
 
 // src/parser.ts
 import { createRequire } from "module";
 import { Parser, Language } from "web-tree-sitter";
-import bpInit, { parse_behavior as bpParseBehavior, parse_description as bpParseDescription, get_graph } from "@dot-agent/parser-dsl";
+import { init as bpInit, parse_behavior as bpParseBehavior, parse_description as bpParseDescription, get_graph } from "@dot-agent/parser-dsl";
 var require2 = createRequire(import.meta.url);
 var { descriptionWasmPath, behaviorWasmPath } = require2("@dot-agent/tree-sitter");
 var _initialized = false;
@@ -177,6 +180,18 @@ async function lintDescription(text, file = "agent.description") {
       message: "No domain declared \u2014 agent will be packaged as unknown/name. Interoperability between runtimes is not guaranteed."
     });
   }
+  const behaviorBlocks = nodesOfType(tree, "behavior_block");
+  if (behaviorBlocks.length > 1) {
+    const { line, col } = nodePosition(behaviorBlocks[1]);
+    messages.push({
+      file,
+      line,
+      col,
+      severity: "error",
+      code: "E017",
+      message: "Multiple 'behavior' declarations \u2014 only one is allowed. To combine multiple files, use 'merge' in your .behavior file."
+    });
+  }
   const declaredTypes = new Set(
     nodesOfType(tree, "type_decl").map((n) => n.childForFieldName("name")?.text).filter(Boolean)
   );
@@ -275,7 +290,7 @@ function collectMergedStates(tree, docDir, states, visited = /* @__PURE__ */ new
     collectMergedStates(mergedTree, dirname(absPath), states, visited);
   }
 }
-async function lintBehavior(text, file = "agent.behavior", docPath) {
+async function lintBehavior(text, file = "agent.behavior", docPath, consolidated = false, externalStates, mergedText) {
   await initBehaviorParser();
   if (!text.endsWith("\n")) text = text + "\n";
   const tree = await parse("behavior", text);
@@ -296,7 +311,7 @@ async function lintBehavior(text, file = "agent.behavior", docPath) {
         col,
         severity: "warning",
         code: "W013",
-        message: `'interact' without 'goal' \u2014 the prettifier will insert one. To set it explicitly, add 'goal "..."' before 'interact'.`
+        message: `'interact' without 'goal'. Add 'goal "..."' before 'interact'.`
       });
     }
     if (hasGoal && !hasInteract) {
@@ -307,7 +322,7 @@ async function lintBehavior(text, file = "agent.behavior", docPath) {
         col,
         severity: "warning",
         code: "W012",
-        message: `'goal' is only valid in an oriented state. Add 'interact' or remove 'goal' \u2014 the prettifier can adjust this.`
+        message: `'goal' is only valid in an oriented state. Add 'interact' or remove 'goal'.`
       });
     }
     if (hasInteract && intentHandlers.length === 0) {
@@ -438,7 +453,7 @@ async function lintBehavior(text, file = "agent.behavior", docPath) {
         col,
         severity: "warning",
         code: "W002",
-        message: `Text block exceeds 280 characters (${content.length}). Consider using 'teach' to load long goal text from an external file.`
+        message: `Text block exceeds 280 characters (${content.length}). Consider using 'guide' to load long orientation text from an external text file.`
       });
     }
   }
@@ -457,7 +472,7 @@ async function lintBehavior(text, file = "agent.behavior", docPath) {
         col,
         severity: "warning",
         code: "W010",
-        message: `'guide' text in state '${stateName}' is ${content.length} characters (limit: 280). Consider using an external file.`
+        message: `'guide' text in state '${stateName}' is ${content.length} characters. Consider using an external file.`
       });
     }
   }
@@ -470,6 +485,9 @@ async function lintBehavior(text, file = "agent.behavior", docPath) {
     } catch {
     }
   }
+  if (externalStates) {
+    for (const name of externalStates) definedStates.add(name);
+  }
   const stateNameList = Array.from(definedStates);
   for (const transitionNode of nodesOfType(tree, "transition_stmt")) {
     const stateNode = transitionNode.childForFieldName("state");
@@ -521,7 +539,9 @@ async function lintBehavior(text, file = "agent.behavior", docPath) {
     return messages;
   }
   const fsm = fsmResult.ok;
-  const allTargets = new Set(collectTransitionTargets(fsm.states.flatMap((s) => s.body)));
+  const wholeFsm = mergedText !== void 0 ? parseBehaviorFile(mergedText).ok : null;
+  const reachabilityStates = wholeFsm?.states ?? fsm.states;
+  const allTargets = new Set(collectTransitionTargets(reachabilityStates.flatMap((s) => s.body)));
   for (const state of fsm.states) {
     const hasOutgoing = collectTransitionTargets(state.body).length > 0;
     const hasIncoming = allTargets.has(state.name);
@@ -551,6 +571,49 @@ async function lintBehavior(text, file = "agent.behavior", docPath) {
       });
     }
   }
+  if (consolidated) {
+    const wholeTreeFsm = wholeFsm ?? fsm;
+    const seenStates = /* @__PURE__ */ new Set();
+    for (const state of wholeTreeFsm.states) {
+      if (seenStates.has(state.name)) {
+        messages.push({
+          file,
+          line: 1,
+          col: 1,
+          severity: "error",
+          code: "E015",
+          message: `Duplicate state '${state.name}' across merged files \u2014 each state name must be unique in the consolidated FSM.`
+        });
+      } else {
+        seenStates.add(state.name);
+      }
+    }
+    if (!wholeTreeFsm.states.some((s) => s.name === "init")) {
+      messages.push({
+        file,
+        line: 1,
+        col: 1,
+        severity: "error",
+        code: "E016",
+        message: `Required 'init' state is missing. Add a state named 'init' as the entry point of your behavior.`
+      });
+    }
+    const seenTriggers = /* @__PURE__ */ new Set();
+    for (const trigger of wholeTreeFsm.global_triggers) {
+      if (seenTriggers.has(trigger.event)) {
+        messages.push({
+          file,
+          line: 1,
+          col: 1,
+          severity: "warning",
+          code: "W014",
+          message: `Duplicate global trigger '${trigger.event}' across merged files \u2014 only the last definition takes effect.`
+        });
+      } else {
+        seenTriggers.add(trigger.event);
+      }
+    }
+  }
   return messages;
 }
 async function createLinter() {
@@ -560,37 +623,19 @@ async function createLinter() {
 // src/zip.ts
 import JSZip from "jszip";
 import { readFile, writeFile } from "fs/promises";
-var MAX_ZIP_SIZE = 500 * 1024 * 1024;
-var MAX_COMPRESSION_RATIO = 100;
 async function readZip(filePath) {
   const data = await readFile(filePath);
   return JSZip.loadAsync(data);
 }
-async function validateZipBomb(filePath) {
+async function validateZipBomb2(filePath) {
   const data = await readFile(filePath);
   const zip = await JSZip.loadAsync(data);
-  let totalUncompressed = 0;
-  zip.forEach((_relativePath, file) => {
-    if (!file.dir) {
-      totalUncompressed += file._data?.uncompressedSize || 0;
-    }
-  });
-  const compressedSize = data.length;
-  const ratio = totalUncompressed / compressedSize;
-  if (totalUncompressed > MAX_ZIP_SIZE) {
-    throw new Error(`ZIP uncompressed size exceeds 500MB limit: ${totalUncompressed}`);
-  }
-  if (ratio > MAX_COMPRESSION_RATIO) {
-    throw new Error(`ZIP compression ratio exceeds 100x limit: ${ratio.toFixed(1)}x`);
-  }
+  validateZipBomb(zip, data.length);
   return true;
 }
-async function validateMagicBytes(filePath) {
+async function validateMagicBytes2(filePath) {
   const data = await readFile(filePath);
-  const magic = data.subarray(0, 4);
-  if (!(magic[0] === 80 && magic[1] === 75 && magic[2] === 3 && magic[3] === 4)) {
-    throw new Error("File is not a valid ZIP (invalid magic bytes)");
-  }
+  validateMagicBytes(data);
   return true;
 }
 async function writeZip(zip, outPath) {
@@ -600,7 +645,7 @@ async function writeZip(zip, outPath) {
 
 // src/pack.ts
 import { readFile as readFile2, stat, readdir } from "fs/promises";
-import { join, basename } from "path";
+import { join, basename, resolve as resolve2, relative, isAbsolute, normalize, dirname as dirname2 } from "path";
 import { execSync } from "child_process";
 import { createHash } from "crypto";
 import JSZip2 from "jszip";
@@ -682,7 +727,81 @@ async function resolveCommit(explicit) {
   if (explicit) return explicit;
   return gitRevParseShort() ?? void 0;
 }
-async function collectFiles(dir) {
+function isExternalPath(agentRoot, declaredPath) {
+  if (isAbsolute(declaredPath)) return true;
+  const normRoot = normalize(resolve2(agentRoot));
+  const resolved = resolve2(normRoot, declaredPath);
+  return relative(normRoot, resolved).startsWith("..");
+}
+async function discoverDescriptionFile(dir, explicit) {
+  if (explicit) {
+    try {
+      await stat(join(dir, explicit));
+      return explicit;
+    } catch {
+      throw new Error(`E003: Description file '${explicit}' not found in ${dir}`);
+    }
+  }
+  const entries = await readdir(dir);
+  const descFiles = entries.filter((f) => f.endsWith(".description"));
+  if (descFiles.length === 0) {
+    throw new Error(`E003: No .description file found in ${dir}`);
+  }
+  if (descFiles.length > 1) {
+    throw new Error(`E003: Multiple .description files found: ${descFiles.join(", ")} \u2014 use PackOptions.description to specify one`);
+  }
+  const name = descFiles[0];
+  if (name !== "agent.description") {
+    console.info(`[dot-agent] using description file: ${name}`);
+  }
+  return name;
+}
+async function consolidate(agentRoot, entryFile) {
+  await initBehaviorParser();
+  const normRoot = normalize(resolve2(agentRoot));
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const order = [];
+  const textCache = /* @__PURE__ */ new Map();
+  async function dfs(relPath) {
+    const absPath = resolve2(normRoot, relPath);
+    if (visiting.has(absPath)) {
+      throw new Error(`E013: Circular merge dependency involving '${relPath}'`);
+    }
+    if (visited.has(absPath)) return;
+    visiting.add(absPath);
+    let fileText;
+    try {
+      fileText = await readFile2(absPath, "utf-8");
+    } catch {
+      throw new Error(`E012: Merge target not found: '${relPath}'`);
+    }
+    textCache.set(absPath, fileText);
+    const result = parseBehaviorFile(fileText);
+    const merges = result.ok?.merges ?? [];
+    for (const mergePath of merges) {
+      if (isAbsolute(mergePath)) {
+        throw new Error(`E014: Merge path '${mergePath}' in '${relPath}' is absolute \u2014 only paths within the agent root are allowed`);
+      }
+      const mergeAbs = resolve2(dirname2(absPath), mergePath);
+      const mergeRel = relative(normRoot, mergeAbs);
+      if (mergeRel.startsWith("..")) {
+        throw new Error(`E014: Merge path '${mergePath}' in '${relPath}' escapes the agent root`);
+      }
+      await dfs(mergeRel);
+    }
+    visiting.delete(absPath);
+    visited.add(absPath);
+    order.push(relPath);
+  }
+  await dfs(entryFile);
+  const texts = order.map((relPath) => textCache.get(resolve2(normRoot, relPath)));
+  return {
+    mergedText: texts.join("\n"),
+    mergeSources: order
+  };
+}
+async function collectFiles(dir, descriptionFile, mergedBehaviorText, mergeSources) {
   const files = /* @__PURE__ */ new Map();
   async function walk(subdir, prefix = "") {
     try {
@@ -701,13 +820,16 @@ async function collectFiles(dir) {
     } catch {
     }
   }
-  files.set("agent.description", await readFile2(join(dir, "agent.description"), "utf-8"));
-  files.set("agent.behavior", await readFile2(join(dir, "agent.behavior"), "utf-8"));
+  files.set(descriptionFile, await readFile2(join(dir, descriptionFile), "utf-8"));
+  const flatBehaviorText = mergedBehaviorText.replace(/^\s*merge\s+"[^"]*"\s*$/gm, "");
+  files.set("agent.behavior", flatBehaviorText);
+  for (const relPath of mergeSources) {
+    files.set(`behaviors/${relPath}`, await readFile2(join(dir, relPath), "utf-8"));
+  }
   try {
     files.set("SOUL.md", await readFile2(join(dir, "SOUL.md"), "utf-8"));
   } catch {
   }
-  await walk(join(dir, "behaviors"), "behaviors");
   await walk(join(dir, "guides"), "guides");
   await walk(join(dir, "knowledge"), "knowledge");
   return files;
@@ -715,29 +837,14 @@ async function collectFiles(dir) {
 async function pack(options = {}) {
   const dir = options.dir ?? process.cwd();
   const outPath = options.out ?? join(dir, `${basename(dir)}.agent`);
-  let descriptionText;
-  let behaviorText;
-  try {
-    descriptionText = await readFile2(join(dir, "agent.description"), "utf-8");
-  } catch {
-    throw new Error("E003: File agent.description not found");
-  }
-  try {
-    behaviorText = await readFile2(join(dir, "agent.behavior"), "utf-8");
-  } catch {
-    throw new Error("E007: File agent.behavior not found");
-  }
-  const [descriptionMessages, behaviorMessages] = await Promise.all([
-    lintDescription(descriptionText),
-    lintBehavior(behaviorText)
-  ]);
-  const allMessages = [...descriptionMessages, ...behaviorMessages];
-  const errors = allMessages.filter((m) => m.severity === "error");
-  const warnings = allMessages.filter((m) => m.severity === "warning");
-  if (errors.length > 0) {
+  const descriptionFileName = await discoverDescriptionFile(dir, options.description);
+  const descriptionText = await readFile2(join(dir, descriptionFileName), "utf-8");
+  const descriptionMessages = await lintDescription(descriptionText, descriptionFileName);
+  const descErrors = descriptionMessages.filter((m) => m.severity === "error");
+  if (descErrors.length > 0) {
     throw new Error(
       `Lint failed:
-${errors.map((e) => `  ${e.file}:${e.line}:${e.col} ${e.code} ${e.message}`).join("\n")}`
+${descErrors.map((e) => `  ${e.file}:${e.line}:${e.col} ${e.code} ${e.message}`).join("\n")}`
     );
   }
   await initBehaviorParser();
@@ -747,9 +854,26 @@ ${errors.map((e) => `  ${e.file}:${e.line}:${e.col} ${e.code} ${e.message}`).joi
     throw new Error(`E_DESC: ${firstError?.message ?? "parse failed"}`);
   }
   const df = descResult.ok;
+  if (!df.behavior) {
+    throw new Error(`E_DESC: '${descriptionFileName}' must declare a behavior file \u2014 add 'behavior "agent.behavior"' (or the name of your entry .behavior file)`);
+  }
+  if (isExternalPath(dir, df.behavior)) {
+    throw new Error(`E014: behavior path '${df.behavior}' in '${descriptionFileName}' is absolute or escapes the agent root`);
+  }
+  const { mergedText, mergeSources } = await consolidate(dir, df.behavior);
+  const behaviorMessages = await lintBehavior(mergedText, "agent.behavior", void 0, true);
+  const allMessages = [...descriptionMessages, ...behaviorMessages];
+  const errors = allMessages.filter((m) => m.severity === "error");
+  const warnings = allMessages.filter((m) => m.severity === "warning");
+  if (errors.length > 0) {
+    throw new Error(
+      `Lint failed:
+${errors.map((e) => `  ${e.file}:${e.line}:${e.col} ${e.code} ${e.message}`).join("\n")}`
+    );
+  }
   const version = await resolveVersion(options.version);
   const commit = await resolveCommit(options.commit);
-  const allFiles = await collectFiles(dir);
+  const allFiles = await collectFiles(dir, descriptionFileName, mergedText, mergeSources);
   const contentForHash = Array.from(allFiles.values()).join("");
   const sha256 = createHash("sha256").update(contentForHash).digest("hex");
   const namespace = df.agent.domain ?? "unknown";
@@ -769,7 +893,7 @@ ${errors.map((e) => `  ${e.file}:${e.line}:${e.col} ${e.code} ${e.message}`).joi
     license: df.agent.license ?? "",
     persona: df.persona ?? "SOUL.md",
     purpose: "unknown",
-    compiler: "dot-agent/1.0.0",
+    compiler: `dot-agent/${COMPILER_VERSION}`,
     commit,
     capabilities: df.capabilities.map((c) => ({ id: c.name, description: c.description ?? "" })),
     requires: df.requires,
@@ -781,26 +905,100 @@ ${errors.map((e) => `  ${e.file}:${e.line}:${e.col} ${e.code} ${e.message}`).joi
   if (typesJson) {
     agentFolder.file("types.json", typesJson);
   }
-  const gitkeepPaths = /* @__PURE__ */ new Set(["behaviors/.gitkeep", "guides/.gitkeep", "knowledge/.gitkeep"]);
+  const gitkeepPaths = /* @__PURE__ */ new Set(["guides/.gitkeep", "knowledge/.gitkeep"]);
   const filesJson = {
-    description: "agent.description",
+    description: descriptionFileName,
     behavior: "agent.behavior",
-    behaviors: Array.from(allFiles.keys()).filter((f) => f.startsWith("behaviors/") && !gitkeepPaths.has(f)),
+    behaviors: Array.from(allFiles.keys()).filter((f) => f.startsWith("behaviors/")),
     guides: Array.from(allFiles.keys()).filter((f) => f.startsWith("guides/") && !gitkeepPaths.has(f)),
     knowledge: Array.from(allFiles.keys()).filter((f) => f.startsWith("knowledge/") && !gitkeepPaths.has(f))
   };
   agentFolder.file("files.json", JSON.stringify(filesJson, null, 2));
   for (const [path, content] of allFiles) {
-    if (!gitkeepPaths.has(path)) zip.file(path, content);
+    zip.file(path, content);
   }
   await writeZip(zip, outPath);
   return { path: outPath, id, warnings };
 }
+
+// src/bundle.ts
+import { readFile as readFile3 } from "fs/promises";
+import { join as join2 } from "path";
+import { createHash as createHash2 } from "crypto";
+var GITKEEP = /* @__PURE__ */ new Set(["guides/.gitkeep", "knowledge/.gitkeep"]);
+async function bundleFromDir(dir) {
+  const descriptionFileName = await discoverDescriptionFile(dir);
+  const descriptionText = await readFile3(join2(dir, descriptionFileName), "utf-8");
+  const descMessages = await lintDescription(descriptionText, descriptionFileName);
+  const descErrors = descMessages.filter((m) => m.severity === "error");
+  if (descErrors.length > 0) {
+    throw new Error(
+      `Lint failed:
+${descErrors.map((e) => `  ${e.file}:${e.line}:${e.col} ${e.code} ${e.message}`).join("\n")}`
+    );
+  }
+  await initBehaviorParser();
+  const descResult = parseDescriptionFile(descriptionText);
+  if (descResult.ok === null) {
+    const firstError = descResult.diagnostics.find((d) => d.severity === "error");
+    throw new Error(`E_DESC: ${firstError?.message ?? "parse failed"}`);
+  }
+  const df = descResult.ok;
+  if (!df.behavior) {
+    throw new Error(`E_DESC: '${descriptionFileName}' must declare a behavior file`);
+  }
+  const { mergedText, mergeSources } = await consolidate(dir, df.behavior);
+  const behaviorMessages = await lintBehavior(mergedText, "agent.behavior", void 0, true);
+  const allMessages = [...descMessages, ...behaviorMessages];
+  const errors = allMessages.filter((m) => m.severity === "error");
+  const warnings = allMessages.filter((m) => m.severity === "warning");
+  if (errors.length > 0) {
+    throw new Error(
+      `Lint failed:
+${errors.map((e) => `  ${e.file}:${e.line}:${e.col} ${e.code} ${e.message}`).join("\n")}`
+    );
+  }
+  for (const w of warnings) {
+    process.stderr.write(`\x1B[33m\u26A0\x1B[0m ${w.file}:${w.line}:${w.col} ${w.code} ${w.message}
+`);
+  }
+  const allFiles = await collectFiles(dir, descriptionFileName, mergedText, mergeSources);
+  const sha256 = createHash2("sha256").update(Array.from(allFiles.values()).join("")).digest("hex");
+  const id = buildId({ namespace: df.agent.domain ?? "local", name: df.agent.name, version: "dev" });
+  const aboutme = buildAboutme({
+    id,
+    name: df.agent.name,
+    description: df.description ?? "",
+    version: "dev",
+    domain: df.agent.domain ?? "",
+    license: df.agent.license ?? "",
+    persona: df.persona ?? "SOUL.md",
+    purpose: "development",
+    compiler: `dot-agent/${COMPILER_VERSION}`,
+    capabilities: df.capabilities.map((c) => ({ id: c.name, description: c.description ?? "" })),
+    requires: df.requires,
+    integrity: { sha256, files: ".agent/files.json" }
+  });
+  const files = {
+    description: descriptionText,
+    // Reuse collectFiles()'s 'agent.behavior' entry rather than the raw
+    // mergedText — it has redundant `merge "..."` lines stripped (see
+    // collectFiles() for why they're dead weight once flattened).
+    behavior: allFiles.get("agent.behavior") ?? mergedText,
+    soul: allFiles.get("SOUL.md"),
+    guides: Array.from(allFiles.entries()).filter(([p]) => p.startsWith("guides/") && !GITKEEP.has(p)).map(([path, content]) => ({ path, content })),
+    knowledge: Array.from(allFiles.entries()).filter(([p]) => p.startsWith("knowledge/") && !GITKEEP.has(p)).map(([path, content]) => ({ path, content })),
+    behaviors: Array.from(allFiles.entries()).filter(([p]) => p.startsWith("behaviors/")).map(([path, content]) => ({ path, content }))
+  };
+  return { id, aboutme, files };
+}
 export {
   aboutmeToJson,
   buildAboutme,
   buildId,
+  bundleFromDir,
   collectFiles,
+  consolidate,
   createLinter,
   createZip,
   extractDigest,
@@ -824,8 +1022,8 @@ export {
   parseSync,
   positionToOffset,
   readZip,
-  validateMagicBytes,
-  validateZipBomb,
+  validateMagicBytes2 as validateMagicBytes,
+  validateZipBomb2 as validateZipBomb,
   writeZip
 };
 //# sourceMappingURL=index.js.map