auvrynt 1.0.1

package/dist/workspace-store.js

@@ -0,0 +1,125 @@
+import { eq } from "drizzle-orm";
+import { openDatabase } from "./db/client.js";
+import { workspaceSessions, } from "./db/schema.js";
+export class SqliteWorkspaceStore {
+    database;
+    constructor(stateDir) {
+        this.database = openDatabase(stateDir);
+        this.migrate();
+    }
+    createSession(input) {
+        const now = new Date().toISOString();
+        const session = {
+            id: input.id,
+            root: input.root,
+            status: "active",
+            mode: input.mode ?? "checkout",
+            sourceRoot: input.sourceRoot,
+            baseRef: input.baseRef,
+            baseSha: input.baseSha,
+            managed: input.managed ?? false,
+            createdAt: now,
+            lastUsedAt: now,
+        };
+        this.database.db
+            .insert(workspaceSessions)
+            .values({
+            id: session.id,
+            root: session.root,
+            status: session.status,
+            mode: session.mode,
+            sourceRoot: session.sourceRoot ?? null,
+            baseRef: session.baseRef ?? null,
+            baseSha: session.baseSha ?? null,
+            managed: String(session.managed),
+            createdAt: session.createdAt,
+            lastUsedAt: session.lastUsedAt,
+        })
+            .run();
+        return session;
+    }
+    getSession(id) {
+        const row = this.database.db
+            .select()
+            .from(workspaceSessions)
+            .where(eq(workspaceSessions.id, id))
+            .get();
+        return row ? rowToWorkspaceSession(row) : undefined;
+    }
+    touchSession(id) {
+        this.database.db
+            .update(workspaceSessions)
+            .set({ lastUsedAt: new Date().toISOString() })
+            .where(eq(workspaceSessions.id, id))
+            .run();
+    }
+    close() {
+        this.database.close();
+    }
+    migrate() {
+        this.database.sqlite.exec(`
+      create table if not exists workspace_sessions (
+        id text primary key,
+        root text not null,
+        status text not null default 'active',
+        mode text not null default 'checkout',
+        source_root text,
+        base_ref text,
+        base_sha text,
+        managed text not null default 'false',
+        created_at text not null,
+        last_used_at text not null
+      );
+
+      create index if not exists workspace_sessions_root_idx
+        on workspace_sessions(root, last_used_at desc);
+
+      create index if not exists workspace_sessions_status_idx
+        on workspace_sessions(status, last_used_at desc);
+
+      create table if not exists loaded_agent_files (
+        workspace_session_id text not null,
+        path text not null,
+        content_hash text not null,
+        content text not null,
+        loaded_at text not null,
+        last_seen_at text not null,
+        primary key (workspace_session_id, path),
+        foreign key (workspace_session_id)
+          references workspace_sessions(id)
+          on delete cascade
+      );
+
+      create index if not exists loaded_agent_files_path_idx
+        on loaded_agent_files(path);
+    `);
+        this.addColumnIfMissing("workspace_sessions", "mode", "text not null default 'checkout'");
+        this.addColumnIfMissing("workspace_sessions", "source_root", "text");
+        this.addColumnIfMissing("workspace_sessions", "base_ref", "text");
+        this.addColumnIfMissing("workspace_sessions", "base_sha", "text");
+        this.addColumnIfMissing("workspace_sessions", "managed", "text not null default 'false'");
+    }
+    addColumnIfMissing(table, column, definition) {
+        const columns = this.database.sqlite.prepare(`pragma table_info(${table})`).all();
+        if (columns.some((existingColumn) => existingColumn.name === column))
+            return;
+        this.database.sqlite.exec(`alter table ${table} add column ${column} ${definition}`);
+    }
+}
+export function createWorkspaceStore(stateDir) {
+    return new SqliteWorkspaceStore(stateDir);
+}
+function rowToWorkspaceSession(row) {
+    return {
+        id: row.id,
+        root: row.root,
+        status: row.status,
+        mode: row.mode === "worktree" ? "worktree" : "checkout",
+        sourceRoot: row.sourceRoot ?? undefined,
+        baseRef: row.baseRef ?? undefined,
+        baseSha: row.baseSha ?? undefined,
+        managed: row.managed === "true",
+        createdAt: row.createdAt,
+        lastUsedAt: row.lastUsedAt,
+    };
+}

package/dist/workspaces.js

