@moretea-labs/forge 1.5.0-rc.1

package/docs/wiki/Implementation.md

@@ -0,0 +1,172 @@
+# Implementation
+
+This page maps the public Forge model to the current source tree. It is an implementation guide, not a substitute for the versioned architecture contracts.
+
+## 1. MCP ingress and stable surface
+
+Primary code:
+
+```text
+src/cli/mcp/server.ts
+src/cli/mcp/toolset-names.ts
+src/cli/mcp/repository-tools.ts
+src/cli/mcp/transports/http.ts
+src/cli/mcp/transports/session-registry.ts
+src/runtime/gateway/mcp/
+```
+
+`toolset-names.ts` defines the bounded default connector surface. The five facade tools come from `src/runtime/control-plane/facade/types.ts`; repository, patch, check, Process, plugin-dispatch, and result tools bring the current default to 19.
+
+The HTTP transport owns authentication and MCP session lifecycle. `McpSessionRegistry` owns session capacity, active-request protection, stream leases, replacement, and close accounting. A tool-surface fingerprint mismatch returns a recoverable reinitialize response; replacement initialize owns actual supersession and transport cleanup.
+
+## 2. Repository registry and execution identity
+
+Primary code:
+
+```text
+src/cli/repositories/registry.ts
+src/cli/repositories/ephemeral-workspace.ts
+src/runtime/control-plane/execution/execution-identity.ts
+```
+
+Registered work is resolved to `repoId` plus `checkoutId`. Git top-level/common-directory checks prevent a caller from supplying a different checkout through `cwd`. `ephemeral-workspace.ts` represents the separate explicit authority for an existing unregistered local directory.
+
+## 3. Context and source access
+
+Primary code:
+
+```text
+src/cli/controller/context-pack.ts
+src/cli/repository/inspector.ts
+src/runtime/repository/session-cache.ts
+```
+
+`rh_context` is the normal code-location/context router. Repository observations are bounded and cached by session/repository identity where valid. Clean Git snapshots avoid redundant `git diff --stat` subprocesses because `git status` already proves that no unstaged diff can exist.
+
+Structural CodeGraph context is optional augmentation for call/dependency questions; it is not another mandatory top-level search abstraction.
+
+## 4. Direct Edit
+
+Primary code:
+
+```text
+src/cli/editing/edit-session.ts
+src/cli/mcp/repository-tools.ts
+```
+
+A bounded patch can be applied directly to the selected checkout with file fingerprints, revisions, savepoints, change budgets, and focused verification. Direct Edit is the default for understood small work; a Plan or worktree is not a prerequisite.
+
+## 5. Command policy and ephemeral workspaces
+
+Primary code:
+
+```text
+src/cli/repositories/command-classifier.ts
+src/cli/repositories/command-executor.ts
+src/runtime/execution/process-runtime/command-facade.ts
+```
+
+The classifier distinguishes readonly, workspace write, remote write, and destructive behavior. Typed argv preserves argument boundaries without shell reparsing. Explicit unregistered workspaces can execute bounded local operations directly, but destructive commands still follow authorization policy.
+
+The MCP result envelope distinguishes “not authorized/executed” from “process executed and failed.” A blocked `rm` therefore returns authorization-required state rather than a fabricated exit-code failure, and successful ephemeral mutations are not labeled as readonly.
+
+## 6. Unified Process Runtime
+
+Primary code:
+
+```text
+src/runtime/execution/process-runtime/runtime.ts
+src/runtime/execution/process-runtime/store.ts
+src/runtime/execution/process-runtime/interactive-admission.ts
+src/runtime/shared/process-identity.ts
+src/runtime/gateway/mcp/process-tools.ts
+```
+
+`spawnManagedProcess` creates one Process record and one physical child execution. Exact PID/start-time/executable identity protects later lifecycle operations. Known-long processes can return handles immediately; short commands may complete during a bounded interactive window. Process startup captures command/start-time together and reuses the running-state persistence result instead of repeating store writes/reads on the hot path.
+
+## 7. Resource claims, leases, and concurrency
+
+Primary code:
+
+```text
+src/runtime/execution/process-runtime/resource-claims.ts
+src/runtime/resources/claims/
+src/runtime/resources/leases/
+src/runtime/control-plane/repo-actor/
+```
+
+Claims describe the resource, not the conversation. Unrelated repositories and independent worktrees do not need a global lock. The same checkout remains a single-writer resource. Lease fencing prevents stale processes from continuing to mutate state after ownership changes.
+
+## 8. Checks and reusable evidence
+
+Primary code:
+
+```text
+src/runtime/execution/process-runtime/check-facade.ts
+src/runtime/gateway/mcp/persisted-check-process.ts
+src/runtime/evidence/
+src/runtime/projections/
+```
+
+Equivalent checks can single-flight, coalesce subscribers, and reuse successful evidence when their content/environment contract matches. Invalidated revisions run physically again. Evidence and large result artifacts remain addressable without making hot status payloads unbounded.
+
+## 9. Durable Work, scheduler, and isolation
+
+Primary code:
+
+```text
+src/runtime/control-plane/facade/work-contract-store.ts
+src/runtime/control-plane/repo-actor/
+src/runtime/scheduler/
+src/runtime/execution/workers/
+src/runtime/control-plane/facade/goal-workloop.ts
+```
+
+Durable Work stores objectives, scope, checks, lifecycle, and evidence when the task actually needs recovery or a longer lifecycle. The scheduler controls global capacity; repository actors decide repository-local safety. Isolated worktrees and workers are mechanisms selected for concurrency/risk, not default ceremony for every code edit.
+
+## 10. Canonical Runtime root
+
+Primary code:
+
+```text
+src/runtime/root/
+src/runtime/control-plane/persistence/sqlite-store.ts
+src/runtime/root/write-fence.ts
+```
+
+The Runtime Root owns lifecycle and readiness. SQLite stores durable Controller facts, while release/write fencing ensures only the active whole-release authority can write Runtime-owned state.
+
+## 11. Recovery and releases
+
+Primary code and docs:
+
+```text
+src/runtime/root/release-store.ts
+src/runtime/health/
+docs/architecture/current/failure-recovery.md
+docs/architecture/current/verification-and-release-gates.md
+```
+
+The primary Runtime cannot be the only authority deciding its own recovery. Standalone Recovery observes the Runtime independently and may perform bounded whole-release restart/rollback only under its own evidence and lock contract.
+
+## 12. Verification
+
+Important regression suites include:
+
+```text
+tests/unit/fix-mcp-session-lifecycle.test.ts
+tests/cli/mcp-runtime-proxy-routing.test.ts
+tests/cli/repository-mcp-command.test.ts
+tests/runtime/process-runtime.test.ts
+scripts/benchmark-route-session-concurrency.ts
+```
+
+The route/session benchmark covers cold/warm context, Direct Edit claims, Process admission/start, check completion, cross-repository and cross-checkout concurrency, same-checkout contention, check coalescing/reuse/invalidation, and Runtime recovery reads. Correctness and latency are tracked separately: expected same-checkout contention is not a concurrency failure.
+
+## Related pages
+
+- [Architecture](Architecture)
+- [Runtime Architecture](Runtime-Architecture)
+- [Work Lifecycle](Work-Lifecycle)
+- [Security Model](Security-Model)
+- [Releases and Upgrades](Releases-and-Upgrades)

