Dev

.devcontainer/devcontainer.json

@@ -1,34 +1,46 @@
 {
-    "image": "mcr.microsoft.com/devcontainers/javascript-node:22",
-    "postCreateCommand": "yarn install --frozen-lockfile --prefer-offline && yarn install:playwright",
-    "customizations": {
-        "vscode": {
-            "extensions": [
-                "GitHub.copilot-chat",
-                "esbenp.prettier-vscode",
-                "dbaeumer.vscode-eslint",
-                "bierner.markdown-mermaid",
-                "yoavbls.pretty-ts-errors",
-                "astro-build.astro-vscode",
-                "unifiedjs.vscode-mdx",
-                "streetsidesoftware.code-spell-checker",
-                "file-icons.file-icons",
-                "GitHub.vscode-pull-request-github",
-                "usernamehw.errorlens",
-                "goessner.mdmath",
-                "vsls-contrib.gistfs",
-                "ms-azuretools.vscode-containers"
-            ]
-        }
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:24",
+  "postCreateCommand": "pnpm install --frozen-lockfile --prefer-offline && pnpm install:playwright",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "GitHub.copilot-chat",
+        "esbenp.prettier-vscode",
+        "dbaeumer.vscode-eslint",
+        "bierner.markdown-mermaid",
+        "yoavbls.pretty-ts-errors",
+        "astro-build.astro-vscode",
+        "unifiedjs.vscode-mdx",
+        "streetsidesoftware.code-spell-checker",
+        "file-icons.file-icons",
+        "GitHub.vscode-pull-request-github",
+        "usernamehw.errorlens",
+        "goessner.mdmath",
+        "vsls-contrib.gistfs",
+        "ms-azuretools.vscode-containers",
+        "ms-vscode.vscode-js-profile-flame",
+        "streetsidesoftware.code-spell-checker-french"
+      ]
     },
-    "features": {
-        "ghcr.io/devcontainers/features/common-utils:2": {},
-        "ghcr.io/devcontainers/features/git:1": {},
-        "ghcr.io/ghcr.io/devcontainers/features/github-cli:1": {},
-        "ghcr.io/devcontainers/features/docker-in-docker:2": {},
-        "ghcr.io/devcontainers/features/azure-cli:1": {},
-        "ghcr.io/devcontainers/features/python:1": {},
-        "ghcr.io/devcontainers-extra/features/ffmpeg-apt-get:1": {},
-        "ghcr.io/devcontainers/features/rust:1": {}
+    "codespaces": {
+      "repositories": {
+        "githubnext/gh-aw": {
+          "permissions": {
+            "releases": "read",
+            "contents": "read"
+          }
+        }
+      }
     }
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {},
+    "ghcr.io/devcontainers/features/git:1": {},
+    "ghcr.io/ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+    "ghcr.io/devcontainers/features/azure-cli:1": {},
+    "ghcr.io/devcontainers/features/python:1": {},
+    "ghcr.io/devcontainers-extra/features/ffmpeg-apt-get:1": {},
+    "ghcr.io/devcontainers/features/rust:1": {}
+  }
 }

.devproxy/devproxyrc.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/rc.schema.json",
+  "plugins": [
+    {
+      "name": "LatencyPlugin",
+      "enabled": true,
+      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
+      "configSection": "apiLatencyPlugin",
+      "urlsToWatch": [
+        "http://api.ecs.eu/*"
+      ]
+    },
+    {
+      "name": "OpenAITelemetryPlugin",
+      "enabled": true,
+      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
+      "configSection": "openAITelemetryPlugin"
+    },
+    {
+      "name": "CrudApiPlugin",
+      "enabled": true,
+      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
+      "configSection": "feedbackApi",
+      "urlsToWatch": [
+        "http://api.ecs.eu/feedback"
+      ]
+    },
+    {
+      "name": "MarkdownReporter",
+      "enabled": true,
+      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
+    }
+  ],
+  "urlsToWatch": [
+    "https://models.github.ai/inference/chat/completions*",
+    "http://localhost:11434"
+  ],
+  "feedbackApi": {
+    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/crudapiplugin.schema.json",
+    "apiFile": "feedback-api.json"
+  },
+  "apiLatencyPlugin": {
+    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/latencyplugin.schema.json",
+    "minMs": 200,
+    "maxMs": 500
+  },
+  "openAITelemetryPlugin": {
+    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/openaitelemetryplugin.schema.json",
+    "currency": "USD",
+    "includeCosts": true,
+    "pricesFile": "prices.json"
+  },
+  "logLevel": "trace",
+  "newVersionNotification": "stable",
+  "showSkipMessages": true
+}

.devproxy/prices.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/openaitelemetryplugin.pricesfile.schema.json",
+  "prices": {
+    "llama-3.2-7b": {
+      "input": 2.5,
+      "output": 10
+    },
+    "gpt-4.1-2025-04-14": {
+      "input": 2.5,
+      "output": 10
+    }
+  }
+}

