@waishnav/devspace 1.0.0

package/docs/chatgpt-coding-workflow.md

@@ -0,0 +1,143 @@
+# ChatGPT Coding Workflow
+
+DevSpace 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, review, 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. DevSpace 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
+~/.devspace/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.
+DevSpace reports when the source checkout was dirty so the model can decide how
+to proceed with the user.
+
+## Project Instructions
+
+When a workspace opens, DevSpace 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.
+
+DevSpace discovers skills from:
+
+- `DEVSPACE_AGENT_DIR`, which defaults to `~/.codex`
+- project `.pi/skills`
+- optional paths from `DEVSPACE_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. DevSpace only permits reading:
+
+- advertised `SKILL.md` files
+- files under a skill directory after that skill's `SKILL.md` has been read
+
+Set `DEVSPACE_SKILLS=0` to hide skills from workspace output.
+
+## Tool Names
+
+Legacy names are the default:
+
+- `open_workspace`
+- `read_file`
+- `write_file`
+- `edit_file`
+- `grep_files`
+- `find_files`
+- `list_directory`
+- `run_shell`
+
+Short names are available with `DEVSPACE_TOOL_NAMING=short`:
+
+- `open_workspace`
+- `read`
+- `write`
+- `edit`
+- `grep`
+- `glob`
+- `ls`
+- `bash`
+
+## Review Changes
+
+By default, `DEVSPACE_WIDGETS=changes`.
+
+In that mode, DevSpace exposes `review_changes`. After a coherent set of edits,
+the model should call it once to show an aggregate diff review card.
+
+Use `DEVSPACE_WIDGETS=off` to disable widget UI, or `DEVSPACE_WIDGETS=full` to
+restore per-tool debug cards.
+
+## 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.

package/docs/configuration.md

@@ -0,0 +1,129 @@
+# Configuration Reference
+
+DevSpace can be configured through `devspace init`, persisted config files, or
+environment variables.
+
+The default files are:
+
+```text
+~/.devspace/config.json
+~/.devspace/auth.json
+```
+
+Use another config directory with:
+
+```bash
+DEVSPACE_CONFIG_DIR=/path/to/config npx @waishnav/devspace serve
+```
+
+## Commands
+
+```bash
+npx @waishnav/devspace init
+npx @waishnav/devspace serve
+npx @waishnav/devspace doctor
+npx @waishnav/devspace config get
+npx @waishnav/devspace config set publicBaseUrl https://devspace.example.com
+```
+
+## Core Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `HOST` | Local bind host. Defaults to `127.0.0.1`. |
+| `PORT` | Local port. Defaults to `7676`. |
+| `DEVSPACE_ALLOWED_ROOTS` | Comma-separated local roots that workspaces may open. |
+| `DEVSPACE_PUBLIC_BASE_URL` | Public origin for the server, without `/mcp`. |
+| `DEVSPACE_ALLOWED_HOSTS` | Optional Host header allowlist override. |
+| `DEVSPACE_OAUTH_OWNER_TOKEN` | Owner password for OAuth approval. Must be at least 16 characters. |
+| `DEVSPACE_WORKTREE_ROOT` | Directory for managed Git worktrees. Defaults to `~/.devspace/worktrees`. |
+| `DEVSPACE_STATE_DIR` | Directory for SQLite state. Defaults to `~/.local/share/devspace`. |
+
+## OAuth
+
+DevSpace uses a single-user OAuth approval flow.
+
+| Variable | Default |
+| --- | --- |
+| `DEVSPACE_OAUTH_ACCESS_TOKEN_TTL_SECONDS` | `3600` |
+| `DEVSPACE_OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `2592000` |
+| `DEVSPACE_OAUTH_SCOPES` | `devspace` |
+| `DEVSPACE_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
+
+`DEVSPACE_TOOL_NAMING` controls tool names.
+
+| Value | Behavior |
+| --- | --- |
+| `legacy` | Default. Uses `read_file`, `edit_file`, `run_shell`, and related names. |
+| `short` | Uses `read`, `edit`, `bash`, and related names. |
+
+`DEVSPACE_TOOL_MODE=minimal` disables dedicated search and list tools. In
+minimal mode, clients use the shell tool with `rg`, `grep`, `find`, `ls`, or
+`tree` for inspection.
+
+## Widgets
+
+`DEVSPACE_WIDGETS` controls ChatGPT Apps iframe usage.
+
+| Value | Behavior |
+| --- | --- |
+| `changes` | Default. Widget UI is attached to `open_workspace` and `review_changes`. |
+| `full` | Enables legacy per-tool cards for debugging. |
+| `off` | Disables widget UI. |
+
+## Skills
+
+| Variable | Purpose |
+| --- | --- |
+| `DEVSPACE_SKILLS` | Set to `0` to hide skills. Enabled by default. |
+| `DEVSPACE_AGENT_DIR` | Defaults to `~/.codex`. |
+| `DEVSPACE_SKILL_PATHS` | Optional comma-separated skill directories. |
+
+Example:
+
+```bash
+DEVSPACE_SKILL_PATHS="$HOME/.codex/skills,$HOME/.claude/skills" \
+npx @waishnav/devspace serve
+```
+
+## Logging
+
+| Variable | Default |
+| --- | --- |
+| `DEVSPACE_LOG_LEVEL` | `info` |
+| `DEVSPACE_LOG_FORMAT` | `json` |
+| `DEVSPACE_LOG_REQUESTS` | `1` |
+| `DEVSPACE_LOG_ASSETS` | `0` |
+| `DEVSPACE_LOG_TOOL_CALLS` | `1` |
+| `DEVSPACE_LOG_SHELL_COMMANDS` | `0` |
+| `DEVSPACE_TRUST_PROXY` | `0` |
+
+Set `DEVSPACE_LOG_FORMAT=pretty` for local debugging.
+
+Set `DEVSPACE_LOG_SHELL_COMMANDS=1` only when you intentionally want command
+previews in logs.
+
+## Env-Only Example
+
+```bash
+DEVSPACE_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)" \
+DEVSPACE_ALLOWED_ROOTS="$HOME/personal,$HOME/work" \
+DEVSPACE_PUBLIC_BASE_URL="https://devspace.example.com" \
+DEVSPACE_WORKTREE_ROOT="$HOME/.devspace/worktrees" \
+DEVSPACE_TOOL_MODE="full" \
+DEVSPACE_TOOL_NAMING="legacy" \
+DEVSPACE_WIDGETS="changes" \
+npx @waishnav/devspace serve
+```
+
+The environment assignments must be part of the same command invocation, or
+exported first.

package/docs/gotchas.md

@@ -0,0 +1,214 @@
+# Troubleshooting Gotchas
+
+This page collects the setup issues users are most likely to hit.
+
+## `devspace` Command Not Found
+
+Use `npx`:
+
+```bash
+npx @waishnav/devspace init
+npx @waishnav/devspace serve
+```
+
+If you installed globally, confirm npm's global bin directory is on `PATH`.
+
+## Unsupported Node Version
+
+DevSpace 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 @waishnav/devspace 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 @waishnav/devspace 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
+DEVSPACE_PUBLIC_BASE_URL="https://new-tunnel.example.com" npx @waishnav/devspace serve
+```
+
+For a stable URL:
+
+```bash
+npx @waishnav/devspace config set publicBaseUrl https://devspace.example.com
+```
+
+## Host Header Or 403 Problems
+
+DevSpace derives allowed hosts from the configured public URL.
+
+Run:
+
+```bash
+npx @waishnav/devspace 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
+DEVSPACE_ALLOWED_HOSTS="*" npx @waishnav/devspace serve
+```
+
+## OAuth Redirect Host Rejected
+
+By default, DevSpace allows redirects for:
+
+```text
+chatgpt.com
+localhost
+127.0.0.1
+```
+
+If another MCP client uses a different redirect host, configure:
+
+```bash
+DEVSPACE_OAUTH_ALLOWED_REDIRECT_HOSTS="chatgpt.com,example.com" npx @waishnav/devspace serve
+```
+
+## Owner Password Not Accepted
+
+Make sure you are entering the Owner password from:
+
+```text
+~/.devspace/auth.json
+```
+
+To regenerate setup:
+
+```bash
+npx @waishnav/devspace 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 @waishnav/devspace config get
+```
+
+Then either open a project under an allowed root or rerun setup:
+
+```bash
+npx @waishnav/devspace 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
+
+DevSpace 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 @waishnav/devspace doctor
+```
+
+Confirm Bash is detected.
+
+## Skills Do Not Appear
+
+Skills are enabled by default. Check:
+
+```bash
+DEVSPACE_SKILLS=1 npx @waishnav/devspace serve
+```
+
+DevSpace looks in:
+
+- `DEVSPACE_AGENT_DIR`, defaulting to `~/.codex`
+- project `.pi/skills`
+- `DEVSPACE_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
+
+The aggregate diff card is enabled by default with:
+
+```bash
+DEVSPACE_WIDGETS=changes
+```
+
+The model should call `review_changes` after a coherent set of edits. Plain MCP
+clients may ignore ChatGPT Apps widget metadata and only show text results.

package/docs/security.md

@@ -0,0 +1,100 @@
+# Security Model
+
+DevSpace 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
+
+DevSpace 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
+
+`devspace init` generates an Owner password and stores it in:
+
+```text
+~/.devspace/auth.json
+```
+
+When an MCP client connects, DevSpace 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
+DEVSPACE_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)"
+```
+
+## Public URL And Host Allowlist
+
+DevSpace needs `DEVSPACE_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 `DEVSPACE_PUBLIC_BASE_URL`.
+
+By default, DevSpace derives allowed Host headers from the local host and public
+URL. Use `DEVSPACE_ALLOWED_HOSTS=*` only for intentional local debugging.
+
+## Tunnels
+
+DevSpace does not manage tunnels. Your tunnel or reverse proxy should point to:
+
+```text
+http://127.0.0.1:7676
+```
+
+Prefer adding Cloudflare Access, Tailscale identity controls, or equivalent
+protection in front of public tunnels. DevSpace 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 DevSpace 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, DevSpace logs requests and tool calls. Shell command previews are
+disabled unless `DEVSPACE_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 DevSpace.
+
+## 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 DevSpace server
+
+DevSpace 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 @waishnav/devspace init
+```
+
+The setup flow asks one question at a time.
+
+### Project Roots
+
+Choose the folders ChatGPT is allowed to open through DevSpace. 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 `7676`.
+
+The local MCP URL is:
+
+```text
+http://127.0.0.1:7676/mcp
+```
+
+### Public Base URL
+
+Start your tunnel or reverse proxy before entering this value. Point the tunnel
+at:
+
+```text
+http://127.0.0.1:7676
+```
+
+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 @waishnav/devspace serve
+```
+
+If your tunnel URL changes for one run, override it without rewriting config:
+
+```bash
+DEVSPACE_PUBLIC_BASE_URL="https://new-tunnel.example.com" npx @waishnav/devspace serve
+```
+
+For a stable public URL, persist it:
+
+```bash
+npx @waishnav/devspace config set publicBaseUrl https://devspace.example.com
+npx @waishnav/devspace serve
+```
+
+## Approve The Client
+
+When ChatGPT, Claude, or another MCP client connects, DevSpace shows an Owner
+password approval page. Enter the Owner password printed during setup.
+
+The default config files are:
+
+```text
+~/.devspace/config.json
+~/.devspace/auth.json
+```
+
+Keep `auth.json` private.
+
+## Check Your Setup
+
+Run:
+
+```bash
+npx @waishnav/devspace 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 DevSpace itself instead of using the published package:
+
+```bash
+npm install --include=dev
+npm run dev
+```
+
+The same setup rules apply.