Improve root onboarding and fix staged dev/check setup

.github/workflows/crates-ci.yml

@@ -7,12 +7,17 @@ on:
       - "crates/**"
       - "Cargo.toml"
       - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - ".github/workflows/crates-ci.yml"
   push:
     branches: [main]
     paths:
       - "crates/**"
       - "Cargo.toml"
       - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - ".github/workflows/crates-ci.yml"
+  workflow_dispatch:
 
 env:
   CARGO_TERM_COLOR: always
@@ -21,6 +26,8 @@ jobs:
   check:
     name: Check
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 

.github/workflows/mark-ci.yml

@@ -5,12 +5,23 @@ on:
     branches: [main]
     paths:
       - "apps/mark/**"
+      - "packages/**"
       - "crates/**"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "package.json"
+      - ".github/workflows/mark-ci.yml"
   push:
     branches: [main]
     paths:
       - "apps/mark/**"
+      - "packages/**"
       - "crates/**"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "package.json"
+      - ".github/workflows/mark-ci.yml"
+  workflow_dispatch:
 
 env:
   CARGO_TERM_COLOR: always
@@ -19,6 +30,8 @@ jobs:
   check:
     name: Check
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 

.github/workflows/staged-ci.yml

@@ -0,0 +1,65 @@
+name: Staged CI
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "apps/staged/**"
+      - "crates/**"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "package.json"
+      - ".github/workflows/staged-ci.yml"
+  push:
+    branches: [main]
+    paths:
+      - "apps/staged/**"
+      - "crates/**"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "package.json"
+      - ".github/workflows/staged-ci.yml"
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      # Install hermit (manages node, rust, just)
+      - uses: cashapp/activate-hermit@e49f5cb4dd64ff0b0b659d1d8df499595451155a # v1
+
+      # Enable pnpm via corepack (node ships with corepack; version comes from packageManager in package.json)
+      - run: corepack enable pnpm
+
+      # Cache Cargo dependencies
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
+        with:
+          workspaces: apps/staged/src-tauri
+
+      # Install system dependencies for Tauri (Linux)
+      - name: Install Tauri dependencies (Linux)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libwebkit2gtk-4.1-dev \
+            libappindicator3-dev \
+            librsvg2-dev \
+            patchelf
+
+      # Install dependencies
+      - name: Install dependencies
+        run: |
+          pnpm install --frozen-lockfile
+          cd apps/staged/src-tauri && cargo fetch
+
+      # Run all checks via the app justfile
+      - name: Check all (fmt, lint, typecheck)
+        run: just -f apps/staged/justfile ci

.gitignore

@@ -1,2 +1,4 @@
 target/
 .DS_Store
+.hermit
+node_modules/

README.md

@@ -0,0 +1,80 @@
+# Builderbot Monorepo
+
+This repository contains Builderbot apps, shared UI packages, and Rust crates.
+
+## Quick Start
+
+```bash
+# from repo root
+source ./bin/activate-hermit
+just setup
+```
+
+`just setup` runs `lefthook install` and `pnpm install`.
+
+Then run an app:
+
+```bash
+just dev          # start Mark
+just dev staged   # start Staged
+```
+
+## Command Guide
+
+The root `justfile` supports both styles:
+
+```bash
+just dev staged     # verb-first (recommended for humans)
+just app staged dev # explicit delegation form
+```
+
+Useful commands:
+
+```bash
+just apps         # list app names
+just setup        # first-time setup (hooks + JS deps)
+just dev          # run Mark app
+just dev staged   # run Staged app
+just mark         # alias for `just app mark dev`
+just staged       # alias for `just app staged dev`
+just check        # full non-modifying checks
+just ci           # alias of `just check`
+just fmt          # format repo
+just lint         # lint repo
+just test         # run Rust workspace tests
+```
+
+## Repo Layout
+
+- `apps/mark`: main desktop app.
+- `apps/staged`: standalone staged/diff app.
+- `packages/diff-viewer`: shared Svelte diff viewer package.
+- `crates/`: shared Rust crates.
+- `scripts/`: helper scripts used by app tooling.
+
+## App-Level Commands
+
+Each app has its own `justfile` for app-specific workflows:
+
+- `apps/mark/justfile`
+- `apps/staged/justfile`
+
+Use root delegation to run any app recipe:
+
+```bash
+just app mark ci
+just app staged build
+```
+
+## Troubleshooting
+
+- `just: command not found`
+  - Run `source ./bin/activate-hermit` in your shell.
+- Frontend waiting on dev server / port issues
+  - Check listeners: `lsof -nP -iTCP:<port> -sTCP:LISTEN`
+- `node_modules` appears at repo root
+  - Expected for this `pnpm` workspace monorepo; app `node_modules` entries are symlinked into the root store.
+
+## More Docs
+
+- Mark app docs: `apps/mark/README.md`

apps/staged/package.json

@@ -16,6 +16,7 @@
     "@sveltejs/vite-plugin-svelte": "^6.2.1",
     "@tauri-apps/cli": "^2.10.0",
     "@tsconfig/svelte": "^5.0.6",
