@akira-tl/forgerelay 0.1.0

package/docs/roadmap.md

@@ -0,0 +1,195 @@
+# ForgeRelay Roadmap
+
+ForgeRelay is the local development control plane between an MCP host and the
+user's real development environment. The project intentionally stays focused on
+workspace, filesystem, process, Git, code-intelligence, hook, and delegated
+local-agent capabilities rather than rebuilding the host model runtime.
+
+## Architecture boundary
+
+The MCP host owns capabilities such as:
+
+- reasoning and conversation;
+- planning and asking the user questions;
+- web and multimodal tools;
+- top-level conversation lifecycle and compaction.
+
+ForgeRelay owns capabilities such as:
+
+- workspace identity and persistence;
+- filesystem operations;
+- local process execution;
+- Git and managed worktrees;
+- review/checkpoint primitives;
+- code intelligence;
+- lifecycle hooks;
+- provider-backed local subagents.
+
+Long-term memory is intentionally outside ForgeRelay. A separate context system
+can be integrated later without coupling memory policy to the local coding
+runtime.
+
+## Explicit non-goals
+
+ForgeRelay does not plan to add:
+
+- an operating-system shell sandbox;
+- a project memory/autonomous memory system;
+- a plugin marketplace/runtime;
+- a second conversation/session runtime;
+- host-owned commands such as plan mode, context inspection, or model selection;
+- automatic installation and management of language servers.
+
+Shell execution remains a trusted local-user capability. Workspace filesystem
+containment must not be described as a shell sandbox.
+
+## 0.1 — ForgeRelay foundation
+
+The initial independent release establishes:
+
+- ForgeRelay product/package/CLI identity;
+- standard SemVer and tag-triggered GitHub/npm releases;
+- preserved upstream MIT attribution and provenance checks;
+- directory-based workspace reuse;
+- checkout-first behavior;
+- branch-backed managed worktrees using `forgerelay/*` branches;
+- safe `close_worktree` fast-forward lifecycle;
+- persisted worktree branch/target metadata;
+- existing local coding-agent profile/provider integration;
+- compatibility with legacy DevSpace configuration/state identifiers.
+
+## 0.2 — Hooks v1
+
+Hooks are the next priority because they provide a general policy extension point
+without hardcoding project-specific commands into Git/workspace logic.
+
+Initial events:
+
+- `WorkspaceOpen`
+- `BeforeTool`
+- `AfterTool`
+- `AfterToolFailure`
+- `AfterFileChange`
+- `BeforeWorktreeClose`
+- `AfterWorktreeClose`
+- `SubagentStart`
+- `SubagentStop`
+
+Initial handler type:
+
+- local command
+
+The first implementation should define a deep hook engine contract and keep MCP
+tool handlers thin. HTTP/prompt/agent-style handlers can be evaluated later if
+there is a concrete need.
+
+`BeforeWorktreeClose` should become the natural place for user-configured test,
+typecheck, formatting, or security verification before a managed branch is
+integrated.
+
+## 0.3 — LSP code intelligence v1
+
+LSP is moderate implementation complexity if ForgeRelay does not become a
+language-server installer.
+
+The first version should launch only language servers already available on the
+user's machine or explicitly configured by the user/project.
+
+Initial operations:
+
+- diagnostics;
+- definition;
+- references;
+- document symbols;
+- workspace symbols;
+- hover/type information.
+
+Prefer one deep MCP capability such as:
+
+```text
+code_intelligence({
+  workspaceId,
+  operation,
+  path,
+  line,
+  column,
+  query
+})
+```
+
+rather than one MCP tool per language or language-server method.
+
+Candidate servers include `typescript-language-server`/tsserver, Pyright,
+`rust-analyzer`, `gopls`, and `clangd`, but ForgeRelay should treat server
+commands/configuration as external dependencies.
+
+## 0.4 — First-class subagent MCP
+
+ForgeRelay already owns provider adapters and resumable local agent sessions.
+The next step is to remove the current `bash -> forgerelay agents ...` indirection
+for MCP hosts.
+
+A compact interface should reuse the existing provider adapter registry:
+
+```text
+subagent({
+  action: "run" | "list" | "show" | "cancel",
+  workspaceId,
+  profile,
+  provider,
+  prompt,
+  agentId
+})
+```
+
+The parent agent chooses an available provider/profile such as Codex or Claude.
+ForgeRelay launches, tracks, resumes, and cancels the provider-backed worker when
+the underlying provider supports those operations.
+
+This is intentionally provider-backed delegation, not an attempt to emulate a
+host-native subagent implementation.
+
+## Worktree and history refinements
+
+These can land alongside the main release lines when the underlying interfaces
+are ready:
+
+- `.worktreeinclude`-style explicit copying of selected gitignored files;
+- hook-backed worktree close verification;
+- stale managed-worktree recovery and cleanup;
+- checkpoint/list/restore primitives based on the existing Git snapshot engine;
+- retention/GC for stale workspace sessions, conversation bindings, and review
+  refs.
+
+Checkpoint restore must protect concurrent/external user edits rather than
+blindly overwriting a working tree.
+
+## Later: task orchestration
+
+After first-class subagents are stable, ForgeRelay may add a small persistent
+task graph for parent/worker coordination:
+
+- task identity/title/status;
+- dependencies;
+- assigned local-agent session;
+- workspace/worktree association;
+- structured result/error state.
+
+Start with DAG-style parent/child orchestration. Peer-to-peer agent-team messaging
+should only be added if real workflows demonstrate that the simpler task model is
+insufficient.
+
+## Compatibility policy
+
+New public names use ForgeRelay:
+
+- `@akira-tl/forgerelay`
+- `forgerelay`
+- `FORGERELAY_*`
+- `~/.forgerelay`
+- `.forgerelay`
+- `forgerelay/*` managed branches
+
+Legacy `DEVSPACE_*`, `~/.devspace`, `.devspace`, old managed branch names, and
+selected persisted internal identifiers remain readable during migration where
+removing compatibility would orphan real user state.

