@akira-tl/forgerelay 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable ForgeRelay changes are documented here.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-09
+
+### Added
+
+- Initial ForgeRelay release, independently maintained by Akira-TL and based on the MIT-licensed DevSpace project by Waishnav.
+- Reusable workspace identity based on the actual checkout or worktree directory rather than request or conversation identity.
+- Branch-backed managed worktrees with explicit source, target-branch, and branch metadata.
+- `close_worktree` lifecycle that commits remaining worktree changes, requires safe fast-forward integration, and cleans up the managed worktree and branch.
+- Persistent worktree branch and target-branch metadata in the workspace store.
+- Local coding-agent profiles and provider adapters for Codex, Claude, OpenCode, Pi, Cursor, and Copilot integrations already supported by the runtime.
+- Tag-triggered GitHub Actions publishing for npm and GitHub Releases.
+- Release metadata validation, package inspection, attribution checks, and standard SemVer release helpers.
+- `NOTICE.md` and release-time attribution checks preserving the upstream MIT copyright and provenance.
+
+### Changed
+
+- Product identity is now ForgeRelay, published as `@akira-tl/forgerelay` with the `forgerelay` CLI.
+- Versioning now follows independent stable SemVer beginning at `0.1.0` instead of the temporary `X.Y.Z-akira.N` fork version format.
+- New managed worktrees use dedicated `forgerelay/*` branches instead of detached HEADs or the earlier `devspace/*` prefix.
+- Worktree creation is reserved for explicitly requested isolated or parallel work; ordinary work continues in the user's checkout.
+- New configuration prefers `FORGERELAY_*` variables and `~/.forgerelay` while retaining legacy DevSpace configuration compatibility.
+- New default state and worktree directories use ForgeRelay naming when no legacy state needs to be reused.
+- MCP lifecycle instructions direct agents to reuse directory workspaces and close completed managed worktrees safely.
+- Project file modifications are directed through dedicated edit/write capabilities rather than shell-based file mutation.
+
+### Compatibility
+
+- Existing `DEVSPACE_*` environment variables remain accepted as fallbacks while `FORGERELAY_*` takes precedence.
+- Existing `~/.devspace` configuration is reused automatically when `~/.forgerelay` does not yet exist.
+- Existing DevSpace state directories and managed worktree metadata remain readable so upgrades do not orphan active work.
+- Legacy internal persistence identifiers such as the existing SQLite schema names and review Git refs are intentionally retained where renaming would break stored state.
+- Existing `@akira-tl/devspace` and upstream `@waishnav/devspace` install paths remain recognized by Pi PATH cleanup logic.
+
+### Fixed
+
+- Reopening the same directory no longer creates a different workspace solely because the request came from another conversation.
+- Worktree reuse resolves the actual target branch instead of treating the string `HEAD` as a stable reuse identity.
+- Managed worktree close refuses dirty, wrong-branch, or diverged source checkouts instead of putting the source checkout into a merge-conflict state.
+- Pi subagent PATH handling correctly removes ForgeRelay's own `node_modules/.bin` entry after the package rename.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Waishnav
+Copyright (c) 2026 Akira-TL, modifications
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,19 @@
+# ForgeRelay Notice
+
+ForgeRelay is independently maintained by Akira-TL and contains substantial modifications to the upstream DevSpace project.
+
+## Upstream origin
+
+The original DevSpace project was created by Waishnav and is available at:
+
+- https://github.com/Waishnav/devspace
+
+The upstream project is distributed under the MIT License. Its original copyright notice and the MIT permission notice are preserved in `LICENSE` and must remain included in copies or substantial portions of this software.
+
+## ForgeRelay modifications
+
+ForgeRelay is a separately named and independently released derivative project. Changes maintained by Akira-TL include, among other work, workspace identity and persistence, branch-backed managed worktrees and close lifecycle, MCP workflow behavior, local coding-agent integration, release infrastructure, and ForgeRelay-specific configuration/runtime behavior.
+
+ForgeRelay releases are not official releases of the upstream DevSpace project, and the ForgeRelay name and distribution should not be interpreted as endorsement by or affiliation with the upstream author.
+
+Git history is intentionally retained so the provenance of upstream and later modifications remains inspectable.

package/README.md

