ForgeFlow/README.md

# ForgeFlow

ForgeFlow 0.8 adds partial-hunk commits, guided conflict recovery, Gitea pull
requests and protected-branch awareness, configurable editor/terminal actions,
deployment policies and release notes, append-only audit export, encrypted
configuration backup, native tray/notifications and a guarded end-to-end
acceptance harness.

## Publish this release to the built-in updater repository

Extract the full source ZIP to a folder under Downloads and run:

```powershell
Set-ExecutionPolicy -Scope Process Bypass
.\Publish-ForgeFlow-Release.ps1
```

The script runs the complete quality gate, clones `git@gitea.itworx.tech:Jens/ForgeFlow.git` into a temporary folder, mirrors the verified source without `.git`, `node_modules` or release ZIPs, commits it on `main` and pushes it. A running older ForgeFlow source installation can then update through **Settings → Updates**.



ForgeFlow is a desktop release cockpit that turns the complete path from a local
code change to a verified server deployment into one guided flow:

```text
Local working tree -> Gitea repository -> exact deployed server version
```

It is not an IDE and it does not replace Gitea Actions. ForgeFlow coordinates
local Git, a private Gitea instance and fixed deployment workflows while keeping
credentials on the user's own computer.

![ForgeFlow overview](docs/screenshots/overview.png)

## Current status: v0.6.0 self-healing Git and Unraid operations

### Git recovery and repository truth

- serializes every mutating Git action per repository;
- waits through a short grace period and automatically retries after safely removing a proven stale lock;
- detects `HEAD.lock`, `index.lock`, ref locks and worktree locks while skipping object storage;
- provides repository-specific actions for fetch, fast-forward, push and backed-up divergence reset;
- creates a `forgeflow/backup-*` safety branch before any reset to upstream.

### SSH / Unraid and DockerMan

- reconciles interrupted deployments against the live SHA, container state and health;
- applies DockerMan WebUI, icon and shell labels through an override and writes a persistent XML template fallback;
- keeps the visible container name such as `Portfolio` while enforcing lowercase internal service/image identities;
- includes a built-in high-contrast ITWorx icon, local PNG upload, persistent DockerMan image storage and cache refresh;
- exposes **Open Web UI**, **Repair DockerMan integration** and **Reconcile** directly on deployment cards.

### Update reliability

- confirms the external updater handshake before closing ForgeFlow;
- rejects malformed PowerShell update helpers before publication;
- validates the replacement source and keeps rollback/success status for the next launch;
- verifies that Gitea reports the exact published release commit.

Read [SSH / Unraid deployment](docs/SSH_UNRAID_DEPLOYMENT.md) and the
[LumaOps audit](docs/LUMAOPS_SERVER_AUDIT.md).

### v0.4.2 automatic clone workflow

**Clone from Gitea** now uses the first configured project root and creates the
repository-named subfolder automatically. The native folder picker is reserved
for the explicit **Choose another location** action. Existing matching checkouts
are linked; conflicting folders are never overwritten.

The Windows environment doctor retains the v0.3.1 npm command-shim correction.

Version 0.3.2 is designed so the user does not need to give a developer any
Gitea token, SSH key, server password or other credential. The application now
includes:

- a five-step setup wizard;
- computer, Gitea and deployment preflights;
- protected local token entry;
- structured local diagnostics with aggressive secret redaction;
- standard and strict privacy support bundles;
- fail-closed bundle safety auditing;
- request IDs that correlate desktop, Actions and server events;
- root-owned allowlisted server target configuration;
- a complete setup guide from fresh checkout to first rollback test.

Start with [START_HERE.md](START_HERE.md). The full installation and acceptance
procedure is in [docs/SETUP_GUIDE.md](docs/SETUP_GUIDE.md).

## What ForgeFlow can do

### Repository workflow

- Connect to a private Gitea instance and validate the account locally.
- Discover Git working trees beneath one or more project roots.
- Use the first project root as the automatic clone destination.
- Match local folders to Gitea repositories using normalized `origin` identity.
- Link existing repositories or clone directly into the default project root.
- Read real Git status through porcelain v2 and NUL-delimited output.
- Inspect diffs and select files.
- Stage and unstage changes.
- Commit locally or commit and push in one action.
- Push, fetch and use fast-forward-only pull.
- Review recent history.
- Create, switch and publish branches.
- Stash, list and restore local work.
- Mark favorites and prioritize repositories requiring attention.
- Refresh repository state automatically while the application is open.

