auvrynt 1.0.1

package/docs/configuration.md

@@ -0,0 +1,132 @@
+# Configuration Reference
+
+Auvrynt can be configured through `auvrynt init`, persisted config files, or
+environment variables.
+
+The default files are:
+
+```text
+~/.auvrynt/config.json
+~/.auvrynt/auth.json
+```
+
+Use another config directory with:
+
+```bash
+AUVRYNT_CONFIG_DIR=/path/to/config npx auvrynt serve
+```
+
+## Commands
+
+```bash
+npx auvrynt init
+npx auvrynt serve
+npx auvrynt doctor
+npx auvrynt config get
+npx auvrynt config set publicBaseUrl https://auvrynt.example.com
+```
+
+## Core Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `HOST` | Local bind host. Defaults to `127.0.0.1`. |
+| `PORT` | Local port. Defaults to `49321`. |
+| `AUVRYNT_ALLOWED_ROOTS` | Comma-separated local roots that workspaces may open. |
+| `AUVRYNT_PUBLIC_BASE_URL` | Public origin for the server, without `/mcp`. |
+| `AUVRYNT_ALLOWED_HOSTS` | Optional Host header allowlist override. |
+| `AUVRYNT_OAUTH_OWNER_TOKEN` | Owner password for OAuth approval. Must be at least 16 characters. |
+| `AUVRYNT_WORKTREE_ROOT` | Directory for managed Git worktrees. Defaults to `~/.auvrynt/worktrees`. |
+| `AUVRYNT_STATE_DIR` | Directory for SQLite state. Defaults to `~/.local/share/auvrynt`. |
+
+## OAuth
+
+Auvrynt uses a single-user OAuth approval flow.
+
+| Variable | Default |
+| --- | --- |
+| `AUVRYNT_OAUTH_ACCESS_TOKEN_TTL_SECONDS` | `3600` |
+| `AUVRYNT_OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `2592000` |
+| `AUVRYNT_OAUTH_SCOPES` | `auvrynt` |
+| `AUVRYNT_OAUTH_ALLOWED_REDIRECT_HOSTS` | `chatgpt.com,localhost,127.0.0.1` |
+
+MCP clients discover metadata from:
+
+```text
+/.well-known/oauth-protected-resource/mcp
+/.well-known/oauth-authorization-server
+```
+
+## Tool Modes
+
+`AUVRYNT_TOOL_NAMING` controls tool names.
+
+| Value | Behavior |
+| --- | --- |
+| `short` | Default. Uses `read`, `edit`, `bash`, and related names. |
+| `legacy` | Uses `read_file`, `edit_file`, `run_shell`, and related names. |
+
+`AUVRYNT_TOOL_MODE` controls the tool surface.
+
+| Value | Behavior |
+| --- | --- |
+| `minimal` | Default. Disables dedicated search and list tools. Clients use the shell tool with `rg`, `grep`, `find`, `ls`, or `tree` for inspection. |
+| `full` | Enables dedicated `grep`, `glob`, and `ls` tools. |
+
+## Widgets
+
+`AUVRYNT_WIDGETS` controls ChatGPT Apps iframe usage.
+
+| Value | Behavior |
+| --- | --- |
+| `full` | Default. Widget UI is attached to exposed workspace, file, edit, and shell tools. |
+| `changes` | Enables the aggregate `show_changes` tool and attaches widget UI to `open_workspace` and `show_changes`. |
+| `off` | Disables widget UI. |
+
+## Skills
+
+| Variable | Purpose |
+| --- | --- |
+| `AUVRYNT_SKILLS` | Set to `0` to hide skills. Enabled by default. |
+| `AUVRYNT_AGENT_DIR` | Defaults to `~/.codex`. |
+| `AUVRYNT_SKILL_PATHS` | Optional comma-separated skill directories. |
+
+Example:
+
+```bash
+AUVRYNT_SKILL_PATHS="$HOME/.codex/skills,$HOME/.claude/skills" \
+npx auvrynt serve
+```
+
+## Logging
+
+| Variable | Default |
+| --- | --- |
+| `AUVRYNT_LOG_LEVEL` | `info` |
+| `AUVRYNT_LOG_FORMAT` | `json` |
+| `AUVRYNT_LOG_REQUESTS` | `1` |
+| `AUVRYNT_LOG_ASSETS` | `0` |
+| `AUVRYNT_LOG_TOOL_CALLS` | `1` |
+| `AUVRYNT_LOG_SHELL_COMMANDS` | `0` |
+| `AUVRYNT_TRUST_PROXY` | `0` |
+
+Set `AUVRYNT_LOG_FORMAT=pretty` for local debugging.
+
+Set `AUVRYNT_LOG_SHELL_COMMANDS=1` only when you intentionally want command
+previews in logs.
+
+## Env-Only Example
+
+```bash
+AUVRYNT_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)" \
+AUVRYNT_ALLOWED_ROOTS="$HOME/personal,$HOME/work" \
+AUVRYNT_PUBLIC_BASE_URL="https://auvrynt.example.com" \
+AUVRYNT_WORKTREE_ROOT="$HOME/.auvrynt/worktrees" \
+AUVRYNT_TOOL_MODE="minimal" \
+AUVRYNT_TOOL_NAMING="short" \
+AUVRYNT_WIDGETS="full" \
+npx auvrynt serve
+```
+
+The environment assignments must be part of the same command invocation, or
+exported first.

package/docs/gotchas.md

@@ -0,0 +1,215 @@
+# Troubleshooting Gotchas
+
+This page collects the setup issues users are most likely to hit.
+
+## `auvrynt` Command Not Found
+
+Use `npx`:
+
+```bash
+npx auvrynt init
+npx auvrynt serve
+```
+
+If you installed globally, confirm npm's global bin directory is on `PATH`.
+
+## Unsupported Node Version
+
+Auvrynt requires Node `>=20.12 <27`.
+
+Check:
+
+```bash
+node --version
+```
+
+Install Node 22 LTS with your preferred version manager such as `nvm`, `fnm`, or
+`mise`.
+
+## `better-sqlite3` Could Not Load
+
+This usually means native dependencies were installed under a different Node
+runtime.
+
+Try:
+
+```bash
+npm rebuild better-sqlite3
+```
+
+Then run:
+
+```bash
+npx auvrynt doctor
+```
+
+Release starts run a native dependency check before launching.
+
+## Public URL Includes `/mcp`
+
+Use the origin for setup:
+
+```text
+https://your-tunnel-host.example.com
+```
+
+Use the MCP endpoint in the client:
+
+```text
+https://your-tunnel-host.example.com/mcp
+```
+
+If you saved the wrong value:
+
+```bash
+npx auvrynt config set publicBaseUrl https://your-tunnel-host.example.com
+```
+
+## Tunnel URL Changed
+
+Temporary tunnels often change URLs between runs.
+
+For a one-off run:
+
+```bash
+AUVRYNT_PUBLIC_BASE_URL="https://new-tunnel.example.com" npx auvrynt serve
+```
+
+For a stable URL:
+
+```bash
+npx auvrynt config set publicBaseUrl https://auvrynt.example.com
+```
+
+## Host Header Or 403 Problems
+
+Auvrynt derives allowed hosts from the configured public URL.
+
+Run:
+
+```bash
+npx auvrynt doctor
+```
+
+Confirm the public URL hostname appears in allowed hosts. If you changed tunnel
+URLs, update `publicBaseUrl`.
+
+Use this only for intentional local debugging:
+
+```bash
+AUVRYNT_ALLOWED_HOSTS="*" npx auvrynt serve
+```
+
+## OAuth Redirect Host Rejected
+
+By default, Auvrynt allows redirects for:
+
+```text
+chatgpt.com
+localhost
+127.0.0.1
+```
+
+If another MCP client uses a different redirect host, configure:
+
+```bash
+AUVRYNT_OAUTH_ALLOWED_REDIRECT_HOSTS="chatgpt.com,example.com" npx auvrynt serve
+```
+
+## Owner Password Not Accepted
+
+Make sure you are entering the Owner password from:
+
+```text
+~/.auvrynt/auth.json
+```
+
+To regenerate setup:
+
+```bash
+npx auvrynt init --force
+```
+
+## Unknown `workspaceId`
+
+`workspaceId` values are session identifiers. If the server restarts and the
+client receives an unknown workspace error, call `open_workspace` again for that
+project.
+
+Workspace session metadata is persisted, but clients should still treat
+`open_workspace` as the way to begin a fresh working session.
+
+## Workspace Path Rejected
+
+The path must be inside one of the allowed roots configured during setup.
+
+Run:
+
+```bash
+npx auvrynt config get
+```
+
+Then either open a project under an allowed root or rerun setup:
+
+```bash
+npx auvrynt init --force
+```
+
+## Worktree Mode Fails
+
+Worktree mode requires:
+
+- Git installed
+- the path is inside a Git repository
+- the repository has at least one commit
+- the requested `baseRef` resolves to a commit
+
+For a new repository, create the first commit or use checkout mode.
+
+Uncommitted source checkout changes are not copied into the managed worktree.
+Commit, stash, or ask the model to work in checkout mode if those changes are
+needed.
+
+## Windows Shell Commands Fail
+
+Auvrynt shell execution requires Bash. Native PowerShell and `cmd.exe` command
+execution are not supported yet.
+
+Install Git for Windows and use Git Bash, or use WSL, MSYS2, or Cygwin Bash.
+
+Run:
+
+```bash
+npx auvrynt doctor
+```
+
+Confirm Bash is detected.
+
+## Skills Do Not Appear
+
+Skills are enabled by default. Check:
+
+```bash
+AUVRYNT_SKILLS=1 npx auvrynt serve
+```
+
+Auvrynt looks in:
+
+- `AUVRYNT_AGENT_DIR`, defaulting to `~/.codex`
+- project `.pi/skills`
+- `AUVRYNT_SKILL_PATHS`
+
+If a skill appears in `open_workspace`, the model must read that skill's
+`SKILL.md` before reading other files inside the skill directory.
+
+## Review Card Does Not Appear
+
+Per-tool widget cards are enabled by default with:
+
+```bash
+AUVRYNT_WIDGETS=full
+```
+
+The aggregate `show_changes` tool is only exposed with
+`AUVRYNT_WIDGETS=changes`. Plain MCP clients may ignore ChatGPT Apps widget
+metadata and only show text results.

package/docs/security.md

@@ -0,0 +1,100 @@
+# Security Model
+
+Auvrynt exposes local coding capabilities over MCP. Treat it as remote access
+to your development machine.
+
+The security model is simple:
+
+- you choose a narrow filesystem allowlist
+- the MCP endpoint requires OAuth approval with your Owner password
+- Host headers are allowlisted from the configured public URL
+- every coding action happens through explicit MCP tool calls
+
+## Filesystem Allowlist
+
+Auvrynt only opens workspaces under configured roots.
+
+Good examples:
+
+```text
+~/work
+~/personal/open-source
+```
+
+Avoid broad roots:
+
+```text
+~
+/
+C:\
+```
+
+The narrower the root, the easier it is to reason about what the MCP client can
+reach.
+
+## Owner Password
+
+`auvrynt init` generates an Owner password and stores it in:
+
+```text
+~/.auvrynt/auth.json
+```
+
+When an MCP client connects, Auvrynt shows an approval page. Enter the Owner
+password only when you intentionally want that client to access this server.
+
+For env-driven deployments, set a long random value:
+
+```bash
+AUVRYNT_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)"
+```
+
+## Public URL And Host Allowlist
+
+Auvrynt needs `AUVRYNT_PUBLIC_BASE_URL` so MCP clients can discover OAuth
+metadata and connect to the correct resource.
+
+The value should be the origin only:
+
+```text
+https://your-tunnel-host.example.com
+```
+
+Do not include `/mcp` in `AUVRYNT_PUBLIC_BASE_URL`.
+
+By default, Auvrynt derives allowed Host headers from the local host and public
+URL. Use `AUVRYNT_ALLOWED_HOSTS=*` only for intentional local debugging.
+
+## Tunnels
+
+Auvrynt does not manage tunnels. Your tunnel or reverse proxy should point to:
+
+```text
+http://127.0.0.1:49321
+```
+
+Prefer adding Cloudflare Access, Tailscale identity controls, or equivalent
+protection in front of public tunnels. Auvrynt OAuth still protects the MCP
+endpoint, but the tunnel URL should not be treated as a secret.
+
+## Shell Access
+
+The shell tool is powerful by design. It is meant for tests, builds, git, and
+package scripts.
+
+Filesystem path containment applies to Auvrynt file tools. Shell commands run
+as local commands and can do what your user account can do. This is why the MCP
+client must be trusted and the Owner password must stay private.
+
+## Worktrees
+
+Managed worktrees reduce accidental edits to your active checkout, but they are
+not a security boundary. They are a workflow boundary for isolated coding
+sessions.
+
+## Logs
+
+By default, Auvrynt logs requests and tool calls. Shell command previews are
+disabled unless `AUVRYNT_LOG_SHELL_COMMANDS=1`.
+
+Do not enable shell command logging if commands may contain secrets.

package/docs/setup.md

@@ -0,0 +1,132 @@
+# Setup Guide
+
+This guide is for users who want ChatGPT or another MCP host to work in local
+projects through Auvrynt.
+
+## Requirements
+
+- Node `>=20.12 <27`; Node 22 LTS is recommended
+- npm
+- Git
+- Bash, including Git Bash or WSL on Windows
+- a public HTTPS URL that forwards to the local Auvrynt server
+
+Auvrynt does not create the public tunnel for you. Use Cloudflare Tunnel,
+ngrok, Pinggy, Tailscale Funnel, or your own HTTPS reverse proxy.
+
+## Install And Configure
+
+Run:
+
+```bash
+npx auvrynt init
+```
+
+The setup flow asks one question at a time.
+
+### Project Roots
+
+Choose the folders ChatGPT is allowed to open through Auvrynt. Keep this
+narrow.
+
+Examples:
+
+```text
+~/personal,~/work
+```
+
+```text
+/Users/alice/dev,/Users/alice/work
+```
+
+```text
+C:\Users\alice\dev,C:\Users\alice\work
+```
+
+### Local Port
+
+The default is `49321`.
+
+The local MCP URL is:
+
+```text
+http://127.0.0.1:49321/mcp
+```
+
+### Public Base URL
+
+Start your tunnel or reverse proxy before entering this value. Point the tunnel
+at:
+
+```text
+http://127.0.0.1:49321
+```
+
+Enter the public origin without `/mcp`:
+
+```text
+https://your-tunnel-host.example.com
+```
+
+Configure the MCP client with the full MCP endpoint:
+
+```text
+https://your-tunnel-host.example.com/mcp
+```
+
+## Start The Server
+
+Run:
+
+```bash
+npx auvrynt serve
+```
+
+If your tunnel URL changes for one run, override it without rewriting config:
+
+```bash
+AUVRYNT_PUBLIC_BASE_URL="https://new-tunnel.example.com" npx auvrynt serve
+```
+
+For a stable public URL, persist it:
+
+```bash
+npx auvrynt config set publicBaseUrl https://auvrynt.example.com
+npx auvrynt serve
+```
+
+## Approve The Client
+
+When ChatGPT, Claude, or another MCP client connects, Auvrynt shows an Owner
+password approval page. Enter the Owner password printed during setup.
+
+The default config files are:
+
+```text
+~/.auvrynt/config.json
+~/.auvrynt/auth.json
+```
+
+Keep `auth.json` private.
+
+## Check Your Setup
+
+Run:
+
+```bash
+npx auvrynt doctor
+```
+
+The doctor command reports the resolved config, Node version, Node ABI, platform,
+Git, Bash, public URL, allowed hosts, and SQLite native dependency status.
+
+## Running From A Local Checkout
+
+If you are developing Auvrynt itself instead of using the published package:
+
+```bash
+npm install --include=dev
+npm run dev
+```
+
+The same setup rules apply.

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "auvrynt",
+  "version": "1.0.1",
+  "description": "Expose a secure local coding workspace through an MCP server.",
+  "type": "module",
+  "main": "dist/server.js",
+  "engines": {
+    "node": ">=20.12 <27"
+  },
+  "bin": {
+    "auvrynt": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "scripts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && npm run build:app && tsc -p tsconfig.build.json",
+    "build:app": "vite build",
+    "dev": "node scripts/dev-server.mjs",
+    "start": "node dist/cli.js serve",
+    "test": "tsx src/config.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/view-image.test.ts && tsx src/processes.test.ts && tsx src/search-discovery.test.ts && tsx src/web-tools.test.ts && tsx src/image-tools.test.ts && tsx src/dotnet-tools.test.ts && tsx src/godot-tools.test.ts && tsx src/godot-dotnet-env.test.ts && tsx src/godot-csharp-project.test.ts && tsx src/godot-csharp-runner.test.ts && tsx src/godot-csharp-semantic.test.ts && tsx src/blender-tools.test.ts && tsx src/godot-gdscript.test.ts && tsx src/review-checkpoints.test.ts && tsx src/workspaces.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "@earendil-works/pi-coding-agent": "^0.79.4",
+    "@modelcontextprotocol/ext-apps": "^1.7.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@pierre/diffs": "^1.2.5",
+    "better-sqlite3": "^12.11.1",
+    "drizzle-orm": "^0.45.2",
+    "express": "^5.2.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "semver": "^7.8.4",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@types/semver": "^7.7.1",
+    "@vitejs/plugin-react": "^6.0.2",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.14"
+  },
+  "overrides": {
+    "protobufjs": "7.6.4",
+    "ws": "8.21.0"
+  },
+  "allowScripts": {
+    "better-sqlite3@12.11.1": true,
+    "esbuild@0.28.1": true,
+    "protobufjs@7.6.4": true,
+    "@google/genai@1.52.0": true
+  }
+}