TylerandClaude Fable 5
fedf1d24c0
Template tests / tests (pull_request) Failing after 31s
Phase 3 of the improvement plan (PR 8 of the sequence): the apt/X11 packaging half of Linux support, in separate Linux-specific files. Replaces the old scripts/package-linux.sh, which the audit flagged as "not production packaging" (it copied the whole dev node_modules — including vulnerable build deps — plus docs/prompts/examples/audit files, hardcoded amd64, declared only xinput, lacked desktop/icon/MIME integration, and could build without node_modules). Production builder (packaging/linux/debian/package.sh): - Stages ONLY runtime files: app code, a fixed Electron runtime, and the production npm deps (enumerated via npm ls --omit=dev). Never copies the development node_modules; guards against electron-builder/app-builder-lib leaking in. Fails if node_modules is absent instead of shipping an unusable artifact. - Detects architecture (dpkg --print-architecture, x64/arm64) rather than hardcoding amd64. Generates DEBIAN/control from control.in with proper runtime Depends, real maintainer, and homepage. - Installs a desktop entry, hicolor icons (16–512), .sfgz/.sfglt MIME registration, the launcher, and the license. postinst makes chrome-sandbox setuid and refreshes desktop/MIME/icon caches; postrm cleans them. - Emits a .deb, a portable tarball that now INCLUDES /usr/bin/stepforge (the old tarball omitted it), and a sha256 sums file. Launcher (packaging/linux/common/launcher.sh): - Runs sandboxed; prefers the user-namespace sandbox, accepts a root-owned setuid helper, and otherwise refuses to launch with an actionable message. --no-sandbox requires an explicit STEPFORGE_ALLOW_NO_SANDBOX opt-in. Never installs anything at runtime. Setup (separate build vs runtime, apt only): - scripts/linux/apt/install-runtime-deps.sh (Chromium/Electron libs, X11 tools, portal/PipeWire) and install-build-deps.sh (dpkg-dev, fakeroot, xvfb). Runtime script installs no build tools. Assets: original StepForge icon — packaging/assets/stepforge.svg plus a generator (scripts/make-icons.js) that renders the PNG set with the repo's own rasterizer/PNG writer (no third-party art). npm run icons regenerates them. Wiring: package.json gains package:linux:deb / package:linux:rpm / icons; build-release.sh uses the production builder and requires node_modules; README points at the apt/dnf guides. Tests: tests/unit/packaging-linux.test.js (structural: files present in their separate locations, old script gone, valid desktop entry, templated arch + runtime Depends, launcher gates --no-sandbox, builder requires node_modules and guards dev-dep leaks, apt build/runtime dep separation, original icon set generates a valid PNG) runs in the normal suite; tests/integration/linux/package-deb.test.sh builds a real .deb and asserts the right files present and the dev tree / build tooling / app docs absent (honest skip only when dpkg-deb/node_modules are genuinely missing). Verified locally: 276 unit tests pass; the integration test builds and validates stepforge_0.3.2_amd64.deb; build-release E2E passes with the new production package. Co-Authored-By: Claude Fable 5 <[email protected]>
150 lines
6.7 KiB
Markdown
150 lines
6.7 KiB
Markdown
# StepForge
|
|
|
|
StepForge is a **local-first**, open-source desktop app for Windows, with
|
|
Linux (WIP) builds. It captures step-by-step workflows as screenshots, lets
|
|
you annotate and describe each step in a focused three-pane editor, and
|
|
exports the result to Markdown, DOCX, PPTX, PDF, HTML (WIP), GIF (WIP),
|
|
confluence (WIP), Wiki.js (WIP), and image bundles (WIP). The current
|
|
reconmendations for exporting is Markdown and PDF.
|
|
|
|
It is an independent desktop guide-capture tool inspired by publicly
|
|
documented workflow patterns of commercial documentation tools like Folge. It
|
|
contains no third-party branding, assets, or code from those tools.
|
|
|
|
**Network and privacy contract.** StepForge has no telemetry, no update
|
|
checks, no license checks, and no cloud. Guides never leave your machine on
|
|
their own. The only outbound network feature is the **optional** AI
|
|
integration: when *you* enable it and configure an [Ollama](https://ollama.com)
|
|
endpoint, StepForge sends step screenshots and text to that endpoint to
|
|
generate titles and descriptions. By default that endpoint must be **local
|
|
(loopback)**; sending data to a remote host requires the explicit "Allow
|
|
remote AI host" opt-in. See [docs/PRIVACY.md](docs/PRIVACY.md) for exactly
|
|
what is collected and sent. Note that OCR (Tesseract) and its English language
|
|
data are bundled production dependencies — Electron is not the only one.
|
|
|
|
## Overview
|
|
|
|
The core workflow:
|
|
|
|
1. **Capture** — take full-screen, active-window, or region screenshots with
|
|
configurable delay, pause/resume, and global hotkeys; or import images and
|
|
paste from the clipboard.
|
|
2. **Annotate** — rectangles, ovals, lines, arrows, text, tooltips, numbered
|
|
markers, blur, highlight, magnify, and crop on a resolution-independent
|
|
annotation scene graph.
|
|
3. **Describe** — rich-text titles and descriptions, informational text
|
|
blocks, code blocks, tables, step links, and placeholders.
|
|
4. **Export** — every exporter renders from the same normalized Render AST,
|
|
so output is deterministic across formats.
|
|
|
|
|
|
## What's Included
|
|
|
|
- **Guide library** with folders, favorites, title search, full-text search,
|
|
duplicate/move/delete, and a quick-actions palette (`Ctrl+/`).
|
|
- **Capture engine** — the editor's **Capture ▾** button offers full screen,
|
|
active window, and region capture (the app hides itself during the shot),
|
|
plus continuous capture sessions that grab a step on every click where the
|
|
OS allows it, or on a 3/5/10 s auto-interval everywhere else. The REC bar
|
|
shows the live count and the start/pause control. Delay, global
|
|
hotkeys, click markers, clipboard paste, and PNG/JPEG/GIF import included.
|
|
The full keyboard shortcut list lives under **More ▾ → Keyboard
|
|
shortcuts** in the editor.
|
|
- **Three-pane editor** — step tree with substeps, statuses
|
|
(todo/in-progress/done), hidden/skipped steps, focused view (zoom/pan that
|
|
never mutates the original image), autosave, and command-stack undo/redo.
|
|
- **Annotation canvas** — normalized JSON scene graph with
|
|
resolution-independent coordinates; annotations render identically in the
|
|
editor and in every exporter.
|
|
- **Sharing & backups** — single-file `.sfgz` archives (zip-based, path-
|
|
traversal validated), linked guides with `.lock-sfgz` lock files and
|
|
explicit save, plus automated snapshot backups and restore.
|
|
- **Exports** — JSON, Markdown, Simple HTML, Rich HTML (checkboxes + floating
|
|
TOC), PDF, animated GIF, image bundle, DOCX, and PPTX, with per-format
|
|
export templates shareable as `.sfglt` files.
|
|
- **Settings & theming** — system/light/dark themes, capture options,
|
|
keyboard shortcuts, preview step count.
|
|
|
|
Everything except the Electron shell is dependency-free Node.js: the ZIP,
|
|
PNG, GIF, PDF, DOCX, and PPTX writers are all implemented in this repository
|
|
using only Node built-ins.
|
|
|
|
## Getting Started
|
|
|
|
For a Windows installation, see [docs/windows_installation](docs/windows_installation.md) or for a developer/more in depth walkthrough, see [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md).
|
|
|
|
On **Linux**, install from a package built for your distro family:
|
|
apt-based (Debian/Ubuntu) → [docs/linux/apt.md](docs/linux/apt.md); dnf-based
|
|
(Fedora) → [docs/linux/dnf.md](docs/linux/dnf.md). Wayland uses the XDG portal
|
|
for screen capture and a hotkey/interval trigger (per-click capture with a
|
|
marker needs X11 + xinput). The general developer walkthrough is
|
|
[docs/GETTING_STARTED_WITH_LINUX.md](docs/GETTING_STARTED_WITH_LINUX.md).
|
|
|
|
Requirements: Node.js 22.12+ and npm (pinned in `.nvmrc`; installs are
|
|
refused on older Nodes because the packaging toolchain needs 22.12+).
|
|
|
|
```bash
|
|
npm ci # one-time, installs the locked dependency tree
|
|
npm start # launch StepForge
|
|
```
|
|
|
|
Dependencies are only ever installed by you, via `npm ci` — the app never
|
|
downloads or repairs packages at runtime.
|
|
|
|
First run creates the local data directory (`~/.local/share/stepforge` on
|
|
Linux (WIP), `%APPDATA%/stepforge` on Windows; override with
|
|
`STEPFORGE_DATA_DIR`).
|
|
|
|
## Testing
|
|
|
|
Please create your tests so that when the following is ran it automatically
|
|
tests your test.
|
|
|
|
```bash
|
|
bash tests/run_test.sh
|
|
```
|
|
|
|
The runner executes every `tests/checks/test_*.sh` script; those scripts run
|
|
the workflow test suites under `tests/unit/` with `node --test`. The tests
|
|
exercise real workflows like creating guides, round-tripping archives, exporting
|
|
documents, and validating the bytes of the output, not string matching.
|
|
|
|
## Building & Packaging
|
|
|
|
```bash
|
|
bash scripts/bootstrap-offline.sh # verify toolchain availability
|
|
bash scripts/verify.sh # full test suite + smoke checks
|
|
bash scripts/build-release.sh # assemble runnable app directory
|
|
bash scripts/package-linux.sh # local Linux packaging (WIP; not part of release)
|
|
npm run package:windows # Windows installer .exe in releases/
|
|
pwsh scripts/package-windows.ps1 # same Windows installer build via PowerShell
|
|
```
|
|
|
|
See [build/build_report.md](build/build_report.md) for what was produced on
|
|
this machine and which packaging tools were unavailable.
|
|
|
|
## Offline Guarantee
|
|
|
|
The shipping app makes **zero network calls**. There is no telemetry, no
|
|
update check, no license validation, no cloud sync, no account system, and no
|
|
remote AI. Exports embed no remote fonts or CDN references. See
|
|
[docs/SECURITY.md](docs/SECURITY.md) for the threat model.
|
|
|
|
## Contributing
|
|
|
|
See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the full contribution flow,
|
|
including the issue-number requirement for every pull request and the
|
|
clean-room rules.
|
|
|
|
## Repository Layout
|
|
|
|
Project docs live in `docs/` and prompt handoffs live in `ai_prompts/`.
|
|
|
|
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the repo layout.
|
|
|
|
## License
|
|
|
|
Creative Commons Attribution-NonCommercial
|
|
|
|
Basically, do whatever you want with it just don't make money off it or sell it.
|