package/docs/security.md

@@ -0,0 +1,142 @@
+# Security Model
+
+ForgeRelay exposes local coding capabilities over MCP. Treat a connected client
+as a trusted coding operator with access to the capabilities you expose.
+
+## Allowed workspace roots
+
+ForgeRelay only opens workspaces under configured roots. Keep the root list as
+narrow as practical.
+
+Example:
+
+```text
+~/personal,~/work
+```
+
+Do not use your entire home directory unless that is intentionally the access
+boundary you want.
+
+Filesystem-oriented tools validate workspace-relative paths and reject paths
+that escape the opened workspace or configured roots.
+
+## Owner-password OAuth
+
+New installations store local configuration in:
+
+```text
+~/.forgerelay/config.json
+~/.forgerelay/auth.json
+```
+
+`auth.json` contains the Owner password and should remain private. When a client
+connects, ForgeRelay presents an approval page where that password authorizes
+the connection.
+
+For environment-only deployments:
+
+```bash
+FORGERELAY_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)"
+```
+
+The token must be at least 16 characters.
+
+Existing `~/.devspace` configuration and `DEVSPACE_*` variables remain readable
+for migration compatibility when the new ForgeRelay equivalents are absent.
+
+## Public URL and tunnels
+
+ForgeRelay needs `FORGERELAY_PUBLIC_BASE_URL` when an MCP client reaches it
+through a public HTTPS origin.
+
+Use the origin without `/mcp`:
+
+```text
+https://forge.example.com
+```
+
+The client connects to:
+
+```text
+https://forge.example.com/mcp
+```
+
+ForgeRelay does not manage the tunnel. Your tunnel or reverse proxy should point
+to the local server, normally:
+
+```text
+http://127.0.0.1:7676
+```
+
+By default, ForgeRelay derives allowed Host headers from the local host and
+configured public URL. `FORGERELAY_ALLOWED_HOSTS=*` disables that allowlist and
+should only be used intentionally.
+
+## Shell execution is not sandboxed
+
+This boundary is important:
+
+**Filesystem path containment is not a shell sandbox.**
+
+ForgeRelay's file tools are scoped to the opened workspace, but shell commands
+run with the authority of the local operating-system user that started
+ForgeRelay. A shell command can therefore access resources that the local user
+can access, including paths outside the workspace.
+
+ForgeRelay intentionally does not add its own OS sandbox. Many development
+workflows need compilers, package managers, system tools, credentials, external
+repositories, local services, and other resources outside a narrow workspace
+sandbox, and MCP currently does not provide a clean universal interaction model
+for dynamically crossing such a boundary.
+
+The security model is therefore based on:
+
+- strong authentication;
+- narrow allowed project roots for filesystem tools;
+- a trusted MCP client/model relationship;
+- explicit tool calls and observable local execution;
+- the user's existing OS/account permissions.
+
+Do not describe ForgeRelay as a sandboxed coding environment.
+
+## Git and managed worktrees
+
+Managed worktrees are branch-backed and visible in the source repository.
+ForgeRelay refuses unsafe close operations when:
+
+- the source checkout is dirty;
+- the source checkout left the recorded target branch;
+- source and worktree histories diverged;
+- the managed worktree is on the wrong branch.
+
+Integration is fast-forward-only, so a failed close does not intentionally put
+the source checkout into a merge-conflict state.
+
+## Native artifact download
+
+When enabled, `download_artifact` accepts only the supported native file value
+provided by the MCP host. It does not accept arbitrary signed URLs, local paths,
+embedded credentials, or base64 strings as substitutes.
+
+Downloads are streamed, size-limited, created without overwrite, and published
+as owner-only files. See [Native File Download](artifact-exchange.md).
+
+## Logging
+
+ForgeRelay logs requests/tool calls by default. Shell command previews are off
+unless explicitly enabled:
+
+```bash
+FORGERELAY_LOG_SHELL_COMMANDS=1
+```
+
+Command arguments can contain secrets, so only enable command-preview logging
+when necessary.
+
+## Package provenance
+
+ForgeRelay is derived from the MIT-licensed DevSpace project. Public releases
+preserve the upstream copyright/license and include `NOTICE.md`. The release
+check fails if required attribution is removed.
+
+See [NOTICE.md](../NOTICE.md) and [LICENSE](../LICENSE).

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 ForgeRelay.
+
+## Requirements
+
+- Node `>=22.19 <27`
+- npm
+- Git
+- Bash, including Git Bash or WSL on Windows
+- a public HTTPS URL when the MCP host cannot connect directly to localhost
+
+ForgeRelay 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 @akira-tl/forgerelay init
+```
+
+The setup flow asks for the allowed project roots, local port, and public base
+URL.
+
+### Project roots
+
+Choose only the folders the connected MCP host should be able to open.
+
+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`.
+
+```text
+http://127.0.0.1:7676/mcp
+```
+
+### Public base URL
+
+Point your tunnel or reverse proxy 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:
+
+```text
+https://your-tunnel-host.example.com/mcp
+```
+
+## Start the server
+
+```bash
+npx @akira-tl/forgerelay serve
+```
+
+For a one-run public URL override:
+
+```bash
+FORGERELAY_PUBLIC_BASE_URL="https://new-tunnel.example.com" \
+npx @akira-tl/forgerelay serve
+```
+
+For a stable public URL:
+
+```bash
+npx @akira-tl/forgerelay config set publicBaseUrl https://forge.example.com
+npx @akira-tl/forgerelay serve
+```
+
+## Approve the client
+
+When ChatGPT, Claude, or another MCP client connects, ForgeRelay displays an
+Owner-password approval page. Enter the Owner password printed during setup.
+
+New installations use:
+
+```text
+~/.forgerelay/config.json
+~/.forgerelay/auth.json
+```
+
+Keep `auth.json` private.
+
+### Existing DevSpace configuration
+
+During migration, if `~/.forgerelay` does not exist but `~/.devspace` does,
+ForgeRelay reuses the legacy directory automatically. `FORGERELAY_CONFIG_DIR`
+takes precedence over the legacy `DEVSPACE_CONFIG_DIR` environment variable.
+
+You do not need to move a working legacy config before starting ForgeRelay.
+
+## Check the setup
+
+```bash
+npx @akira-tl/forgerelay doctor
+```
+
+The doctor command reports the resolved config, Node runtime, platform, Git,
+Bash, public URL, allowed hosts, and native SQLite dependency status.
+
+## Running from a local checkout
+
+For ForgeRelay development itself:
+
+```bash
+npm install --include=dev
+npm run dev
+```

