Merge branch 'dev' into copilot/fix-6f56c3cd-1667-400f-8551-f983d131e664

Author: pelikhan

docs/src/content/docs/reference/scripts/markdown-include.md

@@ -0,0 +1,102 @@
+---
+title: Markdown Script Include
+sidebar:
+  order: 51
+description: Learn how to include external files in markdown scripts using the @include directive
+keywords: markdown scripts, include, file inclusion, @include directive
+hero:
+  image:
+    alt: A minimalistic 8-bit style icon showing two document rectangles with arrows pointing from one to another, representing file inclusion. The first document has an "@include" symbol, and content flows to the second document. Small geometric shapes indicate text content. The image uses five corporate colors on a transparent background, is highly simplified and geometric, and measures 128 by 128 pixels. No people, words, or realistic effects are present.
+    file: ./markdown-include.png
+
+---
+
+Markdown scripts support including external files using the `@include` directive, allowing you to compose larger prompts from reusable components.
+
+## Basic Usage
+
+Use the `@include "filepath"` directive to insert the contents of an external file into your markdown script:
+
+```markdown title="main.genai.md"
+---
+title: "My Script"
+description: "Script with included content"
+---
+
+# Welcome
+
+This is the main content.
+
+@include "templates/greeting.md"
+
+More content after the include.
+```
+
+```markdown title="templates/greeting.md"
+## Hello World
+
+This greeting template can be reused across multiple scripts.
+
+Welcome to GenAIScript!
+```
+
+## File Resolution
+
+File paths in `@include` directives are resolved relative to the directory containing the markdown script:
+
+- `@include "file.txt"` - file in the same directory as the script
+- `@include "templates/header.md"` - file in a subdirectory
+- `@include "../shared/common.md"` - file in a parent directory
+
+## Multiple Includes
+
+You can use multiple `@include` directives in the same markdown script:
+
+```markdown title="complex.genai.md"
+# Complex Script
+
+@include "header.md"
+
+## Main Content
+
+This is the main content section.
+
+@include "examples/code-sample.md"
+
+## Conclusion
+
+@include "footer.md"
+```
+
+## Error Handling
+
+If an included file cannot be found or read, the `@include` directive is replaced with an HTML comment containing the error message:
+
+```markdown
+<!-- Error including missing-file.txt: File not found: /path/to/missing-file.txt -->
+```
+
+This ensures that your script continues to work even when included files are missing, while providing clear feedback about what went wrong.
+
+## Use Cases
+
+The `@include` directive is useful for:
+
+- **Reusable templates**: Share common greetings, instructions, or examples across multiple scripts
+- **Modular prompts**: Break large prompts into manageable, focused files
+- **Content organization**: Keep related content in separate files for better maintainability
+- **Team collaboration**: Allow team members to work on different parts of a prompt independently
+
+## Comparison with importTemplate
+
+The `@include` directive is different from the programmatic `importTemplate` function:
+
+| Feature | `@include` directive | `importTemplate` function |
+|---------|---------------------|---------------------------|
+| **Usage** | Markdown scripts (`.genai.md`) | JavaScript/TypeScript scripts (`.genai.mjs`, `.genai.mts`) |
+| **Processing** | Content replacement during parsing | Runtime template rendering |
+| **Variables** | No variable interpolation | Supports Mustache/Jinja variables |
+| **Error handling** | HTML comments for missing files | Runtime errors |
+| **File types** | Any text file | Template files with variable syntax |
+
+Choose `@include` for simple content inclusion in markdown scripts, and `importTemplate` for dynamic template rendering with variables in JavaScript/TypeScript scripts.

docs/src/content/docs/reference/scripts/markdown-scripts.mdx