package/docs/wiki/Installation.md

@@ -0,0 +1,50 @@
+# Installation
+
+## Supported paths
+
+### Source installation
+
+This is the verified path while `@moretea-labs/forge` remains unpublished:
+
+```bash
+npm ci --ignore-scripts --no-audit --no-fund
+npm install -g . --omit=optional --no-audit --no-fund
+```
+
+### npm RC channel
+
+After the package is visibly published to npm:
+
+```bash
+npm install -g @moretea-labs/forge@next
+```
+
+Bun installs the same npm artifact:
+
+```bash
+bun add -g @moretea-labs/forge@next
+```
+
+Do not infer npm publication from a GitHub tag or prerelease alone.
+
+## Platforms
+
+- macOS and Linux are primary runtime hosts.
+- WSL2 is the recommended Windows host for the complete controller runtime.
+- Native Windows supports the documented CLI and command-shim surface; check the current matrix before relying on host-specific integrations.
+
+See [Platform Support](https://github.com/moretea-labs/forge/blob/main/docs/operations/platform-support.md).
+
+## Command compatibility
+
+Forge exposes only `forge`, `forge-hook`, and `forge-runtime`. State directories, environment variables, protocol identifiers, and release artifacts use the Forge namespace.
+
+## Verify installation
+
+```bash
+forge --version
+forge doctor
+forge repo list --json
+```
+
+A successful CLI launch is not enough to prove the MCP runtime is healthy; verify the connector separately when using ChatGPT.

package/docs/wiki/Integrations.md

@@ -0,0 +1,29 @@
+# Integrations
+
+Integrations extend Forge without changing the core repository-safety model. Each integration has its own authorization and readiness checks.
+
+## ChatGPT MCP
+
+The primary connector uses a stable HTTPS `/mcp` endpoint. Verify initialize, initialized notification, tools/list, a read-only call, and session close—not merely TCP reachability.
+
+## Coding agents
+
+Codex, Claude, and GitHub Copilot can implement bounded tasks when available. Agent output remains subject to repository scope, diff review, tests, and integration rules.
+
+## GitHub
+
+GitHub operations cover issues, pull requests, checks, repository settings, Wiki synchronization, and releases. Remote writes remain explicit and should reference the exact local revision being published.
+
+## Browser and local system
+
+Browser and local-system plugins are optional controller capabilities. They use separate grants and do not turn repository access into unrestricted machine access.
+
+## Google Workspace and personal workflows
+
+Gmail, Calendar, Contacts, and related assistant routines remain connector-specific. Credentials and personal data are not stored in repository source.
+
+## Apple tooling
+
+Simulator and App Store Connect workflows use dedicated capabilities and authorization. They are distinct from generic shell or repository execution.
+
+See the [documentation hub](https://github.com/moretea-labs/forge/blob/main/docs/README.md) for maintained integration guides.

package/docs/wiki/Operations.md

@@ -0,0 +1,26 @@
+# Operations
+
+Use this page to choose the right operational path. Avoid replaying writes merely because a request timed out; first inspect durable Work, Job, Run, and runtime state.
+
+## Normal checks
+
+1. Confirm the selected repository and checkout.
+2. Check Controller and repository readiness.
+3. Inspect active Work or Jobs before retrying an operation.
+4. Run the smallest focused validation first.
+5. Record exact evidence before finalizing or releasing.
+
+## Runtime incidents
+
+- Primary MCP unavailable but Recovery reachable: use the independent Recovery channel to verify the Forge Runtime service, local endpoint, authenticated MCP flow, and external tunnel separately.
+- External 502/503: distinguish tunnel transport, local Runtime health, and authenticated MCP failures before restarting anything.
+- Release drift: stop activation and compare source commit, immutable whole-release manifest, service definition, release authority, SQLite backup binding, and running Runtime revision.
+- Stuck work: use watchdog and maintenance diagnostics before deleting state or killing processes.
+
+## Detailed runbooks
+
+- [Controller reliability](https://github.com/moretea-labs/forge/blob/main/docs/operations/controller-reliability-runbook.md)
+- [Standalone recovery](https://github.com/moretea-labs/forge/blob/main/docs/operations/standalone-disaster-recovery.md)
+- [502 and performance](https://github.com/moretea-labs/forge/blob/main/docs/operations/controller-performance-and-502.md)
+- [Troubleshooting](Troubleshooting)
+- [Release process](Releases-and-Upgrades)

package/docs/wiki/Quick-Start.md

@@ -0,0 +1,46 @@
+# Quick Start
+
+## 1. Install from source
+
+Until the npm RC is publicly available, use the verified source path:
+
+```bash
+git clone https://github.com/moretea-labs/forge.git
+cd forge
+npm ci --ignore-scripts --no-audit --no-fund
+npm install -g . --omit=optional --no-audit --no-fund
+```
+
+Requirements: Git, Node.js 20.10+, npm, and a writable user directory. Bun is recommended for development and the complete test suite.
+
+## 2. Initialize and diagnose
+
+```bash
+forge --version
+forge init --target both
+forge doctor
+```
+
+## 3. Register a repository
+
+```bash
+forge adopt --repo /path/to/project --dry-run
+forge adopt --repo /path/to/project
+forge repo list --json
+```
+
+Use dry-run first when adopting an existing project. Review the proposed files and runtime configuration before applying.
+
+## 4. Connect ChatGPT
+
+Follow the maintained [connector tutorial](https://github.com/moretea-labs/forge/blob/main/docs/tutorials/02-connect-chatgpt.md). After connection, verify status and repository context before starting write work.
+
+## 5. Complete one bounded task
+
+Start with a small change, inspect the diff, run the focused check, commit, and clean the branch or worktree. The full walkthrough is in [First Repository Task](https://github.com/moretea-labs/forge/blob/main/docs/tutorials/03-first-repository-task.md).
+
+## Next
+
+- [Core Concepts](Core-Concepts)
+- [Work Lifecycle](Work-Lifecycle)
+- [Troubleshooting](Troubleshooting)

package/docs/wiki/Releases-and-Upgrades.md

@@ -0,0 +1,34 @@
+# Releases and Upgrades
+
+## Release channels
+
+- `next`: release candidates
+- `latest`: stable releases only
+
+The package version, Git tag, npm channel, GitHub prerelease state, and release notes must agree. GitHub Releases and npm publication are separate facts.
+
+## Release gate
+
+A release candidate must pass the repository's release-readiness check on the exact revision. The gate covers type checking, package identity, public documentation, platform contracts, MCP compatibility, public export, package creation, and tarball installation.
+
+## Stable runtime evidence
+
+Before publication, build an immutable whole-Runtime release from a clean canonical source tree, activate it through the single Forge Runtime service, verify the complete authenticated MCP path, cold-restart that service, and confirm the active release authority still equals the intended commit. Record the fully verified release as known-good.
+
+## Upgrade principles
+
+- Keep the Forge-only command, state, environment, protocol, and release identity consistent across upgrades.
+- Read release notes before changing runtime or connector configuration.
+- Do not overwrite a healthy active release with a stale rollout operation.
+- Keep a verified rollback path before changing production runtime state.
+
+## Publication sequence
+
+1. Merge reviewed code and docs.
+2. Push the exact main revision.
+3. Wait for required CI and Windows checks on that revision.
+4. Synchronize reviewed Wiki source.
+5. Create the exact `v`-prefixed tag and GitHub prerelease.
+6. Verify npm separately; never claim publication without registry evidence.
+
+See the maintained [release process](https://github.com/moretea-labs/forge/blob/main/docs/operations/releasing.md).

package/docs/wiki/Runtime-Architecture.md

@@ -0,0 +1,50 @@
+# Runtime Architecture
+
+## One Runtime authority
+
+The Canonical Forge Runtime is one local MCP application and one lifecycle owner. Its Runtime Root owns MCP transport, Controller services, persistent control-plane state, Process Runtime coordination, readiness, and the active whole-release identity. There is no second active Daemon/Gateway authority, blue-green runtime slot, or component-by-component rollout authority.
+
+## Request path
+
+Authenticated MCP requests enter the in-process transport and Gateway adapter. The Gateway validates schema and repository targeting, returns bounded results, and chooses the shortest valid path:
+
+- bounded read or eligible ephemeral action -> Direct completion;
+- repository command or check -> Unified Process Runtime;
+- genuinely long-lived/dependency-aware objective -> durable Work/Scheduler path;
+- hard external/destructive boundary -> explicit authorization or refusal.
+
+The HTTP request does not become the owner of long-running execution.
+
+## Stable client surface
+
+The normal ChatGPT connector exposes 19 tools, including five preferred facades. Internal atomic handlers and the exhaustive compatibility profile remain available to Forge itself without widening normal discovery.
+
+Tool schema is fenced by a fingerprint. When a connected client carries a stale fingerprint, Forge returns a bounded schema-change error and requests reinitialization. The stale transport is preserved until the replacement initialize supersedes it; closing the transport before the host sees the reset would turn a recoverable schema change into namespace loss.
+
+## Process Runtime
+
+A managed Process has one stable process record and exact process identity. The Runtime records spawn state, output paths, completion state, resource claims, and lease references. `process_get`, `process_wait`, `process_logs`, and `process_cancel` attach to the same Process and never mean “run the command again.”
+
+Short predictable commands may finish inside a small interactive window. Known-long commands return their handle immediately. Process startup avoids duplicate persistence and identity probes on the hot path where the same evidence can be captured once.
+
+## Repository and checkout fencing
+
+Registered execution binds to immutable repository and checkout identity. Claims model the actual resource being touched: unrelated repositories and worktrees can progress concurrently; the same workspace writer conflicts. Ephemeral unregistered workspaces use a separate bounded authority and never masquerade as a registered repository.
+
+## Check reuse
+
+Check identity includes the relevant repository/check-out scope, content revision, check definition, environment/toolchain fingerprint, timeout contract, and reuse scope. Matching callers become subscribers to the same physical execution or valid result. Dirty content invalidates the reuse contract.
+
+## Runtime service and releases
+
+One OS-managed Forge Runtime service reads the active whole-release authority and starts exactly one Runtime Root. Candidate verification happens before an explicitly authorized activation. Runtime/source coherence is a release fact, not something ordinary repository commands are allowed to rewrite.
+
+## Recovery path
+
+Standalone Recovery is independent from the primary MCP endpoint. It verifies Runtime ownership, release coherence, authenticated MCP behavior, and optional external reachability. Sustained local failure can trigger bounded whole-Runtime restart attempts; if those are exhausted, an independently attested previous whole release and its SQLite backup may be restored under the Recovery lock.
+
+## External tunnel
+
+Cloudflare or Tailscale terminates outside the Runtime and points at the configured loopback endpoint. Tunnel health and local Runtime health are separate evidence classes. A tunnel outage alone cannot authorize Runtime rollback.
+
+Detailed code boundaries are in [Implementation](Implementation); normative contracts live in the [current architecture set](https://github.com/moretea-labs/forge/tree/main/docs/architecture/current).

package/docs/wiki/Security-Model.md

@@ -0,0 +1,31 @@
+# Security Model
+
+## Trust boundaries
+
+Forge distinguishes ChatGPT, the public MCP ingress, the local Controller, repository workspaces, external services, optional plugins, and the independent recovery channel. A successful connection at one boundary does not authorize effects at another.
+
+## Repository scope
+
+Normal work is limited to a registered repository and checkout. Outside-repository filesystem access requires a separate capability or grant.
+
+## Effect classes
+
+- Read-only inspection
+- Local repository changes
+- Remote writes
+- Destructive operations
+- Secret or credential access
+
+Remote, destructive, and secret-bearing actions stay explicitly gated even when local repository access is configured for fewer prompts.
+
+## Secret handling
+
+Tokens, OAuth material, private paths, and proprietary source must not enter public logs, artifacts, docs, packages, or issue reports. Public export and release checks scan for unsafe content but do not replace careful review.
+
+## Runtime and release integrity
+
+Stable releases are immutable and identified by full Git revision plus manifest hash. Rollback uses exact known-good evidence. Ambiguous source ownership, stale activation, dirty source, or release drift fails closed.
+
+## Reporting vulnerabilities
+
+Use GitHub private vulnerability reporting. See the repository [Security Policy](https://github.com/moretea-labs/forge/blob/main/SECURITY.md).

package/docs/wiki/Troubleshooting.md

@@ -0,0 +1,38 @@
+# Troubleshooting
+
+## Start with layer separation
+
+1. Is the repository and checkout correct?
+2. Is the canonical Forge Runtime running and ready?
+3. Does the in-process Gateway and MCP transport answer locally?
+4. Does MCP initialize and list tools with the expected release identity?
+5. Is the optional external tunnel reachable?
+6. What does standalone Recovery report for restart attempts and release coherence?
+
+A single 502 does not identify which layer failed.
+
+## Request timed out
+
+Check the durable Work, Job, Run, or managed process before retrying. Replaying a write can create duplicate effects even when the original HTTP request failed.
+
+## External 502 or 503
+
+Compare the local Forge Runtime MCP endpoint with external MCP health. A tunnel process can remain alive after all data-plane connections are lost. Confirm local authenticated MCP first, then inspect the configured tunnel and its registered connections.
+
+## Runtime repeatedly restarts
+
+Inspect the immutable active release, service runner, Runtime ownership, release authority, database compatibility, Worker protocol, and Recovery audit. The watchdog performs only bounded whole-Runtime restart attempts. After exhaustion it may restore an independently attested previous release; it never loops indefinitely or restarts individual components.
+
+## Release mismatch
+
+Compare the canonical source commit, manifest hash, active whole-release authority, installed Forge service definition, Runtime instance, database schema compatibility, Worker protocol, and authenticated MCP tool fingerprint. Short hashes are not sufficient release identity.
+
+## Recovery cannot roll back
+
+A previous release must have exact path, release ID, artifact identity, manifest hash, Worker protocol, bound SQLite backup, and independent known-good attestation. Automatic recovery must also prove the current Runtime stopped before restoration. Never weaken matching merely to force a rollback.
+
+Detailed guides:
+
+- [General troubleshooting](https://github.com/moretea-labs/forge/blob/main/docs/operations/troubleshooting.md)
+- [Controller reliability](https://github.com/moretea-labs/forge/blob/main/docs/operations/controller-reliability-runbook.md)
+- [502 and performance](https://github.com/moretea-labs/forge/blob/main/docs/operations/controller-performance-and-502.md)

package/docs/wiki/Work-Lifecycle.md

@@ -0,0 +1,31 @@
+# Work Lifecycle
+
+## 1. Inspect
+
+Resolve the repository and checkout, read current status, and check whether an Issue, Task, Work, Job, or Run already owns the objective. Avoid duplicate work.
+
+## 2. Plan the smallest safe unit
+
+Use direct edits for bounded changes. Use durable Tasks, isolated worktrees, or campaigns when work is long-running, parallel, dependency-aware, or high risk.
+
+## 3. Execute with ownership
+
+A writer must own the relevant repository or runtime resource. Claims, leases, and fencing prevent two actors from silently mutating the same state.
+
+## 4. Review the actual change
+
+Inspect the localized diff, separate unrelated modifications, and preserve changes whose ownership is not yet known. Never clean a workspace merely to make a check pass.
+
+## 5. Validate
+
+Run focused checks first, then the declared package or release gate. Managed processes may return a durable handle before completion; retrieve the same operation instead of starting a duplicate.
+
+## 6. Integrate
+
+Commit explicit paths, merge through the intended strategy, and record the integrated revision. A validation result from a feature branch is not automatically evidence for a different main revision.
+
+## 7. Finalize and clean
+
+Update task evidence, delete merged branches and temporary worktrees, and verify the target branch is clean. Blocked or failed states remain recoverable; they are not treated as immutable terminal truth.
+
+For detailed lifecycle contracts, see [Job and Run Lifecycle](https://github.com/moretea-labs/forge/blob/main/docs/architecture/current/job-and-run-lifecycle.md).

package/docs/wiki/_Sidebar.md

@@ -0,0 +1,21 @@
+**Forge Wiki**
+
+- [Home](Home)
+- [Quick Start](Quick-Start)
+- [Installation](Installation)
+- [Core Concepts](Core-Concepts)
+- [Work Lifecycle](Work-Lifecycle)
+- [Architecture](Architecture)
+- [Runtime Architecture](Runtime-Architecture)
+- [Implementation](Implementation)
+- [Operations](Operations)
+- [Integrations](Integrations)
+- [Troubleshooting](Troubleshooting)
+- [Security Model](Security-Model)
+- [Releases and Upgrades](Releases-and-Upgrades)
+
+**Project**
+
+- [Repository](https://github.com/moretea-labs/forge)
+- [Versioned Docs](https://github.com/moretea-labs/forge/tree/main/docs)
+- [Support](https://github.com/moretea-labs/forge/blob/main/SUPPORT.md)

package/install.ps1

@@ -0,0 +1,48 @@
+param(
+  [switch]$DryRun,
+  [ValidateSet("auto", "bun", "node")]
+  [string]$Runtime
+)
+$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+$PackageName = "@moretea-labs/forge"
+$PackageVersion = if ($env:FORGE_VERSION) { $env:FORGE_VERSION } else { "next" }
+$InstallRuntime = if ($Runtime) { $Runtime.ToLowerInvariant() } elseif ($env:FORGE_INSTALL_RUNTIME) { $env:FORGE_INSTALL_RUNTIME.ToLowerInvariant() } else { "auto" }
+$MinimumNodeVersion = [version]"20.10.0"
+$BunInstall = if ($env:BUN_INSTALL) { $env:BUN_INSTALL } else { Join-Path $HOME ".bun" }
+$BunBin = Join-Path $BunInstall "bin"
+function Test-Command([string]$Name) { return [bool](Get-Command $Name -ErrorAction SilentlyContinue) }
+function Add-PathEntry([string]$PathEntry) { if ($PathEntry -and (Test-Path $PathEntry)) { $entries = $env:PATH -split [System.IO.Path]::PathSeparator; if ($entries -notcontains $PathEntry) { $env:PATH = "$PathEntry$([System.IO.Path]::PathSeparator)$env:PATH" } } }
+function Refresh-InstallerPath { Add-PathEntry $BunBin; if ($env:APPDATA) { Add-PathEntry (Join-Path $env:APPDATA "npm") }; if (Test-Command "npm") { $npmPrefix = (& npm config get prefix 2>$null | Select-Object -First 1).Trim(); Add-PathEntry $npmPrefix } }
+function Assert-Prerequisites {
+  if ($PSVersionTable.PSVersion -lt [version]"5.1") { throw "PowerShell 5.1 or newer is required. PowerShell 7 is recommended." }
+  if (-not (Test-Command "git")) { throw "Git is required. Install Git for Windows, reopen PowerShell, and rerun this installer." }
+  if (-not (Test-Command "node")) { throw "Node.js 20.10 or newer is required because the published Forge launcher uses Node." }
+  $nodeText = (& node -p "process.versions.node").Trim(); if ($LASTEXITCODE -ne 0 -or -not $nodeText) { throw "Node.js is present, but its version could not be read." }
+  if ([version]$nodeText -lt $MinimumNodeVersion) { throw "Node.js 20.10 or newer is required; found $nodeText." }
+}
+function Install-BunIfNeeded { if (Test-Command "bun") { return }; Invoke-RestMethod https://bun.sh/install.ps1 | Invoke-Expression; Refresh-InstallerPath; if (-not (Test-Command "bun")) { throw "Bun installation completed, but bun is still not on PATH." } }
+function Select-InstallRuntime {
+  switch ($InstallRuntime) {
+    "bun" { Install-BunIfNeeded; return "bun" }
+    "node" { if (-not (Test-Command "npm")) { throw "npm is required for FORGE_INSTALL_RUNTIME=node." }; return "node" }
+    "auto" { if (Test-Command "bun") { return "bun" }; if (Test-Command "npm") { return "node" }; throw "Neither Bun nor npm is available." }
+    default { throw "Invalid FORGE_INSTALL_RUNTIME=$InstallRuntime. Expected auto, bun, or node." }
+  }
+}
+if ($DryRun -or $env:FORGE_DRY_RUN -eq "1") { Write-Host "DRY RUN: would require Git and Node.js 20.10+, choose runtime ($InstallRuntime), install $PackageName@$PackageVersion, and verify the Forge CLI."; exit 0 }
+Refresh-InstallerPath
+Assert-Prerequisites
+$Runtime = Select-InstallRuntime
+$PackageSpec = "$PackageName@$PackageVersion"
+if ($Runtime -eq "bun") { & bun add -g $PackageSpec } else { & npm install -g $PackageSpec --omit=optional --no-audit --no-fund }
+if ($LASTEXITCODE -ne 0) { throw "Package installation failed with exit code $LASTEXITCODE." }
+Refresh-InstallerPath
+if (-not (Test-Command "forge")) { throw "forge is not on PATH after installation." }
+$Version = (& forge --version | Select-Object -First 1).Trim(); if ($LASTEXITCODE -ne 0 -or -not $Version) { throw "Forge installed, but version readback failed." }
+& forge doctor --help *> $null; if ($LASTEXITCODE -ne 0) { throw "Forge installed, but the doctor command could not be loaded." }
+Write-Host "Forge $Version installed."
+Write-Host "Next:"
+Write-Host "  forge install --no-cli"
+Write-Host "  forge doctor"
+Write-Host "  forge adopt --repo C:\path\to\your-project --dry-run"

package/install.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env sh
+set -eu
+
+PACKAGE_NAME="@moretea-labs/forge"
+PACKAGE_VERSION="${FORGE_VERSION:-next}"
+INSTALL_RUNTIME="${FORGE_INSTALL_RUNTIME:-auto}"
+
+log() { printf '%s\n' "$*"; }
+die() { printf 'Forge install: %s\n' "$*" >&2; exit 1; }
+has_command() { command -v "$1" >/dev/null 2>&1; }
+
+HOME_DIR="${HOME:-}"
+[ -n "$HOME_DIR" ] || die "HOME is not set"
+BUN_INSTALL_DIR="${BUN_INSTALL:-$HOME_DIR/.bun}"
+
+ensure_git() { has_command git || die "Git is required. Install Git and reopen the terminal."; }
+ensure_node() {
+  has_command node || die "Node.js 20.10 or newer is required because the published Forge launcher uses Node."
+  node -e 'const [major, minor] = process.versions.node.split(".").map(Number); process.exit(major > 20 || (major === 20 && minor >= 10) ? 0 : 1)' \
+    || die "Node.js 20.10 or newer is required; found $(node --version 2>/dev/null || printf unknown)"
+}
+install_bun() {
+  has_command bun && return 0
+  has_command bash || die "bash is required to install Bun automatically"
+  if has_command curl; then curl -fsSL https://bun.sh/install | bash
+  elif has_command wget; then wget -qO- https://bun.sh/install | bash
+  else die "curl or wget is required to install Bun automatically"; fi
+  export PATH="$BUN_INSTALL_DIR/bin:$PATH"
+  has_command bun || die "Bun install completed, but bun is still not on PATH"
+}
+choose_runtime() {
+  case "$INSTALL_RUNTIME" in
+    bun) install_bun; printf 'bun\n' ;;
+    node) has_command npm || die "npm is required for FORGE_INSTALL_RUNTIME=node"; printf 'node\n' ;;
+    auto) if has_command bun; then printf 'bun\n'; else has_command npm || die "npm is required when Bun is unavailable"; printf 'node\n'; fi ;;
+    *) die "invalid FORGE_INSTALL_RUNTIME=$INSTALL_RUNTIME (expected auto, bun, node)" ;;
+  esac
+}
+install_forge() {
+  runtime="$1"; package_spec="${PACKAGE_NAME}@${PACKAGE_VERSION}"
+  if [ "$runtime" = "bun" ]; then log "Installing ${package_spec} with Bun..."; bun add -g "$package_spec"
+  else log "Installing ${package_spec} with npm..."; npm install -g "$package_spec" --omit=optional --no-audit --no-fund; fi
+}
+verify_forge() {
+  export PATH="$BUN_INSTALL_DIR/bin:$PATH"
+  has_command forge || die "forge is not on PATH after installation. Reopen the terminal or add the package-manager global bin directory to PATH."
+  version="$(forge --version 2>/dev/null || true)"
+  [ -n "$version" ] || die "Forge installed, but version readback failed"
+  forge doctor --help >/dev/null 2>&1 || die "Forge installed, but the doctor command could not be loaded"
+  log "Forge ${version} installed."
+}
+
+if [ "${FORGE_DRY_RUN:-0}" = "1" ]; then
+  log "DRY RUN: would require Git and Node.js 20.10 or newer, choose runtime (${INSTALL_RUNTIME}), install ${PACKAGE_NAME}@${PACKAGE_VERSION}, and verify the Forge CLI."
+  exit 0
+fi
+ensure_git
+ensure_node
+runtime="$(choose_runtime)"
+install_forge "$runtime"
+verify_forge
+log ""
+log "Next:"
+log "  forge install --no-cli"
+log "  forge doctor"
+log "  forge adopt --repo /path/to/your-project --dry-run"