package/docs/versioning.md

@@ -0,0 +1,189 @@
+# Versioning and Release Management
+
+ForgeRelay is published as `@akira-tl/forgerelay` from the
+`Akira-TL/forgerelay` GitHub repository.
+
+## Version format
+
+ForgeRelay uses standard Semantic Versioning:
+
+```text
+MAJOR.MINOR.PATCH
+```
+
+The initial independent release is:
+
+```text
+0.1.0
+```
+
+The old temporary fork version format (`X.Y.Z-akira.N`) is no longer used.
+Upstream DevSpace provenance and baseline information belong in Git history,
+`NOTICE.md`, and release notes rather than ForgeRelay's public version number.
+
+While the project is below `1.0.0`:
+
+- patch releases are backward-compatible fixes and small refinements;
+- minor releases may add substantial runtime capabilities and may include
+  explicitly documented pre-1.0 interface changes;
+- `1.0.0` marks the first stable public runtime/tool contract.
+
+## Changelog policy
+
+All user-visible changes first land under:
+
+```text
+## [Unreleased]
+```
+
+Use the usual categories when relevant:
+
+- Added
+- Changed
+- Fixed
+- Security
+- Removed
+- Compatibility
+
+The release helper promotes `Unreleased` into a dated release section. It
+refuses to bump a version when `Unreleased` is empty.
+
+## Release commands
+
+Check package, lockfile, repository, changelog, and attribution metadata:
+
+```bash
+npm run release:check
+```
+
+Prepare the next patch release:
+
+```bash
+npm run release:patch
+```
+
+`npm run release:next` is an alias for a patch release.
+
+Prepare a minor or major release:
+
+```bash
+npm run release:minor
+npm run release:major
+```
+
+The bump commands update:
+
+- `package.json`
+- root package metadata in `package-lock.json`
+- `CHANGELOG.md`
+
+They do not commit, tag, push, or publish.
+
+Run the full local release gate with:
+
+```bash
+npm run release:verify
+```
+
+Validate a specific tag with:
+
+```bash
+npm run release:tag-check -- v0.1.0
+```
+
+A release tag must exactly equal `v` followed by the package version, and
+`Unreleased` must be empty.
+
+## Tag-triggered publishing
+
+`.github/workflows/release.yml` runs for tags matching `v*.*.*` in the
+`Akira-TL/forgerelay` repository. The release helper performs the strict SemVer
+validation; tags that only match the broad GitHub glob but not the package
+version are rejected.
+
+For a valid tag, the workflow:
+
+1. checks out the tagged commit with full Git history;
+2. verifies the tagged commit is contained in `origin/main`;
+3. installs dependencies;
+4. checks the tag against `package.json` and `CHANGELOG.md`;
+5. runs `npm run release:verify`;
+6. runs `npm pack --dry-run`;
+7. checks whether the exact npm version is already published;
+8. publishes `@akira-tl/forgerelay` when necessary;
+9. creates the matching GitHub Release after npm publication succeeds.
+
+The npm existence check makes the workflow safely restartable when npm
+publication succeeds but GitHub Release creation fails afterward.
+
+## First public npm release
+
+Before the first public release, rename the GitHub repository to:
+
+```text
+Akira-TL/forgerelay
+```
+
+and update the local `origin` remote if Git does not update it automatically.
+The package metadata and release workflow intentionally target the final
+ForgeRelay repository name.
+
+If `@akira-tl/forgerelay` does not yet exist on npm, GitHub Actions can bootstrap
+it with a temporary npm publishing token:
+
+1. create an npm token that can publish packages in the `@akira-tl` scope;
+2. add it to `Akira-TL/forgerelay` as the Actions secret `NPM_TOKEN`;
+3. push the first verified ForgeRelay release tag;
+4. let the tag workflow publish the package;
+5. configure npm Trusted Publishing for the package using:
+   - owner: `Akira-TL`
+   - repository: `forgerelay`
+   - workflow filename: `release.yml`
+6. delete the `NPM_TOKEN` GitHub secret.
+
+After Trusted Publishing is configured, normal releases use GitHub Actions OIDC
+through the workflow's `id-token: write` permission and do not need a long-lived
+npm publishing token.
+
+## Normal release procedure
+
+1. Put all intended user-visible changes under `Unreleased`.
+2. Run `npm run release:check`.
+3. Run the appropriate `release:patch`, `release:minor`, or `release:major`
+   command.
+4. Review the generated version and changelog diff.
+5. Run `npm run release:verify`.
+6. Commit the release-ready code and metadata and push `main`.
+7. Create the exact version tag, for example:
+
+   ```bash
+   git tag v0.2.0
+   git push origin v0.2.0
+   ```
+
+The tag push is the publication action.
+
+## Attribution guardrails
+
+`release:check` intentionally verifies that public packages keep the required
+upstream provenance:
+
+- `LICENSE` must preserve `Copyright (c) 2026 Waishnav`;
+- `LICENSE` records Akira-TL's modifications without replacing the upstream
+  notice;
+- `NOTICE.md` must identify `https://github.com/Waishnav/devspace`;
+- `NOTICE.md` must state that ForgeRelay is independently maintained by Akira-TL;
+- the npm package must include `NOTICE.md`.
+
+Do not weaken these checks as part of ordinary branding or release work.
+
+## Compatibility identifiers
+
+The ForgeRelay rename does not require destructive migration of internal state.
+Some persisted identifiers deliberately keep historical DevSpace names when
+changing them would orphan existing data, including older SQLite schema/file
+identifiers and review Git refs. These are storage compatibility details, not
+public product branding.
+
+New user-facing configuration, managed branches, CLI output, package metadata,
+and release names use ForgeRelay.