@@ -0,0 +1,226 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, opendir, stat } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
+import { createManagedWorktree } from "./git-worktrees.js";
+import { assertAllowedPath, isPathInsideRoot, resolveAllowedPath } from "./roots.js";
+import { loadWorkspaceSkills, markSkillActivated, resolveSkillReadPath, } from "./skills.js";
+export class WorkspaceRegistry {
+    config;
+    store;
+    workspaces = new Map();
+    constructor(config, store) {
+        this.config = config;
+        this.store = store;
+    }
+    async openWorkspace(input) {
+        const options = typeof input === "string" ? { path: input } : input;
+        const mode = options.mode ?? "checkout";
+        if (mode === "worktree") {
+            return this.openWorktreeWorkspace(options.path, options.baseRef);
+        }
+        return this.openCheckoutWorkspace(options.path);
+    }
+    getWorkspace(workspaceId) {
+        const workspace = this.workspaces.get(workspaceId);
+        if (workspace) {
+            this.store?.touchSession(workspaceId);
+            return workspace;
+        }
+        const session = this.store?.getSession(workspaceId);
+        if (!session) {
+            throw new Error(`Unknown workspaceId: ${workspaceId}. Call open_workspace first.`);
+        }
+        const root = this.assertWorkspaceRootAllowed(session.root, session.mode, session.sourceRoot);
+        const restoredWorkspace = {
+            id: session.id,
+            root,
+            mode: session.mode,
+            sourceRoot: session.sourceRoot,
+            worktree: session.mode === "worktree"
+                ? {
+                    path: root,
+                    baseRef: session.baseRef ?? "HEAD",
+                    baseSha: session.baseSha ?? "",
+                    dirtySource: false,
+                    detached: true,
+                    managed: session.managed,
+                }
+                : undefined,
+            ...this.loadSkillsForWorkspace(root),
+            activatedSkillDirs: new Set(),
+        };
+        this.store?.touchSession(workspaceId);
+        this.workspaces.set(restoredWorkspace.id, restoredWorkspace);
+        return restoredWorkspace;
+    }
+    resolvePath(workspace, inputPath) {
+        const absolutePath = resolveAllowedPath(inputPath, workspace.root, [workspace.root]);
+        if (!isPathInsideRoot(absolutePath, workspace.root)) {
+            throw new Error(`Path is outside workspace root: ${inputPath}`);
+        }
+        return absolutePath;
+    }
+    resolveReadPath(workspace, inputPath) {
+        try {
+            return {
+                absolutePath: this.resolvePath(workspace, inputPath),
+                readRoots: [workspace.root],
+            };
+        }
+        catch (workspaceError) {
+            const skillRead = resolveSkillReadPath(workspace.skills, workspace.activatedSkillDirs, inputPath);
+            if (!skillRead)
+                throw workspaceError;
+            return {
+                absolutePath: skillRead.absolutePath,
+                readRoots: [workspace.root, skillRead.skill.baseDir],
+                skillRead,
+            };
+        }
+    }
+    markReadPathLoaded(workspace, readPath) {
+        if (readPath.skillRead?.isSkillFile) {
+            markSkillActivated(workspace.activatedSkillDirs, readPath.skillRead.skill);
+        }
+    }
+    resolveWorkingDirectory(workspace, workingDirectory) {
+        const directory = workingDirectory ? this.resolvePath(workspace, workingDirectory) : workspace.root;
+        return assertAllowedPath(directory, [workspace.root]);
+    }
+    async openCheckoutWorkspace(path) {
+        const root = assertAllowedPath(path, this.config.allowedRoots);
+        await mkdir(root, { recursive: true });
+        const rootStats = await stat(root);
+        if (!rootStats.isDirectory()) {
+            throw new Error(`Workspace root must be a directory: ${path}`);
+        }
+        return this.createWorkspaceContext({ root, mode: "checkout" });
+    }
+    async openWorktreeWorkspace(path, baseRef) {
+        const worktree = await createManagedWorktree({
+            sourcePath: path,
+            baseRef,
+            config: this.config,
+        });
+        return this.createWorkspaceContext({
+            root: worktree.path,
+            mode: "worktree",
+            sourceRoot: worktree.sourceRoot,
+            worktree,
+        });
+    }
+    async createWorkspaceContext(input) {
+        const workspace = {
+            id: `ws_${randomUUID()}`,
+            root: input.root,
+            mode: input.mode,
+            sourceRoot: input.sourceRoot,
+            worktree: input.worktree,
+            ...this.loadSkillsForWorkspace(input.root),
+            activatedSkillDirs: new Set(),
+        };
+        this.store?.createSession({
+            id: workspace.id,
+            root: workspace.root,
+            mode: workspace.mode,
+            sourceRoot: workspace.sourceRoot,
+            baseRef: workspace.worktree?.baseRef,
+            baseSha: workspace.worktree?.baseSha,
+            managed: workspace.worktree?.managed,
+        });
+        this.workspaces.set(workspace.id, workspace);
+        const agentsFiles = this.loadInitialAgentsFiles(workspace.root);
+        const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace.root, agentsFiles);
+        return { workspace, agentsFiles, availableAgentsFiles };
+    }
+    loadSkillsForWorkspace(root) {
+        const result = loadWorkspaceSkills(this.config, root);
+        return {
+            skills: result.skills,
+            skillDiagnostics: result.diagnostics,
+        };
+    }
+    assertWorkspaceRootAllowed(root, mode, sourceRoot) {
+        if (mode === "worktree") {
+            if (!sourceRoot) {
+                throw new Error(`Stored worktree workspace is missing sourceRoot: ${root}`);
+            }
+            assertAllowedPath(sourceRoot, this.config.allowedRoots);
+            return assertAllowedPath(root, [this.config.worktreeRoot]);
+        }
+        return assertAllowedPath(root, this.config.allowedRoots);
+    }
+    loadInitialAgentsFiles(root) {
+        const agentDir = resolve(this.config.agentDir);
+        return loadProjectContextFiles({ cwd: root, agentDir })
+            .filter((file) => {
+            const path = resolve(file.path);
+            if (isPathInsideRoot(path, agentDir))
+                return true;
+            return isPathInsideRoot(path, root) && dirname(path) === root;
+        })
+            .map((file) => ({
+            path: resolve(file.path),
+            content: file.content,
+        }));
+    }
+    async findAvailableAgentsFiles(root, loadedFiles) {
+        const loadedPaths = new Set(loadedFiles.map((file) => resolve(file.path)));
+        const discovered = [];
+        await walkWorkspace(root, async (path, entry) => {
+            if (!entry.isFile())
+                return;
+            if (!CONTEXT_FILE_NAMES.has(entry.name))
+                return;
+            if (loadedPaths.has(path))
+                return;
+            discovered.push({ path });
+        });
+        return discovered.sort((a, b) => a.path.localeCompare(b.path));
+    }
+}
+const CONTEXT_FILE_NAMES = new Set(["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]);
+const SKIPPED_CONTEXT_DIRS = new Set([
+    ".git",
+    ".hg",
+    ".svn",
+    ".auvrynt",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    ".cache",
+]);
+export function formatAgentsPath(path, workspaceRoot) {
+    if (!workspaceRoot)
+        return path.split(sep).join("/");
+    const relationship = relative(workspaceRoot, path);
+    if (relationship === "" ||
+        relationship.startsWith("..") ||
+        relationship === ".." ||
+        relationship.includes(`..${sep}`)) {
+        return path.split(sep).join("/");
+    }
+    return relationship.split(sep).join("/");
+}
+async function walkWorkspace(directory, visit) {
+    let entries;
+    try {
+        entries = await opendir(directory);
+    }
+    catch {
+        return;
+    }
+    for await (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIPPED_CONTEXT_DIRS.has(entry.name)) {
+                await walkWorkspace(path, visit);
+            }
+            continue;
+        }
+        await visit(path, entry);
+    }
+}

