@akira-tl/forgerelay 0.1.0

package/docs/artifact-exchange.md

@@ -0,0 +1,63 @@
+# Native File Download
+
+ForgeRelay can save a file attached to or generated by an MCP host directly into
+an already-open workspace.
+
+Enable the capability with:
+
+```bash
+FORGERELAY_ARTIFACTS=1 forgerelay serve
+```
+
+The legacy `DEVSPACE_ARTIFACTS` variable remains a fallback during migration.
+
+## Workflow
+
+1. Open the destination project with `open_workspace`.
+2. Call `download_artifact` with the native file value supplied by the MCP host,
+   the existing `workspaceId`, and a workspace-relative destination path.
+3. Use the returned normalized path with ordinary ForgeRelay file tools.
+
+The tool creates missing parent directories and refuses to overwrite an existing
+destination.
+
+## Input boundary
+
+The `file` input must be the native value supplied by the MCP connector. Do not
+replace it with:
+
+- an arbitrary URL string;
+- a local host path guessed by the model;
+- base64 content;
+- embedded credentials;
+- an expanded object containing unsupported fields.
+
+Signed URLs/native connector objects should not be copied into shell commands or
+logs.
+
+## Limits
+
+Downloads are streamed under the configured maximum:
+
+```text
+FORGERELAY_ARTIFACT_MAX_FILE_BYTES
+```
+
+The default is 100 MiB (`104857600`). Partial temporary files use a private
+ForgeRelay prefix and are published without overwrite after successful transfer.
+
+The secure native-file publication implementation is currently exposed on Linux
+where the required descriptor-anchored filesystem path is available.
+
+## Non-goals
+
+There is currently no:
+
+- artifact quota or artifact-root database;
+- TTL/pinning system;
+- automatic background artifact cleanup service;
+- arbitrary URL download mode;
+- conflict/overwrite mode.
+
+Use normal workspace tools for explicit inspection, replacement, movement,
+renaming, or deletion after the file is present.

package/docs/chatgpt-coding-workflow.md