### Deployment workflow

- Configure multiple environments per repository.
- Bind each environment to a fixed branch and fixed Gitea Actions workflows.
- Run a visible deployment preflight before confirmation.
- Re-run mandatory checks in the privileged backend before dispatch.
- Verify a clean tree, correct branch, upstream and ahead/behind state.
- Verify that the exact full SHA exists on the allowed remote branch.
- Verify local and remote workflow files and Gitea Actions availability.
- Dispatch a unique request ID with the exact commit SHA.
- Poll Gitea Actions runs and jobs.
- Correlate the workflow with the server status endpoint.
- Verify that the requested SHA is actually live.
- Run an independent application healthcheck.
- Roll back through a separate fixed workflow to the previous exact SHA.
- Preserve a bounded local operation history.

### Safe diagnostics

ForgeFlow stores structured JSONL diagnostics in the application-data folder.
They are intended to make development and troubleshooting possible without
requesting credentials.

The logger records useful operational facts such as:

- timestamps, stable event names and duration;
- Git action outcomes and repository state;
- Gitea endpoint paths and HTTP status, but not authorization headers;
- deployment request IDs, workflow stages and health states;
- preflight results;
- sanitized error names, codes, messages and stacks.

It excludes or redacts:

- Gitea tokens and encrypted token blobs;
- passwords, authorization headers and credential-bearing URLs;
- private keys and common token patterns;
- arbitrary environment-variable dumps;
- local source contents and Git diffs;
- raw Gitea runner logs from support bundles;
- user-home paths.

Support bundles are audited before writing. If a known runtime secret, private
key marker or URL credential remains, ForgeFlow aborts the export instead of
creating the ZIP. Strict privacy mode also hashes repository and user
identifiers while keeping related events correlatable.

Read [docs/DIAGNOSTICS.md](docs/DIAGNOSTICS.md) for the exact policy and its
limitations.

## Security model

- Electron main/preload/renderer separation.
- Sandboxed renderer with context isolation and no direct Node.js access.
- Narrow, frozen preload API.
- Trusted renderer-origin checks on privileged IPC.
- No arbitrary shell command field in the interface.
- Gitea token stored using Electron `safeStorage` when available.
- Blank token updates preserve the existing protected token.
- Atomic local configuration writes and schema migration.
- Repository-relative path validation for file actions.
- Supported-protocol and credential-in-URL validation.
- Fixed workflow, branch and environment allowlists.
- Root-owned server target configuration.
- Exact-SHA deployment and rollback.
- Server-side locking, health validation and status records.
- Local diagnostic retention, rotation and clear/export controls.

More detail is available in [docs/SECURITY.md](docs/SECURITY.md).

## Prerequisites

For a Windows source setup:

- Windows 10 or 11;
- Node.js 22 or newer;
- npm;
- Git on `PATH`;
- a normal signed-in desktop session;
- access to your own Gitea instance.

For deployment:

- Gitea Actions enabled;
- a trusted Gitea runner with an environment-specific label;
- a Linux target server reachable by that runner;
- Git, Docker Compose, `curl` and `flock` on the target server;
- an existing non-interactive server checkout of the application.

## Fastest Windows start

Extract the release, open PowerShell in the folder and run:

```powershell
Set-ExecutionPolicy -Scope Process Bypass
.\setup-windows.ps1
```

The script:

1. checks Node.js, npm and Git;
2. installs the exact dependency versions from `package-lock.json` when present;
3. runs the environment doctor;
4. validates the source tree;
5. runs all automated tests;
6. starts ForgeFlow.

No Gitea or server credential is requested by the PowerShell script. Tokens are
entered later in the local desktop wizard.

Manual equivalent:

```bash
npm install --no-audit --no-fund
npm run doctor
npm run check
npm start
```

## Setup and first acceptance test

Follow these documents in order:

