added more docs

docs/src/content/docs/reference/scripts/imports.mdx

@@ -43,9 +43,19 @@ export function summarize(files) {
 
 ```js title="summarize.genai.mjs"
 import { summarize } from "./summarizer.mjs"
-summarize(env.files)
+summarize(env.generator, env.files)
 ```
 
+## `env.generator`
+
+The `env.generator` references the root prompt generator context, the top level `$`, `def` functions... It can be used to create function that can be used with those function or also with `runPrompt`.
+
+```js title="summarizer.mjs" "_"
+export function summarize(_, files) {
+    _.def("FILE", files)
+    _.$`Summarize each file. Be concise.`
+}
+```
 
 ## Default function export
 
@@ -57,4 +67,4 @@ script(...)
 export default async function() {
     $`Write a poem.`
 }
-```
+```

packages/core/src/promptcontext.ts

@@ -49,7 +49,7 @@ export function createPromptContext(
     model: string
 ) {
     const { cancellationToken, infoCb } = options || {}
-    const env = Object.freeze(vars)
+    const env = structuredClone(vars)
     const parsers = createParsers({ trace, model })
     const YAML = Object.freeze<YAML>({
         stringify: YAMLStringify,
@@ -175,7 +175,7 @@ export function createPromptContext(
         if (fn) appendPromptChild(createOutputProcessor(fn))
     }
 
-    const promptHost: PromptHost = {
+    const promptHost: PromptHost = Object.freeze<PromptHost>({
         askUser: (question) =>
             host.askUser({
                 prompt: question,
@@ -191,13 +191,13 @@ export function createPromptContext(
             const res = await host.container({ ...(options || {}), trace })
             return res
         },
-    }
+    })
 
-    const ctx = Object.freeze<PromptContext & RunPromptContextNode>({
+    const ctx: PromptContext & RunPromptContextNode = {
         ...createChatGenerationContext(options, trace),
         script: () => {},
         system: () => {},
-        env,
+        env: undefined, // set later
         path,
         fs: workspace,
         workspace,
@@ -342,7 +342,9 @@ export function createPromptContext(
                 file,
             }
         },
-    })
+    }
+    env.generator = ctx
+    ctx.env = Object.freeze(env)
     const appendPromptChild = (node: PromptNode) => {
         if (!ctx.node) throw new Error("Prompt closed")
         appendChild(ctx.node, node)

packages/core/src/promptrunner.ts

@@ -2,7 +2,6 @@ import { executeChatSession } from "./chat"
 import { Fragment, Project, PromptScript } from "./ast"
 import { stringToPos } from "./parser"
 import { arrayify, assert, logVerbose, relativePath } from "./util"
-import { staticVars } from "./template"
 import { host } from "./host"
 import { applyLLMDiff, applyLLMPatch, parseLLMDiffs } from "./diff"
 import { MarkdownTrace } from "./trace"
@@ -55,7 +54,6 @@ async function resolveExpansionVars(
         } else trace.error(`secret \`${secret}\` not found`)
     }
     const res: Partial<ExpansionVariables> = {
-        ...staticVars(),
         spec: {
             filename: relativePath(host.projectFolder(), file.filename),
             content: file.content,

packages/core/src/template.ts

@@ -196,14 +196,6 @@ export function parsePromptScriptMeta(jsSource: string) {
     return meta
 }
 
-export function staticVars(): Omit<ExpansionVariables, "template"> {
-    return {
-        spec: { filename: "spec.gpspec.md", content: "" } as WorkspaceFile,
-        files: [] as WorkspaceFile[],
-        vars: {} as Record<string, string>,
-    }
-}
-
 async function parsePromptTemplateCore(
     filename: string,
     content: string,

packages/core/src/types/prompt_template.d.ts

@@ -525,9 +525,14 @@ interface ExpansionVariables {
     vars: PromptParameters
 
     /**
-     * List of secrets used by the prompt, must be registred in `genaiscript`.
+     * List of secrets used by the prompt, must be registered in `genaiscript`.
      */
     secrets?: Record<string, string>
+
+    /**
+     * Root prompt generation context
+     */
+    generator: ChatGenerationContext
 }
 
 type MakeOptional<T, P extends keyof T> = Partial<Pick<T, P>> & Omit<T, P>

packages/sample/genaisrc/mjs.genai.mjs

@@ -13,5 +13,5 @@ import { summarize } from "./summarizer.mjs"
 $`You are an export at analyzing data.`
 
 export default async function () {
-    summarize(env.files)
+    summarize(env.generator, env.files)
 }

packages/sample/genaisrc/summarizer.mjs

@@ -1,5 +1,5 @@
-export function summarize(files) {
-    def("FILE", files)
-    $`...`
-    $`Summarize each file. Be concise.`
+export function summarize(_, files) {
+    _.def("FILE", files)
+    _.$`...`
+    _.$`Summarize each file. Be concise.`
 }