@@ -0,0 +1,183 @@
+# ChatGPT Coding Workflow
+
+ForgeRelay gives ChatGPT and other MCP hosts a local coding workspace with an
+explicit lifecycle instead of treating every request as a fresh temporary
+checkout.
+
+## Workspace identity
+
+`open_workspace` returns a `workspaceId`. Continue using that ID for later tools
+in the same directory.
+
+Workspace identity follows the canonical opened directory rather than the
+conversation/request identity. Reopening the same checkout reuses the same
+active workspace even from another conversation. Conversation metadata is used
+only to decide whether bootstrap context such as project instructions should be
+repeated to that conversation.
+
+A Git worktree directory is a separate workspace identity from its source
+checkout.
+
+## Checkout-first behavior
+
+Checkout mode is the default:
+
+```text
+open_workspace(path="~/project")
+```
+
+ForgeRelay works directly in that directory. It does not silently create an
+isolated checkout.
+
+Use worktree mode only when the user explicitly requests isolated or parallel
+work:
+
+```text
+open_workspace(path="~/project", mode="worktree")
+```
+
+## Managed worktrees
+
+New ForgeRelay worktrees are branch-backed, not detached. A managed branch looks
+like:
+
+```text
+forgerelay/<repo>-<id>
+```
+
+The worktree normally lives under:
+
+```text
+~/.forgerelay/worktrees
+```
+
+Existing configured/legacy roots remain supported.
+
+The recorded target branch is the local branch that should receive completed
+work. An explicit `baseRef` must identify a local branch.
+
+By default, a repeated worktree request for the same source/target reuses the
+existing managed worktree. An explicit new-worktree request creates another
+parallel branch/worktree.
+
+`open_workspace` also returns known managed worktree paths and branch metadata
+so a specific existing worktree can be reopened directly.
+
+## Closing a managed worktree
+
+After the task is complete and verified, call `close_worktree` with the managed
+workspace ID and a commit message.
+
+ForgeRelay:
+
+1. verifies the source checkout remains on the expected target branch;
+2. requires the source checkout to be clean;
+3. verifies the managed worktree is on its recorded branch;
+4. commits remaining worktree changes when needed;
+5. rechecks cleanliness and source state;
+6. requires the source HEAD to be an ancestor of the managed worktree commit;
+7. fast-forwards the target branch;
+8. removes the managed worktree;
+9. deletes the already-merged managed branch.
+
+If histories diverge, close is refused and the worktree is preserved. Rebase and
+verify inside the worktree, then retry. The source checkout is not intentionally
+placed into a merge-conflict state.
+
+Legacy `devspace/*` managed branches remain closable when they are already stored
+in workspace metadata; only new managed branches use `forgerelay/*`.
+
+## Project instructions
+
+When a workspace opens, ForgeRelay loads root-level instruction files when they
+exist:
+
+```text
+AGENTS.md
+AGENTS.MD
+CLAUDE.md
+CLAUDE.MD
+```
+
+Nested instruction files are returned as available paths rather than all being
+injected eagerly. Read the relevant nested file before working under that path.
+
+## Agent Skills
+
+ForgeRelay discovers standard Agent Skills from:
+
+- `~/.agents/skills`
+- project `.agents/skills`
+- the active ForgeRelay config directory's `skills` folder
+- `FORGERELAY_AGENT_DIR/skills` (defaults to `~/.codex/skills`)
+- paths from `FORGERELAY_SKILL_PATHS`
+
+When a task matches an advertised skill, read its `SKILL.md` before using other
+files in the skill directory.
+
+`FORGERELAY_SKILLS=0` hides skills.
+
+## Local subagent profiles
+
+With `FORGERELAY_SUBAGENTS=1`, profiles are discovered from the active global
+config directory plus:
+
+```text
+.forgerelay/agents/*.md
+.devspace/agents/*.md   # migration compatibility
+```
+
+The workspace result exposes only compact profile metadata so the host can
+choose a provider/profile without loading full provider launch details.
+
+The current model-facing delegation workflow is:
+
+```bash
+forgerelay agents ls
+forgerelay agents run <profile-or-provider-or-id> "<prompt>"
+forgerelay agents show <id>
+```
+
+A first-class MCP subagent interface is planned so this CLI indirection can be
+removed.
+
+## Tool modes
+
+Default `FORGERELAY_TOOL_MODE=minimal` exposes:
+
+```text
+open_workspace
+read
+write
+edit
+bash
+close_worktree
+```
+
+The exact lifecycle tools available depend on the active server configuration.
+In minimal mode, normal shell inspection commands such as `rg`, `find`, and `ls`
+can be used rather than dedicated MCP search tools.
+
+`FORGERELAY_TOOL_MODE=full` adds dedicated search/directory tools.
+
+Experimental `FORGERELAY_TOOL_MODE=codex` provides a smaller Codex-shaped
+surface including `apply_patch`, `exec_command`, and `write_stdin`.
+
+## Change review UI
+
+By default `FORGERELAY_WIDGETS=full` attaches ChatGPT Apps-compatible UI to the
+normal workspace/file/edit/shell tools.
+
+`FORGERELAY_WIDGETS=changes` exposes aggregate `show_changes` behavior and keeps
+widget usage focused on workspace/change review.
+
+`FORGERELAY_WIDGETS=off` disables widget UI.
+
+## Legacy configuration
+
+`FORGERELAY_*` is the canonical environment-variable prefix. Equivalent
+`DEVSPACE_*` variables remain accepted as fallbacks during migration.
+
+Likewise, an existing `~/.devspace` configuration/state setup is reused when the
+new ForgeRelay location does not yet exist. See
+[Configuration Reference](configuration.md) for the compatibility rules.

package/docs/configuration.md

