Skip to content

Development

Mel edited this page Nov 10, 2026 · 1 revision

For working on the app itself. Repo: https://github.com/escacs/stack-app.

Prerequisites

  • 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, plus patchelf for bundling. Per-distro install lines are on Install.

Run

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).

Tests and gates

  • 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.

Shell-out decision

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:

  1. 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.
  2. 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).
  3. 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.

Bridge command surface

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>). sync and gitignore take no args; init takes 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 to show and status), --json (passed through). --project is always set by Rust itself and cannot be overridden.
  • Entry ids are charset-checked; --to is joined onto the project and confined (traversal, absolute paths and symlink escapes rejected).
  • stackDir resolution order: the settings override (config.stackPath, folder-picked), the ESCACS_STACK env var, then an upward walk for tools/stack/cli.mjs from 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.

Mock-bridge preview

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.

Layout

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.

Icon regeneration

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.png

Key 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.

Clone this wiki locally