package/docs/DEVELOPMENT_TOOLS.md

@@ -0,0 +1,95 @@
+# Auvrynt Local Development Tools Guide
+
+Auvrynt extends Model Context Protocol (MCP) with tools for web application development, C#/.NET software development, Godot 4 game development, image inspection/comparison, and persistent process management.
+
+---
+
+## Architecture & Security Boundaries
+
+Use `get_connection_status` after `open_workspace` to automatically probe the
+authenticated MCP session, the local Blender bridge, the Godot editor bridge,
+browser support, Chrome MCP registration, and tracked workspace processes. A
+browser marked `available` means Playwright is installed; browser sessions are
+created on demand and are not persistent connections.
+
+1. **Workspace Boundary Enforcement**: Every path input must be relative to the opened workspace root. Path traversal (`..`) or symbolic links escaping the workspace are blocked by `WorkspaceRegistry.resolvePath`.
+2. **Persistent Processes**: Long-running servers, .NET applications, and Godot games run as background child processes managed by `ProcessManager`. Standard output and error streams are captured in bounded in-memory log buffers (max 1000 lines).
+3. **Secret Redaction**: Environment variables containing keywords like `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, or `CONNECTION_STRING` are automatically redacted in responses and log entries.
+4. **Browser & Network Security**: `capture_page_screenshot` and `inspect_page` enforce strict SSRF defenses, blocking non-HTTP(S) schemes (`file:`, `data:`, `javascript:`) and cloud metadata / private network IP addresses unless targeting recognized local development hosts (`localhost`, `127.0.0.1`, `[::1]`).
+
+---
+
+## Tool Reference
+
+### Phase 1: Persistent Process Management
+- `start_process`: Spawns background process inside workspace. Returns `processId`.
+- `get_process_logs`: Tail stdout/stderr for a process (default 100 lines, max 500 lines).
+- `list_processes`: List tracked background processes for a workspace.
+- `stop_process`: Gracefully stop or force-kill (`force: true`) process tree.
+
+### Phase 2: Structured Project Discovery & Search
+- `glob_files`: Fast file globbing respecting `.gitignore` and default exclusions (`.git`, `node_modules`, `dist`, `bin`, `obj`).
+- `search_text`: Workspace-wide text search returning matching lines and context snippets.
+- `inspect_project`: Auto-detect Node.js, TypeScript, .NET, Godot, Python, Git projects and recommended build/run/test commands.
+
+### Phase 3: Web-Development Tools
+- `start_dev_server`: Launch web dev server (auto-detects `npm run dev` script).
+- `capture_page_screenshot`: Playwright browser screenshot saved inside workspace and returned as MCP image content.
+- `inspect_page`: Extract structured page title, headings, buttons, links, landmarks, console errors, and failed requests.
+
+### Phase 4: Image and Screenshot Inspection
+- `inspect_image`: Inspect dimensions, format, MIME type, alpha, and color palette.
+- `compare_images`: RGBA pixel-by-pixel image comparison returning match %, changed pixels, and optional diff PNG output.
+- `inspect_sprite`: Analyze sprite sheet grid dimensions, cell divisibility, and frame bounds.
+- `split_sprite_sheet`: Slices sprite sheet into individual frame PNGs saved inside the workspace.
+
+### Phase 5: C# and .NET Tools
+- `inspect_dotnet_project`: Parse `.csproj`, `.fsproj`, `.sln` for SDK style, frameworks, packages, and test runner.
+- `dotnet_restore`: Run `dotnet restore` securely.
+- `dotnet_build`: Run `dotnet build` returning structured compiler errors/warnings with line and column.
+- `dotnet_test`: Run `dotnet test` returning pass/fail/skip counts, failed test names, and assertion messages.
+- `dotnet_run`: Launch .NET app as persistent process.
+- `dotnet_format`: Run `dotnet format` (`verifyOnly` mode supported).
+
+### Phase 6: Godot 4 Tools
+- `detect_godot_project`: Read `project.godot` for project name, main scene, renderer, autoloads, input actions.
+- `godot_run`: Launch Godot game or editor as persistent process. Environment variable `GODOT_EXECUTABLE` overrides path.
+- `inspect_godot_scene`: Parse `.tscn` text scene trees, node types, signals, and external resources.
+
+### Phase 7: Window Capture
+- `capture_window`: Capture screenshot of Auvrynt-tracked application window (Windows only).
+- `godot_capture_game`: Wrap window capture for Godot game processes.
+
+---
+
+## Development Workflows
+
+### Web Development Workflow
+```text
+1. open_workspace(path)
+2. inspect_project(workspaceId)
+3. start_dev_server(workspaceId)
+4. capture_page_screenshot(workspaceId, url="http://localhost:3000", outputPath="screenshots/home.png")
+5. inspect_page(workspaceId, url="http://localhost:3000")
+6. stop_process(workspaceId, processId)
+```
+
+### .NET Workflow
+```text
+1. open_workspace(path)
+2. inspect_dotnet_project(workspaceId, projectPath="MyApp.csproj")
+3. dotnet_restore(workspaceId, projectPath="MyApp.csproj")
+4. dotnet_build(workspaceId, projectPath="MyApp.csproj")
+5. dotnet_test(workspaceId, projectPath="MyApp.Tests.csproj")
+6. dotnet_run(workspaceId, projectPath="MyApp.csproj")
+```
+
+### Godot 4 Workflow
+```text
+1. open_workspace(path)
+2. detect_godot_project(workspaceId)
+3. inspect_godot_scene(workspaceId, scenePath="scenes/main.tscn")
+4. godot_run(workspaceId, projectPath=".")
+5. godot_capture_game(workspaceId, processId, outputPath="captures/game.png")
+6. stop_process(workspaceId, processId)
+```

package/docs/chatgpt-coding-workflow.md

@@ -0,0 +1,143 @@
+# ChatGPT Coding Workflow
+
+Auvrynt brings a Codex-style coding-agent loop to ChatGPT and other MCP hosts:
+inspect the repo, follow local instructions, make scoped edits, run
+verification, and show the user what changed.
+
+## Open One Workspace
+
+ChatGPT should call `open_workspace` once for a project folder:
+
+```json
+{
+  "path": "~/work/my-project"
+}
+```
+
+The result includes a `workspaceId`. All later file, search, edit, show-changes,
+and shell calls should reuse that same `workspaceId`.
+
+Do not reopen the same folder unless:
+
+- the `workspaceId` is rejected as unknown
+- the user switches to another folder
+- the user switches between checkout and worktree mode
+- the user explicitly asks to reopen
+
+## Checkout Mode
+
+Checkout mode is the default. Auvrynt opens the actual directory:
+
+```json
+{
+  "path": "~/work/my-project"
+}
+```
+
+Use this when the user wants ChatGPT to work in the current checkout.
+
+## Worktree Mode
+
+Use worktree mode for isolated parallel work:
+
+```json
+{
+  "path": "~/work/my-project",
+  "mode": "worktree"
+}
+```
+
+Managed worktrees are created under:
+
+```text
+~/.auvrynt/worktrees
+```
+
+Worktree mode requires a Git repository with at least one commit. It starts from
+`HEAD` unless `baseRef` is provided.
+
+Uncommitted source checkout changes are not copied into the managed worktree.
+Auvrynt reports when the source checkout was dirty so the model can decide how
+to proceed with the user.
+
+## Project Instructions
+
+When a workspace opens, Auvrynt loads root-level instruction files:
+
+- `AGENTS.md`
+- `AGENTS.MD`
+- `CLAUDE.md`
+- `CLAUDE.MD`
+
+Nested instruction files are returned as `availableAgentsFiles`. The model
+should read the relevant nested file before working under that directory.
+
+This keeps instructions explicit and inspectable instead of silently injecting
+new context during later tool calls.
+
+## Skills
+
+Skills are enabled by default for coding-agent workflows.
+
+Auvrynt discovers skills from:
+
+- `AUVRYNT_AGENT_DIR`, which defaults to `~/.codex`
+- project `.pi/skills`
+- optional paths from `AUVRYNT_SKILL_PATHS`
+
+When `open_workspace` returns matching skills, the model should read the
+advertised `SKILL.md` before following that skill.
+
+Skill paths may be outside the workspace. Auvrynt only permits reading:
+
+- advertised `SKILL.md` files
+- files under a skill directory after that skill's `SKILL.md` has been read
+
+Set `AUVRYNT_SKILLS=0` to hide skills from workspace output.
+
+## Tool Names
+
+Short names are the default:
+
+- `open_workspace`
+- `read`
+- `write`
+- `edit`
+- `bash`
+
+By default, Auvrynt also runs in `AUVRYNT_TOOL_MODE=minimal`, so dedicated
+`grep`, `glob`, and `ls` tools are hidden. Use `bash` with command-line tools
+such as `rg`, `find`, and `ls` for search and directory inspection.
+
+Legacy names are available with `AUVRYNT_TOOL_NAMING=legacy`:
+
+- `open_workspace`
+- `read_file`
+- `write_file`
+- `edit_file`
+- `run_shell`
+
+Use `AUVRYNT_TOOL_MODE=full` to restore dedicated search and directory tools.
+
+## Show Changes
+
+By default, `AUVRYNT_WIDGETS=full`.
+
+In that mode, Auvrynt attaches widget UI to the exposed workspace, file, edit,
+and shell tools. The aggregate `show_changes` tool is not exposed by default.
+
+Use `AUVRYNT_WIDGETS=off` to disable widget UI, or `AUVRYNT_WIDGETS=changes`
+to expose the aggregate show-changes flow.
+
+## Shell Use
+
+The shell tool is for commands that belong in a terminal:
+
+- tests
+- builds
+- git inspection
+- package scripts
+- environment checks
+
+File writes should go through the edit/write tools rather than shell
+redirection, heredocs, `tee`, `sed -i`, or generated scripts.