Repository navigation
Development
For working on the app itself. Repo: https://github.com/escacs/stack-app.
- Node.js 22+ (
node --version) - Rust stable (
cargo --version) - An escacs/stack checkout (private repo; this app never bundles it)
- Linux webview deps (names as pkg-config sees them):
webkit2gtk-4.1,librsvg-2.0, pluspatchelffor bundling. Per-distro install lines are on Install.
npm install
npm run dev:app # Tauri dev window (Vite on :1430)Other scripts: npm run dev (Vite only), npm run build, npm run check (tsc --noEmit), npm test (Rust unit tests), npm run build:app (tauri build --no-bundle; never ship release bundles from here).
-
npm run test:ui— vitest (node environment): CLI JSON shapes, parsers, router, onboarding, browse data, argument building, site helpers. -
npm run check—tsc --noEmit. -
npm test— Rust unit tests (cargo test --lib). - Full Rust suite, including the end-to-end shell-out test against a temp stack repo and temp project:
STACK_E2E_REPO=<stack-checkout> cargo test --manifest-path src-tauri/Cargo.toml. Without the var the e2e test skips itself (CI cannot reach the private stack repo, so it runs the lib tests only).
CI gates live in .github/workflows/check.yml (tests), release.yml (bundles) and flatpak.yml (manifest check). See https://github.com/escacs/stack-app/blob/main/.github/workflows/check.yml.
Stack ops (list, show, import, status, update, …) run as node <stack>/tools/stack/cli.mjs … --project <dir> from Rust. Considered alternative: a Tauri sidecar (bundled binary) or a Rust reimplementation of the import logic.
Shell-out wins because:
- Single source of truth. Import/status/update/remove plus the three-way merge live in the stack checkout's
tools/stack/*.mjs. A sidecar or Rust port would fork that logic and drift; every CLI fix would need a matching app release. - Dependency-free tooling rule. The stack keeps tooling dependency-free; a sidecar means bundling a runtime or duplicating the logic in Rust. Shell-out reuses the user's node, which the stack already requires (
engines: node >= 22). - The CLI (CLI Overview) already owns git and the import record (
stack.toml). The app itself never runs git, never commits/pushes, and never executes project code.
Cost: node must be on PATH at runtime. Mitigated by the node_status probe (called at startup; the setup screen shows its error, which names the fix) — every stack_run re-probes and fails with the same clear message.
Revisit if the app must run where node is absent (offline installs): the fallback is packaging tools/stack/ as a Node single-executable sidecar, still without forking the logic.
Call via invoke from @tauri-apps/api/core. All names are camelCase; stack_run/node_status snake_case names are the command names, their payloads are camelCase. Errors arrive as rejected strings — show them verbatim, they are written for users. The typed wrappers live in src/bridge.ts.
| Command | Args | Returns |
|---|---|---|
pick_folder |
— |
string | null (null = cancelled) |
get_config |
— | AppConfig |
save_config |
{ config: AppConfig } |
null |
add_recent_project |
{ path: string } |
AppConfig (updated) |
validate_project |
{ path: string } |
ProjectReport |
scan_projects |
{ root?, roots?, stackDir? } |
ScanOut |
default_scan_roots |
{ stackDir? } |
ScanRoots (wrapper exists; no current view calls it) |
node_status |
— | NodeStatus |
stack_location |
{ stackDir? } |
StackLocation (wrapper exists; no current view calls it) |
validate_stack |
{ stackDir? } |
StackReport |
stack_run |
{ subcommand, args, projectDir, stackDir? } |
{ stdout, stderr, code, truncated } |
type AppConfig = {
recentProjects: string[]; // most recent first, capped at 10
stackPath: string | null; // escacs/stack checkout override (folder-picked)
scanRoot: string | null; // extra scan root; no UI control, edit config.json
scanRoots: string[]; // more scan roots; save_config stores them verbatim
worker: string | null; // e.g. "mel"; a label only, never sent to the stack
project: string | null; // currently selected project dir
};
type ProjectReport = { path: string; valid: boolean; markers: string[]; errors: string[] };
type NodeStatus = { ok: boolean; version: string | null; major: number | null; error: string | null };
type ScanRepo = { path: string; name: string; hasLock: boolean; markers: string[] };
type ScanOut = { root: string; roots: string[]; repos: ScanRepo[]; capped: boolean };
type ScanRoots = { roots: string[]; stackPath: string | null };
type StackLocation = { path: string | null; source: 'settings' | 'env' | 'auto' | 'missing' };
type StackReport = { path: string; valid: boolean; source: string; git: boolean; cli: boolean; node: NodeStatus; error: string | null };stack_run allowlist (enforced in Rust before any subprocess starts):
- Subcommands:
list,search,show,import,status,update,remove,sync,gitignore,init,preset(list,show <name>,apply <name>).syncandgitignoretake no args;inittakes only--json. Everything else (serve,catalog,check,remote,link-skills,path, …) is rejected, so the UI cannot reach repo-maintenance commands. - Flags:
--kind(search),--to <project-relative-dir>(single-entry import),--ref(import, status, update),--file(show),--dry-run(preset apply),--offline(list, search, show, status; the app appends it toshowandstatus),--json(passed through).--projectis always set by Rust itself and cannot be overridden. - Entry ids are charset-checked;
--tois joined onto the project and confined (traversal, absolute paths and symlink escapes rejected). -
stackDirresolution order: the settings override (config.stackPath, folder-picked), theESCACS_STACKenv var, then an upward walk fortools/stack/cli.mjsfrom the app's executable, the folder it was built in, and the working folder (finds nothing in a normal install — first run must pick a folder or export the var). - Output is capped at 4 MiB per stream (truncation marked via
truncated).
Startup sequence (boot() in src/store.ts): node_status → app version → get_config → validate_stack → validate_project (if config.project) → stack_run list worker → stack_run status (if a project is set and node is ok). An unusable stack blocks the views until it is fixed (setup screen).
Security contract (enforced in src-tauri/src/): operate only inside the selected project dir + the stack dir; canonicalize and reject traversal and symlinks escaping the project; never run project code; never git commit/push; never put credentials anywhere (none are handled, none logged).
Capabilities (src-tauri/capabilities/default.json) grant core:default, window minimize / toggle-maximize / close, dialog:allow-open, updater:default and process:allow-restart. App-defined invoke commands need no capability entries; each plugin call needs its permission.
For UI work in a browser, the app can run on a mock of its native bridge. Each mock scenario is a fixture stack, project and user. Fixture data is invented. The mock cannot show the folder picker, the update feed, or persistent settings.
Plain browser checks: POSIX sh and python3, no bash script. The mock is invented fixture data, so a pass proves the UI logic, not the native runtime.
npm run build
out=$(mktemp -d)
cp -r dist/. "$out/"
cp dev/mock-app-bridge.js "$out/mock-bridge.js"
python3 -c 'import sys; p=sys.argv[1]; s=open(p,encoding="utf-8").read(); open(p,"w",encoding="utf-8").write(s.replace("<head>","<head><script src=\"/mock-bridge.js\"></script>",1))' "$out/index.html"
python3 -I -m http.server 8137 --bind 127.0.0.1 --directory "$out"Open http://127.0.0.1:8137/#<scenario>,/<route>, for example #conflicts,/installed. Routes are browse, browse/<kind>, browse/all, browse/<id>, browse/<id>/<file> and installed.
| Scenario | What it shows |
|---|---|
populated (default) |
a project with three imports; one entry not committed; one with uncommitted stack changes |
empty |
who, with two workers |
noworker |
who, with no workers: continue without one leads to browse |
noproject |
project, with recent projects |
scan |
project, with a scan root set. Press scan to list |
conflicts |
installed with update rows and a conflict |
missing |
installed with rows whose files are missing (shown as edited) |
lookalike |
an import refused for skills/file-pr
|
fresh |
installed in a plain folder: init stack.toml
|
bad-stack |
the stack checkout setup screen |
no-node |
the setup screen with node missing |
Reload the page to switch scenario; a hash-only change keeps the old fixture. The mock cannot exercise the native folder picker, the update feed, the startup update event, or real file writes, and its plugin:app|version answer (0.1.0) is not the release version. Label results "fixture check".
dev/mock-bridge.js is an older, minimal mock with three scenarios. When a wire type changes, update both mocks in the same change.
package.json vite.config.ts tsconfig.json index.html
web-vendor/style.css # snapshot of the stack website's stylesheet
dev/mock-bridge.js dev/mock-app-bridge.js
src/ # SolidJS renderer
index.tsx App.tsx app.css ui.tsx site.tsx glide.ts
bridge.ts store.ts updater.ts router.ts onboard.ts
browseData.ts stackArgs.ts json.ts parse.ts
views/
Onboard.tsx StackSetup.tsx TopBar.tsx TitleBar.tsx
Browse.tsx Status.tsx Presets.tsx StackPath.tsx Updates.tsx
*.test.ts # vitest, node environment
src-tauri/
Cargo.toml build.rs tauri.conf.json Cargo.lock
capabilities/default.json
src/{main,lib,config,paths,project,scan,stack}.rs
tests/stack_e2e.rs
docs/ # INSTALL, UPDATES, PORTABILITY, USAGE
scripts/ # install, provision, uninstall (AppImage)
flatpak/ # draft manifest, not validated
.github/workflows/check.yml release.yml flatpak.yml
Pinned versions follow the stack's libraries/tauri and libraries/solid-js entries; config adapted from its templates/solid-tauri-vite (single entry, normal window, no android mode). Cargo.lock is committed — it is what pins the crates.
web-vendor/style.css is a point-in-time copy of the stack website's web/style.css (source commit in its header). Re-copy the file to re-sync, never edit the snapshot in place.
The icons in src-tauri/icons/ were rasterized from the stack checkout's assets/escacs-mark/escacs-app-icon.svg and generated with the Tauri CLI. Scratch lives in a temp dir, never the repo:
node <scratch>/rasterize.mjs
./node_modules/.bin/tauri icon <scratch>/icon-1024.pngKey chrome args inside rasterize.mjs (generate.mjs pattern + transparency):
--no-sandbox --disable-gpu --hide-scrollbars --font-render-hinting=none --default-background-color=00000000 --force-device-scale-factor=1 --window-size=1024,1024 --screenshot=<scratch>/icon-1024.png file://<scratch>/icon.html
NOTE: without --default-background-color=00000000 the screenshot flattens to RGB with white corners — the flag is required.
See also: Settings and Storage, Portability, Updates and Releases.
Stack desktop client + CLI wiki — condensed from the repo docs. App repo: https://github.com/escacs/stack-app. CLI repo (private): https://github.com/escacs/stack.