@@ -219,6 +219,33 @@ Please analyze the uploaded files and provide:
 
 Focus on technical aspects and provide actionable insights.`} lang="markdown" title="analyze-files.genai.md" />
 
+## Including External Files
+
+Markdown scripts support including content from external files using the `@include` directive. This allows you to compose larger prompts from reusable components:
+
+<Code code={`---
+title: "Documentation Generator"
+description: "Generates documentation with templates"
+---
+
+# Documentation Generation
+
+@include "templates/header.md"
+
+Please generate documentation for the following code:
+
+@include "examples/code-sample.md"
+
+@include "templates/footer.md"`} lang="markdown" title="doc-generator.genai.md" />
+
+The `@include "filepath"` directive:
+- Resolves file paths relative to the script's directory
+- Supports subdirectories: `@include "templates/header.md"`
+- Replaces missing files with error comments
+- Processes multiple includes in the same script
+
+For more details, see the [Markdown Script Include](/genaiscript/reference/scripts/markdown-include) documentation.
+
 ## Parameters and Variables
 
 You can define script parameters in the frontmatter and reference them in the content:

packages/core/src/markdownscript.ts

@@ -8,22 +8,75 @@ import { deleteUndefinedValues } from "./cleaners.js";
 import { JSON5Stringify } from "./json5.js";
 import type { PromptArgs } from "./types.js";
 import { genaiscriptDebug } from "./debug.js";
+import { resolve } from "node:path";
 const dbg = genaiscriptDebug("md");
 
+/**
+ * Processes @include directives in markdown text by replacing them with file contents.
+ *
+ * @param text - The markdown text containing @include directives
+ * @param readText - Function to read file contents
+ * @param baseDir - Base directory for resolving relative paths
+ * @returns The processed text with @include directives replaced
+ */
+async function processIncludeDirectives(
+  text: string,
+  readText: (filepath: string) => Promise<string>,
+  baseDir: string,
+): Promise<string> {
+  const includeRegex = /@include\s+"([^"]+)"/g;
+  let result = text;
+  let match;
+
+  while ((match = includeRegex.exec(text)) !== null) {
+    const [fullMatch, filepath] = match;
+    try {
+      // Resolve the file path relative to baseDir
+      const resolvedPath = resolve(baseDir, filepath);
+      dbg(`processing @include directive: ${filepath} -> ${resolvedPath}`);
+
+      const includedContent = await readText(resolvedPath);
+      result = result.replace(fullMatch, includedContent);
+    } catch (error) {
+      // If file reading fails, replace with a comment indicating the error
+      const errorMsg = `<!-- Error including ${filepath}: ${error.message} -->`;
+      dbg(`failed to include ${filepath}: ${error.message}`);
+      result = result.replace(fullMatch, errorMsg);
+    }
+  }
+
+  return result;
+}
+
 /**
  * Parses a markdown script file with frontmatter and transpiles it to GenAIScript.
  *
- * @param filename - The name of the file being processed
  * @param text - The raw text of the document, including optional frontmatter and content body
+ * @param options - Optional configuration including file reading capabilities and base directory
  * @returns The transpiled JavaScript source code
  *
  * The parsing process:
  * - Splits the document into frontmatter and content using splitMarkdown
  * - Converts frontmatter to PromptArgs metadata
+ * - Processes @include directives to inline file contents
  * - Converts content body to $ calls for the prompt using unified/remark AST processing
  */
-export async function markdownScriptParse(text: string) {
-  const { frontmatter = "", content = "" } = splitMarkdown(text);
+export async function markdownScriptParse(
+  text: string,
+  options?: {
+    readText?: (filepath: string) => Promise<string>;
+    baseDir?: string;
+  },
+) {
+  const { readText, baseDir = "." } = options || {};
+
+  // Process @include directives before splitting markdown
+  let processedText = text;
+  if (readText) {
+    processedText = await processIncludeDirectives(text, readText, baseDir);
+  }
+
+  const { frontmatter = "", content = "" } = splitMarkdown(processedText);
 
   // Parse frontmatter as YAML and convert to PromptArgs
   const fm = frontmatter ? YAMLParse(frontmatter) : {};

packages/core/src/template.ts

@@ -16,6 +16,7 @@ import { markdownScriptParse } from "./markdownscript.js";
 import { readJSON } from "./fs.js";
 import type { PromptArgs, PromptScript, McpServersConfig, McpServerConfig, McpAgentServersConfig, McpAgentServerConfig } from "./types.js";
 import { basename, resolve, dirname } from "node:path";
+import { readText } from "./fs.js";
 
 /**
  * Extracts a template ID from the given filename by removing specific extensions
@@ -153,7 +154,10 @@ async function parsePromptTemplateCore(filename: string, content: string) {
   let jsSource: string;
   let meta: ReturnType<typeof parsePromptScriptMeta>;
   if (GENAI_MD_REGEX.test(filename)) {
-    const res = await markdownScriptParse(content);
+    const res = await markdownScriptParse(content, {
+      readText,
+      baseDir: dirname(filename),
+    });
     meta = res.meta;
     jsSource = res.jsSource;
   } else {