@@ -0,0 +1,270 @@
+# ForgeRelay
+
+**Give MCP coding agents a real local workspace.**
+
+[![npm](https://img.shields.io/npm/v/%40akira-tl%2Fforgerelay?style=flat-square)](https://www.npmjs.com/package/@akira-tl/forgerelay)
+[![CI](https://img.shields.io/github/actions/workflow/status/Akira-TL/forgerelay/ci.yml?style=flat-square&branch=main)](https://github.com/Akira-TL/forgerelay/actions/workflows/ci.yml)
+[![License](https://img.shields.io/npm/l/%40akira-tl%2Fforgerelay?style=flat-square)](LICENSE)
+
+ForgeRelay is a self-hosted MCP server that lets ChatGPT and other MCP-capable
+hosts work on the repositories already on your machine. The host gets explicit
+tools for files, shell commands, Git, managed worktrees, change review, and
+optional local-agent delegation. Your project stays in your normal development
+environment, with the same compilers, package managers, credentials, and Git
+installation you already use.
+
+It is not a model and it is not another coding-agent UI. ForgeRelay sits between
+the host and your local development tools and handles the parts that need to run
+on your machine.
+
+> [!NOTE]
+> ForgeRelay is an independently maintained derivative of the MIT-licensed
+> [Waishnav/devspace](https://github.com/Waishnav/devspace) project. It is not an
+> official DevSpace release. The original copyright notice and license are kept
+> in [LICENSE](LICENSE), with additional provenance in [NOTICE.md](NOTICE.md).
+
+## Quick start
+
+ForgeRelay requires Node `>=22.19 <27`, npm, Git, and a Bash-compatible shell.
+
+Install it globally:
+
+```bash
+npm install -g @akira-tl/forgerelay
+```
+
+Then configure and start it:
+
+```bash
+forgerelay init
+forgerelay serve
+```
+
+Or run it directly with `npx`:
+
+```bash
+npx @akira-tl/forgerelay init
+npx @akira-tl/forgerelay serve
+```
+
+The default local MCP endpoint is:
+
+```text
+http://127.0.0.1:7676/mcp
+```
+
+If the MCP host cannot reach localhost, put ForgeRelay behind a public HTTPS
+tunnel or reverse proxy such as Cloudflare Tunnel, ngrok, Pinggy, Tailscale
+Funnel, or your own proxy. During setup, enter the public origin without `/mcp`:
+
+```text
+https://your-tunnel-host.example.com
+```
+
+The client then connects to:
+
+```text
+https://your-tunnel-host.example.com/mcp
+```
+
+ForgeRelay uses an Owner-password OAuth approval flow. `forgerelay init` prints
+the password and stores it in the active config directory. New installations use:
+
+```text
+~/.forgerelay/config.json
+~/.forgerelay/auth.json
+```
+
+Keep `auth.json` private.
+
+## What it gives an MCP host
+
+Once a workspace is open, the host can:
+
+- read, create, edit, and search files inside that workspace;
+- run your local tests, builds, package scripts, Git commands, and shell tools;
+- reuse the same workspace when the same checkout is opened again;
+- follow repository instructions from `AGENTS.md` and `CLAUDE.md`;
+- discover Agent Skills and configured local subagent profiles;
+- create a branch-backed Git worktree when you explicitly ask for isolated or
+  parallel work;
+- close a managed worktree by committing its remaining changes and
+  fast-forwarding the target branch when that can be done safely;
+- show aggregate changes through optional ChatGPT Apps-compatible UI cards.
+
+Normal work happens in your existing checkout. ForgeRelay does not silently move
+every task into a worktree.
+
+## Worktrees without the usual cleanup mess
+
+A new managed worktree gets its own `forgerelay/*` branch instead of a detached
+HEAD. It remains visible from the source repository with ordinary Git commands:
+
+```bash
+git worktree list
+git branch
+```
+
+When `close_worktree` succeeds, ForgeRelay:
+
+1. checks that the source checkout is clean and still on the expected target branch;
+2. commits any remaining worktree changes;
+3. checks that the target can advance without a merge commit or conflict;
+4. fast-forwards the target branch;
+5. removes the worktree and the already-merged managed branch.
+
+If the histories have diverged, the close is refused and the worktree is left in
+place. ForgeRelay does not put the source checkout into a merge-conflict state.
+You can rebase and verify inside the worktree, then retry the close.
+
+## Local coding agents
+
+ForgeRelay can delegate work to local coding runtimes through user-defined
+profiles. The current adapter layer supports Codex, Claude, OpenCode, Pi,
+Cursor, and Copilot where the corresponding local integration is available.
+
+Profiles can live in:
+
+```text
+~/.forgerelay/agents/*.md
+.forgerelay/agents/*.md
+```
+
+The current CLI 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 a parent agent can use the
+same runtime without going through the CLI.
+
+See [Agent Profile Schema](docs/agent-profile-schema.md) for the profile format.
+
+## Configuration and upgrades from DevSpace
+
+New configuration uses the `FORGERELAY_*` prefix. For example:
+
+```bash
+FORGERELAY_ALLOWED_ROOTS="$HOME/projects" \
+FORGERELAY_PUBLIC_BASE_URL="https://forge.example.com" \
+forgerelay serve
+```
+
+Existing `DEVSPACE_*` variables are still accepted as fallbacks during the
+rename transition. When both names are present, `FORGERELAY_*` wins.
+
+The same rule applies to persisted configuration. ForgeRelay prefers
+`~/.forgerelay`, but if that directory does not exist and an existing
+`~/.devspace` setup does, ForgeRelay keeps using the legacy directory rather
+than orphaning OAuth credentials, workspace state, or managed worktrees.
+
+Project-level `.devspace/agents` profiles are also still readable for migration
+compatibility. New project configuration should use `.forgerelay`.
+
+See [Configuration Reference](docs/configuration.md) for all supported options.
+
+## Security model
+
+A connected MCP host can make real changes to local projects through ForgeRelay,
+using the same local account that runs the server. That trust boundary matters.
+
+Filesystem tools enforce configured workspace and allowed-root boundaries. Shell
+commands are different: they run with the authority of your local user and are
+**not** contained by an operating-system sandbox added by ForgeRelay.
+
+Only connect hosts you trust, keep the Owner password private, and expose only
+the project roots you actually want the host to use.
+
+See [Security Model](docs/security.md) for the full boundary and threat model.
+
+## Platform support
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| Linux | Supported | Requires Node, npm, Git, and Bash. |
+| macOS | Supported | Requires Node, npm, Git, and Bash. |
+| Windows with Git Bash, WSL, MSYS2, or Cygwin Bash | Supported | Git Bash is the simplest native Windows setup. |
+| Windows PowerShell or `cmd.exe` only | Not supported yet | Install Git Bash or use WSL. |
+
+You can check the local runtime with:
+
+```bash
+forgerelay doctor
+```
+
+## Where ForgeRelay is going
+
+The next additions are focused on making the local execution layer more useful,
+not on turning ForgeRelay into another all-in-one agent framework:
+
+1. lifecycle hooks;
+2. LSP-backed code intelligence;
+3. first-class MCP subagent delegation;
+4. stronger worktree verification and recovery;
+5. checkpoint/rewind and retention improvements.
+
+ForgeRelay does not plan to add its own shell sandbox, long-term memory system,
+or plugin marketplace. Conversation, planning, web access, and other host-native
+capabilities stay with the MCP host. Long-term context can be provided by a
+separate service instead of being mixed into the workspace runtime.
+
+See [Roadmap](docs/roadmap.md) for the current plan.
+
+## Releases
+
+ForgeRelay uses standard SemVer, starting at `0.1.0`.
+
+Prepare a release with:
+
+```bash
+npm run release:check
+npm run release:patch
+npm run release:minor
+npm run release:major
+npm run release:verify
+```
+
+Pushing a matching `vX.Y.Z` tag to `Akira-TL/forgerelay` is the publish action.
+GitHub Actions verifies the tagged commit, publishes `@akira-tl/forgerelay` to
+npm, and creates the matching GitHub Release.
+
+See [Versioning and Release Management](docs/versioning.md) for the bootstrap and
+Trusted Publishing setup.
+
+## Documentation
+
+- [Setup Guide](docs/setup.md)
+- [ChatGPT Coding Workflow](docs/chatgpt-coding-workflow.md)
+- [Configuration Reference](docs/configuration.md)
+- [Agent Profile Schema](docs/agent-profile-schema.md)
+- [Native File Download](docs/artifact-exchange.md)
+- [Security Model](docs/security.md)
+- [Troubleshooting](docs/gotchas.md)
+- [Roadmap](docs/roadmap.md)
+- [Versioning and Release Management](docs/versioning.md)
+- [Changelog](CHANGELOG.md)
+- [Attribution Notice](NOTICE.md)
+
+## Upstream and attribution
+
+ForgeRelay is based on the original
+[Waishnav/devspace](https://github.com/Waishnav/devspace) project by Waishnav,
+released under the MIT License. ForgeRelay has its own name, package, release
+stream, runtime changes, and roadmap, but the upstream provenance remains part of
+the project.
+
+The original copyright notice remains in [LICENSE](LICENSE). See
+[NOTICE.md](NOTICE.md) for the attribution and modification notice.
+
+## Local development
+
+```bash
+npm install --include=dev
+npm run dev
+npm run typecheck
+npm test
+npm run build
+```