1. [START_HERE.md](START_HERE.md)
2. [docs/SETUP_GUIDE.md](docs/SETUP_GUIDE.md)
3. [docs/UPDATING.md](docs/UPDATING.md)
4. [docs/DEPLOYMENT_SETUP.md](docs/DEPLOYMENT_SETUP.md)
5. [docs/STATUS_ENDPOINT.md](docs/STATUS_ENDPOINT.md)
6. [docs/DIAGNOSTICS.md](docs/DIAGNOSTICS.md)

The recommended first test uses a non-critical staging deployment and validates:

```text
preflight -> commit -> push -> deploy -> Actions -> server SHA -> healthcheck -> rollback
```

## Updating an existing source installation

Close ForgeFlow, copy the v0.4.2 update overlay over the existing source folder
and run:

```powershell
Set-ExecutionPolicy -Scope Process Bypass
.\update-windows.ps1
```

Application configuration and protected credentials are stored outside the
source folder and are not reset. See [docs/UPDATING.md](docs/UPDATING.md).

## Browser demo

The standalone visual demo requires no Gitea connection or credentials:

```bash
npm run demo
```

Open the printed local URL. The demo uses `src/renderer/mock-bridge.js`; the
packaged desktop application uses the privileged `preload.cjs` bridge.

## Quality checks

```bash
npm run verify
npm test
npm run check
npm run doctor -- --json
```

Version 0.3.2 contains 45 automated tests. Two integration suites create real
temporary bare Git remotes and exercise commit, push, branch, stash and exact
remote-SHA behavior. Detailed coverage is listed in
[docs/TEST_MATRIX.md](docs/TEST_MATRIX.md).

## Development packages

```bash
npm run dist:win
npm run dist:linux
npm run dist:mac
```

Windows users can run:

```powershell
.\build-windows.ps1
```

These commands create unsigned development packages. Public distribution still
requires platform code signing and platform-specific release acceptance.

## Server-side deployment model

ForgeFlow never sends a free-form deployment command. It dispatches a fixed
workflow with controlled inputs:

```json
{
  "ref": "main",
  "inputs": {
    "environment": "staging",
    "commit_sha": "0123456789abcdef0123456789abcdef01234567",
    "request_id": "generated-by-forgeflow"
  }
}
```

The workflow calls a root-owned allowlisted server script. Deployment targets
are defined in `/etc/forgeflow/targets.conf`, not supplied by the desktop app.
The server checks repository, environment, paths, branch, exact remote ancestry,
locking, Docker Compose result and health before it updates the public status
JSON.

## Project structure

```text
main.cjs                         Electron lifecycle and service composition
preload.cjs                      Whitelisted renderer API and event bridge
src/main/config-store.cjs        State, migration and protected token storage
src/main/git-service.cjs         Real Git CLI adapter
src/main/gitea-service.cjs       Gitea REST and Actions adapter
src/main/repository-service.cjs  Discovery, matching and repository aggregation
src/main/repository-monitor.cjs  Background working-tree awareness
src/main/deployment-service.cjs  Dispatch, polling, SHA checks and rollback
src/main/preflight-service.cjs   Computer and deployment readiness checks
src/main/diagnostics-service.cjs Safe JSONL diagnostics and support bundles
src/main/log-redaction.cjs       Recursive secret and privacy sanitizer
src/main/ipc.cjs                 Validated privileged operation boundary
src/shared/clone-target.cjs      Safe automatic clone target planning
src/shared/zip-writer.cjs        Dependency-free diagnostic ZIP writer
src/renderer/                    Desktop UI and browser demo
examples/gitea-actions/          Fixed deploy and rollback workflow templates
examples/server/                 Allowlisted Linux deployment implementation
tests/                           Unit and real Git integration tests
docs/                            Setup, diagnostics, security and architecture
```

## Scope and remaining acceptance

The v0.4.2 logic is prepared for self-service configuration and testing, but no
source release can prove compatibility with a private environment it has never
connected to. The remaining acceptance is deliberately local to the user:

- validate the exact Gitea version and Actions API;
- validate the runner label and runner permissions;
- adapt one target line in the root-owned server configuration;
- verify the application-specific Docker Compose and health endpoint;
- execute the documented staging deployment and rollback test;
- export a Strict support bundle if a failure occurs.

No credential needs to be shared for that process.

## License

MIT. See [LICENSE](LICENSE).