@@ -0,0 +1,197 @@
+# Configuration Reference
+
+ForgeRelay can be configured through `forgerelay init`, persisted config files,
+or environment variables.
+
+## Config directory
+
+New installations use:
+
+```text
+~/.forgerelay/config.json
+~/.forgerelay/auth.json
+```
+
+Override the directory with:
+
+```bash
+FORGERELAY_CONFIG_DIR=/path/to/config npx @akira-tl/forgerelay serve
+```
+
+For migration compatibility, `DEVSPACE_CONFIG_DIR` is accepted when
+`FORGERELAY_CONFIG_DIR` is unset. Without either variable, ForgeRelay uses
+`~/.forgerelay` unless that directory is absent and an existing `~/.devspace`
+directory is present; in that case the legacy directory is reused.
+
+## Commands
+
+```bash
+npx @akira-tl/forgerelay init
+npx @akira-tl/forgerelay serve
+npx @akira-tl/forgerelay doctor
+npx @akira-tl/forgerelay config get
+npx @akira-tl/forgerelay config set publicBaseUrl https://forge.example.com
+```
+
+## Environment variable compatibility
+
+The public prefix is `FORGERELAY_*`.
+
+During the rename transition, the equivalent `DEVSPACE_*` variable remains a
+fallback when the ForgeRelay variable is unset. For example:
+
+```text
+FORGERELAY_ALLOWED_ROOTS
+        ↓ if unset
+DEVSPACE_ALLOWED_ROOTS
+```
+
+When both are present, `FORGERELAY_*` wins.
+
+## Core variables
+
+| Variable | Purpose |
+| --- | --- |
+| `HOST` | Local bind host. Defaults to `127.0.0.1`. |
+| `PORT` | Local port. Defaults to `7676`. |
+| `FORGERELAY_ALLOWED_ROOTS` | Comma-separated roots that workspaces may open. |
+| `FORGERELAY_PUBLIC_BASE_URL` | Public origin, without `/mcp`. |
+| `FORGERELAY_ALLOWED_HOSTS` | Optional Host-header allowlist override. |
+| `FORGERELAY_OAUTH_OWNER_TOKEN` | Owner password. Must be at least 16 characters. |
+| `FORGERELAY_STATE_DIR` | SQLite state directory. New default: `~/.local/share/forgerelay`. |
+| `FORGERELAY_WORKTREE_ROOT` | Managed worktree directory. New default: `~/.forgerelay/worktrees`. |
+| `FORGERELAY_WORKFLOW_INSTRUCTIONS` | Replace the built-in workflow policy while retaining the capability contract. |
+| `FORGERELAY_APPEND_INSTRUCTIONS` | Append project/operator workflow policy. |
+
+If an existing legacy state/worktree directory is present and the new default is
+not, ForgeRelay reuses the legacy location rather than orphaning stored state.
+Persisted `stateDir` and `worktreeRoot` values in `config.json` also continue to
+win over defaults.
+
+## Native artifact download
+
+Native-file download is disabled by default. Enable it with:
+
+```bash
+FORGERELAY_ARTIFACTS=1 npx @akira-tl/forgerelay serve
+```
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `FORGERELAY_ARTIFACTS` | `0` | Expose `download_artifact` for trusted native files. |
+| `FORGERELAY_ARTIFACT_MAX_FILE_BYTES` | `104857600` | Maximum streamed size of one file (100 MiB). |
+
+The same settings may be persisted as `artifactsEnabled` and
+`artifactMaxFileBytes` in `config.json`.
+
+The tool currently supports the secure native-file publication path on Linux.
+See [Native File Download](artifact-exchange.md).
+
+## OAuth
+
+ForgeRelay uses a single-user Owner-password OAuth approval flow.
+
+| Variable | Default |
+| --- | --- |
+| `FORGERELAY_OAUTH_ACCESS_TOKEN_TTL_SECONDS` | `3600` |
+| `FORGERELAY_OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `2592000` |
+| `FORGERELAY_OAUTH_SCOPES` | legacy-compatible internal scope `devspace` |
+| `FORGERELAY_OAUTH_ALLOWED_REDIRECT_HOSTS` | `chatgpt.com,localhost,127.0.0.1` |
+
+The default OAuth scope intentionally remains the legacy internal value during
+the rename so existing registrations/state do not need a destructive migration.
+This is a protocol compatibility identifier, not product branding.
+
+MCP clients discover metadata from:
+
+```text
+/.well-known/oauth-protected-resource/mcp
+/.well-known/oauth-authorization-server
+```
+
+## Tool modes
+
+`FORGERELAY_TOOL_MODE` controls the exposed MCP tool surface.
+
+| Value | Behavior |
+| --- | --- |
+| `minimal` | Default. Exposes `open_workspace`, `read`, `write`, `edit`, and `bash`. |
+| `full` | Adds dedicated `grep`, `glob`, and `ls` tools. |
+| `codex` | Experimental Codex-shaped tool surface using `open_workspace`, `read`, `apply_patch`, `exec_command`, and `write_stdin`. |
+
+`FORGERELAY_MINIMAL_TOOLS` remains a compatibility-style boolean alias when the
+explicit tool mode is unset. The corresponding legacy `DEVSPACE_*` names are
+also accepted.
+
+Codex-mode commands run without a PTY by default. `tty: true` enables interactive
+programs when the optional `node-pty` dependency is available.
+
+## Widgets
+
+`FORGERELAY_WIDGETS` controls ChatGPT Apps-compatible UI attachments.
+
+| Value | Behavior |
+| --- | --- |
+| `full` | Default. Attach UI to exposed workspace/file/edit/shell tools. |
+| `changes` | Attach UI to `open_workspace` and aggregate `show_changes`. |
+| `off` | Disable widget UI. |
+
+## Skills and subagents
+
+| Variable | Purpose |
+| --- | --- |
+| `FORGERELAY_SKILLS` | Set to `0` to hide skills. Enabled by default. |
+| `FORGERELAY_SUBAGENTS` | Set to `1` to expose configured subagent profiles. |
+| `FORGERELAY_AGENT_DIR` | Defaults to `~/.codex`; its `skills` child is loaded for compatibility. |
+| `FORGERELAY_SKILL_PATHS` | Optional comma-separated additional skill directories. |
+
+Standard Agent Skills are discovered from:
+
+- `~/.agents/skills`
+- project `.agents/skills`
+- the active ForgeRelay config directory's `skills` folder
+- `FORGERELAY_AGENT_DIR/skills`
+- paths from `FORGERELAY_SKILL_PATHS`
+
+When subagents are enabled, profiles are discovered from:
+
+- `~/.forgerelay/agents/*.md` for new installations;
+- project `.forgerelay/agents/*.md`;
+- active legacy config directory `~/.devspace/agents/*.md` when reused;
+- project `.devspace/agents/*.md` for migration compatibility.
+
+The bundled `subagent-delegation` skill teaches the current CLI workflow:
+
+```bash
+forgerelay agents ls
+forgerelay agents run <profile-or-provider-or-id> "<prompt>"
+forgerelay agents show <id>
+```
+
+## Logging
+
+| Variable | Default |
+| --- | --- |
+| `FORGERELAY_LOG_LEVEL` | `info` |
+| `FORGERELAY_LOG_FORMAT` | `json` |
+| `FORGERELAY_LOG_REQUESTS` | `1` |
+| `FORGERELAY_LOG_ASSETS` | `0` |
+| `FORGERELAY_LOG_TOOL_CALLS` | `1` |
+| `FORGERELAY_LOG_SHELL_COMMANDS` | `0` |
+| `FORGERELAY_TRUST_PROXY` | `0` |
+
+Set `FORGERELAY_LOG_FORMAT=pretty` for local debugging. Enable shell command
+previews only when intentionally needed; they can reveal sensitive arguments.
+
+## Environment-only example
+
+```bash
+FORGERELAY_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)" \
+FORGERELAY_ALLOWED_ROOTS="$HOME/personal,$HOME/work" \
+FORGERELAY_PUBLIC_BASE_URL="https://forge.example.com" \
+FORGERELAY_WORKTREE_ROOT="$HOME/.forgerelay/worktrees" \
+FORGERELAY_ARTIFACTS="1" \
+FORGERELAY_TOOL_MODE="minimal" \
+FORGERELAY_WIDGETS="full" \
+npx @akira-tl/forgerelay serve
+```

package/docs/gotchas.md

@@ -0,0 +1,243 @@
+# Troubleshooting Gotchas
+
+## `forgerelay` command not found
+
+Use `npx`:
+
+```bash
+npx @akira-tl/forgerelay init
+npx @akira-tl/forgerelay serve
+```
+
+If installed globally, confirm npm's global bin directory is on `PATH`.
+
+## Unsupported Node version
+
+ForgeRelay requires Node `>=22.19 <27`.
+
+```bash
+node --version
+```
+
+## `better-sqlite3` could not load
+
+Native dependencies may have been installed under a different Node runtime.
+
+```bash
+npm rebuild better-sqlite3
+npx @akira-tl/forgerelay doctor
+```
+
+## Existing DevSpace config is still being used
+
+This is intentional migration behavior. If `~/.forgerelay` does not exist but
+`~/.devspace` does, ForgeRelay reuses the legacy config directory so existing
+OAuth/state configuration is not silently abandoned.
+
+Check the resolved directory:
+
+```bash
+forgerelay doctor
+```
+
+To force a new location, set:
+
+```bash
+FORGERELAY_CONFIG_DIR="$HOME/.forgerelay" forgerelay init
+```
+
+Do not delete the old directory until you have confirmed which persisted state,
+worktrees, skills, and profiles you still need.
+
+## Public URL includes `/mcp`
+
+Store the public **origin**:
+
+```text
+https://your-tunnel-host.example.com
+```
+
+The MCP client uses:
+
+```text
+https://your-tunnel-host.example.com/mcp
+```
+
+Fix a persisted URL with:
+
+```bash
+forgerelay config set publicBaseUrl https://your-tunnel-host.example.com
+```
+
+## Tunnel URL changed
+
+For one run:
+
+```bash
+FORGERELAY_PUBLIC_BASE_URL="https://new-tunnel.example.com" forgerelay serve
+```
+
+For a stable URL:
+
+```bash
+forgerelay config set publicBaseUrl https://forge.example.com
+```
+
+## Host-header or 403 problems
+
+Run:
+
+```bash
+forgerelay doctor
+```
+
+Confirm the public hostname appears in the resolved allowed hosts.
+
+For intentional local debugging only:
+
+```bash
+FORGERELAY_ALLOWED_HOSTS="*" forgerelay serve
+```
+
+## OAuth redirect host rejected
+
+The default allowed redirect hosts are:
+
+```text
+chatgpt.com
+localhost
+127.0.0.1
+```
+
+For another MCP client:
+
+```bash
+FORGERELAY_OAUTH_ALLOWED_REDIRECT_HOSTS="chatgpt.com,example.com" forgerelay serve
+```
+
+## Owner password not accepted
+
+Check the auth file reported by:
+
+```bash
+forgerelay doctor
+```
+
+New installs normally use:
+
+```text
+~/.forgerelay/auth.json
+```
+
+A migrated install may still use `~/.devspace/auth.json`.
+
+Regenerate setup intentionally with:
+
+```bash
+forgerelay init --force
+```
+
+## Unknown `workspaceId`
+
+Reopen the project with `open_workspace` and use the returned ID. Active
+workspace identity is directory-based; reopening the same canonical checkout
+reuses its workspace ID when the stored session remains valid.
+
+Worktree directories have their own workspace identities.
+
+## Worktree mode fails
+
+Managed worktrees require:
+
+- Git;
+- a repository with at least one commit;
+- an attached local source branch;
+- a local `baseRef` when one is explicitly supplied.
+
+New managed branches use:
+
+```text
+forgerelay/*
+```
+
+Legacy persisted `devspace/*` branches remain valid and closable.
+
+Uncommitted source-checkout changes are not automatically copied into a newly
+created worktree.
+
+## `close_worktree` refuses to finish
+
+Close is deliberately refused when:
+
+- the source checkout is dirty;
+- the source checkout is no longer on the recorded target branch;
+- the managed worktree is on the wrong branch;
+- source and managed histories diverged.
+
+Integration is fast-forward-only. If histories diverge, rebase and verify inside
+the managed worktree, then retry. ForgeRelay does not intentionally leave the
+source checkout in a merge-conflict state.
+
+## Windows shell commands fail
+
+ForgeRelay shell execution requires Bash. Native PowerShell and `cmd.exe` command
+execution are not currently supported by the shell runtime.
+
+Use Git Bash, WSL, MSYS2, or Cygwin Bash, then run:
+
+```bash
+forgerelay doctor
+```
+
+## Skills do not appear
+
+Skills are enabled by default. Check:
+
+```bash
+FORGERELAY_SKILLS=1 forgerelay serve
+```
+
+Standard paths include:
+
+- `~/.agents/skills`
+- project `.agents/skills`
+- active ForgeRelay config `skills` directory
+- `FORGERELAY_AGENT_DIR/skills`
+- additional `FORGERELAY_SKILL_PATHS`
+
+## Subagent profiles do not appear
+
+Enable subagents:
+
+```bash
+FORGERELAY_SUBAGENTS=1 forgerelay serve
+```
+
+New profile locations include:
+
+```text
+~/.forgerelay/agents/*.md
+.forgerelay/agents/*.md
+```
+
+Legacy `.devspace/agents` paths remain supported.
+
+`forgerelay agents ls` lists sessions, not profile definitions. The compact
+profile catalog is returned through `open_workspace`.
+
+## Review/change card does not appear
+
+Per-tool widgets default to:
+
+```bash
+FORGERELAY_WIDGETS=full
+```
+
+Use `FORGERELAY_WIDGETS=changes` for aggregate `show_changes`, or `off` to
+disable UI. Plain MCP clients may ignore ChatGPT Apps widget metadata.
+
+## Data retention
+
+ForgeRelay does not yet automatically prune all persisted workspace sessions,
+conversation bindings, or review refs. Retention/GC remains roadmap work; do not
+assume inactive records are deleted automatically.