From 2f5ff9fefbd968387edb1394377e26ea7df03cd5 Mon Sep 17 00:00:00 2001
From: cashmere <cashmere@autistici.org>
Date: Sun, 26 Jul 2026 22:41:44 +0200
Subject: chore: add justfile with common commands

Recipes wrap the documented bun/turbo/cargo/docker commands; 'just test
<path>' passes through to bun test, 'just dev' ensures .env.local exists.
just is added to the nix devshell so it is available after nix develop.
---
 AGENTS.md |  2 +-
 flake.nix |  1 +
 justfile  | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 71 insertions(+), 1 deletion(-)
 create mode 100644 justfile

diff --git a/AGENTS.md b/AGENTS.md
index addf2ddb..6ce2404c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -42,7 +42,7 @@ Domain folders also include `animation/`, `effects/`, `masks/`, `params/`, `prev
 
 ## Development Commands
 
-Run from repo root unless noted. `flake.nix` provides a devshell (`nix develop`) with bun (1.3.x) + nodejs (24); the pinned bun 1.2.18 works but so does 1.3.x.
+Run from repo root unless noted. `flake.nix` provides a devshell (`nix develop`) with bun (1.3.x) + nodejs (24) + just; the pinned bun 1.2.18 works but so does 1.3.x. The root `justfile` wraps the common commands below (`just` lists them; e.g. `just dev`, `just test <path>`).
 
 ```bash
 bun install
diff --git a/flake.nix b/flake.nix
index 2cf1c096..fab10705 100644
--- a/flake.nix
+++ b/flake.nix
@@ -23,6 +23,7 @@
           default = pkgs.mkShell {
             packages = with pkgs; [
               bun
+              just
               nodejs
             ];
           };
diff --git a/justfile b/justfile
new file mode 100644
index 00000000..c7b65dc8
--- /dev/null
+++ b/justfile
@@ -0,0 +1,69 @@
+# Common commands for the OpenCut fork. Run inside the devshell (`nix develop`)
+# or anywhere bun + node are on PATH. `just` lists all recipes.
+
+default:
+    @just --list
+
+# Install dependencies
+install:
+    bun install
+
+# Create apps/web/.env.local from the example if missing (dev server 500s without it)
+env:
+    @test -f apps/web/.env.local || { cp apps/web/.env.example apps/web/.env.local && echo "Created apps/web/.env.local from example"; }
+
+# First-time setup: install + env file
+setup: install env
+    @echo "Ready. Run 'just dev'."
+
+# Start the web editor dev server (http://localhost:3000, editor at /editor/<project_id>)
+dev: env
+    bun dev:web
+
+# Production build of the web app
+build:
+    bun build:web
+
+# Run tests; pass a path for a single file: just test apps/web/src/timeline
+test *args:
+    bun test {{args}}
+
+# Lint the web app
+lint:
+    bun lint:web
+
+# Lint and auto-fix
+lint-fix:
+    bun lint:web:fix
+
+# Typecheck the web app (pre-existing upstream errors exist; only care about files you touched)
+typecheck:
+    cd apps/web && bunx tsc --noEmit
+
+# Format the web app source with Prettier
+format:
+    cd apps/web && bun run format
+
+# Build the Rust WASM package (run ./script/setup-rust once first)
+wasm:
+    bun build:wasm
+
+# Rebuild the WASM package on Rust changes
+wasm-watch:
+    bun dev:wasm
+
+# Run Rust tests for one crate: just rust-test time
+rust-test crate:
+    cargo test -p {{crate}}
+
+# Run the GPUI desktop app (after apps/desktop/script/setup)
+desktop:
+    cargo run -p opencut-desktop
+
+# Start optional local services (postgres, redis) — not needed for editor work
+services:
+    docker compose up -d db redis serverless-redis-http
+
+# Start the full self-hosted stack at http://localhost:3100
+stack:
+    docker compose up -d
-- 
cgit v1.3.1