.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+indent_size = 2
+indent_style = space
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8

.github/copilot-instructions.md

@@ -0,0 +1,108 @@
+---
+Source: .ruler/instructions.md
+---
+# GenAIScript
+
+- Always use the `dev` branch for development or upstream.
+- Use `vitest` to generate tests. Place tests in the `tests` directory.
+
+```files
+  src/code.ts
+  test/code.test.ts
+```
+
+- Generate TypeScript (esm, async/await) code when possible, not JavaScript.
+- Filenames should be lowercase, with no spaces or special characters.
+
+## Repository structure
+
+The repository is organized as a monorepo with the following main packages in the `packages/` directory:
+
+### Core Packages
+
+- **`core/`** - `@genaiscript/core` - The core GenAIScript library containing the main functionality, LLM integrations, and APIs
+- **`runtime/`** - `@genaiscript/runtime` - Runtime environment for executing GenAIScript scripts with Docker support
+- **`api/`** - `@genaiscript/api` - Public API interfaces and types for GenAIScript
+- **`cli/`** - `genaiscript` - Command-line interface for GenAIScript (main CLI package)
+- **`.genaiscript`** - build artifacts - never commit files from `.genaiscript` folders!
+
+### Extensions & Plugins
+
+- **`vscode/`** - `genaiscript-vscode` - Visual Studio Code extension for GenAIScript
+- **`web/`** - Web-based components and interfaces
+- **`plugin-ast-grep/`** - `@genaiscript/plugin-ast-grep` - AST grep plugin for code analysis
+- **`plugin-mdast/`** - `@genaiscript/plugin-mdast` - Markdown AST plugin
+- **`plugin-mermaid/`** - `@genaiscript/plugin-mermaid` - Mermaid diagram plugin
+- **`plugin-playwright/`** - `@genaiscript/plugin-playwright` - Playwright automation plugin
+- **`plugin-pyodide/`** - `@genaiscript/plugin-pyodide` - Python execution plugin using Pyodide
+- **`plugin-z3/`** - `@genaiscript/plugin-z3` - Z3 theorem prover plugin
+
+### TypeScript Configuration
+
+- **`tsconfig.base.json`** - Base TypeScript configuration
+- **`tsconfig.lib.json`** - Library-specific TypeScript configuration
+- **`tsconfig.nonlib.json`** - Non-library TypeScript configuration
+- **`tsconfig.test.base.json`** - Test-specific TypeScript configuration
+
+## Documentation (`/docs`)
+
+The documentation is built using [Astro](https://astro.build/) with the [Starlight](https://starlight.astro.build/) theme. It includes:
+
+- **Source**: `docs/src/content/docs/` - Markdown documentation files
+- **Blog**: `docs/src/content/docs/blog/` - Built-in blog functionality with `starlight-blog` plugin
+- **Translations**: Ignore translations, they are autogenerated and updated.
+- **Building**: `pnpm build:docs` - Build the documentation site
+
+## Samples (`/samples`)
+
+The repository contains several sample projects demonstrating GenAIScript usage:
+
+### Sample Collection
+
+- **`samples/sample/genaisrc/`** - Comprehensive collection of GenAIScript examples
+  - 200+ sample scripts covering all major features
+  - Examples for tools, agents, data processing, file operations, and more
+  - Test scripts for validating functionality
+  - Organized in subdirectories by topic (blog/, node/, style/, etc.)
+- **`samples/modulesample/`** - Module usage examples
+- **`samples/runtime-sample/`** - Runtime API examples
+
+> Never add files from the `.genaiscript` directory. This folder contains runtime generated temporary files and should not be committed to the repository.
+
+## Building and testing
+
+- Use `pnpm build` to build the project
+- Use `pnpm build:cli` to build the cli only
+- Use `pnpm -r test` to run all tests
+- Use `pnpm test:core` for fast unit tests. It uses `vitest` to run tests.
+- Use `pnpm build:docs` to build the documentation
+
+NEVER try to run `genaiscript` using `npx`. Always using
+the local cli
+
+```sh
+node packages/cli/dist/src/index.js run
+```
+
+> IMPORTANT: Always run `pnpm build` at the end of the your work to ensure that the build still works.
+
+## Debug logging
+
+If you need to add debug logging, use `genaiscriptDebug("category")` to instantiate a new debug logger in a file
+where `category` is a descriptive name for the module or feature.
+
+```ts
+import { genaiscriptDebug } from "@genaiscript";
+const debug = genaiscriptDebug("category");
+```
+
+To enable debug logging, add `DEBUG=genaiscript:category` to the environment variables when running the script.
+
+```bash
+DEBUG=genaiscript:category pnpm test:core
+```
+
+## Self improvement
+
+Before finishing and assigning the pull request back to the user, self-reflect on your current session and generate 5 possible improvements to the `copilot-instructions.md` file. These should be based on your experience and the tasks you completed.
+Pick the most relevant ones and post a pull request review comment with a code update suggestion to the `.ruler/instructions.md` file. Keep it short, don't overdo it, and focus on the most impactful changes.

.github/genaisrc/issue-bot.genai.mts

@@ -4,16 +4,11 @@ script({
     responseType: "markdown",
     systemSafety: true,
     group: "actions",
-    parameters: {
-        issue: {
-            type: "integer",
-            description: "The issue number to answer.",
-            required: false,
-        },
-    },
 })
 
-const { title, body, number } = await github.getIssue(env.vars.issue)
+const info = await github.info()
+console.log(info)
+const { title, body, number } = await github.getIssue()
 const comments = await github.listIssueComments(number, { count: 100 })
 
 def("TITLE", title)

.github/instructions/genaiscript.instructions.md

@@ -0,0 +1,20 @@
+---
+applyTo: "**/*.genai.*"
+description: "Instructions for working with GenAIScript files"
+---
+
+## GenAIScript Code Generation Instructions
+
+GenAIScript is a custom runtime for node.js. It provides a set of unique APIs and support the TypeScript syntax, ESM, await/async.
+
+- GenAIScript documentation: https://microsoft.github.io/genaiscript/llms-full.txt
+- GenAIScript ambient type definitions: https://microsoft.github.io/genaiscript/genaiscript.d.ts
+
+## Guidance for Code Generation
+
+- you always generate TypeScript code using ESM modules for Node.JS.
+- you prefer using APIs from GenAIScript `genaiscript.d.ts` rather than node.js. Do NOT use node.js imports.
+- you keep the code simple, avoid exception handlers or error checking.
+- you add `TODOs` where you are unsure so that the user can review them
+- you use the global types in genaiscript.d.ts are already loaded in the global context, no need to import them.
+- save generated code in the `./genaisrc` folder with `.genai.mts` extension

.github/workflows/anthropic.yml

@@ -12,7 +12,7 @@ on:
             - ".github/workflows/anthropic.yml"
             - "packages/core/**/*"
             - "packages/cli/**/*"
-            - "packages/samples/**/*"
+            - "samples/**/*"
 concurrency:
     group: ${{ github.workflow }}-${{ github.ref }}-anthropic
     cancel-in-progress: true
@@ -24,20 +24,21 @@ jobs:
               with:
                   submodules: "recursive"
                   fetch-depth: 0
+            - uses: pnpm/action-setup@v4
             - uses: actions/setup-node@v4
               with:
                   node-version: "22"
-                  cache: yarn
-            - run: yarn install --frozen-lockfile
+                  cache: pnpm
+            - run: pnpm install --frozen-lockfile
             - name: compile
-              run: yarn compile:action
+              run: pnpm build:cli
             - name: poem
               continue-on-error: true
-              run: yarn run:script poem -p anthropic --out-trace $GITHUB_STEP_SUMMARY
+              run: pnpm run:script poem -p anthropic --out-trace $GITHUB_STEP_SUMMARY
               env:
                   ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
             - name: reasoning
               continue-on-error: true
-              run: yarn run:script tools -p anthropic -m reasoning --out-trace $GITHUB_STEP_SUMMARY
+              run: pnpm run:script tools -p anthropic -m reasoning --out-trace $GITHUB_STEP_SUMMARY
               env:
                   ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

.github/workflows/azure.yml

@@ -12,7 +12,7 @@ on:
             - ".github/workflows/azure.yml"
             - "packages/core/**/*"
             - "packages/cli/**/*"
-            - "packages/samples/**/*"
+            - "samples/**/*"
 concurrency:
     group: ${{ github.workflow }}-${{ github.ref }}-azure
     cancel-in-progress: true
@@ -24,15 +24,16 @@ jobs:
               with:
                   submodules: "recursive"
                   fetch-depth: 0
+            - uses: pnpm/action-setup@v4
             - uses: actions/setup-node@v4
               with:
                   node-version: "22"
-                  cache: yarn
-            - run: yarn install --frozen-lockfile
+                  cache: pnpm
+            - run: pnpm install --frozen-lockfile
             - name: compile
-              run: yarn compile:action
+              run: pnpm build:cli
             - name: poem
-              run: yarn run:script poem --model azure:gpt-4.1 -tlp 5 --out-trace $GITHUB_STEP_SUMMARY
+              run: pnpm run:script poem --model azure:gpt-4.1 -tlp 5 --out-trace $GITHUB_STEP_SUMMARY
               env:
                   AZURE_OPENAI_API_ENDPOINT: ${{ secrets.AZURE_OPENAI_API_ENDPOINT }}
                   AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}