Tyler/StepForge

Fork 0

Files

T

TylerandClaude Fable 5 0f966a5fd0

Template tests / tests (pull_request) Failing after 1m26s

Details

Pin the Node toolchain, remove runtime npm repair, make CI and E2E truthful

Phase 0 of the improvement plan (ai_prompts/prompt4.md): make the baseline
reproducible and stop the test runner from masking real failures.

- Pin Node >= 22.12 (engines + .nvmrc + engine-strict); every entry point
  fails fast with clear guidance instead of dying late with ERR_REQUIRE_ESM
  inside the packaging dependency graph.
- electron-launcher.js is diagnostics-only: all runtime npm install/rebuild/
  repair paths are removed. npm ci on the pinned toolchain is the only
  supported install path (README + GETTING_STARTED updated).
- Refuse to silently launch unsandboxed on Linux: --no-sandbox now requires
  an explicit STEPFORGE_ALLOW_NO_SANDBOX/ELECTRON_DISABLE_SANDBOX opt-in and
  is otherwise a hard error with actionable fixes; user-namespace sandboxing
  is detected and preferred.
- Click-capture E2E no longer converts startup crashes into "SKIPPED": the
  only allowed skip is the upfront absence of a display server. A missing
  shared library or crash now fails with the startup log. Same guard added
  to the startup smoke check.
- GitHub CI: run on pull_request, pin Node from .nvmrc, drop the macOS matrix
  entry (not a support target), and audit production and full dependency
  trees as separate signals. Gitea CI: pull_request trigger + pinned Node.
- Refresh package-lock on Node 22/npm 10 and remediate the form-data and
  undici advisories (npm audit: 0 vulnerabilities, prod and full tree).
- Stop tracking generated machine-specific build reports
  (build/build_report.md, build/artifacts_manifest.json).

Verified: 203 unit tests pass; repo-structure, startup-smoke, unit-workflows,
sample-artifacts, and build-release checks pass locally with a real Electron
launch. The click self-test now truthfully reports the pre-existing Linux
arm/debounce capture failures (also red on Gitea CI main run 177) instead of
hiding behind SKIPPED; that defect is scheduled for the capture-fix PR.

Co-Authored-By: Claude Fable 5 <[email protected]>

2026-07-03 13:09:51 -07:00

2.9 KiB

Raw Permalink Blame History

Getting Started

StepForge is a fully offline desktop app. Nothing is uploaded or synced, and all guides stay on your machine.

Windows installation

For the windows installation, please see windows_installation

Developer install

1. Install

Install the pinned Node toolchain first — Node 22.12 or newer (see .nvmrc; with nvm: nvm install && nvm use). Installs are refused on older Nodes.

From the repository root:

npm ci

That installs the locked dependency tree — Electron and the local packaging tools used by the scripts. npm ci is the only supported installation path; the app never installs or repairs dependencies at runtime.

2. Launch the app

npm start

The first launch creates the local StepForge data directory. On Linux (WIP) it is usually under ~/.local/share/stepforge. On Windows it is usually under %APPDATA%/stepforge.

3. Create your first guide

In the library view:

Click New guide.
Give the guide a clear title (more -> rename guide).
Open the guide to enter the editor.

You can also import a guide archive with Import archive if you already have one.

4. Add content

There are three simple ways to start:

Record your workflow by clicking on the record button (reconmmended).
Import screenshots with the Import button in the editor.
Paste an image from the clipboard if you already copied one.

If you want to capture new screenshots, open Quick actions and start a capture session. Use Settings to set the capture hotkey and other capture options.

5. Edit the guide

The editor is split into three panes:

Steps on the left
Editing canvas in the center
Properties on the right

Use the canvas tools to add shapes, arrows, text, blur, highlight, numbers, and crops. Use the right pane to edit the step title, description, and annotation details.

6. Save and export

Use these actions from the top bar:

Save writes the guide to disk.
Export opens format choices such as JSON, Markdown, HTML, PDF, GIF, image bundle, DOCX, and PPTX.
Linked shows archive details when a guide is linked to a shared .sfgz file.

If you want to find commands quickly, press Ctrl+/ for Quick Actions.

Useful shortcuts

Ctrl+/ opens Quick Actions
Ctrl+S saves the current guide
Ctrl+Z undoes the last edit
Ctrl+Shift+Z redoes the last edit
Alt+Up and Alt+Down move the selected step

If something is missing

Open Settings to review capture, export, and editor options.
Run npm run sample to generate a sample guide and exported examples.
Run bash scripts/verify.sh to check the full offline workflow.

Optional builds

bash scripts/build-release.sh assembles the offline release layout.
npm run package:windows creates the Windows installer .exe in releases/.
bash scripts/package-linux.sh creates Linux release artifacts (WIP; local only).

2.9 KiB Raw Permalink Blame History