package/examples/agents/claude-implementer.md

@@ -0,0 +1,30 @@
+---
+schema: forgerelay-agent/v1
+name: claude-implementer
+description: Implementation profile for multi-file changes, careful refactors, and failing test repair.
+provider: claude
+model: sonnet
+thinking: high
+---
+
+Take ownership of the requested implementation while keeping the change narrow.
+Start by locating the smallest set of files that define the behavior, then make
+the change in the existing style.
+
+Working rules:
+
+- Preserve existing public behavior unless the prompt explicitly asks to change it.
+- Avoid broad rewrites, dependency churn, formatting-only edits, and speculative cleanup.
+- Update or add focused tests when behavior changes.
+- Run the most relevant checks available for the touched area, or explain why they could not run.
+- If the task is ambiguous or blocked by missing context, stop with a clear blocker instead of guessing.
+
+Report:
+
+```text
+summary:
+tests_run:
+blockers:
+risks:
+follow_up_needed:
+```

package/examples/agents/codex-explorer.md

@@ -0,0 +1,27 @@
+---
+schema: forgerelay-agent/v1
+name: codex-explorer
+description: Read-only profile for bounded codebase questions, architecture tracing, and risk discovery.
+provider: codex
+model: gpt-5.4-mini
+thinking: high
+---
+
+Investigate without editing. Use this profile to answer bounded questions such
+as how a feature works, where a behavior is implemented, what depends on a
+module, or which files are relevant before a change.
+
+- Do not modify files.
+- Prefer direct evidence from code over broad repository summaries.
+- Cite file paths, symbols, and commands that support the conclusion.
+- Separate confirmed facts from inferences.
+- Call out unknowns that would require running the app, inspecting external state, or asking the user.
+
+Report:
+
+```text
+answer:
+evidence:
+relevant_files:
+unknowns:
+```