+    "@types/node": "^24.10.1",
     "prettier": "^3.7.4",
     "prettier-plugin-svelte": "^3.4.1",
     "svelte": "^5.46.4",

apps/staged/src-tauri/tauri.conf.json

@@ -6,7 +6,7 @@
   "build": {
     "frontendDist": "../dist",
     "devUrl": "http://localhost:5175",
-    "beforeDevCommand": "pnpm run dev",
+    "beforeDevCommand": "VITE_PORT=${VITE_PORT:-5175} pnpm run dev",
     "beforeBuildCommand": "pnpm run build"
   },
   "app": {

apps/staged/vite.config.ts

@@ -1,10 +1,12 @@
 import { defineConfig } from 'vite';
 import { svelte } from '@sveltejs/vite-plugin-svelte';
 
+const port = parseInt(process.env.VITE_PORT || '5175', 10);
+
 export default defineConfig({
   plugins: [svelte()],
   server: {
-    port: 5175,
+    port,
     strictPort: true,
   },
 });

justfile

@@ -1,51 +1,108 @@
 # Builderbot Monorepo
 # Run `just setup` once after cloning.
+#
+# Common flows:
+#   just dev            # Start Mark
+#   just dev staged     # Start Staged
+#   just app mark ci    # Run any app recipe
+#   just check          # Full non-modifying checks
 
 # Default: list available recipes
 default:
     @just --list
 
-# ── Setup ──────────────────────────────────────────────────
+# ============================================================================
+# Setup
+# ============================================================================
 
 # First-time setup
 setup:
     lefthook install
     pnpm install
 
-# ── Per-App (delegate) ─────────────────────────────────────
+# ============================================================================
+# App Delegation
+# ============================================================================
 
-# Run a just recipe in a specific app (e.g., just app mark dev)
-app name *ARGS:
-    just -f apps/{{name}}/justfile {{ARGS}}
+# List app workspaces that expose a justfile
+apps:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    for dir in apps/*/; do
+        [[ -f "$dir/justfile" ]] || continue
+        basename "$dir"
+    done
+
+# Run a recipe in a specific app (e.g. `just app mark dev`)
+app name recipe="dev" *args:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    app_justfile="apps/{{name}}/justfile"
+    if [[ ! -f "$app_justfile" ]]; then
+        echo "Unknown app '{{name}}'. Available apps:"
+        for dir in apps/*/; do
+            [[ -f "$dir/justfile" ]] || continue
+            echo "  - $(basename "$dir")"
+        done
+        exit 1
+    fi
+
+    just -f "$app_justfile" {{recipe}} {{args}}
 
-# Shortcuts for the most common app commands
-dev app="mark" *ARGS:
-    just -f apps/{{app}}/justfile dev {{ARGS}}
+# Human-friendly shortcuts (supports `just dev staged` style)
+dev app="mark" *args:
+    just app {{app}} dev {{args}}
 
-# ── Cross-Cutting ──────────────────────────────────────────
+# Convenience aliases
+mark recipe="dev" *args:
+    just app mark {{recipe}} {{args}}
+
+staged recipe="dev" *args:
+    just app staged {{recipe}} {{args}}
+
+# ============================================================================
+# Cross-Cutting
+# ============================================================================
 
 # Format all apps + crates
 fmt:
+    #!/usr/bin/env bash
+    set -euo pipefail
     cargo fmt --all
-    for dir in apps/*/; do \
-        [ -f "$dir/justfile" ] && just -f "$dir/justfile" fmt || true; \
+    for dir in apps/*/; do
+        [[ -f "$dir/justfile" ]] || continue
+        just -f "$dir/justfile" fmt
     done
 
 # Lint everything
 lint:
+    #!/usr/bin/env bash
+    set -euo pipefail
     cargo clippy --workspace -- -D warnings
-    for dir in apps/*/; do \
-        [ -f "$dir/justfile" ] && just -f "$dir/justfile" lint || true; \
+    for dir in apps/*/; do
+        [[ -f "$dir/justfile" ]] || continue
+        just -f "$dir/justfile" lint
     done
 
-# Check everything (what CI runs)
-ci:
-    for dir in apps/*/; do \
-        [ -f "$dir/justfile" ] && just -f "$dir/justfile" ci || true; \
+# Verify everything without modifying files (CI-friendly)
+check:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    cargo fmt --all --check
+    cargo clippy --workspace -- -D warnings
+    for dir in apps/*/; do
+        [[ -f "$dir/justfile" ]] || continue
+        just -f "$dir/justfile" ci
     done
     cargo test --workspace
 
-# ── Crates ─────────────────────────────────────────────────
+# Alias: many people expect `just ci`
+ci: check
+
+# ============================================================================
+# Crates
+# ============================================================================
 
 # Build shared crates
 build:
@@ -59,6 +116,6 @@ test:
 install-summarize:
     cargo install --path crates/summarize
 
-# Run summarize directly (e.g. just summarize --prompt "What?" src/)
-summarize *ARGS:
-    cargo run --release -p summarize -- {{ARGS}}
+# Run summarize directly (e.g. `just summarize --prompt "What?" src/`)
+summarize *args:
+    cargo run --release -p summarize -- {{args}}